@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/character/composeBaseMale.js

@@ -0,0 +1,712 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULAR_CHARACTER_FACIAL_ROOT = exports.BASE_MALE_FACIAL_ROOT = void 0;
+exports.composeBaseMaleGlb = composeBaseMaleGlb;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const core_1 = require("@gltf-transform/core");
+const extensions_1 = require("@gltf-transform/extensions");
+const functions_1 = require("@gltf-transform/functions");
+const meshoptimizer_1 = require("meshoptimizer");
+const mat4_1 = require("./mat4");
+const canonicalSkeletonData_1 = require("./canonicalSkeletonData");
+const snapshots_1 = require("../bridge/internal/snapshots");
+const importCharacter_1 = require("./importCharacter");
+const resizeTextures_1 = require("./stages/resizeTextures");
+const ktx2_1 = require("./stages/ktx2");
+exports.BASE_MALE_FACIAL_ROOT = 'FACIAL_C_FacialRoot';
+exports.MODULAR_CHARACTER_FACIAL_ROOT = 'facial_root';
+const BASE_MALE_LODS = 3;
+function fail(message) {
+    throw new Error(`base-male composition: ${message}`);
+}
+function assert(condition, message) {
+    if (!condition)
+        fail(message);
+}
+/** Node names repeat across LOD scenes, so rig lookup must remain scene-local. */
+function nodesByName(scene) {
+    const result = new Map();
+    const visit = (node) => {
+        result.set(node.getName(), node);
+        node.listChildren().forEach(visit);
+    };
+    scene.listChildren().forEach(visit);
+    return result;
+}
+function meshNodeOf(scene) {
+    let found = null;
+    const visit = (node) => {
+        if (node.getMesh() !== null)
+            found ??= node;
+        node.listChildren().forEach(visit);
+    };
+    scene.listChildren().forEach(visit);
+    assert(found !== null, `scene ${scene.getName()} has no mesh node`);
+    return found;
+}
+function maxDelta(a, b) {
+    return Math.max(...a.map((value, index) => Math.abs(value - b[index])));
+}
+/**
+ * Ports the proven Base Male body+face merge into the canonical CLI pipeline.
+ * Each face mesh is rebound to the corresponding body LOD skin, with the one
+ * face-only root grafted beneath `head`; the duplicate face armature is then
+ * removed. Identical inputs produce identical output bytes.
+ */
+async function composeLegacyBaseMaleGlb(bodyBytes, faceBytes) {
+    await Promise.all([meshoptimizer_1.MeshoptDecoder.ready, meshoptimizer_1.MeshoptEncoder.ready]);
+    const io = new core_1.NodeIO()
+        .setLogger(new core_1.Logger(core_1.Logger.Verbosity.SILENT))
+        .registerExtensions(extensions_1.ALL_EXTENSIONS)
+        .registerDependencies({
+        'meshopt.decoder': meshoptimizer_1.MeshoptDecoder,
+        'meshopt.encoder': meshoptimizer_1.MeshoptEncoder,
+    });
+    const document = await io.readBinary(bodyBytes);
+    const faceDocument = await io.readBinary(faceBytes);
+    const expectedMaterials = new Set([
+        ...document.getRoot().listMaterials().map((material) => material.getName()),
+        ...faceDocument.getRoot().listMaterials().map((material) => material.getName()),
+    ]);
+    const bodyScenesBefore = new Set(document.getRoot().listScenes());
+    (0, functions_1.mergeDocuments)(document, faceDocument);
+    const allScenes = document.getRoot().listScenes();
+    const bodyScenes = allScenes.filter((scene) => bodyScenesBefore.has(scene));
+    const faceScenes = allScenes.filter((scene) => !bodyScenesBefore.has(scene));
+    assert(bodyScenes.length === BASE_MALE_LODS && faceScenes.length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} LOD scenes per input, got ${bodyScenes.length}/${faceScenes.length}`);
+    const originalBodyJointCounts = [];
+    for (let lod = 0; lod < BASE_MALE_LODS; lod++) {
+        const bodyScene = bodyScenes[lod];
+        const faceScene = faceScenes[lod];
+        assert(bodyScene.getName() === faceScene.getName(), `LOD ${lod} name mismatch: ${bodyScene.getName()} vs ${faceScene.getName()}`);
+        const bodyNodes = nodesByName(bodyScene);
+        const faceNodes = nodesByName(faceScene);
+        const bodyMeshNode = meshNodeOf(bodyScene);
+        const faceMeshNode = meshNodeOf(faceScene);
+        const bodyMesh = bodyMeshNode.getMesh();
+        const faceMesh = faceMeshNode.getMesh();
+        const bodySkin = bodyMeshNode.getSkin();
+        const faceSkin = faceMeshNode.getSkin();
+        assert(bodyMesh !== null && faceMesh !== null, `LOD ${lod} missing a mesh`);
+        assert(bodySkin !== null && faceSkin !== null, `LOD ${lod} missing a skin`);
+        const bodyJoints = bodySkin.listJoints();
+        const faceJoints = faceSkin.listJoints();
+        const bodyIBM = bodySkin.getInverseBindMatrices();
+        const faceIBM = faceSkin.getInverseBindMatrices();
+        assert(bodyIBM !== null && faceIBM !== null, `LOD ${lod} missing inverse bind matrices`);
+        originalBodyJointCounts.push(bodyJoints.length);
+        const bodyJointIndex = new Map(bodyJoints.map((joint, index) => [joint.getName(), index]));
+        assert(!bodyJointIndex.has(exports.BASE_MALE_FACIAL_ROOT), `LOD ${lod} body skin already contains ${exports.BASE_MALE_FACIAL_ROOT}`);
+        const exclusiveFaceJoints = faceJoints.filter((joint) => !bodyJointIndex.has(joint.getName()));
+        assert(exclusiveFaceJoints.length === 1 &&
+            exclusiveFaceJoints[0].getName() === exports.BASE_MALE_FACIAL_ROOT, `LOD ${lod} face-exclusive joints must be exactly ${exports.BASE_MALE_FACIAL_ROOT}; got ` +
+            `[${exclusiveFaceJoints.map((joint) => joint.getName()).join(', ')}]`);
+        const scratchA = new Array(16);
+        const scratchB = new Array(16);
+        for (let faceIndex = 0; faceIndex < faceJoints.length; faceIndex++) {
+            const name = faceJoints[faceIndex].getName();
+            if (name === exports.BASE_MALE_FACIAL_ROOT)
+                continue;
+            const bodyIndex = bodyJointIndex.get(name);
+            assert(bodyIndex !== undefined, `face joint "${name}" has no body counterpart`);
+            faceIBM.getElement(faceIndex, scratchA);
+            bodyIBM.getElement(bodyIndex, scratchB);
+            const inverseBindDelta = maxDelta(scratchA, scratchB);
+            assert(inverseBindDelta < 1e-4, `inverse bind matrix for "${name}" differs between body and face (${inverseBindDelta})`);
+            const faceNode = faceNodes.get(name);
+            const bodyNode = bodyNodes.get(name);
+            assert(faceNode !== undefined && bodyNode !== undefined, `LOD ${lod} cannot resolve joint "${name}"`);
+            const positionDelta = maxDelta(faceNode.getWorldTranslation(), bodyNode.getWorldTranslation());
+            assert(positionDelta < 1e-4, `bind-pose world position for "${name}" differs (${positionDelta})`);
+        }
+        const faceRootSource = faceNodes.get(exports.BASE_MALE_FACIAL_ROOT);
+        assert(faceRootSource !== undefined, `LOD ${lod} face has no ${exports.BASE_MALE_FACIAL_ROOT}`);
+        assert(faceRootSource.listChildren().length === 0, `${exports.BASE_MALE_FACIAL_ROOT} is not a leaf`);
+        const facialParentName = faceRootSource.getParentNode()?.getName();
+        assert(facialParentName !== undefined, `${exports.BASE_MALE_FACIAL_ROOT} has no parent`);
+        const facialParent = bodyNodes.get(facialParentName);
+        assert(facialParent !== undefined, `${exports.BASE_MALE_FACIAL_ROOT}'s parent "${facialParentName}" is missing from the body skeleton`);
+        const facialRoot = document
+            .createNode(exports.BASE_MALE_FACIAL_ROOT)
+            .setTranslation(faceRootSource.getTranslation())
+            .setRotation(faceRootSource.getRotation())
+            .setScale(faceRootSource.getScale());
+        facialParent.addChild(facialRoot);
+        const facialRootIndex = faceJoints.findIndex((joint) => joint.getName() === exports.BASE_MALE_FACIAL_ROOT);
+        assert(facialRootIndex >= 0, `LOD ${lod} face skin does not use ${exports.BASE_MALE_FACIAL_ROOT}`);
+        const mergedInverseBinds = new Float32Array((bodyJoints.length + 1) * 16);
+        for (let bodyIndex = 0; bodyIndex < bodyJoints.length; bodyIndex++) {
+            bodyIBM.getElement(bodyIndex, scratchA);
+            mergedInverseBinds.set(scratchA, bodyIndex * 16);
+        }
+        faceIBM.getElement(facialRootIndex, scratchA);
+        mergedInverseBinds.set(scratchA, bodyJoints.length * 16);
+        const newIBM = document
+            .createAccessor(`${bodySkin.getName()}_ibm`)
+            .setType('MAT4')
+            .setArray(mergedInverseBinds)
+            .setBuffer(bodyIBM.getBuffer());
+        bodySkin.addJoint(facialRoot).setInverseBindMatrices(newIBM);
+        bodyIBM.dispose();
+        const remap = faceJoints.map((joint) => joint.getName() === exports.BASE_MALE_FACIAL_ROOT
+            ? bodyJoints.length
+            : bodyJointIndex.get(joint.getName()));
+        const jointElement = [0, 0, 0, 0];
+        for (const primitive of faceMesh.listPrimitives()) {
+            const joints = primitive.getAttribute('JOINTS_0');
+            assert(joints !== null, `LOD ${lod} face primitive has no JOINTS_0`);
+            assert(primitive.getAttribute('JOINTS_1') === null, `LOD ${lod} face primitive uses more than four joint influences`);
+            for (let vertex = 0; vertex < joints.getCount(); vertex++) {
+                joints.getElement(vertex, jointElement);
+                for (let influence = 0; influence < jointElement.length; influence++) {
+                    const sourceIndex = jointElement[influence];
+                    const mapped = remap[sourceIndex];
+                    assert(mapped !== undefined, `face vertex references unknown joint index ${sourceIndex}`);
+                    jointElement[influence] = mapped;
+                }
+                joints.setElement(vertex, jointElement);
+            }
+        }
+        const lodRoot = bodyMeshNode.getParentNode() ?? bodyMeshNode;
+        const faceNode = document
+            .createNode('FaceMesh')
+            .setMesh(faceMesh)
+            .setSkin(bodySkin)
+            .setTranslation(faceMeshNode.getTranslation())
+            .setRotation(faceMeshNode.getRotation())
+            .setScale(faceMeshNode.getScale());
+        if (lodRoot === bodyMeshNode)
+            bodyMeshNode.addChild(faceNode);
+        else
+            lodRoot.addChild(faceNode);
+    }
+    for (const scene of faceScenes) {
+        const doomed = [];
+        const visit = (node) => {
+            doomed.push(node);
+            node.listChildren().forEach(visit);
+        };
+        scene.listChildren().forEach(visit);
+        scene.dispose();
+        doomed.forEach((node) => node.dispose());
+    }
+    for (const skin of document.getRoot().listSkins()) {
+        if (skin.listJoints().length === 0)
+            skin.dispose();
+    }
+    await document.transform((0, functions_1.prune)());
+    const buffers = document.getRoot().listBuffers();
+    const primaryBuffer = buffers[0];
+    assert(primaryBuffer !== undefined, 'merged document has no binary buffer');
+    document.getRoot().listAccessors().forEach((accessor) => accessor.setBuffer(primaryBuffer));
+    buffers.slice(1).forEach((buffer) => buffer.dispose());
+    const root = document.getRoot();
+    const meshes = root.listMeshes().map((mesh) => mesh.getName());
+    const materials = root.listMaterials().map((material) => material.getName());
+    const skins = root.listSkins();
+    const nodes = root.listNodes();
+    const fingerBones = nodes.filter((node) => /^(thumb|index|middle|ring|pinky)_/.test(node.getName())).length;
+    assert(meshes.filter((name) => name.includes('BodyMesh')).length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} body meshes, got [${meshes.join(', ')}]`);
+    assert(meshes.filter((name) => name.includes('FaceMesh')).length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} face meshes, got [${meshes.join(', ')}]`);
+    assert(skins.length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} skins, got ${skins.length}`);
+    assert(skins.every((skin, index) => skin.listJoints().length === originalBodyJointCounts[index] + 1), `each skin must add exactly one facial joint; got [${skins.map((skin) => skin.listJoints().length).join(', ')}]`);
+    assert(nodes.filter((node) => node.getName() === exports.BASE_MALE_FACIAL_ROOT).length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} ${exports.BASE_MALE_FACIAL_ROOT} nodes`);
+    for (const material of expectedMaterials) {
+        assert(materials.includes(material), `material ${material} was lost during composition`);
+    }
+    const bytes = await io.writeBinary(document);
+    return {
+        bytes,
+        report: {
+            bytes: bytes.length,
+            sha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex'),
+            scenes: root.listScenes().map((scene) => scene.getName()),
+            meshes,
+            materials,
+            skins: skins.length,
+            jointsPerSkin: skins.map((skin) => skin.listJoints().length),
+            nodes: nodes.length,
+            fingerBones,
+        },
+    };
+}
+function semanticParent(node, jointNames) {
+    const seen = new Set([node]);
+    let parent = node.getParentNode() ?? undefined;
+    while (parent !== undefined) {
+        assert(!seen.has(parent), `joint hierarchy contains a cycle at "${node.getName()}"`);
+        seen.add(parent);
+        if (parent.getName() !== node.getName() && jointNames.has(parent.getName()))
+            return parent;
+        parent = parent.getParentNode() ?? undefined;
+    }
+    return undefined;
+}
+function uniqueJointsByName(joints, label) {
+    const result = new Map();
+    for (const joint of joints) {
+        const name = joint.getName();
+        assert(name.length > 0, `${label} contains an unnamed joint`);
+        assert(!result.has(name), `${label} contains duplicate joint name "${name}"`);
+        result.set(name, joint);
+    }
+    return result;
+}
+function modularLods(scene, label) {
+    const lods = new Map();
+    const visit = (node) => {
+        if (node.getMesh() !== null) {
+            assert(node.getSkin() !== null, `${label} mesh node "${node.getName()}" has no skin`);
+            const match = /_LOD(\d+)$/i.exec(node.getName());
+            assert(match !== null, `${label} mesh node "${node.getName()}" has no unambiguous _LODn suffix`);
+            const index = Number(match[1]);
+            assert(!lods.has(index), `${label} contains multiple mesh nodes for LOD${index}`);
+            lods.set(index, node);
+        }
+        node.listChildren().forEach(visit);
+    };
+    scene.listChildren().forEach(visit);
+    return [...lods.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([index, meshNode]) => ({ index, meshNode }));
+}
+function oneSkinnedMeshNode(scene, label) {
+    const nodes = [];
+    scene.traverse((node) => {
+        if (node.getMesh() !== null && node.getSkin() !== null)
+            nodes.push(node);
+    });
+    assert(nodes.length === 1, `${label} must contain exactly one skinned mesh node; found ${nodes.length}`);
+    return nodes[0];
+}
+function assertValidBindMatrices(joints, inverseBinds, meshNode, label) {
+    const matrix = new Array(16);
+    const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+    const inverseMeshWorld = (0, mat4_1.invert4)(meshNode.getWorldMatrix());
+    for (let index = 0; index < joints.length; index++) {
+        inverseBinds.getElement(index, matrix);
+        const delta = maxDelta((0, mat4_1.mul4)(inverseMeshWorld, (0, mat4_1.mul4)(joints[index].getWorldMatrix(), matrix)), identity);
+        assert(delta < 1e-3, `${label} joint "${joints[index].getName()}" has an invalid bind matrix (${delta})`);
+    }
+}
+function copyNodeMatrixInParentSpace(source, semanticParentSource) {
+    const world = source.getWorldMatrix();
+    return semanticParentSource === undefined
+        ? [...world]
+        : (0, mat4_1.mul4)((0, mat4_1.invert4)(semanticParentSource.getWorldMatrix()), world);
+}
+const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function transformVector(matrix, vector) {
+    return [
+        matrix[0] * vector[0] + matrix[4] * vector[1] + matrix[8] * vector[2],
+        matrix[1] * vector[0] + matrix[5] * vector[1] + matrix[9] * vector[2],
+        matrix[2] * vector[0] + matrix[6] * vector[1] + matrix[10] * vector[2],
+    ];
+}
+function transformNormal(matrix, vector) {
+    const inverse = (0, mat4_1.invert4)(matrix);
+    return [
+        inverse[0] * vector[0] + inverse[1] * vector[1] + inverse[2] * vector[2],
+        inverse[4] * vector[0] + inverse[5] * vector[1] + inverse[6] * vector[2],
+        inverse[8] * vector[0] + inverse[9] * vector[1] + inverse[10] * vector[2],
+    ];
+}
+function normalized(vector) {
+    const length = Math.hypot(vector[0], vector[1], vector[2]) || 1;
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+/** Moves a selected mesh into the canonical scene's identity space. Accessors are cloned before
+ * mutation because Unreal LODs may share buffers or attributes. Morph values are deltas, so their
+ * POSITION/NORMAL transforms intentionally omit translation and normalization. */
+function bakeMeshWorldTransform(meshNode, matrix) {
+    const mesh = meshNode.getMesh();
+    assert(mesh !== null, `mesh node "${meshNode.getName()}" has no mesh`);
+    const transformed = new Map();
+    const transformAccessor = (accessor, semantic, morph) => {
+        const key = `${morph ? 'morph' : 'base'}:${semantic}`;
+        const bySource = transformed.get(key) ?? new Map();
+        transformed.set(key, bySource);
+        const existing = bySource.get(accessor);
+        if (existing !== undefined)
+            return existing;
+        const result = accessor.clone();
+        const value = [0, 0, 0, 0];
+        for (let index = 0; index < result.getCount(); index++) {
+            result.getElement(index, value);
+            let xyz;
+            if (semantic === 'POSITION') {
+                const position = [value[0], value[1], value[2]];
+                xyz = morph ? transformVector(matrix, position) : (0, mat4_1.transformPoint)(matrix, position);
+            }
+            else if (semantic === 'NORMAL')
+                xyz = transformNormal(matrix, value);
+            else
+                xyz = transformVector(matrix, value);
+            if (!morph && semantic !== 'POSITION')
+                xyz = normalized(xyz);
+            result.setElement(index, semantic === 'TANGENT' ? [xyz[0], xyz[1], xyz[2], value[3]] : xyz);
+        }
+        bySource.set(accessor, result);
+        return result;
+    };
+    for (const primitive of mesh.listPrimitives()) {
+        for (const semantic of ['POSITION', 'NORMAL', 'TANGENT']) {
+            const accessor = primitive.getAttribute(semantic);
+            if (accessor !== null)
+                primitive.setAttribute(semantic, transformAccessor(accessor, semantic, false));
+        }
+        for (const target of primitive.listTargets()) {
+            for (const semantic of ['POSITION', 'NORMAL', 'TANGENT']) {
+                const accessor = target.getAttribute(semantic);
+                if (accessor !== null)
+                    target.setAttribute(semantic, transformAccessor(accessor, semantic, true));
+            }
+        }
+    }
+}
+function bindAlignment(bodyByName, headByName) {
+    const anchors = ['pelvis', 'head', 'clavicle_l', 'clavicle_r'];
+    const pairs = anchors.map((name) => ({
+        body: bodyByName.get(name)?.getWorldTranslation(),
+        head: headByName.get(name)?.getWorldTranslation(),
+    }));
+    const available = pairs.filter((pair) => pair.body !== undefined && pair.head !== undefined);
+    const alreadyAligned = available.length > 0 && available.every(({ body, head }) => Math.max(...body.map((value, index) => Math.abs(value - head[index]))) < 1e-3);
+    if (alreadyAligned)
+        return IDENTITY_MATRIX;
+    assert(available.length === anchors.length, 'body/head axis alignment requires pelvis, head, clavicle_l, and clavicle_r');
+    const frame = (points) => {
+        const [pelvis, head, left, right] = points;
+        const y = (0, mat4_1.normalize3)((0, mat4_1.sub3)(head, pelvis));
+        const shoulder = (0, mat4_1.normalize3)((0, mat4_1.sub3)(right, left));
+        const z = (0, mat4_1.normalize3)((0, mat4_1.cross3)(shoulder, y));
+        assert(Math.hypot(...z) > 0.99, 'body/head axis alignment anchors are degenerate');
+        const x = (0, mat4_1.normalize3)((0, mat4_1.cross3)(y, z));
+        return [x[0], x[1], x[2], 0, y[0], y[1], y[2], 0, z[0], z[1], z[2], 0, pelvis[0], pelvis[1], pelvis[2], 1];
+    };
+    const bodyPoints = available.map(({ body }) => body);
+    const headPoints = available.map(({ head }) => head);
+    const bodyHeight = Math.hypot(...(0, mat4_1.sub3)(bodyPoints[1], bodyPoints[0]));
+    const headHeight = Math.hypot(...(0, mat4_1.sub3)(headPoints[1], headPoints[0]));
+    assert(bodyHeight > 1e-6 && headHeight > 1e-6, 'body/head axis alignment has zero-height anchors');
+    const scale = bodyHeight / headHeight;
+    const scaleMatrix = [scale, 0, 0, 0, 0, scale, 0, 0, 0, 0, scale, 0, 0, 0, 0, 1];
+    return (0, mat4_1.mul4)(frame(bodyPoints), (0, mat4_1.mul4)(scaleMatrix, (0, mat4_1.invert4)(frame(headPoints))));
+}
+function copyMeshNode(document, source, name, skin, worldMatrix = source.getWorldMatrix()) {
+    const mesh = source.getMesh();
+    assert(mesh !== null, `${name} source has no mesh`);
+    return document
+        .createNode(name)
+        .setMatrix([...worldMatrix])
+        .setMesh(mesh)
+        .setSkin(skin)
+        .setWeights(source.getWeights())
+        .setExtras({ ...source.getExtras() });
+}
+function remapFaceJointAttributes(document, meshNode, remap, lod) {
+    const mesh = meshNode.getMesh();
+    assert(mesh !== null, `LOD ${lod} head node has no mesh`);
+    const scratch = [0, 0, 0, 0];
+    for (const primitive of mesh.listPrimitives()) {
+        for (const semantic of ['JOINTS_0', 'JOINTS_1']) {
+            const joints = primitive.getAttribute(semantic);
+            if (joints === null) {
+                if (semantic === 'JOINTS_0')
+                    fail(`LOD ${lod} head primitive has no JOINTS_0`);
+                continue;
+            }
+            const elementSize = joints.getElementSize();
+            const remapped = new Uint16Array(joints.getCount() * elementSize);
+            for (let vertex = 0; vertex < joints.getCount(); vertex++) {
+                joints.getElement(vertex, scratch);
+                for (let influence = 0; influence < elementSize; influence++) {
+                    const sourceIndex = scratch[influence];
+                    const mapped = remap[sourceIndex];
+                    assert(mapped !== undefined, `LOD ${lod} head vertex references unknown joint index ${sourceIndex}`);
+                    remapped[vertex * elementSize + influence] = mapped;
+                }
+            }
+            primitive.setAttribute(semantic, document.createAccessor(joints.getName())
+                .setType(joints.getType())
+                .setArray(remapped)
+                .setNormalized(joints.getNormalized())
+                .setBuffer(joints.getBuffer())
+                .setExtras({ ...joints.getExtras() }));
+        }
+    }
+}
+async function composeModularCharacterGlb(bodyBytes, headBytes) {
+    await meshoptimizer_1.MeshoptDecoder.ready;
+    const io = new core_1.NodeIO()
+        .setLogger(new core_1.Logger(core_1.Logger.Verbosity.SILENT))
+        .registerExtensions(extensions_1.ALL_EXTENSIONS)
+        .registerDependencies({
+        'meshopt.decoder': meshoptimizer_1.MeshoptDecoder,
+        'meshopt.encoder': meshoptimizer_1.MeshoptEncoder,
+    });
+    const document = await io.readBinary(bodyBytes);
+    const headDocument = await io.readBinary(headBytes);
+    const bodyScenes = document.getRoot().listScenes();
+    const headScene = headDocument.getRoot().listScenes()[0];
+    assert(bodyScenes.map((scene) => scene.getName()).join(',') === 'lod1,lod2,lod3', `canonical body scenes must be [lod1, lod2, lod3]; found [${bodyScenes.map((scene) => scene.getName()).join(', ')}]`);
+    const bodyLods = bodyScenes.map((scene, index) => ({
+        index,
+        meshNode: oneSkinnedMeshNode(scene, `body ${scene.getName()}`),
+    }));
+    const sourceHeadLods = modularLods(headScene, 'head');
+    assert(sourceHeadLods.length >= BASE_MALE_LODS, `head must provide at least ${BASE_MALE_LODS} LODs`);
+    const bakedEyes = headDocument.getRoot().listMaterials().filter((material) => /^MI_Eye[LR]_Baked$/i.test(material.getName()));
+    const genericEyes = headDocument.getRoot().listMaterials().filter((material) => /^MI_Eye_Instance$/i.test(material.getName()));
+    const primaryEyes = bakedEyes.length > 0 ? bakedEyes : genericEyes;
+    assert((bakedEyes.length === 2 && new Set(bakedEyes.map((material) => material.getName().toLowerCase())).size === 2) ||
+        (bakedEyes.length === 0 && genericEyes.length === 1), `head must contain either MI_EyeL_Baked + MI_EyeR_Baked or one MI_Eye_Instance material`);
+    if (primaryEyes.some((material) => material.getBaseColorTexture() === null)) {
+        const eyePng = await (0, promises_1.readFile)((0, snapshots_1.defaultMetaHumanEyeTexture)());
+        const eyeTexture = headDocument.createTexture('MI_Eye_Baked_BC')
+            .setImage(new Uint8Array(eyePng))
+            .setMimeType('image/png');
+        for (const primaryEye of primaryEyes) {
+            if (primaryEye.getBaseColorTexture() === null)
+                primaryEye.setBaseColorTexture(eyeTexture);
+        }
+    }
+    for (const primaryEye of primaryEyes) {
+        primaryEye
+            .setBaseColorFactor([1, 1, 1, 1])
+            .setMetallicFactor(0)
+            .setRoughnessFactor(0.25);
+    }
+    // The body importer already enforces the web texture budget. Apply the same
+    // 1024px ceiling to the separately prepared modular head before documents
+    // are merged; this covers skin, teeth, and normal maps without touching the
+    // body's existing KTX2 payloads.
+    await (0, resizeTextures_1.resizeTextures)(headDocument, 1024);
+    const sourceNodes = [...document.getRoot().listNodes()];
+    const sourceScenes = [...document.getRoot().listScenes()];
+    const sourceSkins = [...document.getRoot().listSkins()];
+    (0, functions_1.mergeDocuments)(document, headDocument);
+    sourceNodes.push(...document.getRoot().listNodes().filter((node) => !sourceNodes.includes(node)));
+    sourceScenes.push(...document.getRoot().listScenes().filter((scene) => !sourceScenes.includes(scene)));
+    sourceSkins.push(...document.getRoot().listSkins().filter((skin) => !sourceSkins.includes(skin)));
+    const mergedHeadScene = document.getRoot().listScenes().find((scene) => !bodyScenes.includes(scene));
+    assert(mergedHeadScene !== undefined, 'merged document has no modular head scene');
+    const headLods = modularLods(mergedHeadScene, 'head');
+    const bodyJointCounts = [];
+    const selectedBodyMeshes = [];
+    const selectedHeadMeshes = [];
+    for (let outputLod = 0; outputLod < BASE_MALE_LODS; outputLod++) {
+        const bodyLod = bodyLods[outputLod];
+        const headLod = headLods[outputLod];
+        const bodySourceSkin = bodyLod.meshNode.getSkin();
+        const headSourceSkin = headLod.meshNode.getSkin();
+        assert(bodySourceSkin !== null && headSourceSkin !== null, `LOD ${bodyLod.index} is missing a skin`);
+        const bodyIBM = bodySourceSkin.getInverseBindMatrices();
+        const headIBM = headSourceSkin.getInverseBindMatrices();
+        assert(bodyIBM !== null && headIBM !== null, `LOD ${bodyLod.index} is missing inverse bind matrices`);
+        const bodyJoints = bodySourceSkin.listJoints();
+        const headJoints = headSourceSkin.listJoints();
+        assert(bodyIBM.getCount() === bodyJoints.length, `LOD ${bodyLod.index} body IBM count does not match its joints`);
+        assert(headIBM.getCount() === headJoints.length, `LOD ${headLod.index} head IBM count does not match its joints`);
+        const bodyByName = uniqueJointsByName(bodyJoints, `LOD ${bodyLod.index} body skin`);
+        const headByName = uniqueJointsByName(headJoints, `LOD ${headLod.index} head skin`);
+        assert(bodyJoints.map((joint) => joint.getName()).join(',') === canonicalSkeletonData_1.CANONICAL_JOINT_NAMES.join(','), `LOD ${bodyLod.index} body skin is not helix-humanoid@1`);
+        assertValidBindMatrices(bodyJoints, bodyIBM, bodyLod.meshNode, `LOD ${bodyLod.index} body skin`);
+        assertValidBindMatrices(headJoints, headIBM, headLod.meshNode, `LOD ${headLod.index} head skin`);
+        const bodyNames = new Set(bodyByName.keys());
+        const headNames = new Set(headByName.keys());
+        const bodyParents = new Map(bodyJoints.map((joint) => [joint.getName(), semanticParent(joint, bodyNames)?.getName()]));
+        const headParents = new Map(headJoints.map((joint) => [joint.getName(), semanticParent(joint, headNames)?.getName()]));
+        const headToBody = bindAlignment(bodyByName, headByName);
+        const sharedNames = headJoints.map((joint) => joint.getName()).filter((name) => bodyNames.has(name));
+        assert(sharedNames.length > 0, `LOD ${bodyLod.index} body/head skins have no shared joints`);
+        const scratchA = new Array(16);
+        const bodyIndex = new Map(bodyJoints.map((joint, index) => [joint.getName(), index]));
+        for (const name of sharedNames) {
+            let mappedParent = headParents.get(name);
+            while (mappedParent !== undefined && !bodyNames.has(mappedParent))
+                mappedParent = headParents.get(mappedParent);
+            assert(bodyParents.get(name) === mappedParent, `LOD ${bodyLod.index} shared joint "${name}" parent differs: ` +
+                `${bodyParents.get(name) ?? '<root>'} vs ${mappedParent ?? '<root>'}`);
+            // Canonical embed intentionally changes joint orientations/IBMs while preserving the
+            // authored bind positions. Position compatibility is the cross-rig invariant here; each
+            // skin's full IBM was independently validated above.
+            if (name !== 'root') {
+                const positionDelta = maxDelta(bodyByName.get(name).getWorldTranslation(), (0, mat4_1.transformPoint)(headToBody, headByName.get(name).getWorldTranslation()));
+                assert(positionDelta < 1e-2, `LOD ${bodyLod.index} aligned bind position for "${name}" differs (${positionDelta})`);
+            }
+        }
+        assert(headByName.has(exports.MODULAR_CHARACTER_FACIAL_ROOT), `LOD ${bodyLod.index} head has no ${exports.MODULAR_CHARACTER_FACIAL_ROOT}`);
+        assert(headParents.get(exports.MODULAR_CHARACTER_FACIAL_ROOT) === 'head', `LOD ${bodyLod.index} ${exports.MODULAR_CHARACTER_FACIAL_ROOT} must be parented to "head"`);
+        const reachesFacialRoot = (joint) => {
+            const seen = new Set();
+            let name = joint.getName();
+            while (name !== undefined) {
+                if (name === exports.MODULAR_CHARACTER_FACIAL_ROOT)
+                    return true;
+                assert(!seen.has(name), `LOD ${bodyLod.index} head hierarchy is cyclic`);
+                seen.add(name);
+                name = headParents.get(name);
+            }
+            return false;
+        };
+        const facialJoints = headJoints.filter(reachesFacialRoot);
+        const facialNames = new Set(facialJoints.map((joint) => joint.getName()));
+        assert(facialJoints.length > 1 && facialJoints[0].getName() === exports.MODULAR_CHARACTER_FACIAL_ROOT, `LOD ${bodyLod.index} head facial subtree is empty or ambiguous`);
+        for (const joint of facialJoints.slice(1)) {
+            const parent = headParents.get(joint.getName());
+            assert(parent !== undefined && facialNames.has(parent), `LOD ${bodyLod.index} facial joint "${joint.getName()}" is disconnected`);
+        }
+        const mappedHeadTarget = (joint) => {
+            let name = joint.getName();
+            const seen = new Set();
+            while (name !== undefined) {
+                assert(!seen.has(name), `LOD ${bodyLod.index} head hierarchy is cyclic at "${name}"`);
+                seen.add(name);
+                if (bodyNames.has(name))
+                    return name;
+                name = headParents.get(name);
+            }
+            fail(`LOD ${bodyLod.index} non-facial head joint "${joint.getName()}" has no canonical ancestor`);
+        };
+        headJoints.filter((joint) => !facialNames.has(joint.getName())).forEach(mappedHeadTarget);
+        const outputScene = document.createScene(`lod${outputLod + 1}`);
+        const clonedByName = new Map();
+        for (const source of bodyJoints) {
+            const parentName = bodyParents.get(source.getName());
+            const parentSource = parentName === undefined ? undefined : bodyByName.get(parentName);
+            clonedByName.set(source.getName(), document.createNode(source.getName())
+                .setMatrix(copyNodeMatrixInParentSpace(source, parentSource))
+                .setExtras({ ...source.getExtras() }));
+        }
+        for (const source of facialJoints) {
+            const parentName = headParents.get(source.getName());
+            const desiredWorld = (0, mat4_1.mul4)(headToBody, source.getWorldMatrix());
+            const bodyParent = parentName === undefined ? undefined : bodyByName.get(parentName);
+            const headParent = parentName === undefined ? undefined : headByName.get(parentName);
+            const desiredParentWorld = bodyParent?.getWorldMatrix() ??
+                (headParent === undefined ? undefined : (0, mat4_1.mul4)(headToBody, headParent.getWorldMatrix()));
+            clonedByName.set(source.getName(), document.createNode(source.getName())
+                .setMatrix((desiredParentWorld === undefined
+                ? desiredWorld
+                : (0, mat4_1.mul4)((0, mat4_1.invert4)(desiredParentWorld), desiredWorld)))
+                .setExtras({ ...source.getExtras() }));
+        }
+        for (const source of [...bodyJoints, ...facialJoints]) {
+            const parents = bodyNames.has(source.getName()) ? bodyParents : headParents;
+            const parentName = parents.get(source.getName());
+            const clone = clonedByName.get(source.getName());
+            if (parentName === undefined)
+                outputScene.addChild(clone);
+            else {
+                const parent = clonedByName.get(parentName);
+                assert(parent !== undefined, `LOD ${bodyLod.index} cannot clone parent "${parentName}"`);
+                parent.addChild(clone);
+            }
+        }
+        const combinedJoints = [...bodyJoints, ...facialJoints].map((joint) => clonedByName.get(joint.getName()));
+        const mergedInverseBinds = new Float32Array(combinedJoints.length * 16);
+        combinedJoints.forEach((joint, index) => mergedInverseBinds.set((0, mat4_1.invert4)(joint.getWorldMatrix()), index * 16));
+        const mergedIBM = document.createAccessor(`character-skin-${outputLod}-ibm`)
+            .setType('MAT4')
+            .setArray(mergedInverseBinds)
+            .setBuffer(bodyIBM.getBuffer());
+        const mergedSkin = document.createSkin(`character-skin-${outputLod}`)
+            .setInverseBindMatrices(mergedIBM)
+            .setSkeleton(clonedByName.get(bodySourceSkin.getSkeleton()?.getName() ?? 'root') ?? null);
+        combinedJoints.forEach((joint) => mergedSkin.addJoint(joint));
+        const faceRemap = headJoints.map((joint) => {
+            const facialIndex = facialJoints.indexOf(joint);
+            if (facialIndex >= 0)
+                return bodyJoints.length + facialIndex;
+            return bodyIndex.get(mappedHeadTarget(joint));
+        });
+        remapFaceJointAttributes(document, headLod.meshNode, faceRemap, bodyLod.index);
+        const bodyMesh = bodyLod.meshNode.getMesh();
+        const headMesh = headLod.meshNode.getMesh();
+        bakeMeshWorldTransform(bodyLod.meshNode, bodyLod.meshNode.getWorldMatrix());
+        bakeMeshWorldTransform(headLod.meshNode, (0, mat4_1.mul4)(headToBody, headLod.meshNode.getWorldMatrix()));
+        bodyMesh.setName(`BodyMesh_LOD${outputLod}`);
+        headMesh.setName(`FaceMesh_LOD${outputLod}`);
+        selectedBodyMeshes.push(bodyMesh.getName());
+        selectedHeadMeshes.push(headMesh.getName());
+        outputScene.addChild(copyMeshNode(document, bodyLod.meshNode, 'BodyMesh', mergedSkin, IDENTITY_MATRIX));
+        outputScene.addChild(copyMeshNode(document, headLod.meshNode, 'FaceMesh', mergedSkin, IDENTITY_MATRIX));
+        bodyJointCounts.push(bodyJoints.length);
+    }
+    sourceScenes.forEach((scene) => scene.dispose());
+    sourceNodes.forEach((node) => node.dispose());
+    sourceSkins.forEach((skin) => skin.dispose());
+    await document.transform((0, functions_1.prune)());
+    const buffers = document.getRoot().listBuffers();
+    const primaryBuffer = buffers[0];
+    assert(primaryBuffer !== undefined, 'merged document has no binary buffer');
+    document.getRoot().listAccessors().forEach((accessor) => accessor.setBuffer(primaryBuffer));
+    buffers.slice(1).forEach((buffer) => buffer.dispose());
+    const root = document.getRoot();
+    const scenes = root.listScenes();
+    const meshes = root.listMeshes().map((mesh) => mesh.getName());
+    const materials = root.listMaterials().map((material) => material.getName());
+    const skins = root.listSkins();
+    const nodes = root.listNodes();
+    assert(scenes.length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} output LOD scenes`);
+    assert(selectedBodyMeshes.every((name) => meshes.includes(name)), 'a selected body mesh was lost during composition');
+    assert(selectedHeadMeshes.every((name) => meshes.includes(name)), 'a selected head mesh was lost during composition');
+    assert(skins.length === BASE_MALE_LODS, `expected ${BASE_MALE_LODS} output skins, got ${skins.length}`);
+    assert(skins.every((skin, index) => skin.listJoints().length > bodyJointCounts[index]), `each output skin must include the connected facial subtree`);
+    (0, importCharacter_1.assertCanonicalCharacterGeometry)(document, 'character');
+    const reportBeforeCompression = {
+        scenes: scenes.map((scene) => scene.getName()),
+        meshes,
+        materials,
+        skins: skins.length,
+        jointsPerSkin: skins.map((skin) => skin.listJoints().length),
+        nodes: nodes.length,
+        fingerBones: nodes.filter((node) => /^(thumb|index|middle|ring|pinky)_/.test(node.getName())).length,
+    };
+    // The body import has already encoded its textures. Finish the separately
+    // prepared face document here so the combined web package never mixes PNG
+    // face/eye payloads with KTX2 body payloads.
+    await (0, ktx2_1.encodeKtx2)(document, { mode: 'uastc' });
+    // Customizer heads can carry dozens of morph targets on each LOD. Preserve
+    // every target, but quantize and compress their accessor payload for the web
+    // package instead of shipping the exporter's very large raw float arrays.
+    await meshoptimizer_1.MeshoptEncoder.ready;
+    await document.transform((0, functions_1.meshopt)({ encoder: meshoptimizer_1.MeshoptEncoder, level: 'high' }));
+    const bytes = await io.writeBinary(document);
+    return {
+        bytes,
+        report: {
+            bytes: bytes.length,
+            sha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex'),
+            ...reportBeforeCompression,
+        },
+    };
+}
+/**
+ * Composes either the published HELIX Base Male's pre-split LOD inputs or a
+ * canonical HELIX body with a modular Unreal head containing `_LODn` meshes.
+ * Callers must import a raw modular body through the character pipeline first.
+ * The legacy route is deliberately unchanged to keep its canonical output
+ * byte-for-byte stable.
+ */
+async function composeBaseMaleGlb(bodyBytes, faceBytes) {
+    await meshoptimizer_1.MeshoptDecoder.ready;
+    const io = new core_1.NodeIO()
+        .setLogger(new core_1.Logger(core_1.Logger.Verbosity.SILENT))
+        .registerExtensions(extensions_1.ALL_EXTENSIONS)
+        .registerDependencies({ 'meshopt.decoder': meshoptimizer_1.MeshoptDecoder });
+    const [body, face] = await Promise.all([
+        io.readBinary(bodyBytes.slice()),
+        io.readBinary(faceBytes.slice()),
+    ]);
+    const shape = [body.getRoot().listScenes().length, face.getRoot().listScenes().length];
+    if (shape[0] === BASE_MALE_LODS && shape[1] === BASE_MALE_LODS) {
+        return composeLegacyBaseMaleGlb(bodyBytes, faceBytes);
+    }
+    assert(shape[0] === BASE_MALE_LODS && shape[1] === 1, `inputs must use either ${BASE_MALE_LODS}/${BASE_MALE_LODS} pre-split scenes or a ` +
+        `${BASE_MALE_LODS}-scene canonical body plus one modular head scene; got ${shape[0]}/${shape[1]}`);
+    return composeModularCharacterGlb(bodyBytes, faceBytes);
+}
+//# sourceMappingURL=composeBaseMale.js.map