@woosh/meep-engine 3.3.0 → 3.5.0

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

@@ -0,0 +1,254 @@
+import { verify_gpu_bvh_build } from "../../renderer/gpu_primitive/bvh/verify_gpu_bvh_build.js";
+import { verify_radix_sort } from "../../renderer/gpu_primitive/sort/verify_radix_sort.js";
+import { verify_gpu_tlas_build } from "../../renderer/scene/verify_gpu_tlas_build.js";
+import { bvh_repro_device, describe_device } from "./bvh_repro_device.js";
+
+/**
+ * Driver for the standalone GPU BVH repro page.
+ *
+ * The harnesses it runs report through `console`, which is where they report from the main
+ * playground too — so rather than giving them a second output channel, this mirrors the console
+ * into the page while a run is in flight. That keeps one implementation of each check and makes the
+ * page useful to someone who has devtools closed.
+ */
+
+const log_element = document.getElementById('log');
+const status_element = document.getElementById('status');
+const device_element = document.getElementById('device');
+const buttons = [...document.querySelectorAll('button[data-run]')];
+
+/** @type {{graphics: GraphicsContext, device: GPUDevice, adapter: GPUAdapter}|undefined} */
+let context;
+
+/**
+ * @param {string} text
+ * @param {string} [kind] one of 'pass', 'fail', 'warn', 'note'
+ */
+function append(text, kind = '') {
+    const line = document.createElement('div');
+
+    line.className = `line ${kind}`;
+    line.textContent = text;
+
+    log_element.appendChild(line);
+    log_element.scrollTop = log_element.scrollHeight;
+}
+
+/**
+ * The harnesses format their PASS lines with `%c` and a CSS string, which is console syntax and
+ * nothing else. Strip the directives and drop the style arguments that went with them.
+ *
+ * @param {any[]} args
+ * @returns {string}
+ */
+function flatten_console_args(args) {
+    if (args.length === 0) {
+        return '';
+    }
+
+    const [first, ...rest] = args;
+
+    if (typeof first !== 'string' || !first.includes('%c')) {
+        return args.map(value => (typeof value === 'string' ? value : String(value))).join(' ');
+    }
+
+    const directives = (first.match(/%c/g) ?? []).length;
+
+    return [first.replaceAll('%c', ''), ...rest.slice(directives)]
+        .map(value => (typeof value === 'string' ? value : String(value)))
+        .join(' ');
+}
+
+/**
+ * Run `body` with the console mirrored into the page.
+ *
+ * @param {function(): (void|Promise<void>)} body
+ * @returns {Promise<void>}
+ */
+async function with_mirrored_console(body) {
+    const original = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+        table: console.table,
+    };
+
+    console.log = (...args) => {
+        original.log(...args);
+
+        const text = flatten_console_args(args);
+
+        append(text, /\bPASS\b/.test(text) ? 'pass' : '');
+    };
+
+    console.warn = (...args) => {
+        original.warn(...args);
+        append(flatten_console_args(args), 'warn');
+    };
+
+    console.error = (...args) => {
+        original.error(...args);
+        append(flatten_console_args(args), 'fail');
+    };
+
+    console.table = rows => {
+        original.table(rows);
+
+        if (!Array.isArray(rows)) {
+            return;
+        }
+
+        for (const row of rows) {
+            append(`  ${String(row.label).padEnd(34)} ${Number(row.duration_ms).toFixed(4)} ms`, 'note');
+        }
+    };
+
+    try {
+        await body();
+    } finally {
+        Object.assign(console, original);
+    }
+}
+
+/**
+ * Wait until the device has finished the work that was submitted, and until the readback promises
+ * chained off it have had a chance to resolve and report.
+ *
+ * The harnesses are fire-and-forget by design (`graph_inspect_gpu_buffer` calls back from a
+ * `mapAsync` promise), so there is nothing to await directly. `onSubmittedWorkDone` covers the
+ * device side; the turns after it are what let the mapping promises and their `.then` chains run.
+ *
+ * @param {GPUDevice} device
+ * @returns {Promise<void>}
+ */
+async function drain(device) {
+    await device.queue.onSubmittedWorkDone();
+
+    for (let i = 0; i < 8; i++) {
+        await new Promise(resolve => setTimeout(resolve, 0));
+    }
+}
+
+/**
+ * @param {boolean} enabled
+ */
+function set_enabled(enabled) {
+    for (const button of buttons) {
+        button.disabled = !enabled;
+    }
+}
+
+/**
+ * @param {string} text
+ * @param {string} [kind]
+ */
+function set_status(text, kind = '') {
+    status_element.textContent = text;
+    status_element.className = kind;
+}
+
+/**
+ * @returns {Promise<{graphics: GraphicsContext, device: GPUDevice, adapter: GPUAdapter}>}
+ */
+async function obtain_context() {
+    if (context !== undefined) {
+        return context;
+    }
+
+    set_status('acquiring a device…');
+
+    context = await bvh_repro_device();
+
+    device_element.innerHTML = '';
+
+    for (const { label, value } of describe_device(context.adapter, context.device)) {
+        const row = document.createElement('div');
+
+        const name = document.createElement('span');
+        name.className = 'key';
+        name.textContent = label;
+
+        const text = document.createElement('span');
+        text.textContent = value;
+
+        row.append(name, text);
+        device_element.appendChild(row);
+    }
+
+    // An uncaptured validation error is the single most useful thing this page can surface: the
+    // harnesses check bytes, and a shader that failed to create says nothing about bytes at all.
+    context.device.addEventListener('uncapturederror', event => {
+        append(`[device] ${event.error.constructor.name}: ${event.error.message}`, 'fail');
+    });
+
+    context.device.lost.then(info => {
+        append(`[device] LOST (${info.reason}): ${info.message}`, 'fail');
+        set_status('device lost', 'fail');
+    });
+
+    return context;
+}
+
+const RUNS = {
+    sort: {
+        title: 'radix sort',
+        run: graphics => verify_radix_sort(graphics),
+    },
+    bvh: {
+        title: 'GPU BVH build',
+        run: graphics => verify_gpu_bvh_build(graphics),
+    },
+    tlas: {
+        title: 'TLAS end to end',
+        run: graphics => verify_gpu_tlas_build(graphics),
+    },
+};
+
+/**
+ * @param {string} name
+ */
+async function run(name) {
+    set_enabled(false);
+
+    try {
+        const { graphics, device } = await obtain_context();
+
+        const names = name === 'all' ? Object.keys(RUNS) : [name];
+
+        for (const key of names) {
+            const { title, run: body } = RUNS[key];
+
+            append('', '');
+            append(`── ${title} ──`, 'note');
+
+            set_status(`running ${title}…`);
+
+            const started = performance.now();
+
+            await with_mirrored_console(async () => {
+                await body(graphics);
+                await drain(device);
+            });
+
+            append(`   ${title} finished in ${(performance.now() - started).toFixed(0)} ms (wall clock)`, 'note');
+        }
+
+        set_status('done — read the log for PASS/FAIL', 'pass');
+    } catch (error) {
+        append(String(error?.stack ?? error), 'fail');
+        set_status('failed to run — see the log', 'fail');
+    } finally {
+        set_enabled(true);
+    }
+}
+
+for (const button of buttons) {
+    button.addEventListener('click', () => run(button.dataset.run));
+}
+
+document.getElementById('clear').addEventListener('click', () => {
+    log_element.innerHTML = '';
+    set_status('');
+});
+
+set_status('ready — pick a check');

package/src/shade/playground/load_default_environment.d.ts

@@ -1,6 +1,15 @@
 /**
+ * Image-based lighting for a playground scene, if the asset is there.
+ *
+ * The map is optional by design: `test_assets/` is gitignored, so a fresh checkout has none, and a
+ * scene still renders by whatever direct light it carries. A miss is therefore a warning rather
+ * than a throw — and a *handled* one, so a caller that ignores the result is not sitting on an
+ * unhandled rejection. The promise comes back for callers that want to wait, or to repaint once
+ * the sky lands.
  *
  * @param {Scene} scene
+ * @param {string} [url] an octahedral `.hdr`
+ * @returns {Promise<boolean>} whether the environment was applied
  */
-export function load_default_environment(scene: Scene): void;
+export function load_default_environment(scene: Scene, url?: string): Promise<boolean>;
 //# sourceMappingURL=load_default_environment.d.ts.map

package/src/shade/playground/load_default_environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_default_environment.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/load_default_environment.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,6DAaC"}
+{"version":3,"file":"load_default_environment.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/load_default_environment.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;GAYG;AACH,6DAHW,MAAM,GACJ,QAAQ,OAAO,CAAC,CAiB5B"}

package/src/shade/playground/load_default_environment.js

@@ -1,20 +1,44 @@
-import { load_environment_map, ProjectionMappingType } from "../renderer/light/environment/rgbe/load_environment_map.js";
-
-/**
- *
- * @param {Scene} scene
- */
-export function load_default_environment(scene) {
-    const env_map = "environments/octahedral/venice_sunset_2k.hdr";
-    // const env_map = "environments/octahedral/moonless_golf_4k.hdr";
-    // const env_map = "environments/octahedral/rustig_koppie_puresky_2k.hdr";
-    // const env_map = "environments/test4_16.hdr";
-    load_environment_map(env_map, ProjectionMappingType.Octahedral).then(texture => {
-
-        scene.lights.environment = texture;
-
-        // renderer.indicate_view_change();
-
-    });
-
-}
+import { load_environment_map, ProjectionMappingType } from "../renderer/light/environment/rgbe/load_environment_map.js";
+
+/**
+ * The sky a playground page lights itself with when it has none of its own.
+ *
+ * Root-relative, and under `test_assets/`. It used to be page-relative (`environments/…`), which
+ * the browser resolves against the *page's* directory — `/src/shade/playground/<page>/` under the
+ * dev server — so it only ever found the file for a page served from the server root, and 404'd for
+ * every page that actually exists. `test_assets/README.md` has how the file gets there; the sibling
+ * asset repo's `environments/octahedral/` holds several others if a different sky is wanted.
+ *
+ * @type {string}
+ */
+const DEFAULT_ENVIRONMENT_URL = '/test_assets/environments/octahedral/rustig_koppie_puresky_2k.hdr';
+
+/**
+ * Image-based lighting for a playground scene, if the asset is there.
+ *
+ * The map is optional by design: `test_assets/` is gitignored, so a fresh checkout has none, and a
+ * scene still renders by whatever direct light it carries. A miss is therefore a warning rather
+ * than a throw — and a *handled* one, so a caller that ignores the result is not sitting on an
+ * unhandled rejection. The promise comes back for callers that want to wait, or to repaint once
+ * the sky lands.
+ *
+ * @param {Scene} scene
+ * @param {string} [url] an octahedral `.hdr`
+ * @returns {Promise<boolean>} whether the environment was applied
+ */
+export function load_default_environment(scene, url = DEFAULT_ENVIRONMENT_URL) {
+
+    return load_environment_map(url, ProjectionMappingType.Octahedral)
+        .then(texture => {
+
+            scene.lights.environment = texture;
+
+            return true;
+        })
+        .catch(error => {
+
+            console.warn(`no environment map at ${url} — the scene is lit by its own lights alone`, error);
+
+            return false;
+        });
+}

package/src/shade/playground/make_playground_asset_manager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The smallest {@link AssetManager} a glTF load needs.
+ *
+ * `load_gltf` reaches every byte through the asset framework rather than through `fetch` — which is
+ * what makes a texture two models share cost one download and one decode — so it needs a manager,
+ * and a manager only serves the types something has registered a loader for. `TinyGltf` asks for
+ * exactly two: `ArrayBuffer` for the container and its `.bin` buffers, `ImageBitmap` for textures.
+ *
+ * A playground page is not an `Engine`, which is where a fully-populated manager normally comes
+ * from, so this is the two-loader subset that gets a model on screen and nothing else.
+ *
+ * @returns {Promise<AssetManager>}
+ */
+export function make_playground_asset_manager(): Promise<AssetManager<any>>;
+import { AssetManager } from "../../engine/asset/AssetManager.js";
+//# sourceMappingURL=make_playground_asset_manager.d.ts.map

package/src/shade/playground/make_playground_asset_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make_playground_asset_manager.d.ts","sourceRoot":"","sources":["../../../../src/shade/playground/make_playground_asset_manager.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,iDAFa,0BAAqB,CAejC;6BA/B4B,oCAAoC"}

package/src/shade/playground/make_playground_asset_manager.js

@@ -0,0 +1,33 @@
+import ConcurrentExecutor from "../../core/process/executor/ConcurrentExecutor.js";
+import { AssetManager } from "../../engine/asset/AssetManager.js";
+import { GameAssetType } from "../../engine/asset/GameAssetType.js";
+import { ArrayBufferLoader } from "../../engine/asset/loaders/ArrayBufferLoader.js";
+import { ImageBitmapAssetLoader } from "../../engine/asset/loaders/image/ImageBitmapAssetLoader.js";
+
+/**
+ * The smallest {@link AssetManager} a glTF load needs.
+ *
+ * `load_gltf` reaches every byte through the asset framework rather than through `fetch` — which is
+ * what makes a texture two models share cost one download and one decode — so it needs a manager,
+ * and a manager only serves the types something has registered a loader for. `TinyGltf` asks for
+ * exactly two: `ArrayBuffer` for the container and its `.bin` buffers, `ImageBitmap` for textures.
+ *
+ * A playground page is not an `Engine`, which is where a fully-populated manager normally comes
+ * from, so this is the two-loader subset that gets a model on screen and nothing else.
+ *
+ * @returns {Promise<AssetManager>}
+ */
+export async function make_playground_asset_manager() {
+
+    const manager = new AssetManager({
+        context: {},
+        executor: new ConcurrentExecutor(),
+    });
+
+    await manager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
+    await manager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
+
+    manager.startup();
+
+    return manager;
+}

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

@@ -0,0 +1,126 @@
+# skinned BLAS refit — prototype
+
+A dancing character under the path tracer. This is the browser tier for the per-frame BLAS refit
+(`GPU_BVH_BUILD_PLAN.md` §5.2, phase 3a): the one tier that runs the shaders on a real device.
+
+```bash
+npm run dev
+```
+
+then open `/src/shade/playground/skinned_blas_refit/index.html`.
+
+Add `?count=N` for N dancers, up to 64. Each is a clone with a vertex region and a BLAS of its own,
+refit every frame — so more of them is more refits, not a bigger one.
+
+## What it is for
+
+A skinned mesh renders against a per-instance clone of its geometry whose vertices are deformed
+every frame. The rasterizer reads those vertices directly. A ray does not: it walks the clone's
+BLAS. Without a refit that tree keeps the bind pose's boxes, and the character is traced as the
+shape she was standing in when the scene loaded.
+
+The page puts both readings of the same geometry in front of you. Toggle the tracer while she
+dances:
+
+- **working** — the two silhouettes are the same silhouette, and toggling changes the lighting and
+  nothing else.
+- **stale** — the traced figure stands in bind pose while the rasterized one moves, and the floor
+  carries a shadow cast by a body that is not there.
+
+Freeze the pose to let the accumulator settle into a clean image; it resets on every frame the
+animation advances.
+
+## The numeric version
+
+Looking at it is not always possible — a browser stops calling `requestAnimationFrame` for a page
+it is not compositing, so a hidden tab renders no frames to look at. `verify()` in the console
+answers a sharper form of the same question without needing to be watched:
+
+```js
+await verify()
+```
+
+It drives frames by hand and compares two **independent** GPU computations of one quantity:
+
+- `shader_meshlet_bounds_reduce` merges every deformed vertex into the clone's geometry-metadata
+  bounding box. It exists for the rasterizer's culling and knows nothing about trees.
+- `record_blas_refit` takes each leaf triangle's box and climbs the tree, so the root node ends up
+  bounding every triangle.
+
+Same vertices, same frame, no shared code. `min` and `max` are exact in floating point, so the two
+should agree to the bit; a stale BLAS cannot make them, because the metadata box tracks the pose
+while the root holds the bind pose.
+
+It takes two samples a third of a second apart. Agreement at each is one half of the answer; the
+box having *moved* between them is the other, and it is what catches a refit that runs but reads
+the source's rest-pose vertices — those boxes would agree at every sample and never move.
+
+Then it reads the clone's whole node region back and holds every internal node against its own two
+children. The root agreeing says the climb reached the top with the right answer; it says nothing
+about the nodes underneath, and traversal descends through *those* — a subtree whose box is too
+small is a hole rays fall through however right the root is. The property the climb establishes is
+local and exact, so this is bit equality rather than a tolerance.
+
+Measured on an NVIDIA Lovelace device: root box bit-identical to the metadata box at every sample,
+moving 0.39–0.80 of its own span between poses, all 28 105 internal nodes exactly their children's
+union, and each clone at its own arena address on a uniform stride.
+
+## Assets
+
+`/test_assets/Michelle.glb`, which is gitignored and unpublished — see `test_assets/README.md`.
+
+## What the floor disagreement turned out to be
+
+For a while the two images disagreed about where the floor ends: a smooth band along its far edge
+that the rasterizer drew and the tracer did not, several thousand pixels at an ordinary camera and
+growing as the camera approached the edge. It read like a hole in a tree, and it was not one.
+
+The slab was placed by writing `Node3D.transform_global`, which is **derived** — the doc comment on
+it says so. Its two consumers take placement from opposite ends: `Mesh.updateBoundsBasic` reads
+`transform_global` and publishes the result as the mesh's `meshes` row, and the GPU's `transforms`
+row carries the node's *local* TRS for the hierarchy pass to compose `node.global` from. Writing
+only the first left the second at identity, 0.208 m away:
+
+- the rasterizer multiplied positions by `node.global` and drew the slab at the geometry's own
+  origin, its far edge ten rows higher up the screen than the floor actually ends;
+- the tracer tested each ray against the *translated* published box before traversing the
+  *untranslated* geometry, so rays that would have struck the slab near its far edge were turned
+  away by a box that was not around it.
+
+Neither renderer was wrong about the data it was given. Padding the published box shrank the band
+because it widened the interval the TLAS test allows — not because anything was tangent, which is
+why a few per cent of pad did what a rounding-scale slack could not.
+
+The invariant is in `add_floor.spec.js` and needs no device: published bounds must survive
+`updateMatrices`, because that is the walk which recomputes `transform_global` from the local
+transform. `chunk_ray_query_nearest.spec.js` holds the traversal itself against closed-form slab
+arithmetic in the emulator, including the case where the instance box and the node transform
+disagree.
+
+## The quieter version of the same bug: `?count=N`
+
+The dancers were placed the same way — by writing `transform_global` — and stacked at the origin
+rather than spreading over a grid. Both renderers agreed about it, so there was no picture to look
+at; the only symptom was that the characters did not go where they were put.
+
+They also could not have been fixed by copying the floor's fix, because a skinned mesh's own node
+is not its placement point at all. A skinned vertex lands at
+
+```
+mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
+```
+
+— `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the rasterizer
+re-applies `mesh.global`, so the mesh node's transform **cancels exactly**, and
+`compute_skin_world_bounds` composes the published box out of joints without reading it either.
+Michelle's file makes the point structurally: her mesh node `Ch03` carries no local transform, the
+0.01 centimetre scale and the up-axis rotation sit on the root above it, and the joint root
+`mixamorig:Hips` is the mesh node's *sibling*. Nothing under `Ch03` drives a joint.
+
+`place_character` therefore hangs each character's roots under a fresh parent whose whole transform
+is the grid offset. That reaches the joints, leaves the file's own transform untouched below it, and
+— because the offset is a *local* transform — survives the walk that recomputes `transform_global`.
+
+`place_character.spec.js` holds the invariant the floor's cannot see: **published bounds must move
+by the offset the character was placed at.** Its negative control is the bug itself — writing either
+transform on the mesh node and watching the box not move.

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

@@ -0,0 +1,47 @@
+/**
+ * A floor, so the traced image has something for the character to cast onto.
+ *
+ * Shadows are the loudest reading of a stale BLAS: a body in the wrong pose still shades roughly
+ * like a body, but the shadow it throws is unmistakably a different shape from the one standing
+ * over it.
+ *
+ * ## Where it is placed, and why that is the whole of it
+ *
+ * The slab is placed by its **local** transform. `Node3D.transform_global` is derived — the doc
+ * comment on it says so — and the two consumers of a mesh's placement take it from opposite ends:
+ *
+ * - `Mesh.updateBoundsBasic` reads `transform_global`, and its result is the box published to the
+ *   `meshes` table, which is the TLAS leaf the path tracer tests a ray against before it reaches
+ *   any triangle;
+ * - the GPU's `transforms` row carries the node's local TRS, and the hierarchy pass composes
+ *   `node.global` from it — which is the matrix *both* the rasterizer's vertex stage and the ray
+ *   query's geometry-space transform use.
+ *
+ * Setting `transform_global` and nothing else satisfies the first and leaves the second at
+ * identity, which is exactly what this function used to do. The result is a mesh whose published
+ * box is around one place and whose geometry is drawn in another, 0.208 m apart here:
+ *
+ * - the **rasterizer** drew the slab at the geometry's own origin, its far edge ten rows higher up
+ *   the screen than the floor actually ends;
+ * - the **path tracer** tested each ray against the translated box first and only then traversed
+ *   the untranslated geometry, so rays that would have struck the slab near its far edge were
+ *   turned away by a box that was not around it — a smooth band of floor the rasterizer drew and
+ *   the tracer did not, growing as the camera approached the edge.
+ *
+ * Neither renderer was wrong about the data it was given; the two halves of the record disagreed.
+ * Padding the published box (the old `?inflate=1` handle) shrank the band because it widened the
+ * interval the TLAS test allows — which is why a 5% pad did what a 1e-5 rounding slack could not,
+ * and it was never evidence of tangency.
+ *
+ * The invariant that catches this without a GPU or a picture: a mesh's published bounds must
+ * survive `updateMatrices`, because that is the walk which recomputes `transform_global` from the
+ * local transform. `add_floor.spec.js` holds it to that.
+ *
+ * @param {Scene} scene
+ * @param {number} extent width of the slab
+ * @param {number} top world height its upper face sits at
+ * @returns {Mesh}
+ */
+export function add_floor(scene: Scene, extent: number, top: number): Mesh;
+import { Mesh } from "../../renderer/scene/Mesh.js";
+//# sourceMappingURL=add_floor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"add_floor.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/add_floor.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,gDAJW,MAAM,OACN,MAAM,GACJ,IAAI,CAwBhB;qBApEoB,8BAA8B"}

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

@@ -0,0 +1,71 @@
+import { BoxGeometry } from "../../renderer/geometry/BoxGeometry.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../../renderer/scene/Mesh.js";
+
+/**
+ * A floor, so the traced image has something for the character to cast onto.
+ *
+ * Shadows are the loudest reading of a stale BLAS: a body in the wrong pose still shades roughly
+ * like a body, but the shadow it throws is unmistakably a different shape from the one standing
+ * over it.
+ *
+ * ## Where it is placed, and why that is the whole of it
+ *
+ * The slab is placed by its **local** transform. `Node3D.transform_global` is derived — the doc
+ * comment on it says so — and the two consumers of a mesh's placement take it from opposite ends:
+ *
+ * - `Mesh.updateBoundsBasic` reads `transform_global`, and its result is the box published to the
+ *   `meshes` table, which is the TLAS leaf the path tracer tests a ray against before it reaches
+ *   any triangle;
+ * - the GPU's `transforms` row carries the node's local TRS, and the hierarchy pass composes
+ *   `node.global` from it — which is the matrix *both* the rasterizer's vertex stage and the ray
+ *   query's geometry-space transform use.
+ *
+ * Setting `transform_global` and nothing else satisfies the first and leaves the second at
+ * identity, which is exactly what this function used to do. The result is a mesh whose published
+ * box is around one place and whose geometry is drawn in another, 0.208 m apart here:
+ *
+ * - the **rasterizer** drew the slab at the geometry's own origin, its far edge ten rows higher up
+ *   the screen than the floor actually ends;
+ * - the **path tracer** tested each ray against the translated box first and only then traversed
+ *   the untranslated geometry, so rays that would have struck the slab near its far edge were
+ *   turned away by a box that was not around it — a smooth band of floor the rasterizer drew and
+ *   the tracer did not, growing as the camera approached the edge.
+ *
+ * Neither renderer was wrong about the data it was given; the two halves of the record disagreed.
+ * Padding the published box (the old `?inflate=1` handle) shrank the band because it widened the
+ * interval the TLAS test allows — which is why a 5% pad did what a 1e-5 rounding slack could not,
+ * and it was never evidence of tangency.
+ *
+ * The invariant that catches this without a GPU or a picture: a mesh's published bounds must
+ * survive `updateMatrices`, because that is the walk which recomputes `transform_global` from the
+ * local transform. `add_floor.spec.js` holds it to that.
+ *
+ * @param {Scene} scene
+ * @param {number} extent width of the slab
+ * @param {number} top world height its upper face sits at
+ * @returns {Mesh}
+ */
+export function add_floor(scene, extent, top) {
+    const thickness = extent * 0.02;
+
+    const floor = new Mesh();
+
+    floor.geometry = new BoxGeometry(extent, thickness, extent);
+    floor.material = new StandardShadeMaterial();
+
+    // `Transform64` keeps its matrix by hand: setting a component leaves the matrix holding what it
+    // held before, so the write is only real after `updateMatrix`.
+    floor.transform_local.setTranslation(0, top - thickness * 0.5, 0);
+    floor.transform_local.updateMatrix();
+
+    // Derive `transform_global` from the local transform, and the world bounds from that. Nothing
+    // else will: the scene's pre-order walk updates bounds for nodes it visits as part of a
+    // hierarchy, and a mesh added on its own is never visited that way — so the row it seeds the
+    // `meshes` table with would stay the default, which is a zero-sized box at the origin.
+    floor.updateMatrices();
+
+    scene.add(floor);
+
+    return floor;
+}