@woosh/meep-engine 3.29.0 → 3.31.0

package/src/shade/renderer/animation/chunk_animation_curve_evaluate.d.ts

@@ -1,20 +1,16 @@
 /**
- * Evaluate one curve at a given time. Keyframes are stored in a singly
- * linked list of blocks (`animation_keyframe_blocks`), each block
- * inlining up to {@link KEYFRAMES_PER_BLOCK} keyframes in ascending time
- * order. The curve header points at the head block; blocks chain
- * forward via their own `next` until a `0xFFFFFFFF` sentinel.
+ * Evaluate one curve at a given time, as `AnimationCurve.evaluate` does — the CPU reference the
+ * pose twin answers gameplay with. A curve's keyframes are a run of rows of `animation_keyframes`,
+ * `keyframes_first` onwards, in ascending time order.
  *
- * The walk is linear across blocks: keep the most recently visited
- * keyframe as `prev_key`, and as soon as we see a keyframe whose time is
- * `>= t_clamped`, interpolate `(prev_key, current)`. With an upfront
- * clamp to `[time_min, time_max]` we always either land inside a segment
- * or land exactly on the last keyframe.
+ * At or before the first key the curve holds the first key's value, and at or past the last it
+ * holds the last. Between them the segment starts at the last key at or before `time` and ends at
+ * the key after it, so two keys at one time are a step there and the second one's value is what the
+ * curve takes at that time. That is how a glTF STEP track is stored, and it is what gives a clip
+ * that has played out — its time held at the clip's end, on the last key — its last value.
  *
- * Cost is O(N) over total keyframes, but the per-block overhead is one
- * struct fetch per ~8 keyframes, so cache pressure is bounded. Curves
- * with thousands of keyframes were already an outlier shape in this
- * system — nothing in the apply path changed that economics.
+ * The segment is found by binary search over the run, each probe reading only a keyframe's `time`:
+ * ⌈log2(count - 1)⌉ probes, then the two keyframes of the segment.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/animation/chunk_animation_curve_evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_animation_curve_evaluate.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_animation_curve_evaluate.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CAFU,SAAS,CAgFlB;0BA1GyB,iCAAiC"}
+{"version":3,"file":"chunk_animation_curve_evaluate.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_animation_curve_evaluate.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;GAeG;AACH,6CAFU,SAAS,CA0DlB;0BA/EyB,iCAAiC"}

package/src/shade/renderer/animation/chunk_animation_curve_evaluate.js

@@ -1,29 +1,24 @@
 import { chunk_inverse_lerp } from "../shader/chunk/math/chunk_inverse_lerp.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 import { ANIMATION_CURVE_HEADER_STRUCT } from "./ANIMATION_CURVE_HEADER_STRUCT.js";
-import { ANIMATION_CURVE_KEYFRAME_STRUCT } from "./ANIMATION_CURVE_KEYFRAME_STRUCT.js";
 import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
 import { chunk_animation_curve_evaluate_piece } from "./chunk_animation_curve_evaluate_piece.js";
 
-const KEYFRAME_BLOCK_TABLE = ANIMATION_DATABASE_SPEC.get('animation_keyframe_blocks');
+const KEYFRAME_TABLE = ANIMATION_DATABASE_SPEC.get('animation_keyframes');
 
 /**
- * Evaluate one curve at a given time. Keyframes are stored in a singly
- * linked list of blocks (`animation_keyframe_blocks`), each block
- * inlining up to {@link KEYFRAMES_PER_BLOCK} keyframes in ascending time
- * order. The curve header points at the head block; blocks chain
- * forward via their own `next` until a `0xFFFFFFFF` sentinel.
+ * Evaluate one curve at a given time, as `AnimationCurve.evaluate` does — the CPU reference the
+ * pose twin answers gameplay with. A curve's keyframes are a run of rows of `animation_keyframes`,
+ * `keyframes_first` onwards, in ascending time order.
  *
- * The walk is linear across blocks: keep the most recently visited
- * keyframe as `prev_key`, and as soon as we see a keyframe whose time is
- * `>= t_clamped`, interpolate `(prev_key, current)`. With an upfront
- * clamp to `[time_min, time_max]` we always either land inside a segment
- * or land exactly on the last keyframe.
+ * At or before the first key the curve holds the first key's value, and at or past the last it
+ * holds the last. Between them the segment starts at the last key at or before `time` and ends at
+ * the key after it, so two keys at one time are a step there and the second one's value is what the
+ * curve takes at that time. That is how a glTF STEP track is stored, and it is what gives a clip
+ * that has played out — its time held at the clip's end, on the last key — its last value.
  *
- * Cost is O(N) over total keyframes, but the per-block overhead is one
- * struct fetch per ~8 keyframes, so cache pressure is bounded. Curves
- * with thousands of keyframes were already an outlier shape in this
- * system — nothing in the apply path changed that economics.
+ * The segment is found by binary search over the run, each probe reading only a keyframe's `time`:
+ * ⌈log2(count - 1)⌉ probes, then the two keyframes of the segment.
  *
  * @type {CodeChunk}
  */
@@ -35,73 +30,51 @@ fn animation_curve_evaluate(
     animation_database: ptr<storage, array<u32>>,
     curve: ${ANIMATION_CURVE_HEADER_STRUCT.wgsl_ref},
 ) -> f32 {
-    let t_clamped = clamp(time, curve.time_min, curve.time_max);
+    let first = curve.keyframes_first;
 
-    // Single-keyframe fast path: read just the head block's first slot.
-    // The block's \`count\` is guaranteed >= 1 for any allocated curve.
-    if(curve.keyframe_count <= 1u){
-        let head = ${KEYFRAME_BLOCK_TABLE.marshalling_method_read}(animation_database, curve.keyframe_block_head);
-        return head.keyframes[0].value;
+    // One keyframe, or a time at or before the first. A step at the very first key answers with
+    // its first value, as the CPU curve does.
+    if(curve.keyframe_count <= 1u || time <= curve.time_min){
+        return ${KEYFRAME_TABLE.marshalling_method_read}(animation_database, first).value;
     }
 
-    // Walk blocks, keeping the most recent keyframe in prev_key. As soon
-    // as we encounter a keyframe whose time >= t_clamped, interpolate
-    // (prev_key, current). The very first keyframe with no predecessor
-    // is the curve's first key — just return its value (only reachable
-    // when t_clamped == time_min after the upfront clamp).
-    var result: f32 = 0.0;
-    var found = false;
+    let last = first + curve.keyframe_count - 1u;
 
-    var prev_key: ${ANIMATION_CURVE_KEYFRAME_STRUCT.wgsl_ref};
-    var has_prev = false;
+    // At or past the last keyframe — the last of any sharing its time.
+    if(time >= curve.time_max){
+        return ${KEYFRAME_TABLE.marshalling_method_read}(animation_database, last).value;
+    }
 
-    var block_idx = curve.keyframe_block_head;
+    // Now time(first) < time < time(last). Keep time(lo) <= time < time(hi) and close in until the
+    // two are neighbours: lo is then the last keyframe at or before \`time\`.
+    var lo = first;
+    var hi = last;
 
     loop {
-        if(found){ break; }
-        if(block_idx == 0xFFFFFFFFu){ break; }
-
-        let block = ${KEYFRAME_BLOCK_TABLE.marshalling_method_read}(animation_database, block_idx);
-
-        for(var i = 0u; i < block.count; i++){
-            let key = block.keyframes[i];
+        if(hi - lo <= 1u){ break; }
 
-            if(key.time >= t_clamped){
-                if(!has_prev || key.time == prev_key.time){
-                    // At-or-before the curve's first keyframe, or two
-                    // consecutive keys share a time — return the value
-                    // directly rather than feed inverse_lerp a zero
-                    // denominator.
-                    result = key.value;
-                } else {
-                    let t = inverse_lerp(prev_key.time, key.time, t_clamped);
-                    result = animation_curve_evaluate_piece(t, prev_key, key);
-                }
-                found = true;
-                break;
-            }
+        let mid = lo + ((hi - lo) >> 1u);
 
-            prev_key = key;
-            has_prev = true;
+        if(${KEYFRAME_TABLE.marshalling_method_read_field('time')}(animation_database, mid) <= time){
+            lo = mid;
+        } else {
+            hi = mid;
         }
-
-        block_idx = block.next;
     }
 
-    if(!found && has_prev){
-        // t_clamped exceeded every keyframe's time. The upfront clamp to
-        // curve.time_max should make this only reachable when t equals
-        // the last keyframe exactly (or float-rounds past it); return
-        // the last value either way.
-        result = prev_key.value;
-    }
+    // key1 is strictly later than \`time\`, so the span is never zero; exactly on key0, t is 0 and
+    // the piece is key0's value (tangents are finite — Keyframe refuses any other)
+    let key0 = ${KEYFRAME_TABLE.marshalling_method_read}(animation_database, lo);
+    let key1 = ${KEYFRAME_TABLE.marshalling_method_read}(animation_database, hi);
+
+    let t = inverse_lerp(key0.time, key1.time, time);
 
-    return result;
+    return animation_curve_evaluate_piece(t, key0, key1);
 }
     `, [
         ANIMATION_CURVE_HEADER_STRUCT.declaration_chunk,
-        ANIMATION_CURVE_KEYFRAME_STRUCT.declaration_chunk,
-        KEYFRAME_BLOCK_TABLE.chunk_read,
+        KEYFRAME_TABLE.chunk_read,
+        KEYFRAME_TABLE.chunk_read_field('time'),
         chunk_animation_curve_evaluate_piece,
         chunk_inverse_lerp,
     ]

package/src/shade/renderer/animation/chunk_pose_accumulator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,SAAS,CA6FhB;0BA7HuB,iCAAiC"}
+{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,SAAS,CAsGhB;0BAtIuB,iCAAiC"}

package/src/shade/renderer/animation/chunk_pose_accumulator.js

@@ -85,16 +85,25 @@ fn pose_accumulator_add_translation(row: u32, value: vec3<f32>, mask: u32) {
     }
 }
 
-fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32) {
+fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32, weight: f32) {
     // Rotation tracks normally cover all four channels (quaternion is one
     // unit). Channels missing from the mask must default to the identity
     // quaternion (0, 0, 0, 1): the evaluator leaves them at 0, which is
     // right for x/y/z but turns a missing w curve into a 180-degree
-    // rotation after normalisation — the CPU apply path defaults w to 1
-    // (see ShadeAnimationChannel.apply), and the GPU must match.
+    // rotation after normalisation — pose_evaluate_local, the CPU twin,
+    // defaults w to 1 and the GPU must match.
     // The resolve pass normalises the accumulated sum, which is what
     // corrects a weighted-vec4 blend back onto the unit 4-sphere.
-    let w = select(1.0, value.w, (mask & 0x8u) != 0u);
+    //
+    // The value arrives ALREADY multiplied by the clip's weight, which is why
+    // the weight is passed in rather than inferred: this clip's share of the
+    // identity's w is the weight, not 1.0. Substituting an unweighted 1.0 made
+    // one clip at weight 0.5 accumulate (0.5x, 0.5y, 0.5z, 1.0) against the
+    // twin's (0.5x, 0.5y, 0.5z, 0.5) — a different rotation once normalised,
+    // pulled toward identity — and it put a floor of 1.0 under the sum's
+    // length, so the resolve's rest-pose fallback for a zero-length sum could
+    // not fire and a joint rotated only by a silent clip lost its rest pose.
+    let w = select(weight, value.w, (mask & 0x8u) != 0u);
 
     let base = pose_accumulator_slot_base(row) + POSE_OFFSET_ROTATION;
     pose_accumulator_atomic_add_f32(base + 0u, value.x);

package/src/shade/renderer/animation/shader_animation_apply.d.ts

@@ -1,17 +1,17 @@
 /**
  * Workgroup size for the apply pass. Exported so dispatchers can pair it
- * with `animation_bound_track_groups.dispatch_group_count(WORKGROUP_SIZE)` —
+ * with `animation_bindings.dispatch_group_count(WORKGROUP_SIZE)` —
  * the page iterator's slot-to-workgroup mapping is computed against this
  * value, so the two must agree.
  */
 export const WORKGROUP_SIZE: 64;
 /**
- * Compute shader that walks the `animation_bound_track_groups` table —
- * one thread per group-node slot via the page iterator — evaluating
- * every inline binding under its owning clip's `time + time_start` and
- * atomic-adding the (weight-multiplied) result into the pose
- * accumulator (Node3D properties) or directly into the material
- * metadata table (Material properties).
+ * Compute shader that walks the `animation_bindings` table — one thread
+ * per binding slot via the page iterator — evaluating each binding under
+ * its clip's `time + time_start` and atomic-adding the
+ * (weight-multiplied) result into the pose accumulator (Node3D
+ * properties) or directly into the material metadata table (Material
+ * properties).
  *
  * Node3D writes land in `pose_accumulator` rather than directly in
  * `transforms_table.local_*` so multi-clip blending is just additive;
@@ -19,8 +19,14 @@ export const WORKGROUP_SIZE: 64;
  * each dirty row into the transforms table, normalizes rotation, and
  * zeros the slot for the next frame.
  *
+ * One thread per binding rather than one per group of eight, with the curve's segment found by
+ * binary search rather than a walk over keyframe blocks. Measured 2026-09-25 on the
+ * skinned_blas_refit playground, 324 dancers on an RTX 4090, paired launches against the group
+ * version: 27.6 µs a frame (p10) where it took 700–1,540 µs, every launch. The poses it leaves in
+ * the transforms rows read back bit-identical to the group version's at the same clip times.
+ *
  * Dispatch via
- * `shader_animation_apply.dispatch({ group_count_x: animation_bound_track_groups.dispatch_group_count(WORKGROUP_SIZE), ... })` —
+ * `shader_animation_apply.dispatch({ group_count_x: animation_bindings.dispatch_group_count(WORKGROUP_SIZE), ... })` —
  * the iterator covers every allocated page in parallel and skips
  * unallocated/unoccupied slots in-shader.
  */

package/src/shade/renderer/animation/shader_animation_apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_animation_apply.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/shader_animation_apply.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,gCAAiC;AAoFjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,mDAIG;8BA1H2B,4BAA4B"}
+{"version":3,"file":"shader_animation_apply.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/shader_animation_apply.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,gCAAiC;AA+EjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,mDAIG;8BA3H2B,4BAA4B"}

package/src/shade/renderer/animation/shader_animation_apply.js

@@ -1,128 +1,129 @@
-import { atomic_u32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
-import { MATERIAL_METADATA_STRUCT } from "../material/MATERIAL_METADATA_STRUCT.js";
-import { chunk_write_object_property } from "../object_property/chunk_write_object_property.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
-import { chunk_animation_track_evaluate } from "./animation_track_evaluate.js";
-
-const GROUP_TABLE = ANIMATION_DATABASE_SPEC.get('animation_bound_track_groups');
-const CLIP_TABLE = ANIMATION_DATABASE_SPEC.get('animation_clips');
-const TRACK_TABLE = ANIMATION_DATABASE_SPEC.get('animation_tracks');
-
-/**
- * Workgroup size for the apply pass. Exported so dispatchers can pair it
- * with `animation_bound_track_groups.dispatch_group_count(WORKGROUP_SIZE)` —
- * the page iterator's slot-to-workgroup mapping is computed against this
- * value, so the two must agree.
- */
-export const WORKGROUP_SIZE = 64;
-
-const PG_PREFIX = GROUP_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
-
-// `materials` and `pose_accumulator` are referenced by name from the
-// property-write chunks rather than passed as pointers — the chunks
-// rely on these bindings being declared in the importing shader.
-//
-// `pose_accumulator` is the per-Node3D contribution scratch (one slot per
-// transforms-table row, `POSE_ACCUMULATOR_STRIDE` u32s each). Apply
-// atomic-adds weighted values into it; the downstream resolve pass
-// drains it into `transforms_table.local_*`.
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
-    .addStorageBuffer('pose_accumulator', WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer('materials', WebGPUArray.from(MATERIAL_METADATA_STRUCT), true);
-
-// Strict 1:1 page-iterator dispatch: one thread per group-node slot.
-// A page is covered by GROUPS_PER_PAGE workgroups in parallel; setup
-// derives (page_index, page_group) from workgroup_id.x, the in-page
-// slot from page_group + local_id, and lanes past ELEMENTS_PER_PAGE
-// (only possible in the last page_group) are tail-masked.
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
-fn main(
-    @builtin(workgroup_id) wg_id: vec3<u32>,
-    @builtin(local_invocation_index) local_id: u32,
-) {
-    // page_address is uniform across the workgroup → unallocated-page
-    // bail is uniform-control-flow safe.
-    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
-        return;
-    }
-
-    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
-
-    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
-        return;
-    }
-    if !${PG_PREFIX}_is_occupied(slot_in_page) {
-        return;
-    }
-
-    // Per-thread group node: load it, resolve the back-referenced clip,
-    // and apply every inline binding under that clip's effective time.
-    // The chain's next field is for the host (linking new nodes onto
-    // existing chains); the apply pass touches only the current node.
-    let group = ${PG_PREFIX}_read(&animation_database, slot_in_page);
-    let clip = ${CLIP_TABLE.marshalling_method_read}(&animation_database, group.clip);
-
-    // Playback time 0 sits at clip.time_start on the curves' clock.
-    // Curves clamp the result to their own [time_min, time_max], so a
-    // track whose authored range falls outside the clip window just
-    // holds at its endpoint over the gap.
-    let effective_time = clip.time + clip.time_start;
-
-    // Pre-multiply every contribution by this clip's weight so the
-    // accumulator can just add. Translation/scale: scalar*vec3
-    // componentwise; rotation: scalar*vec4, which is the standard
-    // weighted-quaternion blend term — the resolve pass normalizes
-    // the accumulated quat sum back to unit length.
-    let weight = clip.playback_weight;
-
-    for(var i = 0u; i < group.count; i++){
-        let binding = group.bindings[i];
-        let track = ${TRACK_TABLE.marshalling_method_read}(&animation_database, binding.track);
-
-        let value = animation_track_evaluate(effective_time, track, &animation_database) * weight;
-
-        write_object_property(binding.instance, binding.property, track.mask, value);
-    }
-}
-`, [
-        GROUP_TABLE.chunk_iterate(WORKGROUP_SIZE),
-        CLIP_TABLE.chunk_read,
-        TRACK_TABLE.chunk_read,
-        chunk_animation_track_evaluate,
-        chunk_write_object_property,
-    ]
-);
-
-/**
- * Compute shader that walks the `animation_bound_track_groups` table —
- * one thread per group-node slot via the page iterator — evaluating
- * every inline binding under its owning clip's `time + time_start` and
- * atomic-adding the (weight-multiplied) result into the pose
- * accumulator (Node3D properties) or directly into the material
- * metadata table (Material properties).
- *
- * Node3D writes land in `pose_accumulator` rather than directly in
- * `transforms_table.local_*` so multi-clip blending is just additive;
- * `shader_animation_pose_resolve` walks the accumulator next, drains
- * each dirty row into the transforms table, normalizes rotation, and
- * zeros the slot for the next frame.
- *
- * Dispatch via
- * `shader_animation_apply.dispatch({ group_count_x: animation_bound_track_groups.dispatch_group_count(WORKGROUP_SIZE), ... })` —
- * the iterator covers every allocated page in parallel and skips
- * unallocated/unoccupied slots in-shader.
- */
-export const shader_animation_apply = ComputeShader.from({
-    label: "Animation/Apply",
-    body,
-    resources,
-});
+import { atomic_u32, u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { MATERIAL_METADATA_STRUCT } from "../material/MATERIAL_METADATA_STRUCT.js";
+import { chunk_write_object_property } from "../object_property/chunk_write_object_property.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ANIMATION_DATABASE_SPEC } from "./ANIMATION_DATABASE_SPEC.js";
+import { chunk_animation_track_evaluate } from "./animation_track_evaluate.js";
+
+const BINDING_TABLE = ANIMATION_DATABASE_SPEC.get('animation_bindings');
+const CLIP_TABLE = ANIMATION_DATABASE_SPEC.get('animation_clips');
+const TRACK_TABLE = ANIMATION_DATABASE_SPEC.get('animation_tracks');
+
+/**
+ * Workgroup size for the apply pass. Exported so dispatchers can pair it
+ * with `animation_bindings.dispatch_group_count(WORKGROUP_SIZE)` —
+ * the page iterator's slot-to-workgroup mapping is computed against this
+ * value, so the two must agree.
+ */
+export const WORKGROUP_SIZE = 64;
+
+const PG_PREFIX = BINDING_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE);
+
+// `materials` and `pose_accumulator` are referenced by name from the
+// property-write chunks rather than passed as pointers — the chunks
+// rely on these bindings being declared in the importing shader.
+//
+// `pose_accumulator` is the per-Node3D contribution scratch (one slot per
+// transforms-table row, `POSE_ACCUMULATOR_STRIDE` u32s each). Apply
+// atomic-adds weighted values into it; the downstream resolve pass
+// drains it into `transforms_table.local_*`.
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addStorageBuffer('animation_database', WebGPUArray.from(u32), false)
+    .addStorageBuffer('pose_accumulator', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('materials', WebGPUArray.from(MATERIAL_METADATA_STRUCT), true);
+
+// Strict 1:1 page-iterator dispatch: one thread per binding slot.
+// A page is covered by GROUPS_PER_PAGE workgroups in parallel; setup
+// derives (page_index, page_group) from workgroup_id.x, the in-page
+// slot from page_group + local_id, and lanes past ELEMENTS_PER_PAGE
+// (only possible in the last page_group) are tail-masked.
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    // page_address is uniform across the workgroup → unallocated-page
+    // bail is uniform-control-flow safe.
+    if !${PG_PREFIX}_setup(&animation_database, wg_id.x, local_id) {
+        return;
+    }
+
+    let slot_in_page = ${PG_PREFIX}_slot_in_page(local_id);
+
+    if slot_in_page >= ${PG_PREFIX}_ELEMENTS_PER_PAGE {
+        return;
+    }
+    if !${PG_PREFIX}_is_occupied(slot_in_page) {
+        return;
+    }
+
+    // Per-thread binding: load it, resolve the clip it names, and apply it
+    // under that clip's effective time.
+    let binding = ${PG_PREFIX}_read(&animation_database, slot_in_page);
+    let clip = ${CLIP_TABLE.marshalling_method_read}(&animation_database, binding.clip);
+
+    // Playback time 0 sits at clip.time_start on the curves' clock.
+    // Curves clamp the result to their own [time_min, time_max], so a
+    // track whose authored range falls outside the clip window just
+    // holds at its endpoint over the gap.
+    let effective_time = clip.time + clip.time_start;
+
+    // Pre-multiply every contribution by this clip's weight so the
+    // accumulator can just add. Translation/scale: scalar*vec3
+    // componentwise; rotation: scalar*vec4, which is the standard
+    // weighted-quaternion blend term — the resolve pass normalizes
+    // the accumulated quat sum back to unit length.
+    let weight = clip.playback_weight;
+
+    let track = ${TRACK_TABLE.marshalling_method_read}(&animation_database, binding.track);
+
+    let value = animation_track_evaluate(effective_time, track, &animation_database) * weight;
+
+    write_object_property(binding.instance, binding.property, track.mask, value, weight);
+}
+`, [
+        BINDING_TABLE.chunk_iterate(WORKGROUP_SIZE),
+        CLIP_TABLE.chunk_read,
+        TRACK_TABLE.chunk_read,
+        chunk_animation_track_evaluate,
+        chunk_write_object_property,
+    ]
+);
+
+/**
+ * Compute shader that walks the `animation_bindings` table — one thread
+ * per binding slot via the page iterator — evaluating each binding under
+ * its clip's `time + time_start` and atomic-adding the
+ * (weight-multiplied) result into the pose accumulator (Node3D
+ * properties) or directly into the material metadata table (Material
+ * properties).
+ *
+ * Node3D writes land in `pose_accumulator` rather than directly in
+ * `transforms_table.local_*` so multi-clip blending is just additive;
+ * `shader_animation_pose_resolve` walks the accumulator next, drains
+ * each dirty row into the transforms table, normalizes rotation, and
+ * zeros the slot for the next frame.
+ *
+ * One thread per binding rather than one per group of eight, with the curve's segment found by
+ * binary search rather than a walk over keyframe blocks. Measured 2026-09-25 on the
+ * skinned_blas_refit playground, 324 dancers on an RTX 4090, paired launches against the group
+ * version: 27.6 µs a frame (p10) where it took 700–1,540 µs, every launch. The poses it leaves in
+ * the transforms rows read back bit-identical to the group version's at the same clip times.
+ *
+ * Dispatch via
+ * `shader_animation_apply.dispatch({ group_count_x: animation_bindings.dispatch_group_count(WORKGROUP_SIZE), ... })` —
+ * the iterator covers every allocated page in parallel and skips
+ * unallocated/unoccupied slots in-shader.
+ */
+export const shader_animation_apply = ComputeShader.from({
+    label: "Animation/Apply",
+    body,
+    resources,
+});

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js

@@ -254,8 +254,8 @@ export class GPUMeshSkinningContext {
      * Prev-position slices handed back when a binding was dropped, bucketed by their length
      * in vertices. Each bucket is a stack of base vertex offsets free to give out again.
      *
-     * Same shape, and the same reasoning, as the skin matrix free list in
-     * {@link GPUAnimationManager}: a slice's base is written into
+     * The same reasoning as a skin's run of joints in {@link GPUAnimationManager}, whose
+     * matrices sit at its rows: a slice's base is written into
      * {@link #prev_position_offsets_cpu} per meshlet and read by the skinning pass as a flat
      * address, so a slice can be reused where it lies but never moved. Matched exactly and
      * never split — a binding placed in a shorter slice would write past it — which costs

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.d.ts

@@ -6,8 +6,9 @@
  * records, and skins every vertex of that meshlet.
  *
  * Offsets are pre-resolved at upload time:
- *  - `skin_matrix_offset` is read from the animation manager's
- *    {@link GPUAnimationManager#get_skin} so the shader can index
+ *  - `skin_matrix_offset` is the skin's first joint row, read from the
+ *    animation manager's {@link GPUAnimationManager#get_skin_matrix_offset}
+ *    — a joint's matrix sits at its row — so the shader can index
  *    `skin_matrices` directly without dereferencing the skin record.
  *  - The two `*_meshlet_metadata_offset` values are the starts of the
  *    source's and clone's meshlet ranges in the meshlet metadata

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SKINNING_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,mDAwDsB;6BA1EO,mCAAmC"}
+{"version":3,"file":"SKINNING_BINDING_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,mDAwDsB;6BA3EO,mCAAmC"}

package/src/shade/renderer/animation/skinning/SKINNING_BINDING_STRUCT.js

@@ -9,8 +9,9 @@ import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
  * records, and skins every vertex of that meshlet.
  *
  * Offsets are pre-resolved at upload time:
- *  - `skin_matrix_offset` is read from the animation manager's
- *    {@link GPUAnimationManager#get_skin} so the shader can index
+ *  - `skin_matrix_offset` is the skin's first joint row, read from the
+ *    animation manager's {@link GPUAnimationManager#get_skin_matrix_offset}
+ *    — a joint's matrix sits at its row — so the shader can index
  *    `skin_matrices` directly without dereferencing the skin record.
  *  - The two `*_meshlet_metadata_offset` values are the starts of the
  *    source's and clone's meshlet ranges in the meshlet metadata

package/src/shade/renderer/animation/skinning/shader_skin_matrix_prep.d.ts

@@ -1,24 +1,29 @@
 /**
  * Workgroup size for the skin-matrix-prep pass. Exported so dispatchers
  * can pair it with
- * `animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE)` —
+ * `animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE)` —
  * the page iterator's slot-to-workgroup mapping is computed against
  * this value, so the two must agree.
  */
 export const WORKGROUP_SIZE: 64;
 /**
- * Compute shader that walks the `animation_skin_joint_blocks` table —
- * one thread per joint-block slot via the page iterator — and writes
- * each joint's per-frame skinning matrix `node.global * inverse_bind`
- * to the shared `skin_matrices` scratch buffer at the block's pre-baked
- * absolute offset.
+ * Compute shader that walks the `animation_skin_joints` table — one
+ * thread per joint slot via the page iterator — and writes each joint's
+ * per-frame skinning matrix `node.global * inverse_bind` to the shared
+ * `skin_matrices` scratch buffer at the joint's row. A skin's joints are
+ * a run of rows, so its matrices are the same run of the buffer, starting
+ * at its `joints_first`. A joint with no node yet is skipped.
  *
  * Run after `graph_scene_update_transform_hierarchy` (so each joint's
  * `node.global` is up to date) and before any pass that consumes the
  * skin matrices (the pre-skinning compute pass).
  *
+ * One thread per joint rather than one per block of eight. Measured 2026-09-25, the 21,060 joints
+ * of 324 skins on an RTX 4090, paired launches against the block version: 5.1 µs a frame where it
+ * took 9.2, and the matrices read back within 2e-6 of the block version's.
+ *
  * Dispatch via
- * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joint_blocks.dispatch_group_count(WORKGROUP_SIZE), ... })`.
+ * `shader_skin_matrix_prep.dispatch({ group_count_x: animation_skin_joints.dispatch_group_count(WORKGROUP_SIZE), ... })`.
  * Skip the dispatch when `group_count_x === 0` — no skins registered
  * means the iterator has no work and `skin_matrices_buffer` may be
  * `null` on the manager.

package/src/shade/renderer/animation/skinning/shader_skin_matrix_prep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_skin_matrix_prep.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/shader_skin_matrix_prep.js"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,gCAAiC;AAiEjC;;;;;;;;;;;;;;;;GAgBG;AACH,oDAIG;8BAnG2B,+BAA+B"}
+{"version":3,"file":"shader_skin_matrix_prep.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/shader_skin_matrix_prep.js"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,gCAAiC;AA8DjC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,oDAIG;8BArG2B,+BAA+B"}