@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/texture-resolver.d.ts

@@ -8,14 +8,36 @@
  */
 import type * as THREE from 'three';
 import type { TextureUsage } from "./textures.js";
+import type { PinnedMaterialMapPortV1 } from "./pinned-material-map.js";
+export interface PreparedPortableTextureV3 {
+    descriptor: {
+        resourceId: string;
+        usage: TextureUsage;
+        allowedSlots: readonly string[];
+        colorSpace: 'srgb' | 'linear';
+        width: number;
+        height: number;
+        encodedByteLength: number;
+        imageSha256: `sha256:${string}`;
+    };
+    /** Caller-owned verified PNG bytes, prepared without pixel decoding. */
+    bytes: Uint8Array;
+    /** Verified provenance only; decoding supplies actual hasAlpha metadata. */
+    userData: Record<string, unknown>;
+}
 import { type ApprovedTextureResourceCache } from "./material-resources.js";
 export interface TextureResolver {
+    /** Host-only, verified immutable material closure for atlas compilation. */
+    pinnedMaterialMaps?: PinnedMaterialMapPortV1;
     /** Host-only metadata used to reject invalid portable slot bindings before loading. */
     describeApprovedTexture?(resourceId: unknown): {
         usage: TextureUsage;
         allowedSlots: readonly string[];
     } | undefined;
     loadApprovedTexture(resourceId: unknown): Promise<THREE.DataTexture>;
+    preparePortableTexture?(resourceId: unknown, context?: {
+        signal?: AbortSignal;
+    }): Promise<PreparedPortableTextureV3>;
     materialRecipe(id: unknown, overrides?: unknown): Promise<THREE.MeshStandardMaterial>;
 }
 export declare function createTextureResolver(cache?: ApprovedTextureResourceCache): TextureResolver;

package/lib/texture-resolver.js

@@ -18,6 +18,30 @@ export function createTextureResolver(cache = DEFAULT_APPROVED_TEXTURE_CACHE) {
             }
             return (await cache.load(resourceId)).texture;
         },
+        async preparePortableTexture(resourceId, context) {
+            context?.signal?.throwIfAborted();
+            if (typeof resourceId !== 'string')
+                throw new RangeError('Unsupported approved texture resource ID.');
+            const resolved = await cache.resolveAsync(resourceId);
+            context?.signal?.throwIfAborted();
+            // resolveAsync already verifies closed ID, length, hash and bounded PNG IHDR.
+            const header = new DataView(resolved.bytes.buffer, resolved.bytes.byteOffset, resolved.bytes.byteLength);
+            return {
+                descriptor: {
+                    resourceId,
+                    usage: resolved.provenance.usage,
+                    allowedSlots: [...resolved.descriptor.allowedSlots],
+                    colorSpace: resolved.provenance.colorSpace,
+                    width: header.getUint32(16),
+                    height: header.getUint32(20),
+                    encodedByteLength: resolved.bytes.length,
+                    imageSha256: `sha256:${resolved.provenance.contentHash}`,
+                },
+                // resolveAsync already returns a caller-owned copy, never cached bytes.
+                bytes: resolved.bytes,
+                userData: { kilnTexture: { approvedResource: structuredClone(resolved.provenance) } },
+            };
+        },
         async materialRecipe(id, overrides) {
             if (typeof id !== 'string')
                 throw new TypeError('materialRecipe id must be a string');

package/lib/tools/materials.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { assertMaterialJson, materialLibraryHashSchema, materialLibraryIdSchema, materialLibraryPayloadSchema, materialLibraryPortableSpec, materialSourceSchema, proceduralMaterialDraftSchema, } from "../material-library.js";
+import { assertMaterialJson, materialLibraryHashSchema, materialLibraryIdSchema, materialLibraryPayloadAnySchema, materialLibraryPortableSpec, materialSourceSchema, } from "../material-library.js";
 import { createMaterialRecordV1, decodeMaterialLibraryPayload } from "../material-library-node.js";
+import { createProceduralMaterialRecord } from "../material-authoring-node.js";
 import { createMaterialPresetDraft, listMaterialPresets } from "../material-presets.js";
 import { nestedRecordDescription, requireActionFields } from "./actions.js";
 const MATERIAL_ACTIONS = [
@@ -67,8 +68,8 @@ export const materialToolInput = z.strictObject({
     revisionId: materialLibraryHashSchema
         .optional()
         .describe("get: the immutable revision; omitted, the material's only revision."),
-    draft: record(nestedRecordDescription('create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters.', 'shape:material-draft')),
-    payload: record(nestedRecordDescription('import: schemaVersion 1 and complete normalized records with embedded PNG bytes.', 'shape:material-import')),
+    draft: record(nestedRecordDescription('create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library.', 'shape:material-draft')),
+    payload: record(nestedRecordDescription('import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes.', 'shape:material-import')),
 });
 const materialResult = (material) => ({
     ok: true,
@@ -115,7 +116,7 @@ export function createKilnMaterialDef(library, presentation = 'grouped') {
         : "kiln_material { action: 'list' }";
     return {
         name: 'kiln_material',
-        description: 'Manage optional immutable material resources in this workspace. presets discovers shipped architecture, wood, metal, fabric and ground recipes; create-preset bakes one with an explicit seed, creator and license; list returns compact material/revision summaries; get returns full provenance, hashes, map conventions, physical repeat scale and a code-ready portable material spec; create-procedural bakes bounded editable layer recipes including optional height-derived normals; import accepts complete normalized records with embedded PNG bytes. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before authored evaluation resolves the resources; no project is required.',
+        description: 'Manage optional immutable material resources in this workspace. presets lists shipped recipes; create-preset uses explicit seed, creator and license; list returns revision summaries; get returns provenance, hashes, sampling and a portable material spec. create-procedural accepts legacy layer drafts or schemaVersion 2 drafts with explicit samplers and bounded RGBA or named atlas recipes. Atlas resource sources require exact saved revisions; import requires complete normalized records and dependencies with embedded PNG bytes. Read shape:material-draft or shape:material-import through kiln_discover for full fields. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before evaluation; no project or mesh is required.',
         inputSchema: materialToolInput,
         actionContract: MATERIAL_CONTRACT,
         annotations: {
@@ -177,12 +178,12 @@ export function createKilnMaterialDef(library, presentation = 'grouped') {
                     }
                 }
                 case 'create-procedural': {
-                    const record = await createMaterialRecordV1(proceduralMaterialDraftSchema.parse(input.draft));
-                    const [material] = await library.import([record]);
+                    const { record, dependencies } = await createProceduralMaterialRecord(input.draft, library);
+                    const [material] = await library.import([record], dependencies.length ? { materials: dependencies } : undefined);
                     return materialResult(material);
                 }
                 case 'import': {
-                    const records = await decodeMaterialLibraryPayload(materialLibraryPayloadSchema.parse(input.payload));
+                    const records = await decodeMaterialLibraryPayload(materialLibraryPayloadAnySchema.parse(input.payload));
                     const materials = await library.import(records);
                     return {
                         ok: true,

package/lib/tools/registry.js

@@ -135,27 +135,16 @@ async function sha256Glb(bytes) {
 async function renderDerivativeCell(input, context) {
     let derivativeRoot = input.root;
     if (input.backfaceCull === false) {
-        derivativeRoot = derivativeRoot.clone(true);
-        derivativeRoot.traverse((node) => {
-            const mesh = node;
-            if (!mesh.isMesh)
-                return;
-            const prepare = (material) => {
-                const copy = material.clone();
-                copy.side = THREE.DoubleSide;
-                return copy;
-            };
-            mesh.material = Array.isArray(mesh.material)
-                ? mesh.material.map(prepare)
-                : prepare(mesh.material);
-        });
+        const { cloneReviewScene } = await import("../views/scene-copy.js");
+        derivativeRoot = cloneReviewScene(derivativeRoot, { omitHidden: true, doubleSided: true });
     }
     // `withCameraVisibility` and `isolateSubtree` express isolation by clearing
     // `mesh.visible`. The CPU rasterizer culls on that flag (see views/raster.ts),
     // but glTF carries no per-mesh visibility, so serializing unfiltered ships the
     // hidden geometry to the GPU service and makes isolate a silent no-op on exactly
     // the material-faithful path it is most useful on. Prune on a copy: the caller
-    // restores `.visible` afterwards and must not observe a mutated scene.
+    // restores `.visible` afterwards and must not observe a mutated scene. Required
+    // joint ancestors survive as transform-only nodes in the derivative.
     const { withoutHiddenMeshes } = await import("../views/camera.js");
     derivativeRoot = withoutHiddenMeshes(derivativeRoot);
     const rendered = await renderSceneToGLB(derivativeRoot, {
@@ -1860,7 +1849,7 @@ export async function buildProgramAssetDraft(code, context, backdrop) {
     const dependencies = [
         ...(rendered.materialResourceProvenance ?? []),
         ...(rendered.materialLibraryDependencies ?? []).map((manifest) => ({
-            kind: 'kiln.material.v1',
+            kind: `kiln.material.v${manifest.schemaVersion}`,
             delivery: 'runtime',
             manifest,
         })),

package/lib/tools/review.js

@@ -177,7 +177,7 @@ export function createKilnReviewDef(context) {
             const dependencies = [
                 ...(evaluation.materialResourceProvenance ?? []),
                 ...(evaluation.materialLibraryDependencies ?? []).map((manifest) => ({
-                    kind: 'kiln.material.v1',
+                    kind: `kiln.material.v${manifest.schemaVersion}`,
                     delivery: 'runtime',
                     manifest,
                 })),

package/lib/uv-data.d.ts

@@ -0,0 +1,32 @@
+/** Internal safety and correspondence boundary for the xatlasjs adapter. */
+import * as THREE from 'three';
+type Attribute = THREE.BufferAttribute | THREE.InterleavedBufferAttribute;
+export interface AtlasMesh {
+    vertexCount: number;
+    vertex: {
+        coords1?: Float32Array | number[];
+    };
+    index?: Uint16Array | Uint32Array | number[];
+    oldIndexes: Uint16Array | Uint32Array | number[];
+}
+/** Reject truncated Uint16 output and reordered faces before copying protected data. */
+export declare function validateAtlasRemap(mesh: AtlasMesh, inputIndex: Uint32Array, sourceCount: number): {
+    index: number[] | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike>;
+    uv: number[] | Float32Array<ArrayBufferLike>;
+    oldIndexes: number[] | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike>;
+};
+/** Copy raw storage, including normalized integers and half floats, without welding. */
+export declare function remapUnwrapAttribute(attribute: Attribute, oldIndexes: ArrayLike<number>): THREE.BufferAttribute;
+export declare function prepareUnwrap(geometry: THREE.BufferGeometry, opts: {
+    resolution?: number;
+    padding?: number;
+    useNormals?: boolean;
+}): {
+    index: Uint32Array<ArrayBuffer>;
+    positions: Float32Array<ArrayBufferLike>;
+    normals: Float32Array<ArrayBufferLike> | null;
+    useNormals: boolean;
+    resolution: number;
+    padding: number;
+};
+export {};

package/lib/uv-data.js

@@ -0,0 +1,172 @@
+/** Internal safety and correspondence boundary for the xatlasjs adapter. */
+import * as THREE from 'three';
+import { GEOMETRY_ALLOCATION_LIMITS as limits } from "./geometry-budget.js";
+/** Reject truncated Uint16 output and reordered faces before copying protected data. */
+export function validateAtlasRemap(mesh, inputIndex, sourceCount) {
+    const count = mesh.vertexCount;
+    if (!Number.isSafeInteger(count) || count < 1 || count > limits.unwrapVertices)
+        throw new RangeError(`autoUnwrap: xatlas output exceeds the supported 1..${limits.unwrapVertices} vertices. Split the mesh before unwrapping.`);
+    if (mesh.oldIndexes.length !== count)
+        throw new Error('autoUnwrap: xatlas returned an incomplete source-vertex map.');
+    for (const oldIndex of mesh.oldIndexes)
+        if (!Number.isSafeInteger(oldIndex) || oldIndex < 0 || oldIndex >= sourceCount)
+            throw new Error('autoUnwrap: xatlas returned an invalid source-vertex map.');
+    const index = mesh.index;
+    if (!index || index.length !== inputIndex.length)
+        throw new Error('autoUnwrap: xatlas changed the triangle count; face correspondence is unsupported.');
+    for (let i = 0; i < index.length; i++) {
+        const vertex = index[i];
+        if (!Number.isSafeInteger(vertex) ||
+            vertex < 0 ||
+            vertex >= count ||
+            mesh.oldIndexes[vertex] !== inputIndex[i])
+            throw new Error('autoUnwrap: xatlas changed triangle correspondence; refusing to misassign vertex data or material groups.');
+    }
+    const uv = mesh.vertex.coords1;
+    if (!uv || uv.length !== count * 2 || !uv.every((v) => Number.isFinite(v) && v >= 0 && v <= 1))
+        throw new Error('autoUnwrap: xatlas produced no valid UV coordinates (degenerate or zero-area triangles?).');
+    return { index, uv, oldIndexes: mesh.oldIndexes };
+}
+function interleaved(attribute) {
+    return attribute.isInterleavedBufferAttribute === true;
+}
+/** Copy raw storage, including normalized integers and half floats, without welding. */
+export function remapUnwrapAttribute(attribute, oldIndexes) {
+    const ArrayType = attribute.array.constructor;
+    const array = new ArrayType(oldIndexes.length * attribute.itemSize);
+    const stride = interleaved(attribute) ? attribute.data.stride : attribute.itemSize;
+    const offset = interleaved(attribute) ? attribute.offset : 0;
+    for (let i = 0; i < oldIndexes.length; i++) {
+        for (let c = 0; c < attribute.itemSize; c++)
+            array[i * attribute.itemSize + c] = attribute.array[oldIndexes[i] * stride + offset + c];
+    }
+    const output = attribute
+        .isFloat16BufferAttribute
+        ? new THREE.Float16BufferAttribute(array, attribute.itemSize, attribute.normalized)
+        : new THREE.BufferAttribute(array, attribute.itemSize, attribute.normalized);
+    output.name = attribute.name;
+    output.setUsage(interleaved(attribute) ? attribute.data.usage : attribute.usage);
+    if (!interleaved(attribute))
+        output.gpuType = attribute.gpuType;
+    return output;
+}
+function validateAttribute(name, attribute, count) {
+    if (attribute.isInstancedBufferAttribute ||
+        (interleaved(attribute) &&
+            attribute.data
+                .isInstancedInterleavedBuffer))
+        throw new TypeError(`autoUnwrap: ${name} is per-instance data; unwrap the base geometry before instancing.`);
+    if (attribute.count !== count ||
+        !Number.isSafeInteger(attribute.itemSize) ||
+        attribute.itemSize < 1 ||
+        attribute.itemSize > 4)
+        throw new TypeError(`autoUnwrap: ${name} must be a matching per-vertex attribute with 1..4 components.`);
+    if (interleaved(attribute) &&
+        (!Number.isSafeInteger(attribute.offset) ||
+            attribute.offset < 0 ||
+            attribute.offset + attribute.itemSize > attribute.data.stride))
+        throw new TypeError(`autoUnwrap: ${name} has an invalid interleaved offset or stride.`);
+}
+/** Decode xyz through getters: .array alone ignores stride, normalization and half floats. */
+function xyz(attribute, name) {
+    if (attribute.itemSize !== 3)
+        throw new TypeError(`autoUnwrap: ${name} requires three components.`);
+    const output = new Float32Array(attribute.count * 3);
+    for (let i = 0; i < attribute.count; i++) {
+        output[i * 3] = attribute.getX(i);
+        output[i * 3 + 1] = attribute.getY(i);
+        output[i * 3 + 2] = attribute.getZ(i);
+    }
+    if (!output.every(Number.isFinite))
+        throw new TypeError(`autoUnwrap: ${name} must contain finite Float32-representable values.`);
+    return output;
+}
+export function prepareUnwrap(geometry, opts) {
+    const resolution = opts.resolution ?? 1024;
+    const padding = opts.padding ?? 2;
+    if (!Number.isSafeInteger(resolution) || resolution < 1 || resolution > limits.unwrapResolution)
+        throw new RangeError(`autoUnwrap: resolution must be an integer from 1 to ${limits.unwrapResolution}.`);
+    if (!Number.isSafeInteger(padding) || padding < 0 || padding > resolution)
+        throw new RangeError('autoUnwrap: padding must be an integer from 0 to resolution.');
+    if (opts.useNormals !== undefined && typeof opts.useNormals !== 'boolean')
+        throw new TypeError('autoUnwrap: useNormals must be a boolean.');
+    if (geometry.isInstancedBufferGeometry)
+        throw new TypeError('autoUnwrap: unwrap the base geometry before instancing.');
+    const position = geometry.getAttribute('position');
+    if (position?.itemSize !== 3)
+        throw new TypeError('autoUnwrap: geometry requires a three-component position attribute.');
+    const count = position.count;
+    const corners = geometry.index?.count ?? count;
+    if (count === 0 || corners === 0)
+        throw new Error('autoUnwrap: geometry has no triangles. Check the operation that produced it (for example an empty CSG result).');
+    if (!Number.isSafeInteger(count) || count < 1 || count > limits.unwrapVertices)
+        throw new RangeError(`autoUnwrap: input exceeds ${limits.unwrapVertices} vertices supported by xatlasjs. Split the mesh before unwrapping.`);
+    if (!Number.isSafeInteger(corners) || corners % 3 !== 0)
+        throw new TypeError('autoUnwrap: geometry has an index count that is not a whole number of triangles.');
+    if (corners / 3 > limits.unwrapTriangles)
+        throw new RangeError(`autoUnwrap: triangle budget exceeds ${limits.unwrapTriangles}.`);
+    const attributes = Object.entries(geometry.attributes);
+    for (const [name, attribute] of attributes)
+        validateAttribute(name, attribute, count);
+    const normal = geometry.getAttribute('normal');
+    if (normal && normal.itemSize !== 3)
+        throw new TypeError('autoUnwrap: normal requires three components.');
+    const useNormals = !!opts.useNormals && !!normal;
+    for (const [name, targets] of Object.entries(geometry.morphAttributes)) {
+        if (!['position', 'normal', 'color'].includes(name))
+            throw new TypeError(`autoUnwrap: morph ${name} is unsupported; UV0 and tangents change during unwrapping.`);
+        if (name === 'normal' && targets.length && !useNormals)
+            throw new TypeError('autoUnwrap: normal morphs require base normals and useNormals: true to preserve their reference frame.');
+        for (const attribute of targets) {
+            validateAttribute(`morph ${name}`, attribute, count);
+            const base = geometry.getAttribute(name);
+            if (!base || attribute.itemSize !== base.itemSize)
+                throw new TypeError(`autoUnwrap: morph ${name} requires a matching base attribute.`);
+            attributes.push([`morph ${name}`, attribute]);
+        }
+    }
+    // Bound owned output buffers before reading attributes or entering native code.
+    const perVertexBytes = attributes.reduce((sum, [, attr]) => sum + attr.itemSize * attr.array.BYTES_PER_ELEMENT, 20);
+    if (perVertexBytes * Math.min(count + corners, limits.unwrapVertices) >
+        limits.unwrapAttributeBytes)
+        throw new RangeError(`autoUnwrap: attribute budget exceeds ${limits.unwrapAttributeBytes} bytes.`);
+    for (const [name, attribute] of attributes) {
+        const getters = [attribute.getX, attribute.getY, attribute.getZ, attribute.getW];
+        for (let i = 0; i < count; i++) {
+            for (let c = 0; c < attribute.itemSize; c++) {
+                const value = getters[c].call(attribute, i);
+                if (!Number.isFinite(value))
+                    throw new TypeError(`autoUnwrap: ${name} contains non-finite values.`);
+            }
+        }
+    }
+    if (geometry.index && (geometry.index.itemSize !== 1 || geometry.index.normalized))
+        throw new TypeError('autoUnwrap: index must be a scalar, non-normalized integer attribute.');
+    const index = new Uint32Array(corners);
+    for (let i = 0; i < corners; i++) {
+        const value = geometry.index ? geometry.index.getX(i) : i;
+        if (!Number.isSafeInteger(value) || value < 0 || value >= count)
+            throw new RangeError('autoUnwrap: index references an invalid source vertex.');
+        index[i] = value;
+    }
+    for (const { start, count: length, materialIndex = 0 } of geometry.groups) {
+        if (!Number.isSafeInteger(start) ||
+            !Number.isSafeInteger(length) ||
+            start < 0 ||
+            length < 0 ||
+            start % 3 ||
+            length % 3 ||
+            start + length > corners ||
+            !Number.isSafeInteger(materialIndex) ||
+            materialIndex < 0)
+            throw new TypeError('autoUnwrap: groups must reference complete source triangles and nonnegative material indices.');
+    }
+    return {
+        index,
+        positions: xyz(position, 'position'),
+        normals: useNormals ? xyz(normal, 'normal') : null,
+        useNormals,
+        resolution,
+        padding,
+    };
+}

package/lib/uv-shapes.js

@@ -32,6 +32,9 @@ export function remapUV(geo, options = {}) {
         values[i * 2 + 1] = nextV;
     }
     const cloned = geo.clone();
+    // BufferGeometry.clone() shares userData; owned UV results must not write
+    // warnings or later atlas bindings back into their source geometry.
+    cloned.userData = structuredClone(geo.userData);
     cloned.setAttribute('uv', new THREE.Float32BufferAttribute(values, 2));
     if ((scale[0] !== 1 || scale[1] !== 1) && cloned.hasAttribute('tangent')) {
         cloned.deleteAttribute('tangent');

package/lib/uv.d.ts

@@ -15,11 +15,11 @@
  */
 import * as THREE from 'three';
 export interface AutoUnwrapOptions {
-    /** Atlas texture resolution (power-of-2). Default 1024. */
+    /** Target atlas resolution, integer 1..4096. Actual packed dimensions may differ. Default 1024. */
     resolution?: number;
     /** Padding between charts in texels. Default 2. */
     padding?: number;
-    /** Bake surface normals when determining seams. Default false (faster). */
+    /** Use and preserve source normals; otherwise recompute. Required for normal morphs. Default false. */
     useNormals?: boolean;
 }
 /**
@@ -29,7 +29,13 @@ export interface AutoUnwrapOptions {
  * sampling, and (usually) a different vertex count than the input: xatlas
  * duplicates vertices along UV seams so each shell gets its own chart.
  *
- * Returns a *new* BufferGeometry; the input is left untouched.
+ * Returns a *new* BufferGeometry; the input is left untouched. Seam remapping
+ * preserves per-vertex attributes, position/normal/color morphs, groups and JSON
+ * userData. Replaces UV0 and removes stale tangents. Normal behavior is unchanged:
+ * recompute by default, preserve source normals with useNormals: true.
+ * The current xatlasjs adapter supports at most 65,536 input AND output vertices;
+ * split larger meshes. Instancing, multi-page atlases and changed face order are
+ * rejected rather than returning corrupt attribute correspondence.
  *
  * @example
  * const raw = boxGeo(1, 2, 1);

package/lib/uv.js

@@ -22,6 +22,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import * as THREE from 'three';
+import { prepareUnwrap, remapUnwrapAttribute, validateAtlasRemap } from "./uv-data.js";
 // Lazy xatlas init — pays ~100-200ms on first call, then free.
 let _xatlasReady = null;
 async function getXatlas() {
@@ -48,7 +49,13 @@ async function getXatlas() {
  * sampling, and (usually) a different vertex count than the input: xatlas
  * duplicates vertices along UV seams so each shell gets its own chart.
  *
- * Returns a *new* BufferGeometry; the input is left untouched.
+ * Returns a *new* BufferGeometry; the input is left untouched. Seam remapping
+ * preserves per-vertex attributes, position/normal/color morphs, groups and JSON
+ * userData. Replaces UV0 and removes stale tangents. Normal behavior is unchanged:
+ * recompute by default, preserve source normals with useNormals: true.
+ * The current xatlasjs adapter supports at most 65,536 input AND output vertices;
+ * split larger meshes. Instancing, multi-page atlases and changed face order are
+ * rejected rather than returning corrupt attribute correspondence.
  *
  * @example
  * const raw = boxGeo(1, 2, 1);
@@ -56,92 +63,56 @@ async function getXatlas() {
  * const crate = new THREE.Mesh(unwrapped, woodPBR);
  */
 export async function autoUnwrap(geometry, opts = {}) {
+    const prepared = prepareUnwrap(geometry, opts);
     const xa = await getXatlas();
-    // xatlas needs an indexed BufferGeometry. Convert if necessary.
-    const src = geometry.index ? geometry : toIndexed(geometry);
-    const posAttr = src.getAttribute('position');
-    const normAttr = src.getAttribute('normal');
-    const idxAttr = src.getIndex();
-    if (!posAttr || !idxAttr) {
-        throw new Error('autoUnwrap: geometry requires position attribute and an index');
-    }
-    // T2.4: measured — xatlas accepts an empty mesh and returns an empty atlas
-    // without complaint, so a zero-triangle geometry used to come back with zero
-    // vertices and NO uv attribute, and the failure only surfaced later as a
-    // texture that would not appear. The realistic upstream cause is a CSG result
-    // that collapsed to nothing.
-    if (idxAttr.count === 0 || posAttr.count === 0) {
-        throw new Error('autoUnwrap: geometry has no triangles. Nothing can be unwrapped — check the operation that produced it (an empty CSG result is the usual cause).');
-    }
-    if (idxAttr.count % 3 !== 0) {
-        throw new Error(`autoUnwrap: geometry has ${idxAttr.count} indices, which is not a whole number of triangles.`);
-    }
     xa.createAtlas();
-    const useNormals = Boolean(opts.useNormals && normAttr);
-    const indexArray = idxAttr.array instanceof Uint32Array
-        ? idxAttr.array
-        : new Uint32Array(idxAttr.array);
-    const addRes = xa.addMesh(indexArray, new Float32Array(posAttr.array), useNormals && normAttr ? new Float32Array(normAttr.array) : null, null, 'kiln-mesh', useNormals, false, 1);
-    if (!addRes) {
-        xa.destroyAtlas();
-        throw new Error('autoUnwrap: xatlas.addMesh failed (non-manifold or degenerate geometry?)');
-    }
-    const result = xa.generateAtlas({}, { resolution: opts.resolution ?? 1024, padding: opts.padding ?? 2 }, true);
-    const mesh = result.meshes[0];
-    if (!mesh) {
-        xa.destroyAtlas();
-        throw new Error('autoUnwrap: xatlas returned no meshes');
-    }
-    const out = new THREE.BufferGeometry();
-    out.setAttribute('position', new THREE.BufferAttribute(new Float32Array(mesh.vertex.vertices), 3));
-    if (mesh.vertex.normals) {
-        out.setAttribute('normal', new THREE.BufferAttribute(new Float32Array(mesh.vertex.normals), 3));
-    }
-    if (mesh.vertex.coords1) {
-        out.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(mesh.vertex.coords1), 2));
-    }
-    if (mesh.index) {
-        out.setIndex(new THREE.BufferAttribute(new Uint32Array(mesh.index), 1));
+    try {
+        const added = xa.addMesh(prepared.index, prepared.positions, prepared.normals, null, 'kiln-mesh', prepared.useNormals, false, 1);
+        if (!added)
+            throw new Error('autoUnwrap: xatlas.addMesh failed (non-manifold or degenerate geometry?).');
+        const result = xa.generateAtlas({}, { resolution: prepared.resolution, padding: prepared.padding }, true);
+        const mesh = result.meshes[0];
+        if (!mesh || result.meshCount !== 1)
+            throw new Error('autoUnwrap: xatlas returned no single mesh.');
+        if (result.atlasCount !== 1 ||
+            !Number.isSafeInteger(result.width) ||
+            result.width <= 0 ||
+            !Number.isSafeInteger(result.height) ||
+            result.height <= 0)
+            throw new Error('autoUnwrap: xatlas must return one valid atlas; multiple atlas pages are unsupported.');
+        const remap = validateAtlasRemap(mesh, prepared.index, geometry.getAttribute('position').count);
+        const out = new THREE.BufferGeometry();
+        for (const [name, attribute] of Object.entries(geometry.attributes)) {
+            if (name === 'uv' || name === 'tangent' || (name === 'normal' && !prepared.useNormals))
+                continue;
+            out.setAttribute(name, remapUnwrapAttribute(attribute, remap.oldIndexes));
+        }
+        for (const [name, targets] of Object.entries(geometry.morphAttributes)) {
+            // Three's declaration lists standard keys, although its runtime uses a dictionary.
+            out.morphAttributes[name] = targets.map((attribute) => remapUnwrapAttribute(attribute, remap.oldIndexes));
+        }
+        out.morphTargetsRelative = geometry.morphTargetsRelative;
+        out.setIndex(new THREE.BufferAttribute(new Uint32Array(remap.index), 1));
+        out.setAttribute('uv', new THREE.BufferAttribute(new Float32Array(remap.uv), 2));
+        out.name = geometry.name;
+        // Triangle correspondence was checked before retaining material groups and draw range.
+        out.groups = geometry.groups.map((group) => ({ ...group }));
+        out.setDrawRange(geometry.drawRange.start, geometry.drawRange.count);
+        out.userData = JSON.parse(JSON.stringify(geometry.userData));
+        // xatlas's requested resolution is not the returned width/height (often rectangular).
+        out.userData['atlas'] = {
+            width: result.width,
+            height: result.height,
+            atlasCount: result.atlasCount,
+        };
+        if (!out.getAttribute('normal'))
+            out.computeVertexNormals();
+        repairZeroNormals(out);
+        return out;
     }
-    // Atlas metadata lives on userData so downstream tools (texture baking,
-    // projection painting) can sample the atlas resolution.
-    //
-    // T2.4 — read `width`/`height`, do NOT assume `resolution` squared. `resolution`
-    // is an upper bound xatlas packs within, not the atlas it returns: a CSG'd box
-    // at resolution 1024 measured 917x1085. A baker that allocated a square
-    // `resolution x resolution` target would sample the wrong texels along one
-    // axis, which reads as a subtle uniform stretch rather than an obvious break.
-    out.userData['atlas'] = {
-        width: result.width,
-        height: result.height,
-        atlasCount: result.atlasCount,
-    };
-    if (!out.getAttribute('normal'))
-        out.computeVertexNormals();
-    repairZeroNormals(out);
-    // xatlas can pack every chart and still hand back a mesh with no coords1 when
-    // the input degenerates. Better to say so than to return a geometry whose
-    // missing `uv` only shows up as an untextured surface much later.
-    if (!out.getAttribute('uv')) {
+    finally {
         xa.destroyAtlas();
-        throw new Error('autoUnwrap: xatlas produced no UV coordinates for this geometry (degenerate or zero-area triangles?).');
     }
-    xa.destroyAtlas();
-    return out;
-}
-/**
- * Convert a non-indexed BufferGeometry to an indexed one via naive
- * sequential indexing. Sufficient for xatlas input (it re-indexes anyway
- * during chart generation).
- */
-function toIndexed(geo) {
-    const posAttr = geo.getAttribute('position');
-    const indices = new Uint32Array(posAttr.count);
-    for (let i = 0; i < posAttr.count; i++)
-        indices[i] = i;
-    const out = geo.clone();
-    out.setIndex(new THREE.BufferAttribute(indices, 1));
-    return out;
 }
 /**
  * Replace any zero-length or non-finite normal with one derived from the faces

package/lib/views/camera.d.ts

@@ -97,9 +97,9 @@ export declare function withCameraVisibility<T>(root: unknown, shot: ResolvedCam
  * A derivative GLB
  * serialized from a scene with hidden nodes (authored, or isolated by
  * {@link withCameraVisibility}) would ship them to the GPU. Every node with
- * `visible = false` leaves with its subtree, which is what three draws. Returns the root
- * itself when nothing is hidden, else a pruned clone; the caller's scene is never mutated and
- * restores `.visible` itself.
+ * `visible = false` removes drawing from its subtree. Required skeleton ancestors remain
+ * as transforms without drawing payloads. Returns the root itself when nothing is hidden,
+ * else an independent pruned hierarchy/skeleton; the caller restores `.visible` itself.
  */
 export declare function withoutHiddenMeshes(root: Object3D): Object3D;
 /** Flat geometry renderer with exact orthographic/perspective projection and near/far clipping. */