@aura3d/engine 1.0.10 → 1.3.0

package/dist/animation/HumanoidBoneInference.js

@@ -0,0 +1,239 @@
+import { HUMANOID_BONES, REQUIRED_HUMANOID_BONES } from "./HumanoidRetargeting.js";
+/**
+ * Per-logical-group "core" tokens. These are matched against normalized node names. Side-bearing
+ * groups omit the side here — sidedness is detected separately (`L_`, `Left`, `_l`, `.R`, etc.) so
+ * a single table serves both sides. Keys are *logical groups* (`shoulder`, `upperArm`, …), not
+ * {@link HumanoidBoneName}s; the side-resolved slots are derived below in {@link SLOT_SPECS}.
+ */
+const ALIAS_BY_KEY = {
+    hips: ["hips", "hip", "pelvis", "root", "cog", "bip01pelvis"],
+    spine: ["spine", "spine0", "spine00", "spine1", "spine01", "abdomen", "lowerback", "torso"],
+    chest: ["chest", "spine2", "spine02", "spine3", "ribcage", "upperback"],
+    upperChest: ["upperchest", "spine3", "spine03", "spine4", "upperchestspine"],
+    neck: ["neck", "neck0", "neck01", "neck1"],
+    head: ["head"],
+    shoulder: ["shoulder", "clavicle", "collar", "scapula"],
+    upperArm: ["upperarm", "armupper", "arm", "uparm", "shoulderarm", "humerus", "armupper01"],
+    lowerArm: ["lowerarm", "armlower", "forearm", "loarm", "elbow", "ulna", "armlower01"],
+    hand: ["hand", "wrist", "palm"],
+    upperLeg: ["upperleg", "legupper", "thigh", "upleg", "legupper01", "femur"],
+    lowerLeg: ["lowerleg", "leglower", "calf", "shin", "leg", "loleg", "knee", "leglower01", "tibia"],
+    foot: ["foot", "ankle"],
+    toes: ["toe", "toes", "toebase", "ball"]
+};
+const REQUIRED_SET = new Set(REQUIRED_HUMANOID_BONES);
+const SLOT_SPECS = [
+    { bone: "hips", aliasKey: "hips", side: null },
+    { bone: "spine", aliasKey: "spine", side: null },
+    { bone: "chest", aliasKey: "chest", side: null },
+    { bone: "upperChest", aliasKey: "upperChest", side: null },
+    { bone: "neck", aliasKey: "neck", side: null },
+    { bone: "head", aliasKey: "head", side: null },
+    { bone: "leftShoulder", aliasKey: "shoulder", side: "left" },
+    { bone: "leftUpperArm", aliasKey: "upperArm", side: "left" },
+    { bone: "leftLowerArm", aliasKey: "lowerArm", side: "left" },
+    { bone: "leftHand", aliasKey: "hand", side: "left" },
+    { bone: "rightShoulder", aliasKey: "shoulder", side: "right" },
+    { bone: "rightUpperArm", aliasKey: "upperArm", side: "right" },
+    { bone: "rightLowerArm", aliasKey: "lowerArm", side: "right" },
+    { bone: "rightHand", aliasKey: "hand", side: "right" },
+    { bone: "leftUpperLeg", aliasKey: "upperLeg", side: "left" },
+    { bone: "leftLowerLeg", aliasKey: "lowerLeg", side: "left" },
+    { bone: "leftFoot", aliasKey: "foot", side: "left" },
+    { bone: "leftToes", aliasKey: "toes", side: "left" },
+    { bone: "rightUpperLeg", aliasKey: "upperLeg", side: "right" },
+    { bone: "rightLowerLeg", aliasKey: "lowerLeg", side: "right" },
+    { bone: "rightFoot", aliasKey: "foot", side: "right" },
+    { bone: "rightToes", aliasKey: "toes", side: "right" }
+].map((spec) => ({ ...spec, required: REQUIRED_SET.has(spec.bone) }));
+const NAMESPACE_RE = /^(?:mixamorig\d*:|mixamorig\d*|bip\d*\s*|biped\s*|armature[|:_]?)/i;
+function stripNamespace(name) {
+    let out = name;
+    // Blender/glTF skinned hierarchies often prefix `Armature|` or `Armature/`.
+    out = out.replace(/^armature[|/]/i, "");
+    out = out.replace(NAMESPACE_RE, "");
+    return out;
+}
+/** Collapse to alphanumerics only, lowercased — `L_Arm_Upper.01` -> `larmupper01`. */
+function canonicalize(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function detectSide(raw) {
+    const lower = raw.toLowerCase();
+    // Explicit word boundaries first (left/right) — these are unambiguous.
+    if (/(^|[^a-z])left([^a-z]|$)|leftarm|leftleg|lefthand|leftfoot|leftshoulder|leftupleg/.test(lower))
+        return "left";
+    if (/(^|[^a-z])right([^a-z]|$)|rightarm|rightleg|righthand|rightfoot|rightshoulder|rightupleg/.test(lower))
+        return "right";
+    // Side prefixes: L_, R_, l., r.  and suffixes: _l, _r, .l, .r, _L, name ends in L/R
+    if (/(^|[^a-z])l[_.\- ]/.test(lower) || /[_.\- ]l($|[^a-z])/.test(lower))
+        return "left";
+    if (/(^|[^a-z])r[_.\- ]/.test(lower) || /[_.\- ]r($|[^a-z])/.test(lower))
+        return "right";
+    // Leading single side letter directly glued to a part: "LShoulder", "RArm", "L_Leg".
+    if (/^l(?=[a-z0-9])/.test(lower) && !/^le(?!ft)/.test(lower) && !/^lo/.test(lower) && !/^la(?!rm)/.test(lower)) {
+        // crude: only treat leading "l" as side when followed by a known limb-ish token.
+        if (/^l(shoulder|arm|upperarm|lowerarm|forearm|hand|wrist|leg|upperleg|lowerleg|thigh|calf|shin|foot|ankle|toe|clav|coll)/.test(lower)) {
+            return "left";
+        }
+    }
+    if (/^r(?=[a-z0-9])/.test(lower)) {
+        if (/^r(shoulder|arm|upperarm|lowerarm|forearm|hand|wrist|leg|upperleg|lowerleg|thigh|calf|shin|foot|ankle|toe|clav|coll)/.test(lower)) {
+            return "right";
+        }
+    }
+    return null;
+}
+function normalizeNode(raw) {
+    const stripped = stripNamespace(raw);
+    return {
+        raw,
+        canon: canonicalize(stripped),
+        side: detectSide(stripped) ?? detectSide(raw)
+    };
+}
+/**
+ * Score how well `node` fits `aliasKey`. Returns 0 for no match. Higher = better.
+ * The score rewards: exact-token equality, longer alias fragments (more specific), and earlier
+ * occurrence in the name. This lets `spine2`/`chest` win the chest slot over a generic `spine`.
+ */
+function scoreCandidate(node, aliasKey, aliases) {
+    let best = 0;
+    for (const alias of aliases) {
+        const a = canonicalize(alias);
+        if (a.length === 0)
+            continue;
+        const idx = node.canon.indexOf(a);
+        if (idx < 0)
+            continue;
+        // Base: specificity by alias length.
+        let score = 10 + a.length * 2;
+        // Exact match (whole canon equals alias) is the strongest signal.
+        if (node.canon === a)
+            score += 40;
+        // Side bones: a side-stripped exact-ish match where the remainder is only side tokens.
+        const remainder = node.canon.replace(a, "");
+        if (remainder.length <= 2)
+            score += 15;
+        // Prefer matches that appear toward the end (the "leaf" semantic token) for limb parts,
+        // but prefer earlier for spine/hips where the root token leads.
+        score += Math.max(0, 6 - idx);
+        if (score > best)
+            best = score;
+    }
+    // De-emphasize generic "spine" matching when the name clearly carries a chest/upperchest digit.
+    if (aliasKey === "spine" && /(spine[2-9]|spine0[2-9])/.test(node.canon)) {
+        best = Math.max(0, best - 12);
+    }
+    return best;
+}
+/**
+ * Infer a {@link HumanoidRigDefinition} from a flat list of skeleton node names.
+ *
+ * Strategy: each humanoid slot has a side-agnostic alias table plus an L/R/Left/Right side tag.
+ * For every slot we score all candidate nodes (filtered by detected side when the slot is sided),
+ * pick the highest-scoring one, and forbid reusing a node across slots. Conventions covered:
+ * Mixamo (`mixamorig:Hips`/`LeftArm`), Sketchfab/Blender (`Hip_00`, `Spine1..3`, `L_Shoulder`,
+ * `L_Arm_Upper_01`, `L_Leg_Upper_01`, `L_Hand`, `L_Foot`), and UE-ish (`pelvis`, `upperarm_l`,
+ * `thigh_r`, `calf_l`).
+ *
+ * Each produced {@link HumanoidBoneBinding} carries `name` (the resolved node) and `aliases`
+ * (the other plausible candidates for that slot), wiring the previously-unread `aliases` field.
+ */
+export function inferHumanoidRigDetailed(nodeNames, options = {}) {
+    const nodes = nodeNames.map(normalizeNode);
+    const used = new Set();
+    const bones = {};
+    const matches = [];
+    // Process required + more-specific slots first so generic "spine"/"leg" don't steal nodes that a
+    // more specific slot (chest/upperChest/lowerLeg) wants. We sort by a static priority.
+    const ordered = [...SLOT_SPECS].sort((a, b) => slotPriority(a.bone) - slotPriority(b.bone));
+    for (const spec of ordered) {
+        const aliasList = mergeAliases(spec, options.extraAliases);
+        const candidates = [];
+        for (const node of nodes) {
+            if (used.has(node.raw))
+                continue;
+            if (spec.side && node.side && node.side !== spec.side)
+                continue;
+            // For sided slots, skip nodes with no detectable side only if a sided alternative exists.
+            const score = scoreCandidate(node, spec.aliasKey, aliasList);
+            if (score <= 0)
+                continue;
+            // Penalize sided slot matching a side-less node (ambiguous).
+            const adjusted = spec.side && !node.side ? score - 8 : score;
+            if (adjusted <= 0)
+                continue;
+            candidates.push({ node, score: adjusted });
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        const winner = candidates[0];
+        const candidateNames = candidates.map((c) => c.node.raw);
+        if (winner) {
+            used.add(winner.node.raw);
+            bones[spec.bone] = {
+                name: winner.node.raw,
+                aliases: candidateNames.slice(1)
+            };
+            matches.push({ bone: spec.bone, node: winner.node.raw, score: winner.score, candidates: candidateNames });
+        }
+        else {
+            matches.push({ bone: spec.bone, score: 0, candidates: [] });
+        }
+    }
+    const missingRequired = REQUIRED_HUMANOID_BONES.filter((bone) => !bones[bone]);
+    const rig = {
+        id: options.id ?? "inferred-humanoid",
+        ...(options.name !== undefined ? { name: options.name } : {}),
+        bones,
+        ...(options.scale !== undefined ? { scale: options.scale } : {}),
+        ...(options.units !== undefined ? { units: options.units } : {}),
+        ...(options.facingAxis !== undefined ? { facingAxis: options.facingAxis } : {}),
+        metadata: { inferred: true, inferredFromNodeCount: nodeNames.length }
+    };
+    return { rig, matches, missingRequired };
+}
+/** Convenience wrapper returning just the rig definition. */
+export function inferHumanoidRig(nodeNames, options = {}) {
+    return inferHumanoidRigDetailed(nodeNames, options).rig;
+}
+function mergeAliases(spec, extra) {
+    const base = ALIAS_BY_KEY[spec.aliasKey] ?? [];
+    const extraForBone = extra?.[spec.bone] ?? [];
+    return extraForBone.length > 0 ? [...extraForBone, ...base] : base;
+}
+/**
+ * Lower number = resolved earlier. More-specific slots resolve first so they claim their nodes
+ * before generic siblings (e.g. `chest` before `spine`, `lowerLeg` before `upperLeg` before the
+ * generic `leg` token shared by both).
+ */
+function slotPriority(bone) {
+    const table = {
+        hips: 0,
+        head: 1,
+        upperChest: 2,
+        chest: 3,
+        neck: 4,
+        leftHand: 5,
+        rightHand: 5,
+        leftFoot: 6,
+        rightFoot: 6,
+        leftToes: 7,
+        rightToes: 7,
+        leftShoulder: 8,
+        rightShoulder: 8,
+        leftLowerArm: 9,
+        rightLowerArm: 9,
+        leftUpperArm: 10,
+        rightUpperArm: 10,
+        leftLowerLeg: 11,
+        rightLowerLeg: 11,
+        leftUpperLeg: 12,
+        rightUpperLeg: 12,
+        spine: 13
+    };
+    return table[bone] ?? 20;
+}
+/** Re-exported for callers wanting to enumerate which slots inference targets. */
+export const INFERABLE_HUMANOID_BONES = HUMANOID_BONES;
+//# sourceMappingURL=HumanoidBoneInference.js.map

package/dist/animation/HumanoidBoneInference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HumanoidBoneInference.js","sourceRoot":"","sources":["../../../../packages/animation/src/HumanoidBoneInference.ts"],"names":[],"mappings":"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"}

package/dist/animation/HumanoidRetargeting.d.ts

@@ -54,6 +54,14 @@ export interface HumanoidBoneRetargetBinding {
     readonly source: HumanoidBoneBinding;
     readonly target: HumanoidBoneBinding;
     readonly scale: number;
+    /**
+     * Source rig rest-pose local rotation for this bone (identity when unknown). Captured at
+     * map-build time from `source.restPose[bone].rotation` or the binding's own `rotation` so the
+     * pose retargeter can reconcile differing bind orientations without re-reading the rigs.
+     */
+    readonly sourceRest?: AnimationQuaternion;
+    /** Target rig rest-pose local rotation for this bone (identity when unknown). */
+    readonly targetRest?: AnimationQuaternion;
 }
 export interface HumanoidRetargetingMap {
     readonly sourceRigId: string;
@@ -63,14 +71,63 @@ export interface HumanoidRetargetingMap {
     readonly requiredCoverage: number;
     readonly bindings: Partial<Record<HumanoidBoneName, HumanoidBoneRetargetBinding>>;
     readonly diagnostics: readonly HumanoidRetargetingDiagnostic[];
+    /** Source rig facing axis (defaults to `"z"`) used for hip/root facing reconciliation. */
+    readonly sourceFacingAxis?: HumanoidAxis;
+    /** Target rig facing axis (defaults to `"z"`) used for hip/root facing reconciliation. */
+    readonly targetFacingAxis?: HumanoidAxis;
 }
 export interface RetargetHumanoidPoseOptions {
     readonly includeUnmappedSourceBones?: boolean;
     readonly includeSemanticBoneNames?: boolean;
     readonly scaleRootMotion?: boolean;
 }
+export interface AnimationHumanoidRetargetingOptions extends HumanoidRetargetingOptions {
+    readonly requiredClips?: readonly string[];
+    readonly availableClips?: readonly string[];
+    readonly mouthBlendshapeNames?: readonly string[];
+    readonly retargetMapProvided?: boolean;
+}
+export interface AnimationHumanoidRetargetingDiagnostics extends HumanoidRigDiagnostics {
+    readonly kind: "animation-humanoid-retargeting-diagnostics";
+    readonly mouthReady: boolean;
+    readonly clipReady: boolean;
+    readonly retargetMapProvided: boolean;
+}
 export declare function analyzeHumanoidRig(rig: HumanoidRigDefinition, options?: HumanoidRetargetingOptions): HumanoidRigDiagnostics;
 export declare function createHumanoidRetargetingMap(source: HumanoidRigDefinition, target: HumanoidRigDefinition, options?: HumanoidRetargetingOptions): HumanoidRetargetingMap;
+/**
+ * Retarget a source-rig {@link AnimationPose} onto the target rig described by `map`.
+ *
+ * This is NOT a 1:1 rotation copy. For each bone we reconcile differing rest/bind orientations and
+ * a differing facing axis, and scale translations by the per-bone length ratio:
+ *
+ *   1. Rest-pose reconciliation (per bone, local space). Let `Rs0` be the source rest local
+ *      rotation and `Rt0` the target rest local rotation (both from the rigs' `restPose`/binding
+ *      `rotation`, identity when unknown). An animation expresses a source local rotation `Ra`.
+ *      The motion *away from rest* in the source's local frame is the delta `D = Rs0⁻¹ · Ra`. We
+ *      re-anchor that delta onto the target rest: `Rt = Rt0 · D = Rt0 · Rs0⁻¹ · Ra`.
+ *      When both rests are identity (or equal) this collapses to a straight copy, and an identity
+ *      map (source rig === target rig) is therefore a no-op.
+ *
+ *   2. Facing-axis / coordinate-frame conversion. If the source faces a different cardinal axis
+ *      than the target, the hips (root) rotation is pre-multiplied by the frame-alignment rotation
+ *      `F` that carries the source facing axis onto the target facing axis: `Rt_hips = F · Rt_hips`.
+ *      This only touches the root so child bones inherit the reframe through the hierarchy.
+ *
+ *   3. Position / hip-height scaling (unchanged from before): translations are scaled by the
+ *      bone's length ratio (`binding.scale`), and optional root motion by the average bone scale.
+ *
+ * The signature and return type are unchanged.
+ *
+ * Honesty note: step 1 is the well-known "rest-delta" reconciliation. It is exact when the source
+ * and target rest orientations are the bones' true local bind rotations and the bones are mapped
+ * one-to-one (the common case for humanoid GLBs). It does NOT model differing bone *roll* beyond
+ * what the rest rotations capture, nor parent-chain reparametrization when intermediate bones
+ * (e.g. chest/upperChest) are present on one rig and absent on the other — those remain
+ * approximate. Step 2 corrects whole-body facing only via the root; per-limb axis remaps that
+ * aren't expressible as a single root rotation are not handled.
+ */
 export declare function retargetHumanoidPose(sourcePose: AnimationPose, map: HumanoidRetargetingMap, options?: RetargetHumanoidPoseOptions): AnimationPose;
 export declare function humanoidRetargetingDiagnostics(source: HumanoidRigDefinition, target: HumanoidRigDefinition, options?: HumanoidRetargetingOptions): readonly HumanoidRetargetingDiagnostic[];
+export declare function analyzeAnimationHumanoidRetargeting(rig: HumanoidRigDefinition, options?: AnimationHumanoidRetargetingOptions): AnimationHumanoidRetargetingDiagnostics;
 //# sourceMappingURL=HumanoidRetargeting.d.ts.map

package/dist/animation/HumanoidRetargeting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HumanoidRetargeting.d.ts","sourceRoot":"","sources":["../../../../packages/animation/src/HumanoidRetargeting.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HumanoidRetargeting.d.ts","sourceRoot":"","sources":["../../../../packages/animation/src/HumanoidRetargeting.ts"],"names":[],"mappings":"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"}

package/dist/animation/HumanoidRetargeting.js

@@ -200,7 +200,9 @@ export function createHumanoidRetargetingMap(source, target, options = {}) {
             bone,
             source: sourceBinding,
             target: targetBinding,
-            scale: estimateBoneScale(sourceBinding, targetBinding, source.scale, target.scale)
+            scale: estimateBoneScale(sourceBinding, targetBinding, source.scale, target.scale),
+            sourceRest: restRotationFor(source, bone, sourceBinding),
+            targetRest: restRotationFor(target, bone, targetBinding)
         };
     }
     const coverage = mappedBones / HUMANOID_BONES.length;
@@ -221,9 +223,43 @@ export function createHumanoidRetargetingMap(source, target, options = {}) {
         coverage,
         requiredCoverage,
         bindings,
-        diagnostics
+        diagnostics,
+        sourceFacingAxis: source.facingAxis ?? "z",
+        targetFacingAxis: target.facingAxis ?? "z"
     };
 }
+/**
+ * Retarget a source-rig {@link AnimationPose} onto the target rig described by `map`.
+ *
+ * This is NOT a 1:1 rotation copy. For each bone we reconcile differing rest/bind orientations and
+ * a differing facing axis, and scale translations by the per-bone length ratio:
+ *
+ *   1. Rest-pose reconciliation (per bone, local space). Let `Rs0` be the source rest local
+ *      rotation and `Rt0` the target rest local rotation (both from the rigs' `restPose`/binding
+ *      `rotation`, identity when unknown). An animation expresses a source local rotation `Ra`.
+ *      The motion *away from rest* in the source's local frame is the delta `D = Rs0⁻¹ · Ra`. We
+ *      re-anchor that delta onto the target rest: `Rt = Rt0 · D = Rt0 · Rs0⁻¹ · Ra`.
+ *      When both rests are identity (or equal) this collapses to a straight copy, and an identity
+ *      map (source rig === target rig) is therefore a no-op.
+ *
+ *   2. Facing-axis / coordinate-frame conversion. If the source faces a different cardinal axis
+ *      than the target, the hips (root) rotation is pre-multiplied by the frame-alignment rotation
+ *      `F` that carries the source facing axis onto the target facing axis: `Rt_hips = F · Rt_hips`.
+ *      This only touches the root so child bones inherit the reframe through the hierarchy.
+ *
+ *   3. Position / hip-height scaling (unchanged from before): translations are scaled by the
+ *      bone's length ratio (`binding.scale`), and optional root motion by the average bone scale.
+ *
+ * The signature and return type are unchanged.
+ *
+ * Honesty note: step 1 is the well-known "rest-delta" reconciliation. It is exact when the source
+ * and target rest orientations are the bones' true local bind rotations and the bones are mapped
+ * one-to-one (the common case for humanoid GLBs). It does NOT model differing bone *roll* beyond
+ * what the rest rotations capture, nor parent-chain reparametrization when intermediate bones
+ * (e.g. chest/upperChest) are present on one rig and absent on the other — those remain
+ * approximate. Step 2 corrects whole-body facing only via the root; per-limb axis remaps that
+ * aren't expressible as a single root rotation are not handled.
+ */
 export function retargetHumanoidPose(sourcePose, map, options = {}) {
     const bones = {};
     if (options.includeUnmappedSourceBones) {
@@ -231,6 +267,7 @@ export function retargetHumanoidPose(sourcePose, map, options = {}) {
             bones[boneName] = cloneTransform(transform);
         }
     }
+    const facing = facingAlignmentQuat(map.sourceFacingAxis ?? "z", map.targetFacingAxis ?? "z");
     for (const bone of HUMANOID_BONES) {
         const binding = map.bindings[bone];
         if (!binding)
@@ -238,7 +275,7 @@ export function retargetHumanoidPose(sourcePose, map, options = {}) {
         const sourceTransform = sourcePose.bones[binding.source.name] ?? sourcePose.bones[bone];
         if (!sourceTransform)
             continue;
-        const retargeted = scaleTransform(sourceTransform, binding.scale);
+        const retargeted = retargetBoneTransform(sourceTransform, binding, bone === "hips" ? facing : undefined);
         bones[binding.target.name] = retargeted;
         if (options.includeSemanticBoneNames) {
             bones[bone] = retargeted;
@@ -266,6 +303,49 @@ export function retargetHumanoidPose(sourcePose, map, options = {}) {
 export function humanoidRetargetingDiagnostics(source, target, options = {}) {
     return createHumanoidRetargetingMap(source, target, options).diagnostics;
 }
+export function analyzeAnimationHumanoidRetargeting(rig, options = {}) {
+    const base = analyzeHumanoidRig(rig, { minRequiredCoverage: 0.9, requireRestPose: true, ...options });
+    const diagnostics = [...base.diagnostics];
+    const requiredClips = options.requiredClips ?? ["Idle", "Talk", "Gesture", "Walk"];
+    const availableClips = new Set(options.availableClips ?? []);
+    const missingClips = requiredClips.filter((clip) => !availableClips.has(clip));
+    const mouthReady = (options.mouthBlendshapeNames?.length ?? 0) > 0
+        || Array.isArray(rig.metadata?.mouthBlendshapeNames) && rig.metadata.mouthBlendshapeNames.length > 0;
+    const retargetMapProvided = options.retargetMapProvided ?? Boolean(rig.metadata?.retargetMapProvided);
+    if (!mouthReady) {
+        diagnostics.push({
+            severity: "error",
+            code: "ANIMATION_MOUTH_METADATA_MISSING",
+            message: "Animation retargeting requires mouth blendshape or mouth-card metadata.",
+            rigId: rig.id
+        });
+    }
+    for (const clip of missingClips) {
+        diagnostics.push({
+            severity: "error",
+            code: "ANIMATION_REQUIRED_CLIP_MISSING",
+            message: `Animation retargeting requires clip "${clip}".`,
+            rigId: rig.id
+        });
+    }
+    if (!retargetMapProvided) {
+        diagnostics.push({
+            severity: "error",
+            code: "ANIMATION_RETARGET_MAP_MISSING",
+            message: "Animation retargeting requires external bone-map/retarget metadata.",
+            rigId: rig.id
+        });
+    }
+    return {
+        kind: "animation-humanoid-retargeting-diagnostics",
+        ...base,
+        ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+        diagnostics,
+        mouthReady,
+        clipReady: missingClips.length === 0,
+        retargetMapProvided
+    };
+}
 const HUMANOID_SIDE_PAIRS = [
     { left: "leftShoulder", right: "rightShoulder" },
     { left: "leftUpperArm", right: "rightUpperArm" },
@@ -304,13 +384,111 @@ function averageBindingScale(map) {
         return 1;
     return scales.reduce((sum, scale) => sum + scale, 0) / scales.length;
 }
-function scaleTransform(transform, scale) {
+const IDENTITY_QUAT = { x: 0, y: 0, z: 0, w: 1 };
+/**
+ * Extract the rest local rotation for a bone, preferring the rig's explicit `restPose` entry and
+ * falling back to the binding's own `rotation`. Returns identity when neither is present.
+ */
+function restRotationFor(rig, bone, binding) {
+    const fromRestPose = rig.restPose?.[bone]?.rotation;
+    if (fromRestPose)
+        return normalizeQuatObj(fromRestPose);
+    if (binding.rotation)
+        return normalizeQuatObj(binding.rotation);
+    return IDENTITY_QUAT;
+}
+/**
+ * Apply rest-pose reconciliation + (root-only) facing alignment + length scaling to one bone.
+ * See {@link retargetHumanoidPose} for the math derivation.
+ */
+function retargetBoneTransform(transform, binding, facing) {
+    const sourceRest = binding.sourceRest ?? IDENTITY_QUAT;
+    const targetRest = binding.targetRest ?? IDENTITY_QUAT;
+    let rotation = transform.rotation;
+    if (rotation) {
+        // Rt = Rt0 · Rs0⁻¹ · Ra
+        const delta = multiplyQuat(invertQuat(sourceRest), normalizeQuatObj(rotation));
+        rotation = multiplyQuat(targetRest, delta);
+        if (facing) {
+            // Whole-body facing correction, applied on the root before its local rotation.
+            rotation = multiplyQuat(facing, rotation);
+        }
+        rotation = normalizeQuatObj(rotation);
+    }
+    else if (facing) {
+        // No animated rotation but a facing delta still needs to reframe the root.
+        rotation = normalizeQuatObj(multiplyQuat(facing, targetRest));
+    }
     return {
-        position: transform.position ? scaleVector(transform.position, scale) : undefined,
-        rotation: transform.rotation,
+        position: transform.position ? scaleVector(transform.position, binding.scale) : undefined,
+        rotation,
         scale: transform.scale
     };
 }
+/**
+ * Rotation that carries `from` cardinal axis onto `to` cardinal axis (shortest arc). Used to
+ * reconcile rigs that face different world axes (e.g. +Z forward vs -Z forward, or +X vs +Z).
+ */
+function facingAlignmentQuat(from, to) {
+    if (from === to)
+        return undefined;
+    const a = axisVector(from);
+    const b = axisVector(to);
+    return shortestArcQuat(a, b);
+}
+function axisVector(axis) {
+    switch (axis) {
+        case "x": return { x: 1, y: 0, z: 0 };
+        case "-x": return { x: -1, y: 0, z: 0 };
+        case "y": return { x: 0, y: 1, z: 0 };
+        case "-y": return { x: 0, y: -1, z: 0 };
+        case "z": return { x: 0, y: 0, z: 1 };
+        case "-z": return { x: 0, y: 0, z: -1 };
+        default: return { x: 0, y: 0, z: 1 };
+    }
+}
+/** Quaternion of the shortest rotation from unit vector `a` to unit vector `b`. */
+function shortestArcQuat(a, b) {
+    const dot = a.x * b.x + a.y * b.y + a.z * b.z;
+    if (dot >= 1 - 1e-8)
+        return IDENTITY_QUAT;
+    if (dot <= -1 + 1e-8) {
+        // Opposite vectors: rotate 180° about any axis orthogonal to a.
+        let ortho = Math.abs(a.x) < 0.9 ? { x: 1, y: 0, z: 0 } : { x: 0, y: 1, z: 0 };
+        ortho = crossVec(a, ortho);
+        const len = Math.hypot(ortho.x, ortho.y, ortho.z) || 1;
+        return normalizeQuatObj({ x: ortho.x / len, y: ortho.y / len, z: ortho.z / len, w: 0 });
+    }
+    const c = crossVec(a, b);
+    const w = 1 + dot;
+    return normalizeQuatObj({ x: c.x, y: c.y, z: c.z, w });
+}
+function crossVec(a, b) {
+    return {
+        x: a.y * b.z - a.z * b.y,
+        y: a.z * b.x - a.x * b.z,
+        z: a.x * b.y - a.y * b.x
+    };
+}
+function multiplyQuat(a, b) {
+    return {
+        x: a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
+        y: a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
+        z: a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
+        w: a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z
+    };
+}
+function invertQuat(q) {
+    // Unit quaternion inverse is its conjugate; normalize defensively first.
+    const n = normalizeQuatObj(q);
+    return { x: -n.x, y: -n.y, z: -n.z, w: n.w };
+}
+function normalizeQuatObj(q) {
+    const len = Math.hypot(q.x, q.y, q.z, q.w);
+    if (len <= 1e-9)
+        return IDENTITY_QUAT;
+    return { x: q.x / len, y: q.y / len, z: q.z / len, w: q.w / len };
+}
 function cloneTransform(transform) {
     return {
         position: transform.position ? { ...transform.position } : undefined,