@instruktlabs/kiln 1.2.1 → 1.2.3

package/src/views/raster.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,7 +20,10 @@
  * the offline audit grid) so inverted winding shows up as missing faces.
  */
 
+import { Vector3 } from 'three';
 import { resolveBackdrop, type BackdropId } from './background';
+import { visibleNormalSign, worldWindingParity, type SurfaceSide } from './face-policy';
+import { prepareTriangleCoverage } from './triangle-coverage';
 
 export interface ViewSpec {
   name: string;
@@ -118,7 +121,10 @@ export interface RasterOptions {
    * (a sideways/forward-sliding walk would look stationary). The scene's own
    * geometry is still drawn; only the camera center/zoom come from this box.
    */
-  frameBounds?: { min: [number, number, number]; max: [number, number, number] };
+  frameBounds?: {
+    min: [number, number, number];
+    max: [number, number, number];
+  };
   /** Named backdrop to clear to. Omit for the default; see `views/background.ts`. */
   backdrop?: BackdropId;
 }
@@ -146,6 +152,9 @@ interface DuckAttribute {
   array: ArrayLike<number>;
   itemSize: number;
   count: number;
+  getX?(index: number): number;
+  getY?(index: number): number;
+  getZ?(index: number): number;
 }
 interface DuckGeometry {
   getAttribute(name: string): DuckAttribute | undefined;
@@ -159,6 +168,7 @@ interface DuckMaterial {
   /** Effective glTF base-color alpha after OPAQUE/MASK/BLEND handling. */
   opacity?: number;
   doubleSided?: boolean;
+  side?: number;
   visible?: boolean;
 }
 interface DuckMesh {
@@ -167,20 +177,50 @@ interface DuckMesh {
   geometry?: DuckGeometry;
   material?: DuckMaterial | DuckMaterial[];
   matrixWorld?: { elements: ArrayLike<number> };
+  getVertexPosition?(index: number, target: Vector3): Vector3;
+  skeleton?: { bones: DuckObject3D[] };
 }
 interface DuckObject3D {
   visible?: boolean;
   children?: DuckObject3D[];
   updateMatrixWorld?(force?: boolean): void;
+  updateWorldMatrix?(updateParents: boolean, updateChildren: boolean): void;
   traverse?(cb: (obj: unknown) => void): void;
 }
 
+function updateSurfaceMatrices(root: DuckObject3D): void {
+  // 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: DuckMesh, position: DuckAttribute): (index: number) => Vector3 {
+  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]!,
+    );
+}
+
 interface Tri {
   // World-space vertices, flattened [x0,y0,z0, x1,y1,z1, x2,y2,z2]
   v: Float64Array;
   color: [number, number, number];
   alpha: number;
   doubleSided: boolean;
+  side: SurfaceSide;
+  windingParity: 1 | -1;
 }
 
 /**
@@ -241,7 +281,7 @@ export function collectTriangles(root: DuckObject3D): {
   tris: Tri[];
   bbox: { min: Vec3; max: Vec3 };
 } {
-  root.updateMatrixWorld?.(true);
+  updateSurfaceMatrices(root);
 
   const tris: Tri[] = [];
   const min: Vec3 = [Infinity, Infinity, Infinity];
@@ -277,13 +317,12 @@ export function collectTriangles(root: DuckObject3D): {
 
     const m = mesh.matrixWorld?.elements;
     if (!m) return;
+    const windingParity = worldWindingParity(m);
 
-    const arr = pos.array;
+    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]!;
@@ -309,11 +348,15 @@ export function collectTriangles(root: DuckObject3D): {
       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,
       });
     };
 
@@ -410,6 +453,7 @@ export function rasterizeView(
   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(
@@ -423,10 +467,15 @@ export function rasterizeView(
     const n = cross(e1, e2);
     const nLen = Math.hypot(n[0], n[1], n[2]);
     if (nLen < 1e-12) continue;
-    const N: Vec3 = [n[0] / nLen, n[1] / nLen, n[2] / nLen];
+    const N: Vec3 = [
+      (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) continue;
+    const normalSign = visibleNormalSign(facing, tri.side, cull);
+    if (normalSign === 0) continue;
     if (tri.alpha <= 0) continue;
 
     // Project to screen space.
@@ -442,43 +491,20 @@ export function rasterizeView(
 
     // 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) continue;
-    const invArea = 1 / area;
+    const triangle = prepareTriangleCoverage(sx[0]!, sy[0]!, sx[1]!, sy[1]!, sx[2]!, sy[2]!, size);
+    if (!triangle) continue;
+    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) 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]!;
+        if (!triangle.sample(px + 0.5, py + 0.5, weights)) continue;
+        const depth = weights[0]! * sz[0]! + weights[1]! * sz[1]! + weights[2]! * sz[2]!;
         const pi = py * size + px;
         if (depth <= zbuf[pi]!) continue;
         zbuf[pi] = depth;
@@ -525,7 +551,7 @@ export function measurePartBounds(root: unknown): ReturnType<typeof measureBound
 export function createPartBoundsReader(
   root: unknown,
 ): (node: unknown) => ReturnType<typeof measureBounds> | null {
-  (root as DuckObject3D).updateMatrixWorld?.(true);
+  updateSurfaceMatrices(root as DuckObject3D);
   const own = new Map<unknown, { min: Vec3; max: Vec3; tris: number } | null>();
   const meshBounds = (obj: unknown) => {
     if (own.has(obj)) return own.get(obj)!;
@@ -536,11 +562,9 @@ export function createPartBoundsReader(
     if (pos && pos.itemSize === 3 && m) {
       const min: Vec3 = [Infinity, Infinity, Infinity];
       const max: Vec3 = [-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: Vec3 = [
           m[0]! * x + m[4]! * y + m[8]! * z + m[12]!,
           m[1]! * x + m[5]! * y + m[9]! * z + m[13]!,
@@ -614,7 +638,10 @@ export function hideNodeInScene(
   let hidden = 0;
   const r = root as DuckObject3D;
   r.traverse?.((obj) => {
-    const node = obj as { name?: string; traverse?(cb: (o: unknown) => void): void };
+    const node = obj as {
+      name?: string;
+      traverse?(cb: (o: unknown) => void): void;
+    };
     if (!node.name || !test(node.name)) return;
     hidden++;
     // Flip the matched node and its whole subtree (the per-mesh cull means hiding

package/src/views/scene-copy.ts

@@ -0,0 +1,86 @@
+import {
+  DoubleSide,
+  Group,
+  Skeleton,
+  type Bone,
+  type Material,
+  type Mesh,
+  type Object3D,
+  type SkinnedMesh,
+} from 'three';
+
+/** Owned review hierarchy and skeletons; immutable geometry/textures stay shared. */
+export function cloneReviewScene(
+  root: Object3D,
+  options: { omitHidden?: boolean; doubleSided?: boolean } = {},
+): Object3D {
+  const visible = new Set<Object3D>();
+  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<Object3D>();
+  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 as SkinnedMesh;
+    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: Object3D | null = bone; ancestor; ancestor = ancestor.parent) {
+        retained.add(ancestor);
+        if (ancestor === root) break;
+      }
+    }
+  }
+
+  const copies = new Map<Object3D, Object3D>();
+  const copyNode = (node: Object3D): Object3D => {
+    // 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 as Bone).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 as SkinnedMesh;
+    const targetSkin = target as SkinnedMesh;
+    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) as Bone),
+        sourceSkin.skeleton.boneInverses.map((matrix) => matrix.clone()),
+      );
+    }
+    const mesh = target as Mesh;
+    if (options.doubleSided && mesh.isMesh) {
+      const prepare = (material: 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/src/views/scene-raster.ts

@@ -23,6 +23,7 @@ import {
 import { loadGlbReviewScene } from './glb';
 import { encodePng } from './png';
 import { rasterizeView, type ViewSpec } from './raster';
+import { cloneReviewScene } from './scene-copy';
 
 const DEG = Math.PI / 180;
 const PAD = 4;
@@ -103,7 +104,7 @@ export async function rasterizeComposedScene(
       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/src/views/triangle-coverage.ts

@@ -0,0 +1,78 @@
+/** Pixel-centre coverage shared by the flat CPU renderers. No shading/culling policy. */
+interface Edge {
+  x: number;
+  y: number;
+  dx: number;
+  dy: number;
+  sign: number;
+  inclusive: boolean;
+}
+
+function edge(ax: number, ay: number, bx: number, by: number, orientation: number): Edge {
+  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: Edge, x: number, y: number): number {
+  return (e.dx * (y - e.y) - e.dy * (x - e.x)) * e.sign;
+}
+
+export function prepareTriangleCoverage(
+  ax: number,
+  ay: number,
+  bx: number,
+  by: number,
+  cx: number,
+  cy: number,
+  size: number,
+) {
+  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: number, y: number, weights: Float64Array): boolean {
+      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/src/workspace-node.ts

@@ -1,7 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { join } from 'node:path';
 import { FileProjectStore } from './projects-node';
-import { FileMaterialLibrary, createMaterialLibraryPayload } from './material-library-node';
+import {
+  FileMaterialLibrary,
+  createMaterialLibraryPayload,
+  resolveMaterialRecordClosure,
+} from './material-library-node';
 import {
   workspaceSelectionSchema,
   type WorkspaceBinding,
@@ -68,12 +72,12 @@ export class FileWorkspace implements WorkspacePort {
       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(
+    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}`,
@@ -82,6 +86,10 @@ export class FileWorkspace implements WorkspacePort {
         }
       }),
     );
+    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 },

package/src/workspace.ts

@@ -6,12 +6,12 @@ import {
   type MaterialDependency,
   type ProjectRevision,
 } from './projects';
-import type { MaterialLibraryPayloadV1 } from './material-library';
+import type { MaterialLibraryPayload } from './material-library';
 
 export interface WorkspaceBinding {
   project?: ProjectRevision;
   materialDependencies: MaterialDependency[];
-  materialResources: MaterialLibraryPayloadV1;
+  materialResources: MaterialLibraryPayload;
 }
 export const workspaceSelectionSchema = z
   .object({