@aura3d/engine 3.0.0 → 4.0.0

package/dist/assets/GLTFAnimationRuntime.js

@@ -1,5 +1,8 @@
-import { AnimationAction, AnimationClip, AnimationMixer, createFootIkRig, normalizeQuat, slerpQuat, solveTwoBoneIk } from "../animation/browser-index.js";
-import { invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "../scene/index.js";
+import { AnimationAction, AnimationClip, AnimationMixer, consumeRootMotion, extractRootMotion, createFootIkRig, normalizeQuat, slerpQuat, solveTwoBoneIk } from "../animation/browser-index.js";
+import { bindSkeleton, compileClip, createPoseBuffer, makeClipAdditive, PoseMixer } from "../animation/lanes/index.js";
+import { AURA3D_RETARGET_ENGINE_VERSION, bakeClipsInWorker, bakeRetargetedClipMap, createRetargetWorker, decompileCompiledClip, readRetargetCache, retargetCacheKey, retargetClipsHash, retargetSkeletonHash, writeRetargetCache } from "../animation/lanes/index.js";
+import { composeMat4, decomposeMat4, invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "../scene/index.js";
+import { skinningPaletteCache } from "../rendering/index.js";
 /**
  * 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,15 +269,104 @@ 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();
+    footSurfaceVertices = new Map();
     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) {
@@ -284,9 +389,150 @@ export class GLTFSceneAnimationRuntime {
         }
         if (!sameFootPlantingShape(this.footPlanting, config)) {
             this.footRig = undefined;
+            this.footOrientationLocks.clear();
+            this.footDescendantLocks.clear();
         }
         this.footPlanting = config;
     }
+    /**
+     * Extract real authored displacement over unwrapped clip time, hand it to the physical
+     * authority once, then apply an in-place root pose and solve feet in the updated actor
+     * transform. Rejected movement is returned and discarded rather than accumulating drift.
+     * The caller refreshes footPlanting.worldFromLocal inside move after committing movement.
+     */
+    applyRootMotionClip(name, options) {
+        return this.applyRootMotionClips([{ clipName: name, ...options }], options);
+    }
+    /** Blend displacement and consumed poses with the same base/additive weights. */
+    applyRootMotionClips(samples, options) {
+        if (samples.length === 0)
+            throw new Error("glTF root motion blend requires at least one clip sample.");
+        const accumulators = new Map();
+        const motionAccumulators = new Map();
+        const unsupportedTracks = [];
+        const names = [];
+        let maxTime = 0;
+        // Finish validation and sampling before the physical authority can mutate the actor.
+        for (const sample of samples) {
+            const clip = this.clipsByName.get(sample.clipName);
+            if (!clip)
+                throw new Error(`glTF animation clip "${sample.clipName}" was not found.`);
+            const weight = sample.weight ?? 1;
+            if (!Number.isFinite(weight) || weight < 0)
+                throw new Error("glTF root motion blend weight must be finite and non-negative.");
+            const extracted = extractRootMotion(clip, sample);
+            if (weight === 0)
+                continue;
+            const time = sample.loop && clip.duration > 0
+                ? ((sample.toTime % clip.duration) + clip.duration) % clip.duration
+                : Math.max(0, Math.min(clip.duration, sample.toTime));
+            maxTime = Math.max(maxTime, time);
+            names.push(`${clip.name}@${time}x${weight}${sample.additive ? "+add" : ""}`);
+            blendInto(motionAccumulators, "motion", "vector3", extracted.delta, weight, sample.additive === true);
+            for (const track of clip.tracks) {
+                if (!parseAnimationTarget(track.target)) {
+                    unsupportedTracks.push(track.target);
+                    continue;
+                }
+                // Consume each clip's own root before blending, including additive root tracks.
+                const value = track.sample(track.target === sample.target ? 0 : time);
+                blendInto(accumulators, track.target, track.valueType, value, weight, sample.additive === true);
+            }
+        }
+        const values = new Map();
+        for (const [target, accumulator] of accumulators)
+            values.set(target, finalizeTargetBlend(accumulator));
+        const motionAccumulator = motionAccumulators.get("motion");
+        const delta = motionAccumulator ? finalizeTargetBlend(motionAccumulator) : [0, 0, 0];
+        const motion = consumeRootMotion({ target: "blend", fromTime: 0, toTime: maxTime, looped: samples.some(sample => sample.loop), delta }, options.worldFromLocal, options.move);
+        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) {
@@ -298,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}
@@ -326,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) {
@@ -351,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, { 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));
         }
-        this.lastApply = this.applySampledTargets(`blend:${names.join(",")}`, maxTime, { sampledTargets, unsupportedTracks }, samples.length);
+        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.");
@@ -383,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
@@ -525,10 +1150,18 @@ 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();
+        this.footDescendantLocks.clear();
         this.nodesByName.clear();
         this.morphRenderablesByNodeName.clear();
         this.skinningBindings.length = 0;
+        this.footSurfaceVertices.clear();
         this.options.scene.traverse((node) => {
+            this.footBindMatrices.set(node.id, { world: [...node.transform.worldMatrix], local: [...node.transform.localMatrix] });
             const nodes = this.nodesByName.get(node.name) ?? [];
             nodes.push(node);
             this.nodesByName.set(node.name, nodes);
@@ -551,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 });
+                this.skinningBindings.push({ node, renderable, mesh, skin, bindWorldMatrix: [...node.transform.worldMatrix], paletteMatrices: new Float32Array(skin.joints.length * 16) });
             }
         }
     }
@@ -559,9 +1192,9 @@ export class GLTFSceneAnimationRuntime {
         return this.options.scene.collectLights().find((light) => light.name === name);
     }
     /**
-     * Foot-planting post-pass (E2): solves the configured leg chains against the ground and
-     * writes the solved hip/knee/ankle world positions back onto the skeleton. Position-only
-     * write-back (rotations stay as animated); missing leg nodes are reported in
+     * Foot-planting post-pass (E2): solves the configured leg chains against the ground,
+     * applies a shared pelvis reach correction, and rotates rigid hip/knee chains toward the
+     * solved targets. Missing leg nodes are reported in
      * `missingLegNodes` and skipped, never faked. Returns undefined when unconfigured.
      */
     applyFootPlanting() {
@@ -595,11 +1228,20 @@ export class GLTFSceneAnimationRuntime {
                 missingLegNodes.push(`${leg.side}:ankle:${leg.ankle}`);
             if (!hip || !knee || !ankle)
                 continue;
-            resolved.push({ side: leg.side, hip, knee, ankle, pole: leg.pole });
+            resolved.push({ side: leg.side, hip, knee, ankle, pole: leg.pole, ...(leg.contact === undefined ? {} : { contact: leg.contact }), ...(leg.support ? { support: leg.support } : {}) });
         }
         if (resolved.length === 0) {
             return { groundedFeet: 0, averageTargetError: 0, lockedSides: [], missingLegNodes, hipOffset: 0 };
         }
+        // Measure each animated ankle-to-sole offset from the exact pre-solve skinning
+        // palette. One global value cannot plant asymmetric shoes or a rotated touchdown.
+        this.refreshSkinningPalettes();
+        const rawSoles = this.sampleFootSurfaces();
+        const measuredAnkleHeights = new Map(resolved.map(entry => {
+            const ankle = solvePoint(worldPosition(entry.ankle));
+            const minimum = Math.min(Infinity, ...rawSoles.filter(point => point.side === entry.side).map(point => point.worldPosition[1]));
+            return [entry.side, Number.isFinite(minimum) ? Math.max(0, ankle[1] - minimum) : undefined];
+        }));
         if (!this.footRig) {
             this.footRig = createFootIkRig({
                 legs: resolved.map((entry) => ({
@@ -607,6 +1249,7 @@ export class GLTFSceneAnimationRuntime {
                     hip: solvePoint(worldPosition(entry.hip)),
                     knee: solvePoint(worldPosition(entry.knee)),
                     ankle: solvePoint(worldPosition(entry.ankle)),
+                    ...(measuredAnkleHeights.get(entry.side) ?? config.ankleHeight) !== undefined ? { ankleHeight: measuredAnkleHeights.get(entry.side) ?? config.ankleHeight } : {},
                     ...(entry.pole ? { pole: entry.pole } : {})
                 })),
                 raycaster: config.ground,
@@ -617,38 +1260,116 @@ export class GLTFSceneAnimationRuntime {
                 ...(config.hipDropFactor !== undefined ? { hipDropFactor: config.hipDropFactor } : {})
             });
         }
+        const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+        const originalLengths = new Map(resolved.map(entry => [entry.side, {
+                upper: distance(solvePoint(worldPosition(entry.hip)), solvePoint(worldPosition(entry.knee))),
+                lower: distance(solvePoint(worldPosition(entry.knee)), solvePoint(worldPosition(entry.ankle)))
+            }]));
         const solved = this.footRig.solveFootPlacement({
             legs: resolved.map((entry) => ({
                 side: entry.side,
                 hip: solvePoint(worldPosition(entry.hip)),
                 knee: solvePoint(worldPosition(entry.knee)),
                 ankle: solvePoint(worldPosition(entry.ankle)),
-                ...(entry.pole ? { pole: entry.pole } : {})
+                ...(measuredAnkleHeights.get(entry.side) ?? config.ankleHeight) !== undefined ? { ankleHeight: measuredAnkleHeights.get(entry.side) ?? config.ankleHeight } : {},
+                ...(entry.pole ? { pole: entry.pole } : {}),
+                ...(entry.contact === undefined ? {} : { contact: entry.contact }),
+                ...(entry.support ? { support: entry.support } : {})
             }))
         });
+        // A reach correction belongs to the shared pelvis owner. Move it once before
+        // rotating either leg; translating each upper-leg root dislocates the chain,
+        // while omitting the drop leaves a fully extended stance foot above ground.
+        if (solved.hipOffset < 0) {
+            const common = commonAncestor(resolved.map(entry => entry.hip));
+            const anchors = common && common.parent ? [common] : [...new Set(resolved.map(entry => entry.hip))];
+            for (const anchor of anchors) {
+                const currentWorld = solvePoint(worldPosition(anchor));
+                const dropped = actorPoint([currentWorld[0], currentWorld[1] + solved.hipOffset, currentWorld[2]]);
+                setWorldPosition(anchor, dropped);
+            }
+            this.options.scene.updateWorldTransforms();
+        }
         for (const foot of solved.feet) {
             const entry = resolved.find((candidate) => candidate.side === foot.side);
             if (!entry)
                 continue;
-            // The rig returns the pelvis drop separately: apply it to the hip so an over-extended
-            // leg can reach its planted foot. Solved knee/ankle targets already account for the
-            // drop — the rig re-solves over-extended legs from the dropped hip — so they write
-            // back directly; a leg that needed no drop keeps phase-one targets and lets its knee
-            // absorb the pelvis motion by bending, the natural single-pelvis compromise.
-            // Refresh down the chain after each write: setWorldPosition reads the parent's world
-            // matrix, so the knee must see the new hip world before its own write (same for ankle).
-            // Solved targets are world-space; convert to actor-local for the write-back.
-            const hipTarget = actorPoint([foot.hip[0], foot.hip[1] + solved.hipOffset, foot.hip[2]]);
-            setWorldPosition(entry.hip, [hipTarget[0], hipTarget[1], hipTarget[2]]);
-            entry.hip.updateWorldTransform();
+            // Apply the two-bone solution with joint rotations. Moving hip/knee/ankle
+            // translations directly changes authored bone lengths and deforms every weighted
+            // mesh. The solver targets are world-space; orient each parent toward its solved
+            // child while preserving the animation's local translations and scales.
             const kneeTarget = actorPoint(foot.knee);
-            setWorldPosition(entry.knee, [kneeTarget[0], kneeTarget[1], kneeTarget[2]]);
-            entry.knee.updateWorldTransform();
+            orientJointToward(entry.hip, entry.knee, kneeTarget);
+            entry.hip.updateWorldTransform();
             const ankleTarget = actorPoint(foot.ankle);
-            setWorldPosition(entry.ankle, [ankleTarget[0], ankleTarget[1], ankleTarget[2]]);
+            orientJointToward(entry.knee, entry.ankle, ankleTarget);
+            entry.knee.updateWorldTransform();
+        }
+        this.options.scene.updateWorldTransforms();
+        for (const foot of solved.feet) {
+            const entry = resolved.find(candidate => candidate.side === foot.side);
+            if (!foot.locked || config.lockFootRotation === false) {
+                this.footOrientationLocks.delete(foot.side);
+                this.footDescendantLocks.delete(foot.side);
+                continue;
+            }
+            let locked = this.footOrientationLocks.get(foot.side);
+            if (!locked) {
+                // Capture the actual animated sole orientation and toe pose at touchdown.
+                // Reusing the asset bind pose snaps arbitrary rigs and moves their sole vertices.
+                locked = toWorld ? multiplyMat4(toWorld, entry.ankle.transform.worldMatrix) : [...entry.ankle.transform.worldMatrix];
+                const descendants = new Map();
+                entry.ankle.children.forEach(child => child.traverse(node => descendants.set(node.id, [...node.transform.localMatrix])));
+                this.footDescendantLocks.set(foot.side, descendants);
+                const normal = foot.sample.groundNormal;
+                const norm = Math.hypot(...normal);
+                if (!(norm > 0))
+                    throw new Error("Foot contact requires a nonzero ground normal.");
+                const nx = normal[0] / norm, ny = normal[1] / norm, nz = normal[2] / norm;
+                if (ny <= -0.999)
+                    throw new Error("Foot contact cannot plant on a downward facing surface.");
+                const vx = nz, vz = -nx, t = 1 / (1 + ny);
+                const tilt = [1 - vz * vz * t, vz, vx * vz * t, 0, -vz, 1 - (vx * vx + vz * vz) * t, vx, 0, vx * vz * t, -vx, 1 - vx * vx * t, 0, 0, 0, 0, 1];
+                locked = multiplyMat4(tilt, locked);
+                this.footOrientationLocks.set(foot.side, locked);
+            }
+            // Keep the solved ankle position while holding the sole orientation in world space.
+            const ankleWorld = solvePoint(worldPosition(entry.ankle));
+            const desired = [...locked];
+            desired[12] = ankleWorld[0];
+            desired[13] = ankleWorld[1];
+            desired[14] = ankleWorld[2];
+            const actorMatrix = toLocal ? multiplyMat4(toLocal, desired) : desired;
+            const parent = entry.ankle.parent;
+            const local = parent ? multiplyMat4(invertMat4(parent.transform.worldMatrix), actorMatrix) : actorMatrix;
+            entry.ankle.transform.setFromLocalMatrix(local);
+            // Toe joints remain in their touchdown relationship during stance; animated
+            // toe curl otherwise moves the sole while the ankle still reports zero slip.
+            const touchdown = this.footDescendantLocks.get(foot.side);
+            const restore = (node) => {
+                const rest = touchdown?.get(node.id);
+                if (rest)
+                    node.transform.setFromLocalMatrix(rest);
+                node.children.forEach(restore);
+            };
+            entry.ankle.children.forEach(restore);
+            entry.ankle.updateWorldTransform();
         }
         this.options.scene.updateWorldTransforms();
         return {
+            legDeformation: resolved.map(entry => {
+                const before = originalLengths.get(entry.side);
+                const upperAfter = distance(solvePoint(worldPosition(entry.hip)), solvePoint(worldPosition(entry.knee)));
+                const lowerAfter = distance(solvePoint(worldPosition(entry.knee)), solvePoint(worldPosition(entry.ankle)));
+                return { side: entry.side, upperBefore: before.upper, lowerBefore: before.lower, upperAfter, lowerAfter,
+                    maxRelativeLengthChange: Math.max(Math.abs(upperAfter - before.upper) / Math.max(1e-9, before.upper), Math.abs(lowerAfter - before.lower) / Math.max(1e-9, before.lower)) };
+            }),
+            feet: solved.feet.map(foot => {
+                const entry = resolved.find(candidate => candidate.side === foot.side);
+                const position = solvePoint(worldPosition(entry.ankle));
+                return { side: foot.side, worldPosition: position, locked: foot.locked,
+                    contactError: Math.hypot(...position.map((value, axis) => value - foot.sample.plantedFoot[axis])) };
+            }),
             groundedFeet: solved.groundedFeet,
             averageTargetError: solved.averageTargetError,
             lockedSides: solved.feet.filter((foot) => foot.locked).map((foot) => foot.side),
@@ -699,37 +1420,150 @@ export class GLTFSceneAnimationRuntime {
         light.range = asPositiveScalar(value, trackTarget);
         return true;
     }
+    /** CPU skinning oracle using the exact palette submitted to rendering, not IK targets. */
+    sampleFootSurfaces() {
+        const config = this.footPlanting;
+        if (!config)
+            return [];
+        const samples = [];
+        for (const leg of config.legs) {
+            const ankle = this.nodesByName.get(leg.ankle)?.[0];
+            if (!ankle)
+                continue;
+            const footNames = new Set();
+            const visit = (node) => { footNames.add(node.name); node.children.forEach(visit); };
+            visit(ankle);
+            for (const binding of this.skinningBindings) {
+                const palette = binding.renderable.skinning;
+                if (!palette)
+                    continue;
+                const mesh = binding.mesh;
+                const cacheKey = `${leg.ankle}:${binding.node.id}:${mesh.name}`;
+                let selected = this.footSurfaceVertices.get(cacheKey);
+                if (!selected) {
+                    const candidates = [];
+                    for (let vertex = 0; vertex < mesh.positions.length; vertex++) {
+                        let footWeight = 0;
+                        for (let lane = 0; lane < 4; lane++) {
+                            if (footNames.has(binding.skin.jointNames[mesh.joints[vertex]?.[lane] ?? -1] ?? ""))
+                                footWeight += mesh.weights[vertex]?.[lane] ?? 0;
+                            if (footNames.has(binding.skin.jointNames[mesh.joints1?.[vertex]?.[lane] ?? -1] ?? ""))
+                                footWeight += mesh.weights1?.[vertex]?.[lane] ?? 0;
+                        }
+                        if (footWeight >= 0.5)
+                            candidates.push(vertex);
+                    }
+                    if (!candidates.length) {
+                        this.footSurfaceVertices.set(cacheKey, []);
+                        continue;
+                    }
+                    // Fixed bind-space sole strip: never reselect vertices from animated positions.
+                    const bindHeights = new Map(candidates.map(vertex => [vertex, transformPoint(binding.bindWorldMatrix, [...mesh.positions[vertex]])[1]]));
+                    const ys = [...bindHeights.values()];
+                    const minimum = Math.min(...ys), maximum = Math.max(...ys);
+                    const strip = Math.max(1e-6, (maximum - minimum) * 0.001);
+                    selected = candidates.filter(index => bindHeights.get(index) <= minimum + strip);
+                    this.footSurfaceVertices.set(cacheKey, selected);
+                }
+                const toWorld = config.worldFromLocal ? multiplyMat4(config.worldFromLocal, binding.node.transform.worldMatrix) : binding.node.transform.worldMatrix;
+                for (const vertex of selected) {
+                    const authored = [...mesh.positions[vertex]];
+                    for (let morph = 0; morph < mesh.morphTargets.length; morph++) {
+                        const weight = binding.renderable.morphWeights?.[morph] ?? 0;
+                        const delta = mesh.morphTargets[morph]?.positions[vertex];
+                        if (delta && weight)
+                            for (let axis = 0; axis < 3; axis++)
+                                authored[axis] += delta[axis] * weight;
+                    }
+                    const skinned = [0, 0, 0];
+                    let total = 0;
+                    for (let set = 0; set < 2; set++)
+                        for (let lane = 0; lane < 4; lane++) {
+                            const weight = (set ? mesh.weights1?.[vertex]?.[lane] : mesh.weights[vertex]?.[lane]) ?? 0;
+                            const joint = (set ? mesh.joints1?.[vertex]?.[lane] : mesh.joints[vertex]?.[lane]) ?? -1;
+                            if (weight <= 0)
+                                continue;
+                            if (joint < 0 || joint >= palette.jointCount)
+                                throw new Error("Foot surface vertex has an invalid palette influence.");
+                            const point = transformPoint(Array.from(palette.matrices.subarray(joint * 16, joint * 16 + 16)), authored);
+                            for (let axis = 0; axis < 3; axis++)
+                                skinned[axis] += point[axis] * weight;
+                            total += weight;
+                        }
+                    if (Math.abs(total - 1) > 0.001)
+                        throw new Error("Foot surface vertex weights must sum to one.");
+                    const worldPosition = transformPoint(toWorld, skinned);
+                    const hit = config.ground.raycastDown([worldPosition[0], worldPosition[1] + 2, worldPosition[2]], 4);
+                    samples.push({ side: leg.side, mesh: `${binding.node.userData.gltfNodeIndex ?? binding.node.name}:${mesh.name}`, vertex, worldPosition,
+                        groundError: hit ? worldPosition[1] - hit.point[1] : null,
+                        ...(vertex === selected[0] ? { skinningProbe: { position: authored,
+                                joints: [...(mesh.joints[vertex] ?? [0, 0, 0, 0]), ...(mesh.joints1?.[vertex] ?? [0, 0, 0, 0])],
+                                weights: [...(mesh.weights[vertex] ?? [0, 0, 0, 0]), ...(mesh.weights1?.[vertex] ?? [0, 0, 0, 0])],
+                                matrices: Array.from(palette.matrices), modelMatrix: [...toWorld], expectedWorldPosition: worldPosition } } : {}) });
+                }
+            }
+        }
+        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;
@@ -810,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;
@@ -865,6 +1699,7 @@ export class GLTFSceneAnimationRuntime {
         this.options.scene.updateWorldTransforms();
         const footPlanting = this.applyFootPlanting();
         const skinning = this.refreshSkinningPalettes();
+        const measuredFootPlanting = footPlanting ? { ...footPlanting, surfaces: this.sampleFootSurfaces() } : undefined;
         return {
             clipName,
             time,
@@ -874,10 +1709,11 @@ export class GLTFSceneAnimationRuntime {
             morphWeightTracksApplied,
             materialTracksApplied,
             lightTracksApplied,
-            ...(footPlanting === undefined ? {} : { footPlanting }),
+            ...(measuredFootPlanting === undefined ? {} : { footPlanting: measuredFootPlanting }),
             skinningPalettesUpdated: skinning.updated,
             missingTargets: [...missingTargets, ...skinning.missingTargets],
-            unsupportedTracks: sampled.unsupportedTracks
+            unsupportedTracks: sampled.unsupportedTracks,
+            ...(phaseTimings === undefined ? {} : { phaseTimings })
         };
     }
 }
@@ -896,6 +1732,7 @@ export class GLTFSceneAnimationMixerBinding {
     constructor(options) {
         this.runtime = new GLTFSceneAnimationRuntime(options);
         this.mixer = new AnimationMixer({
+            ...(options.consumeRootMotion ? { consumeRootMotion: options.consumeRootMotion } : {}),
             setAnimationValue: (target, value) => {
                 this.pendingValues.set(target, cloneAnimationValue(value));
             }
@@ -1200,6 +2037,8 @@ function sameFootPlantingShape(previous, next) {
         return false;
     if (previous.hipDropFactor !== next.hipDropFactor)
         return false;
+    if (previous.lockFootRotation !== next.lockFootRotation)
+        return false;
     if (previous.legs.length !== next.legs.length)
         return false;
     return previous.legs.every((leg, index) => {
@@ -1209,6 +2048,7 @@ function sameFootPlantingShape(previous, next) {
             && leg.hip === other.hip
             && leg.knee === other.knee
             && leg.ankle === other.ankle
+            && leg.ankleHeight === other.ankleHeight
             && (leg.pole ?? []).join(",") === (other.pole ?? []).join(",");
     });
 }
@@ -1216,6 +2056,47 @@ function worldPosition(node) {
     node.updateWorldTransform();
     return [node.transform.worldMatrix[12], node.transform.worldMatrix[13], node.transform.worldMatrix[14]];
 }
+function commonAncestor(nodes) {
+    if (nodes.length === 0)
+        return undefined;
+    const first = [];
+    for (let node = nodes[0]; node; node = node.parent)
+        first.push(node);
+    return first.find(candidate => nodes.every(node => node === candidate || candidate.isAncestorOf(node)));
+}
+function orientJointToward(node, child, target) {
+    node.updateWorldTransform();
+    child.updateWorldTransform();
+    const origin = worldPosition(node);
+    const current = worldPosition(child);
+    const from = [current[0] - origin[0], current[1] - origin[1], current[2] - origin[2]];
+    const to = [target[0] - origin[0], target[1] - origin[1], target[2] - origin[2]];
+    const delta = quatFromUnitVectors(from, to);
+    const worldRotation = multiplyRigidQuat(delta, decomposeMat4(node.transform.worldMatrix).rotation);
+    const parentRotation = node.parent ? decomposeMat4(node.parent.transform.worldMatrix).rotation : [0, 0, 0, 1];
+    const localRotation = multiplyRigidQuat(invertRigidQuat(parentRotation), worldRotation);
+    node.transform.setRotation(localRotation[0], localRotation[1], localRotation[2], localRotation[3]);
+}
+function quatFromUnitVectors(from, to) {
+    const fl = Math.hypot(...from), tl = Math.hypot(...to);
+    if (!(fl > 1e-12) || !(tl > 1e-12))
+        return [0, 0, 0, 1];
+    const fx = from[0] / fl, fy = from[1] / fl, fz = from[2] / fl, tx = to[0] / tl, ty = to[1] / tl, tz = to[2] / tl;
+    const dot = fx * tx + fy * ty + fz * tz;
+    if (dot < -0.999999) {
+        const axis = Math.abs(fx) > 0.1 ? [-fz, 0, fx] : [0, fz, -fy];
+        const length = Math.hypot(...axis);
+        return [axis[0] / length, axis[1] / length, axis[2] / length, 0];
+    }
+    if (dot > 0.999999)
+        return [0, 0, 0, 1];
+    return normalizeQuaternion([fy * tz - fz * ty, fz * tx - fx * tz, fx * ty - fy * tx, 1 + dot]);
+}
+function multiplyRigidQuat(a, b) {
+    return normalizeQuaternion([a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1], a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0], a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3], a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2]]);
+}
+function invertRigidQuat(q) { return [-q[0], -q[1], -q[2], q[3]]; }
+function normalizeQuaternion(q) { const n = Math.hypot(...q); return n > 0 ? [q[0] / n, q[1] / n, q[2] / n, q[3] / n] : [0, 0, 0, 1]; }
 function setWorldPosition(node, position) {
     const local = node.parent
         ? transformPoint(invertMat4(node.parent.transform.worldMatrix), [position[0], position[1], position[2]])
@@ -1442,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