@woosh/meep-engine 3.0.2 → 3.2.0

package/src/shade/renderer/geometry/virtual/format/prototypeVGEOFormatViewer.js

@@ -1,2063 +1,2063 @@
-/**
- * A debug viewer for the `.vgeo` container.
- *
- * Drop a file onto the page and it is validated, decoded, and drawn — not as an asset, but as the
- * *cut* the container's own metric selects: the clusters a runtime would draw, coloured so the
- * seams between them are visible, with the cluster count on screen.
- *
- *   npm run dev
- *   http://localhost:9000/index.html?entry=/src/mir-engine/meep/src/shade/renderer/geometry/virtual/format/prototypeVGEOFormatViewer.js
- *
- * `?file=/data/models/stanford/vgeo/bunny/<asset-id>.vgeo` loads one straight away, which is what
- * makes a particular view of a particular asset a bookmark.
- *
- * **The cut is frozen until you ask for a new one.** "Adapt to view" re-runs the traversal at
- * wherever the camera is standing now; everything after that is you flying around a decision taken
- * from somewhere else, which is the only way to see what a cut actually selected. Turn `auto` on to
- * watch it chase the camera instead.
- *
- * Drawing goes through Shade's **direct geometry path** — a {@link DynamicMesh} drawn straight from
- * its attributes, no meshlet encode — because a cut is rebuilt from scratch every time it is
- * adapted, and a meshlet build per adapt would price the tool out of being interactive. It is drawn
- * *opaque* on that path ({@link GPUDynamicMeshRenderer.opaque}), so the depth buffer orders the
- * cut's own triangles: a cut is a solid surface and nothing on the CPU can order one correctly.
- *
- * THROWAWAY, and deliberately self-contained. The container reader below is a *debug* reader: whole
- * file, eager, everything resident. The runtime's is streaming and partial and belongs to M1;
- * nothing here should be mistaken for its shape.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-import { assert } from "../../../../../core/assert.js";
-import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
-import { UINT16_MAX } from "../../../../../core/binary/UINT16_MAX.js";
-import {
-    decode_octahedron_to_unit
-} from "../../../../../core/geom/3d/normal/octahedron/decode_octahedron_to_unit.js";
-import Vector3 from "../../../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../../../core/math/DEG_TO_RAD.js";
-import { OrbitalCameraController } from "../../../camera/orbital/index.js";
-import { PerspectiveCamera } from "../../../camera/PerspectiveCamera.js";
-import { create_frame_loop } from "../../../create_frame_loop.js";
-import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../../../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
-import { DEPTH_BACKGROUND_VALUE } from "../../../depth/DEPTH_BACKGROUND_VALUE.js";
-import { GPUDynamicMeshRenderer } from "../../../dynamic/GPUDynamicMeshRenderer.js";
-import { make_sunlight } from "../../../light/make_sunlight.js";
-import { FramePhase } from "../../../extension/FramePhase.js";
-import { RenderExtension } from "../../../extension/RenderExtension.js";
-import { SceneColor } from "../../../extension/SceneColor.js";
-import { ViewTextures } from "../../../extension/ViewTextures.js";
-import { Renderer } from "../../../Renderer.js";
-import { DynamicMesh } from "../../../scene/DynamicMesh.js";
-import { DynamicMeshBatch } from "../../../scene/DynamicMeshBatch.js";
-import { Scene } from "../../../scene/Scene.js";
-import { Attribute } from "../../Attribute.js";
-import { Geometry } from "../../Geometry.js";
-import { StandardAttributes } from "../../StandardAttributes.js";
-import { VGEO_ATTRIBUTE } from "./attribute/VGEO_ATTRIBUTE.js";
-import { VGEO_ATTRIBUTES } from "./attribute/VGEO_ATTRIBUTES.js";
-import { VGEO_CHILD_OFFSET } from "./frame/VGEO_CHILD_OFFSET.js";
-import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
-import { VGEO_CLUSTER_OFFSET } from "./cluster/VGEO_CLUSTER_OFFSET.js";
-import { VGEO_CLUSTER_RECORD_SIZE } from "./cluster/VGEO_CLUSTER_RECORD_SIZE.js";
-import { vgeo_codec_name } from "./frame/vgeo_codec_name.js";
-import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
-import { VGEO_CODEC_RAW } from "./frame/VGEO_CODEC_RAW.js";
-import { vgeo_decode_frame_blob } from "./frame/vgeo_decode_frame_blob.js";
-import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
-import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
-import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
-import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
-import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
-import { VGEO_LEVEL_OFFSET } from "./header/VGEO_LEVEL_OFFSET.js";
-import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
-import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
-import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
-import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
-import { VGEO_PAGE_HEADER_SIZE } from "./page/VGEO_PAGE_HEADER_SIZE.js";
-import { VGEO_PAGE_OFFSET } from "./page/VGEO_PAGE_OFFSET.js";
-import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
-import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
-import { vgeo_payload_attribute_offset } from "./payload/vgeo_payload_attribute_offset.js";
-import { vgeo_validate_container } from "./vgeo_validate_container.js";
-
-/**
- * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
- * @type {boolean}
- */
-const LE = true;
-
-/**
- * The `encoding_flags` bit that says a cluster's normal section holds one constant-compressed word
- * for the whole cluster instead of one per vertex.
- * @type {number}
- */
-const NORMAL_COMPRESSION_FLAG = VGEO_ATTRIBUTES[VGEO_ATTRIBUTE.NORMAL].compression_flag;
-
-// ─────────────────────────────────────────────────────────────────────────────
-//  Reading
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * One page, decoded far enough to traverse.
- */
-export class VGeoPageView {
-    /**
-     * Page index, which is also the frame ordinal.
-     * @type {number}
-     */
-    index = 0;
-
-    /**
-     * Byte offset of the decoded page's first byte in {@link VGeoContainer.page_bytes}.
-     * @type {number}
-     */
-    base = 0;
-
-    /**
-     * The codec its frame stored it under. Informational here — the page is decoded before anything
-     * reads it — and worth showing, because it is per page and a file can carry both.
-     * @type {number}
-     */
-    codec = 0;
-
-    /**
-     * Bytes the frame stores, before decoding.
-     * @type {number}
-     */
-    stored_size = 0;
-
-    /**
-     * Bytes the page occupies decoded.
-     * @type {number}
-     */
-    decoded_size = 0;
-
-    /**
-     * @type {number}
-     */
-    min_level = 0;
-
-    /**
-     * @type {number}
-     */
-    max_level = 0;
-
-    /**
-     * Absolute byte offset of this page's payload section.
-     * @type {number}
-     */
-    payload_base = 0;
-
-    /**
-     * Id of this page's first cluster in the reader's own flat numbering, which is page order and
-     * then cluster-table order. The format has no global cluster id; this exists so the arrays on
-     * {@link VGeoContainer} can be indexed by one.
-     * @type {number}
-     */
-    cluster_base = 0;
-
-    /**
-     * @type {number}
-     */
-    cluster_count = 0;
-
-    /**
-     * `child_ref -> page index`, read out of the frame's child table.
-     * @type {Uint32Array}
-     */
-    child_pages = new Uint32Array(0);
-
-    /**
-     * Per group: index of its first cluster within this page.
-     * @type {Uint16Array}
-     */
-    group_cluster_first = new Uint16Array(0);
-
-    /**
-     * @type {Uint16Array}
-     */
-    group_cluster_count = new Uint16Array(0);
-
-    /**
-     * How many clusters name this group as their child. Zero is what makes a group selectable with
-     * nothing above it — the root page's topmost groups, and only those.
-     * @type {Uint16Array}
-     */
-    group_parent_count = new Uint16Array(0);
-
-    /**
-     * @type {number}
-     */
-    node_count = 0;
-}
-
-/**
- * A whole `.vgeo` file, read into the flat form the traversal wants.
- *
- * Clusters are a structure of arrays rather than objects: an asset of any size has hundreds of
- * thousands of them, a cut reads a handful of fields from the ones it visits and nothing at all
- * from the ones it skips, and an object per cluster would cost more than the file does.
- */
-export class VGeoContainer {
-    /**
-     * Every page decoded, back to back in page order. Each page's {@link VGeoPageView.base} is an
-     * offset into this, and so — through it — is every payload offset a cluster record carries.
-     *
-     * It is not the file. Under a compressing codec the file does not hold a page's bytes at all,
-     * and even under the raw codec the two differ by the frame headers and child tables the decoded
-     * image leaves out.
-     *
-     * @type {Uint8Array}
-     */
-    page_bytes = new Uint8Array(0);
-
-    /**
-     * What the frames store between them, before decoding — the part of the file that is pages.
-     * @type {number}
-     */
-    stored_page_bytes = 0;
-
-    /**
-     * `page_bytes.length`, named so a caller does not have to know that.
-     * @type {number}
-     */
-    decoded_page_bytes = 0;
-
-    /**
-     * @type {number}
-     */
-    format_version = 0;
-
-    /**
-     * @type {number}
-     */
-    payload_encoding = 0;
-
-    /**
-     * Hex, as the 16 asset-id bytes stand in the file.
-     * @type {string}
-     */
-    asset_id = '';
-
-    /**
-     * @type {number}
-     */
-    source_vertex_count = 0;
-
-    /**
-     * @type {number}
-     */
-    source_face_count = 0;
-
-    /**
-     * Object-space bounding sphere of the whole geometry: centre xyz then radius.
-     * @type {Float32Array}
-     */
-    object_sphere = new Float32Array(4);
-
-    /**
-     * @type {Float32Array}
-     */
-    object_bounds = new Float32Array(6);
-
-    /**
-     * @type {VGeoPageView[]}
-     */
-    pages = [];
-
-    /**
-     * @type {{min_error:number, max_error:number, clusters:number, groups:number, triangles:number}[]}
-     */
-    levels = [];
-
-    /**
-     * @type {number}
-     */
-    cluster_count = 0;
-
-    /**
-     * `4 * cluster_count` — the LOD-metric sphere of the step that created each cluster.
-     * @type {Float32Array}
-     */
-    self_sphere = new Float32Array(0);
-
-    /**
-     * @type {Float32Array}
-     */
-    self_error = new Float32Array(0);
-
-    /**
-     * @type {Float32Array}
-     */
-    parent_error = new Float32Array(0);
-
-    /**
-     * `4 * cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
-     * @type {Float32Array}
-     */
-    bounds_sphere = new Float32Array(0);
-
-    /**
-     * @type {Uint16Array}
-     */
-    child_ref = new Uint16Array(0);
-
-    /**
-     * @type {Uint16Array}
-     */
-    child_group = new Uint16Array(0);
-
-    /**
-     * @type {Uint32Array}
-     */
-    encoding_flags = new Uint32Array(0);
-
-    /**
-     * Offset into the owning page's payload section.
-     * @type {Uint32Array}
-     */
-    payload_offset = new Uint32Array(0);
-
-    /**
-     * @type {Uint8Array}
-     */
-    vertex_count = new Uint8Array(0);
-
-    /**
-     * @type {Uint8Array}
-     */
-    triangle_count = new Uint8Array(0);
-
-    /**
-     * @type {Uint32Array}
-     */
-    page_of_cluster = new Uint32Array(0);
-
-    /**
-     * Group index within that page, so a colour can be keyed on the residency unit.
-     * @type {Uint16Array}
-     */
-    group_of_cluster = new Uint16Array(0);
-
-    /**
-     * How many clusters store a normal per vertex rather than one constant-compressed word for the
-     * whole cluster.
-     *
-     * A source carrying no normals encodes the engine default everywhere, and then `colour by
-     * stored normal` comes out one flat colour across the whole model. That is the file's truth and
-     * it reads exactly like a broken viewer, so the panel says the number outright.
-     *
-     * It is not a count of clusters that *have* normals: a cluster whose vertices genuinely all
-     * face the same way compresses to one word as well, and a flat surface is not a missing one.
-     *
-     * @type {number}
-     */
-    per_vertex_normal_cluster_count = 0;
-
-    /**
-     * What {@link vgeo_validate_container} made of the file. Empty is the only good answer, and a
-     * non-empty one is the most interesting thing this tool can tell you.
-     * @type {VGeoDefect[]}
-     */
-    defects = [];
-}
-
-/**
- * @param {DataView} view
- * @param {number} offset
- * @returns {string} 16 bytes as hex
- */
-function read_asset_id(view, offset) {
-    let out = '';
-
-    for (let i = 0; i < 16; i++) {
-        out += view.getUint8(offset + i).toString(16).padStart(2, '0');
-    }
-
-    return out;
-}
-
-/**
- * Read a whole `.vgeo` file.
- *
- * Eager and complete, which is the opposite of what the runtime will do and exactly right for a
- * tool whose job is to look at every part of it.
- *
- * @param {ArrayBuffer} array_buffer the complete file
- * @returns {VGeoContainer}
- * @throws {Error} when the bytes are not a `.vgeo` at all, or a page uses a codec this reader has no
- *     decoder for — everything softer than that lands in {@link VGeoContainer.defects}
- */
-export function vgeo_read_container(array_buffer) {
-    assert.defined(array_buffer, 'array_buffer');
-
-    if (array_buffer.byteLength < VGEO_HEADER_SIZE) {
-        throw new Error(`file is ${array_buffer.byteLength} bytes, shorter than the header`);
-    }
-
-    const view = new DataView(array_buffer);
-
-    const magic = view.getUint32(VGEO_HEADER_OFFSET.MAGIC, LE);
-
-    if (magic !== VGEO_MAGIC) {
-        throw new Error(
-            `not a .vgeo file: magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`
-        );
-    }
-
-    const result = new VGeoContainer();
-
-    const file_bytes = new Uint8Array(array_buffer);
-
-    result.format_version = view.getUint16(VGEO_HEADER_OFFSET.FORMAT_VERSION, LE);
-    result.payload_encoding = view.getUint32(VGEO_HEADER_OFFSET.PAYLOAD_ENCODING, LE);
-    result.asset_id = read_asset_id(view, VGEO_HEADER_OFFSET.ASSET_ID);
-    result.source_vertex_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_VERTEX_COUNT, LE));
-    result.source_face_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_FACE_COUNT, LE));
-
-    for (let i = 0; i < 4; i++) {
-        result.object_sphere[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_SPHERE + i * 4, LE);
-    }
-
-    for (let i = 0; i < 6; i++) {
-        result.object_bounds[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_BOUNDS + i * 4, LE);
-    }
-
-    const level_count = view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT);
-
-    for (let i = 0; i < level_count; i++) {
-        const at = VGEO_HEADER_SIZE + i * VGEO_LEVEL_RECORD_SIZE;
-
-        result.levels.push({
-            min_error: view.getFloat32(at + VGEO_LEVEL_OFFSET.MIN_ERROR, LE),
-            max_error: view.getFloat32(at + VGEO_LEVEL_OFFSET.MAX_ERROR, LE),
-            clusters: view.getUint32(at + VGEO_LEVEL_OFFSET.CLUSTER_COUNT, LE),
-            groups: view.getUint32(at + VGEO_LEVEL_OFFSET.GROUP_COUNT, LE),
-            triangles: view.getUint32(at + VGEO_LEVEL_OFFSET.TRIANGLE_COUNT, LE),
-        });
-    }
-
-    // The frame walk is the format's own, shared with the writer and the validator — a file either
-    // of those can scan is a file this can scan.
-    const frames = vgeo_scan_frames(BinaryBuffer.fromArrayBuffer(array_buffer));
-
-    /*
-     Every page is decoded up front into one image laid out in page order, and everything below
-     addresses that image rather than the file. The runtime does the opposite — one page at a time,
-     wherever it has room — but this tool wants all of them at once and wants one address space to
-     read them through, and under a compressing codec the file simply does not hold a page's bytes.
-
-     Both refusals below happen before a byte is allocated. The second matters more than it looks:
-     `decoded_size` is four bytes of untrusted file, and honouring one that no block of that length
-     could produce turns corruption into an out-of-memory throw.
-     */
-    let decoded_total = 0;
-
-    for (const frame of frames) {
-        if (frame.codec !== VGEO_CODEC_RAW && frame.codec !== VGEO_CODEC_LZ4) {
-            throw new Error(
-                `page ${frame.page_index} uses codec ${frame.codec};`
-                + ` this reader decodes ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`
-            );
-        }
-
-        if (frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
-            throw new Error(
-                `page ${frame.page_index} claims ${frame.decoded_size} decoded bytes,`
-                + ` more than codec ${frame.codec} could produce from ${frame.stored_size} stored`
-            );
-        }
-
-        result.stored_page_bytes += frame.stored_size;
-
-        decoded_total += frame.decoded_size;
-    }
-
-    const page_bytes = new Uint8Array(decoded_total);
-
-    result.page_bytes = page_bytes;
-    result.decoded_page_bytes = decoded_total;
-
-    /**
-     * The decoded pages, addressed a word at a time. A `DataView` has no alignment requirement,
-     * which is what a page's fields need: their offsets are the format's, not the browser's.
-     * @type {DataView}
-     */
-    const page_data = new DataView(page_bytes.buffer, page_bytes.byteOffset, page_bytes.byteLength);
-
-    let page_cursor = 0;
-    let cluster_total = 0;
-
-    for (const frame of frames) {
-        const page = new VGeoPageView();
-
-        page.index = frame.page_index;
-        page.base = page_cursor;
-        page.codec = frame.codec;
-        page.stored_size = frame.stored_size;
-        page.decoded_size = frame.decoded_size;
-
-        page_cursor = vgeo_decode_frame_blob(page_bytes, page_cursor, file_bytes, frame);
-
-        // The child table is plaintext inside the frame, never compressed — which is what lets a
-        // runtime read fetch ranges without decoding anything. So it is read from the file.
-        page.child_pages = new Uint32Array(frame.child_page_count);
-
-        for (let i = 0; i < frame.child_page_count; i++) {
-            const entry = frame.frame_offset
-                + VGEO_FRAME_HEADER_SIZE
-                + i * VGEO_CHILD_TABLE_ENTRY_SIZE;
-
-            page.child_pages[i] = view.getUint32(entry + VGEO_CHILD_OFFSET.PAGE_INDEX, LE);
-        }
-
-        const group_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.GROUP_COUNT, LE);
-
-        page.cluster_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.CLUSTER_COUNT, LE);
-        page.min_level = page_data.getUint8(page.base + VGEO_PAGE_OFFSET.MIN_LEVEL);
-        page.max_level = page_data.getUint8(page.base + VGEO_PAGE_OFFSET.MAX_LEVEL);
-        page.node_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.NODE_COUNT, LE);
-        page.payload_base = page.base
-            + page_data.getUint32(page.base + VGEO_PAGE_OFFSET.PAYLOAD_OFFSET, LE);
-        page.cluster_base = cluster_total;
-
-        page.group_cluster_first = new Uint16Array(group_count);
-        page.group_cluster_count = new Uint16Array(group_count);
-        page.group_parent_count = new Uint16Array(group_count);
-
-        for (let i = 0; i < group_count; i++) {
-            const record = page.base + VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
-
-            page.group_cluster_first[i] = page_data.getUint16(record, LE);
-            page.group_cluster_count[i] = page_data.getUint16(record + 2, LE);
-            page.group_parent_count[i] = page_data.getUint16(record + 4, LE);
-        }
-
-        result.pages.push(page);
-
-        cluster_total += page.cluster_count;
-    }
-
-    result.cluster_count = cluster_total;
-    result.self_sphere = new Float32Array(cluster_total * 4);
-    result.self_error = new Float32Array(cluster_total);
-    result.parent_error = new Float32Array(cluster_total);
-    result.bounds_sphere = new Float32Array(cluster_total * 4);
-    result.child_ref = new Uint16Array(cluster_total);
-    result.child_group = new Uint16Array(cluster_total);
-    result.encoding_flags = new Uint32Array(cluster_total);
-    result.payload_offset = new Uint32Array(cluster_total);
-    result.vertex_count = new Uint8Array(cluster_total);
-    result.triangle_count = new Uint8Array(cluster_total);
-    result.page_of_cluster = new Uint32Array(cluster_total);
-    result.group_of_cluster = new Uint16Array(cluster_total);
-
-    for (const page of result.pages) {
-        const table = page.base
-            + page_data.getUint32(page.base + VGEO_PAGE_OFFSET.CLUSTER_TABLE_OFFSET, LE);
-
-        for (let i = 0; i < page.cluster_count; i++) {
-            const record = table + i * VGEO_CLUSTER_RECORD_SIZE;
-            const id = page.cluster_base + i;
-
-            for (let c = 0; c < 4; c++) {
-                result.self_sphere[id * 4 + c] =
-                    page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_SPHERE + c * 4, LE);
-                result.bounds_sphere[id * 4 + c] =
-                    page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.BOUNDS_SPHERE + c * 4, LE);
-            }
-
-            result.self_error[id] = page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_ERROR, LE);
-            result.parent_error[id] = page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_ERROR, LE);
-            result.child_ref[id] = page_data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_REF, LE);
-            result.child_group[id] = page_data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_GROUP, LE);
-            result.encoding_flags[id] =
-                page_data.getUint32(record + VGEO_CLUSTER_OFFSET.ENCODING_FLAGS, LE);
-            result.payload_offset[id] =
-                page_data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_OFFSET, LE);
-            result.vertex_count[id] = page_data.getUint8(record + VGEO_CLUSTER_OFFSET.VERTEX_COUNT);
-            result.triangle_count[id] = page_data.getUint8(record + VGEO_CLUSTER_OFFSET.TRIANGLE_COUNT);
-            result.page_of_cluster[id] = page.index;
-
-            if ((result.encoding_flags[id] & NORMAL_COMPRESSION_FLAG) === 0) {
-                result.per_vertex_normal_cluster_count++;
-            }
-        }
-
-        for (let group = 0; group < page.group_cluster_first.length; group++) {
-            const first = page.group_cluster_first[group];
-            const count = page.group_cluster_count[group];
-
-            for (let i = 0; i < count; i++) {
-                result.group_of_cluster[page.cluster_base + first + i] = group;
-            }
-        }
-    }
-
-    result.defects = vgeo_validate_container(BinaryBuffer.fromArrayBuffer(array_buffer));
-
-    return result;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-//  The cut
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * The view a cut is selected for. `VIRTUAL_GEOMETRY_DESIGN.md` §4: a cut is selected at one
- * camera's distances and pixel budget, and is the wrong cut for any other.
- */
-export class VGeoCutView {
-    /**
-     * Camera position, object space — the viewer draws at identity, so world and object agree.
-     * @type {Float32Array}
-     */
-    eye = new Float32Array(3);
-
-    /**
-     * Pixels of permitted error. The one quality dial.
-     * @type {number}
-     */
-    tau = 1;
-
-    /**
-     * Height of the render target, in pixels — the projection's numerator.
-     * @type {number}
-     */
-    screen_height = 1080;
-
-    /**
-     * @type {number}
-     */
-    fov_y = 60 * DEG_TO_RAD;
-
-    /**
-     * @type {boolean}
-     */
-    cull_enabled = false;
-
-    /**
-     * Six normalized world-space planes, as {@link Camera.frustum} holds them.
-     * @type {Float32Array}
-     */
-    frustum = new Float32Array(24);
-}
-
-/**
- * What one traversal came to, including what it had to look at to get there.
- */
-export class VGeoCut {
-    /**
-     * Selected clusters, by reader id.
-     * @type {number[]}
-     */
-    clusters = [];
-
-    /**
-     * @type {number}
-     */
-    triangle_count = 0;
-
-    /**
-     * @type {number}
-     */
-    vertex_count = 0;
-
-    /**
-     * @type {number}
-     */
-    groups_visited = 0;
-
-    /**
-     * @type {number}
-     */
-    clusters_tested = 0;
-
-    /**
-     * Clusters whose subtree the frustum threw away, which is a whole region rather than one
-     * cluster — the reason culling belongs in the traversal and not after it.
-     * @type {number}
-     */
-    culled = 0;
-
-    /**
-     * Distinct pages the traversal had to have resident.
-     * @type {number}
-     */
-    pages_touched = 0;
-
-    /**
-     * @type {number}
-     */
-    duration_ms = 0;
-}
-
-/**
- * `VIRTUAL_GEOMETRY_DESIGN.md` §4: `err_px = r_e · screen_height / (2 · tan(fov_y / 2) · d)`, with
- * `d` the distance to the *closest point* of the sphere.
- *
- * A zero error projects to zero unconditionally — otherwise a leaf, whose error is exactly zero,
- * would become undrawable the moment the camera entered its sphere.
- *
- * @param {number} error object-space `r_e`; `+Infinity` for a root's parent
- * @param {Float32Array} spheres
- * @param {number} base index of the sphere's first component
- * @param {Float32Array} eye
- * @param {number} k `screen_height / (2 · tan(fov_y / 2))`, hoisted out of the loop
- * @returns {number} pixels
- */
-function project_error(error, spheres, base, eye, k) {
-    if (error === 0) {
-        return 0;
-    }
-
-    const dx = eye[0] - spheres[base];
-    const dy = eye[1] - spheres[base + 1];
-    const dz = eye[2] - spheres[base + 2];
-
-    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz) - spheres[base + 3];
-
-    if (distance <= 0) {
-        // camera inside the sphere; the projection is unbounded and the cluster must refine
-        return Number.POSITIVE_INFINITY;
-    }
-
-    return (error * k) / distance;
-}
-
-/**
- * Whether a sphere is entirely outside the frustum.
- *
- * Only the five finite planes are tested. The projection is infinite reverse-Z, so the far plane's
- * row is degenerate and normalizing it produces nothing a test can use.
- *
- * @param {Float32Array} frustum
- * @param {Float32Array} spheres
- * @param {number} base
- * @returns {boolean}
- */
-function sphere_outside_frustum(frustum, spheres, base) {
-    const x = spheres[base];
-    const y = spheres[base + 1];
-    const z = spheres[base + 2];
-    const radius = spheres[base + 3];
-
-    for (let plane = 0; plane < 5; plane++) {
-        const o = plane * 4;
-
-        const distance = frustum[o] * x + frustum[o + 1] * y + frustum[o + 2] * z + frustum[o + 3];
-
-        if (distance < -radius) {
-            return true;
-        }
-    }
-
-    return false;
-}
-
-/**
- * Select the cut for a view, by descending the page graph.
- *
- * A traversal rather than a flat pass over every cluster, per design §4 — and it gets the cut rule's
- * first half for free. The rule is `project(parent) > τ AND project(self) ≤ τ`; a group is only ever
- * reached by descending *through* the cluster whose step consumed it, and that descent happened
- * precisely because the step projected above τ. Every cluster of a group shares that step's sphere
- * and error, so the parent test is satisfied by the act of arriving.
- *
- * The residency clamp degenerates here: the whole file is in memory, so nothing is ever
- * non-selectable and a leaf is the only reason to stop early.
- *
- * @param {VGeoContainer} container
- * @param {VGeoCutView} view
- * @returns {VGeoCut}
- */
-export function vgeo_select_cut(container, view) {
-    assert.greaterThan(container.pages.length, 0, 'container.pages.length');
-
-    const started = performance.now();
-
-    const cut = new VGeoCut();
-
-    const k = view.screen_height / (2 * Math.tan(view.fov_y * 0.5));
-
-    /**
-     * Groups already queued, keyed `page · 65536 + group`. A group is referenced by every sibling
-     * cluster of the step that consumed it, so without this the traversal would expand it once per
-     * parent and the cut would carry duplicates.
-     *
-     * @type {Set<number>}
-     */
-    const queued = new Set();
-
-    /**
-     * @type {Set<number>}
-     */
-    const pages = new Set();
-
-    /**
-     * Page index and group index, interleaved.
-     * @type {number[]}
-     */
-    const stack = [];
-
-    const root = container.pages[0];
-
-    for (let group = 0; group < root.group_parent_count.length; group++) {
-        // no cluster anywhere refines into this group, so it is the top of the DAG and selectable
-        // with nothing above it
-        if (root.group_parent_count[group] === 0) {
-            queued.add(group);
-            stack.push(0, group);
-        }
-    }
-
-    while (stack.length > 0) {
-        const group = stack.pop();
-        const page_index = stack.pop();
-
-        const page = container.pages[page_index];
-
-        cut.groups_visited++;
-        pages.add(page_index);
-
-        const first = page.group_cluster_first[group];
-        const count = page.group_cluster_count[group];
-
-        for (let i = 0; i < count; i++) {
-            const id = page.cluster_base + first + i;
-
-            cut.clusters_tested++;
-
-            /*
-             Culling on `self_sphere` rather than on the tight `bounds_sphere`, because this decides
-             the subtree as well as the cluster: monotonicity makes a cluster's self sphere contain
-             every descendant's geometry, so a self sphere outside the frustum means nothing under
-             it can be on screen either.
-             */
-            if (view.cull_enabled
-                && sphere_outside_frustum(view.frustum, container.self_sphere, id * 4)) {
-                cut.culled++;
-                continue;
-            }
-
-            const child_ref = container.child_ref[id];
-
-            const self_px = project_error(
-                container.self_error[id], container.self_sphere, id * 4, view.eye, k
-            );
-
-            if (self_px <= view.tau || child_ref === VGEO_NO_CHILD) {
-                cut.clusters.push(id);
-                cut.triangle_count += container.triangle_count[id];
-                cut.vertex_count += container.vertex_count[id];
-                continue;
-            }
-
-            const child_page = child_ref === VGEO_SAME_PAGE ? page_index : page.child_pages[child_ref];
-            const child_group = container.child_group[id];
-
-            const key = child_page * 65536 + child_group;
-
-            if (!queued.has(key)) {
-                queued.add(key);
-                stack.push(child_page, child_group);
-            }
-        }
-    }
-
-    cut.pages_touched = pages.size;
-    cut.duration_ms = performance.now() - started;
-
-    return cut;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-//  Turning a cut into drawable geometry
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * What a cluster's colour is keyed on.
- *
- * The two normal modes are not keyed on the cluster at all: they paint every vertex with its own
- * direction, and the cluster boundaries go with it. `stored normal` is the container's own
- * {@link VGEO_ATTRIBUTE.NORMAL}, decoded out of the payload — the only mode that shows an attribute
- * the file carries rather than something derived from it. `geometric normal` is the area-weighted
- * normal of the decoded triangles, which is what every other mode shades with. The pair is the
- * point: they agree where the builder's normals still describe the geometry it shipped, and a
- * source with no normals at all makes the first one flat.
- *
- * @enum {string}
- */
-export const VGEO_COLOR_MODE = {
-    Cluster: 'cluster',
-    Group: 'group',
-    Page: 'page',
-    Error: 'error',
-    StoredNormal: 'stored normal',
-    GeometricNormal: 'geometric normal',
-};
-
-/**
- * Key colours are spread by the golden ratio so that adjacent ids never land on adjacent hues —
- * neighbouring clusters are exactly what has to be told apart.
- * @type {number}
- */
-const HUE_STEP = 0.6180339887498949;
-
-/**
- * @param {number} hue in `[0, 1)`
- * @param {number} saturation
- * @param {number} value
- * @param {Float32Array} out
- * @param {number} offset
- */
-function hsv_to_rgb(hue, saturation, value, out, offset) {
-    const sector = hue * 6;
-    const i = Math.floor(sector);
-    const f = sector - i;
-
-    const p = value * (1 - saturation);
-    const q = value * (1 - saturation * f);
-    const t = value * (1 - saturation * (1 - f));
-
-    switch (i % 6) {
-        case 0:
-            out[offset] = value; out[offset + 1] = t; out[offset + 2] = p;
-            break;
-        case 1:
-            out[offset] = q; out[offset + 1] = value; out[offset + 2] = p;
-            break;
-        case 2:
-            out[offset] = p; out[offset + 1] = value; out[offset + 2] = t;
-            break;
-        case 3:
-            out[offset] = p; out[offset + 1] = q; out[offset + 2] = value;
-            break;
-        case 4:
-            out[offset] = t; out[offset + 1] = p; out[offset + 2] = value;
-            break;
-        default:
-            out[offset] = value; out[offset + 1] = p; out[offset + 2] = q;
-            break;
-    }
-}
-
-/**
- * Key lights, baked into vertex colour.
- *
- * The direct path carries position and colour per vertex and nothing else — no normal reaches the
- * shader — so shading happens here, once per cut, against normals derived from the decoded
- * triangles. Two opposed lights and a generous ambient, so that no part of the surface is black and
- * every cluster's colour stays readable wherever it faces.
- *
- * @type {number[]}
- */
-const KEY_LIGHT = [0.35, 0.78, 0.52];
-
-/**
- * @type {number[]}
- */
-const FILL_LIGHT = [-0.55, -0.25, -0.79];
-
-/**
- * Ceiling on a baked colour's brightest channel.
- *
- * The pass draws at `AfterTransparency`, so everything it writes still goes through the tonemapper,
- * and the tonemapper desaturates as it approaches white. Pushed to 1.0 the clusters come out pastel
- * and stop being tellable apart, which defeats the only thing the colour is for — so the shading
- * range is deliberately kept below it.
- *
- * @type {number}
- */
-const COLOR_CEILING = 0.9;
-
-/**
- * One cluster's worth of decoded stored normals, reused across clusters.
- *
- * {@link VGEO_MAX_CLUSTER_VERTEX_COUNT} is the format's ceiling on a cluster and
- * {@link vgeo_validate_container} holds every file to it, so this is never short.
- *
- * @type {Float32Array}
- */
-const stored_normals = new Float32Array(VGEO_MAX_CLUSTER_VERTEX_COUNT * 3);
-
-/**
- * One decoded direction, on its way from the octahedral codec into a caller's array.
- * @type {Float32Array}
- */
-const scratch_direction = new Float32Array(3);
-
-/**
- * Decode one cluster's stored normal section into unit vectors.
- *
- * The section is one octahedral `u32` per vertex, or a single word for the whole cluster when the
- * encoder found every vertex agreeing — which is also what a source lacking normals encodes to, so
- * the constant case is the ordinary one and not an exception. A stride of zero is what reads it:
- * every vertex fetches the same word, and the loop does not have to know which case it is in.
- *
- * @param {VGeoContainer} container
- * @param {DataView} data over the whole file
- * @param {number} id reader cluster id
- * @param {Float32Array} out at least `3 * container.vertex_count[id]` long
- */
-function vgeo_read_cluster_normals(container, data, id, out) {
-    const vertex_count = container.vertex_count[id];
-
-    // out is sized for the format's ceiling, so this fires only on a file that already broke it —
-    // and a short write would come out as a handful of quietly wrong colours instead
-    assert.greaterThanOrEqual(out.length, vertex_count * 3, 'out must hold three components per cluster vertex');
-
-    const encoding_flags = container.encoding_flags[id];
-
-    const page = container.pages[container.page_of_cluster[id]];
-
-    const at = page.payload_base
-        + container.payload_offset[id]
-        + vgeo_payload_attribute_offset(
-            VGEO_ATTRIBUTE.NORMAL, vertex_count, container.triangle_count[id], encoding_flags
-        );
-
-    const stride = (encoding_flags & NORMAL_COMPRESSION_FLAG) === 0 ? 4 : 0;
-
-    for (let i = 0; i < vertex_count; i++) {
-        const word = data.getUint32(at + i * stride, LE);
-
-        const u = ((word & 0xFFFF) / UINT16_MAX) * 2 - 1;
-        const v = (((word >>> 16) & 0xFFFF) / UINT16_MAX) * 2 - 1;
-
-        decode_octahedron_to_unit(scratch_direction, 0, u, v);
-
-        /*
-         The encoder hands the octahedral codec `(nx, nz, ny)` — Shade's own convention, matched so
-         that a `.vgeo` payload is byte for byte a `MeshletBatch` one — so the decode comes back in
-         that order and has to be put back.
-         */
-        out[i * 3] = scratch_direction[0];
-        out[i * 3 + 1] = scratch_direction[2];
-        out[i * 3 + 2] = scratch_direction[1];
-    }
-}
-
-/**
- * Paint a run of vertices with their own directions and no shading: `rgb = n · 0.5 + 0.5`, scaled
- * by {@link COLOR_CEILING} for the same reason every other mode is.
- *
- * Unlit on purpose. A direction multiplied by how much light it happens to catch is unreadable
- * exactly where reading it matters — a normal facing away from both lights would come out black,
- * and black is not a direction.
- *
- * The tonemapper still has the last word on what reaches the screen, so this is a direction to be
- * read and not a value to be measured.
- *
- * @param {Float32Array} colors four per vertex
- * @param {number} first index of the run's first vertex
- * @param {number} count vertices in the run
- * @param {Float32Array} directions unit vectors, three components apiece
- * @param {number} directions_offset index of the run's first component within `directions`
- */
-function paint_directions(colors, first, count, directions, directions_offset) {
-    for (let i = 0; i < count; i++) {
-        const d = directions_offset + i * 3;
-        const o = (first + i) * 4;
-
-        colors[o] = COLOR_CEILING * (directions[d] * 0.5 + 0.5);
-        colors[o + 1] = COLOR_CEILING * (directions[d + 1] * 0.5 + 0.5);
-        colors[o + 2] = COLOR_CEILING * (directions[d + 2] * 0.5 + 0.5);
-        colors[o + 3] = 1;
-    }
-}
-
-/**
- * A cut, decoded into one geometry.
- *
- * Nothing about it depends on where the camera is: the mesh is drawn solid and the depth buffer
- * orders it, so the triangle list is uploaded once when the cut is taken and never touched again.
- */
-export class VGeoCutGeometry {
-    /**
-     * Position and colour, indexed by {@link triangles}.
-     * @type {Geometry}
-     */
-    geometry = new Geometry();
-
-    /**
-     * `3 * triangle_count` — the full triangle list, in cluster order, and the geometry's index.
-     * @type {Uint32Array}
-     */
-    triangles = new Uint32Array(0);
-
-    /**
-     * @type {number}
-     */
-    triangle_count = 0;
-
-    /**
-     * @type {number}
-     */
-    vertex_count = 0;
-}
-
-/**
- * Decode the selected clusters into one geometry.
- *
- * Payloads are `SHADE_MESHLET_V1`'s (format §8): the index section first, three 8-bit local indices
- * per triangle, then the attribute sections. Position is always read — it is raw float32, never
- * constant-compressed — and the stored normal section only when a normal display asks for it,
- * because the direct path carries position and colour per vertex and nowhere to put the rest.
- *
- * @param {VGeoContainer} container
- * @param {VGeoCut} cut
- * @param {VGEO_COLOR_MODE} color_mode
- * @returns {VGeoCutGeometry}
- */
-export function vgeo_build_cut_geometry(container, cut, color_mode) {
-    const vertex_count = cut.vertex_count;
-    const triangle_count = cut.triangle_count;
-
-    const positions = new Float32Array(vertex_count * 3);
-    const colors = new Float32Array(vertex_count * 4);
-    const normals = new Float32Array(vertex_count * 3);
-
-    const result = new VGeoCutGeometry();
-
-    result.triangles = new Uint32Array(triangle_count * 3);
-    result.triangle_count = triangle_count;
-    result.vertex_count = vertex_count;
-
-    const bytes = container.page_bytes;
-    const triangles = result.triangles;
-
-    /**
-     * The decoded pages, addressed a word at a time. A `DataView` has no alignment requirement,
-     * which is what an encoded attribute word needs: its offset is the format's, not the browser's.
-     * @type {DataView}
-     */
-    const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-
-    /*
-     The error ramp spans the *cut's* own errors, not the file's. Normalizing against the coarsest
-     error in the container would be defensible and useless: a fine cut's clusters all sit orders of
-     magnitude below it and the whole model comes out one flat colour. What the question actually is
-     — which parts of this cut settled for more error than the rest — is a question about this cut.
-     */
-    let error_low = Number.POSITIVE_INFINITY;
-    let error_high = 0;
-
-    for (const id of cut.clusters) {
-        error_low = Math.min(error_low, container.self_error[id]);
-        error_high = Math.max(error_high, container.self_error[id]);
-    }
-
-    const error_span = error_high - error_low;
-
-    /**
-     * `[first vertex, first triangle]` of each selected cluster, so colour can be applied per
-     * cluster after the normals are known.
-     * @type {Uint32Array}
-     */
-    const cluster_vertex_first = new Uint32Array(cut.clusters.length);
-
-    let vertex_cursor = 0;
-    let triangle_cursor = 0;
-
-    for (let c = 0; c < cut.clusters.length; c++) {
-        const id = cut.clusters[c];
-
-        const cluster_vertices = container.vertex_count[id];
-        const cluster_triangles = container.triangle_count[id];
-
-        const page = container.pages[container.page_of_cluster[id]];
-        const payload = page.payload_base + container.payload_offset[id];
-
-        cluster_vertex_first[c] = vertex_cursor;
-
-        const position_at = payload + vgeo_payload_attribute_offset(
-            VGEO_ATTRIBUTE.POSITION,
-            cluster_vertices,
-            cluster_triangles,
-            container.encoding_flags[id]
-        );
-
-        /*
-         Copied out rather than viewed in place: a Float32Array view demands 4-byte alignment
-         against the *file's* buffer, which is a property of where the browser happened to put it
-         and not something the format promises.
-         */
-        const coordinates = new Float32Array(
-            bytes.slice(position_at, position_at + cluster_vertices * 12).buffer
-        );
-
-        positions.set(coordinates, vertex_cursor * 3);
-
-        for (let i = 0; i < cluster_triangles * 3; i++) {
-            triangles[triangle_cursor * 3 + i] = vertex_cursor + bytes[payload + i];
-        }
-
-        vertex_cursor += cluster_vertices;
-        triangle_cursor += cluster_triangles;
-    }
-
-    assert.equal(vertex_cursor, vertex_count, 'decoded vertices must match the cut');
-    assert.equal(triangle_cursor, triangle_count, 'decoded triangles must match the cut');
-
-    // Area-weighted vertex normals, which is all shading reads. Clusters share no vertices, so
-    // accumulating over the whole list still gives each cluster its own smoothing — the crease that
-    // leaves at a cluster seam is a feature here, not an artefact.
-    for (let t = 0; t < triangle_count; t++) {
-        const a = triangles[t * 3] * 3;
-        const b = triangles[t * 3 + 1] * 3;
-        const c = triangles[t * 3 + 2] * 3;
-
-        const abx = positions[b] - positions[a];
-        const aby = positions[b + 1] - positions[a + 1];
-        const abz = positions[b + 2] - positions[a + 2];
-
-        const acx = positions[c] - positions[a];
-        const acy = positions[c + 1] - positions[a + 1];
-        const acz = positions[c + 2] - positions[a + 2];
-
-        const nx = aby * acz - abz * acy;
-        const ny = abz * acx - abx * acz;
-        const nz = abx * acy - aby * acx;
-
-        normals[a] += nx; normals[a + 1] += ny; normals[a + 2] += nz;
-        normals[b] += nx; normals[b + 1] += ny; normals[b + 2] += nz;
-        normals[c] += nx; normals[c + 1] += ny; normals[c + 2] += nz;
-    }
-
-    // Normalized here rather than where they are read, because two things read them now — the
-    // shading, and `geometric normal` — and a direction is the same direction for both.
-    for (let v = 0; v < vertex_count; v++) {
-        const n = v * 3;
-
-        const length = Math.hypot(normals[n], normals[n + 1], normals[n + 2]);
-
-        // A vertex left with no area around it has no direction to give. Zero shades as ambient and
-        // displays as mid grey, and both say "nothing here" rather than inventing an answer.
-        const scale = length > 0 ? 1 / length : 0;
-
-        normals[n] *= scale;
-        normals[n + 1] *= scale;
-        normals[n + 2] *= scale;
-    }
-
-    const tint = new Float32Array(3);
-
-    for (let c = 0; c < cut.clusters.length; c++) {
-        const id = cut.clusters[c];
-
-        const first = cluster_vertex_first[c];
-        const count = container.vertex_count[id];
-
-        if (color_mode === VGEO_COLOR_MODE.StoredNormal) {
-            vgeo_read_cluster_normals(container, data, id, stored_normals);
-
-            paint_directions(colors, first, count, stored_normals, 0);
-
-            continue;
-        }
-
-        if (color_mode === VGEO_COLOR_MODE.GeometricNormal) {
-            paint_directions(colors, first, count, normals, first * 3);
-
-            continue;
-        }
-
-        let key;
-
-        switch (color_mode) {
-            case VGEO_COLOR_MODE.Group:
-                key = container.page_of_cluster[id] * 65536 + container.group_of_cluster[id];
-                break;
-            case VGEO_COLOR_MODE.Page:
-                key = container.page_of_cluster[id];
-                break;
-            default:
-                key = id;
-                break;
-        }
-
-        if (color_mode === VGEO_COLOR_MODE.Error) {
-            // cool where the cut is refined, hot where it settled for the most error
-            const t = error_span > 0 ? (container.self_error[id] - error_low) / error_span : 0;
-
-            hsv_to_rgb(0.68 * (1 - t), 0.9, 1, tint, 0);
-        } else {
-            hsv_to_rgb((key * HUE_STEP) % 1, 0.85, 1, tint, 0);
-        }
-
-        const end = first + count;
-
-        for (let v = first; v < end; v++) {
-            const n = v * 3;
-
-            const nx = normals[n];
-            const ny = normals[n + 1];
-            const nz = normals[n + 2];
-
-            const key_term = Math.max(
-                0, nx * KEY_LIGHT[0] + ny * KEY_LIGHT[1] + nz * KEY_LIGHT[2]
-            );
-
-            const fill_term = Math.max(
-                0, nx * FILL_LIGHT[0] + ny * FILL_LIGHT[1] + nz * FILL_LIGHT[2]
-            );
-
-            const shade = COLOR_CEILING * (0.22 + 0.60 * key_term + 0.18 * fill_term);
-
-            colors[v * 4] = tint[0] * shade;
-            colors[v * 4 + 1] = tint[1] * shade;
-            colors[v * 4 + 2] = tint[2] * shade;
-            colors[v * 4 + 3] = 1;
-        }
-    }
-
-    result.geometry.addAttribute(Attribute.from(positions, 3, StandardAttributes.Position));
-    result.geometry.addAttribute(Attribute.from(colors, 4, StandardAttributes.Color));
-    result.geometry.index = Attribute.from(result.triangles, 1, StandardAttributes.Index);
-
-    return result;
-}
-
-/**
- * Clear the frame's depth, so that the cut is the only thing in it.
- *
- * **The renderer does not do this when there is nothing to rasterize.** Depth is cleared as a side
- * effect of drawing the first opaque bucket, and this viewer's `Scene` holds a light and no meshes,
- * so that draw never happens. The renderer also ping-pongs two depth textures frame to frame — so
- * left alone, the cut is depth-tested against *its own depth from two frames ago*, and dissolves
- * into holes wherever the camera has moved since. It reads as missing geometry and it is not.
- *
- * A real scene needs none of this and must not have it: the cut has to be occluded by whatever the
- * scene put in the depth buffer, which is why the draw itself loads rather than clears.
- *
- * It runs immediately before the draw rather than at the top of the frame, so everything earlier
- * that reads depth still sees the previous frame's. With nothing in the scene there is nothing for
- * those passes to occlude, and the alternative is a second registration on another phase to save a
- * result that is empty either way.
- *
- * @param {FrameGraph} graph
- * @param {number} depth
- * @returns {number} the depth handle to draw against
- */
-function vgeo_graph_clear_depth(graph, depth) {
-    const data = {};
-
-    const pass = graph.add('vgeo/clear depth', data, (data, resources, context) => {
-        const texture = resources.get(data.depth);
-
-        // no draws — the clear is the load op, and ending the pass immediately is what performs it
-        context.encoder.beginRenderPass({
-            label: "vgeo/clear depth",
-            colorAttachments: [],
-            depthStencilAttachment: {
-                view: texture.obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
-                depthLoadOp: "clear",
-                depthStoreOp: "store",
-                depthClearValue: DEPTH_BACKGROUND_VALUE,
-            },
-        }).end();
-    });
-
-    data.depth = pass.write(depth);
-
-    return data.depth;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-//  Harness
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * @param {number} value
- * @returns {string}
- */
-function thousands(value) {
-    return value.toLocaleString('en-US');
-}
-
-/**
- * @param {[string, string][]} entries
- * @returns {string} one label/value row apiece
- */
-function panel_table(entries) {
-    return entries
-        .map(([key, value]) => `<div class="row"><span class="muted">${key}</span><span>${value}</span></div>`)
-        .join('');
-}
-
-/**
- * @param {number} bytes
- * @returns {string}
- */
-function human_bytes(bytes) {
-    if (bytes < 1024) {
-        return `${bytes} B`;
-    }
-
-    if (bytes < 1024 * 1024) {
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    }
-
-    if (bytes < 1024 * 1024 * 1024) {
-        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-    }
-
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
-}
-
-/**
- * What the pages cost stored against what they cost decoded, and under which codec.
- *
- * Stored is the number that gets fetched and the number that sits on disk; decoded is the number a
- * resident page costs in RAM. The codec is per frame, so a file can genuinely be a mixture — the
- * encoder stores a page raw whenever compressing it would not have shrunk it — and naming all of
- * them is more honest than naming whichever one happened to come first.
- *
- * @param {VGeoContainer} container
- * @returns {string}
- */
-function page_storage(container) {
-    const codec = Array.from(new Set(container.pages.map((page) => page.codec)))
-        .map(vgeo_codec_name)
-        .join(' + ');
-
-    const ratio = container.decoded_page_bytes / Math.max(container.stored_page_bytes, 1);
-
-    return `${human_bytes(container.stored_page_bytes)} stored`
-        + ` · ${human_bytes(container.decoded_page_bytes)} decoded`
-        + ` · ${codec} ${ratio.toFixed(2)}x`;
-}
-
-const PANEL_CSS = `
-#vgeo-panel {
-    position: absolute; top: 0; right: 0; width: 340px; max-height: 100vh; overflow-y: auto;
-    padding: 12px 14px; box-sizing: border-box;
-    font: 12px/1.45 ui-monospace, "Cascadia Mono", Consolas, monospace;
-    color: #dfe6ee; background: rgba(12, 16, 22, 0.88);
-    border-left: 1px solid #2b3947;
-}
-#vgeo-panel h1 { margin: 0 0 8px; font-size: 13px; letter-spacing: 0.06em; color: #7fd2ff; }
-#vgeo-panel h2 {
-    margin: 14px 0 6px; font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase;
-    color: #6b7c8d; border-bottom: 1px solid #24313d; padding-bottom: 3px;
-}
-#vgeo-panel .row { display: flex; justify-content: space-between; gap: 8px; }
-#vgeo-panel .row span:last-child { color: #f2f6fa; }
-#vgeo-panel .count { font-size: 30px; line-height: 1.1; color: #8fe388; }
-#vgeo-panel .muted { color: #6b7c8d; }
-#vgeo-panel .bad { color: #ff8a7a; }
-#vgeo-panel .good { color: #8fe388; }
-#vgeo-panel button {
-    width: 100%; margin: 8px 0 2px; padding: 7px; cursor: pointer;
-    font: inherit; color: #061018; background: #7fd2ff; border: 0; border-radius: 3px;
-}
-#vgeo-panel button:hover { background: #a5e0ff; }
-#vgeo-panel label { display: flex; align-items: center; gap: 6px; margin: 3px 0; cursor: pointer; }
-#vgeo-panel input[type=range] { width: 100%; }
-#vgeo-panel select { width: 100%; font: inherit; background: #16202b; color: #dfe6ee; border: 1px solid #2b3947; padding: 3px; }
-#vgeo-panel ol { margin: 4px 0; padding-left: 18px; }
-#vgeo-drop {
-    position: absolute; inset: 0; display: none; align-items: center; justify-content: center;
-    font: 20px ui-monospace, monospace; color: #7fd2ff;
-    background: rgba(6, 12, 20, 0.82); border: 3px dashed #7fd2ff; box-sizing: border-box;
-}
-#vgeo-drop.active { display: flex; }
-`;
-
-/**
- * The viewer draws its clusters into the scene, at the phase a full-screen effect that should be
- * tonemapped with the rest of the frame belongs at.
- */
-class VGEOViewerExtension extends RenderExtension {
-    name = "vgeo viewer";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {VGeoViewer}
-     */
-    #viewer;
-
-    /**
-     * @param {VGeoViewer} viewer
-     */
-    constructor(viewer) {
-        super();
-
-        this.#viewer = viewer;
-    }
-
-    record(frame) {
-        this.#viewer.record(frame);
-    }
-}
-
-/**
- * The viewer. One container at a time, one cut at a time, and the cut only changes when asked.
- */
-class VGeoViewer {
-    /**
-     * @type {VGeoContainer|undefined}
-     */
-    #container = undefined;
-
-    /**
-     * @type {VGeoCutGeometry|undefined}
-     */
-    #cut_geometry = undefined;
-
-    /**
-     * @type {VGeoCut}
-     */
-    #cut = new VGeoCut();
-
-    /**
-     * @type {VGeoCutView}
-     */
-    #view = new VGeoCutView();
-
-    /**
-     * @type {DynamicMeshBatch}
-     */
-    #batch = new DynamicMeshBatch();
-
-    /**
-     * @type {DynamicMesh|undefined}
-     */
-    #mesh = undefined;
-
-    /**
-     * A cut is a solid surface, so it is drawn as one: opaque, writing depth, and ordered by the
-     * depth buffer rather than by anything this file does.
-     *
-     * @type {GPUDynamicMeshRenderer}
-     */
-    #dynamic = new GPUDynamicMeshRenderer();
-
-    /**
-     * Where the camera stood when the current cut was taken, so the panel can say how far you have
-     * wandered from the decision you are looking at.
-     * @type {Float32Array}
-     */
-    #cut_eye = new Float32Array(3);
-
-    /**
-     * @type {Float32Array}
-     */
-    #eye = new Float32Array(3);
-
-    /**
-     * @type {boolean}
-     */
-    #auto_adapt = false;
-
-    /**
-     * @type {VGEO_COLOR_MODE}
-     */
-    #color_mode = VGEO_COLOR_MODE.Cluster;
-
-    /**
-     * @type {string}
-     */
-    #status = 'drop a .vgeo file anywhere on the page';
-
-    /**
-     * @type {string}
-     */
-    #file_label = '';
-
-    /**
-     * @type {number}
-     */
-    #file_bytes = 0;
-
-    /**
-     * @type {number}
-     */
-    #read_ms = 0;
-
-    /**
-     * @type {number}
-     */
-    #build_ms = 0;
-
-    constructor() {
-        this.canvas = document.createElement('canvas');
-        this.renderer = new Renderer();
-        this.camera = new PerspectiveCamera();
-        this.scene = new Scene();
-
-        this.#dynamic.opaque = true;
-    }
-
-    /**
-     * @returns {Promise<void>}
-     */
-    async start() {
-        document.body.style.margin = '0';
-        document.body.style.overflow = 'hidden';
-        document.body.style.background = '#070b10';
-
-        this.canvas.style.position = 'absolute';
-        this.canvas.style.inset = '0';
-        this.canvas.style.outline = 'none';
-
-        // the orbital controller attaches a KeyboardDevice, and a canvas cannot receive key events
-        // without being focusable
-        this.canvas.tabIndex = 0;
-
-        document.body.appendChild(this.canvas);
-
-        this.canvas.focus();
-
-        await this.renderer.initialize({ context: this.canvas.getContext('webgpu') });
-
-        /*
-         Everything that would move the image for reasons unrelated to the cut is off. Automatic
-         exposure in particular: it adapts to whatever is on screen, so the same cluster would read
-         a different colour depending on how much of the model is in frame, which is exactly the
-         signal this tool is trying to show.
-         */
-        this.renderer.feature_automatic_exposure_enabled = false;
-        this.renderer.feature_taa_enabled = true;
-        this.renderer.feature_bloom_enabled = false;
-        this.renderer.feature_ssr_enabled = false;
-        this.renderer.feature_ssao_enabled = true;
-        this.renderer.feature_shadows_enabled = false;
-        this.renderer.feature_lpv_enabled = false;
-        this.renderer.pixel_ratio = 1;
-
-        this.scene.lights.add(make_sunlight({ intensity: 3 }));
-
-        this.camera.near = 0.05;
-        this.camera.far = 500;
-        this.camera.fov = 55 * DEG_TO_RAD;
-        this.camera.transform.position.set(0, 0.5, 2);
-        this.camera.transform.lookAt(Vector3.zero);
-
-        this.controller = new OrbitalCameraController(this.camera, this.canvas);
-        this.controller.distanceLimits.min = 1e-4;
-        this.controller.distanceLimits.max = 1e5;
-
-        this.#build_interface();
-        this.#fit_to_window();
-
-        window.addEventListener('resize', () => this.#fit_to_window());
-
-        this.renderer.add_extension(new VGEOViewerExtension(this));
-
-        create_frame_loop((dt) => this.#frame(dt));
-
-        const requested = new URL(window.location.href).searchParams.get('file');
-
-        if (requested !== null) {
-            await this.load_url(requested);
-        }
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        const graph = frame.graph;
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#dynamic.graph_draw({
-            graph,
-            batch: this.#batch,
-            color: scene.color,
-            depth: vgeo_graph_clear_depth(graph, frame.get(ViewTextures).depth),
-            camera: frame.view.camera.buffer,
-        });
-    }
-
-    #fit_to_window() {
-        const width = window.innerWidth;
-        const height = window.innerHeight;
-
-        this.canvas.width = width;
-        this.canvas.height = height;
-
-        this.renderer.resize(width, height);
-
-        this.camera.aspect = this.renderer.aspect_ratio;
-
-        this.#view.screen_height = height;
-        this.#view.fov_y = this.camera.fov;
-    }
-
-    /**
-     * @param {number} dt seconds
-     */
-    #frame(dt) {
-        this.controller.update(dt);
-
-        const position = this.camera.transform.position;
-
-        const moved = position.x !== this.#eye[0]
-            || position.y !== this.#eye[1]
-            || position.z !== this.#eye[2];
-
-        this.#eye[0] = position.x;
-        this.#eye[1] = position.y;
-        this.#eye[2] = position.z;
-
-        if (moved && this.#auto_adapt) {
-            this.adapt();
-        }
-
-        this.renderer.render(this.camera, this.scene, dt);
-
-        if (moved) {
-            this.#refresh_cut();
-        }
-    }
-
-    /**
-     * Re-render the cut readout alone.
-     *
-     * Every number under it moves as the camera does — the drift on every frame, and the whole lot
-     * on every adapt when `follow the camera` is on. Rebuilding the *whole* panel at that rate would
-     * also rebuild the controls, which is how a slider stops being draggable mid-drag; this section
-     * holds no controls, so replacing it is free of that.
-     */
-    #refresh_cut() {
-        const host = this.panel.querySelector('#vgeo-cut');
-
-        if (host === null) {
-            return;
-        }
-
-        host.innerHTML = this.#cut_html();
-    }
-
-    /**
-     * The cut readout — the cluster count first, because it is the number the tool exists to show.
-     *
-     * @returns {string}
-     */
-    #cut_html() {
-        const cut = this.#cut;
-
-        return `<div class="count">${thousands(cut.clusters.length)}</div>`
-            + `<div class="muted" style="margin-bottom:6px">clusters in the current cut</div>`
-            + panel_table([
-                ['triangles', thousands(cut.triangle_count)],
-                ['groups', thousands(cut.groups_visited)],
-                ['pages resident', thousands(cut.pages_touched)],
-                ['clusters tested', thousands(cut.clusters_tested)],
-                ['culled subtrees', thousands(cut.culled)],
-                ['select / build', `${cut.duration_ms.toFixed(1)} / ${this.#build_ms.toFixed(1)} ms`],
-                ['camera drift', `${this.#drift().toExponential(2)} u`],
-            ]);
-    }
-
-    /**
-     * How far the camera has moved since the cut on screen was selected.
-     * @returns {number}
-     */
-    #drift() {
-        return Math.hypot(
-            this.#eye[0] - this.#cut_eye[0],
-            this.#eye[1] - this.#cut_eye[1],
-            this.#eye[2] - this.#cut_eye[2]
-        );
-    }
-
-    /**
-     * Take a fresh cut at wherever the camera is standing, and build the geometry for it.
-     */
-    adapt() {
-        if (this.#container === undefined) {
-            return;
-        }
-
-        // the frustum is derived from matrices the renderer refreshes during its own frame, and an
-        // adapt can land before one has run — a cut culled against last frame's planes would be a
-        // silent, hard-to-see wrong answer
-        this.camera.update();
-
-        this.#view.eye.set(this.#eye);
-        this.#view.screen_height = this.canvas.height;
-        this.#view.fov_y = this.camera.fov;
-        this.#view.frustum.set(this.camera.frustum);
-
-        this.#cut = vgeo_select_cut(this.#container, this.#view);
-
-        const started = performance.now();
-
-        const previous = this.#cut_geometry;
-
-        this.#cut_geometry = vgeo_build_cut_geometry(this.#container, this.#cut, this.#color_mode);
-
-        this.#build_ms = performance.now() - started;
-
-        this.#batch.clear();
-
-        // Residency is keyed on the geometry and deliberately survives leaving the batch, so the
-        // cut that was just replaced would hold its buffers forever otherwise — and this tool
-        // replaces one on every drag of the tau slider.
-        if (previous !== undefined) {
-            this.#dynamic.release(previous.geometry);
-        }
-
-        this.#mesh = DynamicMesh.from(this.#cut_geometry.geometry);
-        this.#mesh.updateMatrices();
-
-        this.#batch.add(this.#mesh);
-
-        this.#cut_eye.set(this.#eye);
-    }
-
-    /**
-     * @param {ArrayBuffer} array_buffer
-     * @param {string} label
-     */
-    load(array_buffer, label) {
-        this.#file_label = label;
-        this.#file_bytes = array_buffer.byteLength;
-
-        const started = performance.now();
-
-        try {
-            this.#container = vgeo_read_container(array_buffer);
-        } catch (e) {
-            this.#container = undefined;
-            this.#cut_geometry = undefined;
-            this.#batch.clear();
-            this.#status = String(e.message ?? e);
-            this.#refresh_panel();
-
-            throw e;
-        }
-
-        this.#read_ms = performance.now() - started;
-        this.#status = '';
-
-        this.#frame_camera();
-        this.adapt();
-        this.#refresh_panel();
-    }
-
-    /**
-     * @param {string} url
-     * @returns {Promise<void>}
-     */
-    async load_url(url) {
-        this.#status = `fetching ${url}`;
-        this.#refresh_panel();
-
-        const response = await fetch(url);
-
-        if (!response.ok) {
-            this.#status = `${url} — HTTP ${response.status}`;
-            this.#refresh_panel();
-
-            return;
-        }
-
-        this.load(await response.arrayBuffer(), url.split('/').pop());
-    }
-
-    /**
-     * Put the camera where the whole asset is on screen, and scale the clip range to it — vgeo
-     * assets are authored at whatever scale the source used, and the Stanford models are a tenth of
-     * a unit across.
-     */
-    #frame_camera() {
-        const sphere = this.#container.object_sphere;
-
-        const radius = Math.max(sphere[3], 1e-6);
-        const center = new Vector3(sphere[0], sphere[1], sphere[2]);
-
-        const distance = radius / Math.tan(this.camera.fov * 0.5) * 1.15;
-
-        const eye = new Vector3(0.55, 0.42, 0.72);
-
-        eye.normalize();
-        eye.multiplyScalar(distance);
-        eye.add(center);
-
-        this.camera.near = radius * 0.005;
-        this.camera.far = radius * 200;
-
-        this.controller.distanceLimits.min = radius * 0.02;
-        this.controller.distanceLimits.max = radius * 200;
-        this.controller.movement_speed_scale = radius;
-
-        this.controller.look(eye, center);
-
-        this.#eye[0] = eye.x;
-        this.#eye[1] = eye.y;
-        this.#eye[2] = eye.z;
-    }
-
-    #build_interface() {
-        const style = document.createElement('style');
-
-        style.textContent = PANEL_CSS;
-        document.head.appendChild(style);
-
-        const drop = document.createElement('div');
-
-        drop.id = 'vgeo-drop';
-        drop.textContent = 'drop a .vgeo file';
-        document.body.appendChild(drop);
-
-        let drag_depth = 0;
-
-        window.addEventListener('dragenter', (event) => {
-            event.preventDefault();
-            drag_depth++;
-            drop.classList.add('active');
-        });
-
-        window.addEventListener('dragover', (event) => event.preventDefault());
-
-        window.addEventListener('dragleave', () => {
-            drag_depth = Math.max(0, drag_depth - 1);
-
-            if (drag_depth === 0) {
-                drop.classList.remove('active');
-            }
-        });
-
-        window.addEventListener('drop', async (event) => {
-            event.preventDefault();
-
-            drag_depth = 0;
-            drop.classList.remove('active');
-
-            const file = event.dataTransfer.files[0];
-
-            if (file === undefined) {
-                return;
-            }
-
-            this.#status = `reading ${file.name}`;
-            this.#refresh_panel();
-
-            this.load(await file.arrayBuffer(), file.name);
-        });
-
-        this.panel = document.createElement('div');
-        this.panel.id = 'vgeo-panel';
-        document.body.appendChild(this.panel);
-
-        this.#refresh_panel();
-    }
-
-    /**
-     * @param {string} id
-     * @param {function(HTMLElement): void} bind
-     */
-    #wire(id, bind) {
-        const element = this.panel.querySelector(`#${id}`);
-
-        if (element !== null) {
-            bind(element);
-        }
-    }
-
-    #refresh_panel() {
-        const container = this.#container;
-
-        const header = [`<h1>.vgeo format viewer</h1>`];
-
-        if (this.#status !== '') {
-            header.push(`<div class="muted">${this.#status}</div>`);
-        }
-
-        if (container === undefined) {
-            this.panel.innerHTML = header.join('');
-
-            return;
-        }
-
-        const defects = container.defects;
-
-        const validation = defects.length === 0
-            ? `<div class="good">container valid — every invariant holds</div>`
-            : `<div class="bad">${defects.length} defect(s)</div><ol class="bad">${
-                defects.slice(0, 12).map((d) => `<li>${d.toString()}</li>`).join('')
-            }</ol>`;
-
-        const rows = [
-            ['file', `${this.#file_label} · ${human_bytes(this.#file_bytes)}`],
-            ['pages', page_storage(container)],
-            ['format', `v${container.format_version} · encoding ${container.payload_encoding}`],
-            ['asset id', container.asset_id.slice(0, 16)],
-            ['source', `${thousands(container.source_face_count)} tris / ${thousands(container.source_vertex_count)} verts`],
-            ['contents', `${thousands(container.cluster_count)} clusters · ${thousands(container.pages.length)} pages · ${container.levels.length} levels`],
-            ['per-vertex normals', `${thousands(container.per_vertex_normal_cluster_count)} / ${thousands(container.cluster_count)} clusters`],
-            ['read', `${this.#read_ms.toFixed(1)} ms`],
-        ];
-
-        this.panel.innerHTML = header.join('')
-            + `<h2>container</h2>${panel_table(rows)}`
-            + `<h2>validation</h2>${validation}`
-            + `<h2>cut</h2>`
-            + `<div id="vgeo-cut">${this.#cut_html()}</div>`
-            + `<h2>selection</h2>`
-            + `<div class="row"><span class="muted">tau</span><span id="vgeo-tau-value">${this.#view.tau.toFixed(2)} px</span></div>`
-            + `<input id="vgeo-tau" type="range" min="-1.3" max="1.7" step="0.01" value="${Math.log10(this.#view.tau)}">`
-            + `<button id="vgeo-adapt">adapt to view</button>`
-            + `<label><input id="vgeo-auto" type="checkbox" ${this.#auto_adapt ? 'checked' : ''}> follow the camera</label>`
-            + `<label><input id="vgeo-cull" type="checkbox" ${this.#view.cull_enabled ? 'checked' : ''}> frustum cull while selecting</label>`
-            + `<h2>display</h2>`
-            + `<select id="vgeo-color">`
-            + Object.values(VGEO_COLOR_MODE).map((mode) =>
-                `<option value="${mode}" ${mode === this.#color_mode ? 'selected' : ''}>colour by ${mode}</option>`
-            ).join('')
-            + `</select>`;
-
-        this.#wire('vgeo-adapt', (element) => {
-            element.onclick = () => {
-                this.adapt();
-                this.#refresh_panel();
-            };
-        });
-
-        this.#wire('vgeo-tau', (element) => {
-            element.oninput = () => {
-                this.#view.tau = Math.pow(10, Number(element.value));
-
-                this.adapt();
-                this.#refresh_panel();
-            };
-        });
-
-        this.#wire('vgeo-auto', (element) => {
-            element.onchange = () => {
-                this.#auto_adapt = element.checked;
-            };
-        });
-
-        this.#wire('vgeo-cull', (element) => {
-            element.onchange = () => {
-                this.#view.cull_enabled = element.checked;
-
-                this.adapt();
-                this.#refresh_panel();
-            };
-        });
-
-        this.#wire('vgeo-color', (element) => {
-            element.onchange = () => {
-                this.#color_mode = element.value;
-
-                this.adapt();
-                this.#refresh_panel();
-            };
-        });
-    }
-}
-
-const viewer = new VGeoViewer();
-
-window.__vgeo = viewer;
-
-viewer.start();
+/**
+ * A debug viewer for the `.vgeo` container.
+ *
+ * Drop a file onto the page and it is validated, decoded, and drawn — not as an asset, but as the
+ * *cut* the container's own metric selects: the clusters a runtime would draw, coloured so the
+ * seams between them are visible, with the cluster count on screen.
+ *
+ *   npm run dev
+ *   http://localhost:9000/index.html?entry=/src/mir-engine/meep/src/shade/renderer/geometry/virtual/format/prototypeVGEOFormatViewer.js
+ *
+ * `?file=/data/models/stanford/vgeo/bunny/<asset-id>.vgeo` loads one straight away, which is what
+ * makes a particular view of a particular asset a bookmark.
+ *
+ * **The cut is frozen until you ask for a new one.** "Adapt to view" re-runs the traversal at
+ * wherever the camera is standing now; everything after that is you flying around a decision taken
+ * from somewhere else, which is the only way to see what a cut actually selected. Turn `auto` on to
+ * watch it chase the camera instead.
+ *
+ * Drawing goes through Shade's **direct geometry path** — a {@link DynamicMesh} drawn straight from
+ * its attributes, no meshlet encode — because a cut is rebuilt from scratch every time it is
+ * adapted, and a meshlet build per adapt would price the tool out of being interactive. It is drawn
+ * *opaque* on that path ({@link GPUDynamicMeshRenderer.opaque}), so the depth buffer orders the
+ * cut's own triangles: a cut is a solid surface and nothing on the CPU can order one correctly.
+ *
+ * THROWAWAY, and deliberately self-contained. The container reader below is a *debug* reader: whole
+ * file, eager, everything resident. The runtime's is streaming and partial and belongs to M1;
+ * nothing here should be mistaken for its shape.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { UINT16_MAX } from "../../../../../core/binary/UINT16_MAX.js";
+import {
+    decode_octahedron_to_unit
+} from "../../../../../core/geom/3d/normal/octahedron/decode_octahedron_to_unit.js";
+import Vector3 from "../../../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../../../core/math/DEG_TO_RAD.js";
+import { OrbitalCameraController } from "../../../camera/orbital/index.js";
+import { PerspectiveCamera } from "../../../camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../../create_frame_loop.js";
+import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../../../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
+import { DEPTH_BACKGROUND_VALUE } from "../../../depth/DEPTH_BACKGROUND_VALUE.js";
+import { GPUDynamicMeshRenderer } from "../../../dynamic/GPUDynamicMeshRenderer.js";
+import { make_sunlight } from "../../../light/make_sunlight.js";
+import { FramePhase } from "../../../extension/FramePhase.js";
+import { RenderExtension } from "../../../extension/RenderExtension.js";
+import { SceneColor } from "../../../extension/SceneColor.js";
+import { ViewTextures } from "../../../extension/ViewTextures.js";
+import { Renderer } from "../../../Renderer.js";
+import { DynamicMesh } from "../../../scene/DynamicMesh.js";
+import { DynamicMeshBatch } from "../../../scene/DynamicMeshBatch.js";
+import { Scene } from "../../../scene/Scene.js";
+import { Attribute } from "../../Attribute.js";
+import { Geometry } from "../../Geometry.js";
+import { StandardAttributes } from "../../StandardAttributes.js";
+import { VGEO_ATTRIBUTE } from "./attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "./attribute/VGEO_ATTRIBUTES.js";
+import { VGEO_CHILD_OFFSET } from "./frame/VGEO_CHILD_OFFSET.js";
+import { VGEO_CHILD_TABLE_ENTRY_SIZE } from "./frame/VGEO_CHILD_TABLE_ENTRY_SIZE.js";
+import { VGEO_CLUSTER_OFFSET } from "./cluster/VGEO_CLUSTER_OFFSET.js";
+import { VGEO_CLUSTER_RECORD_SIZE } from "./cluster/VGEO_CLUSTER_RECORD_SIZE.js";
+import { vgeo_codec_name } from "./frame/vgeo_codec_name.js";
+import { VGEO_CODEC_LZ4 } from "./frame/VGEO_CODEC_LZ4.js";
+import { VGEO_CODEC_RAW } from "./frame/VGEO_CODEC_RAW.js";
+import { vgeo_decode_frame_blob } from "./frame/vgeo_decode_frame_blob.js";
+import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
+import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
+import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
+import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
+import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
+import { VGEO_LEVEL_OFFSET } from "./header/VGEO_LEVEL_OFFSET.js";
+import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
+import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
+import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
+import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
+import { VGEO_PAGE_HEADER_SIZE } from "./page/VGEO_PAGE_HEADER_SIZE.js";
+import { VGEO_PAGE_OFFSET } from "./page/VGEO_PAGE_OFFSET.js";
+import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
+import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
+import { vgeo_payload_attribute_offset } from "./payload/vgeo_payload_attribute_offset.js";
+import { vgeo_validate_container } from "./vgeo_validate_container.js";
+
+/**
+ * Everything in the container is little-endian (`VGEO_FORMAT.md` §2).
+ * @type {boolean}
+ */
+const LE = true;
+
+/**
+ * The `encoding_flags` bit that says a cluster's normal section holds one constant-compressed word
+ * for the whole cluster instead of one per vertex.
+ * @type {number}
+ */
+const NORMAL_COMPRESSION_FLAG = VGEO_ATTRIBUTES[VGEO_ATTRIBUTE.NORMAL].compression_flag;
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  Reading
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * One page, decoded far enough to traverse.
+ */
+export class VGeoPageView {
+    /**
+     * Page index, which is also the frame ordinal.
+     * @type {number}
+     */
+    index = 0;
+
+    /**
+     * Byte offset of the decoded page's first byte in {@link VGeoContainer.page_bytes}.
+     * @type {number}
+     */
+    base = 0;
+
+    /**
+     * The codec its frame stored it under. Informational here — the page is decoded before anything
+     * reads it — and worth showing, because it is per page and a file can carry both.
+     * @type {number}
+     */
+    codec = 0;
+
+    /**
+     * Bytes the frame stores, before decoding.
+     * @type {number}
+     */
+    stored_size = 0;
+
+    /**
+     * Bytes the page occupies decoded.
+     * @type {number}
+     */
+    decoded_size = 0;
+
+    /**
+     * @type {number}
+     */
+    min_level = 0;
+
+    /**
+     * @type {number}
+     */
+    max_level = 0;
+
+    /**
+     * Absolute byte offset of this page's payload section.
+     * @type {number}
+     */
+    payload_base = 0;
+
+    /**
+     * Id of this page's first cluster in the reader's own flat numbering, which is page order and
+     * then cluster-table order. The format has no global cluster id; this exists so the arrays on
+     * {@link VGeoContainer} can be indexed by one.
+     * @type {number}
+     */
+    cluster_base = 0;
+
+    /**
+     * @type {number}
+     */
+    cluster_count = 0;
+
+    /**
+     * `child_ref -> page index`, read out of the frame's child table.
+     * @type {Uint32Array}
+     */
+    child_pages = new Uint32Array(0);
+
+    /**
+     * Per group: index of its first cluster within this page.
+     * @type {Uint16Array}
+     */
+    group_cluster_first = new Uint16Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    group_cluster_count = new Uint16Array(0);
+
+    /**
+     * How many clusters name this group as their child. Zero is what makes a group selectable with
+     * nothing above it — the root page's topmost groups, and only those.
+     * @type {Uint16Array}
+     */
+    group_parent_count = new Uint16Array(0);
+
+    /**
+     * @type {number}
+     */
+    node_count = 0;
+}
+
+/**
+ * A whole `.vgeo` file, read into the flat form the traversal wants.
+ *
+ * Clusters are a structure of arrays rather than objects: an asset of any size has hundreds of
+ * thousands of them, a cut reads a handful of fields from the ones it visits and nothing at all
+ * from the ones it skips, and an object per cluster would cost more than the file does.
+ */
+export class VGeoContainer {
+    /**
+     * Every page decoded, back to back in page order. Each page's {@link VGeoPageView.base} is an
+     * offset into this, and so — through it — is every payload offset a cluster record carries.
+     *
+     * It is not the file. Under a compressing codec the file does not hold a page's bytes at all,
+     * and even under the raw codec the two differ by the frame headers and child tables the decoded
+     * image leaves out.
+     *
+     * @type {Uint8Array}
+     */
+    page_bytes = new Uint8Array(0);
+
+    /**
+     * What the frames store between them, before decoding — the part of the file that is pages.
+     * @type {number}
+     */
+    stored_page_bytes = 0;
+
+    /**
+     * `page_bytes.length`, named so a caller does not have to know that.
+     * @type {number}
+     */
+    decoded_page_bytes = 0;
+
+    /**
+     * @type {number}
+     */
+    format_version = 0;
+
+    /**
+     * @type {number}
+     */
+    payload_encoding = 0;
+
+    /**
+     * Hex, as the 16 asset-id bytes stand in the file.
+     * @type {string}
+     */
+    asset_id = '';
+
+    /**
+     * @type {number}
+     */
+    source_vertex_count = 0;
+
+    /**
+     * @type {number}
+     */
+    source_face_count = 0;
+
+    /**
+     * Object-space bounding sphere of the whole geometry: centre xyz then radius.
+     * @type {Float32Array}
+     */
+    object_sphere = new Float32Array(4);
+
+    /**
+     * @type {Float32Array}
+     */
+    object_bounds = new Float32Array(6);
+
+    /**
+     * @type {VGeoPageView[]}
+     */
+    pages = [];
+
+    /**
+     * @type {{min_error:number, max_error:number, clusters:number, groups:number, triangles:number}[]}
+     */
+    levels = [];
+
+    /**
+     * @type {number}
+     */
+    cluster_count = 0;
+
+    /**
+     * `4 * cluster_count` — the LOD-metric sphere of the step that created each cluster.
+     * @type {Float32Array}
+     */
+    self_sphere = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    self_error = new Float32Array(0);
+
+    /**
+     * @type {Float32Array}
+     */
+    parent_error = new Float32Array(0);
+
+    /**
+     * `4 * cluster_count` — each cluster's own tight sphere, for culling and never for the cut test.
+     * @type {Float32Array}
+     */
+    bounds_sphere = new Float32Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    child_ref = new Uint16Array(0);
+
+    /**
+     * @type {Uint16Array}
+     */
+    child_group = new Uint16Array(0);
+
+    /**
+     * @type {Uint32Array}
+     */
+    encoding_flags = new Uint32Array(0);
+
+    /**
+     * Offset into the owning page's payload section.
+     * @type {Uint32Array}
+     */
+    payload_offset = new Uint32Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    vertex_count = new Uint8Array(0);
+
+    /**
+     * @type {Uint8Array}
+     */
+    triangle_count = new Uint8Array(0);
+
+    /**
+     * @type {Uint32Array}
+     */
+    page_of_cluster = new Uint32Array(0);
+
+    /**
+     * Group index within that page, so a colour can be keyed on the residency unit.
+     * @type {Uint16Array}
+     */
+    group_of_cluster = new Uint16Array(0);
+
+    /**
+     * How many clusters store a normal per vertex rather than one constant-compressed word for the
+     * whole cluster.
+     *
+     * A source carrying no normals encodes the engine default everywhere, and then `colour by
+     * stored normal` comes out one flat colour across the whole model. That is the file's truth and
+     * it reads exactly like a broken viewer, so the panel says the number outright.
+     *
+     * It is not a count of clusters that *have* normals: a cluster whose vertices genuinely all
+     * face the same way compresses to one word as well, and a flat surface is not a missing one.
+     *
+     * @type {number}
+     */
+    per_vertex_normal_cluster_count = 0;
+
+    /**
+     * What {@link vgeo_validate_container} made of the file. Empty is the only good answer, and a
+     * non-empty one is the most interesting thing this tool can tell you.
+     * @type {VGeoDefect[]}
+     */
+    defects = [];
+}
+
+/**
+ * @param {DataView} view
+ * @param {number} offset
+ * @returns {string} 16 bytes as hex
+ */
+function read_asset_id(view, offset) {
+    let out = '';
+
+    for (let i = 0; i < 16; i++) {
+        out += view.getUint8(offset + i).toString(16).padStart(2, '0');
+    }
+
+    return out;
+}
+
+/**
+ * Read a whole `.vgeo` file.
+ *
+ * Eager and complete, which is the opposite of what the runtime will do and exactly right for a
+ * tool whose job is to look at every part of it.
+ *
+ * @param {ArrayBuffer} array_buffer the complete file
+ * @returns {VGeoContainer}
+ * @throws {Error} when the bytes are not a `.vgeo` at all, or a page uses a codec this reader has no
+ *     decoder for — everything softer than that lands in {@link VGeoContainer.defects}
+ */
+export function vgeo_read_container(array_buffer) {
+    assert.defined(array_buffer, 'array_buffer');
+
+    if (array_buffer.byteLength < VGEO_HEADER_SIZE) {
+        throw new Error(`file is ${array_buffer.byteLength} bytes, shorter than the header`);
+    }
+
+    const view = new DataView(array_buffer);
+
+    const magic = view.getUint32(VGEO_HEADER_OFFSET.MAGIC, LE);
+
+    if (magic !== VGEO_MAGIC) {
+        throw new Error(
+            `not a .vgeo file: magic is 0x${magic.toString(16)}, expected 0x${VGEO_MAGIC.toString(16)}`
+        );
+    }
+
+    const result = new VGeoContainer();
+
+    const file_bytes = new Uint8Array(array_buffer);
+
+    result.format_version = view.getUint16(VGEO_HEADER_OFFSET.FORMAT_VERSION, LE);
+    result.payload_encoding = view.getUint32(VGEO_HEADER_OFFSET.PAYLOAD_ENCODING, LE);
+    result.asset_id = read_asset_id(view, VGEO_HEADER_OFFSET.ASSET_ID);
+    result.source_vertex_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_VERTEX_COUNT, LE));
+    result.source_face_count = Number(view.getBigUint64(VGEO_HEADER_OFFSET.SOURCE_FACE_COUNT, LE));
+
+    for (let i = 0; i < 4; i++) {
+        result.object_sphere[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_SPHERE + i * 4, LE);
+    }
+
+    for (let i = 0; i < 6; i++) {
+        result.object_bounds[i] = view.getFloat32(VGEO_HEADER_OFFSET.OBJECT_BOUNDS + i * 4, LE);
+    }
+
+    const level_count = view.getUint8(VGEO_HEADER_OFFSET.LEVEL_COUNT);
+
+    for (let i = 0; i < level_count; i++) {
+        const at = VGEO_HEADER_SIZE + i * VGEO_LEVEL_RECORD_SIZE;
+
+        result.levels.push({
+            min_error: view.getFloat32(at + VGEO_LEVEL_OFFSET.MIN_ERROR, LE),
+            max_error: view.getFloat32(at + VGEO_LEVEL_OFFSET.MAX_ERROR, LE),
+            clusters: view.getUint32(at + VGEO_LEVEL_OFFSET.CLUSTER_COUNT, LE),
+            groups: view.getUint32(at + VGEO_LEVEL_OFFSET.GROUP_COUNT, LE),
+            triangles: view.getUint32(at + VGEO_LEVEL_OFFSET.TRIANGLE_COUNT, LE),
+        });
+    }
+
+    // The frame walk is the format's own, shared with the writer and the validator — a file either
+    // of those can scan is a file this can scan.
+    const frames = vgeo_scan_frames(BinaryBuffer.fromArrayBuffer(array_buffer));
+
+    /*
+     Every page is decoded up front into one image laid out in page order, and everything below
+     addresses that image rather than the file. The runtime does the opposite — one page at a time,
+     wherever it has room — but this tool wants all of them at once and wants one address space to
+     read them through, and under a compressing codec the file simply does not hold a page's bytes.
+
+     Both refusals below happen before a byte is allocated. The second matters more than it looks:
+     `decoded_size` is four bytes of untrusted file, and honouring one that no block of that length
+     could produce turns corruption into an out-of-memory throw.
+     */
+    let decoded_total = 0;
+
+    for (const frame of frames) {
+        if (frame.codec !== VGEO_CODEC_RAW && frame.codec !== VGEO_CODEC_LZ4) {
+            throw new Error(
+                `page ${frame.page_index} uses codec ${frame.codec};`
+                + ` this reader decodes ${VGEO_CODEC_RAW} (raw) and ${VGEO_CODEC_LZ4} (lz4)`
+            );
+        }
+
+        if (frame.decoded_size > vgeo_frame_decode_bound(frame.codec, frame.stored_size)) {
+            throw new Error(
+                `page ${frame.page_index} claims ${frame.decoded_size} decoded bytes,`
+                + ` more than codec ${frame.codec} could produce from ${frame.stored_size} stored`
+            );
+        }
+
+        result.stored_page_bytes += frame.stored_size;
+
+        decoded_total += frame.decoded_size;
+    }
+
+    const page_bytes = new Uint8Array(decoded_total);
+
+    result.page_bytes = page_bytes;
+    result.decoded_page_bytes = decoded_total;
+
+    /**
+     * The decoded pages, addressed a word at a time. A `DataView` has no alignment requirement,
+     * which is what a page's fields need: their offsets are the format's, not the browser's.
+     * @type {DataView}
+     */
+    const page_data = new DataView(page_bytes.buffer, page_bytes.byteOffset, page_bytes.byteLength);
+
+    let page_cursor = 0;
+    let cluster_total = 0;
+
+    for (const frame of frames) {
+        const page = new VGeoPageView();
+
+        page.index = frame.page_index;
+        page.base = page_cursor;
+        page.codec = frame.codec;
+        page.stored_size = frame.stored_size;
+        page.decoded_size = frame.decoded_size;
+
+        page_cursor = vgeo_decode_frame_blob(page_bytes, page_cursor, file_bytes, frame);
+
+        // The child table is plaintext inside the frame, never compressed — which is what lets a
+        // runtime read fetch ranges without decoding anything. So it is read from the file.
+        page.child_pages = new Uint32Array(frame.child_page_count);
+
+        for (let i = 0; i < frame.child_page_count; i++) {
+            const entry = frame.frame_offset
+                + VGEO_FRAME_HEADER_SIZE
+                + i * VGEO_CHILD_TABLE_ENTRY_SIZE;
+
+            page.child_pages[i] = view.getUint32(entry + VGEO_CHILD_OFFSET.PAGE_INDEX, LE);
+        }
+
+        const group_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.GROUP_COUNT, LE);
+
+        page.cluster_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.CLUSTER_COUNT, LE);
+        page.min_level = page_data.getUint8(page.base + VGEO_PAGE_OFFSET.MIN_LEVEL);
+        page.max_level = page_data.getUint8(page.base + VGEO_PAGE_OFFSET.MAX_LEVEL);
+        page.node_count = page_data.getUint16(page.base + VGEO_PAGE_OFFSET.NODE_COUNT, LE);
+        page.payload_base = page.base
+            + page_data.getUint32(page.base + VGEO_PAGE_OFFSET.PAYLOAD_OFFSET, LE);
+        page.cluster_base = cluster_total;
+
+        page.group_cluster_first = new Uint16Array(group_count);
+        page.group_cluster_count = new Uint16Array(group_count);
+        page.group_parent_count = new Uint16Array(group_count);
+
+        for (let i = 0; i < group_count; i++) {
+            const record = page.base + VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
+
+            page.group_cluster_first[i] = page_data.getUint16(record, LE);
+            page.group_cluster_count[i] = page_data.getUint16(record + 2, LE);
+            page.group_parent_count[i] = page_data.getUint16(record + 4, LE);
+        }
+
+        result.pages.push(page);
+
+        cluster_total += page.cluster_count;
+    }
+
+    result.cluster_count = cluster_total;
+    result.self_sphere = new Float32Array(cluster_total * 4);
+    result.self_error = new Float32Array(cluster_total);
+    result.parent_error = new Float32Array(cluster_total);
+    result.bounds_sphere = new Float32Array(cluster_total * 4);
+    result.child_ref = new Uint16Array(cluster_total);
+    result.child_group = new Uint16Array(cluster_total);
+    result.encoding_flags = new Uint32Array(cluster_total);
+    result.payload_offset = new Uint32Array(cluster_total);
+    result.vertex_count = new Uint8Array(cluster_total);
+    result.triangle_count = new Uint8Array(cluster_total);
+    result.page_of_cluster = new Uint32Array(cluster_total);
+    result.group_of_cluster = new Uint16Array(cluster_total);
+
+    for (const page of result.pages) {
+        const table = page.base
+            + page_data.getUint32(page.base + VGEO_PAGE_OFFSET.CLUSTER_TABLE_OFFSET, LE);
+
+        for (let i = 0; i < page.cluster_count; i++) {
+            const record = table + i * VGEO_CLUSTER_RECORD_SIZE;
+            const id = page.cluster_base + i;
+
+            for (let c = 0; c < 4; c++) {
+                result.self_sphere[id * 4 + c] =
+                    page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_SPHERE + c * 4, LE);
+                result.bounds_sphere[id * 4 + c] =
+                    page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.BOUNDS_SPHERE + c * 4, LE);
+            }
+
+            result.self_error[id] = page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.SELF_ERROR, LE);
+            result.parent_error[id] = page_data.getFloat32(record + VGEO_CLUSTER_OFFSET.PARENT_ERROR, LE);
+            result.child_ref[id] = page_data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_REF, LE);
+            result.child_group[id] = page_data.getUint16(record + VGEO_CLUSTER_OFFSET.CHILD_GROUP, LE);
+            result.encoding_flags[id] =
+                page_data.getUint32(record + VGEO_CLUSTER_OFFSET.ENCODING_FLAGS, LE);
+            result.payload_offset[id] =
+                page_data.getUint32(record + VGEO_CLUSTER_OFFSET.PAYLOAD_OFFSET, LE);
+            result.vertex_count[id] = page_data.getUint8(record + VGEO_CLUSTER_OFFSET.VERTEX_COUNT);
+            result.triangle_count[id] = page_data.getUint8(record + VGEO_CLUSTER_OFFSET.TRIANGLE_COUNT);
+            result.page_of_cluster[id] = page.index;
+
+            if ((result.encoding_flags[id] & NORMAL_COMPRESSION_FLAG) === 0) {
+                result.per_vertex_normal_cluster_count++;
+            }
+        }
+
+        for (let group = 0; group < page.group_cluster_first.length; group++) {
+            const first = page.group_cluster_first[group];
+            const count = page.group_cluster_count[group];
+
+            for (let i = 0; i < count; i++) {
+                result.group_of_cluster[page.cluster_base + first + i] = group;
+            }
+        }
+    }
+
+    result.defects = vgeo_validate_container(BinaryBuffer.fromArrayBuffer(array_buffer));
+
+    return result;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  The cut
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The view a cut is selected for. `VIRTUAL_GEOMETRY_DESIGN.md` §4: a cut is selected at one
+ * camera's distances and pixel budget, and is the wrong cut for any other.
+ */
+export class VGeoCutView {
+    /**
+     * Camera position, object space — the viewer draws at identity, so world and object agree.
+     * @type {Float32Array}
+     */
+    eye = new Float32Array(3);
+
+    /**
+     * Pixels of permitted error. The one quality dial.
+     * @type {number}
+     */
+    tau = 1;
+
+    /**
+     * Height of the render target, in pixels — the projection's numerator.
+     * @type {number}
+     */
+    screen_height = 1080;
+
+    /**
+     * @type {number}
+     */
+    fov_y = 60 * DEG_TO_RAD;
+
+    /**
+     * @type {boolean}
+     */
+    cull_enabled = false;
+
+    /**
+     * Six normalized world-space planes, as {@link Camera.frustum} holds them.
+     * @type {Float32Array}
+     */
+    frustum = new Float32Array(24);
+}
+
+/**
+ * What one traversal came to, including what it had to look at to get there.
+ */
+export class VGeoCut {
+    /**
+     * Selected clusters, by reader id.
+     * @type {number[]}
+     */
+    clusters = [];
+
+    /**
+     * @type {number}
+     */
+    triangle_count = 0;
+
+    /**
+     * @type {number}
+     */
+    vertex_count = 0;
+
+    /**
+     * @type {number}
+     */
+    groups_visited = 0;
+
+    /**
+     * @type {number}
+     */
+    clusters_tested = 0;
+
+    /**
+     * Clusters whose subtree the frustum threw away, which is a whole region rather than one
+     * cluster — the reason culling belongs in the traversal and not after it.
+     * @type {number}
+     */
+    culled = 0;
+
+    /**
+     * Distinct pages the traversal had to have resident.
+     * @type {number}
+     */
+    pages_touched = 0;
+
+    /**
+     * @type {number}
+     */
+    duration_ms = 0;
+}
+
+/**
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §4: `err_px = r_e · screen_height / (2 · tan(fov_y / 2) · d)`, with
+ * `d` the distance to the *closest point* of the sphere.
+ *
+ * A zero error projects to zero unconditionally — otherwise a leaf, whose error is exactly zero,
+ * would become undrawable the moment the camera entered its sphere.
+ *
+ * @param {number} error object-space `r_e`; `+Infinity` for a root's parent
+ * @param {Float32Array} spheres
+ * @param {number} base index of the sphere's first component
+ * @param {Float32Array} eye
+ * @param {number} k `screen_height / (2 · tan(fov_y / 2))`, hoisted out of the loop
+ * @returns {number} pixels
+ */
+function project_error(error, spheres, base, eye, k) {
+    if (error === 0) {
+        return 0;
+    }
+
+    const dx = eye[0] - spheres[base];
+    const dy = eye[1] - spheres[base + 1];
+    const dz = eye[2] - spheres[base + 2];
+
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz) - spheres[base + 3];
+
+    if (distance <= 0) {
+        // camera inside the sphere; the projection is unbounded and the cluster must refine
+        return Number.POSITIVE_INFINITY;
+    }
+
+    return (error * k) / distance;
+}
+
+/**
+ * Whether a sphere is entirely outside the frustum.
+ *
+ * Only the five finite planes are tested. The projection is infinite reverse-Z, so the far plane's
+ * row is degenerate and normalizing it produces nothing a test can use.
+ *
+ * @param {Float32Array} frustum
+ * @param {Float32Array} spheres
+ * @param {number} base
+ * @returns {boolean}
+ */
+function sphere_outside_frustum(frustum, spheres, base) {
+    const x = spheres[base];
+    const y = spheres[base + 1];
+    const z = spheres[base + 2];
+    const radius = spheres[base + 3];
+
+    for (let plane = 0; plane < 5; plane++) {
+        const o = plane * 4;
+
+        const distance = frustum[o] * x + frustum[o + 1] * y + frustum[o + 2] * z + frustum[o + 3];
+
+        if (distance < -radius) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Select the cut for a view, by descending the page graph.
+ *
+ * A traversal rather than a flat pass over every cluster, per design §4 — and it gets the cut rule's
+ * first half for free. The rule is `project(parent) > τ AND project(self) ≤ τ`; a group is only ever
+ * reached by descending *through* the cluster whose step consumed it, and that descent happened
+ * precisely because the step projected above τ. Every cluster of a group shares that step's sphere
+ * and error, so the parent test is satisfied by the act of arriving.
+ *
+ * The residency clamp degenerates here: the whole file is in memory, so nothing is ever
+ * non-selectable and a leaf is the only reason to stop early.
+ *
+ * @param {VGeoContainer} container
+ * @param {VGeoCutView} view
+ * @returns {VGeoCut}
+ */
+export function vgeo_select_cut(container, view) {
+    assert.greaterThan(container.pages.length, 0, 'container.pages.length');
+
+    const started = performance.now();
+
+    const cut = new VGeoCut();
+
+    const k = view.screen_height / (2 * Math.tan(view.fov_y * 0.5));
+
+    /**
+     * Groups already queued, keyed `page · 65536 + group`. A group is referenced by every sibling
+     * cluster of the step that consumed it, so without this the traversal would expand it once per
+     * parent and the cut would carry duplicates.
+     *
+     * @type {Set<number>}
+     */
+    const queued = new Set();
+
+    /**
+     * @type {Set<number>}
+     */
+    const pages = new Set();
+
+    /**
+     * Page index and group index, interleaved.
+     * @type {number[]}
+     */
+    const stack = [];
+
+    const root = container.pages[0];
+
+    for (let group = 0; group < root.group_parent_count.length; group++) {
+        // no cluster anywhere refines into this group, so it is the top of the DAG and selectable
+        // with nothing above it
+        if (root.group_parent_count[group] === 0) {
+            queued.add(group);
+            stack.push(0, group);
+        }
+    }
+
+    while (stack.length > 0) {
+        const group = stack.pop();
+        const page_index = stack.pop();
+
+        const page = container.pages[page_index];
+
+        cut.groups_visited++;
+        pages.add(page_index);
+
+        const first = page.group_cluster_first[group];
+        const count = page.group_cluster_count[group];
+
+        for (let i = 0; i < count; i++) {
+            const id = page.cluster_base + first + i;
+
+            cut.clusters_tested++;
+
+            /*
+             Culling on `self_sphere` rather than on the tight `bounds_sphere`, because this decides
+             the subtree as well as the cluster: monotonicity makes a cluster's self sphere contain
+             every descendant's geometry, so a self sphere outside the frustum means nothing under
+             it can be on screen either.
+             */
+            if (view.cull_enabled
+                && sphere_outside_frustum(view.frustum, container.self_sphere, id * 4)) {
+                cut.culled++;
+                continue;
+            }
+
+            const child_ref = container.child_ref[id];
+
+            const self_px = project_error(
+                container.self_error[id], container.self_sphere, id * 4, view.eye, k
+            );
+
+            if (self_px <= view.tau || child_ref === VGEO_NO_CHILD) {
+                cut.clusters.push(id);
+                cut.triangle_count += container.triangle_count[id];
+                cut.vertex_count += container.vertex_count[id];
+                continue;
+            }
+
+            const child_page = child_ref === VGEO_SAME_PAGE ? page_index : page.child_pages[child_ref];
+            const child_group = container.child_group[id];
+
+            const key = child_page * 65536 + child_group;
+
+            if (!queued.has(key)) {
+                queued.add(key);
+                stack.push(child_page, child_group);
+            }
+        }
+    }
+
+    cut.pages_touched = pages.size;
+    cut.duration_ms = performance.now() - started;
+
+    return cut;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  Turning a cut into drawable geometry
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * What a cluster's colour is keyed on.
+ *
+ * The two normal modes are not keyed on the cluster at all: they paint every vertex with its own
+ * direction, and the cluster boundaries go with it. `stored normal` is the container's own
+ * {@link VGEO_ATTRIBUTE.NORMAL}, decoded out of the payload — the only mode that shows an attribute
+ * the file carries rather than something derived from it. `geometric normal` is the area-weighted
+ * normal of the decoded triangles, which is what every other mode shades with. The pair is the
+ * point: they agree where the builder's normals still describe the geometry it shipped, and a
+ * source with no normals at all makes the first one flat.
+ *
+ * @enum {string}
+ */
+export const VGEO_COLOR_MODE = {
+    Cluster: 'cluster',
+    Group: 'group',
+    Page: 'page',
+    Error: 'error',
+    StoredNormal: 'stored normal',
+    GeometricNormal: 'geometric normal',
+};
+
+/**
+ * Key colours are spread by the golden ratio so that adjacent ids never land on adjacent hues —
+ * neighbouring clusters are exactly what has to be told apart.
+ * @type {number}
+ */
+const HUE_STEP = 0.6180339887498949;
+
+/**
+ * @param {number} hue in `[0, 1)`
+ * @param {number} saturation
+ * @param {number} value
+ * @param {Float32Array} out
+ * @param {number} offset
+ */
+function hsv_to_rgb(hue, saturation, value, out, offset) {
+    const sector = hue * 6;
+    const i = Math.floor(sector);
+    const f = sector - i;
+
+    const p = value * (1 - saturation);
+    const q = value * (1 - saturation * f);
+    const t = value * (1 - saturation * (1 - f));
+
+    switch (i % 6) {
+        case 0:
+            out[offset] = value; out[offset + 1] = t; out[offset + 2] = p;
+            break;
+        case 1:
+            out[offset] = q; out[offset + 1] = value; out[offset + 2] = p;
+            break;
+        case 2:
+            out[offset] = p; out[offset + 1] = value; out[offset + 2] = t;
+            break;
+        case 3:
+            out[offset] = p; out[offset + 1] = q; out[offset + 2] = value;
+            break;
+        case 4:
+            out[offset] = t; out[offset + 1] = p; out[offset + 2] = value;
+            break;
+        default:
+            out[offset] = value; out[offset + 1] = p; out[offset + 2] = q;
+            break;
+    }
+}
+
+/**
+ * Key lights, baked into vertex colour.
+ *
+ * The direct path carries position and colour per vertex and nothing else — no normal reaches the
+ * shader — so shading happens here, once per cut, against normals derived from the decoded
+ * triangles. Two opposed lights and a generous ambient, so that no part of the surface is black and
+ * every cluster's colour stays readable wherever it faces.
+ *
+ * @type {number[]}
+ */
+const KEY_LIGHT = [0.35, 0.78, 0.52];
+
+/**
+ * @type {number[]}
+ */
+const FILL_LIGHT = [-0.55, -0.25, -0.79];
+
+/**
+ * Ceiling on a baked colour's brightest channel.
+ *
+ * The pass draws at `AfterTransparency`, so everything it writes still goes through the tonemapper,
+ * and the tonemapper desaturates as it approaches white. Pushed to 1.0 the clusters come out pastel
+ * and stop being tellable apart, which defeats the only thing the colour is for — so the shading
+ * range is deliberately kept below it.
+ *
+ * @type {number}
+ */
+const COLOR_CEILING = 0.9;
+
+/**
+ * One cluster's worth of decoded stored normals, reused across clusters.
+ *
+ * {@link VGEO_MAX_CLUSTER_VERTEX_COUNT} is the format's ceiling on a cluster and
+ * {@link vgeo_validate_container} holds every file to it, so this is never short.
+ *
+ * @type {Float32Array}
+ */
+const stored_normals = new Float32Array(VGEO_MAX_CLUSTER_VERTEX_COUNT * 3);
+
+/**
+ * One decoded direction, on its way from the octahedral codec into a caller's array.
+ * @type {Float32Array}
+ */
+const scratch_direction = new Float32Array(3);
+
+/**
+ * Decode one cluster's stored normal section into unit vectors.
+ *
+ * The section is one octahedral `u32` per vertex, or a single word for the whole cluster when the
+ * encoder found every vertex agreeing — which is also what a source lacking normals encodes to, so
+ * the constant case is the ordinary one and not an exception. A stride of zero is what reads it:
+ * every vertex fetches the same word, and the loop does not have to know which case it is in.
+ *
+ * @param {VGeoContainer} container
+ * @param {DataView} data over the whole file
+ * @param {number} id reader cluster id
+ * @param {Float32Array} out at least `3 * container.vertex_count[id]` long
+ */
+function vgeo_read_cluster_normals(container, data, id, out) {
+    const vertex_count = container.vertex_count[id];
+
+    // out is sized for the format's ceiling, so this fires only on a file that already broke it —
+    // and a short write would come out as a handful of quietly wrong colours instead
+    assert.greaterThanOrEqual(out.length, vertex_count * 3, 'out must hold three components per cluster vertex');
+
+    const encoding_flags = container.encoding_flags[id];
+
+    const page = container.pages[container.page_of_cluster[id]];
+
+    const at = page.payload_base
+        + container.payload_offset[id]
+        + vgeo_payload_attribute_offset(
+            VGEO_ATTRIBUTE.NORMAL, vertex_count, container.triangle_count[id], encoding_flags
+        );
+
+    const stride = (encoding_flags & NORMAL_COMPRESSION_FLAG) === 0 ? 4 : 0;
+
+    for (let i = 0; i < vertex_count; i++) {
+        const word = data.getUint32(at + i * stride, LE);
+
+        const u = ((word & 0xFFFF) / UINT16_MAX) * 2 - 1;
+        const v = (((word >>> 16) & 0xFFFF) / UINT16_MAX) * 2 - 1;
+
+        decode_octahedron_to_unit(scratch_direction, 0, u, v);
+
+        /*
+         The encoder hands the octahedral codec `(nx, nz, ny)` — Shade's own convention, matched so
+         that a `.vgeo` payload is byte for byte a `MeshletBatch` one — so the decode comes back in
+         that order and has to be put back.
+         */
+        out[i * 3] = scratch_direction[0];
+        out[i * 3 + 1] = scratch_direction[2];
+        out[i * 3 + 2] = scratch_direction[1];
+    }
+}
+
+/**
+ * Paint a run of vertices with their own directions and no shading: `rgb = n · 0.5 + 0.5`, scaled
+ * by {@link COLOR_CEILING} for the same reason every other mode is.
+ *
+ * Unlit on purpose. A direction multiplied by how much light it happens to catch is unreadable
+ * exactly where reading it matters — a normal facing away from both lights would come out black,
+ * and black is not a direction.
+ *
+ * The tonemapper still has the last word on what reaches the screen, so this is a direction to be
+ * read and not a value to be measured.
+ *
+ * @param {Float32Array} colors four per vertex
+ * @param {number} first index of the run's first vertex
+ * @param {number} count vertices in the run
+ * @param {Float32Array} directions unit vectors, three components apiece
+ * @param {number} directions_offset index of the run's first component within `directions`
+ */
+function paint_directions(colors, first, count, directions, directions_offset) {
+    for (let i = 0; i < count; i++) {
+        const d = directions_offset + i * 3;
+        const o = (first + i) * 4;
+
+        colors[o] = COLOR_CEILING * (directions[d] * 0.5 + 0.5);
+        colors[o + 1] = COLOR_CEILING * (directions[d + 1] * 0.5 + 0.5);
+        colors[o + 2] = COLOR_CEILING * (directions[d + 2] * 0.5 + 0.5);
+        colors[o + 3] = 1;
+    }
+}
+
+/**
+ * A cut, decoded into one geometry.
+ *
+ * Nothing about it depends on where the camera is: the mesh is drawn solid and the depth buffer
+ * orders it, so the triangle list is uploaded once when the cut is taken and never touched again.
+ */
+export class VGeoCutGeometry {
+    /**
+     * Position and colour, indexed by {@link triangles}.
+     * @type {Geometry}
+     */
+    geometry = new Geometry();
+
+    /**
+     * `3 * triangle_count` — the full triangle list, in cluster order, and the geometry's index.
+     * @type {Uint32Array}
+     */
+    triangles = new Uint32Array(0);
+
+    /**
+     * @type {number}
+     */
+    triangle_count = 0;
+
+    /**
+     * @type {number}
+     */
+    vertex_count = 0;
+}
+
+/**
+ * Decode the selected clusters into one geometry.
+ *
+ * Payloads are `SHADE_MESHLET_V1`'s (format §8): the index section first, three 8-bit local indices
+ * per triangle, then the attribute sections. Position is always read — it is raw float32, never
+ * constant-compressed — and the stored normal section only when a normal display asks for it,
+ * because the direct path carries position and colour per vertex and nowhere to put the rest.
+ *
+ * @param {VGeoContainer} container
+ * @param {VGeoCut} cut
+ * @param {VGEO_COLOR_MODE} color_mode
+ * @returns {VGeoCutGeometry}
+ */
+export function vgeo_build_cut_geometry(container, cut, color_mode) {
+    const vertex_count = cut.vertex_count;
+    const triangle_count = cut.triangle_count;
+
+    const positions = new Float32Array(vertex_count * 3);
+    const colors = new Float32Array(vertex_count * 4);
+    const normals = new Float32Array(vertex_count * 3);
+
+    const result = new VGeoCutGeometry();
+
+    result.triangles = new Uint32Array(triangle_count * 3);
+    result.triangle_count = triangle_count;
+    result.vertex_count = vertex_count;
+
+    const bytes = container.page_bytes;
+    const triangles = result.triangles;
+
+    /**
+     * The decoded pages, addressed a word at a time. A `DataView` has no alignment requirement,
+     * which is what an encoded attribute word needs: its offset is the format's, not the browser's.
+     * @type {DataView}
+     */
+    const data = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+    /*
+     The error ramp spans the *cut's* own errors, not the file's. Normalizing against the coarsest
+     error in the container would be defensible and useless: a fine cut's clusters all sit orders of
+     magnitude below it and the whole model comes out one flat colour. What the question actually is
+     — which parts of this cut settled for more error than the rest — is a question about this cut.
+     */
+    let error_low = Number.POSITIVE_INFINITY;
+    let error_high = 0;
+
+    for (const id of cut.clusters) {
+        error_low = Math.min(error_low, container.self_error[id]);
+        error_high = Math.max(error_high, container.self_error[id]);
+    }
+
+    const error_span = error_high - error_low;
+
+    /**
+     * `[first vertex, first triangle]` of each selected cluster, so colour can be applied per
+     * cluster after the normals are known.
+     * @type {Uint32Array}
+     */
+    const cluster_vertex_first = new Uint32Array(cut.clusters.length);
+
+    let vertex_cursor = 0;
+    let triangle_cursor = 0;
+
+    for (let c = 0; c < cut.clusters.length; c++) {
+        const id = cut.clusters[c];
+
+        const cluster_vertices = container.vertex_count[id];
+        const cluster_triangles = container.triangle_count[id];
+
+        const page = container.pages[container.page_of_cluster[id]];
+        const payload = page.payload_base + container.payload_offset[id];
+
+        cluster_vertex_first[c] = vertex_cursor;
+
+        const position_at = payload + vgeo_payload_attribute_offset(
+            VGEO_ATTRIBUTE.POSITION,
+            cluster_vertices,
+            cluster_triangles,
+            container.encoding_flags[id]
+        );
+
+        /*
+         Copied out rather than viewed in place: a Float32Array view demands 4-byte alignment
+         against the *file's* buffer, which is a property of where the browser happened to put it
+         and not something the format promises.
+         */
+        const coordinates = new Float32Array(
+            bytes.slice(position_at, position_at + cluster_vertices * 12).buffer
+        );
+
+        positions.set(coordinates, vertex_cursor * 3);
+
+        for (let i = 0; i < cluster_triangles * 3; i++) {
+            triangles[triangle_cursor * 3 + i] = vertex_cursor + bytes[payload + i];
+        }
+
+        vertex_cursor += cluster_vertices;
+        triangle_cursor += cluster_triangles;
+    }
+
+    assert.equal(vertex_cursor, vertex_count, 'decoded vertices must match the cut');
+    assert.equal(triangle_cursor, triangle_count, 'decoded triangles must match the cut');
+
+    // Area-weighted vertex normals, which is all shading reads. Clusters share no vertices, so
+    // accumulating over the whole list still gives each cluster its own smoothing — the crease that
+    // leaves at a cluster seam is a feature here, not an artefact.
+    for (let t = 0; t < triangle_count; t++) {
+        const a = triangles[t * 3] * 3;
+        const b = triangles[t * 3 + 1] * 3;
+        const c = triangles[t * 3 + 2] * 3;
+
+        const abx = positions[b] - positions[a];
+        const aby = positions[b + 1] - positions[a + 1];
+        const abz = positions[b + 2] - positions[a + 2];
+
+        const acx = positions[c] - positions[a];
+        const acy = positions[c + 1] - positions[a + 1];
+        const acz = positions[c + 2] - positions[a + 2];
+
+        const nx = aby * acz - abz * acy;
+        const ny = abz * acx - abx * acz;
+        const nz = abx * acy - aby * acx;
+
+        normals[a] += nx; normals[a + 1] += ny; normals[a + 2] += nz;
+        normals[b] += nx; normals[b + 1] += ny; normals[b + 2] += nz;
+        normals[c] += nx; normals[c + 1] += ny; normals[c + 2] += nz;
+    }
+
+    // Normalized here rather than where they are read, because two things read them now — the
+    // shading, and `geometric normal` — and a direction is the same direction for both.
+    for (let v = 0; v < vertex_count; v++) {
+        const n = v * 3;
+
+        const length = Math.hypot(normals[n], normals[n + 1], normals[n + 2]);
+
+        // A vertex left with no area around it has no direction to give. Zero shades as ambient and
+        // displays as mid grey, and both say "nothing here" rather than inventing an answer.
+        const scale = length > 0 ? 1 / length : 0;
+
+        normals[n] *= scale;
+        normals[n + 1] *= scale;
+        normals[n + 2] *= scale;
+    }
+
+    const tint = new Float32Array(3);
+
+    for (let c = 0; c < cut.clusters.length; c++) {
+        const id = cut.clusters[c];
+
+        const first = cluster_vertex_first[c];
+        const count = container.vertex_count[id];
+
+        if (color_mode === VGEO_COLOR_MODE.StoredNormal) {
+            vgeo_read_cluster_normals(container, data, id, stored_normals);
+
+            paint_directions(colors, first, count, stored_normals, 0);
+
+            continue;
+        }
+
+        if (color_mode === VGEO_COLOR_MODE.GeometricNormal) {
+            paint_directions(colors, first, count, normals, first * 3);
+
+            continue;
+        }
+
+        let key;
+
+        switch (color_mode) {
+            case VGEO_COLOR_MODE.Group:
+                key = container.page_of_cluster[id] * 65536 + container.group_of_cluster[id];
+                break;
+            case VGEO_COLOR_MODE.Page:
+                key = container.page_of_cluster[id];
+                break;
+            default:
+                key = id;
+                break;
+        }
+
+        if (color_mode === VGEO_COLOR_MODE.Error) {
+            // cool where the cut is refined, hot where it settled for the most error
+            const t = error_span > 0 ? (container.self_error[id] - error_low) / error_span : 0;
+
+            hsv_to_rgb(0.68 * (1 - t), 0.9, 1, tint, 0);
+        } else {
+            hsv_to_rgb((key * HUE_STEP) % 1, 0.85, 1, tint, 0);
+        }
+
+        const end = first + count;
+
+        for (let v = first; v < end; v++) {
+            const n = v * 3;
+
+            const nx = normals[n];
+            const ny = normals[n + 1];
+            const nz = normals[n + 2];
+
+            const key_term = Math.max(
+                0, nx * KEY_LIGHT[0] + ny * KEY_LIGHT[1] + nz * KEY_LIGHT[2]
+            );
+
+            const fill_term = Math.max(
+                0, nx * FILL_LIGHT[0] + ny * FILL_LIGHT[1] + nz * FILL_LIGHT[2]
+            );
+
+            const shade = COLOR_CEILING * (0.22 + 0.60 * key_term + 0.18 * fill_term);
+
+            colors[v * 4] = tint[0] * shade;
+            colors[v * 4 + 1] = tint[1] * shade;
+            colors[v * 4 + 2] = tint[2] * shade;
+            colors[v * 4 + 3] = 1;
+        }
+    }
+
+    result.geometry.addAttribute(Attribute.from(positions, 3, StandardAttributes.Position));
+    result.geometry.addAttribute(Attribute.from(colors, 4, StandardAttributes.Color));
+    result.geometry.index = Attribute.from(result.triangles, 1, StandardAttributes.Index);
+
+    return result;
+}
+
+/**
+ * Clear the frame's depth, so that the cut is the only thing in it.
+ *
+ * **The renderer does not do this when there is nothing to rasterize.** Depth is cleared as a side
+ * effect of drawing the first opaque bucket, and this viewer's `Scene` holds a light and no meshes,
+ * so that draw never happens. The renderer also ping-pongs two depth textures frame to frame — so
+ * left alone, the cut is depth-tested against *its own depth from two frames ago*, and dissolves
+ * into holes wherever the camera has moved since. It reads as missing geometry and it is not.
+ *
+ * A real scene needs none of this and must not have it: the cut has to be occluded by whatever the
+ * scene put in the depth buffer, which is why the draw itself loads rather than clears.
+ *
+ * It runs immediately before the draw rather than at the top of the frame, so everything earlier
+ * that reads depth still sees the previous frame's. With nothing in the scene there is nothing for
+ * those passes to occlude, and the alternative is a second registration on another phase to save a
+ * result that is empty either way.
+ *
+ * @param {FrameGraph} graph
+ * @param {number} depth
+ * @returns {number} the depth handle to draw against
+ */
+function vgeo_graph_clear_depth(graph, depth) {
+    const data = {};
+
+    const pass = graph.add('vgeo/clear depth', data, (data, resources, context) => {
+        const texture = resources.get(data.depth);
+
+        // no draws — the clear is the load op, and ending the pass immediately is what performs it
+        context.encoder.beginRenderPass({
+            label: "vgeo/clear depth",
+            colorAttachments: [],
+            depthStencilAttachment: {
+                view: texture.obtainView(DEFAULT_DEPTH_TEXTURE_VIEW),
+                depthLoadOp: "clear",
+                depthStoreOp: "store",
+                depthClearValue: DEPTH_BACKGROUND_VALUE,
+            },
+        }).end();
+    });
+
+    data.depth = pass.write(depth);
+
+    return data.depth;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  Harness
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {number} value
+ * @returns {string}
+ */
+function thousands(value) {
+    return value.toLocaleString('en-US');
+}
+
+/**
+ * @param {[string, string][]} entries
+ * @returns {string} one label/value row apiece
+ */
+function panel_table(entries) {
+    return entries
+        .map(([key, value]) => `<div class="row"><span class="muted">${key}</span><span>${value}</span></div>`)
+        .join('');
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function human_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+
+    if (bytes < 1024 * 1024 * 1024) {
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/**
+ * What the pages cost stored against what they cost decoded, and under which codec.
+ *
+ * Stored is the number that gets fetched and the number that sits on disk; decoded is the number a
+ * resident page costs in RAM. The codec is per frame, so a file can genuinely be a mixture — the
+ * encoder stores a page raw whenever compressing it would not have shrunk it — and naming all of
+ * them is more honest than naming whichever one happened to come first.
+ *
+ * @param {VGeoContainer} container
+ * @returns {string}
+ */
+function page_storage(container) {
+    const codec = Array.from(new Set(container.pages.map((page) => page.codec)))
+        .map(vgeo_codec_name)
+        .join(' + ');
+
+    const ratio = container.decoded_page_bytes / Math.max(container.stored_page_bytes, 1);
+
+    return `${human_bytes(container.stored_page_bytes)} stored`
+        + ` · ${human_bytes(container.decoded_page_bytes)} decoded`
+        + ` · ${codec} ${ratio.toFixed(2)}x`;
+}
+
+const PANEL_CSS = `
+#vgeo-panel {
+    position: absolute; top: 0; right: 0; width: 340px; max-height: 100vh; overflow-y: auto;
+    padding: 12px 14px; box-sizing: border-box;
+    font: 12px/1.45 ui-monospace, "Cascadia Mono", Consolas, monospace;
+    color: #dfe6ee; background: rgba(12, 16, 22, 0.88);
+    border-left: 1px solid #2b3947;
+}
+#vgeo-panel h1 { margin: 0 0 8px; font-size: 13px; letter-spacing: 0.06em; color: #7fd2ff; }
+#vgeo-panel h2 {
+    margin: 14px 0 6px; font-size: 11px; letter-spacing: 0.12em; text-transform: uppercase;
+    color: #6b7c8d; border-bottom: 1px solid #24313d; padding-bottom: 3px;
+}
+#vgeo-panel .row { display: flex; justify-content: space-between; gap: 8px; }
+#vgeo-panel .row span:last-child { color: #f2f6fa; }
+#vgeo-panel .count { font-size: 30px; line-height: 1.1; color: #8fe388; }
+#vgeo-panel .muted { color: #6b7c8d; }
+#vgeo-panel .bad { color: #ff8a7a; }
+#vgeo-panel .good { color: #8fe388; }
+#vgeo-panel button {
+    width: 100%; margin: 8px 0 2px; padding: 7px; cursor: pointer;
+    font: inherit; color: #061018; background: #7fd2ff; border: 0; border-radius: 3px;
+}
+#vgeo-panel button:hover { background: #a5e0ff; }
+#vgeo-panel label { display: flex; align-items: center; gap: 6px; margin: 3px 0; cursor: pointer; }
+#vgeo-panel input[type=range] { width: 100%; }
+#vgeo-panel select { width: 100%; font: inherit; background: #16202b; color: #dfe6ee; border: 1px solid #2b3947; padding: 3px; }
+#vgeo-panel ol { margin: 4px 0; padding-left: 18px; }
+#vgeo-drop {
+    position: absolute; inset: 0; display: none; align-items: center; justify-content: center;
+    font: 20px ui-monospace, monospace; color: #7fd2ff;
+    background: rgba(6, 12, 20, 0.82); border: 3px dashed #7fd2ff; box-sizing: border-box;
+}
+#vgeo-drop.active { display: flex; }
+`;
+
+/**
+ * The viewer draws its clusters into the scene, at the phase a full-screen effect that should be
+ * tonemapped with the rest of the frame belongs at.
+ */
+class VGEOViewerExtension extends RenderExtension {
+    name = "vgeo viewer";
+
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {VGeoViewer}
+     */
+    #viewer;
+
+    /**
+     * @param {VGeoViewer} viewer
+     */
+    constructor(viewer) {
+        super();
+
+        this.#viewer = viewer;
+    }
+
+    record(frame) {
+        this.#viewer.record(frame);
+    }
+}
+
+/**
+ * The viewer. One container at a time, one cut at a time, and the cut only changes when asked.
+ */
+class VGeoViewer {
+    /**
+     * @type {VGeoContainer|undefined}
+     */
+    #container = undefined;
+
+    /**
+     * @type {VGeoCutGeometry|undefined}
+     */
+    #cut_geometry = undefined;
+
+    /**
+     * @type {VGeoCut}
+     */
+    #cut = new VGeoCut();
+
+    /**
+     * @type {VGeoCutView}
+     */
+    #view = new VGeoCutView();
+
+    /**
+     * @type {DynamicMeshBatch}
+     */
+    #batch = new DynamicMeshBatch();
+
+    /**
+     * @type {DynamicMesh|undefined}
+     */
+    #mesh = undefined;
+
+    /**
+     * A cut is a solid surface, so it is drawn as one: opaque, writing depth, and ordered by the
+     * depth buffer rather than by anything this file does.
+     *
+     * @type {GPUDynamicMeshRenderer}
+     */
+    #dynamic = new GPUDynamicMeshRenderer();
+
+    /**
+     * Where the camera stood when the current cut was taken, so the panel can say how far you have
+     * wandered from the decision you are looking at.
+     * @type {Float32Array}
+     */
+    #cut_eye = new Float32Array(3);
+
+    /**
+     * @type {Float32Array}
+     */
+    #eye = new Float32Array(3);
+
+    /**
+     * @type {boolean}
+     */
+    #auto_adapt = false;
+
+    /**
+     * @type {VGEO_COLOR_MODE}
+     */
+    #color_mode = VGEO_COLOR_MODE.Cluster;
+
+    /**
+     * @type {string}
+     */
+    #status = 'drop a .vgeo file anywhere on the page';
+
+    /**
+     * @type {string}
+     */
+    #file_label = '';
+
+    /**
+     * @type {number}
+     */
+    #file_bytes = 0;
+
+    /**
+     * @type {number}
+     */
+    #read_ms = 0;
+
+    /**
+     * @type {number}
+     */
+    #build_ms = 0;
+
+    constructor() {
+        this.canvas = document.createElement('canvas');
+        this.renderer = new Renderer();
+        this.camera = new PerspectiveCamera();
+        this.scene = new Scene();
+
+        this.#dynamic.opaque = true;
+    }
+
+    /**
+     * @returns {Promise<void>}
+     */
+    async start() {
+        document.body.style.margin = '0';
+        document.body.style.overflow = 'hidden';
+        document.body.style.background = '#070b10';
+
+        this.canvas.style.position = 'absolute';
+        this.canvas.style.inset = '0';
+        this.canvas.style.outline = 'none';
+
+        // the orbital controller attaches a KeyboardDevice, and a canvas cannot receive key events
+        // without being focusable
+        this.canvas.tabIndex = 0;
+
+        document.body.appendChild(this.canvas);
+
+        this.canvas.focus();
+
+        await this.renderer.initialize({ context: this.canvas.getContext('webgpu') });
+
+        /*
+         Everything that would move the image for reasons unrelated to the cut is off. Automatic
+         exposure in particular: it adapts to whatever is on screen, so the same cluster would read
+         a different colour depending on how much of the model is in frame, which is exactly the
+         signal this tool is trying to show.
+         */
+        this.renderer.feature_automatic_exposure_enabled = false;
+        this.renderer.feature_taa_enabled = true;
+        this.renderer.feature_bloom_enabled = false;
+        this.renderer.feature_ssr_enabled = false;
+        this.renderer.feature_ssao_enabled = true;
+        this.renderer.feature_shadows_enabled = false;
+        this.renderer.feature_lpv_enabled = false;
+        this.renderer.pixel_ratio = 1;
+
+        this.scene.lights.add(make_sunlight({ intensity: 3 }));
+
+        this.camera.near = 0.05;
+        this.camera.far = 500;
+        this.camera.fov = 55 * DEG_TO_RAD;
+        this.camera.transform.position.set(0, 0.5, 2);
+        this.camera.transform.lookAt(Vector3.zero);
+
+        this.controller = new OrbitalCameraController(this.camera, this.canvas);
+        this.controller.distanceLimits.min = 1e-4;
+        this.controller.distanceLimits.max = 1e5;
+
+        this.#build_interface();
+        this.#fit_to_window();
+
+        window.addEventListener('resize', () => this.#fit_to_window());
+
+        this.renderer.add_extension(new VGEOViewerExtension(this));
+
+        create_frame_loop((dt) => this.#frame(dt));
+
+        const requested = new URL(window.location.href).searchParams.get('file');
+
+        if (requested !== null) {
+            await this.load_url(requested);
+        }
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        const graph = frame.graph;
+        const scene = frame.get(SceneColor);
+
+        scene.color = this.#dynamic.graph_draw({
+            graph,
+            batch: this.#batch,
+            color: scene.color,
+            depth: vgeo_graph_clear_depth(graph, frame.get(ViewTextures).depth),
+            camera: frame.view.camera.buffer,
+        });
+    }
+
+    #fit_to_window() {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        this.canvas.width = width;
+        this.canvas.height = height;
+
+        this.renderer.resize(width, height);
+
+        this.camera.aspect = this.renderer.aspect_ratio;
+
+        this.#view.screen_height = height;
+        this.#view.fov_y = this.camera.fov;
+    }
+
+    /**
+     * @param {number} dt seconds
+     */
+    #frame(dt) {
+        this.controller.update(dt);
+
+        const position = this.camera.transform.position;
+
+        const moved = position.x !== this.#eye[0]
+            || position.y !== this.#eye[1]
+            || position.z !== this.#eye[2];
+
+        this.#eye[0] = position.x;
+        this.#eye[1] = position.y;
+        this.#eye[2] = position.z;
+
+        if (moved && this.#auto_adapt) {
+            this.adapt();
+        }
+
+        this.renderer.render(this.camera, this.scene, dt);
+
+        if (moved) {
+            this.#refresh_cut();
+        }
+    }
+
+    /**
+     * Re-render the cut readout alone.
+     *
+     * Every number under it moves as the camera does — the drift on every frame, and the whole lot
+     * on every adapt when `follow the camera` is on. Rebuilding the *whole* panel at that rate would
+     * also rebuild the controls, which is how a slider stops being draggable mid-drag; this section
+     * holds no controls, so replacing it is free of that.
+     */
+    #refresh_cut() {
+        const host = this.panel.querySelector('#vgeo-cut');
+
+        if (host === null) {
+            return;
+        }
+
+        host.innerHTML = this.#cut_html();
+    }
+
+    /**
+     * The cut readout — the cluster count first, because it is the number the tool exists to show.
+     *
+     * @returns {string}
+     */
+    #cut_html() {
+        const cut = this.#cut;
+
+        return `<div class="count">${thousands(cut.clusters.length)}</div>`
+            + `<div class="muted" style="margin-bottom:6px">clusters in the current cut</div>`
+            + panel_table([
+                ['triangles', thousands(cut.triangle_count)],
+                ['groups', thousands(cut.groups_visited)],
+                ['pages resident', thousands(cut.pages_touched)],
+                ['clusters tested', thousands(cut.clusters_tested)],
+                ['culled subtrees', thousands(cut.culled)],
+                ['select / build', `${cut.duration_ms.toFixed(1)} / ${this.#build_ms.toFixed(1)} ms`],
+                ['camera drift', `${this.#drift().toExponential(2)} u`],
+            ]);
+    }
+
+    /**
+     * How far the camera has moved since the cut on screen was selected.
+     * @returns {number}
+     */
+    #drift() {
+        return Math.hypot(
+            this.#eye[0] - this.#cut_eye[0],
+            this.#eye[1] - this.#cut_eye[1],
+            this.#eye[2] - this.#cut_eye[2]
+        );
+    }
+
+    /**
+     * Take a fresh cut at wherever the camera is standing, and build the geometry for it.
+     */
+    adapt() {
+        if (this.#container === undefined) {
+            return;
+        }
+
+        // the frustum is derived from matrices the renderer refreshes during its own frame, and an
+        // adapt can land before one has run — a cut culled against last frame's planes would be a
+        // silent, hard-to-see wrong answer
+        this.camera.update();
+
+        this.#view.eye.set(this.#eye);
+        this.#view.screen_height = this.canvas.height;
+        this.#view.fov_y = this.camera.fov;
+        this.#view.frustum.set(this.camera.frustum);
+
+        this.#cut = vgeo_select_cut(this.#container, this.#view);
+
+        const started = performance.now();
+
+        const previous = this.#cut_geometry;
+
+        this.#cut_geometry = vgeo_build_cut_geometry(this.#container, this.#cut, this.#color_mode);
+
+        this.#build_ms = performance.now() - started;
+
+        this.#batch.clear();
+
+        // Residency is keyed on the geometry and deliberately survives leaving the batch, so the
+        // cut that was just replaced would hold its buffers forever otherwise — and this tool
+        // replaces one on every drag of the tau slider.
+        if (previous !== undefined) {
+            this.#dynamic.release(previous.geometry);
+        }
+
+        this.#mesh = DynamicMesh.from(this.#cut_geometry.geometry);
+        this.#mesh.updateMatrices();
+
+        this.#batch.add(this.#mesh);
+
+        this.#cut_eye.set(this.#eye);
+    }
+
+    /**
+     * @param {ArrayBuffer} array_buffer
+     * @param {string} label
+     */
+    load(array_buffer, label) {
+        this.#file_label = label;
+        this.#file_bytes = array_buffer.byteLength;
+
+        const started = performance.now();
+
+        try {
+            this.#container = vgeo_read_container(array_buffer);
+        } catch (e) {
+            this.#container = undefined;
+            this.#cut_geometry = undefined;
+            this.#batch.clear();
+            this.#status = String(e.message ?? e);
+            this.#refresh_panel();
+
+            throw e;
+        }
+
+        this.#read_ms = performance.now() - started;
+        this.#status = '';
+
+        this.#frame_camera();
+        this.adapt();
+        this.#refresh_panel();
+    }
+
+    /**
+     * @param {string} url
+     * @returns {Promise<void>}
+     */
+    async load_url(url) {
+        this.#status = `fetching ${url}`;
+        this.#refresh_panel();
+
+        const response = await fetch(url);
+
+        if (!response.ok) {
+            this.#status = `${url} — HTTP ${response.status}`;
+            this.#refresh_panel();
+
+            return;
+        }
+
+        this.load(await response.arrayBuffer(), url.split('/').pop());
+    }
+
+    /**
+     * Put the camera where the whole asset is on screen, and scale the clip range to it — vgeo
+     * assets are authored at whatever scale the source used, and the Stanford models are a tenth of
+     * a unit across.
+     */
+    #frame_camera() {
+        const sphere = this.#container.object_sphere;
+
+        const radius = Math.max(sphere[3], 1e-6);
+        const center = new Vector3(sphere[0], sphere[1], sphere[2]);
+
+        const distance = radius / Math.tan(this.camera.fov * 0.5) * 1.15;
+
+        const eye = new Vector3(0.55, 0.42, 0.72);
+
+        eye.normalize();
+        eye.multiplyScalar(distance);
+        eye.add(center);
+
+        this.camera.near = radius * 0.005;
+        this.camera.far = radius * 200;
+
+        this.controller.distanceLimits.min = radius * 0.02;
+        this.controller.distanceLimits.max = radius * 200;
+        this.controller.movement_speed_scale = radius;
+
+        this.controller.look(eye, center);
+
+        this.#eye[0] = eye.x;
+        this.#eye[1] = eye.y;
+        this.#eye[2] = eye.z;
+    }
+
+    #build_interface() {
+        const style = document.createElement('style');
+
+        style.textContent = PANEL_CSS;
+        document.head.appendChild(style);
+
+        const drop = document.createElement('div');
+
+        drop.id = 'vgeo-drop';
+        drop.textContent = 'drop a .vgeo file';
+        document.body.appendChild(drop);
+
+        let drag_depth = 0;
+
+        window.addEventListener('dragenter', (event) => {
+            event.preventDefault();
+            drag_depth++;
+            drop.classList.add('active');
+        });
+
+        window.addEventListener('dragover', (event) => event.preventDefault());
+
+        window.addEventListener('dragleave', () => {
+            drag_depth = Math.max(0, drag_depth - 1);
+
+            if (drag_depth === 0) {
+                drop.classList.remove('active');
+            }
+        });
+
+        window.addEventListener('drop', async (event) => {
+            event.preventDefault();
+
+            drag_depth = 0;
+            drop.classList.remove('active');
+
+            const file = event.dataTransfer.files[0];
+
+            if (file === undefined) {
+                return;
+            }
+
+            this.#status = `reading ${file.name}`;
+            this.#refresh_panel();
+
+            this.load(await file.arrayBuffer(), file.name);
+        });
+
+        this.panel = document.createElement('div');
+        this.panel.id = 'vgeo-panel';
+        document.body.appendChild(this.panel);
+
+        this.#refresh_panel();
+    }
+
+    /**
+     * @param {string} id
+     * @param {function(HTMLElement): void} bind
+     */
+    #wire(id, bind) {
+        const element = this.panel.querySelector(`#${id}`);
+
+        if (element !== null) {
+            bind(element);
+        }
+    }
+
+    #refresh_panel() {
+        const container = this.#container;
+
+        const header = [`<h1>.vgeo format viewer</h1>`];
+
+        if (this.#status !== '') {
+            header.push(`<div class="muted">${this.#status}</div>`);
+        }
+
+        if (container === undefined) {
+            this.panel.innerHTML = header.join('');
+
+            return;
+        }
+
+        const defects = container.defects;
+
+        const validation = defects.length === 0
+            ? `<div class="good">container valid — every invariant holds</div>`
+            : `<div class="bad">${defects.length} defect(s)</div><ol class="bad">${
+                defects.slice(0, 12).map((d) => `<li>${d.toString()}</li>`).join('')
+            }</ol>`;
+
+        const rows = [
+            ['file', `${this.#file_label} · ${human_bytes(this.#file_bytes)}`],
+            ['pages', page_storage(container)],
+            ['format', `v${container.format_version} · encoding ${container.payload_encoding}`],
+            ['asset id', container.asset_id.slice(0, 16)],
+            ['source', `${thousands(container.source_face_count)} tris / ${thousands(container.source_vertex_count)} verts`],
+            ['contents', `${thousands(container.cluster_count)} clusters · ${thousands(container.pages.length)} pages · ${container.levels.length} levels`],
+            ['per-vertex normals', `${thousands(container.per_vertex_normal_cluster_count)} / ${thousands(container.cluster_count)} clusters`],
+            ['read', `${this.#read_ms.toFixed(1)} ms`],
+        ];
+
+        this.panel.innerHTML = header.join('')
+            + `<h2>container</h2>${panel_table(rows)}`
+            + `<h2>validation</h2>${validation}`
+            + `<h2>cut</h2>`
+            + `<div id="vgeo-cut">${this.#cut_html()}</div>`
+            + `<h2>selection</h2>`
+            + `<div class="row"><span class="muted">tau</span><span id="vgeo-tau-value">${this.#view.tau.toFixed(2)} px</span></div>`
+            + `<input id="vgeo-tau" type="range" min="-1.3" max="1.7" step="0.01" value="${Math.log10(this.#view.tau)}">`
+            + `<button id="vgeo-adapt">adapt to view</button>`
+            + `<label><input id="vgeo-auto" type="checkbox" ${this.#auto_adapt ? 'checked' : ''}> follow the camera</label>`
+            + `<label><input id="vgeo-cull" type="checkbox" ${this.#view.cull_enabled ? 'checked' : ''}> frustum cull while selecting</label>`
+            + `<h2>display</h2>`
+            + `<select id="vgeo-color">`
+            + Object.values(VGEO_COLOR_MODE).map((mode) =>
+                `<option value="${mode}" ${mode === this.#color_mode ? 'selected' : ''}>colour by ${mode}</option>`
+            ).join('')
+            + `</select>`;
+
+        this.#wire('vgeo-adapt', (element) => {
+            element.onclick = () => {
+                this.adapt();
+                this.#refresh_panel();
+            };
+        });
+
+        this.#wire('vgeo-tau', (element) => {
+            element.oninput = () => {
+                this.#view.tau = Math.pow(10, Number(element.value));
+
+                this.adapt();
+                this.#refresh_panel();
+            };
+        });
+
+        this.#wire('vgeo-auto', (element) => {
+            element.onchange = () => {
+                this.#auto_adapt = element.checked;
+            };
+        });
+
+        this.#wire('vgeo-cull', (element) => {
+            element.onchange = () => {
+                this.#view.cull_enabled = element.checked;
+
+                this.adapt();
+                this.#refresh_panel();
+            };
+        });
+
+        this.#wire('vgeo-color', (element) => {
+            element.onchange = () => {
+                this.#color_mode = element.value;
+
+                this.adapt();
+                this.#refresh_panel();
+            };
+        });
+    }
+}
+
+const viewer = new VGeoViewer();
+
+window.__vgeo = viewer;
+
+viewer.start();