@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/renderer/geometry/virtual/runtime/SHADOW_PLAN_2026_09_28.md

@@ -1,529 +0,0 @@
-# Virtual geometry casts shadows — the plan
-
-**Closed 2026-09-29.** Everything below is done, withdrawn or measured moot, and §5 is what it
-deliberately leaves out.
-
-**2026-09-28, revision 3**, after an adversarial pass over revision 2 (three reviewers against the
-code; §6 is the ledger, and the sections it changed say so). **S1–S5 are done, S6 is withdrawn, and shadow
-views cut at twice the camera's τ; §7 is what each step measured.** It changes no decision in
-`VIRTUAL_GEOMETRY_DESIGN.md` — §4 already pins one cut per view and withdrew the claim that shadow
-views could reuse the camera's — and it takes `RUNTIME_PLAN.md` §9's "no shadow-view cuts" out of
-the list of things v1 does not do.
-
-## Decided
-
-1. **One cut per view, and a shadow view is a view.** Cascades, spots and a point light's cube faces
-   go through the same seam, the same per-view state and the same rules as the main view. Nothing in
-   the VG runtime knows which kind of view it is cutting for.
-2. **The engine owns the VG frame.** It is a core feature; a host does not open, read or close it.
-3. **VG shadows are not optional.** How is open; whether is not.
-4. **Proxies are not built now, and the architecture leaves room for them.** Nanite-style proxies
-   drawn in place of a cut for some views, behind a switch, may come later; §2.6 is where they would
-   go and what this work must not close off.
-5. **The order is §4's.**
-6. **Shadow views cut at twice the camera's τ** *(after S4)*. The shadow context sets
-   `tau_scale` to 2 on every view it owns (`SHADOWMAP_VGEO_TAU_SCALE`); §7.2 is the price.
-7. **No batched cascade cut** *(after S5)*. Cascades are boxes fitted to separate slices of the view
-   frustum — misaligned, overlapping only at the blend margins — so one descent over all three
-   shares no traversal work, only dispatches. §3 item 2 and S6 are withdrawn.
-
-Revision 1 argued from a measured match between a cascade's texel and the screen pixel at the far end
-of its slice. That argument is withdrawn: what a view's cut needs is a function of what projects into
-*that* view, and §1 says why the camera's view says nothing about it.
-
-## 0. What is true today — measured
-
-### 0.1 Virtual geometry receives shadows and never casts them
-
-Measured on `playground/vgeo_scene` with the textured Zorah rebuild (1,012 containers, 12,597
-instances, the scene's own sun), headless Chrome on the 4090, 1556×592. Each condition is a
-32-frame average after TAA has settled; the column is the fraction of pixels that go more than 16
-luma darker when shadows are switched on.
-
-| view | only VG in view | plus two ordinary `BoxGeometry` casters |
-|---|---:|---:|
-| authored | 0 | 0.110% |
-| oblique | 0 | 0.076% |
-| plan | 0 | 0.106% |
-
-Two identical captures differ by the same 0 at that threshold, so the VG column is noise. The boxes'
-shadows land on VG ground and are the only thing in the on/off difference; the dome and the
-greenhouse, under a sun 52° above the horizon, leave nothing on it.
-
-Before the far-plane fix of 2026-09-28 the page hid every shadow, not only VG's: `look()` set
-`camera.far = distance × 2000`, and `DirectionalLightShadowmap.update` takes `camera.far` as its
-shadow distance, so from the authored viewpoint the nearest cascade spanned 0–5.8 km. The page now
-fits the far plane to the world's bounding sphere, capped at twenty times the orbit distance, and
-the numbers above are from that version.
-
-### 0.2 Why, in the code
-
-Three things each stop it, in the order a frame meets them:
-
-- **The frame is not open yet.** `Renderer.render` calls `sm.select_for_draw` / `sm.draw` before it
-  creates the `Shading` graph, and the VG frame is opened by the host's `RenderExtension` at
-  `FramePhase.FrameStart` — on that graph. Every shadow view is recorded while
-  `runtime.feedback === -1`, and `graph_vgeo_expand_if_enabled` returns at its first check.
-- **The graph is not the frame's.** Each shadow map records on a `new FrameGraph("shadows")` of its
-  own, and the feedback buffer is a transient of the `Shading` graph. Were the frame open, the
-  second check (`runtime.frame_graph !== graph`, REVIEW_LEDGER M13) would skip anyway, and must:
-  the handle names a resource that graph has never heard of.
-- **An orthographic view has no projection the cut can take.** `VGeoViewCut.set_projection` reads
-  `view.camera.camera.fov`; a cascade's `OrthographicCamera` has none, and `vg_project` divides by a
-  distance that means nothing to a parallel projection.
-
-Nothing else stops it. The seam already sits in both rasterization paths shadow views use —
-`graph_rasterize_scene` for cascades and spots, `graph_rasterize_scene_fast` for a point light's cube faces — and
-every `GPUViewContext`, shadow views included, already owns a `VGeoViewCut`. The cascade fit's
-caster range (`shader_csm_caster_range`) already reads every `meshes` row's world bounds, VG rows
-among them, so the near planes already reach VG casters.
-
-### 0.3 What a cut costs now
-
-`GPUProfileSession` at `TIMING`, 90 frames, medians, the same page, `max_iterations` 16 (escalated),
-`descent_steps` 24:
-
-| | authored | oblique |
-|---|---:|---:|
-| GPU frame, sum of spans | 2,903 µs | 2,931 µs |
-| `VGeo cut traverse`, 48 dispatches | 984 µs | 814 µs |
-| `VGeo cut queue prepare`, 48 dispatches | 60 µs | 60 µs |
-| collect + seed, 3 each | 29 µs | 35 µs |
-| per site: traverse | 815 / 120 / 46 µs | 630 / 98 / 70 µs |
-
-The main view records **three cut sites** — the per-opaque-bucket seam of
-`graph_rasterize_partial_opaque` plus the one in `graph_rasterize_remaining_opaque` — and the work
-is almost all in the first. A site with nothing to do still pays its ladder: sixteen traverse
-dispatches at ~3 µs, sixteen prepares, collect, seed, the scan and the remainder, about **80 µs**.
-The cut is already the largest line in the frame, over a third of it.
-
-## 1. Why a shadow view needs its own cut
-
-**A cut is a function of what projects into the view it is drawn into, and a caster's projection into
-a shadow map has nothing to do with its projection onto the screen.** A small object high above the
-observer is a speck to the camera — or outside its frustum altogether — and throws a large shadow on
-the ground in front of it. That shadow needs the caster's fine levels; the camera's cut holds its
-coarse ones where the camera sees it at all, and nothing where the camera does not. No property of
-the camera's view bounds what a shadow view needs, so a shadow view gets its own cut exactly as the
-main view does, with its own projection and its own threshold in the units of its own render target.
-
-It follows that **a shadow view is a streaming client in its own right.** Its demand is not a subset
-of the camera's — the speck in the sky wants pages the camera will never ask for — so its wants reach
-residency on the same terms as the main view's (§2.4), and residency, which is already scene-wide,
-arbitrates between them.
-
-**This is what the references do.** Unreal's Nanite renders every virtual-shadow-map view with its
-own culling and LOD, against that view's resolution; Bevy's meshlet renderer runs a full cull and
-raster per shadow view, and its LOD test reads the bound view's own projection and viewport. Neither
-reuses the camera's cut. The one reference that does, NVIDIA's `vk_lod_clusters`, traces its shadow
-rays against the camera's cut and documents the cost: off-screen instances cast from a coarser level,
-and their shadows change when they come into view.
-
-**Self-shadowing is measured, not argued.** A surface that is both receiver and caster is drawn at
-the camera's level in the G-buffer and at the shadow view's level in the map. The receiver bias in
-`chunk_sample_shadowmap_atlas_for_light` is a normal offset and a slope-scaled depth offset in texels,
-over a 5×5 filter; whether that absorbs the mismatch is S3's measurement (§4), and a new bias term is
-added only if it fails.
-
-## 2. What changes
-
-### 2.1 The engine owns the VG frame *(rev 3)*
-
-The renderer opens the frame for a scene with virtual geometry enabled, **before the shadow block and
-outside its `if`** — so a frame with shadows off still opens and closes — and schedules the readback
-and closes the frame inside the `Shading` graph's recording, after the last phase and before
-`encodeGraph`, in a `finally` so a throwing phase cannot leave it open. `VGeoFrameStart` and
-`VGeoFrameEnd` are deleted from **all three** hosts — `vgeo_scene`, `vgeo_runtime` and `caldera`. That
-closes REVIEW_LEDGER U1: `GPUSceneContext` constructs the runtime, residency and `VGeoFeedbackLoop`
-today, and nothing in the engine drives them. The frame is opened *for* the view being rendered, which
-takes slot 0 (§2.4); that is the frame's own view, not a kind of view.
-
-The feedback buffer stops being a graph transient. It becomes a buffer the runtime owns
-(`STORAGE | COPY_SRC | COPY_DST`), re-made when its layout grows, and **imported** into each graph that
-cuts via `FrameGraph.import_resource` — a write to an imported resource marks the pass side-effecting,
-so nothing is culled. The seam asks the runtime for the graph's handle (`feedback_in(graph)`), and the
-first graph of a frame to import it records a pass that **clears the counter and touch words in-stream**
-(`clearBuffer`, no upload; the want records need no clearing). M13's hazard — a handle from one graph
-named in another — then cannot be written. Ordering between graphs needs nothing: `encodeGraph`
-compiles and executes each graph into the frame's one encoder as it is handed over, and there is one
-submit per render.
-
-`GraphicsEngine.render_to_sampler` renders eight times per call and each is a frame, which is the
-right semantics — each is a render of a view — and it advances the residency's protect clock eight
-times; noted, not changed.
-
-### 2.2 The cut takes an orthographic projection *(rev 3)*
-
-**One derivation, from the projection matrix the view actually draws with** — no camera-type branch in
-the seam, and no widths the old setter could not take:
-
-    k = ½ · max(width · |P[0]|, height · |P[5]|)      w = −P[11]
-
-For this engine's infinite reverse-Z perspective that is `height / (2 tan(fov/2))` and `w = 1`; for its
-reverse-Z orthographic, `height / (top − bottom)` on the finer axis and `w = 0`. Anything else asserts.
-`vg_project` divides by `w · d + (1 − w)` and tests **that** for `≤ 0`, so an orthographic camera whose
-transform sits inside a root sphere — a cascade's centre usually does — is not taken as an eye inside
-the sphere.
-
-The weight lives **in the instance record** (`VGEO_INSTANCE_OFFSET.DISTANCE_WEIGHT`), not only in the
-params, so the traversal never reads a per-view uniform for it. The collect's scale term is
-`k · σmax / (w · σmin + 1 − w)`: σmax/σmin in perspective, as today, and σmax alone orthographically,
-where no distance cancels a scale. `vgeo_select_cut` gets the same term.
-
-**The proof has to discriminate the scale term, not just the formula** *(rev 3)*: the oracle has no
-instance transform, so agreement alone would check the GPU against the same formula it was given. S1
-adds a direct collect check at a uniform scale of 7 (σmax = 7 against σmax/σmin = 1) and a metamorphic
-one — an instance scaled by s in an orthographic view cuts exactly like an unscaled one at s times the
-extent — plus the orthographic frustum held against `construct_frustum_planes`.
-
-Bevy's `lod_error_is_imperceptible` has this shape, and its orthographic arm is where its bug was: PR
-#19318 fixed a metric that had left shadows visibly faceted.
-
-### 2.3 τ is the runtime's, scaled per view *(rev 3)*
-
-Revision 2 made τ an absolute per-view value. That splits the one quality lever — the playgrounds'
-slider sets `runtime.tau`, and an absolute shadow τ of 2 becomes *finer* than the main view the moment
-the slider goes to 4 — and the reference it cited is relative. So a view carries **`tau_scale`**,
-default 1, and cuts at `runtime.tau × tau_scale`. Whoever owns a view may set it; nothing in the runtime
-knows what kind of view it is. S4 measures before anything but 1 is set.
-
-**Shadow views default to 2** *(after S4)*: the shadow context sets it on every view it owns
-(`SHADOWMAP_VGEO_TAU_SCALE`), and the runtime still knows nothing of what kind of view it cuts for.
-At 2 the cascades draw 39% of the clusters they do at 1, and false light against a fine reference
-rises 2.3–4.7× (§7.2).
-
-### 2.4 Feedback is per view *(rev 3)*
-
-Each view that cuts in a frame takes a **slot**. Per slot, the layout carries a header — the want
-counter and the stats block — and a want slice; the touch bits after the headers stay shared, since a
-page any view draws from is a page in use. The view's params hold its offsets (`stats_base`,
-`want_count_offset`, `want_base`, `want_capacity`), so this is parameters, not bindings: every kernel
-that writes feedback already binds `params`, and the traverse is at its tenth storage buffer with no
-eleventh. `want_capacity` keeps its meaning — pages one frame may ask for across every view — and is
-divided evenly among the slots, so the readback does not grow with the view count.
-
-- **Slots.** The frame's own view is slot 0. Other views take the next slot the first time they cut
-  in the frame. The layout is sized to a **high-water mark** of slots used, like `max_iterations`: a
-  view beyond it shares the last slot for that frame, and the next frame has room. The mark is capped,
-  so a frame that draws many point lights for the first time — first draws bypass the shadow budget —
-  cannot grow the buffer without bound.
-- **Wants: one stamp tag per (frame, slot).** The stamp was taken *before* the capacity check, so a
-  full shadow slice burned the stamp of every page it could not write and the main view, recording
-  later, could not ask for it that frame; and the recorded priority was the first writer's. With a
-  tag per view, each view dedups its own wants and records them in its own slice; a page two views want
-  appears twice, and `VGeoResidency` already collapses the second (the page is pending or resident by
-  then).
-- **Priority is error over the view's own τ**, so a want at twice its view's threshold ranks the same
-  whether that view counts screen pixels or texels. Eviction stays LRU over touches; refusals per slot
-  are what S4 measures.
-- **Escalation is per view.** `max_iterations` moves from the runtime onto `VGeoViewCut`, starting
-  from the runtime's and raised from that view's own slot. One far cascade or one cube face of a point light that
-  needed more wavefronts must not double every site's ladder for the life of the scene. The readback
-  closes over the slot → view table with the layout, since it lands frames later and the set of views
-  changes.
-- **Stats** are per slot; `VGeoFeedbackLoop.stats` is slot 0's, which is what the panels show, and each
-  view's last reading is on its `VGeoViewCut`.
-
-### 2.5 What does not change
-
-The seam's call sites, the record type, the HZB meshlet filter, the draw, the shadow atlas, the
-cascade fit and the caster range.
-
-**Cached local maps** *(rev 3)*. A spot or point map drawn once is kept until `shadowmap_update_score`
-re-selects it. Its first draw is forced at creation, when little but the roots is resident, and between
-redraws it touches nothing, so the LRU evicts exactly the pages only it needs. Left alone it would keep
-a root-level cut indefinitely. So a map whose own views' last reading was **clamped**, and under which
-pages have installed since, is re-selected like an invalid one. That keys on the map's own incomplete
-cut rather than on every LOD change, which keeps it clear of an invalidation storm when pages stream in.
-
-### 2.6 Room for proxies — not built
-
-A proxy is a fixed, cheap stand-in for a whole geometry — Nanite's fallback mesh — drawn **instead of**
-a cut for a view that does not justify one. If it comes, it comes as a per-view choice, and this work
-keeps the two places it would need open:
-
-- **The choice is made per (instance, view).** Today that is the seam, which already receives the view:
-  it would either cut or append the instances' proxy meshlets.
-- **A proxy's meshlets would hang off the VG geometry row, never off `VirtualGeometry.meshlets`.**
-  `meshlets.count` is zero for a virtual geometry, and that is what keeps static expansion from
-  drawing a VG instance in every view; filling it with a proxy would draw the proxy *and* the cut
-  everywhere.
-
-That room is for **raster** views *(rev 3)*: ray-traced shadows read `geometries.blas`, built from
-static meshlets, so a proxy for RT needs the BLAS builder to take an input from the VG row as well.
-
-## 3. Cost *(rev 3)*
-
-**Sites** *(before S5)*. A view cuts once per active opaque bucket in phase one plus once in phase two (standard
-path: cascades and spots, ~3 sites each), and once per active bucket in the fast path (a point light's cube faces:
-two active buckets make 12 sites for a cube light and 8 for a tetrahedral one). S5 made it two per
-standard view and one per face (§7.3). An empty site is ~80 µs at
-`max_iterations` 16 and ~225 µs at the ceiling of 64.
-
-**Work.** The three cascades are 1740² + 2 × 1440² ≈ 7.3 Mpx against the 0.92 Mpx main view that §0.3
-measured, and a cut is a function of pixels, so "a cascade costs what the camera's cut does" is a floor
-rather than an estimate. S4 measures it, with the raster cost of the extra clusters beside it.
-
-1. **One cut per view** — CUT_PLAN §7 6b, decided and not done, and **extended to the fast path**:
-   filter instances once, cut once, sort the meshlets by bucket, then loop the buckets for raster
-   alone. That is two sites per standard view and one per cube face.
-2. **One ladder for the cascades — withdrawn.** It would have run one descent over all three
-   cascades. They are not one frustum and not nested ones: each is a box fitted to its own slice of
-   the view frustum, misaligned with the others and overlapping only at the blend margins, so a shared
-   descent shares no traversal work. What it would share is dispatch overhead — 0.2–0.3 ms after S5
-   (§7.4) — for a change inside the traverse.
-
-## 4. Order, and what each step leaves proved *(rev 3)*
-
-**Correctness first, on by default, then cost.** VG shadows are not optional, so they land for every
-scene with virtual geometry with no switch to turn them off. Each step is red-then-green against a spec
-or a scripted headless measurement.
-
-- **S1 — orthographic projection (§2.2).** Agreement spec: orthographic views against the oracle; the
-  σmax collect check; the metamorphic scale check; the orthographic frustum. `VGeoViewCut` derives k and
-  w from the projection matrix, with its own spec. The seam takes it from the view's camera.
-- **S2 — the engine owns the frame; feedback is per view (§2.1, §2.3, §2.4).** This is the step that
-  turns shadow cuts on. Emulator tier: two views in one run write their own stats and want slices, a
-  full slice does not stop another view asking for the same page, and priority is over τ. Recording
-  tier: the seam on a second graph within an open frame records its cut against the same imported
-  buffer, and only the first graph clears it. Headless: all three playgrounds still stream.
-- **S3 — the shadows are right.** Proved against the tree before S2, where every one of these is red.
-  TAA off and single frames, the shadow term measured against a reference with shadow views at a
-  quarter of the τ: false-shadow and false-lit pixels on light-facing receivers.
-  - a caster outside the camera frustum (behind the camera) casts into view;
-  - spot, cube and tetrahedral point lights over VG, including a cached map converging (§2.5);
-  - a yaw sweep over a still scene: frame-to-frame XOR of the shadow mask, VG against an ordinary
-    mesh of the same size, since unstabilized cascades refit — and change `k` — every frame;
-  - per slot: `QUEUE_DROPPED`, `INSTANCES_DROPPED`, `MESHLETS_DROPPED` all zero, `QUEUE_REMAINING`
-    zero after escalation.
-- **S4 — measure.** Per view (the cut's scope and the `VGeoViewCut` label carry the view's name): cut
-  time, drawn clusters, wants, refusals; spot, cube and tetra lights; a frame spawning N point lights;
-  shadow views at `tau_scale` 1, 2, 4 — a default other than 1 only if S3's checks pass at it.
-- **S5 — one cut per view (6b), standard and fast paths.**
-- **S6 — one ladder for the cascades: withdrawn** (§3 item 2).
-
-## 5. Not in this
-
-- **Proxies** (§2.6), beyond keeping the room.
-- **Non-opaque VG casters.** An alpha-tested VG instance draws nothing in the main view either
-  (design §9); the shadow path's alpha-tested bucket inherits that.
-- **Ray-traced and SDF shadows** (`shadow/ray`, `shadow/sdf`). VG × RT is design §9's future work.
-- **Screen-space contact shadows** already see VG — they trace the depth buffer.
-- **Releasing VG on scene teardown** was a defect of its own. It was fixed separately:
-  `GPUSceneContext.destroy()` releases what `enable_virtual_geometry` built (7a9e14fea, and
-  REVIEW_LEDGER U1).
-
-## 6. Adversarial review of revision 2 — the ledger
-
-Three reviewers, one each on the frame and feedback, the kernel, and the shadow path and cost; each
-finding checked against the code before it was taken.
-
-| # | finding | disposition |
-|---|---|---|
-| 1 | want stamp taken before the capacity check: a full shadow slice silences the main view's want for that page; first writer's priority wins (all three) | §2.4: stamp tag per (frame, slot); priority over the view's τ |
-| 2 | absolute per-view τ splits the one lever and inverts at a raised slider | §2.3: `tau_scale` |
-| 3 | one `max_iterations` for the frame lets one hungry view double every site forever | §2.4: per view |
-| 4 | S2 already turns shadows on, so S3 cannot be red after it; the software device cannot prove a readback | §4: S3 proved against the pre-S2 tree; slot writes proved at the emulator tier |
-| 5 | Caldera is a third host; a second `begin_frame` mid-render would split `frame_tag` | §2.1 |
-| 6 | the oracle has no instance transform, so agreement cannot catch a wrong scale term; the seam still reads `fov` | §2.2, S1: σmax and metamorphic checks; projection from the matrix |
-| 7 | `vg_project`'s eye-inside test must be on the denominator — a cascade's centre sits inside root spheres | §2.2 |
-| 8 | "no change inside the traverse" for a batched cut is false; cascades and local maps are in separate graphs; the multi-view collect moves the proxy choice | §3.2 scoped to cascades and called a traverse change; §2.6 restated per (instance, view) |
-| 9 | a point light's cube faces cut per bucket in the fast path, first draws bypass the budget, cascades are 7.3 Mpx | §3 |
-| 10 | 6b as written covers only the standard path | §3.1: and the fast path |
-| 11 | a cached local map keeps its first, root-level cut | §2.5: re-select a map whose cut was clamped once pages have installed |
-| 12 | the S3 probe cannot see speckle through TAA, never looks for leaks, sweeps the wrong τ, and misses off-frustum casters, local lights and stability | §4 S3 |
-| 13 | clearing by `writeBuffer` uploads the whole buffer, and the usage lacks `COPY_DST` | §2.1: in-stream clear of the counter and touch words |
-| 14 | `end_frame` needs a `finally`; the open has to sit outside the shadows-enabled `if` | §2.1 |
-| 15 | per-view attribution impossible: identical scope names, `VGeoViewCut` labelled before its view is | §4 S4 |
-| 16 | proxies as described are raster-only | §2.6 |
-| 17 | unstabilized cascades change `k` every frame, so shadow LOD may pop under camera motion | **measured, no action (§7.6)**: `k` moves and the cut follows, but the picture does not flicker beyond what a frozen-`k` cut — an ordinary mesh, to the map — does. `k` is not quantized |
-| 18 | a point light's cube faces render at a fixed 512² each and are then remapped into the light's octahedral atlas slot, 128² by default and sized by the resolution policy — so each face cuts for texels the slot does not keep | **withdrawn, not a VG issue.** It is the remap's resolution match between cube faces and the octahedral encoding, and a VG knob would only paper over it |
-| 19 | the orthographic far plane is finite and skipped: casters behind a slice's receivers refine and want pages | **withdrawn, measured (§7.5)**: a cascade's far plane is the far corner of its view slice in light space, and testing it culls nothing worth having |
-| 20 | the exact orthographic factor is the largest singular value of the projected 2×3 | declined: σmax is a conservative bound and exact for uniform scale |
-
-## 7. What the steps found
-
-All of it is Zorah (§0.1's page, scene and viewpoints) on the 4090 in headless Chrome, at 1556×592.
-Costs come from `GPUProfileSession` at `TIMING`, as medians over 48 frames. **This GPU runs in two
-modes about 2× apart.** It switches between launches and now and then mid-run, so absolute numbers do
-not compare across runs, or even across the rows of one table. Every cost claimed here is a
-difference within a pair taken in one Chrome, and only pairs taken in one mode are quoted.
-
-### 7.1 Shadows are cast (S3)
-
-The table is §0.1's: the fraction of pixels that go more than 16 luma darker when shadows are switched
-on, only VG in view, against the tree before S2.
-
-| view | before | after |
-|---|---:|---:|
-| authored | 0 | 3.99% |
-| oblique | 0 | 0.31% |
-| plan | 0 | 1.95% |
-
-- **A caster behind the camera casts into view.** From inside the throne room, 39% of the pixels
-  darken.
-- **Local lights, with the sun off.** Pixels darkened: 4.5% under a cube point light, 4.1% under a
-  tetrahedral one, 0.22% under a spot. In every slot `QUEUE_DROPPED`, `INSTANCES_DROPPED`,
-  `MESHLETS_DROPPED` and `QUEUE_REMAINING` are zero.
-- **Cached maps (§2.5).** Twelve point lights spawned in one frame reach zero clamped maps within
-  14 s, with nothing else fetching.
-- **At rest, nothing moves.** Across consecutive settled frames, no pixel changes in the authored view.
-  In the plan view, fewer than one pixel in 100,000 changes by more than 4 luma, and that holds with
-  shadows on and off alike.
-- **Under camera motion, VG shadows flicker no more than ordinary geometry's** (§7.6).
-- **Self-shadowing (§1) needs no new bias.** The main view's `tau_scale` was swept 1 → 8, which makes
-  the G-buffer up to 8× coarser than the maps.
-  - Authored: the fraction of darker pixels holds at 6.98–6.99%, with no isolated acne.
-  - Oblique: 0.79% at 1 and 0.89% at 2, then 1.17% at 4 and 2.29% at 8.
-  - Isolated dark pixels do not grow anywhere in the sweep.
-
-  So the existing bias absorbs about a 2× mismatch, and the default adds none beyond what the two
-  projections make. Measured the other way round, against shadow views at τ × ¼, shadow views at τ × 1
-  leave 0.003–0.012% false shadow and 0.006–0.154% false light.
-
-### 7.2 What shadows cost, and τ (S4)
-
-**The first S4 run found a defect in S2**, fixed in 3f9cce3cc. The first frames were laid out for one
-slot, so the cascades shared slot 0 with the frame's view. The sum of their remainders escalated the
-main view to 32 wavefronts, for good. Now the floor is two slots, a view past the layout never shares
-slot 0, and a shared slot escalates nobody.
-
-**Where the time goes**, read within single frames so the modes cannot move it. The frame is the
-authored view with shadows on, after S5:
-
-- The cut is half of it: 2.67 of 5.27 ms.
-- Of that cut, the three cascades take 1.88 ms and the camera 0.74 ms.
-- Cascade 0 alone is 0.82 ms and draws 113k clusters, against the camera's 32k.
-
-Per-site ladders are the smaller part (§7.4).
-
-**`tau_scale` on the cascades** (`shadow_tau`, TAA and auto exposure off; the reference is every
-cascade at τ × ¼):
-
-| view | false light ×1 | ×2 | ×4 |
-|---|---:|---:|---:|
-| authored | 0.006% | 0.028% | 0.040% |
-| oblique | 0.154% | 0.349% | 0.454% |
-| plan | 0.153% | 0.400% | 0.530% |
-
-×2 draws 36% of ×1's clusters in cascade 0 and cuts the depth raster by about 60%. Across the three
-views it also multiplies the false light by 2.3–4.7×, and false light is sunlit ground under a caster.
-**Shadow views default to 2** — Alex's call on these numbers. The clusters and raster are the saving,
-and the false light is the price.
-
-### 7.3 One cut per view (S5)
-
-- **Standard path, phase one.** The HZB filter appends every opaque bucket to one positive set, as it
-  already did the maybe set. That set is expanded, cut and meshlet-filtered once, then sorted by bucket
-  and drawn a bucket at a time (`graph_meshlets_rasterize_by_bucket`).
-- **Fast path.** The opaque buckets are not neighbours in its bucket-sorted meshes, so it gathers them
-  into one collection first (`shader_gather_bucket`). Each bucket lands after the gathered buckets
-  below it, read off their headers, with no atomics.
-- **Both paths, and phase two,** sort only when there is more than one bucket to separate.
-
-Paired, before (3f9cce3cc) and after in one Chrome, ABBA twice. The ranges are over the pairs taken in
-the fast mode, and the slow mode's pairs save proportionally the same.
-
-| | cut sites | frame saved | cut saved |
-|---|---:|---:|---:|
-| authored, shadows on | 12 → 8 | 1.0–1.1 ms of 6.2 | 0.9–1.2 ms |
-| oblique, shadows on | 12 → 8 | 0.6–1.6 ms of 10.2 | 1.2–1.7 ms |
-| authored, shadows off | 3 → 2 | 0.3–1.0 ms | 0.2–0.7 ms |
-| oblique, shadows off | 3 → 2 | 0.02–0.13 ms | 0.09–0.11 ms |
-
-**Nothing else changed:**
-
-- The two trees' pictures differ by nothing at any threshold, in all four conditions.
-- Every view draws the same number of clusters.
-- Every counter of every face of a cube and a tetrahedral point light is the same, from drawn to
-  culled-by-LOD.
-
-The second bucket's site disappears and the first barely grows, because nearly all of what the second
-site cost was its ladder. Cascade 0 goes from [807, 328, 71] µs to [820, 69] µs.
-
-### 7.4 S6 is withdrawn
-
-After S5 each view is left with **one ladder per phase**, and an empty ladder costs 40–75 µs. That
-ladder is all a batched cascade cut could have shared: the cascades are disjoint boxes over separate
-slices of the view frustum (§3 item 2), so the descent's own work — where the cascades' cost is —
-would be the same.
-
-What would reduce that work is fewer clusters per cascade. Two levers exist:
-
-- `tau_scale` — now 2 on shadow views (§7.2).
-- Starting each view's descent from its previous frontier. `VGeoViewCut` already keeps a frontier
-  (CUT_PLAN 6c), and the seam does not read it.
-
-Neither is proposed here.
-
-### 7.5 A cascade's far plane culls nothing worth having
-
-Ledger 19 said the untested orthographic far plane lets casters behind a cascade's receivers refine.
-That was argued, not measured. A cascade's far plane is `extents.z1`, the far corner of its view
-slice in light space, so anything behind it sits below everything the slice covers.
-
-Measured with shadow views at `tau_scale` 2. The collect's fifth plane was swapped for orthographic
-views only, one Chrome launch per arm: the near plane as shipped, no plane, the far plane, then the
-near plane again.
-
-- **The near plane culls nothing either.** The caster range pushes it behind every caster by
-  construction, so "no plane" matches "near" on every counter.
-- **So the far arm is the far plane's whole effect.** Across the three viewpoints and three cascades,
-  every counter — drawn, items, pages, clusters tested, frustum culls — is identical in all four arms,
-  but one: oblique cascade 0, which draws 65 clusters, draws 14.
-- **The pictures are identical to the pixel** in every arm.
-
-### 7.6 Cascade refits do not make VG shadows flicker (ledger 17)
-
-Cascades are not stabilized, so every camera move refits them and changes each cascade's `k`. The
-question was whether VG's shadow cuts re-selecting on every refit make the shadows flicker more than
-an ordinary caster's.
-
-**Method.** A moving view camera would put its own motion into every frame-to-frame difference, so
-the view stands still and only the camera the cascades are fitted from moves. It yaws
-A·sin(2πk/48), one step per rendered frame, so every change in the picture comes from the refit.
-
-- **Two arms over the identical sequence.** In one, VG's shadow cuts are live. In the other, every
-  shadow view's `k` is frozen at the unwobbled fit: `set_projection` becomes a no-op. A cut with
-  `k` frozen is an ordinary mesh as far as the map is concerned, so live minus frozen is VG's own
-  flicker. Freezing `k` is also exactly the remedy this ledger row named.
-- **Measurement conditions.** TAA and auto exposure are off, and shadow views are at `tau_scale` 2.
-  Each frame is captured inside the render wrapper, so the two arms' phases line up. Metrics cover the
-  central 80% of the screen. A second live arm reproduced the first to the pixel.
-
-Per frame, the fraction of pixels that change by more than 8 luma:
-
-| view | ±3°: live | ±3°: frozen | ±10°: live | ±10°: frozen |
-|---|---:|---:|---:|---:|
-| authored | 0 | 0 | 0.0002% | 0 |
-| oblique | 0.033% | 0.033% | — | — |
-| plan | 0.009% | 0.006% | 0.018% | 0.013% |
-
-Over the ±3° sweep, cascade 0's `k` runs 67–78 and it draws 35k–47k clusters, so the cut does follow
-the refit — and the picture barely notices. At ±10°, about 1.3° a frame and roughly a fast turn, VG's
-own share is 0.005% of the screen per frame.
-
-**The metric can see VG flicker when there is some.** As a positive control, with no wobble, every
-shadow view's `tau_scale` alternated between 2 and 16 each frame: cascade 0 drew 3.7k and 42k clusters
-in turn. That flickers 0.17% of the screen per frame in the authored view and 0.33% in the plan view.
-
-## References
-
-Read 2026-09-28.
-
-- Epic, *Virtual Shadow Maps in Unreal Engine* — per-view Nanite rendering, one pass per light
-  class, 17 directional clipmap levels, page caching and invalidation.
-  https://dev.epicgames.com/documentation/en-us/unreal-engine/virtual-shadow-maps-in-unreal-engine
-- Epic, *Hardware Ray Tracing* — ray-traced shadows trace the Nanite fallback mesh.
-  https://dev.epicgames.com/documentation/en-us/unreal-engine/hardware-ray-tracing-in-unreal-engine
-- Bevy, `crates/bevy_pbr/src/meshlet/cull_shared.wesl` (`lod_error_is_imperceptible`) and
-  `visibility_buffer_raster_node.rs` (one full cull and raster per shadow view).
-  https://github.com/bevyengine/bevy/tree/main/crates/bevy_pbr/src/meshlet
-- Bevy PR #19318, the orthographic LOD metric fix. https://github.com/bevyengine/bevy/pull/19318
-- jms55, *Virtual Geometry in Bevy 0.15* — "render all views at once" listed as shadow performance
-  work. https://jms55.github.io/posts/2024-11-14-virtual-geometry-bevy-0-15/
-- NVIDIA `vk_lod_clusters` — one traversal from the camera, shadow rays traced against it; and
-  `vk_tessellated_clusters`' README on off-screen shadows changing when instances become visible.
-  https://github.com/nvpro-samples/vk_lod_clusters · https://github.com/nvpro-samples/vk_tessellated_clusters
-- **Not found in any primary source:** whether and how Nanite's shadow views issue streaming
-  requests. §2.4 does not rest on it.

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.d.ts

@@ -1,47 +0,0 @@
-/**
- * Words of the payload's header for `job_count` jobs: their counters, then the cut's own counters from its feedback
- * slot (`VGEO_CUT_STAT`), which say whether the cut left a subtree undescended.
- *
- * @param {number} job_count
- * @returns {number}
- */
-export function vgeo_sdf_header_words(job_count: number): number;
-/**
- * The extraction's settings, an immediate of each of its passes.
- * @type {WebGPUStruct}
- */
-export const VGEO_SDF_SETTINGS: WebGPUStruct;
-/**
- * A job the frame cuts, as the host writes it: the vgeo geometry row it cuts and the projection constant that puts its
- * error against a τ of 1, `1 / (½ voxel)` in the geometry's own units. A job the frame writes out (`decode` 1) has its
- * room in the payload: `vertex_count` vertices from `vertex_base` and `triangle_count` triangles from `triangle_base`,
- * what its last complete cut held.
- * @type {WebGPUStruct}
- */
-export const VGEO_SDF_JOB_STRUCT: WebGPUStruct;
-/**
- * A job's counters, atomics the frame's passes add into: the clusters its cut took, the stand-ins among them (a
- * cluster taken for a page not resident or a group held), those dropped past the cluster list, the vertices and
- * triangles of its listed clusters, and of those, what the decode wrote into its room.
- */
-export const VGEO_SDF_COUNTER: Readonly<{
-    TAKEN: 0;
-    STAND_INS: 1;
-    DROPPED: 2;
-    VERTICES: 3;
-    TRIANGLES: 4;
-    VERTICES_WRITTEN: 5;
-    TRIANGLES_WRITTEN: 6;
-}>;
-/**
- * Words of a job's counters.
- * @type {number}
- */
-export const VGEO_SDF_COUNTER_WORDS: number;
-/**
- * Words of a cluster list entry: its job, then its meshlet row.
- * @type {number}
- */
-export const VGEO_SDF_CLUSTER_WORDS: number;
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-//# sourceMappingURL=VGEO_SDF.d.ts.map

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"VGEO_SDF.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.js"],"names":[],"mappings":"AAsEA;;;;;;GAMG;AACH,iDAHW,MAAM,GACJ,MAAM,CAIlB;AArED;;;GAGG;AACH,gCAFU,YAAY,CAWA;AAEtB;;;;;;GAMG;AACH,kCAFU,YAAY,CAWL;AAEjB;;;;GAIG;AACH;;;;;;;;GAQG;AAEH;;;GAGG;AACH,qCAFU,MAAM,CAEwB;AAExC;;;GAGG;AACH,qCAFU,MAAM,CAEwB;6BAnEX,sCAAsC"}

package/src/shade/renderer/geometry/virtual/sdf/VGEO_SDF.js

@@ -1,80 +0,0 @@
-import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-import { VGEO_CUT_STAT_COUNT } from "../runtime/layout/VGEO_CUT_STAT_COUNT.js";
-
-/*
- The layouts of a vgeo geometry's proxy extraction (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, as S8 built it): each geometry
- whose cache is asked for is cut whole at half its cache's level-0 voxel, its cut's clusters listed, and, once a cut
- stands nothing in, its vertices and triangles written out and read back for the proxy the mesh bake bakes.
-*/
-
-/**
- * The extraction's settings, an immediate of each of its passes.
- * @type {WebGPUStruct}
- */
-export const VGEO_SDF_SETTINGS = WebGPUStruct.from({
-    /** jobs the frame cuts */
-    job_count: u32,
-    /** entries the cluster list holds */
-    cluster_capacity: u32,
-    /** the word of the payload its vertices start at, 3 floats a vertex */
-    vertex_offset: u32,
-    /** the word of the payload its triangles start at, 3 indices a triangle */
-    index_offset: u32,
-}, "VGeoSDFSettings");
-
-/**
- * A job the frame cuts, as the host writes it: the vgeo geometry row it cuts and the projection constant that puts its
- * error against a τ of 1, `1 / (½ voxel)` in the geometry's own units. A job the frame writes out (`decode` 1) has its
- * room in the payload: `vertex_count` vertices from `vertex_base` and `triangle_count` triangles from `triangle_base`,
- * what its last complete cut held.
- * @type {WebGPUStruct}
- */
-export const VGEO_SDF_JOB_STRUCT = WebGPUStruct.from({
-    vg_row: u32,
-    projection_k: f32,
-    decode: u32,
-    vertex_base: u32,
-    triangle_base: u32,
-    vertex_count: u32,
-    triangle_count: u32,
-    pad: u32,
-}, "VGeoSDFJob");
-
-/**
- * A job's counters, atomics the frame's passes add into: the clusters its cut took, the stand-ins among them (a
- * cluster taken for a page not resident or a group held), those dropped past the cluster list, the vertices and
- * triangles of its listed clusters, and of those, what the decode wrote into its room.
- */
-export const VGEO_SDF_COUNTER = Object.freeze({
-    TAKEN: 0,
-    STAND_INS: 1,
-    DROPPED: 2,
-    VERTICES: 3,
-    TRIANGLES: 4,
-    VERTICES_WRITTEN: 5,
-    TRIANGLES_WRITTEN: 6,
-});
-
-/**
- * Words of a job's counters.
- * @type {number}
- */
-export const VGEO_SDF_COUNTER_WORDS = 8;
-
-/**
- * Words of a cluster list entry: its job, then its meshlet row.
- * @type {number}
- */
-export const VGEO_SDF_CLUSTER_WORDS = 2;
-
-/**
- * Words of the payload's header for `job_count` jobs: their counters, then the cut's own counters from its feedback
- * slot (`VGEO_CUT_STAT`), which say whether the cut left a subtree undescended.
- *
- * @param {number} job_count
- * @returns {number}
- */
-export function vgeo_sdf_header_words(job_count) {
-    return job_count * VGEO_SDF_COUNTER_WORDS + VGEO_CUT_STAT_COUNT;
-}