@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/character/unrealMaterialSidecar.js

@@ -0,0 +1,879 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNREAL_MATERIAL_SIDECAR_SCHEMA = void 0;
+exports.unrealMaterialSidecarPath = unrealMaterialSidecarPath;
+exports.discoverUnrealMaterialSidecarDependencies = discoverUnrealMaterialSidecarDependencies;
+exports.applyUnrealMaterialSidecar = applyUnrealMaterialSidecar;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const sharp_1 = __importDefault(require("sharp"));
+const hash_1 = require("../bridge/hash");
+const imageLimits_1 = require("./imageLimits");
+exports.UNREAL_MATERIAL_SIDECAR_SCHEMA = 'helix.bridge.unreal-material-sidecar/1';
+const SHA256 = /^[a-f0-9]{64}$/;
+const SLUG = /^[a-z0-9](?:[a-z0-9._-]{0,127})$/;
+const UNREAL_OBJECT_PATH = /^\/[A-Za-z0-9_+]+\/(?:[A-Za-z0-9_+]+\/)*[A-Za-z0-9_+]+(?:\.[A-Za-z0-9_+]+)?$/;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const MAX_SIDECAR_BYTES = 8 * 1024 * 1024;
+const MAX_TEXTURE_BYTES = 512 * 1024 * 1024;
+const MAX_TOTAL_TEXTURE_BYTES = 512 * 1024 * 1024;
+const MAX_MATERIALS = 256;
+const MAX_PARAMETERS_PER_KIND = 512;
+function fail(label, message) {
+    throw new Error(`Unreal material sidecar ${label}: ${message}`);
+}
+function preflightPngDimensions(image, label) {
+    if (image.byteLength < 33 || Buffer.from(image.subarray(12, 16)).toString('ascii') !== 'IHDR') {
+        fail(label, 'has no valid PNG IHDR header.');
+    }
+    const view = Buffer.from(image.buffer, image.byteOffset, image.byteLength);
+    const width = view.readUInt32BE(16);
+    const height = view.readUInt32BE(20);
+    const pixels = width * height;
+    if (width === 0
+        || height === 0
+        || width > imageLimits_1.MAX_CHARACTER_TEXTURE_DIMENSION
+        || height > imageLimits_1.MAX_CHARACTER_TEXTURE_DIMENSION
+        || !Number.isSafeInteger(pixels)
+        || pixels > imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS) {
+        fail(label, `has decoded dimensions ${width}x${height}; character texture budget is `
+            + `${imageLimits_1.MAX_CHARACTER_TEXTURE_DIMENSION}x${imageLimits_1.MAX_CHARACTER_TEXTURE_DIMENSION} and `
+            + `${imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS} pixels.`);
+    }
+}
+function record(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return fail(label, 'must be an object.');
+    }
+    return value;
+}
+function exactKeys(value, required, optional, label) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            fail(label, `contains unsupported field ${JSON.stringify(key)}.`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            fail(label, `is missing required field ${JSON.stringify(key)}.`);
+    }
+}
+function stringValue(value, label, allowEmpty = false) {
+    if (typeof value !== 'string'
+        || value.length > 1024
+        || /[\u0000-\u001f\u007f]/.test(value)
+        || (!allowEmpty && value.trim().length === 0)) {
+        return fail(label, `must be ${allowEmpty ? 'a bounded' : 'a non-empty bounded'} string.`);
+    }
+    return value;
+}
+function unrealPath(value, label) {
+    const path = stringValue(value, label);
+    if (!UNREAL_OBJECT_PATH.test(path) || path.includes('..') || path.includes('\\')) {
+        return fail(label, 'must be a portable Unreal object path.');
+    }
+    return path;
+}
+function finiteNumber(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fail(label, 'must be a finite number.');
+    return value;
+}
+function compareCodePoint(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function parameterEntries(value, label) {
+    const values = record(value, label);
+    const entries = Object.entries(values);
+    if (entries.length > MAX_PARAMETERS_PER_KIND)
+        fail(label, `exceeds ${MAX_PARAMETERS_PER_KIND} entries.`);
+    for (const [name] of entries) {
+        if (name.trim().length === 0 || name.length > 256 || ['__proto__', 'constructor', 'prototype'].includes(name)) {
+            fail(label, `contains unsafe parameter name ${JSON.stringify(name)}.`);
+        }
+    }
+    return entries;
+}
+function parseTextureRecord(value, label) {
+    const input = record(value, label);
+    exactKeys(input, ['sourceAssetPath', 'path', 'sha256', 'sizeBytes', 'colorSpace'], [], label);
+    const sha256 = stringValue(input.sha256, `${label}.sha256`);
+    if (!SHA256.test(sha256))
+        fail(`${label}.sha256`, 'must be a lowercase SHA-256 digest.');
+    const path = stringValue(input.path, `${label}.path`);
+    if (path !== `textures/${sha256}.png`) {
+        fail(`${label}.path`, 'must be the content-addressed textures/<sha256>.png path.');
+    }
+    const sizeBytes = input.sizeBytes;
+    if (!Number.isSafeInteger(sizeBytes) || Number(sizeBytes) <= 0 || Number(sizeBytes) > MAX_TEXTURE_BYTES) {
+        fail(`${label}.sizeBytes`, `must be a positive safe integer no greater than ${MAX_TEXTURE_BYTES}.`);
+    }
+    const colorInput = record(input.colorSpace, `${label}.colorSpace`);
+    exactKeys(colorInput, [], ['srgb', 'compressionSettings', 'flipGreenChannel'], `${label}.colorSpace`);
+    const colorSpace = {};
+    if (Object.hasOwn(colorInput, 'srgb')) {
+        if (typeof colorInput.srgb !== 'boolean')
+            fail(`${label}.colorSpace.srgb`, 'must be a boolean.');
+        colorSpace.srgb = colorInput.srgb;
+    }
+    if (Object.hasOwn(colorInput, 'flipGreenChannel')) {
+        if (typeof colorInput.flipGreenChannel !== 'boolean') {
+            fail(`${label}.colorSpace.flipGreenChannel`, 'must be a boolean.');
+        }
+        colorSpace.flipGreenChannel = colorInput.flipGreenChannel;
+    }
+    if (Object.hasOwn(colorInput, 'compressionSettings')) {
+        colorSpace.compressionSettings = stringValue(colorInput.compressionSettings, `${label}.colorSpace.compressionSettings`);
+    }
+    return {
+        sourceAssetPath: unrealPath(input.sourceAssetPath, `${label}.sourceAssetPath`),
+        path,
+        sha256,
+        sizeBytes: Number(sizeBytes),
+        colorSpace,
+    };
+}
+function parseSlot(value, expectedIndex) {
+    const label = `materials[${expectedIndex}]`;
+    const input = record(value, label);
+    exactKeys(input, [
+        'slotIndex',
+        'slotName',
+        'importedSlotName',
+        'sourceMaterialAssetPath',
+        'sourceRootMaterialAssetPath',
+        'parameters',
+    ], [], label);
+    if (input.slotIndex !== expectedIndex)
+        fail(`${label}.slotIndex`, `must equal ordered slot index ${expectedIndex}.`);
+    const parameters = record(input.parameters, `${label}.parameters`);
+    exactKeys(parameters, ['scalars', 'vectors', 'textures'], [], `${label}.parameters`);
+    const scalars = Object.fromEntries(parameterEntries(parameters.scalars, `${label}.parameters.scalars`)
+        .map(([name, entry]) => [name, finiteNumber(entry, `${label}.parameters.scalars.${name}`)]));
+    const vectors = Object.fromEntries(parameterEntries(parameters.vectors, `${label}.parameters.vectors`)
+        .map(([name, entry]) => {
+        const vector = record(entry, `${label}.parameters.vectors.${name}`);
+        exactKeys(vector, ['r', 'g', 'b', 'a'], [], `${label}.parameters.vectors.${name}`);
+        return [name, {
+                r: finiteNumber(vector.r, `${label}.parameters.vectors.${name}.r`),
+                g: finiteNumber(vector.g, `${label}.parameters.vectors.${name}.g`),
+                b: finiteNumber(vector.b, `${label}.parameters.vectors.${name}.b`),
+                a: finiteNumber(vector.a, `${label}.parameters.vectors.${name}.a`),
+            }];
+    }));
+    const textures = Object.fromEntries(parameterEntries(parameters.textures, `${label}.parameters.textures`)
+        .map(([name, entry]) => [name, parseTextureRecord(entry, `${label}.parameters.textures.${name}`)]));
+    return {
+        slotIndex: expectedIndex,
+        slotName: stringValue(input.slotName, `${label}.slotName`, true),
+        importedSlotName: stringValue(input.importedSlotName, `${label}.importedSlotName`, true),
+        sourceMaterialAssetPath: unrealPath(input.sourceMaterialAssetPath, `${label}.sourceMaterialAssetPath`),
+        sourceRootMaterialAssetPath: unrealPath(input.sourceRootMaterialAssetPath, `${label}.sourceRootMaterialAssetPath`),
+        parameters: { scalars, vectors, textures },
+    };
+}
+function parseSidecar(value, expectedSlug) {
+    const input = record(value, 'root');
+    exactKeys(input, ['schemaVersion', 'asset', 'materials'], [], 'root');
+    if (input.schemaVersion !== exports.UNREAL_MATERIAL_SIDECAR_SCHEMA) {
+        fail('root.schemaVersion', `must equal ${exports.UNREAL_MATERIAL_SIDECAR_SCHEMA}.`);
+    }
+    const asset = record(input.asset, 'asset');
+    exactKeys(asset, ['slug', 'sourceMeshAssetPath'], [], 'asset');
+    const slug = stringValue(asset.slug, 'asset.slug');
+    if (!SLUG.test(slug) || slug !== expectedSlug) {
+        fail('asset.slug', `must equal adjacent FBX basename ${JSON.stringify(expectedSlug)}.`);
+    }
+    if (!Array.isArray(input.materials) || input.materials.length === 0 || input.materials.length > MAX_MATERIALS) {
+        fail('materials', `must contain between 1 and ${MAX_MATERIALS} ordered slots.`);
+    }
+    return {
+        schemaVersion: exports.UNREAL_MATERIAL_SIDECAR_SCHEMA,
+        asset: {
+            slug,
+            sourceMeshAssetPath: unrealPath(asset.sourceMeshAssetPath, 'asset.sourceMeshAssetPath'),
+        },
+        materials: input.materials.map(parseSlot),
+    };
+}
+async function readRegularFile(path, maxBytes, label) {
+    let before;
+    try {
+        before = await (0, promises_1.lstat)(path);
+    }
+    catch (error) {
+        return fail(label, `cannot be read: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    if (before.isSymbolicLink())
+        fail(label, 'must not be a symbolic link.');
+    if (!before.isFile())
+        fail(label, 'must be a regular file.');
+    if (before.size <= 0 || before.size > maxBytes)
+        fail(label, `must contain between 1 and ${maxBytes} bytes.`);
+    const noFollow = process.platform === 'win32' ? 0 : node_fs_1.constants.O_NOFOLLOW;
+    let handle;
+    try {
+        handle = await (0, promises_1.open)(path, node_fs_1.constants.O_RDONLY | noFollow);
+    }
+    catch (error) {
+        return fail(label, `cannot be opened without following links: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    try {
+        const after = await handle.stat();
+        if (!after.isFile() || after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size) {
+            fail(label, 'changed while it was being verified.');
+        }
+        const bytes = Buffer.allocUnsafe(after.size);
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+            if (bytesRead === 0)
+                fail(label, 'was truncated while it was being verified.');
+            offset += bytesRead;
+        }
+        const final = await handle.stat();
+        if (final.dev !== after.dev || final.ino !== after.ino || final.size !== after.size) {
+            fail(label, 'changed while it was being read.');
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Returns the only accepted adjacent sidecar path for an FBX source. */
+function unrealMaterialSidecarPath(fbxPath) {
+    const absolute = (0, node_path_1.resolve)(fbxPath);
+    if ((0, node_path_1.extname)(absolute).toLowerCase() !== '.fbx')
+        fail('FBX path', 'must end in .fbx.');
+    return (0, node_path_1.join)((0, node_path_1.dirname)(absolute), `${(0, node_path_1.basename)(absolute, (0, node_path_1.extname)(absolute))}.materials.json`);
+}
+/** Reads and fully verifies one adjacent Unreal material sidecar and every referenced PNG. */
+async function loadUnrealMaterialSidecar(fbxPath) {
+    const sidecarPath = unrealMaterialSidecarPath(fbxPath);
+    const expectedSlug = (0, node_path_1.basename)(sidecarPath, '.materials.json');
+    const bytes = await readRegularFile(sidecarPath, MAX_SIDECAR_BYTES, 'file');
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch (error) {
+        return fail('file', `is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    const value = parseSidecar(json, expectedSlug);
+    const textureBytes = new Map();
+    const records = new Map();
+    for (const slot of value.materials) {
+        for (const texture of Object.values(slot.parameters.textures)) {
+            const previous = records.get(texture.sha256);
+            if (previous !== undefined) {
+                if (previous.path !== texture.path || previous.sizeBytes !== texture.sizeBytes) {
+                    fail(`texture ${texture.sha256}`, 'has conflicting content-address metadata.');
+                }
+                continue;
+            }
+            records.set(texture.sha256, texture);
+        }
+    }
+    const totalBytes = [...records.values()].reduce((sum, texture) => sum + texture.sizeBytes, 0);
+    if (!Number.isSafeInteger(totalBytes) || totalBytes > MAX_TOTAL_TEXTURE_BYTES) {
+        fail('textures', `exceed the ${MAX_TOTAL_TEXTURE_BYTES}-byte verified input budget.`);
+    }
+    if (records.size > 0) {
+        const texturesDirectory = (0, node_path_1.join)((0, node_path_1.dirname)(sidecarPath), 'textures');
+        let textureDirectoryStat;
+        try {
+            textureDirectoryStat = await (0, promises_1.lstat)(texturesDirectory);
+        }
+        catch (error) {
+            return fail('textures directory', `cannot be read: ${error instanceof Error ? error.message : String(error)}.`);
+        }
+        if (textureDirectoryStat.isSymbolicLink() || !textureDirectoryStat.isDirectory()) {
+            fail('textures directory', 'must be a real directory, not a symbolic link.');
+        }
+        for (const texture of [...records.values()].sort((left, right) => compareCodePoint(left.sha256, right.sha256))) {
+            const path = (0, node_path_1.join)((0, node_path_1.dirname)(sidecarPath), texture.path);
+            const image = await readRegularFile(path, MAX_TEXTURE_BYTES, `texture ${texture.sha256}`);
+            if (image.byteLength !== texture.sizeBytes)
+                fail(`texture ${texture.sha256}`, 'does not match its declared size.');
+            if (!Buffer.from(image.subarray(0, PNG_SIGNATURE.byteLength)).equals(PNG_SIGNATURE)) {
+                fail(`texture ${texture.sha256}`, 'is not a PNG.');
+            }
+            preflightPngDimensions(image, `texture ${texture.sha256}`);
+            const digest = (0, hash_1.sha256Bytes)(image);
+            if (digest !== texture.sha256)
+                fail(`texture ${texture.sha256}`, `has content digest ${digest}.`);
+            textureBytes.set(texture.sha256, image);
+        }
+    }
+    return { sidecarPath, value, textureBytes };
+}
+/**
+ * Lists every adjacent file whose bytes can affect Unreal material translation.
+ * Bridge binds these relative paths into its reviewed plan before snapshotting or execution.
+ */
+async function discoverUnrealMaterialSidecarDependencies(fbxPath) {
+    const sidecarPath = unrealMaterialSidecarPath(fbxPath);
+    try {
+        await (0, promises_1.lstat)(sidecarPath);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : null;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return [];
+        throw error;
+    }
+    const expectedSlug = (0, node_path_1.basename)(sidecarPath, '.materials.json');
+    const bytes = await readRegularFile(sidecarPath, MAX_SIDECAR_BYTES, 'file');
+    let json;
+    try {
+        json = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch (error) {
+        return fail('file', `is not valid JSON: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    const value = parseSidecar(json, expectedSlug);
+    const textures = value.materials.flatMap((slot) => Object.values(slot.parameters.textures).map((texture) => texture.path));
+    return [(0, node_path_1.basename)(sidecarPath), ...new Set(textures)].sort();
+}
+function normalizedName(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+function objectName(path) {
+    const leaf = path.slice(path.lastIndexOf('/') + 1);
+    return leaf.includes('.') ? leaf.slice(leaf.lastIndexOf('.') + 1) : leaf;
+}
+/**
+ * `isFirstOccurrence` says whether this is the FIRST slot (in ascending `slotIndex` order) in the
+ * whole sidecar to reference this slot's `sourceMaterialAssetPath`. Multiple Unreal material SLOTS
+ * routinely point at the same underlying material ASSET (e.g. every one of hair_a1..a21's 5 slots
+ * is a distinct instance of the shared `MI_HairMaster` parent, or several slots on a single outfit
+ * reusing one stitching-detail instance) — Unreal's own per-instance slot name (`importedSlotName`,
+ * e.g. `MI_HairsD`) is normally enough to disambiguate them, but the FBX EXPORT step does not
+ * preserve that instance name: it dedups repeated document material names with an Assimp-style `_N`
+ * numeric suffix instead, and empirically (verified against both the hair and firefighter-outfit
+ * sidecars via a live FBXLoader probe) `N` is the DUPLICATE slot's own `slotIndex` — not a running
+ * count local to the duplicate group — so `M_Stitches_Inst3` used by slots 6/7/8 exports as
+ * `M_Stitches_Inst3`, `M_Stitches_Inst3_7`, `M_Stitches_Inst3_8`, never `_1`/`_2`. Only the FIRST
+ * occurrence keeps the bare name; `objectName(sourceMaterialAssetPath)` alone can never produce the
+ * suffixed forms, so this adds the slotIndex-suffixed alias for every later occurrence.
+ */
+function slotAliases(slot, isFirstOccurrence) {
+    const objectBase = objectName(slot.sourceMaterialAssetPath);
+    return new Set([
+        slot.slotName,
+        slot.importedSlotName,
+        objectBase,
+        isFirstOccurrence ? null : `${objectBase}_${slot.slotIndex}`,
+    ].map((value) => (value === null ? '' : normalizedName(value))).filter(Boolean));
+}
+/** Stable comparison of two slots' resolved Unreal parameters: the same material asset resolved twice. */
+function sameParameters(a, b) {
+    return JSON.stringify(a.parameters) === JSON.stringify(b.parameters);
+}
+/**
+ * Pairs each sidecar slot with the document material it describes.
+ *
+ * THREE passes, in order, because a document material may legitimately serve more than one slot:
+ *
+ *  1. By SLOT INDEX — the document material at the slot's own index, when its name is one of the slot's
+ *     aliases.
+ *  2. By NAME — exactly one unclaimed document material whose name matches an alias.
+ *  3. By MATERIAL IDENTITY — an earlier slot with the SAME `sourceMaterialAssetPath` already matched a
+ *     document material, so this slot is a second reference to that one material. This is not a fallback
+ *     for sloppiness: an Unreal mesh routinely carries a leftover material slot that no triangle uses
+ *     (a template mesh's slot, e.g. Hell_X's backpack/gloves/turtleneck all keep an unused "Jacket" slot
+ *     whose interface is the SAME asset as the used one, verified 2026-09-28). The FBX exporter writes both
+ *     materials, the FBX->GLB conversion keeps only the referenced one, and the one-material document then
+ *     has nothing left to pair with the second slot. Merging is only allowed when the two slots' resolved
+ *     parameters are IDENTICAL — the same material resolved twice — because a document with one material and
+ *     two DIFFERENT parameter sets cannot be satisfied by either choice, and that must fail loudly rather
+ *     than silently drop a look.
+ *
+ * Failures name the reason: no unclaimed material matches, several do, or the identity merge was refused.
+ */
+function matchMaterials(document, sidecar) {
+    const materials = document.getRoot().listMaterials();
+    const claimed = new Set();
+    const firstSlotIndexByAssetPath = new Map();
+    for (const slot of sidecar.materials) {
+        const existing = firstSlotIndexByAssetPath.get(slot.sourceMaterialAssetPath);
+        if (existing === undefined || slot.slotIndex < existing) {
+            firstSlotIndexByAssetPath.set(slot.sourceMaterialAssetPath, slot.slotIndex);
+        }
+    }
+    const matchedByAssetPath = new Map();
+    return sidecar.materials.map((slot) => {
+        const isFirstOccurrence = firstSlotIndexByAssetPath.get(slot.sourceMaterialAssetPath) === slot.slotIndex;
+        const aliases = slotAliases(slot, isFirstOccurrence);
+        const positional = materials[slot.slotIndex];
+        if (positional !== undefined && !claimed.has(positional) && aliases.has(normalizedName(positional.getName()))) {
+            claimed.add(positional);
+            const match = { slot, material: positional };
+            if (!matchedByAssetPath.has(slot.sourceMaterialAssetPath))
+                matchedByAssetPath.set(slot.sourceMaterialAssetPath, match);
+            return match;
+        }
+        const candidates = materials.filter((material) => !claimed.has(material) && aliases.has(normalizedName(material.getName())));
+        if (candidates.length > 1) {
+            fail(`materials[${slot.slotIndex}]`, `has ambiguous document material names (${candidates.map((entry) => entry.getName()).join(', ')}).`);
+        }
+        if (candidates.length === 1) {
+            claimed.add(candidates[0]);
+            const match = { slot, material: candidates[0] };
+            if (!matchedByAssetPath.has(slot.sourceMaterialAssetPath))
+                matchedByAssetPath.set(slot.sourceMaterialAssetPath, match);
+            return match;
+        }
+        // Material identity: the same Unreal material asset, already applied to a document material.
+        const previous = matchedByAssetPath.get(slot.sourceMaterialAssetPath);
+        if (previous !== undefined) {
+            if (!sameParameters(previous.slot, slot)) {
+                fail(`materials[${slot.slotIndex}]`, `shares material asset ${objectName(slot.sourceMaterialAssetPath)} with materials[${previous.slot.slotIndex}], `
+                    + `but that slot already took the document's only material for it ('${previous.material.getName()}') and the two slots `
+                    + 'resolve to DIFFERENT parameters — the document has no separate material for this slot, so neither choice would be right.');
+            }
+            return { slot, material: previous.material, sharedWithSlotIndex: previous.slot.slotIndex };
+        }
+        fail(`materials[${slot.slotIndex}]`, `cannot match a document material by slot index, name (${[...aliases].join(', ')}) or shared material asset `
+            + `(${objectName(slot.sourceMaterialAssetPath)}) — the document has ${materials.length} material(s).`);
+    });
+}
+function selectParameter(values, aliases, label, identity) {
+    const aliasOrder = new Map(aliases.map((alias, index) => [normalizedName(alias), index]));
+    const candidates = Object.entries(values)
+        .filter(([name]) => aliasOrder.has(normalizedName(name)))
+        .sort(([left], [right]) => aliasOrder.get(normalizedName(left)) - aliasOrder.get(normalizedName(right)) || compareCodePoint(left, right));
+    const bestRank = candidates[0] === undefined ? undefined : aliasOrder.get(normalizedName(candidates[0][0]));
+    const preferred = bestRank === undefined
+        ? []
+        : candidates.filter(([name]) => aliasOrder.get(normalizedName(name)) === bestRank);
+    const names = new Set(preferred.map(([name]) => name));
+    const identities = new Set(preferred.map(([, value]) => identity(value)));
+    if (identities.size > 1)
+        fail(label, `has ambiguous preferred bindings: ${preferred.map(([name]) => name).join(', ')}.`);
+    return { value: preferred[0]?.[1], names };
+}
+function numericIdentity(value) {
+    return Object.is(value, -0) ? '-0' : String(value);
+}
+function vectorIdentity(value) {
+    return [value.r, value.g, value.b, value.a].map(numericIdentity).join(',');
+}
+function boundedFactor(value, label) {
+    if (value !== undefined && (value < 0 || value > 1))
+        fail(label, 'must be between 0 and 1 for portable PBR.');
+    return value;
+}
+function rgbaFactor(value, label) {
+    if (value === undefined)
+        return undefined;
+    const result = [value.r, value.g, value.b, value.a];
+    if (result.some((channel) => channel < 0 || channel > 1))
+        fail(label, 'must use channels between 0 and 1.');
+    return result;
+}
+function planSlots(document, sidecar) {
+    return matchMaterials(document, sidecar).map(({ slot, material, sharedWithSlotIndex }) => {
+        const identity = normalizedName([
+            slot.slotName,
+            slot.importedSlotName,
+            slot.sourceMaterialAssetPath,
+            slot.sourceRootMaterialAssetPath,
+        ].join(' '));
+        const isEyelash = identity.includes('eyelash');
+        const isEyeWater = identity.includes('eyewater') || identity.includes('lacrimal');
+        const isEyeOcclusion = identity.includes('eyeao') || identity.includes('eyeocclusion');
+        const isEye = identity.includes('eye') && !isEyelash && !isEyeWater && !isEyeOcclusion;
+        const isFaceSkin = identity.includes('skinface') || identity.includes('skinhead');
+        const isBodySkin = identity.includes('skinbody');
+        const isApparel = identity.includes('basematerialapparel');
+        const isMasked = identity.includes('masked');
+        const isHair = (identity.includes('hair') || identity.includes('beard'))
+            && !identity.includes('eyelash')
+            && !identity.includes('eyebrow');
+        // Unreal's eye shader composes iris and sclera maps procedurally; treating either source map as a
+        // complete glTF base color produces a broken eye. Leave it unbound so the character composer can
+        // install HELIX's proven portable eye bake. For CCMH face skin, Color_Main is the head albedo while
+        // Body Color Map is deliberately a different body texture used only by the source shader.
+        const baseAliases = isEye ? [] : [
+            ...(isFaceSkin ? ['Color_Main', 'Base Color', 'BaseColor', 'Body Color Map'] : [
+                'BaseColor',
+                'Base Color',
+                'Base Color Map',
+                'Body Color Map',
+                'Color_Main',
+            ]),
+            'Albedo',
+            'Albedo Map',
+            'Diffuse',
+            'Diffuse Map',
+            ...((isHair || isEyelash) ? ['Texture'] : []),
+        ];
+        const baseColor = selectParameter(slot.parameters.textures, baseAliases, `materials[${slot.slotIndex}] base color`, (value) => value.sha256);
+        const normal = selectParameter(slot.parameters.textures, ['Normal', 'Normal Map', 'Base Normal'], `materials[${slot.slotIndex}] normal`, (value) => value.sha256);
+        const orm = selectParameter(slot.parameters.textures, ['ORM', 'Packed ORM', 'Occlusion Roughness Metallic', 'Ambient Occlusion Roughness Metallic'], `materials[${slot.slotIndex}] ORM`, (value) => value.sha256);
+        // Unreal trim materials (MM_Stitches) feed an OCCLUSION map into their "Diffuse" input and colour it
+        // with a Tint, cutting the strip out with a separate Alpha texture. Bound as a glTF base colour
+        // unchanged, that packed map renders its false colours (magenta stitching) across the whole strip.
+        const baseIsOcclusion = baseColor.value !== undefined
+            && /(?:^|[_./])(?:OCC|AO|Occlusion)(?:[_.]|$)/i.test(baseColor.value.sourceAssetPath);
+        const cutout = selectParameter(slot.parameters.textures, ['Alpha'], `materials[${slot.slotIndex}] cutout`, (value) => value.sha256);
+        if (baseColor.value?.colorSpace.srgb === false) {
+            fail(`materials[${slot.slotIndex}] base color`, 'references a texture explicitly marked as linear.');
+        }
+        if (normal.value?.colorSpace.srgb === true) {
+            fail(`materials[${slot.slotIndex}] normal`, 'references a texture explicitly marked as sRGB.');
+        }
+        const tintAliases = isEye
+            ? ['Eye Color', 'Tint', 'Base Color Tint', 'BaseColorTint']
+            : isHair
+                ? ['Hair Tint', 'Tint', 'Base Color Tint', 'BaseColorTint']
+                : ['Tint', 'Base Color Tint', 'BaseColorTint', 'Base Color', 'BaseColor', 'Color'];
+        let tint = rgbaFactor(selectParameter(slot.parameters.vectors, tintAliases, `materials[${slot.slotIndex}] tint`, vectorIdentity).value, `materials[${slot.slotIndex}] tint`);
+        if (isEyeWater || isHair || isEyelash || isMasked) {
+            const opacity = boundedFactor(selectParameter(slot.parameters.scalars, ['Opacity'], `materials[${slot.slotIndex}] opacity`, numericIdentity).value, `materials[${slot.slotIndex}] opacity`);
+            if (opacity !== undefined) {
+                const current = tint ?? material.getBaseColorFactor();
+                tint = [current[0], current[1], current[2], opacity];
+            }
+        }
+        const roughnessAliases = isEye
+            ? ['Roughness', 'Roughness Offset', 'IrisRoughness', 'ScleraRougness']
+            : ['Roughness', 'Roughness Scale', 'Roughness Offset'];
+        const roughnessSelection = selectParameter(slot.parameters.scalars, roughnessAliases, `materials[${slot.slotIndex}] roughness`, numericIdentity);
+        let roughness = boundedFactor(roughnessSelection.value, `materials[${slot.slotIndex}] roughness`);
+        // Apparel's "Roughness Offset" modifies a packed source map; zero means
+        // neutral, not mirror-smooth. When the packed channel layout is unknown and
+        // intentionally left unmapped, use a conservative cloth/leather fallback.
+        if (isApparel
+            && roughness === 0
+            && [...roughnessSelection.names].some((name) => normalizedName(name) === 'roughnessoffset')) {
+            roughness = 0.7;
+        }
+        if ((isFaceSkin || isBodySkin) && roughness === undefined)
+            roughness = 0.5;
+        let metallic = boundedFactor(selectParameter(slot.parameters.scalars, ['Metallic', 'Metallic Offset'], `materials[${slot.slotIndex}] metallic`, numericIdentity).value, `materials[${slot.slotIndex}] metallic`);
+        // Unreal's lacrimal shader uses metallic as a lighting trick. Portable PBR
+        // eye water is dielectric.
+        if (isEyeWater)
+            metallic = 0;
+        const alphaMode = isEyeWater
+            ? 'BLEND'
+            : (isHair || isEyelash || isMasked || cutout.value !== undefined) ? 'MASK' : undefined;
+        const consumed = new Set([...baseColor.names, ...normal.names, ...orm.names, ...cutout.names]);
+        const unmappedTextureParameters = Object.keys(slot.parameters.textures)
+            .filter((name) => !consumed.has(name))
+            .sort();
+        return {
+            slot,
+            material,
+            baseColor,
+            normal,
+            orm,
+            cutout,
+            baseIsOcclusion,
+            tint,
+            roughness,
+            metallic,
+            alphaMode,
+            unmappedTextureParameters,
+            ...(sharedWithSlotIndex === undefined ? {} : { sharedWithSlotIndex }),
+        };
+    });
+}
+/**
+ * Derives the portable base-colour image for a slot whose Unreal inputs are not a plain albedo:
+ * an occlusion map becomes grey (its red channel), and a dedicated cutout texture becomes alpha (its
+ * red channel, resampled to the base image's size). The Unreal Tint stays a glTF baseColorFactor.
+ */
+async function deriveBaseColorPng(base, occlusion, cutout) {
+    const limits = { limitInputPixels: imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS };
+    let width, height, data;
+    if (base !== undefined) {
+        const decoded = await (0, sharp_1.default)(Buffer.from(base), limits).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+        ({ width, height } = decoded.info);
+        data = decoded.data;
+    }
+    else {
+        const meta = await (0, sharp_1.default)(Buffer.from(cutout), limits).metadata();
+        width = meta.width;
+        height = meta.height;
+        data = Buffer.alloc(width * height * 4, 255);
+    }
+    if (occlusion) {
+        for (let offset = 0; offset < data.length; offset += 4) {
+            data[offset + 1] = data[offset];
+            data[offset + 2] = data[offset];
+        }
+    }
+    if (cutout !== undefined) {
+        const mask = await (0, sharp_1.default)(Buffer.from(cutout), limits)
+            .resize(width, height, { fit: 'fill' })
+            .ensureAlpha()
+            .raw()
+            .toBuffer();
+        for (let pixel = 0; pixel < width * height; pixel += 1)
+            data[pixel * 4 + 3] = mask[pixel * 4];
+    }
+    return (0, sharp_1.default)(data, { raw: { width, height, channels: 4 } }).png().toBuffer();
+}
+function textureName(sha256) {
+    return `HELIX_UE_${sha256}`;
+}
+function srgbByteToLinear(value) {
+    const channel = value / 255;
+    const linear = channel <= 0.04045
+        ? channel / 12.92
+        : ((channel + 0.055) / 1.055) ** 2.4;
+    return Math.round(linear * 255);
+}
+async function linearizeSrgbPng(image) {
+    const decoded = await (0, sharp_1.default)(Buffer.from(image))
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    for (let offset = 0; offset < decoded.data.length; offset += 4) {
+        decoded.data[offset] = srgbByteToLinear(decoded.data[offset]);
+        decoded.data[offset + 1] = srgbByteToLinear(decoded.data[offset + 1]);
+        decoded.data[offset + 2] = srgbByteToLinear(decoded.data[offset + 2]);
+    }
+    return (0, sharp_1.default)(decoded.data, {
+        raw: {
+            width: decoded.info.width,
+            height: decoded.info.height,
+            channels: 4,
+        },
+    }).png().toBuffer();
+}
+/**
+ * Unreal authors tangent-space normal maps in the DirectX convention (+Y = down the image); glTF
+ * requires +Y = up. With UVs in glTF's top-left convention both share the image orientation, so the
+ * conversion is exactly an inverted green channel.
+ */
+async function directXNormalPngToGltf(image) {
+    const decoded = await (0, sharp_1.default)(Buffer.from(image), { limitInputPixels: imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS })
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    for (let offset = 1; offset < decoded.data.length; offset += 4) {
+        decoded.data[offset] = 255 - decoded.data[offset];
+    }
+    return (0, sharp_1.default)(decoded.data, {
+        raw: { width: decoded.info.width, height: decoded.info.height, channels: 4 },
+    }).png().toBuffer();
+}
+function preflightDocumentTextures(document, textureBytes, needed) {
+    const textures = new Map();
+    const documentTexturesByName = new Map();
+    for (const texture of document.getRoot().listTextures()) {
+        const named = documentTexturesByName.get(texture.getName()) ?? [];
+        named.push(texture);
+        documentTexturesByName.set(texture.getName(), named);
+    }
+    for (const sha256 of [...needed].sort()) {
+        const named = documentTexturesByName.get(textureName(sha256)) ?? [];
+        if (named.length > 1)
+            fail(`document texture ${sha256}`, 'has ambiguous duplicate deterministic names.');
+        const existing = named[0];
+        if (existing !== undefined) {
+            const image = existing.getImage();
+            const digest = image === null ? null : (0, hash_1.sha256Bytes)(image);
+            if (existing.getMimeType() !== 'image/png' || digest !== sha256) {
+                fail(`document texture ${sha256}`, 'conflicts with a pre-existing deterministic texture name.');
+            }
+            textures.set(sha256, existing);
+            continue;
+        }
+        if (!textureBytes.has(sha256))
+            fail(`texture ${sha256}`, 'was not verified before application.');
+    }
+    return textures;
+}
+/**
+ * Unreal's FBX exporter can emit an unauthored, all-zero COLOR_0 stream. glTF
+ * multiplies it into base color, blacking out otherwise valid sidecar textures.
+ * This cleanup runs only after the Unreal sidecar and all of its dependencies
+ * have been verified; generic FBX vertex colors are never inferred or changed.
+ */
+function stripEmptyUnrealVertexColors(document) {
+    let stripped = 0;
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives()) {
+            const color = primitive.getAttribute('COLOR_0');
+            const values = color?.getArray();
+            if (color === null || values === null || values.length === 0)
+                continue;
+            let allZero = true;
+            for (let index = 0; index < values.length; index += 1) {
+                if (values[index] !== 0) {
+                    allZero = false;
+                    break;
+                }
+            }
+            if (!allZero)
+                continue;
+            primitive.setAttribute('COLOR_0', null);
+            stripped += 1;
+        }
+    }
+    if (stripped > 0) {
+        console.warn(`Unreal material sidecar: removed ${stripped} empty COLOR_0 attribute(s).`);
+    }
+    return stripped;
+}
+/**
+ * Applies a verified adjacent Unreal sidecar to a glTF-Transform Document.
+ * Validation and binding planning complete before the Document is mutated.
+ */
+async function applyUnrealMaterialSidecar(document, fbxPath) {
+    const loaded = await loadUnrealMaterialSidecar(fbxPath);
+    const plans = planSlots(document, loaded.value);
+    const verifiedTextureCount = loaded.textureBytes.size;
+    const availableTextureBytes = new Map(loaded.textureBytes);
+    const linearOrmDigests = new Map();
+    for (const plan of plans) {
+        const orm = plan.orm.value;
+        if (orm === undefined || orm.colorSpace.srgb !== true || linearOrmDigests.has(orm.sha256))
+            continue;
+        const linearImage = await linearizeSrgbPng(loaded.textureBytes.get(orm.sha256));
+        const linearDigest = (0, hash_1.sha256Bytes)(linearImage);
+        const previous = availableTextureBytes.get(linearDigest);
+        if (previous !== undefined && !Buffer.from(previous).equals(Buffer.from(linearImage))) {
+            fail(`texture ${orm.sha256}`, `linear conversion conflicts with content digest ${linearDigest}.`);
+        }
+        availableTextureBytes.set(linearDigest, linearImage);
+        linearOrmDigests.set(orm.sha256, linearDigest);
+    }
+    const derivedBaseDigests = new Map();
+    for (const plan of plans) {
+        const cutout = plan.cutout.value;
+        if (!plan.baseIsOcclusion && cutout === undefined)
+            continue;
+        const derived = await deriveBaseColorPng(plan.baseColor.value === undefined ? undefined : loaded.textureBytes.get(plan.baseColor.value.sha256), plan.baseIsOcclusion, cutout === undefined ? undefined : loaded.textureBytes.get(cutout.sha256));
+        const digest = (0, hash_1.sha256Bytes)(derived);
+        const previous = availableTextureBytes.get(digest);
+        if (previous !== undefined && !Buffer.from(previous).equals(Buffer.from(derived))) {
+            fail(`materials[${plan.slot.slotIndex}] base colour`, `derived image conflicts with content digest ${digest}.`);
+        }
+        availableTextureBytes.set(digest, derived);
+        derivedBaseDigests.set(plan, digest);
+    }
+    const gltfNormalDigests = new Map();
+    for (const plan of plans) {
+        const normal = plan.normal.value;
+        if (normal === undefined || normal.colorSpace.flipGreenChannel === true || gltfNormalDigests.has(normal.sha256))
+            continue;
+        const converted = await directXNormalPngToGltf(loaded.textureBytes.get(normal.sha256));
+        const convertedDigest = (0, hash_1.sha256Bytes)(converted);
+        const previous = availableTextureBytes.get(convertedDigest);
+        if (previous !== undefined && !Buffer.from(previous).equals(Buffer.from(converted))) {
+            fail(`texture ${normal.sha256}`, `normal convention conversion conflicts with content digest ${convertedDigest}.`);
+        }
+        availableTextureBytes.set(convertedDigest, converted);
+        gltfNormalDigests.set(normal.sha256, convertedDigest);
+    }
+    const normalDigest = (binding) => gltfNormalDigests.get(binding.sha256) ?? binding.sha256;
+    const needed = new Set();
+    for (const plan of plans) {
+        const derivedBase = derivedBaseDigests.get(plan);
+        if (derivedBase !== undefined)
+            needed.add(derivedBase);
+        else if (plan.baseColor.value !== undefined)
+            needed.add(plan.baseColor.value.sha256);
+        if (plan.normal.value !== undefined)
+            needed.add(normalDigest(plan.normal.value));
+        if (plan.orm.value !== undefined) {
+            needed.add(linearOrmDigests.get(plan.orm.value.sha256) ?? plan.orm.value.sha256);
+        }
+    }
+    const textures = preflightDocumentTextures(document, availableTextureBytes, needed);
+    stripEmptyUnrealVertexColors(document);
+    let createdTextureCount = 0;
+    for (const sha256 of [...needed].sort()) {
+        if (textures.has(sha256))
+            continue;
+        const image = availableTextureBytes.get(sha256);
+        const texture = document.createTexture(textureName(sha256))
+            .setImage(image)
+            .setMimeType('image/png');
+        textures.set(sha256, texture);
+        createdTextureCount += 1;
+    }
+    loaded.textureBytes.clear();
+    availableTextureBytes.clear();
+    const appliedSlots = plans.map((plan) => {
+        const baseColorTexture = plan.baseColor.value;
+        const normalTexture = plan.normal.value;
+        const ormTexture = plan.orm.value;
+        const derivedBase = derivedBaseDigests.get(plan);
+        if (derivedBase !== undefined) {
+            plan.material.setBaseColorTexture(textures.get(derivedBase));
+            plan.material.setBaseColorFactor(plan.tint ?? [1, 1, 1, 1]);
+        }
+        else if (baseColorTexture !== undefined) {
+            plan.material.setBaseColorTexture(textures.get(baseColorTexture.sha256));
+            plan.material.setBaseColorFactor(plan.tint ?? [1, 1, 1, 1]);
+        }
+        else if (plan.tint !== undefined) {
+            plan.material.setBaseColorFactor(plan.tint);
+        }
+        if (normalTexture !== undefined)
+            plan.material.setNormalTexture(textures.get(normalDigest(normalTexture)));
+        if (ormTexture !== undefined) {
+            const texture = textures.get(linearOrmDigests.get(ormTexture.sha256) ?? ormTexture.sha256);
+            plan.material.setMetallicRoughnessTexture(texture).setOcclusionTexture(texture);
+            if (plan.roughness === undefined)
+                plan.material.setRoughnessFactor(1);
+            if (plan.metallic === undefined)
+                plan.material.setMetallicFactor(1);
+        }
+        if (plan.roughness !== undefined)
+            plan.material.setRoughnessFactor(plan.roughness);
+        if (plan.metallic !== undefined)
+            plan.material.setMetallicFactor(plan.metallic);
+        if (plan.alphaMode !== undefined) {
+            plan.material.setAlphaMode(plan.alphaMode);
+            if (plan.alphaMode === 'MASK')
+                plan.material.setAlphaCutoff(0.5).setDoubleSided(true);
+        }
+        return {
+            slotIndex: plan.slot.slotIndex,
+            materialName: plan.material.getName(),
+            ...(plan.sharedWithSlotIndex === undefined ? {} : { sharedWithSlotIndex: plan.sharedWithSlotIndex }),
+            ...(baseColorTexture === undefined ? {} : { baseColorTextureSha256: baseColorTexture.sha256 }),
+            ...(normalTexture === undefined ? {} : { normalTextureSha256: normalTexture.sha256 }),
+            ...(ormTexture === undefined ? {} : { ormTextureSha256: ormTexture.sha256 }),
+            ...(ormTexture?.colorSpace.srgb === true ? { ormColorSpaceConversion: 'srgb-to-linear' } : {}),
+            ...(plan.baseIsOcclusion ? { baseColorConversion: 'occlusion-red-to-grey' } : {}),
+            ...(plan.cutout.value === undefined ? {} : { cutoutTextureSha256: plan.cutout.value.sha256 }),
+            ...(normalTexture !== undefined && gltfNormalDigests.has(normalTexture.sha256)
+                ? { normalConventionConversion: 'directx-to-gltf' }
+                : {}),
+            ...(plan.tint === undefined && baseColorTexture === undefined
+                ? {}
+                : { baseColorFactor: plan.tint ?? [1, 1, 1, 1] }),
+            ...(plan.roughness === undefined ? {} : { roughnessFactor: plan.roughness }),
+            ...(plan.metallic === undefined ? {} : { metallicFactor: plan.metallic }),
+            ...(plan.alphaMode === undefined ? {} : { alphaMode: plan.alphaMode }),
+            unmappedTextureParameters: plan.unmappedTextureParameters,
+        };
+    });
+    return {
+        schemaVersion: exports.UNREAL_MATERIAL_SIDECAR_SCHEMA,
+        sidecarPath: loaded.sidecarPath,
+        sourceMeshAssetPath: loaded.value.asset.sourceMeshAssetPath,
+        appliedSlots,
+        // Distinct document materials the sidecar did not touch — `appliedSlots` has one entry per UNREAL slot,
+        // and several slots can share one document material (see `matchMaterials`), so counting entries would
+        // report a negative "preserved" number for an item like Hell_X's backpack.
+        preservedMaterialCount: document.getRoot().listMaterials().length - new Set(plans.map((plan) => plan.material)).size,
+        verifiedTextureCount,
+        createdTextureCount,
+    };
+}
+//# sourceMappingURL=unrealMaterialSidecar.js.map