@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -1,363 +1,393 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import { NumericInterval } from "../../../core/math/interval/NumericInterval.js";
-import { seededRandom } from "../../../core/math/random/seededRandom.js";
-import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.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 { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
-import { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.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 { load_scene_from_url } from "../../renderer/scene/serialization/deserialize_scene.js";
-import { add_random_meshes } from "../add_random_meshes.js";
-import { load_default_environment } from "../load_default_environment.js";
-import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
-
-/**
- * Sponza under the path tracer, as a prototype.
- *
- * The point is the one thing no device-free tier and no readback harness can answer: what the tree
- * looks like when something traverses it. `AccumulatingPathTracer` binds `scene_ctx.tlas.buffer`
- * directly and is the traversal-heaviest consumer in the tree, so it is where a wrong child index
- * or a loose parent box shows up as something you can see — geometry that vanishes at a grazing
- * angle, or light that leaks through a wall.
- *
- * It was written to A/B the GPU TLAS build against the legacy CPU one; that comparison has been run
- * (`GPU_BVH_BUILD_PLAN.md` §4.6) and the legacy path is gone. What it is now is the place to notice
- * a regression in the tree, and — through the box-scatter control — the place to build a workload
- * where the TLAS is what traversal costs.
- *
- * Runs under the dev server (`npm run dev`), which is what resolves the one bare specifier the
- * renderer reaches for (`robust-predicates`) and what serves `test_assets/`. The panel is
- * hand-rolled rather than lil-gui: four checkboxes are not worth a dependency the library does not
- * otherwise have.
- */
-
-/**
- * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
- * `test_assets/README.md` for how to put the assets there.
- *
- * glTF rather than one of the `.shade` scenes sitting next to it: `deserialize_scene` accepts
- * format version 2 only — deliberately, with no backward compatibility — and every exported Sponza
- * in the sibling repo is version 1. Re-exporting one is the fix if a `.shade` scene is wanted; the
- * loader below still takes one, chosen by extension.
- *
- * @type {string}
- */
-const DEFAULT_SCENE_URL = '/test_assets/Sponza/glTF/Sponza.gltf';
-
-/**
- * How the boxes the stress control scatters are sized, as a fraction of the scene's shortest
- * bounding-box span.
- *
- * Relative rather than absolute because the page loads whatever `?scene=` names and no two exports
- * agree on what a unit is. The two-order-of-magnitude spread between them is the point: a Morton
- * code sees a centroid and nothing about extent, so a mix of sizes is the case it orders worst.
- *
- * @type {NumericInterval}
- */
-const STRESS_SIZE_FRACTION = new NumericInterval(0.005, 0.4);
-
-/**
- * A frame-time readout, kept as a rolling mean so the number is readable rather than jittering.
- */
-class FrameTimer {
-    #samples = new Float64Array(60);
-    #count = 0;
-    #cursor = 0;
-
-    /**
-     * @param {number} seconds
-     */
-    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;
-    }
-
-    /**
-     * @returns {number} mean frame time in milliseconds, or 0 before there is anything to average
-     */
-    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;
-    }
-}
-
-/**
- * Populate a scene from a URL, picking the loader by extension: a glTF document comes in through
- * `load_gltf` and needs a light placed for it, a `.shade` scene carries its own. Either way the
- * camera ends up framing what arrived.
- *
- * @param {string} url
- * @param {Scene} scene
- * @param {OrbitalCameraController} controller
- * @returns {Promise<void>}
- */
-async function load_scene(url, scene, controller) {
-
-    if (/\.gltf$|\.glb$/i.test(url)) {
-        // glTF reads every byte through the asset framework, so it needs a manager with loaders
-        // registered for the two types it asks for
-        const bundle = await load_gltf(url, { assetManager: await make_playground_asset_manager() });
-
-        scene.add(bundle.scenes);
-
-        if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
-            // a glTF document need not carry any light at all, and Sponza does not
-            scene.lights.add(make_sunlight({ intensity: 7.2 }));
-        }
-    } else {
-        await load_scene_from_url(url, scene);
-    }
-
-    const bounds = scene.instances.bounding_box;
-
-    const radius = Math.hypot(bounds.width, bounds.height, bounds.depth) * 0.5;
-
-    camera_frame_sphere(
-        controller,
-        radius,
-        new Vector3(bounds.centerX, bounds.centerY, bounds.centerZ)
-    );
-
-    controller.movement_speed_scale = Math.max(bounds.width, bounds.height, bounds.depth) * 0.1;
-}
-
-/**
- * Stand the prototype up. Called by the page rather than run on import, so that nothing here
- * touches the DOM until there is one.
- *
- * @returns {Promise<void>}
- */
-export async function start() {
-
-    const element = id => document.getElementById(id);
-
-    const status_element = element('status');
-    const stats_element = element('stats');
-
-    /**
-     * @param {string} text
-     * @param {string} [kind]
-     */
-    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 });
-
-    if (!renderer.graphics.device.features.has('subgroups')) {
-        // Not fatal for rasterization, but the GPU TLAS build takes subgroup builtins in the sort's
-        // scatter and in the extraction pass, so the A/B has only one usable side here.
-        set_status('device has no `subgroups` — the GPU TLAS path will fail; use the CPU side of the A/B', 'warn');
-    }
-
-    const camera = new PerspectiveCamera();
-
-    camera.transform.setTranslation(0, 2, -5);
-    camera.transform.lookAt(Vector3.zero);
-
-    camera.near = 0.1;
-    camera.far = 200;
-    camera.fov = 72 * DEG_TO_RAD;
-    camera.aspect = renderer.aspect_ratio;
-
-    const scene = new Scene();
-
-    // 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);
-
-    // handy from the console
-    globalThis.renderer = renderer;
-    globalThis.scene = scene;
-    globalThis.camera = camera;
-
-    // ---- controls -------------------------------------------------------------------------
-
-    const frame_timer = new FrameTimer();
-
-    let paused = false;
-
-    element('path_tracing').addEventListener('change', event => {
-        renderer.feature_path_tracing_enabled = event.target.checked;
-
-        // Two temporal filters over one image is nonsense; the tracer accumulates on its own.
-        if (event.target.checked) {
-            element('taa').checked = false;
-            renderer.feature_taa_enabled = false;
-        }
-
-        renderer.indicate_view_change();
-        frame_timer.reset();
-    });
-
-    element('taa').addEventListener('change', event => {
-        renderer.feature_taa_enabled = event.target.checked;
-        renderer.indicate_view_change();
-    });
-
-    element('pause').addEventListener('click', () => {
-        paused = !paused;
-        element('pause').textContent = paused ? 'Resume' : 'Pause';
-    });
-
-    element('reset_accumulation').addEventListener('click', () => {
-        renderer.path_tracer.clear_history = true;
-        renderer.indicate_view_change();
-        frame_timer.reset();
-    });
-
-    // Built once and shared across clicks: a geometry per click would be a BLAS per click, which
-    // is the opposite of what this control is for. One generator likewise, so a second click
-    // scatters new boxes rather than laying the same ones down again.
-    const stress_geometry = new BoxGeometry(1, 1, 1);
-    const stress_material = new StandardShadeMaterial();
-    const stress_random = seededRandom(12345);
-
-    element('stress').addEventListener('click', () => {
-        const count = Math.max(1, Number.parseInt(element('stress_count').value, 10) || 0);
-
-        const bounds = scene.instances.bounding_box;
-
-        const shortest_span = Math.min(bounds.width, bounds.height, bounds.depth);
-
-        add_random_meshes({
-            batch: scene.instances,
-            geometries: [stress_geometry],
-            materials: [stress_material],
-            count,
-            region: bounds,
-            geometry_scale_range: new NumericInterval(
-                shortest_span * STRESS_SIZE_FRACTION.min,
-                shortest_span * STRESS_SIZE_FRACTION.max
-            ),
-            random: stress_random
-        });
-
-        renderer.path_tracer.clear_history = true;
-        renderer.indicate_view_change();
-        frame_timer.reset();
-
-        set_status(`added ${count} boxes — ${scene.instances.instances.length} instances`, 'pass');
-    });
-
-    // ---- the scene ------------------------------------------------------------------------
-
-    const url = new URLSearchParams(location.search).get('scene') ?? DEFAULT_SCENE_URL;
-
-    const url_input = element('scene_url');
-
-    url_input.value = url;
-
-    // A Scene has no teardown, so changing scenes reloads the page rather than trying to empty one
-    // in place.
-    function load_url(next) {
-        const parameters = new URLSearchParams(location.search);
-
-        parameters.set('scene', next);
-
-        location.search = parameters.toString();
-    }
-
-    element('load').addEventListener('click', () => load_url(url_input.value.trim()));
-
-    url_input.addEventListener('keydown', event => {
-        if (event.key === 'Enter') {
-            load_url(url_input.value.trim());
-        }
-    });
-
-    set_status(`loading ${url} …`);
-
-    try {
-        await load_scene(url, scene, controller);
-    } catch (error) {
-        set_status(
-            `could not load the scene (${error.message}). Put the assets under test_assets/ — `
-            + `see test_assets/README.md — or type a reachable URL above and press Load.`,
-            'fail'
-        );
-        console.error(error);
-        return;
-    }
-
-    // Image-based lighting if a sky is there, and nothing said about it if not: the scene renders
-    // either way, and a missing optional asset is not a reason to show a failure. The helper warns
-    // and resolves false rather than rejecting.
-    load_default_environment(scene).then(applied => {
-        if (applied) {
-            renderer.indicate_view_change();
-        }
-    });
-
-    // 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`, 'pass');
-
-    renderer.indicate_view_change();
-
-    // ---- 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 instances = scene.instances.instances.length;
-        const mean = frame_timer.mean_ms;
-
-        stats_element.textContent =
-            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps  ·  `
-            + `${instances} instances`
-            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : ''}`;
-    }, FRAME_RATE_LIMIT);
-}
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { NumericInterval } from "../../../core/math/interval/NumericInterval.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { camera_frame_sphere } from "../../renderer/camera/camera_frame_sphere.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 { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
+import { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.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 { load_scene_from_url } from "../../renderer/scene/serialization/deserialize_scene.js";
+import { add_random_meshes } from "../add_random_meshes.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { make_playground_asset_manager } from "../make_playground_asset_manager.js";
+import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
+import { prefab_place } from "../../../engine/graphics3/prefab/prefab_place.js";
+import { shade_bundle_bounds } from "../../../engine/graphics3/shade_bundle_bounds.js";
+
+/**
+ * Sponza under the path tracer, as a prototype.
+ *
+ * The point is the one thing no device-free tier and no readback harness can answer: what the tree
+ * looks like when something traverses it. `AccumulatingPathTracer` binds `scene_ctx.tlas.buffer`
+ * directly and is the traversal-heaviest consumer in the tree, so it is where a wrong child index
+ * or a loose parent box shows up as something you can see — geometry that vanishes at a grazing
+ * angle, or light that leaks through a wall.
+ *
+ * It was written to A/B the GPU TLAS build against the legacy CPU one; that comparison has been run
+ * (`GPU_BVH_BUILD_PLAN.md` §4.6) and the legacy path is gone. What it is now is the place to notice
+ * a regression in the tree, and — through the box-scatter control — the place to build a workload
+ * where the TLAS is what traversal costs.
+ *
+ * Runs under the dev server (`npm run dev`), which is what resolves the one bare specifier the
+ * renderer reaches for (`robust-predicates`) and what serves `test_assets/`. The panel is
+ * hand-rolled rather than lil-gui: four checkboxes are not worth a dependency the library does not
+ * otherwise have.
+ */
+
+/**
+ * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
+ * `test_assets/README.md` for how to put the assets there.
+ *
+ * glTF rather than one of the `.shade` scenes sitting next to it: `deserialize_scene` accepts
+ * format version 2 only — deliberately, with no backward compatibility — and every exported Sponza
+ * in the sibling repo is version 1. Re-exporting one is the fix if a `.shade` scene is wanted; the
+ * loader below still takes one, chosen by extension.
+ *
+ * @type {string}
+ */
+const DEFAULT_SCENE_URL = '/test_assets/Sponza/glTF/Sponza.gltf';
+
+/**
+ * How the boxes the stress control scatters are sized, as a fraction of the scene's shortest
+ * bounding-box span.
+ *
+ * Relative rather than absolute because the page loads whatever `?scene=` names and no two exports
+ * agree on what a unit is. The two-order-of-magnitude spread between them is the point: a Morton
+ * code sees a centroid and nothing about extent, so a mix of sizes is the case it orders worst.
+ *
+ * @type {NumericInterval}
+ */
+const STRESS_SIZE_FRACTION = new NumericInterval(0.005, 0.4);
+
+/**
+ * A frame-time readout, kept as a rolling mean so the number is readable rather than jittering.
+ */
+class FrameTimer {
+    #samples = new Float64Array(60);
+    #count = 0;
+    #cursor = 0;
+
+    /**
+     * @param {number} seconds
+     */
+    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;
+    }
+
+    /**
+     * @returns {number} mean frame time in milliseconds, or 0 before there is anything to average
+     */
+    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;
+    }
+}
+
+/** how many primitives the loaded model placed — the boxes the stress button adds are on the batch, counted apart */
+let drawn = 0;
+
+/** how many stress boxes the button has scattered — primitives at rows of their own */
+let boxes = 0;
+
+/** the box the loaded model occupies, which the stress boxes are scattered through */
+const scene_bounds = new AABB3();
+
+/**
+ * @typedef {import("../../renderer/loader/SceneBundle.js").SceneBundle} SceneBundle
+ */
+
+/**
+ * Populate a scene from a URL, picking the loader by extension: a glTF document comes in through
+ * `load_gltf` and needs a light placed for it, a `.shade` scene carries its own. Either way the
+ * camera ends up framing what arrived.
+ *
+ * @param {string} url
+ * @param {Scene} scene
+ * @param {OrbitalCameraController} controller
+ * @returns {Promise<void>}
+ */
+async function load_scene(url, scene, controller) {
+    /** @type {SceneBundle} */
+    let bundle;
+
+    if (/\.gltf$|\.glb$/i.test(url)) {
+        // glTF reads every byte through the asset framework, so it needs a manager with loaders
+        // registered for the two types it asks for
+        bundle = await load_gltf(url, { assetManager: await make_playground_asset_manager() });
+
+        if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
+            // a glTF document need not carry any light at all, and Sponza does not
+            place_light(scene, make_sunlight({ intensity: 7.2 }));
+        }
+    } else {
+        // the file's lights and environment go to the scene; its meshes come back as a model
+        bundle = await load_scene_from_url(url, scene);
+    }
+
+    const placed = prefab_place(renderer.scenes.obtain(scene), scene.dataset, prefab_compile(bundle), new Transform64());
+
+    drawn = placed.drawn;
+
+    const bounds = new AABB3();
+
+    shade_bundle_bounds(bounds, bundle);
+    scene_bounds.copy(bounds);
+
+    const radius = Math.hypot(bounds.width, bounds.height, bounds.depth) * 0.5;
+
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3(bounds.centerX, bounds.centerY, bounds.centerZ)
+    );
+
+    controller.movement_speed_scale = Math.max(bounds.width, bounds.height, bounds.depth) * 0.1;
+}
+
+/**
+ * Stand the prototype up. Called by the page rather than run on import, so that nothing here
+ * touches the DOM until there is one.
+ *
+ * @returns {Promise<void>}
+ */
+export async function start() {
+
+    const element = id => document.getElementById(id);
+
+    const status_element = element('status');
+    const stats_element = element('stats');
+
+    /**
+     * @param {string} text
+     * @param {string} [kind]
+     */
+    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 });
+
+    if (!renderer.graphics.device.features.has('subgroups')) {
+        // Not fatal for rasterization, but the GPU TLAS build takes subgroup builtins in the sort's
+        // scatter and in the extraction pass, so the A/B has only one usable side here.
+        set_status('device has no `subgroups` — the GPU TLAS path will fail; use the CPU side of the A/B', 'warn');
+    }
+
+    const camera = new PerspectiveCamera();
+
+    camera.transform.setTranslation(0, 2, -5);
+    camera.transform.lookAt(Vector3.zero);
+
+    camera.near = 0.1;
+    camera.far = 200;
+    camera.fov = 72 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+
+    // the sun stands at an entity, so the scene names a dataset for it
+    scene.dataset = new EntityComponentDataset();
+
+    // 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);
+
+    // handy from the console
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+
+    // ---- controls -------------------------------------------------------------------------
+
+    const frame_timer = new FrameTimer();
+
+    let paused = false;
+
+    element('path_tracing').addEventListener('change', event => {
+        renderer.feature_path_tracing_enabled = event.target.checked;
+
+        // Two temporal filters over one image is nonsense; the tracer accumulates on its own.
+        if (event.target.checked) {
+            element('taa').checked = false;
+            renderer.feature_taa_enabled = false;
+        }
+
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    });
+
+    element('taa').addEventListener('change', event => {
+        renderer.feature_taa_enabled = event.target.checked;
+        renderer.indicate_view_change();
+    });
+
+    element('pause').addEventListener('click', () => {
+        paused = !paused;
+        element('pause').textContent = paused ? 'Resume' : 'Pause';
+    });
+
+    element('reset_accumulation').addEventListener('click', () => {
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+        frame_timer.reset();
+    });
+
+    // Built once and shared across clicks: a geometry per click would be a BLAS per click, which
+    // is the opposite of what this control is for. One generator likewise, so a second click
+    // scatters new boxes rather than laying the same ones down again.
+    const stress_geometry = new BoxGeometry(1, 1, 1);
+    const stress_material = new StandardShadeMaterial();
+    const stress_random = seededRandom(12345);
+
+    element('stress').addEventListener('click', () => {
+        const count = Math.max(1, Number.parseInt(element('stress_count').value, 10) || 0);
+
+        const bounds = scene_bounds;
+        const shortest_span = Math.min(bounds.width, bounds.height, bounds.depth);
+
+        boxes += add_random_meshes({
+            scene_context: renderer.scenes.obtain(scene),
+            geometries: [stress_geometry],
+            materials: [stress_material],
+            count,
+            region: bounds,
+            geometry_scale_range: new NumericInterval(
+                shortest_span * STRESS_SIZE_FRACTION.min,
+                shortest_span * STRESS_SIZE_FRACTION.max
+            ),
+            random: stress_random
+        }).length;
+
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+        frame_timer.reset();
+
+        set_status(`added ${count} boxes — ${drawn + boxes} instances`, 'pass');
+    });
+
+    // ---- the scene ------------------------------------------------------------------------
+
+    const url = new URLSearchParams(location.search).get('scene') ?? DEFAULT_SCENE_URL;
+
+    const url_input = element('scene_url');
+
+    url_input.value = url;
+
+    // A Scene has no teardown, so changing scenes reloads the page rather than trying to empty one
+    // in place.
+    function load_url(next) {
+        const parameters = new URLSearchParams(location.search);
+
+        parameters.set('scene', next);
+
+        location.search = parameters.toString();
+    }
+
+    element('load').addEventListener('click', () => load_url(url_input.value.trim()));
+
+    url_input.addEventListener('keydown', event => {
+        if (event.key === 'Enter') {
+            load_url(url_input.value.trim());
+        }
+    });
+
+    set_status(`loading ${url} …`);
+
+    try {
+        await load_scene(url, scene, controller);
+    } catch (error) {
+        set_status(
+            `could not load the scene (${error.message}). Put the assets under test_assets/ — `
+            + `see test_assets/README.md — or type a reachable URL above and press Load.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    // Image-based lighting if a sky is there, and nothing said about it if not: the scene renders
+    // either way, and a missing optional asset is not a reason to show a failure. The helper warns
+    // and resolves false rather than rejecting.
+    load_default_environment(scene).then(applied => {
+        if (applied) {
+            renderer.indicate_view_change();
+        }
+    });
+
+    // the controller's keyboard device listens on body, and only a focused element gets key events
+    document.body.focus();
+
+    set_status(`loaded — ${drawn} instances`, 'pass');
+
+    renderer.indicate_view_change();
+
+    // ---- 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 instances = drawn + boxes;
+        const mean = frame_timer.mean_ms;
+
+        stats_element.textContent =
+            `${mean.toFixed(1)} ms  ·  ${mean > 0 ? (1000 / mean).toFixed(0) : '0'} fps  ·  `
+            + `${instances} instances`
+            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : ''}`;
+    }, FRAME_RATE_LIMIT);
+}