Node batching: items, columns, doors and windows draw through BatchedMesh containers

[wass08]

Metric (charter backlog 3a+3b): idle frame CPU across the fixture ladder. Measured: −26% rich 2× (10.7→7.8ms), −37% Maxi 8× (21.1→13.2ms), −8..−14% everywhere else; in-page noise-cancelled A/B: rich 2× −19%, rich 4× −27%.

What

The frame's bottleneck is CPU draw submission (~3µs per mesh: pipeline/bind/uniform setup per object; the GPU idles at 1–2ms). Items, columns and wall-hosted openings now render through THREE.BatchedMesh containers — one per (level, material, attribute-signature) — paying setup once per batch and ~0.3µs per instance, with per-instance frustum culling intact.

Architecture mirrors the proven wall batch (shared/node-batch/{types,store,candidates,system}):

• Sources stay mounted and draw-hide via the existing 'batched' layer hold — picking, hover outlines, selection paint, measuring and GLB export are untouched by construction. Batch meshes are draw-only (noop raycast, pascalExport='strip').
• Membership follows the dirty signal + count tell + settle window. Lit nodes release and draw themselves; a dirty/lit/mid-gesture host wall cascades to its openings; a door/window animation record releases its node for the tween; isolation stands everything down; a level-subtree remount is detected by parent identity and re-sewn.
• Existing batches always accept rejoins; new batches need MIN_BATCH_ENTRIES — a scene of a few unique items creates zero batches and pays zero overhead (verified: 4-item scene, 0 batches, wave quiesces).
• Bake/thumbnail pages (?disable=draw) don't batch at all, and the release-everything paths sweep stale 'batched' holds so exports can never lose geometry.
• ?perf gains a batch membership row (on WebGPU each batched instance still counts in drawCalls — the backend loops drawIndexed per visible instance — so the DRAW number cannot show the win; frame/encode ms is the metric).

Evidence (charter plans/performance/editor-scalable-scene-runtime.md in private-editor)

• Matrix (7 fixtures, quiet machine, vs post-dirty-lifecycle baseline): idle −8..−37%, hover −8..−30%, wall-move settle −66/−67% on two fixtures, dirty lifecycle intact.
• Isolation fixtures (in-page A/B, batching toggled live): 100× sofa −29%, 32 assets ×10 −29%, AI-generated textured items ×25 −15% (copies share GLB-cached materials — no per-texture fragmentation), AI+catalog 360 −27%.
• Per-instance frustum culling verified live (mixed fixture draws 350/810 instances at default framing).

Gates

• Editing e2e 8/8: perf-regression-pack (door place/reselect, undo, wall endpoint), click-batched-wall, click-hidden-wall, opening placement.
• Visual: cross-build pixel parity ≤0.006% (items); in-session batched-vs-released diff 0.4% confined to coplanar-seam AA and transparent blend order (diff image reviewed — no missing/displaced geometry).
• Bake: tri+byte identical batching-on vs batching-off on the same scene.
• Item-move settle parity (order-controlled ×5; earlier matrix wobble was cold-path single-sampling).

Trade-offs + the v1→v3 ladder (unmount sources / indirect multi-draw) and follow-ups (ceilings+slabs coverage, wall-mode-aware wall batch for the rich-4× <12ms target) are documented in the charter's architecture notes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Nq2rLE18tFVES2LU6HGokK

---

Note

Medium Risk
Large new render-path subsystem with many release paths (export, isolation, gestures); incorrect batch membership or stale 'batched' holds could cause missing geometry or frozen poses, though capture sweeps and invariants are explicitly designed to mitigate that.

Overview
Adds a node batching pipeline (shared/node-batch) that mirrors the wall batch but uses THREE.BatchedMesh per (level, material, attribute-signature) so static items, columns, and wall-hosted doors/windows can draw through instanced containers after a settle window, while source meshes stay mounted and are only draw-hidden with the existing 'batched' layer hold.

NodeBatchSystem is mounted once from the item system bundle and orchestrates join/release from dirty marks, selection/hover tint, live overrides, door/window animations, appearance changes, isolation, and thumbnail:before-capture (plus no-op on ?disable=draw). Candidates skip interactive/animated items, unsettled GLBs, transparent/array materials, and hosted child nodes; the item renderer now stamps itemHasAnimations when a GLB has clips.

The ?perf overlay gains a batch membership row via publishPerfBatchStats, a drawComposition probe, optional ?spike=batch BatchedMesh spike, and window.__itemBatch debugging hooks.

^{Reviewed by Cursor Bugbot for commit 1d7a548. 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: 9b34fc56-47be-4feb-acb6-7e2b2ee46476

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 393a494. Configure here.}