@woosh/meep-engine 3.28.0 → 3.30.0

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

@@ -0,0 +1,1565 @@
+import { Color } from "../../../core/color/Color.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { GIGABYTE } from "../../../core/science/units/memory/GIGABYTE.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 { meshlet_geometry_from_bytes } from "../../renderer/geometry/meshlet_geometry_transfer.js";
+import {
+    vgeo_byte_source_over_url
+} from "../../renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.js";
+import {
+    VGeoContainerReader
+} from "../../renderer/geometry/virtual/format/read/VGeoContainerReader.js";
+import {
+    VGeoReadOptions
+} from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
+import { VGEO_CUT_STAT } from "../../renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
+import {
+    VGeoResidencyOptions
+} from "../../renderer/geometry/virtual/runtime/VGeoResidencyOptions.js";
+import { VirtualGeometry } from "../../renderer/geometry/virtual/runtime/VirtualGeometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.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";
+import { load_default_environment } from "../load_default_environment.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import {
+    CALDERA_TABLE_ROW,
+    caldera_coalesce_ranges,
+    caldera_read_geometry_table,
+    caldera_read_placements,
+} from "./caldera_format.js";
+
+/**
+ * Caldera, drawn by meep: 45 districts, millions of placements, and every triangle of it standing
+ * where Activision's map put it.
+ *
+ * [`../vgeo_scene/`](../vgeo_scene/README.md) already puts a converted scene of this order on the
+ * screen, and this is deliberately **not** that page. `vgeo_scene` asks one question — what a
+ * virtual-geometry cut costs across a whole scene — and answers it with every asset on the same
+ * backing, because the point is the cut. This page asks the opposite: what the **ordinary** engine
+ * does when a real production map is handed to it whole. So the default backing here is the plain
+ * meshlet path every game asset takes, the rows are ordinary mesh rows, and virtual geometry is a
+ * *promotion* that a few hundred of the largest geometries get — which is how a game would actually
+ * use it, and which makes the two paths comparable inside one frame instead of across two pages.
+ *
+ * ## What it is looking at
+ *
+ * Caldera is the Call of Duty: Warzone map, released by Activision as OpenUSD. Its own README calls
+ * it 17.5 million primitives and two billion points across two miles square, and it is the largest
+ * honest test of a renderer's *scene* — not of one hero asset — that is freely available.
+ * `tools/caldera/` converts it; the README beside this file has the numbers that came out.
+ *
+ * ## What it is measuring
+ *
+ * Load time first, because that is what the conversion is for. The set holds **serialized
+ * `MeshletGeometry`** — {@link MeshletGeometrySerializationAdapter}, the format whose own docblock
+ * says building meshlets at load costs 1,246 ms per 199k triangles — so opening a district is a
+ * range request, a deserialize and an upload, with no geometry processing anywhere on the path. The
+ * panel's `open` row is that claim, per district, in milliseconds.
+ *
+ * Then everything the scale breaks. Four million mesh rows is two orders of magnitude past what any
+ * meep page has asked for, and the things that give way first — a rasterization collection's limit,
+ * the geometry manager's arenas, VRAM against half a million BLAS — are exactly what a page like
+ * this exists to find. Every one of them is a counter in the panel rather than a stall you have to
+ * guess at.
+ *
+ * ## Running it
+ *
+ * The dev server in front of the page, and an asset server in front of the converted set — Vite
+ * refuses to serve a path outside the workspace, and a converted Caldera has no business inside
+ * one:
+ *
+ * ```
+ * npm run dev --workspace @woosh/meep-engine
+ * node tools/geometry/virtual/vgeo_serve.js H:/git/caldera/meep
+ * ```
+ *
+ * Then `/src/shade/playground/caldera/index.html`. `?districts=` takes what to open,
+ * `?placements=` caps how much of it, and the rest are in the README.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const element = id => document.getElementById(id);
+
+/**
+ * Where the asset server is, when the page is not told otherwise. The same default port
+ * `vgeo_serve.js` binds, because it is the same server.
+ *
+ * @type {string}
+ */
+const DEFAULT_ORIGIN = 'http://localhost:5200';
+
+/**
+ * The manifest `caldera_build.js` writes, at the asset origin's root.
+ *
+ * @type {string}
+ */
+const DEFAULT_MANIFEST = 'caldera.meep.json';
+
+/**
+ * How long a placement pass may hold the thread before it yields.
+ *
+ * Rows are created one at a time and there are millions of them, so the question is not whether to
+ * break the work up but where. A frame's worth is the wrong budget — it makes the page *smooth*
+ * while it loads and makes loading take four times as long. Four frames' worth is the compromise:
+ * the page still answers a drag, and the scene arrives at something like the rate the machine can
+ * actually build it.
+ *
+ * @type {number}
+ */
+const PLACEMENT_BUDGET_MS = 64;
+
+/**
+ * How long the deserialize loop may hold the thread before it yields.
+ *
+ * The same reasoning as {@link PLACEMENT_BUDGET_MS} and a different loop, and it was worth splitting
+ * because the range was the wrong unit: yielding once per fetched range is fine over a district of
+ * four-triangle props and starves the frame completely over the terrain, where one range is one
+ * two-million-triangle geometry and four of them are being read at once. The frame counter sitting
+ * still for minutes on the `st_*` districts is what this is for.
+ *
+ * @type {number}
+ */
+const DESERIALIZE_BUDGET_MS = 32;
+
+/**
+ * `.vgeo` containers opened at once. The same figure `vgeo_scene` settled on: enough that the
+ * round trips overlap, few enough that a browser does not queue them behind each other anyway.
+ *
+ * @type {number}
+ */
+const OPEN_CONCURRENCY = 24;
+
+/**
+ * The row count past which this set has not been held to be safe.
+ *
+ * It used to be 2²⁰, where the picture stopped being correct — and that was never a row count at
+ * all: the dispatch that broke was over *meshlets*, and 2²⁰ rows is where this scene's meshlet
+ * count crossed it. Fixed in `962e79183` / `53deaa9b5`, so a scene of any row count draws what it
+ * is given now.
+ *
+ * What is left is memory, which is the wall the README calls the second one: this set ran out of
+ * VRAM on a 24 GB card somewhere between 2.2 and 3.7 million rows, once saying so out of `render`
+ * and once by thrashing until the main thread stopped answering. 2.2 million is where it said so,
+ * so it is the last figure this page can stand behind.
+ *
+ * The page does not stop here, because stopping would hide it. It says so in the panel instead.
+ *
+ * @type {number}
+ */
+const ROWS_LAST_KNOWN_GOOD = 2_200_000;
+
+/**
+ * What a container's always-resident set costs at the median across a converted set — header, level
+ * table, root frame. Asking for this much on the first read opens the container in **one** round
+ * trip instead of the reader's default 64 KiB of over-fetch.
+ *
+ * @type {number}
+ */
+const HEAD_PREFIX_BYTES = 8 * 1024;
+
+/**
+ * @type {Record<string, ShadeDrawSide>}
+ */
+const DRAW_SIDES = Object.freeze({
+    front: ShadeDrawSide.Front,
+    back: ShadeDrawSide.Back,
+    double: ShadeDrawSide.Double,
+});
+
+
+/**
+ * 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 = "caldera/vgeo frame start";
+
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @param {CalderaPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.runtime.begin_frame({ graph: frame.graph });
+    }
+}
+
+
+/**
+ * Schedules the readback and closes the frame, after everything that could have cut has cut.
+ */
+class VGeoFrameEnd extends RenderExtension {
+    name = "caldera/vgeo frame end";
+
+    phase = FramePhase.BeforePresent;
+
+    /**
+     * @param {CalderaPlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.feedback.read(frame.graph);
+        this.page.runtime.end_frame();
+    }
+}
+
+
+class CalderaPlayground {
+
+    /** @type {Renderer} */
+    renderer;
+
+    /** @type {HTMLCanvasElement} */
+    canvas;
+
+    /** @type {Scene} */
+    scene;
+
+    /** @type {GPUSceneContext} */
+    scene_context;
+
+    /** @type {PerspectiveCamera} */
+    camera;
+
+    /** @type {OrbitalCameraController} */
+    controller;
+
+    /**
+     * The one material the whole map is drawn with.
+     *
+     * Caldera ships without materials or textures — its own README says so, and says why: the set
+     * is about the relationships between spatial elements rather than about how they look. So there
+     * is nothing to shade this with but geometry, and one material is the honest representation of
+     * that rather than a simplification this page is making.
+     *
+     * @type {StandardShadeMaterial}
+     */
+    material;
+
+    /** @type {object|undefined} */
+    manifest;
+
+    /**
+     * The geometry table, as column arrays.
+     * @type {ReturnType<typeof caldera_read_geometry_table>|undefined}
+     */
+    table;
+
+    /** @type {string} where the manifest came from; every other URL resolves against it */
+    base = '';
+
+    /**
+     * Meshlet geometries that have been deserialized, by geometry id.
+     *
+     * Held because a geometry is shared between districts — that is the whole reason the set has a
+     * geometry table rather than a scene per district — and because dropping one would drop the
+     * rows that draw it.
+     *
+     * @type {Map<number, MeshletGeometry>}
+     */
+    geometries = new Map();
+
+    /**
+     * Geometries placed on the virtual backing instead, by geometry id, with the reader kept beside
+     * each so nothing collects it out from under the residency.
+     *
+     * @type {Map<number, {geometry: VirtualGeometry, reader: VGeoContainerReader}>}
+     */
+    virtual = new Map();
+
+    /**
+     * The merged assets — one container each, holding what the source had cut into pieces.
+     *
+     * Caldera's ground arrives this way: 728 geometries placed once each on an 832 m grid, baked by
+     * `caldera_build.js --merge` into a single `.vgeo`. They are held for the same reason the other
+     * readers are, and they are placed at the identity because the baking already put every vertex
+     * in world space.
+     *
+     * @type {Array<{record: object, geometry: VirtualGeometry, reader: VGeoContainerReader}>}
+     */
+    merged = [];
+
+    /** @type {number} placements turned into rows */
+    placed = 0;
+
+    /** @type {number} how many of those were drawn from the virtual backing */
+    placed_virtual = 0;
+
+    /** @type {number} instanced triangles standing in the scene */
+    instanced_triangles = 0;
+
+    /** @type {number} distinct source triangles behind them */
+    source_triangles = 0;
+
+    /** @type {number} bytes of pack, table, placements and container heads fetched */
+    bytes_fetched = 0;
+
+    /** @type {number} geometries the set declared but this page could not open */
+    refused = 0;
+
+    /** @type {number} milliseconds from the first district's first byte to its last row */
+    open_ms = 0;
+
+    /** @type {number} */
+    frames = 0;
+
+    /** @type {number} */
+    frame_ms = 0;
+
+    /** @type {number} what the last frame cost on the CPU, which at this scale is the interesting half */
+    cpu_ms = 0;
+
+    /** @type {string} */
+    status_text = '';
+
+    /** @type {number} */
+    screen_width = 1;
+
+    /** @type {number} */
+    screen_height = 1;
+
+    /**
+     * Districts as the manifest declares them, with what this page has done about each.
+     * @type {Array<object & {state: string}>}
+     */
+    districts = [];
+
+    /**
+     * Whether the promoted geometries are drawn from their `.vgeo` rather than their meshlet blob.
+     * @type {boolean}
+     */
+    virtual_enabled = false;
+
+    /** @type {GPUVirtualGeometryRuntime|undefined} */
+    runtime;
+
+    /** @type {VGeoResidency|undefined} */
+    residency;
+
+    /** @type {GPUVirtualGeometryFeedback|undefined} */
+    feedback;
+
+    /** @type {number} half the diagonal of the whole map, which sets the far plane */
+    world_radius = 1000;
+
+    /**
+     * What the virtual-geometry tables were sized to, kept so a session can read back the numbers
+     * the page chose rather than infer them.
+     *
+     * @type {object|undefined}
+     */
+    capacities;
+
+    /**
+     * What killed the frame loop, if anything did.
+     *
+     * A scene this size runs out of somewhere — VRAM first — and the engine says so, out of
+     * `render`: *Failed to allocate GPU memory for meshlet batch*. The loop catches that and stops,
+     * and without this flag the loader carries on behind it for another twenty minutes, fetching
+     * geometry for a renderer that is never going to draw again and burying the one message that
+     * explained what happened. Whatever is on the screen when this is set is what the machine could
+     * hold, which is the reading the page exists to take.
+     *
+     * @type {Error|undefined}
+     */
+    fatal;
+
+    /**
+     * Put the camera at `eye` looking at `target`, and rescale everything that is a function of how
+     * far away it is.
+     *
+     * The near and far planes are the part that matters here: Caldera is three kilometres across and
+     * a viewer stands centimetres from a wall inside it, so a fixed pair of planes either z-fights
+     * everything close or clips everything far. Deriving them from the distance is what lets one
+     * page do both.
+     *
+     * @param {ArrayLike<number>} eye
+     * @param {ArrayLike<number>} target
+     */
+    look(eye, target) {
+        const from = new Vector3(eye[0], eye[1], eye[2]);
+        const to = new Vector3(target[0], target[1], target[2]);
+
+        const distance = Math.max(Vector3.distance(from, to), 1e-3);
+
+        this.camera.near = distance * 0.002;
+        this.camera.far = Math.max(distance * 2000, this.world_radius * 4);
+
+        this.controller.distanceLimits.min = distance * 0.01;
+        this.controller.distanceLimits.max = Math.max(distance * 2000, this.world_radius * 4);
+        this.controller.movement_speed_scale = distance;
+
+        this.controller.look(from, to);
+
+        // the pixels the camera is about to cover have no correspondence in a TAA history written
+        // from where it was standing
+        this.renderer.indicate_view_change();
+    }
+
+    /**
+     * @param {string} text
+     * @param {boolean} [error]
+     */
+    status(text, error = false) {
+        this.status_text = text;
+
+        const node = element('status');
+
+        node.textContent = text;
+        node.classList.toggle('error', error);
+    }
+
+    /**
+     * Size the canvas to the document.
+     *
+     * The **document**, not the canvas: `Renderer` writes an inline `style.width` and `style.height`
+     * every time it configures the context, so measuring the canvas measures what the renderer last
+     * decided rather than what the window now is, and the two ratchet against each other.
+     */
+    fit() {
+        const renderer = this.renderer;
+
+        const viewport = document.documentElement;
+
+        renderer.pixel_ratio = globalThis.devicePixelRatio || 1;
+
+        renderer.resize(
+            Math.max(1, Math.floor(viewport.clientWidth)),
+            Math.max(1, Math.floor(viewport.clientHeight))
+        );
+
+        this.camera.aspect = renderer.aspect_ratio;
+
+        const resolution = renderer.output_resolution;
+        const scale = renderer.internal_resolution_scale;
+
+        this.screen_width = Math.max(1, Math.floor(resolution.x * scale));
+        this.screen_height = Math.max(1, Math.floor(resolution.y * scale));
+    }
+
+    /**
+     * @param {string} path relative to the manifest
+     * @param {{start: number, end: number}} [range] inclusive-exclusive, as the table reports one
+     * @returns {Promise<ArrayBuffer>}
+     */
+    async fetch_bytes(path, range) {
+        const url = new URL(path, this.base).href;
+
+        const options = range === undefined
+            ? undefined
+            : { headers: { Range: `bytes=${range.start}-${range.end - 1}` } };
+
+        const response = await fetch(url, options);
+
+        if (!response.ok) {
+            throw new Error(`${path} answered HTTP ${response.status}`);
+        }
+
+        /*
+         A `200` where a range was asked for is a server that ignored the request and sent the head
+         of the file — plausible bytes at the wrong offset, which downstream is a meshlet geometry
+         built out of another geometry's middle. The same check `vgeo_fetch_byte_source` makes, for
+         the same reason, and it is the one thing a static server in front of this set has to get
+         right.
+        */
+        if (range !== undefined && response.status !== 206) {
+            throw new Error(
+                `${path} answered HTTP ${response.status} to a Range request — the asset server`
+                + ` must support ranges; vgeo_serve.js does`
+            );
+        }
+
+        const bytes = await response.arrayBuffer();
+
+        this.bytes_fetched += bytes.byteLength;
+
+        return bytes;
+    }
+
+    /**
+     * Open every district that was asked for, one after another, placing each as it lands.
+     *
+     * Sequential rather than concurrent, and that is the shape of the thing rather than a
+     * simplification: placing rows is main-thread work that does not overlap with itself, so
+     * fetching a second district while the first is still being placed buys nothing but memory. The
+     * fetch inside a district is concurrent, which is where the overlap actually is.
+     *
+     * @param {number} placement_budget stop once this many rows exist
+     * @returns {Promise<void>}
+     */
+    async open_districts(placement_budget) {
+        const started = performance.now();
+
+        /*
+         The merged assets first, and not because they are large — because they are the *ground*. A
+         scene that fills in district by district over four minutes reads as a map being built if
+         the terrain is under it from the first second, and as debris floating in the sea if it is
+         not.
+        */
+        await this.open_merged();
+
+        for (const district of this.districts) {
+            if (this.fatal !== undefined || this.placed >= placement_budget) {
+                district.state = 'skipped';
+
+                continue;
+            }
+
+            district.state = 'loading';
+
+            this.paint_districts();
+
+            try {
+                await this.open_district(district, placement_budget);
+
+                district.state = 'done';
+            } catch (error) {
+                district.state = 'failed';
+
+                console.warn(`${district.name} — ${error.message ?? error}`);
+            }
+
+            this.paint_districts();
+
+            this.status(
+                `${this.placed.toLocaleString()} placements`
+                + `, ${(this.geometries.size + this.virtual.size).toLocaleString()} geometries`
+                + `, ${((performance.now() - started) / 1000).toFixed(1)} s`
+            );
+        }
+
+        this.open_ms = performance.now() - started;
+    }
+
+    /**
+     * Open every merged asset the manifest names and place each at the identity.
+     *
+     * One row apiece, and that is the point of them: the ground is 24 million triangles that would
+     * otherwise be 728 containers and 728 rows, each with its own cluster DAG over a surface it
+     * shares with its neighbours. As one asset the cut sees one surface, and a coarse level may
+     * simplify across a seam that is no longer there.
+     *
+     * These have no meshlet alternative — the pieces they were baked from have no blobs of their
+     * own — so `?vgeo=off` does not apply to them, and a page that could not open one is missing
+     * its terrain rather than drawing it the other way.
+     *
+     * @returns {Promise<void>}
+     */
+    async open_merged() {
+        const records = this.manifest.merged ?? [];
+
+        if (records.length === 0 || this.runtime === undefined) {
+            return;
+        }
+
+        const options = new VGeoReadOptions();
+
+        options.verify_frames = true;
+        options.track_selectability = false;
+        options.head_prefix_bytes = HEAD_PREFIX_BYTES;
+
+        const transform = new Transform64();
+
+        for (const record of records) {
+            try {
+                const source = vgeo_byte_source_over_url(
+                    new URL(record.file, this.base).href, record.bytes
+                );
+
+                const reader = await VGeoContainerReader.open(source, options);
+
+                const geometry = new VirtualGeometry(reader);
+
+                geometry.vg_row = this.residency.register(reader);
+
+                place_primitive(this.scene_context, geometry, this.material, transform);
+
+                this.merged.push({ record, geometry, reader });
+
+                this.placed++;
+                this.placed_virtual++;
+                this.source_triangles += record.triangles;
+                this.instanced_triangles += record.triangles;
+            } catch (error) {
+                this.refused++;
+
+                console.warn(`${record.file} — ${error.message ?? error}`);
+            }
+        }
+
+        this.status(
+            `${this.merged.length} merged asset${this.merged.length === 1 ? '' : 's'}`
+            + `, ${this.merged.reduce((t, m) => t + m.record.triangles, 0).toLocaleString()} triangles`
+        );
+    }
+
+    /**
+     * @param {object} district
+     * @param {number} placement_budget
+     * @returns {Promise<void>}
+     */
+    async open_district(district, placement_budget) {
+        const placements = caldera_read_placements(await this.fetch_bytes(district.file));
+
+        /*
+         What this district needs that is not already here. A geometry shared with a district that
+         opened earlier costs nothing the second time, which is most of why the whole map fits at
+         all: the set's 3.8 million placements stand on a far smaller number of geometries, and the
+         sharing is between districts as much as inside them.
+        */
+        const wanted_meshlets = [];
+        const wanted_virtual = [];
+
+        const seen = new Set();
+
+        for (let i = 0; i < placements.count; i++) {
+            const id = placements.geometry[i];
+
+            if (seen.has(id) || this.geometries.has(id) || this.virtual.has(id)) {
+                continue;
+            }
+
+            seen.add(id);
+
+            if (this.use_virtual(id)) {
+                wanted_virtual.push(id);
+            } else {
+                wanted_meshlets.push(id);
+            }
+        }
+
+        await Promise.all([
+            this.open_virtual(wanted_virtual),
+            this.open_meshlets(wanted_meshlets),
+        ]);
+
+        await this.place(placements, placement_budget);
+    }
+
+    /**
+     * Whether this geometry is drawn from a `.vgeo` rather than from its meshlet blob.
+     *
+     * Both were built for it — `caldera_build.js` promotes by triangle count and keeps the meshlet
+     * blob anyway — so this is a runtime choice and `?vgeo=off` unmakes it without rebuilding
+     * anything. What it costs is not symmetric: the meshlet blob of a 200k-triangle geometry is
+     * fetched and uploaded whole, and the `.vgeo` of one is a 2.5 KiB head and whatever the cut
+     * asks for afterwards.
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    use_virtual(id) {
+        return this.virtual_enabled && this.table.vgeo[id] !== CALDERA_TABLE_ROW.NO_VGEO;
+    }
+
+    /**
+     * Fetch and deserialize a set of meshlet geometries.
+     *
+     * The fetch is by **coalesced range**, which is the one thing about this path that had to be
+     * designed rather than written: a district wants tens of thousands of blobs, a request each is
+     * tens of thousands of round trips, and the blobs are laid down in geometry-id order precisely
+     * so that a district's own geometry is a handful of long runs. What comes back is sliced apart
+     * here.
+     *
+     * @param {number[]} ids
+     * @returns {Promise<void>}
+     */
+    async open_meshlets(ids) {
+        if (ids.length === 0) {
+            return;
+        }
+
+        const table = this.table;
+        const packs = this.manifest.packs;
+
+        const ranges = caldera_coalesce_ranges(ids, table);
+
+        let next = 0;
+
+        const worker = async () => {
+            while (next < ranges.length && this.fatal === undefined) {
+                const range = ranges[next++];
+
+                const bytes = await this.fetch_bytes(packs[range.pack].file, range);
+
+                let deadline = performance.now() + DESERIALIZE_BUDGET_MS;
+
+                for (const id of range.ids) {
+                    const at = table.offset[id] - range.start;
+
+                    try {
+                        const geometry = meshlet_geometry_from_bytes(
+                            bytes.slice(at, at + table.bytes[id])
+                        );
+
+                        this.geometries.set(id, geometry);
+
+                        this.source_triangles += table.triangles[id];
+                    } catch (error) {
+                        this.refused++;
+
+                        console.warn(`geometry ${id} — ${error.message ?? error}`);
+                    }
+
+                    if (performance.now() >= deadline) {
+                        await new Promise(resolve => setTimeout(resolve, 0));
+
+                        deadline = performance.now() + DESERIALIZE_BUDGET_MS;
+                    }
+                }
+
+                // a pack range is tens of megabytes and the geometries out of it are already
+                // copies; yielding here is what lets the collector have it back
+                await new Promise(resolve => setTimeout(resolve, 0));
+            }
+        };
+
+        const workers = [];
+
+        for (let i = 0; i < Math.min(4, ranges.length); i++) {
+            workers.push(worker());
+        }
+
+        await Promise.all(workers);
+    }
+
+    /**
+     * Open the `.vgeo` containers for a set of geometries and register each with the one residency.
+     *
+     * @param {number[]} ids
+     * @returns {Promise<void>}
+     */
+    async open_virtual(ids) {
+        if (ids.length === 0) {
+            return;
+        }
+
+        const options = new VGeoReadOptions();
+
+        /*
+         Frame verification on. These are bytes off a network rather than bytes a tool just wrote,
+         which is the case the check exists for and the reason §10 leaves it off by default.
+        */
+        options.verify_frames = true;
+
+        // the runtime answers activation out of its arena; the reader's own counters would be
+        // megabytes at this instance count and are read by nothing
+        options.track_selectability = false;
+
+        options.head_prefix_bytes = HEAD_PREFIX_BYTES;
+
+        let next = 0;
+
+        const worker = async () => {
+            while (next < ids.length && this.fatal === undefined) {
+                const id = ids[next++];
+
+                const record = this.manifest.vgeo[this.table.vgeo[id]];
+
+                try {
+                    const source = vgeo_byte_source_over_url(
+                        new URL(record.file, this.base).href, record.bytes
+                    );
+
+                    const reader = await VGeoContainerReader.open(source, options);
+
+                    const geometry = new VirtualGeometry(reader);
+
+                    geometry.vg_row = this.residency.register(reader);
+
+                    this.virtual.set(id, { geometry, reader });
+
+                    this.source_triangles += this.table.triangles[id];
+                } catch (error) {
+                    this.refused++;
+
+                    console.warn(`${record.file} — ${error.message ?? error}`);
+                }
+            }
+        };
+
+        const workers = [];
+
+        for (let i = 0; i < Math.min(OPEN_CONCURRENCY, ids.length); i++) {
+            workers.push(worker());
+        }
+
+        await Promise.all(workers);
+    }
+
+    /**
+     * Turn placements into rows, yielding often enough that the page stays alive.
+     *
+     * A row is an entity, three components and a mesh row, and there are millions of them; this is
+     * the loop that decides whether the page loads in a minute or in five, and the only knob it has
+     * is how long it holds the thread between yields. It is also the loop that will break first
+     * when this set is scaled up, which is the point of the page.
+     *
+     * @param {{count: number, geometry: Uint32Array, matrices: Float32Array}} placements
+     * @param {number} budget stop once this many rows exist
+     * @returns {Promise<void>}
+     */
+    async place(placements, budget) {
+        const transform = new Transform64();
+
+        const table = this.table;
+
+        let deadline = performance.now() + PLACEMENT_BUDGET_MS;
+
+        for (let i = 0; i < placements.count; i++) {
+            if (this.fatal !== undefined || this.placed >= budget) {
+                return;
+            }
+
+            const id = placements.geometry[i];
+
+            const virtual = this.virtual.get(id);
+            const geometry = virtual?.geometry ?? this.geometries.get(id);
+
+            if (geometry === undefined) {
+                // a geometry that refused; its placements are holes rather than a failure
+                continue;
+            }
+
+            /*
+             The source matrix, decomposed. A transform row carries a TRS and the GPU composes the
+             world from it, so an instance carrying **shear** cannot be represented exactly and is
+             placed at the closest rigid-plus-scale fit. The engine reverses a reflected instance's
+             winding in the vertex shader off the row's own flag, so a negative determinant needs
+             nothing done to it here for the picture to be right.
+            */
+            transform.fromMatrix(placements.matrices.subarray(i * 16, i * 16 + 16));
+
+            place_primitive(this.scene_context, geometry, this.material, transform);
+
+            this.placed++;
+
+            if (virtual !== undefined) {
+                this.placed_virtual++;
+            }
+
+            this.instanced_triangles += table.triangles[id];
+
+            if (performance.now() >= deadline) {
+                await new Promise(resolve => setTimeout(resolve, 0));
+
+                deadline = performance.now() + PLACEMENT_BUDGET_MS;
+            }
+        }
+    }
+
+    paint_districts() {
+        const done = this.districts.reduce(
+            (total, district) => total + (district.state === 'done' ? district.placements : 0), 0
+        );
+
+        const declared = this.districts.reduce(
+            (total, district) => total + district.placements, 0
+        );
+
+        element('progress').firstElementChild.style.width =
+            `${declared === 0 ? 0 : Math.round(100 * done / declared)}%`;
+
+        element('districts').innerHTML = this.districts.map(district => (
+            `<div class="row ${district.state}"><span>${escape_html(district.name)}</span>`
+            + `<span>${district.state === 'done'
+                ? district.placements.toLocaleString()
+                : district.state}</span></div>`
+        )).join('');
+    }
+
+    /**
+     * Everything the panel shows and a profile capture records, in one object.
+     *
+     * @returns {object}
+     */
+    state() {
+        const stats = this.feedback?.stats;
+        const pool = this.runtime?.pool;
+
+        const limits = this.renderer.graphics.collection_limits;
+
+        return {
+            frames: this.frames,
+            frame_ms: this.frame_ms,
+            cpu_ms: this.cpu_ms,
+            status: this.status_text,
+            fatal: this.fatal === undefined ? null : (this.fatal.message ?? String(this.fatal)),
+            screen_width: this.screen_width,
+            screen_height: this.screen_height,
+            scene: {
+                source: this.manifest?.source ?? '',
+                districts: this.districts.filter(d => d.state === 'done').length,
+                districts_declared: this.districts.length,
+                placements: this.placed,
+                placements_virtual: this.placed_virtual,
+                geometries: this.geometries.size,
+                geometries_virtual: this.virtual.size + this.merged.length,
+                merged: this.merged.length,
+                merged_triangles: this.merged.reduce((t, m) => t + m.record.triangles, 0),
+                source_triangles: this.source_triangles,
+                instanced_triangles: this.instanced_triangles,
+                bytes_fetched: this.bytes_fetched,
+                refused: this.refused,
+                open_ms: this.open_ms,
+            },
+            /*
+             The **limits**, not the counts: what the rasterization collections have had to grow to
+             in order to hold what the frame handed them. At this scale that is the number worth
+             watching — a collection that stops growing while placements keep arriving is one
+             dropping the difference, and `dropped` beside it is where that shows up.
+            */
+            collections: {
+                meshes: limits.get_limit(RasterizationCollectionType.Meshes),
+                meshlets: limits.get_limit(RasterizationCollectionType.Meshlets),
+            },
+            capacities: this.capacities,
+            cut: stats === undefined ? undefined : {
+                tau: this.runtime.tau,
+                // the runtime's own, not what the page asked for — it is the one that was used
+                queue_capacity: this.runtime.queue_capacity,
+                drawn: stats[VGEO_CUT_STAT.DRAWN],
+                clamped: stats[VGEO_CUT_STAT.CLAMPED],
+                pages: stats[VGEO_CUT_STAT.PAGES],
+                clusters_tested: stats[VGEO_CUT_STAT.CLUSTERS_TESTED],
+                meshlets_dropped: stats[VGEO_CUT_STAT.MESHLETS_DROPPED],
+                instances_dropped: stats[VGEO_CUT_STAT.INSTANCES_DROPPED],
+                queue_dropped: stats[VGEO_CUT_STAT.QUEUE_DROPPED],
+                queue_remaining: stats[VGEO_CUT_STAT.QUEUE_REMAINING],
+                max_iterations: this.runtime.max_iterations,
+            },
+            vram: pool === undefined ? undefined : {
+                pages: pool.resident_page_count,
+                bytes: pool.resident_bytes,
+                capacity: pool.tables.page_capacity,
+                evicted: this.residency.evicted_vram_count,
+                refused: this.residency.refused_install_count,
+            },
+            camera: {
+                eye: Array.from(this.camera.transform.translation),
+                target: this.controller.target.toJSON(),
+                distance: this.controller.distance,
+            },
+        };
+    }
+}
+
+
+function human_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    if (bytes < 1024 * 1024 * 1024) {
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+    }
+
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GiB`;
+}
+
+
+function escape_html(text) {
+    return String(text).replace(/[&<>"]/g, c => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]
+    ));
+}
+
+
+/**
+ * How large the virtual-geometry tables have to be for the containers this set holds.
+ *
+ * These are the capacities a *scene* reaches first, and two of them degrade silently — a lookup
+ * arena too small refuses containers, and a claim arena too small drops instances. Both are
+ * functions of the set rather than of the frame, so they come off the manifest rather than out of a
+ * constant.
+ *
+ * @param {object} manifest
+ * @param {number} page_capacity
+ * @returns {{geometry_capacity: number, lookup_words: number, claim_word_capacity: number}}
+ */
+function virtual_capacities(manifest, page_capacity, requested_queue) {
+    const merged = manifest.merged ?? [];
+
+    /*
+     Both kinds, because the tables are per *container* and the residency does not care which list a
+     container came from. A merged asset is one container and a large share of the pages — Caldera's
+     ground is one of 228 and a third of them.
+    */
+    const containers = Math.max(1, (manifest.vgeo?.length ?? 0) + merged.length);
+
+    const pages = Math.max(
+        1, (manifest.vgeo_pages ?? 0) + merged.reduce((total, m) => total + (m.pages ?? 0), 0)
+    );
+
+    /*
+     Every instance of every promoted container, plus one apiece for the merged assets. The builder
+     counts them while it writes the district files, because the count is a property of the
+     placements and nothing else on either side of the conversion knows it.
+    */
+    const instances = (manifest.vgeo ?? []).reduce((total, e) => total + (e.instances ?? 0), 0)
+        + merged.length;
+
+    const queue = requested_queue > 0
+        ? requested_queue
+        : Math.min(
+            1 << 22,
+            1 << Math.ceil(Math.log2(Math.max(1 << 18, Math.max(1, instances) * 16)))
+        );
+
+    return {
+        geometry_capacity: containers + 64,
+        lookup_words: 1 << Math.ceil(Math.log2(Math.max(1 << 16, pages * 1.5))),
+        claim_word_capacity: Math.ceil(
+            Math.max(1, manifest.max_vgeo_instances ?? 1) * page_capacity / 32
+        ) * 2,
+        queue_capacity: queue,
+        instances,
+    };
+}
+
+
+/**
+ * Where the converted set is.
+ *
+ * `?scene=` names a manifest outright; otherwise the asset server's root is asked, which is the
+ * common case and saves typing a URL the server already knows.
+ *
+ * @returns {Promise<string>}
+ */
+async function resolve_manifest_url() {
+    const parameters = new URL(globalThis.location.href).searchParams;
+
+    const named = parameters.get('scene');
+
+    if (named !== null) {
+        return new URL(named, globalThis.location.href).href;
+    }
+
+    const origin = parameters.get('origin') ?? DEFAULT_ORIGIN;
+
+    return new URL(DEFAULT_MANIFEST, origin.endsWith('/') ? origin : `${origin}/`).href;
+}
+
+
+async function start() {
+    const canvas = element('view');
+
+    const page = new CalderaPlayground();
+
+    page.canvas = canvas;
+
+    const parameters = new URL(globalThis.location.href).searchParams;
+
+    page.status('reading the manifest…');
+
+    const manifest_url = await resolve_manifest_url();
+
+    const response = await fetch(manifest_url);
+
+    if (!response.ok) {
+        throw new Error(
+            `${manifest_url} answered HTTP ${response.status}`
+            + ` — is \`node tools/geometry/virtual/vgeo_serve.js <converted set>\` running?`
+        );
+    }
+
+    const manifest = await response.json();
+
+    if (manifest.format !== 1) {
+        throw new Error(
+            `${manifest_url} is a format-${manifest.format} set and this page reads format 1`
+        );
+    }
+
+    page.manifest = manifest;
+    page.base = manifest_url;
+
+    page.status('reading the geometry table…');
+
+    page.table = caldera_read_geometry_table(
+        await page.fetch_bytes(manifest.geometry_table)
+    );
+
+    if (page.table.count !== manifest.geometry_count) {
+        throw new Error(
+            `the manifest names ${manifest.geometry_count} geometries and the table holds`
+            + ` ${page.table.count}`
+        );
+    }
+
+    /*
+     Which districts, and how much of them. Both default to everything, because the whole point of
+     the page is the whole map — but a machine that cannot hold it should find out by watching a
+     counter stop rather than by waiting for a tab to die, and these are how you come back down.
+    */
+    const wanted = parameters.get('districts');
+
+    page.districts = manifest.districts
+        .filter(district => wanted === null || wanted.split(',').includes(district.name))
+        .map(district => ({ ...district, state: 'pending' }));
+
+    if (page.districts.length === 0) {
+        throw new Error(`no district matched ?districts=${wanted}`);
+    }
+
+    const placement_budget = Number(parameters.get('placements') ?? Number.POSITIVE_INFINITY);
+
+    /*
+     `?vgeo=off` moves the *promoted* geometries back onto their meshlet blobs. It cannot move the
+     merged assets, which have no blobs to move to — so the runtime is enabled whenever the set holds
+     either kind, and only the promotion is a choice.
+    */
+    page.virtual_enabled = parameters.get('vgeo') !== 'off' && (manifest.vgeo?.length ?? 0) > 0;
+
+    const has_virtual = page.virtual_enabled || (manifest.merged?.length ?? 0) > 0;
+
+    const box = manifest.world_bounds;
+
+    page.world_radius = 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+
+    const renderer = new Renderer();
+
+    page.renderer = renderer;
+
+    await renderer.initialize({
+        context: canvas.getContext('webgpu'),
+        pixelRatio: globalThis.devicePixelRatio || 1,
+    });
+
+    /*
+     TAA on, SSAO and bloom off. The jitter is what keeps a scene made almost entirely of small
+     hard-edged geometry from crawling; the other two are picture rather than geometry and this page
+     is about geometry, so they are frame time spent on the wrong question.
+    */
+    renderer.feature_taa_enabled = true;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
+
+    const scene = new Scene();
+
+    scene.dataset = new EntityComponentDataset();
+
+    page.scene = scene;
+
+    /*
+     A sun roughly overhead and from the south-west, which is where Caldera's own lighting layer
+     puts it. The set carries no lights — the conversion takes geometry and the source has no
+     materials to begin with — so which way this points decides whether half the map is in ambient.
+    */
+    place_light(scene, make_sunlight({ direction: new Vector3(0.4, -0.82, 0.41) }));
+
+    /*
+     Image-based lighting, for the geometry rather than for the picture: a sun alone puts every
+     surface facing away from it at ambient zero, and those are the silhouettes worth looking at.
+     Not awaited — `test_assets/` is gitignored, so a checkout without it gets the sun alone.
+    */
+    load_default_environment(scene);
+
+    const camera = new PerspectiveCamera();
+
+    camera.fov_degrees = 60;
+
+    page.camera = camera;
+    page.controller = new OrbitalCameraController(camera, document.body);
+
+    /*
+     The camera opens on the first district asked for rather than on the whole map. Caldera is two
+     miles across and almost all of it is terrain; framed on the world box, a viewer opens three
+     kilometres up looking at a grey lozenge, which is a true picture of the extent and tells you
+     nothing about the geometry.
+    */
+    const framed = page.districts[0];
+
+    frame_on(page, framed.placements > 0 ? framed.bounds : box);
+
+    page.fit();
+
+    globalThis.addEventListener('resize', () => page.fit());
+
+    // 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);
+
+    page.scene_context = scene_context;
+
+    if (has_virtual) {
+        enable_virtual_geometry(page, manifest, parameters);
+    }
+
+    /*
+     What the rasterization collections are primed to expect. Both grow on their own from what the
+     frame reports, so this is about the first seconds rather than the steady state — but the first
+     seconds are when the map is being placed, and a `Meshes` limit of 1e4 against four million rows
+     counts the difference as `instances_dropped` for as long as it takes to catch up.
+    */
+    const limits = renderer.graphics.collection_limits;
+
+    limits.prime(
+        RasterizationCollectionType.Meshes,
+        Math.max(1e4, Math.ceil(Math.min(manifest.placements, placement_budget) * 0.25))
+    );
+
+    limits.prime(RasterizationCollectionType.Meshlets, 1e6);
+
+    const material = new StandardShadeMaterial();
+
+    material.diffuse_color.copy(new Color(0.70, 0.69, 0.66));
+    material.roughness_factor = 0.62;
+    material.metallic_factor = 0;
+
+    /*
+     `?side=front|back|double` sets the whole map's draw side, which is the cheapest way to ask
+     whether what you are looking at is a winding problem: under `double` nothing is culled, so a
+     surface that appears there and not under `front` was being culled rather than being absent.
+    */
+    material.draw_side = DRAW_SIDES[parameters.get('side')] ?? ShadeDrawSide.Front;
+
+    page.material = material;
+
+    install_profile_hotkey({
+        renderer,
+        name: "caldera",
+        status: element('profile-status'),
+        settings: () => {
+            const state = page.state();
+
+            return [
+                state.scene.districts_declared === state.scene.districts
+                    ? `${state.scene.districts} districts`
+                    : `${state.scene.districts} of ${state.scene.districts_declared} districts`,
+                `${state.scene.placements} placements`,
+                `${state.scene.geometries + state.scene.geometries_virtual} geometries`,
+                page.virtual_enabled ? `vgeo on, τ=${state.cut?.tau}px` : 'vgeo off',
+                `${state.screen_width}×${state.screen_height}`,
+            ];
+        },
+    });
+
+    // a drag on a control in the panel is a drag on the body, and the camera controller listens there
+    element('panel').addEventListener('pointerdown', event => event.stopPropagation());
+
+    page.paint_districts();
+
+    /*
+     What a headless session reads. `__state` is the panel's own numbers, so a screenshot and a probe
+     can never disagree about what the frame did; `__look` is how a scripted tour moves.
+    */
+    globalThis.__page = page;
+    globalThis.__state = () => page.state();
+    globalThis.__look = (eye, target) => page.look(eye, target);
+
+    let stopped = false;
+    let last_time;
+
+    const tick = time => {
+        if (stopped) {
+            return;
+        }
+
+        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) {
+            stopped = true;
+
+            page.fatal = error;
+
+            page.status(
+                `${error.message ?? String(error)}`
+                + ` — stopped at ${page.placed.toLocaleString()} placements`
+                + ` and ${(page.geometries.size + page.virtual.size).toLocaleString()} geometries`,
+                true
+            );
+
+            console.error(error);
+
+            return;
+        }
+
+        page.cpu_ms += ((performance.now() - cpu_started) - page.cpu_ms) * 0.1;
+        page.frames++;
+
+        paint(page);
+
+        requestAnimationFrame(tick);
+    };
+
+    requestAnimationFrame(tick);
+
+    page.status(
+        `opening ${page.districts.length} district${page.districts.length === 1 ? '' : 's'}…`
+    );
+
+    /*
+     Awaited, unlike the frame loop above it, because there is nothing after it but the summary. The
+     scene arrives under a camera that is already drawing, which is the behaviour worth watching: a
+     district that has not landed is simply not in the frame, and the frame does not wait for it.
+    */
+    await page.open_districts(placement_budget);
+
+    if (page.fatal === undefined) {
+        page.status(
+            `${page.placed.toLocaleString()} placements`
+            + `, ${(page.geometries.size + page.virtual.size).toLocaleString()} geometries`
+            + `, ${human_bytes(page.bytes_fetched)} fetched`
+            + `, opened in ${(page.open_ms / 1000).toFixed(1)} s`
+            + (page.refused > 0 ? ` — ${page.refused} refused` : '')
+        );
+    }
+
+    globalThis.__opened = true;
+}
+
+
+/**
+ * Point the camera at a box, from far enough out to see all of it.
+ *
+ * Down and along rather than straight down: a map is read from an angle, and a plan view of one made
+ * of buildings is a picture of their roofs.
+ *
+ * @param {CalderaPlayground} page
+ * @param {number[]} box
+ */
+function frame_on(page, box) {
+    const centre = [
+        (box[0] + box[3]) / 2, (box[1] + box[4]) / 2, (box[2] + box[5]) / 2,
+    ];
+
+    const radius = Math.max(
+        10, 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2])
+    );
+
+    page.look(
+        [centre[0] + radius * 0.9, centre[1] + radius * 0.55, centre[2] + radius * 0.9],
+        centre
+    );
+}
+
+
+/**
+ * Turn on virtual geometry for the containers the set promoted, and size its tables for them.
+ *
+ * @param {CalderaPlayground} page
+ * @param {object} manifest
+ * @param {URLSearchParams} parameters
+ */
+function enable_virtual_geometry(page, manifest, parameters) {
+    const page_capacity = Number(parameters.get('pages') ?? 16384);
+
+    const capacities = virtual_capacities(
+        manifest, page_capacity, Number(parameters.get('queue') ?? 0)
+    );
+
+    page.capacities = capacities;
+
+    const residency = new VGeoResidencyOptions();
+
+    residency.ram_budget_bytes = 2 * GIGABYTE;
+
+    /*
+     VRAM is a strict subset of RAM, so the RAM tier has to hold the whole VRAM tier and every
+     container's pinned root besides.
+    */
+    residency.ram_slot_capacity = Math.max(
+        1 << 14,
+        (page_capacity + (manifest.vgeo?.length ?? 0) + (manifest.merged?.length ?? 0)) * 2
+    );
+
+    residency.max_fetches_per_reading = 64;
+    residency.max_concurrent_fetches = 24;
+    residency.max_promotions_per_reading = 128;
+
+    page.runtime = page.scene_context.enable_virtual_geometry({
+        page_size: manifest.vgeo_page_size ?? manifest.merged?.[0]?.page_size,
+        table_options: {
+            page_capacity,
+            geometry_capacity: capacities.geometry_capacity,
+            lookup_words: capacities.lookup_words,
+        },
+        claim_word_capacity: capacities.claim_word_capacity,
+        want_capacity: 8192,
+        /*
+         Traversal items one wavefront may hold, over the engine's 1 << 16. This is the capacity a
+         scene reaches first and its overflow is invisible without looking: the frontier is simply
+         thrown away, and what you see is the drawn cluster count wandering between frames as
+         different subtrees lose the race.
+
+         It is derived from the instance count rather than fixed, because the descent is seeded with
+         one item per visible virtual instance and that number is a property of the *set*: at the
+         default 20,000-triangle promotion Caldera has 12,147 virtual instances, and at 4,096 it has
+         172,764. A constant that is ample for one is a fourteenth of the other. Zorah settled at
+         1 << 18 for 17,424 instances, which is where the factor of sixteen comes from.
+        */
+        queue_capacity: capacities.queue_capacity,
+        residency,
+    });
+
+    page.residency = page.scene_context.virtual_geometry_residency;
+    page.feedback = page.scene_context.virtual_geometry_feedback;
+
+    globalThis.addEventListener('pagehide', () => page.feedback.destroy());
+
+    page.renderer.add_extension(new VGeoFrameStart(page));
+    page.renderer.add_extension(new VGeoFrameEnd(page));
+
+    const tau = element('tau');
+
+    tau.addEventListener('input', event => {
+        page.runtime.tau = Number(event.target.value);
+
+        element('tau-value').textContent = page.runtime.tau.toFixed(2);
+    });
+
+    const requested = Number(parameters.get('tau'));
+
+    if (Number.isFinite(requested) && requested > 0) {
+        page.runtime.tau = requested;
+
+        tau.value = String(requested);
+        element('tau-value').textContent = requested.toFixed(2);
+    }
+}
+
+
+/**
+ * @type {number}
+ */
+let painted_at = 0;
+
+
+/**
+ * @param {CalderaPlayground} page
+ */
+function paint(page) {
+    const now = performance.now();
+
+    // the panel is DOM and the scene is four million rows; repainting it every frame is a
+    // measurable share of a frame that this page is trying to measure
+    if (now - painted_at < 250) {
+        return;
+    }
+
+    painted_at = now;
+
+    const state = page.state();
+    const scene = state.scene;
+
+    set('s-districts', `${scene.districts} / ${scene.districts_declared}`);
+    set(
+        's-placements',
+        scene.placements.toLocaleString()
+        + (scene.placements > ROWS_LAST_KNOWN_GOOD ? '  ⚠ past measured VRAM' : ''),
+        scene.placements > ROWS_LAST_KNOWN_GOOD ? 'bad' : ''
+    );
+    set('s-geometries', scene.geometries_virtual > 0
+        ? `${scene.geometries.toLocaleString()} + ${scene.geometries_virtual.toLocaleString()} vg`
+        : scene.geometries.toLocaleString());
+    set('s-source', scene.source_triangles.toLocaleString());
+    set('s-instanced', scene.instanced_triangles.toLocaleString());
+    set('s-fetched', human_bytes(scene.bytes_fetched));
+    set('s-open', scene.open_ms > 0 ? `${(scene.open_ms / 1000).toFixed(1)} s` : '—');
+
+    set('f-frame', `${state.frame_ms.toFixed(1)} ms`);
+    set('f-cpu', `${state.cpu_ms.toFixed(1)} ms`);
+    set('f-resolution', `${state.screen_width}×${state.screen_height}`);
+    set('f-meshes', state.collections.meshes.toLocaleString());
+    set('f-meshlets', state.collections.meshlets.toLocaleString());
+
+    /*
+     Virtual geometry's drops only — the ordinary meshlet path publishes none, which is exactly why
+     the 2^20 failure above was invisible. A zero here is not a statement that the frame is complete.
+
+     `queue_dropped` is in the sum because it is the one that degrades *quietly*: an overflowed
+     frontier is thrown away rather than refused, and what you see is the drawn cluster count
+     wandering between frames as different subtrees lose the race. It reads as instability in the
+     cut rather than as a capacity that was too small.
+    */
+    const dropped = (state.cut?.instances_dropped ?? 0)
+        + (state.cut?.meshlets_dropped ?? 0)
+        + (state.cut?.queue_dropped ?? 0);
+
+    set('f-dropped', dropped.toLocaleString(), dropped > 0 ? 'bad' : 'good');
+
+    if (state.cut === undefined) {
+        set('v-containers', 'off', 'muted');
+
+        return;
+    }
+
+    set('v-containers', scene.merged > 0
+        ? `${scene.geometries_virtual.toLocaleString()} (${scene.merged} merged)`
+        : scene.geometries_virtual.toLocaleString());
+    set('v-instances', scene.placements_virtual.toLocaleString());
+    set('v-drawn', state.cut.drawn.toLocaleString());
+    set('v-pages', `${state.vram.pages.toLocaleString()} / ${state.vram.capacity.toLocaleString()}`);
+
+    const strained = state.vram.refused + state.cut.clamped;
+
+    set('v-refused', `${state.vram.refused.toLocaleString()} / ${state.cut.clamped.toLocaleString()}`,
+        strained > 0 ? 'warn' : 'good');
+}
+
+
+/**
+ * @param {string} id
+ * @param {string} text
+ * @param {string} [tone]
+ */
+function set(id, text, tone) {
+    const node = element(id);
+
+    node.textContent = text;
+    node.className = tone ?? '';
+}
+
+
+start().catch(error => {
+    console.error(error);
+
+    const node = element('status');
+
+    node.textContent = error.message ?? String(error);
+    node.classList.add('error');
+});