@woosh/meep-engine 3.20.0 → 3.22.0

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

@@ -0,0 +1,1302 @@
+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 { make_sunlight } from "../../renderer/light/make_sunlight.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', 64 * 1024],
+    ['256 KB — the default', 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 the resident 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 {VGeoPage[]} pages
+ * @returns {string}
+ */
+function page_storage(pages) {
+    if (pages.length === 0) {
+        return '—';
+    }
+
+    let stored = 0;
+    let decoded = 0;
+
+    for (const page of pages) {
+        stored += page.stored_size;
+        decoded += page.decoded_size;
+    }
+
+    const codec = Array.from(new Set(pages.map((page) => page.codec)))
+        .map(vgeo_codec_name)
+        .join(' + ');
+
+    return `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
+        + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`;
+}
+
+/**
+ * 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();
+
+        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;
+
+        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.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.#mesh.updateMatrices();
+
+        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 one nominal page plus the head, and a *default* build has 256 KB
+         pages. The sample's are 8 KB, so the same prefix would swallow most of it and there would be
+         nothing 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 this.#reader.validate();
+        } 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();
+
+        await this.#reader.install_all_pages((done, total) => {
+            this.#status = `installing every page — ${done} / ${total}`;
+        });
+
+        this.#status = '';
+
+        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 pages = reader.pages;
+
+        /*
+         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', page_storage(pages)],
+                ['per-vertex normals', this.#normal_share(pages)],
+            ]);
+    }
+
+    /**
+     * How many resident clusters store a normal per vertex, against how many are resident at all.
+     *
+     * 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 {VGeoPage[]} pages
+     * @returns {string}
+     */
+    #normal_share(pages) {
+        let per_vertex = 0;
+        let total = 0;
+
+        for (const page of pages) {
+            per_vertex += page.per_vertex_normal_cluster_count;
+            total += page.cluster_count;
+        }
+
+        return `${thousands(per_vertex)} / ${thousands(total)} clusters`;
+    }
+
+    /**
+     * @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,
+        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>`;
+});