@aura3d/assets 3.0.1 → 4.0.0

package/dist/GLTFAnimationRuntime.js

@@ -1,5 +1,8 @@
 import { AnimationAction, AnimationClip, AnimationMixer, consumeRootMotion, extractRootMotion, createFootIkRig, normalizeQuat, slerpQuat, solveTwoBoneIk } from "@aura3d/animation";
+import { bindSkeleton, compileClip, createPoseBuffer, makeClipAdditive, PoseMixer } from "@aura3d/animation/lanes";
+import { AURA3D_RETARGET_ENGINE_VERSION, bakeClipsInWorker, bakeRetargetedClipMap, createRetargetWorker, decompileCompiledClip, readRetargetCache, retargetCacheKey, retargetClipsHash, retargetSkeletonHash, writeRetargetCache } from "@aura3d/animation/lanes";
 import { composeMat4, decomposeMat4, invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "@aura3d/scene";
+import { skinningPaletteCache } from "@aura3d/rendering";
 /**
  * Synonym groups for fuzzy clip-name matching. Real catalog assets label the same
  * motion wildly differently ("Loops" vs "Idle", "Take 001" vs "Run", "sprint" vs
@@ -17,19 +20,31 @@ const GLTF_CLIP_SYNONYM_GROUPS = [
 function normalizeClipToken(name) {
     return name.toLowerCase().replace(/[\s_.\-]+/g, "");
 }
-/**
- * Resolve a requested clip name to the best available clip name.
- *
- * Matching order:
- *   1. Exact case-insensitive (ignoring whitespace/underscores/dots/dashes).
- *   2. Synonym-group match: the requested name and an available name belong to
- *      the same synonym group (e.g. "run" resolves to "Sprint").
- *   3. Substring match in either direction (e.g. "walk" -> "WalkCycle").
- *   4. Fallback to the first available clip.
- *
- * Returns `undefined` only when there are no available clips.
- */
-export function resolveGLTFClipName(requested, available) {
+const animationClipDefaultsAre31 = () => {
+    const parseList = (value) => value === undefined ? [] : value.split(/[\s,]+/).map((entry) => entry.trim().toLowerCase()).filter((entry) => entry !== "");
+    const env = typeof process !== "undefined" ? process.env : undefined;
+    if (env !== undefined) {
+        const scoped = env["A3D_QR_ANIMATION"];
+        if (scoped !== undefined && scoped !== "0" && scoped.toLowerCase() !== "false" && scoped.toLowerCase() !== "off")
+            return true;
+        const root = parseList(env["A3D_QR"] ?? env["A3D_QR_FLAGS"]);
+        if (root.includes("animation") || root.includes("all") || root.includes("true"))
+            return true;
+    }
+    if (typeof location !== "undefined" && typeof location.search === "string") {
+        try {
+            const params = new URLSearchParams(location.search);
+            const urlFlags = parseList(params.get("a3d-qr") ?? undefined);
+            if (urlFlags.includes("animation") || urlFlags.includes("all") || urlFlags.includes("true"))
+                return true;
+        }
+        catch {
+            // malformed URLSearchParams input — ignore URL source
+        }
+    }
+    return false;
+};
+export function resolveGLTFClipName(requested, available, options) {
     if (available.length === 0)
         return undefined;
     const requestedToken = normalizeClipToken(requested);
@@ -50,7 +65,8 @@ export function resolveGLTFClipName(requested, available) {
             return name;
         }
     }
-    return available[0];
+    const fallback = options?.fallback ?? (animationClipDefaultsAre31() ? "error" : "first");
+    return fallback === "first" ? available[0] : undefined;
 }
 function clipMaskAllowsNode(mask, nodeName) {
     if (!mask)
@@ -253,12 +269,73 @@ export class GLTFImportedSkeletonIKController {
         };
     }
 }
+/** PRD-06 §9.8 — wall clock, ms (`performance.now` where it exists). */
+function nowMs() {
+    return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+/** Column-major mat4 multiply written into a Float32Array slot — the T0.11 no-alloc palette path. Exported so the §13 palette-build micro-budget test measures the exact per-joint write the runtime performs. `a` is hoisted into scalars once per call so the inner writes are pure FMA-grade flops — the indexed-read loop measured ~1.3× over the §13 palette budget. */
+export function multiplyMat4Into(out, outOffset, a, b) {
+    const a00 = a[0], a10 = a[1], a20 = a[2], a30 = a[3];
+    const a01 = a[4], a11 = a[5], a21 = a[6], a31 = a[7];
+    const a02 = a[8], a12 = a[9], a22 = a[10], a32 = a[11];
+    const a03 = a[12], a13 = a[13], a23 = a[14], a33 = a[15];
+    for (let col = 0; col < 4; col += 1) {
+        const b0 = b[col * 4 + 0], b1 = b[col * 4 + 1], b2 = b[col * 4 + 2], b3 = b[col * 4 + 3];
+        out[outOffset + col * 4 + 0] = a00 * b0 + a01 * b1 + a02 * b2 + a03 * b3;
+        out[outOffset + col * 4 + 1] = a10 * b0 + a11 * b1 + a12 * b2 + a13 * b3;
+        out[outOffset + col * 4 + 2] = a20 * b0 + a21 * b1 + a22 * b2 + a23 * b3;
+        out[outOffset + col * 4 + 3] = a30 * b0 + a31 * b1 + a32 * b2 + a33 * b3;
+    }
+}
+/** Column-major general 4×4 inverse into `out` (adjugate / determinant, gl-matrix `mat4.invert`; 06-T0: out[7], out[10], out[11], out[14], out[15] previously used the wrong cofactor terms, so even inverse(identity) had out[11] = -1 and every skinning palette carried a non-affine row 3 that projected skinned vertices off-screen on the GPU). §13: `invertMat4` allocates two objects per call — over 600 frames that alone blows the steady-state budget. */
+export function invertMat4Into(out, a) {
+    const a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3];
+    const a10 = a[4], a11 = a[5], a12 = a[6], a13 = a[7];
+    const a20 = a[8], a21 = a[9], a22 = a[10], a23 = a[11];
+    const a30 = a[12], a31 = a[13], a32 = a[14], a33 = a[15];
+    const b00 = a00 * a11 - a01 * a10;
+    const b01 = a00 * a12 - a02 * a10;
+    const b02 = a00 * a13 - a03 * a10;
+    const b03 = a01 * a12 - a02 * a11;
+    const b04 = a01 * a13 - a03 * a11;
+    const b05 = a02 * a13 - a03 * a12;
+    const b06 = a20 * a31 - a21 * a30;
+    const b07 = a20 * a32 - a22 * a30;
+    const b08 = a20 * a33 - a23 * a30;
+    const b09 = a21 * a32 - a22 * a31;
+    const b10 = a21 * a33 - a23 * a31;
+    const b11 = a22 * a33 - a23 * a32;
+    let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+    if (!det) {
+        out.fill(0);
+        return out;
+    }
+    det = 1.0 / det;
+    out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det;
+    out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det;
+    out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det;
+    out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det;
+    out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det;
+    out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det;
+    out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det;
+    out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det;
+    out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det;
+    out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det;
+    out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det;
+    out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det;
+    out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det;
+    out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det;
+    out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det;
+    out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det;
+    return out;
+}
 export class GLTFSceneAnimationRuntime {
     options;
     clipsByName = new Map();
     nodesByName = new Map();
     morphRenderablesByNodeName = new Map();
     skinningBindings = [];
+    disposed = false;
     footBindMatrices = new Map();
     footOrientationLocks = new Map();
     footDescendantLocks = new Map();
@@ -266,6 +343,30 @@ export class GLTFSceneAnimationRuntime {
     footPlanting;
     footRig;
     lastApply;
+    /** T0.11 scratch for the per-joint palette multiply (inverseMeshWorld * jointWorld). */
+    paletteScratch = new Float32Array(16);
+    /** §13: reusable scratch for the per-binding inverse world matrix (no alloc/frame). */
+    inverseWorldScratch = new Float32Array(16);
+    /** §13: persistent result object for `refreshSkinningPalettes` (0 bytes/frame). */
+    paletteResult = { updated: 0, missingTargets: [] };
+    /**
+     * T1.7 (PRD-06) — the per-runtime pose pipeline backing `applyClips`: a
+     * scene-wide SkeletonBinding (every traversed node in order, rest pose = the
+     * node's local TRS at bind time), one PoseMixer, and the compiled clips.
+     * Rebuilt whenever `reindexScene` re-reads the node set.
+     */
+    poseState;
+    /**
+     * T3.5 — world→model matrix provider for pose constraints. Defaults to the
+     * scene root's world matrix; the `prd06.animation` actor extension installs
+     * the app-node transform when one is known.
+     */
+    poseConstraintModelMatrix;
+    /**
+     * Wall-clock (ms) of the last constraint evaluation under `applyClips` —
+     * its caller passes no dt, so constraint dynamics measure the real gap.
+     */
+    lastConstraintEvalAtMs;
     constructor(options) {
         this.options = options;
         for (const clip of options.clips) {
@@ -347,6 +448,91 @@ export class GLTFSceneAnimationRuntime {
         this.lastApply = this.applySampledTargets(`root-motion:${names.join(",")}`, maxTime, { sampledTargets: values, unsupportedTracks }, samples.length);
         return { motion, applyResult: this.lastApply };
     }
+    /**
+     * T3.7 (PRD-06 §6.8) — resolve the root-motion translation track target for
+     * spec-level `play(clip, {rootMotion})`: with `bone` set, the bone's own
+     * `translation`/`position` track; without it, the clip's root-motion
+     * candidate (largest planar displacement on a hips/root/pelvis node, then
+     * any translation track by displacement). Throws when nothing qualifies.
+     */
+    rootMotionTargetFor(clipName, bone) {
+        const clip = this.clipsByName.get(clipName);
+        if (!clip)
+            throw new Error(`glTF animation clip "${clipName}" was not found.`);
+        const isTranslation = (target) => target.endsWith(".translation") || target.endsWith(".position");
+        if (bone !== undefined) {
+            for (const leaf of ["translation", "position"]) {
+                const candidate = `${bone}.${leaf}`;
+                if (clip.tracks.some(track => track.target === candidate && track.valueType === "vector3"))
+                    return candidate;
+            }
+            throw new Error(`Root motion bone "${bone}" has no translation track in glTF animation clip "${clipName}".`);
+        }
+        let best;
+        let bestDistance = -1;
+        let fallback;
+        for (const track of clip.tracks) {
+            if (track.valueType !== "vector3" || !isTranslation(track.target))
+                continue;
+            fallback ??= track.target;
+            const keys = track.keyframes ?? [];
+            if (keys.length < 2)
+                continue;
+            const first = vec3OfKeyframeValue(keys[0].value);
+            const last = vec3OfKeyframeValue(keys[keys.length - 1].value);
+            if (!first || !last)
+                continue;
+            const distance = Math.hypot(last[0] - first[0], last[2] - first[2]);
+            const rooted = /hips|root|pelvis/i.test(track.target);
+            if (distance > 0.05 && (rooted || best === undefined || distance > bestDistance)) {
+                if (rooted || best === undefined || !/hips|root|pelvis/i.test(best)) {
+                    best = track.target;
+                    bestDistance = distance;
+                }
+            }
+        }
+        const resolved = best ?? fallback;
+        if (resolved === undefined) {
+            throw new Error(`glTF animation clip "${clipName}" has no translation track for root motion.`);
+        }
+        return resolved;
+    }
+    /**
+     * T3.7 — yaw delta (radians, about local Y) authored on `bone`'s rotation
+     * track between `fromTime`/`toTime` (loop-aware). Returns 0 when the clip
+     * has no matching rotation track.
+     */
+    rootMotionYawDelta(clipName, bone, fromTime, toTime, loop) {
+        const clip = this.clipsByName.get(clipName);
+        if (!clip)
+            throw new Error(`glTF animation clip "${clipName}" was not found.`);
+        const node = bone ?? this.rootMotionTargetFor(clipName).replace(/\.(translation|position)$/, "");
+        const track = clip.tracks.find(candidate => candidate.valueType === "quaternion" &&
+            (candidate.target === `${node}.rotation` || candidate.target === `${node}.quaternion`));
+        if (!track)
+            return 0;
+        const yawAt = (time) => {
+            const q = track.sample(time);
+            const arr = (Array.isArray(q) || ArrayBuffer.isView(q)) ? q : undefined;
+            const [x, y, z, w] = arr !== undefined && arr.length >= 4
+                ? [arr[0], arr[1], arr[2], arr[3]]
+                : [0, 0, 0, 1];
+            // forward = q * (0,0,1); yaw = atan2(forward.x, forward.z)
+            const fx = 2 * (x * z + w * y);
+            const fz = 1 - 2 * (x * x + y * y);
+            return Math.atan2(fx, fz);
+        };
+        const wrap01 = (t) => ((t % clip.duration) + clip.duration) % clip.duration;
+        const unwrap = (delta) => delta - Math.round(delta / (Math.PI * 2)) * Math.PI * 2;
+        if (!loop || clip.duration <= 0) {
+            const clamp = (t) => Math.max(0, Math.min(clip.duration, t));
+            return unwrap(yawAt(clamp(toTime)) - yawAt(clamp(fromTime)));
+        }
+        // Continuous-loop yaw: same-cycle delta plus per-cycle contribution per wrap.
+        const perCycle = unwrap(yawAt(clip.duration) - yawAt(0));
+        const crossings = Math.floor(toTime / clip.duration) - Math.floor(fromTime / clip.duration);
+        return unwrap(yawAt(wrap01(toTime)) - yawAt(wrap01(fromTime))) + crossings * perCycle;
+    }
     applyClipByName(name, time) {
         const clip = this.clipsByName.get(name);
         if (!clip) {
@@ -358,13 +544,27 @@ export class GLTFSceneAnimationRuntime {
     clipNames() {
         return [...this.clipsByName.keys()];
     }
+    /**
+     * T0.6 (PRD-06) — the C-19 `AuraResolvedClipInfo` surface that backs the
+     * `prd06.animation` handle extension's `resolveAnimationClips()`: real GLB
+     * clip durations (plus channel counts and the 5 cm XZ-displacement
+     * root-motion candidate heuristic of T0.7) after the asset has loaded.
+     */
+    resolvedClipInfos() {
+        return [...this.clipsByName.values()].map((clip) => ({
+            name: clip.name,
+            duration: clip.duration,
+            channelCount: clip.tracks.length,
+            hasRootMotionCandidate: clipHasRootMotionCandidate(clip)
+        }));
+    }
     /**
      * Resolve a requested clip name to the best available registered clip name
      * using fuzzy matching (exact -> synonym group -> substring -> first clip).
      * Returns `undefined` when the runtime has no clips.
      */
-    resolveClipName(name) {
-        return resolveGLTFClipName(name, this.clipNames());
+    resolveClipName(name, options) {
+        return resolveGLTFClipName(name, this.clipNames(), options);
     }
     /**
      * Apply a clip selected by fuzzy name resolution. Unlike {@link applyClipByName}
@@ -386,14 +586,35 @@ export class GLTFSceneAnimationRuntime {
         this.lastApply = this.applySampledTargets(clip.name, wrappedTime, sampleClipTracks(clip, wrappedTime, 1, false));
         return this.lastApply;
     }
+    /**
+     * T1.7 (PRD-06 §10) — re-implemented on the per-runtime `PoseMixer` in
+     * stateless mode (`evaluateSamples` with explicit per-sample times). Node
+     * translation/rotation/scale tracks bound to a scene node go through the
+     * pose pipeline (incremental-weight accumulate + rest fill + additive
+     * accumulators, three r185 `AnimationMixer` order); morph-weight, material
+     * and light pointer tracks keep the existing accumulator path, and so do
+     * node tracks aimed at nodes the binding does not cover (they keep their
+     * `missingTargets` reporting). Two documented semantic changes vs the old
+     * accumulator blend: partial-weight mixes fill the remainder from the rest
+     * pose instead of renormalising (rest blend), and a bone covered by the
+     * blend but not by a given channel resets that channel to rest (rest reset).
+     */
     applyClips(samples) {
         if (samples.length === 0) {
             throw new Error("glTF animation runtime blend requires at least one clip sample.");
         }
+        const phaseStart = nowMs();
+        let mixerMs = 0;
+        let constraintsMs = 0;
+        let springsMs = 0;
         const accumulators = new Map();
         const unsupportedTracks = [];
         let maxTime = 0;
         const names = [];
+        const pose = this.poseRuntime();
+        const poseSpecs = [];
+        const touchedBones = new Set();
+        const maskWeights = new Map();
         for (const sample of samples) {
             const clip = this.clipsByName.get(sample.clipName);
             if (!clip) {
@@ -411,25 +632,353 @@ export class GLTFSceneAnimationRuntime {
             const wrappedTime = clip.duration > 0 && sample.time > clip.duration ? sample.time % clip.duration : Math.min(sample.time, clip.duration);
             maxTime = Math.max(maxTime, wrappedTime);
             names.push(`${clip.name}@${Number(wrappedTime.toFixed(4))}x${Number(weight.toFixed(4))}${sample.additive ? "+add" : ""}`);
+            let bindsNodes = false;
             for (const track of clip.tracks) {
                 const target = parseAnimationTarget(track.target);
                 if (!target) {
                     unsupportedTracks.push(track.target);
                     continue;
                 }
-                // Bone masks filter node tracks only; material/light property tracks always apply.
-                if (target.kind === "node" && !clipMaskAllowsNode(sample.mask, target.nodeName))
+                if (target.kind === "node" && target.path !== "weights") {
+                    // Node TRS: pose path when the name binds and the mask allows it.
+                    const boneIndices = pose.binding.jointIndicesByName.get(target.nodeName);
+                    if (boneIndices !== undefined && boneIndices.length > 0 && clipMaskAllowsNode(sample.mask, target.nodeName)) {
+                        bindsNodes = true;
+                        touchedBones.add(boneIndices[0]);
+                    }
+                    else if (boneIndices === undefined) {
+                        // Track points at a node absent from the scene — legacy path so
+                        // `missingTargets` reporting is unchanged.
+                        blendInto(accumulators, track.target, track.valueType, track.sample(wrappedTime), weight, sample.additive === true);
+                    }
                     continue;
+                }
                 blendInto(accumulators, track.target, track.valueType, track.sample(wrappedTime), weight, sample.additive === true);
             }
+            if (bindsNodes) {
+                let mask = null;
+                if (sample.mask !== undefined) {
+                    let cached = maskWeights.get(sample.mask);
+                    if (cached === undefined) {
+                        cached = new Float32Array(pose.binding.boneCount);
+                        for (let i = 0; i < pose.binding.boneCount; i += 1) {
+                            cached[i] = clipMaskAllowsNode(sample.mask, pose.binding.jointNames[i]) ? 1 : 0;
+                        }
+                        maskWeights.set(sample.mask, cached);
+                    }
+                    mask = cached;
+                }
+                poseSpecs.push({ clipName: clip.name, time: wrappedTime, weight, additive: sample.additive === true, mask });
+            }
         }
         const sampledTargets = new Map();
+        if (poseSpecs.length > 0) {
+            const mixerStart = nowMs();
+            pose.mixer.evaluateSamples(poseSpecs, pose.pose);
+            mixerMs = nowMs() - mixerStart;
+            // T3.5 — constraints apply to the freshly-mixed pose before palette
+            // build; touched joints union into the emitted sampled targets. Their
+            // dynamics (look-at half-life, spring substeps) integrate in wall-clock
+            // seconds, so measure the real gap between applies — a hardcoded 1/60
+            // makes smoothing converge ~6× too slowly in sub-60fps sessions.
+            const now = nowMs();
+            const constraintDt = this.lastConstraintEvalAtMs === undefined
+                ? 1 / 60
+                : Math.min(0.25, Math.max(1e-4, (now - this.lastConstraintEvalAtMs) / 1000));
+            this.lastConstraintEvalAtMs = now;
+            const constrained = this.runPoseConstraints(pose.pose, pose.binding, constraintDt);
+            constraintsMs = constrained.constraintsMs;
+            springsMs = constrained.springsMs;
+            for (const boneIndex of constrained.touched)
+                touchedBones.add(boneIndex);
+            for (const boneIndex of touchedBones) {
+                const name = pose.binding.jointNames[boneIndex];
+                const p = boneIndex * 3;
+                const q = boneIndex * 4;
+                sampledTargets.set(`${name}.translation`, [pose.pose.positions[p], pose.pose.positions[p + 1], pose.pose.positions[p + 2]]);
+                sampledTargets.set(`${name}.rotation`, [pose.pose.rotations[q], pose.pose.rotations[q + 1], pose.pose.rotations[q + 2], pose.pose.rotations[q + 3]]);
+                sampledTargets.set(`${name}.scale`, [pose.pose.scales[p], pose.pose.scales[p + 1], pose.pose.scales[p + 2]]);
+            }
+        }
         for (const [target, accumulator] of accumulators) {
             sampledTargets.set(target, finalizeTargetBlend(accumulator));
         }
-        this.lastApply = this.applySampledTargets(`blend:${names.join(",")}`, maxTime, { sampledTargets, unsupportedTracks }, samples.length);
+        this.lastApply = this.applySampledTargets(`blend:${names.join(",")}`, maxTime, { sampledTargets, unsupportedTracks }, samples.length, { mixerMs, constraintsMs, springsMs, paletteBytes: this.paletteBufferBytes(), cpuMs: nowMs() - phaseStart });
         return this.lastApply;
     }
+    /**
+     * §10 (PRD-06) — the scene-wide pose binding the pose path evaluates on.
+     * Joints are every scene node in `traverse` order, resolved by node index
+     * (duplicate names bind all slots); the rest pose is each node's local TRS
+     * captured at bind time.
+     */
+    skeletons() {
+        return [this.poseRuntime().binding];
+    }
+    /** §10 (PRD-06) — the per-clip compiled tracks used by the pose path. */
+    compiledClips() {
+        return this.poseRuntime().compiled;
+    }
+    /** §10 (PRD-06) — the per-runtime PoseMixer `applyClips` evaluates on. */
+    mixer() {
+        return this.poseRuntime().mixer;
+    }
+    /**
+     * T3.8 (PRD-06 §7.2, C-19) — `actor.animation.addClipsFrom(source)` retarget-
+     * bakes another skeleton's compiled clips onto this runtime's skeleton and
+     * registers them by name (raw + compiled + mixer) so `play`/`playLayer`
+     * resolve them like loaded clips. The bake runs in `pose/retarget.worker.ts`
+     * when the platform has workers, otherwise in-process, and its output is
+     * cached in IndexedDB under `(engineVersion, sourceHash, targetHash)` so a
+     * rollback ignores newer caches. Returns the registered clip names.
+     */
+    async addClipsFrom(source, options = {}) {
+        const pose = this.poseRuntime();
+        const sourceSkeleton = "skeletons" in source ? source.skeletons()[0] : source.skeleton;
+        const sourceClips = "compiledClips" in source ? source.compiledClips() : source.clips;
+        if (sourceSkeleton === undefined) {
+            throw new Error("addClipsFrom: source has no skeleton to retarget from.");
+        }
+        const engineVersion = options.engineVersion ?? AURA3D_RETARGET_ENGINE_VERSION;
+        const sourceHash = `${retargetSkeletonHash(sourceSkeleton)}:${retargetClipsHash(sourceClips)}`;
+        const targetHash = retargetSkeletonHash(pose.binding);
+        const key = retargetCacheKey(engineVersion, sourceHash, targetHash);
+        let baked = options.cache === false ? undefined : await readRetargetCache(key);
+        if (baked === undefined) {
+            const bakeOptions = {
+                ...(options.map !== undefined ? { map: options.map } : {}),
+                hipsScale: options.hipsScale ?? "leg-length",
+                ...(options.fingers !== undefined ? { fingers: options.fingers } : {}),
+                ...(options.retarget !== undefined ? { retarget: options.retarget } : {})
+            };
+            const worker = options.worker === false ? undefined : createRetargetWorker();
+            baked = worker !== undefined
+                ? await bakeClipsInWorker(worker, {
+                    sourceSkeleton,
+                    targetSkeleton: pose.binding,
+                    clips: sourceClips,
+                    options: bakeOptions
+                })
+                : bakeRetargetedClipMap({ skeleton: sourceSkeleton, clips: sourceClips }, pose.binding, bakeOptions);
+            if (options.cache !== false)
+                void writeRetargetCache(key, baked);
+        }
+        const names = [];
+        for (const [name, compiled] of baked) {
+            const raw = decompileCompiledClip(name, compiled);
+            this.clipsByName.set(name, raw);
+            pose.compiled.set(name, compiled);
+            pose.mixer.addCompiledClip(name, compiled, raw);
+            names.push(name);
+        }
+        return names;
+    }
+    /**
+     * T1.9 (PRD-06 §10) — advance the per-runtime `PoseMixer` by `dt` seconds
+     * and write the evaluated pose to scene nodes in `applySampledTargets`
+     * order. `restPoseReset !== false` writes every bound bone (rest-filled
+     * channels reset); `false` writes only the bones covered by active actions'
+     * bound tracks, so uncovered bones keep their current scene values.
+     * Non-pose tracks (morph weights, material/light pointer, node tracks
+     * aimed at nodes outside the binding) keep the legacy accumulator path,
+     * sampled at each active action's own clock and effective weight.
+     */
+    applyPoseMixer(dt, options) {
+        const phaseStart = nowMs();
+        const pose = this.poseRuntime();
+        const mixerStart = nowMs();
+        pose.mixer.update(dt);
+        pose.mixer.evaluate(pose.pose);
+        const mixerMs = nowMs() - mixerStart;
+        // T3.5 — constraints evaluate post-mixer / pre-palette; their touched
+        // bones union into `covered` so the write-back emits them.
+        this.lastConstraintEvalAtMs = nowMs();
+        const constrained = this.runPoseConstraints(pose.pose, pose.binding, dt);
+        const constraintsMs = constrained.constraintsMs;
+        const springsMs = constrained.springsMs;
+        const actions = pose.mixer.activeActions();
+        let covered;
+        if (options?.restPoseReset === false) {
+            const set = new Set();
+            for (const action of actions) {
+                for (const binding of action.bindings)
+                    set.add(binding.boneIndex);
+            }
+            for (const boneIndex of constrained.touched)
+                set.add(boneIndex);
+            covered = set;
+        }
+        // `covered === undefined` already emits every bound bone below — the
+        // constraint union matters only on the covered path.
+        const sampledTargets = new Map();
+        const writeBone = (boneIndex) => {
+            const name = pose.binding.jointNames[boneIndex];
+            const p = boneIndex * 3;
+            const q = boneIndex * 4;
+            sampledTargets.set(`${name}.translation`, [pose.pose.positions[p], pose.pose.positions[p + 1], pose.pose.positions[p + 2]]);
+            sampledTargets.set(`${name}.rotation`, [pose.pose.rotations[q], pose.pose.rotations[q + 1], pose.pose.rotations[q + 2], pose.pose.rotations[q + 3]]);
+            sampledTargets.set(`${name}.scale`, [pose.pose.scales[p], pose.pose.scales[p + 1], pose.pose.scales[p + 2]]);
+        };
+        if (covered === undefined) {
+            for (let i = 0; i < pose.binding.boneCount; i += 1)
+                writeBone(i);
+        }
+        else {
+            for (const boneIndex of covered)
+                writeBone(boneIndex);
+        }
+        // Legacy accumulator path for every track the pose binding does not
+        // cover — sampled at each action's clock and effective weight, in active
+        // action order (same semantics as `applyClips`' per-sample partition).
+        const accumulators = new Map();
+        const unsupportedTracks = [];
+        for (const action of actions) {
+            const source = this.clipsByName.get(action.clipName);
+            if (source === undefined)
+                continue;
+            for (const track of source.tracks) {
+                const target = parseAnimationTarget(track.target);
+                if (target === undefined) {
+                    unsupportedTracks.push(track.target);
+                    continue;
+                }
+                if (target.kind === "node" && target.path !== "weights") {
+                    const boneIndices = pose.binding.jointIndicesByName.get(target.nodeName);
+                    if (boneIndices !== undefined && boneIndices.length > 0)
+                        continue; // bound → mixer path
+                }
+                blendInto(accumulators, track.target, track.valueType, track.sample(action.time), action.effectiveWeight, action.additive);
+            }
+        }
+        for (const [target, accumulator] of accumulators) {
+            sampledTargets.set(target, finalizeTargetBlend(accumulator));
+        }
+        const active = actions.filter((action) => action.effectiveWeight > 0);
+        this.lastApply = this.applySampledTargets(`mixer:${options?.label ?? (actions.map((action) => action.clipName).join("+") || "idle")}`, active[0]?.time ?? 0, { sampledTargets, unsupportedTracks }, actions.length > 0 ? actions.length : undefined, { mixerMs, constraintsMs, springsMs, paletteBytes: this.paletteBufferBytes(), cpuMs: nowMs() - phaseStart });
+        return this.lastApply;
+    }
+    /**
+     * T1.10 (PRD-06 §10, C-19 `blendMode: "additive"`/`additiveReference`) — lazily
+     * compile an additive variant of `clipName` via `makeClipAdditive` (reference
+     * defaults to the clip's own first frame) and register it on the mixer under
+     * a synthesized name. Returns the registered clip key for `clipAction`/`playLayer`.
+     */
+    ensureAdditiveClip(clipName, reference) {
+        const pose = this.poseRuntime();
+        const source = this.clipsByName.get(clipName);
+        if (source === undefined) {
+            return clipName;
+        }
+        const referenceClip = reference?.clip === undefined ? undefined : this.clipsByName.get(reference.clip);
+        const referenceTime = reference?.time ?? 0;
+        const name = `${clipName}#additive:${reference?.clip ?? "self"}:${referenceTime}`;
+        if (!pose.compiled.has(name)) {
+            const additive = makeClipAdditive(source, referenceClip === undefined ? referenceTime : { clip: referenceClip, time: referenceTime });
+            const compiledClip = compileClip(additive);
+            pose.compiled.set(name, compiledClip);
+            pose.mixer.addCompiledClip(name, compiledClip, additive);
+        }
+        return name;
+    }
+    /**
+     * T1.10 (C-19 `animation.mask`) — bind-order joint names for `createBoneMask`.
+     */
+    skeletonJointNames() {
+        return this.poseRuntime().binding.jointNames;
+    }
+    /**
+     * T3.5 — register a pose constraint. Entries evaluate in insertion order
+     * after each mixer write; returns a disposer that removes exactly this
+     * constraint (by identity — a duplicate spec stays).
+     */
+    addPoseConstraint(constraint) {
+        const state = this.poseRuntime();
+        state.constraints.push(constraint);
+        let live = true;
+        return () => {
+            if (!live)
+                return;
+            live = false;
+            const index = state.constraints.indexOf(constraint);
+            if (index >= 0)
+                state.constraints.splice(index, 1);
+        };
+    }
+    /** T3.5 — drop every pose constraint (constant-time identity sweep). */
+    clearPoseConstraints() {
+        if (this.poseState === undefined)
+            return;
+        this.poseState.constraints.length = 0;
+    }
+    /** T3.5 — the count of live pose constraints (diagnostics/tests). */
+    poseConstraintCount() {
+        return this.poseState?.constraints.length ?? 0;
+    }
+    /** T3.5 — install the world→model matrix provider (actor extension). */
+    setPoseConstraintModelMatrix(provider) {
+        this.poseConstraintModelMatrix = provider;
+    }
+    /**
+     * T3.5 — evaluate the constraint list in order onto the just-mixed pose and
+     * return the union of touched joint indices (empty when no constraints),
+     * plus the §9.8 wall-clock split between `"springs"`-tagged constraints and
+     * the rest.
+     */
+    runPoseConstraints(pose, binding, dt) {
+        const touched = new Set();
+        const constraints = this.poseState?.constraints;
+        let constraintsMs = 0;
+        let springsMs = 0;
+        if (constraints === undefined || constraints.length === 0)
+            return { touched, constraintsMs, springsMs };
+        const modelMatrix = this.poseConstraintModelMatrix?.() ?? this.options.scene.root.transform.worldMatrix;
+        for (const constraint of constraints) {
+            const start = nowMs();
+            constraint.evaluate(pose, binding, modelMatrix, { dt });
+            const elapsed = nowMs() - start;
+            if (constraint.kind === "springs")
+                springsMs += elapsed;
+            else
+                constraintsMs += elapsed;
+            for (const bone of constraint.bones)
+                touched.add(bone);
+        }
+        return { touched, constraintsMs, springsMs };
+    }
+    /** §9.8/§13 — CPU-side palette payload this runtime owns, bytes (16 f32/joint). */
+    paletteBufferBytes() {
+        let bytes = 0;
+        for (const binding of this.skinningBindings)
+            bytes += binding.skin.joints.length * 16 * 4;
+        return bytes;
+    }
+    poseRuntime() {
+        if (this.poseState === undefined) {
+            const nodes = [];
+            this.options.scene.traverse((node) => nodes.push(node));
+            const indexByNode = new Map(nodes.map((node, index) => [node, index]));
+            const binding = bindSkeleton({
+                joints: nodes.map((_, index) => index),
+                resolveNode: (index) => {
+                    const node = nodes[index];
+                    if (node === undefined)
+                        return undefined;
+                    return { name: node.name, position: node.transform.position, rotation: node.transform.rotation, scale: node.transform.scale };
+                },
+                jointNames: nodes.map((node) => node.name),
+                parentIndices: nodes.map((node) => (node.parent === null ? -1 : indexByNode.get(node.parent) ?? -1))
+            });
+            const mixer = new PoseMixer({ skeleton: binding });
+            const compiled = new Map();
+            for (const [name, clip] of this.clipsByName) {
+                const compiledClip = compileClip(clip);
+                compiled.set(name, compiledClip);
+                mixer.addCompiledClip(name, compiledClip, clip);
+            }
+            this.poseState = { binding, mixer, compiled, pose: createPoseBuffer(binding.boneCount), constraints: [] };
+        }
+        return this.poseState;
+    }
     applyAnimationValues(label, time, values, unsupportedTracks = []) {
         if (label.trim().length === 0) {
             throw new Error("glTF animation runtime value application label cannot be empty.");
@@ -443,6 +992,22 @@ export class GLTFSceneAnimationRuntime {
         });
         return this.lastApply;
     }
+    /**
+     * §16 S3 (PRD-06) — teardown frees the C-18 palette textures this runtime
+     * stamped, keyed on each skin binding (`skinningPaletteCache.release`).
+     * Morph array textures and CPU-morph scratch are released by the actor's
+     * own teardown (`prd06.animation` extension dispose / pipeline lifecycle),
+     * which is the layer that can see resolved `Geometry` objects — the scene
+     * layer here only knows geometry handles.
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        for (const binding of this.skinningBindings) {
+            skinningPaletteCache.release(binding.paletteView?.paletteKey ?? binding);
+        }
+        this.disposed = true;
+    }
     /**
      * Render-time bridge: drive the loaded GLB from an externally-computed pose whose keys are GLB
      * **node names** (e.g. the output of `@aura3d/animation`'s `retargetHumanoidPose`, whose
@@ -585,6 +1150,8 @@ export class GLTFSceneAnimationRuntime {
         return [...this.clipsByName.values()].map((clip) => this.inspectClipBinding(clip));
     }
     reindexScene() {
+        this.poseState = undefined;
+        this.lastConstraintEvalAtMs = undefined;
         this.options.scene.updateWorldTransforms();
         this.footBindMatrices.clear();
         this.footOrientationLocks.clear();
@@ -617,7 +1184,7 @@ export class GLTFSceneAnimationRuntime {
                 const skin = mesh?.skinIndex === undefined ? undefined : this.options.asset.skins[mesh.skinIndex];
                 if (!mesh || !skin || skin.joints.length > MAX_RENDERABLE_SKINNING_JOINTS)
                     continue;
-                this.skinningBindings.push({ node, renderable, mesh, skin, bindWorldMatrix: [...node.transform.worldMatrix] });
+                this.skinningBindings.push({ node, renderable, mesh, skin, bindWorldMatrix: [...node.transform.worldMatrix], paletteMatrices: new Float32Array(skin.joints.length * 16) });
             }
         }
     }
@@ -939,36 +1506,64 @@ export class GLTFSceneAnimationRuntime {
         return samples;
     }
     refreshSkinningPalettes() {
+        const result = this.paletteResult;
+        result.updated = 0;
+        result.missingTargets.length = 0;
         if (this.skinningBindings.length === 0) {
-            return { updated: 0, missingTargets: [] };
+            return result;
         }
-        let updated = 0;
-        const missingTargets = [];
+        const missingTargets = result.missingTargets;
         for (const binding of this.skinningBindings) {
-            const matrices = new Float32Array(binding.skin.joints.length * 16);
-            const inverseMeshWorld = invertMat4(binding.node.transform.worldMatrix);
+            // T0.11: write into the binding's persistent palette buffer — no per-frame
+            // Float32Array allocation, and the renderer's C-18 cache can key on it.
+            const matrices = binding.paletteMatrices;
+            const inverseMeshWorld = invertMat4Into(this.inverseWorldScratch, binding.node.transform.worldMatrix);
+            // §13: joint nodes resolved once per binding instead of a string Map
+            // lookup per joint per frame; the cache rebuilds while any joint is
+            // missing so late-registered nodes still resolve.
+            let jointNodes = binding.jointNodes;
+            if (!jointNodes) {
+                jointNodes = new Array(binding.skin.jointNames.length);
+                let allResolved = true;
+                for (let index = 0; index < binding.skin.jointNames.length; index += 1) {
+                    const node = this.nodesByName.get(binding.skin.jointNames[index])?.[0];
+                    jointNodes[index] = node;
+                    if (!node)
+                        allResolved = false;
+                }
+                if (allResolved)
+                    binding.jointNodes = jointNodes;
+            }
             let complete = true;
             for (let index = 0; index < binding.skin.jointNames.length; index += 1) {
-                const jointName = binding.skin.jointNames[index];
-                const jointNode = this.nodesByName.get(jointName)?.[0];
+                const jointNode = jointNodes[index];
                 const inverseBind = binding.skin.inverseBindMatrices[index];
                 if (!jointNode || !inverseBind) {
-                    missingTargets.push(`${binding.skin.name}.${jointName}`);
+                    missingTargets.push(`${binding.skin.name}.${binding.skin.jointNames[index]}`);
                     complete = false;
                     break;
                 }
-                const jointMatrix = multiplyMat4(multiplyMat4(inverseMeshWorld, jointNode.transform.worldMatrix), inverseBind);
-                matrices.set(jointMatrix, index * 16);
+                // (inverseMeshWorld * jointWorld) * inverseBind, straight into the palette.
+                multiplyMat4Into(this.paletteScratch, 0, inverseMeshWorld, jointNode.transform.worldMatrix);
+                multiplyMat4Into(matrices, index * 16, this.paletteScratch, inverseBind);
             }
             if (!complete)
                 continue;
-            binding.renderable.skinning = {
-                jointCount: binding.skin.joints.length,
-                matrices
-            };
-            updated += 1;
+            let skinningPalette = binding.paletteView;
+            if (!skinningPalette) {
+                skinningPalette = {
+                    jointCount: binding.skin.joints.length,
+                    matrices
+                };
+                binding.paletteView = skinningPalette;
+            }
+            // C-18/§9.2: the stable per-skin key the palette cache binds on is this
+            // binding object, not the per-frame `renderable.skinning` wrapper (E40).
+            skinningPalette.paletteKey = binding;
+            binding.renderable.skinning = skinningPalette;
+            result.updated += 1;
         }
-        return { updated, missingTargets };
+        return result;
     }
     inspectClipBinding(clip) {
         let supportedTrackCount = 0;
@@ -1049,7 +1644,7 @@ export class GLTFSceneAnimationRuntime {
             animatesSkeleton: this.skinningBindings.length > 0 && boundTrackCount > 0 && transformTrackCount > 0
         };
     }
-    applySampledTargets(clipName, time, sampled, blendedClipCount) {
+    applySampledTargets(clipName, time, sampled, blendedClipCount, phaseTimings) {
         let transformTracksApplied = 0;
         let morphWeightTracksApplied = 0;
         let materialTracksApplied = 0;
@@ -1117,7 +1712,8 @@ export class GLTFSceneAnimationRuntime {
             ...(measuredFootPlanting === undefined ? {} : { footPlanting: measuredFootPlanting }),
             skinningPalettesUpdated: skinning.updated,
             missingTargets: [...missingTargets, ...skinning.missingTargets],
-            unsupportedTracks: sampled.unsupportedTracks
+            unsupportedTracks: sampled.unsupportedTracks,
+            ...(phaseTimings === undefined ? {} : { phaseTimings })
         };
     }
 }
@@ -1727,4 +2323,44 @@ function multiplyQuat(a, b) {
         a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2]
     ];
 }
+/**
+ * T0.6/T0.7 (PRD-06) — a clip "has a root-motion candidate" when a translation
+ * track on a hips/root-named target nets more than 5 cm of XZ displacement
+ * between its first and last keyframes.
+ */
+function clipHasRootMotionCandidate(clip) {
+    for (const track of clip.tracks) {
+        const target = parseAnimationTarget(track.target);
+        if (target?.kind !== "node" || target.path !== "translation")
+            continue;
+        if (!/hips|root|pelvis/i.test(target.nodeName))
+            continue;
+        const keys = track.keyframes ?? [];
+        if (keys.length < 2)
+            continue;
+        const first = vec3OfKeyframeValue(keys[0].value);
+        const last = vec3OfKeyframeValue(keys[keys.length - 1].value);
+        if (!first || !last)
+            continue;
+        const dx = last[0] - first[0];
+        const dz = last[2] - first[2];
+        if (Math.hypot(dx, dz) > 0.05)
+            return true;
+    }
+    return false;
+}
+function vec3OfKeyframeValue(value) {
+    if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+        const arr = value;
+        if (arr.length >= 3)
+            return [arr[0], arr[1], arr[2]];
+        return undefined;
+    }
+    if (value && typeof value === "object") {
+        const v = value;
+        if (typeof v.x === "number" && typeof v.z === "number")
+            return [v.x, v.y ?? 0, v.z];
+    }
+    return undefined;
+}
 //# sourceMappingURL=GLTFAnimationRuntime.js.map