@woosh/meep-engine 3.60.3 → 3.60.5

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

@@ -1,442 +0,0 @@
-# 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 per-row buffer of the "bounds last seen". Since 2026-10-27 the scene owns the pass and
-  the buffer (`GPUSceneContext.graph_movers`, `scene/movers/`), and the maps' stale pass is one
-  reader of its list among others (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md D32).
-- 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

@@ -1,43 +0,0 @@
-# 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 |