@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -1,6 +1,5 @@
 import { Color } from "../../../core/color/Color.js";
 import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
 import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
@@ -8,23 +7,27 @@ import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
 import { FramePhase } from "../../renderer/extension/FramePhase.js";
 import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
 import { VGEO_CUT_STAT } from "../../renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
-import { VGeoFeedbackLoop } from "../../renderer/geometry/virtual/runtime/VGeoFeedbackLoop.js";
 import { VirtualGeometry } from "../../renderer/geometry/virtual/runtime/VirtualGeometry.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 {
-    VGeoResidencyManager
-} from "../../renderer/geometry/virtual/residency/VGeoResidencyManager.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { place_light } from "../../renderer/light/place_light.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 import { Renderer } from "../../renderer/Renderer.js";
 import { place_primitive } from "../../renderer/scene/rows/place_primitive.js";
 import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
 import { vgeo_sample_source } from "../vgeo_viewer/sample_asset.js";
 
 /**
@@ -48,6 +51,12 @@ import { vgeo_sample_source } from "../vgeo_viewer/sample_asset.js";
  *   are what fetch the rest.
  * - **nothing is drawn twice.** `drawn` against the triangle count the rasterizer reports.
  *
+ * The container is built in the page so there is something to look at on load, but the page is not
+ * about that container: **drop a `.vgeo` file on it**, or open it at `?file=`, and the asset is
+ * swapped for a real one. That is the reading worth having, because a sample built here is a torus
+ * of thirteen pages and an asset off a converter is thousands — and the claim being made is about
+ * the second.
+ *
  * `__state()` is what a headless session asserts on; everything the panel shows comes from it.
  *
  * @author Alex Goldring
@@ -56,6 +65,39 @@ import { vgeo_sample_source } from "../vgeo_viewer/sample_asset.js";
 
 const element = id => document.getElementById(id);
 
+/**
+ * The page size every container shown here is expected to have been built at.
+ *
+ * One number for the asset and for the tier that holds it, and it is fixed for the life of the
+ * page: a page size is a bound the container states (FORMAT §11.14), the pool lays its arena out in
+ * slots of exactly that stride, and there is no slot-size class table. So a dropped container built
+ * at a different size is refused at `register` — loudly, by an error naming both numbers — rather
+ * than reconciled. The sample is built at this size for the same reason.
+ *
+ * @type {number}
+ */
+const PAGE_SIZE = 64 * 1024;
+
+/**
+ * Page slots the VRAM tier is built with, over the engine's default of 1,024.
+ *
+ * The default is sized for a scene, and this page is a single-asset viewer for containers off a
+ * converter — where a ninth of a measured 2,975-asset set has more than a thousand pages, and the
+ * largest has seventeen thousand. At 1,024 slots the tier fills, `install` starts refusing, and the
+ * cut clamps against a *budget* rather than against τ: the surface stays watertight and goes coarse,
+ * `clamped` stops falling to zero, and the one claim this page exists to show — that the cut is a
+ * function of the threshold and the resolution, not of the source — is no longer what you are
+ * looking at.
+ *
+ * It is cheap in the place it sounds expensive. A slot holds a page's *runtime rows* rather than its
+ * payload — an eighth of the page size, see `vgeo_runtime_page_slot_words` — so this is a 32 MB
+ * arena, and the payload goes where a static mesh's meshlets go. What it does spend is the decoded
+ * budget the pool derives from it, which is 256 MB.
+ *
+ * @type {number}
+ */
+const PAGE_CAPACITY = 4096;
+
 /**
  * Opens the VG frame before anything records a rasterization pass, because the seam inside those
  * passes writes into the feedback buffer this creates.
@@ -103,10 +145,70 @@ class VGeoFrameEnd extends RenderExtension {
 
 class VGeoPlayground {
     /**
-     * @type {VGeoContainerReader}
+     * @type {Renderer}
+     */
+    renderer;
+
+    /**
+     * Held for a session driving the page rather than for anything here: `fit` measures the
+     * document, and the renderer is what writes this element's two sizes.
+     * @type {HTMLCanvasElement}
+     */
+    canvas;
+
+    /**
+     * @type {Scene}
+     */
+    scene;
+
+    /**
+     * @type {GPUSceneContext}
+     */
+    scene_context;
+
+    /**
+     * @type {PerspectiveCamera}
+     */
+    camera;
+
+    /**
+     * @type {OrbitalCameraController}
+     */
+    controller;
+
+    /**
+     * The one material every asset is drawn with — a `Front`-sided standard material, which is what
+     * makes this page able to report a container whose triangles face the wrong way. The viewer
+     * beside it draws with `cullMode: 'none'` and cannot.
+     *
+     * @type {StandardShadeMaterial}
+     */
+    material;
+
+    /**
+     * The open container, or `undefined` before the first one arrives.
+     * @type {VGeoContainerReader|undefined}
      */
     reader;
 
+    /**
+     * @type {VGeoByteSource|undefined}
+     */
+    source;
+
+    /**
+     * What the scene draws the container as, held so that {@link retire} can give its record back
+     * to the geometry manager — nothing else names it once `place_primitive` has returned.
+     * @type {VirtualGeometry|undefined}
+     */
+    geometry;
+
+    /**
+     * The entity the container is drawn at, or `-1` when nothing is placed.
+     * @type {number}
+     */
+    entity = -1;
+
     /**
      * @type {GPUVirtualGeometryRuntime}
      */
@@ -118,7 +220,7 @@ class VGeoPlayground {
     feedback;
 
     /**
-     * @type {VGeoResidencyManager}
+     * @type {VGeoResidency}
      */
     residency;
 
@@ -127,32 +229,110 @@ class VGeoPlayground {
      */
     frames = 0;
 
+    /**
+     * Height of the render target in pixels, which is what τ is measured against — so it follows
+     * the window, and moving the page to a display of a different density changes it.
+     * @type {number}
+     */
+    screen_height = 1;
+
     /**
      * @type {number}
      */
-    canvas_height = 600;
+    screen_width = 1;
 
     /**
      * @type {number}
      */
-    fov_y = 50 * DEG_TO_RAD;
+    fov_y = 1;
+
+    /**
+     * One open at a time. Opening is asynchronous and the frame loop keeps running underneath it,
+     * so two drops in flight would race on the swap below.
+     * @type {boolean}
+     */
+    loading = false;
+
+    /**
+     * @type {string}
+     */
+    status_text = '';
+
+    /**
+     * @param {string} text
+     * @param {boolean} [error]
+     */
+    status(text, error = false) {
+        this.status_text = text;
+
+        const node = element('status');
+
+        node.textContent = text;
+        node.classList.toggle('error', error);
+    }
+
+    /**
+     * Bring the canvas, the renderer, the camera and the cut's own notion of the screen up to the
+     * size the window actually is.
+     *
+     * **Measured from the document, never from the canvas.** `Renderer` takes CSS pixels here and
+     * writes back both of the canvas's sizes when it configures the context — the backing store in
+     * device pixels, and an *inline* `style.width`/`style.height` in CSS pixels. An inline style
+     * wins over a stylesheet, so a canvas laid out at `width: 100%` stops following the window the
+     * moment the first frame is drawn, and a `fit` that then read `clientWidth` back would be
+     * reading the renderer its own last answer: the canvas would never change size again, which is
+     * exactly how this page shipped with a fixed viewport.
+     *
+     * Three things downstream have to follow, and all three are why a fixed-size canvas was wrong
+     * rather than merely small:
+     *
+     * - the camera's **aspect**, which comes off the renderer rather than the window, because the
+     *   internal resolution is what the projection has to match;
+     * - the cut's **screen height**, because `err_px = r_e * screen_height / (2 tan(fov/2) d)` is a
+     *   count of *render-target* pixels, and a τ of one pixel against a screen height the window
+     *   has outgrown selects a cut for a screen nobody is looking at;
+     * - the cut's **fov**, for the same reason, so that changing the camera's is enough.
+     */
+    fit() {
+        const renderer = this.renderer;
+
+        const viewport = document.documentElement;
+
+        const width = Math.max(1, Math.floor(viewport.clientWidth));
+        const height = Math.max(1, Math.floor(viewport.clientHeight));
+
+        // a window dragged onto a display of another density changes this and nothing else
+        renderer.pixel_ratio = globalThis.devicePixelRatio || 1;
+
+        renderer.resize(width, height);
+
+        this.camera.aspect = renderer.aspect_ratio;
+
+        /*
+         The internal resolution rather than the output one: the rasterizer draws at
+         `output × internal_resolution_scale` and upscales, and the cut is selected for what is
+         rasterized. At the scale of 1 this page runs at, the two are the same number.
+        */
+        const resolution = renderer.output_resolution;
+        const scale = renderer.internal_resolution_scale;
+
+        this.screen_width = Math.max(1, Math.floor(resolution.x * scale));
+        this.screen_height = Math.max(1, Math.floor(resolution.y * scale));
+
+        this.fov_y = this.camera.fov;
+    }
 
     /**
      * @param {FrameContext} frame
      */
     begin(frame) {
-        this.runtime.begin_frame(frame.graph, {
-            screen_height: this.canvas_height,
-            fov_y: this.fov_y,
-        });
+        this.runtime.begin_frame({ graph: frame.graph });
     }
 
     /**
      * @param {FrameContext} frame
      */
     finish(frame) {
-        // the RAM tier's clock moves inside this: a host that drives the loop gets a bounded
-        // second tier without having to know it had one to wind
         this.feedback.read(frame.graph);
 
         this.runtime.end_frame();
@@ -160,6 +340,226 @@ class VGeoPlayground {
         this.frames++;
     }
 
+    /**
+     * Open a container over a byte source and put it on screen in place of whatever is there.
+     *
+     * A refusal leaves the page exactly as it was, which is the reason the new container is
+     * registered *before* the old one is taken down: the two ways this fails — a container built at
+     * another page size, and a tier with no room for another root — both fail inside `register`,
+     * and a page that had already dropped its asset to find that out would answer a bad file with
+     * an empty screen and an error, rather than with the error alone.
+     *
+     * @param {VGeoByteSource} source
+     * @returns {Promise<boolean>} whether the asset on screen changed
+     */
+    async load(source) {
+        if (this.loading) {
+            this.status(`a container is still opening — ${source.name} was ignored`, true);
+
+            return false;
+        }
+
+        this.loading = true;
+
+        this.status(`opening ${source.name}…`);
+
+        try {
+            /*
+             Frame verification on, because this reader is a runtime's rather than a tool's —
+             format §10 leaves it off by default precisely because a tool reading a file it just
+             built is not defending against a network, and a runtime is. A dropped file is the case
+             that was always meant: bytes this page did not produce.
+            */
+            const options = new VGeoReadOptions();
+
+            options.verify_frames = true;
+
+            // the runtime answers activation in the arena; the reader's own counters would be
+            // tens of megabytes at fifty thousand pages, read by nothing
+            options.track_selectability = false;
+
+            source.reset_counters();
+
+            const started = performance.now();
+
+            const reader = await VGeoContainerReader.open(source, options);
+
+            const open_ms = performance.now() - started;
+
+            this.adopt(reader, source);
+
+            this.status(
+                `${source.name} — ${reader.header.total_pages} pages,`
+                + ` opened in ${open_ms.toFixed(0)} ms`
+            );
+
+            return true;
+        } catch (error) {
+            this.status(error.message ?? String(error), true);
+
+            console.error(error);
+
+            return false;
+        } finally {
+            this.loading = false;
+        }
+    }
+
+    /**
+     * The same door the drop target opens, for a session that has no pointer to drop with — and for
+     * a link to an asset. A `.vgeo` is read by ranges, so this is one `HEAD` and one request per
+     * page the cut asks for, against a server that honours `Range`.
+     *
+     * @param {string} url
+     * @returns {Promise<boolean>} whether the asset on screen changed
+     */
+    async load_url(url) {
+        this.status(`probing ${url}…`);
+
+        let source;
+
+        try {
+            source = await vgeo_fetch_byte_source(url);
+        } catch (error) {
+            this.status(`${url} — ${error.message ?? error}`, true);
+
+            return false;
+        }
+
+        return this.load(source);
+    }
+
+    /**
+     * Register an open container with both tiers, retire the one it replaces, and place it.
+     *
+     * @param {VGeoContainerReader} reader
+     * @param {VGeoByteSource} source
+     */
+    adopt(reader, source) {
+        /*
+         Only the root page is resident. Everything else arrives because the cut asked for it,
+         which is the loop this page exists to show — and it means the first frames draw a
+         coarse, watertight surface rather than nothing at all. A refusal throws here and
+         leaves nothing registered.
+        */
+        const geometry_row = this.residency.register(reader);
+
+        this.retire();
+
+        this.reader = reader;
+        this.source = source;
+        this.geometry = new VirtualGeometry(reader);
+
+        this.geometry.vg_row = geometry_row;
+
+        this.entity = place_primitive(
+            this.scene_context, this.geometry, this.material, new Transform64(),
+            { name: source.name }
+        );
+
+        this.frame_camera(reader.header.object_sphere);
+
+        /*
+         The scene it is drawing has just been replaced wholesale, which is what this exists to be
+         told. TAA reprojects through motion vectors, and the pixels the new container covers have
+         no correspondence in a history written from the old one — so without this the first frames
+         after a drop blend one asset's colour into the other's silhouette.
+        */
+        this.renderer.indicate_view_change();
+    }
+
+    /**
+     * Give back everything the container on screen holds: its mesh row, its entity, its geometry
+     * record, its VRAM pages and the decoded bytes it was holding in RAM.
+     *
+     * **Detaching the mesh row is only the first of them.** `detach_mesh` gives back the `meshes`
+     * row and releases the material, and it does *not* give the geometry back to
+     * `GPUGeometryManager` — `#write_mesh` calls `add` and `#free_mesh` has no matching `remove`.
+     * So without the line below, every container ever dropped stayed named by the manager, and the
+     * record it was named by holds the `VirtualGeometry`, which holds the **reader**, which holds
+     * every page that reader had decoded. The RAM tier's bytes were not merely uncollected, they
+     * were unreachable. Five drops, measured: with `remove`, the manager names none of the five
+     * retired geometries and each retired reader is down to its one pinned root page; without it,
+     * all five and everything they had streamed.
+     *
+     * `evict_all` is then about *when* rather than whether — it releases the decoded pages at the
+     * swap instead of at whatever garbage collection comes next, which is worth having when the
+     * container leaving held a hundred megabytes and the one arriving is about to ask for its own.
+     * `VGeoResidencyManager.unregister` says in as many words that this is the caller's business:
+     * it stops counting a reader against the budget and drops nothing.
+     *
+     * What this does *not* give back is the geometry **id**. `__last_geometry_index` only ever
+     * counts up — `remove` frees the record, the BLAS slot and the meshlet batch, but not the
+     * index — so the metadata table and the BLAS address lookup are still one row longer per drop.
+     * Measured at 64 bytes a drop, which is a residual rather than a leak worth a playground
+     * reaching into the geometry manager over.
+     *
+     * `abort()` first, and that is not tidiness either. The wants in flight name page indices *of
+     * the container being retired*, and a fetch that lands after its reader is gone resolves a byte
+     * range out of a child table nothing owns any more.
+     */
+    retire() {
+        if (this.entity !== -1) {
+            this.scene_context.rows.detach_mesh(this.entity);
+            this.scene.dataset.removeEntity(this.entity);
+
+            this.entity = -1;
+        }
+
+        if (this.geometry !== undefined) {
+            this.scene_context.geometries.remove(this.geometry);
+
+            this.geometry = undefined;
+        }
+
+        const reader = this.reader;
+
+        if (reader === undefined) {
+            return;
+        }
+
+        // gives back its rows, its lookup, its RAM slots, and cancels what it had on the wire
+        this.residency.unregister(reader);
+
+        reader.evict_all();
+
+        this.reader = undefined;
+        this.source = undefined;
+    }
+
+    /**
+     * Stand the camera off the container's own bounding sphere.
+     *
+     * A sample torus is a unit across and sits at the origin; a converted asset can be a centimetre
+     * or a hundred metres, and can stand a long way from it. Everything that has a length in it —
+     * the near plane, the orbit limits, the speed the controller moves at — is taken from the
+     * radius for the same reason: a near plane of 2 cm is right for the torus and puts a whole
+     * building inside itself.
+     *
+     * @param {Float32Array} sphere centre xyz then radius, object space — and object space is world
+     *     space here, because the primitive is placed at the identity
+     */
+    frame_camera(sphere) {
+        const radius = sphere[3] > 0 ? sphere[3] : 1;
+
+        const center = new Vector3(sphere[0], sphere[1], sphere[2]);
+
+        const eye = new Vector3(0.35, 0.45, 1);
+
+        eye.normalize();
+        eye.multiplyScalar(radius * 2.8);
+        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);
+    }
+
     /**
      * Everything a headless session needs, and everything the panel shows.
      *
@@ -168,12 +568,25 @@ class VGeoPlayground {
     state() {
         const stats = this.feedback.stats;
         const pool = this.runtime.pool;
+        const reader = this.reader;
 
         return {
             frames: this.frames,
             tau: this.runtime.tau,
+            status: this.status_text,
+            screen_width: this.screen_width,
+            screen_height: this.screen_height,
             feedback_reads: this.feedback.read_count,
             feedback_skipped: this.feedback.skipped_frames,
+            asset: {
+                name: this.source?.name ?? '',
+                bytes: this.source?.byte_length ?? 0,
+                // this thread's reads and the workers', which the source never sees
+                bytes_read: (this.source?.bytes_read ?? 0) + this.residency.fetcher.worker_bytes_read,
+                faces: reader === undefined ? 0 : Number(reader.header.source_face_count),
+                radius: reader?.header.object_sphere[3] ?? 0,
+                page_size: reader?.header.nominal_page_size ?? 0,
+            },
             cut: {
                 drawn: stats[VGEO_CUT_STAT.DRAWN],
                 clamped: stats[VGEO_CUT_STAT.CLAMPED],
@@ -182,6 +595,7 @@ class VGeoPlayground {
                 items: stats[VGEO_CUT_STAT.ITEMS],
                 clusters_tested: stats[VGEO_CUT_STAT.CLUSTERS_TESTED],
                 culled_frustum: stats[VGEO_CUT_STAT.CULLED_FRUSTUM],
+                culled_cluster: stats[VGEO_CUT_STAT.CULLED_CLUSTER],
                 culled_lod: stats[VGEO_CUT_STAT.CULLED_LOD],
                 meshlets_dropped: stats[VGEO_CUT_STAT.MESHLETS_DROPPED],
                 wants_dropped: stats[VGEO_CUT_STAT.WANTS_DROPPED],
@@ -195,103 +609,176 @@ class VGeoPlayground {
             vram: {
                 pages: pool.resident_page_count,
                 bytes: pool.resident_bytes,
-                evicted: pool.evicted_page_count,
-                refused: pool.refused_install_count,
+                evicted: this.residency.evicted_vram_count,
+                refused: this.residency.refused_install_count,
             },
             ram: {
-                pages: this.reader.resident_page_count,
-                bytes: this.reader.resident_bytes,
-                total_pages: this.reader.header.total_pages,
+                pages: this.residency.ram_page_count,
+                bytes: this.residency.ram_resident_bytes,
+                evicted: this.residency.evicted_ram_count,
+                refused: this.residency.refused_fetch_count,
+                total_pages: reader?.header.total_pages ?? 0,
             },
+            fetches_in_flight: this.residency.fetches_in_flight,
+            worker_fetches: this.residency.fetcher.worker_fetch_count,
+            in_process_fetches: this.residency.fetcher.in_process_fetch_count,
+            deferred: this.residency.deferred_want_count,
         };
     }
 }
 
-async function start() {
-    const canvas = element('view');
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function human_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Take a file the moment it is dropped anywhere on the page.
+ *
+ * Counted rather than latched, because `dragleave` fires for every element the pointer crosses on
+ * its way in — the overlay's own, the panel's — and a boolean flag put the hint away while the file
+ * was still over the window.
+ *
+ * @param {VGeoPlayground} page
+ */
+function wire_drop_target(page) {
+    const overlay = element('drop');
 
-    const status = text => {
-        element('status').textContent = text;
+    let depth = 0;
+
+    const hide = () => {
+        depth = 0;
+
+        overlay.classList.remove('active');
     };
 
-    const renderer = new Renderer();
+    globalThis.addEventListener('dragenter', event => {
+        event.preventDefault();
 
-    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+        depth++;
 
-    renderer.feature_taa_enabled = false;
-    renderer.feature_ssao_enabled = false;
-    renderer.feature_bloom_enabled = false;
+        overlay.classList.add('active');
+    });
 
-    renderer.resize(canvas.width, canvas.height);
+    globalThis.addEventListener('dragover', event => event.preventDefault());
 
-    status('building a container in the page…');
+    globalThis.addEventListener('dragleave', () => {
+        depth = Math.max(0, depth - 1);
 
-    /*
-     One number for the asset and for the tier that holds it. A page size is a bound the container
-     states (FORMAT §11.14) and the pool holds pages at exactly one, so a mismatch here is a refusal
-     at `register` rather than something that limps.
-     */
-    const page_size = 64 * 1024;
+        if (depth === 0) {
+            overlay.classList.remove('active');
+        }
+    });
 
-    const { source, build_ms } = vgeo_sample_source(128, 48, page_size);
+    globalThis.addEventListener('drop', async event => {
+        event.preventDefault();
 
-    /*
-     Frame verification on, because this reader is a runtime's rather than a tool's — format §10
-     leaves it off by default precisely because a tool reading a file it just built is not
-     defending against a network, and a runtime is.
-     */
-    const options = new VGeoReadOptions();
+        hide();
+
+        const file = event.dataTransfer?.files[0];
 
-    options.verify_frames = true;
+        if (file === undefined) {
+            return;
+        }
 
-    const reader = await VGeoContainerReader.open(source, options);
+        await page.load(VGeoByteSource.from_blob(file));
+
+        // the controller's keyboard device listens on the body, and a drop leaves focus elsewhere
+        document.body.focus();
+    });
+}
+
+async function start() {
+    const canvas = element('view');
 
     const page = new VGeoPlayground();
 
-    page.reader = reader;
-    page.canvas_height = canvas.height;
+    page.canvas = canvas;
+
+    const renderer = new Renderer();
+
+    page.renderer = renderer;
+
+    await renderer.initialize({
+        context: canvas.getContext('webgpu'),
+        pixelRatio: globalThis.devicePixelRatio || 1,
+    });
 
-    page.residency = new VGeoResidencyManager();
-    page.residency.register(reader);
+    /*
+     TAA on, which for a page about a *cut* is not a cosmetic choice. A cut is selected per frame
+     against a threshold in pixels, so the clusters it draws change under the camera and the seams
+     between two levels of detail land on different pixels from one frame to the next. Without a
+     temporal filter every one of those is an aliased edge that crawls, and the crawl reads as the
+     cut being unstable when it is the rasterizer being point-sampled. It also costs the readings
+     nothing: TAA is downstream of the G-buffer, and the cut has already been selected and drawn
+     by the time it runs.
+
+     SSAO and bloom stay off. They are off because this page is a measurement harness and they are
+     two more passes between a change and its effect, not because they would break anything.
+    */
+    renderer.feature_taa_enabled = true;
+    renderer.feature_ssao_enabled = false;
+    renderer.feature_bloom_enabled = false;
 
     const scene = new Scene();
 
-    // the sun stands at an entity, and so does the torus, so the scene names a dataset
+    // the sun stands at an entity, and so does the asset, so the scene names a dataset
     scene.dataset = new EntityComponentDataset();
 
+    page.scene = scene;
+
     // a light stands at an entity of the dataset now, like everything else the scene holds
     place_light(scene, make_sunlight());
 
+    /*
+     Image-based lighting, and the reason is the geometry rather than the picture. A sun alone puts
+     every surface facing away from it at ambient zero, and the whole point of a cut is what happens
+     at the silhouette and in the creases — the places a single directional light renders as flat
+     black. A converted asset arrives with normals and no material authoring, so the environment is
+     most of what there is to shade it with.
+
+     Not awaited, and the page does not depend on it: `test_assets/` is gitignored, so a fresh
+     checkout has no sky and gets the sun alone, which still draws every triangle the cut selected.
+     The environment lands a frame or two later when it is there.
+    */
+    load_default_environment(scene);
+
     const camera = new PerspectiveCamera();
 
-    camera.near = 0.02;
-    camera.far = 200;
-    camera.fov = page.fov_y;
-    camera.aspect = canvas.width / canvas.height;
+    camera.fov_degrees = 50;
 
-    const controller = new OrbitalCameraController(camera, document.body);
+    page.camera = camera;
+    page.controller = new OrbitalCameraController(camera, document.body);
 
-    controller.look(new Vector3(0, 1.6, 3.6), new Vector3(0, 0, 0));
+    page.fit();
+
+    globalThis.addEventListener('resize', () => page.fit());
 
     // one frame to let the renderer build its scene context, which is what owns the geometry manager
     renderer.render(camera, scene, 1 / 60);
 
     const scene_context = renderer.scenes.obtain(scene);
 
-    const runtime = scene_context.enable_virtual_geometry({ page_size });
-
-    page.runtime = runtime;
-
-    /*
-     Only the root page is resident. Everything else arrives because the cut asked for it, which is
-     the loop this page exists to show — and it means the first frames draw a coarse, watertight
-     surface rather than nothing at all.
-     */
-    const geometry_row = runtime.pool.register(reader);
-
-    const geometry = new VirtualGeometry(reader);
+    page.scene_context = scene_context;
+    page.runtime = scene_context.enable_virtual_geometry({
+        page_size: PAGE_SIZE,
+        table_options: { page_capacity: PAGE_CAPACITY },
+    });
 
-    geometry.vg_row = geometry_row;
+    // the scene context built both tiers and the loop with the runtime; this page only reads them
+    page.residency = scene_context.virtual_geometry_residency;
+    page.feedback = scene_context.virtual_geometry_feedback;
 
     const material = new StandardShadeMaterial();
 
@@ -299,11 +786,7 @@ async function start() {
     material.roughness_factor = 0.55;
     material.metallic_factor = 0;
 
-    place_primitive(
-        scene_context, geometry, material, new Transform64(), { name: 'virtual torus' }
-    );
-
-    page.feedback = new VGeoFeedbackLoop({ runtime, residency: page.residency });
+    page.material = material;
 
     /*
      The loop's only teardown caller anywhere, and worth having for the same reason M12's clock was:
@@ -318,15 +801,71 @@ async function start() {
     renderer.add_extension(new VGeoFrameEnd(page));
 
     element('tau').addEventListener('input', event => {
-        runtime.tau = Number(event.target.value);
+        page.runtime.tau = Number(event.target.value);
 
-        element('tau-value').textContent = runtime.tau.toFixed(2);
+        element('tau-value').textContent = page.runtime.tau.toFixed(2);
+    });
+
+    // a drag on the τ slider is a drag on the body, and the camera controller listens there
+    element('panel').addEventListener('pointerdown', event => event.stopPropagation());
+
+    wire_drop_target(page);
+
+    /*
+     T records a GPU capture, T again saves it — the same key the other playgrounds bind, out of the
+     same module (`playground/profile_hotkey.js`), so there is one implementation of the drain and
+     the `.sgpt` naming rather than one per page.
+
+     What it is for here is the question this page cannot otherwise answer. Every reading in the
+     panel is a *count* — clusters drawn, pages visited, wavefronts run — and none of them is a
+     cost. The cut is four compute passes ahead of a G-buffer that does not know virtual geometry
+     exists, so what is worth knowing is how the seed, the traverse loop, the collect and the
+     expansion compare against the rasterization they feed, and whether the descent's wavefront
+     count shows up as time or disappears into occupancy. That is a capture, not a counter.
+
+     The settings line is what makes one readable. A pass at 0.4 ms says nothing without τ, the
+     asset and the cut it selected — the same 0.4 ms is a triumph at 10,000 clusters and a scandal
+     at nine — so all three go into the note beside the adapter and the resolution.
+    */
+    install_profile_hotkey({
+        renderer,
+        name: "vgeo_runtime",
+        status: element('profile-status'),
+        settings: () => {
+            const state = page.state();
+
+            return [
+                `τ=${state.tau}px`,
+                state.asset.name,
+                `${state.cut.drawn} clusters`,
+                `${state.vram.pages} resident of ${state.ram.total_pages}`,
+                `${state.screen_width}×${state.screen_height}`,
+            ];
+        },
     });
 
     globalThis.__state = () => page.state();
     globalThis.__page = page;
+    globalThis.__load_url = url => page.load_url(url);
+
+    const requested = new URL(globalThis.location.href).searchParams.get('file');
 
-    status(`container built in ${build_ms.toFixed(0)} ms · ${reader.header.total_pages} pages`);
+    if (requested !== null) {
+        await page.load_url(requested);
+    } else {
+        page.status('building a container in the page…');
+
+        // yielded so the status paints before the builder takes the thread for half a second
+        await new Promise(resolve => setTimeout(resolve, 0));
+
+        const { source, build_ms } = vgeo_sample_source(128, 48, PAGE_SIZE);
+
+        await page.load(source);
+
+        page.status(
+            `${page.reader.header.total_pages} pages, built in the page in ${build_ms.toFixed(0)} ms`
+        );
+    }
 
     let stopped = false;
     let last_time;
@@ -334,12 +873,24 @@ async function start() {
     function paint() {
         const state = page.state();
 
+        const name = escape_html(state.asset.name);
+
+        element('asset').innerHTML = [
+            ['source', `<span title="${name}">${name}</span>`],
+            ['triangles', state.asset.faces.toLocaleString()],
+            ['file', human_bytes(state.asset.bytes)],
+            ['read', human_bytes(state.asset.bytes_read)],
+            ['view', `${state.screen_width}×${state.screen_height}`],
+        ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
+            .join('');
+
         element('cut').innerHTML = [
             ['drawn clusters', state.cut.drawn],
             ['clamped', state.cut.clamped],
             ['pages visited', state.cut.pages],
             ['clusters tested', state.cut.clusters_tested],
             ['subtrees culled', state.cut.culled_frustum + state.cut.culled_lod],
+            ['clusters culled', state.cut.culled_cluster],
             ['wants', state.wants],
         ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
             .join('');
@@ -347,11 +898,25 @@ async function start() {
         const dropped = state.cut.meshlets_dropped + state.cut.queue_dropped
             + state.cut.instances_dropped;
 
+        /*
+         `refused` is the tier saying it had nowhere to put a page the cut asked for, and it is the
+         one reading that explains a picture going coarse for a reason that is not τ. It belongs
+         beside `clamped` above: a clamped count that will not fall to zero while this climbs is a
+         budget, not a threshold.
+        */
         element('residency').innerHTML = [
-            ['VRAM pages', `${state.vram.pages}`],
-            ['VRAM bytes', `${(state.vram.bytes / 1024).toFixed(0)} KB`],
+            ['VRAM pages', `${state.vram.pages} / ${PAGE_CAPACITY}`],
+            ['VRAM bytes', human_bytes(state.vram.bytes)],
             ['RAM pages', `${state.ram.pages} / ${state.ram.total_pages}`],
+            ['RAM evicted', state.ram.evicted],
+            ['fetching', state.fetches_in_flight],
+            ['worker fetches', `${state.worker_fetches} / ${state.worker_fetches + state.in_process_fetches}`],
             ['evicted', state.vram.evicted],
+            [
+                'refused',
+                `<span class="${state.vram.refused > 0 ? 'bad' : 'good'}">`
+                + `${state.vram.refused.toLocaleString()}</span>`,
+            ],
             ['dropped', `<span class="${dropped > 0 ? 'bad' : 'good'}">${dropped}</span>`],
         ].map(([name, value]) => `<div class="row"><span>${name}</span><span>${value}</span></div>`)
             .join('');
@@ -367,14 +932,13 @@ async function start() {
         last_time = time;
 
         try {
-            controller.update(dt);
+            page.controller.update(dt);
 
             renderer.render(camera, scene, dt);
         } catch (error) {
             stopped = true;
 
-            status(error.message ?? String(error));
-            element('status').classList.add('error');
+            page.status(error.message ?? String(error), true);
 
             console.error(error);
 
@@ -389,6 +953,19 @@ async function start() {
     requestAnimationFrame(tick);
 }
 
+/**
+ * A file name arrives from a drop and lands in the panel's markup, so it is a string from outside
+ * the page in the one place a string from outside the page can do something.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escape_html(text) {
+    return text.replace(/[&<>"]/g, character => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;',
+    })[character]);
+}
+
 start().catch(error => {
     element('status').textContent = error.message ?? String(error);
     element('status').classList.add('error');