@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/atlas-provenance.js

@@ -0,0 +1,448 @@
+import * as THREE from 'three';
+import { restoreGltfTextureBinding } from "./gltf-texture-binding.js";
+import { canonicalAtlasMetadataJsonV1, canonicalizeTextureAtlasSpecV1, validateTextureAtlasManifestV1, } from "./texture-atlas-contract.js";
+export const ATLAS_PROVENANCE_VERSION = 'kiln.atlas-provenance.v1';
+const TABLE_ENVELOPE_BYTES = new TextEncoder().encode(JSON.stringify({ version: ATLAS_PROVENANCE_VERSION, atlases: [] })).length;
+export const ATLAS_PROVENANCE_LIMITS = Object.freeze({
+    atlases: 128,
+    bytes: 4_194_304,
+    bindings: 1024,
+    entryBytes: 262_144,
+    encodedBytes: 16_777_216,
+    aggregateEncodedBytes: 67_108_864,
+    bakeDecodedBytes: 67_108_864,
+});
+function fail(message) {
+    throw new TypeError(`atlas provenance: ${message}`);
+}
+function field(input, key) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        fail('plain metadata object required.');
+    const proto = Object.getPrototypeOf(input);
+    if (proto !== null && proto !== Object.prototype)
+        fail('plain metadata prototype required.');
+    const d = Object.getOwnPropertyDescriptor(input, key);
+    if (!d)
+        return undefined;
+    if (!d.enumerable || !('value' in d))
+        fail('metadata accessors/hidden fields are unsupported.');
+    return d.value;
+}
+function closed(input, keys) {
+    for (const key of Reflect.ownKeys(input))
+        if (typeof key !== 'string' || !keys.includes(key))
+            fail('unsupported metadata field.');
+    for (const key of keys)
+        field(input, key);
+    return input;
+}
+function normalize(input) {
+    canonicalAtlasMetadataJsonV1(input);
+    const r = closed(input, ['spec', 'manifest']);
+    const spec = canonicalizeTextureAtlasSpecV1(r['spec']);
+    return { spec, manifest: validateTextureAtlasManifestV1(r['manifest'], spec) };
+}
+function textureCandidates(texture) {
+    const direct = field(texture.userData, 'kilnAtlas'), resource = field(texture.userData, 'kilnMaterialResource');
+    const map = resource === undefined ? undefined : field(resource, 'map'), recipe = map === undefined ? undefined : field(map, 'recipe');
+    const candidates = [];
+    if (direct !== undefined)
+        candidates.push(direct);
+    if (recipe !== undefined && field(recipe, 'kind') === 'atlas')
+        candidates.push({ spec: field(recipe, 'spec'), manifest: field(recipe, 'manifest') });
+    return candidates;
+}
+function normalizeCandidates(candidates) {
+    let result;
+    for (const candidate of candidates) {
+        const p = normalize(candidate);
+        if (result && canonicalAtlasMetadataJsonV1(result) !== canonicalAtlasMetadataJsonV1(p))
+            fail('direct and saved atlas identities disagree.');
+        result = p;
+    }
+    return result;
+}
+/** Reads only engine metadata data descriptors; author metadata and encoded arrays are not serialized. */
+export function readAtlasTextureProvenance(texture) {
+    return normalizeCandidates(textureCandidates(texture));
+}
+function admitTable(input) {
+    const r = closed(input, ['version', 'atlases']);
+    if (r['version'] !== ATLAS_PROVENANCE_VERSION)
+        fail('unsupported version.');
+    const entries = r['atlases'];
+    if (!Array.isArray(entries) || Object.getPrototypeOf(entries) !== Array.prototype)
+        fail('dense atlas array required.');
+    const n = Object.getOwnPropertyDescriptor(entries, 'length').value;
+    if (n > ATLAS_PROVENANCE_LIMITS.atlases || Reflect.ownKeys(entries).length !== n + 1)
+        fail('atlas count/density budget exceeded.');
+    let bytes = TABLE_ENVELOPE_BYTES;
+    const admitted = [];
+    for (let i = 0; i < n; i++) {
+        const d = Object.getOwnPropertyDescriptor(entries, String(i));
+        if (!d?.enumerable || !('value' in d))
+            fail('atlas array accessors are unsupported.');
+        const json = canonicalAtlasMetadataJsonV1(d.value);
+        bytes += new TextEncoder().encode(json).length + (i > 0 ? 1 : 0);
+        if (bytes > ATLAS_PROVENANCE_LIMITS.bytes)
+            fail('aggregate metadata byte budget exceeded.');
+        admitted.push(closed(d.value, ['id', 'spec', 'manifest']));
+    }
+    return admitted;
+}
+export function validateAtlasProvenanceTable(input) {
+    const admitted = admitTable(input), ids = new Set(), atlases = [];
+    for (const e of admitted) {
+        const p = normalize({ spec: e['spec'], manifest: e['manifest'] });
+        if (e['id'] !== p.manifest.manifestHash || ids.has(e['id']))
+            fail('duplicate or mismatched atlas identity.');
+        ids.add(e['id']);
+        atlases.push({ id: e['id'], ...p });
+    }
+    return { version: ATLAS_PROVENANCE_VERSION, atlases };
+}
+function lookup(table, id) {
+    const found = table.atlases.find((a) => a.id === id);
+    if (!found)
+        fail('unknown atlas reference.');
+    return found;
+}
+function derivedBinding(p, regionName, origin, mode) {
+    if (!['top-left', 'bottom-left'].includes(origin) ||
+        !['content-boundary', 'texel-center'].includes(mode))
+        fail('explicit binding origin/mode required.');
+    const r = p.manifest.regions.find((r) => r.name === regionName);
+    if (!r)
+        fail('unknown named region.');
+    const { x, y, width: w, height: h } = r.content, center = mode === 'texel-center', bottom = origin === 'bottom-left';
+    return {
+        manifestHash: p.manifest.manifestHash,
+        specHash: p.manifest.specHash,
+        layoutHash: p.manifest.layoutHash,
+        region: r.name,
+        content: structuredClone(r.content),
+        allocation: structuredClone(r.allocation),
+        inputOrigin: origin,
+        mode,
+        scale: [
+            (w - (center ? 1 : 0)) / p.manifest.width,
+            ((bottom ? -1 : 1) * (h - (center ? 1 : 0))) / p.manifest.height,
+        ],
+        offset: [
+            (x + (center ? 0.5 : 0)) / p.manifest.width,
+            (y + (bottom ? h - (center ? 0.5 : 0) : center ? 0.5 : 0)) / p.manifest.height,
+        ],
+    };
+}
+export function expandAtlasBinding(input, table) {
+    canonicalAtlasMetadataJsonV1(input);
+    const r = closed(input, ['version', 'atlasId', 'region', 'inputOrigin', 'mode']);
+    if (r['version'] !== ATLAS_PROVENANCE_VERSION)
+        fail('unsupported binding version.');
+    return derivedBinding(lookup(table, r['atlasId']), r['region'], r['inputOrigin'], r['mode']);
+}
+/** A geometry-wide stamp can be associated only with the exact primary atlas supplied here. */
+export function readAtlasGeometryBinding(geometry, provenance) {
+    const stamp = field(geometry.userData, 'kilnAtlasBinding');
+    if (stamp === undefined)
+        return undefined;
+    canonicalAtlasMetadataJsonV1(stamp);
+    const r = stamp, derived = derivedBinding(provenance, r['region'], r['inputOrigin'], r['mode']);
+    if (canonicalAtlasMetadataJsonV1(stamp) !== canonicalAtlasMetadataJsonV1(derived))
+        fail('named binding identity or remap formula mismatch.');
+    return {
+        version: ATLAS_PROVENANCE_VERSION,
+        atlasId: provenance.manifest.manifestHash,
+        region: r['region'],
+        inputOrigin: r['inputOrigin'],
+        mode: r['mode'],
+    };
+}
+export function collectAtlasProvenance(root) {
+    const textures = new Map(), geometries = new Map(), candidates = new Map(), sizes = new Map(), pendingGeometry = new Map();
+    let total = TABLE_ENVELOPE_BYTES, pixelBytes = 0, bindings = 0;
+    // Entire metadata graph admission comes before canonicalizers clone manifests or exporters clone scene state.
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh && !node.isSprite)
+            return;
+        const meshIds = new Set(), mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const mat of mats)
+            for (const slot of [
+                'map',
+                'normalMap',
+                'roughnessMap',
+                'metalnessMap',
+                'emissiveMap',
+                'aoMap',
+            ]) {
+                const texture = mat[slot];
+                if (!(texture instanceof THREE.Texture))
+                    continue;
+                let ref = textures.get(texture);
+                if (!ref) {
+                    const raw = textureCandidates(texture);
+                    if (!raw.length)
+                        continue;
+                    for (const candidate of raw) {
+                        canonicalAtlasMetadataJsonV1(candidate);
+                        const r = closed(candidate, ['spec', 'manifest']), id = field(r['manifest'], 'manifestHash');
+                        if (typeof id !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(id))
+                            fail('invalid atlas identity.');
+                        const bytes = new TextEncoder().encode(canonicalAtlasMetadataJsonV1({ ...r, id })).length;
+                        const prior = sizes.get(id) ?? 0;
+                        total += Math.max(0, bytes - prior) + (prior === 0 && sizes.size > 0 ? 1 : 0);
+                        sizes.set(id, Math.max(prior, bytes));
+                        if (total > ATLAS_PROVENANCE_LIMITS.bytes ||
+                            sizes.size > ATLAS_PROVENANCE_LIMITS.atlases)
+                            fail('aggregate metadata budget exceeded.');
+                        ref ??= { version: ATLAS_PROVENANCE_VERSION, id };
+                    }
+                    const spec = field(raw[0], 'spec'), width = field(spec, 'width'), height = field(spec, 'height');
+                    if (!Number.isSafeInteger(width) ||
+                        !Number.isSafeInteger(height) ||
+                        width < 1 ||
+                        height < 1)
+                        fail('invalid atlas image dimensions.');
+                    pixelBytes += width * height * 4;
+                    if (pixelBytes > ATLAS_PROVENANCE_LIMITS.bakeDecodedBytes)
+                        fail('aggregate atlas bake pixel budget exceeded.');
+                    candidates.set(texture, raw);
+                    textures.set(texture, ref);
+                }
+                if (++bindings > ATLAS_PROVENANCE_LIMITS.bindings)
+                    fail('texture binding budget exceeded.');
+                meshIds.add(ref.id);
+            }
+        if (!mesh.isMesh)
+            return;
+        const stamp = field(mesh.geometry.userData, 'kilnAtlasBinding');
+        if (stamp === undefined)
+            return;
+        if (++bindings > ATLAS_PROVENANCE_LIMITS.bindings)
+            fail('primitive binding budget exceeded.');
+        canonicalAtlasMetadataJsonV1(stamp);
+        const id = field(stamp, 'manifestHash');
+        if (typeof id !== 'string' || !meshIds.has(id))
+            fail('named binding has no matching primary atlas texture on this mesh.');
+        pendingGeometry.set(mesh.geometry, id);
+    });
+    const identities = new Map();
+    for (const [texture, raw] of candidates) {
+        const p = normalizeCandidates(raw), id = p.manifest.manifestHash, prior = identities.get(id);
+        if (prior && canonicalAtlasMetadataJsonV1(prior) !== canonicalAtlasMetadataJsonV1(p))
+            fail('conflicting atlas identity.');
+        identities.set(id, p);
+        textures.set(texture, { version: ATLAS_PROVENANCE_VERSION, id });
+    }
+    for (const [geometry, id] of pendingGeometry)
+        geometries.set(geometry, readAtlasGeometryBinding(geometry, identities.get(id)));
+    const table = identities.size
+        ? {
+            version: ATLAS_PROVENANCE_VERSION,
+            atlases: [...identities].map(([id, p]) => ({ id, ...p })),
+        }
+        : undefined;
+    return { table, texture: (t) => textures.get(t), binding: (g) => geometries.get(g) };
+}
+function rawDocumentTable(doc) {
+    const scene = doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0];
+    return scene ? field(scene.getExtras(), 'kilnAtlasProvenance') : undefined;
+}
+export function atlasDocumentTable(doc) {
+    const raw = rawDocumentTable(doc);
+    return raw === undefined ? undefined : validateAtlasProvenanceTable(raw);
+}
+export function atlasMaterialUses(doc) {
+    const uses = [];
+    for (const mat of doc.getRoot().listMaterials())
+        for (const [texture, info] of [
+            [mat.getBaseColorTexture(), mat.getBaseColorTextureInfo()],
+            [mat.getNormalTexture(), mat.getNormalTextureInfo()],
+            [mat.getMetallicRoughnessTexture(), mat.getMetallicRoughnessTextureInfo()],
+            [mat.getEmissiveTexture(), mat.getEmissiveTextureInfo()],
+            [mat.getOcclusionTexture(), mat.getOcclusionTextureInfo()],
+        ])
+            if (texture && info && field(info.getExtras(), 'kilnAtlasReference') !== undefined) {
+                if (uses.length >= ATLAS_PROVENANCE_LIMITS.bindings)
+                    fail('document binding budget exceeded.');
+                uses.push({ texture, info });
+            }
+    return uses;
+}
+async function imageHash(texture) {
+    const bytes = texture.getImage();
+    if (!bytes || bytes.byteLength > ATLAS_PROVENANCE_LIMITS.encodedBytes)
+        fail('encoded image missing or over budget.');
+    const result = await crypto.subtle.digest('SHA-256', bytes);
+    return `sha256:${[...new Uint8Array(result)].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+}
+function sampler(info) {
+    const value = {
+        minFilter: info.getMinFilter(),
+        magFilter: info.getMagFilter(),
+        wrapS: info.getWrapS(),
+        wrapT: info.getWrapT(),
+    };
+    if (![null, 9728, 9729, 9984, 9985, 9986, 9987].includes(value.minFilter) ||
+        ![null, 9728, 9729].includes(value.magFilter) ||
+        ![33071, 33648, 10497].includes(value.wrapS) ||
+        ![33071, 33648, 10497].includes(value.wrapT))
+        fail('unsupported effective sampler.');
+    return value;
+}
+function reference(input, table) {
+    canonicalAtlasMetadataJsonV1(input);
+    const r = closed(input, ['version', 'id', 'effectiveSampler', 'finalMime', 'finalImageSha256']);
+    if (r['version'] !== ATLAS_PROVENANCE_VERSION)
+        fail('unsupported texture reference version.');
+    lookup(table, r['id']);
+    return r;
+}
+function admitEncodedImages(uses) {
+    const seen = new Set();
+    let total = 0;
+    for (const { texture } of uses) {
+        if (seen.has(texture))
+            continue;
+        seen.add(texture);
+        const bytes = texture.getImage();
+        if (!bytes || bytes.byteLength > ATLAS_PROVENANCE_LIMITS.encodedBytes)
+            fail('encoded image missing or over budget.');
+        total += bytes.byteLength;
+        if (total > ATLAS_PROVENANCE_LIMITS.aggregateEncodedBytes)
+            fail('aggregate encoded image hash budget exceeded.');
+    }
+}
+/** Export/optimization only: bind source identity to the final encoded bytes and actual per-use sampler. */
+export async function refreshAtlasDocumentProvenance(doc) {
+    const table = atlasDocumentTable(doc), uses = atlasMaterialUses(doc);
+    if (!uses.length)
+        return;
+    if (!table)
+        fail('atlas table missing.');
+    admitEncodedImages(uses);
+    const hashes = new Map();
+    for (const { texture, info } of uses) {
+        const r = reference(field(info.getExtras(), 'kilnAtlasReference'), table);
+        let hash = hashes.get(texture);
+        if (!hash) {
+            hash = await imageHash(texture);
+            hashes.set(texture, hash);
+        }
+        info.setExtras({
+            ...info.getExtras(),
+            kilnAtlasReference: {
+                version: ATLAS_PROVENANCE_VERSION,
+                id: r.id,
+                effectiveSampler: sampler(info),
+                finalMime: texture.getMimeType(),
+                finalImageSha256: hash,
+            },
+        });
+    }
+}
+/** Import is validation, never a repair or identity refresh. */
+export async function validateAtlasDocumentProvenance(doc) {
+    const table = atlasDocumentTable(doc), uses = atlasMaterialUses(doc);
+    if (uses.length && !table)
+        fail('atlas table missing.');
+    if (!table) {
+        for (const mesh of doc.getRoot().listMeshes())
+            for (const primitive of mesh.listPrimitives())
+                if (field(primitive.getExtras(), 'kilnAtlasBinding') !== undefined)
+                    fail('atlas table missing.');
+        return;
+    }
+    admitEncodedImages(uses);
+    const hashes = new Map();
+    for (const { texture, info } of uses) {
+        const r = reference(field(info.getExtras(), 'kilnAtlasReference'), table);
+        let hash = hashes.get(texture);
+        if (!hash) {
+            hash = await imageHash(texture);
+            hashes.set(texture, hash);
+        }
+        if (r.finalImageSha256 !== hash ||
+            r.finalMime !== texture.getMimeType() ||
+            canonicalAtlasMetadataJsonV1(r.effectiveSampler) !==
+                canonicalAtlasMetadataJsonV1(sampler(info)))
+            fail('final image or effective sampler identity mismatch.');
+    }
+    let bindings = 0;
+    for (const mesh of doc.getRoot().listMeshes())
+        for (const prim of mesh.listPrimitives()) {
+            const binding = field(prim.getExtras(), 'kilnAtlasBinding');
+            if (binding !== undefined) {
+                if (++bindings > ATLAS_PROVENANCE_LIMITS.bindings)
+                    fail('primitive budget exceeded.');
+                expandAtlasBinding(binding, table);
+                const material = prim.getMaterial(), id = field(binding, 'atlasId');
+                const infos = material
+                    ? [
+                        material.getBaseColorTextureInfo(),
+                        material.getNormalTextureInfo(),
+                        material.getMetallicRoughnessTextureInfo(),
+                        material.getEmissiveTextureInfo(),
+                        material.getOcclusionTextureInfo(),
+                    ]
+                    : [];
+                if (!infos.some((info) => info &&
+                    field(info.getExtras(), 'kilnAtlasReference') !== undefined &&
+                    field(field(info.getExtras(), 'kilnAtlasReference'), 'id') === id))
+                    fail('named binding has no matching material atlas reference.');
+            }
+        }
+}
+const validatedDeliveries = new WeakMap();
+/** Host-only owned identity established by the validated GLB loader; no serialized skip flag. */
+export function readValidatedAtlasDelivery(texture) {
+    const ref = validatedDeliveries.get(texture);
+    return ref ? structuredClone(ref) : undefined;
+}
+export function readAtlasEncodedTexture(texture) {
+    const encoded = field(texture.userData, 'encoded');
+    if (encoded === undefined)
+        return undefined;
+    const r = closed(encoded, ['mime', 'bytes']);
+    if (r['mime'] !== 'image/png' ||
+        !(r['bytes'] instanceof Uint8Array) ||
+        r['bytes'].byteLength > ATLAS_PROVENANCE_LIMITS.encodedBytes)
+        fail('bounded PNG encoding required.');
+    return { mime: 'image/png', bytes: r['bytes'] };
+}
+/** Called only after validateAtlasDocumentProvenance; each sampler use gets owned Three state. */
+export function restoreAtlasTextureProvenance(texture, info, table) {
+    const r = reference(field(info.getExtras(), 'kilnAtlasReference'), table), p = lookup(table, r.id);
+    texture.userData.kilnAtlas = structuredClone({ spec: p.spec, manifest: p.manifest });
+    validatedDeliveries.set(texture, Object.freeze(structuredClone(r)));
+    restoreGltfTextureBinding(texture, info);
+}
+/** Compose before mergeDocuments copies image/geometry buffers or deletes the source scene. */
+export async function mergeAtlasDocumentProvenance(target, source) {
+    const sourceRaw = rawDocumentTable(source), targetRaw = rawDocumentTable(target);
+    const union = new Map();
+    for (const raw of [targetRaw, sourceRaw])
+        if (raw !== undefined)
+            for (const entry of admitTable(raw)) {
+                const prior = union.get(entry['id']);
+                if (prior && canonicalAtlasMetadataJsonV1(prior) !== canonicalAtlasMetadataJsonV1(entry))
+                    fail('conflicting atlas identity during composition.');
+                union.set(entry['id'], entry);
+            }
+    // The combined graph is admitted before any recipe/manifest cloning or source graph merge.
+    const combined = union.size
+        ? { version: ATLAS_PROVENANCE_VERSION, atlases: [...union.values()] }
+        : undefined;
+    if (combined)
+        admitTable(combined);
+    admitEncodedImages([...atlasMaterialUses(target), ...atlasMaterialUses(source)]);
+    await validateAtlasDocumentProvenance(source);
+    await validateAtlasDocumentProvenance(target);
+    if (combined) {
+        const table = validateAtlasProvenanceTable(combined), scene = target.getRoot().getDefaultScene() ?? target.getRoot().listScenes()[0];
+        if (!scene)
+            fail('composition target scene missing.');
+        scene.setExtras({ ...scene.getExtras(), kilnAtlasProvenance: table });
+    }
+}

package/lib/character.d.ts

@@ -1,9 +1,10 @@
 /**
- * Body-plan-neutral character rig contracts and the one approved joint-chain
- * scaffold. Presets are semantic data only; they do not introduce humanoid or
+ * Body-plan-neutral character rig contracts and rigid/bone joint-chain
+ * scaffolds. Presets are semantic data only; they do not introduce humanoid or
  * animal geometry primitive families.
  */
 import * as THREE from 'three';
+export { createSkinnedPart, type CreateSkinnedPartOptions } from "./skin-binding.js";
 export declare const KILN_CHARACTER_JOINT_EXTRAS_KEY: 'kilnCharacterJoint';
 export declare const KILN_CHARACTER_RIG_EXTRAS_KEY: 'kilnCharacterRig';
 export declare const KILN_CHARACTER_JOINT_SCHEMA_VERSION: 1;
@@ -123,6 +124,14 @@ export interface CharacterJointNodeEvidenceV1 {
     nodePath: string;
     descriptor: CharacterJointDescriptorV1;
 }
+export interface BoneChainResultV1 extends JointChainResultV1 {
+    root: THREE.Bone;
+    end: THREE.Bone;
+    nodes: THREE.Bone[];
+    byRole: ReadonlyMap<string, THREE.Bone>;
+}
+/** Opt-in semantic bones. Existing createJointChain continues to make rigid pivots. */
+export declare function createBoneChain(chainName: string, segments: readonly JointChainSegmentV1[], options?: CreateJointChainOptionsV1): BoneChainResultV1;
 /** Deterministic indexed paths shared by QA and diagnostic descriptors. */
 export declare function collectCharacterJointNodes(root: THREE.Object3D): CharacterJointNodeEvidenceV1[];
 export declare const BIPED_RIG_PRESET_V1: CharacterRigGraphV1;

package/lib/character.js

@@ -1,10 +1,13 @@
 /**
- * Body-plan-neutral character rig contracts and the one approved joint-chain
- * scaffold. Presets are semantic data only; they do not introduce humanoid or
+ * Body-plan-neutral character rig contracts and rigid/bone joint-chain
+ * scaffolds. Presets are semantic data only; they do not introduce humanoid or
  * animal geometry primitive families.
  */
 import * as THREE from 'three';
 import { stampSemanticMetadataV1 } from "./contracts/index.js";
+import { GEOMETRY_ALLOCATION_LIMITS } from "./geometry-budget.js";
+import { AuthoringDiagnosticError } from "./evaluator/authoring-diagnostic.js";
+export { createSkinnedPart } from "./skin-binding.js";
 export const KILN_CHARACTER_JOINT_EXTRAS_KEY = 'kilnCharacterJoint';
 export const KILN_CHARACTER_RIG_EXTRAS_KEY = 'kilnCharacterRig';
 export const KILN_CHARACTER_JOINT_SCHEMA_VERSION = 1;
@@ -486,6 +489,91 @@ export function createJointChain(chainName, segments, options = {}) {
         descriptors,
     };
 }
+/** Opt-in semantic bones. Existing createJointChain continues to make rigid pivots. */
+export function createBoneChain(chainName, segments, options = {}) {
+    try {
+        return buildBoneChain(chainName, segments, options);
+    }
+    catch (error) {
+        if (error instanceof TypeError || error instanceof RangeError)
+            throw new AuthoringDiagnosticError('BONE_CHAIN_ARGUMENT', error.message);
+        throw error;
+    }
+}
+function buildBoneChain(chainName, segments, options = {}) {
+    if (!Array.isArray(segments) ||
+        segments.length < 1 ||
+        segments.length > GEOMETRY_ALLOCATION_LIMITS.skinBones)
+        throw new RangeError(`createBoneChain segment limit is 1..${GEOMETRY_ALLOCATION_LIMITS.skinBones}.`);
+    if (options.parent !== undefined && !options.parent.isObject3D)
+        throw new TypeError('createBoneChain parent must be an Object3D.');
+    const parentDescriptor = options.parent
+        ? readCharacterJointDescriptorV1(options.parent)
+        : undefined;
+    if (options.parentRole !== undefined && options.parentRole !== parentDescriptor?.role)
+        throw new TypeError('createBoneChain parentRole must match the declared parent joint.');
+    const roles = new Set(), names = new Set();
+    if (options.parent) {
+        let top = options.parent;
+        while (top.parent)
+            top = top.parent;
+        top.traverse((node) => {
+            if (node.name)
+                names.add(node.name);
+            const descriptor = readCharacterJointDescriptorV1(node);
+            if (descriptor)
+                roles.add(descriptor.role);
+        });
+    }
+    let parentRole = parentDescriptor?.role;
+    // Validate the complete chain before allocating nodes or parenting any of them.
+    const descriptors = segments.map((segment) => {
+        const descriptor = createCharacterJointDescriptorV1({
+            role: segment.role,
+            aliases: segment.aliases,
+            parentRole,
+            side: segment.side,
+            rest: {
+                translation: segment.offset,
+                rotation: segment.restRotation,
+                scale: segment.restScale,
+            },
+            localForwardAxis: segment.localForwardAxis,
+            localBendAxis: segment.localBendAxis,
+            endEffector: segment.endEffector,
+            contact: segment.contact,
+        });
+        const name = characterJointNodeName(chainName, descriptor.role);
+        if (roles.has(descriptor.role))
+            throw new TypeError(`createBoneChain duplicate role: ${descriptor.role}.`);
+        if (names.has(name))
+            throw new TypeError(`createBoneChain duplicate node name after sanitization: ${name}.`);
+        roles.add(descriptor.role);
+        names.add(name);
+        parentRole = descriptor.role;
+        return descriptor;
+    });
+    const nodes = descriptors.map((descriptor) => {
+        const node = new THREE.Bone();
+        node.name = characterJointNodeName(chainName, descriptor.role);
+        node.position.fromArray(descriptor.rest.translation);
+        node.quaternion.fromArray(descriptor.rest.rotation);
+        node.scale.fromArray(descriptor.rest.scale);
+        stampCharacterJointDescriptorV1(node, descriptor);
+        return node;
+    });
+    for (let i = 1; i < nodes.length; i++)
+        nodes[i - 1].add(nodes[i]);
+    if (options.parent)
+        options.parent.add(nodes[0]);
+    return {
+        root: nodes[0],
+        end: nodes[nodes.length - 1],
+        nodes,
+        byRole: new Map(descriptors.map((descriptor, i) => [descriptor.role, nodes[i]])),
+        descriptors,
+    };
+}
 /** Deterministic indexed paths shared by QA and diagnostic descriptors. */
 export function collectCharacterJointNodes(root) {
     const joints = [];

package/lib/community-exporter.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from 'three';
-import type { Document } from '@gltf-transform/core';
+import { type Document } from '@gltf-transform/core';
 import type { AuthorExtras } from "./user-data-extras.js";
+import { type AtlasProvenanceCollection } from "./atlas-provenance.js";
 export declare function resolveGltfExporter(value?: string | undefined): 'legacy' | 'three';
 export interface ExportPlatform {
     prepare(hasTextures: boolean): Promise<void>;
@@ -10,4 +11,4 @@ export interface ExportPlatform {
         height: number;
     }>;
 }
-export declare function communitySceneDocument(root: THREE.Object3D, clips: THREE.AnimationClip[], platform?: ExportPlatform, authorExtras?: AuthorExtras): Promise<Document>;
+export declare function communitySceneDocument(root: THREE.Object3D, clips: THREE.AnimationClip[], platform?: ExportPlatform, authorExtras?: AuthorExtras, atlas?: AtlasProvenanceCollection): Promise<Document>;