@woosh/meep-engine 3.43.0 → 3.45.0

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

@@ -1,509 +1,502 @@
-import Vector3 from "../../../core/geom/Vector3.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-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 {
-    GLTFSceneBundleAssetLoader
-} from "../../../engine/asset/loaders/GLTFSceneBundleAssetLoader.js";
-import { ImageBitmapAssetLoader } from "../../../engine/asset/loaders/image/ImageBitmapAssetLoader.js";
-import { load_model_scene_bundle } from "../../../engine/asset/load_model_scene_bundle.js";
-import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
-import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
-import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.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 { make_sunlight } from "../../renderer/light/make_sunlight.js";
-import { place_light } from "../../renderer/light/place_light.js";
-import { Renderer } from "../../renderer/Renderer.js";
-import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
-import { Scene } from "../../renderer/scene/Scene.js";
-import { load_default_environment } from "../load_default_environment.js";
-import { grid_position, place_character } from "../skinned_blas_refit/place_character.js";
-
-/**
- * A skinned character, loaded the way the game loads one, with the pieces that could be making soup
- * put on switches.
- *
- * ## Why this page exists next to `skinned_blas_refit`
- *
- * That page renders the same character and answers a sharp question about the BLAS — does the tree
- * follow the mesh — with `verify()`. It answers that question *numerically*, by holding the tree's
- * root box against the bounds chain's box over the same deformed vertices, and both of those are
- * derived from the clone's vertex region. **Vertices that are wrong in the same way agree with each
- * other perfectly.** So a refit can be correct, `verify()` green, every internal node exactly its
- * children's union — and the picture still soup, because the thing the tree faithfully bounds is
- * itself wrong.
- *
- * This page is that other question, and it is built to bisect it rather than to look good:
- *
- * - **`?skin=off`** — no skin registered. A skinned mesh entity still gets a vertex clone (see
- *   {@link GPUMeshSkinningContext#obtain_clone}), but nothing ever deforms it, so what is drawn is
- *   the memcpy of the source: the rest pose, under the mesh entity's row — which the prefab put
- *   into the skin's own frame. Soup here is the geometry upload — the meshlet copy or its address
- *   patch — and has nothing to do with skinning.
- * - **`?skin=bind`** — the skin registered, no clip. The skinning pass runs every frame over a pose
- *   that never changes, and the answer it should write is one the CPU knows exactly. `diagnose()`
- *   in the console reads the clone's vertices back and says which of them are wrong and in what
- *   pattern — see {@link verify_clone_vertices}. Soup here is the skinning machinery.
- * - **`?skin=animated`** — the dance, as `skinned_blas_refit` runs it. Soup only here is the pose:
- *   the joint matrices, their range, or the order the skin's joints were resolved in.
- *
- * ## What the bisect found, and what was done
- *
- * `chunk_skin_blend_mesh_local` folds `inverse(mesh.transform_global)` into each joint matrix and
- * converts the product to a dual quaternion, which can only carry a rigid motion. Michelle's
- * positions and inverse-bind matrices are authored in the already-scaled space, so
- * `joint.global × inverse_bind` is the *identity* and the fold was a bare 100×.
- * `dual_quat_from_m4` reads `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms of `1 + 100·(…)`, clamps
- * whichever go negative and normalizes the rest, so the rotation it extracted was wrong — and wrong
- * differently per joint, which is what tore the mesh apart. `?skin=bind` was the right character at
- * 1/100 size (one shared matrix, one shared error) and `?skin=animated` was soup.
- *
- * The frame is now the engine's rather than the asset's: compiling a model puts each skinned mesh
- * on its skin's own bind transform, so the fold is the identity at bind and a rigid displacement
- * under a clip, for every shape a glTF file arrives in. See
- * `renderer/animation/SKINNING_FRAME_PLAN.md`.
- *
- * All of which was established without a device — `__soup_blend_probe.spec.js` runs the shader's own
- * blend over this character's own matrices, and the emulator tier in
- * `chunk_skin_blend_mesh_local.spec.js` runs the real WGSL over both shapes. This page is where that
- * is confirmed against pixels, which by then is a formality.
- *
- * ## Why through the asset framework
- *
- * `skinned_blas_refit` calls `load_gltf` directly and parses the file once per character.
- * {@link GLTFSceneBundleAssetLoader} is what the game and the editor register, and it hands **the
- * same bundle** to every caller — so a second character is not a second parse, it is
- * `prefab_instantiate` over the prefab compiled from it once: its own entities, its own skins bound
- * to those entities' joints, its own clips retargeted onto them, sharing the geometry and the
- * inverse-bind matrices. That is a
- * materially different path into the renderer, and running the repro on it means a fix found here
- * is a fix for the engine rather than for one prototype page.
- *
- * Runs under the dev server (`npm run dev`), which serves `test_assets/`.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
- * `test_assets/README.md`.
- *
- * @type {string}
- */
-const CHARACTER_URL = '/test_assets/Michelle.glb';
-
-/**
- * How far apart characters stand, in character heights.
- *
- * @type {number}
- */
-const SPACING = 1.1;
-
-/**
- * How the skin is driven. The page's whole point is that these are three different questions.
- *
- * @enum {string}
- */
-const SkinMode = {
-    /** no skin registered — the clone is never deformed */
-    Off: 'off',
-    /** skin registered, no clip — the pose the CPU can predict */
-    Bind: 'bind',
-    /** skin registered, the file's dance bound and playing */
-    Animated: 'animated',
-};
-
-/**
- * The manager a model load needs, registered the way the game's graphics profile registers it.
- *
- * Not {@link make_playground_asset_manager}: that one is the two-loader subset `load_gltf` needs
- * when a page calls it by hand. Going through {@link load_model_scene_bundle} means the *model* is
- * an asset too, which is the thing this page wants to be on.
- *
- * @returns {Promise<AssetManager>}
- */
-async function make_asset_manager() {
-    const manager = new AssetManager({
-        context: {},
-        executor: new ConcurrentExecutor(),
-    });
-
-    // One instance for both glTF types, as `addModelLoaders` does — the loader holds no per-type
-    // state, and the two types are `.glb` and `.gltf` telling themselves apart.
-    const models = new GLTFSceneBundleAssetLoader();
-
-    await manager.registerLoader(GameAssetType.ModelGLTF, models);
-    await manager.registerLoader(GameAssetType.ModelGLTF_JSON, models);
-
-    // the container's `.bin` buffers, and its images — `load_gltf` asks for both back through the
-    // manager rather than fetching them itself
-    await manager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
-    await manager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
-
-    manager.startup();
-
-    return manager;
-}
-
-/**
- * Every skinned mesh entity an instance's skins deform.
- *
- * Off the skins rather than by walking the entities: a skin already lists exactly the meshes that
- * bind to it, which is what `register_skin` uses.
- *
- * @param {PrefabInstance} instance
- * @returns {number[]}
- */
-function skinned_meshes_of(instance) {
-    const meshes = new Set();
-
-    for (const skin of instance.skins) {
-        for (const mesh of skin.meshes) {
-            meshes.add(mesh);
-        }
-    }
-
-    return [...meshes];
-}
-
-/**
- * The world-space box the renderer culls and traces this mesh by — the `meshes` table row, which
- * the skinning pass's bounds-refresh chain rewrites every frame from the vertices it just moved.
- *
- * Not the source geometry's box under the mesh entity's transform: that is the rest pose, and
- * the dance has moved on from it.
- *
- * @param {GPUSceneContext} scene_context
- * @param {number} entity a mesh entity
- * @returns {Promise<{low: Vector3, high: Vector3}>}
- */
-async function world_bounds_of(scene_context, entity) {
-    const row = row_of_entity(entity);
-
-    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
-
-    const box = record.bounding_box;
-
-    return {
-        low: new Vector3(box[0], box[1], box[2]),
-        high: new Vector3(box[3], box[4], box[5]),
-    };
-}
-
-/**
- * Stand the page up.
- *
- * @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;
-    }
-
-    // ---- what the url asks for ------------------------------------------------------------------
-
-    const parameters = new URLSearchParams(location.search);
-
-    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
-
-    const skin_mode = Object.values(SkinMode).includes(parameters.get('skin'))
-        ? parameters.get('skin')
-        : SkinMode.Animated;
-
-    const tracing = parameters.get('trace') === '1';
-
-    element('character_count').value = String(count);
-    element('skin_mode').value = skin_mode;
-    element('path_tracing').checked = tracing;
-
-    // A Scene has no teardown, so changing any of these reloads the page rather than emptying one
-    // in place. Every switch is in the url for the same reason a repro is a url: it can be sent.
-    function reload_with(changes) {
-        const next = new URLSearchParams(location.search);
-
-        for (const [key, value] of Object.entries(changes)) {
-            next.set(key, value);
-        }
-
-        location.search = next.toString();
-    }
-
-    element('respawn').addEventListener('click', () => reload_with({
-        count: element('character_count').value,
-        skin: element('skin_mode').value,
-    }));
-
-    element('skin_mode').addEventListener('change', () => reload_with({
-        skin: element('skin_mode').value,
-    }));
-
-    // ---- the renderer ---------------------------------------------------------------------------
-
-    const renderer = new Renderer();
-
-    set_status('acquiring a device…');
-
-    await renderer.initialize({ context });
-
-    if (!renderer.graphics.device.features.has('subgroups')) {
-        set_status('device has no `subgroups`, which this engine takes as a baseline', 'warn');
-    }
-
-    const camera = new PerspectiveCamera();
-
-    camera.near = 0.01;
-    camera.far = 200;
-    camera.fov = 50 * DEG_TO_RAD;
-    camera.aspect = renderer.aspect_ratio;
-
-    const scene = new Scene();
-
-    // the characters are entities, and the scene's rows are theirs
-    const dataset = new EntityComponentDataset();
-
-    scene.dataset = dataset;
-
-    // document.body rather than the canvas: the controller starts a keyboard device, and only a
-    // focusable element receives key events — body carries tabindex for exactly that.
-    const controller = new OrbitalCameraController(camera, document.body);
-
-    // Rasterized by default. It is the simpler of the two readings — it reads the deformed vertices
-    // directly, with no tree in the way — so it is the one to establish the answer on first.
-    renderer.feature_path_tracing_enabled = tracing;
-    renderer.feature_taa_enabled = false;
-
-    element('path_tracing').addEventListener('change', event => {
-        renderer.feature_path_tracing_enabled = event.target.checked;
-        renderer.indicate_view_change();
-    });
-
-    globalThis.renderer = renderer;
-    globalThis.scene = scene;
-    globalThis.camera = camera;
-    globalThis.controller = controller;
-
-    // ---- the cast -------------------------------------------------------------------------------
-
-    set_status(`loading ${CHARACTER_URL} …`);
-
-    const scene_context = renderer.scenes.obtain(scene);
-
-    /** @type {number[]} the skinned mesh entities */
-    const characters = [];
-
-    try {
-        const asset_manager = await make_asset_manager();
-
-        // One load and one compile, whatever the count: the asset hands out the model itself, and
-        // a placement is `prefab_instantiate` over the prefab compiled from it.
-        const bundle = await load_model_scene_bundle(asset_manager, CHARACTER_URL);
-
-        const prefab = prefab_compile(bundle);
-
-        const animations = scene_context.animation_manager;
-
-        for (let i = 0; i < count; i++) {
-            const { x, z } = grid_position(i, count, SPACING);
-
-            const { instance } = place_character(scene_context, dataset, prefab, x, z, {
-                register_animation: skin_mode !== SkinMode.Off,
-            });
-
-            const meshes = skinned_meshes_of(instance);
-
-            if (meshes.length === 0) {
-                throw new Error(`${CHARACTER_URL} has no skinned mesh`);
-            }
-
-            if (skin_mode === SkinMode.Animated) {
-                // One clip, looping, at full weight. The pose accumulator sums every *bound* clip
-                // whatever its weight, so binding the T-pose alongside the dance would blend the
-                // two — only what should play is registered.
-                const clip = instance.clips.find(candidate => /samba|dance/i.test(candidate.name ?? ''))
-                    ?? instance.clips[0];
-
-                if (clip !== undefined) {
-                    const clip_id = animations.register_clip(clip);
-
-                    animations.set_playback_weight(clip_id, 1);
-                    animations.set_flags(clip_id, AnimationClipFlags.Loop);
-                    animations.start(clip_id);
-                }
-            }
-
-            characters.push(...meshes);
-        }
-    } catch (error) {
-        set_status(
-            `could not load the character (${error.message}). Put it under test_assets/ — `
-            + `see test_assets/README.md.`,
-            'fail'
-        );
-        console.error(error);
-        return;
-    }
-
-    if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
-        // a glTF character carries no light of its own
-        place_light(scene, make_sunlight({ intensity: 6 }));
-    }
-
-    // ---- frames enough for the box to be worth framing on ----------------------------------------
-
-    set_status('first frames — uploading clones and their trees …');
-
-    for (let i = 0; i < 8; i++) {
-        renderer.render(camera, scene, 1 / 60);
-
-        await renderer.graphics.device.queue.onSubmittedWorkDone();
-    }
-
-    let low = null;
-    let high = null;
-
-    for (const character of characters) {
-        const bounds = await world_bounds_of(scene_context, character);
-
-        low = low === null ? bounds.low : new Vector3(
-            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
-        );
-
-        high = high === null ? bounds.high : new Vector3(
-            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
-        );
-    }
-
-    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
-
-    const radius = Math.hypot(span.x, span.y, span.z) * 0.5;
-
-    camera_frame_sphere(
-        controller,
-        radius,
-        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
-    );
-
-    controller.movement_speed_scale = radius * 0.2;
-
-    camera.near = radius * 0.01;
-    camera.far = radius * 400;
-
-    console.log(
-        `published box: low=(${low.x.toFixed(4)}, ${low.y.toFixed(4)}, ${low.z.toFixed(4)}) `
-        + `high=(${high.x.toFixed(4)}, ${high.y.toFixed(4)}, ${high.z.toFixed(4)}) — `
-        + `span ${span.x.toFixed(4)} × ${span.y.toFixed(4)} × ${span.z.toFixed(4)} m`
-    );
-
-    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();
-
-    globalThis.characters = characters;
-
-    // ---- the console half ------------------------------------------------------------------------
-
-    let animating = skin_mode === SkinMode.Animated;
-
-    /**
-     * The clone's deformed vertices, against the answer the CPU knows for the bind pose.
-     *
-     * Only meaningful under `?skin=bind`: with a clip playing there is no CPU-side answer to compare
-     * against, and with no skin registered there is nothing deforming the clone. It runs in the
-     * other two modes anyway rather than refusing — under `?skin=off` a pass says the clone's copy
-     * and address patch are right, which is worth knowing on its own.
-     */
-    globalThis.diagnose = async () => {
-        const { verify_clone_vertices } = await import('./verify_clone_vertices.js');
-
-        const was_animating = animating;
-
-        animating = false;
-
-        try {
-            return await verify_clone_vertices({ renderer, scene, entity: characters[0] });
-        } finally {
-            animating = was_animating;
-        }
-    };
-
-    set_status(
-        `loaded — ${count} × ${CHARACTER_URL}, skin=${skin_mode}. `
-        + `\`await diagnose()\` in the console.`,
-        'pass'
-    );
-
-    renderer.indicate_view_change();
-
-    // ---- frame loop --------------------------------------------------------------------------
-
-    element('animation').disabled = skin_mode !== SkinMode.Animated;
-
-    if (skin_mode !== SkinMode.Animated) {
-        // there is no clip to freeze; saying so beats a live-looking button that does nothing
-        element('animation').textContent = 'No clip playing';
-    }
-
-    element('animation').addEventListener('click', () => {
-        animating = !animating;
-
-        element('animation').textContent = animating ? 'Freeze pose' : 'Resume dance';
-
-        renderer.path_tracer.clear_history = true;
-        renderer.indicate_view_change();
-    });
-
-    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();
-
-        // A frozen pose is a still scene, which is the only condition under which the tracer's
-        // accumulator converges — so time stops rather than the frame loop stopping.
-        renderer.render(camera, scene, animating ? time_delta_s : 0);
-
-        stats_element.textContent =
-            `${count} × skin=${skin_mode}`
-            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : '  ·  rasterized'}`;
-    }, FRAME_RATE_LIMIT);
-}
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+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 {
+    GLTFSceneBundleAssetLoader
+} from "../../../engine/asset/loaders/GLTFSceneBundleAssetLoader.js";
+import { ImageBitmapAssetLoader } from "../../../engine/asset/loaders/image/ImageBitmapAssetLoader.js";
+import { load_model_scene_bundle } from "../../../engine/asset/load_model_scene_bundle.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { MeshSkin } from "../../../engine/graphics/ecs/mesh-v2/MeshSkin.js";
+import { AnimationClips } from "../../../engine/graphics3/animation/AnimationClips.js";
+import { prefab_compile } from "../../../engine/graphics3/prefab/prefab_compile.js";
+import { AnimationClipFlags } from "../../renderer/animation/AnimationClipFlags.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 { make_sunlight } from "../../renderer/light/make_sunlight.js";
+import { place_light } from "../../renderer/light/place_light.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { row_of_entity } from "../../renderer/scene/rows/GPUSceneRows.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { grid_position, place_character } from "../skinned_blas_refit/place_character.js";
+
+/**
+ * A skinned character, loaded the way the game loads one, with the pieces that could be making soup
+ * put on switches.
+ *
+ * ## Why this page exists next to `skinned_blas_refit`
+ *
+ * That page renders the same character and answers a sharp question about the BLAS — does the tree
+ * follow the mesh — with `verify()`. It answers that question *numerically*, by holding the tree's
+ * root box against the bounds chain's box over the same deformed vertices, and both of those are
+ * derived from the clone's vertex region. **Vertices that are wrong in the same way agree with each
+ * other perfectly.** So a refit can be correct, `verify()` green, every internal node exactly its
+ * children's union — and the picture still soup, because the thing the tree faithfully bounds is
+ * itself wrong.
+ *
+ * This page is that other question, and it is built to bisect it rather than to look good:
+ *
+ * - **`?skin=off`** — no skin registered. A skinned mesh entity still gets a vertex clone (see
+ *   {@link GPUMeshSkinningContext#obtain_clone}), but nothing ever deforms it, so what is drawn is
+ *   the memcpy of the source: the rest pose, under the mesh entity's row — which the prefab put
+ *   into the skin's own frame. Soup here is the geometry upload — the meshlet copy or its address
+ *   patch — and has nothing to do with skinning.
+ * - **`?skin=bind`** — the skin registered, no clip. The skinning pass runs every frame over a pose
+ *   that never changes, and the answer it should write is one the CPU knows exactly. `diagnose()`
+ *   in the console reads the clone's vertices back and says which of them are wrong and in what
+ *   pattern — see {@link verify_clone_vertices}. Soup here is the skinning machinery.
+ * - **`?skin=animated`** — the dance, as `skinned_blas_refit` runs it. Soup only here is the pose:
+ *   the joint matrices, their range, or the order the skin's joints were resolved in.
+ *
+ * ## What the bisect found, and what was done
+ *
+ * `chunk_skin_blend_mesh_local` folds `inverse(mesh.transform_global)` into each joint matrix and
+ * converts the product to a dual quaternion, which can only carry a rigid motion. Michelle's
+ * positions and inverse-bind matrices are authored in the already-scaled space, so
+ * `joint.global × inverse_bind` is the *identity* and the fold was a bare 100×.
+ * `dual_quat_from_m4` reads `sqrt(max(0, 1 ± m00 ± m11 ± m22))` over terms of `1 + 100·(…)`, clamps
+ * whichever go negative and normalizes the rest, so the rotation it extracted was wrong — and wrong
+ * differently per joint, which is what tore the mesh apart. `?skin=bind` was the right character at
+ * 1/100 size (one shared matrix, one shared error) and `?skin=animated` was soup.
+ *
+ * The frame is now the engine's rather than the asset's: compiling a model puts each skinned mesh
+ * on its skin's own bind transform, so the fold is the identity at bind and a rigid displacement
+ * under a clip, for every shape a glTF file arrives in. See
+ * `renderer/animation/SKINNING_FRAME_PLAN.md`.
+ *
+ * All of which was established without a device — `__soup_blend_probe.spec.js` runs the shader's own
+ * blend over this character's own matrices, and the emulator tier in
+ * `chunk_skin_blend_mesh_local.spec.js` runs the real WGSL over both shapes. This page is where that
+ * is confirmed against pixels, which by then is a formality.
+ *
+ * ## Why through the asset framework
+ *
+ * `skinned_blas_refit` calls `load_gltf` directly and parses the file once per character.
+ * {@link GLTFSceneBundleAssetLoader} is what the game and the editor register, and it hands **the
+ * same bundle** to every caller — so a second character is not a second parse, it is
+ * `prefab_instantiate` over the prefab compiled from it once: its own entities, its own skins bound
+ * to those entities' joints, its own clips retargeted onto them, sharing the geometry and the
+ * inverse-bind matrices. That is a
+ * materially different path into the renderer, and running the repro on it means a fix found here
+ * is a fix for the engine rather than for one prototype page.
+ *
+ * Runs under the dev server (`npm run dev`), which serves `test_assets/`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Served by the dev server out of `test_assets/`, which is gitignored and unpublished. See
+ * `test_assets/README.md`.
+ *
+ * @type {string}
+ */
+const CHARACTER_URL = '/test_assets/Michelle.glb';
+
+/**
+ * How far apart characters stand, in character heights.
+ *
+ * @type {number}
+ */
+const SPACING = 1.1;
+
+/**
+ * How the skin is driven. The page's whole point is that these are three different questions.
+ *
+ * @enum {string}
+ */
+const SkinMode = {
+    /** no skin registered — the clone is never deformed */
+    Off: 'off',
+    /** skin registered, no clip — the pose the CPU can predict */
+    Bind: 'bind',
+    /** skin registered, the file's dance bound and playing */
+    Animated: 'animated',
+};
+
+/**
+ * The manager a model load needs, registered the way the game's graphics profile registers it.
+ *
+ * Not {@link make_playground_asset_manager}: that one is the two-loader subset `load_gltf` needs
+ * when a page calls it by hand. Going through {@link load_model_scene_bundle} means the *model* is
+ * an asset too, which is the thing this page wants to be on.
+ *
+ * @returns {Promise<AssetManager>}
+ */
+async function make_asset_manager() {
+    const manager = new AssetManager({
+        context: {},
+        executor: new ConcurrentExecutor(),
+    });
+
+    // One instance for both glTF types, as `addModelLoaders` does — the loader holds no per-type
+    // state, and the two types are `.glb` and `.gltf` telling themselves apart.
+    const models = new GLTFSceneBundleAssetLoader();
+
+    await manager.registerLoader(GameAssetType.ModelGLTF, models);
+    await manager.registerLoader(GameAssetType.ModelGLTF_JSON, models);
+
+    // the container's `.bin` buffers, and its images — `load_gltf` asks for both back through the
+    // manager rather than fetching them itself
+    await manager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
+    await manager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
+
+    manager.startup();
+
+    return manager;
+}
+
+/**
+ * Every mesh entity of an instance that a skin deforms: the ones carrying a `MeshSkin`, which is
+ * exactly what gets registered and bound.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {PrefabInstance} instance
+ * @returns {number[]}
+ */
+function skinned_meshes_of(dataset, instance) {
+    return Array.from(instance.mesh_entities).filter(entity => dataset.getComponent(entity, MeshSkin) !== undefined);
+}
+
+/**
+ * The world-space box the renderer culls and traces this mesh by — the `meshes` table row, which
+ * the skinning pass's bounds-refresh chain rewrites every frame from the vertices it just moved.
+ *
+ * Not the source geometry's box under the mesh entity's transform: that is the rest pose, and
+ * the dance has moved on from it.
+ *
+ * @param {GPUSceneContext} scene_context
+ * @param {number} entity a mesh entity
+ * @returns {Promise<{low: Vector3, high: Vector3}>}
+ */
+async function world_bounds_of(scene_context, entity) {
+    const row = row_of_entity(entity);
+
+    const record = await scene_context.scene_database.debug_table_read_element('meshes', row);
+
+    const box = record.bounding_box;
+
+    return {
+        low: new Vector3(box[0], box[1], box[2]),
+        high: new Vector3(box[3], box[4], box[5]),
+    };
+}
+
+/**
+ * Stand the page up.
+ *
+ * @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;
+    }
+
+    // ---- what the url asks for ------------------------------------------------------------------
+
+    const parameters = new URLSearchParams(location.search);
+
+    const count = Math.min(64, Math.max(1, Number.parseInt(parameters.get('count'), 10) || 1));
+
+    const skin_mode = Object.values(SkinMode).includes(parameters.get('skin'))
+        ? parameters.get('skin')
+        : SkinMode.Animated;
+
+    const tracing = parameters.get('trace') === '1';
+
+    element('character_count').value = String(count);
+    element('skin_mode').value = skin_mode;
+    element('path_tracing').checked = tracing;
+
+    // A Scene has no teardown, so changing any of these reloads the page rather than emptying one
+    // in place. Every switch is in the url for the same reason a repro is a url: it can be sent.
+    function reload_with(changes) {
+        const next = new URLSearchParams(location.search);
+
+        for (const [key, value] of Object.entries(changes)) {
+            next.set(key, value);
+        }
+
+        location.search = next.toString();
+    }
+
+    element('respawn').addEventListener('click', () => reload_with({
+        count: element('character_count').value,
+        skin: element('skin_mode').value,
+    }));
+
+    element('skin_mode').addEventListener('change', () => reload_with({
+        skin: element('skin_mode').value,
+    }));
+
+    // ---- the renderer ---------------------------------------------------------------------------
+
+    const renderer = new Renderer();
+
+    set_status('acquiring a device…');
+
+    await renderer.initialize({ context });
+
+    if (!renderer.graphics.device.features.has('subgroups')) {
+        set_status('device has no `subgroups`, which this engine takes as a baseline', 'warn');
+    }
+
+    const camera = new PerspectiveCamera();
+
+    camera.near = 0.01;
+    camera.far = 200;
+    camera.fov = 50 * DEG_TO_RAD;
+    camera.aspect = renderer.aspect_ratio;
+
+    const scene = new Scene();
+
+    // the characters are entities, and the scene's rows are theirs
+    const dataset = new EntityComponentDataset();
+
+    scene.dataset = dataset;
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element receives key events — body carries tabindex for exactly that.
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    // Rasterized by default. It is the simpler of the two readings — it reads the deformed vertices
+    // directly, with no tree in the way — so it is the one to establish the answer on first.
+    renderer.feature_path_tracing_enabled = tracing;
+    renderer.feature_taa_enabled = false;
+
+    element('path_tracing').addEventListener('change', event => {
+        renderer.feature_path_tracing_enabled = event.target.checked;
+        renderer.indicate_view_change();
+    });
+
+    globalThis.renderer = renderer;
+    globalThis.scene = scene;
+    globalThis.camera = camera;
+    globalThis.controller = controller;
+
+    // ---- the cast -------------------------------------------------------------------------------
+
+    set_status(`loading ${CHARACTER_URL} …`);
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    /** @type {number[]} the skinned mesh entities */
+    const characters = [];
+
+    try {
+        const asset_manager = await make_asset_manager();
+
+        // One load and one compile, whatever the count: the asset hands out the model itself, and
+        // a placement is `prefab_instantiate` over the prefab compiled from it.
+        const bundle = await load_model_scene_bundle(asset_manager, CHARACTER_URL);
+
+        const prefab = prefab_compile(bundle);
+
+        const animations = scene_context.animation_manager;
+
+        for (let i = 0; i < count; i++) {
+            const { x, z } = grid_position(i, count, SPACING);
+
+            const { root, instance } = place_character(scene_context, dataset, prefab, x, z, {
+                register_animation: skin_mode !== SkinMode.Off,
+            });
+
+            const meshes = skinned_meshes_of(dataset, instance);
+
+            if (meshes.length === 0) {
+                throw new Error(`${CHARACTER_URL} has no skinned mesh`);
+            }
+
+            if (skin_mode === SkinMode.Animated) {
+                // One clip, looping, at full weight. The pose accumulator sums every *bound* clip
+                // whatever its weight, so binding the T-pose alongside the dance would blend the
+                // two — only what should play is registered.
+                const clips = dataset.getComponent(root, AnimationClips).clips;
+                const clip = clips.find(candidate => /samba|dance/i.test(candidate.name ?? '')) ?? clips[0];
+
+                if (clip !== undefined) {
+                    const clip_id = animations.register_clip(clip);
+
+                    animations.set_playback_weight(clip_id, 1);
+                    animations.set_flags(clip_id, AnimationClipFlags.Loop);
+                    animations.start(clip_id);
+                }
+            }
+
+            characters.push(...meshes);
+        }
+    } catch (error) {
+        set_status(
+            `could not load the character (${error.message}). Put it under test_assets/ — `
+            + `see test_assets/README.md.`,
+            'fail'
+        );
+        console.error(error);
+        return;
+    }
+
+    if (!scene.lights.elements.some(light => light.isDirectionalLight)) {
+        // a glTF character carries no light of its own
+        place_light(scene, make_sunlight({ intensity: 6 }));
+    }
+
+    // ---- frames enough for the box to be worth framing on ----------------------------------------
+
+    set_status('first frames — uploading clones and their trees …');
+
+    for (let i = 0; i < 8; i++) {
+        renderer.render(camera, scene, 1 / 60);
+
+        await renderer.graphics.device.queue.onSubmittedWorkDone();
+    }
+
+    let low = null;
+    let high = null;
+
+    for (const character of characters) {
+        const bounds = await world_bounds_of(scene_context, character);
+
+        low = low === null ? bounds.low : new Vector3(
+            Math.min(low.x, bounds.low.x), Math.min(low.y, bounds.low.y), Math.min(low.z, bounds.low.z)
+        );
+
+        high = high === null ? bounds.high : new Vector3(
+            Math.max(high.x, bounds.high.x), Math.max(high.y, bounds.high.y), Math.max(high.z, bounds.high.z)
+        );
+    }
+
+    const span = new Vector3(high.x - low.x, high.y - low.y, high.z - low.z);
+
+    const radius = Math.hypot(span.x, span.y, span.z) * 0.5;
+
+    camera_frame_sphere(
+        controller,
+        radius,
+        new Vector3((low.x + high.x) / 2, (low.y + high.y) / 2, (low.z + high.z) / 2)
+    );
+
+    controller.movement_speed_scale = radius * 0.2;
+
+    camera.near = radius * 0.01;
+    camera.far = radius * 400;
+
+    console.log(
+        `published box: low=(${low.x.toFixed(4)}, ${low.y.toFixed(4)}, ${low.z.toFixed(4)}) `
+        + `high=(${high.x.toFixed(4)}, ${high.y.toFixed(4)}, ${high.z.toFixed(4)}) — `
+        + `span ${span.x.toFixed(4)} × ${span.y.toFixed(4)} × ${span.z.toFixed(4)} m`
+    );
+
+    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();
+
+    globalThis.characters = characters;
+
+    // ---- the console half ------------------------------------------------------------------------
+
+    let animating = skin_mode === SkinMode.Animated;
+
+    /**
+     * The clone's deformed vertices, against the answer the CPU knows for the bind pose.
+     *
+     * Only meaningful under `?skin=bind`: with a clip playing there is no CPU-side answer to compare
+     * against, and with no skin registered there is nothing deforming the clone. It runs in the
+     * other two modes anyway rather than refusing — under `?skin=off` a pass says the clone's copy
+     * and address patch are right, which is worth knowing on its own.
+     */
+    globalThis.diagnose = async () => {
+        const { verify_clone_vertices } = await import('./verify_clone_vertices.js');
+
+        const was_animating = animating;
+
+        animating = false;
+
+        try {
+            return await verify_clone_vertices({ renderer, scene, entity: characters[0] });
+        } finally {
+            animating = was_animating;
+        }
+    };
+
+    set_status(
+        `loaded — ${count} × ${CHARACTER_URL}, skin=${skin_mode}. `
+        + `\`await diagnose()\` in the console.`,
+        'pass'
+    );
+
+    renderer.indicate_view_change();
+
+    // ---- frame loop --------------------------------------------------------------------------
+
+    element('animation').disabled = skin_mode !== SkinMode.Animated;
+
+    if (skin_mode !== SkinMode.Animated) {
+        // there is no clip to freeze; saying so beats a live-looking button that does nothing
+        element('animation').textContent = 'No clip playing';
+    }
+
+    element('animation').addEventListener('click', () => {
+        animating = !animating;
+
+        element('animation').textContent = animating ? 'Freeze pose' : 'Resume dance';
+
+        renderer.path_tracer.clear_history = true;
+        renderer.indicate_view_change();
+    });
+
+    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();
+
+        // A frozen pose is a still scene, which is the only condition under which the tracer's
+        // accumulator converges — so time stops rather than the frame loop stopping.
+        renderer.render(camera, scene, animating ? time_delta_s : 0);
+
+        stats_element.textContent =
+            `${count} × skin=${skin_mode}`
+            + `${renderer.feature_path_tracing_enabled ? '  ·  path traced' : '  ·  rasterized'}`;
+    }, FRAME_RATE_LIMIT);
+}