@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/importCharacter.js

@@ -1,31 +1,55 @@
 "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.
+// CANONICAL HELIX character conversion implementation. Shared conversion fixes belong here and are
+// exposed through Bridge; runtime repositories consume the CLI contract instead of owning a fork.
 // This file folds the engine tool's four drivers (retarget-cli, conform-cli, retarget-clip-cli,
 // package-cli) into the one `helix character import` flow; the stage code itself is ported verbatim.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANONICAL_BODY_FILENAME = void 0;
+exports.DEFAULT_FACE_DETAIL = exports.CANONICAL_BODY_FILENAME = void 0;
+exports.retainHighestDetailSourceLods = retainHighestDetailSourceLods;
+exports.faceTriShareForLevel = faceTriShareForLevel;
 exports.findCanonicalBody = findCanonicalBody;
+exports.selectDefaultBoneMap = selectDefaultBoneMap;
+exports.prepareCharacterSource = prepareCharacterSource;
+exports.retargetAnimation = retargetAnimation;
+exports.assertCanonicalCharacterGeometry = assertCanonicalCharacterGeometry;
 exports.importCharacter = importCharacter;
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 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 install_1 = require("../install");
 const esm_1 = require("./esm");
 const meshyToHelixMap_1 = require("./meshyToHelixMap");
+const metahumanToHelixMap_1 = require("./metahumanToHelixMap");
 const retarget_1 = require("./stages/retarget");
 const conform_1 = require("./stages/conform");
+const addonPushOut_1 = require("./addonPushOut");
+const poseAwareFit_1 = require("./stages/poseAwareFit");
+const mat4_1 = require("./mat4");
+const sanitizeMaterials_1 = require("./stages/sanitizeMaterials");
+const limbBridge_1 = require("./stages/limbBridge");
 const canonicalSkeleton_1 = require("./canonicalSkeleton");
 const retargetClip_1 = require("./stages/retargetClip");
 const simplifyMesh_1 = require("./stages/simplifyMesh");
 const weldedSimplify_1 = require("./stages/weldedSimplify");
 const bakeTexture_1 = require("./stages/bakeTexture");
 const splitFacePrimitive_1 = require("./stages/splitFacePrimitive");
+const faceRegion_1 = require("./stages/faceRegion");
 const mergeLods_1 = require("./stages/mergeLods");
+const slotBudgets_1 = require("./slotBudgets");
 const resizeTextures_1 = require("./stages/resizeTextures");
+const unifyMaterial_1 = require("./stages/unifyMaterial");
+const joinPerMesh_1 = require("./stages/joinPerMesh");
 const ktx2_1 = require("./stages/ktx2");
+const fbx_1 = require("./fbx");
+const unrealMaterialSidecar_1 = require("./unrealMaterialSidecar");
+const untrustedSource_1 = require("./untrustedSource");
+const importTrust_1 = require("./importTrust");
+const faceManifest_1 = require("./faceManifest");
+const helixPalette_1 = require("./helixPalette");
 exports.CANONICAL_BODY_FILENAME = 'body-m-default.web.glb';
 const DEFAULT_CLIP_NAME = 'locomotion.warriorWalk';
 /** Canonical bones the conform cannot approximate from neighbours — the map must cover every one
@@ -37,7 +61,7 @@ const REQUIRED_TARGETS = [
     'thigh_l', 'calf_l', 'foot_l', 'thigh_r', 'calf_r', 'foot_r',
 ];
 /** Throws a diagnosis-quality error when the source rig is not what the bone map expects. */
-function assertMapCoverage(body, boneMap, log) {
+function assertFullCharacterMapCoverage(body, boneMap, log) {
     const coverage = (0, retarget_1.checkMapCoverage)(body, boneMap);
     if (coverage.sourceJoints === 0) {
         throw new Error('character import: the source GLB has no skinned character (no skin joints found) — export the character WITH its rig');
@@ -60,6 +84,143 @@ function assertMapCoverage(body, boneMap, log) {
         log(`⚠ ${coverage.extra.length} source bone(s) not covered by the map (kept as-is; their deformation is unverified): [${coverage.extra.join(', ')}]`);
     }
 }
+function mappedTargetForJoint(joint, boneMap) {
+    let current = joint;
+    while (current !== null) {
+        const target = boneMap.map[current.getName()];
+        if (target !== undefined)
+            return target;
+        current = current.listParents().find((parent) => parent.propertyType === core_1.PropertyType.NODE) ?? null;
+    }
+    return null;
+}
+/** Add-ons may intentionally carry only the local rig subset their vertices use. They still have to
+ * be a lossless subset of helix-humanoid@1: every source joint must resolve through a mapped ancestor,
+ * every positive influence must resolve, and at least one deforming influence must target anatomy
+ * below the root. This admits modular MetaHuman garments without treating arbitrary partial rigs as
+ * characters or silently collapsing an incompatible rig onto the root. */
+function assertAddonMapCoverage(body, boneMap, log) {
+    const coverage = (0, retarget_1.checkMapCoverage)(body, boneMap);
+    if (coverage.sourceJoints === 0) {
+        throw new Error('character add-on import: the source GLB has no skinned add-on (no skin joints found) — export the add-on WITH its rig');
+    }
+    if (coverage.matched.length === 0) {
+        const sample = coverage.extra.slice(0, 8).join(', ') + (coverage.extra.length > 8 ? ', …' : '');
+        throw new Error(`character add-on import: the source rig matches none of the '${boneMap.name}' bone map. Source joints: [${sample}]`);
+    }
+    const canonicalJoints = new Set((0, canonicalSkeleton_1.vendoredCanonicalSkeleton)().jointNames);
+    const unresolved = new Set();
+    const invalidTargets = new Set();
+    const targetByJoint = new Map();
+    for (const skin of body.getRoot().listSkins()) {
+        for (const joint of skin.listJoints()) {
+            const target = mappedTargetForJoint(joint, boneMap);
+            if (target === null)
+                unresolved.add(joint.getName());
+            else if (!canonicalJoints.has(target))
+                invalidTargets.add(target);
+            else
+                targetByJoint.set(joint, target);
+        }
+    }
+    if (unresolved.size > 0) {
+        throw new Error(`character add-on import: incompatible partial rig — joint(s) have no mapped ancestor in '${boneMap.name}': [${[...unresolved].join(', ')}]`);
+    }
+    if (invalidTargets.size > 0) {
+        throw new Error(`character add-on import: bone map targets are not in helix-humanoid@1: [${[...invalidTargets].join(', ')}]`);
+    }
+    let positiveInfluences = 0;
+    const deformingTargets = new Set();
+    for (const node of body.getRoot().listNodes()) {
+        const skin = node.getSkin();
+        const mesh = node.getMesh();
+        if (skin === null || mesh === null)
+            continue;
+        const joints = skin.listJoints();
+        for (const primitive of mesh.listPrimitives()) {
+            for (const semantic of primitive.listSemantics().filter((name) => name.startsWith('JOINTS_'))) {
+                const set = semantic.slice('JOINTS_'.length);
+                const jointIndices = primitive.getAttribute(semantic)?.getArray();
+                const weights = primitive.getAttribute(`WEIGHTS_${set}`)?.getArray();
+                if (jointIndices === null || jointIndices === undefined || weights === null || weights === undefined) {
+                    throw new Error(`character add-on import: skin attribute set ${set} must provide both JOINTS_${set} and WEIGHTS_${set}`);
+                }
+                if (jointIndices.length !== weights.length) {
+                    throw new Error(`character add-on import: JOINTS_${set} and WEIGHTS_${set} have different lengths`);
+                }
+                for (let index = 0; index < jointIndices.length; index++) {
+                    if (weights[index] <= 0)
+                        continue;
+                    const joint = joints[jointIndices[index]];
+                    if (joint === undefined) {
+                        throw new Error(`character add-on import: JOINTS_${set} references missing skin joint ${jointIndices[index]}`);
+                    }
+                    const target = targetByJoint.get(joint);
+                    if (target === undefined) {
+                        throw new Error(`character add-on import: weighted joint '${joint.getName()}' is not compatible with helix-humanoid@1`);
+                    }
+                    positiveInfluences++;
+                    if (target !== 'root')
+                        deformingTargets.add(target);
+                }
+            }
+        }
+    }
+    if (positiveInfluences === 0) {
+        throw new Error('character add-on import: the source rig has no positive skin weights');
+    }
+    if (deformingTargets.size === 0) {
+        throw new Error('character add-on import: the source mesh has no deforming influence mapped below the canonical root');
+    }
+    if (coverage.extra.length > 0) {
+        log(`⚠ ${coverage.extra.length} source bone(s) fold through a mapped ancestor: [${coverage.extra.join(', ')}]`);
+    }
+}
+function assertMapCoverage(body, boneMap, scope, log) {
+    if (scope === 'addon')
+        assertAddonMapCoverage(body, boneMap, log);
+    else
+        assertFullCharacterMapCoverage(body, boneMap, log);
+}
+function sourceLodIdentity(node) {
+    for (const name of [node.getName(), node.getMesh()?.getName() ?? '']) {
+        const match = /^(.*?)(?:[_ .-]LOD)(\d+)$/i.exec(name.trim());
+        if (match !== null && match[1].length > 0) {
+            return { base: match[1].toLowerCase(), level: Number.parseInt(match[2], 10) };
+        }
+    }
+    return null;
+}
+/** Unreal exports often contain authored LOD0..N meshes in one scene. HELIX generates its own
+ * three deterministic LODs, so retaining every authored level duplicates the character in each
+ * output scene and makes modular composition ambiguous. Keep authored LOD0 for each explicitly
+ * numbered mesh family and leave unnumbered meshes untouched. A family without LOD0 is untouched
+ * as well, avoiding guesses about incomplete or nonstandard sources. */
+async function retainHighestDetailSourceLods(document) {
+    const tagged = document.getRoot().listNodes()
+        .filter((node) => node.getMesh() !== null)
+        .map((node) => ({ node, identity: sourceLodIdentity(node) }))
+        .filter((entry) => entry.identity !== null);
+    const familiesWithLod0 = new Set(tagged.filter(({ identity }) => identity.level === 0).map(({ identity }) => identity.base));
+    const removed = tagged.filter(({ identity }) => identity.level > 0 && familiesWithLod0.has(identity.base));
+    if (removed.length === 0)
+        return { retained: [], removed: [] };
+    const retained = tagged.filter(({ identity }) => identity.level === 0 && familiesWithLod0.has(identity.base));
+    for (const { node } of removed)
+        node.dispose();
+    await document.transform((0, functions_1.prune)({ keepSolidTextures: true }));
+    return {
+        retained: retained.map(({ node }) => node.getName()),
+        removed: removed.map(({ node }) => node.getName()),
+    };
+}
+exports.DEFAULT_FACE_DETAIL = { triShare: 0.2, texelBoost: 2.25, maxAtlasShare: 0.25, minLevelTris: 4000 };
+/** The face's triangle reserve for one LOD level (0 = area-blind), given the resolved face-detail options. */
+function faceTriShareForLevel(targetTris, faceDetail) {
+    if (faceDetail === null || targetTris < faceDetail.minLevelTris)
+        return 0;
+    return faceDetail.triShare;
+}
 /**
  * Finds the canonical helix body GLB inside the world's installed packs. First-party installs copy
  * whole bundles (code AND assets) into <world>/helix_modules/<id>/; consumer installs are code-only
@@ -89,6 +250,220 @@ function findCanonicalBody(cwd) {
     }
     return null;
 }
+async function readCharacterSource(io, path, log, fbxCache) {
+    if (!/\.fbx$/i.test(path))
+        return io.read(path);
+    const key = (0, node_path_1.resolve)(path);
+    let bytes = fbxCache.get(key);
+    if (bytes === undefined) {
+        log(`fbx: ${(0, node_path_1.basename)(path)} -> deterministic in-process GLB`);
+        bytes = await (0, fbx_1.convertFbxToGlb)(path);
+        fbxCache.set(key, bytes);
+    }
+    return io.readBinary(bytes);
+}
+function selectDefaultBoneMap(source, scope = 'character') {
+    const metahuman = (0, retarget_1.checkMapCoverage)(source, metahumanToHelixMap_1.METAHUMAN_TO_HELIX_MAP);
+    const hasMetaHumanBody = REQUIRED_TARGETS.every((target) => metahuman.coveredTargets.has(target)) && metahuman.coveredTargets.has('spine_01');
+    if (hasMetaHumanBody)
+        return metahumanToHelixMap_1.METAHUMAN_TO_HELIX_MAP;
+    const candidates = [
+        ...(scope === 'addon' ? [metahumanToHelixMap_1.METAHUMAN_TO_HELIX_MAP] : []),
+        meshyToHelixMap_1.MESHY_TO_HELIX_MAP,
+        meshyToHelixMap_1.MIXAMO_TO_HELIX_MAP,
+        meshyToHelixMap_1.MIXAMO_FBX_TO_HELIX_MAP,
+    ];
+    return candidates
+        .map((candidate) => ({ candidate, matches: (0, retarget_1.checkMapCoverage)(source, candidate).matched.length }))
+        .reduce((best, current) => current.matches > best.matches ? current : best)
+        .candidate;
+}
+async function hashBoundedCharacterSource(path) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    let sizeBytes = 0;
+    for await (const chunk of (0, node_fs_1.createReadStream)(path)) {
+        sizeBytes += chunk.length;
+        if (sizeBytes > untrustedSource_1.CHARACTER_SOURCE_LIMITS.maxBytes) {
+            throw new Error(`character import preflight: source is more than ${untrustedSource_1.CHARACTER_SOURCE_LIMITS.maxBytes} bytes; limit is ${untrustedSource_1.CHARACTER_SOURCE_LIMITS.maxBytes}`);
+        }
+        hash.update(chunk);
+    }
+    return { sha256: hash.digest('hex'), sizeBytes };
+}
+/**
+ * Normalizes an accepted character source into the self-contained GLB consumed
+ * by the hardened preflight. FBX conversion is deterministic and the exact
+ * temporary directory is removed before the expensive import stages begin.
+ * Receipts continue to identify and hash the original source file.
+ */
+/** Floor for the iterative aggregate-shrink below, matching the LOD bake's own mip-chain floor (`Math.max(128, texCap >> level)`). */
+const MIN_TEXTURE_EDGE_CAP = 128;
+/**
+ * Structurally validates `tempPath` (deferring both the per-image AND the whole-file/aggregate byte
+ * ceilings — see `preflightGeneratedCharacterSourceForDownscale`), then downscales any embedded
+ * texture whose longest edge exceeds `textureEdgeCap` before re-running the FULL gate (both ceilings
+ * enforced) on the result. Safe to call unconditionally: `resizeTextures` is a no-op per texture that
+ * is already within the cap, so an already-compliant GLB round-trips unchanged (mtime aside).
+ *
+ * A single pass at `textureEdgeCap` clears the per-image ceiling outright (every texture ends up
+ * under it), but a garment with several materials — each carrying several maps — can still sum past
+ * the 128MB AGGREGATE ceiling even once every individual texture is compliant. When that happens,
+ * keep halving the edge cap (same mip-chain convention as the LOD bake's own `texSize = Math.max(128,
+ * texCap >> level)`) and re-downscaling until the aggregate fits or the floor is reached, rather than
+ * stopping once each texture merely clears its own per-image cap. Only retries while a pass actually
+ * shrank something (`resized.length > 0`) — an unresized pass means no texture is left above the
+ * current cap, so a smaller cap cannot help and the final gate's failure is the real answer.
+ */
+async function downscaleOversizedTexturesAndRegate(tempPath, textureEdgeCap) {
+    const io = new core_1.NodeIO();
+    let cap = textureEdgeCap;
+    for (;;) {
+        (0, untrustedSource_1.preflightGeneratedCharacterSourceForDownscale)(tempPath);
+        const document = await io.readBinary((0, node_fs_1.readFileSync)(tempPath));
+        const { resized } = await (0, resizeTextures_1.resizeTextures)(document, cap);
+        if (resized.length > 0) {
+            (0, node_fs_1.writeFileSync)(tempPath, await io.writeBinary(document));
+        }
+        try {
+            return (0, untrustedSource_1.preflightGeneratedCharacterSource)(tempPath);
+        }
+        catch (error) {
+            if (resized.length === 0 || cap <= MIN_TEXTURE_EDGE_CAP)
+                throw error;
+            cap = Math.max(MIN_TEXTURE_EDGE_CAP, cap >> 1);
+        }
+    }
+}
+async function prepareCharacterSource(sourcePath, outputDir, convertFbx = fbx_1.convertFbxToGlb, 
+/**
+ * Downscale target for any embedded texture that exceeds the per-image 32MB ceiling, applied
+ * before that ceiling is enforced (see `downscaleOversizedTexturesAndRegate`). Defaults to 1024px,
+ * matching this module's own default publish resolution (`ImportCharacterOptions.texSize`) — the
+ * caller-visible slot-type distinction (1024 for most add-on slots, 2048 for a genuine
+ * `character.outfit@1` full-outfit slot) is NOT threaded down to this function: `importCharacter`
+ * already forwards its own resolved `texSize`/`texCap` here, so a caller that wants the 2048 cap for
+ * an outfit slot gets it automatically by passing `texSize: 2048`; the Bridge add-on entry point
+ * (`executeCharacterAddon`) does not do that today and so gets this 1024 default. That is a
+ * genuinely tighter cap than the platform's own 2048px wearable/add-on publish ceiling for a
+ * `character.outfit@1` item, but a correct and safe default for every slot type: it matches the
+ * pipeline's own existing default final-publish resolution (`ImportCharacterOptions.texSize`), so
+ * this pre-pass never produces a texture larger than what an unblocked item would already ship at
+ * today.
+ */
+textureEdgeCap = 1024) {
+    if (!/\.fbx$/i.test(sourcePath)) {
+        const glb = (0, untrustedSource_1.preflightCharacterSource)(sourcePath);
+        return {
+            glb,
+            original: { sha256: glb.sha256, sizeBytes: glb.sizeBytes },
+            convertedFromFbx: false,
+            materialSidecar: null,
+        };
+    }
+    const sourceSize = (0, node_fs_1.statSync)(sourcePath).size;
+    if (sourceSize > untrustedSource_1.CHARACTER_SOURCE_LIMITS.maxBytes) {
+        throw new Error(`character import preflight: source is ${sourceSize} bytes; limit is ${untrustedSource_1.CHARACTER_SOURCE_LIMITS.maxBytes}`);
+    }
+    const original = await hashBoundedCharacterSource(sourcePath);
+    const converted = await convertFbx(sourcePath);
+    const tempDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)(outputDir, '.helix-fbx-preflight-'));
+    const tempPath = (0, node_path_1.join)(tempDir, 'source.glb');
+    try {
+        (0, node_fs_1.writeFileSync)(tempPath, converted);
+        // Downscale any texture the raw FBX conversion itself embedded over the target edge cap
+        // (rare — three's GLTFExporter usually carries only whatever preview art the FBX had) before
+        // the per-image ceiling is enforced.
+        const convertedPreflight = await downscaleOversizedTexturesAndRegate(tempPath, textureEdgeCap);
+        let materialSidecar = null;
+        if (!(0, node_fs_1.existsSync)((0, unrealMaterialSidecar_1.unrealMaterialSidecarPath)(sourcePath))) {
+            return {
+                glb: convertedPreflight,
+                original,
+                convertedFromFbx: true,
+                materialSidecar,
+            };
+        }
+        // Do not let glTF-Transform parse converter output before the structural
+        // gate. Sidecar application rewrites the GLB, so gate that result again.
+        const io = new core_1.NodeIO();
+        const document = await io.readBinary(convertedPreflight.bytes);
+        materialSidecar = await (0, unrealMaterialSidecar_1.applyUnrealMaterialSidecar)(document, sourcePath);
+        (0, node_fs_1.writeFileSync)(tempPath, await io.writeBinary(document));
+        // The sidecar embeds real full-resolution art from the Unreal texture cache — this is where a
+        // real Unreal export actually exceeds the 32MB-per-image ceiling (a raw multi-K Albedo/Normal/ORM
+        // TGA baked straight into the source), so downscale again here, before the ceiling is enforced.
+        return {
+            glb: await downscaleOversizedTexturesAndRegate(tempPath, textureEdgeCap),
+            original,
+            convertedFromFbx: true,
+            materialSidecar,
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(tempDir, { recursive: true, force: true });
+    }
+}
+function mergeClipMeta(metaPath, meta) {
+    let metas = [];
+    try {
+        metas = JSON.parse((0, node_fs_1.readFileSync)(metaPath, 'utf8'));
+    }
+    catch {
+        // A fresh output directory has no clip-meta.json yet.
+    }
+    const name = meta.name;
+    metas = metas.filter((entry) => entry.name !== name);
+    metas.push(meta);
+    (0, node_fs_1.writeFileSync)(metaPath, JSON.stringify(metas, null, 2));
+}
+/**
+ * Retargets one raw FBX/GLB directly to the platform clip format without
+ * requiring a separate body-conversion run.
+ */
+async function retargetAnimation(opts) {
+    const log = opts.onProgress ?? ((message) => console.log(message));
+    const cwd = opts.cwd ?? process.cwd();
+    if (!(0, node_fs_1.existsSync)(opts.animation)) {
+        throw new Error(`retarget-animation: source not found: ${opts.animation}`);
+    }
+    if (opts.canonical !== undefined && !(0, node_fs_1.existsSync)(opts.canonical)) {
+        throw new Error(`retarget-animation: canonical body GLB not found: ${opts.canonical}`);
+    }
+    await meshoptimizer_1.MeshoptDecoder.ready;
+    const io = new core_1.NodeIO()
+        .registerExtensions(extensions_1.ALL_EXTENSIONS)
+        .registerDependencies({ 'meshopt.decoder': meshoptimizer_1.MeshoptDecoder });
+    const cache = new Map();
+    const source = await readCharacterSource(io, opts.animation, log, cache);
+    const boneMap = opts.map !== undefined
+        ? JSON.parse((0, node_fs_1.readFileSync)(opts.map, 'utf8'))
+        : selectDefaultBoneMap(source);
+    assertMapCoverage(source, boneMap, 'character', log);
+    const canonicalPath = opts.canonical ?? findCanonicalBody(cwd);
+    const canon = canonicalPath !== null
+        ? (0, conform_1.extractCanonicalSkeleton)(await io.read(canonicalPath))
+        : (0, canonicalSkeleton_1.vendoredCanonicalSkeleton)();
+    const clipName = opts.clipName ?? DEFAULT_CLIP_NAME;
+    const result = (0, retargetClip_1.retargetClip)(source, canon, boneMap, clipName, {
+        loop: opts.loop ?? false,
+    });
+    const clipPath = (0, node_path_1.resolve)(cwd, opts.output ?? (0, node_path_1.join)('character-out', 'anims', `${clipName}.glb`));
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(clipPath), { recursive: true });
+    await io.write(clipPath, result.document);
+    const metaPath = (0, node_path_1.join)((0, node_path_1.dirname)(clipPath), 'clip-meta.json');
+    mergeClipMeta(metaPath, result.meta);
+    log(`retarget-animation: ${(0, node_path_1.basename)(opts.animation)} -> ${clipPath}`);
+    log(`  ${result.frames} frames · ${result.meta.duration}s · ${result.animatedBones.length} animated bones`);
+    log(`  clip-meta -> ${metaPath}`);
+    return {
+        name: clipName,
+        path: clipPath,
+        metaPath,
+        frames: result.frames,
+        duration: result.meta.duration,
+        animatedBones: result.animatedBones,
+    };
+}
 function sceneTris(doc) {
     return doc.getRoot().listScenes().map((scene) => {
         let tris = 0;
@@ -129,25 +504,152 @@ function assertSkinnedLods(doc) {
             throw new Error(`package: LOD${i} decimated to 0 triangles — --lod-tris target is too aggressive`);
     });
 }
+const IDENTITY_4 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+/**
+ * World-space geometry postcondition for runtime character packages.
+ *
+ * Measures what a glTF renderer draws at rest: each vertex skinned by its joints
+ * (`Σ weight · jointWorld · IBM · position`). The skinned mesh node's own transform is ignored by
+ * glTF skinning, so measuring `nodeWorld · position` instead can report a correct character at the
+ * wrong scale — or pass one that renders at the wrong scale.
+ */
+function assertCanonicalCharacterGeometry(doc, scope) {
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let vertices = 0;
+    const scratch = [];
+    const influence = [];
+    const weight = [];
+    for (const scene of doc.getRoot().listScenes()) {
+        scene.traverse((node) => {
+            const skin = node.getSkin();
+            if (skin === null || node.getMesh() === null)
+                return;
+            const nodeWorld = node.getWorldMatrix();
+            const inverseBinds = skin.getInverseBindMatrices();
+            const jointBinds = skin.listJoints().map((joint, index) => (0, mat4_1.mul4)(joint.getWorldMatrix(), inverseBinds === null ? IDENTITY_4 : inverseBinds.getElement(index, new Array(16).fill(0))));
+            for (const primitive of node.getMesh().listPrimitives()) {
+                const position = primitive.getAttribute('POSITION');
+                if (position === null)
+                    continue;
+                const sets = primitive.listSemantics().filter((semantic) => semantic.startsWith('JOINTS_'))
+                    .map((semantic) => [primitive.getAttribute(semantic), primitive.getAttribute(semantic.replace('JOINTS_', 'WEIGHTS_'))])
+                    .filter(([joints, weights]) => joints !== null && weights !== null);
+                for (let index = 0; index < position.getCount(); index++) {
+                    position.getElement(index, scratch);
+                    const source = [scratch[0], scratch[1], scratch[2]];
+                    const point = [0, 0, 0];
+                    let total = 0;
+                    for (const [joints, weights] of sets) {
+                        joints.getElement(index, influence);
+                        weights.getElement(index, weight);
+                        for (let component = 0; component < influence.length; component++) {
+                            const w = weight[component];
+                            const bind = jointBinds[influence[component]];
+                            if (w <= 0 || bind === undefined)
+                                continue;
+                            const skinned = (0, mat4_1.transformPoint)(bind, source);
+                            point[0] += w * skinned[0];
+                            point[1] += w * skinned[1];
+                            point[2] += w * skinned[2];
+                            total += w;
+                        }
+                    }
+                    if (total > 0) {
+                        point[0] /= total;
+                        point[1] /= total;
+                        point[2] /= total;
+                    }
+                    else {
+                        // An unweighted vertex is malformed skin data; measure it where the node places it.
+                        const placed = (0, mat4_1.transformPoint)(nodeWorld, source);
+                        point[0] = placed[0];
+                        point[1] = placed[1];
+                        point[2] = placed[2];
+                    }
+                    for (let axis = 0; axis < 3; axis++) {
+                        min[axis] = Math.min(min[axis], point[axis]);
+                        max[axis] = Math.max(max[axis], point[axis]);
+                    }
+                    vertices++;
+                }
+            }
+        });
+    }
+    if (vertices === 0 || [...min, ...max].some((value) => !Number.isFinite(value))) {
+        throw new Error('package: canonical character geometry bounds are empty or non-finite');
+    }
+    const size = [
+        max[0] - min[0], max[1] - min[1], max[2] - min[2],
+    ];
+    const maxAbs = Math.max(...min.map(Math.abs), ...max.map(Math.abs));
+    const maxSpan = Math.max(...size);
+    if (maxAbs > 5 || maxSpan > 5 || maxSpan <= 1e-6) {
+        throw new Error(`package: ${scope} geometry is not in canonical meter scale ` +
+            `(bounds ${size.map((value) => value.toFixed(3)).join(' x ')}, max |coordinate| ${maxAbs.toFixed(3)})`);
+    }
+    if (scope === 'character' && (size[1] < 0.5 || size[1] < size[2] * 1.2)) {
+        throw new Error(`package: character geometry is not Y-up humanoid space ` +
+            `(bounds ${size.map((value) => value.toFixed(3)).join(' x ')})`);
+    }
+    return { min, max, size };
+}
 /**
  * Converts an external biped character GLB into a helix-humanoid@1 drop-in, chaining the engine
  * pipeline's stages: rename the rig (retargetSkeleton) -> embed the canonical skeleton at the source's
  * proportions (conformToHelixRest) -> LODs (rebake route for micro-chart atlases) -> merge -> resize ->
  * KTX2 -> <out>/<name>.web.glb. With `anim`, also retargets the clip -> <out>/anims/<clipName>.glb.
  */
+/** Largest world-space scale of any node instancing `mesh` (the same weight gltf-transform's scene-grouped unwrap uses). */
+function meshWorldScale(mesh) {
+    let scale = 0;
+    for (const parent of mesh.listParents()) {
+        if (parent.propertyType !== core_1.PropertyType.NODE)
+            continue;
+        for (const axis of parent.getWorldScale())
+            if (Number.isFinite(axis))
+                scale = Math.max(scale, Math.abs(axis));
+    }
+    return scale > 0 ? scale : 1;
+}
+/** Attempts at re-packaging a slot-budgeted add-on whose combined LOD triangles landed over its ceiling. */
+const MAX_BUDGET_ATTEMPTS = 3;
 async function importCharacter(opts) {
     const log = opts.onProgress ?? ((message) => console.log(message));
     const cwd = opts.cwd ?? process.cwd();
-    const lodTris = opts.lodTris ?? [10_000, 5000, 1500];
-    const texCap = opts.texSize ?? 1024;
+    const slotBudget = (opts.rigScope ?? 'character') === 'addon' && opts.slotType !== undefined ? (0, slotBudgets_1.characterAddOnBudget)(opts.slotType) : null;
+    const explicitLodTris = opts.lodTris !== undefined;
+    const lodTris = opts.lodTris ?? (slotBudget !== null ? (0, slotBudgets_1.slotAwareLodTris)(slotBudget.slotType) : [...slotBudgets_1.DEFAULT_LOD_TRIS]);
+    const texCap = Math.min(opts.texSize ?? 1024, slotBudget?.maxTextureEdge ?? Infinity);
+    const maxMaterials = slotBudget === null ? opts.maxMaterials : Math.min(opts.maxMaterials ?? Infinity, slotBudget.maxMaterials);
     const error = opts.simplifyError ?? 0.02;
     const lockBorder = opts.lockBorder ?? false;
     const weld = opts.weld ?? true;
+    // Ceiling for the seam-weld fallback's error-budget escalation below (10x the pipeline's own
+    // 0.02 default) — generous enough to unstick the real-world floor cases without becoming an
+    // unbounded "just keep relaxing until it works" loop.
+    const WELD_FALLBACK_MAX_ERROR = 0.2;
+    const faceDetail = opts.faceDetail === false || (opts.faceDetail === undefined && (opts.rigScope ?? 'character') !== 'character')
+        ? null
+        : { ...exports.DEFAULT_FACE_DETAIL, ...(opts.faceDetail ?? {}) };
     if (lodTris.length === 0)
         throw new Error('character import: --lod-tris needs at least one triangle target');
     if (!(0, node_fs_1.existsSync)(opts.body))
-        throw new Error(`character import: body GLB not found: ${opts.body}`);
-    const boneMap = opts.map !== undefined ? JSON.parse((0, node_fs_1.readFileSync)(opts.map, 'utf8')) : meshyToHelixMap_1.MESHY_TO_HELIX_MAP;
+        throw new Error(`character import: body source not found: ${opts.body}`);
+    const outDir = (0, node_path_1.resolve)(cwd, opts.output ?? './character-out');
+    const name = (0, importTrust_1.validateCharacterOutputName)(opts.name ?? (0, node_path_1.basename)(opts.body).replace(/\.(fbx|glb|gltf)$/i, ''));
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    const prepared = await prepareCharacterSource(opts.body, outDir, fbx_1.convertFbxToGlb, texCap);
+    const preflight = prepared.glb;
+    if (prepared.convertedFromFbx)
+        log(`fbx: ${(0, node_path_1.basename)(opts.body)} -> deterministic in-process GLB`);
+    if (prepared.materialSidecar !== null) {
+        log(`materials: applied ${prepared.materialSidecar.appliedSlots.length} Unreal slot(s) from `
+            + `${(0, node_path_1.basename)(prepared.materialSidecar.sidecarPath)} · verified ${prepared.materialSidecar.verifiedTextureCount} texture(s)`);
+    }
+    log(`source preflight: ${prepared.original.sizeBytes} bytes, sha256 ${prepared.original.sha256}, ${preflight.counts.nodes} nodes, ${preflight.counts.primitives} primitives`);
+    const provenance = opts.provenance !== undefined ? (0, importTrust_1.validateProvenance)(opts.provenance) : null;
+    let boneMap = opts.map !== undefined ? JSON.parse((0, node_fs_1.readFileSync)(opts.map, 'utf8')) : meshyToHelixMap_1.MESHY_TO_HELIX_MAP;
     // Canonical skeleton: explicit --canonical > the world's installed pack > the embedded
     // helix-humanoid@1 snapshot. The snapshot makes the command fully STANDALONE (no engine checkout,
     // no installed assets) — the skeleton is a frozen contract, so the embedded copy is authoritative
@@ -155,19 +657,36 @@ async function importCharacter(opts) {
     const canonicalPath = opts.canonical ?? findCanonicalBody(cwd);
     if (opts.canonical !== undefined && !(0, node_fs_1.existsSync)(opts.canonical))
         throw new Error(`character import: canonical body GLB not found: ${opts.canonical}`);
-    const outDir = (0, node_path_1.resolve)(cwd, opts.output ?? './character-out');
-    const name = opts.name ?? (0, node_path_1.basename)(opts.body).replace(/\.(glb|gltf)$/i, '');
-    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
-    const io = new core_1.NodeIO().registerExtensions(extensions_1.ALL_EXTENSIONS);
-    const canon = canonicalPath !== null ? (0, conform_1.extractCanonicalSkeleton)(await io.read(canonicalPath)) : (0, canonicalSkeleton_1.vendoredCanonicalSkeleton)();
+    await meshoptimizer_1.MeshoptDecoder.ready;
+    const io = new core_1.NodeIO()
+        .registerExtensions(extensions_1.ALL_EXTENSIONS)
+        .registerDependencies({ 'meshopt.decoder': meshoptimizer_1.MeshoptDecoder });
+    const canon = canonicalPath !== null
+        ? (0, conform_1.extractCanonicalSkeleton)(await io.read(canonicalPath), {
+            includeRootWorld: opts.fit === 'host-aligned',
+            // An add-on's skeleton must be the HOST's skeleton in the host's frame, including a `root_offset`
+            // wrapper the host hoists above its root (Base Female: (0, -0.0331, -0.0049) m). Dropping it left every
+            // female add-on's rig 33 mm above the host's, and the engine (host bones x the PART's inverse binds)
+            // rendered each part 33 mm low and 5 mm back of where its mesh was authored.
+            hoistRootOffset: opts.rigScope === 'addon',
+        })
+        : (0, canonicalSkeleton_1.vendoredCanonicalSkeleton)();
     const canonSource = canonicalPath !== null ? (0, node_path_1.basename)(canonicalPath) : 'embedded helix-humanoid@1 snapshot';
     log(`canonical skeleton: ${canon.jointNames.length} joints, ${canon.nodes.length} subtree nodes, root '${canon.skeletonRootName}' (${canonSource})`);
-    log(`bone map: ${boneMap.name} (${Object.keys(boneMap.map).length} bones, drop [${(boneMap.drop ?? []).join(', ')}])`);
     // 1. Rename the source rig onto helix bone names (drops the map's childless leaf helpers).
     // Preflight FIRST: fail with a diagnosis while the rig still has its source names.
-    const body = await io.read(opts.body);
-    assertMapCoverage(body, boneMap, log);
-    const ret = (0, retarget_1.retargetSkeleton)(body, boneMap);
+    const body = await io.readBinary(preflight.bytes);
+    const sourceLods = await retainHighestDetailSourceLods(body);
+    if (sourceLods.removed.length > 0) {
+        log(`source LODs: retained authored LOD0 [${sourceLods.retained.join(', ')}], ` +
+            `removed ${sourceLods.removed.length} lower-detail variant(s) before HELIX LOD generation`);
+    }
+    const rigScope = opts.rigScope ?? 'character';
+    if (opts.map === undefined)
+        boneMap = selectDefaultBoneMap(body, rigScope);
+    log(`bone map: ${boneMap.name} (${Object.keys(boneMap.map).length} bones, drop [${(boneMap.drop ?? []).join(', ')}])`);
+    assertMapCoverage(body, boneMap, rigScope, log);
+    const ret = (0, retarget_1.retargetSkeleton)(body, boneMap, { requireAnchors: rigScope === 'character' });
     log(`retarget: renamed ${Object.keys(ret.renamed).length}, dropped [${ret.dropped.join(', ')}], unmapped [${ret.unmapped.join(', ')}]`);
     // 2. Conform (embed): fit the canonical skeleton into the source proportions and rebind the mesh.
     // conformToHelixRest resolves joints by their CURRENT names; after the rename those are helix names,
@@ -177,15 +696,61 @@ async function importCharacter(opts) {
         ...boneMap,
         map: { ...boneMap.map, ...Object.fromEntries(Object.values(boneMap.map).map((helix) => [helix, helix])) },
     };
-    const conf = (0, conform_1.conformToHelixRest)(body, canon, conformMap);
+    const conf = (0, conform_1.conformToHelixRest)(body, canon, conformMap, {
+        mode: opts.fit === 'canonical' ? 'repose' : opts.fit === 'host-aligned' ? 'preserve' : 'embed',
+        anatomicalAnchorJoints: ret.anatomicalAnchorJoints,
+    });
     log(`conform: ${(0, node_path_1.basename)(opts.body)} [mode: ${conf.mode}]`);
-    log(`  ${conf.mode === 'embed' ? 'embedded canonical skeleton into' : 're-posed'} ${conf.verticesProcessed} verts · ${conf.jointsRebuilt} canonical joints`);
+    if (conf.unitScale !== 1)
+        log(`  ⚠ unit-normalized: source joint worlds scaled by ${conf.unitScale} to match the mesh's units (cm-scale rig)`);
+    log(`  ${conf.mode === 'embed' ? 'embedded canonical skeleton into' : conf.mode === 'preserve' ? 'preserved host-aligned geometry for' : 're-posed'} ${conf.verticesProcessed} verts · ${conf.jointsRebuilt} canonical joints · ${conf.restAimed} rests aimed at source segments`);
+    const san = await (0, sanitizeMaterials_1.sanitizeBakedEmissive)(body);
+    if (san.emissiveStripped > 0)
+        log(`  stripped baked emissive on ${san.emissiveStripped} material(s)${san.blackEmissiveStripped > 0 ? ` (${san.blackEmissiveStripped} flat-black emissive map)` : ''}${san.metallicZeroed > 0 ? ` · metallic → 0 on ${san.metallicZeroed}` : ''}`);
+    if (san.metadataStripped > 0)
+        log(`  stripped untrusted material metadata on ${san.metadataStripped} material(s)`);
+    // 2a. Limb bridges (full characters): an A-pose mesher can fuse a resting hand to the thigh; cut the bridge
+    // here, on the full-resolution conformed mesh, so every LOD below decimates the repaired surface.
+    const limbBridgeOptions = rigScope === 'character' && opts.limbBridges !== false ? (opts.limbBridges ?? {}) : null;
+    const limbBridgeReport = limbBridgeOptions !== null
+        ? (0, limbBridge_1.repairLimbBridges)(body, { ...limbBridgeOptions, sampleLuma: limbBridgeOptions.sampleLuma ?? await (0, limbBridge_1.baseColorLumaSamplers)(body) })
+        : null;
+    if (limbBridgeReport !== null)
+        for (const line of (0, limbBridge_1.describeLimbBridgeReport)(limbBridgeReport))
+            log(`  ${line}`);
+    // 2b. Push-out (add-ons only): the conformed garment now sits in the SAME rest-pose space as the host
+    // body it was fit against (that is what `fit: 'canonical'` + `canonical: <host.glb>` means), so a
+    // second, independent host-body read can serve as the poke-through reference here — a hem, cuff or
+    // waistband too tight for `bodyRegionHide.ts`'s region hide gets a small push clear of the skin instead
+    // of relying on the creator to notice. No host GLB (a plain character import, or an addon conformed
+    // without an explicit `--canonical`) means nothing to push away from, so this is skipped rather than
+    // guessed at.
+    let pushOutReport = null;
+    if (rigScope === 'addon' && opts.pushOut !== false && canonicalPath !== null) {
+        const hostDocument = await io.read(canonicalPath);
+        pushOutReport = (0, addonPushOut_1.pushGarmentOutOfBody)(body, hostDocument, opts.pushOut ?? {});
+        if (pushOutReport.verticesPushed > 0) {
+            log(`push-out: ${pushOutReport.verticesPushed}/${pushOutReport.verticesAtRisk} at-risk vert(s) moved clear `
+                + `of the body (max correction ${(pushOutReport.maxCorrectionMeters * 1000).toFixed(1)}mm)`
+                + `${pushOutReport.verticesClamped > 0 ? `, ${pushOutReport.verticesClamped} clamped at the max` : ''}`);
+        }
+        else if (pushOutReport.verticesAtRisk > 0) {
+            log('push-out: at-risk vertex(es) found but none needed moving (already at or beyond the target offset)');
+        }
+    }
     // 3. Package (the engine package-cli flow). The conformed doc is serialized once so each LOD level
     // decimates a fresh copy, exactly like package-cli re-reading its --body input per level.
     const conformedBytes = await io.writeBinary(body);
     const source = await io.readBinary(conformedBytes);
     const seams = (0, weldedSimplify_1.analyzeSeams)(source);
-    const bake = opts.bake ?? seams.microChartAtlas;
+    const bakeableBaseColor = (0, bakeTexture_1.hasBakeableBaseColorTexture)(source);
+    if (opts.bake === true && !bakeableBaseColor) {
+        throw new Error('character import: --bake requires at least one embedded base-color texture with image data');
+    }
+    const bake = opts.bake === true || (opts.bake === undefined && seams.microChartAtlas && bakeableBaseColor);
+    if (opts.bake === undefined && seams.microChartAtlas && !bakeableBaseColor) {
+        log(`atlas: micro-chart (${seams.charts} charts / ${seams.tris} tris), but no bakeable base-color texture -> non-bake path`);
+    }
     let watlas = null;
     if (bake) {
         log(`atlas: ${seams.charts} charts / ${seams.tris} tris (${seams.verts} verts, ${seams.positions} positions) -> ${opts.bake === true ? 'bake forced' : 'micro-chart, rebake route'}`);
@@ -196,66 +761,219 @@ async function importCharacter(opts) {
     // On the plain (non-bake) route, levels sharing a mode produce byte-identical textures that
     // merge-lods dedup still collapses; a mixed chain keeps one texture per distinct encoding.
     const ktxModes = opts.ktxModes !== undefined && opts.ktxModes.length > 0 ? opts.ktxModes : ['uastc', 'etc1s'];
+    const ktx2Enabled = opts.ktx2 ?? true;
     const modeFor = (level) => ktxModes[Math.min(level, ktxModes.length - 1)];
     const kb = (n) => Math.round(n / 1024);
     const textureSizes = [];
-    const lods = [];
     let ktxBefore = 0, ktxAfter = 0;
-    let encoder = 'basis-wasm';
-    for (const [level, target] of lodTris.entries()) {
-        let doc = await io.readBinary(conformedBytes);
-        if (bake) {
-            const w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, error);
-            await doc.transform((0, functions_1.unwrap)({ watlas: watlas, overwrite: true }));
-            const texSize = Math.max(128, texCap >> level); // halve per level, like a mip chain
-            const b = await (0, bakeTexture_1.bakeBaseColor)(doc, source, texSize);
-            log(`lod: ${w.before} -> ${w.after} tris (target ${target})  rebaked ${texSize}px (${b.sampled} texels, ${b.far} far)`);
-            textureSizes.push(texSize);
-        }
-        else {
-            const r = await (0, simplifyMesh_1.simplifyToTarget)(doc, target, error, lockBorder);
-            const missed = r.after > target * 1.15;
-            if (missed && weld && level > 0) {
-                doc = await io.readBinary(conformedBytes);
-                const w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, error);
-                log(`lod: ${w.before} -> ${w.after} tris (target ${target})  seam-weld fallback, uv-coherent ${(w.uvCoherence * 100).toFixed(0)}%`);
+    let encoder = ktx2Enabled ? 'basis-wasm' : 'skipped';
+    // LOD generation → merge → post-merge passes, as one re-runnable step: when a slot budget applies and the
+    // packaged result lands over the slot's COMBINED triangle ceiling, the ladder is rescaled and this runs
+    // again (see the loop below) instead of shipping a file the server will refuse.
+    // Every LOD re-checks its own decimated surface BEFORE it is unwrapped and baked: the full-resolution cut
+    // leaves the two sides joined through unowned (pelvis/torso) vertices, and decimation can collapse those into
+    // a new arm<->leg triangle. The same stage, same gate, so LOD1/LOD2 never walk worse than LOD0.
+    const repairLodBridges = async (doc, level) => {
+        if (limbBridgeOptions === null)
+            return;
+        const report = (0, limbBridge_1.repairLimbBridges)(doc, { ...limbBridgeOptions, sampleLuma: limbBridgeOptions.sampleLuma ?? await (0, limbBridge_1.baseColorLumaSamplers)(doc) });
+        for (const line of (0, limbBridge_1.describeLimbBridgeReport)(report))
+            log(`     lod${level} ${line}`);
+    };
+    const packageLevels = async (targets) => {
+        textureSizes.length = 0;
+        ktxBefore = 0;
+        ktxAfter = 0;
+        const lods = [];
+        // Snapshot of each level's geometry BEFORE encodeKtx2 mutates its textures to KTX2-compressed
+        // binaries below (still plain PNG/JPEG) — the seam-weld fallback's "retarget from the previous
+        // level" floor needs a document `resizeTextures`'/sharp's PNG decode can still read; `lods[]`
+        // itself is unusable for that once a level's own encodeKtx2 has already run on it.
+        const preKtxLods = [];
+        for (const [level, target] of targets.entries()) {
+            let doc = await io.readBinary(conformedBytes);
+            if (bake) {
+                const faceShare = faceTriShareForLevel(target, faceDetail);
+                const w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, error, faceShare > 0 ? { share: faceShare } : undefined);
+                await repairLodBridges(doc, level);
+                // One atlas for the whole level: every primitive's charts are packed together, because the bake
+                // writes all of them into the same images. Per-mesh atlases would overlap in [0,1]. With face detail the
+                // face rides in its own primitive for the unwrap only (charts never cross primitives), scaled up so the
+                // packer gives it more texels, then folds back into the body after the bake.
+                const faceSplits = faceDetail !== null ? (0, faceRegion_1.splitFaceForUnwrap)(doc) : [];
+                let faceScale = 1;
+                if (faceSplits.length > 0) {
+                    const faceArea = faceSplits.reduce((sum, split) => sum + split.faceAreaShare, 0) / faceSplits.length;
+                    faceScale = (0, faceRegion_1.faceChartScale)(faceArea, faceDetail.texelBoost, faceDetail.maxAtlasShare);
+                    const faces = new Set(faceSplits.map((split) => split.face));
+                    const prims = doc.getRoot().listMeshes().flatMap((mesh) => mesh.listPrimitives().map((prim) => ({ prim, scale: meshWorldScale(mesh) })));
+                    await watlas.Initialize();
+                    (0, functions_1.unwrapPrimitives)(prims.map(({ prim }) => prim), {
+                        watlas: watlas, overwrite: true, texcoord: 0,
+                        weights: prims.map(({ prim, scale }) => scale * (faces.has(prim) ? faceScale : 1)),
+                    });
+                }
+                else {
+                    await doc.transform((0, functions_1.unwrap)({ watlas: watlas, overwrite: true, groupBy: 'scene' }));
+                }
+                const texSize = Math.max(128, texCap >> level); // halve per level, like a mip chain
+                const b = await (0, bakeTexture_1.bakeMaterials)(doc, source, texSize);
+                (0, faceRegion_1.rejoinFaceSplits)(doc, faceSplits);
+                log(`lod: ${w.before} -> ${w.after} tris (target ${target})  rebaked ${texSize}px [${b.slots.join('+')}] (${b.sampled} texels, ${b.far} far)`);
+                if (w.face !== undefined)
+                    log(`     face detail: ${w.face.before} -> ${w.face.after} face tris (budget ${w.face.budget}), face charts x${faceScale.toFixed(2)} texel density`);
+                textureSizes.push(texSize);
             }
             else {
-                log(`lod: ${r.before} -> ${r.after} tris (target ${target})${missed ? '  ⚠ floored above target' : ''}`);
-                if (missed)
-                    log(`     seam-locked mesh (micro-chart atlas / disconnected islands). Try --bake, raise --simplify-error, or accept the floor.`);
+                const r = await (0, simplifyMesh_1.simplifyToTarget)(doc, target, error, lockBorder);
+                const missed = r.after > target * 1.15;
+                if (missed && weld && level > 0) {
+                    doc = await io.readBinary(conformedBytes);
+                    let w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, error);
+                    // weldedSimplify itself can floor: on a geometrically complex mesh pushed to an aggressive
+                    // target, meshopt's quadric collapse stops the moment the NEXT edge collapse would exceed
+                    // `error`, which can mean near-zero reduction at this stage's default (the same `error`
+                    // budget the plain attempt above already missed with). Real failure: Male Orangekombes and
+                    // Male Panda Bag 2's LOD2 (target 1500) came back 51812 -> 51812 — completely unreduced, so
+                    // LOD2 shipped LARGER than LOD0/LOD1. Escalate the error budget — the same relaxation the
+                    // pilot's own decimate3.mjs scratch tool used by hand (0.05, later found up to 0.2 needed for
+                    // some meshes) — and retry until the target is met or the ceiling is reached.
+                    let relaxedError = error;
+                    while (w.after > target * 1.15 && relaxedError < WELD_FALLBACK_MAX_ERROR) {
+                        relaxedError = Math.min(WELD_FALLBACK_MAX_ERROR, relaxedError * 2.5);
+                        doc = await io.readBinary(conformedBytes);
+                        w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, relaxedError);
+                    }
+                    // Belt-and-suspenders floor: whatever error-budget relaxation achieves, a LOD level must
+                    // never ship with MORE triangles than the level before it (the actual defect: LOD2 > LOD0).
+                    // Re-target from the PREVIOUS level's own already-simplified geometry when that happens —
+                    // meshopt's simplify never increases triangle count, so decimating an already-lower-poly mesh
+                    // can only tie or improve on it, guaranteeing a monotonically non-increasing LOD chain by
+                    // construction regardless of how this mesh behaves under any error budget.
+                    const previousLodTris = level > 0 ? sceneTris(preKtxLods[level - 1]).reduce((a, b) => a + b, 0) : Infinity;
+                    if (w.after > previousLodTris) {
+                        const previousBytes = await io.writeBinary(preKtxLods[level - 1]);
+                        doc = await io.readBinary(previousBytes);
+                        w = await (0, weldedSimplify_1.weldedSimplify)(doc, target, WELD_FALLBACK_MAX_ERROR);
+                        log(`lod: retargeted from LOD${level - 1}'s own geometry (${previousLodTris} tris) — seam-weld fallback still exceeded it`);
+                    }
+                    log(`lod: ${w.before} -> ${w.after} tris (target ${target})  seam-weld fallback${relaxedError !== error ? ` (error ${relaxedError.toFixed(3)})` : ''}, uv-coherent ${(w.uvCoherence * 100).toFixed(0)}%`);
+                    if (w.after > target * 1.15)
+                        log(`     ⚠ floored above target even after seam-weld relaxation`);
+                }
+                else {
+                    log(`lod: ${r.before} -> ${r.after} tris (target ${target})${missed ? '  ⚠ floored above target' : ''}`);
+                    if (missed)
+                        log(`     seam-locked mesh (micro-chart atlas / disconnected islands). Try --bake, raise --simplify-error, or accept the floor.`);
+                }
+                await repairLodBridges(doc, level);
+                const resized = await (0, resizeTextures_1.resizeTextures)(doc, texCap);
+                if (level === 0 && resized.resized.length > 0)
+                    log(`resize-textures: ${resized.resized.join('; ')}`);
             }
-            const resized = await (0, resizeTextures_1.resizeTextures)(doc, texCap);
-            if (level === 0 && resized.resized.length > 0)
-                log(`resize-textures: ${resized.resized.join('; ')}`);
+            preKtxLods.push(await io.readBinary(await io.writeBinary(doc)));
+            if (ktx2Enabled) {
+                const ktx = await (0, ktx2_1.encodeKtx2)(doc, { mode: modeFor(level), ...(opts.ktxQuality !== undefined && { quality: opts.ktxQuality }) });
+                const before = ktx.encoded.reduce((s, e) => s + e.before, 0), after = ktx.encoded.reduce((s, e) => s + e.after, 0);
+                ktxBefore += before;
+                ktxAfter += after;
+                encoder = ktx.encoder;
+                log(`ktx2 lod${level} (${ktx.mode}, ${ktx.encoder}): ${ktx.encoded.length} texture(s), ${kb(before)}KB -> ${kb(after)}KB`);
+            }
+            else if (level === 0) {
+                log('ktx2: skipped (ktx2: false) — textures stay png/jpeg');
+            }
+            lods.push(doc);
         }
-        const ktx = await (0, ktx2_1.encodeKtx2)(doc, { mode: modeFor(level), ...(opts.ktxQuality !== undefined && { quality: opts.ktxQuality }) });
-        const before = ktx.encoded.reduce((s, e) => s + e.before, 0), after = ktx.encoded.reduce((s, e) => s + e.after, 0);
-        ktxBefore += before;
-        ktxAfter += after;
-        encoder = ktx.encoder;
-        log(`ktx2 lod${level} (${ktx.mode}, ${ktx.encoder}): ${ktx.encoded.length} texture(s), ${kb(before)}KB -> ${kb(after)}KB`);
-        lods.push(doc);
-    }
-    if (!bake)
-        textureSizes.push(texCap);
-    const merged = await (0, mergeLods_1.mergeLods)(lods);
-    log(`merge-lods: ${lods.length} LODs -> scenes [${merged.scenes.join(', ')}], textures ${merged.texturesBefore} -> ${merged.texturesAfter}`);
-    const out = merged.document;
-    // AFTER merge-lods: its material dedup would fold the face's cloned material back into the body's.
-    if (opts.splitFace ?? true) {
-        const s = (0, splitFacePrimitive_1.splitFacePrimitive)(out);
-        if (s.split)
-            log(`split-face: ${s.faceTris} head tris -> 'FaceMesh' per level (${s.headJoints} head-subtree joints), bodies keep ${s.bodyTris}`);
-        else
-            log(`⚠ split-face: no head-weighted triangles found — first-person mode cannot hide this character's head`);
+        if (!bake)
+            textureSizes.push(texCap);
+        const merged = await (0, mergeLods_1.mergeLods)(lods);
+        log(`merge-lods: ${lods.length} LODs -> scenes [${merged.scenes.join(', ')}], textures ${merged.texturesBefore} -> ${merged.texturesAfter}`);
+        const packaged = merged.document;
+        // AFTER merge-lods: its material dedup would fold the face's cloned material back into the body's.
+        if (opts.splitFace ?? true) {
+            const s = (0, splitFacePrimitive_1.splitFacePrimitive)(packaged);
+            if (s.split)
+                log(`split-face: ${s.faceTris} head tris -> 'FaceMesh' per level (${s.headJoints} head-subtree joints), bodies keep ${s.bodyTris}`);
+            else
+                log(`⚠ split-face: no head-weighted triangles found — first-person mode cannot hide this character's head`);
+        }
+        if (maxMaterials !== undefined) {
+            // The rebake route re-unwraps and re-bakes every LOD into its OWN atlas, so a lower LOD's UVs only make sense
+            // against its own texture: unify within each LOD scene, never across them (see `shareAcrossScenes`).
+            const unified = await (0, unifyMaterial_1.unifyDominantMaterial)(packaged, { maxMaterials, shareAcrossScenes: !bake });
+            if (unified.dominant !== null) {
+                log(`unify-material: ${unified.materialsBefore} -> ${unified.materialsAfter} materials (over the ${maxMaterials}-material cap) — rebound ${unified.rebound} primitive(s) onto '${unified.dominant}'`);
+                if (unified.cutoutsPromoted > 0)
+                    log(`  unify-material: kept the alpha cutout of ${unified.cutoutsPromoted} primitive(s) by promoting the shared atlas material to MASK`);
+                if (unified.cutoutsFlattened > 0)
+                    log(`⚠ unify-material: ${unified.cutoutsFlattened} cutout/blend primitive(s) were folded into an opaque material that does not share their texture — they now draw SOLID (stitching/lace/mesh panels will look like slabs); raise the material cap or fix the source`);
+                if (unified.crossSceneFallback)
+                    log(`⚠ unify-material: one material per LOD still exceeds the ${maxMaterials}-material cap, so lower LODs were rebound onto another LOD's material${bake ? ' — on the rebake route their UVs index a DIFFERENT atlas, so they will sample the wrong texels' : ''}`);
+                const joined = (0, joinPerMesh_1.joinPrimitivesPerMesh)(packaged);
+                if (joined.meshesJoined > 0)
+                    log(`join-per-mesh: ${joined.primitivesBefore} -> ${joined.primitivesAfter} primitives across ${joined.meshesJoined} LOD mesh(es)`);
+            }
+        }
+        return packaged;
+    };
+    if (slotBudget !== null) {
+        log(`slot budget: ${slotBudget.slotType} ${slotBudget.tiered ? '' : '(untiered → flat add-on ceiling) '}`
+            + `≤ ${slotBudget.maxTriangles} tris combined across LODs, ≤ ${slotBudget.maxMaterials} material(s), ≤ ${slotBudget.maxTextureEdge}px`
+            + ` — LOD targets ${lodTris.join('/')}${explicitLodTris ? ' (explicit)' : ' (slot-aware)'}`);
+    }
+    let targets = lodTris;
+    let out;
+    for (let attempt = 1;; attempt++) {
+        out = await packageLevels(targets);
+        if (slotBudget === null)
+            break;
+        const combined = sceneTris(out).reduce((sum, tris) => sum + tris, 0);
+        if (combined <= slotBudget.maxTriangles) {
+            log(`slot budget: ${combined} tris combined ≤ ${slotBudget.maxTriangles} (${slotBudget.slotType})`);
+            break;
+        }
+        const over = `${combined} tris combined across LODs is over ${slotBudget.slotType}'s ${slotBudget.maxTriangles} ceiling (the server refuses this at publish)`;
+        if (explicitLodTris)
+            throw new Error(`character import: ${over} — the explicit LOD targets ${lodTris.join('/')} are too high for this slot; lower them or omit them to use the slot-aware ladder`);
+        if (attempt >= MAX_BUDGET_ATTEMPTS)
+            throw new Error(`character import: ${over} after ${attempt} rescaled attempts — this mesh floors above its slot's budget (try bake: true or a higher simplify error)`);
+        const scale = (slotBudget.maxTriangles * slotBudgets_1.LOD_BUDGET_HEADROOM) / combined;
+        targets = targets.map((tris) => Math.max(1, Math.floor(tris * scale)));
+        log(`slot budget: ${over} — rescaling LOD targets ×${scale.toFixed(3)} to ${targets.join('/')} and re-packaging`);
+    }
+    const materialCount = out.getRoot().listMaterials().length;
+    if (slotBudget !== null && materialCount > slotBudget.maxMaterials) {
+        throw new Error(`character import: ${materialCount} materials is over ${slotBudget.slotType}'s ${slotBudget.maxMaterials}-material ceiling after unify-material`);
     }
     assertSkinnedLods(out); // every LOD must still be a valid, non-empty skinned mesh
+    (0, mergeLods_1.assertSelfContainedLodScenes)(out); // …and loadable: each scene's skins bind to bones in that scene (see mergeLods)
     await out.transform((0, functions_1.prune)({ keepSolidTextures: true }));
-    const modes = lodTris.map((_, level) => modeFor(level));
+    // Pose-aware fit (add-ons only), on the PACKAGED document so every LOD level is fitted and the gate judges
+    // exactly what ships. Runs after the LOD merge on purpose: decimating a fitted LOD0 would reintroduce the
+    // coarse chords that cut into the body, which is most of what the fit exists to fix.
+    let poseFitReport = null;
+    if (rigScope === 'addon' && opts.poseFit && canonicalPath !== null) {
+        poseFitReport = (0, poseAwareFit_1.poseAwareFit)(out, await io.read(canonicalPath), { ...opts.poseFit, onProgress: opts.poseFit.onProgress ?? log });
+        log(`pose-fit: ${poseFitReport.outcome}${poseFitReport.reason ? ` — ${poseFitReport.reason}` : ''}`);
+    }
+    const geometryBounds = assertCanonicalCharacterGeometry(out, rigScope);
+    log(`geometry: canonical ${rigScope} bounds ${geometryBounds.size.map((value) => value.toFixed(3)).join(' x ')}m`);
+    const face = opts.faceMap !== undefined ? (0, faceManifest_1.readFaceManifest)(opts.faceMap) : (0, faceManifest_1.detectFaceManifest)(out);
+    (0, faceManifest_1.attachFaceManifest)(out, face);
+    const faceMode = (0, faceManifest_1.faceCapability)(face);
+    log(`face: ${faceMode}${opts.faceMap !== undefined ? ` (explicit ${(0, node_path_1.basename)(opts.faceMap)})` : ' (safe-name detection)'}`);
+    const palette = opts.palette === undefined
+        ? null
+        : (0, helixPalette_1.applyHelixPaletteSelection)(out, (0, helixPalette_1.resolveHelixPaletteSelection)(opts.palette.path, opts.palette.selection));
+    if (palette !== null) {
+        log(`palette: ${palette.familyId}@${palette.familyVersion} -> ${palette.appliedMaterialCount} material(s) `
+            + `(authored textures preserved; assets ${palette.assetsState})`);
+    }
+    const modes = ktx2Enabled ? lodTris.map((_, level) => modeFor(level)) : [];
     const bodyPath = (0, node_path_1.join)(outDir, `${name}.web.glb`);
     await io.write(bodyPath, out);
-    log(`\npackage: ${(0, node_path_1.basename)(opts.body)} -> ${bodyPath}  |  LOD tris ${sceneTris(out).join(' / ')}  |  ${texCap}px KTX2 (${modes.join('/')})`);
+    log(`\npackage: ${(0, node_path_1.basename)(opts.body)} -> ${bodyPath}  |  LOD tris ${sceneTris(out).join(' / ')}  |  ${texCap}px ${ktx2Enabled ? `KTX2 (${modes.join('/')})` : 'png/jpeg (ktx2 skipped)'}`);
     // 4. Optional clip retarget (the engine retarget-clip-cli flow) — works on the RAW source anim + map.
     let clip = null;
     if (opts.anim !== undefined) {
@@ -269,25 +987,84 @@ async function importCharacter(opts) {
         log(`  ${r.frames} frames · ${r.meta.duration}s · ${r.animatedBones.length} animated bones: ${r.animatedBones.join(', ')}`);
         // Merge into clip-meta.json (so it can be loaded like the platform clip set).
         const metaPath = (0, node_path_1.join)(animsDir, 'clip-meta.json');
-        let metas = [];
-        try {
-            metas = JSON.parse((0, node_fs_1.readFileSync)(metaPath, 'utf8'));
-        }
-        catch { /* fresh */ }
-        metas = metas.filter((m) => m.name !== r.meta.name);
-        metas.push(r.meta);
-        (0, node_fs_1.writeFileSync)(metaPath, JSON.stringify(metas, null, 2));
+        mergeClipMeta(metaPath, r.meta);
         log(`  clip-meta -> ${metaPath}`);
         clip = { name: clipName, path: clipPath, metaPath, frames: r.frames, duration: r.meta.duration, animatedBones: r.animatedBones };
     }
+    const outputBytes = (0, node_fs_1.readFileSync)(bodyPath);
+    const receiptPath = (0, node_path_1.join)(outDir, `${name}.avatar-import.json`);
+    (0, node_fs_1.writeFileSync)(receiptPath, JSON.stringify({
+        contract: 'helix/avatar-import-receipt@1',
+        source: {
+            file: (0, node_path_1.basename)(opts.body),
+            sha256: prepared.original.sha256,
+            sizeBytes: prepared.original.sizeBytes,
+            counts: preflight.counts,
+            provenance,
+        },
+        output: {
+            file: (0, node_path_1.basename)(bodyPath),
+            sha256: (0, node_crypto_1.createHash)('sha256').update(outputBytes).digest('hex'),
+            sizeBytes: outputBytes.length,
+            skeleton: 'helix-humanoid@1',
+            face: { capability: faceMode, manifest: face },
+            lodTriangles: sceneTris(out),
+        },
+        transforms: {
+            boneMap: { name: boneMap.name, version: boneMap.version },
+            retargetedBones: Object.keys(ret.renamed).length,
+            conformed: { mode: conf.mode, unitScale: conf.unitScale, restAimed: conf.restAimed, verticesProcessed: conf.verticesProcessed, jointsRebuilt: conf.jointsRebuilt },
+            textureSizes,
+            ktx2: { encoder, modes, before: ktxBefore, after: ktxAfter },
+            splitFace: opts.splitFace ?? true,
+            unrealMaterialSidecar: prepared.materialSidecar === null ? null : {
+                schemaVersion: prepared.materialSidecar.schemaVersion,
+                file: (0, node_path_1.basename)(prepared.materialSidecar.sidecarPath),
+                sourceMeshAssetPath: prepared.materialSidecar.sourceMeshAssetPath,
+                appliedSlots: prepared.materialSidecar.appliedSlots,
+                preservedMaterialCount: prepared.materialSidecar.preservedMaterialCount,
+                verifiedTextureCount: prepared.materialSidecar.verifiedTextureCount,
+                createdTextureCount: prepared.materialSidecar.createdTextureCount,
+            },
+            helixPalette: palette,
+            limbBridges: limbBridgeReport === null ? null : {
+                mode: limbBridgeReport.mode,
+                removedTriangles: limbBridgeReport.removedTriangles,
+                fillTriangles: limbBridgeReport.fillTriangles,
+                verticesReweighted: limbBridgeReport.verticesReweighted,
+                units: limbBridgeReport.units.filter((u) => u.bridgeTriangles > 0 || u.reassignedPieces.length > 0).map((u) => ({
+                    mesh: u.mesh, bridgeTriangles: u.bridgeTriangles, outcome: u.outcome, reason: u.reason,
+                    clusters: u.clusters.map((c) => ({ arm: c.arm, leg: c.leg, triangles: c.triangles, refused: c.refused })),
+                    stretchBefore: u.stretchBefore, stretchAfter: u.stretchAfter,
+                })),
+            },
+            pushOut: pushOutReport,
+            poseFit: poseFitReport === null ? null : {
+                outcome: poseFitReport.outcome,
+                reason: poseFitReport.reason,
+                settings: poseFitReport.settings,
+                before: poseFitReport.before && { totalViolations: poseFitReport.before.totalViolations, totalExposedViolations: poseFitReport.before.totalExposedViolations },
+                after: poseFitReport.after && { totalViolations: poseFitReport.after.totalViolations, totalExposedViolations: poseFitReport.after.totalExposedViolations },
+                applied: poseFitReport.applied,
+            },
+        },
+        limits: untrustedSource_1.CHARACTER_SOURCE_LIMITS,
+    }, null, 2));
+    log(`receipt: ${receiptPath}`);
     return {
         bodyPath,
         lodTris: sceneTris(out),
         textureSizes,
         retarget: { renamed: Object.keys(ret.renamed).length, unmapped: ret.unmapped, dropped: ret.dropped },
-        conform: { mode: conf.mode, verticesProcessed: conf.verticesProcessed, jointsRebuilt: conf.jointsRebuilt },
+        conform: { mode: conf.mode, unitScale: conf.unitScale, restAimed: conf.restAimed, verticesProcessed: conf.verticesProcessed, jointsRebuilt: conf.jointsRebuilt },
         ktx2: { encoder, modes, before: ktxBefore, after: ktxAfter },
         clip,
+        receiptPath,
+        face: { capability: faceMode, manifest: face },
+        palette,
+        limbBridges: limbBridgeReport,
+        pushOut: pushOutReport,
+        poseFit: poseFitReport,
     };
 }
 //# sourceMappingURL=importCharacter.js.map