@woosh/meep-engine 3.27.0 → 3.28.0

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

@@ -1,1343 +0,0 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { OrbitalCameraController } from "../../renderer/camera/orbital/index.js";
-import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
-import { create_frame_loop } from "../../renderer/create_frame_loop.js";
-import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../../renderer/depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
-import { DEPTH_BACKGROUND_VALUE } from "../../renderer/depth/DEPTH_BACKGROUND_VALUE.js";
-import { GPUDynamicMeshRenderer } from "../../renderer/dynamic/GPUDynamicMeshRenderer.js";
-import { FramePhase } from "../../renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../renderer/extension/SceneColor.js";
-import { ViewTextures } from "../../renderer/extension/ViewTextures.js";
-import {
-    vgeo_codec_name
-} from "../../renderer/geometry/virtual/format/frame/vgeo_codec_name.js";
-import {
-    VGeoByteSource
-} from "../../renderer/geometry/virtual/format/read/VGeoByteSource.js";
-import {
-    VGeoContainerReader
-} from "../../renderer/geometry/virtual/format/read/VGeoContainerReader.js";
-import {
-    vgeo_fetch_byte_source
-} from "../../renderer/geometry/virtual/format/read/vgeo_fetch_byte_source.js";
-import {
-    VGeoReadOptions
-} from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
-import {
-    vgeo_audit_container
-} from "../../renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js";
-import {
-    vgeo_install_all_pages
-} from "../../renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js";
-import { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { place_light } from "../../renderer/light/place_light.js";
-import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
-import { Renderer } from "../../renderer/Renderer.js";
-import { DynamicMesh } from "../../renderer/scene/DynamicMesh.js";
-import { DynamicMeshBatch } from "../../renderer/scene/DynamicMeshBatch.js";
-import { Scene } from "../../renderer/scene/Scene.js";
-import { VGEO_COLOR_MODE, vgeo_build_cut_geometry } from "./cut_geometry.js";
-import { vgeo_sample_source } from "./sample_asset.js";
-import { VGeoCut, VGeoCutView, vgeo_select_cut } from "./select_cut.js";
-
-/**
- * An interactive viewer for the `.vgeo` container.
- *
- * Point it at a file and it is opened *incrementally* — the header, the level table and the root
- * page, and after that only the pages a cut actually asks for. What is drawn is not the asset but
- * the **cut**: the clusters the container's own metric selects for where the camera is standing,
- * coloured so the seams between them are visible.
- *
- * Two things are therefore on screen at once, and telling them apart is the point of the tool:
- *
- * - **The cut is frozen until you ask for a new one.** "Adapt to view" re-runs the traversal at
- *   wherever the camera is 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 `follow the
- *   camera` on to watch it chase instead.
- * - **A cut taken from a partly-arrived file is clamped, not wrong.** Where the page holding a
- *   refinement is missing, the coarser cluster is drawn and a want is recorded — a watertight
- *   surface either way. `colour by clamp` paints exactly those regions, and `stream wanted pages`
- *   fetches them and re-adapts until the count reaches zero.
- *
- * 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.
- *
- * The reader under it is not a debug reader. It is `format/read/`, it is what a runtime would use,
- * and everything above — the traversal, the clamp, the wants — is the page's own. See README.md.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * How many wanted pages one streaming round installs before the cut is retaken and the panel
- * redrawn.
- *
- * Small on purpose. A round that installed every want would arrive as one step from coarse to final
- * and show nothing of the process; this is what makes refinement visible while it happens, which is
- * the only reason to look at a streaming reader rather than read its numbers.
- *
- * @type {number}
- */
-const STREAM_BATCH = 8;
-
-/**
- * The head prefixes the panel offers, in bytes.
- *
- * §10 gives a reader two cold starts and this is the dial between them: the header alone, and then
- * one exact range per page it decides it wants — or one speculative prefix that brings the head and
- * whatever else it happens to cover. Both are correct and they cost very differently, and which is
- * better depends entirely on how big the asset is against how much of it a view needs. Being able to
- * flip between them on one file, and watch `read` and `requests` move, is most of what there is to
- * learn about the front of this format.
- *
- * @type {[string, number][]}
- */
-const HEAD_PREFIXES = [
-    ['256 B — header only', 256],
-    ['16 KB', 16 * 1024],
-    ['64 KB — the default', 64 * 1024],
-    ['256 KB', 256 * 1024],
-    ['1 MB', 1024 * 1024],
-];
-
-/**
- * @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`;
-}
-
-/**
- * @param {string} text
- * @returns {string}
- */
-function escape_html(text) {
-    return String(text).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
-}
-
-/**
- * What a reader's quarantine amounts to, for the panel.
- *
- * A page that has failed its retries is not an error the viewer can act on — the clamped cut keeps
- * that surface correct with a coarser ancestor — but it is the difference between an asset that is
- * coarse because the camera just moved and one that is coarse because a page will never arrive, and
- * those look identical on screen. So the count goes on the panel, with the first reason.
- *
- * @param {VGeoContainerReader} reader
- * @returns {string}
- */
-function quarantine_summary(reader) {
-    const count = reader.quarantined_page_count;
-
-    if (count === 0) {
-        return 'none';
-    }
-
-    const [page, reason] = reader.quarantine().next().value;
-
-    return `${thousands(count)} page(s) · page ${page}: ${escape_html(reason)}`;
-}
-
-/**
- * Everything the panel says about the resident set, in one pass over it.
- *
- * One pass, and over `resident_pages()` rather than `pages`, because the panel refreshes on every
- * streaming round and `VGeoContainerReader.pages` is a snapshot that allocates an array and sorts
- * it — 0.29 ms at 20,000 resident pages, and this used to ask for two of them.
- *
- * Storage: stored is what gets fetched and what sits on disk, decoded is what 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 came first.
- *
- * Normals: worth saying outright because the alternative reads as a broken viewer. A source that
- * carried no normals encodes the engine default everywhere, every cluster compresses to one constant
- * word, and `colour by stored normal` comes out one flat colour across the whole model.
- *
- * @param {VGeoContainerReader} reader
- * @returns {{storage: string, normals: string}}
- */
-function page_summary(reader) {
-    let stored = 0;
-    let decoded = 0;
-    let per_vertex = 0;
-    let clusters = 0;
-    let pages = 0;
-
-    const codecs = new Set();
-
-    for (const page of reader.resident_pages()) {
-        stored += page.stored_size;
-        decoded += page.decoded_size;
-        per_vertex += page.per_vertex_normal_cluster_count;
-        clusters += page.cluster_count;
-
-        codecs.add(page.codec);
-
-        pages++;
-    }
-
-    const codec = Array.from(codecs).map(vgeo_codec_name).join(' + ');
-
-    return {
-        storage: pages === 0
-            ? '—'
-            : `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
-                + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`,
-        normals: `${thousands(per_vertex)} / ${thousands(clusters)} clusters`,
-    };
-}
-
-/**
- * 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);
-    }
-}
-
-/**
- * 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;
-}
-
-/**
- * The viewer. One container at a time, one cut at a time, and the cut only changes when asked.
- */
-class VGeoViewer {
-    /**
-     * @type {VGeoContainerReader|undefined}
-     */
-    #reader = undefined;
-
-    /**
-     * The source the current container was opened over, kept so that changing a read option can
-     * re-open it rather than ask for the file again.
-     * @type {VGeoByteSource|undefined}
-     */
-    #source = undefined;
-
-    /**
-     * @type {VGeoCutGeometry|undefined}
-     */
-    #cut_geometry = undefined;
-
-    /**
-     * @type {VGeoCut}
-     */
-    #cut = new VGeoCut();
-
-    /**
-     * @type {VGeoCutView}
-     */
-    #view = new VGeoCutView();
-
-    /**
-     * @type {VGeoReadOptions}
-     */
-    #read_options = new VGeoReadOptions();
-
-    /**
-     * Whether `?head=` named a prefix, in which case nothing here overrides it.
-     * @type {boolean}
-     */
-    #head_pinned = false;
-
-    /**
-     * @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;
-
-    /**
-     * Whether a clamped cut chases its own wants until there are none left.
-     * @type {boolean}
-     */
-    #auto_stream = true;
-
-    /**
-     * One streaming loop at a time — the loop retakes the cut between rounds, and two of them would
-     * be fetching against each other's want lists.
-     * @type {boolean}
-     */
-    #streaming = 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}
-     */
-    #open_ms = 0;
-
-    /**
-     * Bytes the source had served by the time the container was open — the cold start, measured.
-     * @type {number}
-     */
-    #open_bytes = 0;
-
-    /**
-     * @type {number}
-     */
-    #build_ms = 0;
-
-    /**
-     * What the last {@link VGeoContainerReader.validate} came to, or `undefined` while it has never
-     * been asked for — which is the default and the ordinary state.
-     * @type {VGeoDefect[]|undefined}
-     */
-    #defects = undefined;
-
-    /**
-     * @type {string}
-     */
-    #validation_status = 'not run';
-
-    constructor() {
-        this.canvas = document.createElement('canvas');
-        this.renderer = new Renderer();
-        this.camera = new PerspectiveCamera();
-        this.scene = new Scene();
-
-        // the sun stands at an entity, so the scene names a dataset for it
-        this.scene.dataset = new EntityComponentDataset();
-
-        this.#dynamic.opaque = true;
-    }
-
-    /**
-     * @returns {VGeoContainerReader|undefined}
-     */
-    get reader() {
-        return this.#reader;
-    }
-
-    /**
-     * @returns {VGeoCut}
-     */
-    get cut() {
-        return this.#cut;
-    }
-
-    /**
-     * Whether a clamped cut chases its own wants until there are none left.
-     *
-     * Setting it does not start a run — a caller that wants one calls {@link stream} and holds the
-     * promise, which is what a scripted session needs in order to wait for the end of it.
-     *
-     * @param {boolean} value
-     */
-    set_auto_stream(value) {
-        this.#auto_stream = value;
-    }
-
-    /**
-     * @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;
-
-        place_light(this.scene, make_sunlight({ intensity: 3 }));
-
-        this.camera.near = 0.05;
-        this.camera.far = 500;
-        this.camera.fov = 55 * DEG_TO_RAD;
-        this.camera.transform.setTranslation(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 query = new URL(window.location.href).searchParams;
-
-        const head = query.get('head');
-
-        if (head !== null) {
-            this.#read_options.head_prefix_bytes = Number(head);
-            this.#head_pinned = true;
-        }
-
-        this.#read_options.validate = query.get('validate') !== null;
-        this.#read_options.verify_frames = query.get('verify') !== null;
-
-        const requested = query.get('file');
-
-        if (requested !== null) {
-            await this.load_url(requested);
-        } else if (query.get('sample') !== null) {
-            await this.open_sample();
-        }
-    }
-
-    /**
-     * @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;
-
-        const moved = position.translation_x !== this.#eye[0]
-            || position.translation_y !== this.#eye[1]
-            || position.translation_z !== this.#eye[2];
-
-        this.#eye[0] = position.translation_x;
-        this.#eye[1] = position.translation_y;
-        this.#eye[2] = position.translation_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,
-     * and the clamp count second, because it is the one that says the picture is still arriving.
-     *
-     * @returns {string}
-     */
-    #cut_html() {
-        const cut = this.#cut;
-
-        const clamped = cut.clamped === 0
-            ? `<span class="good">0 — this is the cut the file selects</span>`
-            : `<span class="warn">${thousands(cut.clamped)} waiting on ${cut.wants.length} page(s)</span>`;
-
-        const rows = [
-            ['triangles', thousands(cut.triangle_count)],
-            ['clamped', clamped],
-            ['groups', thousands(cut.groups_visited)],
-            ['pages read', 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`],
-        ];
-
-        /*
-         A clamp whose child page is already resident is waiting on a page holding one of that
-         group's *other* parents (§10, activation) — so it is not counted by any want, and without
-         this row the panel reads as `20 waiting on 5 page(s)` while five pages would not have
-         settled all twenty. Only shown when it happens, which on a small asset is never.
-        */
-        if (cut.clamped_on_activation > 0) {
-            rows.push([
-                'of those, on a parent',
-                `<span class="warn">${thousands(cut.clamped_on_activation)}</span>`
-            ]);
-        }
-
-        if (cut.broken_child_refs > 0) {
-            rows.push(['broken child refs', `<span class="bad">${thousands(cut.broken_child_refs)}</span>`]);
-        }
-
-        return `<div class="count">${thousands(cut.clusters.length)}</div>`
-            + `<div class="muted" style="margin-bottom:6px">clusters in the current cut</div>`
-            + panel_table(rows);
-    }
-
-    /**
-     * 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, from whatever the reader currently holds,
-     * and build the geometry for it.
-     */
-    adapt() {
-        if (this.#reader === 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.#reader, this.#view);
-
-        const started = performance.now();
-
-        const previous = this.#cut_geometry;
-
-        this.#cut_geometry = vgeo_build_cut_geometry(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.#batch.add(this.#mesh);
-
-        this.#cut_eye.set(this.#eye);
-    }
-
-    /**
-     * Fetch the pages the current cut is clamped against, a batch at a time, retaking the cut after
-     * each — until nothing is clamped, or the loop is turned off, or a round installs nothing.
-     *
-     * Note what is *not* here: any handling for the cut being wrong in the meantime. It is not. Every
-     * intermediate cut this loop draws is a complete watertight surface at some level of detail, so
-     * there is nothing to hide while it converges and nothing to reconcile when it does.
-     *
-     * @returns {Promise<void>}
-     */
-    async stream() {
-        if (this.#streaming || this.#reader === undefined) {
-            return;
-        }
-
-        this.#streaming = true;
-
-        try {
-            while (this.#cut.wants.length > 0) {
-                const before = this.#reader.resident_page_count;
-
-                this.#status = `fetching ${Math.min(this.#cut.wants.length, STREAM_BATCH)}`
-                    + ` of ${this.#cut.wants.length} wanted page(s)`;
-
-                this.#refresh_panel();
-
-                await this.#reader.install_wants(this.#cut.wants, STREAM_BATCH);
-
-                // A round that installed nothing means every want is unfetchable, and continuing
-                // would be a spin against the same list forever.
-                if (this.#reader.resident_page_count === before) {
-                    this.#status = 'the wanted pages could not be installed';
-                    break;
-                }
-
-                this.#status = '';
-
-                this.adapt();
-                this.#refresh_panel();
-
-                if (!this.#auto_stream) {
-                    break;
-                }
-            }
-        } catch (e) {
-            this.#status = String(e.message ?? e);
-
-            throw e;
-        } finally {
-            this.#streaming = false;
-            this.#refresh_panel();
-        }
-    }
-
-    /**
-     * Open a container over a byte source, and take the first cut.
-     *
-     * @param {VGeoByteSource} source
-     * @returns {Promise<void>}
-     */
-    async open(source) {
-        this.#source = source;
-        this.#file_label = source.name;
-        this.#defects = undefined;
-        this.#validation_status = 'not run';
-        this.#status = `opening ${source.name}`;
-
-        source.reset_counters();
-
-        this.#refresh_panel();
-
-        const started = performance.now();
-
-        try {
-            this.#reader = await VGeoContainerReader.open(source, this.#read_options);
-        } catch (e) {
-            this.#reader = undefined;
-            this.#cut = new VGeoCut();
-            this.#cut_geometry = undefined;
-            this.#batch.clear();
-            this.#status = String(e.message ?? e);
-            this.#refresh_panel();
-
-            throw e;
-        }
-
-        this.#open_ms = performance.now() - started;
-        this.#open_bytes = source.bytes_read;
-        this.#status = '';
-
-        this.#frame_camera();
-        this.adapt();
-        this.#refresh_panel();
-
-        if (this.#auto_stream) {
-            await this.stream();
-        }
-    }
-
-    /**
-     * @param {Blob} blob a dropped `File`
-     * @returns {Promise<void>}
-     */
-    open_blob(blob) {
-        return this.open(VGeoByteSource.from_blob(blob));
-    }
-
-    /**
-     * Build a container in the page and open it, so there is something to look at without a file.
-     *
-     * The source is over bytes already in memory, which changes nothing above it: the reader still
-     * opens on the head and installs a page at a time, and the panel's `read` still says what
-     * fraction of the container this view actually cost.
-     *
-     * @returns {Promise<void>}
-     */
-    async open_sample() {
-        this.#status = 'building a sample asset';
-        this.#refresh_panel();
-
-        // yielded so the status paints before the builder takes the thread for a second
-        await new Promise((resolve) => setTimeout(resolve, 0));
-
-        const sample = vgeo_sample_source();
-
-        /*
-         The default prefix is 64 KB, sized against a *default* build's pages of hundreds of KB. The
-         sample's are 8 KB, so even that prefix would swallow much of it and there would be little
-         left to stream — a demonstration of the head prefix rather than of the reader. Sized to the
-         sample's own pages instead, unless the address bar has already made the choice.
-        */
-        if (!this.#head_pinned) {
-            this.#read_options.head_prefix_bytes = 16 * 1024;
-        }
-
-        await this.open(sample.source);
-
-        this.#status = `built in ${sample.build_ms.toFixed(0)} ms`;
-        this.#refresh_panel();
-    }
-
-    /**
-     * Open the current source again, from cold, under whatever the read options now say.
-     *
-     * Which is the point of it: the head prefix and frame verification are decisions taken at open
-     * time, and comparing two of them means comparing two opens. Nothing is re-fetched that the
-     * source would not have re-fetched anyway — a URL source really does go back to the network,
-     * which is what makes the cold-start number honest.
-     *
-     * @returns {Promise<void>}
-     */
-    async reopen() {
-        if (this.#source === undefined) {
-            return;
-        }
-
-        await this.open(this.#source);
-    }
-
-    /**
-     * @param {string} url
-     * @returns {Promise<void>}
-     */
-    async load_url(url) {
-        this.#status = `probing ${url}`;
-        this.#refresh_panel();
-
-        try {
-            await this.open(await vgeo_fetch_byte_source(url));
-        } catch (e) {
-            this.#status = `${url} — ${e.message ?? e}`;
-            this.#refresh_panel();
-        }
-    }
-
-    /**
-     * Run the whole-file audit, which is the one thing here that reads every byte.
-     *
-     * @returns {Promise<VGeoDefect[]>}
-     */
-    async validate() {
-        if (this.#reader === undefined) {
-            return [];
-        }
-
-        this.#validation_status = 'reading the whole file…';
-        this.#refresh_panel();
-
-        const started = performance.now();
-
-        try {
-            this.#defects = await vgeo_audit_container(this.#reader);
-        } catch (e) {
-            this.#defects = undefined;
-            this.#validation_status = String(e.message ?? e);
-            this.#refresh_panel();
-
-            throw e;
-        }
-
-        this.#validation_status = `${(performance.now() - started).toFixed(0)} ms`;
-        this.#refresh_panel();
-
-        return this.#defects;
-    }
-
-    /**
-     * Install every page the directory lists — the opposite of what this reader is for, and what a
-     * question about the file rather than about a view of it wants.
-     *
-     * @returns {Promise<void>}
-     */
-    async load_all_pages() {
-        if (this.#reader === undefined) {
-            return;
-        }
-
-        this.#status = 'installing every page';
-        this.#refresh_panel();
-
-        try {
-            await vgeo_install_all_pages(this.#reader, (done, total) => {
-                this.#status = `installing every page — ${done} / ${total}`;
-            });
-
-            this.#status = '';
-        } catch (e) {
-            // A page that could not be read is quarantined rather than fatal now, and the tool
-            // reports at the end rather than stopping at the first one — so every page that *could*
-            // be installed is here, and the message says how many could not.
-            this.#status = String(e.message ?? e);
-        }
-
-        this.adapt();
-        this.#refresh_panel();
-    }
-
-    /**
-     * Drop everything but the root page, so the file arrives again from cold.
-     */
-    reset_residency() {
-        if (this.#reader === undefined) {
-            return;
-        }
-
-        this.#reader.evict_all();
-
-        this.adapt();
-        this.#refresh_panel();
-
-        if (this.#auto_stream) {
-            this.stream();
-        }
-    }
-
-    /**
-     * 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.#reader.header.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 drop = document.getElementById('vgeo-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;
-            }
-
-            await this.open_blob(file);
-        });
-
-        this.panel = document.getElementById('vgeo-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);
-        }
-    }
-
-    /**
-     * The container section: what the header said, and what has actually been read.
-     *
-     * The second half is the point of the whole exercise. `read` against `file` is the fraction of
-     * the asset this view cost, and on anything larger than a toy it is a small one.
-     *
-     * @returns {string}
-     */
-    #container_html() {
-        const reader = this.#reader;
-        const header = reader.header;
-        const source = reader.source;
-
-        const summary = page_summary(reader);
-
-        /*
-         Cumulative for the session, and deliberately allowed past the file's own size: evicting and
-         re-streaming really does fetch those pages again, and the audit really does read every byte.
-         Rendered as a multiple rather than a percentage once it passes one, because "151.8%" reads
-         as a broken counter and "1.52× the file" reads as what it is.
-        */
-        const read_share = source.byte_length === 0
-            ? ''
-            : source.bytes_read < source.byte_length
-                ? ` (${(100 * source.bytes_read / source.byte_length).toFixed(1)}% of the file)`
-                : ` (${(source.bytes_read / source.byte_length).toFixed(2)}× the file)`;
-
-        return panel_table([
-            ['file', `${escape_html(this.#file_label)} · ${human_bytes(source.byte_length)}`],
-            ['format', `v${header.format_version} · encoding ${header.payload_encoding}`],
-            ['asset id', header.asset_id.slice(0, 16)],
-            ['source', `${thousands(header.source_face_count)} tris / ${thousands(header.source_vertex_count)} verts`],
-            ['contents', `${thousands(header.total_clusters)} clusters · ${thousands(header.total_pages)} pages · ${header.levels.length} levels`],
-        ])
-            + `<h2>streaming</h2>`
-            + panel_table([
-                ['read so far', `${human_bytes(source.bytes_read)}${read_share}`],
-                ['requests', thousands(source.request_count)],
-                ['cold start', `${human_bytes(this.#open_bytes)} · ${this.#open_ms.toFixed(1)} ms`],
-                ['resident', `${thousands(reader.resident_page_count)} / ${thousands(header.total_pages)} pages · ${human_bytes(reader.resident_bytes)}`],
-                ['page storage', summary.storage],
-                ['per-vertex normals', summary.normals],
-                ['head prefix', reader.head_bytes === 0 ? 'released' : human_bytes(reader.head_bytes)],
-                ['quarantined', quarantine_summary(reader)],
-            ]);
-    }
-
-
-    /**
-     * @returns {string}
-     */
-    #validation_html() {
-        const defects = this.#defects;
-
-        const note = `<div class="muted" style="margin-bottom:4px">`
-            + `off by default — it reads the whole file</div>`;
-
-        if (defects === undefined) {
-            return note
-                + `<div class="muted">${escape_html(this.#validation_status)}</div>`
-                + `<button id="vgeo-validate">validate the whole file</button>`;
-        }
-
-        const verdict = 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>${escape_html(d.toString())}</li>`).join('')
-            }</ol>`;
-
-        return note
-            + verdict
-            + `<div class="row"><span class="muted">took</span><span>${escape_html(this.#validation_status)}</span></div>`
-            + `<button id="vgeo-validate">validate again</button>`;
-    }
-
-    #refresh_panel() {
-        const reader = this.#reader;
-
-        const header = [`<h1>.vgeo viewer</h1>`];
-
-        if (this.#status !== '') {
-            header.push(`<div class="muted">${escape_html(this.#status)}</div>`);
-        }
-
-        if (reader === undefined) {
-            this.panel.innerHTML = header.join('')
-                + `<div class="muted" style="margin-top:8px">`
-                + `or open <code>?file=/some/asset.vgeo</code></div>`
-                + `<button id="vgeo-sample">build a sample asset</button>`;
-
-            this.#wire('vgeo-sample', (element) => {
-                element.onclick = () => this.open_sample();
-            });
-
-            return;
-        }
-
-        this.panel.innerHTML = header.join('')
-            + `<h2>container</h2>${this.#container_html()}`
-            + `<button id="vgeo-stream" ${this.#cut.wants.length === 0 ? 'disabled' : ''}>`
-            + `stream ${this.#cut.wants.length} wanted page(s)</button>`
-            + `<label><input id="vgeo-auto-stream" type="checkbox" ${this.#auto_stream ? 'checked' : ''}> stream until nothing is clamped</label>`
-            + `<label><input id="vgeo-verify" type="checkbox" ${this.#read_options.verify_frames ? 'checked' : ''}> verify each frame's checksum</label>`
-            + `<button id="vgeo-load-all">install every page</button>`
-            + `<button id="vgeo-evict">evict everything but the root</button>`
-            + `<div class="row" style="margin-top:8px"><span class="muted">head prefix</span>`
-            + `<span class="muted">re-opens from cold</span></div>`
-            + `<select id="vgeo-head">`
-            + HEAD_PREFIXES.map(([label, size]) =>
-                `<option value="${size}" ${size === this.#read_options.head_prefix_bytes ? 'selected' : ''}>${label}</option>`
-            ).join('')
-            + `</select>`
-            + `<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>`
-            + `<h2>validation</h2>${this.#validation_html()}`;
-
-        this.#wire('vgeo-adapt', (element) => {
-            element.onclick = () => {
-                this.adapt();
-                this.#refresh_panel();
-            };
-        });
-
-        this.#wire('vgeo-stream', (element) => {
-            element.onclick = () => this.stream();
-        });
-
-        this.#wire('vgeo-auto-stream', (element) => {
-            element.onchange = () => {
-                this.set_auto_stream(element.checked);
-
-                if (element.checked) {
-                    this.stream();
-                }
-            };
-        });
-
-        this.#wire('vgeo-verify', (element) => {
-            // read per fetch, so this takes effect on the next page rather than on a reopen
-            element.onchange = () => {
-                this.#read_options.verify_frames = element.checked;
-            };
-        });
-
-        this.#wire('vgeo-head', (element) => {
-            element.onchange = () => {
-                this.#read_options.head_prefix_bytes = Number(element.value);
-
-                this.reopen();
-            };
-        });
-
-        this.#wire('vgeo-load-all', (element) => {
-            element.onclick = () => this.load_all_pages();
-        });
-
-        this.#wire('vgeo-evict', (element) => {
-            element.onclick = () => this.reset_residency();
-        });
-
-        this.#wire('vgeo-validate', (element) => {
-            element.onclick = () => this.validate();
-        });
-
-        this.#wire('vgeo-tau', (element) => {
-            element.oninput = () => {
-                this.#view.tau = Math.pow(10, Number(element.value));
-
-                this.adapt();
-                this.#refresh_panel();
-
-                if (this.#auto_stream) {
-                    this.stream();
-                }
-            };
-        });
-
-        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();
-
-/*
- Everything a session might want to reach for, and the handles a scripted one needs. A page that can
- be driven from the console is one that can be driven from a headless browser, which is what makes
- this verifiable without a person watching it.
-*/
-Object.assign(globalThis, {
-    __vgeo: viewer,
-
-    __open_url: (url) => viewer.load_url(url),
-    __open_sample: () => viewer.open_sample().then(__state),
-    __adapt: () => {
-        viewer.adapt();
-
-        return __state();
-    },
-    __stream: () => viewer.stream().then(__state),
-    __validate: () => viewer.validate().then((defects) => defects.map(String)),
-    __state,
-});
-
-/**
- * Everything a scripted session asks about, in one object.
- *
- * @returns {object}
- */
-function __state() {
-    const reader = viewer.reader;
-    const cut = viewer.cut;
-
-    return {
-        open: reader !== undefined,
-        asset_id: reader?.header.asset_id,
-        total_pages: reader?.header.total_pages,
-        total_clusters: reader?.header.total_clusters,
-        resident_pages: reader?.resident_page_count ?? 0,
-        resident_bytes: reader?.resident_bytes ?? 0,
-        head_bytes: reader?.head_bytes ?? 0,
-        quarantined_pages: reader?.quarantined_page_count ?? 0,
-        file_bytes: reader?.source.byte_length ?? 0,
-        bytes_read: reader?.source.bytes_read ?? 0,
-        requests: reader?.source.request_count ?? 0,
-        clusters: cut.clusters.length,
-        triangles: cut.triangle_count,
-        clamped: cut.clamped,
-        clamped_on_activation: cut.clamped_on_activation,
-        wants: cut.wants.length,
-        broken_child_refs: cut.broken_child_refs,
-    };
-}
-
-viewer.start().catch((e) => {
-    console.error(e);
-
-    document.getElementById('vgeo-panel').innerHTML =
-        `<h1>.vgeo viewer</h1><div class="bad">${e.message ?? e}</div>`;
-});