085 — Window niches and shop windows: performance and follow-ups
Status: TODO. Written 2026-11-10 from the review rounds on PR #273 (window niches, shop windows cut into the wall, painted signs). Every point below came up there, more than once, and was left out of #273 on purpose: none is a visible fault on a typical walk. They are ordered by what they cost a phone.
Read first: docs/rendering.md (rows Window niches, Shopfronts,
Plinths), app/_components/window-niche-layer.ts,
window-niche-client.ts, lib/city/window-niches.ts,
lib/city/shop-windows.ts, scripts/bake-city-mesh.ts
(planShopfronts, appendShopfronts), ADR 0047 (phone memory).
STOP if a step makes a phone's memory grow (ADR 0047) or a WebGPU-only
check is needed that the headless WebGL2 e2e cannot make: then measure on
a real GPU (bun run shots, ?trail=1 on the iPhone) first.
A. Performance on the runtime path
- Refill without churn. Every 6 m (and every frame in a fast
flight)
fillrescans every packed niche within 270 m of every shown tile, allocates a candidate per niche, unpacks them twice and, when the set changed, rewrites the whole instance range. Group the niches by house atadd(a house → [first, end) index, its box and its nearest point), rank houses by their boxes, unpack only the picked houses, and write only the instances that changed (addUpdateRangeper run). Measure: refill time and GC in a flight over the Altstadt, desktop and phone. - Only the changed flag texels.
setNiched→markObjectswalks every object and re-uploads the tile's whole object texture for a few OBJECT_FLAG_NICHED bits. Either an update range over the changed rows or a small separate niched mask (one byte per object) the clay reads. - The wall copy off the main thread.
nicheInputscans every triangle of a full-LoD2 tile inprocessTileModel(accessors,applyMatrix4per corner) before the worker sees anything. Hand the raw quantised arrays and the tile's matrix over and filter and transform in the worker; weigh the copy as today (nicheCopyBytes). Watch the CPU-copy drop (cityCpuDroppable) andbvhBuilding: the arrays must be copied, not borrowed. - The cut variant compiled before it shows.
cutOnflips the clay'smaskNodeand only queuesrecompile, so the first tile that starts cutting builds theclay|nichespipeline in the frame (once per session and camera kind). Compile it before the flip: a stand-in mesh on the same geometry with a cut clone, or warm the variant once with the first city tile; keep the stand-in until the real mesh has drawn (three frees a node-builder state when its last user goes). Also: do not anchor the variant for Modell's camera (Modell never cuts), and keycompile-lanesrecords bymaterial.versionsocutGround(terrain design cut) stops building in the frame too;PostStack.recompilethen goes. - No discard in the shadow pass.
maskShadowNode = keepWalls(a constant true) still routes the clay's shadow depth through three's mask path with a discard and its own pipeline. Find a way to keep the walls whole in the shadow map without a mask node there. - One wall view per fragment.
clayWindowsevaluateswallViewtwice (recess,parts) andfwidth(s)twice (grid'sinside); compute once and pass down.
B. Bake
- Ask coverage, cut once.
planShopfrontsruns a fullcutWall(difference, earcut, edge loops) per bay only to learn whether it is covered, andappendShopfrontscuts again. A coverage-only pass (intersection areas) for the plan; or keep the plan's cut and reuse it. The (s, z) box reject is in (#273). - Plan and cut agree. Two shopfront records on one host and plane:
one's sign is cut before the other's window, which may then fall under
MIN_COVERalthough the plan broke the plinth for it. Plan signs as well, or take the plinth breaks from what was cut (lay the plinths after the cut, keeping the plan only for wall finding).
C. Correctness follow-ups (rare)
- The niche's colour as the wall's.
wallColourmixes base and tint only; the clay also darkens the lowest 5 m (GROUND_SHADE) and applies OSM colours, facade readings and articulation. Share the clay's wall colour node with the niche material (an instance attribute or the object texture) so a house keeps its tone at the 250 m hand-over. - Box front at a grazing view. The box's open front sits on the wall's mean plane; where a quantised triangle stands up to 3 cm in front of it, a ray past ≈ 55° through the cut's edge can miss the 4 cm overlap. A box reaching a little out of the wall only within the opening, or a deeper side overlap.
- Opening sizes past 5.1 m.
packNichescaps width and height at 255 ×SIZE_STEP_M; a taller stair-hall window would get a box shorter than its cut. Widen the field or refuse the niche (no cut: the object then keeps the drawn window). - Column index past 255.
jis packed in 8 bits; a wall with more than 256 axes would light its niches differently after dark. - Hidden while the BVH holds the index.
stands()reads the wanted hidden set, while the clay applies it once the BVH worker hands the index back (≈ 1 s on a phone): boxes may stand in the air for that long after a design moves. Refill when the deferredapplyHiddensettles, and read the applied set. - A sign over drawn windows on a raised host is placed from the
street's ground, not the host's base (
shopfrontMeshknows no base). - A stepped wall's niche whose opening straddles the wall's edge shows its box beside the wall (any probe on the wall places it). Clip the box to the wall's extent along the opening.
- CPU and shader grids tied by a test.
wallColumns/wallRowsre-implementclay-windows.tscolumns/rows; a test that evaluates both (the TSL graph on a fixed input, or shared constants with a golden table) keeps them one.
D. Structure
- One worker job queue.
window-niche-client.ts,bvh-client.tsandground-prep-client.tseach hand-roll start, give-up, abort, copy-until-answered and stop. One helper, parameterised by transfer and run-here. - Motion blur hold by time.
BLUR_HOLD_FRAMEScounts frames (83 ms at 144 Hz, 400 ms at 30 fps); hold by accumulatedmoveMs. - The ground-join audit (
scripts/ground-joins.ts) still reads the plinths from the unbroken features; read the baked stretches (afterwithoutSegments) so the plinths' budget measures what is drawn. drawSceneinpost-stack.tsis a single-use closure; inline it.
