perf: drain initial wall builds within the time budget (charter row 6)

[wass08]

Metric

Maxi 8× time-to-first-clean after load (charter backlog row 6; the row's settled < 8 s target contains a 3 s runner quiet window, so the runner now reports firstCleanMs alongside it).

Three back-to-back PR-vs-main pairs, same machine (a fourth under load average 21–24 discarded as starved); third pair = this tip:

fixture	first clean	settled	same-gesture endpoint-drag settle	idle frame
Maxi 8× (472 walls)	4 900 → 3 930 ms (−20 %); 4 836 → 4 251 (−12 %); 5 639 → 4 283 (−24 %)	8 441 → 7 312; 8 681 → 7 608; 9 534 → 7 633	420 → 435 ms	6.8 → 6.3; 8.7 → 6.6 ms
Maxi 4×	−8 % / −14 % / −4 %	6 775 → 6 117	342 → 365; 349 → 370 ms	flat
rich 4×	−13 % / −5 % / −11 %	7 815 → 6 942	window 308 → 292; wall body 510 → 516	11.3 → 9.0 ms

What changed

• Initial-build state for the wall system, entered from setScene's hydration token and left on the first frame with no dirty wall and an empty pending-neighbour queue (a document write, live override/transform, or canvas pointer/wheel ends it early). Exposed read-only via isWallInitialBuildActive().
• While active: walls are consumed by the existing 8 ms time budget without the 8-per-frame count cap (heavy ≥ 6-opening walls still get their own frame), and a wall's first build does not enqueue neighbour re-invalidation — every neighbour is itself queued for its own first build, and a test proves junction geometry identical to the capped path. Opening-completion re-dirtying is unchanged. After initial build everything returns to today's scheduling.
• Counters under __pascalPerf.batchStats().wallDrain (walls consumed per frame, exit reasons, pending-neighbour length, first-build vs re-invalidation) and a wall-initial-build span.
• Fix found by the receipt sensor (1137afc): the first cut's hydration invalidation was a nested scene write, so the first edit after load reached space reconciliation twice and re-invalidated the whole level (same-gesture endpoint drag 422 → 1 598 ms). Invalidation now happens atomically with the document write; the regression fixture rebuilds 4 walls instead of 48.
• Batching during the drain (bounded join waves while walls are dirty) is deliberately left for a follow-up.

Gates

• e2e: 9/9 against the PR dists (perf-regression pack ×5, batched-wall click, hidden-wall click, undo/redo graph, floor placement)
• Unit: core 1 430 / viewer+nodes 2 681 pass (--randomize --seed=1); tsc --noEmit core/viewer/nodes clean; biome clean.
• No rendering change → no pixel/bake gate. Independent audit: no blocker, four should-fixes closed in the second round (token published after normalization; interaction capture spans the lazy mount and remounts; bounded stall exit for never-registering walls; ?perf-gated, allocation-free diagnostics) plus a pre-existing core test-fixture ordering flake fixed (three seeds green).
• Docs: wiki/architecture/systems.md describes the initial-build scheduling.

Charter: plans/performance/editor-scalable-scene-runtime.md row 6 (private PR follows with the evidence row and the runner's first-clean / undo-phase sampling).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jmmz2AMwTzcnKsSHHPEMhN

---

Note

High Risk
Touches core scene load/hydration, undo/history boundaries, and wall rebuild scheduling—incorrect token or invalidation timing could cause wrong geometry, stalled loads, or extra full-level invalidation after edits.

Overview
Introduces a scene hydration boundary around setScene: elevator opening sync runs synchronously, stair rise/opening normalization is queued on microtasks, and a hydrationToken is published only after that work finishes. Document writes outside normalization atomically cancel pending publication or clear an issued token; live overrides/transforms and canvas pointer/wheel also end hydration early. applySceneSnapshot now clears live maps before replacing the scene.

Initial wall build follows that token: walls drain under the existing 8 ms frame budget without the interactive 8 walls/frame cap (heavy walls still get a dedicated frame), and each wall’s first build skips neighbour re-invalidation while hydration is active. A canvas-level lifecycle owner tracks drain state across lazy WallSystem mounts, exposes isWallInitialBuildActive(), and adds optional ?perf wall-drain counters. Stair auto-sync defers through queueSceneNormalization so it participates in the same boundary.

Fixes hydration invalidation happening as a nested write (which could double space reconciliation on the first post-load edit). Docs and broad lifecycle tests cover interruption, late system mount, and pending-neighbour behaviour during drain.

^{Reviewed by Cursor Bugbot for commit 54cedd9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: d08da89a-c471-4f51-ab16-816f2435e6c2