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

package/dist/character/stages/bakeTexture.js

@@ -1,6 +1,4 @@
 "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.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -35,84 +33,264 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bakeBaseColor = bakeBaseColor;
+exports.bakeBaseColor = void 0;
+exports.bakeMaterials = bakeMaterials;
+exports.hasBakeableBaseColorTexture = hasBakeableBaseColorTexture;
+const core_1 = require("@gltf-transform/core");
+const imageLimits_1 = require("../imageLimits");
+const sanitizeMaterials_1 = require("./sanitizeMaterials");
 /**
- * Re-bakes the SOURCE document's base-color texture onto the (decimated, freshly unwrapped) target
+ * Re-bakes the SOURCE document's material textures onto the (decimated, freshly unwrapped) target
  * document. For every texel of every target triangle: barycentric -> 3D point -> closest point on the
- * SOURCE mesh (BVH) -> source UV -> bilinear sample of the source texture. Layered surfaces (hair shell
- * over scalp) are disambiguated by preferring source triangles whose facing agrees with the target
- * triangle when their distances are comparable. Unwritten texels are dilated outward into gutters so
- * bilinear/mip filtering never bleeds background into charts. Base color only — imports carry a single
- * baked atlas by contract (the conform pipeline drops other maps).
+ * SOURCE triangles of the SAME material (BVH per material) -> that material's own UVs -> bilinear
+ * sample of that material's own textures.
+ *
+ * Up to four atlases share the new layout: base colour (sRGB), an emissive map (sRGB, only when a source
+ * material has a genuine one), a packed ORM (R = occlusion, G/B = metallic-roughness, linear), and a
+ * tangent-space normal map. Normals are transferred through object
+ * space: decoded in the source triangle's UV-derived tangent frame and re-encoded in the target
+ * triangle's, so detail survives the new UV layout. Each target material binds only the slots its
+ * source material had; every other texture binding is cleared, because the old images no longer match
+ * the new UVs.
+ *
+ * EMISSIVE: an emissiveFactor must never outlive its map. A genuine (non-black) emissive map is rebaked with its
+ * factor multiplied in and the target factor becomes [1,1,1]; a black map (Meshy ships one beside factor [1,1,1])
+ * or a zero factor contributes nothing, so the texture is dropped and the factor zeroed. Clearing the map and
+ * keeping the factor rendered the whole avatar flat white.
+ *
+ * Layered surfaces (hair shell over scalp) are disambiguated by preferring source triangles whose
+ * facing agrees with the target triangle when their distances are comparable. Unwritten texels are
+ * dilated outward into gutters so bilinear/mip filtering never bleeds background into charts.
  */
-async function bakeBaseColor(target, source, outSize) {
+async function bakeMaterials(target, source, outSize) {
     const sharp = (await Promise.resolve().then(() => __importStar(require('sharp')))).default;
-    // --- source geometry + texture ---
-    const src = collectTriangles(source);
-    const srcTexture = findBaseColorTexture(source);
-    if (srcTexture === null)
+    const sourceMaterials = source.getRoot().listMaterials();
+    const targetMaterials = target.getRoot().listMaterials();
+    if (sourceMaterials.length !== targetMaterials.length) {
+        throw new Error(`bake: target has ${targetMaterials.length} materials, source has ${sourceMaterials.length}; they must be the same document`);
+    }
+    const decoded = new Map();
+    const decode = async (texture) => {
+        if (texture === null)
+            return null;
+        const cached = decoded.get(texture);
+        if (cached !== undefined)
+            return cached;
+        const image = texture.getImage();
+        if (image === null)
+            return null;
+        const raw = await sharp(Buffer.from(image), { limitInputPixels: imageLimits_1.MAX_CHARACTER_TEXTURE_PIXELS })
+            .ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+        const result = { data: raw.data, width: raw.info.width, height: raw.info.height };
+        decoded.set(texture, result);
+        return result;
+    };
+    const emissiveSlot = async (material) => {
+        const texture = material.getEmissiveTexture();
+        const [fr, fg, fb] = material.getEmissiveFactor();
+        const factor = [fr, fg, fb];
+        if (texture === null)
+            return { emissive: null, emissiveFactor: factor, emissiveDropped: false };
+        const image = await decode(texture);
+        const nothing = image === null || image.data.length === 0 || (fr <= 0 && fg <= 0 && fb <= 0) || isBlackImage(image);
+        if (nothing)
+            return { emissive: null, emissiveFactor: factor, emissiveDropped: true };
+        return { emissive: await slotSource(texture, material.getEmissiveTextureInfo()), emissiveFactor: factor, emissiveDropped: false };
+    };
+    const slotSource = async (texture, info) => {
+        const image = await decode(texture);
+        if (image === null || info === null)
+            return null;
+        const transform = textureTransform(info);
+        const texCoord = (transform?.texCoord ?? info.getTexCoord()) === 1 ? 1 : 0;
+        return { image, texCoord, transform: transform?.matrix ?? null };
+    };
+    const slots = [];
+    for (const material of sourceMaterials) {
+        slots.push({
+            baseColor: await slotSource(material.getBaseColorTexture(), material.getBaseColorTextureInfo()),
+            metallicRoughness: await slotSource(material.getMetallicRoughnessTexture(), material.getMetallicRoughnessTextureInfo()),
+            occlusion: await slotSource(material.getOcclusionTexture(), material.getOcclusionTextureInfo()),
+            normal: await slotSource(material.getNormalTexture(), material.getNormalTextureInfo()),
+            ...(await emissiveSlot(material)),
+        });
+    }
+    if (!slots.some((slot) => slot.baseColor !== null))
         throw new Error('bake: source document has no base-color texture');
-    const decoded = await sharp(Buffer.from(srcTexture)).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
-    const image = { data: decoded.data, width: decoded.info.width, height: decoded.info.height };
-    const bvh = buildBvh(src.pos, src.idx);
-    const diag = bboxDiagonal(src.pos);
+    const bakeBase = true;
+    const bakeOrm = slots.some((slot) => slot.metallicRoughness !== null || slot.occlusion !== null);
+    const bakeNormal = slots.some((slot) => slot.normal !== null);
+    const bakeEmissive = slots.some((slot) => slot.emissive !== null);
+    // --- source geometry, grouped by material, one BVH each ---
+    const src = collectByMaterial(source, sourceMaterials);
+    const allPos = concatPositions([...src.values()].map((soup) => soup.pos));
+    if (allPos.length === 0)
+        throw new Error('bake: no indexed triangle primitives found');
+    const diag = bboxDiagonal(allPos);
     const farDistSq = (0.02 * diag) ** 2;
-    // --- rasterize every target triangle into the new atlas ---
+    const bvhs = new Map();
+    const srcFrames = new Map();
+    for (const [materialIndex, soup] of src) {
+        bvhs.set(materialIndex, buildBvh(soup.pos, soup.idx, ALIGNED_HIT_SLACK * diag));
+        const normalSlot = slots[materialIndex]?.normal ?? null;
+        srcFrames.set(materialIndex, normalSlot === null ? null : triangleFrames(soup, normalSlot));
+    }
+    // --- rasterize every target triangle into the new atlases ---
     // Render at 2x and lanczos-downsample: one hit per texel aliases hard texture boundaries
     // (necklines, makeup edges) into sawtooth; 2x supersampling is the cheapest clean fix.
     const size = outSize * 2;
-    const out = new Uint8ClampedArray(size * size * 4);
+    const outBase = new Uint8ClampedArray(size * size * 4);
+    const outOrm = bakeOrm ? new Uint8ClampedArray(size * size * 4) : null;
+    const outNormal = bakeNormal ? new Uint8ClampedArray(size * size * 4) : null;
+    const outEmissive = bakeEmissive ? new Uint8ClampedArray(size * size * 4) : null;
     const written = new Uint8Array(size * size);
     let sampled = 0, far = 0;
-    const tgt = collectTriangles(target);
+    const tgt = collectByMaterial(target, targetMaterials);
     const bary = { u: 0, v: 0, w: 0 };
-    for (let t = 0; t < tgt.idx.length; t += 3) {
-        const [a, b, c] = [tgt.idx[t], tgt.idx[t + 1], tgt.idx[t + 2]];
-        const ax = tgt.uv[a * 2] * size - 0.5, ay = tgt.uv[a * 2 + 1] * size - 0.5;
-        const bx = tgt.uv[b * 2] * size - 0.5, by = tgt.uv[b * 2 + 1] * size - 0.5;
-        const cx = tgt.uv[c * 2] * size - 0.5, cy = tgt.uv[c * 2 + 1] * size - 0.5;
-        const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
-        if (Math.abs(area) < 1e-9)
-            continue;
-        // target face normal = the layer-filter reference for the whole triangle
-        const [nx, ny, nz] = faceNormal(tgt.pos, a, b, c);
-        const x0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), x1 = Math.min(size - 1, Math.ceil(Math.max(ax, bx, cx)));
-        const y0 = Math.max(0, Math.floor(Math.min(ay, by, cy))), y1 = Math.min(size - 1, Math.ceil(Math.max(ay, by, cy)));
-        for (let py = y0; py <= y1; py++) {
-            for (let px = x0; px <= x1; px++) {
-                let u = ((bx - px) * (cy - py) - (by - py) * (cx - px)) / area;
-                let v = ((cx - px) * (ay - py) - (cy - py) * (ax - px)) / area;
-                let w = 1 - u - v;
-                if (u < -0.02 || v < -0.02 || w < -0.02)
-                    continue; // slight tolerance closes rasterization cracks
-                u = Math.max(u, 0);
-                v = Math.max(v, 0);
-                w = Math.max(w, 0);
-                const s = u + v + w;
-                u /= s;
-                v /= s;
-                w /= s;
-                const x = u * tgt.pos[a * 3] + v * tgt.pos[b * 3] + w * tgt.pos[c * 3];
-                const y = u * tgt.pos[a * 3 + 1] + v * tgt.pos[b * 3 + 1] + w * tgt.pos[c * 3 + 1];
-                const z = u * tgt.pos[a * 3 + 2] + v * tgt.pos[b * 3 + 2] + w * tgt.pos[c * 3 + 2];
-                const hit = bvh.closest(x, y, z, nx, ny, nz, bary);
-                if (hit < 0)
-                    continue;
-                if (bary.u * 0 !== 0)
-                    continue; // NaN guard on degenerate source triangles
-                const sa = src.idx[hit * 3], sb = src.idx[hit * 3 + 1], sc = src.idx[hit * 3 + 2];
-                const su = bary.u * src.uv[sa * 2] + bary.v * src.uv[sb * 2] + bary.w * src.uv[sc * 2];
-                const sv = bary.u * src.uv[sa * 2 + 1] + bary.v * src.uv[sb * 2 + 1] + bary.w * src.uv[sc * 2 + 1];
-                const o = (py * size + px) * 4;
-                bilinear(image, su, sv, out, o);
-                written[py * size + px] = 1;
-                sampled++;
-                if (bvh.lastDistSq > farDistSq)
-                    far++;
+    const px4 = new Float64Array(4);
+    const n = new Float64Array(3);
+    for (const [materialIndex, soup] of tgt) {
+        const bvh = bvhs.get(materialIndex);
+        const srcSoup = src.get(materialIndex);
+        if (bvh === undefined || srcSoup === undefined)
+            continue; // material has no source surface to sample
+        const matSlots = slots[materialIndex];
+        const sourceMaterial = sourceMaterials[materialIndex];
+        // An OPAQUE material's texture alpha is ignored by every renderer and is routinely junk in extracted sources, but this
+        // atlas may later be bound by a MASK material (a cutout overlay folded into the garment's material by
+        // `unifyDominantMaterial`), so write the alpha the opaque material actually renders with: 1.
+        const opaqueSource = sourceMaterial.getAlphaMode() === 'OPAQUE';
+        // A material with no metallic-roughness image renders with its FACTORS, so that is what its texels must hold. The old
+        // 255/255/255 default meant metallic=1, roughness=1: invisible while the material kept its own (ORM-less) binding, but
+        // it became solid glossy metal the moment the material was folded onto one that does bind this atlas.
+        const ormDefaultRoughness = Math.round(Math.min(1, Math.max(0, sourceMaterial.getRoughnessFactor())) * 255);
+        const ormDefaultMetallic = Math.round(Math.min(1, Math.max(0, sourceMaterial.getMetallicFactor())) * 255);
+        const uv = soup.uv[0];
+        if (uv === null)
+            throw new Error('bake: target primitive has no TEXCOORD_0 (unwrap must run first)');
+        const frameSrc = srcFrames.get(materialIndex) ?? null;
+        const frameTgt = matSlots.normal === null ? null : triangleFrames(soup, { texCoord: 0, transform: null, image: matSlots.normal.image });
+        for (let t = 0; t < soup.idx.length; t += 3) {
+            const [a, b, c] = [soup.idx[t], soup.idx[t + 1], soup.idx[t + 2]];
+            const ax = uv[a * 2] * size - 0.5, ay = uv[a * 2 + 1] * size - 0.5;
+            const bx = uv[b * 2] * size - 0.5, by = uv[b * 2 + 1] * size - 0.5;
+            const cx = uv[c * 2] * size - 0.5, cy = uv[c * 2 + 1] * size - 0.5;
+            const area = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+            if (Math.abs(area) < 1e-9)
+                continue;
+            // target face normal = the layer-filter reference for the whole triangle
+            const [fx, fy, fz] = faceNormal(soup.pos, a, b, c);
+            const x0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), x1 = Math.min(size - 1, Math.ceil(Math.max(ax, bx, cx)));
+            const y0 = Math.max(0, Math.floor(Math.min(ay, by, cy))), y1 = Math.min(size - 1, Math.ceil(Math.max(ay, by, cy)));
+            for (let py = y0; py <= y1; py++) {
+                for (let px = x0; px <= x1; px++) {
+                    let u = ((bx - px) * (cy - py) - (by - py) * (cx - px)) / area;
+                    let v = ((cx - px) * (ay - py) - (cy - py) * (ax - px)) / area;
+                    let w = 1 - u - v;
+                    if (u < -0.02 || v < -0.02 || w < -0.02)
+                        continue; // slight tolerance closes rasterization cracks
+                    u = Math.max(u, 0);
+                    v = Math.max(v, 0);
+                    w = Math.max(w, 0);
+                    const s = u + v + w;
+                    u /= s;
+                    v /= s;
+                    w /= s;
+                    const x = u * soup.pos[a * 3] + v * soup.pos[b * 3] + w * soup.pos[c * 3];
+                    const y = u * soup.pos[a * 3 + 1] + v * soup.pos[b * 3 + 1] + w * soup.pos[c * 3 + 1];
+                    const z = u * soup.pos[a * 3 + 2] + v * soup.pos[b * 3 + 2] + w * soup.pos[c * 3 + 2];
+                    const hit = bvh.closest(x, y, z, fx, fy, fz, bary);
+                    if (hit < 0)
+                        continue;
+                    if (bary.u * 0 !== 0)
+                        continue; // NaN guard on degenerate source triangles
+                    const sa = srcSoup.idx[hit * 3], sb = srcSoup.idx[hit * 3 + 1], sc = srcSoup.idx[hit * 3 + 2];
+                    const o = (py * size + px) * 4;
+                    if (matSlots.baseColor !== null) {
+                        sampleSlot(matSlots.baseColor, srcSoup, sa, sb, sc, bary, px4);
+                        outBase[o] = px4[0];
+                        outBase[o + 1] = px4[1];
+                        outBase[o + 2] = px4[2];
+                        outBase[o + 3] = opaqueSource ? 255 : px4[3];
+                    }
+                    else {
+                        outBase[o] = 255;
+                        outBase[o + 1] = 255;
+                        outBase[o + 2] = 255;
+                        outBase[o + 3] = 255;
+                    }
+                    if (outEmissive !== null) {
+                        // Materials with no genuine emissive map hold black (alpha 1), so folding them onto an emissive-bearing
+                        // material later adds no light.
+                        if (matSlots.emissive !== null) {
+                            sampleSlot(matSlots.emissive, srcSoup, sa, sb, sc, bary, px4);
+                            for (let k = 0; k < 3; k++)
+                                outEmissive[o + k] = linearToSrgbByte(srgbByteToLinear(px4[k]) * matSlots.emissiveFactor[k]);
+                        }
+                        else {
+                            outEmissive[o] = 0;
+                            outEmissive[o + 1] = 0;
+                            outEmissive[o + 2] = 0;
+                        }
+                        outEmissive[o + 3] = 255;
+                    }
+                    if (outOrm !== null) {
+                        let occlusion = 255, roughness = 255, metallic = 255;
+                        if (matSlots.metallicRoughness === null) {
+                            roughness = ormDefaultRoughness;
+                            metallic = ormDefaultMetallic;
+                        }
+                        if (matSlots.occlusion !== null) {
+                            sampleSlot(matSlots.occlusion, srcSoup, sa, sb, sc, bary, px4);
+                            occlusion = px4[0];
+                        }
+                        if (matSlots.metallicRoughness !== null) {
+                            sampleSlot(matSlots.metallicRoughness, srcSoup, sa, sb, sc, bary, px4);
+                            roughness = px4[1];
+                            metallic = px4[2];
+                        }
+                        outOrm[o] = occlusion;
+                        outOrm[o + 1] = roughness;
+                        outOrm[o + 2] = metallic;
+                        outOrm[o + 3] = 255;
+                    }
+                    if (outNormal !== null) {
+                        if (matSlots.normal !== null && frameSrc !== null && frameTgt !== null) {
+                            sampleSlot(matSlots.normal, srcSoup, sa, sb, sc, bary, px4);
+                            // decode in the source frame -> object space
+                            const hitBary = { u: bary.u, v: bary.v, w: bary.w };
+                            interpolatedNormal(srcSoup, sa, sb, sc, hitBary, hit, n);
+                            const tsx = px4[0] / 127.5 - 1, tsy = px4[1] / 127.5 - 1, tsz = px4[2] / 127.5 - 1;
+                            // A source that ships TANGENT was authored (and is rendered by every glTF viewer) against its interpolated
+                            // vertex frame, not the per-triangle UV frame: Meshy's normal map carries most of the shading over
+                            // deliberately faceted vertex normals, so decoding it in the wrong frame painted per-triangle facets.
+                            const world = srcSoup.tan !== null
+                                ? fromVertexTangentSpace(srcSoup.tan, sa, sb, sc, hitBary, n, tsx, tsy, tsz)
+                                : fromTangentSpace(frameSrc, hit, n, tsx, tsy, tsz);
+                            // re-encode in the target frame at this texel
+                            interpolatedNormal(soup, a, b, c, { u, v, w }, t / 3, n);
+                            const [ex, ey, ez] = toTangentSpace(frameTgt, t / 3, n, world);
+                            outNormal[o] = (ex + 1) * 127.5;
+                            outNormal[o + 1] = (ey + 1) * 127.5;
+                            outNormal[o + 2] = (ez + 1) * 127.5;
+                        }
+                        else {
+                            outNormal[o] = 128;
+                            outNormal[o + 1] = 128;
+                            outNormal[o + 2] = 255;
+                        }
+                        outNormal[o + 3] = 255;
+                    }
+                    written[py * size + px] = 1;
+                    sampled++;
+                    if (bvh.lastDistSq > farDistSq)
+                        far++;
+                }
             }
         }
     }
     // --- dilate gutters (8 texels — enough for trilinear down to 1/8 res mips) ---
+    const atlases = [outBase, outEmissive, outOrm, outNormal].filter((atlas) => atlas !== null);
     let dilated = 0;
     for (let pass = 0; pass < 8; pass++) {
         const next = [];
@@ -120,68 +298,339 @@ async function bakeBaseColor(target, source, outSize) {
             if (written[i] !== 0)
                 continue;
             const px = i % size, py = (i / size) | 0;
-            let r = 0, g = 0, b2 = 0, a2 = 0, n = 0;
+            const neighbours = [];
             for (let dy = -1; dy <= 1; dy++) {
                 for (let dx = -1; dx <= 1; dx++) {
                     const qx = px + dx, qy = py + dy;
                     if (qx < 0 || qy < 0 || qx >= size || qy >= size || written[qy * size + qx] !== 1)
                         continue;
-                    const q = (qy * size + qx) * 4;
-                    r += out[q];
-                    g += out[q + 1];
-                    b2 += out[q + 2];
-                    a2 += out[q + 3];
-                    n++;
+                    neighbours.push((qy * size + qx) * 4);
                 }
             }
-            if (n > 0) {
-                const o = i * 4;
-                out[o] = r / n;
-                out[o + 1] = g / n;
-                out[o + 2] = b2 / n;
-                out[o + 3] = a2 / n;
-                next.push(i);
-                dilated++;
+            if (neighbours.length === 0)
+                continue;
+            const o = i * 4;
+            for (const atlas of atlases) {
+                for (let ch = 0; ch < 4; ch++) {
+                    let sum = 0;
+                    for (const q of neighbours)
+                        sum += atlas[q + ch];
+                    atlas[o + ch] = sum / neighbours.length;
+                }
             }
+            next.push(i);
+            dilated++;
         }
         for (const i of next)
             written[i] = 1;
     }
-    const png = await sharp(Buffer.from(out.buffer), { raw: { width: size, height: size, channels: 4 } })
+    const encode = async (atlas) => new Uint8Array(await sharp(Buffer.from(atlas.buffer), { raw: { width: size, height: size, channels: 4 } })
         .resize(outSize, outSize, { kernel: 'lanczos3' })
         .png()
-        .toBuffer();
-    const tgtTexture = target.getRoot().listTextures();
-    if (tgtTexture.length === 0)
-        throw new Error('bake: target document has no texture to replace');
-    for (const tex of tgtTexture)
-        tex.setImage(new Uint8Array(png)).setMimeType('image/png').setURI('');
-    return { size: outSize, sampled, dilated, far };
+        .toBuffer());
+    const previous = target.getRoot().listTextures();
+    const baked = {};
+    if (bakeBase)
+        baked.baseColor = target.createTexture('helix_baked_base_color').setImage(await encode(outBase)).setMimeType('image/png');
+    if (outEmissive !== null)
+        baked.emissive = target.createTexture('helix_baked_emissive').setImage(await encode(outEmissive)).setMimeType('image/png');
+    if (outOrm !== null)
+        baked.orm = target.createTexture('helix_baked_orm').setImage(await encode(outOrm)).setMimeType('image/png');
+    if (outNormal !== null)
+        baked.normal = target.createTexture('helix_baked_normal').setImage(await encode(outNormal)).setMimeType('image/png');
+    targetMaterials.forEach((material, index) => {
+        const slot = slots[index];
+        material
+            .setBaseColorTexture(slot.baseColor !== null ? baked.baseColor : null)
+            .setMetallicRoughnessTexture(slot.metallicRoughness !== null ? baked.orm : null)
+            .setOcclusionTexture(slot.occlusion !== null ? baked.orm : null)
+            .setNormalTexture(slot.normal !== null ? baked.normal : null)
+            .setEmissiveTexture(slot.emissive !== null ? baked.emissive : null);
+        // The factor travels with its map: baked into the texels (so [1,1,1] here) when the map is carried over, zero when
+        // the map was dropped. A source with no emissive texture keeps its textureless factor untouched.
+        if (slot.emissive !== null)
+            material.setEmissiveFactor([1, 1, 1]);
+        else if (slot.emissiveDropped)
+            material.setEmissiveFactor([0, 0, 0]);
+        for (const info of [
+            material.getBaseColorTextureInfo(),
+            material.getMetallicRoughnessTextureInfo(),
+            material.getOcclusionTextureInfo(),
+            material.getNormalTextureInfo(),
+            material.getEmissiveTextureInfo(),
+        ]) {
+            if (info === null)
+                continue;
+            info.setTexCoord(0);
+            info.setExtension('KHR_texture_transform', null);
+        }
+    });
+    // A TANGENT that rode through decimate + unwrap describes the SOURCE layout's frames, not the new UVs the atlases were
+    // just baked against. glTF viewers (three.js USE_TANGENT) prefer a vertex tangent over the UV-derivative frame the
+    // normal atlas is encoded in, so a stale one rotates every baked normal per triangle — the faceted, smeared Meshy
+    // faces. Drop it: without TANGENT the runtime derives the same UV-gradient frame the bake wrote.
+    for (const mesh of target.getRoot().listMeshes()) {
+        for (const prim of mesh.listPrimitives()) {
+            const tangent = prim.getAttribute('TANGENT');
+            if (tangent === null)
+                continue;
+            prim.setAttribute('TANGENT', null);
+            if (tangent.listParents().every((parent) => parent.propertyType === core_1.PropertyType.ROOT))
+                tangent.dispose();
+        }
+    }
+    // The replaced images describe the OLD UV layout; nothing may keep sampling them.
+    for (const texture of previous) {
+        if (texture.listParents().every((parent) => parent.propertyType === core_1.PropertyType.ROOT))
+            texture.dispose();
+    }
+    return {
+        size: outSize,
+        sampled,
+        dilated,
+        far,
+        slots: Object.keys(baked).sort(),
+    };
 }
-/** Flattens all mode-4 indexed prims into one soup (positions + UVs denormalized via getElement). */
-function collectTriangles(document) {
-    const pos = [], uv = [], idx = [];
+/** @deprecated Kept for callers of the original base-colour-only bake; bakes every material slot. */
+exports.bakeBaseColor = bakeMaterials;
+function textureTransform(info) {
+    const extension = info.getExtension('KHR_texture_transform');
+    if (extension === null)
+        return null;
+    const [ox, oy] = extension.getOffset();
+    const [sx, sy] = extension.getScale();
+    const r = extension.getRotation();
+    const cos = Math.cos(r), sin = Math.sin(r);
+    // glTF: uv' = T * R * S * uv with R = [[cos, sin], [-sin, cos]]
+    return { matrix: [cos * sx, sin * sy, -sin * sx, cos * sy, ox, oy], texCoord: extension.getTexCoord() };
+}
+function slotUv(soup, slot, vertex, out) {
+    const uv = soup.uv[slot.texCoord] ?? soup.uv[0];
+    if (uv === null) {
+        out[0] = 0;
+        out[1] = 0;
+        return;
+    }
+    const u = uv[vertex * 2], v = uv[vertex * 2 + 1];
+    const m = slot.transform;
+    if (m === null) {
+        out[0] = u;
+        out[1] = v;
+        return;
+    }
+    out[0] = m[4] + m[0] * u + m[1] * v;
+    out[1] = m[5] + m[2] * u + m[3] * v;
+}
+const uvA = [0, 0], uvB = [0, 0], uvC = [0, 0];
+function sampleSlot(slot, soup, a, b, c, bary, out) {
+    slotUv(soup, slot, a, uvA);
+    slotUv(soup, slot, b, uvB);
+    slotUv(soup, slot, c, uvC);
+    const su = bary.u * uvA[0] + bary.v * uvB[0] + bary.w * uvC[0];
+    const sv = bary.u * uvA[1] + bary.v * uvB[1] + bary.w * uvC[1];
+    bilinear(slot.image, su, sv, out);
+}
+/**
+ * Per-triangle tangent frames from positions and the slot's UVs: T = dP/du and B = -dP/dv. glTF's V
+ * runs down the image while a normal map's +Y (green) points up it, so the frame's second axis is the
+ * negated V gradient — the same frame Three.js derives from screen-space UV derivatives.
+ */
+function triangleFrames(soup, slot) {
+    const triangles = soup.idx.length / 3;
+    const frames = new Float32Array(triangles * 6);
+    for (let t = 0; t < triangles; t++) {
+        const a = soup.idx[t * 3], b = soup.idx[t * 3 + 1], c = soup.idx[t * 3 + 2];
+        slotUv(soup, slot, a, uvA);
+        slotUv(soup, slot, b, uvB);
+        slotUv(soup, slot, c, uvC);
+        const du1 = uvB[0] - uvA[0], dv1 = uvB[1] - uvA[1], du2 = uvC[0] - uvA[0], dv2 = uvC[1] - uvA[1];
+        const det = du1 * dv2 - du2 * dv1;
+        if (Math.abs(det) < 1e-12)
+            continue; // degenerate UVs: frame stays zero -> normal falls back to N
+        const r = 1 / det;
+        for (let k = 0; k < 3; k++) {
+            const e1 = soup.pos[b * 3 + k] - soup.pos[a * 3 + k], e2 = soup.pos[c * 3 + k] - soup.pos[a * 3 + k];
+            frames[t * 6 + k] = (e1 * dv2 - e2 * dv1) * r; // dP/du
+            frames[t * 6 + 3 + k] = -(e2 * du1 - e1 * du2) * r; // -dP/dv
+        }
+    }
+    return frames;
+}
+function interpolatedNormal(soup, a, b, c, bary, triangle, out) {
+    if (soup.nrm !== null) {
+        for (let k = 0; k < 3; k++) {
+            out[k] = bary.u * soup.nrm[a * 3 + k] + bary.v * soup.nrm[b * 3 + k] + bary.w * soup.nrm[c * 3 + k];
+        }
+    }
+    else {
+        const [x, y, z] = faceNormal(soup.pos, soup.idx[triangle * 3], soup.idx[triangle * 3 + 1], soup.idx[triangle * 3 + 2]);
+        out[0] = x;
+        out[1] = y;
+        out[2] = z;
+    }
+    const len = Math.hypot(out[0], out[1], out[2]) || 1;
+    out[0] = out[0] / len;
+    out[1] = out[1] / len;
+    out[2] = out[2] / len;
+}
+/** Gram-Schmidt the triangle frame against the shading normal; null when the UVs are degenerate. */
+function orthonormalFrame(frames, triangle, n) {
+    const t = [frames[triangle * 6], frames[triangle * 6 + 1], frames[triangle * 6 + 2]];
+    const b = [frames[triangle * 6 + 3], frames[triangle * 6 + 4], frames[triangle * 6 + 5]];
+    const dot = (p, q) => p[0] * q[0] + p[1] * q[1] + p[2] * q[2];
+    const nt = dot(t, n);
+    for (let k = 0; k < 3; k++)
+        t[k] = t[k] - n[k] * nt;
+    const tl = Math.hypot(t[0], t[1], t[2]);
+    if (tl < 1e-12)
+        return null;
+    for (let k = 0; k < 3; k++)
+        t[k] = t[k] / tl;
+    const nb = dot(b, n), tb = dot(b, t);
+    for (let k = 0; k < 3; k++)
+        b[k] = b[k] - n[k] * nb - t[k] * tb;
+    const bl = Math.hypot(b[0], b[1], b[2]);
+    if (bl < 1e-12)
+        return null;
+    for (let k = 0; k < 3; k++)
+        b[k] = b[k] / bl;
+    return [t, b];
+}
+function fromTangentSpace(frames, triangle, n, x, y, z) {
+    const frame = orthonormalFrame(frames, triangle, n);
+    if (frame === null)
+        return [n[0], n[1], n[2]];
+    const [t, b] = frame;
+    const out = [
+        x * t[0] + y * b[0] + z * n[0],
+        x * t[1] + y * b[1] + z * n[1],
+        x * t[2] + y * b[2] + z * n[2],
+    ];
+    const len = Math.hypot(...out) || 1;
+    return [out[0] / len, out[1] / len, out[2] / len];
+}
+/**
+ * glTF's vertex tangent frame at a barycentric point: T = interpolated TANGENT.xyz Gram-Schmidt'd against the shading
+ * normal, B = cross(N, T) * w — exactly what three.js (USE_TANGENT) and the glTF spec decode a normal map with.
+ */
+function fromVertexTangentSpace(tan, a, b, c, bary, n, x, y, z) {
+    const t = [0, 1, 2].map((k) => bary.u * tan[a * 4 + k] + bary.v * tan[b * 4 + k] + bary.w * tan[c * 4 + k]);
+    const handed = bary.u * tan[a * 4 + 3] + bary.v * tan[b * 4 + 3] + bary.w * tan[c * 4 + 3] < 0 ? -1 : 1;
+    const nt = t[0] * n[0] + t[1] * n[1] + t[2] * n[2];
+    for (let k = 0; k < 3; k++)
+        t[k] = t[k] - n[k] * nt;
+    const tl = Math.hypot(t[0], t[1], t[2]);
+    if (tl < 1e-12)
+        return [n[0], n[1], n[2]];
+    for (let k = 0; k < 3; k++)
+        t[k] = t[k] / tl;
+    const bt = [
+        (n[1] * t[2] - n[2] * t[1]) * handed,
+        (n[2] * t[0] - n[0] * t[2]) * handed,
+        (n[0] * t[1] - n[1] * t[0]) * handed,
+    ];
+    const out = [
+        x * t[0] + y * bt[0] + z * n[0],
+        x * t[1] + y * bt[1] + z * n[1],
+        x * t[2] + y * bt[2] + z * n[2],
+    ];
+    const len = Math.hypot(...out) || 1;
+    return [out[0] / len, out[1] / len, out[2] / len];
+}
+function toTangentSpace(frames, triangle, n, world) {
+    const frame = orthonormalFrame(frames, triangle, n);
+    if (frame === null)
+        return [0, 0, 1];
+    const [t, b] = frame;
+    const x = world[0] * t[0] + world[1] * t[1] + world[2] * t[2];
+    const y = world[0] * b[0] + world[1] * b[1] + world[2] * b[2];
+    const z = Math.max(0, world[0] * n[0] + world[1] * n[1] + world[2] * n[2]);
+    const len = Math.hypot(x, y, z) || 1;
+    return [x / len, y / len, z / len];
+}
+/** Flattens mode-4 indexed prims into one triangle soup per material index (positions/normals/UV0/UV1). */
+function collectByMaterial(document, materials) {
+    const index = new Map(materials.map((material, i) => [material, i]));
+    const parts = new Map();
     const el = [];
     for (const mesh of document.getRoot().listMeshes()) {
         for (const prim of mesh.listPrimitives()) {
-            const p = prim.getAttribute('POSITION'), t = prim.getAttribute('TEXCOORD_0'), ix = prim.getIndices();
-            if (prim.getMode() !== 4 || p === null || t === null || ix === null)
+            const p = prim.getAttribute('POSITION'), ix = prim.getIndices();
+            const material = prim.getMaterial();
+            if (prim.getMode() !== 4 || p === null || ix === null || material === null)
                 continue;
-            const base = pos.length / 3;
+            const materialIndex = index.get(material);
+            const nrm = prim.getAttribute('NORMAL');
+            const tan = prim.getAttribute('TANGENT');
+            const t0 = prim.getAttribute('TEXCOORD_0'), t1 = prim.getAttribute('TEXCOORD_1');
+            let part = parts.get(materialIndex);
+            if (part === undefined) {
+                part = { pos: [], nrm: [], tan: [], uv0: [], uv1: [], idx: [] };
+                parts.set(materialIndex, part);
+            }
+            const base = part.pos.length / 3;
             for (let v = 0; v < p.getCount(); v++) {
                 p.getElement(v, el);
-                pos.push(el[0], el[1], el[2]);
-                t.getElement(v, el);
-                uv.push(el[0], el[1]);
+                part.pos.push(el[0], el[1], el[2]);
+                if (part.nrm !== null) {
+                    if (nrm === null)
+                        part.nrm = null;
+                    else {
+                        nrm.getElement(v, el);
+                        part.nrm.push(el[0], el[1], el[2]);
+                    }
+                }
+                if (part.tan !== null) {
+                    if (tan === null)
+                        part.tan = null;
+                    else {
+                        tan.getElement(v, el);
+                        part.tan.push(el[0], el[1], el[2], el[3] < 0 ? -1 : 1);
+                    }
+                }
+                if (part.uv0 !== null) {
+                    if (t0 === null)
+                        part.uv0 = null;
+                    else {
+                        t0.getElement(v, el);
+                        part.uv0.push(el[0], el[1]);
+                    }
+                }
+                if (part.uv1 !== null) {
+                    if (t1 === null)
+                        part.uv1 = null;
+                    else {
+                        t1.getElement(v, el);
+                        part.uv1.push(el[0], el[1]);
+                    }
+                }
             }
             const arr = ix.getArray();
             for (let i = 0; i < arr.length; i++)
-                idx.push(base + arr[i]);
+                part.idx.push(base + arr[i]);
         }
     }
-    if (idx.length === 0)
-        throw new Error('bake: no indexed triangle primitives found');
-    return { pos: new Float32Array(pos), uv: new Float32Array(uv), idx: new Uint32Array(idx) };
+    const out = new Map();
+    for (const [materialIndex, part] of parts) {
+        out.set(materialIndex, {
+            pos: new Float32Array(part.pos),
+            nrm: part.nrm === null ? null : new Float32Array(part.nrm),
+            tan: part.tan === null || part.nrm === null ? null : new Float32Array(part.tan),
+            uv: [part.uv0 === null ? null : new Float32Array(part.uv0), part.uv1 === null ? null : new Float32Array(part.uv1)],
+            idx: new Uint32Array(part.idx),
+        });
+    }
+    return out;
+}
+function concatPositions(parts) {
+    const out = new Float32Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
 }
 function findBaseColorTexture(document) {
     for (const mat of document.getRoot().listMaterials()) {
@@ -191,6 +640,26 @@ function findBaseColorTexture(document) {
     }
     return null;
 }
+/** Every texel's RGB at or below the black-emissive ceiling (see `BLACK_EMISSIVE_MAX_CHANNEL`). */
+function isBlackImage(image) {
+    for (let i = 0; i < image.data.length; i += 4) {
+        if (image.data[i] > sanitizeMaterials_1.BLACK_EMISSIVE_MAX_CHANNEL || image.data[i + 1] > sanitizeMaterials_1.BLACK_EMISSIVE_MAX_CHANNEL || image.data[i + 2] > sanitizeMaterials_1.BLACK_EMISSIVE_MAX_CHANNEL)
+            return false;
+    }
+    return true;
+}
+function srgbByteToLinear(value) {
+    const c = Math.min(1, Math.max(0, value / 255));
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function linearToSrgbByte(value) {
+    const c = Math.min(1, Math.max(0, value));
+    return Math.round((c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055) * 255);
+}
+/** True only when the rebake stage has actual embedded pixels to sample. */
+function hasBakeableBaseColorTexture(document) {
+    return findBaseColorTexture(document) !== null;
+}
 function faceNormal(pos, a, b, c) {
     const ux = pos[b * 3] - pos[a * 3], uy = pos[b * 3 + 1] - pos[a * 3 + 1], uz = pos[b * 3 + 2] - pos[a * 3 + 2];
     const vx = pos[c * 3] - pos[a * 3], vy = pos[c * 3 + 1] - pos[a * 3 + 1], vz = pos[c * 3 + 2] - pos[a * 3 + 2];
@@ -208,19 +677,26 @@ function bboxDiagonal(pos) {
     }
     return Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]);
 }
-/** Bilinear sample with repeat wrap; writes RGBA to out[o..o+3]. */
-function bilinear(image, u, v, out, o) {
+/** Bilinear sample with repeat wrap; writes RGBA (0..255) to out[0..3]. */
+function bilinear(image, u, v, out) {
     const fx = (u - Math.floor(u)) * image.width - 0.5, fy = (v - Math.floor(v)) * image.height - 0.5;
     const x0 = Math.floor(fx), y0 = Math.floor(fy);
     const tx = fx - x0, ty = fy - y0;
     const wrap = (n, m) => ((n % m) + m) % m;
     for (let ch = 0; ch < 4; ch++) {
         const s = (x, y) => image.data[(wrap(y, image.height) * image.width + wrap(x, image.width)) * 4 + ch];
-        out[o + ch] = s(x0, y0) * (1 - tx) * (1 - ty) + s(x0 + 1, y0) * tx * (1 - ty) + s(x0, y0 + 1) * (1 - tx) * ty + s(x0 + 1, y0 + 1) * tx * ty;
+        out[ch] = s(x0, y0) * (1 - tx) * (1 - ty) + s(x0 + 1, y0) * tx * (1 - ty) + s(x0, y0 + 1) * (1 - tx) * ty + s(x0 + 1, y0 + 1) * tx * ty;
     }
 }
 /** Median-split AABB tree over triangles; queries prefer facing-aligned hits when distances are close. */
-function buildBvh(pos, idx) {
+/**
+ * How much FARTHER (as a fraction of the source's bbox diagonal, ~1 cm on an avatar) a facing-aligned source triangle may be
+ * than the closest one and still win. A decimated cloth surface passes within a millimetre of the BACK of a thin shell
+ * (Meshy models a hoodie as two opposite-facing sheets ~1 mm apart); the 1.5x-relative rule alone then took the inner
+ * sheet for ~20% of texels on a 52k-tri Dreamer avatar (job 8a976ac2), and its inward normal baked as dark shards.
+ */
+const ALIGNED_HIT_SLACK = 0.005;
+function buildBvh(pos, idx, alignSlack = 0) {
     const triCount = idx.length / 3;
     const order = new Uint32Array(triCount);
     for (let t = 0; t < triCount; t++)
@@ -280,10 +756,12 @@ function buildBvh(pos, idx) {
             // distance is within 1.5x of the absolute best (layered-surface disambiguation).
             let bestD = Infinity, bestT = -1, bu = 0, bv = 0, bw = 0;
             let alignD = Infinity, alignT = -1, au = 0, av = 0, aw = 0;
+            // aligned-acceptance radius: 1.5x the closest distance, or that distance plus the absolute slack
+            const acceptSq = (d) => Math.max(d * 2.25, (Math.sqrt(d) + alignSlack) ** 2);
             const visit = (node) => {
-                // prune at the aligned-acceptance radius (bestD * 1.5²): beyond it a hit can neither win
-                // outright nor qualify as the preferred aligned hit
-                if (aabbDistSq(node.bounds, x, y, z) > bestD * 2.25)
+                // prune at the aligned-acceptance radius: beyond it a hit can neither win outright nor qualify
+                // as the preferred aligned hit
+                if (aabbDistSq(node.bounds, x, y, z) > acceptSq(bestD))
                     return;
                 if (node.left === null) {
                     for (let i = node.start; i < node.start + node.count; i++) {
@@ -318,7 +796,7 @@ function buildBvh(pos, idx) {
                 }
             };
             visit(root);
-            if (alignT >= 0 && alignD <= bestD * 2.25) {
+            if (alignT >= 0 && alignD <= acceptSq(bestD)) {
                 bary.u = au;
                 bary.v = av;
                 bary.w = aw;