@woosh/meep-engine 3.52.0 → 3.53.0

package/src/shade/renderer/animation/foliage/chunk_foliage_wind_step.js

@@ -0,0 +1,143 @@
+import { chunk_mat4_extract_scale } from "../../shader/chunk/geometry/mat4/chunk_mat4_extract_scale.js";
+import { chunk_build_orthonormal_matrix_n } from "../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_n.js";
+import { chunk_quat_from_axis_angle } from "../../shader/chunk/geometry/quaternion/chunk_quat_from_axis_angle.js";
+import { chunk_quat_multiply } from "../../shader/chunk/geometry/quaternion/chunk_quat_multiply.js";
+import { QUAT_IDENTITY_DEFINITION } from "../../shader/chunk/geometry/quaternion/QUAT_IDENTITY_DEFINITION.js";
+import { chunk_pow2 } from "../../shader/chunk/math/chunk_pow2.js";
+import { chunk_v3_safe_rcp } from "../../shader/chunk/math/chunk_safe_rcp.js";
+import { EPSILON_DECLARATION } from "../../shader/chunk/math/EPSILON_DECLARATION.js";
+import { GOLDEN_ANGLE_DECLARATION } from "../../shader/chunk/math/GOLDEN_ANGLE_DECLARATION.js";
+import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ANIMATION_FOLIAGE_JOINT_STRUCT } from "../ANIMATION_FOLIAGE_JOINT_STRUCT.js";
+
+/**
+ * Aeroelastic foliage bone step and local pose composition.
+ *
+ * - `foliage_wind_to_model(wind_ws, root_global)`: projects a world-space fluid velocity (m/s)
+ *   onto the unit local axes of the tree root's world matrix (`mat4_extract_scale` + `v3_safe_rcp`),
+ *   preserving metric wind speed regardless of node scale.
+ * - `foliage_wind_step(joint, wind_model, dt)`: evaluates cross-flow aerodynamic drag torque and
+ *   Strouhal vortex-shedding oscillation around the bone's rest `branch_axis` (using
+ *   `build_orthonormal_matrix_n` when flow is axial), soft-saturates the target deflection to
+ *   `joint.max_angle`, and advances the bone's 2nd-order damped spring-damper state with an
+ *   unconditionally stable implicit Euler step.
+ * - `foliage_wind_local_rotation(rest_rotation, angular_displacement)`: composes the bone's
+ *   rest quaternion with the axis-angle deflection (`quat_from_axis_angle` + `quat_multiply`).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_foliage_wind_step = CodeChunk.from(
+    //language=WGSL
+    `
+struct FoliageWindStepResult {
+    angular_displacement: vec3<f32>,
+    angular_velocity: vec3<f32>,
+    flutter_phase: f32,
+}
+
+fn foliage_wind_to_model(wind_ws: vec3<f32>, root_global: mat4x4<f32>) -> vec3<f32> {
+    let inv_scale = v3_safe_rcp(mat4_extract_scale(root_global));
+    return vec3<f32>(
+        dot(wind_ws, root_global[0].xyz),
+        dot(wind_ws, root_global[1].xyz),
+        dot(wind_ws, root_global[2].xyz),
+    ) * inv_scale;
+}
+
+fn foliage_wind_step(
+    joint: ${ANIMATION_FOLIAGE_JOINT_STRUCT.wgsl_ref},
+    wind_model: vec3<f32>,
+    dt: f32,
+) -> FoliageWindStepResult {
+    var theta_new = joint.angular_displacement;
+    var vel_new = joint.angular_velocity;
+    var phase_new = joint.flutter_phase;
+
+    if (joint.compliance > 0.0 && dt > 0.0) {
+        let axis = joint.branch_axis;
+        let wind_speed = length(wind_model);
+        let omega = max(joint.natural_frequency, 0.1);
+
+        // Strouhal vortex-shedding phase advance, wrapped to [0, 2π)
+        let tau = 2.0 * PI;
+        phase_new = phase_new + omega * (1.0 + 0.22 * wind_speed) * dt;
+        phase_new = phase_new - floor(phase_new / tau) * tau;
+
+        // Cross-flow aerodynamic drag torque: bends branch toward local fluid flow
+        let cross_drag = cross(axis, wind_model);
+        let drag_torque = cross_drag * (joint.compliance * (0.5 + 0.5 * wind_speed));
+
+        // Turbulent vortex-shedding oscillation (streamwise buffeting + cross-wind lift)
+        var vortex_torque = vec3<f32>(0.0);
+        if (wind_speed > EPSILON && joint.turbulence > 0.0) {
+            let drag_len = length(cross_drag);
+            var e1: vec3<f32>;
+            var e2: vec3<f32>;
+            if (drag_len > EPSILON) {
+                e1 = cross_drag / drag_len;
+                e2 = cross(axis, e1);
+            } else {
+                let basis = build_orthonormal_matrix_n(axis);
+                e1 = basis[0];
+                e2 = basis[1];
+            }
+            let vortex_amp = joint.turbulence * min(
+                wind_speed * joint.compliance * (0.6 + 0.25 * wind_speed),
+                0.45 * joint.max_angle,
+            );
+            vortex_torque = vortex_amp * (
+                sin(phase_new) * e1 +
+                0.65 * cos(GOLDEN_ANGLE * phase_new + 1.1) * e2
+            );
+        }
+
+        let theta_raw = drag_torque + vortex_torque;
+        let raw_len = length(theta_raw);
+        let max_ang = max(joint.max_angle, 1e-3);
+        var theta_target = theta_raw;
+        if (raw_len > EPSILON) {
+            // Asymptotic soft saturation so extreme fluid impulses bend smoothly up to max_angle
+            theta_target = theta_raw * (max_ang / (max_ang + raw_len));
+        }
+
+        // Unconditionally stable implicit 2nd-order damped spring-damper step
+        let zeta = max(joint.damping_ratio, 0.05);
+        let k = pow2(omega);
+        let c = 2.0 * zeta * omega;
+        let denom = 1.0 + c * dt + k * pow2(dt);
+
+        vel_new = (vel_new + k * dt * (theta_target - theta_new)) / denom;
+        theta_new = theta_new + vel_new * dt;
+
+        let new_len = length(theta_new);
+        if (new_len > max_ang) {
+            theta_new = theta_new * (max_ang / new_len);
+        }
+    }
+
+    return FoliageWindStepResult(theta_new, vel_new, phase_new);
+}
+
+fn foliage_wind_local_rotation(rest_rotation: vec4<f32>, angular_displacement: vec3<f32>) -> vec4<f32> {
+    let angle = length(angular_displacement);
+    var q_delta = QUAT_IDENTITY;
+    if (angle > EPSILON) {
+        q_delta = quat_from_axis_angle(angular_displacement / angle, angle);
+    }
+    return quat_multiply(rest_rotation, q_delta);
+}
+`, [
+        ANIMATION_FOLIAGE_JOINT_STRUCT.declaration_chunk,
+        PI_DECLARATION,
+        GOLDEN_ANGLE_DECLARATION,
+        EPSILON_DECLARATION,
+        QUAT_IDENTITY_DEFINITION,
+        chunk_pow2,
+        chunk_v3_safe_rcp,
+        chunk_mat4_extract_scale,
+        chunk_build_orthonormal_matrix_n,
+        chunk_quat_from_axis_angle,
+        chunk_quat_multiply,
+    ]
+);

package/src/shade/renderer/animation/foliage/shader_foliage_wind_apply.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Workgroup size for the GPU foliage fluid wind bone pass.
+ * Paired with `animation_foliage_joints.dispatch_group_count(WORKGROUP_SIZE)`.
+ */
+export const WORKGROUP_SIZE: 64;
+/**
+ * Compute shader that evaluates aeroelastic foliage bones (`animation_foliage_joints`) against
+ * the scene's 3D fluid dynamics wind field (`GPUSceneWind` / `wind_field_sample`), steps each
+ * bone's 2nd-order damped spring-damper state (`chunk_foliage_wind_step`), and atomic-adds
+ * weighted local rotations into `pose_accumulator` ahead of `shader_animation_pose_resolve`.
+ */
+export const shader_foliage_wind_apply: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_foliage_wind_apply.d.ts.map

package/src/shade/renderer/animation/foliage/shader_foliage_wind_apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_foliage_wind_apply.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/foliage/shader_foliage_wind_apply.js"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,gCAAiC;AAoFjC;;;;;GAKG;AACH,sDAIG;8BA/G2B,+BAA+B"}

package/src/shade/renderer/animation/foliage/shader_foliage_wind_apply.js

@@ -0,0 +1,116 @@
+import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { chunk_mat4_extract_position } from "../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_wind_field_sample } from "../../wind/chunk_wind_field_sample.js";
+import { wind_field_add_resources } from "../../wind/wind_field_add_resources.js";
+import { ANIMATION_DATABASE_SPEC } from "../ANIMATION_DATABASE_SPEC.js";
+import { chunk_pose_accumulator } from "../chunk_pose_accumulator.js";
+import { chunk_foliage_wind_step } from "./chunk_foliage_wind_step.js";
+
+const JOINT_TABLE = ANIMATION_DATABASE_SPEC.get('animation_foliage_joints');
+const RIG_TABLE = ANIMATION_DATABASE_SPEC.get('animation_foliage_rigs');
+
+/**
+ * Workgroup size for the GPU foliage fluid wind bone pass.
+ * Paired with `animation_foliage_joints.dispatch_group_count(WORKGROUP_SIZE)`.
+ */
+export const WORKGROUP_SIZE = 64;
+
+const PG_PREFIX = JOINT_TABLE.page_iterator_symbol_prefix(WORKGROUP_SIZE, true);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("dt", f32);
+
+wind_field_add_resources(
+    resources.createGroup()
+        .addStorageBuffer('scene_database', WebGPUArray.from(u32), false)
+        .addStorageBuffer('animation_database', WebGPUArray.from(u32), true)
+        .addStorageBuffer('pose_accumulator', WebGPUArray.from(atomic_u32), true)
+);
+
+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,
+) {
+    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;
+    }
+
+    let joint = ${PG_PREFIX}_read(&animation_database, slot_in_page);
+
+    if joint.node == ${GPU_DATABASE_NULL}u {
+        return;
+    }
+
+    let rig = ${RIG_TABLE.marshalling_method_read_rw}(&animation_database, joint.rig);
+
+    if rig.root_node == ${GPU_DATABASE_NULL}u || rig.weight <= 0.0 {
+        return;
+    }
+
+    let joint_node = scene_read_node(&scene_database, joint.node);
+    let root_node = scene_read_node(&scene_database, rig.root_node);
+
+    // Sample 3D fluid velocity (m/s) at the bone's world position and project into the tree root's model frame
+    let pos_ws = mat4_extract_position(joint_node.global);
+    let wind_ws = wind_field_sample(pos_ws);
+    let wind_model = foliage_wind_to_model(wind_ws, root_node.global);
+
+    let stepped = foliage_wind_step(joint, wind_model, dt);
+
+    if joint.compliance > 0.0 && dt > 0.0 {
+        let joint_row = ${PG_PREFIX}_slot_to_index(slot_in_page);
+        ${JOINT_TABLE.marshalling_method_write_field('angular_displacement')}(&animation_database, joint_row, stepped.angular_displacement);
+        ${JOINT_TABLE.marshalling_method_write_field('angular_velocity')}(&animation_database, joint_row, stepped.angular_velocity);
+        ${JOINT_TABLE.marshalling_method_write_field('flutter_phase')}(&animation_database, joint_row, stepped.flutter_phase);
+    }
+
+    let q_local = foliage_wind_local_rotation(joint.rest_rotation, stepped.angular_displacement);
+    let w = rig.weight;
+
+    pose_accumulator_add_rotation(joint.node, q_local * w, 0xFu, w, joint.rest_rotation);
+}
+`, [
+        JOINT_TABLE.chunk_iterate(WORKGROUP_SIZE, true),
+        JOINT_TABLE.wgsl_gen_write_field_code('angular_displacement'),
+        JOINT_TABLE.wgsl_gen_write_field_code('angular_velocity'),
+        JOINT_TABLE.wgsl_gen_write_field_code('flutter_phase'),
+        RIG_TABLE.chunk_read_rw,
+        chunk_scene_database_access,
+        chunk_mat4_extract_position,
+        chunk_wind_field_sample,
+        chunk_foliage_wind_step,
+        chunk_pose_accumulator,
+    ]
+);
+
+/**
+ * Compute shader that evaluates aeroelastic foliage bones (`animation_foliage_joints`) against
+ * the scene's 3D fluid dynamics wind field (`GPUSceneWind` / `wind_field_sample`), steps each
+ * bone's 2nd-order damped spring-damper state (`chunk_foliage_wind_step`), and atomic-adds
+ * weighted local rotations into `pose_accumulator` ahead of `shader_animation_pose_resolve`.
+ */
+export const shader_foliage_wind_apply = ComputeShader.from({
+    label: "Animation/FoliageWindApply",
+    body,
+    resources,
+});

package/src/shade/renderer/animation/pose/pose_evaluate_local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pose_evaluate_local.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/pose/pose_evaluate_local.js"],"names":[],"mappings":"AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iEALW,MAAM,gCAEN,cAAc,eAsJxB;oCAjPY,OAAO,6BAA6B,EAAE,qBAAqB"}
+{"version":3,"file":"pose_evaluate_local.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/pose/pose_evaluate_local.js"],"names":[],"mappings":"AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iEALW,MAAM,gCAEN,cAAc,eAgKxB;oCA3PY,OAAO,6BAA6B,EAAE,qBAAqB"}

package/src/shade/renderer/animation/pose/pose_evaluate_local.js

@@ -118,6 +118,19 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
 
     let dirty = 0;
 
+    const rest_tx = rest.translation_x;
+    const rest_ty = rest.translation_y;
+    const rest_tz = rest.translation_z;
+
+    const rest_rx = rest.rotation_x;
+    const rest_ry = rest.rotation_y;
+    const rest_rz = rest.rotation_z;
+    const rest_rw = rest.rotation_w;
+
+    const rest_sx = rest.scale_x;
+    const rest_sy = rest.scale_y;
+    const rest_sz = rest.scale_z;
+
     for (let p = 0; p < playbacks.length; p++) {
         const playback = playbacks[p];
         const index = playback.channel_index;
@@ -152,15 +165,15 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
             switch (channel.property) {
                 case Node3DProperty.Translation: {
                     if (curves.x !== undefined) {
-                        SUM_TRANSLATION[0] += curves.x.evaluate(time) * weight;
+                        SUM_TRANSLATION[0] += (curves.x.evaluate(time) - rest_tx) * weight;
                         dirty |= DIRTY_TX;
                     }
                     if (curves.y !== undefined) {
-                        SUM_TRANSLATION[1] += curves.y.evaluate(time) * weight;
+                        SUM_TRANSLATION[1] += (curves.y.evaluate(time) - rest_ty) * weight;
                         dirty |= DIRTY_TY;
                     }
                     if (curves.z !== undefined) {
-                        SUM_TRANSLATION[2] += curves.z.evaluate(time) * weight;
+                        SUM_TRANSLATION[2] += (curves.z.evaluate(time) - rest_tz) * weight;
                         dirty |= DIRTY_TZ;
                     }
                     break;
@@ -175,10 +188,10 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
                     const qz = curves.z !== undefined ? curves.z.evaluate(time) : 0;
                     const qw = curves.w !== undefined ? curves.w.evaluate(time) : 1;
 
-                    SUM_ROTATION[0] += qx * weight;
-                    SUM_ROTATION[1] += qy * weight;
-                    SUM_ROTATION[2] += qz * weight;
-                    SUM_ROTATION[3] += qw * weight;
+                    SUM_ROTATION[0] += (qx - rest_rx) * weight;
+                    SUM_ROTATION[1] += (qy - rest_ry) * weight;
+                    SUM_ROTATION[2] += (qz - rest_rz) * weight;
+                    SUM_ROTATION[3] += (qw - rest_rw) * weight;
 
                     dirty |= DIRTY_R;
                     break;
@@ -186,15 +199,15 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
 
                 case Node3DProperty.Scale: {
                     if (curves.x !== undefined) {
-                        SUM_SCALE[0] += curves.x.evaluate(time) * weight;
+                        SUM_SCALE[0] += (curves.x.evaluate(time) - rest_sx) * weight;
                         dirty |= DIRTY_SX;
                     }
                     if (curves.y !== undefined) {
-                        SUM_SCALE[1] += curves.y.evaluate(time) * weight;
+                        SUM_SCALE[1] += (curves.y.evaluate(time) - rest_sy) * weight;
                         dirty |= DIRTY_SY;
                     }
                     if (curves.z !== undefined) {
-                        SUM_SCALE[2] += curves.z.evaluate(time) * weight;
+                        SUM_SCALE[2] += (curves.z.evaluate(time) - rest_sz) * weight;
                         dirty |= DIRTY_SZ;
                     }
                     break;
@@ -207,29 +220,26 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
     }
 
     result.setTranslation(
-        (dirty & DIRTY_TX) !== 0 ? SUM_TRANSLATION[0] : rest.translation_x,
-        (dirty & DIRTY_TY) !== 0 ? SUM_TRANSLATION[1] : rest.translation_y,
-        (dirty & DIRTY_TZ) !== 0 ? SUM_TRANSLATION[2] : rest.translation_z,
+        (dirty & DIRTY_TX) !== 0 ? rest_tx + SUM_TRANSLATION[0] : rest_tx,
+        (dirty & DIRTY_TY) !== 0 ? rest_ty + SUM_TRANSLATION[1] : rest_ty,
+        (dirty & DIRTY_TZ) !== 0 ? rest_tz + SUM_TRANSLATION[2] : rest_tz,
     );
 
     result.setScale(
-        (dirty & DIRTY_SX) !== 0 ? SUM_SCALE[0] : rest.scale_x,
-        (dirty & DIRTY_SY) !== 0 ? SUM_SCALE[1] : rest.scale_y,
-        (dirty & DIRTY_SZ) !== 0 ? SUM_SCALE[2] : rest.scale_z,
+        (dirty & DIRTY_SX) !== 0 ? rest_sx + SUM_SCALE[0] : rest_sx,
+        (dirty & DIRTY_SY) !== 0 ? rest_sy + SUM_SCALE[1] : rest_sy,
+        (dirty & DIRTY_SZ) !== 0 ? rest_sz + SUM_SCALE[2] : rest_sz,
     );
 
     if ((dirty & DIRTY_R) !== 0) {
-        const x = SUM_ROTATION[0];
-        const y = SUM_ROTATION[1];
-        const z = SUM_ROTATION[2];
-        const w = SUM_ROTATION[3];
-
-        // A quaternion sum of length zero has no orientation in it to recover. The ordinary way in
-        // is a joint whose rotation only clips at weight zero write — the accumulator takes a bound
-        // clip's contribution whatever its weight — and the other is contributions that cancelled
-        // exactly. The answer is the rest pose: the GPU writes the rest rotation every
-        // contribution carried from its binding, which was taken from this same rest when the clip
-        // bound the target.
+        const x = rest_rx + SUM_ROTATION[0];
+        const y = rest_ry + SUM_ROTATION[1];
+        const z = rest_rz + SUM_ROTATION[2];
+        const w = rest_rw + SUM_ROTATION[3];
+
+        // Reconstruct `rest_r + sum(w_i * (q_i - rest_r))` and normalise. If the
+        // reconstructed vector cancels to zero length (e.g. an antipodal contribution
+        // at weight 1), fall back to `rest_r` to match the GPU resolve shader.
         const length = Math.sqrt(x * x + y * y + z * z + w * w);
 
         if (length > 0) {
@@ -237,10 +247,10 @@ export function pose_evaluate_local(result, target, rest, playbacks) {
 
             result.setRotation(x * scale, y * scale, z * scale, w * scale);
         } else {
-            result.setRotation(rest.rotation_x, rest.rotation_y, rest.rotation_z, rest.rotation_w);
+            result.setRotation(rest_rx, rest_ry, rest_rz, rest_rw);
         }
     } else {
-        result.setRotation(rest.rotation_x, rest.rotation_y, rest.rotation_z, rest.rotation_w);
+        result.setRotation(rest_rx, rest_ry, rest_rz, rest_rw);
     }
 
     return result;

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

@@ -63,24 +63,27 @@ fn main(
     // ── Translation ───────────────────────────────────────────────
     if (dirty & POSE_DIRTY_T_MASK) != 0u {
         let t_base = slot_base + POSE_OFFSET_TRANSLATION;
+        let rest_t_base = slot_base + POSE_OFFSET_REST_TRANSLATION;
         // Per-axis: only overwrite the channels that actually had a
-        // contribution. Read the current local_translation through
-        // the rw helper and patch the dirty channels in-place — the
-        // sibling-axis race that the old direct writer already
-        // tolerated still applies (two threads writing different
-        // axes of the same node), but we now have at most one resolve
-        // thread per row, so it never triggers here.
+        // contribution. Reconstruct rest_t + delta_t on each dirty
+        // axis and leave undirty axes untouched.
         var t = scene_read_node_rw(&scene_database, row).local_translation;
         if (dirty & POSE_DIRTY_TX) != 0u {
-            t.x = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 0u]));
+            let delta_x = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 0u]));
+            let rest_x = bitcast<f32>(atomicLoad(&pose_accumulator[rest_t_base + 0u]));
+            t.x = rest_x + delta_x;
             atomicStore(&pose_accumulator[t_base + 0u], 0u);
         }
         if (dirty & POSE_DIRTY_TY) != 0u {
-            t.y = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 1u]));
+            let delta_y = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 1u]));
+            let rest_y = bitcast<f32>(atomicLoad(&pose_accumulator[rest_t_base + 1u]));
+            t.y = rest_y + delta_y;
             atomicStore(&pose_accumulator[t_base + 1u], 0u);
         }
         if (dirty & POSE_DIRTY_TZ) != 0u {
-            t.z = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 2u]));
+            let delta_z = bitcast<f32>(atomicLoad(&pose_accumulator[t_base + 2u]));
+            let rest_z = bitcast<f32>(atomicLoad(&pose_accumulator[rest_t_base + 2u]));
+            t.z = rest_z + delta_z;
             atomicStore(&pose_accumulator[t_base + 2u], 0u);
         }
         scene_write_node_local_translation(&scene_database, row, t);
@@ -89,7 +92,7 @@ fn main(
     // ── Rotation ──────────────────────────────────────────────────
     if (dirty & POSE_DIRTY_R) != 0u {
         let r_base = slot_base + POSE_OFFSET_ROTATION;
-        let r = vec4<f32>(
+        let delta = vec4<f32>(
             bitcast<f32>(atomicLoad(&pose_accumulator[r_base + 0u])),
             bitcast<f32>(atomicLoad(&pose_accumulator[r_base + 1u])),
             bitcast<f32>(atomicLoad(&pose_accumulator[r_base + 2u])),
@@ -99,33 +102,23 @@ fn main(
         atomicStore(&pose_accumulator[r_base + 1u], 0u);
         atomicStore(&pose_accumulator[r_base + 2u], 0u);
         atomicStore(&pose_accumulator[r_base + 3u], 0u);
-        // The weighted-quaternion sum (\`w_i * q_i\`) is the standard
-        // nlerp blend numerator; normalise here, once, after every
-        // contributor has been folded in. The apply pass canonicalised
-        // signs at GLTF load so we don't hit the antipode case for
-        // imported clips.
-        //
-        // A sum of length zero carries no orientation to recover: every
-        // clip that writes this rotation is playing at weight zero — a
-        // faded-out clip keeps its binding, and the apply pass
-        // contributes to a bound clip whatever its weight — or the
-        // contributions cancelled exactly. \`normalize\` answers NaN there,
-        // and one NaN local rotation reaches every skin matrix naming the
-        // joint, so the meshes it drives stop rasterising altogether. Nor
-        // can the row be left alone: once a clip has written it, it holds
-        // that clip's last pose, not the rest. The answer is the rest
-        // rotation, which every contribution carried into the slot from
-        // its binding — what the CPU twin (\`pose_evaluate_local\`) gives.
+
+        let rest_base = slot_base + POSE_OFFSET_REST_ROTATION;
+        let rest = vec4<f32>(
+            bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 0u])),
+            bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 1u])),
+            bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 2u])),
+            bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 3u])),
+        );
+
+        // Reconstruct rest + sum(w_i * (q_i - rest)) and normalise once
+        // after every contributor has been folded in. If the reconstructed
+        // vector cancels to zero length (e.g. an antipodal contribution at
+        // weight 1), fall back to rest to avoid NaN propagation.
+        let r = rest + delta;
         if length(r) > 0.0 {
             scene_write_node_local_rotation(&scene_database, row, normalize(r));
         } else {
-            let rest_base = slot_base + POSE_OFFSET_REST_ROTATION;
-            let rest = vec4<f32>(
-                bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 0u])),
-                bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 1u])),
-                bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 2u])),
-                bitcast<f32>(atomicLoad(&pose_accumulator[rest_base + 3u])),
-            );
             scene_write_node_local_rotation(&scene_database, row, rest);
         }
     }
@@ -133,17 +126,24 @@ fn main(
     // ── Scale ─────────────────────────────────────────────────────
     if (dirty & POSE_DIRTY_S_MASK) != 0u {
         let s_base = slot_base + POSE_OFFSET_SCALE;
+        let rest_s_base = slot_base + POSE_OFFSET_REST_SCALE;
         var s = scene_read_node_rw(&scene_database, row).local_scale;
         if (dirty & POSE_DIRTY_SX) != 0u {
-            s.x = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 0u]));
+            let delta_x = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 0u]));
+            let rest_x = bitcast<f32>(atomicLoad(&pose_accumulator[rest_s_base + 0u]));
+            s.x = rest_x + delta_x;
             atomicStore(&pose_accumulator[s_base + 0u], 0u);
         }
         if (dirty & POSE_DIRTY_SY) != 0u {
-            s.y = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 1u]));
+            let delta_y = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 1u]));
+            let rest_y = bitcast<f32>(atomicLoad(&pose_accumulator[rest_s_base + 1u]));
+            s.y = rest_y + delta_y;
             atomicStore(&pose_accumulator[s_base + 1u], 0u);
         }
         if (dirty & POSE_DIRTY_SZ) != 0u {
-            s.z = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 2u]));
+            let delta_z = bitcast<f32>(atomicLoad(&pose_accumulator[s_base + 2u]));
+            let rest_z = bitcast<f32>(atomicLoad(&pose_accumulator[rest_s_base + 2u]));
+            s.z = rest_z + delta_z;
             atomicStore(&pose_accumulator[s_base + 2u], 0u);
         }
         scene_write_node_local_scale(&scene_database, row, s);

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

@@ -108,8 +108,8 @@ const MESHLET_STRIDE_BYTES = MESHLET_METADATA_STRUCT.aligned_size;
  * manager. Resolution happens at upload time via
  * `animation_manager.get_skin_matrix_offset(skin_id)`.
  */
-export class GPUMeshSkinningContext {
-
+export class GPUMeshSkinningContext {
+
     /** @type {GPUDevice} */
     #device;
 

package/src/shade/renderer/extension/RenderExtension.d.ts

@@ -59,6 +59,13 @@ export class RenderExtension {
      * @param {FrameContext} frame
      */
     record(frame: FrameContext): void;
+    /**
+     * Offer the pipelines this extension's passes dispatch or draw with — see
+     * {@link PipelineEnquiry}.
+     *
+     * @param {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry: import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry): void;
 }
 export type FrameContext = import("./FrameContext.js").FrameContext;
 import { FramePhase } from "./FramePhase.js";

package/src/shade/renderer/extension/RenderExtension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderExtension.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtension.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IACI;;;;;;;;;;OAUG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,OAFU,UAAU,CAEiB;IAErC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;;OASG;IACH,cAFW,YAAY,QAGtB;CACJ;2BAjEY,OAAO,mBAAmB,EAAE,YAAY;2BAH1B,iBAAiB"}
+{"version":3,"file":"RenderExtension.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtension.js"],"names":[],"mappings":"AAEA;;GAEG;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IACI;;;;;;;;;;OAUG;IACH,MAFU,MAAM,CAEN;IAEV;;OAEG;IACH,OAFU,UAAU,CAEiB;IAErC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;;OASG;IACH,cAFW,YAAY,QAGtB;IAED;;;;;OAKG;IACH,0BAFW,OAAO,0CAA0C,EAAE,eAAe,QAG5E;CACJ;2BA1EY,OAAO,mBAAmB,EAAE,YAAY;2BAH1B,iBAAiB"}

package/src/shade/renderer/extension/RenderExtension.js

@@ -66,4 +66,13 @@ export class RenderExtension {
      */
     record(frame) {
     }
+
+    /**
+     * Offer the pipelines this extension's passes dispatch or draw with — see
+     * {@link PipelineEnquiry}.
+     *
+     * @param {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry) {
+    }
 }

package/src/shade/renderer/extension/RenderExtensionRegistry.d.ts

@@ -36,6 +36,12 @@ export class RenderExtensionRegistry {
      * @returns {number} how many extensions are registered on `phase`
      */
     count(phase: FramePhase): number;
+    /**
+     * Offer the pipelines of every registered extension, in phase and resolved order.
+     *
+     * @param {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry: import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry): void;
     /**
      * Record every extension registered on `frame.phase`, in resolved order, each inside a graph
      * scope named after it.

package/src/shade/renderer/extension/RenderExtensionRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RenderExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtensionRegistry.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH;IAqBI;;;;;;;;;OASG;IACH,iDAcC;IAED;;;;;;OAMG;IACH,oCAFa,OAAO,CAsBnB;IAED;;;OAGG;IACH,aAHW,UAAU,GACR,MAAM,CAOlB;IAED;;;;;;;;;OASG;IACH,+BA0CC;;CACJ;2BAhK4C,iBAAiB"}
+{"version":3,"file":"RenderExtensionRegistry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/extension/RenderExtensionRegistry.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH;IAqBI;;;;;;;;;OASG;IACH,iDAcC;IAED;;;;;;OAMG;IACH,oCAFa,OAAO,CAsBnB;IAED;;;OAGG;IACH,aAHW,UAAU,GACR,MAAM,CAOlB;IAED;;;;OAIG;IACH,0BAFW,OAAO,0CAA0C,EAAE,eAAe,QAU5E;IAED;;;;;;;;;OASG;IACH,+BA0CC;;CACJ;2BA/K4C,iBAAiB"}

package/src/shade/renderer/extension/RenderExtensionRegistry.js

@@ -106,6 +106,21 @@ export class RenderExtensionRegistry {
         return this.#resolved[phase].length;
     }
 
+    /**
+     * Offer the pipelines of every registered extension, in phase and resolved order.
+     *
+     * @param {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    enquirePipelines(enquiry) {
+        for (let phase = 0; phase < PHASE_COUNT; phase++) {
+            const extensions = this.#resolved[phase];
+
+            for (let i = 0; i < extensions.length; i++) {
+                extensions[i].enquirePipelines?.(enquiry);
+            }
+        }
+    }
+
     /**
      * Record every extension registered on `frame.phase`, in resolved order, each inside a graph
      * scope named after it.

package/src/shade/renderer/fluid/GPUFluidCascade.d.ts

@@ -131,6 +131,13 @@ export const GPU_FLUID_CASCADE_GROWTH_EXPONENT_LIMIT: number;
  * solve's inputs live in retained records, and several steps may be recorded into one graph.
  */
 export class GPUFluidCascade {
+    /**
+     * Offer the compute pipelines a cascade's step, scroll fill, and child restriction dispatch —
+     * see {@link PipelineEnquiry}.
+     *
+     * @param {import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: import("../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry): void;
     /**
      * @param {object} record
      * @param {*} _resources