@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -1,917 +1,917 @@
-import package_json from "../../../../package.json";
-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 { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.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 { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
-import { Renderer } from "../../renderer/Renderer.js";
-import { Scene } from "../../renderer/scene/Scene.js";
-import {
-    ParticipatingMediaVolume,
-    VolumetricsParticleSpec
-} from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
-import { load_default_environment } from "../load_default_environment.js";
-import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
-
-/**
- * The froxel volumetrics pass, with the controls that make its known defects visible.
- *
- * `shader_volumetrics_build_lighting` and the passes around it were reviewed statically and five
- * correctness findings came out of it (C-01 … C-05). Four are geometric, and geometry is the one
- * class of defect a unit test can prove but not show: an emulator can assert that a sample lands at
- * the wrong depth, and it still cannot tell you whether that reads as a smear, a seam, or nothing
- * at all. This page exists so each fix can be looked at before and after.
- *
- * Every control below is aimed at one finding. The panel says which.
- *
- * Runs under the dev server (`npm run dev`), which serves `test_assets/` and resolves the one bare
- * specifier the renderer reaches for. The panel is hand-rolled for the same reason the Sponza page
- * hand-rolls its own — a dozen inputs are not worth a dependency the library does not otherwise
- * have.
- *
- * @see src/shade/renderer/volumetrics/NOTES.md
- */
-
-/**
- * Served out of `test_assets/`, which is gitignored and unpublished — `test_assets/README.md` has
- * how it gets there.
- *
- * glTF rather than the `.shade` scene sitting next to it: that export's header reads format
- * version 1 and `deserialize_scene` accepts version 2 only, deliberately and with no backward
- * compatibility. Re-exporting it is the fix if the `.shade` is ever wanted.
- *
- * @type {string}
- */
-const SCENE_URL = '/test_assets/flying_world_-_battle_of_the_trash_god/v2/scene.gltf';
-
-/**
- * A low sun, which is what the volumetrics want: it rakes the scene, so the shafts have something
- * to be cast by, and it sits near the horizon where the sun can be swung in and out of the frustum
- * without also swinging it behind the terrain.
- *
- * @type {string}
- */
-const ENVIRONMENT_URL = '/test_assets/environments/octahedral/venice_sunset_2k.hdr';
-
-/**
- * Camera placements carried over from the sibling repo's playground, where they were found by
- * hand while looking at this exact scene. Keeping the numbers rather than re-deriving them means a
- * before/after pair is taken from the same place to the pixel.
- *
- * The `c` field names the finding each one is good for; the panel groups by it.
- */
-const VIEWS = [
-    {
-        id: 'overview',
-        label: 'Dead overview',
-        c: 'orientation',
-        hint: 'the whole island — start here',
-        position: { x: -44.23572420730413, y: 16.787419516572818, z: -0.3908097424888902 },
-        rotation: { x: -0.10289617976426199, y: 0.8965686124184902, z: -0.32052909150868936, w: -0.2878162624184363 }
-    },
-    {
-        id: 'vol_0',
-        label: 'Fog bank, wide',
-        c: 'C-01',
-        hint: 'fog fills the frame corners, where the depth error is largest',
-        position: { x: -39.165083083628595, y: 9.002002938463146, z: -12.822321096883556 },
-        rotation: { x: 0.0461501744849993, y: 0.9414711984407541, z: -0.14428237367052793, w: 0.3011390717750397 }
-    },
-    {
-        id: 'vol_1',
-        label: 'Inside the fog',
-        c: 'C-01',
-        hint: 'camera inside the medium — radial thinning shows against a flat wall of fog',
-        position: { x: -57.19543561067503, y: 4.497368033549733, z: -5.431935542965578 },
-        rotation: {
-            x: 0.0012158994167123557,
-            y: 0.9584376528911036,
-            z: -0.0040851224490818586,
-            w: 0.28527022081489145
-        }
-    },
-    {
-        id: 'broadside',
-        label: 'Island broadside',
-        c: 'C-03',
-        hint: 'the island against open sky — the clearest place to swing the sun in and out of frame',
-        position: { x: -30, y: 11, z: -5 },
-        rotation: {
-            x: 0.08308534470573395,
-            y: -0.7022085341941733,
-            z: 0.08308534470573395,
-            w: 0.7022085341941732
-        }
-    },
-    {
-        id: 'above',
-        label: 'Island from above',
-        c: 'C-03',
-        hint: 'all six volumes at once, with sky behind them',
-        position: { x: -18, y: 26, z: 26 },
-        rotation: {
-            x: -0.09605984305376475,
-            y: 0.8751796663464206,
-            z: -0.19438519850844194,
-            w: -0.43248982966896177
-        }
-    },
-    {
-        id: 'cloud_deck',
-        label: 'Inside the cloud deck',
-        c: 'C-01',
-        hint: 'uniform medium filling the frame — radial thinning reads as a vignette here',
-        position: { x: -57, y: -10, z: 20 },
-        rotation: { x: 0, y: 0.9999652844073138, z: 0.008332465433472727, w: 0 }
-    },
-    {
-        id: 'aliasing_0',
-        label: 'Volume edge',
-        c: 'C-02',
-        hint: 'a fog volume boundary against geometry — a half-froxel shift moves this edge',
-        position: { x: -44.358600521646366, y: 8.13976892720825, z: 2.6707745658793725 },
-        rotation: { x: -0.07197787209539422, y: 0.9277035010259875, z: -0.24609398688026018, w: -0.2713358614966388 }
-    },
-    {
-        id: 'aliasing_1',
-        label: 'Volume edge, above',
-        c: 'C-02',
-        hint: 'the same boundary from above, where the slab stack is edge-on',
-        position: { x: -36.56903863396318, y: 19.1017887067011, z: 13.881382214134083 },
-        rotation: { x: -0.0961072760435774, y: 0.9036695806244697, z: -0.3054532939528032, w: -0.28432897453277794 }
-    },
-    {
-        id: 'fog_box_0',
-        label: 'Beside the fog box',
-        c: 'Q-04',
-        hint: 'the sun crosses three units of medium here — where sixteen march steps read +58',
-        position: { x: -49.64917207609583, y: 3.9195318273572317, z: -4.211048766762115 },
-        rotation: {
-            x: -0.037898077937503966,
-            y: 0.6176094542736352,
-            z: 0.029816629610983452,
-            w: 0.7850052651282708
-        }
-    },
-    {
-        id: 'fog_box_1',
-        label: 'Beside the fog box, deeper',
-        c: 'Q-04',
-        hint: 'the same medium a little further in; +70 for the march, and where the volume strobed',
-        position: { x: -50.28590468756837, y: 4.239170044321892, z: -3.9966900541348767 },
-        rotation: {
-            x: -0.03789807793750395,
-            y: 0.6176094542736352,
-            z: 0.02981662961098345,
-            w: 0.7850052651282708
-        }
-    },
-    {
-        id: 'inside_out',
-        label: 'Under the island',
-        c: 'C-05',
-        hint: 'thin haze over a dark ground — per-froxel noise is most legible here',
-        position: { x: -61.55864473831582, y: 23.7158848700074, z: -19.634434309820563 },
-        rotation: { x: 0.27745576215003553, y: 0.0922110339369582, z: -0.026764015593898134, w: 0.9559284035634205 }
-    },
-];
-
-/**
- * The participating media, carried over from the sibling repo's setup for this scene. Positions are
- * tuned to the model, so they move with it and not with anything here.
- *
- * `target_extinction` rather than `density`: it normalizes across particle specs, so swapping a
- * preset changes how the medium *looks* without changing how much light it stops.
- *
- * @param {Scene} scene
- */
-function add_participating_media(scene) {
-
-    /**
-     * @param {object} spec
-     * @param {number[]} spec.position
-     * @param {number[]} spec.scale
-     * @param {object} spec.particle from MIE_PARTICLES_STANDARD_PRECOMPUTED
-     * @param {number} spec.extinction
-     * @param {number} spec.fade
-     * @param {number} [spec.yaw_degrees]
-     */
-    function volume({ position, scale, particle, extinction, fade, yaw_degrees = 0 }) {
-        const v = new ParticipatingMediaVolume();
-
-        v.transform.position.set(...position);
-        v.transform.scale.set(...scale);
-
-        if (yaw_degrees !== 0) {
-            v.transform.rotation.fromAxisAngle(Vector3.up, yaw_degrees * DEG_TO_RAD);
-        }
-
-        v.fade_distance = fade;
-        v.particle_spec = VolumetricsParticleSpec.fromMeep(particle);
-        v.target_extinction = extinction;
-
-        scene.volumetrics.add(v);
-
-        return v;
-    }
-
-    const P = MIE_PARTICLES_STANDARD_PRECOMPUTED;
-
-    // the dense bank along the western edge — the thickest medium in the scene, and the one that
-    // fills the frame corners from the `vol_0` view
-    volume({
-        position: [-55, 4, -5.116],
-        scale: [10, 3, 20],
-        yaw_degrees: 83,
-        particle: P.CLOUD_DROPLET_LARGE,
-        extinction: 1,
-        fade: 0.5,
-    });
-
-    // graveyard
-    volume({
-        position: [-51.98019820725889, 7.899311905935347, -15.3228393616169],
-        scale: [7, 5, 7],
-        particle: P.FOG_DROPLET_SMALL,
-        extinction: 0.4,
-        fade: 1,
-    });
-
-    // mine
-    volume({
-        position: [-50.846390607312934, 0.3159949821015605, 17.89429433940319],
-        scale: [10, 7, 10],
-        particle: P.COARSE_DUST_MEDIUM,
-        extinction: 0.4,
-        fade: 4,
-    });
-
-    // large crystal
-    volume({
-        position: [-53.41918585295826, 17.333878151116526, 29.90844167706601],
-        scale: [18, 10, 18],
-        particle: P.MARITIME_HAZE_MEDIUM,
-        extinction: 0.1,
-        fade: 4,
-    });
-
-    // the low cloud deck the island sits above — big and thin, so it is what a wide FOV sees at the
-    // frame edges
-    volume({
-        position: [-57.36387203979457, -15, 2.607232848593789],
-        scale: [400, 20, 400],
-        particle: P.CLOUD_DROPLET_LARGE,
-        extinction: 0.1,
-        fade: 4,
-    });
-
-    // ball cloud overhead
-    volume({
-        position: [-51.137423384559284, 33, 5.593067265589105],
-        scale: [15, 15, 15],
-        particle: P.CLOUD_DROPLET_LARGE,
-        extinction: 1,
-        fade: 7,
-    });
-}
-
-/**
- * A rolling mean frame time, so the readout is legible rather than jittering.
- */
-class FrameTimer {
-    #samples = new Float64Array(60);
-    #count = 0;
-    #cursor = 0;
-
-    add(seconds) {
-        this.#samples[this.#cursor] = seconds * 1000;
-        this.#cursor = (this.#cursor + 1) % this.#samples.length;
-        this.#count = Math.min(this.#count + 1, this.#samples.length);
-    }
-
-    reset() {
-        this.#count = 0;
-        this.#cursor = 0;
-    }
-
-    get mean_ms() {
-        if (this.#count === 0) {
-            return 0;
-        }
-
-        let total = 0;
-        for (let i = 0; i < this.#count; i++) {
-            total += this.#samples[i];
-        }
-        return total / this.#count;
-    }
-}
-
-/**
- * Point a directional light along a heading, in place.
- *
- * The sun's azimuth is the control C-03 turns on: the shadow ray is clipped against a frustum whose
- * far plane is degenerate, so a sun direction that lies inside the view cone never exits it. Swing
- * the sun through the frame and the media self-shadowing should be steady; if it switches on as the
- * sun leaves the frustum, that is the finding.
- *
- * @param {DirectionalLight} light
- * @param {number} azimuth_degrees 0 points along +X
- * @param {number} elevation_degrees above the horizon
- */
-function aim_light(light, azimuth_degrees, elevation_degrees) {
-    const azimuth = azimuth_degrees * DEG_TO_RAD;
-    const elevation = elevation_degrees * DEG_TO_RAD;
-
-    const horizontal = Math.cos(elevation);
-
-    // direction the light travels — downward for a sun above the horizon
-    const direction = new Vector3(
-        Math.cos(azimuth) * horizontal,
-        -Math.sin(elevation),
-        Math.sin(azimuth) * horizontal
-    ).normalize();
-
-    const q = new Quaternion();
-    q.fromUnitVectors(Vector3.forward, direction);
-    q.normalize();
-
-    light.transform_local.setRotation(q.x, q.y, q.z, q.w);
-    light.updateMatrices();
-}
-
-/**
- * How much each profile capture records. `WORKLOAD` is the highest of the three levels the proposal
- * calls shippable: pass spans, the frame graph, and dispatch/draw counts.
- *
- * Measured on this page it runs ~11 KB a frame over ~393 spans, so ~660 KB/s at 60 Hz — the
- * proposal's estimate of 6 KB assumed ~200 passes and this graph is about twice that. Still small
- * enough that a hand-driven recording will not notice. `VERBOSE` above it adds bind group contents
- * at roughly seven times the rate and wants a frame limit set, not a key you can lean on.
- *
- * @type {number}
- */
-const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
-
-/**
- * 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, matching the naming the other `.sgpt` captures on this machine
- * already use — same sort order, and it reads as the clock you took it by rather than as UTC.
- *
- * @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 status_element = element('status');
-    const stats_element = element('stats');
-
-    function set_status(text, kind = '') {
-        status_element.textContent = text;
-        status_element.className = kind;
-    }
-
-    const canvas = element('view');
-
-    const context = canvas.getContext('webgpu');
-
-    if (context === null) {
-        set_status('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
-        return;
-    }
-
-    const renderer = new Renderer();
-
-    set_status('acquiring a device…');
-
-    await renderer.initialize({ context });
-
-    const camera = new PerspectiveCamera();
-
-    camera.near = 0.1;
-    camera.far = 120;
-    camera.fov = 60 * DEG_TO_RAD;
-    // aspect is set by the frame loop, which is the first place the viewport has a size
-
-    const scene = new Scene();
-
-    const controller = new OrbitalCameraController(camera, document.body);
-
-    // handy from the console
-    globalThis.renderer = renderer;
-    globalThis.scene = scene;
-    globalThis.camera = camera;
-    globalThis.controller = controller;
-
-    // ---- scene ----------------------------------------------------------------------------
-
-    set_status(`loading ${SCENE_URL} …`);
-
-    try {
-        const bundle = await load_gltf(SCENE_URL, { assetManager: await make_playground_asset_manager() });
-
-        scene.add(bundle.scenes);
-    } catch (error) {
-        set_status(
-            `could not load the scene (${error.message}). Put the assets under test_assets/ — `
-            + `see test_assets/README.md.`,
-            'fail'
-        );
-        console.error(error);
-        return;
-    }
-
-    const sun = make_sunlight({ intensity: 0.6, temperature: 5500 });
-
-    scene.lights.add(sun);
-
-    add_participating_media(scene);
-
-    load_default_environment(scene, ENVIRONMENT_URL).then(applied => {
-        if (applied) {
-            renderer.indicate_view_change();
-        }
-    });
-
-    // ---- controls -------------------------------------------------------------------------
-
-    const frame_timer = new FrameTimer();
-
-    let paused = false;
-
-    /** Re-render and drop the frame-time history, since a setting change invalidates it. */
-    function repaint() {
-        renderer.indicate_view_change();
-        frame_timer.reset();
-    }
-
-    // -- views
-
-    const views_element = element('views');
-
-    /**
-     * Which placement the camera was last sent to, for the profile capture's note — a capture that
-     * cannot say where it was taken is much less use a week later.
-     * @type {object|null}
-     */
-    let current_view = null;
-
-    /** @param {object} view */
-    function go_to(view) {
-        current_view = view;
-
-        camera.transform.fromJSON({ position: view.position, rotation: view.rotation });
-
-        // the controller holds its own spherical state and would otherwise snap the camera back on
-        // the next update
-        controller.from_transform(camera.transform);
-
-        repaint();
-    }
-
-    for (const view of VIEWS) {
-        const button = document.createElement('button');
-
-        button.className = 'view';
-        button.title = view.hint;
-        button.innerHTML = `<span class="tag">${view.c}</span>${view.label}`;
-        button.addEventListener('click', () => {
-            go_to(view);
-            set_status(view.hint);
-        });
-
-        views_element.appendChild(button);
-    }
-
-    // -- sun
-
-    let sun_azimuth = 200;
-    let sun_elevation = 12;
-
-    function update_sun() {
-        aim_light(sun, sun_azimuth, sun_elevation);
-
-        element('sun_azimuth_value').textContent = `${sun_azimuth}°`;
-        element('sun_elevation_value').textContent = `${sun_elevation}°`;
-
-        repaint();
-    }
-
-    element('sun_azimuth').addEventListener('input', event => {
-        sun_azimuth = Number(event.target.value);
-        update_sun();
-    });
-
-    element('sun_elevation').addEventListener('input', event => {
-        sun_elevation = Number(event.target.value);
-        update_sun();
-    });
-
-    /**
-     * Put the sun directly in front of the camera, or directly behind it, at the current elevation.
-     *
-     * This is the C-03 A/B reduced to two clicks. "Into view" places the sun's direction inside the
-     * frustum's direction cone, which is the condition under which `frustum_clip_ray` returns its
-     * 1e20 sentinel.
-     *
-     * @param {boolean} in_front
-     */
-    function aim_sun_relative_to_camera(in_front) {
-        // Straight off the view matrix rather than by rotating a basis vector through the camera's
-        // quaternion by hand: the third row of a view matrix is the camera's backward axis, so this
-        // is the renderer's own answer and cannot disagree with what is on screen. The hand-rolled
-        // version this replaces had a sign error that put the sun behind the camera on both
-        // branches, which is invisible in a screenshot and made the C-03 A/B read as a null result.
-        // The matrices are rebuilt during render, so a placement made this tick is not in them yet
-        // — reading straight after `go_to` would aim the sun at wherever the camera used to be.
-        camera.update();
-
-        const vm = camera.view_matrix;
-
-        const forward_x = -vm[2];
-        const forward_z = -vm[10];
-
-        // `aim_light` takes the direction light *travels*, so the sun sits opposite it. Placing the
-        // sun on the camera's forward axis therefore means aiming its travel back along that axis.
-        const toward_sun_x = in_front ? forward_x : -forward_x;
-        const toward_sun_z = in_front ? forward_z : -forward_z;
-
-        const azimuth = Math.atan2(-toward_sun_z, -toward_sun_x) / DEG_TO_RAD;
-
-        sun_azimuth = Math.round((azimuth % 360 + 360) % 360);
-
-        element('sun_azimuth').value = String(sun_azimuth);
-
-        update_sun();
-    }
-
-    element('sun_into_view').addEventListener('click', () => {
-        aim_sun_relative_to_camera(true);
-        set_status('sun placed in front of the camera — C-03 predicts media self-shadowing vanishes here', 'warn');
-    });
-
-    element('sun_behind').addEventListener('click', () => {
-        aim_sun_relative_to_camera(false);
-        set_status('sun placed behind the camera — C-03 predicts media self-shadowing returns here', 'pass');
-    });
-
-    // -- camera
-
-    element('fov').addEventListener('input', event => {
-        const degrees = Number(event.target.value);
-
-        camera.fov = degrees * DEG_TO_RAD;
-
-        element('fov_value').textContent = `${degrees}°`;
-
-        repaint();
-    });
-
-    // -- volumetrics knobs, read by GPUViewVolumetrics on every metadata update
-
-    element('vol_taa').addEventListener('change', event => {
-        globalThis.__VOL_TAA_ENABLED = event.target.checked;
-        repaint();
-    });
-
-    element('taa').addEventListener('change', event => {
-        renderer.feature_taa_enabled = event.target.checked;
-        repaint();
-    });
-
-    // Off by default on this page. Auto exposure keeps adapting for seconds after anything changes,
-    // which makes a before/after pair differ by more than most of the fixes being judged here do —
-    // it read as a large effect with the wrong sign more than once while this page was being built.
-    renderer.feature_automatic_exposure_enabled = false;
-
-    element('auto_exposure').addEventListener('change', event => {
-        renderer.feature_automatic_exposure_enabled = event.target.checked;
-        repaint();
-    });
-
-    element('froxel_far').addEventListener('input', event => {
-        const value = Number(event.target.value);
-
-        // the slider's top notch means "no split", which is the engine default
-        globalThis.__VOL_FROXEL_FAR = value >= 120 ? Infinity : value;
-
-        element('froxel_far_value').textContent = value >= 120 ? 'off' : `${value} m`;
-
-        repaint();
-    });
-
-    element('ms_octaves').addEventListener('input', event => {
-        const value = Number(event.target.value);
-
-        globalThis.__VOL_MS_OCTAVES = value;
-
-        element('ms_octaves_value').textContent = String(value);
-
-        repaint();
-    });
-
-    // -- profiling: T starts a recording, T again stops it and downloads the capture
-
-    const profile_status = element('profile_status');
-
-    /**
-     * The recording in progress, or null.
-     *
-     * The engine never constructs one of these — `Renderer.profile_session` is a nullable field and
-     * the null checks around it are the entire integration, which is what keeps the profiler out of
-     * a bundle that does not ask for it. The two imports at the top of this file are the whole
-     * opt-in.
-     *
-     * @type {GPUProfileSession|null}
-     */
-    let profile_session = null;
-
-    /** Guards against T being leaned on while a stop is still draining. */
-    let profile_busy = false;
-
-    function set_profile_status(text, recording = false) {
-        profile_status.textContent = text;
-        profile_status.className = recording ? 'recording' : '';
-    }
-
-    function start_profile() {
-        const device = renderer.device;
-
-        const settings = [
-            current_view === null ? 'free camera' : current_view.label,
-            `fov ${Math.round(camera.fov / DEG_TO_RAD)}°`,
-            `volumetric TAA ${(globalThis.__VOL_TAA_ENABLED ?? true) ? 'on' : 'off'}`,
-            `${renderer.pixel_ratio.toFixed(2)}x`,
-        ];
-
-        const session = new GPUProfileSession({
-            level: PROFILE_LEVEL,
-            note: `volumetrics_froxel — ${settings.join(' · ')}`,
-        });
-
-        // Populate before start(): the meta record is written into the stream there and not read
-        // again. Without it the capture is unreadable in the sense that matters — a pass taking
-        // 0.4 ms says nothing until you know which GPU and at what resolution.
-        const meta = session.meta;
-
-        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
-        // and several browsers withhold the fields even when they do. Empty is what the format
-        // expects in that case.
-        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 => {
-            set_profile_status(
-                `● recording — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  T to stop`,
-                true
-            );
-        });
-
-        renderer.profile_session = session;
-        session.start();
-
-        profile_session = session;
-
-        // The timers go quiet without this rather than failing, so the capture still carries the
-        // frame graph and the workload — it just has no durations in it. Worth knowing before you
-        // record for a minute and then look.
-        const timed = device.features.has('timestamp-query');
-
-        set_profile_status(
-            timed
-                ? '● recording — 0 frames  ·  T to stop'
-                : '● recording without timestamp-query — structure only, no durations  ·  T to stop',
-            true
-        );
-    }
-
-    /**
-     * Wait for frames already submitted to finish landing in the session.
-     *
-     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
-     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
-     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
-     * the last few frames, which are the ones you were most likely looking at.
-     *
-     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
-     * taken while the page is paused never moves at all.
-     *
-     * @param {GPUProfileSession} session
-     */
-    async function drain_profile(session) {
-        const DEADLINE_MS = 1000;
-        const QUIET_MS = 60;
-
-        await renderer.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;
-        }
-    }
-
-    async function stop_profile() {
-        const session = profile_session;
-
-        profile_session = null;
-
-        // Detach first, so nothing encoded during the drain below joins the recording. Frames
-        // already encoded are unaffected: Renderer captures the session into a local before it
-        // subscribes to the readback.
-        renderer.profile_session = null;
-
-        set_profile_status('stopping — draining in-flight frames…');
-
-        await drain_profile(session);
-
-        const bytes = session.stop();
-
-        const filename = `volumetrics_froxel-${file_timestamp()}.sgpt`;
-
-        download_bytes(bytes, filename);
-
-        // Also to the console, because the status line is the only other place the name appears and
-        // a browser that declines the save says nothing about which capture it declined.
-        console.log(
-            `profile: ${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
-            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`
-        );
-
-        set_profile_status(
-            `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}`
-            + `, ${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'}`
-            + `  ·  ${filename}`
-        );
-    }
-
-    window.addEventListener('keydown', event => {
-        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
-            return;
-        }
-
-        // `key` first, because it is the letter actually printed on the key the user pressed —
-        // `code` is physical position, so on AZERTY it names the key where T sits on QWERTY. `code`
-        // is the fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
-        if (event.key.toLowerCase() !== 't' && event.code !== 'KeyT') {
-            return;
-        }
-
-        // the panel's sliders and buttons are focusable; do not steal a key from a field
-        const target = event.target;
-
-        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
-            return;
-        }
-
-        if (profile_busy) {
-            return;
-        }
-
-        event.preventDefault();
-
-        profile_busy = true;
-
-        const done = profile_session === null
-            ? Promise.resolve(start_profile())
-            : stop_profile();
-
-        done.catch(error => {
-            set_profile_status(`profiling failed: ${error?.message ?? error}`);
-            console.error(error);
-
-            profile_session = null;
-            renderer.profile_session = null;
-        }).finally(() => {
-            profile_busy = false;
-        });
-    });
-
-    element('pause').addEventListener('click', () => {
-        paused = !paused;
-        element('pause').textContent = paused ? 'Resume' : 'Pause';
-    });
-
-    element('log_camera').addEventListener('click', () => {
-        const t = camera.transform;
-
-        const json = {
-            position: { x: t.position.x, y: t.position.y, z: t.position.z },
-            rotation: { x: t.rotation.x, y: t.rotation.y, z: t.rotation.z, w: t.rotation.w }
-        };
-
-        console.log(JSON.stringify(json, null, 4));
-        set_status('camera written to the console', 'pass');
-    });
-
-    // ---- start ----------------------------------------------------------------------------
-
-    update_sun();
-    go_to(VIEWS[0]);
-
-    controller.movement_speed_scale = 4;
-
-    // the controller's keyboard device listens on body, and only a focused element gets key events
-    document.body.focus();
-
-    set_status(`loaded — ${scene.instances.instances.length} instances, ${scene.volumetrics.volumes.length} media volumes`, 'pass');
-
-    // ---- frame loop -----------------------------------------------------------------------
-
-    const FRAME_RATE_LIMIT = 60;
-
-    create_frame_loop(time_delta_s => {
-        const width = window.innerWidth;
-        const height = window.innerHeight;
-
-        renderer.resize(width, height);
-        renderer.pixel_ratio = window.devicePixelRatio;
-        camera.aspect = width / height;
-
-        controller.update();
-
-        if (paused) {
-            return;
-        }
-
-        renderer.render(camera, scene, time_delta_s);
-
-        frame_timer.add(time_delta_s);
-
-        const mean = frame_timer.mean_ms;
-
-        stats_element.textContent =
-            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps`
-            + `  ·  fov ${Math.round(camera.fov / DEG_TO_RAD)}°`;
-    }, FRAME_RATE_LIMIT);
-}
+import package_json from "../../../../package.json";
+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 { MIE_PARTICLES_STANDARD_PRECOMPUTED } from "../../../core/math/physics/mie/MIE_PARTICLES_STANDARD_PRECOMPUTED.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 { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { load_gltf } from "../../renderer/loader/gltf/load_gltf.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import {
+    ParticipatingMediaVolume,
+    VolumetricsParticleSpec
+} from "../../renderer/volumetrics/ParticipatingMediaVolume.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+
+/**
+ * The froxel volumetrics pass, with the controls that make its known defects visible.
+ *
+ * `shader_volumetrics_build_lighting` and the passes around it were reviewed statically and five
+ * correctness findings came out of it (C-01 … C-05). Four are geometric, and geometry is the one
+ * class of defect a unit test can prove but not show: an emulator can assert that a sample lands at
+ * the wrong depth, and it still cannot tell you whether that reads as a smear, a seam, or nothing
+ * at all. This page exists so each fix can be looked at before and after.
+ *
+ * Every control below is aimed at one finding. The panel says which.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/` and resolves the one bare
+ * specifier the renderer reaches for. The panel is hand-rolled for the same reason the Sponza page
+ * hand-rolls its own — a dozen inputs are not worth a dependency the library does not otherwise
+ * have.
+ *
+ * @see src/shade/renderer/volumetrics/NOTES.md
+ */
+
+/**
+ * Served out of `test_assets/`, which is gitignored and unpublished — `test_assets/README.md` has
+ * how it gets there.
+ *
+ * glTF rather than the `.shade` scene sitting next to it: that export's header reads format
+ * version 1 and `deserialize_scene` accepts version 2 only, deliberately and with no backward
+ * compatibility. Re-exporting it is the fix if the `.shade` is ever wanted.
+ *
+ * @type {string}
+ */
+const SCENE_URL = '/test_assets/flying_world_-_battle_of_the_trash_god/v2/scene.gltf';
+
+/**
+ * A low sun, which is what the volumetrics want: it rakes the scene, so the shafts have something
+ * to be cast by, and it sits near the horizon where the sun can be swung in and out of the frustum
+ * without also swinging it behind the terrain.
+ *
+ * @type {string}
+ */
+const ENVIRONMENT_URL = '/test_assets/environments/octahedral/venice_sunset_2k.hdr';
+
+/**
+ * Camera placements carried over from the sibling repo's playground, where they were found by
+ * hand while looking at this exact scene. Keeping the numbers rather than re-deriving them means a
+ * before/after pair is taken from the same place to the pixel.
+ *
+ * The `c` field names the finding each one is good for; the panel groups by it.
+ */
+const VIEWS = [
+    {
+        id: 'overview',
+        label: 'Dead overview',
+        c: 'orientation',
+        hint: 'the whole island — start here',
+        position: { x: -44.23572420730413, y: 16.787419516572818, z: -0.3908097424888902 },
+        rotation: { x: -0.10289617976426199, y: 0.8965686124184902, z: -0.32052909150868936, w: -0.2878162624184363 }
+    },
+    {
+        id: 'vol_0',
+        label: 'Fog bank, wide',
+        c: 'C-01',
+        hint: 'fog fills the frame corners, where the depth error is largest',
+        position: { x: -39.165083083628595, y: 9.002002938463146, z: -12.822321096883556 },
+        rotation: { x: 0.0461501744849993, y: 0.9414711984407541, z: -0.14428237367052793, w: 0.3011390717750397 }
+    },
+    {
+        id: 'vol_1',
+        label: 'Inside the fog',
+        c: 'C-01',
+        hint: 'camera inside the medium — radial thinning shows against a flat wall of fog',
+        position: { x: -57.19543561067503, y: 4.497368033549733, z: -5.431935542965578 },
+        rotation: {
+            x: 0.0012158994167123557,
+            y: 0.9584376528911036,
+            z: -0.0040851224490818586,
+            w: 0.28527022081489145
+        }
+    },
+    {
+        id: 'broadside',
+        label: 'Island broadside',
+        c: 'C-03',
+        hint: 'the island against open sky — the clearest place to swing the sun in and out of frame',
+        position: { x: -30, y: 11, z: -5 },
+        rotation: {
+            x: 0.08308534470573395,
+            y: -0.7022085341941733,
+            z: 0.08308534470573395,
+            w: 0.7022085341941732
+        }
+    },
+    {
+        id: 'above',
+        label: 'Island from above',
+        c: 'C-03',
+        hint: 'all six volumes at once, with sky behind them',
+        position: { x: -18, y: 26, z: 26 },
+        rotation: {
+            x: -0.09605984305376475,
+            y: 0.8751796663464206,
+            z: -0.19438519850844194,
+            w: -0.43248982966896177
+        }
+    },
+    {
+        id: 'cloud_deck',
+        label: 'Inside the cloud deck',
+        c: 'C-01',
+        hint: 'uniform medium filling the frame — radial thinning reads as a vignette here',
+        position: { x: -57, y: -10, z: 20 },
+        rotation: { x: 0, y: 0.9999652844073138, z: 0.008332465433472727, w: 0 }
+    },
+    {
+        id: 'aliasing_0',
+        label: 'Volume edge',
+        c: 'C-02',
+        hint: 'a fog volume boundary against geometry — a half-froxel shift moves this edge',
+        position: { x: -44.358600521646366, y: 8.13976892720825, z: 2.6707745658793725 },
+        rotation: { x: -0.07197787209539422, y: 0.9277035010259875, z: -0.24609398688026018, w: -0.2713358614966388 }
+    },
+    {
+        id: 'aliasing_1',
+        label: 'Volume edge, above',
+        c: 'C-02',
+        hint: 'the same boundary from above, where the slab stack is edge-on',
+        position: { x: -36.56903863396318, y: 19.1017887067011, z: 13.881382214134083 },
+        rotation: { x: -0.0961072760435774, y: 0.9036695806244697, z: -0.3054532939528032, w: -0.28432897453277794 }
+    },
+    {
+        id: 'fog_box_0',
+        label: 'Beside the fog box',
+        c: 'Q-04',
+        hint: 'the sun crosses three units of medium here — where sixteen march steps read +58',
+        position: { x: -49.64917207609583, y: 3.9195318273572317, z: -4.211048766762115 },
+        rotation: {
+            x: -0.037898077937503966,
+            y: 0.6176094542736352,
+            z: 0.029816629610983452,
+            w: 0.7850052651282708
+        }
+    },
+    {
+        id: 'fog_box_1',
+        label: 'Beside the fog box, deeper',
+        c: 'Q-04',
+        hint: 'the same medium a little further in; +70 for the march, and where the volume strobed',
+        position: { x: -50.28590468756837, y: 4.239170044321892, z: -3.9966900541348767 },
+        rotation: {
+            x: -0.03789807793750395,
+            y: 0.6176094542736352,
+            z: 0.02981662961098345,
+            w: 0.7850052651282708
+        }
+    },
+    {
+        id: 'inside_out',
+        label: 'Under the island',
+        c: 'C-05',
+        hint: 'thin haze over a dark ground — per-froxel noise is most legible here',
+        position: { x: -61.55864473831582, y: 23.7158848700074, z: -19.634434309820563 },
+        rotation: { x: 0.27745576215003553, y: 0.0922110339369582, z: -0.026764015593898134, w: 0.9559284035634205 }
+    },
+];
+
+/**
+ * The participating media, carried over from the sibling repo's setup for this scene. Positions are
+ * tuned to the model, so they move with it and not with anything here.
+ *
+ * `target_extinction` rather than `density`: it normalizes across particle specs, so swapping a
+ * preset changes how the medium *looks* without changing how much light it stops.
+ *
+ * @param {Scene} scene
+ */
+function add_participating_media(scene) {
+
+    /**
+     * @param {object} spec
+     * @param {number[]} spec.position
+     * @param {number[]} spec.scale
+     * @param {object} spec.particle from MIE_PARTICLES_STANDARD_PRECOMPUTED
+     * @param {number} spec.extinction
+     * @param {number} spec.fade
+     * @param {number} [spec.yaw_degrees]
+     */
+    function volume({ position, scale, particle, extinction, fade, yaw_degrees = 0 }) {
+        const v = new ParticipatingMediaVolume();
+
+        v.transform.setTranslation(...position);
+        v.transform.setScale(...scale);
+
+        if (yaw_degrees !== 0) {
+            v.transform.rotation.fromAxisAngle(Vector3.up, yaw_degrees * DEG_TO_RAD);
+        }
+
+        v.fade_distance = fade;
+        v.particle_spec = VolumetricsParticleSpec.fromMeep(particle);
+        v.target_extinction = extinction;
+
+        scene.volumetrics.add(v);
+
+        return v;
+    }
+
+    const P = MIE_PARTICLES_STANDARD_PRECOMPUTED;
+
+    // the dense bank along the western edge — the thickest medium in the scene, and the one that
+    // fills the frame corners from the `vol_0` view
+    volume({
+        position: [-55, 4, -5.116],
+        scale: [10, 3, 20],
+        yaw_degrees: 83,
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 1,
+        fade: 0.5,
+    });
+
+    // graveyard
+    volume({
+        position: [-51.98019820725889, 7.899311905935347, -15.3228393616169],
+        scale: [7, 5, 7],
+        particle: P.FOG_DROPLET_SMALL,
+        extinction: 0.4,
+        fade: 1,
+    });
+
+    // mine
+    volume({
+        position: [-50.846390607312934, 0.3159949821015605, 17.89429433940319],
+        scale: [10, 7, 10],
+        particle: P.COARSE_DUST_MEDIUM,
+        extinction: 0.4,
+        fade: 4,
+    });
+
+    // large crystal
+    volume({
+        position: [-53.41918585295826, 17.333878151116526, 29.90844167706601],
+        scale: [18, 10, 18],
+        particle: P.MARITIME_HAZE_MEDIUM,
+        extinction: 0.1,
+        fade: 4,
+    });
+
+    // the low cloud deck the island sits above — big and thin, so it is what a wide FOV sees at the
+    // frame edges
+    volume({
+        position: [-57.36387203979457, -15, 2.607232848593789],
+        scale: [400, 20, 400],
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 0.1,
+        fade: 4,
+    });
+
+    // ball cloud overhead
+    volume({
+        position: [-51.137423384559284, 33, 5.593067265589105],
+        scale: [15, 15, 15],
+        particle: P.CLOUD_DROPLET_LARGE,
+        extinction: 1,
+        fade: 7,
+    });
+}
+
+/**
+ * A rolling mean frame time, so the readout is legible rather than jittering.
+ */
+class FrameTimer {
+    #samples = new Float64Array(60);
+    #count = 0;
+    #cursor = 0;
+
+    add(seconds) {
+        this.#samples[this.#cursor] = seconds * 1000;
+        this.#cursor = (this.#cursor + 1) % this.#samples.length;
+        this.#count = Math.min(this.#count + 1, this.#samples.length);
+    }
+
+    reset() {
+        this.#count = 0;
+        this.#cursor = 0;
+    }
+
+    get mean_ms() {
+        if (this.#count === 0) {
+            return 0;
+        }
+
+        let total = 0;
+        for (let i = 0; i < this.#count; i++) {
+            total += this.#samples[i];
+        }
+        return total / this.#count;
+    }
+}
+
+/**
+ * Point a directional light along a heading, in place.
+ *
+ * The sun's azimuth is the control C-03 turns on: the shadow ray is clipped against a frustum whose
+ * far plane is degenerate, so a sun direction that lies inside the view cone never exits it. Swing
+ * the sun through the frame and the media self-shadowing should be steady; if it switches on as the
+ * sun leaves the frustum, that is the finding.
+ *
+ * @param {DirectionalLight} light
+ * @param {number} azimuth_degrees 0 points along +X
+ * @param {number} elevation_degrees above the horizon
+ */
+function aim_light(light, azimuth_degrees, elevation_degrees) {
+    const azimuth = azimuth_degrees * DEG_TO_RAD;
+    const elevation = elevation_degrees * DEG_TO_RAD;
+
+    const horizontal = Math.cos(elevation);
+
+    // direction the light travels — downward for a sun above the horizon
+    const direction = new Vector3(
+        Math.cos(azimuth) * horizontal,
+        -Math.sin(elevation),
+        Math.sin(azimuth) * horizontal
+    ).normalize();
+
+    const q = new Quaternion();
+    q.fromUnitVectors(Vector3.forward, direction);
+    q.normalize();
+
+    light.transform_local.setRotation(q.x, q.y, q.z, q.w);
+    light.updateMatrices();
+}
+
+/**
+ * How much each profile capture records. `WORKLOAD` is the highest of the three levels the proposal
+ * calls shippable: pass spans, the frame graph, and dispatch/draw counts.
+ *
+ * Measured on this page it runs ~11 KB a frame over ~393 spans, so ~660 KB/s at 60 Hz — the
+ * proposal's estimate of 6 KB assumed ~200 passes and this graph is about twice that. Still small
+ * enough that a hand-driven recording will not notice. `VERBOSE` above it adds bind group contents
+ * at roughly seven times the rate and wants a frame limit set, not a key you can lean on.
+ *
+ * @type {number}
+ */
+const PROFILE_LEVEL = GPUProfileLevel.WORKLOAD;
+
+/**
+ * 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, matching the naming the other `.sgpt` captures on this machine
+ * already use — same sort order, and it reads as the clock you took it by rather than as UTC.
+ *
+ * @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 status_element = element('status');
+    const stats_element = element('stats');
+
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    const canvas = element('view');
+
+    const context = canvas.getContext('webgpu');
+
+    if (context === null) {
+        set_status('no WebGPU context — this browser has none, or the page is not a secure context', 'fail');
+        return;
+    }
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.1;
+    camera.far = 120;
+    camera.fov = 60 * DEG_TO_RAD;
+    // aspect is set by the frame loop, which is the first place the viewport has a size
+
+    const scene = new Scene();
+
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // handy from the console
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.controller = controller;
+
+    // ---- scene ----------------------------------------------------------------------------
+
+    set_status(`loading ${SCENE_URL} …`);
+
+    try {
+        const bundle = await load_gltf(SCENE_URL, { assetManager: await make_playground_asset_manager() });
+
+        scene.add(bundle.scenes);
+    } catch (error) {
+        set_status(
+            `could not load the scene (${error.message}). Put the assets under test_assets/ — `
+            + `see test_assets/README.md.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    const sun = make_sunlight({ intensity: 0.6, temperature: 5500 });
+
+    scene.lights.add(sun);
+
+    add_participating_media(scene);
+
+    load_default_environment(scene, ENVIRONMENT_URL).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    // ---- controls -------------------------------------------------------------------------
+
+    const frame_timer = new FrameTimer();
+
+    let paused = false;
+
+    /** Re-render and drop the frame-time history, since a setting change invalidates it. */
+    function repaint() {
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    }
+
+    // -- views
+
+    const views_element = element('views');
+
+    /**
+     * Which placement the camera was last sent to, for the profile capture's note — a capture that
+     * cannot say where it was taken is much less use a week later.
+     * @type {object|null}
+     */
+    let current_view = null;
+
+    /** @param {object} view */
+    function go_to(view) {
+        current_view = view;
+
+        camera.transform.fromJSON({ translation: view.position, rotation: view.rotation });
+
+        // the controller holds its own spherical state and would otherwise snap the camera back on
+        // the next update
+        controller.from_transform(camera.transform);
+
+        repaint();
+    }
+
+    for (const view of VIEWS) {
+        const button = document.createElement('button');
+
+        button.className = 'view';
+        button.title = view.hint;
+        button.innerHTML = `<span class="tag">${view.c}</span>${view.label}`;
+        button.addEventListener('click', () => {
+            go_to(view);
+            set_status(view.hint);
+        });
+
+        views_element.appendChild(button);
+    }
+
+    // -- sun
+
+    let sun_azimuth = 200;
+    let sun_elevation = 12;
+
+    function update_sun() {
+        aim_light(sun, sun_azimuth, sun_elevation);
+
+        element('sun_azimuth_value').textContent = `${sun_azimuth}°`;
+        element('sun_elevation_value').textContent = `${sun_elevation}°`;
+
+        repaint();
+    }
+
+    element('sun_azimuth').addEventListener('input', event => {
+        sun_azimuth = Number(event.target.value);
+        update_sun();
+    });
+
+    element('sun_elevation').addEventListener('input', event => {
+        sun_elevation = Number(event.target.value);
+        update_sun();
+    });
+
+    /**
+     * Put the sun directly in front of the camera, or directly behind it, at the current elevation.
+     *
+     * This is the C-03 A/B reduced to two clicks. "Into view" places the sun's direction inside the
+     * frustum's direction cone, which is the condition under which `frustum_clip_ray` returns its
+     * 1e20 sentinel.
+     *
+     * @param {boolean} in_front
+     */
+    function aim_sun_relative_to_camera(in_front) {
+        // Straight off the view matrix rather than by rotating a basis vector through the camera's
+        // quaternion by hand: the third row of a view matrix is the camera's backward axis, so this
+        // is the renderer's own answer and cannot disagree with what is on screen. The hand-rolled
+        // version this replaces had a sign error that put the sun behind the camera on both
+        // branches, which is invisible in a screenshot and made the C-03 A/B read as a null result.
+        // The matrices are rebuilt during render, so a placement made this tick is not in them yet
+        // — reading straight after `go_to` would aim the sun at wherever the camera used to be.
+        camera.update();
+
+        const vm = camera.view_matrix;
+
+        const forward_x = -vm[2];
+        const forward_z = -vm[10];
+
+        // `aim_light` takes the direction light *travels*, so the sun sits opposite it. Placing the
+        // sun on the camera's forward axis therefore means aiming its travel back along that axis.
+        const toward_sun_x = in_front ? forward_x : -forward_x;
+        const toward_sun_z = in_front ? forward_z : -forward_z;
+
+        const azimuth = Math.atan2(-toward_sun_z, -toward_sun_x) / DEG_TO_RAD;
+
+        sun_azimuth = Math.round((azimuth % 360 + 360) % 360);
+
+        element('sun_azimuth').value = String(sun_azimuth);
+
+        update_sun();
+    }
+
+    element('sun_into_view').addEventListener('click', () => {
+        aim_sun_relative_to_camera(true);
+        set_status('sun placed in front of the camera — C-03 predicts media self-shadowing vanishes here', 'warn');
+    });
+
+    element('sun_behind').addEventListener('click', () => {
+        aim_sun_relative_to_camera(false);
+        set_status('sun placed behind the camera — C-03 predicts media self-shadowing returns here', 'pass');
+    });
+
+    // -- camera
+
+    element('fov').addEventListener('input', event => {
+        const degrees = Number(event.target.value);
+
+        camera.fov = degrees * DEG_TO_RAD;
+
+        element('fov_value').textContent = `${degrees}°`;
+
+        repaint();
+    });
+
+    // -- volumetrics knobs, read by GPUViewVolumetrics on every metadata update
+
+    element('vol_taa').addEventListener('change', event => {
+        globalThis.__VOL_TAA_ENABLED = event.target.checked;
+        repaint();
+    });
+
+    element('taa').addEventListener('change', event => {
+        renderer.feature_taa_enabled = event.target.checked;
+        repaint();
+    });
+
+    // Off by default on this page. Auto exposure keeps adapting for seconds after anything changes,
+    // which makes a before/after pair differ by more than most of the fixes being judged here do —
+    // it read as a large effect with the wrong sign more than once while this page was being built.
+    renderer.feature_automatic_exposure_enabled = false;
+
+    element('auto_exposure').addEventListener('change', event => {
+        renderer.feature_automatic_exposure_enabled = event.target.checked;
+        repaint();
+    });
+
+    element('froxel_far').addEventListener('input', event => {
+        const value = Number(event.target.value);
+
+        // the slider's top notch means "no split", which is the engine default
+        globalThis.__VOL_FROXEL_FAR = value >= 120 ? Infinity : value;
+
+        element('froxel_far_value').textContent = value >= 120 ? 'off' : `${value} m`;
+
+        repaint();
+    });
+
+    element('ms_octaves').addEventListener('input', event => {
+        const value = Number(event.target.value);
+
+        globalThis.__VOL_MS_OCTAVES = value;
+
+        element('ms_octaves_value').textContent = String(value);
+
+        repaint();
+    });
+
+    // -- profiling: T starts a recording, T again stops it and downloads the capture
+
+    const profile_status = element('profile_status');
+
+    /**
+     * The recording in progress, or null.
+     *
+     * The engine never constructs one of these — `Renderer.profile_session` is a nullable field and
+     * the null checks around it are the entire integration, which is what keeps the profiler out of
+     * a bundle that does not ask for it. The two imports at the top of this file are the whole
+     * opt-in.
+     *
+     * @type {GPUProfileSession|null}
+     */
+    let profile_session = null;
+
+    /** Guards against T being leaned on while a stop is still draining. */
+    let profile_busy = false;
+
+    function set_profile_status(text, recording = false) {
+        profile_status.textContent = text;
+        profile_status.className = recording ? 'recording' : '';
+    }
+
+    function start_profile() {
+        const device = renderer.device;
+
+        const settings = [
+            current_view === null ? 'free camera' : current_view.label,
+            `fov ${Math.round(camera.fov / DEG_TO_RAD)}°`,
+            `volumetric TAA ${(globalThis.__VOL_TAA_ENABLED ?? true) ? 'on' : 'off'}`,
+            `${renderer.pixel_ratio.toFixed(2)}x`,
+        ];
+
+        const session = new GPUProfileSession({
+            level: PROFILE_LEVEL,
+            note: `volumetrics_froxel — ${settings.join(' · ')}`,
+        });
+
+        // Populate before start(): the meta record is written into the stream there and not read
+        // again. Without it the capture is unreadable in the sense that matters — a pass taking
+        // 0.4 ms says nothing until you know which GPU and at what resolution.
+        const meta = session.meta;
+
+        // `GPUDevice.adapterInfo` is recent enough that a browser running this page may not have it,
+        // and several browsers withhold the fields even when they do. Empty is what the format
+        // expects in that case.
+        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 => {
+            set_profile_status(
+                `● recording — ${session.frames_recorded} frames, ${format_bytes(bytes)}  ·  T to stop`,
+                true
+            );
+        });
+
+        renderer.profile_session = session;
+        session.start();
+
+        profile_session = session;
+
+        // The timers go quiet without this rather than failing, so the capture still carries the
+        // frame graph and the workload — it just has no durations in it. Worth knowing before you
+        // record for a minute and then look.
+        const timed = device.features.has('timestamp-query');
+
+        set_profile_status(
+            timed
+                ? '● recording — 0 frames  ·  T to stop'
+                : '● recording without timestamp-query — structure only, no durations  ·  T to stop',
+            true
+        );
+    }
+
+    /**
+     * Wait for frames already submitted to finish landing in the session.
+     *
+     * A frame is committed when its timestamp readback resolves — a `mapAsync` a frame or two behind
+     * submit, see `ShadeGPUCommandContext.profiling_absorbed` — and `record_frame` silently ignores
+     * anything arriving after `stop()`. Stopping the instant the key goes down therefore discards
+     * the last few frames, which are the ones you were most likely looking at.
+     *
+     * Drains the queue, then waits for the frame count to stop moving. Capped, because a recording
+     * taken while the page is paused never moves at all.
+     *
+     * @param {GPUProfileSession} session
+     */
+    async function drain_profile(session) {
+        const DEADLINE_MS = 1000;
+        const QUIET_MS = 60;
+
+        await renderer.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;
+        }
+    }
+
+    async function stop_profile() {
+        const session = profile_session;
+
+        profile_session = null;
+
+        // Detach first, so nothing encoded during the drain below joins the recording. Frames
+        // already encoded are unaffected: Renderer captures the session into a local before it
+        // subscribes to the readback.
+        renderer.profile_session = null;
+
+        set_profile_status('stopping — draining in-flight frames…');
+
+        await drain_profile(session);
+
+        const bytes = session.stop();
+
+        const filename = `volumetrics_froxel-${file_timestamp()}.sgpt`;
+
+        download_bytes(bytes, filename);
+
+        // Also to the console, because the status line is the only other place the name appears and
+        // a browser that declines the save says nothing about which capture it declined.
+        console.log(
+            `profile: ${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}, `
+            + `${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'} -> ${filename}`
+        );
+
+        set_profile_status(
+            `${session.frames_recorded} frames, ${format_bytes(bytes.byteLength)}`
+            + `, ${session.topology_count} topolog${session.topology_count === 1 ? 'y' : 'ies'}`
+            + `  ·  ${filename}`
+        );
+    }
+
+    window.addEventListener('keydown', event => {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        // `key` first, because it is the letter actually printed on the key the user pressed —
+        // `code` is physical position, so on AZERTY it names the key where T sits on QWERTY. `code`
+        // is the fallback for layouts whose `key` is not Latin at all (Cyrillic gives "е" here).
+        if (event.key.toLowerCase() !== 't' && event.code !== 'KeyT') {
+            return;
+        }
+
+        // the panel's sliders and buttons are focusable; do not steal a key from a field
+        const target = event.target;
+
+        if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+            return;
+        }
+
+        if (profile_busy) {
+            return;
+        }
+
+        event.preventDefault();
+
+        profile_busy = true;
+
+        const done = profile_session === null
+            ? Promise.resolve(start_profile())
+            : stop_profile();
+
+        done.catch(error => {
+            set_profile_status(`profiling failed: ${error?.message ?? error}`);
+            console.error(error);
+
+            profile_session = null;
+            renderer.profile_session = null;
+        }).finally(() => {
+            profile_busy = false;
+        });
+    });
+
+    element('pause').addEventListener('click', () => {
+        paused = !paused;
+        element('pause').textContent = paused ? 'Resume' : 'Pause';
+    });
+
+    element('log_camera').addEventListener('click', () => {
+        const t = camera.transform;
+
+        const json = {
+            position: { x: t.translation_x, y: t.translation_y, z: t.translation_z },
+            rotation: { x: t.rotation_x, y: t.rotation_y, z: t.rotation_z, w: t.rotation_w }
+        };
+
+        console.log(JSON.stringify(json, null, 4));
+        set_status('camera written to the console', 'pass');
+    });
+
+    // ---- start ----------------------------------------------------------------------------
+
+    update_sun();
+    go_to(VIEWS[0]);
+
+    controller.movement_speed_scale = 4;
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    set_status(`loaded — ${scene.instances.instances.length} instances, ${scene.volumetrics.volumes.length} media volumes`, 'pass');
+
+    // ---- frame loop -----------------------------------------------------------------------
+
+    const FRAME_RATE_LIMIT = 60;
+
+    create_frame_loop(time_delta_s => {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        renderer.resize(width, height);
+        renderer.pixel_ratio = window.devicePixelRatio;
+        camera.aspect = width / height;
+
+        controller.update();
+
+        if (paused) {
+            return;
+        }
+
+        renderer.render(camera, scene, time_delta_s);
+
+        frame_timer.add(time_delta_s);
+
+        const mean = frame_timer.mean_ms;
+
+        stats_element.textContent =
+            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps`
+            + `  ·  fov ${Math.round(camera.fov / DEG_TO_RAD)}°`;
+    }, FRAME_RATE_LIMIT);
+}