@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/views/pose.js

@@ -35,11 +35,13 @@ export function clipNames(clips) {
  * clip doesn't carry one.
  */
 export function prepareClip(root, clip) {
-    const nodeNames = new Set();
+    const nodes = new Map();
     root.traverse?.((obj) => {
-        const n = obj.name;
-        if (n)
-            nodeNames.add(n);
+        const node = obj;
+        if (node.name && !nodes.has(node.name))
+            nodes.set(node.name, node);
+        if (node.uuid)
+            nodes.set(node.uuid, node);
     });
     const tracks = [];
     const unresolved = [];
@@ -52,8 +54,10 @@ export function prepareClip(root, clip) {
         if (dot === -1)
             continue;
         const nodeName = raw.slice(0, dot);
-        const property = raw.slice(dot + 1);
-        if (property !== 'position' && property !== 'quaternion' && property !== 'scale')
+        const suffix = raw.slice(dot + 1);
+        const morph = /^morphTargetInfluences(?:\[([^\]]+)\])?$/.exec(suffix);
+        const property = (morph ? 'morphTargetInfluences' : suffix);
+        if (property !== 'position' && property !== 'quaternion' && property !== 'scale' && !morph)
             continue;
         const times = track.times ? Array.from(track.times) : [];
         const values = track.values ? Array.from(track.values) : [];
@@ -68,17 +72,48 @@ export function prepareClip(root, clip) {
             throw new Error(`Unsupported animation interpolation on ${raw}; use LINEAR, STEP or CUBICSPLINE.`);
         }
         const interpolation = cubic ? 'CUBICSPLINE' : mode === 2300 ? 'STEP' : 'LINEAR';
-        if (!nodeNames.has(nodeName))
+        const node = nodes.get(nodeName);
+        const indexed = morph?.[1];
+        const morphIndex = indexed === undefined
+            ? undefined
+            : /^\d+$/.test(indexed)
+                ? Number(indexed)
+                : node?.morphTargetDictionary?.[indexed];
+        let stride = morph
+            ? indexed === undefined
+                ? (node?.morphTargetInfluences?.length ?? 0)
+                : 1
+            : PROP_STRIDE[property];
+        let resolved = !!node;
+        if (morph) {
+            resolved =
+                !!node?.morphTargetInfluences?.length &&
+                    (indexed === undefined ||
+                        (Number.isInteger(morphIndex) &&
+                            morphIndex >= 0 &&
+                            morphIndex < node.morphTargetInfluences.length));
+            // Unresolved morph tracks remain visible diagnostics, but never get sampled.
+            if (!resolved)
+                stride = values.length / (times.length * (cubic ? 3 : 1));
+            if (!Number.isInteger(stride) ||
+                stride < 1 ||
+                values.length !== times.length * stride * (cubic ? 3 : 1) ||
+                !values.every(Number.isFinite) ||
+                !times.every((v, i) => Number.isFinite(v) && v >= 0 && (i === 0 || v > times[i - 1])))
+                throw new Error(`Invalid morph animation values on ${raw}.`);
+        }
+        if (!resolved)
             unresolved.push(raw);
         if (times[times.length - 1] > maxTime)
             maxTime = times[times.length - 1];
         tracks.push({
             nodeName,
             prop: property,
-            stride: PROP_STRIDE[property],
+            stride,
             times,
             values,
             interpolation,
+            ...(morph ? { sourceName: raw, ...(morphIndex === undefined ? {} : { morphIndex }) } : {}),
         });
     }
     const duration = clip.duration && clip.duration > 0 ? clip.duration : maxTime;
@@ -153,7 +188,7 @@ function sampleTrack(track, t, out) {
     }
     if (track.interpolation === 'CUBICSPLINE') {
         cubicSegment(values, stride, i, times[i], times[i + 1], t, out);
-        if (stride === 4)
+        if (track.prop === 'quaternion')
             normalizeQuaternion(out);
         return;
     }
@@ -168,7 +203,7 @@ function sampleTrack(track, t, out) {
     const a = span > 0 ? (t - t0) / span : 0;
     const o0 = i * stride;
     const o1 = (i + 1) * stride;
-    if (stride === 4) {
+    if (track.prop === 'quaternion') {
         slerpFlat(quatTmp, values, o0, values, o1, a);
         out[0] = quatTmp[0];
         out[1] = quatTmp[1];
@@ -229,6 +264,12 @@ export function measureLoopClosure(root, clip) {
     }
     result.unassessedTracks = total - prepared.tracks.length;
     for (const track of prepared.tracks) {
+        // This established evidence contract measures transforms only. Weight-loop
+        // continuity needs a separately versioned evidence field, not a scale label.
+        if (track.prop === 'morphTargetInfluences') {
+            result.unassessedTracks++;
+            continue;
+        }
         const name = `${track.nodeName}.${track.prop}`;
         const valid = !prepared.unresolved.includes(name) &&
             track.values.length ===
@@ -300,19 +341,29 @@ export function poseSceneAtTime(root, prepared, t) {
         const node = obj;
         if (node.name && !byName.has(node.name))
             byName.set(node.name, node);
+        if (node.uuid)
+            byName.set(node.uuid, node);
     });
     const buf = [0, 0, 0, 0];
     for (const track of prepared.tracks) {
         const node = byName.get(track.nodeName);
-        if (!node)
+        if (!node ||
+            prepared.unresolved.includes(track.sourceName ?? `${track.nodeName}.${track.prop}`))
             continue;
         sampleTrack(track, t, buf);
         if (track.prop === 'position')
             node.position?.set(buf[0], buf[1], buf[2]);
         else if (track.prop === 'scale')
             node.scale?.set(buf[0], buf[1], buf[2]);
-        else
+        else if (track.prop === 'quaternion')
             node.quaternion?.set(buf[0], buf[1], buf[2], buf[3]);
+        else if (node.morphTargetInfluences) {
+            if (track.morphIndex !== undefined)
+                node.morphTargetInfluences[track.morphIndex] = buf[0];
+            else
+                for (let i = 0; i < track.stride; i++)
+                    node.morphTargetInfluences[i] = buf[i];
+        }
     }
     root.updateMatrixWorld?.(true);
 }

package/lib/views/raster.d.ts

@@ -6,13 +6,13 @@
  * kiln-studio agent-runtime container ships without a browser
  * (PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1) and Playwright is unsupported under
  * Bun on Windows (see imposter/bake.ts). headless-gl is WebGL1-only while
- * three >= r163 requires WebGL2. So: a dependency-free scanline z-buffer
+ * three >= r163 requires WebGL2. So: a CPU scanline z-buffer
  * rasterizer over the executed scene. Flat lambert, base color only — enough
  * fidelity for silhouette / proportion / orientation / contact QA, which is
  * what the vision loop checks.
  *
  * Scene access is strictly duck-typed (`.isMesh`, `matrixWorld.elements`,
- * position attribute arrays) because sandbox-created objects live in a
+ * vertex readers and position attributes) because sandbox-created objects live in a
  * different module realm — see executeKilnCode in ../render.ts.
  *
  * Lighting matches scripts/visual-audit.ts: key directional light from
@@ -20,6 +20,7 @@
  * the offline audit grid) so inverted winding shows up as missing faces.
  */
 import { type BackdropId } from "./background.js";
+import { type SurfaceSide } from "./face-policy.js";
 export interface ViewSpec {
     name: string;
     /** Direction from model center toward the camera (kiln frame: +X fwd, +Y up, +Z right). */
@@ -95,6 +96,7 @@ interface DuckObject3D {
     visible?: boolean;
     children?: DuckObject3D[];
     updateMatrixWorld?(force?: boolean): void;
+    updateWorldMatrix?(updateParents: boolean, updateChildren: boolean): void;
     traverse?(cb: (obj: unknown) => void): void;
 }
 interface Tri {
@@ -102,6 +104,8 @@ interface Tri {
     color: [number, number, number];
     alpha: number;
     doubleSided: boolean;
+    side: SurfaceSide;
+    windingParity: 1 | -1;
 }
 /**
  * Opaque triangles first in scene order, then translucent ones farthest-first,

package/lib/views/raster.js

@@ -6,20 +6,23 @@
  * kiln-studio agent-runtime container ships without a browser
  * (PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1) and Playwright is unsupported under
  * Bun on Windows (see imposter/bake.ts). headless-gl is WebGL1-only while
- * three >= r163 requires WebGL2. So: a dependency-free scanline z-buffer
+ * three >= r163 requires WebGL2. So: a CPU scanline z-buffer
  * rasterizer over the executed scene. Flat lambert, base color only — enough
  * fidelity for silhouette / proportion / orientation / contact QA, which is
  * what the vision loop checks.
  *
  * Scene access is strictly duck-typed (`.isMesh`, `matrixWorld.elements`,
- * position attribute arrays) because sandbox-created objects live in a
+ * vertex readers and position attributes) because sandbox-created objects live in a
  * different module realm — see executeKilnCode in ../render.ts.
  *
  * Lighting matches scripts/visual-audit.ts: key directional light from
  * [1.5, 2, 1] at 1.1 plus 0.25 ambient. Back-face culling is strict (like
  * the offline audit grid) so inverted winding shows up as missing faces.
  */
+import { Vector3 } from 'three';
 import { resolveBackdrop } from "./background.js";
+import { visibleNormalSign, worldWindingParity } from "./face-policy.js";
+import { prepareTriangleCoverage } from "./triangle-coverage.js";
 /** Same six views as the offline audit grid (scripts/visual-audit.ts). */
 export const SIX_VIEWS = [
     { name: 'Front', dir: [1, 0, 0] },
@@ -98,6 +101,25 @@ function cross(a, b) {
 function dot(a, b) {
     return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 }
+function updateSurfaceMatrices(root) {
+    // Isolated part measurements may start below a changed parent. Keep the normal
+    // updateMatrixWorld dispatch too: SkinnedMesh refreshes its bind inverse there.
+    root.updateWorldMatrix?.(true, false);
+    root.updateMatrixWorld?.(true);
+}
+/** Three's own vertex reader applies morphs, then skinning, without changing the
+ * source buffers. A local Vector3 works across realms; no class identity test is
+ * needed. Plain GLB duck geometry retains its deterministic array fallback. */
+function surfaceVertexReader(mesh, position) {
+    for (const bone of mesh.skeleton?.bones ?? [])
+        bone.updateWorldMatrix?.(true, false);
+    const vertex = new Vector3();
+    if (mesh.getVertexPosition)
+        return (index) => mesh.getVertexPosition(index, vertex);
+    if (position.getX && position.getY && position.getZ)
+        return (index) => vertex.set(position.getX(index), position.getY(index), position.getZ(index));
+    return (index) => vertex.set(position.array[index * 3], position.array[index * 3 + 1], position.array[index * 3 + 2]);
+}
 /**
  * Opaque triangles first in scene order, then translucent ones farthest-first,
  * as a GPU renderer composites them. Drawn in scene order, a translucent pane
@@ -147,7 +169,7 @@ function forEachDrawn(root, visit) {
 }
 /** Collect world-space triangles + base colors from a (possibly cross-realm) scene. */
 export function collectTriangles(root) {
-    root.updateMatrixWorld?.(true);
+    updateSurfaceMatrices(root);
     const tris = [];
     const min = [Infinity, Infinity, Infinity];
     const max = [-Infinity, -Infinity, -Infinity];
@@ -183,12 +205,11 @@ export function collectTriangles(root) {
         const m = mesh.matrixWorld?.elements;
         if (!m)
             return;
-        const arr = pos.array;
+        const windingParity = worldWindingParity(m);
+        const readVertex = surfaceVertexReader(mesh, pos);
         const world = new Float64Array(pos.count * 3);
         for (let i = 0; i < pos.count; i++) {
-            const x = arr[i * 3];
-            const y = arr[i * 3 + 1];
-            const z = arr[i * 3 + 2];
+            const { x, y, z } = readVertex(i);
             const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
             const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
             const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
@@ -219,11 +240,14 @@ export function collectTriangles(root) {
             v[6] = world[c2 * 3];
             v[7] = world[c2 * 3 + 1];
             v[8] = world[c2 * 3 + 2];
+            const side = material?.doubleSided === true || material?.side === 2 ? 2 : material?.side === 1 ? 1 : 0;
             tris.push({
                 v,
                 color: colorOf(material),
                 alpha: clamp01(material?.opacity ?? 1),
-                doubleSided: material?.doubleSided === true,
+                doubleSided: side === 2,
+                side,
+                windingParity,
             });
         };
         // Geometry groups address the index buffer for indexed geometry and the
@@ -307,6 +331,7 @@ export function rasterizeView(root, dir, opts = {}) {
     const sx = new Float64Array(3);
     const sy = new Float64Array(3);
     const sz = new Float64Array(3);
+    const weights = new Float64Array(3);
     // Orthographic: distance from the viewer runs against the view axis `z`.
     const ordered = compositingOrder(tris, (px, py, pz) => -((px - center[0]) * z[0] + (py - center[1]) * z[1] + (pz - center[2]) * z[2]));
     for (const tri of ordered) {
@@ -317,9 +342,14 @@ export function rasterizeView(root, dir, opts = {}) {
         const nLen = Math.hypot(n[0], n[1], n[2]);
         if (nLen < 1e-12)
             continue;
-        const N = [n[0] / nLen, n[1] / nLen, n[2] / nLen];
+        const N = [
+            (n[0] / nLen) * tri.windingParity,
+            (n[1] / nLen) * tri.windingParity,
+            (n[2] / nLen) * tri.windingParity,
+        ];
         const facing = dot(N, z);
-        if (cull && facing <= 0 && !tri.doubleSided)
+        const normalSign = visibleNormalSign(facing, tri.side, cull);
+        if (normalSign === 0)
             continue;
         if (tri.alpha <= 0)
             continue;
@@ -335,38 +365,20 @@ export function rasterizeView(root, dir, opts = {}) {
         }
         // Flat lambert with the audit-grid light rig, in linear space, then the
         // sRGB output transform (matching what a Three.js renderer would write).
-        const lambert = Math.max(0, dot(N, KEY_DIR));
+        const lambert = Math.max(0, dot(N, KEY_DIR) * normalSign);
         const lit = Math.min(1, AMBIENT + KEY_INTENSITY * lambert);
         const r = Math.round(linearToSrgb(tri.color[0] * lit) * 255);
         const g = Math.round(linearToSrgb(tri.color[1] * lit) * 255);
         const b = Math.round(linearToSrgb(tri.color[2] * lit) * 255);
-        // Rasterize via edge functions.
-        const minX = Math.max(0, Math.floor(Math.min(sx[0], sx[1], sx[2])));
-        const maxX = Math.min(size - 1, Math.ceil(Math.max(sx[0], sx[1], sx[2])));
-        const minY = Math.max(0, Math.floor(Math.min(sy[0], sy[1], sy[2])));
-        const maxY = Math.min(size - 1, Math.ceil(Math.max(sy[0], sy[1], sy[2])));
-        if (minX > maxX || minY > maxY)
-            continue;
-        const ax = sx[0], ay = sy[0], bx2 = sx[1], by = sy[1], cx = sx[2], cy = sy[2];
-        const area = (bx2 - ax) * (cy - ay) - (by - ay) * (cx - ax);
-        if (Math.abs(area) < 1e-9)
+        const triangle = prepareTriangleCoverage(sx[0], sy[0], sx[1], sy[1], sx[2], sy[2], size);
+        if (!triangle)
             continue;
-        const invArea = 1 / area;
+        const { minX, maxX, minY, maxY } = triangle;
         for (let py = minY; py <= maxY; py++) {
             for (let px = minX; px <= maxX; px++) {
-                const cxp = px + 0.5;
-                const cyp = py + 0.5;
-                const w0 = ((bx2 - ax) * (cyp - ay) - (by - ay) * (cxp - ax)) * invArea;
-                const w1 = ((cx - bx2) * (cyp - by) - (cy - by) * (cxp - bx2)) * invArea;
-                const w2 = 1 - w0 - w1;
-                // Accept either winding on screen (back-face culling already happened
-                // in world space) — check all barycentrics share the area's sign space.
-                if (w0 < 0 || w1 < 0 || w2 < 0)
+                if (!triangle.sample(px + 0.5, py + 0.5, weights))
                     continue;
-                // Barycentric weights map: w0 → vertex C, w1 → vertex A, w2 → vertex B
-                // for this edge-function arrangement; depth interpolation just needs a
-                // consistent convex combination, so order doesn't matter for QA views.
-                const depth = w1 * sz[0] + w2 * sz[1] + w0 * sz[2];
+                const depth = weights[0] * sz[0] + weights[1] * sz[1] + weights[2] * sz[2];
                 const pi = py * size + px;
                 if (depth <= zbuf[pi])
                     continue;
@@ -406,7 +418,7 @@ export function measurePartBounds(root) {
  * triangle), but each mesh is transformed once however many requested ancestors contain it.
  */
 export function createPartBoundsReader(root) {
-    root.updateMatrixWorld?.(true);
+    updateSurfaceMatrices(root);
     const own = new Map();
     const meshBounds = (obj) => {
         if (own.has(obj))
@@ -418,9 +430,9 @@ export function createPartBoundsReader(root) {
         if (pos && pos.itemSize === 3 && m) {
             const min = [Infinity, Infinity, Infinity];
             const max = [-Infinity, -Infinity, -Infinity];
-            const arr = pos.array;
+            const readVertex = surfaceVertexReader(mesh, pos);
             for (let i = 0; i < pos.count; i++) {
-                const x = arr[i * 3], y = arr[i * 3 + 1], z = arr[i * 3 + 2];
+                const { x, y, z } = readVertex(i);
                 const w = [
                     m[0] * x + m[4] * y + m[8] * z + m[12],
                     m[1] * x + m[5] * y + m[9] * z + m[13],

package/lib/views/scene-copy.d.ts

@@ -0,0 +1,6 @@
+import { type Object3D } from 'three';
+/** Owned review hierarchy and skeletons; immutable geometry/textures stay shared. */
+export declare function cloneReviewScene(root: Object3D, options?: {
+    omitHidden?: boolean;
+    doubleSided?: boolean;
+}): Object3D;

package/lib/views/scene-copy.js

@@ -0,0 +1,73 @@
+import { DoubleSide, Group, Skeleton, } from 'three';
+/** Owned review hierarchy and skeletons; immutable geometry/textures stay shared. */
+export function cloneReviewScene(root, options = {}) {
+    const visible = new Set();
+    if (options.omitHidden)
+        root.traverseVisible((node) => visible.add(node));
+    else
+        root.traverse((node) => visible.add(node));
+    const retained = new Set(visible);
+    const hierarchy = new Set();
+    root.traverse((node) => hierarchy.add(node));
+    // Visibility hides drawing, not the transforms used by another mesh's skeleton.
+    for (const node of visible) {
+        const mesh = node;
+        if (!mesh.isSkinnedMesh)
+            continue;
+        if (!mesh.skeleton)
+            throw new Error(`Review skin ${mesh.name} has no skeleton.`);
+        for (const bone of mesh.skeleton.bones) {
+            if (!hierarchy.has(bone)) {
+                throw new Error(`Skin bone ${bone?.name ?? '(missing)'} is outside the review hierarchy. Include its ancestors in the review root.`);
+            }
+            for (let ancestor = bone; ancestor; ancestor = ancestor.parent) {
+                retained.add(ancestor);
+                if (ancestor === root)
+                    break;
+            }
+        }
+    }
+    const copies = new Map();
+    const copyNode = (node) => {
+        // A hidden mesh/light can be a joint ancestor. Keep its transform as a group,
+        // not its drawing payload. Referenced bones must retain their Bone identity.
+        const copy = !visible.has(node) && !node.isBone
+            ? new Group().copy(node, false)
+            : node.clone(false);
+        copies.set(node, copy);
+        if (options.omitHidden)
+            copy.visible = true;
+        for (const child of node.children)
+            if (retained.has(child))
+                copy.add(copyNode(child));
+        return copy;
+    };
+    if (!retained.has(root)) {
+        const empty = new Group();
+        empty.name = root.name;
+        return empty;
+    }
+    const copy = copyNode(root);
+    for (const [source, target] of copies) {
+        const sourceSkin = source;
+        const targetSkin = target;
+        if (targetSkin.isSkinnedMesh) {
+            // SkinnedMesh.copy already preserves bind mode/matrices and morph weights.
+            // Reconnect only to copied bones, including detached skeletons. Keep inverse
+            // matrices independent too, so later edits cannot mutate the retained source.
+            targetSkin.skeleton = new Skeleton(sourceSkin.skeleton.bones.map((bone) => copies.get(bone)), sourceSkin.skeleton.boneInverses.map((matrix) => matrix.clone()));
+        }
+        const mesh = target;
+        if (options.doubleSided && mesh.isMesh) {
+            const prepare = (material) => {
+                const owned = material.clone();
+                owned.side = DoubleSide;
+                return owned;
+            };
+            mesh.material = Array.isArray(mesh.material)
+                ? mesh.material.map(prepare)
+                : prepare(mesh.material);
+        }
+    }
+    return copy;
+}

package/lib/views/scene-raster.js

@@ -18,6 +18,7 @@ import { resolveEvaluatorPortV2, } from "../evaluator/index.js";
 import { loadGlbReviewScene } from "./glb.js";
 import { encodePng } from "./png.js";
 import { rasterizeView } from "./raster.js";
+import { cloneReviewScene } from "./scene-copy.js";
 const DEG = Math.PI / 180;
 const PAD = 4;
 const PAD_COLOR = [10, 11, 13];
@@ -51,7 +52,7 @@ export async function rasterizeComposedScene(parts, opts = {}) {
             base = (await loadGlbReviewScene(glb)).root;
             baseByInput.set(key, base);
         }
-        const inst = base.clone(true);
+        const inst = cloneReviewScene(base);
         inst.position.set(part.pos[0], part.pos[1], part.pos[2]);
         inst.rotation.set(0, part.rotYDeg * DEG, 0);
         inst.scale.setScalar(part.scale);

package/lib/views/triangle-coverage.d.ts

@@ -0,0 +1,8 @@
+export declare function prepareTriangleCoverage(ax: number, ay: number, bx: number, by: number, cx: number, cy: number, size: number): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    /** Writes A/B/C weights into caller-owned storage; no per-pixel allocations. */
+    sample(x: number, y: number, weights: Float64Array): boolean;
+} | null;

package/lib/views/triangle-coverage.js

@@ -0,0 +1,58 @@
+function edge(ax, ay, bx, by, orientation) {
+    const dx = (bx - ax) * orientation;
+    const dy = (by - ay) * orientation;
+    // Screen Y grows downward. For positive area, top/left edges own exact ties.
+    const inclusive = dy < 0 || (dy === 0 && dx > 0);
+    // Both triangles evaluate a shared edge from the SAME endpoint. Merely reversing
+    // (B-A)x(P-A) can round differently from (A-B)x(P-B), causing cracks/overlap.
+    const forward = ax < bx || (ax === bx && ay <= by);
+    return forward
+        ? { x: ax, y: ay, dx: bx - ax, dy: by - ay, sign: orientation, inclusive }
+        : { x: bx, y: by, dx: ax - bx, dy: ay - by, sign: -orientation, inclusive };
+}
+function value(e, x, y) {
+    return (e.dx * (y - e.y) - e.dy * (x - e.x)) * e.sign;
+}
+export function prepareTriangleCoverage(ax, ay, bx, by, cx, cy, size) {
+    if (![ax, ay, bx, by, cx, cy].every(Number.isFinite))
+        return null;
+    const area = value(edge(ax, ay, bx, by, 1), cx, cy);
+    if (!Number.isFinite(area) || area === 0)
+        return null;
+    const orientation = area < 0 ? -1 : 1;
+    const a = edge(bx, by, cx, cy, orientation);
+    const b = edge(cx, cy, ax, ay, orientation);
+    const c = edge(ax, ay, bx, by, orientation);
+    const minX = Math.max(0, Math.floor(Math.min(ax, bx, cx)));
+    const maxX = Math.min(size - 1, Math.ceil(Math.max(ax, bx, cx)));
+    const minY = Math.max(0, Math.floor(Math.min(ay, by, cy)));
+    const maxY = Math.min(size - 1, Math.ceil(Math.max(ay, by, cy)));
+    if (minX > maxX || minY > maxY)
+        return null;
+    return {
+        minX,
+        maxX,
+        minY,
+        maxY,
+        /** Writes A/B/C weights into caller-owned storage; no per-pixel allocations. */
+        sample(x, y, weights) {
+            const wa = value(a, x, y), wb = value(b, x, y), wc = value(c, x, y);
+            if (wa < 0 ||
+                wb < 0 ||
+                wc < 0 ||
+                (wa === 0 && !a.inclusive) ||
+                (wb === 0 && !b.inclusive) ||
+                (wc === 0 && !c.inclusive))
+                return false;
+            // Evaluate all three edges directly. Deriving one as 1-wa-wb was the source
+            // of false negative coverage. Tie ownership never biases interpolation.
+            const sum = wa + wb + wc;
+            if (!(sum > 0) || !Number.isFinite(sum))
+                return false;
+            weights[0] = wa / sum;
+            weights[1] = wb / sum;
+            weights[2] = wc / sum;
+            return true;
+        },
+    };
+}

package/lib/workspace-node.js

@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { join } from 'node:path';
 import { FileProjectStore } from "./projects-node.js";
-import { FileMaterialLibrary, createMaterialLibraryPayload } from "./material-library-node.js";
+import { FileMaterialLibrary, createMaterialLibraryPayload, resolveMaterialRecordClosure, } from "./material-library-node.js";
 import { workspaceSelectionSchema, } from "./workspace.js";
 import { materialDependenciesSchema } from "./projects.js";
 import { MATERIAL_LIBRARY_LIMITS } from "./material-library.js";
@@ -58,16 +58,20 @@ export class FileWorkspace {
         const materialDependencies = materialDependenciesSchema.parse([...pins.values()].sort((a, b) => a.resourceId.localeCompare(b.resourceId)));
         if (materialDependencies.length > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
             throw new Error(`An evaluation may resolve at most ${MATERIAL_LIBRARY_LIMITS.maxPayloadRecords} material resources; select a smaller dependency closure.`);
-        const materials = await Promise.all(materialDependencies.map(async (dependency) => {
+        const manifests = await Promise.all(materialDependencies.map(async (dependency) => {
             if (dependency.sha256 !== dependency.revisionId)
                 throw new Error(`Material lock hash mismatch: ${dependency.resourceId}`);
             try {
-                return await this.materials.read(dependency.resourceId, dependency.revisionId);
+                return await this.materials.readManifest(dependency.resourceId, dependency.revisionId);
             }
             catch (error) {
                 throw new Error(`Locked material unavailable: ${dependency.resourceId} at ${dependency.revisionId}`, { cause: error });
             }
         }));
+        const materials = await resolveMaterialRecordClosure(manifests, {
+            readManifest: (id, revision) => this.materials.readManifest(id, revision),
+            read: (id, revision) => this.materials.readRecordFiles(id, revision),
+        });
         const materialResources = await createMaterialLibraryPayload(materials);
         return this.active.run({ ...(project ? { project } : {}), materialDependencies, materialResources }, execute);
     }

package/lib/workspace.d.ts

@@ -1,10 +1,10 @@
 import { z } from 'zod';
 import { type MaterialDependency, type ProjectRevision } from "./projects.js";
-import type { MaterialLibraryPayloadV1 } from "./material-library.js";
+import type { MaterialLibraryPayload } from "./material-library.js";
 export interface WorkspaceBinding {
     project?: ProjectRevision;
     materialDependencies: MaterialDependency[];
-    materialResources: MaterialLibraryPayloadV1;
+    materialResources: MaterialLibraryPayload;
 }
 export declare const workspaceSelectionSchema: z.ZodObject<{
     projectId: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruktlabs/kiln",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",
   "license": "MIT",
   "author": "Matthew Kissinger",
@@ -293,6 +293,8 @@
     "docs/install.md",
     "docs/material-library.md",
     "docs/migration.md",
+    "docs/procedural-surfaces-v3.md",
+    "docs/atlas-provenance.md",
     "docs/programs.md",
     "docs/projects-and-live-review.md",
     "docs/rendering.md",

package/plugin.json

@@ -2,7 +2,7 @@
   "name": "kiln",
   "displayName": "Kiln",
   "description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "license": "MIT",
   "homepage": "https://github.com/instruktlabs/kiln",
   "keywords": [

package/plugins/kiln-engine/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "kiln-engine",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
   "author": {
     "name": "Instrukt Labs",

package/plugins/kiln-engine/README.md

@@ -1,7 +1,7 @@
 # Kiln local plugin
 
-Plugin version 1.2.1, maintained by Instrukt Labs under the MIT license.
-This plugin pins engine 1.2.1. Registry setup requires that exact version
+Plugin version 1.2.3, maintained by Instrukt Labs under the MIT license.
+This plugin pins engine 1.2.3. Registry setup requires that exact version
 to be published. Use a published release tag for normal installation or a reviewed
 local archive for development qualification. The installation ID remains
 `kiln-engine@instruktlabs`.
@@ -31,7 +31,7 @@ codex plugin add kiln-engine@instruktlabs
 Restart or reload your coding agent's plugins as its installation message directs.
 Then ask it to set up a Kiln workspace. The maintained setup skill runs this
 plugin's `bin/kiln-setup-workspace.mjs` with Node, installs
-`@instruktlabs/kiln@1.2.1` outside the project and configures your chosen
+`@instruktlabs/kiln@1.2.3` outside the project and configures your chosen
 workspace. The same initializer supports existing projects and new workspaces.
 
 The plugin registers setup only. The workspace supplies authoring skills and one