@woosh/meep-engine 3.39.0 → 3.40.0

package/src/shade/renderer/shadow/vsm/PLAN.md

@@ -0,0 +1,440 @@
+# Virtual Shadow Map — build-out plan (2026-10-04)
+
+Branch: `claude/virtual-shadow-map-build-64d4ad`. Nothing lands on master until Alex says so.
+
+## The brief
+
+* Finish the partial VSM in this directory, and give it a playground with debug views and scenes.
+* The number of page updates per frame is configurable.
+* Moving casters mark the pages they overlap stale. The detection runs **on the GPU in a compute
+  shader**.
+* Page requests come back to the CPU the way VT and VGeo feedback do. There they are prioritised,
+  allocated, and rendered under the budget.
+* Reuse the engine's code; no parallel versions of it.
+* An adversarial review at the end.
+
+## Forks, settled with Alex before implementing
+
+* **F1 address space: clipmaps** (camera-centred, toroidal), not the prototype's single quadtree over
+  a fixed region.
+* **F2 page rendering: a pooled view per page render**, reusing the raster/VG path as it is.
+* **F3: superseded prototype code is deleted** (D14).
+
+## What exists today
+
+* A mip quadtree over one orthographic light frustum: 16384² virtual, 256 tiles, a 4096²
+  `depth16unorm` pool.
+* A demand pass counting pixels per tile from the main depth, and a coarse-bounds reduction.
+* GPU allocation of pages **from zero every frame**. No caching, no invalidation, no page rendering
+  (`vms_render_tiles.js` is empty), no sampling.
+* Nothing reaches it at runtime. `GPUViewLightContext` is never constructed, so `GPUViewShadowMaps`
+  and `VirtualShadowmapRenderer` are reached only by specs.
+
+## The clipmap
+
+### Light space
+
+Light space is the view space of a rotation-only camera at the world origin, oriented as the light.
+In `Camera.update_view_matrix` terms:
+
+* `x = -dot(p, right)`
+* `y = dot(p, up)`
+* `d = dot(p, forward)`, the distance along the light
+
+The page grids live on (x, y), anchored to the world, so a page's content does not depend on where
+the camera is.
+
+### Levels
+
+* There are `K` levels (default 12). Level `k` has texel `t_k = t_0 · 2^k`, with `t_0` defaulting
+  to 1 cm.
+* Pages are 128 texels with a 4-texel border (`SHADOWMAP_ATLAS_BORDER`, which covers the PCF's
+  ±3.25-texel footprint), so a slot is 136 texels.
+* Page `k` spans `p_k = 128 · t_k` world units. World page `(wx, wy)` at level `k` covers
+  `[wx·p_k, (wx+1)·p_k) × [wy·p_k, (wy+1)·p_k)`.
+* Its parent at level `k+1` is `(wx >> 1, wy >> 1)` — floor division, exact for negatives on int32.
+
+### Windows
+
+Each level keeps an `N×N` window of pages (default N = 64, which is 8192 texels a level).
+
+* The window origin is `floor(camera_xy / p_k) - N/2`. The CPU computes it and writes it to the
+  record as integers, so the CPU and GPU agree exactly.
+* Cells are toroidal: world page `(wx, wy)` sits in cell `(wx mod N, wy mod N)`.
+* When a window scrolls, the CPU evicts only the cells it vacated. That costs O(scroll · N).
+* With the defaults, level 0 is selected within about 19 m of the camera. Its window reaches ±41 m.
+* The coarsest level's window is ±84 km.
+* The origin puts the camera's page N/2 pages in from the window's low edge, so on its high side the
+  window reaches at least N/2 − 1 = 31 pages past the camera's page.
+* The window covers the region where its level is selected whenever
+  `pixel_angle · (N/2 − 1) · 128 ≥ 2`, a pixel angle of at least 5.0e-4. That is a vertical field
+  of view of about 31° or more at 1080p, and 57° or more at 4K. (The first draft of this plan had
+  `N` for `N/2 − 1` and claimed 4x to spare; the review found it.)
+* Where it does not hold — a narrow field, a zoom, 4K at 50°, a negative LOD bias — the outer ring
+  of each level on its high side is served by the next level up that contains the point. A
+  positive LOD bias widens the margin.
+
+### Depth range
+
+There is one range for the whole clipmap: `[d_c - D, d_c + D]`, where `d_c` is the camera's `d`
+snapped to `D/4`. D defaults to 1000 m.
+
+### Mip selection
+
+`k0 = clamp(floor(log2(distance · pixel_angle / t_0) + bias), 0, K-1)`. The demand pass and every
+sampler run **one shared chunk**: the first level at or above `k0` whose window holds the point.
+So a pixel samples what it asked for, or a coarser resident page.
+
+The selection is distance-based (the camera position and pixel angle travel in the record), so a
+consumer with no neighbouring pixels — volumetrics, OIT, water — can still select a level.
+
+### Fallback
+
+The sampler walks levels upward from the selected one until a resident page is found. The walk is
+bounded by `K ≤ 16` and is usually one step.
+
+VT's quadtree closure does not carry over to toroidal windows: a scroll would rewrite descendants
+across levels. So the walk replaces it.
+
+## Where it lives: existing structures, no new bindings
+
+### Pool
+
+The pool is a `bind()`-ed rect of the shadow atlas (`GPUSceneShadowmapContext.bind`,
+`MaxRectanglesPacker`, depth32float). At 4080² it holds 900 slots shared by every level.
+
+### Light database
+
+Every lighting consumer already binds the light database. It gains three tables:
+
+* `shadow_virtual` — one record per map. It holds:
+  * the light view (mat4);
+  * the per-level window origins (`array<vec2i,16>`);
+  * near/far;
+  * `t_0`, K, N, page size, border, pool origin, slots per axis;
+  * the main camera position and pixel angle, and the LOD bias;
+  * the first rows and counts of its two runs (ranges, non-owning).
+* `shadow_virtual_page` — `K·N²` u32 rows, level-major, toroidal cell order. Each is a VT entry,
+  `vt_entry_pack(phys_x, phys_y, level)`, or `VT_ENTRY_INVALID`.
+* `shadow_virtual_slot` — one row per physical slot: the world page it holds (level, wx, wy, valid).
+  The stale test reads it.
+
+`shadow_directional` gains a nullable `virtual_map` link. `CSM_SHADOWMAP_STRUCT` becomes
+`DIRECTIONAL_SHADOWMAP_STRUCT`. `shadowmap_sample_directional` branches on the link, and the CSM path
+is untouched.
+
+## Reused
+
+| Need | From |
+|---|---|
+| Slots, LRU, protect window, finest-first tie-break | `VTPhysicalCache`'s bookkeeping, split out of its textures with no behaviour change; the VT specs keep pinning it |
+| Page-table entry encode/decode | `vt_entry_pack`/`unpack`/`VT_ENTRY_INVALID`; the WGSL `vt_entry_unpack` lifted from `build_chunk_vt_lookup` into the static `chunk_vt_page_table_entry` that `VT_CONSTANTS` already names (a dangling link today) |
+| Readback | `graph_read_buffer`, with the in-flight cap that skips the frame when full (VT 3, VGeo 2) |
+| Choosing the frame's pages | `IndexedFloatMaxHeap` drained to the budget, as `ShadowmapDrawSelector` does |
+| Rendering a page | `RasterizationJob` + `execute_rasterization_jobs`, the shadow pass descriptors, a viewport into the atlas, exactly `#draw_direct`; meshlets, alpha-tested and **VG cut-per-view** come with it |
+| Sampling a page | `sample_shadowmap_atlas_for_light(page_view_projection, …, slot_rect)`: CSM's and spots' own bias and 5-tap PCF |
+| Map lifecycle | `Shadowmap`, `ShadowmapRegistry`, `process_lights`' rebuild-on-settings-change (the tetrahedron and cascade-count precedent) |
+| Mover inputs | `meshes.bounding_box`, `transforms.global`/`prev_global`, the `MESHES_TABLE` page iterator (the `shader_csm_caster_range` shape), the skinning bindings |
+| Compute passes | `ComputeShader` + `ShaderResourceSetDescriptor`, immediates for small per-dispatch state |
+| Debug | `RenderExtension` (`BeforePresent`/`Overlay`), `graph_image_pass`, the turbo depth map of `draw_texture_as_rgba` |
+
+## Decisions
+
+**D5 Demand (GPU, per main-view pixel).**
+- The pass reads depth and computes the world position, then the level, the world page and the
+  toroidal cell.
+- It does an `atomicAdd` on the cell's counter. The add is subgroup-aggregated when all of a
+  subgroup's lanes hit one cell.
+- The lane that sees the old value 0 appends `[level, wx, wy, count, d]`. `d` is that pixel's light
+  depth, used when a light changes. Dedupe and append happen in one step.
+- A fixed-size gather writes the final counts into the list.
+- No ancestors are requested by the GPU, per NOTES.md.
+
+**D6 Movers (GPU, scene-level, once a frame).**
+- The pass runs over every mesh-row slot, including slots in pages since freed. It uses the
+  page-iterator dispatch and covers a high-water mark of rows.
+- It keeps a VSM-owned per-row buffer of the "bounds last seen".
+- A row is a mover when **any** of these holds:
+  1. `global != prev_global` — every rigid change, AABB-invariant rotations included;
+  2. its world box, geometry or material differs from the one last seen — appear, remove, mesh or
+     material swap, deformation that changes bounds;
+  3. it is skinned and a joint's skin matrix differs from last frame's, which the animation manager
+     keeps for motion vectors — a pose that changes inside the box. (The first build listed every
+     skinned mesh every frame, by category; the review found it.)
+- The mover's `cur ∪ last` world box is appended to a list with capacity 4096.
+- The test is observed, not declared (the `LastUpdateFrame` shape).
+
+**D7 Stale (GPU, per map).**
+- An indirect `(ceil(slots/64), movers, 1)` dispatch: one workgroup per mover, one lane per slot,
+  **no per-thread loop**.
+- Each lane widens the slot's page rect by its border, and tests it against the mover box projected
+  through the light view.
+- On a hit, `atomicExchange(&stale[slot], 1) == 0` appends the slot to the stale list.
+- If the mover count exceeds capacity, every occupied slot is marked stale, and the overflow is
+  counted.
+
+**D8 Readback.**
+- One transient feedback buffer per map, cleared with the encoder (never queue-written: the
+  `framegraph-buffers-are-pooled` rule).
+- It holds a header (counts and drops), the request list, and the stale list.
+- Up to 3 readbacks are in flight. Each reading carries its frame.
+- Readings older than the map's last invalidation are dropped.
+
+**D9 CPU page manager** (`VSMPageManager`, pure CPU and specced on its own).
+- **Each reading** replaces the want set, because each reading is a whole-frame snapshot.
+- It touches the resident pages, and the serving fallback of every missing page.
+- It sets the per-slot stale flags, unless the slot was rendered at or after the reading's frame.
+- **Each frame**, candidates are drained from a max-heap to `page_budget`:
+  - **Uncovered** wanted pages are those with no resident page anywhere up their chain. Each is
+    covered by **one** page `COVER_STEP = 3` levels up, deduped per cell by frame stamp, before
+    anything finer. A cover page is drawn only because pixels are about to sample it, which keeps to
+    NOTES.md's "coarse tiles only when used".
+  - **Stale and wanted** pages come next, ordered by pixel count.
+  - **Missing but covered** pages come last, by pixel count, coarser first on ties.
+- A missing page takes a free slot, or evicts the least recently touched page outside the protect
+  window. If nothing qualifies, it is refused and counted.
+- Rows change only on delta: page-table rows on install, evict and scroll, slot rows on install and
+  evict. They are written before `draw()`'s existing `database.update`.
+
+**D10 Light change.** A change of the light's rotation, or of the snapped depth centre, means:
+- every page is evicted;
+- readings recorded before the change are dropped;
+- the last want set is **re-projected** into the new light space, through each want's page centre
+  and representative `d`, so wants exist the same frame;
+- everything is now uncovered, so a few cover pages render first, the same frame.
+
+Shadows go coarse and refine at the budget rate. They are never sampled through a projection they
+were not rendered with.
+
+**D11 Rendering.**
+- One pooled `View` + `OrthographicCamera` per budget unit, from the shadow context's own
+  `ViewManager` (VG `tau_scale` 2, like the cascades).
+- A page sets the light rotation and its border-widened ortho planes, and runs
+  `RasterizationPipelineType.Fast`: the point-light path, without an HZB. A pooled view's previous
+  HZB belongs to another page, and occlusion buys nothing on a 136² viewport.
+- All of a frame's page jobs go into one graph, as `#draw_direct` does with cascades.
+- Sampling widens the projection by the same border, so the page edges match what was rendered.
+
+**D12 Selection and knobs.**
+- `Renderer.feature_virtual_shadow_maps` (off by default) switches every directional light to VSM.
+- A flip rebuilds the maps in `process_lights`, like `feature_tetrahedron_point_shadows`.
+- `shadow_virtual_page_budget` (default 8) is the brief's page updates per frame.
+- `shadow_virtual_lod_bias` (0).
+- `shadow_virtual_first_texel_size` (0.01 m). Changing it rebuilds the maps.
+
+**D14 Deleted**, along with its specs:
+- `vsm_tile_allocation_pipeline`;
+- `vms_pipeline_compute_coarse_bounds` and `debug_inspect_coarse_bounds_buffer`;
+- `VirtualShadowmapRenderer`, `GPUViewShadowMaps`, `GPUViewLightContext`;
+- `GPUVirtualShadowTextureResidence`;
+- `render/vms_render_tiles.js`;
+- `VSM_UNIFORMS_STRUCT`;
+- `decode_tile_address` and `debug_inspect_residence_buffer` (quadtree-only).
+
+The demand pass is the prototype's residence pass reworked, and `VirtualShadowMap` evolves in place.
+
+## Frame timeline
+
+```
+frame N   head: readings delivered since N-1 → want set, touches, stale flags
+          select_for_draw: map.update — light view, windows (scroll → evict), invalidation, record
+                           → candidates → heap → page_budget jobs; allocate/evict → row deltas
+          draw: page jobs (Fast, pooled views) into slots; records; database.update
+          Shading graph, after the G-buffer:
+              movers (scene, once) → per map: demand, gather, stale args, stale test → readback
+          lighting: shadowmap_sample_directional → virtual_map? → level walk → VT entry →
+                    sample_shadowmap_atlas_for_light(page VP, slot rect)
+frame N+2..3  reading N lands, applied at the next head
+```
+
+A mover's shadow lags by the readback latency (2–3 frames) plus its place in the queue. That lag
+comes with CPU scheduling, which the brief asks for. On the mover itself it reads as acne; see Known
+limits.
+
+## Playground: `src/shade/playground/vsm/`
+
+**Scenes.**
+* **Courtyard:** ground, pillars, walls, an overhang, thin poles at distance, a long avenue reaching
+  out through the clipmap levels, and movers (orbiting boxes, a pendulum, a bobbing sphere).
+* **Crowd:** N wandering boxes, adjustable past the 4096 mover capacity.
+* A **sun sweep** toggle in either scene.
+
+**Controls.**
+* VSM/CSM A/B.
+* Page budget, LOD bias, first texel size.
+* Movers and sun sweep on/off.
+* Camera fly-through presets.
+* Freeze residency (stop applying readings).
+
+**Debug views.**
+1. A screen overlay, through an extension, showing one of: the serving level as a ramp; the deficit
+   (desired − serving), red; page id hash, to show page edges; the plain shadow factor.
+2. The physical pool, in the Overlay phase: turbo depth with the slot grid tinted by state (free,
+   resident, stale, rendered this frame).
+3. The clipmap, from CPU state on a 2D canvas: one panel per level for the N×N window, with
+   resident, wanted, stale and uncovered cells, and the camera.
+4. Stats:
+   - wants, uncovered and stale per reading;
+   - renders this frame, and the backlog;
+   - movers and overflow;
+   - pool use, evictions, refusals;
+   - scroll evictions;
+   - invalidations;
+   - readbacks in flight and dropped.
+
+**Console.**
+- `vsm_lab` exposes `renderer`, `scene`, `map()`, `stats()` and `step(n)`.
+- `verify()` holds the animation still across its readbacks. It checks that the page-table rows equal
+  the CPU's residency, that the slot rows agree, that no world page has two slots, and that a still
+  scene converges to "nothing uncovered, nothing missing" within the expected number of frames.
+
+## Work, as commits (each green)
+
+1. VT extraction: the `VTPhysicalCache` slot base and `chunk_vt_page_table_entry`.
+2. Light database: the `DIRECTIONAL_SHADOWMAP_STRUCT` rename + `virtual_map`, and the three VSM
+   tables with links and ranges. CSM writes NULL.
+3. Shared chunks: light-space, level selection, world page and toroidal cell, the page VP mirroring
+   `ortho_reverse_z`, and the lookup with its level walk.
+4. `VSMPageManager`: readings, want set, cover, priority, heap, allocation and eviction, windows and
+   scroll, invalidation and re-projection, row deltas, debug accessors.
+5. Shadow-context integration: the `process_lights` branch, settings pushes, page jobs in `draw`,
+   records, evict and teardown.
+6. GPU feedback: demand, gather, movers, stale test, readback, and the Renderer hook beside VT's.
+7. Sampling: the `shadowmap_sample_directional` branch.
+8. Deleting the superseded files (D14).
+9. The playground, its scenes and debug views.
+10. Adversarial review, and its ledger worked red-then-green.
+
+## Tests, by tier (no mocks, hooks or `.each`; helpers inside the specs)
+
+* **Tier 1:** every new WGSL module validated.
+* **Tier 2 (emulator):**
+  - level selection against a distance oracle, with the window fallback;
+  - world page and cell for negative coordinates;
+  - **the page VP built in WGSL equals the CPU page camera's VP** (render/sample agreement);
+  - the lookup's level walk;
+  - the demand kernel on synthetic depth, giving the list plus counts;
+  - movers on real `gpu_database_words`: a still row, a moved row, appear, remove, mesh swap,
+    and a row in a freed page;
+  - the stale test: hit, miss, dedupe, overflow.
+* **Tier 3 (SoftwareGPUDevice):**
+  - `process_lights` builds, rebuilds and evicts VSM maps, handing back the pool rect and rows;
+  - `draw` encodes at most `budget` page passes, with viewports exactly on slots;
+  - the host-written page and slot rows;
+  - readback scheduling and its cap;
+  - a teardown leak spec.
+* **CPU:**
+  - priority, budget, and covers ahead of everything else;
+  - LRU and the protect window;
+  - the stale guard by frame;
+  - scroll eviction;
+  - invalidation and re-projection;
+  - a random fuzz holding "page rows == residency".
+* **Tier 4:** a one-off headless-Chrome drive of the playground, reported and not committed:
+  pictures, `verify()`, stats, and paired frame times at budgets 1/8/32, a few hundred frames.
+
+## Known limits (stated, not fixed here)
+
+* A page drawn under a clamped VG cut stays coarse until it is invalidated. The pooled view does not
+  keep per-page attribution for `caster_detail_pending`. This is a fact about the code; its cost has
+  not been measured.
+* Demand and level selection follow the main view.
+* Continuous light rotation invalidates every frame. Caching then buys nothing, and the budget bounds
+  what is drawn (UE's VSM has the same property).
+* Casters further than D along the light from the camera's snapped depth are clipped. A receiver
+  past the far end is shadowed only by casters drawn inside the range: the atlas sampler holds its
+  reference depth just above the cleared value, where it would otherwise read shadowed everywhere.
+* A change to a material's parameters — the same material, a new dissolve cutoff — is not a mover.
+* ~~A shadow starts 1–1.5 texels of its page short of where a caster meets the ground.~~ Closed
+  2026-10-04: every shadow caster is now drawn by its front faces, as the main view draws it. Back-face
+  casting stacked on the shared rasterizer slope bias (`DEPTH_STENCIL_STATE_SHADOW`) had pushed a
+  caster's steep far face past the ground near its base, in every shadow type. Point lights needed
+  their sampler's depth bias made texel-scaled to stay clean on front faces.
+* **A mover self-shadows against its own stale image.** A stale slot reaches the CPU by readback, so a
+  page holding a mover is 0–5 frames old when it is sampled, about 1.6 on average (courtyard, budget
+  64). Front-face casting puts that image on the mover's own lit faces, which read as hatched.
+  - Measured on an RTX 4090 in headless Chrome, the same pose through stale pages against freshly
+    drawn ones: pages 1, 2 and 3 frames stale, at the orbiters' motion at 140 fps, darken 27%, 47% and
+    52% of an orbiter's pixels by more than 10%. Cascades, which redraw every frame: 0%. Back faces
+    cast in the same arms: 0–0.7%.
+  - Fresh pages are clean, so the bias is sufficient. Bias cannot absorb staleness: a motion Δ over
+    the latency needs |Δ·n| / cos θ of clearance, up to about 18 cm (9–18 texels at levels 0–1) for
+    three frames at 3.6 m/s.
+  - Removing it means drawing a mover's pages in the frame it moves, as UE 5.4 does: it invalidates
+    the old footprint during the scene update and draws a moved instance into every allocated page.
+    At the playground's close framing about 24 wanted pages hold a mover each frame, against 7 pages
+    drawn per frame now.
+* Below the window coverage condition (see Windows), each level's outer ring is served a level
+  coarser.
+
+## Status (2026-10-04, branch only)
+
+Landed as planned, with these departures, each made when the code or a measurement asked for it:
+
+* **Window corners are a table** (`shadow_virtual_level`), not an array in the record: a by-value
+  record array indexed by level spills to local memory (the CSM 217→80 µs lesson).
+* **Stale flags persist** on the GPU until a readback lists them, so a frame whose readback the cap
+  skipped loses no movers.
+* **Priority is aged.** Covers first; stale and missing pages compete by
+  `log2((1 + importance)(1 + frames waited))`, the weighting `compute_shadowmap_update_score` uses.
+  Strict "stale before missing" starved missing pages for as long as anything moved: the 5000-walker
+  crowd left 217 waiting.
+* **Pixels are weighed by where they are on screen.** The demand pass adds each pixel's weight under
+  the automatic exposure's metering mask (`chunk_screen_importance`, moved out of the exposure's
+  histogram shader so both share it): 64 at full importance over most of the screen, falling over
+  13% of its height in from each edge, never below 1. So a page wanted in the middle of the view
+  outranks one wanted by as many pixels at its edge, and the middle resolves first.
+* **An uncovered page is offered itself** beside its cover, so a budget with room fills both the same
+  frame.
+* **Agreement in the demand pass** is `subgroupMin == subgroupMax`. The emulator has no
+  `subgroupAll`, and this form is exact on a device.
+* **The cell index uses `u32()` per component**: the emulator returns NaN components for a vector
+  `bitcast` between i32 and u32.
+* **Engine fixes found on the way:**
+  - the GPU database's WGSL serde gains i32/vec2-4i;
+  - `read_wgsl_type_value` read signed vectors into a `Uint32Array` (negatives came back as their bit
+    patterns).
+
+**Measured** on an RTX 4090, headless Chrome, 1600×900, courtyard, paired arms in one launch:
+- GPU per frame is 734–758 µs at budget 0, 779–795 at budget 1, 1072–1076 at budget 8 (7.1–7.5 pages),
+  and 1273–1305 µs for 3 cascades.
+- A page costs about 40–45 µs GPU and about 85 µs CPU.
+- The feedback passes cost about 59 µs, the demand pass 46 of it.
+- `verify()` passes: GPU page table, slots and windows equal the CPU's after settling.
+
+So the pooled-view cost (F2) is measured: at budget 8 it is CSM's CPU cost and less than CSM's GPU
+cost in this scene.
+
+The sun sweep at 0.05 rad/s falls back to cover pages every frame, which is the light-change limit
+above, observed.
+
+## Adversarial review (2026-10-04)
+
+Four reviewers, one dimension each: GPU shaders and dispatch, the page manager and integration,
+regressions and house rules, and the playground. The findings are in `REVIEW_LEDGER.md`, worked in
+order of severity, each pinned by a test that failed first wherever a test can see it, and each in a
+commit of its own. Among them:
+
+* **A receiver past the far end of the depth range read black.** Fixed in the shared atlas sampler.
+* **The bias was sized off the page's matrix**, which takes in the depth range as the sun climbs: 29 m
+  a texel straight overhead. The virtual sampler hands the atlas sampler the page's texel.
+* **A light turning every frame lost every reading**, older than the cutoff each time. Readings are
+  now carried from the light space they were recorded under, 16 remembered.
+* **A camera on a snap plane moved the depth range every frame.** The range re-centres only once the
+  camera is a whole snap from its centre.
+* **Skinned meshes were movers by category**, and **mesh or material swaps were missed.**
+* The rest are smaller: the budget remainder, the pool search after a refusal, the dispatch fold,
+  the readback stamps of a new view, the playground's `verify()`, inset, crowd and controls.
+
+**Measured on the device after the fixes** (RTX 4090, headless Chrome):
+* The demand pass's subgroup counting is exact. Every pixel on the ground gave requests whose pixel
+  counts summed to the 1,265,556 pixels of the view, with no page asked for twice.
+* The movers' wave-aggregated append listed 400 of 400 moving walkers.
+* `verify()` passes on both scenes, with the new record and page-to-slot-to-page checks.
+* **The virtual path costs the cascades about 2.4 µs.** Every directional shader carries the virtual
+  branch, uniform but compiled in. With cascades, deferred shading took 48.1–49.2 µs with it and
+  46.1–47.1 µs with the branch stripped, over three launches a side alternated at 1578×802, and
+  volumetric lighting about 1 µs more. Open: taking it out would mean a lighting shader per
+  technique.
+* The cascades share the matrix-read bias scale the virtual pages had, but measure 1.0–1.4x their
+  true texel from 45° to 89° of elevation: their depth ranges are fitted, so it stays small.

package/src/shade/renderer/shadow/vsm/REVIEW_LEDGER.md

@@ -0,0 +1,43 @@
+# Virtual shadow map — adversarial review ledger (2026-10-04)
+
+There were four reviewers, each covering one dimension:
+
+- **G**: shaders and dispatch.
+- **CPU**: page manager and integration.
+- **R**: regressions, house rules and test quality.
+- **P**: playground and debug views.
+
+Each row is worked red-then-green where a test can see it. "Device" means checked once on the RTX 4090 outside the repo, and reported in the commit.
+
+| # | Severity | Finding | Status | Pinned by |
+|---|---|---|---|---|
+| 1 | major | Turning VSM off left `shadow_directional.virtual_map` naming the freed row; the sun went unshadowed (R1) | fixed `0189945bd` | VirtualShadowMap.spec, the flip test |
+| 2 | major | Light rotating every frame: every reading is older than the cutoff and dropped, and the wants freeze and drift (CPU1) | fixed: readings carried through the view they were recorded under (16 light spaces remembered) | VSMPageManager.spec, the two "carried" tests |
+| 3 | major | Per-view `frame_index` restarts with a new camera; the map drops readings until it catches up (CPU2) | fixed: each map keeps its own count | graph_vsm_feedback.spec, the second-camera test |
+| 4 | major | Skinned rows are movers by category, every frame, idle or not (R6) | fixed: a skinned mesh is a mover when a joint's skin matrix differs from last frame's; the binding carries its joint count | shader_vsm_movers.spec, the skinned test; GPUMeshSkinningContext.spec, the matrices test |
+| 5 | major | `verify()` "settles" passes vacuously when every page is refused, and needs no reading taken after the freeze (P1) | fixed: needs a reading recorded after the stop that wants pages; refused pages count as waiting (row 11) | device: both scenes pass |
+| 6 | major | The inset's red edge shows GPU flags the compact pass has already cleared, not the CPU's stale state (P2) | fixed: the overlay uploads the page manager's stale state; a stale slot is washed red | device: screenshot of the crowd |
+| 7 | major | Each crowd resize leaks a whole scene's GPU state (P3) | fixed: the crowd resizes in place | device: 200 to 400, same scene |
+| 8 | minor | Depth snap has no hysteresis: a camera on a snap plane invalidates almost every frame (CPU3) | fixed: the range re-centres only once the camera is a snap from its centre | VirtualShadowMap.spec, the snap-plane test |
+| 9 | minor | A pool that does not fit allocates about 2.3 MB of manager arrays per retry, every frame (CPU4) | fixed: the pool is bound before the map is built | none: the allocation is not visible through the API |
+| 10 | minor | The budget remainder always goes to the first suns: with budget < suns, later suns starve (CPU5) | fixed: the remainder goes round the maps a frame at a time | VirtualShadowMap.spec, the two-suns test |
+| 11 | minor | After one refusal, `select` keeps draining the heap, scanning 900 slots per candidate (CPU6) | fixed: no slot search after the first refusal of a frame; the backlog counts the refused | VSMPageManager.spec, the full-pool test |
+| 12 | minor | The mover tracker outlives the feature (R2) | fixed: destroyed on the first frame with no virtual map | none: the tracker is private |
+| 13 | minor | Every directional-shadow shader carries the virtual path; cost not measured (R3) | measured, open: with cascades, deferred shading costs 48.1–49.2 µs with the path and 46.1–47.1 µs without (+2.4 µs, 5%), volumetric lighting +1 µs; RTX 4090, 1578×802, three launches a side alternated | device A/B, not committed |
+| 14 | minor | `afterEach` hooks in new specs (R4); vacuous assertions (R5) | fixed: hooks gone; the cover test derives its level from the constant | |
+| 15 | minor | The mover dispatch has no fold: 65,535 × 128 rows is a hard cap (R7) | fixed: folded into rows of 65,535 workgroups | shader_vsm_movers.spec, the folded test |
+| 16 | minor | Subgroup aggregation in demand and append is never exercised; the emulator is one lane wide (R/T2) | checked on the device: the requests' pixel counts summed to all 1,265,556 pixels with no page twice; 400 of 400 moving walkers listed | device, not committed |
+| 17 | minor | The rows spec reads the CPU copy, not what reaches the device (R/T3) | fixed: entries, slots and windows read from the database's flushed words | VirtualShadowMap.spec, the rows test |
+| 18 | minor | No test of the budget split or of two suns (R/T4) | fixed with row 10 | VirtualShadowMap.spec, the two-suns test |
+| 19 | minor | `verify()` readback runs while frames continue; record row not read back; no GPU cell↔slot check; TypeError on missing rows (P4, P5) | fixed: page updates held across the readback; record, rows present, and page to slot to page checked | device: both scenes pass |
+| 20 | minor | The overlay's doc claims more than it checks (P6); it draws last frame's map on a scene switch (P7) | fixed: doc says what it runs; the map is assigned before the render | |
+| 21 | minor | `configure({scene})` does not switch scenes; a reload restores the dropdown but not the scene (P8); status line stuck (P9) | fixed | device: configure switches both ways, status returns |
+| 22 | minor | README overstates "pause"; per-frame allocations in the playground; bfcache `pagehide` (P10–P12) | fixed: wording; no per-frame state objects, aim_sun keeps scratch; reload on a persisted pageshow, as caldera does | |
+| 23 | minor | CHANGELOG entry missing; PLAN.md untracked (R10) | fixed | |
+| 24 | major | A receiver past the far end of the depth range reads shadowed against a slot nothing was drawn into: ground over ~1 km down-sun under a 30° sun, all of it from 1.1 km up under a high one (G1) | fixed: the atlas sampler holds the reference depth just above the cleared value | chunk_shadowmap_sample_virtual.spec, the "beyond the far end" test |
+| 25 | major | The bias is sized by a texel read off the page's matrix, which takes in the depth range as the sun climbs: 1.4x the true texel at 45°, 5.8x at 80°, 29 m straight overhead (G2) | fixed: the virtual sampler hands the atlas sampler its page's texel | chunk_shadowmap_sample_virtual.spec, the "overhead sun" test |
+| 26 | minor | A mesh or material swapped in place, box and transform unchanged, is not a mover (G3) | fixed: the pass remembers each row's geometry and material with its box (8 words a row) | shader_vsm_movers.spec, the "in place" test |
+| 27 | minor | PLAN's window coverage condition is off by two: a level's window reaches 31 pages on its +x/+y side, so a view needs a pixel angle of at least 5.0e-4 (about 31° vertical field at 1080p, 57° at 4K), not 2.4e-4; below it the outer ring of each level is served one level coarser (G4) | PLAN corrected, and the coarser ring listed as a known limit; argued, not measured | |
+| — | note | verify script ships (R8): precedent `skinned_blas_refit/verify_*.js`; the owner's call | no change | |
+| — | note | Per-frame graph and job objects (R9): the `#draw_direct` pattern, scaling with the page budget only | no change | |
+| — | note | The cascades share the matrix-read bias scale of row 25: measured at 1.0–1.4x their true texel from 45° to 89°, their depth ranges being fitted | no change | device, not committed |

package/src/shade/renderer/shadow/vsm/VSMMoverTracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The scene's memory of where its casters were and what they were: {@link VSM_LAST_SEEN_WORDS} per
+ * row of the `meshes` table — the world box {@link shader_vsm_movers} saw each row with last frame,
+ * and its geometry and material — empty for a row that held nothing. Comparing against it is how the
+ * mover pass sees a row appear, leave, change shape or change mesh, which no per-row fact of the
+ * scene database says.
+ *
+ * Covers every row the table has ever had — a high-water mark, so a page of rows that was freed
+ * still gets compared once more and its casters' old shadows found. Grows by doubling; a grown
+ * buffer starts empty and takes the old one's rows by a copy recorded in the next mover pass, in
+ * order with the rest of the frame.
+ */
+export class VSMMoverTracker {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * @returns {GPUBuffer|null}
+     */
+    get buffer(): any;
+    /**
+     * @returns {number} rows the buffer covers
+     */
+    get row_count(): number;
+    /**
+     * Cover at least `rows` rows.
+     *
+     * @param {number} rows
+     */
+    ensure(rows: number): void;
+    /**
+     * Record the copy of the rows the buffer had before it grew, if it did since the last call, and
+     * let the old buffer go once the frame is done with it.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     */
+    encode_growth(encoder: ShadeGPUCommandContext): void;
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=VSMMoverTracker.d.ts.map

package/src/shade/renderer/shadow/vsm/VSMMoverTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VSMMoverTracker.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/vsm/VSMMoverTracker.js"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH;IAwBI;;OAEG;IACH,+BAIC;IAED;;OAEG;IACH,kBAEC;IAED;;OAEG;IACH,wBAEC;IAED;;;;OAIG;IACH,aAFW,MAAM,QA+ChB;IAED;;;;;OAKG;IACH,qDAWC;IAED,gBAYC;;CACJ"}