@woosh/meep-engine 3.24.0 → 3.26.0

package/src/shade/device/mock/texture_copy.js

@@ -104,6 +104,34 @@ function texture_endpoint_refusal(info, role, required_usage, required_usage_nam
         return `${role} copySize.height (${extent.height}) is not a multiple of the ${format.block_height}-texel block height of ${texture.format}`;
     }
 
+    /*
+     WebGPU's rule for `copyTextureToBuffer`/`copyBufferToTexture`/`writeTexture`: "if the
+     GPUTexture.format is a depth-or-stencil format or GPUTexture.sampleCount is more than 1, the
+     subresource size is equal to size". A depth buffer is copied whole or not at all — there is no
+     reading one texel of one, and the one-pixel read that looks like the obvious way to pick an
+     entity off the frame's depth is the thing this forbids. The restriction comes from D3D12, so
+     it is enforced everywhere rather than being a Windows-only surprise.
+
+     Only the two axes a region is named in: this does not also require a layered copy to take every
+     layer, which WebGPU's definition of a subresource's size does.
+    */
+    const depth_or_stencil = !format.aspects.includes("all");
+
+    if (depth_or_stencil || texture.sampleCount > 1) {
+        const full_width = texture.mip_width(mip);
+        const full_height = texture.mip_height(mip);
+
+        if (origin.x !== 0 || origin.y !== 0 || extent.width !== full_width || extent.height !== full_height) {
+            const why = depth_or_stencil
+                ? `is ${texture.format}, a depth-or-stencil format`
+                : `has sampleCount ${texture.sampleCount}`;
+
+            return `${role} texture '${texture.label}' ${why}, so a copy must cover the whole`
+                + ` subresource; mip ${mip} is ${full_width}x${full_height} and the region asked for`
+                + ` is ${extent.width}x${extent.height} at (${origin.x}, ${origin.y})`;
+        }
+    }
+
     return null;
 }
 

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

@@ -0,0 +1,94 @@
+# `vgeo_runtime` — the cut, on the GPU, through the engine
+
+A `.vgeo` container drawn as an ordinary `Mesh`, in an ordinary `Scene`, with an ordinary material.
+This page draws nothing itself: every triangle on screen is there because the compute cut appended
+`MESHLET_DEFINITION_STRUCT` records into the same collection a static mesh's meshlets go into, and
+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.
+
+## What it shows
+
+The container is built in the page and opened holding **only its root page**. Everything else
+arrives because the cut asked for it: a clamped cluster emits a want, the want names the page it
+was discovered through, the feedback readback resolves it to a byte range out of that page's own
+child table, and the page installs. Nothing is prefetched and no directory is read.
+
+Measured on an nvidia/lovelace adapter, a 128×48 torus at 64 KB pages — 13 pages, built in ~0.5 s
+in-page — and **re-measured on the same adapter after the review campaign**, which rewrote the VRAM
+tier onto fixed-stride page slots, moved selectability off the RAM tier, corrected the near plane's
+sign and replaced the scale correction. Every row is identical:
+
+| τ (px) | drawn clusters | pages visited | clamped | wavefronts | queue remaining |
+|---:|---:|---:|---:|---:|---:|
+| 0.5 | 50 | 9 | 0 | 14 | 0 |
+| 1 | 31 | 8 | 0 | 14 | 0 |
+| 2 | 18 | 6 | 0 | 11 | 0 |
+| 4 | 17 | 6 | 0 | 11 | 0 |
+| 8 | 9 | 5 | 0 | 8 | 0 |
+| 16 | 8 | 5 | 0 | 8 | 0 |
+
+The last two columns are new and are what the review's M8 was about: the descent ran fourteen
+wavefronts at its deepest against a budget of 64, and stopped with nothing still queued. A non-zero
+`queue remaining` is the one reading here that means a **hole** rather than a coarser surface.
+
+The cut is monotone in τ and it is a *fraction* of the asset at every setting, which is design §1's
+whole claim: rendering cost is a function of the threshold and the resolution, not of the source
+triangle count. Residency settles at 9 of 13 pages and 230 KB — the four it never fetches are the
+ones the cut never wanted.
+
+Two readings are worth watching for what they say about the loop rather than the picture:
+
+- **`clamped` goes to zero.** The first frames draw a coarse, watertight surface because the pages
+  holding the refinement have not arrived. That is not a fallback — it is the correct surface over
+  exactly that region — and the count falling to zero is the streaming finishing.
+- **`feedback skipped` is about half the frames.** The readback cap is two in flight, and a frame
+  that finds it saturated drops its feedback entirely. That is the virtual-texture contract, it
+  costs streaming latency and nothing on screen, and a loop that insisted on a reading every frame
+  would stall the frame it was reading.
+
+## Driving it
+
+`__state()` is the whole surface a headless session needs — frames, the cut's counters, and both
+residency tiers. `__page.runtime.tau` is the threshold. The panel shows nothing `__state()` does
+not.
+
+```
+npm run dev --workspace @woosh/meep-engine
+# then open /src/shade/playground/vgeo_runtime/index.html
+```
+
+**This page is the only thing that exercises the engine-integration path**, and that is not a
+rhetorical claim: 18,569 passing specs did not notice it failing to boot at all, because
+`scene.add(make_sunlight())` had outlived `Scene.add` and the page threw before defining
+`__state`. Treat a green suite without a drive as unverified.
+
+### The headless recipe, and the two things that cost an hour
+
+Start the dev server, then launch Chrome with a debugging port and connect over CDP:
+
+```
+node node_modules/vite/bin/vite.js --port 5199 --strictPort    # from packages/meep-engine
+chrome --headless=new --enable-unsafe-webgpu --remote-debugging-port=9333 \
+       --user-data-dir=<a fresh one> \
+       http://localhost:5199/src/shade/playground/vgeo_runtime/index.html
+```
+
+- **`--enable-unsafe-webgpu` and nothing else.** Adding `--enable-features=Vulkan`,
+  `--use-angle=vulkan` or `--disable-gpu-sandbox` — all of which appear in the recipes people write
+  down for headless WebGPU — makes `requestAdapter()` return nothing on this machine, and the page
+  reports it as "the browser supports WebGPU but would not provide a GPU to run on". The plain flag
+  gives a real nvidia/lovelace adapter.
+- **Pick the CDP target by URL.** `/json/list` returns extension background pages and
+  `chrome://omnibox-popup` targets as well, and the first entry is routinely not the page. Attaching
+  to one of those and asking it for `navigator.gpu` answers `undefined`, which reads exactly like a
+  browser without WebGPU.
+
+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
+`__state()` back.

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

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — virtual geometry runtime</title>
+
+    <link rel="icon" href="data:,">
+
+    <style>
+        :root { color-scheme: dark; }
+
+        html, body { height: 100%; margin: 0; overflow: hidden; background: #070b10; }
+
+        #panel {
+            position: absolute; top: 0; right: 0; width: 320px; 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; }
+        #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; }
+        #status.error { color: #ff8a7a; }
+    </style>
+</head>
+<body tabindex="0">
+
+<div id="panel">
+    <h1>virtual geometry runtime</h1>
+    <div id="status" class="muted">starting…</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">
+
+    <h2>cut</h2>
+    <div id="cut"></div>
+
+    <h2>residency</h2>
+    <div id="residency"></div>
+</div>
+
+<canvas id="view" width="960" height="600"></canvas>
+
+<script type="module" src="./main.js"></script>
+
+</body>
+</html>

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

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

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

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

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

@@ -0,0 +1,399 @@
+import { Color } from "../../../core/color/Color.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.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 { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { VGEO_CUT_STAT } from "../../renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
+import { VGeoFeedbackLoop } from "../../renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VirtualGeometry } from "../../renderer/geometry/virtual/runtime/VirtualGeometry.js";
+import {
+    VGeoContainerReader
+} from "../../renderer/geometry/virtual/format/read/VGeoContainerReader.js";
+import {
+    VGeoReadOptions
+} from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
+import {
+    VGeoResidencyManager
+} from "../../renderer/geometry/virtual/residency/VGeoResidencyManager.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 { Renderer } from "../../renderer/Renderer.js";
+import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { vgeo_sample_source } from "../vgeo_viewer/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,
+ * 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
+ * geometry exists.
+ *
+ * So the interesting readings here are the ones about the engine rather than about the DAG:
+ *
+ * - **drawn triangles track τ and the resolution, not the source.** Design §1's whole claim. Move
+ *   the slider and watch the cut, not the asset.
+ * - **clamped falls to zero as pages arrive.** The cut starts against a container holding only its
+ *   root page, so the first frames are a coarse but watertight surface, and the wants the cut emits
+ *   are what fetch the rest.
+ * - **nothing is drawn twice.** `drawn` against the triangle count the rasterizer reports.
+ *
+ * `__state()` is what a headless session asserts on; everything the panel shows comes from it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const element = id => document.getElementById(id);
+
+/**
+ * Opens the VG frame before anything records a rasterization pass, because the seam inside those
+ * passes writes into the feedback buffer this creates.
+ */
+class VGeoFrameStart extends RenderExtension {
+    name = "vgeo/frame start";
+
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @param {VGeoPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.begin(frame);
+    }
+}
+
+/**
+ * Schedules the readback and closes the frame, after everything that could have cut has cut.
+ */
+class VGeoFrameEnd extends RenderExtension {
+    name = "vgeo/frame end";
+
+    phase = FramePhase.BeforePresent;
+
+    /**
+     * @param {VGeoPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.finish(frame);
+    }
+}
+
+class VGeoPlayground {
+    /**
+     * @type {VGeoContainerReader}
+     */
+    reader;
+
+    /**
+     * @type {GPUVirtualGeometryRuntime}
+     */
+    runtime;
+
+    /**
+     * @type {VGeoFeedbackLoop}
+     */
+    feedback;
+
+    /**
+     * @type {VGeoResidencyManager}
+     */
+    residency;
+
+    /**
+     * @type {number}
+     */
+    frames = 0;
+
+    /**
+     * @type {number}
+     */
+    canvas_height = 600;
+
+    /**
+     * @type {number}
+     */
+    fov_y = 50 * DEG_TO_RAD;
+
+    /**
+     * @param {FrameContext} frame
+     */
+    begin(frame) {
+        this.runtime.begin_frame(frame.graph, {
+            screen_height: this.canvas_height,
+            fov_y: this.fov_y,
+        });
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    finish(frame) {
+        // the RAM tier's clock moves inside this: a host that drives the loop gets a bounded
+        // second tier without having to know it had one to wind
+        this.feedback.read(frame.graph);
+
+        this.runtime.end_frame();
+
+        this.frames++;
+    }
+
+    /**
+     * Everything a headless session needs, and everything the panel shows.
+     *
+     * @returns {object}
+     */
+    state() {
+        const stats = this.feedback.stats;
+        const pool = this.runtime.pool;
+
+        return {
+            frames: this.frames,
+            tau: this.runtime.tau,
+            feedback_reads: this.feedback.read_count,
+            feedback_skipped: this.feedback.skipped_frames,
+            cut: {
+                drawn: stats[VGEO_CUT_STAT.DRAWN],
+                clamped: stats[VGEO_CUT_STAT.CLAMPED],
+                clamped_on_activation: stats[VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION],
+                pages: stats[VGEO_CUT_STAT.PAGES],
+                items: stats[VGEO_CUT_STAT.ITEMS],
+                clusters_tested: stats[VGEO_CUT_STAT.CLUSTERS_TESTED],
+                culled_frustum: stats[VGEO_CUT_STAT.CULLED_FRUSTUM],
+                culled_lod: stats[VGEO_CUT_STAT.CULLED_LOD],
+                meshlets_dropped: stats[VGEO_CUT_STAT.MESHLETS_DROPPED],
+                wants_dropped: stats[VGEO_CUT_STAT.WANTS_DROPPED],
+                queue_dropped: stats[VGEO_CUT_STAT.QUEUE_DROPPED],
+                instances_dropped: stats[VGEO_CUT_STAT.INSTANCES_DROPPED],
+                wavefronts: stats[VGEO_CUT_STAT.WAVEFRONTS],
+                queue_remaining: stats[VGEO_CUT_STAT.QUEUE_REMAINING],
+            },
+            wants: this.feedback.last_want_count,
+            touches: this.feedback.last_touch_count,
+            vram: {
+                pages: pool.resident_page_count,
+                bytes: pool.resident_bytes,
+                evicted: pool.evicted_page_count,
+                refused: pool.refused_install_count,
+            },
+            ram: {
+                pages: this.reader.resident_page_count,
+                bytes: this.reader.resident_bytes,
+                total_pages: this.reader.header.total_pages,
+            },
+        };
+    }
+}
+
+async function start() {
+    const canvas = element('view');
+
+    const status = text => {
+        element('status').textContent = text;
+    };
+
+    const renderer = new Renderer();
+
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+
+    renderer.feature_taa_enabled = false;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    renderer.resize(canvas.width, canvas.height);
+
+    status('building a container in the page…');
+
+    /*
+     One number for the asset and for the tier that holds it. A page size is a bound the container
+     states (FORMAT §11.14) and the pool holds pages at exactly one, so a mismatch here is a refusal
+     at `register` rather than something that limps.
+     */
+    const page_size = 64 * 1024;
+
+    const { source, build_ms } = vgeo_sample_source(128, 48, page_size);
+
+    /*
+     Frame verification on, because this reader is a runtime's rather than a tool's — format §10
+     leaves it off by default precisely because a tool reading a file it just built is not
+     defending against a network, and a runtime is.
+     */
+    const options = new VGeoReadOptions();
+
+    options.verify_frames = true;
+
+    const reader = await VGeoContainerReader.open(source, options);
+
+    const page = new VGeoPlayground();
+
+    page.reader = reader;
+    page.canvas_height = canvas.height;
+
+    page.residency = new VGeoResidencyManager();
+    page.residency.register(reader);
+
+    const scene = new Scene();
+
+    // the sun stands at an entity, and so does the torus, so the scene names a dataset
+    scene.dataset = new EntityComponentDataset();
+
+    // a light stands at an entity of the dataset now, like everything else the scene holds
+    place_light(scene, make_sunlight());
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.02;
+    camera.far = 200;
+    camera.fov = page.fov_y;
+    camera.aspect = canvas.width / canvas.height;
+
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    controller.look(new Vector3(0, 1.6, 3.6), new Vector3(0, 0, 0));
+
+    // one frame to let the renderer build its scene context, which is what owns the geometry manager
+    renderer.render(camera, scene, 1 / 60);
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const runtime = scene_context.enable_virtual_geometry({ page_size });
+
+    page.runtime = runtime;
+
+    /*
+     Only the root page is resident. Everything else arrives because the cut asked for it, which is
+     the loop this page exists to show — and it means the first frames draw a coarse, watertight
+     surface rather than nothing at all.
+     */
+    const geometry_row = runtime.pool.register(reader);
+
+    const geometry = new VirtualGeometry(reader);
+
+    geometry.vg_row = geometry_row;
+
+    const material = new StandardShadeMaterial();
+
+    material.diffuse_color.copy(new Color(0.72, 0.74, 0.78));
+    material.roughness_factor = 0.55;
+    material.metallic_factor = 0;
+
+    place_primitive(
+        scene_context, geometry, material, new Transform64(), { name: 'virtual torus' }
+    );
+
+    page.feedback = new VGeoFeedbackLoop({ runtime, residency: page.residency });
+
+    /*
+     The loop's only teardown caller anywhere, and worth having for the same reason M12's clock was:
+     `abort()` existed and nothing pulled it, so the one thing the `AbortSignal` was added for was
+     never exercised outside a spec. Nothing in the engine constructs a feedback loop yet — a scene
+     context gives you a runtime and a pool, and the host wires the loop — so this page is the whole
+     population of hosts, and it is what a real one should do on the way out.
+     */
+    globalThis.addEventListener('pagehide', () => page.feedback.destroy());
+
+    renderer.add_extension(new VGeoFrameStart(page));
+    renderer.add_extension(new VGeoFrameEnd(page));
+
+    element('tau').addEventListener('input', event => {
+        runtime.tau = Number(event.target.value);
+
+        element('tau-value').textContent = runtime.tau.toFixed(2);
+    });
+
+    globalThis.__state = () => page.state();
+    globalThis.__page = page;
+
+    status(`container built in ${build_ms.toFixed(0)} ms · ${reader.header.total_pages} pages`);
+
+    let stopped = false;
+    let last_time;
+
+    function paint() {
+        const state = page.state();
+
+        element('cut').innerHTML = [
+            ['drawn clusters', state.cut.drawn],
+            ['clamped', state.cut.clamped],
+            ['pages visited', state.cut.pages],
+            ['clusters tested', state.cut.clusters_tested],
+            ['subtrees culled', state.cut.culled_frustum + state.cut.culled_lod],
+            ['wants', state.wants],
+        ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+            .join('');
+
+        const dropped = state.cut.meshlets_dropped + state.cut.queue_dropped
+            + state.cut.instances_dropped;
+
+        element('residency').innerHTML = [
+            ['VRAM pages', `${state.vram.pages}`],
+            ['VRAM bytes', `${(state.vram.bytes / 1024).toFixed(0)} KB`],
+            ['RAM pages', `${state.ram.pages} / ${state.ram.total_pages}`],
+            ['evicted', state.vram.evicted],
+            ['dropped', `<span class="${dropped > 0 ? 'bad' : 'good'}">${dropped}</span>`],
+        ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+            .join('');
+    }
+
+    function tick(time) {
+        if (stopped) {
+            return;
+        }
+
+        const dt = last_time === undefined ? 1 / 60 : Math.min((time - last_time) / 1000, 0.05);
+
+        last_time = time;
+
+        try {
+            controller.update(dt);
+
+            renderer.render(camera, scene, dt);
+        } catch (error) {
+            stopped = true;
+
+            status(error.message ?? String(error));
+            element('status').classList.add('error');
+
+            console.error(error);
+
+            return;
+        }
+
+        paint();
+
+        requestAnimationFrame(tick);
+    }
+
+    requestAnimationFrame(tick);
+}
+
+start().catch(error => {
+    element('status').textContent = error.message ?? String(error);
+    element('status').classList.add('error');
+
+    globalThis.__state = () => ({ error: error.message ?? String(error) });
+
+    console.error(error);
+});

package/src/shade/playground/vgeo_viewer/sample_asset.js

@@ -99,7 +99,7 @@ function torus(major, minor) {
  * @param {number} [page_size] target decoded bytes per page
  * @returns {{source: VGeoByteSource, build_ms: number}}
  */
-export function vgeo_sample_source(major = 128, minor = 48, page_size = 8 * 1024) {
+export function vgeo_sample_source(major = 128, minor = 48, page_size = 16 * 1024) {
     const options = new VGeoBuildOptions();
 
     options.nominal_page_size = page_size;

package/src/shade/renderer/camera/Camera.d.ts

@@ -1,3 +1,17 @@
+/**
+ * ref: Gribb-Hartmann
+ * Updates frustum planes from a View-Projection matrix.
+ * Geared for Reverse-Z (WebGPU/DirectX range [0,1]).
+ *
+ * Exported because it is the engine's **one** answer to this question and somebody else asks it:
+ * the virtual-geometry cut extracts the same six rows from an object-space view-projection, in a
+ * shader, and shipped with the near plane's sign wrong. A spec that holds the two against each
+ * other is worth more than a second derivation with a comment saying it matches.
+ *
+ * @param {Float32Array} planes
+ * @param {Float32Array} vp ViewProjection matrix
+ */
+export function construct_frustum_planes(planes: Float32Array, vp: Float32Array): void;
 export class Camera {
     transform: Transform64;
     view_matrix: Float32Array;

package/src/shade/renderer/camera/Camera.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAiFA;IAMI,uBAA8B;IAE9B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,oBAEC;IAED,mBAEC;IAED,mBAEC;IAED,kBAEC;IAED,sBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAuDC;IAED,uBAIC;IAED,eAQC;;CACJ;4BAvR2B,8CAA8C"}
+{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AACH,iDAHW,YAAY,MACZ,YAAY,QA8DtB;AAED;IAMI,uBAA8B;IAE9B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,oBAEC;IAED,mBAEC;IAED,mBAEC;IAED,kBAEC;IAED,sBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAuDC;IAED,uBAIC;IAED,eAQC;;CACJ;4BA7R2B,8CAA8C"}

package/src/shade/renderer/camera/Camera.js

@@ -14,10 +14,16 @@ let id_counter = 0;
  * ref: Gribb-Hartmann
  * Updates frustum planes from a View-Projection matrix.
  * Geared for Reverse-Z (WebGPU/DirectX range [0,1]).
+ *
+ * Exported because it is the engine's **one** answer to this question and somebody else asks it:
+ * the virtual-geometry cut extracts the same six rows from an object-space view-projection, in a
+ * shader, and shipped with the near plane's sign wrong. A spec that holds the two against each
+ * other is worth more than a second derivation with a comment saying it matches.
+ *
  * @param {Float32Array} planes
  * @param {Float32Array} vp ViewProjection matrix
  */
-function construct_frustum_planes(planes, vp) {
+export function construct_frustum_planes(planes, vp) {
     // Left Plane (w + x)
     // Row 3 + Row 0
     plane3_normalize(

package/src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GEOMETRY_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,oDAgB8B;6BAnBD,gCAAgC"}
+{"version":3,"file":"GEOMETRY_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,oDA+B8B;6BAlCD,gCAAgC"}

package/src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js

@@ -18,5 +18,20 @@ export const GEOMETRY_METADATA_STRUCT = WebGPUStruct.from({
     meshlets_count: u32,
 
     bounding_sphere: vec4f,
-    bounding_box: WebGPUArray.from(f32, 6)
+    bounding_box: WebGPUArray.from(f32, 6),
+
+    /**
+     * Row in the virtual-geometry table, or {@link VGEO_GEOMETRY_ROW_NONE}.
+     *
+     * A VG geometry has no static meshlets — `meshlets_count` is zero, so the mesh-to-meshlet
+     * expansion contributes nothing for it by construction — and everything it draws comes from a
+     * cut selected that frame. This field is how a pass handed a list of visible instances tells
+     * the two apart, and it is the only change virtual geometry asks of the engine's record
+     * formats: the draw records, the meshlet metadata, the material buckets and the indirect draws
+     * are all unchanged.
+     *
+     * Appended rather than inserted. Every other consumer reads this struct by field name or
+     * computes an offset from it, so a field at the end costs them nothing.
+     */
+    vg_row: u32,
 }, "GeometryMetadata").pack();