@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,875 @@
+import package_json from "../../../../package.json";
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
+import { shader_avboit_build_warp } from "../../renderer/rasterize/native/avboit/shader_avboit_build_warp.js";
+import { shader_avboit_draw_brick4 } from "../../renderer/rasterize/native/avboit/shader_avboit_draw_brick4.js";
+import { shader_avboit_draw_ibl } from "../../renderer/rasterize/native/avboit/shader_avboit_draw_ibl.js";
+import { shader_avboit_integrate } from "../../renderer/rasterize/native/avboit/shader_avboit_integrate.js";
+import { shader_avboit_occupancy } from "../../renderer/rasterize/native/avboit/shader_avboit_occupancy.js";
+import { shader_avboit_resolve } from "../../renderer/rasterize/native/avboit/shader_avboit_resolve.js";
+import { shader_avboit_splat } from "../../renderer/rasterize/native/avboit/shader_avboit_splat.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { ShadeIndirectLightingMode } from "../../renderer/ShadeIndirectLightingMode.js";
+import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
+import { load_default_environment } from "../load_default_environment.js";
+
+/**
+ * AVBOIT against MBOIT on the deck's own test case: a stack of near-opaque cards whose depth
+ * separation is a control, plus a tinted glass pane and an opaque surface pushed through the
+ * transparency pipeline, over an opaque backdrop.
+ *
+ * What to look for (deck slides 35–45 and 86–92):
+ *
+ *  - With `alpha` near 1 and a few units of spacing, the front card should hide everything behind
+ *    it. MBOIT is not depth-complexity invariant and lets the cards behind bleed through as the stack
+ *    deepens; AVBOIT should not, because each card lands in its own slice.
+ *  - As `spacing` drops toward zero the cards share a slice and AVBOIT degrades to weighted
+ *    blending — the "frequency soup" the deck describes. The spacing at which that starts is the
+ *    slice thickness at that depth, and the adaptive warp is what keeps it small.
+ *  - The glass pane tints what is behind it under AVBOIT (per-channel transmittance) once
+ *    "tint transmitted light by base colour" is on — `renderer.avboit.transmission_tint_from_base_color`,
+ *    off by default so the three modes agree on what the material means — and never under MBOIT
+ *    or the tracer, which have no per-channel transmission.
+ *  - The "opaque quad, transparent material" is the deck's own fail case for moments (slides 35–38):
+ *    an alpha-1 surface pushed through the transparency pipeline. Both pipelines clamp coverage at
+ *    0.997, so it should read as opaque, with a hard edge against whatever is behind it. Moments
+ *    smear that step — the surface leaks what is behind it and its edges tear where the depth
+ *    jumps — while a voxel slice holds it.
+ *  - "path traced (reference)" hands the frame to the accumulating path tracer, which rolls each
+ *    transparent hit against its alpha and so converges to the exact order-independent answer for
+ *    the card stack. It has no per-channel transmission tint, so for the glass pane it is a
+ *    reference for the Fresnel coverage only, not for the tint (see the README).
+ *
+ * The camera orbits (drag), zooms (wheel) and pans (right drag); its state copies to the clipboard
+ * as JSON and pastes back, so a view that shows something can be handed over exactly. A GPU profile
+ * recording downloads an `.sgpt` capture the gpu-inspector-tool reads.
+ *
+ * The camera, its controller and every control are wired *before* the device is requested, so on
+ * a browser with no adapter the page still orbits and copies its camera — which is also what lets
+ * the input path be exercised where the renderer cannot run.
+ *
+ * `npm run dev`, then `/src/shade/playground/avboit/`. Everything is also reachable from the console
+ * as `renderer`, `scene`, `camera`, `controller`, `configure(settings)`, `camera_state()`,
+ * `apply_camera(state)`, `compile_check()`, `start_profile()` and `stop_profile()`.
+ */
+
+const CAMERA = {
+    position: new Vector3(0, 2.5, 12),
+    target: new Vector3(0, 1.5, 0),
+    fov_degrees: 45,
+    near: 0.1,
+    far: 200,
+};
+
+const VIEWPORT = { width: 1280, height: 720 };
+
+/**
+ * Card colours, front to back; strong hues so bleed-through is unmistakable.
+ * @type {Color[]}
+ */
+const CARD_COLORS = [
+    new Color(0.95, 0.25, 0.2),
+    new Color(0.2, 0.55, 0.95),
+    new Color(0.25, 0.9, 0.3),
+    new Color(0.95, 0.85, 0.2),
+    new Color(0.9, 0.3, 0.9),
+    new Color(0.3, 0.9, 0.9),
+];
+
+const GLASS_TINTS = {
+    red: new Color(1.0, 0.15, 0.15, 1),
+    green: new Color(0.15, 1.0, 0.15, 1),
+    blue: new Color(0.15, 0.15, 1.0, 1),
+    none: new Color(1, 1, 1, 1),
+};
+
+/**
+ * The modules the compile check pushes through the device, by name.
+ * @type {[string, () => string][]}
+ */
+const AVBOIT_MODULES = [
+    ["occupancy", () => shader_avboit_occupancy.descriptor.source],
+    ["build warp", () => shader_avboit_build_warp.descriptor.source],
+    ["splat / vertex", () => shader_avboit_splat.pipeline.vertex.module.code],
+    ["splat / fragment", () => shader_avboit_splat.pipeline.fragment.module.code],
+    ["integrate", () => shader_avboit_integrate.descriptor.source],
+    ["draw IBL / vertex", () => shader_avboit_draw_ibl.pipeline.vertex.module.code],
+    ["draw IBL / fragment", () => shader_avboit_draw_ibl.pipeline.fragment.module.code],
+    ["draw Brick4 / vertex", () => shader_avboit_draw_brick4.pipeline.vertex.module.code],
+    ["draw Brick4 / fragment", () => shader_avboit_draw_brick4.pipeline.fragment.module.code],
+    ["resolve", () => shader_avboit_resolve.descriptor.source],
+];
+
+/**
+ * How much a profile capture records: pass spans, the frame graph, dispatch and draw counts — the
+ * level the inspector's timeline and pass detail read. See `volumetrics_froxel/main.js` for the
+ * per-frame cost; a hand-driven recording of a few seconds does not notice it.
+ * @type {number}
+ */
+const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
+
+/**
+ * The running-mean floor while tracing. The tracer's default 0.01 turns the mean into a 100-sample
+ * exponential average, which keeps a viewport responsive but never settles below that noise floor;
+ * a reference wants it lower. Restored when leaving reference mode.
+ * @type {number}
+ */
+const REFERENCE_MIN_ACCUMULATION_ALPHA = 0.002;
+
+/**
+ * A meshlet plane, the only geometry the renderer draws.
+ *
+ * @param {number} width
+ * @param {number} height
+ * @returns {MeshletGeometry}
+ */
+function make_plane(width, height) {
+    const geometry = make_plane_geometry(width, height, 1, 1);
+    const meshlets = new MeshletGeometry();
+
+    meshlet_geometry_build_from_geometry(geometry, meshlets);
+
+    return meshlets;
+}
+
+/**
+ * @param {Color} diffuse rgb and alpha
+ * @param {object} [options]
+ * @param {number} [options.transmission]
+ * @param {boolean} [options.transparent]
+ * @returns {StandardShadeMaterial}
+ */
+function make_material(diffuse, { transmission = 0, transparent = true } = {}) {
+    const material = new StandardShadeMaterial();
+
+    material.diffuse_color.copy(diffuse);
+    material.roughness_factor = 0.6;
+    material.metallic_factor = 0;
+    material.transmission_factor = transmission;
+    material.ior_factor = 1.5;
+    material.transparency_mode = transparent ? TransparencyMode.Transparent : TransparencyMode.Opaque;
+    material.draw_side = ShadeDrawSide.Double;
+
+    return material;
+}
+
+/**
+ * @param {MeshletGeometry} geometry
+ * @param {StandardShadeMaterial} material
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ * @returns {Mesh}
+ */
+function place(geometry, material, position, rotation = new Quaternion()) {
+    const mesh = Mesh.from(geometry, material);
+
+    mesh.transform_local.setTranslation(position.x, position.y, position.z);
+    mesh.transform_local.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    mesh.updateMatrices();
+
+    return mesh;
+}
+
+/**
+ * Compile every AVBOIT module on the live device and collect what the compiler said.
+ *
+ * `pushErrorScope("validation")` catches the module-creation error; `getCompilationInfo` carries the
+ * per-line messages. Both are reported, because a module that fails to create has its reason in the
+ * second and only a one-line summary in the first.
+ *
+ * @param {GPUDevice} device
+ * @returns {Promise<{name: string, ok: boolean, messages: string[]}[]>}
+ */
+async function compile_all(device) {
+    const results = [];
+
+    for (const [name, get_source] of AVBOIT_MODULES) {
+        device.pushErrorScope("validation");
+
+        const module = device.createShaderModule({ label: `avboit playground / ${name}`, code: get_source() });
+
+        const error = await device.popErrorScope();
+        const info = await module.getCompilationInfo();
+
+        const messages = info.messages
+            .filter(m => m.type !== "info")
+            .map(m => `${m.type} ${m.lineNum}:${m.linePos} ${m.message}`);
+
+        if (error !== null) {
+            messages.unshift(`validation: ${error.message.split("\n")[0]}`);
+        }
+
+        results.push({ name, ok: error === null && !info.messages.some(m => m.type === "error"), messages });
+    }
+
+    return results;
+}
+
+/**
+ * Hand an ArrayBuffer to the browser as a file.
+ *
+ * @param {ArrayBuffer} bytes
+ * @param {string} filename
+ */
+function download_bytes(bytes, filename) {
+    const url = URL.createObjectURL(new Blob([bytes], { type: 'application/octet-stream' }));
+
+    const anchor = document.createElement('a');
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+/**
+ * `YYYYMMDD-HHMMSS` in local time, the naming the other `.sgpt` captures use.
+ *
+ * @returns {string}
+ */
+function file_timestamp() {
+    const now = new Date();
+
+    const pad = value => String(value).padStart(2, '0');
+
+    return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+        + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+function format_bytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    }
+
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const report_element = element('report');
+
+    /**
+     * @param {string} text
+     * @param {string} [state] pass | fail | ''
+     */
+    function report(text, state = '') {
+        report_element.textContent = text;
+        report_element.className = state;
+        console.log(text);
+    }
+
+    /**
+     * Run a control's handler and put its failure in the panel. A handler that throws otherwise
+     * leaves the page looking as if the button did nothing, with the reason only in the console.
+     *
+     * @param {string} what
+     * @param {() => (void|Promise<void>)} action
+     * @returns {Promise<void>}
+     */
+    async function guarded(what, action) {
+        try {
+            await action();
+        } catch (e) {
+            console.error(`${what} failed`, e);
+            report(`${what} failed: ${e.message}`, 'fail');
+        }
+    }
+
+    const canvas = element('view');
+
+    canvas.width = VIEWPORT.width;
+    canvas.height = VIEWPORT.height;
+
+    // ---- camera, before anything needs a device ----------------------------------------------
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = CAMERA.near;
+    camera.far = CAMERA.far;
+    camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
+    camera.aspect = VIEWPORT.width / VIEWPORT.height;
+    camera.transform.setTranslation(CAMERA.position[0], CAMERA.position[1], CAMERA.position[2]);
+    camera.transform.lookAt(CAMERA.target);
+    camera.transform.updateMatrix();
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element can receive key events — body carries tabindex for exactly that
+    const controller = new OrbitalCameraController(camera, document.body);
+    controller.look(CAMERA.position, CAMERA.target);
+    controller.movement_speed_scale = 4;
+
+    // handy from the console, and on the page as early as they exist
+    Object.assign(globalThis, { camera, controller });
+
+    /**
+     * Where the camera is and what it orbits, as plain numbers: enough to put another instance of
+     * this page in exactly the same view.
+     *
+     * @returns {{position: number[], target: number[], fov_degrees: number}}
+     */
+    globalThis.camera_state = () => {
+        const p = camera.transform;
+        const t = controller.target;
+
+        const round = v => Math.round(v * 1000) / 1000;
+
+        return {
+            position: [round(p.translation_x), round(p.translation_y), round(p.translation_z)],
+            target: [round(t.x), round(t.y), round(t.z)],
+            fov_degrees: round(camera.fov / DEG_TO_RAD),
+        };
+    };
+
+    /** @type {Renderer|null} the renderer once its device is up; null before and on failure */
+    let renderer = null;
+
+    /**
+     * Put the camera where a {@link camera_state} says. The controller moves the camera on its next
+     * update, so the frame after this one is the one that shows it.
+     *
+     * @param {{position: number[], target: number[], fov_degrees?: number}|string} state
+     */
+    globalThis.apply_camera = state => {
+        const parsed = typeof state === 'string' ? JSON.parse(state) : state;
+
+        if (parsed.fov_degrees !== undefined) {
+            camera.fov = parsed.fov_degrees * DEG_TO_RAD;
+        }
+
+        controller.look(
+            new Vector3(parsed.position[0], parsed.position[1], parsed.position[2]),
+            new Vector3(parsed.target[0], parsed.target[1], parsed.target[2])
+        );
+
+        renderer?.indicate_view_change();
+    };
+
+    element('copy_camera').addEventListener('click', () => guarded('copy camera', async () => {
+        const text = JSON.stringify(globalThis.camera_state());
+
+        element('camera_state').value = text;
+
+        try {
+            await navigator.clipboard.writeText(text);
+            report(`camera copied: ${text}`);
+        } catch (e) {
+            // clipboard access wants a secure context and a user gesture; the box has it anyway
+            report(`camera (clipboard unavailable, copy from the box): ${text}`);
+        }
+    }));
+
+    element('apply_camera').addEventListener('click', () => guarded('apply camera', () => {
+        globalThis.apply_camera(element('camera_state').value);
+        report(`camera applied: ${element('camera_state').value}`);
+    }));
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    // ---- the scene, which needs no device either ----------------------------------------------
+
+    // The meshlet builder runs on a WASM instance that instantiates asynchronously at import; the
+    // renderer's own initialize used to give it the time, and building geometry before that meant
+    // reading an instance that was not there yet.
+    await MeshoptClusterizer.ready;
+
+    const scene = new Scene();
+
+    scene.lights.add(make_sunlight({
+        intensity: 1.2,
+        direction: new Vector3(0.3, -1, -0.4),
+        temperature: 5500,
+    }));
+
+    const flat = Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2);
+
+    const backdrop = place(
+        make_plane(40, 16),
+        make_material(new Color(0.55, 0.55, 0.58, 1), { transparent: false }),
+        new Vector3(0, 6, -12)
+    );
+    const floor = place(
+        make_plane(40, 40),
+        make_material(new Color(0.35, 0.33, 0.3, 1), { transparent: false }),
+        new Vector3(0, 0, 0),
+        flat
+    );
+
+    // a dark opaque bar behind the stack, so bleed-through of the cards' colours has a reference
+    const bar = place(
+        make_plane(1.2, 6),
+        make_material(new Color(0.05, 0.05, 0.06, 1), { transparent: false }),
+        new Vector3(0, 3, -8)
+    );
+
+    scene.add(backdrop);
+    scene.add(floor);
+    scene.add(bar);
+
+    /** @type {Mesh[]} */
+    let cards = [];
+    /** @type {Mesh|undefined} */
+    let glass;
+    /** @type {Mesh|undefined} */
+    let opaque_quad;
+
+    /**
+     * Rebuild the stack, the pane and the quad. Materials are rebuilt too, so a change in alpha
+     * reaches the material buffer rather than a stale copy.
+     *
+     * @param {number} count
+     * @param {number} spacing world units between consecutive cards, along the view axis
+     * @param {number} alpha
+     * @param {boolean} with_glass
+     * @param {string} tint key of GLASS_TINTS
+     * @param {boolean} with_opaque_quad
+     */
+    function rebuild(count, spacing, alpha, with_glass, tint, with_opaque_quad) {
+        for (const card of cards) {
+            scene.remove(card);
+        }
+        cards = [];
+
+        if (glass !== undefined) {
+            scene.remove(glass);
+            glass = undefined;
+        }
+
+        if (opaque_quad !== undefined) {
+            scene.remove(opaque_quad);
+            opaque_quad = undefined;
+        }
+
+        const card_geometry = make_plane(3, 3);
+
+        for (let i = 0; i < count; i++) {
+            const color = CARD_COLORS[i % CARD_COLORS.length];
+            const material = make_material(new Color(color.r, color.g, color.b, alpha));
+
+            // a slight lateral offset per card so the stack reads as a stack from this camera
+            const card = place(
+                card_geometry,
+                material,
+                new Vector3(-1.5 + i * 0.45, 2.2 + i * 0.25, 2 - i * spacing)
+            );
+
+            cards.push(card);
+            scene.add(card);
+        }
+
+        if (with_glass) {
+            glass = place(
+                make_plane(3.5, 4.5),
+                make_material(GLASS_TINTS[tint], { transmission: 1 }),
+                new Vector3(3.6, 2.4, 3)
+            );
+            scene.add(glass);
+        }
+
+        if (with_opaque_quad) {
+            /*
+             One unit behind the last card, high and to the right of the stack's centre, so part of it
+             is seen through the cards and part stands clear against the backdrop and the dark bar.
+             Alpha 1 through `TransparencyMode.Transparent` (the default of make_material): both
+             pipelines clamp coverage at OIT_COVERAGE_MAX, so this is the "0 % transmittance card" of
+             the deck's harness, and its edges are the depth discontinuities moments cannot hold.
+            */
+            const z_last = 2 - (count - 1) * spacing;
+
+            opaque_quad = place(
+                make_plane(1.6, 1.6),
+                make_material(new Color(0.95, 0.9, 0.8, 1)),
+                new Vector3(0.9, 3.5, z_last - 1)
+            );
+            scene.add(opaque_quad);
+        }
+
+        renderer?.indicate_view_change();
+    }
+
+    // ---- settings ----------------------------------------------------------------------------
+
+    /**
+     * The recording in progress, or null. `Renderer.profile_session` is a nullable field and the
+     * null checks around it are the whole integration; the two imports at the top of this file are
+     * the opt-in.
+     *
+     * @type {GPUProfileSession|null}
+     */
+    let profile_session = null;
+
+    /** the tracer's own floor, read once the renderer exists */
+    let default_min_accumulation_alpha = 0.01;
+
+    function apply_settings() {
+        const mode = element('mode').value;
+        const reference = mode === 'REFERENCE';
+
+        VIEWPORT.width = Math.max(2, Number(element('width').value) | 0);
+        VIEWPORT.height = Math.max(2, Number(element('height').value) | 0);
+
+        rebuild(
+            Math.max(1, Number(element('count').value) | 0),
+            Number(element('spacing').value),
+            Math.min(0.997, Math.max(0.01, Number(element('alpha').value))),
+            element('glass').checked,
+            element('tint').value,
+            element('opaque_quad').checked
+        );
+
+        if (renderer === null) {
+            report(`no device — mode ${mode} set aside; the camera still orbits and copies`, 'fail');
+            return;
+        }
+
+        renderer.transparency_mode = mode === 'MBOIT'
+            ? ShadeTransparencyMode.MBOIT
+            : ShadeTransparencyMode.AVBOIT;
+
+        renderer.avboit.transmission_tint_from_base_color = element('tint_from_base_color').checked;
+
+        renderer.indirect_lighting_mode = element('indirect').value === 'Brick4'
+            ? ShadeIndirectLightingMode.Brick4
+            : ShadeIndirectLightingMode.IBL;
+
+        // The tracer accumulates on its own and resets when the camera moves; TAA on top of it is a
+        // second temporal filter over the same image. The checkbox keeps the user's choice for the
+        // rasterized modes, it is only overridden while tracing.
+        renderer.feature_path_tracing_enabled = reference;
+        renderer.path_tracer.min_accumulation_alpha = reference
+            ? REFERENCE_MIN_ACCUMULATION_ALPHA
+            : default_min_accumulation_alpha;
+        renderer.path_tracer.clear_history = true;
+
+        renderer.feature_taa_enabled = element('taa').checked && !reference;
+        renderer.feature_shadows_enabled = element('shadows').checked;
+        renderer.feature_automatic_exposure_enabled = element('exposure').checked;
+        renderer.exposure_compensation = Number(element('exposure_compensation').value);
+
+        report(`mode ${mode}, ${element('indirect').value} indirect, ${element('count').value} cards, spacing ${element('spacing').value}, alpha ${element('alpha').value}`);
+    }
+
+    element('apply').addEventListener('click', () => guarded('apply', apply_settings));
+    element('mode').addEventListener('change', () => guarded('apply', apply_settings));
+    element('indirect').addEventListener('change', () => guarded('apply', apply_settings));
+
+    element('reset').addEventListener('click', () => guarded('reset accumulation', () => {
+        if (renderer === null) {
+            return;
+        }
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    }));
+
+    /**
+     * While tracing, the report carries how settled the reference is: the sample count of the tile
+     * that has had the fewest, which is the floor on convergence anywhere in the image. Updated on
+     * its own clock rather than per frame so the panel stays readable. Silent while a profile is
+     * recording, whose own status owns the report then.
+     */
+    setInterval(() => {
+        if (renderer === null || !renderer.feature_path_tracing_enabled || profile_session !== null) {
+            return;
+        }
+
+        const samples = renderer.path_tracer.min_sample_count;
+        const floor = Math.round(1 / renderer.path_tracer.min_accumulation_alpha);
+
+        report(
+            `mode REFERENCE — ${samples} samples/pixel accumulated (running mean up to ${floor}, then exponential); `
+            + `hold the camera still, or press Reset accumulation after a change`
+        );
+    }, 1000);
+
+    /**
+     * Set controls by name and apply them, for driving an A/B from a script rather than by hand.
+     * A `camera` entry takes the shape {@link camera_state} returns.
+     *
+     * @param {Record<string, string|number|boolean|object>} settings keyed by input id
+     */
+    globalThis.configure = settings => {
+        for (const [id, value] of Object.entries(settings)) {
+            if (id === 'camera') {
+                globalThis.apply_camera(value);
+                continue;
+            }
+
+            const input = element(id);
+
+            if (input === null) {
+                throw new Error(`no control named '${id}'`);
+            }
+
+            if (input.type === 'checkbox') {
+                input.checked = Boolean(value);
+            } else {
+                input.value = String(value);
+            }
+        }
+
+        apply_settings();
+    };
+
+    // ---- compile check -----------------------------------------------------------------------
+
+    /**
+     * Compile every AVBOIT module on this device and print the result.
+     *
+     * @returns {Promise<{name: string, ok: boolean, messages: string[]}[]>}
+     */
+    globalThis.compile_check = async () => {
+        if (renderer === null) {
+            throw new Error('no device');
+        }
+
+        report('compiling…');
+
+        const results = await compile_all(renderer.graphics.device);
+        const failed = results.filter(r => !r.ok);
+
+        const lines = results.map(r => `${r.ok ? 'ok  ' : 'FAIL'} ${r.name}${r.messages.length ? '\n    ' + r.messages.join('\n    ') : ''}`);
+
+        report(
+            `${results.length - failed.length}/${results.length} AVBOIT modules compiled\n${lines.join('\n')}`,
+            failed.length === 0 ? 'pass' : 'fail'
+        );
+
+        globalThis.__last_compile = results;
+
+        return results;
+    };
+
+    element('compile').addEventListener('click', () => guarded('compile check', () => globalThis.compile_check()));
+
+    // ---- profiling ---------------------------------------------------------------------------
+
+    /** Guards against the button being leaned on while a stop is still draining. */
+    let profile_busy = false;
+
+    globalThis.start_profile = () => {
+        if (renderer === null) {
+            throw new Error('no device');
+        }
+
+        const device = renderer.graphics.device;
+
+        const settings = [
+            element('mode').value,
+            `${element('indirect').value} indirect`,
+            `${element('count').value} cards`,
+            `spacing ${element('spacing').value}`,
+            `alpha ${element('alpha').value}`,
+            `${VIEWPORT.width}x${VIEWPORT.height}`,
+            element('taa').checked ? 'TAA' : 'no TAA',
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `avboit — ${settings.join(' · ')}`,
+        });
+
+        // Populate before start(): the meta record is written into the stream there. A pass taking
+        // 0.4 ms says nothing until you know which GPU and at what resolution.
+        const meta = session.meta;
+        const info = device.adapterInfo;
+
+        if (info !== undefined && info !== null) {
+            meta.adapter_vendor = info.vendor ?? "";
+            meta.adapter_architecture = info.architecture ?? "";
+            meta.adapter_device = info.device ?? "";
+            meta.adapter_description = info.description ?? "";
+        }
+
+        meta.features = [...device.features];
+        meta.engine_version = package_json.version;
+
+        session.onBytesWritten.add(bytes => {
+            report(`● recording ${element('mode').value} — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  press Profile again to stop`);
+        });
+
+        renderer.profile_session = session;
+        session.start();
+
+        profile_session = session;
+
+        const timed = device.features.has('timestamp-query');
+
+        report(timed
+            ? `● recording ${element('mode').value} — 0 frames  ·  press Profile again to stop`
+            : '● recording without timestamp-query — structure only, no durations  ·  press Profile again to stop');
+
+        element('profile').textContent = 'Stop profile and download';
+        element('profile').classList.add('recording');
+    };
+
+    /**
+     * Wait for frames already submitted to land in the session; stopping the instant the button is
+     * pressed would drop the last frames, which are the ones being looked at.
+     *
+     * @param {GPUProfileSession} session
+     */
+    async function drain_profile(session) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.graphics.device.queue.onSubmittedWorkDone();
+
+        const deadline = performance.now() + DEADLINE_MS;
+
+        let previous = session.frames_recorded;
+
+        while (performance.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, QUIET_MS));
+
+            if (session.frames_recorded === previous) {
+                return;
+            }
+
+            previous = session.frames_recorded;
+        }
+    }
+
+    globalThis.stop_profile = async () => {
+        const session = profile_session;
+
+        if (session === null) {
+            return;
+        }
+
+        profile_session = null;
+
+        // detach first, so nothing encoded during the drain joins the recording
+        renderer.profile_session = null;
+
+        report('stopping — draining in-flight frames…');
+
+        await drain_profile(session);
+
+        const bytes = session.stop();
+
+        const filename = `avboit-${element('mode').value}-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        const summary = `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`;
+
+        console.log(`profile: ${summary}`);
+        report(`profile saved: ${summary}\nopen it in packages/gpu-inspector-tool (npm run dev --workspace @woosh/gpu-inspector-tool)`, 'pass');
+
+        element('profile').textContent = 'Profile (record GPU timings)';
+        element('profile').classList.remove('recording');
+    };
+
+    element('profile').addEventListener('click', () => guarded('profile', async () => {
+        if (profile_busy) {
+            return;
+        }
+
+        profile_busy = true;
+
+        try {
+            if (profile_session === null) {
+                globalThis.start_profile();
+            } else {
+                await globalThis.stop_profile();
+            }
+        } finally {
+            profile_busy = false;
+        }
+    }));
+
+    globalThis.scene = scene;
+
+    // ---- the device, last -------------------------------------------------------------------
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        report('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
+    }
+
+    if (context !== null) {
+        const candidate = new Renderer();
+
+        report('acquiring a device…');
+
+        try {
+            await candidate.initialize({ context, pixelRatio: 1 });
+
+            renderer = candidate;
+
+            // eye adaptation keeps drifting for seconds after any change, which makes an A/B unreadable
+            renderer.feature_automatic_exposure_enabled = false;
+            renderer.exposure_compensation = 1.5;
+
+            default_min_accumulation_alpha = renderer.path_tracer.min_accumulation_alpha;
+
+            globalThis.renderer = renderer;
+
+            load_default_environment(scene).then(() => renderer.indicate_view_change());
+        } catch (e) {
+            report(`device: ${e.message}`, 'fail');
+            console.error(e);
+        }
+    }
+
+    await guarded('apply', apply_settings);
+
+    if (renderer !== null) {
+        report(
+            `${report_element.textContent}
+`
+            + 'camera: drag to orbit, wheel to zoom, right-drag to pan, W/A/S/D to move (click the page first)'
+        );
+    }
+
+    // ---- frame loop --------------------------------------------------------------------------
+
+    create_frame_loop(time_delta_s => {
+        if (canvas.width !== VIEWPORT.width || canvas.height !== VIEWPORT.height) {
+            canvas.width = VIEWPORT.width;
+            canvas.height = VIEWPORT.height;
+            camera.aspect = VIEWPORT.width / VIEWPORT.height;
+            renderer?.resize(VIEWPORT.width, VIEWPORT.height);
+        }
+
+        controller.update();
+
+        if (renderer !== null) {
+            renderer.render(camera, scene, time_delta_s);
+        }
+    });
+}