@woosh/meep-engine 3.27.0 → 3.29.0

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

@@ -0,0 +1,85 @@
+# `mesh_row_ceiling` — where the rasterizer stops covering the scene
+
+A grid of identical instances, with two knobs that move **one quantity each**, and a number for
+whether the frame actually drew anything.
+
+It exists because [`../caldera/`](../caldera/README.md) found a wall it could not name. That page
+loads a real production map, and its one knob — `?placements=` — moves rows, distinct geometries and
+meshlets together, so all it could say was "the picture stops being correct at 2²⁰ rows". Its repro
+is a 14 GiB asset and about a minute a run.
+
+This one opens in a couple of seconds on nothing but `vite`:
+
+```
+node node_modules/vite/bin/vite.js --port 5181 --strictPort     # from packages/meep-engine
+```
+
+`/src/shade/playground/mesh_row_ceiling/index.html`
+
+| parameter | what it moves |
+|---|---|
+| `?rows=N` | how many instances. One geometry, one material, a regular grid — nothing else changes. |
+| `?segments=N` | the geometry: an `N x N` plane instead of the unit box, which is `(N/8)²` meshlets. Same instances, same pixels, more meshlets. |
+
+Sweeping `?segments=` with `?rows=` held still is the controlled experiment the other page could not
+run: every setting draws the same picture from the same camera, so anything that moves in `coverage`
+is the pipeline and not the scene.
+
+## What it found
+
+| scene | meshlets | coverage |
+|---|---:|---:|
+| `?rows=1100000` | 1,100,000 | 20.3 % |
+| `?rows=150000&segments=32` | 2,400,000 | 9.7 % |
+| `?rows=150000&segments=64` | 9,600,000 | **0 %** |
+| `?rows=200000&segments=64` | 12,800,000 | **0 %** |
+
+**1,100,000 rows draw**, so the ceiling was never on rows — 2²⁰ was where Caldera's own scene
+happened to cross it. The three 150,000-row scenes are the *same* scene at three meshlet densities,
+and the middle one is where it stops.
+
+The number is `maxComputeWorkgroupsPerDimension` (65,535, and `Renderer.initialize` does not raise
+it — an adapter will not hand up more) times the engine's group size of 128: **8,388,480 meshlets in
+one dispatch dimension**. Past it, `shader_prefix_sum_to_command` wrote an indirect command asking
+for more workgroups than the device allows, and a `dispatchWorkgroupsIndirect` in that state **does
+not run at all**. Measured directly against Dawn on nvidia/lovelace from this page's own device:
+
+| workgroups requested | elements written |
+|---:|---:|
+| 65,535 | 65,535 |
+| 65,536 | **0** |
+
+No validation error, nothing logged, `render` does not throw. And the meshlet collection's `count`
+is written by a separate single-thread pass that runs either way, so every counter went on reporting
+a complete frame over an element array the expansion had never filled in. What the rasterizer drew
+was whatever the pooled frame-graph buffer last held — nothing here, and the "huge untextured
+triangles fanning across the frame" `caldera` saw at 1.5 million rows.
+
+The fix is in `IndirectComputeCommandBuildPass`: what will not fit in `x` is folded into `y` and
+then `z`, and the passes these commands drive flatten the grid back with `chunk_grid3d_to_index` —
+the same flattening the light and decal clusters use — instead of reading `global_invocation_id.x`,
+which carries the x dimension alone. One thread per element still, nothing dropped, and while `y`
+and `z` are 1 the index is `global_invocation_id.x` term for term, so a scene under the ceiling pays
+nothing. `mesh_expand_dispatch_ceiling.spec.js` pins it — it runs the real WGSL under the emulator
+over a grid that is deliberately more than one workgroup deep, which is the arithmetic a device
+performs on a folded command.
+
+After the fix the three 150,000-row scenes agree to within a rounding error — 9.74 %, 9.73 %,
+9.74 % at 2.4M, 9.6M and 21.6M meshlets — which is what "the meshlet count no longer changes the
+picture" looks like as a number.
+
+## Driving it headless
+
+`caldera`'s recipe, unchanged, and its first bullet is still the one that costs an hour:
+**`--enable-unsafe-webgpu` and nothing else**. Open the page as Chrome's startup URL, pick the CDP
+target by URL, and poll for `__ready` rather than trusting `load`.
+
+`__state()` is the whole surface; `__page` reaches the renderer, its device and the scene context
+for a session that wants to probe past it.
+
+## What it is not
+
+Not a benchmark. Every instance is the same shape at the same size on a regular grid with one
+material and no textures, which is the wrong shape for a frame-time claim and the right one for
+isolating a count. `caldera` and [`../vgeo_scene/`](../vgeo_scene/README.md) are where the numbers
+about real content live.

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

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — mesh row ceiling</title>
+    <style>
+        :root { color-scheme: dark; }
+
+        * { box-sizing: border-box; }
+
+        html, body { margin: 0; height: 100%; background: #0b0d10; color: #d6dae0;
+            font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; overflow: hidden; }
+
+        #view { display: block; width: 100vw; height: 100vh; }
+
+        #panel {
+            position: fixed; top: 12px; left: 12px; padding: 10px 12px;
+            background: rgba(20, 23, 28, 0.86); border: 1px solid #2b3038; border-radius: 8px;
+            font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 12px;
+            white-space: pre; pointer-events: none;
+        }
+
+        .bad { color: #ff6b6b; }
+    </style>
+</head>
+<body tabindex="0">
+<canvas id="view"></canvas>
+<div id="panel">booting…</div>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

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

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

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

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

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

@@ -0,0 +1,389 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { BoxGeometry, PlaneGeometry } from "../../renderer/geometry/BoxGeometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { RasterizationCollectionType } from "../../renderer/rasterize/expand/RasterizationCollectionType.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+
+/**
+ * The cheapest scene big enough to find a dispatch ceiling.
+ *
+ * `caldera` found that the picture stops being correct somewhere past a million mesh rows and says
+ * nothing about it — see that page's README. Its repro is a 14 GiB asset and a minute of loading a
+ * run, and `?placements=` moves three quantities at once: rows, distinct geometries and meshlets
+ * all grow together, so it cannot say which of the three the ceiling belongs to. It reported the
+ * ceiling as 2²⁰ **rows** because that is where its own scene crossed it.
+ *
+ * This page separates them, from nothing but `vite`:
+ *
+ * - **`?rows=N`** places N instances of one geometry on a grid. Every row is the same shape, so
+ *   the row count is the only thing that moves.
+ * - **`?segments=N`** swaps the unit box for an N x N plane, which is `(N/8)²` meshlets. The
+ *   instances stay where they were and cover the same pixels — only the meshlet count moves.
+ *
+ * Which answered the question in two runs: **1,100,000 rows of one meshlet each draw** and
+ * 150,000 rows of 64 draw nothing, so the ceiling was never on rows. It is
+ * `maxComputeWorkgroupsPerDimension` x {@link COMPUTE_SHADER_DEFAULT_GROUP_SIZE} = 8,388,480
+ * meshlets in *one dispatch dimension*, past which an indirect dispatch does not run at all — see
+ * {@link build_indirect_compute_dispatch_command}, whose fold is the fix, and
+ * `mesh_expand_dispatch_ceiling.spec.js`, which pins it.
+ *
+ * `__state()` is the driving surface, as on the other pages. `coverage` in it is the fraction of
+ * the canvas that is not the clear colour, sampled on a grid — which is the one thing every
+ * counter in the engine was reporting as healthy while the screen was empty. Holding `?rows=`
+ * still and sweeping `?segments=` is the controlled experiment: the picture is identical at every
+ * setting, so any change in `coverage` is the pipeline.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** How many rows, when the URL does not say. */
+const DEFAULT_ROWS = 1_100_000;
+
+/** Side of one box, in world units. Spacing is twice this, so boxes never touch. */
+const BOX_SIZE = 1;
+
+const page = {
+    /** @type {Renderer} */
+    renderer: undefined,
+    /** @type {HTMLCanvasElement} */
+    canvas: undefined,
+    /** @type {PerspectiveCamera} */
+    camera: undefined,
+    /** @type {Scene} */
+    scene: undefined,
+    /** @type {GPUSceneContext} */
+    scene_context: undefined,
+    rows: 0,
+    frames: 0,
+    frame_ms: 0,
+    cpu_ms: 0,
+    place_ms: 0,
+    /** @type {Error|undefined} */
+    fatal: undefined,
+};
+
+/**
+ * Fraction of the canvas that is not the clear colour.
+ *
+ * Read through a 2D canvas rather than from the device: the question is what a viewer sees, and a
+ * `drawImage` of the presented surface is exactly that. Sampled on a stride rather than per pixel
+ * so it can run every frame without becoming the frame.
+ *
+ * @param {HTMLCanvasElement} canvas
+ * @param {number} [stride] sample every `stride`-th pixel along each axis
+ * @returns {number} 0 when nothing was drawn, 1 when every sample differs from the clear colour
+ */
+function measure_coverage(canvas, stride = 4) {
+    const w = canvas.width;
+    const h = canvas.height;
+
+    if (w === 0 || h === 0) {
+        return 0;
+    }
+
+    const scratch = measure_coverage.scratch ??= document.createElement('canvas');
+
+    if (scratch.width !== w || scratch.height !== h) {
+        scratch.width = w;
+        scratch.height = h;
+    }
+
+    const ctx = scratch.getContext('2d', { willReadFrequently: true });
+
+    ctx.clearRect(0, 0, w, h);
+    ctx.drawImage(canvas, 0, 0);
+
+    const pixels = ctx.getImageData(0, 0, w, h).data;
+
+    let sampled = 0;
+    let covered = 0;
+
+    /*
+     The clear colour is whatever the top-left corner is: the camera looks down at a grid that does
+     not reach the corners, so that pixel is background in every scene this page draws. Taking it
+     from the frame rather than naming a constant keeps this honest if the clear colour changes.
+    */
+    const bg_r = pixels[0];
+    const bg_g = pixels[1];
+    const bg_b = pixels[2];
+
+    for (let y = 0; y < h; y += stride) {
+        for (let x = 0; x < w; x += stride) {
+            const i = (y * w + x) * 4;
+
+            sampled++;
+
+            const dr = pixels[i] - bg_r;
+            const dg = pixels[i + 1] - bg_g;
+            const db = pixels[i + 2] - bg_b;
+
+            // 3/255 of slack, so film grain and dither do not read as geometry
+            if (dr * dr + dg * dg + db * db > 27) {
+                covered++;
+            }
+        }
+    }
+
+    return sampled === 0 ? 0 : covered / sampled;
+}
+
+/**
+ * Lay `count` boxes out on a square grid in the XZ plane, centred on the origin.
+ *
+ * @param {number} count
+ * @returns {number} half the diagonal of the grid, for framing
+ */
+function place_grid(geometry, count, segments) {
+    const material = new StandardShadeMaterial();
+
+    const side = Math.ceil(Math.sqrt(count));
+    const spacing = BOX_SIZE * 2;
+    const origin = -0.5 * (side - 1) * spacing;
+
+    const transform = new Transform64();
+
+    /*
+     A plane is authored in XY facing +Z, and this camera looks down the Y axis — so laid out as
+     authored every one of them is edge-on and the frame is empty for a reason that has nothing to
+     do with the pipeline. A quarter turn about X puts them face up. A box needs no such thing.
+    */
+    const quarter_turn = Math.SQRT1_2;
+
+    for (let i = 0; i < count; i++) {
+        const x = origin + (i % side) * spacing;
+        const z = origin + Math.floor(i / side) * spacing;
+
+        transform.setTranslation(x, 0, z);
+
+        if (segments !== 0) {
+            transform.setRotation(-quarter_turn, 0, 0, quarter_turn);
+        }
+
+        transform.updateMatrix();
+
+        place_primitive(page.scene_context, geometry, material, transform);
+    }
+
+    return 0.5 * Math.hypot(side * spacing, BOX_SIZE, side * spacing);
+}
+
+/**
+ * What every row draws.
+ *
+ * A box is one meshlet, so `?rows=` alone moves rows and meshlets together at 1:1 and cannot
+ * separate them. A segmented plane is the second axis: `?segments=N` is an N x N grid of quads,
+ * which comes out at a meshlet per 64-odd triangles, so a modest row count can be pushed to any
+ * meshlet count the pipeline might have a ceiling on.
+ *
+ * @param {number} segments
+ * @returns {MeshletGeometry}
+ */
+function make_geometry(segments) {
+    return segments === 0
+        ? new BoxGeometry(BOX_SIZE, BOX_SIZE, BOX_SIZE)
+        : new PlaneGeometry(BOX_SIZE, BOX_SIZE, segments, segments);
+}
+
+function paint() {
+    const panel = document.getElementById('panel');
+
+    const limits = page.renderer.graphics.collection_limits;
+
+    const lines = [
+        `rows            ${page.rows.toLocaleString()}`,
+        `meshlets / row  ${page.meshlets_per_row}`,
+        `meshlets        ${(page.rows * page.meshlets_per_row).toLocaleString()}`,
+        `placed in       ${(page.place_ms / 1000).toFixed(1)} s`,
+        `frames          ${page.frames}`,
+        `frame / cpu     ${page.frame_ms.toFixed(1)} / ${page.cpu_ms.toFixed(1)} ms`,
+        `coverage        ${(page.coverage * 100).toFixed(2)} %`,
+        `mesh limit      ${limits.get_limit(RasterizationCollectionType.Meshes).toLocaleString()}`,
+        `meshlet limit   ${limits.get_limit(RasterizationCollectionType.Meshlets).toLocaleString()}`,
+    ];
+
+    if (page.fatal !== undefined) {
+        lines.push(`<span class="bad">${page.fatal.message ?? String(page.fatal)}</span>`);
+    }
+
+    panel.innerHTML = lines.join('\n');
+}
+
+async function boot() {
+    const parameters = new URLSearchParams(globalThis.location.search);
+
+    const rows = Math.max(1, Math.floor(Number(parameters.get('rows') ?? DEFAULT_ROWS)));
+    const segments = Math.max(0, Math.floor(Number(parameters.get('segments') ?? 0)));
+
+    page.rows = rows;
+    page.segments = segments;
+
+    const canvas = document.getElementById('view');
+
+    page.canvas = canvas;
+
+    const renderer = new Renderer();
+
+    page.renderer = renderer;
+
+    await renderer.initialize({
+        context: canvas.getContext('webgpu'),
+        pixelRatio: 1,
+    });
+
+    // geometry, not picture — every one of these is frame time spent on a question this page is not asking
+    renderer.feature_taa_enabled = false;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    const scene = new Scene();
+
+    scene.dataset = new EntityComponentDataset();
+
+    page.scene = scene;
+
+    place_light(scene, make_sunlight({ direction: new Vector3(0.4, -0.82, 0.41) }));
+
+    const camera = new PerspectiveCamera();
+
+    camera.fov_degrees = 60;
+
+    page.camera = camera;
+    page.controller = new OrbitalCameraController(camera, document.body);
+
+    fit();
+
+    globalThis.addEventListener('resize', fit);
+
+    // one frame, so the renderer builds the scene context the rows go into
+    renderer.render(camera, scene, 1 / 60);
+
+    page.scene_context = renderer.scenes.obtain(scene);
+
+    /*
+     Primed rather than grown: the collections start at 1e4 meshes, and a scene that arrives all at
+     once would spend its first frames reporting the difference as dropped instances. This page is
+     about what the pipeline does with the rows, not about how fast the limits catch up.
+    */
+    const limits = renderer.graphics.collection_limits;
+
+    const geometry = make_geometry(segments);
+
+    page.meshlets_per_row = geometry.meshlets.count;
+
+    limits.prime(RasterizationCollectionType.Meshes, rows);
+    limits.prime(RasterizationCollectionType.Meshlets, rows * page.meshlets_per_row);
+
+    const place_started = performance.now();
+
+    const radius = place_grid(geometry, rows, segments);
+
+    page.place_ms = performance.now() - place_started;
+
+    look_at_grid(radius);
+
+    let last_time;
+
+    const tick = time => {
+        const dt = last_time === undefined ? 1 / 60 : Math.min((time - last_time) / 1000, 0.05);
+
+        if (last_time !== undefined) {
+            page.frame_ms += ((time - last_time) - page.frame_ms) * 0.1;
+        }
+
+        last_time = time;
+
+        const cpu_started = performance.now();
+
+        try {
+            page.controller.update(dt);
+            renderer.render(camera, scene, dt);
+        } catch (error) {
+            page.fatal = error;
+            console.error(error);
+            paint();
+            return;
+        }
+
+        page.cpu_ms += ((performance.now() - cpu_started) - page.cpu_ms) * 0.1;
+        page.frames++;
+
+        page.coverage = measure_coverage(canvas);
+
+        paint();
+
+        requestAnimationFrame(tick);
+    };
+
+    requestAnimationFrame(tick);
+
+    globalThis.__ready = true;
+}
+
+/**
+ * Size the canvas to the document — see `caldera`'s `fit()` for why the document and not the canvas.
+ */
+function fit() {
+    const renderer = page.renderer;
+    const viewport = document.documentElement;
+
+    renderer.pixel_ratio = 1;
+
+    renderer.resize(
+        Math.max(1, Math.floor(viewport.clientWidth)),
+        Math.max(1, Math.floor(viewport.clientHeight))
+    );
+
+    page.camera.aspect = renderer.aspect_ratio;
+}
+
+/**
+ * @param {number} radius half the grid's diagonal
+ */
+function look_at_grid(radius) {
+    const distance = radius * 1.6;
+
+    page.camera.near = Math.max(0.05, distance * 0.002);
+    page.camera.far = distance * 8;
+
+    page.controller.look(
+        new Vector3(distance * 0.6, distance * 0.7, distance * 0.6),
+        new Vector3(0, 0, 0)
+    );
+}
+
+/**
+ * The page's own objects, for a session that wants to look past `__state()` — the renderer, its
+ * device and the scene context are all reachable from here.
+ */
+globalThis.__page = page;
+
+globalThis.__state = () => ({
+    rows: page.rows,
+    segments: page.segments,
+    meshlets_per_row: page.meshlets_per_row,
+    meshlets: page.rows * page.meshlets_per_row,
+    frames: page.frames,
+    coverage: page.coverage,
+    frame_ms: page.frame_ms,
+    cpu_ms: page.cpu_ms,
+    place_ms: page.place_ms,
+    mesh_limit: page.renderer?.graphics.collection_limits.get_limit(RasterizationCollectionType.Meshes),
+    meshlet_limit: page.renderer?.graphics.collection_limits.get_limit(RasterizationCollectionType.Meshlets),
+    fatal: page.fatal === undefined ? null : (page.fatal.message ?? String(page.fatal)),
+});
+
+boot().catch(error => {
+    page.fatal = error;
+    console.error(error);
+    paint();
+    globalThis.__ready = true;
+});

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
@@ -230,9 +244,11 @@ chrome --headless=new --enable-unsafe-webgpu --remote-debugging-port=9333 \
 - **A drop is dispatchable.** `new DataTransfer()`, `items.add(new File([bytes], name))`, then
   `window.dispatchEvent(new DragEvent('drop', { dataTransfer }))` goes through the page's own
   handler — no pointer, and no separate code path to keep honest. `?file=` needs a server that
-  answers `Range` with a `206`; vite refuses `/@fs/` outside the workspace, so an asset off the
-  tree wants twenty lines of `http.createServer` with `Access-Control-Expose-Headers:
-  Content-Range`.
+  answers `Range` with a `206`, and **the dev server is one**: `tools/dev/vite_test_assets.js`
+  serves `/test_assets/` by range out of an asset root outside the checkout as well as the one
+  inside it, so `?file=/test_assets/<whatever>.vgeo` is a container off the tree with nothing else
+  running. `tools/geometry/virtual/vgeo_serve.js` is still what a directory under neither root
+  wants, and the CORS headers are the whole difference.
 
 Open the page as Chrome's startup URL rather than with `Page.navigate` — the `load` event is not a
 reliable signal here, so poll for `__state` itself. Then set `__page.runtime.tau` and read

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
@@ -596,6 +596,7 @@ class VGeoPlayground {
                 clusters_tested: stats[VGEO_CUT_STAT.CLUSTERS_TESTED],
                 culled_frustum: stats[VGEO_CUT_STAT.CULLED_FRUSTUM],
                 culled_cluster: stats[VGEO_CUT_STAT.CULLED_CLUSTER],
+                culled_cluster_box: stats[VGEO_CUT_STAT.CULLED_CLUSTER_BOX],
                 culled_lod: stats[VGEO_CUT_STAT.CULLED_LOD],
                 meshlets_dropped: stats[VGEO_CUT_STAT.MESHLETS_DROPPED],
                 wants_dropped: stats[VGEO_CUT_STAT.WANTS_DROPPED],
@@ -617,6 +618,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,
@@ -858,7 +860,7 @@ async function start() {
         // yielded so the status paints before the builder takes the thread for half a second
         await new Promise(resolve => setTimeout(resolve, 0));
 
-        const { source, build_ms } = vgeo_sample_source(128, 48, PAGE_SIZE);
+        const { source, build_ms } = await vgeo_sample_source(128, 48, PAGE_SIZE);
 
         await page.load(source);
 
@@ -890,7 +892,7 @@ async function start() {
             ['pages visited', state.cut.pages],
             ['clusters tested', state.cut.clusters_tested],
             ['subtrees culled', state.cut.culled_frustum + state.cut.culled_lod],
-            ['clusters culled', state.cut.culled_cluster],
+            ['clusters culled', `${state.cut.culled_cluster} (box ${state.cut.culled_cluster_box})`],
             ['wants', state.wants],
         ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
             .join('');
@@ -917,6 +919,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('');