Partially addresses #4522: document NeedsLayout invariant + lock in layout-convergence guards

[harder]

Partially addresses #4522 (NeedsLayout is buggy).

⚠️ Draft. This intentionally does not fully close #4522 — see "What this deliberately does not do".

Summary

This PR delivers the safe, verifiable portion of #4522 and — critically — measures the current layout-convergence behavior to determine whether the long-feared NeedsLayout/SetFrame convergence redesign is still warranted after the #4973-era fixes (#5357 / #5358 / #5359). It is not, and this PR locks in the good behavior with regression guards instead of taking on a high-risk rewrite.

What changed

Library (View.Layout.cs)

• Replaced the misleading NeedsLayout region comment — which the issue explicitly calls "bogus" ("We expose no setter…") — with an accurate description of the real invariant and the internal write sites, and a note on why the setter stays internal (test seam) pending full removal.
• LayoutSubViews now re-reads GetContentSize() after the SubViewLayout event as well. It already did so after the OnSubViewLayout virtual (Partially Fixes #4522 - Stale ContentSize capture #4863); this closes the symmetric gap so a handler on the event that calls SetContentSize is honored.

Tests

• StaleContentSizeCaptureTests: +1 regression test for the SubViewLayout-event content-size case.
• LayoutConvergenceTests (new): permanent guards that pin the deterministic properties established by Split upward layout propagation from downward subtree invalidation #5357/Stop child-only redraws from escalating into full parent redraws #5358/Fix NeedsDrawRect accumulation so partial invalidations stay partial #5359 — single-pass convergence, no spurious FrameChanged, bounded ancestor-chain fan-out (no subtree fan-out), Dim.Auto growth correctness, and Pos.Right sibling repositioning (each asserted single-pass).
• AllViewsRenderFingerprintTests (new): an all-views smoke guard (every concrete View lays out + draws in design mode without throwing), and the harness used to prove render-neutrality below.

Measured convergence (the key finding)

Fan-out of a single property change on current develop:

Tree (depth × breadth)	total views	application layout passes	views that re-ran LayoutSubViews	FrameChanged
3 × 3	10	1	5	1
6 × 3	19	1	8	1
8 × 4	33	1	10	1

• Convergence is already single-pass — no multi-iteration thrashing (Bug Bug in FindDeepestView  #6 symptom gone).
• Only the changed view's frame changes (FrameChanged == 1) — Bug There is a problem with the high-intensity colors, they are not showing up #1's spurious churn gone.
• No sibling/subtree fan-out — work stays on the affected ancestor chain (≈ depth+2), far below total view count (Split upward layout propagation from downward subtree invalidation #5357).
• Dim.Auto parents still converge in one pass; the upward SetFrame → NeedsLayout mark is load-bearing for that.

The only residual is O(depth) ancestor re-layout that changes no frame. Removing it needs dependency-aware invalidation, which is high-risk to Dim.Auto correctness for an already-single-pass gain.

What this deliberately does NOT do

• No SetFrame self-dirtying guard / dependency-aware invalidation (Bug There is a problem with the high-intensity colors, they are not showing up #1/Bug in FindDeepestView  #6) — the measurements show it is not warranted and the upward mark is load-bearing for Dim.Auto.
• No removal of the direct Layout() workaround calls — those are convergence crutches that need individual, visually-verified treatment.
• No full removal of the NeedsLayout setter — it has a legitimate test seam; full removal needs a replacement.

These remain as deferred, now data-backed as low priority (see plans/4522-needslayout-lifecycle.md).

Verification

• All-views render diff: SHA of Driver.ToString() for all 61 concrete view types with the LayoutSubViews change applied vs. reverted → byte-identical (combined hash CCF30A9EA3C45AB5 both ways). The change is provably render- and layout-neutral across all views.
• Existing AllViewsDrawTests passes (every view draws with exactly one layout pass).
• UnitTestsParallelizable: 17,382 passed, 0 failed. UnitTests.NonParallelizable: 74 passed, 0 failed.

To pull down this PR locally

git remote add copilot https://github.com/harder/Terminal.Gui.git
git fetch copilot kh/4522-needslayout-lifecycle
git checkout kh/4522-needslayout-lifecycle

🤖 Generated with Claude Code