@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -8,11 +8,11 @@
  * @param {number} [major]
  * @param {number} [minor]
  * @param {number} [page_size] target decoded bytes per page
- * @returns {{source: VGeoByteSource, build_ms: number}}
+ * @returns {Promise<{source: VGeoByteSource, build_ms: number}>}
  */
-export function vgeo_sample_source(major?: number, minor?: number, page_size?: number): {
+export function vgeo_sample_source(major?: number, minor?: number, page_size?: number): Promise<{
     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,QAAQ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAAC,CAiB/D;+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
@@ -114,16 +115,16 @@ function torus(major, minor) {
  * @param {number} [major]
  * @param {number} [minor]
  * @param {number} [page_size] target decoded bytes per page
- * @returns {{source: VGeoByteSource, build_ms: number}}
+ * @returns {Promise<{source: VGeoByteSource, build_ms: number}>}
  */
-export function vgeo_sample_source(major = 128, minor = 48, page_size = 16 * 1024) {
+export async function vgeo_sample_source(major = 128, minor = 48, page_size = 16 * 1024) {
     const options = new VGeoBuildOptions();
 
     options.nominal_page_size = page_size;
 
     const started = performance.now();
 
-    const bytes = vgeo_build(torus(major, minor), options).buffer.raw_bytes;
+    const bytes = (await vgeo_build(torus(major, minor), options)).buffer.raw_bytes;
 
     const build_ms = performance.now() - started;
 

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

@@ -0,0 +1,487 @@
+# `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
+
+Two things: a scene manifest under the asset root, and the dev server.
+
+```
+node tools/geometry/virtual/vgeo_scene.js <manifest.vgeo.json> --camera "..." --sun "..."
+npm run dev --workspace @woosh/meep-engine
+```
+
+Then open `/src/shade/playground/vgeo_scene/index.html`. With no parameters it asks the dev server
+for every `.vgeoscene.json` under the roots it is serving and opens the one scene that is there;
+`?scene=<url>` overrides.
+
+**The containers do not have to be in the checkout, and the dev server is what serves them.**
+`tools/dev/vite_test_assets.js` serves `/test_assets/` out of the package's own directory *and* out
+of an external asset root — `MEEP_TEST_ASSETS`, or the nearest `test_assets/` above the package,
+which on this machine is `H:/test_assets` — so Zorah's 51 GiB sit on a drive and are reached at
+`/test_assets/Zorah/…` from the server that is already running. The dev server prints the roots it
+found at startup.
+
+**Ranges are what makes that a claim worth checking.** 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. That invariant is
+`tools/dev/serve_file_range.js` and there is one of it:
+`tools/geometry/virtual/vgeo_serve.js` — still the answer for a directory under no asset root, or a
+page served from another origin — is the same code plus CORS, where
+`Access-Control-Expose-Headers` is the header that is easy to miss, 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.
+- **A material's texture, when it has one.** The containers have no texture coordinates — see the
+  next section — so a material is bound as the constants its textures average to rather than as the
+  textures themselves.
+
+## Materials, and why they arrive from the side
+
+A `.vgeo` carries geometry only, so a converted set has no material authoring in it. For a long time
+this page drew all of it with one grey material and said so here, because the alternative was
+inventing colour.
+
+It now reads a **sidecar** instead: `<scene>.vgeomaterials.json`, written by
+[`vgeo_scene_materials.js`](../../../../../tools/geometry/virtual/vgeo_scene_materials.js) out of an
+extraction of the original Unreal project
+([`tools/ue/`](../../../../../tools/ue/)). It says which material each container is — a `.vgeo` is
+one glTF primitive and a primitive has exactly one material, so the container *is* the bucket — and
+what to shade that material with. It is a separate file from the scene manifest because it answers
+to a separate source, and a scene nobody has extracted a project for is still a scene: the page
+opens with or without one.
+
+`?materials=off` refuses it and restores the one-grey-material picture. `?materials=<url>` names one
+explicitly.
+
+**What is bound is the constants, not the textures, and that is about the asset.**
+`zorah_main_public.v2.gltf` — the document every container was built from — declares `POSITION` and
+nothing else. No `TEXCOORD_0`, no `NORMAL`; the normals and tangents in the containers were generated
+during conversion. So there is nothing to sample an albedo map *with* until a UV-carrying source is
+built and the containers are made again from it. The constants are measured rather than invented:
+`albedo` is the extracted base colour map's own alpha-weighted mean **in linear space**, multiplied
+by the material's authored tint; roughness comes from the real ORM and metalness from the same map,
+rounded, because metalness is binary per texel and the mean of a map is not a metalness. What a
+surface loses is its detail, not its identity.
+
+**The numbers, for Zorah.** 341 material names, of which 146 are in the distributed Unreal sample —
+it ships a subset of the scene the glTF came from, and 191 of the names are nowhere in it. 72 more
+are drawn as the nearest sibling within a narrow family and say so in `approximated_from`. That is
+**218 materials over 2,533 of the 3,163 containers**; the remaining 630 draw as a neutral grey.
+
+**They cost about 2.4 ms.** Measured on an nvidia/lovelace adapter at 1578×746 from the authored
+viewpoint, twelve samples each: **5.28 ms** median with one material, **7.7 ms** with 218. That is
+the scene's real shape rather than a price this page chose to pay, and it is worth knowing that a
+material bucket is not free — about eleven microseconds of one, here.
+
+## The indirect light is brighter than the light
+
+Extracted materials read paler and less saturated than the maps they came from, and the reason is
+not in the materials. `?env=` and `?sun=` are here to say so in one measurement.
+
+`?env=uniform:<v>` replaces the sky with a **constant radiance from every direction** — 64×64 so it
+carries a mip chain, every level the same value — and `?sun=off` takes the only other light away.
+Against a uniform environment the question is closed rather than arguable: nothing can return more
+of a constant field than it reflects.
+
+Measured on the `waterjug` sample at `env=uniform:0.5&sun=off&textures=off`, one pixel of the
+surface against one pixel of the background, in the same frame and therefore at the same exposure:
+
+| material | surface ÷ environment | should be |
+|---|---:|---:|
+| albedo 0, roughness 0.57 | **2.74** | ~0.05 |
+| albedo 0, roughness 1.0 | **2.69** | ~0.05 |
+| albedo 0.18 | 3.06 | ~0.23 |
+| albedo 1.0 | 4.49 | ~1.0 |
+
+**A black, non-metal surface returns 2.7× the only light in the scene.** Tonemapping is monotonic,
+so no curve makes that legitimate — it is energy gain, and it is what puts a constant neutral
+pedestal under every material and washes the colour out of it. It is independent of albedo, of
+roughness, and of the sun; `?env=off` removes it entirely.
+
+`indirect_specular` is `radiance * totalScattering` and radiance here is 0.5 by construction, so
+`totalScattering` is coming out near 2.7. `compute_multiscattering_specular` cannot produce that
+from a sane split-sum lookup, so the gain is above it — the LUT's own values, `specular_occlusion`,
+or the specular IBL pass. Not chased further than that.
+
+**None of this is about virtual geometry**, which is why it is a note rather than a fix here: it
+reproduces with a constant-colour `StandardShadeMaterial` and no extraction involved.
+
+## 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 (any
+URL, and `/test_assets/…` is the asset root),
+`?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', `?materials=off|<url>` the material sidecar,
+`?textures=off` its maps, `?env=off|uniform:<v>` and `?sun=off` the lighting —
+and `?catch=<fraction>[&freeze=1]` the dropout catcher. `__state().scene.mirrored` is the reflected
+count the panel shows, `__state().scene.materials` and `.materialised` the material counts, 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.