perf(layout): per-subtree layout caching / RelayoutBoundary to avoid full-tree relayout on every change

[TimLai666]

Summary

A gpui/Flutter-inspired layout optimization. Today, any change that sets needsLayout re-runs layout over the entire widget tree from the root, even when only a small subtree actually changed. This proposes per-subtree layout caching (the layout-side analogue of the existing RepaintBoundary), so a localized change only re-measures the affected subtree.

Filing as a design discussion first per CONTRIBUTING.md (layout algorithms → open an issue first), and because correct cache invalidation is behavior-affecting and needs alignment before implementation.

Current behavior (grounded)

• Idle frames already skip layout — good: Window.Frame only lays out when w.needsLayout is set (app/window.go:543). This is already better than "relayout every frame".
• But when needsLayout is set, the whole tree is re-laid-out: w.layout() → w.root.Layout(w.ctx, constraints) (app/window.go:546, 768). There is no per-node result cache and no per-subtree dirty granularity.
• needsLayout is a single window-level bool, flipped to true by resize, animations, content/signal changes, SetRoot, etc. (app/window.go:186, 216, 319, 363, 465, 1032). Any one of these → O(tree) re-measure of every node.

So the cost model today is: cost(change) = O(total nodes), regardless of how local the change was. For large trees (dashboards, IDE layouts, big tables/trees) where one widget animates or one label changes, this re-measures everything every affected frame.

Prior art

• Flutter — RenderObject.layout() short-circuits when constraints are unchanged and the node isn't dirty; RelayoutBoundary stops dirty propagation when a node's size can't be affected by its parent. This repo already implements the paint side of this (RepaintBoundary, app/window.go:309 comment), so the layout side is a natural symmetric addition.
• taffy (used by gpui) — caches per-node measured sizes keyed by the input constraints + a style/version stamp, and reuses them across layout passes.

Proposed design (phased)

Phase 1 — per-node measure cache + layout-dirty flag

• Add to WidgetBase: a small layout cache {lastConstraints geometry.Constraints, lastSize geometry.Size, valid bool} and a MarkNeedsLayout() that clears valid and propagates up to the nearest relayout boundary (or the window).
• Containers, before calling a child's Layout(ctx, constraints), check: if the child's cache is valid and lastConstraints == constraints, reuse lastSize and skip the recompute.
• Widgets call MarkNeedsLayout() when a layout-affecting property changes (text/content, font size, padding, visibility, children, explicit size). This is distinct from SetNeedsRedraw (paint-only) and from the window-level needsLayout (which becomes the "root got dirtied" signal).

Phase 2 — RelayoutBoundary

• Mirror RepaintBoundary: a node that is laid out with tight constraints (its size cannot change due to descendant changes) becomes a relayout boundary, so a descendant's MarkNeedsLayout() stops propagating there instead of reaching the root. This bounds cost(change) to the boundary's subtree.

Phase 3 (optional) — constraint rounding / size-stamp reuse à la taffy for nodes measured multiple times in one pass.

Risks / why design-first

• The hard part is invalidation correctness: if a widget mutates a layout-affecting property without calling MarkNeedsLayout(), you get a silent stale-layout bug that existing unit tests won't catch. Getting the set of "layout-affecting" mutations right across every widget is the real work and the real risk.
• Mitigation: land Phase 1 mechanism on WidgetBase first (default conservative: cache only honored when the framework can prove the node wasn't touched), wire it into primitives/* and a few core/* widgets with golden/integration tests, and only then expand. A debug mode that re-runs uncached layout and asserts the cached result matches would catch missing invalidations during development.

Relationship to existing work

• Complements perf(layout): pool per-Compute temporary slices to cut frame allocations #140 (per-Compute slice pooling in layout/) — that cut allocations; this cuts redundant work.
• Reuses the existing RepaintBoundary mental model and the window-level needsLayout gate; nothing here regresses the idle-frame skip.

Offer

If the approach and especially the invalidation strategy look right, I'm happy to implement Phase 1 incrementally (base mechanism + tests + wire into primitives and a representative set of core widgets), then iterate. Wanted to align on the design and the "layout-affecting mutation" contract before writing code, since it touches WidgetBase and every widget's mutation paths.

[kolkov]

@TimLai666 — we ran a deep cross-framework analysis before committing to an approach. Research covered Flutter, Android View, Qt QBoxLayout, Taffy (Servo/Dioxus), SwiftUI, Iced, and Yoga.

The data

Every enterprise retained-mode framework caches layout results. We are at Iced level today (full re-layout on any needsLayout=true). Iced is not enterprise-scale.

Framework	Cache	Boundary	Cache Key
Flutter	constraints + size per node	RelayoutBoundary (auto)	Constraints ==
Android	16-entry LongSparseLongArray	No (implicit)	MeasureSpec pair
Qt	dirty bool + 3 cached sizes	No	Dirty sentinel
Taffy	9 deterministic slots	No	known_dims + available_space
gogpu/ui	None	None	—

Your analysis was accurate — we verified all line references against the code.

Architecture context: how we got here

The signal system. Our reactive state (coregx/signals + state.BindToScheduler) was designed after the polymorpheus pattern (taiga-family, Tinkoff/T-Bank) and Angular's 2026 signal inputs evolution. Core principle: host provides context, content adapts — Content[C].Render(ctx) receives fresh context each call, signals trigger automatic invalidation. This is our Go-native distillation of Angular's PolymorpheusOutlet + POLYMORPHEUS_CONTEXT + signal inputs — same architecture, simpler API via Go generics.

The signal chain today: signal.Set() → SubscribeForever → sched.MarkDirty(widget) → flushFn → widget.SetNeedsRedraw(true). This is paint-only — onDirty sets window.needsRedraw but NOT needsLayout (by design, app/window.go:275: "Layout is NOT needed"). Correct for paint-only signals (counter value, progress, color). But layout-affecting signals (item count, text content) currently rely on widgets calling ctx.Invalidate() separately — which triggers full-tree layout.

Angular's signal inputs distinguish layout-affecting from paint-only changes via change detection. We don't yet. Layout caching needs this distinction.

The Engine. We have internal/layout/Engine with a constraint-keyed cache + dirty set — created in Phase 0 (the very first foundation commit). It was designed with a Layoutable interface: Layout(constraints) Size. But when real widgets came in Phase 1-2, the widget.Widget interface emerged with Layout(ctx, constraints) Size — the ctx parameter (theme, focus, scheduler) was essential for the polymorpheus pattern (context propagation). The Engine's Layoutable was never adapted, and no widget implements it today.

Architecture decisions evolved through our ADRs (RepaintBoundary on WidgetBase in ADR-024, dirty propagation in ADR-028, retained-mode compositor in ADR-007), but the layout caching story was left behind. We now need to decide the right path forward — and get it right this time so we're not redoing it later.

Our analysis shows that Flutter, Android, and Qt all use distributed caching (fields on each widget/View/RenderObject), not a centralized engine. Our RepaintBoundary already follows this pattern (cache fields on WidgetBase). Layout caching should be symmetric — also on WidgetBase, not through the Engine.

Proposed approach (ADR-032)

Phase 1a — WidgetBase fields (layoutNeedsUpdate, lastConstraints, lastSize, layoutCacheValid) + MarkNeedsLayout() with upward propagation.

Phase 1b — Wire into Box, Text, ProgressBar, ScrollView. Audit + convert 10 ctx.Invalidate() sites:

Widget	Calls	Change type
Collapsible	3	expand/collapse
TabView	2	tab switch
Docking	2	panel resize
SplitView	1	divider drag
DataTable	1	column resize
TreeView	1	node expand/collapse

Phase 1c — GOGPU_DEBUG_LAYOUT=1 verification: re-run layout on cache hit, assert result matches. Flutter does this in debug mode. Prerequisite — without it, missing MarkNeedsLayout() = silent stale layout.

Phase 2 — RelayoutBoundary (auto-compute from constraints.IsTight()). Layout dirty list with depth-sorted processing.

Discussion

The lower-level ecosystem (naga, wgpu, gg, gogpu) is now stable — v0.17+ / v0.30+ / v0.48+ respectively. It's time to seriously focus on getting the GUI framework architecture right. This layout caching decision will affect every widget we build going forward, so we want to get input from the broader team.

Questions for discussion:

1. Distributed (WidgetBase) vs centralized (Engine) — we lean distributed (Flutter/Android pattern, symmetric with RepaintBoundary). The existing Engine has the right cache key design but wrong interface. Adapt it or build fresh on WidgetBase?

2. LayoutCacheHit placement — each widget checks at the top of its Layout(), or framework intercepts at parent level (Flutter RenderObject.layout() calls performLayout() only if needed)?

3. MarkNeedsLayout vs ctx.Invalidate — should ctx.Invalidate() internally call MarkNeedsLayout() (backward compatible), or should widgets call MarkNeedsLayout() directly (explicit, forces audit)?

4. Debug verification scope — doubles layout cost. On by default in dev, or opt-in via env var?

5. What about the existing Engine? — keep for standalone testing? deprecate? adapt?

6. Signal integration — new BindToSchedulerLayout for layout-affecting signals (symmetric with existing BindToScheduler for paint), or widget calls MarkNeedsLayout() in its own signal callback? Angular distinguishes this at the change detection level — we need our Go equivalent.

For context: v0.1.35 (just released) includes your #138, #139, #140 plus ListView per-item decorator + scroll recycling. #140 and this proposal are complementary: #140 cuts allocations per Compute call, #142 cuts redundant Compute calls entirely.

Roadmap note: we are currently on v0.1.x (pre-release, breaking changes OK). Moving to v0.2+ requires solving the layout caching problem first — it's a foundational piece that affects every widget's Layout() contract. Better to get it right now while the API is still fluid than to retrofit it later with backward compatibility constraints.

cc @lkmavi @jdbann @darkliquid @celer @unxed @rcarlier @k-chimi @z46-dev @crsolver — would appreciate your thoughts on the layout caching approach, especially if you've hit layout performance issues in your projects or have opinions on the distributed vs centralized cache question.

[TimLai666]

Thanks for the depth here, @kolkov — the cross-framework table and the Engine/Layoutable history make the trade-offs concrete. My recommendations on the six questions, with the reasoning:

The migration-safety point first (frames Q3 + Q4)

The single biggest risk is a missing MarkNeedsLayout() → silent stale layout. I'd design the migration so that a miss can never be stale, only slow:

• Keep ctx.Invalidate() exactly as today, but have it mark the relayout pass cache-cold (caches bypassed/ignored for that pass = today's full uncached relayout). Context.Invalidate() is window-level and parameterless (widget/context.go:71,537) — it structurally can't target a node, so it can't do targeted invalidation anyway. Let it stay the correct-but-slow path.
• MarkNeedsLayout(node) is the new targeted path: invalidate that node's cache, propagate to the nearest relayout boundary, add to a layout-dirty list → cache-warm pass, only dirty subtrees recompute.

Net effect: an unconverted widget keeps calling ctx.Invalidate() and lays out correctly (just unoptimized); a converted widget gets the fast path. Migration becomes incremental and reversible per-widget with zero stale-layout risk. The 10 ctx.Invalidate() sites become a performance backlog, not a correctness cliff.

Q1 — Distributed vs centralized

Distributed cache, centralized scheduling. Cache fields (lastConstraints, lastSize, layoutCacheValid) on WidgetBase — symmetric with RepaintBoundary, cache-local to the pointer you already hold, no per-node map lookup. But keep a single depth-sorted layout-dirty list centrally (mirror ADR-028's flat dirty-boundary set for paint). Data distributed, ordering centralized. The Engine's cache-key design (constraints+size) is the part worth keeping; its Layoutable interface is the wrong shape (no ctx, which the polymorpheus context-propagation needs).

Q2 — Cache-hit placement

Framework choke point, not per-widget. A check at the top of every Layout() is boilerplate × every widget = exactly where misses hide. You already have a natural interception point: the algorithm layouts go through LayoutTree.Measure(nodeID, constraints) (layout/), so constraint-keyed caching can live there for Flex/Grid/Stack for free. For hand-rolled containers that call child.Layout(ctx, c) directly, add one helper — LayoutChild(child, ctx, c) that does check→Layout→store — and convert containers to it. Audit surface = containers (a handful), not all widgets. Leaf widgets need no change.

Q3 — MarkNeedsLayout vs ctx.Invalidate

Both, layered (see top). Don't auto-route ctx.Invalidate() → MarkNeedsLayout(): it can't name the node, so it'd just reproduce full-tree behavior while looking targeted. Explicit MarkNeedsLayout() at the mutation site, ctx.Invalidate() as the safe cache-cold fallback, migrate sites one at a time.

Q4 — Debug verification

Opt-in env var (GOGPU_DEBUG_LAYOUT=1) AND auto-enabled in the test suite. Go has no debug/release split, so doubling layout cost on every dev run is too much; but a test helper that flips it on lets CI catch missing MarkNeedsLayout() for any widget under test. This is the Go-idiomatic version of Flutter's debug asserts, and it's the prerequisite that makes the incremental migration trustworthy.

Q5 — Existing Engine

It's internal/, so no compat cost. Keep it short-term as a standalone/headless reference for the cache-key logic, mark the Layoutable path as not-on-the-widget-hot-path, and plan removal once WidgetBase caching lands so there's a single source of truth. Don't adapt it to be the widget path — that recreates the centralized design you're moving away from.

Q6 — Signal integration

BindToSchedulerLayout (+ BindToSchedulerLayoutFunc), symmetric with the existing paint bindings. On change it calls both MarkDirty (paint) and MarkNeedsLayout (layout) on the bound widget. Putting the layout-vs-paint distinction at the binding declaration is self-documenting and greppable ("which signals are layout-affecting?") — the Go-native equivalent of Angular distinguishing this at change detection. Widget-callback-only would re-scatter the logic that BindToScheduler was created to centralize. Keep the Func dedup variant for the progressbar-style "suppress unchanged" case.

Offer

If the team converges on distributed + the cache-cold fallback, I'm happy to take Phase 1a (WidgetBase fields + MarkNeedsLayout propagation + the LayoutChild choke point + GOGPU_DEBUG_LAYOUT verifier), with the debug verifier landing first so 1b conversions are checkable as they go. That ordering makes each subsequent ctx.Invalidate()→MarkNeedsLayout() conversion a small, individually-verifiable PR.

(One caveat on my end: I can validate correctness via the debug verifier + tests and measure CPU-side layout work, but I don't have a GPU/display in my environment, so visual/integration sign-off would need someone with hardware.)

[kolkov]

@TimLai666 — solid reasoning across all six points. We validated each against our codebase and cross-referenced with Flutter/Android patterns. Here's where we land:

Where we agree

Q1 (Distributed + centralized scheduling) — yes. Cache on WidgetBase, dirty list centrally. The Engine's cache key design is validated, its Layoutable interface is not (missing ctx needed for polymorpheus context propagation). Engine will be removed after WidgetBase caching lands.

Q2 (LayoutChild helper) — yes, and it's stronger than we initially thought. We already have widget.DrawChild() (widget/draw.go:102) that intercepts Draw calls at the call site — containers call DrawChild(child, ctx, canvas) instead of child.Draw(). Layout should be symmetric: widget.LayoutChild(child, ctx, constraints) instead of child.Layout(ctx, constraints). We verified: ~30 child.Layout(ctx,...) call sites across 18 files. LayoutTree.Measure() has 0 usage in core/primitives — confirmed it's not the interception point.

Q5 (Engine) — agreed. Keep as reference, remove after WidgetBase cache.

Q6 (BindToSchedulerLayout) — agreed. Ship with Phase 1. MarkNeedsLayout() on SchedulerRef (currently just MarkDirty(w Widget) — one method). Clean, self-documenting, symmetric.

Where we disagree: Q3 (cache-cold fallback)

We audited all 10 ctx.Invalidate() sites line-by-line:

Widget	Calls	Trigger
Collapsible	3	animation tick + mouse toggle + key toggle
TabView	2	tab close + tab select
Docking	2	panel switch + panel close
SplitView	1	divider drag (ratio change)
DataTable	1	column sort click
TreeView	1	node expand/collapse

Every call is a one-line mechanical replacement. All already have ADR-028 comments documenting the intent ("layout change — [reason]"). All 6 widgets have 88-95% test coverage.

Our concern with the fallback approach: ctx.Invalidate() bypasses the layout cache entirely (it sets window.needsLayout which triggers full uncached relayout). This means the cache is never populated for unconverted widgets, and stale layout bugs are hidden — they only surface when someone converts the site later. Flutter never had a fallback path — markNeedsLayout() was there from the first commit (2015). Missing calls are caught by debug assertions, not by graceful degradation.

Since we're at v0.1.x with zero external consumers locked to the API, and we deliberately held off adding widgets to avoid rewrites — we think one-shot conversion of all 10 sites is the right move. It's a smaller, more verifiable change than maintaining two parallel invalidation paths. The debug verifier (Phase 1c) is the real safety net, not the fallback.

Q4 (debug verifier) — timing adjustment

We agree on the design (env var + auto in tests), but the verifier validates infrastructure that doesn't exist yet. We'll land it alongside the cache, not before. Once LayoutChild and cache fields are in place, the verifier becomes testable.

Revised plan

1. WidgetBase cache fields + MarkNeedsLayout() + MarkNeedsLayout() on SchedulerRef
2. widget.LayoutChild() helper (symmetric with DrawChild)
3. Convert ~30 child.Layout() → widget.LayoutChild() in containers (18 files)
4. Convert ALL 10 ctx.Invalidate() → MarkNeedsLayout() (6 files)
5. BindToSchedulerLayout + BindToSchedulerLayoutFunc
6. Debug verifier (GOGPU_DEBUG_LAYOUT=1)
7. RelayoutBoundary (Phase 2, later)

Steps 1-6 can ship in 2-3 focused PRs. Step 7 deferred.

On GPU/display testing

We have a full software rasterization backend (hal/software) with pixel-exact readback — no GPU or display needed. Unit tests use createSoftwareDevice(t) for deterministic rendering. You can validate layout correctness + visual output entirely in CI. Happy to help wire this up.

Your offer to take Phase 1a is welcome. Given the one-shot approach, we'd suggest scoping the first PR as: WidgetBase fields + MarkNeedsLayout + LayoutChild helper + debug verifier. The 10 ctx.Invalidate() conversions and BindToSchedulerLayout can be a second PR that builds on it.

[kolkov]

@TimLai666 — we ran a deep follow-up study before the community discussion closes. Four parallel research tracks: Flutter source deep dive (rendering/object.dart, box.dart, flex.dart — now cloned locally), Android/Qt/SwiftUI/Yoga cross-framework analysis, exact Go API design, and a full codebase audit of every Layout call site.

The core decisions from our previous discussion hold. But we found 8 gaps in the accepted plan, 3 of them critical. Sharing so the community and you have full context before PR 1.

Corrected numbers (codebase audit, every file checked)

Category	Estimated	Actual	Notes
child.Layout(...) sites	~30	34	30 to convert, 4 exceptions (see below)
ctx.Invalidate() sites	10	12	2 additional in TabView + Transition
internal/layout/Engine usage	"keep as reference"	0 production usage	Dead code, safe to remove
LayoutTree.Measure() in core/	unknown	0 usage	Also dead code

3 critical gaps

GAP-1: Paint dirty timing. Our plan had MarkNeedsLayout() calling SetNeedsRedraw(true). Flutter does it differently — markNeedsLayout() does NOT call markNeedsPaint(). Paint dirty is set at the END of layout() / _layoutWithoutResize(), after layout actually runs. The reason: if MarkNeedsLayout() immediately triggers paint propagation, boundaries get marked dirty before layout has run — some of those subtrees might not actually change (cache hit on relayout). This causes unnecessary repaints.

Revised approach: MarkNeedsLayout() sets needsRedraw = true on self only (no upward propagation). LayoutChild() calls SetNeedsRedraw(true) with boundary propagation after layout completes (cache miss path). This matches Flutter exactly.

GAP-2: Layout-in-Draw exceptions. Two virtualized widgets call Layout() inside Draw(), not during the layout pass: core/listview/virtual_content.go:99 and core/gridview/gridview.go:1174 (drawVisibleCells). This is a deliberate optimization — only visible items are measured on demand, analogous to Flutter's RenderSliverList. These sites must NOT be converted to LayoutChild because the cache dirty/clean cycle assumes layout runs during the layout phase. Two other sites (offscreen entry points in offscreen/renderer.go) are also framework-level, not parent→child.

GAP-3: Animation path. Collapsible calls ctx.Invalidate() inside tickAnimation() which is called from Layout(). Converting this to MarkNeedsLayout() inside Layout could conflict with re-entrancy detection (debug mode). Flutter's pattern: animation ticks fire in handleBeginFrame BEFORE flushLayout(). The tick calls markNeedsLayout() there, and performLayout() only reads the current progress. Our Collapsible should be restructured the same way — MarkNeedsLayout() from the animation tick callback (in BeginFrame), not from inside Layout.

5 important (non-critical) gaps

Gap	Pattern	Source	Phase
SchedulerRef unchanged	BindToSchedulerLayout uses type assertion w.(layoutMarker), does NOT extend SchedulerRef	API research — avoids breaking uitest mocks	1
Constraints satisfaction	assert constraints.IsSatisfiedBy(size) in debug LayoutChild	Flutter debugAssertDoesMeetConstraints	1 (debug)
Window callback	SetOnLayoutDirty(fn) wired by Window in SetRoot, same pattern as onBoundaryDirty	Propagation reaches root, root fires callback	1
Generation count	layoutGeneration uint64 on WidgetBase for robust staleness detection in debug verifier	Yoga LayoutResults.generationCount — unique innovation, no other framework has it	4
parentUsesSize	Most common RelayoutBoundary trigger in Flutter. Add via LayoutChild(..., opts ...LayoutChildOpt)	Flutter layout(parentUsesSize: false)	5

Full cache clear (Android pattern)

Android's requestLayout() calls mMeasureCache.clear() — not just sets a dirty flag. Our MarkNeedsLayout() should also zero lastConstraints and lastSize, not just set layoutCacheValid = false. This prevents accidental stale cache hits if the dirty flag is somehow missed.

Finalized LayoutChild signature

func LayoutChild(child Widget, ctx Context, constraints geometry.Constraints) geometry.Size

Returns geometry.Size only (Option A from our discussion). No baseline (separate interface if needed later), no cache-hit bool (debug verifier handles this), no parentUsesSize (Phase 5 via functional options). This matches Flutter's layout() returning void + parent reading child.size.

Revised implementation order

1. PR 1 (infrastructure): WidgetBase fields + MarkNeedsLayout() + LayoutChild() + SetOnLayoutDirty callback + debug verifier + Window wiring + tests
2. PR 2 (conversion): 30 child.Layout() → LayoutChild() + 12 ctx.Invalidate() → MarkNeedsLayout() + animation path restructure (Collapsible, Transition)
3. PR 3 (signals): BindToSchedulerLayout[T]() + BindToSchedulerLayoutFunc[T]() + convert layout-affecting bindings
4. PR 4 (cleanup): Remove internal/layout/Engine (confirmed 0 usage) + update ADR-032 + docs

Full research report: LAYOUT-CACHING-DEEP-RESEARCH.md (synthesis of all 4 studies with exact Go API signatures, WidgetBase memory analysis, framework comparison tables, and conversion exception list).

cc @lkmavi @jdbann @darkliquid @celer @unxed @rcarlier @k-chimi @z46-dev @crsolver

[TimLai666]

Great — the one-shot decision on Q3 convinces me (no external consumers + debug verifier as the real net beats a fallback that hides misses; agreed it's the smaller, more verifiable change). And the software-rasterization backend resolves my hardware caveat — I'll wire correctness/visual checks through createSoftwareDevice(t).

I'll take PR 1 (infrastructure) to the finalized spec:

• WidgetBase fields (layoutCacheValid, lastConstraints, lastSize, onLayoutDirty) + MarkNeedsLayout() + SetOnLayoutDirty(), mirroring the existing isRepaintBoundary / onBoundaryDirty / propagateDirtyUpward machinery (base.go:75-83, 523-586).
• widget.LayoutChild(child, ctx, constraints) geometry.Size — symmetric with DrawChild (draw.go:102), returning Size only (Option A).
• GOGPU_DEBUG_LAYOUT=1 verifier (re-run on cache hit + assert equal; constraints.IsSatisfiedBy(size) assert) + Window SetOnLayoutDirty wiring in SetRoot.

Honoring the three critical gaps:

• GAP-1: MarkNeedsLayout() sets paint-dirty self-only (markDirtyLocal, no upward paint propagation); LayoutChild does SetNeedsRedraw(true) with boundary propagation only on the cache-miss path, after child.Layout returns.
• GAP-2: PR 1 only adds the helper; the layout-in-Draw sites (listview virtual_content.go:99, gridview gridview.go:1174) and the offscreen entry points stay on direct child.Layout() — I'll leave the conversion exceptions documented for PR 2.
• GAP-3: no animation-path changes in PR 1; I'll restructure Collapsible's tick→MarkNeedsLayout (in BeginFrame, not inside Layout) as part of PR 2.

Also folding in: Android full-clear (MarkNeedsLayout zeroes lastConstraints/lastSize, not just the flag), and propagating layout-cache invalidation up the parent chain (ancestors depend on child size) — stopping at root for now, at RelayoutBoundary in Phase 2.

PR 1 is purely additive (nothing calls LayoutChild/MarkNeedsLayout in production until PR 2), so it can't change behavior — only adds the mechanism + tests. Starting now.

[kolkov]

@TimLai666 — great, looking forward to PR 1. The purely-additive approach is exactly right — mechanism + tests first, wiring in PR 2.

One addition to the ADR before we close the design discussion: mobile platform consideration for cache strategy.

Why LayoutChild uses functional options (future-proofing for Android/iOS)

The Phase 1 signature LayoutChild(child, ctx, constraints) is deliberately extensible to LayoutChild(child, ctx, constraints, opts ...LayoutChildOpt). This allows adding mobile-specific cache strategies without breaking existing call sites.

Current decision: single-entry cache — correct for desktop AND mobile. gogpu/ui renders its own widget tree via GPU on all platforms (no native View/UIView wrapping). Each widget instance = one position in tree = one set of constraints per frame.

But mobile introduces scenarios worth researching before v1.0:

Scenario	Description	Multi-entry helps?
Widget recycling	Pool-based reuse of widget instances for 10K+ item lists (Android ViewHolder pattern). Same widget, different data positions, potentially different constraints.	Maybe — but MarkNeedsLayout() on rebind does full clear, so cached entries from previous position are lost anyway. Android skips requestLayout() on bind when specs unchanged — different pattern.
Orientation change	Portrait ↔ landscape = two distinct constraint sets. User rotates back = same constraints as before.	Two-entry cache could avoid re-layout on return. But rotation is rare enough that one cache miss per rotation is negligible.
Foldable devices	Samsung Fold: 2 screen sizes. iPad Split View: 3 split ratios.	2-3 entry cache covers all states. But transitions are infrequent.
Intrinsic size queries	GetMinIntrinsicWidth(height) measures same widget with different inputs. Mobile's smaller screens make auto-sizing more common.	Separate intrinsic cache (Flutter _LayoutCacheStorage pattern), not multi-entry main cache.

Conclusion: single-entry is correct now. We've created a backlog research task (TASK-UI-MOBILE-LAYOUT) to validate this on real hardware when mobile backends are ready. The functional options in LayoutChild signature ensure we can add WithCacheStrategy(MultiEntry) or WithRecycleHint(true) without API break if research shows the need.

Would appreciate thoughts from anyone with mobile GUI framework experience — especially @lkmavi (macOS/iOS) on whether iOS layout patterns suggest any cache strategy changes.

cc @lkmavi @jdbann @darkliquid @celer @unxed @rcarlier @k-chimi @z46-dev @crsolver

[TimLai666]

PR 1 (infrastructure) is up: #143. Purely additive — LayoutChild + MarkNeedsLayout + WidgetBase cache fields + GOGPU_DEBUG_LAYOUT verifier + root onLayoutDirty wiring, with GAP-1/2/3 honored as discussed. 100% coverage on the new code, full suite green. PR 2 (the conversion audit) will build on it.

[kolkov]

https://news.ycombinator.com/item?id=48608069 - about GoGPU GUI

[TimLai666]

Started PR 2 (conversion) — did the ~26 child.Layout→LayoutChild + the event-handler ctx.Invalidate→MarkNeedsLayout conversions on a branch, then ran the whole suite under GOGPU_DEBUG_LAYOUT=1. The verifier earned its keep — it surfaced a real bug and two design questions I'd rather settle with you before finalizing, since two of them touch decisions you own.

✅ The verifier caught a real stale-layout bug

panic: layout cache stale for *listview.virtualContent:
  cached Size(300, 240) but recomputed Size(300, 960) ...
  — a layout-affecting mutation is missing a MarkNeedsLayout() call

Root cause → the big finding: PR 2 and PR 3 are entangled. The listview's itemCountSignal is bound with BindToScheduler (paint-only MarkDirty), not a layout-aware binding (listview/widget.go:230, 233). So a count change resizes virtualContent but never invalidates layout → stale cache once LayoutChild is active. Same pattern in gridview (itemCountSignal/columnsSignal, gridview.go:554, 581) and datatable (rowCountSignal, datatable.go:499) — all layout-affecting signals on the paint-only path.

Implication: activating the cache (PR 2) without the layout-aware signal bindings (PR 3 BindToSchedulerLayout) produces stale layout for every signal-driven size change. They can't ship independently in that order. Options:

1. Fold the layout-affecting count/column/row signal bindings into PR 2 (i.e. land a minimal BindToSchedulerLayout now and convert those bindings), effectively merging PR 2 + PR 3.
2. Keep the order but gate LayoutChild adoption per-widget behind its bindings being converted first.

I lean (1) — the cache and the layout-aware bindings are two halves of the same correctness story. Your call on sequencing.

⚠️ The constraints-satisfaction assert conflicts with intended overflow

My PR 1 debug assert (constraints.IsSatisfiedBy(size), which you approved) fires on a legitimate case:

panic: *primitives.BoxWidget returned size Size(100, 30)
  that does not satisfy constraints Constraints(0<=w<=50, 0<=h<=300)

TestHBoxLayoutConstrainedWidth confirms this is intended: a child Box().Width(100) returns 100 even when handed max-50 (explicit size wins), and the parent HBox clamps its own total to 150. So gogpu/ui deliberately lets children overflow their constraints — unlike Flutter's tight contract the assert assumed. Recommend removing the constraints-satisfaction assert from LayoutChild and keeping only the stale-cache re-run check (the half that found the listview bug). Cheap to do; flagging since it reverses a PR 1 decision.

⚠️ The re-run verifier can't be a blanket suite gate

Re-running Layout on a cache hit doubles Layout calls, so any test counting Layout invocations fails under GOGPU_DEBUG_LAYOUT=1 (including PR 1's own TestLayoutChild_CachesOnSameConstraints). So it's best as a targeted integration check, not a global CI flag. I'll document it that way unless you'd rather make the verifier opt-in per-call.

In-scope, no decision needed (I'll just do these)

• collapsible/tabview …KeepsFullInvalidation guard tests assert the old ctx.Invalidate(); I'll update them to assert the granular MarkNeedsLayout path (this is exactly the Phase 1b conversion).
• GAP-3: collapsible.go:381 ticks animCtrl.Tick + ctx.Invalidate() from inside Layout; I'll move the per-frame invalidation to the BeginFrame animation callback as agreed.

Branch is ready; I'll finalize once you confirm (1) the PR2/PR3 sequencing and (2) dropping the constraints assert.