@instruktlabs/kiln 1.2.2 → 1.2.3

package/src/character.ts

@@ -1,11 +1,15 @@
 /**
- * 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';
+import { GEOMETRY_ALLOCATION_LIMITS } from './geometry-budget';
+import { AuthoringDiagnosticError } from './evaluator/authoring-diagnostic';
+
+export { createSkinnedPart, type CreateSkinnedPartOptions } from './skin-binding';
 
 export const KILN_CHARACTER_JOINT_EXTRAS_KEY = 'kilnCharacterJoint' as const;
 export const KILN_CHARACTER_RIG_EXTRAS_KEY = 'kilnCharacterRig' as const;
@@ -637,6 +641,107 @@ export interface CharacterJointNodeEvidenceV1 {
   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 function createBoneChain(
+  chainName: string,
+  segments: readonly JointChainSegmentV1[],
+  options: CreateJointChainOptionsV1 = {},
+): BoneChainResultV1 {
+  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: string,
+  segments: readonly JointChainSegmentV1[],
+  options: CreateJointChainOptionsV1 = {},
+): BoneChainResultV1 {
+  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<string>(),
+    names = new Set<string>();
+  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: THREE.Object3D): CharacterJointNodeEvidenceV1[] {
   const joints: CharacterJointNodeEvidenceV1[] = [];

package/src/community-exporter.ts

@@ -1,10 +1,16 @@
 import * as THREE from 'three';
 import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
-import type { Document } from '@gltf-transform/core';
+import { GLB_BUFFER, type Document } from '@gltf-transform/core';
 import { createGltfIO } from './gltf-io';
 import { openShellExtras } from './open-shell';
 import { rigExtrasForExport } from './rig-export';
 import type { AuthorExtras } from './user-data-extras';
+import { assertPortableMaterialSides } from './material-export';
+import {
+  collectAtlasProvenance,
+  refreshAtlasDocumentProvenance,
+  type AtlasProvenanceCollection,
+} from './atlas-provenance';
 import {
   KILN_SEMANTIC_EXTRAS_KEY,
   validateSemanticMetadataV1,
@@ -60,9 +66,14 @@ export async function communitySceneDocument(
   clips: THREE.AnimationClip[],
   platform: ExportPlatform = browserPlatform,
   authorExtras?: AuthorExtras,
+  atlas: AtlasProvenanceCollection = collectAtlasProvenance(root),
 ): Promise<Document> {
+  assertPortableMaterialSides(root);
   const materials = new Map<THREE.Material, THREE.Material>();
+  const originalMaterials = new Map<THREE.Material, THREE.Material>();
+  const originalGeometries = new Map<THREE.Mesh, THREE.BufferGeometry>();
   const textures = new Map<THREE.Texture, THREE.Texture>();
+  const directImages = new Map<THREE.Texture, { bytes: Uint8Array; mime: string }>();
   const nodes = new Map<THREE.Object3D, THREE.Object3D>();
   const encoded: Array<Promise<void>> = [];
   function texture(source: THREE.Texture): THREE.Texture {
@@ -75,6 +86,11 @@ export async function communitySceneDocument(
     textures.set(source, copy);
     const bytes = source.userData['encoded'] as { bytes?: Uint8Array; mime?: string } | undefined;
     if (bytes?.bytes) {
+      // Canvas stores premultiplied color and can discard hidden cutout RGB or
+      // round partial-alpha channels. Keep already-encoded direct images when
+      // the exporter does not need to flip or derive a new texture from them.
+      if (!copy.flipY && (bytes.mime === 'image/png' || bytes.mime === 'image/jpeg'))
+        directImages.set(copy, { bytes: bytes.bytes, mime: bytes.mime });
       encoded.push(
         (async () => {
           copy.image = await platform.decode(bytes.bytes!);
@@ -104,6 +120,7 @@ export async function communitySceneDocument(
         (copy as unknown as Record<string, unknown>)[key] = texture(value);
     }
     materials.set(source, copy);
+    originalMaterials.set(copy, source);
     return copy;
   }
   function node(source: THREE.Object3D): THREE.Object3D {
@@ -137,6 +154,7 @@ export async function communitySceneDocument(
         map: sprite.material.map ? texture(sprite.material.map) : null,
       });
       Object.assign(spriteMaterial.userData, authorExtras?.material(sprite.material));
+      originalMaterials.set(spriteMaterial, sprite.material);
       copy = new THREE.Mesh(geometry, spriteMaterial);
       THREE.Object3D.prototype.copy.call(copy, shadow, false);
     }
@@ -172,6 +190,7 @@ export async function communitySceneDocument(
       const original = source as THREE.Mesh;
       const mesh = copy as THREE.Mesh;
       mesh.geometry = cleanClone(original.geometry);
+      originalGeometries.set(mesh, original.geometry);
       mesh.material = Array.isArray(original.material)
         ? original.material.map(material)
         : material(original.material);
@@ -195,6 +214,42 @@ export async function communitySceneDocument(
   }
   await Promise.all(encoded);
   await platform.prepare(textures.size > 0);
+  // Upstream channel-packing and normal-basis conversions use drawImage, which
+  // does not accept a DataTexture's {data,width,height} image in either host.
+  // Adapt only those detached inputs; direct color textures keep their bytes.
+  const canvasInputs = new Map<THREE.Texture, THREE.Texture>();
+  const canvasInput = (map: THREE.Texture | null): THREE.Texture | null => {
+    const raw = map?.image as { data?: Uint8Array; width: number; height: number } | undefined;
+    if (!map || !raw?.data) return map;
+    const found = canvasInputs.get(map);
+    if (found) return found;
+    const { data, width, height } = raw;
+    const canvas = new OffscreenCanvas(width, height);
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('A 2D canvas is required to prepare export texture channels.');
+    context.putImageData(new ImageData(new Uint8ClampedArray(data), width, height), 0, 0);
+    const adapted = new THREE.Texture().copy(map);
+    adapted.source = new THREE.TextureSource(canvas);
+    canvasInputs.set(map, adapted);
+    const direct = directImages.get(map);
+    if (direct) directImages.set(adapted, direct);
+    return adapted;
+  };
+  for (const material of materials.values()) {
+    // putImageData ignores the canvas transform used by GLTFExporter for flipY.
+    // A canvas image makes that explicit orientation request reach drawImage.
+    for (const [key, value] of Object.entries(material)) {
+      if (value instanceof THREE.Texture && value.flipY && value.image?.data)
+        (material as unknown as Record<string, unknown>)[key] = canvasInput(value);
+    }
+    const standard = material as THREE.MeshStandardMaterial;
+    if (!standard.isMeshStandardMaterial) continue;
+    if (standard.metalnessMap !== standard.roughnessMap) {
+      standard.metalnessMap = canvasInput(standard.metalnessMap);
+      standard.roughnessMap = canvasInput(standard.roughnessMap);
+    }
+    standard.normalMap = canvasInput(standard.normalMap);
+  }
   const exportClips = clips.map((clip) => {
     const cloned = cleanClone(clip);
     // UUID-targeted clips must point at the export copy, not the live scene.
@@ -220,7 +275,55 @@ export async function communitySceneDocument(
     });
     return cloned;
   });
-  const bytes = await new GLTFExporter().parseAsync(copy, {
+  const preservedImages = new Map<number, { bytes: Uint8Array; mime: string }>();
+  const exporter = new GLTFExporter().register(() => ({
+    writeMesh(mesh, definition) {
+      const geometry = originalGeometries.get(mesh);
+      const binding = geometry && atlas.binding(geometry);
+      if (binding)
+        for (const primitive of definition.primitives as Array<{
+          extras?: Record<string, unknown>;
+        }>)
+          primitive.extras = { ...primitive.extras, kilnAtlasBinding: binding };
+    },
+    async writeMaterialAsync(material, definition) {
+      const source = originalMaterials.get(material);
+      if (!source) return;
+      const bag = source as unknown as Record<string, THREE.Texture | undefined>;
+      const pbr = definition.pbrMetallicRoughness as
+        | {
+            baseColorTexture?: { extras?: Record<string, unknown> };
+            metallicRoughnessTexture?: { extras?: Record<string, unknown> };
+          }
+        | undefined;
+      for (const [slot, info] of [
+        ['map', pbr?.baseColorTexture],
+        ['normalMap', definition.normalTexture as { extras?: Record<string, unknown> } | undefined],
+        ['metalnessMap', pbr?.metallicRoughnessTexture],
+        ['roughnessMap', pbr?.metallicRoughnessTexture],
+        [
+          'emissiveMap',
+          definition.emissiveTexture as { extras?: Record<string, unknown> } | undefined,
+        ],
+        ['aoMap', definition.occlusionTexture as { extras?: Record<string, unknown> } | undefined],
+      ] as const) {
+        const texture = bag[slot],
+          ref = texture && atlas.texture(texture);
+        if (ref && info) {
+          const prior = info.extras?.['kilnAtlasReference'] as { id?: string } | undefined;
+          if (prior && prior.id !== ref.id)
+            throw new TypeError('Atlas channel packing requires one exact source identity.');
+          info.extras = { ...info.extras, kilnAtlasReference: ref };
+        }
+      }
+    },
+    writeTexture(map, definition) {
+      const direct = directImages.get(map);
+      if (direct && typeof definition['source'] === 'number')
+        preservedImages.set(definition['source'], direct);
+    },
+  }));
+  const bytes = await exporter.parseAsync(copy, {
     binary: true,
     trs: true,
     onlyVisible: false,
@@ -228,6 +331,37 @@ export async function communitySceneDocument(
   });
   const io = createGltfIO();
   const json = await io.binaryToJSON(new Uint8Array(bytes as ArrayBuffer));
+  for (const [index, original] of preservedImages) {
+    const image = json.json.images?.[index];
+    if (!image) throw new Error('The glTF converter lost a direct texture image.');
+    const uri = `kiln-direct-image-${index}`;
+    image.uri = uri;
+    image.mimeType = original.mime;
+    delete image.bufferView;
+    json.resources[uri] = new Uint8Array(original.bytes);
+  }
+  // GLTFExporter includes four-byte buffer alignment in generated image views.
+  // Keep the BIN allocation aligned but end a PNG's view at its IEND chunk.
+  // Direct authored bytes above remain untouched; this is not an input decoder.
+  for (const image of json.json.images ?? []) {
+    if (image.mimeType !== 'image/png' || image.bufferView === undefined) continue;
+    const view = json.json.bufferViews![image.bufferView]!;
+    const buffer = json.resources[json.json.buffers?.[view.buffer]?.uri ?? GLB_BUFFER]!;
+    const start = view.byteOffset ?? 0;
+    const png = buffer.subarray(start, start + view.byteLength);
+    const data = new DataView(png.buffer, png.byteOffset, png.byteLength);
+    for (let offset = 8; offset + 12 <= png.length; ) {
+      const length = data.getUint32(offset),
+        end = offset + length + 12;
+      if (end > png.length) break;
+      if (data.getUint32(offset + 4) === 0x49454e44 && length === 0) {
+        if (png.length - end <= 3 && png.subarray(end).every((byte) => byte === 0))
+          view.byteLength = end;
+        break;
+      }
+      offset = end;
+    }
+  }
   // Three names texture/sampler bindings; glTF Transform models textures by
   // image. Carry the first named binding onto an unnamed shared image so the
   // conversion retains a useful authored resource name without duplicating it.
@@ -236,7 +370,13 @@ export async function communitySceneDocument(
     const image = json.json.images?.[binding.source];
     if (image && !image.name) image.name = binding.name;
   }
-  return io.readJSON(json);
+  const document = await io.readJSON(json);
+  if (atlas.table) {
+    const scene = document.getRoot().getDefaultScene() ?? document.getRoot().listScenes()[0]!;
+    scene.setExtras({ ...scene.getExtras(), kilnAtlasProvenance: atlas.table });
+    await refreshAtlasDocumentProvenance(document);
+  }
+  return document;
 }
 
 /** Encode the effective UV matrix in glTF's T*R*S order, including manual

package/src/discovery/helper-contracts.ts

@@ -1176,6 +1176,74 @@ define(
     intents: ['create a body-plan-neutral articulated chain'],
   },
 );
+define(
+  'createBoneChain',
+  {
+    ...nodeFacts,
+    axes: 'Explicit local forward/bend axes and rest transforms; body-plan neutral.',
+    origin: 'Offsets are local to the preceding bone; first offset is under the supplied parent.',
+    parameters: [
+      '1..1024 descriptors; unique roles and sanitized node names across the parent hierarchy. The first parentRole is inferred from a declared parent joint; an explicit value must agree.',
+    ],
+    preservation: [
+      'Creates real Bones with the same versioned semantic descriptors as rigid createJointChain; leaves existing nodes untouched.',
+    ],
+    semantics: ['Preserves declared roles, local rest frames, axes, contacts and end-effectors.'],
+    cost: 'Linear in descriptors and existing parent hierarchy; validates before adding the chain.',
+  },
+  {
+    kind: 'assembly',
+    references: ['src/character.ts'],
+    tags: ['rig', 'bones', 'skinning'],
+    aliases: ['bone chain', 'semantic bones'],
+    intents: ['create bones for a skinned custom body plan'],
+    related: [
+      { name: 'createJointChain', relation: 'alternative' },
+      { name: 'createSkinnedPart', relation: 'companion' },
+    ],
+    limitations: [
+      'Does not bind geometry, create animations, choose a body plan or generate anatomical weights.',
+    ],
+  },
+);
+define(
+  'createSkinnedPart',
+  {
+    ...nodeFacts,
+    ownership:
+      'Owns cloned geometry, influence arrays and inverse bind matrices. Materials and caller-owned bones are shared; source geometry stays unchanged.',
+    coordinates:
+      'Geometry is mesh-local; supplied mesh transforms are local to the required parent. All bones must share its existing hierarchy and be in the intended rest pose.',
+    axes: 'No forced character forward axis. Local rotation options are Euler XYZ degrees, matching createPart.',
+    origin: 'The supplied geometry origin is unchanged.',
+    topology: [
+      'Creates a skinned mesh on cloned unchanged topology; no automatic solid repair or watertightness claim.',
+    ],
+    parameters: [
+      '1..1024 distinct named Bones; 1..262144 xyz vertices; 128 MiB total cloned attribute storage plus new influences.',
+      'Exactly four valid indices and finite nonnegative weights per vertex. Default requires each weight <=1 and sum within 1e-5 of one; normalizeWeights:true explicitly normalizes positive finite sums. Zero sums never receive invented weights.',
+      'Existing skin attributes, singular/nonfinite bind transforms and ambiguous bone names are rejected.',
+    ],
+    preservation: [
+      'Unchanged topology retains UV/color/morph attributes and material groups on an owned clone. Skeleton order matches the supplied bone array.',
+    ],
+    semantics: ['Optional semantic metadata is stamped on the returned Mesh_name.'],
+    cost: 'O(vertices + attributes + bones + parent hierarchy); no automatic weighting or anatomical fit computation.',
+  },
+  {
+    kind: 'assembly',
+    references: ['src/skin-binding.ts'],
+    tags: ['rig', 'skinning', 'weights', 'binding'],
+    aliases: ['skin binding', 'weighted mesh'],
+    intents: ['bind explicit vertex influences without mutating shared geometry'],
+    related: [{ name: 'createBoneChain', relation: 'prerequisite' }],
+    limitations: [
+      'Requires the explicit Three exporter for skin delivery; legacy defaults remain unchanged.',
+      'Four influences are this helper contract, not a new global restriction on direct Three.js authoring.',
+      'Bind only after rest transforms are assembled. Reparenting or editing rest geometry afterward needs deliberate rebinding; runtime posed bounds remain the consumer responsibility.',
+    ],
+  },
+);
 define(
   'createVehicleFrame',
   {
@@ -1427,6 +1495,39 @@ define(
   },
 );
 
+define(
+  'compilePortableMaterialSpecV3',
+  {
+    ...materialFacts,
+    execution: 'async',
+    ownership:
+      'Creates an owned material and owned texture, Source, pixel and encoded-byte bindings; never mutates a cached resource texture.',
+    parameters: [
+      'Strict schemaVersion 3 pbrMetallicRoughness specification, with existing scalar PBR fields and exact slot usage checks.',
+      'Each texture ref is a typed procedural V3 spec or approved resource ID plus a complete sampler: minFilter, magFilter, wrapS and wrapT.',
+      'Procedural dimensions are independent width/height; colors are straight RGBA bytes. The material selects opaque, mask or blend behavior explicitly.',
+      'Source accepts exactly one specification. Host resources are injected after verification; authored source cannot provide bytes, paths, URLs or a resolver.',
+    ],
+    preservation: [
+      'Existing V1/V2 recipe algorithms, hashes and material defaults are unchanged.',
+      'Sampler and alpha state export through standard glTF material and sampler fields; runtime glow, lighting and postprocessing remain consumer choices.',
+    ],
+  },
+  {
+    ...materialMetadata,
+    references: [
+      'src/procedural-material-v3.ts',
+      'src/portable-material-runtime.ts',
+      'src/portable-sampler.ts',
+    ],
+    aliases: ['portable RGBA material', 'explicit texture sampling'],
+    intents: ['compile cutout or pixel-textured portable materials'],
+    limitations: [
+      'Height-map derivation is not part of the V3 binding contract. V2 remains available for existing derive recipes.',
+    ],
+  },
+);
+
 const animationFacts = {
   units:
     'Keyframe times and durations are seconds; transform values are absolute, not additive offsets.',
@@ -2048,13 +2149,16 @@ define(
     execution: 'async',
     axes: 'Chart orientation is selected by xatlas, not a directional material frame.',
     parameters: [
-      'Nonempty complete triangle geometry; resolution is a packing limit, not guaranteed final dimensions.',
-      'padding defaults 2; useNormals defaults false.',
+      'Nonempty complete triangle geometry; at most 65,536 source and output vertices, 1,000,000 triangles and a 128 MiB attribute allocation bound. Split larger meshes.',
+      'resolution is an integer 1..4096 target, not guaranteed final dimensions; read userData.atlas.width/height. padding is an integer 0..resolution, default 2.',
+      'useNormals defaults false (recompute); true uses and preserves source normals. Normal morphs require true and a base normal attribute.',
     ],
     topology: ['Reindexes/splits vertices for charts; does not repair malformed source topology.'],
     preservation: [
-      'Returns new positions/index/UVs and atlas metadata; normals depend on input/options.',
-      'Arbitrary custom attributes, groups, materials and original UV orientation are not preserved by this reconstruction.',
+      'Returns owned buffers; source remains unchanged. Seam mapping retains per-vertex attributes with 1..4 components, including colors, skin weights/indices, extra UVs and normalized/interleaved storage values.',
+      'Preserves position/normal/color morph targets, relative-mode flag, triangle groups, draw range, name and JSON userData. Normal policy stays opt-in; zero normals are repaired.',
+      'Replaces UV0 and atlas metadata; drops stale tangents. Recompute tangents after final UVs. Mesh materials, skeleton and animation belong to the caller, not the geometry helper.',
+      'Rejects instanced data, unsupported morph semantics, multiple atlas pages, invalid correspondence and adapter index overflow instead of silently discarding data.',
     ],
     cost: 'WASM charting/packing depends on mesh complexity and resolution; no general time bound.',
   },
@@ -2111,17 +2215,23 @@ define(
     ...textureFacts,
     ownership: 'Creates a new DataTexture with generated bytes and portable metadata.',
     parameters: [
-      'Strict schemaVersion 2; size power-of-two 4..1024; at most 8 layers.',
+      'V1/V2 preserve opaque patterns: size power-of-two 4..1024 and at most 8 layers. Explicit schemaVersion 3 uses width/height integers 4..1024, byte RGBA, at most 64 ordered operations and 64 polygon vertices.',
+      'V3 paint/mask use integer pixel-edge shapes with binary center coverage and fixed integer source-over rounding. A mask clears outside its shape; invert keeps outside. Zero-alpha pixels are transparent black.',
+      'V3 color-only palette colors are 1..32 RGB integers, optional fixed Bayer4 dither. Color-only stamps use bounded Xorshift32 seed/area placement; periodic wrapping is explicit and at most 256 expanded copies. Legacy-v2 layers delegate unchanged square V2 patterns with matching usage.',
       'Pattern counts 1..256 and noise octaves 1..6; seeded patterns are deterministic.',
       'For stripes and gradient, angleDeg rotates the direction of color variation in UV space about the image center. At 0 degrees colors vary across U: stripe bands run along V. At 90 degrees colors vary across V: bands run along U. This does not rotate the mesh UVs.',
       'Stripes count is the number of alternating bands across one unit of the projected coordinate, not the number of colorA/colorB pairs. Gradient runs from its from color to its to color along that coordinate and clamps outside 0..1.',
       'Unknown keys, callbacks, paths, URLs and shader source are rejected.',
     ],
     preservation: ['Produces repeat-wrapped encoded texture content; color space follows usage.'],
-    cost: 'Bounded pixel/layer budgets; generation scales with pixels × layers × pattern work.',
+    cost: 'V2 retains pixel/layer budgets. V3 preflights at most 1,048,576 texels, 64million work units including polygon edges, palette comparisons and periodic copies, and 64MiB transient bytes.',
   },
   {
-    references: ['src/procedural-texture.ts'],
+    references: [
+      'src/procedural-texture.ts',
+      'src/procedural-texture-v3-contract.ts',
+      'docs/procedural-surfaces-v3.md',
+    ],
     tags: ['texture', 'procedural', 'deterministic'],
     aliases: ['generated texture', 'noise texture', 'layered pattern'],
     intents: ['generate a repeatable texture without external image files'],
@@ -2249,6 +2359,77 @@ define(
     ],
   },
 );
+define(
+  'textureAtlas',
+  {
+    ...textureFacts,
+    execution: 'async',
+    units: 'Integer image pixel edges; half-open content rectangles and gutters.',
+    axes: 'Image +X right and +Y down, top-left origin. Texture flipY=false.',
+    ownership:
+      'Creates an owned texture and immutable-by-copy source snapshots; host map capability is never exposed to authored code.',
+    parameters: [
+      'schemaVersion1, width/height 4..1024, explicit usage and 1..64 named regions from at most16 distinct sources.',
+      'Each region has name, content rectangle and source; gutter defaults2 and edgeMode defaults copy-edge. Source crops and content dimensions must match without resampling.',
+      'Source is {kind:"procedural",spec:V3} or {kind:"resource",resourceId:exactMapId,pin:{resourceId:materialId,revisionId,sha256},expected?}. Pins are host-selected immutable library revisions; no arbitrary acquisition I/O.',
+      'Optional sampler specifies all four portable fields; default linear-mipmap-linear/linear/clamp-to-edge on both axes.',
+    ],
+    preservation: [
+      'Copies straight RGBA; mask-rgb-dilate changes only transparent RGB, leaving coverage unchanged. Sources and padded allocations stay separate.',
+    ],
+    semantics: [
+      'Named atlas metadata records compiler, recipe, layout, source, raw-pixel and domain-separated atlas hashes. It does not establish project membership.',
+    ],
+    cost: 'Bounded full-source decode, compilation, pixel work and scratch memory admitted together before source loads.',
+  },
+  {
+    references: [
+      'src/texture-atlas-contract.ts',
+      'src/texture-atlas-pixels.ts',
+      'src/texture-atlas.ts',
+    ],
+    tags: ['texture', 'atlas', 'rgba', 'ownership'],
+    aliases: ['named texture sheet', 'foliage atlas'],
+    intents: ['compose reusable named pixel regions without a mesh'],
+    limitations: [
+      'No automatic packing, rotation or resampling. Gutters reduce filtering bleed but cannot isolate every downsampled mip level.',
+    ],
+    related: [{ name: 'remapUVToAtlas', relation: 'companion' }],
+  },
+);
+
+define(
+  'remapUVToAtlas',
+  {
+    ...ownedGeometry,
+    units: 'Input unit UVs [0,1]; target rectangles are atlas pixels.',
+    axes: 'Explicit top-left or bottom-left input origin; target follows top-left image coordinates.',
+    parameters: [
+      'Requires a compiled atlas texture or manifest and exact region name.',
+      'inputOrigin and content-boundary/texel-center mode are both required; finite per-vertex UV0 only.',
+    ],
+    topology: ['Preserves vertices, indices, groups, draw range and morph correspondence.'],
+    preservation: [
+      'Owns output attributes and metadata; UV0 is replaced. Nonidentity scale drops stale tangents with a warning.',
+    ],
+    semantics: [
+      'Records the named region and affine mapping without changing asset category, project membership or materials.',
+    ],
+    cost: 'Linear UV mapping plus a bounded clone of geometry and morph buffers.',
+  },
+  {
+    references: ['src/texture-atlas.ts', 'src/uv-shapes.ts'],
+    tags: ['uv', 'atlas', 'ownership'],
+    aliases: ['named region UV mapping'],
+    intents: ['bind existing UVs to a named atlas region'],
+    limitations: ['Does not unwrap, project, resample or tile within a region.'],
+    related: [
+      { name: 'textureAtlas', relation: 'prerequisite' },
+      { name: 'projectUV', relation: 'companion' },
+    ],
+  },
+);
+
 define(
   'materialBudgetAdvisory',
   {