@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/playground/animation_prototype_stress.js

@@ -1,765 +1,765 @@
-import Quaternion from "../../core/geom/Quaternion.js";
-import Vector3 from "../../core/geom/Vector3.js";
-import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
-import { randomFromArray } from "../../core/math/random/randomFromArray.js";
-import { roundFair } from "../../core/math/random/roundFair.js";
-import { seededRandom } from "../../core/math/random/seededRandom.js";
-import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
-import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
-import { Transform } from "../../engine/ecs/transform/Transform.js";
-import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
-import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
-import {
-    shader_animation_pose_resolve,
-    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
-} from "../renderer/animation/shader_animation_pose_resolve.js";
-import { BoxGeometry, PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
-import { RasterizationCollectionType } from "../renderer/rasterize/expand/RasterizationCollectionType.js";
-import { make_sunlight } from "../renderer/light/make_sunlight.js";
-import { load_default_environment } from "./load_default_environment.js";
-import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
-import { Mesh } from "../renderer/scene/Mesh.js";
-import { Node3D } from "../renderer/scene/Node3D.js";
-import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
-import {
-    REFRESH_ALL_MESH_BOUNDS_SETTINGS_STRUCT,
-    shader_refresh_all_mesh_bounds
-} from "../renderer/object_property/shader_refresh_all_mesh_bounds.js";
-import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
-import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
-
-/**
- * Number of trees per side of the grid; total tree count is the square
- * of this. Adjust to scale the load — each tree adds dozens to thousands
- * of joints depending on how the branching dice land.
- */
-const TREE_GRID_RESOLUTION = 3;
-
-/**
- * Centre-to-centre spacing between trees in metres. Kept short so a
- * single camera pose covers the full grid; small enough that limbs at
- * full sway don't punch into the next tree's roots.
- */
-const TREE_SPACING = 3.0;
-
-/**
- * Limb dimensions. The box is centred on its origin in the geometry,
- * but each Mesh is offset by `BOX_HEIGHT/2` along its joint's local +Y
- * so the joint sits at the *base* of the limb. Children attach at the
- * limb's tip (offset `BOX_HEIGHT` from the joint origin).
- */
-const BOX_HEIGHT = 0.3;
-const BOX_THICKNESS = 0.08;
-
-/**
- * Hard depth cap for any branch — guards against pathologically long
- * tails when the branching distribution stays at ≥ 1 by chance. The
- * deepest a leaf transform's parent walk can go is `MAX_DEPTH + 1`
- * (the wrapping joint plus the visual mesh), comfortably under the
- * hierarchy shader's MAX_PARENT_WALK = 64.
- */
-const MAX_DEPTH = 32;
-
-/**
- * Number of pre-built rotation tracks shared across every joint. Each
- * limb picks one at random via `randomFromArray`, so the visual
- * variety is bounded by this pool size — more tracks → more distinct
- * rotation targets visible at once. Per-frame cost is independent of
- * the pool: tracks are GPU-side animation data, evaluated by the
- * apply shader, not iterated on the CPU.
- */
-const TRACK_POOL_SIZE = 1024;
-
-/**
- * Common loop period for every track in the pool — the curve
- * evaluator clamps `time` to `[time_min, time_max]`, so a single
- * clip-time can only meaningfully drive tracks that share its range.
- * Per-tree clips get a random phase offset within this period for
- * cross-tree variety.
- */
-const LOOP_PERIOD_S = 7;
-
-/**
- * How far each joint slerps from identity at the apex of its cycle. A
- * full random quaternion is on average a ~90° rotation; this scales
- * that down so a deep chain doesn't sweep through wild angles when
- * everything aligns.
- */
-const ROTATION_SLERP_FACTOR = 0.04;
-
-/**
- * Seed for the scene generator so the topology and the per-joint
- * animation choices are reproducible.
- */
-const RANDOM_SEED = 1234;
-
-/**
- * Shape of the per-joint branching distribution.
- *
- * Branch count is rolled as `roundFair(randomFloatBetween(lo, hi))`,
- * with `lo` and `hi` shrinking as we go deeper. The floor decays
- * slowly while the range (hi − lo) decays much faster, so deeper
- * levels collapse to a near-deterministic ~0.85 — almost always one
- * child, occasionally none, never branching. That keeps the tree
- * extending without exploding: depth ~32 is reachable by chance, but
- * the total node count stays tractable.
- *
- * @param {number} depth
- * @returns {{lo: number, hi: number}}
- */
-function branching_range_at_depth(depth) {
-    const FLOOR_INITIAL = 1.0;
-    const FLOOR_SHRINK_PER_LEVEL = 0.99;
-
-    const RANGE_INITIAL = 2.0;
-    const RANGE_SHRINK_PER_LEVEL = 0.9;
-
-    const lo = FLOOR_INITIAL * Math.pow(FLOOR_SHRINK_PER_LEVEL, depth);
-    const range = RANGE_INITIAL * Math.pow(RANGE_SHRINK_PER_LEVEL, depth);
-
-    return { lo, hi: lo + range };
-}
-
-/**
- * Build a quaternion-rotation animation track that oscillates between
- * identity and `target` and back over `period_s` seconds.
- *
- * The four channels (x, y, z, w) animate independently as scalar
- * Hermite curves; the apply shader normalizes the result so any drift
- * off the unit 4-sphere from per-channel interpolation is corrected.
- * Three keyframes per channel are enough for a small offset — the
- * exact path between identity and a small `target` is nearly linear,
- * so smoothed cubic interpolation is well within visual tolerance.
- *
- * @param {GPUAnimationManager} manager
- * @param {Quaternion} source
- * @param {Quaternion} target
- * @param {number} period_s
- * @returns {number} track id
- */
-function add_oscillating_rotation_track(manager, source, target, period_s) {
-    const x_keys = [
-        Keyframe.from(0, source.x),
-        Keyframe.from(period_s / 2, target.x),
-        Keyframe.from(period_s, source.x),
-    ];
-    const y_keys = [
-        Keyframe.from(0, source.y),
-        Keyframe.from(period_s / 2, target.y),
-        Keyframe.from(period_s, source.y),
-    ];
-    const z_keys = [
-        Keyframe.from(0, source.z),
-        Keyframe.from(period_s / 2, target.z),
-        Keyframe.from(period_s, source.z),
-    ];
-    const w_keys = [
-        Keyframe.from(0, source.w),
-        Keyframe.from(period_s / 2, target.w),
-        Keyframe.from(period_s, source.w),
-    ];
-
-    const x_curve = AnimationCurve.from(x_keys);
-    x_curve.alignAllTangents();
-    const y_curve = AnimationCurve.from(y_keys);
-    y_curve.alignAllTangents();
-    const z_curve = AnimationCurve.from(z_keys);
-    z_curve.alignAllTangents();
-    const w_curve = AnimationCurve.from(w_keys);
-    w_curve.alignAllTangents();
-
-    return manager.add_track({
-        x: manager.add_curve(x_curve),
-        y: manager.add_curve(y_curve),
-        z: manager.add_curve(z_curve),
-        w: manager.add_curve(w_curve),
-    });
-}
-
-/**
- * Recursively build a single tree of jointed limbs into `parent`.
- *
- * Each level adds:
- *  - a non-mesh `Node3D` (the joint) that owns the rotation animation,
- *    positioned at the tip of the parent's limb so its rotation pivots
- *    around that point;
- *  - a child `Mesh` (the visible limb) offset along the joint's local
- *    +Y so the limb extends outward from the pivot;
- *  - 0..N child joints, recursively, attached at the limb's tip.
- *
- * Joints are pushed into `joints_out` (a flat list) so the deferred
- * animation-binding pass can iterate them once GPU node ids are
- * known.
- *
- * @param {Node3D} parent_joint  Parent in the hierarchy. The first
- *     call passes the tree root; recursive calls pass the joint
- *     spawned at the previous level.
- * @param {number} depth
- * @param {function():number} random
- * @param {BoxGeometry} limb_geometry
- * @param {StandardShadeMaterial} limb_material
- * @param {Node3D[]} joints_out  Accumulator the caller scans after the
- *     tree is fully attached to the scene.
- */
-function grow_branch(parent_joint, depth, random, limb_geometry, limb_material, joints_out) {
-    // Visual limb: offset along the joint's local +Y so the limb
-    // extends from the joint origin upward. Rotating the joint pivots
-    // both the limb and any child joints around this origin — exactly
-    // the "elbow at the base of the bone" feel we want.
-    const limb = new Mesh();
-    limb.geometry = limb_geometry;
-    limb.material = limb_material;
-    limb.transform_local.setTranslation(0, BOX_HEIGHT / 2, 0);
-    parent_joint.addChild(limb);
-
-    joints_out.push(parent_joint);
-
-    if (depth >= MAX_DEPTH) return;
-
-    const { lo, hi } = branching_range_at_depth(depth);
-    const branch_count = roundFair(randomFloatBetween(random, lo, hi), random);
-
-    for (let i = 0; i < branch_count; i++) {
-        const child_joint = new Node3D();
-        // Hung off the tip of the parent limb so children visually
-        // attach at the far end. Same axis as the limb's extension —
-        // the joint's rotation pivot is the limb tip.
-        child_joint.transform_local.setTranslation(0, BOX_HEIGHT, 0);
-        parent_joint.addChild(child_joint);
-
-        grow_branch(child_joint, depth + 1, random, limb_geometry, limb_material, joints_out);
-    }
-}
-
-/**
- * Stress test for the GPU animation system and the transform-hierarchy
- * resolve pass.
- *
- * Generates a `TREE_GRID_RESOLUTION × TREE_GRID_RESOLUTION` grid of
- * jointed branches in the XZ plane. The animation database is structured as:
- *  - a shared pool of `TRACK_POOL_SIZE` rotation tracks, each with a
- *    distinct small random target rotation slerped `ROTATION_SLERP_FACTOR`
- *    of the way toward a uniformly-random orientation;
- *  - one clip per tree, with one binding per joint pointing at a
- *    randomly-picked track from the pool;
- *  - per-tree random phase offsets so neighbouring trees animate out
- *    of sync without needing per-track time-scaling.
- *
- * Per-frame the engine advances one clip per tree and dispatches
- * the apply shader over every (clip, binding) pair (~total joint
- * count). The transform-hierarchy pass sees long parent chains (up to
- * depth `MAX_DEPTH`) with deep-tree fan-out near the roots, exercising
- * both the lookback fast-path and the local-walk fallback in
- * `shader_nodes_update_transform_hierarchy`.
- *
- * Topology, track targets, and per-joint track picks are all seeded by
- * `RANDOM_SEED` so reruns produce identical scenes.
- *
- * @param {object} args
- * @param {Renderer} args.renderer
- * @param {Scene} args.scene
- * @param {OrbitalCameraController} args.controller
- */
-export function animation_prototype_stress({ renderer, scene, controller }) {
-
-    const random = seededRandom(RANDOM_SEED);
-
-    // ── Lighting & environment ──────────────────────────────────
-    scene.lights.add(make_sunlight({
-        intensity: 3,
-        direction: new Vector3(-0.4, -1, -0.3),
-    }));
-
-    load_default_environment(scene);
-
-    // ── Ground plane ────────────────────────────────────────────
-    // Sized to fit the grid plus margin on every side.
-    const ground_extent = TREE_GRID_RESOLUTION * TREE_SPACING + 10;
-    const plane_material = new StandardShadeMaterial();
-    plane_material.diffuse_color.parse("#b5b5b5");
-    plane_material.roughness_factor = 1;
-    plane_material.metallic_factor = 0;
-
-    const plane_transform = Transform.fromJSON({ position: { x: 0, y: 0, z: 0 } });
-    plane_transform.lookAt(Vector3.up);
-
-    const ground = Mesh.from(
-        new PlaneGeometry(ground_extent, ground_extent, 1, 1),
-        plane_material,
-        plane_transform.matrix,
-    );
-    ground.name = "Ground";
-    scene.add(ground);
-
-    // ── Trees ──────────────────────────────────────────────────
-    // One geometry + material shared across every limb. The mesh
-    // count still scales with joints (rasterization, culling,
-    // bounds-refresh all run per mesh), but vertex-buffer / material
-    // memory is constant.
-    const limb_geometry = new BoxGeometry(BOX_THICKNESS, BOX_HEIGHT, BOX_THICKNESS);
-    const limb_material = new StandardShadeMaterial();
-    limb_material.diffuse_color.parse("#7E5A3C");
-    limb_material.roughness_factor = 0.7;
-    limb_material.metallic_factor = 0;
-
-    // ── Animation manager + track pool ─────────────────────────
-    // Pool of TRACK_POOL_SIZE pre-built rotation tracks, each with a
-    // distinct small random target rotation. Tracks are created once
-    // upfront; every limb picks one at random via `randomFromArray`,
-    // so the apply shader sees a steady-state animation database
-    // regardless of how many trees end up referencing each track.
-    // Animation manager is owned by the scene context — fetch it via
-    // the scene context, don't construct a separate one. See the
-    // matching note in animation_prototype.js.
-    const animation_manager = renderer.scenes.obtain(scene).animation_manager;
-
-    /** @type {number[]} */
-    const track_pool = [];
-    {
-        const scratch_target = new Quaternion();
-        const scratch_source = new Quaternion();
-        for (let i = 0; i < TRACK_POOL_SIZE; i++) {
-            scratch_target.random(random);
-            scratch_target.slerpQuaternions(Quaternion.identity, scratch_target, ROTATION_SLERP_FACTOR);
-            scratch_source.normalize();
-
-            scratch_source.random(random);
-            scratch_source.slerpQuaternions(Quaternion.identity, scratch_source, ROTATION_SLERP_FACTOR);
-            scratch_source.normalize();
-
-            const track_id = add_oscillating_rotation_track(
-                animation_manager, scratch_source, scratch_target, LOOP_PERIOD_S
-            );
-            track_pool.push(track_id);
-        }
-    }
-
-    let total_joint_count = 0;
-
-    /**
-     * Per-tree state captured at scene-build time. The joints array
-     * and the corresponding track-pick array are populated together
-     * during topology generation (track picks happen here so the
-     * scene's reproducible-from-seed property covers track selection
-     * too); the deferred animation-binding pass turns each row into a
-     * single clip whose bindings reference the picked tracks.
-     *
-     * @type {{
-     *     joints: Node3D[],
-     *     track_ids: number[],
-     *     phase_offset_s: number,
-     * }[]}
-     */
-    const trees = [];
-
-    // Grid centred on the origin in the XZ plane. With
-    // TREE_GRID_RESOLUTION = 10 and TREE_SPACING = 1 each side spans
-    // [-4.5, 4.5]. Iterated as a flat index so the rest of the loop
-    // body needs no extra indentation.
-    const total_tree_count = TREE_GRID_RESOLUTION * TREE_GRID_RESOLUTION;
-    const grid_start = -((TREE_GRID_RESOLUTION - 1) * TREE_SPACING) / 2;
-
-    for (let i = 0; i < total_tree_count; i++) {
-        const gx = i % TREE_GRID_RESOLUTION;
-        const gz = Math.floor(i / TREE_GRID_RESOLUTION);
-
-        const tree_root = new Node3D();
-        tree_root.name = `tree_${gx}_${gz}_root`;
-        tree_root.transform_local.setTranslation(
-            grid_start + gx * TREE_SPACING,
-            0,
-            grid_start + gz * TREE_SPACING,
-        );
-
-        const tree_joints = [];
-        grow_branch(tree_root, 0, random, limb_geometry, limb_material, tree_joints);
-
-        // updateMatrices populates each node's transform_global from
-        // local + parent.global on the CPU side, so the first
-        // GPUSceneContext.build has correct globals to upload before
-        // the GPU hierarchy pass takes over.
-        tree_root.updateMatrices();
-
-        scene.add(tree_root);
-
-        // Pick a track per joint now, while RNG state is fresh.
-        // Doing it in two passes (build topology → pick tracks)
-        // would also work, but coupling them keeps the seed → output
-        // mapping straightforward to reason about.
-        const tree_track_ids = new Array(tree_joints.length);
-        for (let j = 0; j < tree_joints.length; j++) {
-            tree_track_ids[j] = randomFromArray(random, track_pool);
-        }
-
-        trees.push({
-            joints: tree_joints,
-            track_ids: tree_track_ids,
-            phase_offset_s: randomFloatBetween(random, 0, LOOP_PERIOD_S),
-        });
-
-        total_joint_count += tree_joints.length;
-    }
-
-    // Prime two rasterization collection limits — Meshes / Meshlets —
-    // through `limits.prime()` (sets both stats AND the runaway-clamp
-    // baseline so the renderer's first `update()` doesn't observe
-    // these as growth and reset siblings).
-    //
-    // Meshes / Meshlets: a 3×3 tree grid with depth-32 branching
-    // produces ~40k limb meshes, well past the GPUCollectionLimits
-    // defaults of 1e4 / 2e5. Without the prime, the cull-pass output
-    // overflows `arrayLength(output.elements)` and the truncated tail
-    // drops most trees from the visible set — ground at row 0
-    // survives because page-iteration order puts it first in the
-    // output stream. Each box has ~6 meshlets (one per face); pad to
-    // 10 to absorb larger primitives or any future encoder change
-    // that bumps the per-mesh meshlet count.
-    {
-        const limits = renderer.graphics.collection_limits;
-
-        // mesh count = ground (1) + every limb across every tree.
-        // `scene.instances.instances` is the cached mesh-only filter
-        // of the scene's InstanceBatch — same accessor scene.build
-        // iterates.
-        const total_mesh_count = scene.instances.instances.length;
-        const meshes_target = Math.ceil(total_mesh_count * 1.5);
-        if (meshes_target > limits.get_limit(RasterizationCollectionType.Meshes)) {
-            limits.prime(RasterizationCollectionType.Meshes, meshes_target);
-        }
-
-        const meshlets_target = total_mesh_count * 10;
-        if (meshlets_target > limits.get_limit(RasterizationCollectionType.Meshlets)) {
-            limits.prime(RasterizationCollectionType.Meshlets, meshlets_target);
-        }
-
-        console.log(
-            `[stress] total_joint_count=${total_joint_count}, ` +
-            `total_mesh_count=${total_mesh_count}; ` +
-            `Meshes=${limits.get_limit(RasterizationCollectionType.Meshes)}, ` +
-            `Meshlets=${limits.get_limit(RasterizationCollectionType.Meshlets)}`
-        );
-    }
-
-    // ── Camera ──────────────────────────────────────────────────
-    // Pulled back along +Z and slightly elevated so the whole grid
-    // fits in frame at startup.
-    const grid_span = TREE_GRID_RESOLUTION * TREE_SPACING;
-    const camera_position = new Vector3(0, BOX_HEIGHT * MAX_DEPTH * 0.4, grid_span * 0.55);
-    const camera_target = new Vector3(0, BOX_HEIGHT * MAX_DEPTH * 0.25, 0);
-    controller.look(camera_position, camera_target);
-    controller.camera.near = 0.1;
-    controller.camera.far = grid_span * 3 + 10;
-
-    // ── Deferred clip creation ─────────────────────────────────
-    // Clips can't be created until the joints have GPU rows in
-    // `id_mapping`, which only happens after the first
-    // `GPUSceneContext.build`. We run this once on the first
-    // onFrameFinished where the scene database is populated.
-
-    /**
-     * One clip id per tree, captured in the same order as `trees`.
-     * Used per-frame to advance each clip's time.
-     * @type {number[]}
-     */
-    const tree_clip_ids = new Array(trees.length);
-
-    let bindings_initialised = false;
-    let post_apply_readback_done = false;
-    let post_apply_frames_remaining = 1;
-    let render_state_logged = false;
-
-    /**
-     * Diagnostic — one-shot dump of what the GPU side actually believes
-     * about the scene right after the first build runs. Pinpoints the
-     * category of bug for "trees aren't visible":
-     *  - meshes_table empty / row 0 only → mesh-add path didn't run.
-     *  - meshes_table populated but every row points at the same geometry
-     *    id → obtain_geometry_index folded source + clones into one slot.
-     *  - meshes_table populated but every row's geometry id is past
-     *    geometry_count → clones polluted the buffer for non-skinned meshes.
-     *  - meshes_table populated, geometry ids reasonable, but bounds are
-     *    NaN / garbage → bounding-box / sphere serialisation regressed.
-     *
-     * @param {GPUSceneContext} gpu_scene
-     */
-    function log_render_state(gpu_scene) {
-        const meshes_table = gpu_scene.scene_database.get('meshes');
-        const transforms_table = gpu_scene.scene_database.get('transforms');
-        const geometry_count = gpu_scene.geometries.managed.size;
-
-        // CPU-side meshes_table.count (count() is the cardinality of the
-        // occupancy bitset, populated synchronously by add() during build).
-        const mesh_row_count = meshes_table.count;
-        const transform_row_count = transforms_table.count;
-
-        console.log(
-            `[stress] render state: ` +
-            `meshes_table.count=${mesh_row_count}, ` +
-            `transforms_table.count=${transform_row_count}, ` +
-            `geometry_count=${geometry_count}, ` +
-            `instance_count=${gpu_scene.scene.instance_count}, ` +
-            `node_count=${gpu_scene.scene.node_count}`
-        );
-
-        // Async: read the meshes_table back from the GPU and dump a
-        // representative cross-section so we can compare CPU's view with
-        // what's actually in the buffer the rasterizer reads.
-        gpu_scene.scene_database.debug_table_read_element('meshes', 0).then((row0) => {
-            const summary = row0
-                ? `geometry=${row0.geometry}, material=${row0.material}, node=${row0.node}, bb=${JSON.stringify(row0.bounding_box)}`
-                : 'undefined';
-            console.log(`[stress] gpu meshes[0] = ${summary}`);
-        });
-
-        if (mesh_row_count > 1) {
-            gpu_scene.scene_database.debug_table_read_element('meshes', 1).then((row1) => {
-                const summary = row1
-                    ? `geometry=${row1.geometry}, material=${row1.material}, node=${row1.node}, bb=${JSON.stringify(row1.bounding_box)}`
-                    : 'undefined';
-                console.log(`[stress] gpu meshes[1] = ${summary}`);
-            });
-        }
-
-        if (mesh_row_count > 2) {
-            gpu_scene.scene_database.debug_table_read_element('meshes', mesh_row_count - 1).then((rowN) => {
-                const summary = rowN
-                    ? `geometry=${rowN.geometry}, material=${rowN.material}, node=${rowN.node}, bb=${JSON.stringify(rowN.bounding_box)}`
-                    : 'undefined';
-                console.log(`[stress] gpu meshes[${mesh_row_count - 1}] = ${summary}`);
-            });
-        }
-    }
-
-    function initialise_bindings(gpu_scene) {
-        let min_instance = Infinity;
-        let max_instance = -Infinity;
-        let undefined_count = 0;
-        let total_bindings = 0;
-
-        // Sanity: walk id_mapping and count entries that resolve into
-        // the scene/mesh/joint ranges based on what we know about how
-        // GPUSceneContext.build allocates rows. A joint should never
-        // resolve to scene's row 0 or to a mesh row — if any do, the
-        // binding will write rotation into the wrong place.
-        const expected_first_joint_row = 1 + gpu_scene.scene.instance_count;
-        let joints_outside_expected_range = 0;
-
-        for (let i = 0; i < trees.length; i++) {
-            const tree = trees[i];
-            const bindings = [];
-
-            for (let j = 0; j < tree.joints.length; j++) {
-                const joint = tree.joints[j];
-                const node_row = gpu_scene.id_mapping.get(joint.id);
-                if (node_row === undefined) {
-                    undefined_count++;
-                    continue;
-                }
-
-                if (node_row < expected_first_joint_row) {
-                    joints_outside_expected_range++;
-                }
-
-                if (node_row < min_instance) min_instance = node_row;
-                if (node_row > max_instance) max_instance = node_row;
-                total_bindings++;
-
-                bindings.push({
-                    track: tree.track_ids[j],
-                    instance: node_row,
-                    property: Node3DProperty.Rotation,
-                });
-            }
-
-            if (bindings.length === 0) continue;
-
-            tree_clip_ids[i] = animation_manager.add_clip({
-                time: tree.phase_offset_s,
-                bindings,
-            });
-        }
-
-        console.log(
-            `[stress] bindings: total=${total_bindings}, ` +
-            `instance range=[${min_instance}, ${max_instance}], ` +
-            `expected_first_joint_row=${expected_first_joint_row}, ` +
-            `joints_in_mesh_range=${joints_outside_expected_range}, ` +
-            `id_mapping_size=${gpu_scene.id_mapping.size}, ` +
-            `instance_count=${gpu_scene.scene.instance_count}, ` +
-            `node_count=${gpu_scene.scene.node_count}, ` +
-            `undefined_resolutions=${undefined_count}`
-        );
-
-        bindings_initialised = true;
-
-    }
-
-    // Expose for debugging from the console.
-    window.animation_manager = animation_manager;
-
-    // ── Per-frame: advance clip times, dispatch evaluation ─────
-    const start_time_ms = performance.now();
-
-    renderer.onFrameFinished.add(() => {
-        const gpu_scene = renderer.scenes.obtain(scene);
-        const scene_database_buffer = gpu_scene.scene_database_buffer;
-
-        if (scene_database_buffer === undefined) {
-            // Scene hasn't been built yet — nothing to write into
-            // and id_mapping isn't populated.
-            return;
-        }
-
-        if (!render_state_logged) {
-            log_render_state(gpu_scene);
-            render_state_logged = true;
-        }
-
-        if (!bindings_initialised) {
-            initialise_bindings(gpu_scene);
-        }
-
-        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
-
-        // One clip per tree. Each clip drives every limb in its tree
-        // through its own time axis; the per-tree phase offset is
-        // baked in here (rather than as a track property) so all
-        // tracks in the pool can share the same curve range and stay
-        // cheap to evaluate.
-        for (let i = 0; i < tree_clip_ids.length; i++) {
-            const clip_id = tree_clip_ids[i];
-            if (clip_id === undefined) continue;
-            const t = (elapsed_s + trees[i].phase_offset_s) % LOOP_PERIOD_S;
-            animation_manager.set_time(clip_id, t);
-        }
-
-        const apply_dispatch_groups = animation_manager.database
-            .get('animation_bound_track_groups')
-            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
-        if (apply_dispatch_groups === 0) {
-            return;
-        }
-
-        const cmd = ShadeGPUCommandContext.create(
-            renderer.graphics,
-            "AnimationPrototypeStress/Tick"
-        );
-
-        animation_manager.update(cmd);
-
-        // Size the pose accumulator to cover every allocated row of
-        // the transforms table — apply writes by absolute row index,
-        // resolve iterates the table via page iterator.
-        const transforms_table = gpu_scene.scene_database.get('transforms');
-        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
-            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
-        );
-        const pose_accumulator_rows = transforms_table.dispatch_page_count
-            * transforms_table.descriptor.elements_per_page;
-        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
-
-        const graph = new FrameGraph("AnimationPrototypeStress/Tick");
-
-        // ── Imported existing resources ────────────────────────
-        const gr_animation_database = graph_import_buffer(
-            graph, animation_manager.database.buffer, "animation_database"
-        );
-        const gr_scene_database = graph_import_buffer(
-            graph, scene_database_buffer, "scene_database"
-        );
-        const gr_geometries = graph_import_buffer(
-            graph, gpu_scene.geometries.buffer_metadata, "geometries"
-        );
-        const gr_materials = graph_import_buffer(
-            graph, gpu_scene.materials.metadata_table.buffer, "materials"
-        );
-        const gr_pose_accumulator = graph_import_buffer(
-            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
-        );
-
-        // ── Pass 1: animation apply ───────────────────────────
-        // Atomic-adds weighted per-binding values into the pose
-        // accumulator. With one clip per tree at weight 1.0 and
-        // disjoint joint targets, there's no inter-thread contention
-        // on accumulator slots.
-        const apply_data = {};
-        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
-            shader_animation_apply.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: apply_dispatch_groups,
-                bindings: {
-                    animation_database: resources.get(data.animation_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                    materials: resources.get(data.materials),
-                },
-            });
-        });
-
-        apply_data.animation_database = apply_pass.read(gr_animation_database);
-        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
-        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
-
-        // ── Pass 2: pose resolve ──────────────────────────────
-        const resolve_data = {};
-        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
-            if (resolve_dispatch_groups === 0) {
-                return;
-            }
-            shader_animation_pose_resolve.dispatch({
-                encoder: ctx.encoder,
-                group_count_x: resolve_dispatch_groups,
-                bindings: {
-                    scene_database: resources.get(data.scene_database),
-                    pose_accumulator: resources.get(data.pose_accumulator),
-                },
-            });
-        });
-
-        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
-        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
-
-        // ── Pass 3: propagate node.local → node.global ─────────
-        const { scene_database: gr_scene_database_after_propagate } =
-            graph_scene_update_transform_hierarchy({
-                graph,
-                scene: gpu_scene,
-                scene_database: resolve_data.scene_database,
-            });
-
-        // ── Pass 4: blanket bounds refresh ─────────────────────
-        // With the stress test driving joints (non-mesh nodes),
-        // descendant limbs' world positions move but their bounds
-        // don't update. Sweep every mesh once a frame until proper
-        // descendant invalidation lands (Phase 3 — per-meshlet
-        // bounds refresh).
-        const refresh_all_data = {};
-        const refresh_all_pass = graph.add(
-            "object-property/refresh-all-mesh-bounds",
-            refresh_all_data,
-            (data, resources, ctx) => {
-                const settings = ctx.encoder.allocateTransientValueBuffer(
-                    REFRESH_ALL_MESH_BOUNDS_SETTINGS_STRUCT,
-                    { instance_count: gpu_scene.scene.instance_count }
-                );
-                shader_refresh_all_mesh_bounds.dispatchLinear({
-                    encoder: ctx.encoder,
-                    element_count: gpu_scene.scene.instance_count,
-                    bindings: {
-                        settings,
-                        scene_database: resources.get(data.scene_database),
-                        geometries: resources.get(data.geometries),
-                    },
-                });
-            }
-        );
-        refresh_all_data.scene_database = refresh_all_pass.write(
-            refresh_all_pass.read(gr_scene_database_after_propagate)
-        );
-        refresh_all_data.geometries = refresh_all_pass.read(gr_geometries);
-
-        cmd.encodeGraph(graph);
-        cmd.finish();
-
-    });
-}
+import Quaternion from "../../core/geom/Quaternion.js";
+import Vector3 from "../../core/geom/Vector3.js";
+import { randomFloatBetween } from "../../core/math/random/randomFloatBetween.js";
+import { randomFromArray } from "../../core/math/random/randomFromArray.js";
+import { roundFair } from "../../core/math/random/roundFair.js";
+import { seededRandom } from "../../core/math/random/seededRandom.js";
+import { AnimationCurve } from "../../engine/animation/curve/AnimationCurve.js";
+import { Keyframe } from "../../engine/animation/curve/Keyframe.js";
+import { Transform } from "../../engine/ecs/transform/Transform.js";
+import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
+import { shader_animation_apply, WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE } from "../renderer/animation/shader_animation_apply.js";
+import {
+    shader_animation_pose_resolve,
+    WORKGROUP_SIZE as ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE,
+} from "../renderer/animation/shader_animation_pose_resolve.js";
+import { BoxGeometry, PlaneGeometry } from "../renderer/geometry/BoxGeometry.js";
+import { RasterizationCollectionType } from "../renderer/rasterize/expand/RasterizationCollectionType.js";
+import { make_sunlight } from "../renderer/light/make_sunlight.js";
+import { load_default_environment } from "./load_default_environment.js";
+import { StandardShadeMaterial } from "../renderer/material/StandardShadeMaterial.js";
+import { Mesh } from "../renderer/scene/Mesh.js";
+import { Node3D } from "../renderer/scene/Node3D.js";
+import { Node3DProperty } from "../renderer/object_property/Node3DProperty.js";
+import {
+    REFRESH_ALL_MESH_BOUNDS_SETTINGS_STRUCT,
+    shader_refresh_all_mesh_bounds
+} from "../renderer/object_property/shader_refresh_all_mesh_bounds.js";
+import { graph_scene_update_transform_hierarchy } from "../renderer/scene/hierarchy/graph_scene_update_transform_hierarchy.js";
+import { graph_import_buffer } from "../renderer/shader/graph/graph_import_buffer.js";
+
+/**
+ * Number of trees per side of the grid; total tree count is the square
+ * of this. Adjust to scale the load — each tree adds dozens to thousands
+ * of joints depending on how the branching dice land.
+ */
+const TREE_GRID_RESOLUTION = 3;
+
+/**
+ * Centre-to-centre spacing between trees in metres. Kept short so a
+ * single camera pose covers the full grid; small enough that limbs at
+ * full sway don't punch into the next tree's roots.
+ */
+const TREE_SPACING = 3.0;
+
+/**
+ * Limb dimensions. The box is centred on its origin in the geometry,
+ * but each Mesh is offset by `BOX_HEIGHT/2` along its joint's local +Y
+ * so the joint sits at the *base* of the limb. Children attach at the
+ * limb's tip (offset `BOX_HEIGHT` from the joint origin).
+ */
+const BOX_HEIGHT = 0.3;
+const BOX_THICKNESS = 0.08;
+
+/**
+ * Hard depth cap for any branch — guards against pathologically long
+ * tails when the branching distribution stays at ≥ 1 by chance. The
+ * deepest a leaf transform's parent walk can go is `MAX_DEPTH + 1`
+ * (the wrapping joint plus the visual mesh), comfortably under the
+ * hierarchy shader's MAX_PARENT_WALK = 64.
+ */
+const MAX_DEPTH = 32;
+
+/**
+ * Number of pre-built rotation tracks shared across every joint. Each
+ * limb picks one at random via `randomFromArray`, so the visual
+ * variety is bounded by this pool size — more tracks → more distinct
+ * rotation targets visible at once. Per-frame cost is independent of
+ * the pool: tracks are GPU-side animation data, evaluated by the
+ * apply shader, not iterated on the CPU.
+ */
+const TRACK_POOL_SIZE = 1024;
+
+/**
+ * Common loop period for every track in the pool — the curve
+ * evaluator clamps `time` to `[time_min, time_max]`, so a single
+ * clip-time can only meaningfully drive tracks that share its range.
+ * Per-tree clips get a random phase offset within this period for
+ * cross-tree variety.
+ */
+const LOOP_PERIOD_S = 7;
+
+/**
+ * How far each joint slerps from identity at the apex of its cycle. A
+ * full random quaternion is on average a ~90° rotation; this scales
+ * that down so a deep chain doesn't sweep through wild angles when
+ * everything aligns.
+ */
+const ROTATION_SLERP_FACTOR = 0.04;
+
+/**
+ * Seed for the scene generator so the topology and the per-joint
+ * animation choices are reproducible.
+ */
+const RANDOM_SEED = 1234;
+
+/**
+ * Shape of the per-joint branching distribution.
+ *
+ * Branch count is rolled as `roundFair(randomFloatBetween(lo, hi))`,
+ * with `lo` and `hi` shrinking as we go deeper. The floor decays
+ * slowly while the range (hi − lo) decays much faster, so deeper
+ * levels collapse to a near-deterministic ~0.85 — almost always one
+ * child, occasionally none, never branching. That keeps the tree
+ * extending without exploding: depth ~32 is reachable by chance, but
+ * the total node count stays tractable.
+ *
+ * @param {number} depth
+ * @returns {{lo: number, hi: number}}
+ */
+function branching_range_at_depth(depth) {
+    const FLOOR_INITIAL = 1.0;
+    const FLOOR_SHRINK_PER_LEVEL = 0.99;
+
+    const RANGE_INITIAL = 2.0;
+    const RANGE_SHRINK_PER_LEVEL = 0.9;
+
+    const lo = FLOOR_INITIAL * Math.pow(FLOOR_SHRINK_PER_LEVEL, depth);
+    const range = RANGE_INITIAL * Math.pow(RANGE_SHRINK_PER_LEVEL, depth);
+
+    return { lo, hi: lo + range };
+}
+
+/**
+ * Build a quaternion-rotation animation track that oscillates between
+ * identity and `target` and back over `period_s` seconds.
+ *
+ * The four channels (x, y, z, w) animate independently as scalar
+ * Hermite curves; the apply shader normalizes the result so any drift
+ * off the unit 4-sphere from per-channel interpolation is corrected.
+ * Three keyframes per channel are enough for a small offset — the
+ * exact path between identity and a small `target` is nearly linear,
+ * so smoothed cubic interpolation is well within visual tolerance.
+ *
+ * @param {GPUAnimationManager} manager
+ * @param {Quaternion} source
+ * @param {Quaternion} target
+ * @param {number} period_s
+ * @returns {number} track id
+ */
+function add_oscillating_rotation_track(manager, source, target, period_s) {
+    const x_keys = [
+        Keyframe.from(0, source.x),
+        Keyframe.from(period_s / 2, target.x),
+        Keyframe.from(period_s, source.x),
+    ];
+    const y_keys = [
+        Keyframe.from(0, source.y),
+        Keyframe.from(period_s / 2, target.y),
+        Keyframe.from(period_s, source.y),
+    ];
+    const z_keys = [
+        Keyframe.from(0, source.z),
+        Keyframe.from(period_s / 2, target.z),
+        Keyframe.from(period_s, source.z),
+    ];
+    const w_keys = [
+        Keyframe.from(0, source.w),
+        Keyframe.from(period_s / 2, target.w),
+        Keyframe.from(period_s, source.w),
+    ];
+
+    const x_curve = AnimationCurve.from(x_keys);
+    x_curve.alignAllTangents();
+    const y_curve = AnimationCurve.from(y_keys);
+    y_curve.alignAllTangents();
+    const z_curve = AnimationCurve.from(z_keys);
+    z_curve.alignAllTangents();
+    const w_curve = AnimationCurve.from(w_keys);
+    w_curve.alignAllTangents();
+
+    return manager.add_track({
+        x: manager.add_curve(x_curve),
+        y: manager.add_curve(y_curve),
+        z: manager.add_curve(z_curve),
+        w: manager.add_curve(w_curve),
+    });
+}
+
+/**
+ * Recursively build a single tree of jointed limbs into `parent`.
+ *
+ * Each level adds:
+ *  - a non-mesh `Node3D` (the joint) that owns the rotation animation,
+ *    positioned at the tip of the parent's limb so its rotation pivots
+ *    around that point;
+ *  - a child `Mesh` (the visible limb) offset along the joint's local
+ *    +Y so the limb extends outward from the pivot;
+ *  - 0..N child joints, recursively, attached at the limb's tip.
+ *
+ * Joints are pushed into `joints_out` (a flat list) so the deferred
+ * animation-binding pass can iterate them once GPU node ids are
+ * known.
+ *
+ * @param {Node3D} parent_joint  Parent in the hierarchy. The first
+ *     call passes the tree root; recursive calls pass the joint
+ *     spawned at the previous level.
+ * @param {number} depth
+ * @param {function():number} random
+ * @param {BoxGeometry} limb_geometry
+ * @param {StandardShadeMaterial} limb_material
+ * @param {Node3D[]} joints_out  Accumulator the caller scans after the
+ *     tree is fully attached to the scene.
+ */
+function grow_branch(parent_joint, depth, random, limb_geometry, limb_material, joints_out) {
+    // Visual limb: offset along the joint's local +Y so the limb
+    // extends from the joint origin upward. Rotating the joint pivots
+    // both the limb and any child joints around this origin — exactly
+    // the "elbow at the base of the bone" feel we want.
+    const limb = new Mesh();
+    limb.geometry = limb_geometry;
+    limb.material = limb_material;
+    limb.transform_local.setTranslation(0, BOX_HEIGHT / 2, 0);
+    parent_joint.addChild(limb);
+
+    joints_out.push(parent_joint);
+
+    if (depth >= MAX_DEPTH) return;
+
+    const { lo, hi } = branching_range_at_depth(depth);
+    const branch_count = roundFair(randomFloatBetween(random, lo, hi), random);
+
+    for (let i = 0; i < branch_count; i++) {
+        const child_joint = new Node3D();
+        // Hung off the tip of the parent limb so children visually
+        // attach at the far end. Same axis as the limb's extension —
+        // the joint's rotation pivot is the limb tip.
+        child_joint.transform_local.setTranslation(0, BOX_HEIGHT, 0);
+        parent_joint.addChild(child_joint);
+
+        grow_branch(child_joint, depth + 1, random, limb_geometry, limb_material, joints_out);
+    }
+}
+
+/**
+ * Stress test for the GPU animation system and the transform-hierarchy
+ * resolve pass.
+ *
+ * Generates a `TREE_GRID_RESOLUTION × TREE_GRID_RESOLUTION` grid of
+ * jointed branches in the XZ plane. The animation database is structured as:
+ *  - a shared pool of `TRACK_POOL_SIZE` rotation tracks, each with a
+ *    distinct small random target rotation slerped `ROTATION_SLERP_FACTOR`
+ *    of the way toward a uniformly-random orientation;
+ *  - one clip per tree, with one binding per joint pointing at a
+ *    randomly-picked track from the pool;
+ *  - per-tree random phase offsets so neighbouring trees animate out
+ *    of sync without needing per-track time-scaling.
+ *
+ * Per-frame the engine advances one clip per tree and dispatches
+ * the apply shader over every (clip, binding) pair (~total joint
+ * count). The transform-hierarchy pass sees long parent chains (up to
+ * depth `MAX_DEPTH`) with deep-tree fan-out near the roots, exercising
+ * both the lookback fast-path and the local-walk fallback in
+ * `shader_nodes_update_transform_hierarchy`.
+ *
+ * Topology, track targets, and per-joint track picks are all seeded by
+ * `RANDOM_SEED` so reruns produce identical scenes.
+ *
+ * @param {object} args
+ * @param {Renderer} args.renderer
+ * @param {Scene} args.scene
+ * @param {OrbitalCameraController} args.controller
+ */
+export function animation_prototype_stress({ renderer, scene, controller }) {
+
+    const random = seededRandom(RANDOM_SEED);
+
+    // ── Lighting & environment ──────────────────────────────────
+    scene.lights.add(make_sunlight({
+        intensity: 3,
+        direction: new Vector3(-0.4, -1, -0.3),
+    }));
+
+    load_default_environment(scene);
+
+    // ── Ground plane ────────────────────────────────────────────
+    // Sized to fit the grid plus margin on every side.
+    const ground_extent = TREE_GRID_RESOLUTION * TREE_SPACING + 10;
+    const plane_material = new StandardShadeMaterial();
+    plane_material.diffuse_color.parse("#b5b5b5");
+    plane_material.roughness_factor = 1;
+    plane_material.metallic_factor = 0;
+
+    const plane_transform = Transform.fromJSON({ position: { x: 0, y: 0, z: 0 } });
+    plane_transform.lookAt(Vector3.up);
+
+    const ground = Mesh.from(
+        new PlaneGeometry(ground_extent, ground_extent, 1, 1),
+        plane_material,
+        plane_transform.matrix,
+    );
+    ground.name = "Ground";
+    scene.add(ground);
+
+    // ── Trees ──────────────────────────────────────────────────
+    // One geometry + material shared across every limb. The mesh
+    // count still scales with joints (rasterization, culling,
+    // bounds-refresh all run per mesh), but vertex-buffer / material
+    // memory is constant.
+    const limb_geometry = new BoxGeometry(BOX_THICKNESS, BOX_HEIGHT, BOX_THICKNESS);
+    const limb_material = new StandardShadeMaterial();
+    limb_material.diffuse_color.parse("#7E5A3C");
+    limb_material.roughness_factor = 0.7;
+    limb_material.metallic_factor = 0;
+
+    // ── Animation manager + track pool ─────────────────────────
+    // Pool of TRACK_POOL_SIZE pre-built rotation tracks, each with a
+    // distinct small random target rotation. Tracks are created once
+    // upfront; every limb picks one at random via `randomFromArray`,
+    // so the apply shader sees a steady-state animation database
+    // regardless of how many trees end up referencing each track.
+    // Animation manager is owned by the scene context — fetch it via
+    // the scene context, don't construct a separate one. See the
+    // matching note in animation_prototype.js.
+    const animation_manager = renderer.scenes.obtain(scene).animation_manager;
+
+    /** @type {number[]} */
+    const track_pool = [];
+    {
+        const scratch_target = new Quaternion();
+        const scratch_source = new Quaternion();
+        for (let i = 0; i < TRACK_POOL_SIZE; i++) {
+            scratch_target.random(random);
+            scratch_target.slerpQuaternions(Quaternion.identity, scratch_target, ROTATION_SLERP_FACTOR);
+            scratch_source.normalize();
+
+            scratch_source.random(random);
+            scratch_source.slerpQuaternions(Quaternion.identity, scratch_source, ROTATION_SLERP_FACTOR);
+            scratch_source.normalize();
+
+            const track_id = add_oscillating_rotation_track(
+                animation_manager, scratch_source, scratch_target, LOOP_PERIOD_S
+            );
+            track_pool.push(track_id);
+        }
+    }
+
+    let total_joint_count = 0;
+
+    /**
+     * Per-tree state captured at scene-build time. The joints array
+     * and the corresponding track-pick array are populated together
+     * during topology generation (track picks happen here so the
+     * scene's reproducible-from-seed property covers track selection
+     * too); the deferred animation-binding pass turns each row into a
+     * single clip whose bindings reference the picked tracks.
+     *
+     * @type {{
+     *     joints: Node3D[],
+     *     track_ids: number[],
+     *     phase_offset_s: number,
+     * }[]}
+     */
+    const trees = [];
+
+    // Grid centred on the origin in the XZ plane. With
+    // TREE_GRID_RESOLUTION = 10 and TREE_SPACING = 1 each side spans
+    // [-4.5, 4.5]. Iterated as a flat index so the rest of the loop
+    // body needs no extra indentation.
+    const total_tree_count = TREE_GRID_RESOLUTION * TREE_GRID_RESOLUTION;
+    const grid_start = -((TREE_GRID_RESOLUTION - 1) * TREE_SPACING) / 2;
+
+    for (let i = 0; i < total_tree_count; i++) {
+        const gx = i % TREE_GRID_RESOLUTION;
+        const gz = Math.floor(i / TREE_GRID_RESOLUTION);
+
+        const tree_root = new Node3D();
+        tree_root.name = `tree_${gx}_${gz}_root`;
+        tree_root.transform_local.setTranslation(
+            grid_start + gx * TREE_SPACING,
+            0,
+            grid_start + gz * TREE_SPACING,
+        );
+
+        const tree_joints = [];
+        grow_branch(tree_root, 0, random, limb_geometry, limb_material, tree_joints);
+
+        // updateMatrices populates each node's transform_global from
+        // local + parent.global on the CPU side, so the first
+        // GPUSceneContext.build has correct globals to upload before
+        // the GPU hierarchy pass takes over.
+        tree_root.updateMatrices();
+
+        scene.add(tree_root);
+
+        // Pick a track per joint now, while RNG state is fresh.
+        // Doing it in two passes (build topology → pick tracks)
+        // would also work, but coupling them keeps the seed → output
+        // mapping straightforward to reason about.
+        const tree_track_ids = new Array(tree_joints.length);
+        for (let j = 0; j < tree_joints.length; j++) {
+            tree_track_ids[j] = randomFromArray(random, track_pool);
+        }
+
+        trees.push({
+            joints: tree_joints,
+            track_ids: tree_track_ids,
+            phase_offset_s: randomFloatBetween(random, 0, LOOP_PERIOD_S),
+        });
+
+        total_joint_count += tree_joints.length;
+    }
+
+    // Prime two rasterization collection limits — Meshes / Meshlets —
+    // through `limits.prime()` (sets both stats AND the runaway-clamp
+    // baseline so the renderer's first `update()` doesn't observe
+    // these as growth and reset siblings).
+    //
+    // Meshes / Meshlets: a 3×3 tree grid with depth-32 branching
+    // produces ~40k limb meshes, well past the GPUCollectionLimits
+    // defaults of 1e4 / 2e5. Without the prime, the cull-pass output
+    // overflows `arrayLength(output.elements)` and the truncated tail
+    // drops most trees from the visible set — ground at row 0
+    // survives because page-iteration order puts it first in the
+    // output stream. Each box has ~6 meshlets (one per face); pad to
+    // 10 to absorb larger primitives or any future encoder change
+    // that bumps the per-mesh meshlet count.
+    {
+        const limits = renderer.graphics.collection_limits;
+
+        // mesh count = ground (1) + every limb across every tree.
+        // `scene.instances.instances` is the cached mesh-only filter
+        // of the scene's InstanceBatch — same accessor scene.build
+        // iterates.
+        const total_mesh_count = scene.instances.instances.length;
+        const meshes_target = Math.ceil(total_mesh_count * 1.5);
+        if (meshes_target > limits.get_limit(RasterizationCollectionType.Meshes)) {
+            limits.prime(RasterizationCollectionType.Meshes, meshes_target);
+        }
+
+        const meshlets_target = total_mesh_count * 10;
+        if (meshlets_target > limits.get_limit(RasterizationCollectionType.Meshlets)) {
+            limits.prime(RasterizationCollectionType.Meshlets, meshlets_target);
+        }
+
+        console.log(
+            `[stress] total_joint_count=${total_joint_count}, ` +
+            `total_mesh_count=${total_mesh_count}; ` +
+            `Meshes=${limits.get_limit(RasterizationCollectionType.Meshes)}, ` +
+            `Meshlets=${limits.get_limit(RasterizationCollectionType.Meshlets)}`
+        );
+    }
+
+    // ── Camera ──────────────────────────────────────────────────
+    // Pulled back along +Z and slightly elevated so the whole grid
+    // fits in frame at startup.
+    const grid_span = TREE_GRID_RESOLUTION * TREE_SPACING;
+    const camera_position = new Vector3(0, BOX_HEIGHT * MAX_DEPTH * 0.4, grid_span * 0.55);
+    const camera_target = new Vector3(0, BOX_HEIGHT * MAX_DEPTH * 0.25, 0);
+    controller.look(camera_position, camera_target);
+    controller.camera.near = 0.1;
+    controller.camera.far = grid_span * 3 + 10;
+
+    // ── Deferred clip creation ─────────────────────────────────
+    // Clips can't be created until the joints have GPU rows in
+    // `id_mapping`, which only happens after the first
+    // `GPUSceneContext.build`. We run this once on the first
+    // onFrameFinished where the scene database is populated.
+
+    /**
+     * One clip id per tree, captured in the same order as `trees`.
+     * Used per-frame to advance each clip's time.
+     * @type {number[]}
+     */
+    const tree_clip_ids = new Array(trees.length);
+
+    let bindings_initialised = false;
+    let post_apply_readback_done = false;
+    let post_apply_frames_remaining = 1;
+    let render_state_logged = false;
+
+    /**
+     * Diagnostic — one-shot dump of what the GPU side actually believes
+     * about the scene right after the first build runs. Pinpoints the
+     * category of bug for "trees aren't visible":
+     *  - meshes_table empty / row 0 only → mesh-add path didn't run.
+     *  - meshes_table populated but every row points at the same geometry
+     *    id → obtain_geometry_index folded source + clones into one slot.
+     *  - meshes_table populated but every row's geometry id is past
+     *    geometry_count → clones polluted the buffer for non-skinned meshes.
+     *  - meshes_table populated, geometry ids reasonable, but bounds are
+     *    NaN / garbage → bounding-box / sphere serialisation regressed.
+     *
+     * @param {GPUSceneContext} gpu_scene
+     */
+    function log_render_state(gpu_scene) {
+        const meshes_table = gpu_scene.scene_database.get('meshes');
+        const transforms_table = gpu_scene.scene_database.get('transforms');
+        const geometry_count = gpu_scene.geometries.managed.size;
+
+        // CPU-side meshes_table.count (count() is the cardinality of the
+        // occupancy bitset, populated synchronously by add() during build).
+        const mesh_row_count = meshes_table.count;
+        const transform_row_count = transforms_table.count;
+
+        console.log(
+            `[stress] render state: ` +
+            `meshes_table.count=${mesh_row_count}, ` +
+            `transforms_table.count=${transform_row_count}, ` +
+            `geometry_count=${geometry_count}, ` +
+            `instance_count=${gpu_scene.scene.instance_count}, ` +
+            `node_count=${gpu_scene.scene.node_count}`
+        );
+
+        // Async: read the meshes_table back from the GPU and dump a
+        // representative cross-section so we can compare CPU's view with
+        // what's actually in the buffer the rasterizer reads.
+        gpu_scene.scene_database.debug_table_read_element('meshes', 0).then((row0) => {
+            const summary = row0
+                ? `geometry=${row0.geometry}, material=${row0.material}, node=${row0.node}, bb=${JSON.stringify(row0.bounding_box)}`
+                : 'undefined';
+            console.log(`[stress] gpu meshes[0] = ${summary}`);
+        });
+
+        if (mesh_row_count > 1) {
+            gpu_scene.scene_database.debug_table_read_element('meshes', 1).then((row1) => {
+                const summary = row1
+                    ? `geometry=${row1.geometry}, material=${row1.material}, node=${row1.node}, bb=${JSON.stringify(row1.bounding_box)}`
+                    : 'undefined';
+                console.log(`[stress] gpu meshes[1] = ${summary}`);
+            });
+        }
+
+        if (mesh_row_count > 2) {
+            gpu_scene.scene_database.debug_table_read_element('meshes', mesh_row_count - 1).then((rowN) => {
+                const summary = rowN
+                    ? `geometry=${rowN.geometry}, material=${rowN.material}, node=${rowN.node}, bb=${JSON.stringify(rowN.bounding_box)}`
+                    : 'undefined';
+                console.log(`[stress] gpu meshes[${mesh_row_count - 1}] = ${summary}`);
+            });
+        }
+    }
+
+    function initialise_bindings(gpu_scene) {
+        let min_instance = Infinity;
+        let max_instance = -Infinity;
+        let undefined_count = 0;
+        let total_bindings = 0;
+
+        // Sanity: walk id_mapping and count entries that resolve into
+        // the scene/mesh/joint ranges based on what we know about how
+        // GPUSceneContext.build allocates rows. A joint should never
+        // resolve to scene's row 0 or to a mesh row — if any do, the
+        // binding will write rotation into the wrong place.
+        const expected_first_joint_row = 1 + gpu_scene.scene.instance_count;
+        let joints_outside_expected_range = 0;
+
+        for (let i = 0; i < trees.length; i++) {
+            const tree = trees[i];
+            const bindings = [];
+
+            for (let j = 0; j < tree.joints.length; j++) {
+                const joint = tree.joints[j];
+                const node_row = gpu_scene.id_mapping.get(joint.id);
+                if (node_row === undefined) {
+                    undefined_count++;
+                    continue;
+                }
+
+                if (node_row < expected_first_joint_row) {
+                    joints_outside_expected_range++;
+                }
+
+                if (node_row < min_instance) min_instance = node_row;
+                if (node_row > max_instance) max_instance = node_row;
+                total_bindings++;
+
+                bindings.push({
+                    track: tree.track_ids[j],
+                    instance: node_row,
+                    property: Node3DProperty.Rotation,
+                });
+            }
+
+            if (bindings.length === 0) continue;
+
+            tree_clip_ids[i] = animation_manager.add_clip({
+                time: tree.phase_offset_s,
+                bindings,
+            });
+        }
+
+        console.log(
+            `[stress] bindings: total=${total_bindings}, ` +
+            `instance range=[${min_instance}, ${max_instance}], ` +
+            `expected_first_joint_row=${expected_first_joint_row}, ` +
+            `joints_in_mesh_range=${joints_outside_expected_range}, ` +
+            `id_mapping_size=${gpu_scene.id_mapping.size}, ` +
+            `instance_count=${gpu_scene.scene.instance_count}, ` +
+            `node_count=${gpu_scene.scene.node_count}, ` +
+            `undefined_resolutions=${undefined_count}`
+        );
+
+        bindings_initialised = true;
+
+    }
+
+    // Expose for debugging from the console.
+    window.animation_manager = animation_manager;
+
+    // ── Per-frame: advance clip times, dispatch evaluation ─────
+    const start_time_ms = performance.now();
+
+    renderer.onFrameFinished.add(() => {
+        const gpu_scene = renderer.scenes.obtain(scene);
+        const scene_database_buffer = gpu_scene.scene_database_buffer;
+
+        if (scene_database_buffer === undefined) {
+            // Scene hasn't been built yet — nothing to write into
+            // and id_mapping isn't populated.
+            return;
+        }
+
+        if (!render_state_logged) {
+            log_render_state(gpu_scene);
+            render_state_logged = true;
+        }
+
+        if (!bindings_initialised) {
+            initialise_bindings(gpu_scene);
+        }
+
+        const elapsed_s = (performance.now() - start_time_ms) * 1e-3;
+
+        // One clip per tree. Each clip drives every limb in its tree
+        // through its own time axis; the per-tree phase offset is
+        // baked in here (rather than as a track property) so all
+        // tracks in the pool can share the same curve range and stay
+        // cheap to evaluate.
+        for (let i = 0; i < tree_clip_ids.length; i++) {
+            const clip_id = tree_clip_ids[i];
+            if (clip_id === undefined) continue;
+            const t = (elapsed_s + trees[i].phase_offset_s) % LOOP_PERIOD_S;
+            animation_manager.set_time(clip_id, t);
+        }
+
+        const apply_dispatch_groups = animation_manager.database
+            .get('animation_bound_track_groups')
+            .dispatch_group_count(ANIMATION_APPLY_WORKGROUP_SIZE);
+        if (apply_dispatch_groups === 0) {
+            return;
+        }
+
+        const cmd = ShadeGPUCommandContext.create(
+            renderer.graphics,
+            "AnimationPrototypeStress/Tick"
+        );
+
+        animation_manager.update(cmd);
+
+        // Size the pose accumulator to cover every allocated row of
+        // the transforms table — apply writes by absolute row index,
+        // resolve iterates the table via page iterator.
+        const transforms_table = gpu_scene.scene_database.get('transforms');
+        const resolve_dispatch_groups = transforms_table.dispatch_group_count(
+            ANIMATION_POSE_RESOLVE_WORKGROUP_SIZE
+        );
+        const pose_accumulator_rows = transforms_table.dispatch_page_count
+            * transforms_table.descriptor.elements_per_page;
+        animation_manager.ensure_pose_accumulator_capacity(pose_accumulator_rows);
+
+        const graph = new FrameGraph("AnimationPrototypeStress/Tick");
+
+        // ── Imported existing resources ────────────────────────
+        const gr_animation_database = graph_import_buffer(
+            graph, animation_manager.database.buffer, "animation_database"
+        );
+        const gr_scene_database = graph_import_buffer(
+            graph, scene_database_buffer, "scene_database"
+        );
+        const gr_geometries = graph_import_buffer(
+            graph, gpu_scene.geometries.buffer_metadata, "geometries"
+        );
+        const gr_materials = graph_import_buffer(
+            graph, gpu_scene.materials.metadata_table.buffer, "materials"
+        );
+        const gr_pose_accumulator = graph_import_buffer(
+            graph, animation_manager.pose_accumulator_buffer, "pose_accumulator"
+        );
+
+        // ── Pass 1: animation apply ───────────────────────────
+        // Atomic-adds weighted per-binding values into the pose
+        // accumulator. With one clip per tree at weight 1.0 and
+        // disjoint joint targets, there's no inter-thread contention
+        // on accumulator slots.
+        const apply_data = {};
+        const apply_pass = graph.add("animation/apply", apply_data, (data, resources, ctx) => {
+            shader_animation_apply.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: apply_dispatch_groups,
+                bindings: {
+                    animation_database: resources.get(data.animation_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                    materials: resources.get(data.materials),
+                },
+            });
+        });
+
+        apply_data.animation_database = apply_pass.read(gr_animation_database);
+        apply_data.materials = apply_pass.write(apply_pass.read(gr_materials));
+        apply_data.pose_accumulator = apply_pass.write(apply_pass.read(gr_pose_accumulator));
+
+        // ── Pass 2: pose resolve ──────────────────────────────
+        const resolve_data = {};
+        const resolve_pass = graph.add("animation/pose_resolve", resolve_data, (data, resources, ctx) => {
+            if (resolve_dispatch_groups === 0) {
+                return;
+            }
+            shader_animation_pose_resolve.dispatch({
+                encoder: ctx.encoder,
+                group_count_x: resolve_dispatch_groups,
+                bindings: {
+                    scene_database: resources.get(data.scene_database),
+                    pose_accumulator: resources.get(data.pose_accumulator),
+                },
+            });
+        });
+
+        resolve_data.scene_database = resolve_pass.write(resolve_pass.read(gr_scene_database));
+        resolve_data.pose_accumulator = resolve_pass.write(resolve_pass.read(apply_data.pose_accumulator));
+
+        // ── Pass 3: propagate node.local → node.global ─────────
+        const { scene_database: gr_scene_database_after_propagate } =
+            graph_scene_update_transform_hierarchy({
+                graph,
+                scene: gpu_scene,
+                scene_database: resolve_data.scene_database,
+            });
+
+        // ── Pass 4: blanket bounds refresh ─────────────────────
+        // With the stress test driving joints (non-mesh nodes),
+        // descendant limbs' world positions move but their bounds
+        // don't update. Sweep every mesh once a frame until proper
+        // descendant invalidation lands (Phase 3 — per-meshlet
+        // bounds refresh).
+        const refresh_all_data = {};
+        const refresh_all_pass = graph.add(
+            "object-property/refresh-all-mesh-bounds",
+            refresh_all_data,
+            (data, resources, ctx) => {
+                const settings = ctx.encoder.allocateTransientValueBuffer(
+                    REFRESH_ALL_MESH_BOUNDS_SETTINGS_STRUCT,
+                    { instance_count: gpu_scene.scene.instance_count }
+                );
+                shader_refresh_all_mesh_bounds.dispatchLinear({
+                    encoder: ctx.encoder,
+                    element_count: gpu_scene.scene.instance_count,
+                    bindings: {
+                        settings,
+                        scene_database: resources.get(data.scene_database),
+                        geometries: resources.get(data.geometries),
+                    },
+                });
+            }
+        );
+        refresh_all_data.scene_database = refresh_all_pass.write(
+            refresh_all_pass.read(gr_scene_database_after_propagate)
+        );
+        refresh_all_data.geometries = refresh_all_pass.read(gr_geometries);
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+
+    });
+}