@instruktlabs/kiln 1.2.1 → 1.2.3

package/src/texture-bake.ts

@@ -41,6 +41,12 @@
 
 import { createHash } from 'node:crypto';
 import * as THREE from 'three';
+import {
+  collectAtlasProvenance,
+  readAtlasEncodedTexture,
+  readValidatedAtlasDelivery,
+  type AtlasReferenceV1,
+} from './atlas-provenance';
 import type { EncodedTextureData, KilnTextureMetadata, TextureUsage } from './textures';
 
 export interface BakedTextureBindingV1 {
@@ -94,6 +100,8 @@ export interface BakedTextureProvenanceV1 {
    * regenerate the exact bytes. Absent for textures loaded from a file.
    */
   procedural?: ProceduralRecipeRecord;
+  /** Compact atlas source identity; the export scene table owns its recipe/manifest. */
+  atlas?: AtlasReferenceV1;
 }
 
 /** The `userData.kilnProcedural` stamp `proceduralTexture()` leaves behind. */
@@ -228,6 +236,7 @@ export async function bakeSceneTextures(
   root: THREE.Object3D,
   warnings: string[],
 ): Promise<BakedTextureProvenanceV1[]> {
+  const atlas = collectAtlasProvenance(root);
   // Collect first, encode second: traversal is sync, encoding is not, and doing
   // them together would interleave awaits with a mutating walk.
   const pending = new Map<
@@ -251,7 +260,8 @@ export async function bakeSceneTextures(
       for (const [slot, usage] of SLOT_USAGE) {
         const texture = bag[slot];
         if (!isTexture(texture)) continue;
-        if ((texture.userData as Record<string, unknown>)['encoded']) continue;
+        if ((texture.userData as Record<string, unknown>)['encoded'] && !atlas.texture(texture))
+          continue;
         const existing = pending.get(texture) ?? { texture, bindings: [] };
         existing.bindings.push({
           node: node.name || '(unnamed node)',
@@ -267,19 +277,84 @@ export async function bakeSceneTextures(
   const baked: BakedTextureProvenanceV1[] = [];
   for (const entry of pending.values()) {
     const name = entry.texture.name || '(unnamed texture)';
-    const raw = readPixels(entry.texture);
+    const atlasRef = atlas.texture(entry.texture);
+    const atlasRecord = atlasRef && atlas.table!.atlases.find((a) => a.id === atlasRef.id)!;
+    const encoded = atlasRef ? readAtlasEncodedTexture(entry.texture) : undefined;
+    if (
+      encoded &&
+      (encoded.mime !== 'image/png' ||
+        !(encoded.bytes instanceof Uint8Array) ||
+        encoded.bytes.length > 16_777_216)
+    )
+      throw new TypeError('Atlas baked encoding must be bounded PNG bytes.');
+    const raw =
+      encoded && atlasRecord
+        ? {
+            width: atlasRecord.spec.width,
+            height: atlasRecord.spec.height,
+            channels: 4 as const,
+            data: new Uint8Array(0),
+          }
+        : readPixels(entry.texture);
     const firstBinding = entry.bindings[0]!;
     const bindingSummary = `material ${JSON.stringify(firstBinding.material)} (${firstBinding.slot})${entry.bindings.length > 1 ? ` and ${entry.bindings.length - 1} other binding(s)` : ''}`;
     if (typeof raw === 'string') {
+      if (atlasRef)
+        throw new TypeError(
+          `Atlas has stale compiled provenance: ${raw}; rebuild with textureAtlas() or remove atlas metadata for a manual texture.`,
+        );
       warnings.push(
         `Texture ${JSON.stringify(name)} on ${bindingSummary} was dropped from the GLB: ${raw}.`,
       );
       continue;
     }
 
+    if (atlasRecord) {
+      const stale = () =>
+        new TypeError(
+          'Atlas has stale compiled provenance: rebuild with textureAtlas() after editing pixels, or remove atlas metadata for a manual texture.',
+        );
+      if (encoded) {
+        const delivery = readValidatedAtlasDelivery(entry.texture);
+        if (delivery) {
+          if (
+            delivery.id !== atlasRef!.id ||
+            delivery.finalMime !== encoded.mime ||
+            delivery.finalImageSha256 !==
+              `sha256:${createHash('sha256').update(encoded.bytes).digest('hex')}`
+          )
+            throw stale();
+        } else {
+          const sharp = (await import('sharp')).default;
+          const image = sharp(encoded.bytes, {
+            limitInputPixels: atlasRecord.spec.width * atlasRecord.spec.height,
+          });
+          const metadata = await image.metadata();
+          if (
+            metadata.width !== atlasRecord.spec.width ||
+            metadata.height !== atlasRecord.spec.height
+          )
+            throw stale();
+          const decoded = await image.ensureAlpha().raw().toBuffer();
+          if (
+            `sha256:${createHash('sha256').update(decoded).digest('hex')}` !==
+            atlasRecord.manifest.decodedPixelHash
+          )
+            throw stale();
+        }
+      } else if (
+        raw.width !== atlasRecord.spec.width ||
+        raw.height !== atlasRecord.spec.height ||
+        raw.channels !== 4 ||
+        `sha256:${createHash('sha256').update(raw.data).digest('hex')}` !==
+          atlasRecord.manifest.decodedPixelHash
+      )
+        throw stale();
+    }
+
     let bytes: Uint8Array;
     try {
-      bytes = await encodePngFromRaw(raw);
+      bytes = encoded?.bytes ?? (await encodePngFromRaw(raw));
     } catch (err) {
       warnings.push(
         `Texture ${JSON.stringify(name)} on ${bindingSummary} was dropped from the GLB: PNG encoding failed (${err instanceof Error ? err.message : String(err)}).`,
@@ -302,18 +377,20 @@ export async function bakeSceneTextures(
     // metallic-roughness map occupies both Three.js slots, where choosing the
     // first (`roughnessMap`) loses the authored combined-channel meaning.
     const primaryUsage =
+      atlasRecord?.spec.usage ??
       recipe?.usage ??
       (entry.bindings.some(({ slot }) => slot === 'roughnessMap') &&
       entry.bindings.some(({ slot }) => slot === 'metalnessMap')
         ? 'metallicRoughness'
         : (entry.bindings[0]?.usage ?? 'albedo'));
-    (entry.texture.userData as Record<string, unknown>)['kilnTexture'] = {
-      usage: primaryUsage,
-      colorSpace,
-      width: raw.width,
-      height: raw.height,
-      hasAlpha: hasTranslucentPixel(raw),
-    } satisfies KilnTextureMetadata;
+    if (!encoded)
+      (entry.texture.userData as Record<string, unknown>)['kilnTexture'] = {
+        usage: primaryUsage,
+        colorSpace,
+        width: raw.width,
+        height: raw.height,
+        hasAlpha: hasTranslucentPixel(raw),
+      } satisfies KilnTextureMetadata;
 
     const sha1 = createHash('sha1').update(bytes).digest('hex');
     const imageSha256 = `sha256:${createHash('sha256').update(bytes).digest('hex')}` as const;
@@ -334,6 +411,7 @@ export async function bakeSceneTextures(
       imageSha256,
       sha1,
       ...(recipe ? { procedural: recipe } : {}),
+      ...(atlasRef ? { atlas: atlasRef } : {}),
     });
   }
 

package/src/texture-resolver.ts

@@ -8,6 +8,24 @@
  */
 import type * as THREE from 'three';
 import type { TextureUsage } from './textures';
+import type { PinnedMaterialMapPortV1 } from './pinned-material-map';
+
+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,
@@ -21,11 +39,17 @@ import type {
 } from './material-recipes';
 
 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>;
 }
 
@@ -47,6 +71,37 @@ export function createTextureResolver(
       }
       return (await cache.load(resourceId as ApprovedTextureResourceId)).texture;
     },
+    async preparePortableTexture(
+      resourceId: unknown,
+      context?: { signal?: AbortSignal },
+    ): Promise<PreparedPortableTextureV3> {
+      context?.signal?.throwIfAborted();
+      if (typeof resourceId !== 'string')
+        throw new RangeError('Unsupported approved texture resource ID.');
+      const resolved = await cache.resolveAsync(resourceId as ApprovedTextureResourceId);
+      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: unknown, overrides?: unknown): Promise<THREE.MeshStandardMaterial> {
       if (typeof id !== 'string') throw new TypeError('materialRecipe id must be a string');
       return applyTrustedMaterialRecipe(

package/src/tools/materials.ts

@@ -3,14 +3,14 @@ import {
   assertMaterialJson,
   materialLibraryHashSchema,
   materialLibraryIdSchema,
-  materialLibraryPayloadSchema,
+  materialLibraryPayloadAnySchema,
   materialLibraryPortableSpec,
   materialSourceSchema,
-  proceduralMaterialDraftSchema,
   type MaterialLibrary,
-  type MaterialManifestV1,
+  type MaterialManifest,
 } from '../material-library';
 import { createMaterialRecordV1, decodeMaterialLibraryPayload } from '../material-library-node';
+import { createProceduralMaterialRecord } from '../material-authoring-node';
 import { createMaterialPresetDraft, listMaterialPresets } from '../material-presets';
 import { nestedRecordDescription, requireActionFields } from './actions';
 import type { KilnToolDef } from './registry';
@@ -89,18 +89,18 @@ export const materialToolInput = z.strictObject({
     .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.',
+      '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 and complete normalized records with embedded PNG bytes.',
+      'import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes.',
       'shape:material-import',
     ),
   ),
 });
-const materialResult = (material: MaterialManifestV1) => ({
+const materialResult = (material: MaterialManifest) => ({
   ok: true,
   material,
   portableSpec: materialLibraryPortableSpec(material),
@@ -157,7 +157,7 @@ export function createKilnMaterialDef(
   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.',
+      '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: {
@@ -225,15 +225,19 @@ export function createKilnMaterialDef(
           }
         }
         case 'create-procedural': {
-          const record = await createMaterialRecordV1(
-            proceduralMaterialDraftSchema.parse(input.draft),
+          const { record, dependencies } = await createProceduralMaterialRecord(
+            input.draft,
+            library,
+          );
+          const [material] = await library.import(
+            [record],
+            dependencies.length ? { materials: dependencies } : undefined,
           );
-          const [material] = await library.import([record]);
           return materialResult(material!);
         }
         case 'import': {
           const records = await decodeMaterialLibraryPayload(
-            materialLibraryPayloadSchema.parse(input.payload),
+            materialLibraryPayloadAnySchema.parse(input.payload),
           );
           const materials = await library.import(records);
           return {

package/src/tools/registry.ts

@@ -492,26 +492,16 @@ async function renderDerivativeCell(
 ): Promise<import('../views').DerivativeCellRenderResult> {
   let derivativeRoot = input.root as THREE.Object3D;
   if (input.backfaceCull === false) {
-    derivativeRoot = derivativeRoot.clone(true);
-    derivativeRoot.traverse((node) => {
-      const mesh = node as THREE.Mesh;
-      if (!mesh.isMesh) return;
-      const prepare = (material: THREE.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');
+    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');
   derivativeRoot = withoutHiddenMeshes(derivativeRoot);
   const rendered = await renderSceneToGLB(derivativeRoot, {
@@ -2807,7 +2797,7 @@ export async function buildProgramAssetDraft(
   const dependencies = [
     ...(rendered.materialResourceProvenance ?? []),
     ...(rendered.materialLibraryDependencies ?? []).map((manifest) => ({
-      kind: 'kiln.material.v1',
+      kind: `kiln.material.v${manifest.schemaVersion}`,
       delivery: 'runtime',
       manifest,
     })),

package/src/tools/review.ts

@@ -216,7 +216,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/src/uv-data.ts

@@ -0,0 +1,238 @@
+/** Internal safety and correspondence boundary for the xatlasjs adapter. */
+import * as THREE from 'three';
+import { GEOMETRY_ALLOCATION_LIMITS as limits } from './geometry-budget';
+
+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 function validateAtlasRemap(mesh: AtlasMesh, inputIndex: Uint32Array, sourceCount: number) {
+  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: Attribute): attribute is THREE.InterleavedBufferAttribute {
+  return (attribute as THREE.InterleavedBufferAttribute).isInterleavedBufferAttribute === true;
+}
+
+/** Copy raw storage, including normalized integers and half floats, without welding. */
+export function remapUnwrapAttribute(
+  attribute: Attribute,
+  oldIndexes: ArrayLike<number>,
+): THREE.BufferAttribute {
+  const ArrayType = attribute.array.constructor as new (length: number) => THREE.TypedArray;
+  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 as Attribute & { isFloat16BufferAttribute?: boolean })
+    .isFloat16BufferAttribute
+    ? new THREE.Float16BufferAttribute(
+        array as Uint16Array,
+        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: string, attribute: Attribute, count: number): void {
+  if (
+    (attribute as THREE.InstancedBufferAttribute).isInstancedBufferAttribute ||
+    (interleaved(attribute) &&
+      (attribute.data as THREE.InterleavedBuffer & { isInstancedInterleavedBuffer?: boolean })
+        .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: Attribute, name: string): Float32Array {
+  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: THREE.BufferGeometry,
+  opts: { resolution?: number; padding?: number; useNormals?: boolean },
+) {
+  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 as THREE.InstancedBufferGeometry).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/src/uv-shapes.ts

@@ -47,6 +47,9 @@ export function remapUV(
     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');