@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/vrmCharacter.js

@@ -0,0 +1,678 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEARABLE_BUDGET = exports.HERO_BUDGET = exports.YAW_FLIP = void 0;
+exports.readGlbJson = readGlbJson;
+exports.vrmBoneMap = vrmBoneMap;
+exports.collapseIdenticalSkins = collapseIdenticalSkins;
+exports.bakeYawFlip = bakeYawFlip;
+exports.makeVrmCharacter = makeVrmCharacter;
+const node_fs_1 = require("node:fs");
+const core_1 = require("@gltf-transform/core");
+const extensions_1 = require("@gltf-transform/extensions");
+const conform_1 = require("./stages/conform");
+const retarget_1 = require("./stages/retarget");
+const resizeTextures_1 = require("./stages/resizeTextures");
+const simplifyMesh_1 = require("./stages/simplifyMesh");
+const report_1 = require("./stages/report");
+const mat4_1 = require("./mat4");
+const vrmDynamics_1 = require("./stages/vrmDynamics");
+const faceManifest_1 = require("./faceManifest");
+const vrmFace_1 = require("./stages/vrmFace");
+const functions_1 = require("@gltf-transform/functions");
+const atlasMaterials_1 = require("./stages/atlasMaterials");
+const firstPersonHide_1 = require("./stages/firstPersonHide");
+/**
+ * VRM → a playable HELIX character, secondary motion and all.
+ *
+ * `character-pipeline make-vrm-character <avatar.vrm> --canonical <body-m-default.web.glb> -o <out.glb>`
+ *
+ * Three things have to survive this conversion for the result to be worth anything, and each is a place the
+ * obvious implementation loses one of them:
+ *
+ *   1. The BODY has to end up on `helix-humanoid@1` so the platform's own locomotion clips drive it. That is
+ *      `conformToHelixRest` in 'embed' mode — it fits the canonical skeleton to the source's joint positions
+ *      rather than re-posing the mesh, so the character keeps its own proportions and silhouette.
+ *
+ *   2. The HAIR, EARS, TAIL, SKIRT and accessory joints have to survive as joints. Conform's default is to
+ *      resolve every unmapped joint to its nearest mapped ancestor, which turns a nineteen-chain hairstyle into
+ *      one rigid lump welded to `head`. `preserveAuxiliary` is what stops that.
+ *
+ *   3. The SPRING CONFIGURATION has to come across pointing at those same joints. It does, because the
+ *      auxiliary joints keep their source names, so the importer's chain roots resolve unchanged.
+ *
+ * The humanoid bone map is derived from the file's own `VRMC_vrm`/`VRM` humanoid block rather than guessed from
+ * naming conventions — every VRM carries an explicit map, which is exactly what makes VRM the sane import
+ * target and a raw FBX not.
+ */
+/** VRM humanoid bone id → `helix-humanoid@1` joint. VRM's three-segment spine spreads across helix's five. */
+const HUMANOID_TO_HELIX = {
+    hips: 'pelvis', spine: 'spine_01', chest: 'spine_03', upperChest: 'spine_05',
+    neck: 'neck_01', head: 'head',
+    leftShoulder: 'clavicle_l', leftUpperArm: 'upperarm_l', leftLowerArm: 'lowerarm_l', leftHand: 'hand_l',
+    rightShoulder: 'clavicle_r', rightUpperArm: 'upperarm_r', rightLowerArm: 'lowerarm_r', rightHand: 'hand_r',
+    leftUpperLeg: 'thigh_l', leftLowerLeg: 'calf_l', leftFoot: 'foot_l', leftToes: 'ball_l',
+    rightUpperLeg: 'thigh_r', rightLowerLeg: 'calf_r', rightFoot: 'foot_r', rightToes: 'ball_r',
+};
+/**
+ * Finger bones, which are the ONE part of the humanoid vocabulary the two VRM versions disagree about.
+ *
+ * 0.x names the thumb's three segments Proximal / Intermediate / Distal, like every other digit. 1.0 renamed
+ * them Metacarpal / Proximal / Distal to match the anatomy — the thumb has no intermediate phalanx, and what
+ * 0.x called `Proximal` is really the metacarpal. So `leftThumbProximal` exists in BOTH versions and means a
+ * DIFFERENT bone in each, which is why this cannot be one flat table.
+ *
+ * Reading a 0.x file through the 1.0 table is not a near miss. `leftThumbProximal` lands on `thumb_02_l`, the
+ * whole thumb shifts one segment out, `leftThumbIntermediate` matches nothing and survives as a stray
+ * auxiliary joint, and `thumb_01_l` — the joint every authored hand pose actually rotates — drives nothing.
+ */
+function fingerBoneMap(version) {
+    const map = {};
+    for (const side of ['left', 'right']) {
+        const s = side === 'left' ? 'l' : 'r';
+        for (const [vrm, helix] of [['Thumb', 'thumb'], ['Index', 'index'], ['Middle', 'middle'], ['Ring', 'ring'], ['Little', 'pinky']]) {
+            const segments = vrm !== 'Thumb'
+                ? ['Proximal', 'Intermediate', 'Distal']
+                : version === '1.0' ? ['Metacarpal', 'Proximal', 'Distal'] : ['Proximal', 'Intermediate', 'Distal'];
+            segments.forEach((segment, i) => { map[`${side}${vrm}${segment}`] = `${helix}_0${i + 1}_${s}`; });
+        }
+    }
+    return map;
+}
+/** Read the JSON chunk out of a GLB/VRM without a full parse — the humanoid map lives there. */
+function readGlbJson(path) {
+    const buffer = (0, node_fs_1.readFileSync)(path);
+    const total = buffer.readUInt32LE(8);
+    let offset = 12;
+    while (offset < total) {
+        const length = buffer.readUInt32LE(offset);
+        const type = buffer.readUInt32LE(offset + 4);
+        if (type === 0x4e4f534a)
+            return JSON.parse(buffer.subarray(offset + 8, offset + 8 + length).toString('utf8'));
+        offset += 8 + length;
+    }
+    throw new Error(`${path}: no glTF JSON chunk`);
+}
+/** Build a `BoneMap` from the VRM's own humanoid block. Handles both the 0.x array and the 1.0 object form. */
+function vrmBoneMap(json, label) {
+    const nodes = json.nodes ?? [];
+    const vrm1 = json.extensions?.VRMC_vrm?.humanoid?.humanBones;
+    const vrm0 = json.extensions?.VRM?.humanoid?.humanBones;
+    const map = {};
+    // The finger half of the vocabulary is version-dependent, so the version is resolved BEFORE any lookup.
+    const version = Array.isArray(vrm0) ? '0.x' : '1.0';
+    const humanoid = { ...HUMANOID_TO_HELIX, ...fingerBoneMap(version) };
+    if (Array.isArray(vrm0)) {
+        for (const entry of vrm0) {
+            const helix = humanoid[entry.bone];
+            const name = nodes[entry.node]?.name;
+            if (helix !== undefined && name !== undefined)
+                map[name] = helix;
+        }
+    }
+    else if (vrm1 !== undefined) {
+        for (const [bone, ref] of Object.entries(vrm1)) {
+            const helix = humanoid[bone];
+            const name = nodes[ref.node]?.name;
+            if (helix !== undefined && name !== undefined)
+                map[name] = helix;
+        }
+    }
+    else {
+        throw new Error(`${label}: no VRM humanoid block — this is not a VRM`);
+    }
+    // Everything above the hips maps onto `root`, or conform hits an unmapped top-level ancestor and refuses.
+    const hipsName = Object.keys(map).find((name) => map[name] === 'pelvis');
+    let cursor = nodes.findIndex((n) => n.name === hipsName);
+    for (let guard = 0; guard < 8 && cursor >= 0; guard++) {
+        const parent = nodes.findIndex((n) => (n.children ?? []).includes(cursor));
+        if (parent < 0)
+            break;
+        const name = nodes[parent]?.name;
+        if (name !== undefined && map[name] === undefined)
+            map[name] = 'root';
+        cursor = parent;
+    }
+    return { name: `VRM → helix-humanoid@1 (${label})`, version: '1.0.0', map };
+}
+/**
+ * Point every skinned mesh at ONE skin when the file's skins are interchangeable.
+ *
+ * VRoid exports the body, the face and the hair as separate meshes with separate `Skin` objects that share an
+ * identical joint list and identical inverse bind matrices — three names for one skeleton. `conformToHelixRest`
+ * reads `listSkins()[0]` and rebinds only the meshes using it, so on a file like that it silently converts a
+ * third of the character and leaves the rest bound to a rig it then deletes. The result loads, and the hair is
+ * in the wrong place forever.
+ *
+ * Collapsing only happens when the skins are provably the same skeleton — same joints in the same order, same
+ * bind matrices. Anything else is left alone and reported, because merging genuinely different skins is a
+ * different and much harder operation than this.
+ */
+function collapseIdenticalSkins(document) {
+    const skins = document.getRoot().listSkins();
+    if (skins.length < 2)
+        return 0;
+    const signature = (skin) => {
+        const joints = skin.listJoints().map((j) => j.getName()).join('|');
+        const ibm = skin.getInverseBindMatrices()?.getArray();
+        // Bind matrices are compared at float32 precision, which is the precision they are stored at.
+        return `${joints}#${ibm === null || ibm === undefined ? 'none' : Array.from(ibm).join(',')}`;
+    };
+    const first = skins[0];
+    const target = signature(first);
+    const duplicates = skins.slice(1).filter((skin) => signature(skin) === target);
+    if (duplicates.length === 0)
+        return 0;
+    const dead = new Set(duplicates);
+    for (const node of document.getRoot().listNodes()) {
+        const skin = node.getSkin();
+        if (skin !== null && dead.has(skin))
+            node.setSkin(first);
+    }
+    for (const skin of duplicates)
+        skin.dispose();
+    return duplicates.length;
+}
+function measureRigFidelity(document, renamed, canonWorldByName, pre = null) {
+    const joints = new Set();
+    for (const skin of document.getRoot().listSkins())
+        for (const joint of skin.listJoints())
+            joints.add(joint);
+    let max = 0, sum = 0, count = 0, worst = '(none)';
+    for (const joint of joints) {
+        const helix = renamed[joint.getName()] ?? joint.getName();
+        const canonRaw = canonWorldByName.get(helix);
+        if (canonRaw === undefined)
+            continue;
+        // The reference has to live in the same space as the rig: a flipped import is compared against a flipped
+        // canonical, or every bone reads as ~180 degrees wrong and the metric measures its own miscalibration.
+        const canonical = pre === null ? canonRaw : (0, mat4_1.mul4)(pre, canonRaw);
+        // LOCAL rest rotation, not world. A clip stores per-bone LOCAL rotations, so a rig that is globally
+        // rotated but locally consistent plays clips perfectly — comparing world frames measures a difference the
+        // animation never sees, and reports a correct rig as tens of degrees wrong.
+        const parentNode = [...joint.listParents()].find((c) => joints.has(c));
+        const parentWorld = parentNode === undefined ? null : parentNode.getWorldMatrix();
+        const world = joint.getWorldMatrix();
+        const local = parentWorld === null ? world : (0, mat4_1.mul4)((0, mat4_1.invert4)(parentWorld), world);
+        const canonParent = parentNode === undefined ? undefined
+            : canonWorldByName.get(renamed[parentNode.getName()] ?? parentNode.getName());
+        const canonLocal = canonParent === undefined ? canonical : (0, mat4_1.mul4)((0, mat4_1.invert4)(canonParent), canonical);
+        let trace = 0;
+        for (let c = 0; c < 3; c++)
+            for (let r = 0; r < 3; r++)
+                trace += local[c * 4 + r] * canonLocal[c * 4 + r];
+        const degrees = (Math.acos(Math.min(1, Math.max(-1, (trace - 1) / 2))) * 180) / Math.PI;
+        sum += degrees;
+        count++;
+        if (degrees > max) {
+            max = degrees;
+            worst = helix;
+        }
+    }
+    return { maxDegrees: +max.toFixed(1), meanDegrees: +(count > 0 ? sum / count : 0).toFixed(1), worst };
+}
+/**
+ * Re-orient the renamed joints onto the CANONICAL rest orientations, keeping their positions, and recompute the
+ * bind matrices so the mesh does not move.
+ *
+ * This is the whole reason a rename alone is not enough. A locomotion clip stores, per bone, a LOCAL rotation
+ * expressed in that bone's rest frame. `helix-humanoid@1`'s pelvis rest frame and a VRoid avatar's hips rest
+ * frame differ by about ninety degrees, so playing an idle authored for the first on the second lays the
+ * character flat on her back — which is exactly what it did.
+ *
+ * The fix is cheap because rest ORIENTATION and rest POSITION are separable. Give every mapped joint the
+ * canonical orientation, keep its own position (so the avatar keeps its proportions and silhouette), and set the
+ * inverse bind matrix to the inverse of that new rest world. At rest `world · IBM` is still the identity, so the
+ * mesh renders byte-identically; what changed is only the frame the clips are interpreted in.
+ *
+ * Auxiliary joints — hair, ears, tail, skirt — keep their own orientation untouched. Nothing addresses them by
+ * name from a clip, and their springs were authored against exactly the frames they already have.
+ *
+ * The canonical orientation is AIMED before it is used. Copying it wholesale gives every mapped bone the frame
+ * the canonical body has, which is only correct if the avatar's limbs point where the canonical body's do — and
+ * they do not: a VRoid avatar stands closer to a T-pose than `helix-humanoid@1` does, so the arms end up held
+ * out sideways through the whole run cycle. Rotating the canonical frame by the arc from the canonical bone's
+ * own rest direction to THIS avatar's rest direction keeps the canonical twist convention (which is what the
+ * clips address) while pointing the bone down the limb that actually exists.
+ */
+function reorientToCanonicalRest(document, renamed, canonWorldByName, pre = null) {
+    const joints = new Set();
+    for (const skin of document.getRoot().listSkins())
+        for (const joint of skin.listJoints())
+            joints.add(joint);
+    // Parent-first, so a joint's new parent world is known before its local is derived.
+    const parentOf = new Map();
+    for (const joint of joints) {
+        let parent = null;
+        for (const candidate of joint.listParents()) {
+            if (candidate instanceof Object && joints.has(candidate)) {
+                parent = candidate;
+                break;
+            }
+        }
+        parentOf.set(joint, parent);
+    }
+    const ordered = [];
+    const placed = new Set();
+    let progress = true;
+    while (ordered.length < joints.size && progress) {
+        progress = false;
+        for (const joint of joints) {
+            if (placed.has(joint))
+                continue;
+            const parent = parentOf.get(joint) ?? null;
+            if (parent !== null && !placed.has(parent))
+                continue;
+            ordered.push(joint);
+            placed.add(joint);
+            progress = true;
+        }
+    }
+    // `pre` is the forward-convention flip. Applying it to every joint world here is the skeleton half of the
+    // rotation whose vertex half `bakeYawFlip` performed; doing them in one pass is what keeps the binding valid.
+    const oldWorld = new Map(ordered.map((j) => {
+        const world = [...j.getWorldMatrix()];
+        return [j, pre === null ? world : (0, mat4_1.mul4)(pre, world)];
+    }));
+    const newWorld = new Map();
+    let reoriented = 0;
+    let flipped = false;
+    const helixOf = (joint) => renamed[joint.getName()] ?? (canonWorldByName.has(joint.getName()) ? joint.getName() : undefined);
+    const posOf = (m) => [m[12], m[13], m[14]];
+    const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+    // A joint's aim child: the first MAPPED child, so the arc is measured between corresponding segments.
+    const aimChild = new Map();
+    for (const joint of ordered) {
+        const parent = parentOf.get(joint) ?? null;
+        if (parent === null || aimChild.has(parent))
+            continue;
+        if (helixOf(parent) !== undefined && helixOf(joint) !== undefined)
+            aimChild.set(parent, joint);
+    }
+    for (const joint of ordered) {
+        const current = oldWorld.get(joint);
+        const helix = helixOf(joint);
+        const canonical = helix === undefined ? undefined : canonWorldByName.get(helix);
+        let world;
+        if (canonical === undefined) {
+            world = current; // auxiliary: unchanged
+        }
+        else {
+            let oriented = [...canonical];
+            const child = aimChild.get(joint);
+            const childHelix = child === undefined ? undefined : helixOf(child);
+            const childCanon = childHelix === undefined ? undefined : canonWorldByName.get(childHelix);
+            if (child !== undefined && childCanon !== undefined) {
+                // MEASURED: aiming with the source direction as-is scores 36.5 degrees mean divergence from the
+                // canonical frames; carrying it back through the forward flip first — which looks more principled —
+                // scores 56. The spaces here are genuinely subtle and the number is the arbiter, not the argument.
+                const srcDir = sub(posOf(oldWorld.get(child)), posOf(current));
+                const canonDir = sub(posOf(childCanon), posOf(canonical));
+                if (Math.hypot(...srcDir) > 1e-6 && Math.hypot(...canonDir) > 1e-6) {
+                    oriented = (0, mat4_1.mul4)((0, mat4_1.shortestArc4)((0, mat4_1.normalize3)(canonDir), (0, mat4_1.normalize3)(srcDir)), oriented);
+                }
+            }
+            world = oriented;
+            world[12] = current[12];
+            world[13] = current[13];
+            world[14] = current[14];
+            reoriented++;
+        }
+        newWorld.set(joint, world);
+        const parent = parentOf.get(joint) ?? null;
+        const parentWorld = parent === null ? [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] : newWorld.get(parent);
+        joint.setMatrix((0, mat4_1.mul4)((0, mat4_1.invert4)(parentWorld), world));
+    }
+    for (const skin of document.getRoot().listSkins()) {
+        const list = skin.listJoints();
+        const ibm = new Float32Array(list.length * 16);
+        list.forEach((joint, i) => ibm.set((0, mat4_1.invert4)(newWorld.get(joint)), i * 16));
+        skin.getInverseBindMatrices()?.setArray(ibm);
+    }
+    return reoriented;
+}
+/**
+ * VRM 0.x models face +Z. glTF, three.js and `helix-humanoid@1` all face −Z.
+ *
+ * ── WHY THIS IS BAKED INTO THE GEOMETRY AND NOT APPLIED AT RUNTIME ─────────────────────────────────────────────
+ * The obvious fix is a 180° wrapper node above the skeleton. It is wrong, and wrong in a way that looks right
+ * standing still: the wrapper rotates the animated RESULT, so the character faces the correct way but every clip
+ * plays mirrored — she runs backwards, and her heels lead. The locomotion system then turns the model to face
+ * its velocity, which hides the cause and leaves only the symptom.
+ *
+ * The convention has to be normalised into the asset instead. Rotating a skinned character by `R` means rotating
+ * three things together, or the binding breaks:
+ *
+ *     v_bind' = R·v_bind            the vertices
+ *     jointWorld' = R·jointWorld    the skeleton
+ *     IBM' = inverse(jointWorld')   the bind matrices, which follow
+ *
+ * Then `jointWorld'·IBM'·v_bind'` reduces to `R·(jointWorld·IBM·v_bind)`: the whole character turns around and
+ * every weight still means what it meant. This function does the vertices; `reorientToCanonicalRest` does the
+ * skeleton and the bind matrices in the same pass, which is why the two are always called together.
+ *
+ * The skeleton half CANNOT live on the root bone. Platform clips carry `root:rotation` and `pelvis:rotation`
+ * tracks — verified, not assumed — so a rotation written there is overwritten by the mixer on the first frame.
+ */
+exports.YAW_FLIP = [-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1];
+/** Rotate every vertex position, normal and tangent 180° about Y, in place. */
+function bakeYawFlip(document) {
+    let primitives = 0;
+    const seen = new Set();
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives()) {
+            for (const semantic of ['POSITION', 'NORMAL', 'TANGENT']) {
+                const accessor = primitive.getAttribute(semantic);
+                if (accessor === null || seen.has(accessor))
+                    continue;
+                seen.add(accessor);
+                const array = accessor.getArray();
+                if (array === null)
+                    continue;
+                const stride = accessor.getElementSize();
+                // (x, y, z) → (−x, y, −z). A tangent's fourth component is a handedness sign and must not be touched.
+                for (let i = 0; i < array.length; i += stride) {
+                    array[i] = -array[i];
+                    array[i + 2] = -array[i + 2];
+                }
+                accessor.setArray(array);
+            }
+            // Morph targets ride the same space as the base geometry.
+            for (const target of primitive.listTargets()) {
+                for (const semantic of ['POSITION', 'NORMAL']) {
+                    const accessor = target.getAttribute(semantic);
+                    if (accessor === null || seen.has(accessor))
+                        continue;
+                    seen.add(accessor);
+                    const array = accessor.getArray();
+                    if (array === null)
+                        continue;
+                    for (let i = 0; i < array.length; i += 3) {
+                        array[i] = -array[i];
+                        array[i + 2] = -array[i + 2];
+                    }
+                    accessor.setArray(array);
+                }
+            }
+            primitives++;
+        }
+    }
+    return primitives;
+}
+/**
+ * The hero budget from the character architecture: 15k triangles for a fully dressed character, and the 512-pixel
+ * canonical character texture size. Well inside the validator's 60k/10 MB avatar ceiling, which is a refusal threshold rather than a
+ * target.
+ */
+/**
+ * The hero import budget.
+ *
+ * `maxMaterials` is the platform publish gate's own number (`AVATAR_MAX_MATERIALS`), not a pipeline preference:
+ * an import that clears triangles and bytes but ships 28 materials is refused at upload, and the creator learns
+ * that after the round trip rather than here.
+ */
+exports.HERO_BUDGET = { triangles: 15_000, textureSize: 512, maxMaterials: 8 };
+/**
+ * The wearable budget — roughly a third of an avatar's, because several are worn on one at a time.
+ *
+ * The platform's own `WEARABLE_MAX_*` ceilings are 20,000 triangles and 6 MB; this aims under them for the same
+ * reason `HERO_BUDGET` aims under the avatar's, so a garment that later gains a layer does not immediately
+ * breach the gate.
+ */
+exports.WEARABLE_BUDGET = { triangles: 8_000, textureSize: 512, maxMaterials: 4 };
+/**
+ * Keep only the surfaces whose material name matches, dropping the rest.
+ *
+ * How a WEARABLE is cut from a source avatar: the same conversion runs — the flip, the conform, the spring
+ * bones, the budget — and then everything that is not the garment is deleted. Re-deriving a separate extraction
+ * path would mean two implementations of the hard parts (forward axis, skeleton rebuild, chain survival) and
+ * only one of them getting fixed when either is wrong.
+ *
+ * Selection is by MATERIAL name because that is what a VRoid export actually organises by: `_CLOTH`, `_SKIN`,
+ * `_HAIR`, `_FACE`, and a garment slot inside that (`Tops`, `Onepiece`, `Shoes`, `Accessory`).
+ */
+function keepMatchingPrimitives(document, keep) {
+    let kept = 0;
+    let dropped = 0;
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives()) {
+            const name = primitive.getMaterial()?.getName() ?? '';
+            if (keep.test(name)) {
+                kept++;
+                continue;
+            }
+            mesh.removePrimitive(primitive);
+            primitive.dispose();
+            dropped++;
+        }
+        if (mesh.listPrimitives().length === 0) {
+            // A mesh with nothing left takes its node with it, or the export carries an empty skinned mesh that
+            // every downstream validator then complains about.
+            for (const node of document.getRoot().listNodes())
+                if (node.getMesh() === mesh)
+                    node.dispose();
+            mesh.dispose();
+        }
+    }
+    return { kept, dropped };
+}
+/**
+ * Joint names any remaining geometry actually has weight on.
+ *
+ * The skeleton survives a primitive deletion untouched — it must, because the wearable binds to the host's
+ * bones — so "is this joint in the skin" cannot tell a garment's own chains from its donor's. Weight can.
+ */
+function weightedJoints(document) {
+    const names = new Set();
+    for (const skin of document.getRoot().listSkins()) {
+        const joints = skin.listJoints();
+        for (const node of document.getRoot().listNodes()) {
+            if (node.getSkin() !== skin)
+                continue;
+            const mesh = node.getMesh();
+            if (mesh === null)
+                continue;
+            for (const primitive of mesh.listPrimitives()) {
+                const jointsAttr = primitive.getAttribute('JOINTS_0');
+                const weightsAttr = primitive.getAttribute('WEIGHTS_0');
+                if (jointsAttr === null || weightsAttr === null)
+                    continue;
+                const jointSlot = [0, 0, 0, 0];
+                const weightSlot = [0, 0, 0, 0];
+                // The primitive's OWN vertices: VRoid shares skin accessors across a mesh's primitives, so reading the
+                // whole attribute would hand a pair of shoes every joint the body is weighted to.
+                for (const vertex of (0, firstPersonHide_1.primitiveVertices)(primitive)) {
+                    jointsAttr.getElement(vertex, jointSlot);
+                    weightsAttr.getElement(vertex, weightSlot);
+                    for (let slot = 0; slot < 4; slot++) {
+                        if (weightSlot[slot] > 0) {
+                            const joint = joints[jointSlot[slot]];
+                            if (joint !== undefined)
+                                names.add(joint.getName());
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return names;
+}
+/** Whether `rootName` or anything under it carries skin weight in what remains. */
+function subtreeIsWeighted(document, rootName, weighted) {
+    const start = document.getRoot().listNodes().find((node) => node.getName() === rootName);
+    if (start === undefined)
+        return false;
+    const stack = [start];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (weighted.has(node.getName()))
+            return true;
+        stack.push(...node.listChildren());
+    }
+    return false;
+}
+async function makeVrmCharacter(vrmPath, canonicalPath, outPath, options = {}) {
+    const mode = options.mode ?? 'conform';
+    const budget = options.budget === undefined ? exports.HERO_BUDGET : options.budget;
+    const io = new core_1.NodeIO().registerExtensions(extensions_1.ALL_EXTENSIONS);
+    const label = vrmPath.split('/').pop() ?? vrmPath;
+    const json = readGlbJson(vrmPath);
+    const boneMap = vrmBoneMap(json, label);
+    const dynamics = (0, vrmDynamics_1.convertVrmDynamics)(json);
+    const canon = (0, conform_1.extractCanonicalSkeleton)(await io.read(canonicalPath));
+    const document = await io.read(vrmPath);
+    const collapsed = collapseIdenticalSkins(document);
+    let auxiliaryJoints;
+    let unitScale = 1;
+    let renamed = {};
+    let reoriented = 0;
+    let flipped = false;
+    if (mode === 'rename') {
+        const retarget = (0, retarget_1.retargetSkeleton)(document, boneMap);
+        renamed = retarget.renamed;
+        // VRM 0.x faces +Z; 1.0 already faces −Z. The flip is baked into vertices and skeleton together.
+        flipped = json.extensions?.VRM !== undefined;
+        if (flipped)
+            bakeYawFlip(document);
+        reoriented = reorientToCanonicalRest(document, renamed, canon.worldByName, flipped ? exports.YAW_FLIP : null);
+        // Everything the map did NOT rename is auxiliary by definition — it kept its source name, which is exactly
+        // the name the spring configuration refers to.
+        const mapped = new Set(Object.keys(renamed));
+        auxiliaryJoints = [...new Set(document.getRoot().listSkins().flatMap((skin) => skin.listJoints().map((j) => j.getName())))].filter((name) => !mapped.has(name) && !Object.values(renamed).includes(name));
+    }
+    else {
+        // conform REBUILDS the skeleton on canonical frames, which already face −Z. The mesh does not move in
+        // 'embed' mode, so a VRM 0.x source would be left with a +Z mesh on a −Z rig. Flip the vertices, and flip
+        // the source skeleton it measures joint positions from — that rig is discarded during the rebuild, so
+        // rotating it costs nothing and keeps positions in the same space as the geometry.
+        flipped = json.extensions?.VRM !== undefined;
+        if (flipped) {
+            bakeYawFlip(document);
+            const sourceRoot = document.getRoot().listSkins()[0]?.getSkeleton()
+                ?? document.getRoot().listScenes()[0]?.listChildren().find((c) => c.getName() === 'Root');
+            if (sourceRoot !== undefined && sourceRoot !== null) {
+                sourceRoot.setMatrix((0, mat4_1.mul4)(exports.YAW_FLIP, sourceRoot.getMatrix()));
+            }
+        }
+        const conformed = (0, conform_1.conformToHelixRest)(document, canon, boneMap, { mode: 'embed', preserveAuxiliary: true });
+        auxiliaryJoints = conformed.auxiliaryJoints;
+        unitScale = conformed.unitScale;
+        // conform renames by rebuilding, so the collider bone names it produced are the canonical ones already.
+        renamed = Object.fromEntries(Object.entries(boneMap.map));
+    }
+    // ── CUT THE WEARABLE OUT, BEFORE ANYTHING IS DECIDED ABOUT IT ───────────────────────────────────────────
+    // Immediately after the conform and before every downstream decision, because all of them are answers about
+    // WHAT SHIPS: which spring chains have geometry to move, which surfaces the first-person camera sits inside,
+    // how many triangles and materials the budget has to reduce. Cutting later gave a pair of shoes its donor's
+    // eighteen hair chains and gave a cat-ear accessory no first-person declaration at all.
+    if (options.keepMaterials !== undefined) {
+        const selection = keepMatchingPrimitives(document, options.keepMaterials);
+        if (selection.kept === 0) {
+            throw new Error(`no material matched ${String(options.keepMaterials)} — nothing to publish`);
+        }
+    }
+    // Only chains whose root actually survived can be simulated. A chain rooted on a joint conform dropped is a
+    // chain that would silently do nothing, and silence is the failure mode this whole system is built to avoid.
+    const kept = new Set(auxiliaryJoints);
+    // AND the geometry has to be there. A wearable cut from an avatar keeps the whole skeleton, so a garment
+    // would otherwise ship its donor's hair, ear and tail chains — simulating bones that move nothing, out of a
+    // frame budget shared with everything the player is actually wearing. Measured on the first outfit cut from
+    // this avatar: 48 chains declared, 8 of them with any of the garment's weight on them.
+    // A chain's ROOT often carries no skin weight itself — it is the pivot, and the weight lives further down
+    // the strand. Filtering on the root alone dropped 30 of this avatar's 48 chains, every one of which moves
+    // geometry that is still there. The question is whether anything in the chain's SUBTREE is weighted.
+    const weighted = weightedJoints(document);
+    const afterKept = (dynamics?.chains ?? []).filter((chain) => kept.has(chain.root));
+    const chains = afterKept.filter((chain) => weighted.size === 0 || subtreeIsWeighted(document, chain.root, weighted));
+    // `VRM_DEBUG_CHAINS=1` prints what survived and what did not. Kept because the answer to "why does her hair
+    // not move" is a list of chain names, and reconstructing that list from the outside means rebuilding the
+    // whole conversion with a patch in it — which is how this filter's own two bugs were found.
+    if (process.env['VRM_DEBUG_CHAINS'] === '1') {
+        console.error(`[chains] source ${(dynamics?.chains ?? []).length} -> kept ${afterKept.length} -> weighted ${chains.length}`);
+        console.error(`  kept: ${chains.map((c) => c.root).join(', ')}`);
+        const droppedRoots = afterKept.filter((c) => !chains.includes(c)).map((c) => c.root);
+        console.error(`  dropped(${droppedRoots.length}): ${droppedRoots.join(', ')}`);
+    }
+    // Colliders hang off CANONICAL bones — head, chest, hips — and those are exactly the names that just changed.
+    // A collider still pointing at `J_Bip_C_Head` resolves to nothing and the chain silently stops colliding,
+    // which is the quiet-failure shape this system keeps trying to design out.
+    const usedColliders = new Set(chains.flatMap((chain) => chain.colliders ?? []));
+    const colliders = (dynamics?.colliders ?? [])
+        .filter((collider) => usedColliders.has(collider.id))
+        .map((collider) => ({ ...collider, bone: renamed[collider.bone] ?? collider.bone }));
+    if (chains.length > 0) {
+        for (const scene of document.getRoot().listScenes()) {
+            scene.setExtras({
+                ...scene.getExtras(),
+                helixDynamics: { contract: 'helix/dynamics@1', chains, colliders, lod: { minPixels: 14 } },
+            });
+        }
+    }
+    // ── BUDGET ──────────────────────────────────────────────────────────────────────────────────────────────────
+    // An imported avatar has to clear the SAME publish gate a first-party one does: the validator caps an avatar
+    // at 60,000 triangles and 10 MB, and the architecture's hero budget is tighter still. A stock VRoid export is
+    // ~60k triangles and 14 MB of textures before it starts, so an importer that does not decimate produces
+    // content the platform would refuse — the creator-facing failure this pipeline exists to absorb.
+    const fidelity = measureRigFidelity(document, renamed, canon.worldByName, null);
+    const trianglesBefore = (0, report_1.countTriangles)(document);
+    let trianglesAfter = trianglesBefore;
+    let texturesResized = 0;
+    let materialsBefore = document.getRoot().listMaterials().length;
+    let materialsAfter = materialsBefore;
+    if (budget !== null) {
+        texturesResized = (await (0, resizeTextures_1.resizeTextures)(document, budget.textureSize)).resized.length;
+        trianglesAfter = (await (0, simplifyMesh_1.simplifyToTarget)(document, budget.triangles, 0.02, false)).after;
+        // AFTER decimation: atlasing rewrites UVs, and a decimator that runs afterwards would weld across tile
+        // seams and pull texels from a neighbouring surface's tile.
+        const atlas = await (0, atlasMaterials_1.atlasMaterials)(document, {
+            maxMaterials: budget.maxMaterials,
+            maxEdge: budget.textureSize * 4,
+        });
+        materialsBefore = atlas.materialsBefore;
+        materialsAfter = atlas.materialsAfter;
+    }
+    // ── FACE ────────────────────────────────────────────────────────────────────────────────────────────────────
+    // AFTER the budget stage on purpose: `attachFaceManifest` verifies every declared morph still exists, so if
+    // decimation ever drops or renames a mouth shape the import fails here rather than shipping a manifest that
+    // points at nothing. A face that silently does not move is the same class of quiet failure as hair that
+    // silently does not swing, and this pipeline keeps choosing the loud version.
+    // Through the STRICT parser before it is attached. `attachFaceManifest` only proves the named morphs exist;
+    // it does not apply the contract's name rule, so a manifest could pass the build and still be refused at load
+    // — which is what happened: a mesh named `Face (merged).baked` produced a face block the runtime dropped on
+    // the floor, and the character loaded with `capability: none` and no complaint from anyone.
+    // Declared AFTER atlasing, which renames nothing but does rewrite primitives — the names are read from the
+    // final document so what ships is what the runtime will see.
+    const firstPerson = (0, firstPersonHide_1.declareFirstPersonHide)(document);
+    //
+    // A WEARABLE carries no face: its morph targets went with the head that was deleted. Skipping is right, and
+    // skipping only here keeps the avatar path's failure LOUD — an avatar whose visemes did not survive
+    // decimation must stop the build, not ship a manifest pointing at morphs that no longer exist.
+    const face = options.keepMaterials === undefined ? (0, vrmFace_1.convertVrmFace)(json) : null;
+    let faceMorphsRemoved = 0;
+    if (face !== null) {
+        const manifest = (0, faceManifest_1.parseFaceManifest)((0, vrmFace_1.faceManifestFrom)(face));
+        (0, faceManifest_1.attachFaceManifest)(document, manifest);
+        // PRUNE, and it is the single largest saving in this pipeline. A VRoid face carries 57 blend shapes and
+        // the contract can drive 13 of them — five vowels, two blinks, six expressions. The other 44 are shapes
+        // an FX layer used to reach and nothing here can: 1.24 MB of morph deltas, 30% of the whole character,
+        // paid for on every load to move nothing. Measured on the reference avatar: 4.07 -> 2.57 MB.
+        //
+        // AFTER `attachFaceManifest`, which has already proved every declared morph exists, so this can only ever
+        // remove targets the manifest does not name.
+        faceMorphsRemoved = (0, faceManifest_1.pruneUnusedFaceMorphTargets)(document, manifest).removed;
+    }
+    // Deleting primitives leaves their vertex data in the buffer — a pair of shoes cut from this avatar still
+    // weighed 9.1 MB against a 6 MB wearable cap, because it was carrying the whole body it was cut from.
+    await document.transform((0, functions_1.prune)(), (0, functions_1.dedup)());
+    await io.write(outPath, document);
+    return {
+        collapsedSkins: collapsed, auxiliaryJoints, reoriented, flipped,
+        trianglesBefore, trianglesAfter, texturesResized, fidelity,
+        chains: chains.length, colliders: colliders.length, materialsBefore, materialsAfter,
+        firstPersonHide: firstPerson.meshes,
+        faceChannels: Object.keys(face?.channels ?? {}),
+        faceExpressions: Object.keys(face?.expressions ?? {}),
+        faceMorphsRemoved,
+        warnings: [...(dynamics?.warnings ?? []), ...(face?.warnings ?? [])], unitScale,
+    };
+}
+//# sourceMappingURL=vrmCharacter.js.map