@woosh/meep-engine 3.26.0 → 3.28.0

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
@@ -56,13 +56,31 @@ function torus(major, minor) {
 
     const stride = minor + 1;
 
+    /*
+     Wound so that a triangle seen from **outside** the tube is counter-clockwise, which is what
+     `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 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 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
+     preserves it, and the pool hands it to the rasterizer untouched — so this one line decides
+     whether the whole chain has ever been seen drawing a surface the right way out.
+     */
     for (let i = 0; i < major; i++) {
         for (let j = 0; j < minor; j++) {
             const a = i * stride + j;
             const b = a + stride;
 
-            indices.push(a, b, a + 1);
-            indices.push(a + 1, b, b + 1);
+            indices.push(a, a + 1, b);
+            indices.push(a + 1, b + 1, b);
         }
     }
 

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.

package/src/shade/playground/vgeo_scene/index.html

@@ -0,0 +1,144 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — a whole virtual-geometry scene</title>
+
+    <link rel="icon" href="data:,">
+
+    <style>
+        :root { color-scheme: dark; }
+
+        html, body { height: 100%; margin: 0; overflow: hidden; background: #070b10; }
+
+        /* Placed, not sized — `Renderer` writes an inline `style.width`/`style.height` every time
+           it configures the context, and an inline style beats a rule in here. `main.js` measures
+           the document for the same reason. */
+        #view { position: absolute; top: 0; left: 0; display: block; }
+
+        #panel {
+            position: absolute; top: 0; right: 0; width: 330px; max-height: 100vh; overflow-y: auto;
+            z-index: 10; padding: 12px 14px; box-sizing: border-box;
+            font: 12px/1.45 ui-monospace, "Cascadia Mono", Consolas, monospace;
+            color: #dfe6ee; background: rgba(12, 16, 22, 0.88);
+            border-left: 1px solid #2b3947;
+        }
+
+        #panel h1 { margin: 0 0 8px; font-size: 13px; letter-spacing: 0.06em; color: #7fd2ff; }
+
+        #panel h2 {
+            margin: 14px 0 6px; font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase;
+            color: #6b7c8d; border-bottom: 1px solid #24313d; padding-bottom: 3px;
+        }
+
+        #panel .row { display: flex; justify-content: space-between; gap: 8px; }
+
+        #panel .row span:last-child {
+            color: #f2f6fa; text-align: right;
+            min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+        }
+
+        #panel .row span:first-child { flex: none; }
+        #panel .muted { color: #6b7c8d; }
+        #panel .bad { color: #ff8a7a; }
+        #panel .good { color: #8fe388; }
+        #panel input[type=range] { width: 100%; }
+        #panel label { display: block; margin: 6px 0 2px; }
+
+        #status { white-space: pre-wrap; overflow-wrap: anywhere; }
+        #status.error { color: #ff8a7a; }
+
+        /* The one thing on this page that is not a number: how much of the scene is open. A scene
+           arrives container by container and the picture fills in as it does, so a bar is the
+           honest shape for it — the page is usable long before it is finished. */
+        #progress {
+            margin: 8px 0 2px; height: 4px; background: #1b2530; border-radius: 2px;
+            overflow: hidden;
+        }
+
+        #progress > div { height: 100%; width: 0; background: #7fd2ff; transition: width 0.2s; }
+
+        #views { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 6px; }
+
+        #views button {
+            flex: 1 1 auto; padding: 3px 6px; cursor: pointer;
+            font: inherit; font-size: 11px; color: #dfe6ee;
+            background: #1b2530; border: 1px solid #2b3947; border-radius: 3px;
+        }
+
+        #views button:hover { background: #24313d; border-color: #3d5164; }
+
+        #capture { margin-top: 6px; }
+
+        #capture button {
+            width: 100%; padding: 4px 6px; cursor: pointer;
+            font: inherit; font-size: 11px; color: #dfe6ee;
+            background: #1b2530; border: 1px solid #2b3947; border-radius: 3px;
+        }
+
+        #capture button:hover { background: #24313d; border-color: #3d5164; }
+
+        /* Selectable and wrapped: the clipboard is the happy path and this is what is left when a
+           browser declines it, so it has to be something a person can drag over. */
+        #camera-url {
+            margin-top: 5px; padding: 4px 6px; user-select: all; word-break: break-all;
+            font-size: 11px; color: #9fb4c7; background: #10171f;
+            border: 1px solid #24313d; border-radius: 3px;
+        }
+
+        #hint, #profile-note { margin-top: 10px; color: #6b7c8d; }
+
+        #profile-status { margin-top: 4px; color: #dfe6ee; word-break: break-word; }
+        #profile-status.recording { color: #ff8a7a; }
+    </style>
+</head>
+<body tabindex="0">
+
+<canvas id="view"></canvas>
+
+<div id="panel">
+    <h1>a whole VG scene</h1>
+    <div id="status" class="muted">starting…</div>
+    <div id="progress"><div></div></div>
+
+    <label>threshold τ <span id="tau-value">1.0</span> px</label>
+    <input id="tau" type="range" min="0.25" max="16" step="0.25" value="1">
+
+    <div id="views"></div>
+
+    <div id="capture">
+        <button id="copy-camera" type="button">copy camera link</button>
+        <div id="camera-url" hidden></div>
+    </div>
+
+    <h2>scene</h2>
+    <div id="scene"></div>
+
+    <h2>cut</h2>
+    <div id="cut"></div>
+
+    <h2>residency</h2>
+    <div id="residency"></div>
+
+    <div id="catch-section" hidden>
+        <h2>dropout catcher</h2>
+        <div id="catch"></div>
+        <div class="muted" style="margin-top:6px">a frame unlike the two either side of it, by
+            luminance. <code>&amp;freeze=1</code> stops on the first one and leaves it on screen.
+            <code>__caught()</code> reports, <code>__catch_rows()</code> is the per-frame log.</div>
+    </div>
+
+    <h2>profiling</h2>
+    <div id="profile-status">idle · T to record</div>
+    <div id="profile-note"><strong>T</strong> starts a GPU capture and <strong>T</strong> again
+        stops it and downloads an <code>.sgpt</code>. The note carries τ, the instance count and the
+        cut it selected, because a pass timing means nothing without them.</div>
+
+    <div id="hint">W/A/S/D to move, drag to look, wheel to close in.
+        <code>?scene=&lt;url&gt;</code> opens another one.</div>
+</div>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

package/src/shade/playground/vgeo_scene/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/vgeo_scene/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_scene/main.js"],"names":[],"mappings":""}