@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/stages/conform.js

@@ -1,7 +1,6 @@
 "use strict";
-// PORTED from helix-web-engine-new/tools/character-pipeline — the source of truth for the character
-// pipeline. SYNC OBLIGATION: fix bugs there first, then mirror the change here; do not diverge.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.skinBindTransform = skinBindTransform;
 exports.extractCanonicalSkeleton = extractCanonicalSkeleton;
 exports.conformToHelixRest = conformToHelixRest;
 const core_1 = require("@gltf-transform/core");
@@ -11,6 +10,125 @@ const posOf = (m) => [m[12], m[13], m[14]];
 const vlen = (v) => Math.hypot(v[0], v[1], v[2]);
 /** Apply the transpose (=inverse, for a rotation) of a column-major matrix's upper 3x3 to a vector. */
 const applyRotT = (m, v) => [m[0] * v[0] + m[1] * v[1] + m[2] * v[2], m[4] * v[0] + m[5] * v[1] + m[6] * v[2], m[8] * v[0] + m[9] * v[1] + m[10] * v[2]];
+function matrixIsIdentity(matrix) {
+    return matrix.every((value, index) => Math.abs(value - IDENTITY[index]) <= 1e-9);
+}
+/** Two affine matrices describe the same transform, to a tolerance relative to their magnitude. */
+function matricesAgree(a, b) {
+    const scale = Math.max(1, ...a.map(Math.abs), ...b.map(Math.abs));
+    return a.every((value, index) => Math.abs(value - b[index]) <= 1e-3 * scale);
+}
+/**
+ * The transform glTF skinning actually applies to a skin's vertices at rest: `jointWorld · IBM`.
+ * In a rig exported at its bind pose every joint yields the same matrix, and that matrix — not the
+ * skinned mesh node's own transform, which the glTF spec says is ignored — places the vertices in the
+ * joints' world. Returns null when the joints disagree (a posed or inconsistent bind), where there is
+ * no single answer to read.
+ */
+function skinBindTransform(skin) {
+    const joints = skin.listJoints();
+    if (joints.length === 0)
+        return null;
+    const inverseBinds = skin.getInverseBindMatrices();
+    const element = new Array(16).fill(0);
+    let consensus = null;
+    for (const [index, joint] of joints.entries()) {
+        const ibm = inverseBinds === null ? IDENTITY : inverseBinds.getElement(index, element);
+        const bind = (0, mat4_1.mul4)(joint.getWorldMatrix(), ibm);
+        if (consensus === null)
+            consensus = bind;
+        else if (!matricesAgree(consensus, bind))
+            return null;
+    }
+    return consensus;
+}
+/**
+ * Character stages operate in one canonical world space. glTF/FBX inputs may
+ * carry their axis and unit conversion on ancestors of the skinned mesh;
+ * conform later replaces those ancestors, so bake the world transform into
+ * geometry first. Morph POSITION values are deltas and omit translation.
+ *
+ * Baked only when the skin agrees that the node's world transform IS the space its vertices live in
+ * (`jointWorld · IBM` equals it, as three's FBX export writes it). When the skin's bind says otherwise,
+ * the node transform is one glTF skinning never applies, and baking it scales the character a second
+ * time. That is the Meshy/Blender export: a 0.01 `Armature` over centimetre bones is the parent of both
+ * the joints and the mesh node, the IBMs already absorb it (`jointWorld · IBM = I`), and the vertices
+ * are metres. Baking the 0.01 shrank every Meshy-rigged Dreamer avatar to 1.8 cm, after which unit
+ * normalization scaled the metre joints down to match (helix-cli 0.1.15 through 0.1.17).
+ */
+function bakeSkinnedMeshWorldTransforms(document) {
+    const root = document.getRoot();
+    const scene = root.listScenes()[0];
+    if (scene === undefined)
+        return;
+    const transformed = new Map();
+    const apply = (accessor, matrix, kind) => {
+        if (accessor === null)
+            return;
+        const key = `${kind}:${matrix.map((value) => value.toPrecision(12)).join(',')}`;
+        const previous = transformed.get(accessor);
+        if (previous !== undefined) {
+            if (previous !== key) {
+                throw new Error('conformToHelixRest: one geometry accessor is instanced under different world transforms');
+            }
+            return;
+        }
+        transformed.set(accessor, key);
+        const element = new Array(accessor.getElementSize()).fill(0);
+        const inverse = kind === 'normal' ? (0, mat4_1.invert4)(matrix) : null;
+        const rotate = (source) => {
+            const sx = Math.hypot(matrix[0], matrix[1], matrix[2]) || 1;
+            const sy = Math.hypot(matrix[4], matrix[5], matrix[6]) || 1;
+            const sz = Math.hypot(matrix[8], matrix[9], matrix[10]) || 1;
+            return [
+                matrix[0] / sx * source[0] + matrix[4] / sy * source[1] + matrix[8] / sz * source[2],
+                matrix[1] / sx * source[0] + matrix[5] / sy * source[1] + matrix[9] / sz * source[2],
+                matrix[2] / sx * source[0] + matrix[6] / sy * source[1] + matrix[10] / sz * source[2],
+            ];
+        };
+        for (let index = 0; index < accessor.getCount(); index++) {
+            accessor.getElement(index, element);
+            const source = [element[0], element[1], element[2]];
+            let value;
+            if (kind === 'point')
+                value = (0, mat4_1.transformPoint)(matrix, source);
+            else if (kind === 'normal')
+                value = applyRotT(inverse, source);
+            else if (kind === 'normalDelta' || kind === 'tangentDelta')
+                value = rotate(source);
+            else
+                value = (0, mat4_1.transformDir)(matrix, source);
+            if (kind === 'normal' || kind === 'tangent')
+                value = (0, mat4_1.normalize3)(value);
+            element[0] = value[0];
+            element[1] = value[1];
+            element[2] = value[2];
+            accessor.setElement(index, element);
+        }
+    };
+    for (const node of [...root.listNodes()]) {
+        const mesh = node.getMesh();
+        if (mesh === null || node.getSkin() === null)
+            continue;
+        const world = node.getWorldMatrix();
+        const bind = skinBindTransform(node.getSkin());
+        const ignoredBySkinning = bind !== null && !matricesAgree(bind, world);
+        if (!matrixIsIdentity(world) && !ignoredBySkinning) {
+            for (const primitive of mesh.listPrimitives()) {
+                apply(primitive.getAttribute('POSITION'), world, 'point');
+                apply(primitive.getAttribute('NORMAL'), world, 'normal');
+                apply(primitive.getAttribute('TANGENT'), world, 'tangent');
+                for (const target of primitive.listTargets()) {
+                    apply(target.getAttribute('POSITION'), world, 'direction');
+                    apply(target.getAttribute('NORMAL'), world, 'normalDelta');
+                    apply(target.getAttribute('TANGENT'), world, 'tangentDelta');
+                }
+            }
+        }
+        node.setMatrix(IDENTITY);
+        scene.addChild(node);
+    }
+}
 function parentNode(node) {
     for (const p of node.listParents())
         if (p.propertyType === core_1.PropertyType.NODE)
@@ -21,9 +139,10 @@ function parentNode(node) {
  * Reads the canonical helix-humanoid@1 rest skeleton out of a shipped body GLB (body-m-default): the
  * full bone subtree (local rest transforms + hierarchy) and the skin's joint order. World transforms
  * are recomputed from the skeleton root down (independent of the source file's mesh-node ancestor),
- * so a rebuilt copy with the root at scene identity reproduces them exactly.
+ * so a rebuilt copy with the root at scene identity reproduces them exactly. A host-aligned add-on
+ * can opt into the root's world transform to retain a base avatar's hoisted root_offset wrapper.
  */
-function extractCanonicalSkeleton(document) {
+function extractCanonicalSkeleton(document, options = {}) {
     const skin = document.getRoot().listSkins()[0];
     if (skin === undefined)
         throw new Error('extractCanonicalSkeleton: no skin in the canonical body GLB');
@@ -32,7 +151,12 @@ function extractCanonicalSkeleton(document) {
     const nodes = [];
     const worldByName = new Map();
     const visit = (node, parent, parentWorld) => {
-        const local = node.getMatrix();
+        // Base avatars may hoist hip height into a wrapper above the animated root.
+        // A host-aligned add-on must retain that offset; otherwise a garment already
+        // sitting on the host is rebound to a rig translated below it.
+        const local = (parent === null && options.includeRootWorld
+            ? node.getWorldMatrix()
+            : node.getMatrix());
         const world = (0, mat4_1.mul4)(parentWorld, local);
         const name = node.getName();
         nodes.push({ name, local, parent });
@@ -41,24 +165,105 @@ function extractCanonicalSkeleton(document) {
             visit(child, name, world);
     };
     visit(rootNode, null, IDENTITY);
-    return { nodes, jointNames, worldByName, skeletonRootName: rootNode.getName() };
+    const skeleton = { nodes, jointNames, worldByName, skeletonRootName: rootNode.getName() };
+    if (options.hoistRootOffset === true && options.includeRootWorld !== true) {
+        // The wrapper's world is the root's world divided by its own local: parent chain above the root.
+        const rootWorld = rootNode.getWorldMatrix();
+        const offset = (0, mat4_1.mul4)(rootWorld, (0, mat4_1.invert4)(rootNode.getMatrix()));
+        if (!matrixIsIdentity(offset))
+            skeleton.rootOffset = offset;
+    }
+    return skeleton;
 }
 /**
- * Fits the canonical skeleton onto a source character's proportions: KEEPS every canonical bone's local
- * REST ROTATION (so target clips apply natively) but sets each bone's WORLD POSITION to the source's
- * corresponding joint — directly for mapped bones, and for unmapped in-betweens (spine_02/04, neck_02,
- * twists, fingers) by scaling their canonical offset-from-parent by the enclosing mapped segment's
- * scale. The result is a rig with canonical orientations at the source's own joint positions, so the
- * source mesh binds to it UNCHANGED (no shape distortion — the whole point vs. re-posing the mesh).
+ * Fits the canonical skeleton onto a source character's proportions. Positions: mapped bones sit at the
+ * source's joint worlds — EXCEPT interior spine joints, which are position-skipped (see POSITION_SKIP)
+ * and, like unmapped in-betweens (spine_02/04, neck_02, twists), interpolate along their enclosing
+ * mapped span at their canonical fraction (extrapolating by parent-segment scale overshoots — a 3×
+ * lower spine threw spine_02 past spine_03, a zigzag lever every clip then rotates); bones with no
+ * mapped span (fingers) scale their canonical offset by the parent segment. Orientations: canonical
+ * local rest rotations, EXCEPT mapped bones with a mapped continuation, whose rest is re-aimed by the
+ * shortest arc from the canonical segment direction onto the source's. The IBM (inverse of rest) then
+ * subtracts the source-bind-vs-canonical direction delta ONCE — a shared canonical clip lands every
+ * segment in the same world direction as the stock body instead of carrying the bind delta into every
+ * pose (Meshy binding arms ~19° flatter than MetaHuman read as hands-behind-the-back in every clip).
+ * Shortest-arc adds no roll: the twist DOF a segment direction can't express stays canonical. The
+ * source mesh still binds UNCHANGED — rest render is pristine (M·IBM = I) whatever rest we choose.
  */
 function fitSkeletonToWarrior(canon, directPos) {
     const canonPos = (n) => posOf(canon.worldByName.get(n));
+    // Interior spine joints keep their WEIGHT mapping but are never position anchors: sources place them
+    // by rig convention, not anatomy (Meshy trisects a straight hips->neck line — its bottom joint lands
+    // at NAVEL height, a 4× pelvis->spine_01 lever that swings the whole waist with every clip's hip
+    // sway). Dropped here, they interpolate on the pelvis->neck span at canonical fractions like any
+    // unmapped in-between; pelvis/neck/head/limbs stay the proportion anchors.
+    const POSITION_SKIP = new Set(['spine_01', 'spine_02', 'spine_03', 'spine_04', 'spine_05']);
+    for (const n of POSITION_SKIP)
+        directPos.delete(n);
+    // Canonical topology lookups.
+    const parentOf = new Map();
+    const childrenOf = new Map();
+    for (const def of canon.nodes) {
+        parentOf.set(def.name, def.parent);
+        if (def.parent !== null) {
+            const arr = childrenOf.get(def.parent);
+            if (arr === undefined)
+                childrenOf.set(def.parent, [def.name]);
+            else
+                arr.push(def.name);
+        }
+    }
+    const mappedBelow = (name) => {
+        const out = [];
+        for (const c of childrenOf.get(name) ?? []) {
+            if (directPos.has(c))
+                out.push(c);
+            else
+                out.push(...mappedBelow(c));
+        }
+        return out;
+    };
+    const nearestMappedAncestor = (name) => {
+        for (let p = parentOf.get(name) ?? null; p !== null; p = parentOf.get(p) ?? null)
+            if (directPos.has(p))
+                return p;
+        return null;
+    };
+    // Aim anchor per mapped bone: the nearest mapped descendant that best CONTINUES the chain (max
+    // alignment with the bone's canonical incoming direction — picks spine_01 over the thighs for pelvis).
+    const aimAnchor = new Map();
+    for (const def of canon.nodes) {
+        if (!directPos.has(def.name))
+            continue;
+        const cands = mappedBelow(def.name);
+        if (cands.length === 0)
+            continue;
+        const parent = def.parent;
+        const inDir = parent !== null ? (0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(def.name), canonPos(parent))) : [0, 1, 0];
+        let best = cands[0], bestDot = -Infinity;
+        for (const c of cands) {
+            const d = (0, mat4_1.dot3)((0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(c), canonPos(def.name))), inDir);
+            if (d > bestDot) {
+                bestDot = d;
+                best = c;
+            }
+        }
+        aimAnchor.set(def.name, best);
+    }
     // Pass 1 — desired world position per bone (canon.nodes is DFS, parent before child).
+    // HIP-HEIGHT RE-REFERENCE: clips drive the pelvis's LOCAL translation with values authored for the
+    // canonical hip height, so a source whose pelvis rests higher/lower loses that delta under every clip
+    // and its feet sink into / float off the ground by exactly it. Shift the delta into the ROOT's rest
+    // translation (no clip writes root — the pipeline strips non-pelvis position tracks): the pelvis rest
+    // local becomes canonical by construction, worlds are unchanged (rest render pristine), and under
+    // clips the pelvis rides at root Δ + clip value — the source's own height, feet planted like stock.
+    const rootDelta = directPos.has('pelvis') ? (0, mat4_1.sub3)(directPos.get('pelvis'), canonPos('pelvis')) : [0, 0, 0];
     const desired = new Map();
     const scaleBy = new Map();
     for (const def of canon.nodes) {
         if (def.parent === null) {
-            desired.set(def.name, canonPos(def.name));
+            const c = canonPos(def.name);
+            desired.set(def.name, [c[0] + rootDelta[0], c[1] + rootDelta[1], c[2] + rootDelta[2]]);
             scaleBy.set(def.name, 1);
             continue;
         }
@@ -69,53 +274,98 @@ function fitSkeletonToWarrior(canon, directPos) {
             desired.set(def.name, dp);
             const cl = vlen(canonOff);
             scaleBy.set(def.name, cl > 1e-6 ? vlen((0, mat4_1.sub3)(dp, pPos)) / cl : (scaleBy.get(def.parent) ?? 1));
+            continue;
         }
-        else {
-            const s = scaleBy.get(def.parent) ?? 1;
-            desired.set(def.name, [pPos[0] + canonOff[0] * s, pPos[1] + canonOff[1] * s, pPos[2] + canonOff[2] * s]);
-            scaleBy.set(def.name, s);
+        // Unmapped: interpolate on the mapped span around it (ancestor A -> nearest mapped descendant, or
+        // A's own continuation anchor for off-chain bones like twists), at the canonical fraction with the
+        // canonical perpendicular offset rotated/scaled into the source segment.
+        const A = nearestMappedAncestor(def.name);
+        const B = A !== null ? (mappedBelow(def.name)
+            .reduce((acc, c) => {
+            if (acc === null)
+                return c;
+            const ref = (0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(def.name), canonPos(A)));
+            return (0, mat4_1.dot3)((0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(c), canonPos(A))), ref) > (0, mat4_1.dot3)((0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(acc), canonPos(A))), ref) ? c : acc;
+        }, null) ?? aimAnchor.get(A) ?? null) : null;
+        if (A !== null && B !== null) {
+            const segC = (0, mat4_1.sub3)(canonPos(B), canonPos(A));
+            const segS = (0, mat4_1.sub3)(directPos.get(B), directPos.get(A));
+            const lC = vlen(segC), lS = vlen(segS);
+            if (lC > 1e-6 && lS > 1e-6) {
+                const u = (0, mat4_1.sub3)(canonPos(def.name), canonPos(A));
+                const t = (0, mat4_1.dot3)(u, segC) / (lC * lC);
+                const perp = [u[0] - segC[0] * t, u[1] - segC[1] * t, u[2] - segC[2] * t];
+                const s = lS / lC;
+                const [px, py, pz] = (0, mat4_1.transformDir)((0, mat4_1.shortestArc4)(segC, segS), perp);
+                const a = directPos.get(A);
+                desired.set(def.name, [a[0] + segS[0] * t + px * s, a[1] + segS[1] * t + py * s, a[2] + segS[2] * t + pz * s]);
+                scaleBy.set(def.name, s);
+                continue;
+            }
         }
+        const s = scaleBy.get(def.parent) ?? 1;
+        desired.set(def.name, [pPos[0] + canonOff[0] * s, pPos[1] + canonOff[1] * s, pPos[2] + canonOff[2] * s]);
+        scaleBy.set(def.name, s);
     }
-    // Pass 2 — rebuild local matrices = canonical local ROTATION + fitted local TRANSLATION; recompute world.
-    // Exception — CLAVICLE rest-correction: the source's shoulder mesh is authored for its own clavicle
-    // direction (Meshy is ~horizontal; MetaHuman droops ~9°). Keeping the canonical clavicle rest binds the
-    // shoulder to the wrong reference, so a SHARED canonical clip drives the animated shoulder ~9° too
-    // horizontal (a shrug). Fix: rebase ONLY the two clavicle bones' rest ORIENTATION to point along the
-    // SOURCE clavicle direction. The IBM (inverse of this rest) then re-references the clip — the ~9° gap
-    // between the clip's canonical clavicle pose and this source-aligned rest becomes the corrective pull,
-    // so the animated shoulder matches the stock body. Children keep canonical local rotation and ride the
-    // correction. Positions/proportions untouched (lt kept); rest render stays pristine (M·IBM = I).
-    const ORIGIN = [0, 0, 0];
-    const CLAVICLE_CHILD = { clavicle_l: 'upperarm_l', clavicle_r: 'upperarm_r' };
+    // Pass 2 — rebuild local matrices = local ROTATION + fitted local TRANSLATION; recompute world.
+    // Mapped bones with an anchor: segment-aimed from the CANONICAL rest world, so corrections stay
+    // absolute and never compound down the chain (net effect on the anchor child's local translation:
+    // lt = s · lt_canonical — identical clip rotations reproduce the stock body's segment directions at
+    // the source's lengths). Mapped bones WITHOUT an anchor: their segment tells us nothing, so keep the
+    // ABSOLUTE canonical rest world rotation — heads are authored level and toes ground-flat no matter how
+    // the source's neck/foot segments tilt; riding the parent's aim would counter-tilt them under clips.
+    // Exception HANDS: a bound hand continues its forearm, so they DO ride the forearm's aim. Unmapped
+    // bones (twists, fingers — unweighted helpers) ride their parent via canonical locals.
+    const RIDE_PARENT_AIM = new Set(['hand_l', 'hand_r']);
+    // FEET and CLAVICLES are never aimed despite having anchors — both are PROPORTIONS bones whose
+    // authored direction must survive clips. Feet: soles are authored ground-flat however steeply the
+    // source ankle->toe bone runs; aiming pitches the sole by the bone-vs-canonical delta (toes lift).
+    // Clavicles: Meshy binds the shoulder shelf ~horizontal while the canonical clavicle droops ~9° —
+    // aiming pulled the girdle down to canonical in every clip (collapsed silhouette). Neck: Meshy binds
+    // it near-vertical while the canonical neck rest pitches ~8-12° forward — aiming folded that delta
+    // into the bind, so every clip rotated the neck FLESH ~12° forward of the default body (forward-jut
+    // head under run). Absolute canonical rest keeps the authored direction for these; the aimed chain
+    // beyond them still lands canonical, riding at the source's joint (~2 cm offsets, not misdirection).
+    const AIM_SKIP = new Set(['foot_l', 'foot_r', 'clavicle_l', 'clavicle_r', 'neck_01']);
+    let restAimed = 0;
     const world = new Map();
     const nodes = [];
     for (const def of canon.nodes) {
         const parentWorld = def.parent !== null ? world.get(def.parent) : IDENTITY;
         const worldOff = def.parent !== null ? (0, mat4_1.sub3)(desired.get(def.name), desired.get(def.parent)) : desired.get(def.name);
-        const lt = def.parent !== null ? applyRotT(parentWorld, worldOff) : worldOff; // into parent's (canonical) frame
+        const lt = def.parent !== null ? applyRotT(parentWorld, worldOff) : worldOff; // into parent's fitted frame
         let rot = (0, mat4_1.rigidize)(def.local); // default: canonical local orientation
-        const clavChild = CLAVICLE_CHILD[def.name];
-        if (clavChild !== undefined && directPos.has(def.name) && directPos.has(clavChild)) {
-            const srcDir = (0, mat4_1.normalize3)((0, mat4_1.sub3)(directPos.get(clavChild), directPos.get(def.name))); // warrior clavicle dir
-            const canonDir = (0, mat4_1.normalize3)((0, mat4_1.sub3)(canonPos(clavChild), canonPos(def.name))); // canonical clavicle dir
-            const O = (0, mat4_1.mul4)((0, mat4_1.frameFromAxis)(canonDir, ORIGIN), (0, mat4_1.invert4)((0, mat4_1.frameFromAxis)(srcDir, ORIGIN))); // world src->canon
-            const worldRotDes = (0, mat4_1.mul4)((0, mat4_1.invert4)(O), (0, mat4_1.rigidize)(canon.worldByName.get(def.name))); // canon->src rest world
-            rot = (0, mat4_1.mul4)((0, mat4_1.invert4)((0, mat4_1.rigidize)(parentWorld)), worldRotDes); // back to local
+        if (directPos.has(def.name)) {
+            const anchor = AIM_SKIP.has(def.name) ? undefined : aimAnchor.get(def.name);
+            let arc = null;
+            if (anchor !== undefined) {
+                const srcDir = (0, mat4_1.sub3)(directPos.get(anchor), directPos.get(def.name));
+                const canonDir = (0, mat4_1.sub3)(canonPos(anchor), canonPos(def.name));
+                if (vlen(srcDir) > 1e-6 && vlen(canonDir) > 1e-6) {
+                    arc = (0, mat4_1.shortestArc4)(canonDir, srcDir);
+                    restAimed++;
+                }
+            }
+            if (arc !== null || !RIDE_PARENT_AIM.has(def.name)) {
+                const canonWorldRot = (0, mat4_1.rigidize)(canon.worldByName.get(def.name));
+                const worldRotDes = arc !== null ? (0, mat4_1.mul4)(arc, canonWorldRot) : canonWorldRot;
+                rot = (0, mat4_1.mul4)((0, mat4_1.invert4)((0, mat4_1.rigidize)(parentWorld)), worldRotDes);
+            }
         }
         const local = [rot[0], rot[1], rot[2], 0, rot[4], rot[5], rot[6], 0, rot[8], rot[9], rot[10], 0, lt[0], lt[1], lt[2], 1];
         nodes.push({ name: def.name, local, parent: def.parent });
         world.set(def.name, (0, mat4_1.mul4)(parentWorld, local));
     }
-    return { nodes, jointNames: canon.jointNames, worldByName: world, skeletonRootName: canon.skeletonRootName };
+    return { skeleton: { nodes, jointNames: canon.jointNames, worldByName: world, skeletonRootName: canon.skeletonRootName }, restAimed };
 }
 /**
  * Retargets a source character onto `helix-humanoid@1` so the PLATFORM's shared clips drive it.
  *
  * 'embed' (default, the better retarget): the source mesh is left byte-for-byte unchanged and the
- * canonical 68-bone skeleton is fitted INTO it (canonical bone orientations at the source's joint
- * positions, §fitSkeletonToWarrior). Clips — authored as local rotations relative to the canonical rest
- * — produce the correct WORLD-space motion regardless of the source's bone-axis convention, because the
- * mesh rides the bones in world space (we never route the mesh through mismatched local frames). Output
+ * canonical 68-bone skeleton is fitted INTO it (segment-aimed canonical orientations at the source's
+ * joint positions, §fitSkeletonToWarrior). Clips — authored as local rotations relative to the canonical
+ * rest — produce the correct WORLD-space motion regardless of the source's bone-axis convention or bind
+ * pose, because the aimed rests subtract the source-bind-vs-canonical direction delta at the IBM. Output
  * IBMs = inverse(fitted world), so LBS at rest reproduces the pristine source bind pose.
  *
  * 'repose' re-poses the mesh onto the canonical rest via frame-based rest-pose correction (kept for
@@ -126,20 +376,19 @@ function fitSkeletonToWarrior(canon, directPos) {
 function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
     const mode = opts.mode ?? 'embed';
     const root = warrior.getRoot();
+    bakeSkinnedMeshWorldTransforms(warrior);
     const wskin = root.listSkins()[0];
     if (wskin === undefined)
         throw new Error('conformToHelixRest: warrior GLB has no skin');
     const wjoints = wskin.listJoints();
     // Resolve each warrior joint to a helix joint (map, else nearest mapped ancestor).
-    const jointByNode = new Map(wjoints.map((j) => [j, true]));
     const helixFor = (joint) => {
         let cur = joint;
         while (cur !== null) {
             const mapped = boneMap.map[cur.getName()];
             if (mapped !== undefined)
                 return mapped;
-            const p = parentNode(cur);
-            cur = p !== null && jointByNode.has(p) ? p : null;
+            cur = parentNode(cur);
         }
         throw new Error(`conformToHelixRest: warrior joint '${joint.getName()}' has no mapped ancestor`);
     };
@@ -148,28 +397,189 @@ function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
     wjoints.forEach((j, i) => (weightTargets[j.getName()] = helixByWarriorIdx[i]));
     // Warrior joint hierarchy + world rest positions.
     const idxByNode = new Map(wjoints.map((j, i) => [j, i]));
-    const parentIdx = wjoints.map((j) => { const p = parentNode(j); return p !== null && idxByNode.has(p) ? idxByNode.get(p) : -1; });
+    const idxByName = new Map(wjoints.map((j, i) => [j.getName(), i]));
+    const parentIdx = wjoints.map((joint, jointIndex) => {
+        let parent = parentNode(joint);
+        while (parent !== null) {
+            const direct = idxByNode.get(parent);
+            const mappedName = boneMap.map[parent.getName()] ?? parent.getName();
+            const byName = idxByName.get(mappedName);
+            const candidate = direct ?? byName;
+            // THREE's FBX -> glTF fallback can emit an unlisted duplicate node for
+            // each bone between a skin joint and its actual parent. Duplicate self
+            // names are wrappers, not a parent edge; keep walking past them.
+            if (candidate !== undefined && candidate !== jointIndex)
+                return candidate;
+            parent = parentNode(parent);
+        }
+        return -1;
+    });
     const childIdxs = wjoints.map(() => []);
     parentIdx.forEach((p, i) => { if (p >= 0)
         childIdxs[p].push(i); });
-    const Tsrc = wjoints.map((j) => posOf(j.getWorldMatrix()));
+    // UNIT NORMALIZATION. Meshy rig exports have shipped in two conventions: cm bones under an Armature
+    // scaled 0.01 (joint worlds land in meters), and — later exports — cm bones at scene scale 1 (joint
+    // worlds ARE cm). glTF ignores a skinned mesh node's own transform, so the VERTEX data defines the
+    // model's true unit space; a rig fitted at cm positions still binds pristinely (bone·IBM = I at rest,
+    // any uniform scale cancels) and passes every static check, then explodes the instant meter-space
+    // platform clips drive it. Snap the joint worlds to the vertex data's decade before fitting.
+    const rawTsrc = wjoints.map((j) => posOf(j.getWorldMatrix()));
+    const maxWeightByJoint = new Float32Array(wjoints.length);
+    let meshMinY = Infinity, meshMaxY = -Infinity;
+    for (const node of root.listNodes()) {
+        if (node.getSkin() !== wskin || node.getMesh() === null)
+            continue;
+        for (const prim of node.getMesh().listPrimitives()) {
+            const pos = prim.getAttribute('POSITION');
+            if (pos === null)
+                continue;
+            const mn = [], mx = [];
+            pos.getMin(mn);
+            pos.getMax(mx);
+            meshMinY = Math.min(meshMinY, mn[1]);
+            meshMaxY = Math.max(meshMaxY, mx[1]);
+            const setCount = prim.listSemantics().filter((semantic) => semantic.startsWith('JOINTS_')).length;
+            for (let set = 0; set < setCount; set++) {
+                const joints = prim.getAttribute(`JOINTS_${set}`)?.getArray();
+                const weights = prim.getAttribute(`WEIGHTS_${set}`)?.getArray();
+                if (joints === null || joints === undefined || weights === null || weights === undefined)
+                    continue;
+                for (let component = 0; component < joints.length; component++) {
+                    const jointIndex = joints[component];
+                    maxWeightByJoint[jointIndex] = Math.max(maxWeightByJoint[jointIndex], weights[component]);
+                }
+            }
+        }
+    }
+    // Tiny cleanup influences are common on rigid accessories and may reach a distant root/head joint.
+    // They are real deformation weights, but they do not describe the anatomy represented by the mesh.
+    // Including a 1% outlier can expand a necklace's inferred joint span by a full decade and make an
+    // already-metre rig look centimetre-scaled. Unit inference therefore uses joints that own at least
+    // 5% of one vertex; if an invalid/non-normalized source has none, retain the fail-safe of using every
+    // positive influence so the later conformance checks still see the rig rather than an empty set.
+    const materialWeightedJoints = [...maxWeightByJoint]
+        .map((weight, index) => ({ weight, index }))
+        .filter(({ weight }) => weight >= 0.05)
+        .map(({ index }) => index);
+    const weightedJointIndices = new Set(materialWeightedJoints.length > 0
+        ? materialWeightedJoints
+        : [...maxWeightByJoint].flatMap((weight, index) => weight > 0 ? [index] : []));
+    let jointMinY = Infinity, jointMaxY = -Infinity;
+    // A modular garment still carries the complete avatar skin, but only a local subset of those joints
+    // influences its vertices. Comparing sleeves against the full head-to-foot span misclassifies a valid
+    // metre rig as centimetres. The weighted joints are the only skeleton extent represented by this mesh.
+    for (const index of weightedJointIndices) {
+        const p = rawTsrc[index];
+        if (p === undefined)
+            continue;
+        jointMinY = Math.min(jointMinY, p[1]);
+        jointMaxY = Math.max(jointMaxY, p[1]);
+    }
+    const meshSpanY = meshMaxY - meshMinY, skelSpanY = jointMaxY - jointMinY;
+    // A rigidly weighted garment can legitimately reference only one joint, leaving the weighted Y-span at
+    // zero. In that case compare its nearest mapped bone segment with the same canonical segment. This keeps
+    // the decision local to the represented anatomy while still distinguishing metre and centimetre rigs.
+    let anchoredDecade = 1;
+    if (skelSpanY <= 1e-6) {
+        const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+        findAnchor: for (const index of weightedJointIndices) {
+            const candidates = [];
+            for (let parent = parentIdx[index]; parent >= 0; parent = parentIdx[parent])
+                candidates.push(parent);
+            candidates.push(...childIdxs[index]);
+            for (const anchor of candidates) {
+                const sourceSpan = distance(rawTsrc[index], rawTsrc[anchor]);
+                const canonicalWeighted = canon.worldByName.get(helixByWarriorIdx[index]);
+                const canonicalAnchor = canon.worldByName.get(helixByWarriorIdx[anchor]);
+                if (canonicalWeighted === undefined || canonicalAnchor === undefined)
+                    continue;
+                const canonicalSpan = distance(posOf(canonicalWeighted), posOf(canonicalAnchor));
+                if (sourceSpan <= 1e-6 || canonicalSpan <= 1e-6)
+                    continue;
+                anchoredDecade = 10 ** Math.round(Math.log10(sourceSpan / canonicalSpan));
+                break findAnchor;
+            }
+        }
+    }
+    const decade = meshSpanY > 1e-6 && skelSpanY > 1e-6
+        ? 10 ** Math.round(Math.log10(skelSpanY / meshSpanY))
+        : anchoredDecade;
+    // A short garment can span a different Y extent than its weighted joints, even when
+    // it already shares the host's metre frame. The anchor comparison below is the
+    // stronger unit check for host-aligned rebinding; never guess a scale from the hem.
+    const unitScale = mode === 'preserve' ? 1 : 1 / decade;
+    const Tsrc = unitScale === 1 ? rawTsrc : rawTsrc.map((p) => [p[0] * unitScale, p[1] * unitScale, p[2] * unitScale]);
     // The rig the mesh binds to. 'embed': canonical orientations at the source's joint positions
     // (proportions preserved). 'repose': the pristine canonical rest.
     const directPos = new Map();
     wjoints.forEach((j, i) => { const m = boneMap.map[j.getName()]; if (m !== undefined)
         directPos.set(m, Tsrc[i]); });
-    const rig = mode === 'embed' ? fitSkeletonToWarrior(canon, directPos) : canon;
+    // A bone map's weight targets can intentionally fold many muscle/twist helpers onto one joint.
+    // Their skin order is not an anatomical ranking: select the declared source joint after all
+    // weight targets are resolved, including when retargetSkeleton has renamed every helper alike.
+    for (const [target, selected] of opts.anatomicalAnchorJoints ?? []) {
+        const index = idxByNode.get(selected);
+        if (index === undefined || helixByWarriorIdx[index] !== target) {
+            throw new Error(`conformToHelixRest: anatomical anchor for '${target}' is not a matching skin joint`);
+        }
+        directPos.set(target, Tsrc[index]);
+    }
+    if (opts.anatomicalAnchorJoints === undefined) {
+        for (const [target, source] of Object.entries(boneMap.anchors ?? {})) {
+            const matches = wjoints.map((joint, index) => joint.getName() === source ? index : -1).filter((index) => index >= 0);
+            if (matches.length !== 1 || helixByWarriorIdx[matches[0]] !== target) {
+                throw new Error(`conformToHelixRest: anatomical anchor '${source}' for '${target}' must resolve to one matching skin joint`);
+            }
+            directPos.set(target, Tsrc[matches[0]]);
+        }
+    }
+    const fit = mode === 'embed' ? fitSkeletonToWarrior(canon, directPos) : null;
+    const rig = fit !== null ? fit.skeleton : canon;
     const Tdst = (helix) => posOf(rig.worldByName.get(helix));
+    if (mode === 'preserve') {
+        const matched = [...directPos].filter(([name, position]) => name !== 'root' &&
+            Math.hypot(...(0, mat4_1.sub3)(position, Tdst(name))) <= 1e-4);
+        const anchors = ['pelvis', 'head', 'clavicle_l', 'clavicle_r', 'upperarm_l', 'upperarm_r', 'thigh_l', 'thigh_r'];
+        const missing = anchors.filter((name) => !matched.some(([candidate]) => candidate === name));
+        if (matched.length < 10 || matched.length < (directPos.size - Number(directPos.has('root'))) * 0.85 || missing.length > 0) {
+            throw new Error(`conformToHelixRest: host-aligned add-on does not match host rest anchors (matched ${matched.length}/${directPos.size}, missing [${missing.join(', ')}])`);
+        }
+    }
     // 'repose' only: per-warrior-joint frame-based delta D_i = frameDst·frameSrc⁻¹ (both frames from
     // GEOMETRY, so the bone-axis CONVENTION cancels). Unused in 'embed' (mesh is not re-posed).
     const incomingDirSrc = (i) => (parentIdx[i] >= 0 ? (0, mat4_1.normalize3)((0, mat4_1.sub3)(Tsrc[i], Tsrc[parentIdx[i]])) : [0, 1, 0]);
     const incomingDirDst = (i) => parentIdx[i] >= 0 ? (0, mat4_1.normalize3)((0, mat4_1.sub3)(Tdst(helixByWarriorIdx[i]), Tdst(helixByWarriorIdx[parentIdx[i]]))) : [0, 1, 0];
-    const D = mode === 'repose' ? wjoints.map((_, i) => {
+    const directMappedOwner = (i) => {
+        let current = i;
+        while (boneMap.map[wjoints[current].getName()] === undefined) {
+            current = parentIdx[current];
+            if (current < 0) {
+                throw new Error(`conformToHelixRest: '${wjoints[i].getName()}' has no directly mapped repose ancestor`);
+            }
+        }
+        return current;
+    };
+    const correctionByOwner = new Map();
+    const correctionFor = (i) => {
+        const owner = directMappedOwner(i);
+        const cached = correctionByOwner.get(owner);
+        if (cached !== undefined)
+            return cached;
+        // A source helper/corrective with no direct map folds onto its nearest mapped ancestor. Its weights
+        // are remapped to that canonical joint below, so its vertices must inherit the same repose delta as
+        // that joint too. Building a separate target frame for the helper is invalid: both it and its parent
+        // resolve to the same canonical position, producing a zero target axis (MetaHuman hair and face rigs
+        // contain hundreds of these weighted helpers).
+        i = owner;
         const inDir = incomingDirSrc(i);
         let primary = -1, best = -Infinity;
         for (const c of childIdxs[i]) {
             if (helixByWarriorIdx[c] === helixByWarriorIdx[i])
                 continue;
+            // A collapsed target twist cannot define its parent's outgoing frame.
+            // Prefer a real segment (for example thigh -> calf) when one exists.
+            if (Math.hypot(...(0, mat4_1.sub3)(Tdst(helixByWarriorIdx[c]), Tdst(helixByWarriorIdx[i]))) <= 1e-9)
+                continue;
             const d = (0, mat4_1.dot3)((0, mat4_1.normalize3)((0, mat4_1.sub3)(Tsrc[c], Tsrc[i])), inDir);
             if (d > best) {
                 best = d;
@@ -178,10 +588,62 @@ function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
         }
         const axisSrc = primary >= 0 ? (0, mat4_1.normalize3)((0, mat4_1.sub3)(Tsrc[primary], Tsrc[i])) : inDir;
         const axisDst = primary >= 0 ? (0, mat4_1.normalize3)((0, mat4_1.sub3)(Tdst(helixByWarriorIdx[primary]), Tdst(helixByWarriorIdx[i]))) : incomingDirDst(i);
-        return (0, mat4_1.mul4)((0, mat4_1.frameFromAxis)(axisDst, Tdst(helixByWarriorIdx[i])), (0, mat4_1.invert4)((0, mat4_1.frameFromAxis)(axisSrc, Tsrc[i])));
-    }) : null;
+        const sourceAxisLength = Math.hypot(axisSrc[0], axisSrc[1], axisSrc[2]);
+        const targetAxisLength = Math.hypot(axisDst[0], axisDst[1], axisDst[2]);
+        // A host may place a directly mapped twist joint at exactly its parent's rest position.
+        // There is no target segment from which to build its own repose frame; the parent's
+        // correction is the only defined deformation for that collapsed span. This also handles
+        // positive weights on the twist joint, rather than relying on it being unused.
+        const parent = parentIdx[i];
+        if (targetAxisLength <= 1e-9 && parent >= 0 &&
+            helixByWarriorIdx[parent] !== helixByWarriorIdx[i] &&
+            Math.hypot(...(0, mat4_1.sub3)(Tdst(helixByWarriorIdx[i]), Tdst(helixByWarriorIdx[parent]))) <= 1e-9) {
+            const correction = correctionFor(parent);
+            correctionByOwner.set(owner, correction);
+            return correction;
+        }
+        if (sourceAxisLength <= 1e-9 || targetAxisLength <= 1e-9) {
+            throw new Error(`conformToHelixRest: degenerate repose frame for '${wjoints[i].getName()}' `
+                + `(mapped '${helixByWarriorIdx[i]}', primary '${primary >= 0 ? wjoints[primary].getName() : "<incoming>"}', `
+                + `source axis ${axisSrc.join(',')}, target axis ${axisDst.join(',')}, weighted ${weightedJointIndices.has(i)})`);
+        }
+        const correction = (0, mat4_1.mul4)((0, mat4_1.frameFromAxis)(axisDst, Tdst(helixByWarriorIdx[i])), (0, mat4_1.invert4)((0, mat4_1.frameFromAxis)(axisSrc, Tsrc[i])));
+        correctionByOwner.set(owner, correction);
+        return correction;
+    };
+    const D = mode === 'repose' ? wjoints.map((_, i) => correctionFor(i)) : null;
     const canonIndexByName = new Map(canon.jointNames.map((n, i) => [n, i]));
+    // ── AUXILIARY JOINTS ──────────────────────────────────────────────────────────────────────────────────────
+    // Chosen here, before the mesh remap, because their skin indices have to exist by the time JOINTS_* is
+    // rewritten. Appended AFTER the canonical set so canonical indices are untouched and a consumer that knows
+    // nothing about auxiliary joints reads exactly the skeleton it expects.
+    const keepAux = opts.preserveAuxiliary === true && mode === 'embed';
+    const isAux = wjoints.map((j) => keepAux && boneMap.map[j.getName()] === undefined);
+    // Parent-first, so each joint's parent transform is known when it is created.
+    const auxOrder = [];
+    {
+        const pending = new Set(wjoints.map((_, i) => i).filter((i) => isAux[i]));
+        let progress = true;
+        while (pending.size > 0 && progress) {
+            progress = false;
+            for (const i of [...pending]) {
+                const p = parentIdx[i];
+                if (p >= 0 && pending.has(p))
+                    continue;
+                auxOrder.push(i);
+                pending.delete(i);
+                progress = true;
+            }
+        }
+        // A cycle cannot happen in a glTF node tree; if it somehow did, dropping is safer than looping forever.
+        for (const i of pending)
+            isAux[i] = false;
+    }
+    const auxSlot = new Map();
+    auxOrder.forEach((i, k) => auxSlot.set(i, canon.jointNames.length + k));
     const newIndexForWarriorIdx = wjoints.map((_, i) => {
+        if (isAux[i])
+            return auxSlot.get(i);
         const idx = canonIndexByName.get(helixByWarriorIdx[i]);
         if (idx === undefined)
             throw new Error(`conformToHelixRest: '${helixByWarriorIdx[i]}' not a canonical joint`);
@@ -189,72 +651,132 @@ function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
     });
     // Remap JOINTS_* to the canonical joint order on every primitive; in 'repose' also blend D into
     // POSITION/NORMAL. In 'embed' the geometry is left untouched.
+    //
+    // Both passes rewrite ACCESSORS in place, and accessors are shared: a multi-material mesh from the
+    // FBX converter (Unreal garments with a stitch or trim slot) is one vertex buffer drawn by several
+    // primitives. Processing per primitive therefore rewrote a shared JOINTS_0 once per primitive, and
+    // the second pass read canonical indices back as SOURCE indices — thigh/calf correctives landed on
+    // whatever source joint sat at the thigh's canonical slot (the left hand's fingers on a MetaHuman
+    // rig). 'repose' blended the same POSITION twice with the same confusion. Every source array is
+    // therefore snapshotted before anything is written, and each accessor is written exactly once.
+    const originalJoints = new Map();
+    const skinnedPrimitives = root.listNodes()
+        .filter((node) => node.getSkin() === wskin && node.getMesh() !== null)
+        .flatMap((node) => node.getMesh().listPrimitives())
+        .filter((prim) => prim.listSemantics().some((s) => s.startsWith('JOINTS_')));
+    for (const prim of skinnedPrimitives) {
+        for (const semantic of prim.listSemantics().filter((s) => s.startsWith('JOINTS_'))) {
+            const accessor = prim.getAttribute(semantic);
+            if (!originalJoints.has(accessor))
+                originalJoints.set(accessor, new Uint32Array(accessor.getArray()));
+        }
+    }
+    const reposed = new Set();
     let verticesProcessed = 0;
-    for (const node of root.listNodes()) {
-        if (node.getSkin() !== wskin || node.getMesh() === null)
+    for (const prim of skinnedPrimitives) {
+        const setCount = prim.listSemantics().filter((s) => s.startsWith('JOINTS_')).length;
+        const pos = prim.getAttribute('POSITION');
+        const nrm = prim.getAttribute('NORMAL');
+        const vCount = pos.getCount();
+        if (reposed.has(pos))
             continue;
-        for (const prim of node.getMesh().listPrimitives()) {
-            const setCount = prim.listSemantics().filter((s) => s.startsWith('JOINTS_')).length;
-            if (setCount === 0)
-                continue;
-            const pos = prim.getAttribute('POSITION');
-            const nrm = prim.getAttribute('NORMAL');
-            const vCount = pos.getCount();
-            const jointSets = Array.from({ length: setCount }, (_, s) => new Uint32Array(prim.getAttribute(`JOINTS_${s}`).getArray()));
-            if (D !== null) {
-                const weightSets = Array.from({ length: setCount }, (_, s) => prim.getAttribute(`WEIGHTS_${s}`).getArray());
-                const posArr = Float32Array.from(pos.getArray());
-                const nrmArr = nrm !== null ? Float32Array.from(nrm.getArray()) : null;
-                for (let v = 0; v < vCount; v++) {
-                    const p = [posArr[v * 3], posArr[v * 3 + 1], posArr[v * 3 + 2]];
-                    const n = nrmArr !== null ? [nrmArr[v * 3], nrmArr[v * 3 + 1], nrmArr[v * 3 + 2]] : null;
-                    let px = 0, py = 0, pz = 0, nx = 0, ny = 0, nz = 0, wsum = 0;
-                    for (let s = 0; s < setCount; s++)
-                        for (let c = 0; c < 4; c++) {
-                            const w = weightSets[s][v * 4 + c];
-                            if (w === 0)
-                                continue;
-                            const d = D[jointSets[s][v * 4 + c]];
-                            const tp = (0, mat4_1.transformPoint)(d, p);
-                            px += w * tp[0];
-                            py += w * tp[1];
-                            pz += w * tp[2];
-                            if (n !== null) {
-                                const td = (0, mat4_1.transformDir)(d, n);
-                                nx += w * td[0];
-                                ny += w * td[1];
-                                nz += w * td[2];
-                            }
-                            wsum += w;
-                        }
-                    if (wsum > 0) {
-                        px /= wsum;
-                        py /= wsum;
-                        pz /= wsum;
-                    }
-                    posArr[v * 3] = px;
-                    posArr[v * 3 + 1] = py;
-                    posArr[v * 3 + 2] = pz;
-                    if (nrmArr !== null) {
-                        const l = Math.hypot(nx, ny, nz) || 1;
-                        nrmArr[v * 3] = nx / l;
-                        nrmArr[v * 3 + 1] = ny / l;
-                        nrmArr[v * 3 + 2] = nz / l;
+        reposed.add(pos);
+        verticesProcessed += vCount;
+        if (D === null)
+            continue;
+        const jointSets = Array.from({ length: setCount }, (_, s) => originalJoints.get(prim.getAttribute(`JOINTS_${s}`)));
+        const weightSets = Array.from({ length: setCount }, (_, s) => prim.getAttribute(`WEIGHTS_${s}`).getArray());
+        const posArr = Float32Array.from(pos.getArray());
+        const nrmArr = nrm !== null && !reposed.has(nrm) ? Float32Array.from(nrm.getArray()) : null;
+        for (let v = 0; v < vCount; v++) {
+            const p = [posArr[v * 3], posArr[v * 3 + 1], posArr[v * 3 + 2]];
+            const n = nrmArr !== null ? [nrmArr[v * 3], nrmArr[v * 3 + 1], nrmArr[v * 3 + 2]] : null;
+            let px = 0, py = 0, pz = 0, nx = 0, ny = 0, nz = 0, wsum = 0;
+            for (let s = 0; s < setCount; s++)
+                for (let c = 0; c < 4; c++) {
+                    const w = weightSets[s][v * 4 + c];
+                    if (w === 0)
+                        continue;
+                    const d = D[jointSets[s][v * 4 + c]];
+                    const tp = (0, mat4_1.transformPoint)(d, p);
+                    px += w * tp[0];
+                    py += w * tp[1];
+                    pz += w * tp[2];
+                    if (n !== null) {
+                        const td = (0, mat4_1.transformDir)(d, n);
+                        nx += w * td[0];
+                        ny += w * td[1];
+                        nz += w * td[2];
                     }
+                    wsum += w;
                 }
-                pos.setArray(posArr);
-                if (nrm !== null && nrmArr !== null)
-                    nrm.setArray(nrmArr);
+            if (wsum > 0) {
+                px /= wsum;
+                py /= wsum;
+                pz /= wsum;
             }
-            for (let s = 0; s < setCount; s++) {
-                const src = jointSets[s];
-                const out = new Uint16Array(src.length);
-                for (let k = 0; k < src.length; k++)
-                    out[k] = newIndexForWarriorIdx[src[k]];
-                prim.getAttribute(`JOINTS_${s}`).setArray(out);
+            posArr[v * 3] = px;
+            posArr[v * 3 + 1] = py;
+            posArr[v * 3 + 2] = pz;
+            if (nrmArr !== null) {
+                const l = Math.hypot(nx, ny, nz) || 1;
+                nrmArr[v * 3] = nx / l;
+                nrmArr[v * 3 + 1] = ny / l;
+                nrmArr[v * 3 + 2] = nz / l;
             }
-            verticesProcessed += vCount;
         }
+        pos.setArray(posArr);
+        if (nrm !== null && nrmArr !== null) {
+            nrm.setArray(nrmArr);
+            reposed.add(nrm);
+        }
+    }
+    // Folding sends several source joints (a thigh and its twist/bulge correctives) to ONE canonical joint,
+    // so a vertex can name the same canonical joint in more than one slot. That is equivalent under LBS but
+    // wastes influences and hides the owning bone from anything that reads the dominant slot, so the folded
+    // influences are summed per canonical joint and written heaviest first (each accessor set exactly once).
+    const written = new Set();
+    for (const prim of skinnedPrimitives) {
+        const setCount = prim.listSemantics().filter((s) => s.startsWith('JOINTS_')).length;
+        const jointAccessors = Array.from({ length: setCount }, (_, s) => prim.getAttribute(`JOINTS_${s}`));
+        if (jointAccessors.every((a) => written.has(a)))
+            continue;
+        const weightAccessors = Array.from({ length: setCount }, (_, s) => prim.getAttribute(`WEIGHTS_${s}`));
+        const sources = jointAccessors.map((a) => originalJoints.get(a));
+        const outJoints = sources.map((source) => new Uint16Array(source.length));
+        const mergeable = jointAccessors.every((a) => !written.has(a))
+            && weightAccessors.every((a) => a !== null && !written.has(a) && a.getCount() * 4 === sources[0].length);
+        if (!mergeable) {
+            // Inconsistent sharing (never emitted by our converters): plain index remap, weights untouched.
+            sources.forEach((source, s) => { for (let k = 0; k < source.length; k++)
+                outJoints[s][k] = newIndexForWarriorIdx[source[k]]; });
+        }
+        else {
+            const weights = weightAccessors.map((a) => a.getArray());
+            const outWeights = weights.map((w) => new w.constructor(w.length));
+            const vertexCount = sources[0].length / 4;
+            const merged = new Map();
+            for (let v = 0; v < vertexCount; v++) {
+                merged.clear();
+                for (let s = 0; s < setCount; s++)
+                    for (let c = 0; c < 4; c++) {
+                        const w = weights[s][v * 4 + c];
+                        if (w <= 0)
+                            continue;
+                        const joint = newIndexForWarriorIdx[sources[s][v * 4 + c]];
+                        merged.set(joint, (merged.get(joint) ?? 0) + w);
+                    }
+                [...merged].sort((a, b) => b[1] - a[1] || a[0] - b[0]).forEach(([joint, w], slot) => {
+                    outJoints[slot >> 2][v * 4 + (slot & 3)] = joint;
+                    outWeights[slot >> 2][v * 4 + (slot & 3)] = w;
+                });
+            }
+            weightAccessors.forEach((a, s) => { a.setArray(outWeights[s]); written.add(a); });
+        }
+        jointAccessors.forEach((a, s) => { if (!written.has(a)) {
+            a.setArray(outJoints[s]);
+            written.add(a);
+        } });
     }
     // Rebuild the target skeleton (`rig`) in the warrior doc.
     const buffer = root.listBuffers()[0];
@@ -265,13 +787,59 @@ function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
         if (def.parent !== null)
             created.get(def.parent).addChild(created.get(def.name));
     const skeletonRoot = created.get(rig.skeletonRootName);
-    root.listScenes()[0].addChild(skeletonRoot);
-    const newIbm = new Float32Array(rig.jointNames.length * 16);
-    rig.jointNames.forEach((name, i) => newIbm.set((0, mat4_1.invert4)(rig.worldByName.get(name)), i * 16));
+    // The hip-height delta cannot live on the root bone itself: every platform clip carries a constant
+    // root translation track pinned to the origin, so the mixer would null it each frame. Hoist it onto
+    // a wrapper above the root — nothing animates that node (PropertyBinding resolves tracks by bone
+    // name), so the delta survives while the clip harmlessly re-pins the root's now-zero local.
+    const rootLocal = skeletonRoot.getTranslation();
+    // The HOST's own `root_offset` (extractCanonicalSkeleton `hoistRootOffset`): applied here, at the very end,
+    // so the repose maths above ran in the offset-free source frame and the mesh stays where the garment was
+    // authored — in the host's mesh frame. Only the SKELETON the part carries moves: the part rides the host's
+    // bones with its OWN inverse-bind matrices (attachSkinnedPart), so for the part to land where it was
+    // authored its skeleton must be the host's skeleton in the host's frame — wrapper included. Auxiliary
+    // joints (character imports only) sit in the source frame already; leave those alone.
+    const hostOffset = canon.rootOffset !== undefined && auxOrder.length === 0 ? canon.rootOffset : null;
+    if (Math.hypot(rootLocal[0], rootLocal[1], rootLocal[2]) > 1e-9 || hostOffset !== null) {
+        const wrapperMatrix = (0, mat4_1.mul4)(hostOffset ?? IDENTITY, [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, rootLocal[0], rootLocal[1], rootLocal[2], 1]);
+        const wrapper = warrior.createNode('root_offset').setMatrix(wrapperMatrix);
+        skeletonRoot.setTranslation([0, 0, 0]);
+        wrapper.addChild(skeletonRoot);
+        root.listScenes()[0].addChild(wrapper);
+    }
+    else {
+        root.listScenes()[0].addChild(skeletonRoot);
+    }
+    // Auxiliary joints keep their SOURCE world rest transform (unit-scaled). In 'embed' the mesh was never
+    // moved, so that transform is still exactly the one the skin weights were authored against.
+    const auxWorld = new Map();
+    const auxNode = new Map();
+    for (const i of auxOrder) {
+        const raw = [...wjoints[i].getWorldMatrix()];
+        raw[12] = raw[12] * unitScale;
+        raw[13] = raw[13] * unitScale;
+        raw[14] = raw[14] * unitScale;
+        const world = (0, mat4_1.rigidize)(raw);
+        const p = parentIdx[i];
+        const parentWorld = p < 0 ? IDENTITY
+            : isAux[p] ? auxWorld.get(p)
+                : rig.worldByName.get(helixByWarriorIdx[p]);
+        const parentTarget = p < 0 ? skeletonRoot
+            : isAux[p] ? auxNode.get(p)
+                : created.get(helixByWarriorIdx[p]);
+        const node = warrior.createNode(wjoints[i].getName()).setMatrix((0, mat4_1.mul4)((0, mat4_1.invert4)(parentWorld), world));
+        parentTarget.addChild(node);
+        auxWorld.set(i, world);
+        auxNode.set(i, node);
+    }
+    const newIbm = new Float32Array((rig.jointNames.length + auxOrder.length) * 16);
+    rig.jointNames.forEach((name, i) => newIbm.set((0, mat4_1.invert4)(hostOffset === null ? rig.worldByName.get(name) : (0, mat4_1.mul4)(hostOffset, rig.worldByName.get(name))), i * 16));
+    auxOrder.forEach((i, k) => newIbm.set((0, mat4_1.invert4)(auxWorld.get(i)), (rig.jointNames.length + k) * 16));
     const newIbmAcc = warrior.createAccessor().setType('MAT4').setArray(newIbm).setBuffer(buffer);
     const newSkin = warrior.createSkin('helix-humanoid').setInverseBindMatrices(newIbmAcc).setSkeleton(skeletonRoot);
     for (const name of rig.jointNames)
         newSkin.addJoint(created.get(name));
+    for (const i of auxOrder)
+        newSkin.addJoint(auxNode.get(i));
     // Rebind the mesh nodes, reparent to the scene at identity, and delete the old rig + its bind-pose anim.
     const scene = root.listScenes()[0];
     for (const node of root.listNodes()) {
@@ -287,6 +855,11 @@ function conformToHelixRest(warrior, canon, boneMap, opts = {}) {
     const topOld = (() => { let cur = wjoints[0]; for (let p = parentNode(cur); p !== null; p = parentNode(cur))
         cur = p; return cur; })();
     topOld.dispose();
-    return { mode, verticesProcessed, jointsRebuilt: rig.jointNames.length, weightTargets };
+    return {
+        mode, unitScale, restAimed: fit?.restAimed ?? 0, verticesProcessed,
+        jointsRebuilt: rig.jointNames.length + auxOrder.length,
+        weightTargets,
+        auxiliaryJoints: auxOrder.map((i) => wjoints[i].getName()),
+    };
 }
 //# sourceMappingURL=conform.js.map