@woosh/meep-engine 3.27.0 → 3.28.0

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

@@ -0,0 +1,1716 @@
+import { Color } from "../../../core/color/Color.js";
+import { m4_linear_determinant } from "../../../core/geom/3d/mat4/m4_linear_determinant.js";
+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 { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.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";
+
+/**
+ * A **whole converted scene** of virtual geometry: thousands of containers, tens of thousands of
+ * instances, one cut.
+ *
+ * `playground/vgeo_runtime/` draws one `.vgeo` and is the page that proves the engine seam. This is
+ * the other question that seam raises and it cannot answer: a container placed once by a page that
+ * frames the camera on its own bounding sphere is a *viewer*, and design §1's claim is about a
+ * **scene** — that rendering cost is a function of the threshold and the resolution rather than of
+ * the source, across every asset in view at once, with instances sharing pages and one residency
+ * budget deciding between all of them.
+ *
+ * So everything here that is not in the runtime page is about breadth rather than depth:
+ *
+ * - **One residency, N containers.** Every asset registers with the same `VGeoResidency`, whose
+ *   budgets are scene-wide by construction — the RAM tier's bytes and the VRAM tier's slots are
+ *   counted across every reader, and a page evicted from one asset is room for another's. That is
+ *   the thing a single-asset page cannot show, because with one reader there is nothing to
+ *   arbitrate between.
+ * - **One cut, N instances.** `shader_vgeo_cut_collect` runs over the visible mesh rows and emits
+ *   one instance record per virtual one; the descent is seeded with one item per instance and every
+ *   cull and error test downstream runs in that instance's own object space. Seventeen thousand
+ *   instances are seventeen thousand seeds of one wavefront, not seventeen thousand cuts.
+ * - **Instances share the asset.** A geometry placed by four hundred nodes is one reader, one
+ *   geometry row, one page lookup and one set of resident pages. That is what `VirtualGeometry`'s
+ *   `equals` is for, and it is most of why this is affordable at all.
+ *
+ * What it takes as input is a **scene manifest** — `tools/geometry/virtual/vgeo_scene.js` writes
+ * one out of a builder manifest — naming each container and the matrices it is placed at. The
+ * containers are served by ranges: nothing is downloaded, each is opened out of its own head.
+ *
+ * `__state()` is the whole surface a headless session needs, and the panel shows nothing it does
+ * not.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const element = id => document.getElementById(id);
+
+/**
+ * Where the containers are served from when the page is opened without a `?scene=`.
+ *
+ * `tools/geometry/virtual/vgeo_serve.js` binds this by default and answers `/scenes.json` with what
+ * it holds, so a page with no parameters finds the scene that is there rather than asking for a URL
+ * to be pasted. It is a *separate* origin on purpose: vite refuses `/@fs/` outside the workspace,
+ * and a forty-gigabyte directory has no business inside one.
+ *
+ * @type {string}
+ */
+const DEFAULT_ORIGIN = 'http://localhost:5200';
+
+/**
+ * Head bytes read on the first request of every container.
+ *
+ * §10's always-resident set is the header, the level table and the root frame, contiguous and in
+ * that order, and a reader that guesses short pays a second round trip to grow. The default is
+ * 64 KB, which is right for a page that opens one container and wasteful for one that opens three
+ * thousand: measured across Zorah's 2,966, the resident head is 2,560 bytes at the median and
+ * 6,528 at the very worst, so 8 KB opens **every** container in the set in exactly one range
+ * request and reads 7.4 MB in total rather than 190 MB.
+ *
+ * A container whose head is larger than this is not refused — `#grow_head` fetches the rest — so
+ * the number is a throughput choice and not a limit.
+ *
+ * @type {number}
+ */
+const HEAD_PREFIX_BYTES = 8 * 1024;
+
+/**
+ * Containers being opened at once.
+ *
+ * A cold scene is one range request per container and they are independent, so the only thing this
+ * trades is head-of-line latency against the browser's own per-origin connection pool. Beyond about
+ * the pool's width the requests queue in the browser instead of on the wire and the number stops
+ * meaning anything.
+ *
+ * @type {number}
+ */
+const OPEN_CONCURRENCY = 24;
+
+/**
+ * What `?side=` accepts, for a session asking whether a surface is missing or merely culled.
+ *
+ * @type {Readonly<Record<string, number>>}
+ */
+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 = "vgeo/frame start";
+
+    phase = FramePhase.FrameStart;
+
+    /**
+     * @param {VGeoScenePlayground} 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 = "vgeo/frame end";
+
+    phase = FramePhase.BeforePresent;
+
+    /**
+     * @param {VGeoScenePlayground} page
+     */
+    constructor(page) {
+        super();
+
+        this.page = page;
+    }
+
+    record(frame) {
+        this.page.feedback.read(frame.graph);
+
+        this.page.runtime.end_frame();
+
+        this.page.frames++;
+    }
+}
+
+class VGeoScenePlayground {
+    /**
+     * @type {Renderer}
+     */
+    renderer;
+
+    /**
+     * @type {HTMLCanvasElement}
+     */
+    canvas;
+
+    /**
+     * @type {Scene}
+     */
+    scene;
+
+    /**
+     * @type {GPUSceneContext}
+     */
+    scene_context;
+
+    /**
+     * @type {PerspectiveCamera}
+     */
+    camera;
+
+    /**
+     * @type {OrbitalCameraController}
+     */
+    controller;
+
+    /**
+     * The one material the whole scene is drawn with.
+     *
+     * Not a simplification this page is making: a `.vgeo` carries **geometry only** — design §7 —
+     * so a converted set has no material data in it at all, and the source's 2,714 materials did
+     * not survive the conversion because nothing asked them to. Giving each container a tinted
+     * material of its own would read better and would be a lie about where the colour came from,
+     * and it would also put 2,714 material buckets in front of the draw path to say it with.
+     *
+     * @type {StandardShadeMaterial}
+     */
+    material;
+
+    /**
+     * What a **reflected** instance is drawn with — one whose transform has a negative determinant,
+     * which in Zorah is 2,722 of 17,424.
+     *
+     * By default this is {@link material}, and the scene is one bucket. `?mirrored=` splits it, and
+     * the split is the only way to ask the question at all: a reflection reverses the screen-space
+     * winding of every triangle of the instance, `cullMode` is pipeline state chosen per material
+     * bucket, and nothing between `construct_primitive_state` and the rasterizer sees a transform.
+     * So the sign of the determinant cannot reach the cull unless the instance is put in a
+     * different bucket, and putting it in one is both the diagnosis and, for a page, the fix.
+     *
+     * @type {StandardShadeMaterial}
+     */
+    mirror_material;
+
+    /**
+     * Instances placed with a negative-determinant transform.
+     * @type {number}
+     */
+    mirrored = 0;
+
+    /**
+     * The scene manifest as loaded, or `undefined` before it arrives.
+     * @type {object|undefined}
+     */
+    manifest;
+
+    /**
+     * Where the manifest was loaded from, which every container's URL is resolved against.
+     * @type {string}
+     */
+    base = '';
+
+    /**
+     * One entry per container that opened, held so nothing collects the reader out from under the
+     * residency and so a session can be told what is in the scene.
+     * @type {Array<{reader: VGeoContainerReader, geometry: VirtualGeometry, file: string, instances: number}>}
+     */
+    assets = [];
+
+    /**
+     * @type {GPUVirtualGeometryRuntime}
+     */
+    runtime;
+
+    /**
+     * @type {VGeoFeedbackLoop}
+     */
+    feedback;
+
+    /**
+     * @type {VGeoResidency}
+     */
+    residency;
+
+    /**
+     * @type {number}
+     */
+    frames = 0;
+
+    /**
+     * Containers opened, refused, and how many the manifest names.
+     * @type {number}
+     */
+    opened = 0;
+
+    /**
+     * @type {number}
+     */
+    refused = 0;
+
+    /**
+     * @type {number}
+     */
+    placed = 0;
+
+    /**
+     * @type {number}
+     */
+    total_containers = 0;
+
+    /**
+     * Wall-clock milliseconds the whole scene took to open, or 0 while it is still opening.
+     * @type {number}
+     */
+    open_ms = 0;
+
+    /**
+     * @type {number}
+     */
+    screen_height = 1;
+
+    /**
+     * @type {number}
+     */
+    screen_width = 1;
+
+    /**
+     * Frame time, exponentially smoothed — a scene page's one reading that is a cost rather than a
+     * count, and coarse enough to be honest about being one. A capture is what measures.
+     * @type {number}
+     */
+    frame_ms = 0;
+
+    /**
+     * @type {string}
+     */
+    status_text = '';
+
+    /**
+     * The dropout catcher, when `?catch=` armed one.
+     * @type {FlickerCatcher|undefined}
+     */
+    catcher;
+
+    /**
+     * Named viewpoints, so a session that cannot drag has somewhere to stand and a reader of the
+     * panel can get back to a reading. Seeded from the manifest's own camera.
+     * @type {Array<{name: string, eye: number[], target: number[]}>}
+     */
+    viewpoints = [];
+
+    /**
+     * @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);
+    }
+
+    /**
+     * Bring the canvas, the renderer and the camera up to the size the window actually is.
+     *
+     * **Measured from the document, never from the canvas.** `Renderer` writes back both of the
+     * canvas's sizes when it configures the context, including an *inline* `style.width` in CSS
+     * pixels — so a `fit` that read `clientWidth` back would be reading the renderer its own last
+     * answer and the canvas would never change size again.
+     *
+     * The cut's screen height and field of view follow from the renderer rather than from the
+     * window because τ is a count of **render-target** pixels: `GPUViewCut.set_projection` takes
+     * them off the view every frame, so nothing here has to push them.
+     */
+    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));
+    }
+
+    /**
+     * Open every container the manifest names and place its instances, as each one lands.
+     *
+     * **Placed as they arrive rather than at the end**, and that is the whole difference between a
+     * page you can look at in a second and one you wait a minute for. It costs nothing: a geometry
+     * that is not registered yet is a geometry the cut does not collect, and the residency's budgets
+     * are recomputed per reading rather than at registration, so a scene that grows under the camera
+     * is the case both tiers were designed for.
+     *
+     * A container that refuses — the wrong page size, a tier with no room for another root — leaves
+     * every other asset exactly as it was and is counted. Refusing one container out of three
+     * thousand is a hole in the scene, and a hole is what the count is for.
+     *
+     * @param {object} manifest
+     * @returns {Promise<void>}
+     */
+    async open_scene(manifest) {
+        const geometries = manifest.geometries;
+
+        this.total_containers = geometries.length;
+
+        const options = new VGeoReadOptions();
+
+        /*
+         Frame verification on, for the same reason the runtime page has it on: these are bytes off
+         a network rather than bytes a tool just wrote, and §10 leaves it off by default precisely
+         because a builder reading back its own output is not defending against one.
+        */
+        options.verify_frames = true;
+
+        // the runtime answers activation out of the arena; the reader's own counters would be
+        // tens of megabytes at seventeen thousand pages, read by nothing
+        options.track_selectability = false;
+
+        options.head_prefix_bytes = HEAD_PREFIX_BYTES;
+
+        const started = performance.now();
+
+        let next = 0;
+
+        const worker = async () => {
+            while (next < geometries.length) {
+                const record = geometries[next++];
+
+                await this.open_one(record, options);
+            }
+        };
+
+        const workers = [];
+
+        for (let i = 0; i < Math.min(OPEN_CONCURRENCY, geometries.length); i++) {
+            workers.push(worker());
+        }
+
+        await Promise.all(workers);
+
+        this.open_ms = performance.now() - started;
+
+        this.status(
+            `${this.opened.toLocaleString()} containers`
+            + `, ${this.placed.toLocaleString()} instances`
+            + `, opened in ${(this.open_ms / 1000).toFixed(1)} s`
+            + (this.refused > 0 ? ` — ${this.refused} refused` : '')
+        );
+    }
+
+    /**
+     * @param {object} record one manifest geometry
+     * @param {VGeoReadOptions} options
+     * @returns {Promise<void>}
+     */
+    async open_one(record, options) {
+        const url = new URL(record.file, this.base).href;
+
+        try {
+            /*
+             The length comes from the manifest rather than from a `HEAD`. `vgeo_fetch_byte_source`
+             probes for it because a URL is usually all a caller has; here the builder wrote it down
+             beside the file name, and taking it saves 2,966 round trips that would tell this page
+             something it was already holding.
+            */
+            const source = vgeo_byte_source_over_url(url, record.bytes);
+
+            const reader = await VGeoContainerReader.open(source, options);
+
+            /*
+             Only the root page is resident. Everything below it arrives because the cut asked for
+             it, which at this scale is the whole point: the manifest names 46.7 GiB of geometry and
+             what is fetched is what a threshold in pixels selected out of it.
+            */
+            const geometry_row = this.residency.register(reader);
+
+            const geometry = new VirtualGeometry(reader);
+
+            geometry.vg_row = geometry_row;
+
+            const matrices = record.instances;
+
+            const transform = new Transform64();
+
+            for (let i = 0; i < matrices.length; i += 16) {
+                /*
+                 The source matrix, decomposed. A transform row carries a TRS — 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 instead. 391 of Zorah's 17,424 have
+                 any, and the worst is about eleven degrees off orthogonal; the other 17,033 are
+                 exact. That is a property of the engine's transform model rather than of this page,
+                 and it is worth knowing when a wall looks subtly wrong.
+                */
+                const matrix = matrices.slice(i, i + 16);
+
+                transform.fromMatrix(matrix);
+
+                /*
+                 The engine reverses a reflected instance's winding in the vertex shader, off the
+                 row's own `NODE3D_GLOBAL_FLAG_MIRRORED`, so nothing here has to be done for the
+                 picture to be right. Splitting the bucket is what `?mirrored=` is for: a
+                 diagnostic that can tint the reflected half, or reproduce the old bug by reversing
+                 it a second time. See the README.
+                */
+                const reflected = m4_linear_determinant(matrix) < 0;
+
+                if (reflected) {
+                    this.mirrored++;
+                }
+
+                place_primitive(
+                    this.scene_context, geometry,
+                    reflected ? this.mirror_material : this.material,
+                    transform
+                );
+
+                this.placed++;
+            }
+
+            this.assets.push({
+                reader,
+                geometry,
+                file: record.file,
+                instances: matrices.length / 16,
+            });
+
+            this.opened++;
+        } catch (error) {
+            this.refused++;
+
+            // one line per refusal rather than a thrown scene: 2,965 of 2,966 is a scene
+            console.warn(`${record.file} — ${error.message ?? error}`);
+        }
+    }
+
+    /**
+     * Stand the camera somewhere, in world units.
+     *
+     * Everything with a length in it is taken from the distance between the two points rather than
+     * from the scene's extent, which is the difference between a camera that works in a town and
+     * one that works in a hundred-kilometre bounding box: a near plane derived from Zorah's world
+     * radius is fifty metres, and fifty metres puts every building the viewer is standing in behind
+     * it.
+     *
+     * @param {number[]} eye
+     * @param {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();
+    }
+
+    /**
+     * Half the diagonal of every instance's world box, which is the only length the manifest offers
+     * that is about the scene rather than about a viewpoint.
+     * @type {number}
+     */
+    world_radius = 1;
+
+    /**
+     * Everything a headless session needs, and everything the panel shows.
+     *
+     * @returns {object}
+     */
+    state() {
+        const stats = this.feedback.stats;
+        const pool = this.runtime.pool;
+
+        let bytes_read = this.residency.fetcher.worker_bytes_read;
+
+        for (const asset of this.assets) {
+            bytes_read += asset.reader.source.bytes_read;
+        }
+
+        return {
+            frames: this.frames,
+            frame_ms: this.frame_ms,
+            tau: this.runtime.tau,
+            status: this.status_text,
+            screen_width: this.screen_width,
+            screen_height: this.screen_height,
+            feedback_reads: this.feedback.read_count,
+            feedback_skipped: this.feedback.skipped_frames,
+            camera: {
+                eye: Array.from(this.camera.transform.translation),
+                target: this.controller.target.toJSON(),
+                distance: this.controller.distance,
+            },
+            scene: {
+                name: this.manifest?.source ?? '',
+                containers: this.opened,
+                declared: this.total_containers,
+                refused: this.refused,
+                instances: this.placed,
+                mirrored: this.mirrored,
+                faces: this.manifest === undefined ? 0 : scene_faces(this.manifest),
+                bytes: this.manifest?.total_bytes ?? 0,
+                bytes_read,
+                pages: this.manifest?.total_pages ?? 0,
+                open_ms: this.open_ms,
+            },
+            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_cluster: stats[VGEO_CUT_STAT.CULLED_CLUSTER],
+                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],
+                /*
+                 The bound beside the use of it, because one is meaningless without the other: eight
+                 wavefronts is a drained descent under a bound of 32 and a truncated one under a
+                 bound of 8, and the panel could not tell them apart while it showed only the count.
+                */
+                max_iterations: this.runtime.max_iterations,
+                iteration_escalations: this.runtime.iteration_escalations,
+            },
+            wants: this.feedback.last_want_count,
+            touches: this.feedback.last_touch_count,
+            vram: {
+                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,
+            },
+            ram: {
+                pages: this.residency.ram_page_count,
+                bytes: this.residency.ram_resident_bytes,
+                evicted: this.residency.evicted_ram_count,
+                refused: this.residency.refused_fetch_count,
+            },
+            fetches_in_flight: this.residency.fetches_in_flight,
+            worker_fetches: this.residency.fetcher.worker_fetch_count,
+            in_process_fetches: this.residency.fetcher.in_process_fetch_count,
+            deferred: this.residency.deferred_want_count,
+        };
+    }
+}
+
+/**
+ * Catches a frame that is **not like its neighbours** and keeps it.
+ *
+ * A cut re-selected every frame has a shimmer floor set by TAA (see the README), and that is a
+ * property of the content. A *dropout* — a single frame missing a large part of what the frames
+ * either side of it drew — is not, and the two are nothing alike to measure even though both read
+ * as "flicker": the first moves a tenth of a per cent of the pixels, the second moves tens of per
+ * cent. This looks only for the second.
+ *
+ * **It has to sample the canvas, not the counters.** `__state()`'s cut statistics come from the
+ * feedback readback, which is capped at two in flight and is skipped on more than half the frames —
+ * so on any given frame `drawn` is a reading from one to three frames ago, and a one-frame
+ * disappearance need never appear in it at all. The pixels are the only per-frame truth available,
+ * and `drawImage` into a 2D canvas is the only way to get at them: the swap chain is not
+ * `preserveDrawingBuffer`, so `getImageData` cannot reach it.
+ *
+ * A frame is judged against the **median of its two neighbours on each side** rather than against a
+ * running average, because the thing being looked for is one frame wide and a mean that includes it
+ * hides it. That costs a two-frame delay before a verdict, which is why the full-resolution ring
+ * below is five deep: by the time a frame is convicted it is two frames old, and it still has to be
+ * there to be looked at.
+ */
+class FlickerCatcher {
+    /**
+     * @param {HTMLCanvasElement} canvas the page's own, which is read and never written
+     * @param {number} threshold relative departure from the neighbours that counts, e.g. 0.15
+     * @param {boolean} freeze whether to stop on the first one and put it on screen
+     * @param {function(): string} describe answers a link that reopens the page where the camera
+     *     stands — held per event, because where it happened is the one thing a report of one
+     *     cannot be reconstructed without and the camera may have moved by the time it is read
+     */
+    constructor(canvas, threshold, freeze, describe) {
+        this.source = canvas;
+        this.threshold = threshold;
+        this.freeze = freeze;
+        this.describe = describe;
+
+        this.width = 128;
+        this.height = 72;
+
+        this.scratch = document.createElement('canvas');
+        this.scratch.width = this.width;
+        this.scratch.height = this.height;
+
+        this.context = this.scratch.getContext('2d', { willReadFrequently: true });
+
+        /** Full-resolution frames, so a convicted one can be looked at rather than only counted. */
+        this.ring = [];
+
+        for (let i = 0; i < 5; i++) {
+            const frame = document.createElement('canvas');
+
+            this.ring.push({ canvas: frame, context: frame.getContext('2d'), frame: -1, mean: 0 });
+        }
+
+        this.at = 0;
+        this.recent = [];
+        this.rows = [];
+
+        this.frames = 0;
+        this.events = [];
+        this.worst = 0;
+        this.frozen = false;
+
+        /**
+         * Frames the scene has to have been drawing for before anything is judged.
+         *
+         * The first lit frame departs from the black ones before it by 103%, which is a real
+         * observation about a page that has just started and nothing at all about a dropout. Five
+         * is enough to clear it and short enough that arming is not something you wait for.
+         * @type {number}
+         */
+        this.armed_after = 5;
+
+        this.drawing = 0;
+    }
+
+    /**
+     * One frame. Called after the render, from the page's own loop.
+     *
+     * @param {object} state what {@link VGeoScenePlayground.state} answered this frame
+     */
+    sample(state) {
+        if (this.frozen) {
+            return;
+        }
+
+        const source = this.source;
+
+        /*
+         The full-resolution copy is the expensive half — a whole-canvas `drawImage` every frame,
+         measured at rather more than the 128x72 read below — and it buys exactly one thing: a frame
+         that can be looked at after the fact. A run that is only counting does not need it, and
+         paying for it would slow the page enough to change the timing of whatever is being hunted.
+        */
+        if (this.freeze) {
+            const slot = this.ring[this.at % this.ring.length];
+
+            if (slot.canvas.width !== source.width || slot.canvas.height !== source.height) {
+                slot.canvas.width = source.width;
+                slot.canvas.height = source.height;
+            }
+
+            slot.context.drawImage(source, 0, 0);
+            slot.frame = state.frames;
+
+            this.at++;
+        }
+
+        this.context.drawImage(source, 0, 0, this.width, this.height);
+
+        const pixels = this.context.getImageData(0, 0, this.width, this.height).data;
+
+        let sum = 0;
+
+        for (let i = 0; i < pixels.length; i += 4) {
+            sum += 0.2126 * pixels[i] + 0.7152 * pixels[i + 1] + 0.0722 * pixels[i + 2];
+        }
+
+        const mean = sum / (this.width * this.height);
+
+        this.frames++;
+
+        if (state.cut.drawn > 0) {
+            this.drawing++;
+        }
+
+        this.rows.push([
+            state.frames, Math.round(mean * 100) / 100, state.cut.drawn, state.cut.clamped,
+            state.cut.queue_remaining, state.cut.meshlets_dropped, state.cut.instances_dropped,
+            state.cut.wavefronts, state.vram.pages, state.vram.refused, state.vram.evicted,
+        ]);
+
+        if (this.rows.length > 4096) {
+            this.rows.shift();
+        }
+
+        this.recent.push(mean);
+
+        if (this.recent.length > 5) {
+            this.recent.shift();
+        }
+
+        if (this.recent.length < 5 || this.drawing < this.armed_after) {
+            return;
+        }
+
+        const middle = this.recent[2];
+
+        /*
+         **Both sides, same direction, and the smaller of the two departures.** Judging the middle
+         against the median of all four neighbours looks right and is not: when the picture takes a
+         persistent *step* — the scene streaming in, a coarse level replaced by a fine one — two of
+         the four neighbours sit on the far side of it, the median lands between the two levels, and
+         the frame *before* the step is convicted for being where it always was. Every one of
+         fourteen close-range poses "caught" one that way, and not one of them was a dropout.
+
+         A frame that is genuinely alone is above (or below) the pair before it *and* the pair after
+         it. Taking the smaller of the two departures is what makes a step score zero: on a step one
+         of the two is ~0 by construction, whichever side the middle belongs to.
+        */
+        const before = (this.recent[0] + this.recent[1]) / 2;
+        const after = (this.recent[3] + this.recent[4]) / 2;
+
+        const from_before = (middle - before) / Math.max(before, 1e-6);
+        const from_after = (middle - after) / Math.max(after, 1e-6);
+
+        const departure = Math.sign(from_before) === Math.sign(from_after)
+            ? Math.min(Math.abs(from_before), Math.abs(from_after))
+            : 0;
+
+        const local = (before + after) / 2;
+
+        this.worst = Math.max(this.worst, departure);
+
+        if (departure < this.threshold) {
+            return;
+        }
+
+        const convicted = this.rows[this.rows.length - 3];
+
+        this.events.push({
+            frame: convicted[0],
+            departure: Math.round(departure * 10000) / 10000,
+            mean: Math.round(middle * 100) / 100,
+            neighbours: Math.round(local * 100) / 100,
+            url: this.describe(),
+            rows: this.rows.slice(Math.max(0, this.rows.length - 5)),
+        });
+
+        if (this.freeze) {
+            this.show(convicted[0]);
+        }
+    }
+
+    /**
+     * @returns {boolean} whether a frame that was caught can still be put on screen
+     */
+    get holds_frames() {
+        return this.freeze;
+    }
+
+    /**
+     * Put one of the held frames on screen and stop sampling, so what is on the page is that frame
+     * and a screenshot of the page is a screenshot of it.
+     *
+     * @param {number} frame
+     * @returns {string}
+     */
+    show(frame) {
+        const slot = this.ring.find(entry => entry.frame === frame);
+
+        if (slot === undefined) {
+            return `frame ${frame} is no longer held; the ring has `
+                + this.ring.map(entry => entry.frame).join(', ');
+        }
+
+        this.frozen = true;
+
+        for (const entry of this.ring) {
+            entry.canvas.remove();
+        }
+
+        /*
+         **Under the panel, not over it.** At a z-index above it the held frame covered the readings
+         that explain it and the camera-link button that says where it happened — which is the one
+         moment both are wanted. The panel is at 10.
+        */
+        slot.canvas.style.cssText = 'position:absolute;top:0;left:0;z-index:5;'
+            + `width:${this.source.style.width};height:${this.source.style.height}`;
+
+        document.body.append(slot.canvas);
+
+        return `frozen on frame ${frame}`;
+    }
+
+    /**
+     * @returns {object}
+     */
+    report() {
+        return {
+            frames: this.frames,
+            threshold: this.threshold,
+            worst: Math.round(this.worst * 10000) / 10000,
+            events: this.events.length,
+            frozen: this.frozen,
+            held: this.ring.map(entry => entry.frame).filter(frame => frame >= 0),
+            last: this.events[this.events.length - 1],
+        };
+    }
+}
+
+/**
+ * @param {object} manifest
+ * @returns {number}
+ */
+function scene_faces(manifest) {
+    let faces = 0;
+
+    for (const geometry of manifest.geometries) {
+        faces += geometry.faces * (geometry.instances.length / 16);
+    }
+
+    return faces;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function human_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    }
+
+    if (bytes < 1024 * 1024 * 1024) {
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+
+    return `${(bytes / (1024 ** 3)).toFixed(2)} GB`;
+}
+
+/**
+ * Where the scene manifest is, out of `?scene=` or out of the asset server's own listing.
+ *
+ * The listing is what makes the page turn-key: `vgeo_serve.js` answers `/scenes.json` with the
+ * manifests in the directory it is serving, so a page opened with no parameters at all finds the
+ * one scene that is there. More than one and it takes the first and says which, because a page
+ * that refuses to choose between two is a page that shows nothing.
+ *
+ * @returns {Promise<string>}
+ */
+async function resolve_scene_url() {
+    const requested = new URL(globalThis.location.href).searchParams.get('scene');
+
+    if (requested !== null) {
+        return new URL(requested, globalThis.location.href).href;
+    }
+
+    const listing = await fetch(`${DEFAULT_ORIGIN}/scenes.json`);
+
+    if (!listing.ok) {
+        throw new Error(
+            `no ?scene= was given and ${DEFAULT_ORIGIN} answered HTTP ${listing.status};`
+            + ` start the asset server with`
+            + ` "node tools/geometry/virtual/vgeo_serve.js <container directory>"`
+        );
+    }
+
+    const scenes = await listing.json();
+
+    if (scenes.length === 0) {
+        throw new Error(
+            `${DEFAULT_ORIGIN} is serving no .vgeoscene.json;`
+            + ` build one with "node tools/geometry/virtual/vgeo_scene.js <manifest.vgeo.json>"`
+        );
+    }
+
+    return `${DEFAULT_ORIGIN}/${scenes[0]}`;
+}
+
+/**
+ * A number that is the same for the same scene and comfortably above what it will ever need.
+ *
+ * Three of the runtime's capacities are properties of the *scene* rather than of the engine, and
+ * all three are knowable before a byte is fetched:
+ *
+ * - **`geometry_capacity`** is one row per container, and the default of 256 is an order of
+ *   magnitude short of a converted set.
+ * - **`lookup_words`** is one word per page of every registered container, out of one arena. The
+ *   default of 65,536 holds a fourteenth of Zorah's 947,664, and it is allocated out of an
+ *   `OffsetAllocator` whose bins round *down* — it can refuse an allocation that fits — so the
+ *   slack here is the difference between a scene that registers and one that refuses its own
+ *   largest container for no visible reason.
+ * - **`claim_word_capacity`** is one bit per (collected instance, page ordinal of its geometry).
+ *   The engine derives it from a hint of a thousand instances times the whole tier, which at this
+ *   scale is both far too small and far too large: the real bound is
+ *   `max instances of any one geometry × page capacity`, because ordinals come out of the tier and
+ *   the sum of `instances × ordinals` is maximised by giving every slot to the most-instanced
+ *   asset. For Zorah that is 381 × the tier, which is a fifth of what the default derivation asks
+ *   for and provably enough — doubled here, because an ordinal capacity is a high-water mark and a
+ *   scene that has churned can hold more of them than the tier holds pages.
+ *
+ * @param {object} manifest
+ * @param {number} page_capacity
+ * @returns {{geometry_capacity: number, lookup_words: number, claim_word_capacity: number, max_instances: number}}
+ */
+function scene_capacities(manifest, page_capacity) {
+    let max_instances = 1;
+
+    for (const geometry of manifest.geometries) {
+        max_instances = Math.max(max_instances, geometry.instances.length / 16);
+    }
+
+    return {
+        geometry_capacity: manifest.geometry_count + 64,
+        lookup_words: 1 << Math.ceil(Math.log2(Math.max(1 << 16, manifest.total_pages * 1.5))),
+        claim_word_capacity: Math.ceil(max_instances * page_capacity / 32) * 2,
+        max_instances,
+    };
+}
+
+async function start() {
+    const canvas = element('view');
+
+    const page = new VGeoScenePlayground();
+
+    page.canvas = canvas;
+
+    const parameters = new URL(globalThis.location.href).searchParams;
+
+    page.status('reading the scene manifest…');
+
+    const scene_url = await resolve_scene_url();
+
+    const manifest_response = await fetch(scene_url);
+
+    if (!manifest_response.ok) {
+        throw new Error(`${scene_url} answered HTTP ${manifest_response.status}`);
+    }
+
+    const manifest = await manifest_response.json();
+
+    if (manifest.format !== 1) {
+        throw new Error(
+            `${scene_url} is a format-${manifest.format} scene and this page reads format 1`
+        );
+    }
+
+    page.manifest = manifest;
+    page.base = scene_url;
+
+    const box = manifest.world_bounds;
+
+    page.world_radius = 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+
+    /*
+     Page slots the VRAM tier is built with, over the engine's default of 1,024 and the runtime
+     page's 4,096. A slot holds a page's *runtime rows* rather than its payload — an eighth of the
+     page size — so this is a 96 MB arena; what it really spends is the decoded budget the pool
+     derives from it, which is 12,288 pages of payload in the meshlet pool, or 768 MB.
+
+     **The number is what the τ slider costs, measured.** Zorah from its authored viewpoint at
+     1578×746 settles at 6,387 resident pages at τ=1 and 9,412 at τ=0.5, which is the slider's
+     busiest end; at 8,192 slots that end fills the tier, `refused` climbs past two hundred
+     thousand, `clamped` stops falling to zero and the cut is being selected by a **budget** rather
+     than by τ — which is the one thing this page is not meant to be showing. A bigger window wants
+     more, because the cut is a function of the resolution, so it is a URL parameter and `refused`
+     is in the panel to say when it was the wrong one.
+    */
+    const page_capacity = Number(parameters.get('pages') ?? 12288);
+
+    const capacities = scene_capacities(manifest, page_capacity);
+
+    const renderer = new Renderer();
+
+    page.renderer = renderer;
+
+    await renderer.initialize({
+        context: canvas.getContext('webgpu'),
+        pixelRatio: globalThis.devicePixelRatio || 1,
+    });
+
+    /*
+     TAA on. A cut is re-selected every frame against a threshold in pixels, so the seams between
+     two levels of detail land on different pixels from one frame to the next and every one of them
+     is an aliased edge that crawls without a temporal filter — and the crawl reads as the cut being
+     unstable when it is the rasterizer being point-sampled. It costs the readings nothing: TAA is
+     downstream of the G-buffer, long after the cut has been selected and drawn.
+    */
+    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;
+
+    /*
+     The scene's own sun when the manifest names one, and the engine's default otherwise.
+
+     A converted container carries geometry and nothing else — no material authoring, no lights —
+     so the sun is most of what there is to shade it with, and which way it points is not
+     decoration: the engine's default comes down from above and slightly behind the world axes,
+     which over an outdoor scene authored around a different one puts every façade a viewer would
+     stand in front of into ambient. `--sundirection` in Zorah's own config is the direction it
+     shines *from*, which is the opposite of the direction a light points.
+    */
+    const sun = manifest.sun === undefined
+        ? make_sunlight()
+        : make_sunlight({
+            direction: new Vector3(-manifest.sun[0], -manifest.sun[1], -manifest.sun[2]),
+        });
+
+    place_light(scene, sun);
+
+    /*
+     Image-based lighting, and for the geometry rather than for the picture: a sun alone puts every
+     surface facing away from it at ambient zero, which is exactly the silhouettes and the creases a
+     cut is worth looking at. Not awaited — `test_assets/` is gitignored, so a checkout without it
+     gets the sun alone and still draws every triangle the cut selected.
+    */
+    load_default_environment(scene);
+
+    const camera = new PerspectiveCamera();
+
+    camera.fov_degrees = manifest.camera?.fov ?? 60;
+
+    page.camera = camera;
+    page.controller = new OrbitalCameraController(camera, document.body);
+
+    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;
+
+    /*
+     The residency's knobs, which are per-reading budgets rather than sizes — nothing here scales
+     with how much is resident. What a scene changes about them is the breadth each reading has to
+     cover: the wants of one reading now come from thousands of containers rather than from one, so
+     a fetch budget sized for a single asset spends the whole reading on whichever asset happened to
+     be first in the want list.
+    */
+    const residency = new VGeoResidencyOptions();
+
+    residency.ram_budget_bytes = 1024 * 1024 * 1024;
+
+    /*
+     VRAM is a strict subset of RAM, so the RAM tier has to be able to hold the whole VRAM tier and
+     every container's pinned root besides — 8,192 and 2,966 for Zorah, against a default of 16,384
+     slots that the two together are already within sight of.
+    */
+    residency.ram_slot_capacity = Math.max(1 << 14, (page_capacity + manifest.geometry_count) * 2);
+
+    residency.max_fetches_per_reading = 64;
+    residency.max_concurrent_fetches = 24;
+    residency.max_promotions_per_reading = 128;
+
+    page.runtime = scene_context.enable_virtual_geometry({
+        page_size: manifest.page_size,
+        table_options: {
+            page_capacity,
+            geometry_capacity: capacities.geometry_capacity,
+            lookup_words: capacities.lookup_words,
+        },
+        claim_word_capacity: capacities.claim_word_capacity,
+        /*
+         Pages one frame may ask for, across every view. A single asset's cut wants a handful once
+         it has settled; a cold scene of three thousand containers wants from all of them at once,
+         and a want the frame had no room for is one more reading before that page arrives.
+        */
+        want_capacity: 8192,
+        /*
+         Traversal items one wavefront may hold, over the engine's 1 << 16. This is the capacity a
+         *scene* reaches first and the only one whose overflow is invisible without looking: at
+         τ=0.5 with 17,424 instances the descent pushed past 65,536 items in flight and
+         `VGEO_CUT_STAT.QUEUE_DROPPED` came back at 32,676 — a third of the frontier thrown away,
+         which showed up not as an error but as `drawn` wandering over ten thousand clusters
+         between one frame and the next as different subtrees lost the race.
+
+         It is two buffers of `capacity × 16` bytes per expansion site, so this is 4 MiB a site
+         against the 1 MiB the default costs. At 1 << 18 the same view drops nothing.
+        */
+        queue_capacity: 1 << 18,
+        /*
+         The wavefront bound is the engine's and is deliberately **not** set here. It starts at 8
+         and `GPUVirtualGeometryRuntime.note_incomplete_descent` raises it from what the cut
+         reports, so this page gets the same escalation any host does — and pinning it here would
+         hide the one behaviour worth watching from the page best placed to watch it.
+
+         `?iterations=` overrides it for an experiment. At 8 with no escalation, this scene at
+         3419×1286 left up to 13,467 items queued on 750 frames of 900 and `drawn` swung 11,857
+         clusters; the panel's `dropped: queue N` row is that reading.
+        */
+        ...(parameters.has('iterations')
+            ? { max_iterations: Number(parameters.get('iterations')), max_iteration_ceiling: Number(parameters.get('iterations')) }
+            : {}),
+        residency,
+    });
+
+    page.residency = scene_context.virtual_geometry_residency;
+    page.feedback = scene_context.virtual_geometry_feedback;
+
+    /*
+     What the rasterization collections are primed to expect. Both of these grow on their own from
+     what the frame reports, so priming is about the first seconds rather than the steady state —
+     but the first seconds are when the scene is being placed, and a `Meshes` limit of 1e4 against
+     17,424 instances drops the difference on the floor and counts them as `instances_dropped` while
+     the collection catches up.
+    */
+    const limits = renderer.graphics.collection_limits;
+
+    limits.prime(
+        RasterizationCollectionType.Meshes,
+        Math.max(1e4, Math.ceil(manifest.instance_count * 1.25))
+    );
+
+    limits.prime(RasterizationCollectionType.Meshlets, 5e5);
+
+    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;
+
+    /*
+     `?side=front|back|double` sets the whole scene's draw side, which is the cheapest way to ask
+     whether what you are looking at is a winding problem: `double` culls nothing, so any surface
+     that appears under it and not under `front` was being culled rather than being absent.
+    */
+    material.draw_side = DRAW_SIDES[parameters.get('side')] ?? ShadeDrawSide.Front;
+
+    page.material = material;
+
+    /*
+     `?mirrored=flip|tint|double` puts reflected instances in a bucket of their own — see
+     {@link VGeoScenePlayground.mirror_material}. Off by default: the engine reverses their winding
+     per instance, so the default is already the correct picture.
+
+     - **tint** leaves the side alone and colours them, so you can see which geometry in the frame
+       is reflected without changing what is drawn.
+     - **flip** draws them `Back`-sided. This was the page's own fix before the engine had one; now
+       it reverses a second time and reproduces the old inside-out picture on demand.
+     - **double** draws both sides of them, which fills the holes and gets the shading wrong, and is
+       here because it is the fix people reach for first.
+    */
+    const mirrored_mode = parameters.get('mirrored');
+
+    const mirror_material = new StandardShadeMaterial();
+
+    mirror_material.copy(material);
+
+    if (mirrored_mode === 'flip') {
+        mirror_material.draw_side = ShadeDrawSide.Back;
+    } else if (mirrored_mode === 'double') {
+        mirror_material.draw_side = ShadeDrawSide.Double;
+    } else if (mirrored_mode === 'tint') {
+        mirror_material.diffuse_color.copy(new Color(0.85, 0.16, 0.12));
+    }
+
+    page.mirror_material = mirrored_mode === null ? material : mirror_material;
+
+    globalThis.addEventListener('pagehide', () => page.feedback.destroy());
+
+    renderer.add_extension(new VGeoFrameStart(page));
+    renderer.add_extension(new VGeoFrameEnd(page));
+
+    element('tau').addEventListener('input', event => {
+        page.runtime.tau = Number(event.target.value);
+
+        element('tau-value').textContent = page.runtime.tau.toFixed(2);
+    });
+
+    /*
+     τ before the first container, for a session measuring one. Residency is a **high-water mark** —
+     the tier only evicts under pressure — so a page swept downwards through the thresholds reports,
+     at every step, the pages the *busiest* setting it has already been at asked for. A row of a τ
+     table is only about τ if the page has been at nothing else, which means a load per row.
+    */
+    const requested_tau = Number(parameters.get('tau'));
+
+    if (Number.isFinite(requested_tau) && requested_tau > 0) {
+        page.runtime.tau = requested_tau;
+
+        element('tau').value = String(requested_tau);
+        element('tau-value').textContent = requested_tau.toFixed(2);
+    }
+
+    // a drag on the τ slider is a drag on the body, and the camera controller listens there
+    element('panel').addEventListener('pointerdown', event => event.stopPropagation());
+
+    install_profile_hotkey({
+        renderer,
+        name: "vgeo_scene",
+        status: element('profile-status'),
+        settings: () => {
+            const state = page.state();
+
+            return [
+                `τ=${state.tau}px`,
+                state.scene.name,
+                `${state.scene.containers} containers`,
+                `${state.scene.instances} instances`,
+                `${state.cut.drawn} clusters`,
+                `${state.vram.pages} of ${state.vram.capacity} pages resident`,
+                `${state.screen_width}×${state.screen_height}`,
+            ];
+        },
+    });
+
+    globalThis.__state = () => page.state();
+    globalThis.__page = page;
+    globalThis.__look = (eye, target) => page.look(eye, target);
+    globalThis.__camera_url = () => camera_url(page);
+
+    /*
+     The camera before the first container, so the cut that runs while the scene is arriving is the
+     one the viewpoint asked for rather than a cut of everything from the origin.
+
+     The manifest's camera when it has one — a converted scene's own authored pose, which is the
+     only thing that knows which forty metres of a hundred-kilometre box the scene is *about*. With
+     no camera, the box: wrong for Zorah and right for a scene that is its own extent, and the
+     parameter overrides both.
+    */
+    const eye = read_vector(parameters.get('eye')) ?? manifest.camera?.eye;
+    const target = read_vector(parameters.get('at')) ?? manifest.camera?.target;
+
+    const center = [
+        (box[0] + box[3]) / 2, (box[1] + box[4]) / 2, (box[2] + box[5]) / 2,
+    ];
+
+    page.viewpoints = [
+        {
+            name: 'scene',
+            eye: [
+                center[0] + page.world_radius * 0.9,
+                center[1] + page.world_radius * 0.5,
+                center[2] + page.world_radius * 0.9,
+            ],
+            target: center,
+        },
+    ];
+
+    if (manifest.camera !== undefined) {
+        page.viewpoints.unshift({
+            name: 'authored',
+            eye: manifest.camera.eye,
+            target: manifest.camera.target,
+        });
+    }
+
+    const start_view = eye !== undefined && target !== undefined
+        ? { name: 'url', eye, target }
+        : page.viewpoints[0];
+
+    page.look(start_view.eye, start_view.target);
+
+    wire_viewpoints(page);
+    wire_camera_capture(page);
+
+    /*
+     `?catch=0.15` arms the dropout catcher — see {@link FlickerCatcher} for why it reads pixels
+     rather than counters. Off by default: it is a `drawImage` and a `getImageData` every frame, and
+     a page that is a measurement harness should not pay for a diagnostic nobody asked for.
+
+     `&freeze=1` stops on the first one and leaves it on screen, which is what makes a screenshot of
+     the page a screenshot of the offending frame. Without it the catcher keeps counting and the
+     panel shows the running tally, which is the mode for flying around looking for one.
+    */
+    const catch_threshold = Number(parameters.get('catch'));
+
+    if (Number.isFinite(catch_threshold) && catch_threshold > 0) {
+        page.catcher = new FlickerCatcher(
+            canvas, catch_threshold, parameters.get('freeze') !== null, () => camera_url(page)
+        );
+
+        globalThis.__caught = () => page.catcher.report();
+        globalThis.__show_frame = frame => page.catcher.show(frame);
+        globalThis.__catch_rows = () => page.catcher.rows;
+    }
+
+    let stopped = false;
+    let last_time;
+
+    function 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;
+
+        try {
+            page.controller.update(dt);
+
+            renderer.render(camera, scene, dt);
+        } catch (error) {
+            stopped = true;
+
+            page.status(error.message ?? String(error), true);
+
+            console.error(error);
+
+            return;
+        }
+
+        const state = page.state();
+
+        // after the render, so the canvas it reads is this frame's
+        page.catcher?.sample(state);
+
+        paint(page, capacities, state);
+
+        requestAnimationFrame(tick);
+    }
+
+    requestAnimationFrame(tick);
+
+    page.status(`opening ${manifest.geometry_count.toLocaleString()} containers…`);
+
+    /*
+     Not awaited: the frame loop above is already running, and a scene that placed its first
+     container two hundred frames before its last is the loop this page exists to show.
+    */
+    page.open_scene(manifest);
+}
+
+/**
+ * `"x,y,z"` out of a URL parameter.
+ *
+ * @param {string|null} text
+ * @returns {number[]|undefined}
+ */
+function read_vector(text) {
+    if (text === null) {
+        return undefined;
+    }
+
+    const numbers = text.split(',').map(Number);
+
+    if (numbers.length !== 3 || numbers.some(n => !Number.isFinite(n))) {
+        return undefined;
+    }
+
+    return numbers;
+}
+
+/**
+ * A link that reopens the page **where it is standing now**, with everything else about how it was
+ * opened left alone.
+ *
+ * This exists because a viewpoint is the one piece of state that a person has and a session does
+ * not. Everything else this page can be told — the scene, τ, the tier's size, which side to draw —
+ * is a URL parameter already; where the camera got dragged to is not, and a phenomenon that happens
+ * "in many places" is useless to chase without one of them. So the button hands over a URL rather
+ * than three numbers: paste it back and the page opens on the same view, at the same threshold,
+ * with the same tier, and with whatever diagnostic was already armed still armed.
+ *
+ * `?eye=`/`?at=` were already the way in; this is the way out.
+ *
+ * @param {VGeoScenePlayground} page
+ * @returns {string}
+ */
+function camera_url(page) {
+    const url = new URL(globalThis.location.href);
+
+    const state = page.state();
+
+    // nine significant digits, which is exact for a float and about half the characters an f64
+    // print of one costs — the same trim `vgeo_scene.js` writes its matrices with
+    const trim = value => Number(value.toPrecision(9));
+
+    const triple = values => values.map(trim).join(',');
+
+    url.searchParams.set('eye', triple(state.camera.eye));
+    url.searchParams.set('at', triple([
+        state.camera.target.x, state.camera.target.y, state.camera.target.z,
+    ]));
+
+    /*
+     τ as it stands rather than as it was asked for. The slider moves and the parameter does not
+     follow it, so a link that carried only what the page was opened with would reopen at a
+     different cut from the one being looked at — which for a page about a cut is the whole thing.
+    */
+    url.searchParams.set('tau', String(trim(state.tau)));
+
+    /*
+     `URLSearchParams` percent-encodes the separators, and `eye=27.9%2C8.9%2C-4` is correct, ugly,
+     and about to be read by a person and pasted into a message. A comma is legal unencoded in a
+     query string, so it goes back.
+    */
+    return url.href.replace(/%2C/g, ',');
+}
+
+/**
+ * @param {VGeoScenePlayground} page
+ */
+function wire_camera_capture(page) {
+    const button = element('copy-camera');
+    const output = element('camera-url');
+
+    button.addEventListener('click', async () => {
+        const url = camera_url(page);
+
+        output.textContent = url;
+        output.hidden = false;
+
+        /*
+         The clipboard is a permission and a secure context away, and this page is served over
+         plain HTTP from a dev server on whatever host someone pointed it at. So the text is put on
+         screen first and copied second: the button works either way, and the label says which
+         happened rather than failing silently.
+        */
+        try {
+            await navigator.clipboard.writeText(url);
+
+            button.textContent = 'copied to clipboard';
+
+            // the controller's keyboard device listens on the body, and a click leaves focus here.
+            // Only on the happy path: the fallback below has just made a selection, and moving
+            // focus would drop it.
+            document.body.focus();
+        } catch {
+            /*
+             Selected rather than merely shown, so the fallback is one Ctrl+C rather than a drag
+             across four lines of wrapped URL. `user-select: all` makes a click do the same thing,
+             and this makes the click unnecessary.
+            */
+            const range = document.createRange();
+
+            range.selectNodeContents(output);
+
+            const selection = globalThis.getSelection();
+
+            selection.removeAllRanges();
+            selection.addRange(range);
+
+            button.textContent = 'selected below — Ctrl+C';
+        }
+
+        setTimeout(() => { button.textContent = 'copy camera link'; }, 2500);
+    });
+}
+
+/**
+ * @param {VGeoScenePlayground} page
+ */
+function wire_viewpoints(page) {
+    const container = element('views');
+
+    container.innerHTML = '';
+
+    for (const viewpoint of page.viewpoints) {
+        const button = document.createElement('button');
+
+        button.textContent = viewpoint.name;
+
+        button.addEventListener('click', () => {
+            page.look(viewpoint.eye, viewpoint.target);
+
+            // the controller's keyboard device listens on the body, and a click leaves focus here
+            document.body.focus();
+        });
+
+        container.append(button);
+    }
+}
+
+/**
+ * @param {VGeoScenePlayground} page
+ * @param {object} capacities
+ */
+function paint(page, capacities, state) {
+    const scene = state.scene;
+
+    element('progress').firstElementChild.style.width =
+        `${scene.declared === 0 ? 0 : (100 * scene.containers / scene.declared).toFixed(1)}%`;
+
+    rows('scene', [
+        ['source', escape_html(scene.name)],
+        ['containers', `${scene.containers.toLocaleString()} / ${scene.declared.toLocaleString()}`],
+        ['instances', scene.instances.toLocaleString()],
+        ['reflected', scene.mirrored.toLocaleString()],
+        ['source triangles', scene.faces.toLocaleString()],
+        ['on the server', human_bytes(scene.bytes)],
+        ['read', human_bytes(scene.bytes_read)],
+        ['view', `${state.screen_width}×${state.screen_height}`],
+        ['frame', `${state.frame_ms.toFixed(1)} ms`],
+    ]);
+
+    rows('cut', [
+        ['drawn clusters', state.cut.drawn.toLocaleString()],
+        ['clamped', state.cut.clamped.toLocaleString()],
+        ['pages visited', state.cut.pages.toLocaleString()],
+        ['clusters tested', state.cut.clusters_tested.toLocaleString()],
+        ['subtrees culled', (state.cut.culled_frustum + state.cut.culled_lod).toLocaleString()],
+        ['clusters culled', state.cut.culled_cluster.toLocaleString()],
+        [
+            'wavefronts',
+            `${state.cut.wavefronts} / ${state.cut.max_iterations}`
+            + (state.cut.iteration_escalations > 0 ? ` (${state.cut.iteration_escalations}↑)` : ''),
+        ],
+        ['wants', state.wants],
+    ]);
+
+    /*
+     Four counts of the cut giving up, kept apart from the six of it succeeding, because at this
+     scale every one of them names a different capacity and a scene is the first thing big enough
+     to reach any of them.
+    */
+    const dropped = [
+        ['meshlets', state.cut.meshlets_dropped],
+        ['instances', state.cut.instances_dropped],
+        ['queue', state.cut.queue_dropped + state.cut.queue_remaining],
+        ['wants', state.cut.wants_dropped],
+    ].filter(([, count]) => count > 0);
+
+    rows('residency', [
+        ['VRAM pages', `${state.vram.pages.toLocaleString()} / ${state.vram.capacity.toLocaleString()}`],
+        ['VRAM bytes', human_bytes(state.vram.bytes)],
+        ['RAM pages', state.ram.pages.toLocaleString()],
+        ['RAM bytes', human_bytes(state.ram.bytes)],
+        ['evicted', `${state.vram.evicted.toLocaleString()} / ${state.ram.evicted.toLocaleString()}`],
+        ['fetching', state.fetches_in_flight],
+        [
+            'refused',
+            `<span class="${state.vram.refused > 0 ? 'bad' : 'good'}">`
+            + `${state.vram.refused.toLocaleString()}</span>`,
+        ],
+        [
+            'dropped',
+            dropped.length === 0
+                ? '<span class="good">0</span>'
+                : `<span class="bad">${dropped.map(([n, c]) => `${n} ${c.toLocaleString()}`).join(', ')}</span>`,
+        ],
+        ['claim words', capacities.claim_word_capacity.toLocaleString()],
+    ]);
+
+    const catcher = page.catcher;
+
+    if (catcher === undefined) {
+        return;
+    }
+
+    const report = catcher.report();
+
+    element('catch-section').hidden = false;
+
+    rows('catch', [
+        ['sampled', report.frames.toLocaleString()],
+        ['threshold', `${(100 * report.threshold).toFixed(0)}%`],
+        ['worst so far', `${(100 * report.worst).toFixed(1)}%`],
+        [
+            'caught',
+            `<span class="${report.events > 0 ? 'bad' : 'good'}">${report.events}</span>`,
+        ],
+        ['frozen', report.frozen ? `<span class="bad">yes</span>` : 'no'],
+        ['last at frame', report.last === undefined ? '—' : report.last.frame],
+    ]);
+}
+
+/**
+ * @param {string} id
+ * @param {Array<[string, string|number]>} entries
+ */
+function rows(id, entries) {
+    element(id).innerHTML = entries
+        .map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+        .join('');
+}
+
+/**
+ * A manifest's source name lands in the panel's markup, so it is a string from outside the page in
+ * the one place a string from outside the page can do something.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escape_html(text) {
+    return text.replace(/[&<>"]/g, character => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;',
+    })[character]);
+}
+
+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);
+});