@woosh/meep-engine 3.27.0 → 3.28.0

package/src/shade/RENDERER_CONTRACT.md

@@ -277,16 +277,25 @@ change every frame, you are on the wrong path — see §8.
 
 `ShadeMaterial` is the base: `transparency_mode`, `draw_mode` and `draw_side`.
 
-**`draw_side` is part of the rasterization bucket key, and it changes what is drawn.** `Front` (the
-default) culls back faces, `Back` culls front faces, and `Double` culls neither — the three map
-straight onto the pipeline's cull mode, so a bucket exists per side that any material in the scene
-asks for. A face seen from behind is shaded with its normal flipped, so `Double` is a working
-double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and stays that
-way; the loader's fix-up pass only rewrites `Back` to `Front`, by flipping the geometry.
-
-Shadow passes invert the mapping — `Front` culls *front* faces there — so a one-sided surface casts
-from its back face and does not shadow-acne against its own lit side. `Double` has no opposite and
-stays unculled in both.
+**`draw_side` changes what is drawn.** `Front` (the default) draws the front face, `Back` the back
+face, `Double` both. A face seen from behind is shaded with its normal flipped, so `Double` is a
+working double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and
+stays that way; glTF cannot ask for `Back`, which comes from authoring.
+
+**Only `Double` costs a pipeline of its own.** It culls nothing, and no amount of winding expresses
+that. `Front` and `Back` differ by winding alone, and the vertex shader reverses winding per
+instance, so the two share a rasterization bucket and draw in one pass — which matters because a
+bucket is not a pipeline here but a whole chain: extract, expand to meshlets, select a
+virtual-geometry cut, one render pass.
+
+**That is also why a mirrored instance works.** Place a mesh under a negative scale, or under a
+parent that reflects, and it draws right way out, with the handedness of its tangent frame flipped
+to match — the reflection and the material's side are the same one bit, combined before a corner is
+chosen. glTF makes this the rule rather than an extra: the determinant of a node's world transform
+decides its winding, and a conformant renderer has to read it.
+
+Shadow passes cull the other face — so a one-sided surface casts from its back face and does not
+shadow-acne against its own lit side. `Double` has no opposite and stays unculled in both.
 
 `StandardShadeMaterial` is the PBR one everything uses:
 

package/src/shade/device/timing/GPU_PROFILER_PROPOSAL_2026_08_28.md

@@ -693,7 +693,7 @@ what they are looking at is the observer.
 ## 7. The inspector
 
 `packages/gpu-inspector-tool/`. A static site: drop a `.sgpt` on it, or pass `?file=` for a
-bookmarkable view — the affordance the `vgeo_viewer` playground already establishes in this codebase.
+bookmarkable view — the affordance the `.vgeo` playgrounds already establish in this codebase.
 
 ### 7.1 Technology
 

package/src/shade/playground/vgeo_runtime/README.md

@@ -6,19 +6,26 @@ This page draws nothing itself: every triangle on screen is there because the co
 the HZB meshlet filter, the material bucket, the indirect draw and the G-buffer took it from there
 without knowing that virtual geometry exists.
 
-That is the whole difference from [`../vgeo_viewer/`](../vgeo_viewer/README.md), and the two are
-worth keeping apart. The viewer draws a **CPU** cut through Shade's direct geometry path — it
-proves the DAG, the format and the residency clamp, and by construction it proves nothing about the
-engine. This page proves the engine seam and nothing about the DAG, because the DAG has its own
-tests and its own oracle.
-
-And it proves one thing neither the specs nor the viewer can, which is what the surface **looks
-like**. The viewer draws with `cullMode: 'none'` and colours its cut per cluster; this page draws
-through a `Front`-sided standard material with a light on it. That is the difference that caught
-the shared sample torus being wound inside-out — the near surface culled away, the far inner wall
-showing through the hole where it should have been, and normals pointing into the tube so what
-survived was lit from inside. Eighteen thousand specs and a second playground had drawn that
-container without a single one of them being able to notice.
+This page proves the engine seam and nothing about the DAG, because the DAG has its own tests and
+its own oracle: `renderer/geometry/virtual/runtime/cut/__fixtures__/vgeo_select_cut.js`, a **CPU**
+traversal of the same rule that every cut spec is held to. A `vgeo_viewer` page used to draw that
+traversal on screen through Shade's direct geometry path, carrying its own renderer, its own camera
+and its own streaming loop; it was retired rather than kept as a second runtime, and everything it
+showed is shown here or on the scene page below.
+
+It is also not [`../vgeo_scene/`](../vgeo_scene/README.md), which opens a whole converted set —
+thousands of containers, tens of thousands of instances, one cut — and is where the claim about a
+*scene* is measured. This page is one container framed on its own bounding sphere, which is what
+makes it a viewer and what makes its readings about the seam rather than about breadth.
+
+And it proves one thing no spec can, which is what the surface **looks like**. The retired viewer
+drew with `cullMode: 'none'` and coloured its cut per cluster; this page draws through a
+`Front`-sided standard material with a light on it. That is the difference that caught the sample
+torus being wound inside-out — the near surface culled away, the far inner wall showing through the
+hole where it should have been, and normals pointing into the tube so what survived was lit from
+inside. Eighteen thousand specs and a second playground had drawn that container without a single
+one of them being able to notice, which is the argument for this page and part of the argument
+against the other one.
 
 ## How it is lit, and why that is not decoration
 
@@ -138,6 +145,13 @@ The panel's `RAM evicted`, `fetching` and `worker fetches` rows are new with it,
 the reading to keep watching: it climbs only while the tier is full of pages the cut still draws
 from, which is a budget saying no and not a tier scanning.
 
+**`quarantined`** came here from the retired viewer, and it is the row that tells two coarse
+surfaces apart. A page that fails its retries is quarantined with its reason and is never asked for
+again; the clamped cut then keeps that region correct with a coarser ancestor, indefinitely. On
+screen that is indistinguishable from a container that is merely still arriving, and `clamped`
+alone cannot separate them — a count that will not fall while this is non-zero is a page that is
+never coming.
+
 Two things the tour still shows. The four long tasks left are `GPUMeshletManager` compactions —
 a refused allocation with free space behind it rebuilds every batch, which is the one O(resident)
 event the rebuild deferred. And under a vite dev server the first seconds after a container opens

package/src/shade/playground/vgeo_runtime/main.js

@@ -28,15 +28,15 @@ import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
 import { Scene } from "../../renderer/scene/Scene.js";
 import { load_default_environment } from "../load_default_environment.js";
 import { install_profile_hotkey } from "../profile_hotkey.js";
-import { vgeo_sample_source } from "../vgeo_viewer/sample_asset.js";
+import { vgeo_sample_source } from "./sample_asset.js";
 
 /**
  * A `.vgeo` container drawn **through the meshlet pipeline**, by a cut selected on the GPU.
  *
- * This is the other half of what `playground/vgeo_viewer/` proves, and the two are worth keeping
- * apart. The viewer draws a CPU cut through Shade's direct geometry path: it proves the DAG, the
- * format and the clamp, and by construction it proves nothing about the engine. This page draws
- * nothing itself. It puts an ordinary mesh row in an ordinary `Scene` with an ordinary material,
+ * What proves the DAG, the format and the clamp is not a page:
+ * `renderer/geometry/virtual/runtime/cut/__fixtures__/vgeo_select_cut.js` is a CPU traversal of the
+ * same rule, and every cut spec is held to it. This page proves the other half — the engine seam —
+ * and it draws nothing itself. It puts an ordinary mesh row in an ordinary `Scene` with an ordinary material,
  * and every triangle on screen arrives because the compute cut appended `MESHLET_DEFINITION_STRUCT`
  * records into the same collection a static mesh's meshlets go into — through the HZB meshlet
  * filter, the material bucket, the indirect draw and the G-buffer, none of which know that virtual
@@ -617,6 +617,7 @@ class VGeoPlayground {
                 bytes: this.residency.ram_resident_bytes,
                 evicted: this.residency.evicted_ram_count,
                 refused: this.residency.refused_fetch_count,
+                quarantined: this.residency.quarantined_page_count,
                 total_pages: reader?.header.total_pages ?? 0,
             },
             fetches_in_flight: this.residency.fetches_in_flight,
@@ -917,6 +918,18 @@ async function start() {
                 `<span class="${state.vram.refused > 0 ? 'bad' : 'good'}">`
                 + `${state.vram.refused.toLocaleString()}</span>`,
             ],
+            /*
+             A page that failed its retries is quarantined with its reason and is never asked for
+             again, and the clamped cut keeps its surface correct with a coarser ancestor
+             indefinitely. That is the difference between a container that is coarse because the
+             camera just moved and one that is coarse because a page will never arrive — which look
+             identical on screen, and which `clamped` alone cannot tell apart.
+            */
+            [
+                'quarantined',
+                `<span class="${state.ram.quarantined > 0 ? 'bad' : 'good'}">`
+                + `${state.ram.quarantined}</span>`,
+            ],
             ['dropped', `<span class="${dropped > 0 ? 'bad' : 'good'}">${dropped}</span>`],
         ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
             .join('');

package/src/shade/playground/vgeo_runtime/sample_asset.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a sample container and hand back a source over it.
+ *
+ * The page size is deliberately far below the 256 KB default: a sample that came out as one page
+ * would be a container with nothing to stream, and the point of opening this one is to watch it
+ * arrive.
+ *
+ * @param {number} [major]
+ * @param {number} [minor]
+ * @param {number} [page_size] target decoded bytes per page
+ * @returns {{source: VGeoByteSource, build_ms: number}}
+ */
+export function vgeo_sample_source(major?: number, minor?: number, page_size?: number): {
+    source: VGeoByteSource;
+    build_ms: number;
+};
+import { VGeoByteSource } from "../../renderer/geometry/virtual/format/read/VGeoByteSource.js";
+//# sourceMappingURL=sample_asset.d.ts.map

package/src/shade/playground/vgeo_runtime/sample_asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample_asset.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_runtime/sample_asset.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;GAWG;AACH,2CALW,MAAM,UACN,MAAM,cACN,MAAM,GACJ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiBtD;+BA3HM,+DAA+D"}

package/src/shade/playground/{vgeo_viewer → vgeo_runtime}/sample_asset.js

@@ -12,7 +12,7 @@ import {
 } from "../../renderer/geometry/virtual/format/read/VGeoByteSource.js";
 
 /**
- * A `.vgeo` built in the page, so the viewer has something to open without a file.
+ * A `.vgeo` built in the page, so there is something to open without a file.
  *
  * The builder is environment-agnostic by design (`VIRTUAL_GEOMETRY_DESIGN.md` §8) — typed arrays and
  * topology, no file or process API anywhere under it — so the same call the node CLI makes runs here.
@@ -31,8 +31,8 @@ import {
  *
  * Curvature is what makes it a useful sample rather than a shape: a flat face simplifies at zero
  * quadric cost, so a box would produce a DAG whose every step records no error and whose every
- * threshold selects the same cut. A torus has an error at every level, which is the thing the viewer
- * is drawing.
+ * threshold selects the same cut. A torus has an error at every level, which is the thing the cut
+ * is selecting against.
  *
  * @param {number} major segments the long way round
  * @param {number} minor segments around the tube
@@ -61,12 +61,13 @@ function torus(major, minor) {
      `CullPolicy.Standard` means by a front face and what `vgeo_compute_vertex_normals` takes the
      sign of its normals from.
 
-     It was the other way round, and both of the pages that build this were blind to it: the viewer
-     draws its cut with `cullMode: 'none'` and colours it per cluster, so neither the culling nor
-     the shading could report it. The moment the same sample went through the engine's material
-     path — `playground/vgeo_runtime/`, where a `Front`-sided material culls back faces — the torus
+     It was the other way round, and the CPU viewer this sample was written for could not see it:
+     that page drew its cut with `cullMode: 'none'` and coloured it per cluster, so neither the
+     culling nor the shading could report it. The moment the same sample went through the engine's
+     material path — this page, where a `Front`-sided material culls back faces — the torus
      rendered as its own far inner wall with the near surface missing, and the normals pointed into
-     the tube so what survived was lit from inside.
+     the tube so what survived was lit from inside. The viewer has since been retired; this is the
+     only page that builds it now, and it is the one that could have caught it.
 
      The winding of a sample is not a detail of the sample. Everything downstream of the builder
      carries it: the cluster's triangles are stored in this order, the DAG's simplification

package/src/shade/playground/vgeo_scene/README.md

@@ -0,0 +1,408 @@
+# `vgeo_scene` — a whole converted scene, one cut
+
+Thousands of `.vgeo` containers, tens of thousands of instances, **one** compute cut, drawn through
+the ordinary meshlet pipeline.
+
+[`../vgeo_runtime/`](../vgeo_runtime/README.md) is the page that proves the engine seam, and it does
+it with one container framed on its own bounding sphere. That makes it a *viewer*, and by
+construction it cannot show the other half of what
+[`VIRTUAL_GEOMETRY_DESIGN.md`](../../renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md) §1
+claims — that rendering cost is a function of the threshold and the resolution rather than of the
+source, **across every asset in view at once**, with instances sharing pages and one residency
+budget arbitrating between all of them. With one reader there is nothing to arbitrate.
+
+So everything here that the runtime page does not do is about breadth:
+
+- **One residency, N containers.** Every asset registers with the same `VGeoResidency`, whose two
+  budgets are scene-wide by construction: the RAM tier's bytes and the VRAM tier's slots are counted
+  across every reader, and a page evicted from one asset is room for another's.
+- **One cut, N instances.** `shader_vgeo_cut_collect` runs over the visible mesh rows and emits one
+  instance record per virtual one; the descent is seeded with one item per instance and every cull
+  and error test downstream runs in that instance's own object space. Seventeen thousand instances
+  are seventeen thousand seeds of **one** wavefront, not seventeen thousand cuts.
+- **Instances share the asset.** A geometry placed by 381 nodes is one reader, one geometry row, one
+  page lookup and one set of resident pages — which is `VirtualGeometry.equals`, and most of why
+  this is affordable at all.
+
+## Running it
+
+Three things: the dev server in front of the page, an asset server in front of the containers, and
+a scene manifest telling the page which is which.
+
+```
+npm run dev --workspace @woosh/meep-engine
+
+node tools/geometry/virtual/vgeo_scene.js <manifest.vgeo.json> --camera "..." --sun "..."
+node tools/geometry/virtual/vgeo_serve.js <container directory>
+```
+
+Then open `/src/shade/playground/vgeo_scene/index.html`. With no parameters it asks the asset server
+what it is holding and opens the one scene that is there; `?scene=<url>` overrides.
+
+**The asset server is not optional and vite cannot replace it.** A `.vgeo` is opened out of its head
+and streamed by `Range`, and `vgeo_fetch_byte_source` refuses anything but a `206` naming the range
+it asked for — a `200` is a server ignoring the request and answering the head of the file where the
+reader asked for the middle of a frame, silently and with plausible numbers. Vite also refuses
+`/@fs/` outside the workspace, and a converted scene is tens of gigabytes that has no business
+inside one. `vgeo_serve.js` is ranges, CORS and nothing else; the header that is easy to miss is
+`Access-Control-Expose-Headers`, because a cross-origin response's `Content-Range` is invisible to
+the page without it.
+
+## What a scene manifest is, and what it is not
+
+`gltf_to_vgeo.js` already writes everything the page needs — a glTF primitive is one container and
+the nodes that placed it are its instances — but its manifest is a *build report*: every level of
+every DAG, every cluster and group count, the weld distance each geometry settled on. At this scale
+that is twenty-odd megabytes of numbers a renderer has no use for. `vgeo_scene.js` is the projection
+to four fields and a list of matrices: **2.2 MiB for Zorah's 2,966 containers and 17,424 instances**,
+and nothing in it is discovered — it is all in the build manifest or in the containers' own headers.
+
+The headers are **read rather than trusted**. A manifest is written by the builder that produced the
+files and a directory is whatever is on disk now, so the probe is what catches a half-finished
+conversion and a container rebuilt at another page size. It costs one head read each and 1.8 s for
+all 2,966.
+
+Two fields are neither: `--camera` and `--sun`.
+
+- **A bounding box is a bad place to put a camera.** Zorah's instances span 107 km, almost all of it
+  terrain, and the town the scene is *about* is forty metres across at the origin — a viewer framed
+  on the box opens a hundred kilometres up looking at a speck. The pose belongs to the source, and
+  Zorah's own `.cfg` carries one, so it is passed in rather than guessed at either end.
+- **A converted container carries geometry and nothing else.** Design §7: VG is geometry only, so a
+  converted set arrives with normals, no material authoring and no lights. The sun is most of what
+  there is to shade it with, and the engine's default direction over a scene authored around a
+  different one puts every façade a viewer stands in front of into ambient.
+
+## What it measures
+
+Zorah, 2,966 containers and 17,424 instances of them, **46.71 GiB** on the server across 947,664
+pages, 1.36 billion source triangles and **10.75 billion instanced** ones. Measured on an
+nvidia/lovelace adapter at a render target of 1578×746, from the scene's authored viewpoint, with a
+**fresh page load per row** — residency is a high-water mark, so a page swept downwards through the
+thresholds reports at every step what the busiest setting it has already been at asked for, and a
+row of this table is only about τ if the page has been at nothing else.
+
+| τ (px) | drawn clusters | pages visited | clusters tested | resident pages | bytes read | frame |
+|---:|---:|---:|---:|---:|---:|---:|
+| 0.25 | 387,875 | 79,574 | 1,232,352 | 12,288 *(full)* | 452 MB | 7.3 ms |
+| 0.5 | 182,887 | 51,035 | 617,540 | 9,365 | 242 MB | 5.0 ms |
+| 1 | 84,481 | 31,842 | 279,088 | 6,387 | 128 MB | 4.7 ms |
+| 2 | 45,302 | 22,356 | 139,290 | 4,939 | 76 MB | 4.8 ms |
+| 4 | 28,874 | 17,483 | 79,651 | 4,121 | 52 MB | 5.2 ms |
+| 8 | 21,334 | 15,235 | 56,561 | 3,704 | 40 MB | 4.8 ms |
+| 16 | 18,137 | 14,289 | 45,717 | 3,489 | 35 MB | 6.0 ms |
+
+Monotone in τ, and a *fraction* of the asset at every setting: at τ=1 the scene is on screen out of
+**0.67% of its pages** and 128 MB of 46.71 GiB, and at τ=16 out of 0.37% and 35 MB. `clamped` is
+zero at every row but the first, which is the streaming having finished rather than a budget having
+given up — the distinction the `refused` counter beside it exists to make.
+
+**τ=0.25 is the budget wall, and it is in the table on purpose.** At the slider's minimum the cut
+wants more than 12,288 page slots, `refused` climbs to 1.1 million, `clamped` stops falling to zero,
+and the cut is then being selected by a **budget** rather than by a threshold — which is the one
+thing this page is not meant to be showing you. It is one slider notch away at all times, and
+`refused` going red is how you know that is what you are looking at. `?pages=` raises the tier.
+
+A tour of five viewpoints at τ=1 — a hundred metres up, three hundred out, a nose against one
+façade, the whole 107 km box, and back to the authored pose — held 4.5 to 5.8 ms a frame with
+`clamped`, `refused` and every drop counter at zero throughout, and residency settling at 7,948 of
+12,288 pages without a single eviction.
+
+## Opening it, and what the first five seconds are
+
+Measured cold, three times: **2,966 containers open in about four seconds**, and the whole scene is
+drawing about a second and a half later.
+
+The opens are one range request each. §10's always-resident set — header, level table, root frame —
+is 2,560 bytes at the median across this set and 6,528 at the very worst, so the page asks for an
+**8 KB head prefix** rather than the reader's default of 64 KB: every container in the set opens in
+exactly one round trip and the cold read is 7.4 MB of heads instead of 190 MB of over-fetch. The
+byte length comes from the manifest rather than from a `HEAD`, which is 2,966 round trips not spent
+learning something the page was already holding.
+
+**About four and a half seconds of that is not this page.** The first frame that draws geometry pays
+the engine's pipeline warm-up, and `vgeo_runtime` — driven the same way, with a thirteen-page torus
+built in-page — sits on exactly the same stall before *its* first frame. It is a fixed cost of a
+cold device under a dev server, it is not a function of the scene, and a bundled build does not pay
+all of it. Containers keep opening underneath it.
+
+Containers are **placed as they land** rather than at the end, which costs nothing: a geometry that
+is not registered yet is one the cut does not collect, and both residency tiers recompute their
+budgets per reading rather than at registration, so a scene that grows under the camera is the case
+they were designed for. A container that refuses leaves every other asset exactly as it was and is
+counted — 2,965 of 2,966 is a scene, and the count is what says there is a hole in it.
+
+## The four capacities a scene reaches first
+
+These are the page's real finding, because every one of them is an engine default that a
+single-asset page never touches, and two of them degrade *silently*.
+
+- **`queue_capacity`, and this is the one that hurt.** At τ=0.5 with 17,424 instances the descent
+  pushed past the engine's 65,536 items in flight and `VGEO_CUT_STAT.QUEUE_DROPPED` came back at
+  **32,676** — a third of the frontier thrown away. It does not surface as an error or as a visible
+  hole; it surfaces as `drawn` wandering over ten thousand clusters between one frame and the next,
+  as different subtrees lose the race. At `1 << 18` the same view drops nothing and `drawn` is
+  stable, at a cost of 4 MiB a site against 1 MiB.
+- **`lookup_words`** is one word per page of every registered container out of one arena, and the
+  default of 65,536 holds a fourteenth of Zorah's 947,664. It is allocated out of an
+  `OffsetAllocator` whose bins round *down* — it can refuse an allocation that fits — so this is
+  sized to the next power of two above 1.5× the total rather than to the total.
+- **`geometry_capacity`** is one row per container against a default of 256.
+- **`claim_word_capacity`** is one bit per (collected instance, page ordinal of its geometry), and
+  the engine derives it from a hint of a thousand instances times the whole tier. At this scale that
+  is both too small and too large, and the real bound is knowable exactly: ordinals come out of the
+  tier, so `Σ instances × ordinals` is maximised by giving every slot to the most-instanced asset,
+  which makes it `max instances of any one geometry × page capacity`. For Zorah that is 381 × the
+  tier — a fifth of what the default derivation asks for — doubled here, because an ordinal capacity
+  is a high-water mark and a scene that has churned can hold more of them than the tier holds pages.
+
+`RasterizationCollectionType.Meshes` is a fifth, and it self-corrects: it grows from what the frame
+reports, so priming it to the instance count only buys the first seconds. But the first seconds are
+when the scene is being placed, and against a default of 1e4 the other 7,424 instances would be
+counted as `instances_dropped` while the collection caught up.
+
+## Two things it approximates, and says so
+
+- **Shear.** A transform row carries a TRS and the GPU composes the world from it, so an instance
+  whose matrix has shear in it cannot be represented exactly and is placed at the closest
+  rigid-plus-scale fit. 391 of Zorah's 17,424 have any and the worst is about eleven degrees off
+  orthogonal; the other 17,033 are exact, including the 2,722 reflected ones — `m4_decompose_array`
+  folds a negative determinant into a scale axis, so a reflection survives. This is a property of
+  the engine's transform model rather than of this page. The reflections surviving is what the next
+  section is about.
+- **One material for the whole scene.** Not a simplification being made here: a `.vgeo` carries
+  geometry only, so the source's 2,714 materials did not survive a conversion that never asked them
+  to. Tinting each container would read better, would be a lie about where the colour came from, and
+  would put 2,714 material buckets in front of the draw path to say it with.
+
+## Reflected instances — the bug this page was built to show, and where it went
+
+2,722 of Zorah's 17,424 instances have a negative-determinant transform: the courtyard is
+bilaterally symmetric and the left half is the mirror of the right. Until 2026-09-15 every one of
+them rendered with its near surface culled and its far surface showing through, because:
+
+1. A reflection reverses the orientation of every triangle it transforms, so a reflected instance
+   presents the **opposite screen-space winding** from the same geometry under a rotation.
+2. Front-face determination is fixed-function and reads that winding and nothing else.
+3. `cullMode` is **pipeline state chosen per material bucket**, and the bucket key was three fields
+   of a *material* — transparency, topology and side — with `construct_primitive_state` turning the
+   third into a cull mode. Nothing from there down to the rasterizer saw a transform.
+
+The sign was never lost — `m4_decompose_array` preserves it and the row the GPU composes reflects
+exactly as the source did — it was simply never consulted.
+
+**It is consulted now, and not through the bucket key.** A node's row carries
+`NODE3D_GLOBAL_FLAG_MIRRORED`, derived from its composed world matrix by whoever publishes it, and
+every vertex shader over a meshlet emits that instance's triangle corners in the opposite order —
+`triangle_list_reverse_winding`. The draw is non-indexed and the vertex shader resolves its own
+index, so which corner lands where is already the shader's choice; reversing it costs a `select`,
+no second pipeline, and no fourth field in the bucket key. It is what Nanite does for the same
+reason (`FInstanceSceneData::DeterminantSign`, read in `HWRasterizeVS`), and what the glTF spec
+requires of a conformant renderer. The tangent frame's handedness flips with it.
+
+The parameters remain, and now read as diagnostics rather than as fixes:
+
+- `?mirrored=tint` colours reflected instances red — in this view the **whole left arcade** comes up
+  red while the right stays grey. Nothing about which of them is *drawn* changes.
+- `?mirrored=flip` draws them `Back`-sided. This used to be the page's own fix; `Back` is now drawn
+  by reversing winding too, so on a reflected instance the two cancel and it reproduces the old bug
+  on demand.
+- `?mirrored=double` draws both sides of them — the fix people reach for first, and still the wrong
+  one: it doubles the work and gets the shading wrong.
+- `?side=front|back|double` sets the whole scene's side, for the cruder question of whether a
+  surface is missing or merely culled.
+
+The bug was hard to recognise because `fragment_gbuffer` flips normal, tangent and face normal when
+`dot(world_face_normal, view_direction) < 0` — a test about the *view*, not about the winding — so
+the far wall you were left looking at was correctly lit, and it read as bad geometry rather than as
+a culling problem. Nothing about any of it was virtual-geometry-specific: it reached every mesh
+placed under a mirroring transform, by any loader or prefab.
+
+## Two different things are called flicker here, and they have different causes
+
+**A dropout is not a shimmer and they do not measure alike.** A shimmer moves a tenth of a per cent
+of the pixels and comes from the TAA jitter under sub-pixel geometry; a frame missing a large part
+of what the frames either side of it drew moves tens of per cent and comes from the descent running
+out of wavefronts. One section each, below. Measuring the first when asked about the second cost a
+whole pass of this investigation, and the tell that separates them is the amplified frame
+difference: an **edge map** is the shimmer, **solid blobs** are the dropout.
+
+## The shimmer is the TAA jitter, and the geometry is finer than a pixel
+
+There is a visible shimmer over the ornament, and it is **exactly 16 frames long**.
+
+Measured over 600 consecutive frame pairs at 780×368 samples (~2×2 screen pixels each), camera
+static, everything settled:
+
+| | pixels changing >8/255 per frame | >24/255 | worst single step | period |
+|---|---:|---:|---:|---:|
+| as shipped | 350 (0.12%) | 17 | 57/255 | 16 (r=0.97) |
+| τ=16 | 182 (0.06%) | 13 | 69/255 | 16 (r=0.95) |
+| `?mirrored=flip` | 314 (0.11%) | 21 | 56/255 | 16 (r=0.96) |
+| TAA off | **79,391 (27.66%)** | 33,841 | 161/255 | 16 (r=0.97) |
+| jitter pinned | 89 (0.03%) | 3 | 88/255 | 16 (r=0.96) |
+
+Sixteen is `TAA.#jitter_sequence_size`, and the attribution follows from the last two rows. **Pin the
+jitter and fifteen frames out of every sixteen go pixel-static** — 18 to 123 changed samples out of
+287,040, which is the noise floor — against 240 to 470 *every* frame as shipped. The flicker is the
+Halton jitter cycling the projection under geometry whose detail is finer than a pixel, with TAA
+resolving most but not all of it.
+
+An amplified `|frame(t) − frame(t−1)|` over eighteen consecutive pairs says the same thing in one
+picture: it is an **edge map**. Every silhouette and every piece of filigree sparkles; the flat
+courtyard floor is dead black. LOD popping would light up in cluster-shaped patches and does not.
+
+Three things fall out of it that are worth writing down:
+
+- **`feature_taa_enabled = false` does not turn the jitter off.** `Renderer` writes
+  `view_ctx.camera.setViewportOffset` from the jitter sequence unconditionally, and only the
+  *resolve* is behind the flag. So TAA off is not "no temporal AA", it is "jitter with nothing to
+  resolve it": 27.66% of pixels move every frame, which is forty times worse than shipping it on and
+  worse than never jittering at all. Anyone A/B-ing TAA on this content is not measuring what they
+  think.
+- **The jitter does move the cut, slightly, and it is not where the flicker comes from.** `drawn`
+  and `pages visited` are weakly 16-periodic (r=0.34 and r=0.40) because the cut's frustum planes
+  come out of the *jittered* view-projection while `projection_k` — the error metric — does not. So
+  what moves is which clusters are inside the frustum, by up to 117 of 84,455 (0.14%), confined to
+  the screen border. `vgeo_runtime`'s README says the jitter does not move the cut and its τ table is
+  identical either way; at this scale that is very nearly true rather than exactly true, and the
+  difference is not visible in the diff image.
+- **`GPUViewContext.setJitter` and `setJitterDelta` write the same two fields.** Only the first is
+  called, so nothing is broken today; a caller that used the second would silently overwrite the
+  jitter with its delta.
+
+None of this is the scene's fault and τ=16 halving the count is the proof: less sub-pixel detail,
+less shimmer, same period. It is what a temporal filter does on content authored at a density no
+rasterizer resolves, which is the content virtual geometry exists to put on screen — so it is worth
+knowing that the page's picture has a floor set by TAA rather than by the cut.
+
+## The dropout: the descent's wavefront bound, and how the engine finds it
+
+**`max_iterations` starts at 8, and at a large viewport that is the binding bound rather than the
+safety one.** The descent then stops with items still queued, and a queued item is a **subtree that
+was never expanded** — so what it would have drawn is not on screen that frame. It is the one
+degradation of this cut that costs a *hole* rather than a coarser surface, which is why it reads as
+geometry disappearing rather than as anything softening.
+
+Reported from a live session at **3441×1440** with `dropped: queue 82` in the panel and `wavefronts`
+jittering between 8 and 13. Reproduced at that pose and viewport, 900 frames, camera static, with
+the bound pinned:
+
+| pinned `max_iterations` | `queue_remaining` non-zero | worst | `drawn` swing |
+|---|---:|---:|---:|
+| **8** | **750 of 900 frames** | 13,467 items | **11,857 clusters** |
+| 16 / 32 / 64 | 0 | 0 | 81 |
+
+`drawn` going from a swing of 11,857 clusters to **81** is the flicker, in one number. An amplified
+`|frame(t) − frame(t−1)|` says the same thing in a picture: at 8 it is **solid white blobs** — whole
+pieces of carved ornament blinking on and off — and above it those are gone, leaving only the thin
+edge shimmer of the section above. The two phenomena look nothing alike once they are separated.
+
+**It is a resolution story, and that is why it took so long to find.** The cut is a function of the
+render target, so the same viewpoint at 1578×746 — a quarter of the pixels — drains inside 8
+wavefronts and never drops an item. Every negative result in this file's earlier drafts was measured
+at that size. A quarter-sized window is not a smaller version of this test.
+
+### The bound raises itself
+
+Nothing here pins it. `GPUVirtualGeometryRuntime.note_incomplete_descent` takes the one reading that
+says the descent was truncated and **doubles the bound, permanently**, which is the same shape the
+rasterizer already uses for meshlet counts: a quantity that cannot be known before the work runs,
+learned from what the work reported, kept as a high-water mark.
+
+It has to be learned, because how many wavefronts a cut needs is a function of the frontier's
+*breadth* — the scene, the viewpoint and the render target together — and neither the kernel before
+it runs nor the host at any time can compute it. Doubling rather than solving for it, because
+`QUEUE_REMAINING` is a count of *items* and there is no ratio converting those into wavefronts. It
+is never lowered: a frame that drained is evidence about that frame, not that the scene got smaller,
+and a bound that fell back would re-learn the same lesson at a hole a time every time the camera
+turned away and back. An unused wavefront is an empty indirect dispatch, which is the cheap side of
+that trade.
+
+**What it costs when it is wrong is one frame.** Measured cold at 3419×1286 on the reported
+viewpoint: `queue_remaining` non-zero on **1 frame of 600**, and zero for the rest of the session.
+The ceiling is 64, so the worst case is three such frames, once, ever.
+
+The panel shows `wavefronts` as *used / bound*, with an arrow and a count when the bound has moved,
+because eight wavefronts is a drained descent under a bound of 32 and a truncated one under a bound
+of 8 — and the reading could not tell them apart while it showed only the count.
+
+`?iterations=N` pins both the start and the ceiling, which turns the escalation off and reproduces
+the hole on demand: at 8 the same view gives `queue_remaining` on 395 frames of 500 and a `drawn`
+swing of 15,874.
+
+**`descent_steps` is the wrong knob for this.** It sets how many levels one dispatch advances, so it
+answers depth; what runs out here is *breadth* — a wave keeps one child per lane and spills the
+rest, and the spill generations are what consume the bound. Measured at the small viewport, 24
+against 48 left `drawn` bit-identical.
+
+### Catching it where it happens
+
+`?catch=0.15` arms {@link FlickerCatcher} — a per-frame detector in the page itself. It judges each
+frame against the pair before it **and** the pair after it, taking the smaller of the two
+departures and only when both point the same way. Judging against the median of all four is the
+obvious thing and is wrong: when the picture takes a persistent *step* — the scene streaming in, a
+coarse level replaced by a fine one — two of the four sit on the far side, the median lands between
+the levels, and the frame *before* the step is convicted for being where it always was. Fourteen
+poses each "caught" one that way. On a step the smaller departure is ~0 by construction, which is
+what makes the corrected test score the reported event at 62% and every one of those artifacts at
+or under 1%.
+
+It works on **pixels rather than counters**:
+the cut's statistics come from a readback capped at two in flight and skipped on more than half the
+frames, so `drawn` on any given frame is a reading from one to three frames ago and a one-frame
+disappearance need never appear in it at all. That is why the panel's numbers look calm during one.
+
+```
+?catch=0.15            count them, panel shows a running tally — fly around looking for one
+?catch=0.15&freeze=1   stop on the first one and leave that frame on screen
+```
+
+**"copy camera link" is how a viewpoint gets out of the browser.** A viewpoint is the one piece of
+state a person has and a session does not: everything else this page can be told is a URL parameter
+already, and a phenomenon that happens "in many places" is not chaseable without one of them. The
+button writes a link that reopens the page where the camera is standing — `?eye=`/`?at=` from the
+live pose, `?tau=` from the slider as it stands rather than as the page was opened, and every other
+parameter left exactly as it was, so a link captured with `?catch=0.15&mirrored=tint` on comes back
+with both still armed. It goes to the clipboard, and to a selected box under the button when a
+browser declines that. `__camera_url()` is the same string for a session with no pointer.
+
+**An event carries its own camera link**, captured at the instant it fires, so `__caught()` is
+self-contained: where it happened is the one thing a report of a one-frame dropout cannot be
+reconstructed without, and by the time anybody reads the report the camera may have moved. The held
+frame goes on *under* the panel, so freezing does not hide the readings that explain it.
+
+`__caught()` reports what it has seen and the counters for the five frames around the last one;
+`__catch_rows()` is the per-frame log. Freezing also holds the five frames around it, and
+`__show_frame(n)` pages between them — the frame before and the frame itself, side by side, is what
+says whether the geometry went missing or merely moved.
+
+It costs a whole-canvas `drawImage` and a small `getImageData` per frame: 4.2 ms a frame becomes
+10.3 ms here, which is slack on a 60 Hz display and is why the full-resolution ring is only kept
+when `freeze=1` is asked for.
+
+## Driving it
+
+`__state()` is the whole surface a headless session needs and the panel shows nothing it does not:
+the scene's counts, the cut's counters, both residency tiers, the render target's size and the
+camera. `__page.runtime.tau` is the threshold, `__look(eye, target)` stands the camera somewhere,
+and `__page.viewpoints` is what the buttons in the panel are.
+
+URL parameters, all of them for a session rather than for a person: `?scene=` the manifest,
+`?tau=` the threshold **before the first container** (see the table above for why a load per row),
+`?pages=` the VRAM tier's slots, `?iterations=` the descent's wavefront ceiling,
+`?eye=x,y,z&at=x,y,z` a viewpoint, `?side=front|back|double` the whole scene's draw side,
+`?mirrored=flip|tint|double` the reflected instances' — and `?catch=<fraction>[&freeze=1]` the
+dropout catcher. `__state().scene.mirrored` is the reflected count the panel shows, and `__caught()`
+the catcher's report.
+
+**`T` records a GPU capture and `T` again downloads an `.sgpt`** — the same key and the same module
+(`playground/profile_hotkey.js`) every other playground binds. It answers the question the panel
+cannot: every reading above is a *count* and not one of them is a cost. The capture's note carries
+τ, the container and instance counts, the cut it selected and the resolution, because the same
+0.4 ms is a triumph at eighty thousand clusters and a scandal at eighteen thousand.
+
+The headless recipe is `vgeo_runtime`'s and has not changed — `--enable-unsafe-webgpu` and nothing
+else, pick the CDP target by URL, resize the window rather than the viewport, and poll for `__state`
+rather than trusting `load`. Its README is where those four are written down and why each one costs
+an hour.