@instruktlabs/kiln 1.2.2 → 1.2.3

package/lib/community-exporter.js

@@ -1,8 +1,11 @@
 import * as THREE from 'three';
 import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+import { GLB_BUFFER } from '@gltf-transform/core';
 import { createGltfIO } from "./gltf-io.js";
 import { openShellExtras } from "./open-shell.js";
 import { rigExtrasForExport } from "./rig-export.js";
+import { assertPortableMaterialSides } from "./material-export.js";
+import { collectAtlasProvenance, refreshAtlasDocumentProvenance, } from "./atlas-provenance.js";
 import { KILN_SEMANTIC_EXTRAS_KEY, validateSemanticMetadataV1, cloneSemanticMetadataV1, createSemanticMetadataV1, } from "./contracts/index.js";
 export function resolveGltfExporter(value = typeof process !== 'undefined'
     ? process.env['KILN_GLTF_EXPORTER']
@@ -39,9 +42,13 @@ function cleanClone(source) {
     shadow.userData = {};
     return shadow.clone();
 }
-export async function communitySceneDocument(root, clips, platform = browserPlatform, authorExtras) {
+export async function communitySceneDocument(root, clips, platform = browserPlatform, authorExtras, atlas = collectAtlasProvenance(root)) {
+    assertPortableMaterialSides(root);
     const materials = new Map();
+    const originalMaterials = new Map();
+    const originalGeometries = new Map();
     const textures = new Map();
+    const directImages = new Map();
     const nodes = new Map();
     const encoded = [];
     function texture(source) {
@@ -55,6 +62,11 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
         textures.set(source, copy);
         const bytes = source.userData['encoded'];
         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);
                 Object.defineProperty(copy, 'isDataTexture', { value: true });
@@ -83,6 +95,7 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
                 copy[key] = texture(value);
         }
         materials.set(source, copy);
+        originalMaterials.set(copy, source);
         return copy;
     }
     function node(source) {
@@ -115,6 +128,7 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
                 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);
         }
@@ -143,6 +157,7 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
             const original = source;
             const mesh = copy;
             mesh.geometry = cleanClone(original.geometry);
+            originalGeometries.set(mesh, original.geometry);
             mesh.material = Array.isArray(original.material)
                 ? original.material.map(material)
                 : material(original.material);
@@ -169,6 +184,47 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
     }
     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();
+    const canvasInput = (map) => {
+        const raw = map?.image;
+        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[key] = canvasInput(value);
+        }
+        const standard = material;
+        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.
@@ -191,7 +247,48 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
         });
         return cloned;
     });
-    const bytes = await new GLTFExporter().parseAsync(copy, {
+    const preservedImages = new Map();
+    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)
+                    primitive.extras = { ...primitive.extras, kilnAtlasBinding: binding };
+        },
+        async writeMaterialAsync(material, definition) {
+            const source = originalMaterials.get(material);
+            if (!source)
+                return;
+            const bag = source;
+            const pbr = definition.pbrMetallicRoughness;
+            for (const [slot, info] of [
+                ['map', pbr?.baseColorTexture],
+                ['normalMap', definition.normalTexture],
+                ['metalnessMap', pbr?.metallicRoughnessTexture],
+                ['roughnessMap', pbr?.metallicRoughnessTexture],
+                [
+                    'emissiveMap',
+                    definition.emissiveTexture,
+                ],
+                ['aoMap', definition.occlusionTexture],
+            ]) {
+                const texture = bag[slot], ref = texture && atlas.texture(texture);
+                if (ref && info) {
+                    const prior = info.extras?.['kilnAtlasReference'];
+                    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,
@@ -199,6 +296,39 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
     });
     const io = createGltfIO();
     const json = await io.binaryToJSON(new Uint8Array(bytes));
+    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.
@@ -209,7 +339,13 @@ export async function communitySceneDocument(root, clips, platform = browserPlat
         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
  * matrices and Three's center. A sheared UV basis needs baking, not TRS. */

package/lib/discovery/helper-contracts.js

@@ -951,6 +951,64 @@ define('createJointChain', {
     aliases: ['joint chain', 'articulated chain'],
     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', {
     ...nodeFacts,
     axes: '+X forward, +Y up, +Z right.',
@@ -1151,6 +1209,33 @@ define('compilePortableMaterialSpecV2', {
     aliases: ['portable material specification', 'project material library'],
     intents: ['compile a strict portable material definition'],
 });
+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.',
     axes: 'Target-local XYZ axes.',
@@ -1653,13 +1738,16 @@ define('autoUnwrap', {
     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.',
 }, {
@@ -1705,16 +1793,22 @@ define('proceduralTexture', {
     ...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'],
@@ -1819,6 +1913,66 @@ define('remapUV', {
         { name: 'copyGeometry', relation: 'companion' },
     ],
 });
+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', {
     units: 'Counts distinct material object references.',
     axes: 'Not applicable.',

package/lib/discovery/helper-specs.js

@@ -56,6 +56,24 @@ const PRIMITIVES = [
         example: "const leg = createJointChain('LegL', [{ role: 'hip.left', offset: [0, 1, -0.2], side: 'left' }, { role: 'knee.left', offset: [0, -0.5, 0], side: 'left' }, { role: 'ankle.left', offset: [0, -0.5, 0], side: 'left', endEffector: true, contact: true }], { parent: root });",
         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: 'createVehicleFrame(name, opts?: { chassis?, axles?, seats?, contacts?, steering?, propulsion?, parent? })',
@@ -445,6 +463,15 @@ const PRIMITIVES = [
         example: "const steel = await compilePortableMaterialSpecV2({ schemaVersion: 2, model: 'pbrMetallicRoughness', roughness: 0.45, metalness: 0.85, textures: { metallicRoughness: { kind: 'procedural', spec: { schemaVersion: 2, usage: 'metallicRoughness', size: 64, layers: [{ op: 'solid', color: 0x0080cc }] } } } });",
         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 })',
@@ -711,7 +738,7 @@ const PRIMITIVES = [
         signature: 'await autoUnwrap(geometry: BufferGeometry, opts?: { resolution?: 1024, padding?: 2, useNormals?: false })',
         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.',
+        description: '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);',
     },
     // ---------------------------------------------------------------------------
@@ -728,12 +755,30 @@ const PRIMITIVES = [
     },
     {
         name: 'proceduralTexture',
-        signature: 'proceduralTexture({ schemaVersion: 2, size?: 4..1024 pow2, usage?, name?, layers: ProceduralLayer[] })',
+        signature: '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.',
+        description: '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.",
+        promptNotes: "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/lib/discovery/shapes.js

@@ -8,11 +8,12 @@
  * the shape a model reads is the shape the server enforces.
  */
 import { z } from 'zod';
-import { materialLibraryPayloadSchema, proceduralMaterialDraftSchema } from "../material-library.js";
+import { materialLibraryPayloadAnySchema, proceduralMaterialDraftAnySchema, } from "../material-library.js";
 import { projectDraftSchema, projectPatchSchema } from "../projects.js";
 import { cameraShotInput, captureShapeInput } from "../tools/capture-input.js";
 const jsonSchema = (schema) => {
-    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;
 };
 const shape = (name, tool, field, summary, schema, extra = {}) => ({
@@ -42,12 +43,24 @@ export const discoveryShapes = [
         intents: ['update a project brief, design, inventory or material pins'],
         references: ['docs/projects-and-live-review.md'],
     }),
-    shape('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, {
-        aliases: ['procedural material', 'material recipe draft', 'texture layers'],
-        intents: ['bake a custom tileable material from layers'],
-        references: ['docs/projects-and-live-review.md'],
+    shape('material-draft', 'kiln_material', 'draft', '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',
+            '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, {
+    shape('material-import', 'kiln_material', 'payload', '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'],
         references: ['docs/projects-and-live-review.md'],

package/lib/engine-identity.d.ts

@@ -26,7 +26,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 declare const ENGINE_VERSION = "1.2.2";
+export declare const ENGINE_VERSION = "1.2.3";
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.
  *

package/lib/engine-identity.js

@@ -26,7 +26,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/lib/evaluator/authoring-diagnostic.d.ts

@@ -1,5 +1,5 @@
 /** Closed, engine-owned repair hints. Never serialize exception messages or stacks. */
-export type AuthoringDiagnostic = 'TUBE_RADIUS' | 'TAPER_CONE_AXIS' | 'SOLID_FLOAT32_COLLAPSE' | 'MESH_DATA_NONFINITE' | 'MATERIAL_ALPHA_MODE' | 'MATERIAL_COLOR_ARGUMENT' | 'MATERIAL_PACKED_CHANNELS' | 'MATERIAL_RECIPE_TEXTURE_BINDING' | 'PORTABLE_TEXTURE_REFERENCE' | 'PORTABLE_COLOR_ARGUMENT' | 'PART_NAME_ARGUMENT' | 'PART_GEOMETRY_ARGUMENT' | 'PART_MATERIAL_ARGUMENT' | 'REMOVED_HELPER' | 'UNBOUND_VARIABLE' | 'GEAR_RADII_ORDER' | 'ROUNDED_BOX_RADIUS' | 'PROCEDURAL_TEXTURE_UNKNOWN_KEY' | 'PROCEDURAL_TEXTURE_BLEND' | 'MATERIAL_FRACTION_RANGE' | 'PARAMETRIC_PERIODIC_ENDPOINT' | 'PROFILE_HOLES_UNSUPPORTED' | 'PROFILE_BEVEL_COLLAPSE' | 'PROFILE_CORRESPONDENCE_COLLAPSE' | 'UNINITIALIZED_BINDING' | 'BUILD_RESULT' | 'MATERIAL_RECIPE_OVERRIDE' | 'PROGRAM_TYPE_ERROR' | 'PROGRAM_RANGE_ERROR' | 'LOD_SET' | 'OPEN_SHELL';
+export type AuthoringDiagnostic = 'TUBE_RADIUS' | 'TAPER_CONE_AXIS' | 'SOLID_FLOAT32_COLLAPSE' | 'MESH_DATA_NONFINITE' | 'MATERIAL_ALPHA_MODE' | 'MATERIAL_COLOR_ARGUMENT' | 'MATERIAL_PACKED_CHANNELS' | 'MATERIAL_RECIPE_TEXTURE_BINDING' | 'PORTABLE_TEXTURE_REFERENCE' | 'PORTABLE_COLOR_ARGUMENT' | 'PART_NAME_ARGUMENT' | 'PART_GEOMETRY_ARGUMENT' | 'PART_MATERIAL_ARGUMENT' | 'REMOVED_HELPER' | 'UNBOUND_VARIABLE' | 'GEAR_RADII_ORDER' | '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' | 'PROFILE_BEVEL_COLLAPSE' | 'PROFILE_CORRESPONDENCE_COLLAPSE' | 'UNINITIALIZED_BINDING' | 'BUILD_RESULT' | 'MATERIAL_RECIPE_OVERRIDE' | 'PROGRAM_TYPE_ERROR' | 'PROGRAM_RANGE_ERROR' | 'LOD_SET' | 'OPEN_SHELL' | 'BONE_CHAIN_ARGUMENT' | 'SKIN_BINDING_ARGUMENT' | 'EXPORT_MATERIAL_SIDE_UNSUPPORTED';
 export declare const UNBOUND_VARIABLE_ADVICE = "Check variable spelling and scope: generated code used an undeclared variable. Read the current source and check declarations before retrying. If it was meant to be a Kiln helper, call kiln_discover to confirm the exact name and signature; the sandbox exposes only those globals.";
 export declare const GEAR_RADII_ORDER_ADVICE = "gearGeo requires boreRadius < rootRadius < tipRadius; specify rootRadius when changing tipRadius. Omitted radii keep their absolute defaults.";
 export declare const ROUNDED_BOX_RADIUS_ADVICE = "roundedBoxGeo: radius must be less than half the smallest dimension. Reduce radius or increase the smallest dimension; equality is invalid.";

package/lib/evaluator/authoring-diagnostic.js

@@ -27,6 +27,18 @@ export const OPEN_SHELL_ADVICE = 'markOpenShell(part, reason) marks a part as in
  */
 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) {
+    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')