@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/qa/skin-integrity.js

@@ -0,0 +1,221 @@
+import * as THREE from 'three';
+const MAX_FINDINGS = 64;
+const WEIGHT_TOLERANCE = 1e-5;
+function validAttribute(a, count, size) {
+    if (!a || a.itemSize !== size || a.count !== count || !Number.isSafeInteger(count) || count < 1)
+        return false;
+    if ('isInterleavedBufferAttribute' in a) {
+        return (Number.isSafeInteger(a.data.stride) &&
+            a.data.stride >= size &&
+            Number.isSafeInteger(a.offset) &&
+            a.offset >= 0 &&
+            a.offset + size <= a.data.stride &&
+            (count - 1) * a.data.stride + a.offset + size <= a.array.length);
+    }
+    return count * size <= a.array.length;
+}
+function finiteAffine(matrix) {
+    const e = matrix?.elements;
+    return (!!e &&
+        e.length === 16 &&
+        [...e].every((v) => Number.isFinite(v) && Number.isFinite(Math.fround(v))) &&
+        // Inverting valid TRS matrices can introduce double-precision roundoff.
+        // Judge the affine row at the Float32 precision used by the exported data.
+        Math.fround(e[3]) === 0 &&
+        Math.fround(e[7]) === 0 &&
+        Math.fround(e[11]) === 0 &&
+        Math.fround(e[15]) === 1);
+}
+/** Read logical attributes and transforms without updating or repairing the caller's scene. */
+export function inspectSkinIntegrity(root) {
+    const result = {
+        schemaVersion: 1,
+        findings: [],
+        meshesChecked: 0,
+        verticesChecked: 0,
+        truncated: false,
+        bounds: [],
+    };
+    const paths = new Map();
+    const pending = [[root, '', 0]];
+    while (pending.length) {
+        const [node, parent, sibling] = pending.pop();
+        if (paths.has(node))
+            continue;
+        const segment = `${(node.name || node.type).slice(0, 80)}[${sibling}]`;
+        const path = (parent ? `${parent}/${segment}` : segment).slice(-800);
+        paths.set(node, path);
+        for (let i = node.children.length - 1; i >= 0; i--)
+            pending.push([node.children[i], path, i]);
+    }
+    const worlds = new Map();
+    function world(node) {
+        const chain = [], seen = new Set();
+        let cursor = node;
+        while (cursor && !worlds.has(cursor)) {
+            if (seen.has(cursor))
+                return undefined;
+            seen.add(cursor);
+            chain.push(cursor);
+            cursor = cursor.parent;
+        }
+        while (chain.length) {
+            const n = chain.pop();
+            const local = n.matrixAutoUpdate
+                ? new THREE.Matrix4().compose(n.position, n.quaternion, n.scale)
+                : n.matrix.clone();
+            const parent = n.parent ? worlds.get(n.parent) : undefined;
+            const value = n.matrixWorldAutoUpdate === false
+                ? n.matrixWorld.clone()
+                : parent
+                    ? new THREE.Matrix4().multiplyMatrices(parent, local)
+                    : local;
+            worlds.set(n, value);
+        }
+        return worlds.get(node);
+    }
+    for (const [node, nodePath] of paths) {
+        const mesh = node;
+        if (!mesh.isSkinnedMesh)
+            continue;
+        if (result.findings.length >= MAX_FINDINGS) {
+            result.truncated = true;
+            break;
+        }
+        result.meshesChecked++;
+        const start = result.findings.length;
+        const add = (code, message, attribute, measurement) => {
+            if (result.findings.length >= MAX_FINDINGS) {
+                result.truncated = true;
+                return;
+            }
+            result.findings.push({
+                code,
+                disposition: 'block',
+                dimension: 'exportIntegrity',
+                profile: 'skin.source-integrity.v1',
+                message,
+                affected: { node: mesh.name.slice(0, 160), nodePath, ...(attribute ? { attribute } : {}) },
+                ...(measurement ? { measurement } : {}),
+                repairText: 'Rebuild the named binding at its intended rest pose. Keep bone order, inverse bind matrices and four influence lanes aligned with every final vertex; unwrap or change topology before binding. Do not repair invalid indices by normalizing weights.',
+            });
+        };
+        const skeleton = mesh.skeleton, bones = skeleton?.bones;
+        if (!bones?.length || !Array.isArray(bones)) {
+            add('SKIN_SKELETON', 'Skinned mesh requires a nonempty skeleton in the exported hierarchy.');
+            continue;
+        }
+        const unique = new Set();
+        for (let joint = 0; joint < bones.length; joint++) {
+            const bone = bones[joint];
+            if (!bone?.isObject3D || !paths.has(bone) || unique.has(bone)) {
+                add('SKIN_JOINT_MEMBERSHIP', `Joint ${joint} (${JSON.stringify(bone?.name?.slice(0, 160) ?? 'missing')}) must be a distinct node inside the exported hierarchy.`, `joints[${joint}]`);
+            }
+            if (bone)
+                unique.add(bone);
+            if (!finiteAffine(skeleton.boneInverses?.[joint])) {
+                add('SKIN_INVERSE_BIND', `Joint ${joint} (${JSON.stringify(bone?.name?.slice(0, 160) ?? 'missing')}) requires a finite affine inverse bind matrix.`, `boneInverses[${joint}]`);
+            }
+            if (result.truncated)
+                break;
+        }
+        if (!finiteAffine(mesh.bindMatrix) ||
+            !Number.isFinite(mesh.bindMatrix.determinant()) ||
+            mesh.bindMatrix.determinant() === 0 ||
+            ![THREE.AttachedBindMode, THREE.DetachedBindMode].includes(mesh.bindMode)) {
+            add('SKIN_BIND_MATRIX', 'Mesh requires a finite invertible affine bind matrix and an attached or detached bind mode.', 'bindMatrix');
+        }
+        const position = mesh.geometry?.getAttribute('position'), count = position?.count ?? 0;
+        const indices = mesh.geometry?.getAttribute('skinIndex'), weights = mesh.geometry?.getAttribute('skinWeight');
+        if (!validAttribute(position, count, 3) ||
+            !validAttribute(indices, count, 4) ||
+            indices.normalized ||
+            !validAttribute(weights, count, 4)) {
+            add('SKIN_ATTRIBUTES', 'Skin requires xyz positions and four non-normalized joint indices and four weights per final vertex, backed by complete buffers.', 'skinIndex/skinWeight');
+            continue;
+        }
+        const invalid = new Map();
+        const bad = (code, vertex, attribute) => {
+            const row = invalid.get(code);
+            if (row) {
+                if (row.last !== vertex)
+                    row.count++;
+                row.last = vertex;
+            }
+            else
+                invalid.set(code, { count: 1, first: vertex, last: vertex, attribute });
+        };
+        for (let vertex = 0; vertex < count; vertex++) {
+            let sum = 0;
+            for (let lane = 0; lane < 4; lane++) {
+                const index = indices.getComponent(vertex, lane), weight = weights.getComponent(vertex, lane);
+                if (!Number.isInteger(index) || index < 0 || index >= bones.length)
+                    bad('SKIN_JOINT_INDEX', vertex, 'skinIndex');
+                if (!Number.isFinite(weight) || weight < 0 || weight > 1)
+                    bad('SKIN_WEIGHT_VALUE', vertex, 'skinWeight');
+                sum += weight;
+            }
+            if (!Number.isFinite(sum) || Math.abs(sum - 1) > WEIGHT_TOLERANCE)
+                bad('SKIN_WEIGHT_SUM', vertex, 'skinWeight');
+        }
+        result.verticesChecked += count;
+        for (const [code, row] of invalid) {
+            const why = code === 'SKIN_JOINT_INDEX'
+                ? 'indices must address the skeleton, including zero-weight lanes'
+                : code === 'SKIN_WEIGHT_SUM'
+                    ? `weights must sum to one within ${WEIGHT_TOLERANCE}`
+                    : 'weights must be finite values in [0,1]';
+            add(code, `Invalid ${row.attribute} at vertex range ${row.first}..${row.last} (${row.count} affected vertices): ${why}.`, row.attribute, {
+                name: 'invalidSkinVertices',
+                actual: row.count,
+                expected: 0,
+                breakdown: { firstVertex: row.first, lastVertex: row.last },
+            });
+        }
+        if (result.findings.length !== start)
+            continue;
+        const meshWorld = world(mesh);
+        if (!finiteAffine(meshWorld)) {
+            add('SKIN_POSE_TRANSFORM', 'Current mesh world transform must be finite and affine.');
+            continue;
+        }
+        const inverse = mesh.bindMode === THREE.AttachedBindMode
+            ? meshWorld.clone().invert()
+            : mesh.bindMatrix.clone().invert();
+        const matrices = [];
+        for (let joint = 0; joint < bones.length; joint++) {
+            const boneWorld = world(bones[joint]);
+            if (!finiteAffine(boneWorld)) {
+                add('SKIN_POSE_TRANSFORM', `Current transform for joint ${joint} must be finite and affine.`, `joints[${joint}]`);
+                break;
+            }
+            matrices.push(new THREE.Matrix4()
+                .multiplyMatrices(boneWorld, skeleton.boneInverses[joint])
+                .multiply(mesh.bindMatrix));
+        }
+        if (result.findings.length !== start)
+            continue;
+        const base = new THREE.Vector3(), posed = new THREE.Vector3(), temp = new THREE.Vector3(), box = new THREE.Box3();
+        for (let vertex = 0; vertex < count; vertex++) {
+            // Mesh's implementation evaluates morphs but does not invoke the unsafe skin path.
+            THREE.Mesh.prototype.getVertexPosition.call(mesh, vertex, base);
+            posed.set(0, 0, 0);
+            for (let lane = 0; lane < 4; lane++) {
+                const weight = weights.getComponent(vertex, lane);
+                if (weight !== 0)
+                    posed.addScaledVector(temp.copy(base).applyMatrix4(matrices[indices.getComponent(vertex, lane)]), weight);
+            }
+            posed.applyMatrix4(inverse).applyMatrix4(meshWorld);
+            if (!Number.isFinite(Math.fround(posed.x)) ||
+                !Number.isFinite(Math.fround(posed.y)) ||
+                !Number.isFinite(Math.fround(posed.z))) {
+                add('SKIN_POSED_VERTEX', `Current deformed vertex ${vertex} is not finite and Float32-representable. Check positions, morphs and weighted joint transforms.`, `position[${vertex}]`);
+                break;
+            }
+            box.expandByPoint(posed);
+        }
+        if (result.findings.length === start)
+            result.bounds.push({ nodePath, min: box.min.toArray(), max: box.max.toArray() });
+    }
+    return result;
+}

package/lib/render-service-host.js

@@ -207,7 +207,6 @@ export async function startLocalRenderService(dir = renderServiceDir(), environm
         stderr = `${stderr}${chunk.toString()}`.slice(-2_000);
     });
     const deadline = Date.now() + budget;
-    let exitedAt;
     try {
         while (Date.now() < deadline) {
             const fresh = await inspectLocalRenderService(url, dir, 1_000);
@@ -218,12 +217,10 @@ export async function startLocalRenderService(dir = renderServiceDir(), environm
             const exited = windowsLaunch
                 ? windowsLaunch.hasExited()
                 : running.exitCode !== null || running.signalCode !== null;
-            if (exited)
-                exitedAt ??= Date.now();
-            // Another client may have won the socket while this child lost its bind. Give
-            // that listener a bounded health warmup, and join only after full verification.
-            // A failed spawn has no such race; absent/unknown never count as success.
-            if (spawnError || (exitedAt !== undefined && Date.now() - exitedAt >= 1500))
+            // A competing child can win the socket while this one exits after losing
+            // its bind. An unknown listener gets the same startup deadline as our child;
+            // only verified health permits joining. An exited child with no listener fails.
+            if (spawnError || (exited && fresh.kind === 'absent'))
                 throw new Error(`render service exited during startup${spawnError ? `: ${spawnError.message}` : ''}${stderr.trim() ? `: ${stderr.trim()}` : windowsLaunch ? '; launch the renderer manually to inspect native-driver errors' : ''}`);
             await new Promise((done) => setTimeout(done, 250));
         }

package/lib/render.d.ts

@@ -24,7 +24,7 @@ import { type MaterialMetricsV1 } from "./material-metrics.js";
 import { type MaterialRecipeApplicationProvenanceV1 } from "./material-recipe-runtime.js";
 import { type MaterialResourceProvenanceV1 } from "./material-resources.js";
 import { type TextureResolver } from "./texture-resolver.js";
-import type { MaterialLibraryPayloadV1, MaterialManifestV1 } from "./material-library.js";
+import type { MaterialLibraryPayload, MaterialManifest } from "./material-library.js";
 import { type RebuildOptions } from "./rebuild-options.js";
 import { type RigidMergeSummary } from "./rigid-merge.js";
 import { type KitPackOptions, type KitPackSummary } from "./kit.js";
@@ -146,7 +146,7 @@ export interface RenderResult {
     materialResourceProvenance?: MaterialResourceProvenanceV1[];
     /** Exact host-approved input dependencies, including licenses and procedural recipes.
      * These are declared build inputs, not proof that every supplied map was used. */
-    materialLibraryDependencies?: MaterialManifestV1[];
+    materialLibraryDependencies?: MaterialManifest[];
     /** Textures baked into the returned GLB, including bounded procedural lineage. */
     bakedTextures?: BakedTextureProvenanceV1[];
     integrationManifest: IntegrationManifestV1;
@@ -338,7 +338,7 @@ export interface RenderGlbOptions {
     /** Trusted evaluator dependency; never derived from generated code. */
     textureResolver?: TextureResolver;
     /** Host-approved portable material maps, transported as data to evaluator workers. */
-    materialResources?: MaterialLibraryPayloadV1;
+    materialResources?: MaterialLibraryPayload;
     /** In-process host diagnostic sink; not serializable to evaluator workers. */
     diagnosticConsole?: DiagnosticConsole;
 }

package/lib/render.js

@@ -1,5 +1,7 @@
 import { assertNoLegacyRuntimePolicy, resolveRequirementsContext, } from "./requirements-context.js";
 import { runRequirementsSceneQa, collectRequirementsSceneEvidence, appendRequirementsFinalQa, } from "./qa/requirements-run.js";
+import { createRequirementsQaReport } from "./qa/requirements-report.js";
+import { inspectSkinIntegrity } from "./qa/skin-integrity.js";
 import { AuthoringDiagnosticError, rethrowAuthoringError } from "./evaluator/authoring-diagnostic.js";
 /**
  * Headless Kiln GLB Renderer
@@ -18,6 +20,8 @@ import { collectLodSets } from "./lod.js";
 import { applyLodChains, summarizeLodChains } from "./lod-export.js";
 import { applyNodeVisibility, drawnSceneBounds, summarizeHiddenNodes } from "./node-visibility.js";
 import { communitySceneDocument, resolveGltfExporter } from "./community-exporter.js";
+import { collectAtlasProvenance, mergeAtlasDocumentProvenance, refreshAtlasDocumentProvenance, validateAtlasDocumentProvenance, } from "./atlas-provenance.js";
+import { assertPortableMaterialSides } from "./material-export.js";
 import { isCubicSplineTrack } from "./animation-spline.js";
 import { applyIndexPolicy, resolveIndexPolicy, } from "./index-policy.js";
 import { openShellExtras } from "./open-shell.js";
@@ -255,7 +259,42 @@ function bridgeEmissive(doc, target, source) {
         .createEmissiveStrength()
         .setEmissiveStrength(peak));
 }
-function bridgeMaterial(doc, threeMat, cache, textureCache, authorExtras) {
+const GLTF_MIN_FILTER = {
+    [THREE.NearestFilter]: 9728,
+    [THREE.LinearFilter]: 9729,
+    [THREE.NearestMipmapNearestFilter]: 9984,
+    [THREE.LinearMipmapNearestFilter]: 9985,
+    [THREE.NearestMipmapLinearFilter]: 9986,
+    [THREE.LinearMipmapLinearFilter]: 9987,
+};
+const GLTF_MAG_FILTER = { [THREE.NearestFilter]: 9728, [THREE.LinearFilter]: 9729 };
+const GLTF_WRAP = {
+    [THREE.ClampToEdgeWrapping]: 33071,
+    [THREE.MirroredRepeatWrapping]: 33648,
+    [THREE.RepeatWrapping]: 10497,
+};
+/** Samplers belong to each texture use, not the cached glTF image. */
+function bridgeTextureSampler(source, target, atlas) {
+    const min = GLTF_MIN_FILTER[source.minFilter];
+    const mag = GLTF_MAG_FILTER[source.magFilter];
+    const s = GLTF_WRAP[source.wrapS];
+    const t = GLTF_WRAP[source.wrapT];
+    for (const [property, value] of [
+        ['minFilter', min],
+        ['magFilter', mag],
+        ['wrapS', s],
+        ['wrapT', t],
+    ]) {
+        if (typeof source[property] !== 'number' || value === undefined) {
+            throw new TypeError(`${source.name || '(unnamed texture)'}: unsupported ${property} ${source[property]}`);
+        }
+    }
+    target.setMinFilter(min).setMagFilter(mag).setWrapS(s).setWrapT(t);
+    const ref = atlas?.texture(source);
+    if (ref)
+        target.setExtras({ ...target.getExtras(), kilnAtlasReference: ref });
+}
+function bridgeMaterial(doc, threeMat, cache, textureCache, authorExtras, atlas) {
     const cached = cache.get(threeMat);
     if (cached)
         return cached;
@@ -286,13 +325,17 @@ function bridgeMaterial(doc, threeMat, cache, textureCache, authorExtras) {
         // PBR texture slots (Wave 3B)
         if (stdMat.map) {
             const t = bridgeTexture(doc, stdMat.map, textureCache);
-            if (t)
+            if (t) {
                 mat.setBaseColorTexture(t);
+                bridgeTextureSampler(stdMat.map, mat.getBaseColorTextureInfo(), atlas);
+            }
         }
         if (stdMat.normalMap) {
             const t = bridgeTexture(doc, stdMat.normalMap, textureCache);
-            if (t)
+            if (t) {
                 mat.setNormalTexture(t);
+                bridgeTextureSampler(stdMat.normalMap, mat.getNormalTextureInfo(), atlas);
+            }
         }
         // metallic + roughness live in one glTF texture (R=unused, G=rough, B=metal).
         // If the agent used separate Three.js maps we emit the roughness one as
@@ -303,18 +346,24 @@ function bridgeMaterial(doc, threeMat, cache, textureCache, authorExtras) {
         const mrSource = stdMat.roughnessMap ?? stdMat.metalnessMap;
         if (mrSource) {
             const t = bridgeTexture(doc, mrSource, textureCache);
-            if (t)
+            if (t) {
                 mat.setMetallicRoughnessTexture(t);
+                bridgeTextureSampler(mrSource, mat.getMetallicRoughnessTextureInfo(), atlas);
+            }
         }
         if (stdMat.emissiveMap) {
             const t = bridgeTexture(doc, stdMat.emissiveMap, textureCache);
-            if (t)
+            if (t) {
                 mat.setEmissiveTexture(t);
+                bridgeTextureSampler(stdMat.emissiveMap, mat.getEmissiveTextureInfo(), atlas);
+            }
         }
         if (stdMat.aoMap) {
             const t = bridgeTexture(doc, stdMat.aoMap, textureCache);
-            if (t)
+            if (t) {
                 mat.setOcclusionTexture(t);
+                bridgeTextureSampler(stdMat.aoMap, mat.getOcclusionTextureInfo(), atlas);
+            }
             mat.setOcclusionStrength(stdMat.aoMapIntensity ?? 1);
         }
     }
@@ -363,8 +412,10 @@ function bridgeMaterial(doc, threeMat, cache, textureCache, authorExtras) {
         mat.setDoubleSided(true);
     if (common.map && !mat.getBaseColorTexture()) {
         const texture = bridgeTexture(doc, common.map, textureCache);
-        if (texture)
+        if (texture) {
             mat.setBaseColorTexture(texture);
+            bridgeTextureSampler(common.map, mat.getBaseColorTextureInfo(), atlas);
+        }
     }
     cache.set(threeMat, mat);
     return mat;
@@ -396,7 +447,7 @@ function bridgeTexture(doc, threeTex, cache) {
     cache.set(threeTex, t);
     return t;
 }
-function bridgeGeometry(doc, buf, geometry, material, meshName) {
+function bridgeGeometry(doc, buf, geometry, material, meshName, atlas) {
     if (!geometry.getAttribute('normal')) {
         geometry.computeVertexNormals();
     }
@@ -445,6 +496,9 @@ function bridgeGeometry(doc, buf, geometry, material, meshName) {
             .setType(TYPE_SCALAR)
             .setBuffer(buf));
     }
+    const binding = atlas?.binding(geometry);
+    if (binding)
+        prim.setExtras({ kilnAtlasBinding: binding });
     const mesh = doc.createMesh(meshName);
     if (!Array.isArray(material))
         return mesh.addPrimitive(prim);
@@ -462,12 +516,14 @@ function bridgeGeometry(doc, buf, geometry, material, meshName) {
             .setArray(new IndexArray(indexValues.slice(group.start, group.start + group.count)))
             .setType(TYPE_SCALAR)
             .setBuffer(buf));
+        if (binding)
+            part.setExtras({ kilnAtlasBinding: binding });
         mesh.addPrimitive(part);
     }
     prim.dispose();
     return mesh;
 }
-function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache, authorExtras) {
+function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache, authorExtras, atlas) {
     const gtNode = doc.createNode(threeObj.name || undefined);
     // Author userData reaches extras only through `collectAuthorExtras` (plain JSON, no
     // `kiln*` key, bounded); the engine's own reserved payloads are promoted here only
@@ -534,7 +590,7 @@ function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache,
     if (threeObj.isMesh) {
         const threeMesh = threeObj;
         const threeMats = Array.isArray(threeMesh.material) ? threeMesh.material : [threeMesh.material];
-        const gtMats = threeMats.map((material) => bridgeMaterial(doc, material, matCache, texCache, authorExtras));
+        const gtMats = threeMats.map((material) => bridgeMaterial(doc, material, matCache, texCache, authorExtras, atlas));
         const gtMat = Array.isArray(threeMesh.material) ? gtMats : gtMats[0];
         // Key the mesh cache by (geometry ref, material ref) so createInstance
         // (same geo + mat as source) produces a GLB-level mesh instance: a
@@ -543,7 +599,7 @@ function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache,
         const cacheKey = `${threeMesh.geometry.uuid}__${threeMats.map((material) => material.uuid).join('_')}`;
         let gtMesh = meshCache.get(cacheKey);
         if (!gtMesh) {
-            gtMesh = bridgeGeometry(doc, buf, threeMesh.geometry, gtMat, threeMesh.name || 'mesh');
+            gtMesh = bridgeGeometry(doc, buf, threeMesh.geometry, gtMat, threeMesh.name || 'mesh', atlas);
             meshCache.set(cacheKey, gtMesh);
         }
         gtNode.setMesh(gtMesh);
@@ -551,7 +607,7 @@ function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache,
     else if (threeObj.isSprite) {
         const sprite = threeObj;
         const threeMat = sprite.material;
-        const gtMat = bridgeMaterial(doc, threeMat, matCache, texCache, authorExtras);
+        const gtMat = bridgeMaterial(doc, threeMat, matCache, texCache, authorExtras, atlas);
         // Unit XY quad matches Three.js Sprite scale semantics. Non-default center
         // and material rotation are baked into the quad; camera-facing remains an
         // explicit semantic runtime behavior on the exported node.
@@ -567,7 +623,7 @@ function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache,
             }
             if (rotation !== 0)
                 geometry.rotateZ(rotation);
-            gtMesh = bridgeGeometry(doc, buf, geometry, gtMat, sprite.name || 'sprite-quad');
+            gtMesh = bridgeGeometry(doc, buf, geometry, gtMat, sprite.name || 'sprite-quad', atlas);
             meshCache.set(cacheKey, gtMesh);
         }
         gtNode.setMesh(gtMesh);
@@ -576,7 +632,7 @@ function bridgeNode(doc, buf, threeObj, matCache, nodeMap, meshCache, texCache,
         nodeMap.set(threeObj.name, gtNode);
     }
     for (const child of threeObj.children) {
-        const childNode = bridgeNode(doc, buf, child, matCache, nodeMap, meshCache, texCache, authorExtras);
+        const childNode = bridgeNode(doc, buf, child, matCache, nodeMap, meshCache, texCache, authorExtras, atlas);
         gtNode.addChild(childNode);
     }
     return gtNode;
@@ -1032,6 +1088,26 @@ export async function renderSceneToGLB(root, opts = {}) {
     if (opts.geometryPolicy !== undefined && !['warn', 'strict'].includes(opts.geometryPolicy))
         throw new Error('geometryPolicy must be warn or strict');
     const exporter = resolveGltfExporter(opts.gltfExporter);
+    // Mandatory source-data invariants precede any operation that dereferences bindings.
+    // Reuse the structured QA transport without claiming that the full QA rules ran.
+    // Like invalid geometry buffers, malformed skin data cannot be made safe by QA-warn
+    // or derivative mode. No automatic weight normalization or rest-pose repair occurs.
+    const skinIntegrity = inspectSkinIntegrity(root);
+    if (skinIntegrity.findings.length) {
+        throw new AssetQaBlockedError(createRequirementsQaReport(requirements, {
+            findings: skinIntegrity.findings,
+            executedRules: [],
+            evaluatedDimensions: ['exportIntegrity'],
+            metrics: {
+                exportIntegrity: {
+                    skinMeshesChecked: skinIntegrity.meshesChecked,
+                    skinVerticesChecked: skinIntegrity.verticesChecked,
+                    skinInspectionTruncated: skinIntegrity.truncated,
+                },
+            },
+        }), 'scene');
+    }
+    assertPortableMaterialSides(root);
     // A set of LOD tiers needs its declared thresholds before anything is written. A
     // derivative re-serializes a review scene that has no declarations, so it is not judged.
     const lodSets = opts.derivative === true ? [] : collectLodSets(root);
@@ -1062,6 +1138,7 @@ export async function renderSceneToGLB(root, opts = {}) {
     // that will actually be written. A procedural DataTexture used to reach the
     // bridge with no encoded bytes and be dropped without a word; now it is
     // either baked into the GLB or warned about by name.
+    const atlas = collectAtlasProvenance(root);
     const bakedTextures = await bakeSceneTextures(root, warnings);
     // A normal-mapped mesh without tangents makes every runtime invent its own
     // tangent basis, so the same asset lights differently in different engines.
@@ -1085,7 +1162,7 @@ export async function renderSceneToGLB(root, opts = {}) {
     const authorExtras = collectAuthorExtras(root);
     warnings.push(...authorExtras.warnings);
     const doc = exporter === 'three'
-        ? await communitySceneDocument(root, nativeClips, (await import("./exporter-node.js")).nodeExportPlatform, authorExtras)
+        ? await communitySceneDocument(root, nativeClips, (await import("./exporter-node.js")).nodeExportPlatform, authorExtras, atlas)
         : new Document();
     // `asset.generator` defaults to the serializer's own version string, which put
     // `glTF-Transform v4.4.1` inside every artifact's bytes -- and therefore inside
@@ -1103,7 +1180,7 @@ export async function renderSceneToGLB(root, opts = {}) {
         const meshCache = new Map();
         const texCache = new Map();
         const nodeMap = new Map();
-        const rootNode = bridgeNode(doc, buf, root, matCache, nodeMap, meshCache, texCache, authorExtras);
+        const rootNode = bridgeNode(doc, buf, root, matCache, nodeMap, meshCache, texCache, authorExtras, atlas);
         const gltfScene = doc.createScene(opts.sceneName ?? 'Scene').addChild(rootNode);
         doc.getRoot().setDefaultScene(gltfScene);
         if (clips.length > 0) {
@@ -1124,6 +1201,10 @@ export async function renderSceneToGLB(root, opts = {}) {
                 scene.setExtras({ [REVIEW_CLIPS_EXTRAS_KEY]: review });
         }
     }
+    if (atlas.table) {
+        const scene = doc.getRoot().getDefaultScene();
+        scene.setExtras({ ...scene.getExtras(), kilnAtlasProvenance: atlas.table });
+    }
     // Visibility flags and LOD chains are written before any pass merges or prunes nodes, so
     // those passes see them and keep them; flags first, while every node is still in place.
     applyNodeVisibility(root, doc);
@@ -1202,6 +1283,8 @@ export async function renderSceneToGLB(root, opts = {}) {
     }
     const io = engineIO();
     ensureDefaultScene(doc);
+    await refreshAtlasDocumentProvenance(doc);
+    await validateAtlasDocumentProvenance(doc);
     const bytes = await io.writeBinary(doc);
     const artifactGlbSha256 = `sha256:${await sha256Hex(bytes)}`;
     const boundBakedTextures = bakedTextures.map((entry) => ({
@@ -1415,6 +1498,7 @@ export async function optimizeGlbBytes(bytes, opts = {}) {
     try {
         const io = engineIO();
         const doc = await io.readBinary(bytes);
+        await validateAtlasDocumentProvenance(doc);
         // GPU-instancing first (dedup already ran at bake; instance → palette is the
         // canonical order). Defaults OFF here — this is the web-tier re-bake seam, and
         // the caller opts in per-asset (Studio passes instance:'auto' + the record's
@@ -1443,6 +1527,8 @@ export async function optimizeGlbBytes(bytes, opts = {}) {
         if (!summary && !instancing)
             return undefined;
         ensureDefaultScene(doc);
+        await refreshAtlasDocumentProvenance(doc);
+        await validateAtlasDocumentProvenance(doc);
         const outBytes = await io.writeBinary(doc);
         const gltfValidation = await assertFinalGlbValid(outBytes);
         let report;
@@ -1516,6 +1602,7 @@ export async function snapGlbToPalette(bytes, slots, opts = {}) {
     try {
         const io = engineIO();
         const doc = await io.readBinary(bytes);
+        await validateAtlasDocumentProvenance(doc);
         const before = collectGlbMetrics(doc);
         const idx = buildSlotIndex(slots);
         let snapped = 0;
@@ -1570,6 +1657,8 @@ export async function snapGlbToPalette(bytes, slots, opts = {}) {
             drawsAfter: after.drawCalls,
         };
         ensureDefaultScene(doc);
+        await refreshAtlasDocumentProvenance(doc);
+        await validateAtlasDocumentProvenance(doc);
         const outBytes = await io.writeBinary(doc);
         const gltfValidation = await assertFinalGlbValid(outBytes);
         let report;
@@ -1629,6 +1718,7 @@ export async function composeSceneGLB(parts, opts = {}) {
         const part = parts[i];
         try {
             const src = await io.readBinary(part.bytes);
+            await mergeAtlasDocumentProvenance(master, src);
             if (opts.keepAnimations && opts.animationNaming === 'instance') {
                 for (const [clipIndex, animation] of src.getRoot().listAnimations().entries()) {
                     animation.setName(`${i}:${part.name ?? 'part'}/${clipIndex}:${animation.getName() || 'clip'}`);
@@ -1695,6 +1785,8 @@ export async function composeSceneGLB(parts, opts = {}) {
     }
     const metrics = collectGlbMetrics(master);
     ensureDefaultScene(master);
+    await refreshAtlasDocumentProvenance(master);
+    await validateAtlasDocumentProvenance(master);
     const bytes = await io.writeBinary(master);
     const gltfValidation = await assertFinalGlbValid(bytes, 'scene.glb');
     for (const issue of gltfValidation.issues.messages) {

package/lib/skin-binding.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from 'three';
+import { type SemanticMetadataV1, type SemanticMetadataV1Input } from "./contracts/index.js";
+export interface CreateSkinnedPartOptions {
+    /** Already assembled common hierarchy containing every bone, in the rest pose. */
+    parent: THREE.Object3D;
+    /** Explicit, stable index order. Bones remain owned by the caller's hierarchy. */
+    bones: readonly THREE.Bone[];
+    /** Four indices and weights per geometry vertex, including zero-weight lanes. */
+    indices: ArrayLike<number>;
+    weights: ArrayLike<number>;
+    /** Default false: require weights to sum to one. Never invent weights for zero sums. */
+    normalizeWeights?: boolean;
+    position?: [number, number, number];
+    /** Local Euler angles in degrees, matching createPart. */
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    semantic?: SemanticMetadataV1 | SemanticMetadataV1Input;
+}
+/** Clone unchanged topology, attach explicit four-lane influences and bind at the current rest pose. */
+export declare function createSkinnedPart(name: string, geometry: THREE.BufferGeometry, material: THREE.Material | THREE.Material[], options: CreateSkinnedPartOptions): THREE.SkinnedMesh;