@instruktlabs/kiln 1.2.2 → 1.2.3

package/src/discovery/helper-specs.ts

@@ -98,6 +98,32 @@ const PRIMITIVES: HelperSpec[] = [
     promptNotes:
       'Use only the resolved body-plan graph. Offsets are local to the previous joint; contact end effectors must land at world Y=0.',
   },
+  {
+    name: 'createBoneChain',
+    signature:
+      'createBoneChain(name, segments: JointChainSegmentV1[], opts?: { parent?, parentRole? })',
+    returns: '{ root: Bone, end: Bone, nodes: Bone[], byRole, descriptors }',
+    category: 'structure',
+    description:
+      'Creates an opt-in semantic Bone chain with the same local rest descriptors as createJointChain, for explicitly skinned meshes.',
+    example:
+      "const bones = createBoneChain('Arm', [{ role: 'arm.base', offset: [0, 0, 0] }, { role: 'arm.tip', offset: [0, 1, 0] }], { parent: root });",
+    promptNotes:
+      'The bones must be in their assembled rest pose before binding. Use unique roles and names across the rig. createJointChain still returns rigid pivots.',
+  },
+  {
+    name: 'createSkinnedPart',
+    signature:
+      'createSkinnedPart(name, geometry, material, opts: { parent, bones: Bone[], indices: ArrayLike<number>, weights: ArrayLike<number>, normalizeWeights?, position?, rotation?, scale?, semantic? })',
+    returns: 'THREE.SkinnedMesh',
+    category: 'structure',
+    description:
+      'Clones unchanged geometry and binds explicit four-lane vertex influences to an already assembled rest-pose bone hierarchy.',
+    example:
+      "const skin = createSkinnedPart('Arm', geometry, material, { parent: root, bones: chain.nodes, indices, weights });",
+    promptNotes:
+      'Supply exactly four bone indices and weights per vertex; zero-weight lanes still need valid indices. Weights sum to one unless normalizeWeights:true is explicit; zero sums are rejected. Mesh transforms use local meters and Euler degrees. Three exporter is required for portable skin delivery; no automatic converter switch.',
+  },
   {
     name: 'createVehicleFrame',
     signature:
@@ -596,6 +622,19 @@ const PRIMITIVES: HelperSpec[] = [
     promptNotes:
       'Use textures: { baseColor: { kind: "resource", resourceId: "kiln.texture.rough-concrete-albedo.v1" } } for an approved resource, or { kind: "procedural", spec: { schemaVersion: 2, ... } }; bare ID strings are invalid. Use metallicRoughness as one packed G=roughness/B=metalness map. Every procedural ref usage must match its slot; resource refs must be approved for that exact slot. baseColor and emissive are numeric color integers from 0x000000 to 0xffffff, not CSS or materialRecipe hex strings. roughness, metalness and alphaCutoff are finite 0..1; emissiveIntensity is finite 0..64 (unlike materialRecipe, whose intensity is 0..1).',
   },
+  {
+    name: 'compilePortableMaterialSpecV3',
+    signature:
+      "await compilePortableMaterialSpecV3({ schemaVersion: 3, model: 'pbrMetallicRoughness', name?, baseColor?, roughness?, metalness?, emissive?, emissiveIntensity?, alphaMode?, alphaCutoff?, doubleSided?, textures?: { baseColor?, normal?, metallicRoughness?, emissive?, occlusion? } })",
+    returns: 'Promise<THREE.MeshStandardMaterial>',
+    category: 'material',
+    description:
+      'Compiles opt-in portable PBR materials with bounded rectangular RGBA procedural textures and explicit portable samplers, preserving existing V2 behavior.',
+    example:
+      "const leaf = await compilePortableMaterialSpecV3({ schemaVersion: 3, model: 'pbrMetallicRoughness', alphaMode: 'mask', doubleSided: true, textures: { baseColor: { kind: 'procedural', spec: { schemaVersion: 3, width: 16, height: 32, usage: 'albedo', background: [0, 0, 0, 0], operations: [{ op: 'paint', shape: { kind: 'ellipse', x: 2, y: 1, width: 12, height: 30 }, rgba: [60, 90, 40, 255] }] }, sampler: { minFilter: 'nearest', magFilter: 'nearest', wrapS: 'clamp-to-edge', wrapT: 'clamp-to-edge' } } } });",
+    promptNotes:
+      'Every texture ref needs all four sampler fields. minFilter accepts nearest, linear, nearest-mipmap-nearest, linear-mipmap-nearest, nearest-mipmap-linear or linear-mipmap-linear; magFilter accepts nearest or linear; wrapS/wrapT accept clamp-to-edge, repeat or mirrored-repeat. Use typed procedural V3 specs or approved resource refs. Slot usages must match. RGBA alpha alone does not select mask/blend: set material alphaMode explicitly. Each binding owns texture state and bytes; no resolver, path, URL, raw pixels or shader arguments. V2 recipes and defaults remain separate.',
+  },
   {
     name: 'basicMaterial',
     signature: 'basicMaterial(color, opts?: { transparent, opacity })',
@@ -937,7 +976,7 @@ const PRIMITIVES: HelperSpec[] = [
     returns: 'Promise<THREE.BufferGeometry>',
     category: 'uv',
     description:
-      'xatlas-based UV atlas for ANY geometry (CSG output, subdivided, deformed). Output is a packed atlas with arbitrary per-chart rotation — use for non-tileable baked textures. For directional tileable textures on box/cylinder/plane primitives, prefer the shape-aware unwraps below.',
+      'xatlas-based UV atlas for bounded triangle geometry, including CSG output. Remaps vertex data and morphs across seams; preserves groups. Replaces UV0 and removes stale tangents. Maximum 65,536 input and output vertices; split larger meshes. Packed charts rotate arbitrarily: use for baked textures; prefer projectUV or original primitive UVs for directional tiling. See the preservation contract before unwrapping skinned or morphed geometry.',
     example:
       'const unwrapped = await autoUnwrap(someCsgResult, { resolution: 1024 });\nconst mesh = new THREE.Mesh(unwrapped, bakedPbr);',
   },
@@ -959,15 +998,41 @@ const PRIMITIVES: HelperSpec[] = [
   {
     name: 'proceduralTexture',
     signature:
-      'proceduralTexture({ schemaVersion: 2, size?: 4..1024 pow2, usage?, name?, layers: ProceduralLayer[] })',
+      'proceduralTexture({ schemaVersion: 2, size?: 4..1024 pow2, usage?, name?, layers: ProceduralLayer[] } | { schemaVersion: 3, width: 4..1024, height: 4..1024, usage?, name?, background?: RGBA, operations: OperationV3[], palette? })',
     returns: 'THREE.DataTexture (tiling, sRGB or linear per usage)',
     category: 'textures',
     description:
-      'Builds a repeat-wrapped texture from a bounded layer stack, with no image file needed. Layers composite bottom-first; the same spec produces the same bytes. Seeded noise is tileable, while other patterns can have visible repeat seams. Baked to PNG and embedded in the GLB automatically.',
+      'Builds a repeat-wrapped deterministic texture without an image file. V2 retains opaque pattern layers. Explicit V3 adds rectangular RGBA, pixel shapes/masks, color palettes and seeded stamps. Repeat wrapping alone does not prove seamless pixels. Baked to PNG and embedded in the GLB automatically.',
     example:
       "const bark = proceduralTexture({ schemaVersion: 2, size: 256, usage: 'albedo', name: 'Bark', layers: [{ op: 'solid', color: 0x5a4632 }, { op: 'noise', colorA: 0x3d2f21, colorB: 0x7a6248, scale: 6, octaves: 4, blend: 'overlay' }] });",
     promptNotes:
-      "Layer fields by op — solid: { color }; checker: { colorA, colorB, squares? }; stripes: { colorA, colorB, count?, angleDeg? }; gradient: { from, to, angleDeg? }; bricks: { brick, mortar, rows?, cols?, mortarWidth?: 0..1 (fraction of a brick cell, default 0.06), stagger?: 0..1 (row offset fraction, default 0.5) }; noise: { colorA, colorB, scale?, octaves?, seed? }. Every layer also accepts blend?: 'normal'|'multiply'|'screen'|'overlay' and opacity?: 0..1. Pattern counts are integers 1..256; noise octaves are 1..6. Sync — no await. Unknown/prototype keys, callbacks, paths, URLs, and shader source are rejected. Max 8 layers.",
+      "V2 layer fields by op: solid: { color }; checker: { colorA, colorB, squares? }; stripes: { colorA, colorB, count?, angleDeg? }; gradient: { from, to, angleDeg? }; bricks: { brick, mortar, rows?, cols?, mortarWidth?: 0..1 (fraction of a brick cell, default 0.06), stagger?: 0..1 (row offset fraction, default 0.5) }; noise: { colorA, colorB, scale?, octaves?, seed? }. V2 blend normal|multiply|screen|overlay; opacity 0..1; max 8 layers, counts 1..256, octaves 1..6. V3 operations: paint {shape,rgba,opacity?}; mask {shape,alpha?,invert?}; stamps {shape,rgba,count,seed,area,periodic?,opacity?}; legacy-v2 {spec,alpha?,opacity?} delegates an explicit V2 recipe with matching square dimensions/usage. RGBA is four bytes; V3 opacity/alpha are bytes0..255 default255. Shape kinds: rectangle/ellipse {x,y,width,height}; polygon {points:[[x,y],...]}; line {from:[x,y],to:[x,y],width}. Coordinates are integer pixel edges; centers define binary coverage, round line caps. Mask clears outside; invert keeps outside instead. area {x,y,width,height} sets seeded stamp translation offsets; periodic:true wraps copies explicitly. V3 background defaults transparent black, max64 ops,64 polygon vertices,256 expanded stamps (periodic counts9),32 palette colors,64million estimated work including edges. palette {colors:[RGB integers],dither?:'none'|'bayer4'} and stamps are albedo/emissive only. Zero alpha normalizes RGB to0. Sampler defaults remain repeat/linear/mips; alphaMode belongs to pbrMaterial. Sync; strict JSON rejects unknown/prototype fields and accessors. See docs/procedural-surfaces-v3.md for exact rounding and bounds.",
+  },
+  {
+    name: 'textureAtlas',
+    signature:
+      'await textureAtlas({ schemaVersion: 1, width, height, usage, sampler?, regions: [{ name, content: { x, y, width, height }, gutter?, edgeMode?, source, crop? }] })',
+    returns: 'Promise<THREE.DataTexture>',
+    category: 'textures',
+    description:
+      'Composes named, disjoint pixel regions from bounded procedural V3 recipes or exact pinned library maps without creating a mesh.',
+    example:
+      "const atlas = await textureAtlas({ schemaVersion: 1, width: 8, height: 8, usage: 'albedo', regions: [{ name: 'patch', content: { x: 2, y: 2, width: 4, height: 4 }, source: { kind: 'procedural', spec: { schemaVersion: 3, width: 4, height: 4, background: [70, 90, 40, 255], operations: [] } } }] });",
+    promptNotes:
+      'Coordinates are integer pixel edges from top left. Width/height 4..1024. Content excludes gutter (default2); padded allocations must not overlap. copy-edge (default) extrudes RGBA; mask-rgb-dilate preserves positive alpha and extends nearest donor RGB into zero-alpha pixels without growing alpha, for albedo/emissive only. No packing, rotation or resampling. An optional crop must exactly match content dimensions. Resource sources require {kind:"resource",resourceId:exactMapId,pin:{resourceId:materialId,revisionId,sha256}} and a host-supplied exact dependency; paths, URLs, latest and approved non-library resources are unsupported. Default sampler is linear-mipmap-linear/linear/clamp-to-edge on both axes; explicit samplers require all four fields. Gutters do not guarantee isolation at every mip level. Use remapUVToAtlas with an explicit input origin and mode; inspect at intended scene distance.',
+  },
+  {
+    name: 'remapUVToAtlas',
+    signature:
+      "remapUVToAtlas(geometry, atlasTextureOrManifest, regionName, { inputOrigin: 'top-left' | 'bottom-left', mode: 'content-boundary' | 'texel-center' })",
+    returns: 'THREE.BufferGeometry',
+    category: 'uv',
+    description:
+      'Maps existing unit UV0 into a named atlas content rectangle on an owned geometry clone, preserving topology and rich attributes.',
+    example:
+      "const card = remapUVToAtlas(planeGeo(1, 1), atlas, 'patch', { inputOrigin: 'bottom-left', mode: 'texel-center' });",
+    promptNotes:
+      'UV0 must be finite in [0,1], with two components per vertex. Content-boundary maps endpoints to content edges; texel-center maps endpoints to the first/last content texel centers. Explicitly identify the input UV origin; atlas image coordinates use top left and flipY=false. Geometry, normals, colors, skin weights, morph buffers, groups and source metadata are preserved independently. UV scale changes invalidate tangents; regenerate when needed. This helper does not project, unwrap, tile within a region or change material sampling.',
   },
   {
     name: 'normalMapFromHeight',

package/src/discovery/shapes.ts

@@ -8,7 +8,10 @@
  * the shape a model reads is the shape the server enforces.
  */
 import { z } from 'zod';
-import { materialLibraryPayloadSchema, proceduralMaterialDraftSchema } from '../material-library';
+import {
+  materialLibraryPayloadAnySchema,
+  proceduralMaterialDraftAnySchema,
+} from '../material-library';
 import { projectDraftSchema, projectPatchSchema } from '../projects';
 import { cameraShotInput, captureShapeInput } from '../tools/capture-input';
 import type { DiscoveryEntry } from './catalog-schema';
@@ -16,7 +19,8 @@ import type { DiscoveryEntry } from './catalog-schema';
 type ShapeEntry = Extract<DiscoveryEntry, { kind: 'shape' }>;
 
 const jsonSchema = (schema: z.ZodType): Record<string, unknown> => {
-  const { $schema: _dialect, ...rest } = z.toJSONSchema(schema, { io: 'input' });
+  // Local JSON Schema refs preserve complete fields without repeating nested recipes.
+  const { $schema: _dialect, ...rest } = z.toJSONSchema(schema, { io: 'input', reused: 'ref' });
   return rest;
 };
 
@@ -73,20 +77,32 @@ export const discoveryShapes: ShapeEntry[] = [
     'material-draft',
     'kiln_material',
     'draft',
-    'The record kiln_material create-procedural takes: materialId, name, tileable, sources with license, and maps whose layered procedural specs (solid, checker, stripes, gradient, bricks, noise) bake into PNG maps; optional tags, physicalSizeMeters and parameters.',
-    proceduralMaterialDraftSchema,
+    'The record kiln_material create-procedural takes: a legacy layered draft or schemaVersion 2 with explicit map samplers and V3 RGBA or named atlas recipes. Each includes materialId, name, tileable, sources with license, and maps. Atlas resource sources pin exact saved revisions.',
+    proceduralMaterialDraftAnySchema,
     {
-      aliases: ['procedural material', 'material recipe draft', 'texture layers'],
-      intents: ['bake a custom tileable material from layers'],
-      references: ['docs/projects-and-live-review.md'],
+      aliases: [
+        'procedural material',
+        'material recipe draft',
+        'texture layers',
+        'saved atlas',
+        'RGBA texture',
+      ],
+      intents: [
+        'bake a custom tileable material from layers',
+        'save a standalone texture or named atlas',
+      ],
+      limitations: [
+        'Semantic recipe, canonical-form and aggregate budget checks apply beyond the field shapes. Exact pinned sources must already exist in the injected library. No file paths or source fetching.',
+      ],
+      references: ['docs/projects-and-live-review.md', 'docs/procedural-surfaces-v3.md'],
     },
   ),
   shape(
     'material-import',
     'kiln_material',
     'payload',
-    'The record kiln_material import takes: schemaVersion 1 and complete normalized material records, each a manifest plus base64 PNG files keyed by map name.',
-    materialLibraryPayloadSchema,
+    'The record kiln_material import takes: schemaVersion 1 for legacy-only data or 2 for mixed/new records, each a manifest plus base64 PNG files keyed by map name. Supply complete exact dependency closures for atlas records.',
+    materialLibraryPayloadAnySchema,
     {
       aliases: ['material import payload', 'material records'],
       intents: ['import a material library payload'],

package/src/engine-identity.ts

@@ -27,7 +27,7 @@
  * `src/__tests__/package-contents.test.ts` fails if it disagrees with the manifest
  * or with any plugin manifest, which is what keeps the literal honest.
  */
-export const ENGINE_VERSION = '1.2.2';
+export const ENGINE_VERSION = '1.2.3';
 
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.

package/src/evaluator/authoring-diagnostic.ts

@@ -19,6 +19,9 @@ export type AuthoringDiagnostic =
   | 'ROUNDED_BOX_RADIUS'
   | 'PROCEDURAL_TEXTURE_UNKNOWN_KEY'
   | 'PROCEDURAL_TEXTURE_BLEND'
+  | 'PROCEDURAL_TEXTURE_V3_CONTRACT'
+  | 'PORTABLE_MATERIAL_V3_CONTRACT'
+  | 'TEXTURE_ATLAS_CONTRACT'
   | 'MATERIAL_FRACTION_RANGE'
   | 'PARAMETRIC_PERIODIC_ENDPOINT'
   | 'PROFILE_HOLES_UNSUPPORTED'
@@ -30,7 +33,10 @@ export type AuthoringDiagnostic =
   | 'PROGRAM_TYPE_ERROR'
   | 'PROGRAM_RANGE_ERROR'
   | 'LOD_SET'
-  | 'OPEN_SHELL';
+  | 'OPEN_SHELL'
+  | 'BONE_CHAIN_ARGUMENT'
+  | 'SKIN_BINDING_ARGUMENT'
+  | 'EXPORT_MATERIAL_SIDE_UNSUPPORTED';
 // Names no identifier on purpose. The identifier is only available from the
 // sandboxed exception message, and this module's contract is that no captured
 // identifier, path, message or stack crosses that boundary. Pointing at the
@@ -76,6 +82,18 @@ export const OPEN_SHELL_ADVICE =
 export const EXECUTION_REJECTED_ADVICE =
   'No message, stack or identifier crosses the sandbox: a thrown Error, a source-policy denial and any other failure are each reported only as this sentence. Run kiln_validate on the same source for the failing line and code; to read values, render the program and call kiln_inspect (listParts, measurements) instead of throwing. A TypeError, RangeError, unbound variable or build() mistake is named when it is the cause.';
 export function authoringDiagnosticAdvice(diagnostic: AuthoringDiagnostic | undefined): string {
+  if (diagnostic === 'PORTABLE_MATERIAL_V3_CONTRACT')
+    return 'compilePortableMaterialSpecV3 requires schemaVersion 3, model pbrMetallicRoughness, typed V3 procedural or injected resource references, and complete minFilter/magFilter/wrapS/wrapT samplers. Match texture usage to its slot and split work exceeding the material budget. Resource bindings need a host with verified-byte admission. V2 remains available unchanged. Shader code, paths, raw textures and V3 height derivation are unsupported. Read kiln_discover ids ["compilePortableMaterialSpecV3"] for the exact contract.';
+  if (diagnostic === 'TEXTURE_ATLAS_CONTRACT')
+    return 'textureAtlas requires bounded named integer content rectangles with nonoverlapping gutter allocations, matching source crops and usage, and explicit portable sampling. Sources are V3 recipes or exact host-injected library map pins. Split atlases exceeding aggregate work or allocation budgets. remapUVToAtlas requires finite unit UV0, a named content region, inputOrigin and mapping mode; it preserves topology and does not unwrap or tile a region. Read kiln_discover ids ["textureAtlas", "remapUVToAtlas"] for the exact contracts.';
+  if (diagnostic === 'PROCEDURAL_TEXTURE_V3_CONTRACT')
+    return 'proceduralTexture schemaVersion 3 requires bounded JSON: width/height 4..1024, byte RGBA, integer pixel shapes and at most 64 operations. Palette/dither and seeded stamps support only albedo/emissive. Work includes polygon edges and periodic copies. Read kiln_discover ids ["proceduralTexture"] for the V3 contract; keep schemaVersion 2 for existing opaque patterns.';
+  if (diagnostic === 'BONE_CHAIN_ARGUMENT')
+    return 'createBoneChain requires 1..1024 valid local joint descriptors with unique roles and animation-safe names across the parent hierarchy. Use normalized perpendicular forward/bend axes and finite rest transforms; an explicit parentRole must match the declared parent. Read the retained source and kiln_discover ids ["createBoneChain"] for the exact contract.';
+  if (diagnostic === 'SKIN_BINDING_ARGUMENT')
+    return 'createSkinnedPart requires four valid bone indices and finite nonnegative weights per vertex, summing to one unless normalizeWeights:true is explicit. Zero sums are rejected. Assemble distinct named Bones and the parent in one rest-pose hierarchy before binding. Use unbound geometry within the documented budgets and finite invertible transforms. Read the retained source and kiln_discover ids ["createSkinnedPart"] for the exact contract; the Three exporter is required for skin delivery.';
+  if (diagnostic === 'EXPORT_MATERIAL_SIDE_UNSUPPORTED')
+    return 'EXPORT_MATERIAL_SIDE_UNSUPPORTED: A used material has BackSide, which glTF cannot encode directly. Author inward-facing triangles with FrontSide, or choose DoubleSide when both faces are intended. Neither adds missing geometry. Read the retained program with kiln_source query BackSide to locate the material; source names and exception text do not cross the evaluator boundary.';
   if (diagnostic === 'UNINITIALIZED_BINDING') return UNINITIALIZED_BINDING_ADVICE;
   if (diagnostic === 'LOD_SET') return LOD_SET_ADVICE;
   if (diagnostic === 'OPEN_SHELL') return OPEN_SHELL_ADVICE;

package/src/evaluator/protocol.ts

@@ -17,10 +17,10 @@ import { validateRequirementsQaReport } from '../qa/requirements-report';
 import type { RenderGlbOptions, RenderResult } from '../render';
 import type { KhronosGltfValidationReport } from '../qa/gltf';
 import {
-  validateMaterialLibraryPayload,
-  validateMaterialManifestIdentity,
+  validateMaterialLibraryPayloadAny,
+  validateMaterialManifestIdentityAny,
 } from '../material-library-node';
-import type { MaterialLibraryPayloadV1 } from '../material-library';
+import { canonicalMaterialJson, type MaterialLibraryPayload } from '../material-library';
 import { rebuildOptionsSchema } from '../rebuild-options';
 
 export const EVALUATOR_REQUEST_VERSION = 'kiln.evaluator.request.v2' as const;
@@ -287,7 +287,7 @@ function parseOptions(
   }
   const options: Omit<RenderGlbOptions, 'textureResolver' | 'diagnosticConsole'> = {};
   if (value.materialResources !== undefined)
-    options.materialResources = validateMaterialLibraryPayload(value.materialResources);
+    options.materialResources = validateMaterialLibraryPayloadAny(value.materialResources);
   if (value.gltfExporter !== undefined) {
     if (value.gltfExporter !== 'legacy' && value.gltfExporter !== 'three') fail('request');
     options.gltfExporter = value.gltfExporter;
@@ -437,6 +437,9 @@ export function decodeEvaluatorResultV2(
           value.error.diagnostic !== 'ROUNDED_BOX_RADIUS' &&
           value.error.diagnostic !== 'PROCEDURAL_TEXTURE_UNKNOWN_KEY' &&
           value.error.diagnostic !== 'PROCEDURAL_TEXTURE_BLEND' &&
+          value.error.diagnostic !== 'PROCEDURAL_TEXTURE_V3_CONTRACT' &&
+          value.error.diagnostic !== 'PORTABLE_MATERIAL_V3_CONTRACT' &&
+          value.error.diagnostic !== 'TEXTURE_ATLAS_CONTRACT' &&
           value.error.diagnostic !== 'MATERIAL_FRACTION_RANGE' &&
           value.error.diagnostic !== 'MATERIAL_RECIPE_TEXTURE_BINDING' &&
           value.error.diagnostic !== 'PORTABLE_TEXTURE_REFERENCE' &&
@@ -462,7 +465,10 @@ export function decodeEvaluatorResultV2(
           value.error.diagnostic !== 'PROGRAM_TYPE_ERROR' &&
           value.error.diagnostic !== 'PROGRAM_RANGE_ERROR' &&
           value.error.diagnostic !== 'LOD_SET' &&
-          value.error.diagnostic !== 'OPEN_SHELL'))
+          value.error.diagnostic !== 'OPEN_SHELL' &&
+          value.error.diagnostic !== 'EXPORT_MATERIAL_SIDE_UNSUPPORTED' &&
+          value.error.diagnostic !== 'BONE_CHAIN_ARGUMENT' &&
+          value.error.diagnostic !== 'SKIN_BINDING_ARGUMENT'))
     )
       return fail('result');
     if (value.error.qa !== undefined) {
@@ -524,7 +530,7 @@ export function decodeEvaluatorResultV2(
       fail('result');
     try {
       for (const manifest of value.render.materialLibraryDependencies)
-        validateMaterialManifestIdentity(manifest);
+        validateMaterialManifestIdentityAny(manifest);
     } catch {
       return fail('result');
     }
@@ -657,13 +663,17 @@ export function createEvaluatorPortV2(
 /** All transports bind decoded acceptance evidence to the same current-host snapshot. */
 export function assertEvaluatorResultMaterialResources(
   result: EvaluatorResultV2,
-  expected?: MaterialLibraryPayloadV1,
+  expected?: MaterialLibraryPayload,
 ): void {
   if (!result.ok) return;
   const actual = result.render.materialLibraryDependencies ?? [];
-  const wanted = expected?.records.map((record) => record.manifest.revisionId).sort() ?? [];
+  const wanted = expected?.records.map((record) => record.manifest) ?? [];
+  const identity = (manifest: (typeof actual)[number]) =>
+    `${manifest.materialId}/${manifest.revisionId}`;
   if (
-    JSON.stringify(actual.map((manifest) => manifest.revisionId).sort()) !== JSON.stringify(wanted)
+    new Set(actual.map(identity)).size !== actual.length ||
+    JSON.stringify(actual.map(canonicalMaterialJson).sort()) !==
+      JSON.stringify(wanted.map(canonicalMaterialJson).sort())
   )
     throw new EvaluatorPortError('PROTOCOL_ERROR');
 }

package/src/evaluator/subprocess.ts

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 import type { RenderGlbOptions, RenderResult } from '../render';
 import { AssetQaBlockedError } from '../qa/run';
 import { assertNoLegacyRuntimePolicy, resolveRequirementsContext } from '../requirements-context';
-import { validateMaterialLibraryPayload } from '../material-library-node';
+import { validateMaterialLibraryPayloadAny } from '../material-library-node';
 import {
   decodeEvaluatorResultV2,
   assertEvaluatorResultRequirements,
@@ -117,7 +117,7 @@ export async function renderGLBViaProcessLaunch(
     96 * 1024 * 1024,
   );
   if (options.materialResources !== undefined)
-    validateMaterialLibraryPayload(options.materialResources);
+    validateMaterialLibraryPayloadAny(options.materialResources);
   const request: EvaluatorRequestV2 = {
     version: EVALUATOR_REQUEST_VERSION,
     requestId: 'render-1',

package/src/exporter-node.ts

@@ -19,8 +19,19 @@ export async function prepareNodeExport(hasTextures: boolean): Promise<void> {
   const host = globalThis as unknown as Record<string, unknown>;
   if (!host['FileReader']) host['FileReader'] = ExportFileReader;
   if (!hasTextures || host['OffscreenCanvas'] || host['document']) return;
-  const { Canvas, ImageData } = await import('@napi-rs/canvas');
+  const { Canvas, ImageData } = await import('@napi-rs/canvas').catch((cause: unknown) => {
+    throw new Error(
+      'Headless textured export requires @napi-rs/canvas. Reinstall Kiln with optional dependencies enabled, then verify the native binding in the same Node runtime and platform used by the Kiln host.',
+      { cause },
+    );
+  });
   class ExportCanvas extends Canvas {
+    constructor(width: number, height: number) {
+      super(width, height);
+      // Native Canvas.data() is a method, not a DataTexture image byte array.
+      // Shadow it on the instance: the native constructor supplies its own prototype.
+      Object.defineProperty(this, 'data', { value: undefined });
+    }
     override async convertToBlob(
       options: { type?: string; mime?: string; quality?: number } = {},
     ): Promise<Blob> {

package/src/generated/mcp-manifest.json

@@ -1289,7 +1289,7 @@
     },
     {
       "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": {
         "type": "object",
         "properties": {
@@ -1386,7 +1386,7 @@
             "pattern": "^sha256:[a-f0-9]{64}$"
           },
           "draft": {
-            "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+            "description": "create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
             "type": "object",
             "propertyNames": {
               "type": "string"
@@ -1394,7 +1394,7 @@
             "additionalProperties": {}
           },
           "payload": {
-            "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+            "description": "import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
             "type": "object",
             "propertyNames": {
               "type": "string"

package/src/geometry-budget.ts

@@ -7,6 +7,14 @@ export const GEOMETRY_ALLOCATION_LIMITS = Object.freeze({
   repeatedMeshes: 10_000,
   primitiveSegments: 4096,
   primitiveGridVertices: 262_144,
+  // xatlasjs 0.2 returns Uint16 indices and source-vertex correspondence.
+  unwrapVertices: 65_536,
+  unwrapTriangles: 1_000_000,
+  unwrapAttributeBytes: 128 * 1024 * 1024,
+  unwrapResolution: 4096,
+  skinBones: 1024,
+  skinVertices: 262_144,
+  skinAttributeBytes: 128 * 1024 * 1024,
 });
 export function assertDimension(name: string, value: number, allowZero = false): void {
   if (

package/src/gltf-texture-binding.ts

@@ -0,0 +1,60 @@
+import * as THREE from 'three';
+import type { TextureInfo } from '@gltf-transform/core';
+import type { Transform } from '@gltf-transform/extensions';
+
+const MIN: Record<number, THREE.MinificationTextureFilter> = {
+  9728: THREE.NearestFilter,
+  9729: THREE.LinearFilter,
+  9984: THREE.NearestMipmapNearestFilter,
+  9985: THREE.LinearMipmapNearestFilter,
+  9986: THREE.NearestMipmapLinearFilter,
+  9987: THREE.LinearMipmapLinearFilter,
+};
+const WRAP: Record<number, THREE.Wrapping> = {
+  33071: THREE.ClampToEdgeWrapping,
+  33648: THREE.MirroredRepeatWrapping,
+  10497: THREE.RepeatWrapping,
+};
+
+/** glTF image orientation and sampling belong to every texture use, not just atlases. */
+export function restoreGltfTextureBinding(texture: THREE.Texture, info: TextureInfo): void {
+  texture.minFilter = MIN[info.getMinFilter() ?? 9729]!;
+  texture.magFilter = info.getMagFilter() === 9728 ? THREE.NearestFilter : THREE.LinearFilter;
+  texture.wrapS = WRAP[info.getWrapS()]!;
+  texture.wrapT = WRAP[info.getWrapT()]!;
+  texture.generateMipmaps = [9984, 9985, 9986, 9987].includes(info.getMinFilter() ?? 9729);
+  texture.flipY = false;
+  const transform = info.getExtension<Transform>('KHR_texture_transform');
+  texture.channel = transform?.getTexCoord() ?? info.getTexCoord();
+  if (transform) {
+    texture.offset.fromArray(transform.getOffset());
+    texture.repeat.fromArray(transform.getScale());
+    texture.rotation = transform.getRotation();
+    // glTF composes T*R*S. Three's automatic UV matrix composes nonuniform
+    // repeat and rotation in a different order; retain the actual glTF basis.
+    const c = Math.cos(texture.rotation),
+      s = Math.sin(texture.rotation);
+    const [sx, sy] = transform.getScale(),
+      [x, y] = transform.getOffset();
+    texture.matrix.set(sx * c, sy * s, x, -sx * s, sy * c, y, 0, 0, 1);
+    texture.matrixAutoUpdate = false;
+  }
+}
+
+/** Two uses of one image may differ in sampler, UV channel, transform or atlas provenance. */
+export function gltfTextureBindingKey(info: TextureInfo | null | undefined): string {
+  if (!info) return '';
+  const transform = info.getExtension<Transform>('KHR_texture_transform');
+  return JSON.stringify([
+    info.getMinFilter(),
+    info.getMagFilter(),
+    info.getWrapS(),
+    info.getWrapT(),
+    info.getTexCoord(),
+    transform?.getTexCoord(),
+    transform?.getOffset(),
+    transform?.getScale(),
+    transform?.getRotation(),
+    info.getExtras()['kilnAtlasReference'],
+  ]);
+}

package/src/material-authoring-node.ts

@@ -0,0 +1,68 @@
+/** Shared CLI/MCP JSON authoring boundary. Library pins never imply project membership. */
+import {
+  MATERIAL_LIBRARY_LIMITS,
+  assertMaterialJson,
+  proceduralMaterialDraftSchema,
+  proceduralMaterialDraftV2Schema,
+  type MaterialLibrary,
+  type MaterialManifest,
+  type MaterialRecord,
+} from './material-library';
+import {
+  createMaterialRecordV1,
+  createMaterialRecordV2,
+  resolveMaterialRecordClosure,
+} from './material-library-node';
+import { canonicalizeTextureAtlasSpecV1 } from './texture-atlas-contract';
+import type { MaterialMapPinV1 } from './pinned-material-map';
+
+export async function createProceduralMaterialRecord(
+  value: unknown,
+  library: MaterialLibrary,
+): Promise<{ record: MaterialRecord; dependencies: MaterialRecord[] }> {
+  assertMaterialJson(value);
+  if (
+    new TextEncoder().encode(JSON.stringify(value)).length >
+    MATERIAL_LIBRARY_LIMITS.maxManifestBytes
+  )
+    throw new Error('Material draft exceeds size limit');
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error('Material draft must be a JSON object');
+  if (!Object.hasOwn(value, 'schemaVersion'))
+    return {
+      record: await createMaterialRecordV1(proceduralMaterialDraftSchema.parse(value)),
+      dependencies: [],
+    };
+
+  const draft = proceduralMaterialDraftV2Schema.parse(value);
+  const pins = new Map<string, MaterialMapPinV1>();
+  for (const map of draft.maps) {
+    if (!map.atlas) continue;
+    for (const region of canonicalizeTextureAtlasSpecV1(map.atlas).regions) {
+      if (region.source.kind !== 'resource') continue;
+      const pin = region.source.pin;
+      pins.set(`${pin.resourceId}@${pin.revisionId}`, pin);
+    }
+  }
+  if (pins.size > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+    throw new Error('Material source closure count limit exceeded');
+  const roots: MaterialManifest[] = [];
+  if (pins.size && !library.readManifest)
+    throw new Error('Pinned atlas creation requires a material library with readManifest support.');
+  for (const pin of pins.values()) {
+    const manifest = await library.readManifest!(pin.resourceId, pin.revisionId);
+    if (manifest.materialId !== pin.resourceId || manifest.revisionId !== pin.revisionId)
+      throw new Error('Material source pin identity mismatch');
+    roots.push(manifest);
+  }
+  const dependencies = roots.length
+    ? await resolveMaterialRecordClosure(roots, {
+        readManifest: (id, revision) => library.readManifest!(id, revision),
+        read: (id, revision) =>
+          library.readRecordFiles
+            ? library.readRecordFiles(id, revision)
+            : library.read(id, revision),
+      })
+    : [];
+  return { record: await createMaterialRecordV2(draft, { materials: dependencies }), dependencies };
+}