@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js

@@ -0,0 +1,366 @@
+import { GEOMETRY_METADATA_STRUCT } from "../../renderer/geometry/GEOMETRY_METADATA_STRUCT.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD,
+    BVH_NODE_STRIDE_WORDS
+} from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { bvh2_check_containment } from "../../renderer/geometry/bvh/bvh2_check_bounds.js";
+import { record_blas_refit } from "../../renderer/geometry/bvh/record_blas_refit.js";
+import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+
+/**
+ * @type {number}
+ */
+const BVH_NULL_NODE = 0xffffffff;
+
+/**
+ * Device-level check for the per-frame BLAS refit, for when looking at the picture is not enough or
+ * not possible.
+ *
+ * The page next door answers "does the traced silhouette match the rasterized one" with your eyes.
+ * This answers a sharper version of the same question with numbers, by comparing two *independent*
+ * GPU computations of one quantity:
+ *
+ *   - `shader_meshlet_bounds_reduce` atomically merges every deformed vertex into the clone's
+ *     geometry-metadata bounding box. It exists for the rasterizer's culling and knows nothing
+ *     about trees.
+ *   - {@link record_blas_refit} takes each leaf triangle's box and climbs the tree. The root node
+ *     ends up bounding every triangle.
+ *
+ * Same vertices, same frame, two paths that share no code. They have to agree, and a stale BLAS
+ * cannot make them: the metadata box tracks the pose while the root node holds the bind pose.
+ *
+ * Both are read straight out of the buffers the shaders wrote, so this needs a real device — call
+ * it from the playground page's console, not from a spec.
+ */
+
+/**
+ * Read a range of a GPU buffer back to the CPU.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer must carry `COPY_SRC`
+ * @param {number} offset in bytes, a multiple of 4
+ * @param {number} size in bytes
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    // mapped ranges come in multiples of 4, and copies of 4 — round out rather than refusing an
+    // offset the caller had no reason to align
+    const aligned_offset = Math.floor(offset / 4) * 4;
+    const slack = offset - aligned_offset;
+    const aligned_size = Math.ceil((size + slack) / 4) * 4;
+
+    const staging = device.createBuffer({
+        label: 'verify/readback',
+        size: aligned_size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'verify/readback' });
+
+    encoder.copyBufferToBuffer(buffer, aligned_offset, staging, 0, aligned_size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(slack, slack + size);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * `[min.xyz, max.xyz]` of the tree's root node, as the refit left it.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUGeometryBVHManager} blas
+ * @param {number} address arena node index of the tree's root
+ * @returns {Promise<number[]>}
+ */
+async function read_root_bounds(device, blas, address) {
+    const bytes = await read_back(device, blas.buffer_data, address * BVH2_NODE_STRUCT.size, 24);
+
+    return [...new Float32Array(bytes)];
+}
+
+/**
+ * `[min.xyz, max.xyz]` from a geometry's metadata row, as the bounds-refresh chain left it.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUGeometryManager} geometries
+ * @param {number} geometry_index
+ * @returns {Promise<number[]>}
+ */
+async function read_metadata_bounds(device, geometries, geometry_index) {
+    const stride = GEOMETRY_METADATA_STRUCT.aligned_size;
+
+    // ask the struct where its box is rather than counting bytes by hand — `.pack()` reorders
+    const field_offset = GEOMETRY_METADATA_STRUCT.fields.find(f => f.name === 'bounding_box').offset;
+
+    const bytes = await read_back(
+        device,
+        geometries.buffer_metadata,
+        geometry_index * stride + field_offset,
+        24
+    );
+
+    return [...new Float32Array(bytes)];
+}
+
+/**
+ * How far apart two boxes are, relative to their own size.
+ *
+ * Relative because the assets do not agree on what a unit is, and absolute epsilons then say
+ * nothing. The two paths reduce in different orders over the same floats, so exact equality is not
+ * the bar — being the same box to within rounding is.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+function box_disagreement(a, b) {
+    const span = Math.max(
+        1e-6,
+        ...[0, 1, 2].map(axis => Math.abs(a[axis + 3] - a[axis]))
+    );
+
+    return Math.max(...a.map((value, i) => Math.abs(value - b[i]))) / span;
+}
+
+/**
+ * Advance the scene by hand.
+ *
+ * `create_frame_loop` runs on `requestAnimationFrame`, which a browser throttles to a stop when the
+ * page is not being composited — a hidden tab, a devtools-only session. Driving `render` directly
+ * makes the check independent of whether anyone is looking at it.
+ *
+ * @param {Renderer} renderer
+ * @param {PerspectiveCamera} camera
+ * @param {Scene} scene
+ * @param {number} frames
+ * @param {number} [dt] seconds per frame
+ */
+async function advance(renderer, camera, scene, frames, dt = 1 / 60) {
+    for (let i = 0; i < frames; i++) {
+        renderer.render(camera, scene, dt);
+
+        await renderer.graphics.device.queue.onSubmittedWorkDone();
+    }
+}
+
+/**
+ * Run the check.
+ *
+ * Two samples, taken far enough apart in the dance that the pose is meaningfully different. Each
+ * sample holds the two boxes against each other; the pair holds the tree against *itself* over
+ * time, which is what catches a refit that runs but reads the source's rest-pose vertices — the
+ * boxes would agree at every sample and never move.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance] relative box disagreement to accept
+ * @returns {Promise<object>} the samples and the verdict
+ */
+export async function verify_skinned_blas_refit({
+                                                    renderer,
+                                                    camera,
+                                                    scene,
+                                                    mesh,
+                                                    tolerance = 1e-3,
+                                                }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometries = graphics.geometries;
+
+    // settle: the first frames register the clone, upload its tree and run the first refit
+    await advance(renderer, camera, scene, 8);
+
+    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+
+    if (geometry_index === undefined) {
+        throw new Error('the mesh has no clone — is it a SkinnedMesh, bound to a skin, and in the scene?');
+    }
+
+    const address = new Uint32Array(
+        await read_back(device, geometries.blas.buffer_metadata, geometry_index * 4, 4)
+    )[0];
+
+    const samples = [];
+
+    for (let i = 0; i < 2; i++) {
+        // a third of a second between samples — far enough into the dance that a limb has moved,
+        // close enough that the whole check is quick
+        if (i > 0) {
+            await advance(renderer, camera, scene, 20);
+        }
+
+        const root = await read_root_bounds(device, geometries.blas, address);
+        const metadata = await read_metadata_bounds(device, geometries, geometry_index);
+
+        samples.push({ root, metadata, disagreement: box_disagreement(metadata, root) });
+    }
+
+    // and the interior, which the root box alone says nothing about
+    const region = await read_back(
+        device,
+        geometries.blas.buffer_data,
+        address * BVH2_NODE_STRUCT.size,
+        (mesh.geometry.bvh.byteLength / BVH2_NODE_STRUCT.size | 0) * BVH2_NODE_STRUCT.size
+    );
+
+    // the same checker the spec asserts with, so the browser tier and CI ask one question
+    const union_check = bvh2_check_containment(region);
+
+    const agrees = samples.every(sample => sample.disagreement <= tolerance)
+        && union_check.problems.length === 0;
+
+    // the pose has to have moved for the agreement above to mean anything
+    const moved = box_disagreement(samples[0].root, samples[1].root);
+
+    const result = {
+        geometry_index,
+        address,
+        samples,
+        union_check,
+        agrees,
+        moved,
+        // a box that never moves is a box that is not being recomputed, however well it agrees
+        verdict: agrees && moved > tolerance
+            ? `pass — the tree bounds the deformed mesh and follows it; `
+            + `${union_check.internal} internal nodes are exactly their children's union`
+            : agrees
+                ? `inconclusive — the boxes agree but neither moved (${moved.toExponential(2)}); is the animation playing?`
+                : union_check.problems.length > 0
+                    ? `FAIL — the interior does not hold together: ${union_check.problems[0]}`
+                    : `FAIL — the tree does not bound the deformed mesh (${samples.map(s => s.disagreement.toExponential(2)).join(', ')})`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}
+
+/**
+ * Does each leaf's box belong to the triangle that leaf names?
+ *
+ * The check above cannot see this, and it is worth being explicit about why. Its two properties —
+ * root box equals the metadata box, every internal node equals its children's union — are both
+ * invariant under *any* permutation of triangles among leaves. Deal the same set of triangle boxes
+ * out to the wrong leaves and the union of all of them is unchanged, so the root still matches, and
+ * the climb still computes each node from whatever its children hold. A tree that fits every
+ * triangle to the wrong leaf passes both and traces garbage: a ray descends into a box, tests the
+ * triangle the leaf names, and that triangle is somewhere else entirely.
+ *
+ * The way to see it is to refit a geometry that is **not** deforming, and hold the result against
+ * the tree it was copied from. The CPU builder put each leaf's box there with the correspondence
+ * that is correct by construction; the refit recomputes those boxes from the vertex buffer. Nothing
+ * moved in between, so the two have to be the same bytes — and a permutation is exactly what stops
+ * them being.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {MeshletGeometry} options.geometry a geometry nothing deforms
+ * @returns {Promise<object>}
+ */
+export async function verify_leaf_correspondence({ renderer, geometry }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const geometries = graphics.geometries;
+
+    const metadata = geometries.get_metadata(geometry);
+
+    if (metadata === undefined) {
+        throw new Error('that geometry is not registered');
+    }
+
+    const target = geometries.blas.get_refit_target(metadata);
+
+    if (target === undefined) {
+        throw new Error('that geometry has no resident tree');
+    }
+
+    const expected = new Float32Array(geometry.bvh);
+    const expected_words = new Uint32Array(geometry.bvh);
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'verify/leaf correspondence');
+
+    record_blas_refit(cmd, {
+        blas: geometries.blas,
+        geometries,
+        owner: metadata,
+        geometry_index: metadata.index,
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const region = new Float32Array(await read_back(
+        device,
+        geometries.blas.buffer_data,
+        target.node_word_offset * Uint32Array.BYTES_PER_ELEMENT,
+        geometry.bvh.byteLength
+    ));
+
+    const node_count = Math.floor(expected.length / BVH_NODE_STRIDE_WORDS);
+
+    const problems = [];
+
+    let leaves = 0;
+    let worst = 0;
+
+    for (let node = 0; node < node_count && problems.length < 8; node++) {
+        const base = node * BVH_NODE_STRIDE_WORDS;
+
+        // only the leaves: an internal node's box comes from the climb, which the union check
+        // already covers, and slots the tree never reaches hold whatever the free list left
+        if (expected_words[base + BVH_NODE_CHILD_1_WORD] !== BVH_NULL_NODE) {
+            continue;
+        }
+
+        leaves += 1;
+
+        for (let i = 0; i < 6; i++) {
+            const want = expected[base + BVH_NODE_BOUNDS_WORD + i];
+            const got = region[base + BVH_NODE_BOUNDS_WORD + i];
+
+            const error = Math.abs(want - got);
+
+            if (error > worst) {
+                worst = error;
+            }
+
+            if (want !== got) {
+                problems.push(
+                    `leaf node ${node} bound ${i}: builder says ${want}, refit says ${got}`
+                );
+            }
+        }
+    }
+
+    const result = {
+        leaves,
+        worst,
+        problems,
+        verdict: problems.length === 0
+            ? `pass — all ${leaves} leaf boxes are the ones the builder put there, so each leaf's `
+            + `box is its own triangle's`
+            : `FAIL — ${problems.length}+ leaf boxes differ from the builder's: ${problems[0]}`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera whose position the rays start from
+ * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
+ * @param {object} options.target refit target of the tree to audit
+ * @param {number} options.geometry_index
+ * @returns {Promise<object>}
+ */
+export function verify_traversal_reachability({ renderer, camera, mesh, target, geometry_index, }: {
+    renderer: Renderer;
+    camera: PerspectiveCamera;
+    mesh: Mesh;
+    target: object;
+    geometry_index: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_traversal_reachability.d.ts.map

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_traversal_reachability.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js"],"names":[],"mappings":"AAoHA;;;;;;;;GAQG;AACH;IAP6B,QAAQ;IACC,MAAM;IACnB,IAAI;IACF,MAAM,EAAtB,MAAM;IACU,cAAc,EAA9B,MAAM;IACJ,QAAQ,MAAM,CAAC,CA6H3B"}

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js

@@ -0,0 +1,249 @@
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import {
+    BLAS_VISIBILITY_SETTINGS_STRUCT,
+    shader_blas_audit_visibility
+} from "./shader_blas_audit_visibility.js";
+
+/**
+ * Can the traversal reach every triangle in the tree?
+ *
+ * The last unexercised link. Everything about the tree itself checks out — leaf boxes contain the
+ * triangles the intersector fetches, internal nodes are their children's union, the root matches an
+ * independently computed box, the instance's world AABB contains the geometry, and the stack does
+ * not overflow. None of that runs `ray_query_blas_nearest`, and that function is what the picture
+ * is made of.
+ *
+ * So: one ray per triangle, from the camera to that triangle's own centroid. The centroid is inside
+ * the triangle, so the ray intersects it, so a hit is guaranteed — this triangle, or whatever
+ * occludes it. A miss cannot happen geometrically. Every miss is the traversal declining to enter a
+ * box the ray is inside.
+ *
+ * Run it from a view that the picture disagrees at and from one it agrees at; the difference
+ * between the two counts is the fault, expressed as triangles rather than pixels.
+ */
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} size
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, size) {
+    const staging = device.createBuffer({
+        label: 'reachability/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'reachability/readback' });
+
+    encoder.copyBufferToBuffer(buffer, 0, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Apply the inverse of a mesh's transform to a world point — the same trip `chunk_ray_query_nearest`
+ * makes to put a ray into geometry space.
+ *
+ * Done on the host with a full inverse rather than by transposing a rotation, because the transform
+ * carries the asset's centimetre scale and a shortcut that assumes orthonormality would silently be
+ * a hundred times wrong here.
+ *
+ * @param {ArrayLike<number>} m column-major 4x4
+ * @param {number[]} point
+ * @returns {number[]}
+ */
+function inverse_transform_point(m, point) {
+    const a = [
+        [m[0], m[4], m[8], m[12]],
+        [m[1], m[5], m[9], m[13]],
+        [m[2], m[6], m[10], m[14]],
+        [m[3], m[7], m[11], m[15]],
+    ];
+
+    const b = [point[0], point[1], point[2], 1];
+
+    // Gaussian elimination on the 4x4 — small, and clearer than an inlined cofactor expansion
+    for (let column = 0; column < 4; column++) {
+        let pivot = column;
+
+        for (let row = column + 1; row < 4; row++) {
+            if (Math.abs(a[row][column]) > Math.abs(a[pivot][column])) {
+                pivot = row;
+            }
+        }
+
+        [a[column], a[pivot]] = [a[pivot], a[column]];
+        [b[column], b[pivot]] = [b[pivot], b[column]];
+
+        const divisor = a[column][column];
+
+        for (let k = column; k < 4; k++) {
+            a[column][k] /= divisor;
+        }
+
+        b[column] /= divisor;
+
+        for (let row = 0; row < 4; row++) {
+            if (row === column) {
+                continue;
+            }
+
+            const factor = a[row][column];
+
+            for (let k = column; k < 4; k++) {
+                a[row][k] -= factor * a[column][k];
+            }
+
+            b[row] -= factor * b[column];
+        }
+    }
+
+    const w = b[3] === 0 ? 1 : b[3];
+
+    return [b[0] / w, b[1] / w, b[2] / w];
+}
+
+/**
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {PerspectiveCamera} options.camera whose position the rays start from
+ * @param {Mesh} options.mesh the instance whose transform puts the camera into geometry space
+ * @param {object} options.target refit target of the tree to audit
+ * @param {number} options.geometry_index
+ * @returns {Promise<object>}
+ */
+export async function verify_traversal_reachability({
+                                                        renderer,
+                                                        camera,
+                                                        mesh,
+                                                        target,
+                                                        geometry_index,
+                                                    }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+    const meshlets = geometries.meshlets;
+
+    const { leaf_count, node_word_offset, leaf_nodes_offset } = target;
+
+    const origin = inverse_transform_point(
+        mesh.transform_global.matrix,
+        [...camera.transform.position]
+    );
+
+    const t_bytes = leaf_count * Float32Array.BYTES_PER_ELEMENT;
+
+    const out_t = device.createBuffer({
+        label: 'reachability/t',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const out_triangle = device.createBuffer({
+        label: 'reachability/triangle',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const out_expected_t = device.createBuffer({
+        label: 'reachability/expected t',
+        size: t_bytes,
+        usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+    });
+
+    const cmd = ShadeGPUCommandContext.create(graphics, 'audit/reachability');
+
+    shader_blas_audit_visibility.dispatchLinear({
+        encoder: cmd,
+        element_count: leaf_count,
+        bindings: {
+            settings: cmd.allocateTransientValueBuffer(BLAS_VISIBILITY_SETTINGS_STRUCT, {
+                origin,
+                leaf_count,
+                node_word_offset,
+                leaf_nodes_offset,
+                geometry_index,
+                tmax: 1e12,
+            }),
+            leaf_nodes: blas.buffer_leaf_nodes,
+            blas_lookup: blas.buffer_metadata,
+            blas_data: blas.buffer_data,
+            geometries: geometries.buffer_metadata,
+            meshlet_metadata: meshlets.buffer_metadata,
+            meshlet_data: meshlets.buffer_data,
+            nodes: blas.buffer_data,
+            out_t,
+            out_triangle,
+            out_expected_t,
+        },
+    });
+
+    cmd.finish();
+
+    await device.queue.onSubmittedWorkDone();
+
+    const t = new Float32Array(await read_back(device, out_t, t_bytes));
+    const expected = new Float32Array(await read_back(device, out_expected_t, t_bytes));
+
+    out_t.destroy();
+    out_triangle.destroy();
+    out_expected_t.destroy();
+
+    let missed = 0;
+    let overshot = 0;
+    let worst_overshoot = 0;
+
+    for (let i = 0; i < leaf_count; i++) {
+        if (!(t[i] >= 0)) {
+            missed += 1;
+
+            continue;
+        }
+
+        // 1e-3 of the aimed distance, which is far above float error on these magnitudes and far
+        // below the gap between one surface and the next
+        const overshoot = (t[i] - expected[i]) / Math.max(1e-9, expected[i]);
+
+        if (overshoot > 1e-3) {
+            overshot += 1;
+
+            worst_overshoot = Math.max(worst_overshoot, overshoot);
+        }
+    }
+
+    const lost = missed + overshot;
+
+    const result = {
+        leaf_count,
+        missed,
+        overshot,
+        worst_overshoot: +worst_overshoot.toFixed(4),
+        lost,
+        lost_pct: +(lost / leaf_count * 100).toFixed(3),
+        origin: origin.map(v => +v.toFixed(3)),
+        verdict: lost === 0
+            ? `pass — the traversal returns a surface at or before every one of ${leaf_count} `
+            + `triangles it was aimed at`
+            : `FAIL — ${lost} of ${leaf_count} (${(lost / leaf_count * 100).toFixed(2)}%) rays aimed `
+            + `at a triangle came back with nothing (${missed}) or with something behind it `
+            + `(${overshot}). Neither is geometrically possible, so the traversal is walking past `
+            + `surfaces it was pointed at — which is the hole in the traced image.`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/sponza_path_trace/README.md

@@ -0,0 +1,57 @@
+# Sponza — path tracer
+
+A prototype page that loads Sponza and renders it with the path tracer, the traversal-heaviest
+consumer of the TLAS.
+
+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 has the numbers), the GPU build won on every axis at instance scale,
+and the legacy path has been deleted — so the toggle is gone with it. What the page is for now:
+noticing a regression in the tree, since a wrong child index or a parent box that does not contain
+its children survives every per-node byte assertion and shows up here as geometry that disappears
+at a grazing angle or light through a wall; and building a workload where the TLAS is what
+traversal costs, which is what the box-scatter control does.
+
+## Running it
+
+```bash
+npm install
+npm run dev
+```
+
+then open <http://localhost:5173/src/shade/playground/sponza_path_trace/index.html>.
+
+The scene comes from `test_assets/Sponza/glTF/Sponza.gltf`, which is gitignored and unpublished —
+`test_assets/README.md` has the two lines that put it and an environment map there. To load
+something else, type its URL in the box and press Load, or pass it up front:
+
+```
+?scene=/some/other/scene.shade
+```
+
+The loader picks itself by extension: `.gltf` / `.glb` through `load_gltf`, anything else through
+`deserialize_scene`. Changing the URL reloads the page — a `Scene` has no teardown, so swapping one
+in place is not something this prototype tries to do.
+
+Note that the `.shade` scenes sitting beside Sponza in the sibling repo do **not** load:
+`deserialize_scene` takes format version 2 only and those are version 1. See `test_assets/README.md`.
+
+## The controls
+
+| control | what it does |
+|---|---|
+| **Path tracer** | `renderer.feature_path_tracing_enabled`. Accumulates one tile per frame and resets when the camera moves, so let it settle before judging an image. |
+| **TAA** | Turned off automatically when the tracer goes on — the tracer has its own temporal accumulation and two of them fight. |
+| **Reset accumulation** | Discards traced history without touching the camera. |
+| **Add boxes** | Scatters N boxes at sizes spanning two orders of magnitude, through `add_random_meshes`. At Sponza's own ~100 instances a traced frame is entirely BLAS and shading and the TLAS's shape is invisible in it; quantity is what moves traversal cost into the TLAS, and size variety is the case a Morton order handles worst. Sizes are a fraction of the loaded scene's own bounds, so the control means the same thing whatever `?scene=` names, and clicking twice adds different boxes rather than the same ones again. |
+
+Frame time is a 60-frame rolling mean next to the instance count. It is a *whole-frame* number and
+the tracer dominates it — for build cost specifically, `bvh_repro`'s BVH check times the build
+passes individually.
+
+## Notes
+
+- `renderer`, `scene` and `camera` are on `globalThis`, so the console can reach them.
+- Drag to orbit, wheel to zoom. The controller is attached to `document.body`, so dragging across
+  the panel moves the camera too.
+- The path tracer is prototype-grade and off by default in `Renderer`; `feature_path_tracing_enabled`
+  exists to make this comparison possible, not as a shipping render mode.