@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,414 +1,414 @@
-import { assert } from "../../../core/assert.js";
-import {
-    animation_curve_optimize
-} from "../../../engine/animation/curve/animation_curve_optimize.js";
-import { Quaternion } from "../../../core/geom/Quaternion.js";
-import {
-    TRANSFORM64_ROTATION_OFFSET,
-    TRANSFORM64_SCALE_OFFSET,
-    TRANSFORM64_TRANSLATION_OFFSET
-} from "../../../engine/ecs/transform/Transform64.js";
-import { Node3DProperty } from "../object_property/Node3DProperty.js";
-
-/**
- * Somewhere to normalise a quaternion before it lands on a transform — {@link Transform64} takes a
- * unit quaternion and does not normalise for you, and {@link Quaternion} already knows how.
- *
- * @type {Quaternion}
- */
-const SCRATCH_ROTATION = new Quaternion();
-
-/**
- * Tolerance for "is this value the identity?" comparisons inside
- * {@link ShadeAnimationChannel#optimize}. Picked at 1e-5 because:
- *  - Position units are typically metres → 1e-5 is sub-millimetre.
- *  - Rotation components are in [-1, 1] → well below the visual
- *    threshold of any reasonable per-frame quaternion change.
- *  - Scale factors are typically near 1 → 1e-5 is one part in a
- *    hundred thousand, far tighter than authoring tools quantise.
- *
- * Source-side `AnimationCurve` keyframe values are f32 (the f16
- * encoding only enters at GPU upload time), so f32 round-trip
- * noise is the only thing this needs to tolerate.
- *
- * @type {number}
- */
-const IDENTITY_EPSILON = 1e-5;
-
-/**
- * Strictly-constant check: every keyframe's `value` matches
- * `expected_value` AND both tangents are zero (within
- * {@link IDENTITY_EPSILON}). The cubic Hermite spline between two
- * keyframes with equal values and zero tangents is guaranteed to
- * stay at that value across the interpolation interval — non-zero
- * tangents would cause overshoot away from the value, so we can't
- * declare such a curve "constant" even if the keyframe values
- * happen to match.
- *
- * @param {AnimationCurve} curve
- * @param {number} expected_value
- * @returns {boolean}
- */
-function is_curve_constant(curve, expected_value) {
-    const keys = curve.keys;
-    for (let i = 0; i < keys.length; i++) {
-        const k = keys[i];
-        if (Math.abs(k.value - expected_value) > IDENTITY_EPSILON) return false;
-        if (Math.abs(k.inTangent) > IDENTITY_EPSILON) return false;
-        if (Math.abs(k.outTangent) > IDENTITY_EPSILON) return false;
-    }
-    return true;
-}
-
-/**
- * @typedef {object} ChannelCurves
- * Per-component curves keyed by the GPU track's `(x, y, z, w)`
- * channels. Slots omitted (or set to `undefined`) leave that
- * component unanimated — the GPU track's per-component mask drops
- * the corresponding write.
- *
- * @property {AnimationCurve} [x]
- * @property {AnimationCurve} [y]
- * @property {AnimationCurve} [z]
- * @property {AnimationCurve} [w]
- */
-
-/**
- * One binding inside a {@link ShadeAnimationClip}: a single target
- * Node3D, the property of that node being animated, and the
- * per-component curves driving each scalar slot.
- *
- * Curve slots are property-specific and align with the GPU track's
- * `(x, y, z, w)` channels:
- *
- *  - {@link Node3DProperty.Translation}: `x`, `y`, `z` (no `w`)
- *  - {@link Node3DProperty.Scale}: `x`, `y`, `z` (no `w`)
- *  - {@link Node3DProperty.Rotation}: quaternion `x`, `y`, `z`, `w`
- *
- * An absent slot means "this component isn't animated"; the GPU
- * track's per-component mask drops the corresponding write.
- * Rotation tracks should supply all four channels — the shader
- * writes the quaternion as a whole, not per-component; missing
- * slots fall back to identity values (0/0/0/1) so the result is
- * still a valid unit quaternion after normalise.
- *
- * Pure CPU data. Knows nothing about the GPU; consumed by
- * {@link GPUAnimationManager#register_clip}, which resolves the
- * target to a transforms-table row and uploads the curves.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ShadeAnimationChannel {
-
-    /**
-     * Scene-graph node whose property this channel animates. Resolved
-     * to its `transforms` table row at registration time via the
-     * scene context's `id_mapping`.
-     *
-     * @type {Node3D}
-     */
-    target = null;
-
-    /**
-     * Which property of {@link target} is animated. One of
-     * {@link Node3DProperty}. The GPU clip binding stores this as
-     * the `property` field; the apply shader's property writer
-     * dispatches off it.
-     *
-     * @type {number}
-     */
-    property = 0;
-
-    /**
-     * Per-component curves keyed by `x` / `y` / `z` / `w`. Omitted
-     * slots leave that component unanimated.
-     *
-     * @type {ChannelCurves}
-     */
-    curves = {};
-
-    /**
-     * @param {{
-     *     target: Node3D,
-     *     property: number,
-     *     curves: ChannelCurves,
-     * }} args
-     * @returns {ShadeAnimationChannel}
-     */
-    static from({ target, property, curves }) {
-        assert.defined(target, 'target');
-        assert.isNumber(property, 'property');
-        assert.defined(curves, 'curves');
-
-        const r = new ShadeAnimationChannel();
-        r.target = target;
-        r.property = property;
-        // Shallow copy so the caller's input object isn't aliased
-        // into the channel — mutations on either side stay isolated.
-        // Curve references themselves are shared (curve data is
-        // read-only across retargets and the dedup path expects
-        // identity-keyed sharing).
-        r.curves = {
-            x: curves.x,
-            y: curves.y,
-            z: curves.z,
-            w: curves.w,
-        };
-        return r;
-    }
-
-    /**
-     * Copy `other`'s shape into `this`. Target reference, property,
-     * and per-axis curve references are shared with `other` — not
-     * deep-cloned. Curves are read-only animation data; sharing
-     * across channels (e.g. a base clip retargeted onto many
-     * character instances) is the intended pattern.
-     *
-     * Retargeting after a clone is the caller's job: walk the cloned
-     * channels and replace each `target` with the new Node3D.
-     *
-     * @param {ShadeAnimationChannel} other
-     */
-    copy(other) {
-        if (this === other) return;
-
-        this.target = other.target;
-        this.property = other.property;
-        this.curves = {
-            x: other.curves.x,
-            y: other.curves.y,
-            z: other.curves.z,
-            w: other.curves.w,
-        };
-    }
-
-    /**
-     * Structural clone. Target is shared with the original; callers
-     * who clone a clip for a new character instance should overwrite
-     * `clone.target` with the new joint Node3D.
-     *
-     * @returns {ShadeAnimationChannel}
-     */
-    clone() {
-        const r = new ShadeAnimationChannel();
-        r.copy(this);
-        return r;
-    }
-
-    /**
-     * Evaluate this channel's curves at time `t` and write the
-     * result into {@link target}'s `transform_local`.
-     *
-     * - Translation / Scale: per-axis: an absent slot leaves the
-     *   axis untouched, so partial-axis channels are non-destructive
-     *   on the unanimated components.
-     * - Rotation: reads all four quaternion components (missing
-     *   slots fall back to identity values 0/0/0/1) and normalises
-     *   the result — cubic-Hermite interpolation of the four
-     *   scalar curves drifts off the unit 4-sphere; the GPU apply
-     *   shader does the same normalise.
-     *
-     * Mutates `target`. Callers that need to preserve the bind
-     * pose are responsible for snapshotting before calling and
-     * restoring after — or pass a {@link Node3D#clone}d target so
-     * the original is untouched.
-     *
-     * @param {number} t
-     */
-    apply(t) {
-        const curves = this.curves;
-        const tl = this.target.transform_local;
-
-        switch (this.property) {
-            case Node3DProperty.Translation: {
-                // written through the layout rather than a component view: a channel drives one axis
-                // and `translation` would allocate a fresh view for each of them
-                if (curves.x !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET] = curves.x.evaluate(t);
-                if (curves.y !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET + 1] = curves.y.evaluate(t);
-                if (curves.z !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET + 2] = curves.z.evaluate(t);
-                break;
-            }
-            case Node3DProperty.Rotation: {
-                // All four quaternion components are expected per
-                // the docstring above; missing slots fall back to
-                // identity component values rather than skipped,
-                // so a malformed channel still leaves a valid
-                // unit quaternion after normalise().
-                const qx = curves.x !== undefined ? curves.x.evaluate(t) : 0;
-                const qy = curves.y !== undefined ? curves.y.evaluate(t) : 0;
-                const qz = curves.z !== undefined ? curves.z.evaluate(t) : 0;
-                const qw = curves.w !== undefined ? curves.w.evaluate(t) : 1;
-                SCRATCH_ROTATION.set(qx, qy, qz, qw);
-                SCRATCH_ROTATION.normalize();
-
-                tl.setRotation(
-                    SCRATCH_ROTATION[0],
-                    SCRATCH_ROTATION[1],
-                    SCRATCH_ROTATION[2],
-                    SCRATCH_ROTATION[3]
-                );
-                break;
-            }
-            case Node3DProperty.Scale: {
-                if (curves.x !== undefined) tl[TRANSFORM64_SCALE_OFFSET] = curves.x.evaluate(t);
-                if (curves.y !== undefined) tl[TRANSFORM64_SCALE_OFFSET + 1] = curves.y.evaluate(t);
-                if (curves.z !== undefined) tl[TRANSFORM64_SCALE_OFFSET + 2] = curves.z.evaluate(t);
-                break;
-            }
-            default: break;
-        }
-    }
-
-    /**
-     * Number of currently-live curves on this channel — slots
-     * defined as a non-undefined value. After {@link optimize} this
-     * drops to the count of non-identity per-axis curves (which is
-     * what actually drives a non-bind-pose transform). Channels
-     * whose `curve_count` is 0 after `optimize` are no-ops and the
-     * containing clip drops them.
-     *
-     * @returns {number}
-     */
-    get curve_count() {
-        const c = this.curves;
-        let n = 0;
-        if (c.x !== undefined) n++;
-        if (c.y !== undefined) n++;
-        if (c.z !== undefined) n++;
-        if (c.w !== undefined) n++;
-        return n;
-    }
-
-    /**
-     * Strip identity curves and key-reduce the survivors.
-     *
-     * Dropping a curve is only pose-preserving when the target's
-     * authored rest value for that component already sits at the
-     * identity: an absent slot leaves the rest value in place,
-     * while a present constant-identity curve overwrites it. So
-     * every drop below is gated on the target's `transform_local`
-     * rest component matching the identity value (within
-     * {@link IDENTITY_EPSILON}). When the rest transform isn't
-     * available the channel is kept — conservative.
-     *
-     * Per-property semantics:
-     *  - **Translation** (identity = `(0, 0, 0)`): each axis whose
-     *    curve is constant 0 AND whose rest position component is 0
-     *    is null'd individually. `apply(t)` treats absent slots as
-     *    no-ops.
-     *  - **Scale** (identity = `(1, 1, 1)`): same shape, identity
-     *    value of 1, gated on the rest scale component.
-     *  - **Rotation** (identity rotation): components are coupled
-     *    by the blend's normalise. The rotation is identity iff
-     *    `x, y, z` curves are all constant 0 (`w` is free — any
-     *    non-zero `w` with zero `xyz` normalises to ±identity).
-     *    When that pattern holds AND the rest rotation is itself
-     *    the identity orientation (rest `x, y, z` all 0; rest `w`
-     *    free, ±1 encode the same orientation), all four curves
-     *    are null'd so the channel collapses to
-     *    `curve_count === 0`. Otherwise none of the four are
-     *    touched (we can't strip individual rotation components).
-     *
-     * Survivors get key-reduced via `animation_curve_optimize` on
-     * a clone — the original is replaced only when the optimised
-     * shape actually differs (per {@link AnimationCurve#equals}).
-     * This keeps shared curves (e.g. one base clip retargeted
-     * across many character instances) from being mutated under
-     * sibling clips that haven't asked to optimise.
-     *
-     * Mutates `this.curves` (drops identity slots; possibly
-     * swaps in optimised clones). The constant-curve check is
-     * strict: every keyframe value within tolerance of the
-     * identity AND both tangents within tolerance of zero (cubic
-     * Hermite between such keyframes provably stays at the value).
-     *
-     * @returns {number} count of per-axis curve slots null'd out
-     *     (Translation/Scale: 0..3; Rotation: 0 or 4 — all-or-
-     *     nothing). Use {@link curve_count} after the call to
-     *     decide whether the channel is now empty.
-     */
-    optimize() {
-        const curves = this.curves;
-        const rest = this.target !== null ? this.target.transform_local : undefined;
-        let removed = 0;
-
-        switch (this.property) {
-            case Node3DProperty.Translation: {
-                if (rest !== undefined) {
-                    if (curves.x !== undefined && Math.abs(rest.translation_x) <= IDENTITY_EPSILON && is_curve_constant(curves.x, 0)) { curves.x = undefined; removed++; }
-                    if (curves.y !== undefined && Math.abs(rest.translation_y) <= IDENTITY_EPSILON && is_curve_constant(curves.y, 0)) { curves.y = undefined; removed++; }
-                    if (curves.z !== undefined && Math.abs(rest.translation_z) <= IDENTITY_EPSILON && is_curve_constant(curves.z, 0)) { curves.z = undefined; removed++; }
-                }
-                break;
-            }
-            case Node3DProperty.Scale: {
-                if (rest !== undefined) {
-                    if (curves.x !== undefined && Math.abs(rest.scale_x - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.x, 1)) { curves.x = undefined; removed++; }
-                    if (curves.y !== undefined && Math.abs(rest.scale_y - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.y, 1)) { curves.y = undefined; removed++; }
-                    if (curves.z !== undefined && Math.abs(rest.scale_z - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.z, 1)) { curves.z = undefined; removed++; }
-                }
-                break;
-            }
-            case Node3DProperty.Rotation: {
-                // x, y, z all identity-zero → identity rotation
-                // regardless of w. Droppable only when the rest
-                // rotation is also identity orientation (rest xyz
-                // all 0; w free — ±1 are the same orientation):
-                // drop all four to collapse the channel to
-                // curve_count === 0.
-                const rest_identity = rest !== undefined
-                    && Math.abs(rest.rotation_x) <= IDENTITY_EPSILON
-                    && Math.abs(rest.rotation_y) <= IDENTITY_EPSILON
-                    && Math.abs(rest.rotation_z) <= IDENTITY_EPSILON;
-                const xyz_identity =
-                    (curves.x === undefined || is_curve_constant(curves.x, 0)) &&
-                    (curves.y === undefined || is_curve_constant(curves.y, 0)) &&
-                    (curves.z === undefined || is_curve_constant(curves.z, 0));
-                if (rest_identity && xyz_identity) {
-                    if (curves.x !== undefined) { curves.x = undefined; removed++; }
-                    if (curves.y !== undefined) { curves.y = undefined; removed++; }
-                    if (curves.z !== undefined) { curves.z = undefined; removed++; }
-                    if (curves.w !== undefined) { curves.w = undefined; removed++; }
-                }
-                break;
-            }
-            default:
-                // Unknown property — leave alone.
-                break;
-        }
-
-        // Key-reduce surviving curves on a clone — replace the
-        // slot only when the optimised result actually differs.
-        // Two clips that share a curve (the common retarget case)
-        // therefore don't trample each other; the slot keeps the
-        // original reference when nothing changed, preserving
-        // identity-keyed dedup in `#intern_curve`.
-        this.#optimize_slot('x');
-        this.#optimize_slot('y');
-        this.#optimize_slot('z');
-        this.#optimize_slot('w');
-
-        return removed;
-    }
-
-    /**
-     * @param {'x'|'y'|'z'|'w'} axis
-     */
-    #optimize_slot(axis) {
-        const original = this.curves[axis];
-        if (original === undefined) return;
-
-        const optimised = original.clone();
-        animation_curve_optimize(optimised);
-        if (!original.equals(optimised)) {
-            this.curves[axis] = optimised;
-        }
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-ShadeAnimationChannel.prototype.isShadeAnimationChannel = true;
+import { assert } from "../../../core/assert.js";
+import {
+    animation_curve_optimize
+} from "../../../engine/animation/curve/animation_curve_optimize.js";
+import { Quaternion } from "../../../core/geom/Quaternion.js";
+import {
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../../../engine/ecs/transform/Transform64.js";
+import { Node3DProperty } from "../object_property/Node3DProperty.js";
+
+/**
+ * Somewhere to normalise a quaternion before it lands on a transform — {@link Transform64} takes a
+ * unit quaternion and does not normalise for you, and {@link Quaternion} already knows how.
+ *
+ * @type {Quaternion}
+ */
+const SCRATCH_ROTATION = new Quaternion();
+
+/**
+ * Tolerance for "is this value the identity?" comparisons inside
+ * {@link ShadeAnimationChannel#optimize}. Picked at 1e-5 because:
+ *  - Position units are typically metres → 1e-5 is sub-millimetre.
+ *  - Rotation components are in [-1, 1] → well below the visual
+ *    threshold of any reasonable per-frame quaternion change.
+ *  - Scale factors are typically near 1 → 1e-5 is one part in a
+ *    hundred thousand, far tighter than authoring tools quantise.
+ *
+ * Source-side `AnimationCurve` keyframe values are f32 (the f16
+ * encoding only enters at GPU upload time), so f32 round-trip
+ * noise is the only thing this needs to tolerate.
+ *
+ * @type {number}
+ */
+const IDENTITY_EPSILON = 1e-5;
+
+/**
+ * Strictly-constant check: every keyframe's `value` matches
+ * `expected_value` AND both tangents are zero (within
+ * {@link IDENTITY_EPSILON}). The cubic Hermite spline between two
+ * keyframes with equal values and zero tangents is guaranteed to
+ * stay at that value across the interpolation interval — non-zero
+ * tangents would cause overshoot away from the value, so we can't
+ * declare such a curve "constant" even if the keyframe values
+ * happen to match.
+ *
+ * @param {AnimationCurve} curve
+ * @param {number} expected_value
+ * @returns {boolean}
+ */
+function is_curve_constant(curve, expected_value) {
+    const keys = curve.keys;
+    for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        if (Math.abs(k.value - expected_value) > IDENTITY_EPSILON) return false;
+        if (Math.abs(k.inTangent) > IDENTITY_EPSILON) return false;
+        if (Math.abs(k.outTangent) > IDENTITY_EPSILON) return false;
+    }
+    return true;
+}
+
+/**
+ * @typedef {object} ChannelCurves
+ * Per-component curves keyed by the GPU track's `(x, y, z, w)`
+ * channels. Slots omitted (or set to `undefined`) leave that
+ * component unanimated — the GPU track's per-component mask drops
+ * the corresponding write.
+ *
+ * @property {AnimationCurve} [x]
+ * @property {AnimationCurve} [y]
+ * @property {AnimationCurve} [z]
+ * @property {AnimationCurve} [w]
+ */
+
+/**
+ * One binding inside a {@link ShadeAnimationClip}: a single target
+ * Node3D, the property of that node being animated, and the
+ * per-component curves driving each scalar slot.
+ *
+ * Curve slots are property-specific and align with the GPU track's
+ * `(x, y, z, w)` channels:
+ *
+ *  - {@link Node3DProperty.Translation}: `x`, `y`, `z` (no `w`)
+ *  - {@link Node3DProperty.Scale}: `x`, `y`, `z` (no `w`)
+ *  - {@link Node3DProperty.Rotation}: quaternion `x`, `y`, `z`, `w`
+ *
+ * An absent slot means "this component isn't animated"; the GPU
+ * track's per-component mask drops the corresponding write.
+ * Rotation tracks should supply all four channels — the shader
+ * writes the quaternion as a whole, not per-component; missing
+ * slots fall back to identity values (0/0/0/1) so the result is
+ * still a valid unit quaternion after normalise.
+ *
+ * Pure CPU data. Knows nothing about the GPU; consumed by
+ * {@link GPUAnimationManager#register_clip}, which resolves the
+ * target to a transforms-table row and uploads the curves.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ShadeAnimationChannel {
+
+    /**
+     * Scene-graph node whose property this channel animates. Resolved
+     * to its `transforms` table row at registration time via the
+     * scene context's `id_mapping`.
+     *
+     * @type {Node3D}
+     */
+    target = null;
+
+    /**
+     * Which property of {@link target} is animated. One of
+     * {@link Node3DProperty}. The GPU clip binding stores this as
+     * the `property` field; the apply shader's property writer
+     * dispatches off it.
+     *
+     * @type {number}
+     */
+    property = 0;
+
+    /**
+     * Per-component curves keyed by `x` / `y` / `z` / `w`. Omitted
+     * slots leave that component unanimated.
+     *
+     * @type {ChannelCurves}
+     */
+    curves = {};
+
+    /**
+     * @param {{
+     *     target: Node3D,
+     *     property: number,
+     *     curves: ChannelCurves,
+     * }} args
+     * @returns {ShadeAnimationChannel}
+     */
+    static from({ target, property, curves }) {
+        assert.defined(target, 'target');
+        assert.isNumber(property, 'property');
+        assert.defined(curves, 'curves');
+
+        const r = new ShadeAnimationChannel();
+        r.target = target;
+        r.property = property;
+        // Shallow copy so the caller's input object isn't aliased
+        // into the channel — mutations on either side stay isolated.
+        // Curve references themselves are shared (curve data is
+        // read-only across retargets and the dedup path expects
+        // identity-keyed sharing).
+        r.curves = {
+            x: curves.x,
+            y: curves.y,
+            z: curves.z,
+            w: curves.w,
+        };
+        return r;
+    }
+
+    /**
+     * Copy `other`'s shape into `this`. Target reference, property,
+     * and per-axis curve references are shared with `other` — not
+     * deep-cloned. Curves are read-only animation data; sharing
+     * across channels (e.g. a base clip retargeted onto many
+     * character instances) is the intended pattern.
+     *
+     * Retargeting after a clone is the caller's job: walk the cloned
+     * channels and replace each `target` with the new Node3D.
+     *
+     * @param {ShadeAnimationChannel} other
+     */
+    copy(other) {
+        if (this === other) return;
+
+        this.target = other.target;
+        this.property = other.property;
+        this.curves = {
+            x: other.curves.x,
+            y: other.curves.y,
+            z: other.curves.z,
+            w: other.curves.w,
+        };
+    }
+
+    /**
+     * Structural clone. Target is shared with the original; callers
+     * who clone a clip for a new character instance should overwrite
+     * `clone.target` with the new joint Node3D.
+     *
+     * @returns {ShadeAnimationChannel}
+     */
+    clone() {
+        const r = new ShadeAnimationChannel();
+        r.copy(this);
+        return r;
+    }
+
+    /**
+     * Evaluate this channel's curves at time `t` and write the
+     * result into {@link target}'s `transform_local`.
+     *
+     * - Translation / Scale: per-axis: an absent slot leaves the
+     *   axis untouched, so partial-axis channels are non-destructive
+     *   on the unanimated components.
+     * - Rotation: reads all four quaternion components (missing
+     *   slots fall back to identity values 0/0/0/1) and normalises
+     *   the result — cubic-Hermite interpolation of the four
+     *   scalar curves drifts off the unit 4-sphere; the GPU apply
+     *   shader does the same normalise.
+     *
+     * Mutates `target`. Callers that need to preserve the bind
+     * pose are responsible for snapshotting before calling and
+     * restoring after — or pass a {@link Node3D#clone}d target so
+     * the original is untouched.
+     *
+     * @param {number} t
+     */
+    apply(t) {
+        const curves = this.curves;
+        const tl = this.target.transform_local;
+
+        switch (this.property) {
+            case Node3DProperty.Translation: {
+                // written through the layout rather than a component view: a channel drives one axis
+                // and `translation` would allocate a fresh view for each of them
+                if (curves.x !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET] = curves.x.evaluate(t);
+                if (curves.y !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET + 1] = curves.y.evaluate(t);
+                if (curves.z !== undefined) tl[TRANSFORM64_TRANSLATION_OFFSET + 2] = curves.z.evaluate(t);
+                break;
+            }
+            case Node3DProperty.Rotation: {
+                // All four quaternion components are expected per
+                // the docstring above; missing slots fall back to
+                // identity component values rather than skipped,
+                // so a malformed channel still leaves a valid
+                // unit quaternion after normalise().
+                const qx = curves.x !== undefined ? curves.x.evaluate(t) : 0;
+                const qy = curves.y !== undefined ? curves.y.evaluate(t) : 0;
+                const qz = curves.z !== undefined ? curves.z.evaluate(t) : 0;
+                const qw = curves.w !== undefined ? curves.w.evaluate(t) : 1;
+                SCRATCH_ROTATION.set(qx, qy, qz, qw);
+                SCRATCH_ROTATION.normalize();
+
+                tl.setRotation(
+                    SCRATCH_ROTATION[0],
+                    SCRATCH_ROTATION[1],
+                    SCRATCH_ROTATION[2],
+                    SCRATCH_ROTATION[3]
+                );
+                break;
+            }
+            case Node3DProperty.Scale: {
+                if (curves.x !== undefined) tl[TRANSFORM64_SCALE_OFFSET] = curves.x.evaluate(t);
+                if (curves.y !== undefined) tl[TRANSFORM64_SCALE_OFFSET + 1] = curves.y.evaluate(t);
+                if (curves.z !== undefined) tl[TRANSFORM64_SCALE_OFFSET + 2] = curves.z.evaluate(t);
+                break;
+            }
+            default: break;
+        }
+    }
+
+    /**
+     * Number of currently-live curves on this channel — slots
+     * defined as a non-undefined value. After {@link optimize} this
+     * drops to the count of non-identity per-axis curves (which is
+     * what actually drives a non-bind-pose transform). Channels
+     * whose `curve_count` is 0 after `optimize` are no-ops and the
+     * containing clip drops them.
+     *
+     * @returns {number}
+     */
+    get curve_count() {
+        const c = this.curves;
+        let n = 0;
+        if (c.x !== undefined) n++;
+        if (c.y !== undefined) n++;
+        if (c.z !== undefined) n++;
+        if (c.w !== undefined) n++;
+        return n;
+    }
+
+    /**
+     * Strip identity curves and key-reduce the survivors.
+     *
+     * Dropping a curve is only pose-preserving when the target's
+     * authored rest value for that component already sits at the
+     * identity: an absent slot leaves the rest value in place,
+     * while a present constant-identity curve overwrites it. So
+     * every drop below is gated on the target's `transform_local`
+     * rest component matching the identity value (within
+     * {@link IDENTITY_EPSILON}). When the rest transform isn't
+     * available the channel is kept — conservative.
+     *
+     * Per-property semantics:
+     *  - **Translation** (identity = `(0, 0, 0)`): each axis whose
+     *    curve is constant 0 AND whose rest position component is 0
+     *    is null'd individually. `apply(t)` treats absent slots as
+     *    no-ops.
+     *  - **Scale** (identity = `(1, 1, 1)`): same shape, identity
+     *    value of 1, gated on the rest scale component.
+     *  - **Rotation** (identity rotation): components are coupled
+     *    by the blend's normalise. The rotation is identity iff
+     *    `x, y, z` curves are all constant 0 (`w` is free — any
+     *    non-zero `w` with zero `xyz` normalises to ±identity).
+     *    When that pattern holds AND the rest rotation is itself
+     *    the identity orientation (rest `x, y, z` all 0; rest `w`
+     *    free, ±1 encode the same orientation), all four curves
+     *    are null'd so the channel collapses to
+     *    `curve_count === 0`. Otherwise none of the four are
+     *    touched (we can't strip individual rotation components).
+     *
+     * Survivors get key-reduced via `animation_curve_optimize` on
+     * a clone — the original is replaced only when the optimised
+     * shape actually differs (per {@link AnimationCurve#equals}).
+     * This keeps shared curves (e.g. one base clip retargeted
+     * across many character instances) from being mutated under
+     * sibling clips that haven't asked to optimise.
+     *
+     * Mutates `this.curves` (drops identity slots; possibly
+     * swaps in optimised clones). The constant-curve check is
+     * strict: every keyframe value within tolerance of the
+     * identity AND both tangents within tolerance of zero (cubic
+     * Hermite between such keyframes provably stays at the value).
+     *
+     * @returns {number} count of per-axis curve slots null'd out
+     *     (Translation/Scale: 0..3; Rotation: 0 or 4 — all-or-
+     *     nothing). Use {@link curve_count} after the call to
+     *     decide whether the channel is now empty.
+     */
+    optimize() {
+        const curves = this.curves;
+        const rest = this.target !== null ? this.target.transform_local : undefined;
+        let removed = 0;
+
+        switch (this.property) {
+            case Node3DProperty.Translation: {
+                if (rest !== undefined) {
+                    if (curves.x !== undefined && Math.abs(rest.translation_x) <= IDENTITY_EPSILON && is_curve_constant(curves.x, 0)) { curves.x = undefined; removed++; }
+                    if (curves.y !== undefined && Math.abs(rest.translation_y) <= IDENTITY_EPSILON && is_curve_constant(curves.y, 0)) { curves.y = undefined; removed++; }
+                    if (curves.z !== undefined && Math.abs(rest.translation_z) <= IDENTITY_EPSILON && is_curve_constant(curves.z, 0)) { curves.z = undefined; removed++; }
+                }
+                break;
+            }
+            case Node3DProperty.Scale: {
+                if (rest !== undefined) {
+                    if (curves.x !== undefined && Math.abs(rest.scale_x - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.x, 1)) { curves.x = undefined; removed++; }
+                    if (curves.y !== undefined && Math.abs(rest.scale_y - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.y, 1)) { curves.y = undefined; removed++; }
+                    if (curves.z !== undefined && Math.abs(rest.scale_z - 1) <= IDENTITY_EPSILON && is_curve_constant(curves.z, 1)) { curves.z = undefined; removed++; }
+                }
+                break;
+            }
+            case Node3DProperty.Rotation: {
+                // x, y, z all identity-zero → identity rotation
+                // regardless of w. Droppable only when the rest
+                // rotation is also identity orientation (rest xyz
+                // all 0; w free — ±1 are the same orientation):
+                // drop all four to collapse the channel to
+                // curve_count === 0.
+                const rest_identity = rest !== undefined
+                    && Math.abs(rest.rotation_x) <= IDENTITY_EPSILON
+                    && Math.abs(rest.rotation_y) <= IDENTITY_EPSILON
+                    && Math.abs(rest.rotation_z) <= IDENTITY_EPSILON;
+                const xyz_identity =
+                    (curves.x === undefined || is_curve_constant(curves.x, 0)) &&
+                    (curves.y === undefined || is_curve_constant(curves.y, 0)) &&
+                    (curves.z === undefined || is_curve_constant(curves.z, 0));
+                if (rest_identity && xyz_identity) {
+                    if (curves.x !== undefined) { curves.x = undefined; removed++; }
+                    if (curves.y !== undefined) { curves.y = undefined; removed++; }
+                    if (curves.z !== undefined) { curves.z = undefined; removed++; }
+                    if (curves.w !== undefined) { curves.w = undefined; removed++; }
+                }
+                break;
+            }
+            default:
+                // Unknown property — leave alone.
+                break;
+        }
+
+        // Key-reduce surviving curves on a clone — replace the
+        // slot only when the optimised result actually differs.
+        // Two clips that share a curve (the common retarget case)
+        // therefore don't trample each other; the slot keeps the
+        // original reference when nothing changed, preserving
+        // identity-keyed dedup in `#intern_curve`.
+        this.#optimize_slot('x');
+        this.#optimize_slot('y');
+        this.#optimize_slot('z');
+        this.#optimize_slot('w');
+
+        return removed;
+    }
+
+    /**
+     * @param {'x'|'y'|'z'|'w'} axis
+     */
+    #optimize_slot(axis) {
+        const original = this.curves[axis];
+        if (original === undefined) return;
+
+        const optimised = original.clone();
+        animation_curve_optimize(optimised);
+        if (!original.equals(optimised)) {
+            this.curves[axis] = optimised;
+        }
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ShadeAnimationChannel.prototype.isShadeAnimationChannel = true;