partforge 0.155.0 → 0.157.0

package/src/framework/gltf/decode-preview.js

@@ -11,8 +11,11 @@
 // rotation; parenting the glTF root under the pivot would turn the part twice.
 // Undoing the root here hands the viewer geometry in the frame it already owns.
 //
-// Feature edges (encoder version 2): a sub-part's mesh may carry a second
-// primitive, mode LINES, holding the kernel's edge segments. GLTFLoader then
+// Feature edges (encoder version 2+): a sub-part's mesh may carry a second
+// primitive, mode LINES, holding the kernel's edge segments — with its own
+// vertices in version 2, as indices into the surface's vertex array in version 3
+// (which may also carry, past the surface's own vertices, endpoints that lie on
+// none of them: the payload's positions stop before those). GLTFLoader then
 // makes the node a Group of a Mesh and a LineSegments (the node's extras and
 // name on the Group, not the Mesh), so each surface and its lines are matched
 // through the glTF NODE they belong to. Lines go back to model frame through
@@ -36,11 +39,12 @@ function toArrayBuffer(bytes) {
   throw new TypeError("decodePreviewGlb: the preview must be a Uint8Array or an ArrayBuffer");
 }
 
-// Read a (possibly quantized, normalized) vec3 attribute out as Float32, transformed.
-function readVec3(attr, matrix, isNormal) {
-  const out = new Float32Array(attr.count * 3);
+// Read a (possibly quantized, normalized) vec3 attribute out as Float32,
+// transformed — its first `count` elements (all of them by default).
+function readVec3(attr, matrix, isNormal, count = attr.count) {
+  const out = new Float32Array(count * 3);
   const v = new Vector3();
-  for (let i = 0; i < attr.count; i++) {
+  for (let i = 0; i < count; i++) {
     v.fromBufferAttribute(attr, i); // denormalizes a KHR_mesh_quantization attribute
     if (isNormal) v.applyMatrix3(matrix).normalize();
     else v.applyMatrix4(matrix);
@@ -70,19 +74,38 @@ function nodeObjectOf(obj) {
   return parent?.isGroup && parent.userData && ("partforgeSubPart" in parent.userData || "name" in parent.userData) ? parent : obj;
 }
 
-// Line segments as endpoint pairs in model frame (an indexed LINES primitive —
-// weld() indexes it — expanded back to pairs).
+// Line segments as endpoint pairs in model frame: an indexed LINES primitive
+// expanded back to pairs. Version 3's position attribute is the SURFACE's
+// (GLTFLoader hands both objects the same BufferAttribute), so only the
+// vertices the line indices name are read — never the whole array.
 function readSegments(geometry, matrix) {
   const position = geometry.getAttribute("position");
   if (!position || position.count === 0) return null;
-  const points = readVec3(position, matrix, false);
-  if (!geometry.index) return points;
+  if (!geometry.index) return readVec3(position, matrix, false);
   const index = geometry.index.array;
   const out = new Float32Array(index.length * 3);
-  for (let i = 0; i < index.length; i++) out.set(points.subarray(index[i] * 3, index[i] * 3 + 3), i * 3);
+  const v = new Vector3();
+  for (let i = 0; i < index.length; i++) {
+    v.fromBufferAttribute(position, index[i]).applyMatrix4(matrix);
+    out[i * 3] = v.x;
+    out[i * 3 + 1] = v.y;
+    out[i * 3 + 2] = v.z;
+  }
   return out;
 }
 
+// How many leading vertices the surface's triangles use. Version 3 appends edge
+// endpoints that lie on no surface vertex AFTER the surface's own (which weld +
+// reorder leave all referenced, in first-use order); they belong to the lines,
+// so the payload stops before them. For versions 1–2 this is every vertex.
+function surfaceVertexCount(position, index) {
+  if (!index) return position.count;
+  let max = -1;
+  const a = index.array;
+  for (let i = 0; i < a.length; i++) if (a[i] > max) max = a[i];
+  return max + 1;
+}
+
 export async function decodePreviewGlb(bytes) {
   const data = toArrayBuffer(bytes);
   const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
@@ -112,15 +135,16 @@ export async function decodePreviewGlb(bytes) {
     normalMatrix.getNormalMatrix(toModel);
     const normal = geometry.getAttribute("normal");
     const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
+    const count = surfaceVertexCount(position, geometry.index);
     const node = nodeObjectOf(obj);
     const { partforgeSubPart, partforgeDisplay, name: originalName } = node.userData;
     const payload = {
       // The writer's own record of the key, then the unsanitized glTF node name.
       name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? node.name),
-      positions: readVec3(position, toModel, false),
-      normals: normal ? readVec3(normal, normalMatrix, true) : null,
+      positions: readVec3(position, toModel, false, count),
+      normals: normal ? readVec3(normal, normalMatrix, true, count) : null,
       indices,
-      triangles: (indices ? indices.length : position.count) / 3,
+      triangles: (indices ? indices.length : count) / 3,
       edges: new Float32Array(0), // filled below from the node's LINES primitive, if any
       display: partforgeDisplay && typeof partforgeDisplay === "object" ? partforgeDisplay : null,
     };

package/src/framework/gltf/encode-preview.js

@@ -6,12 +6,27 @@
 //  - one node + mesh per sub-part, both named by the sub-part key; the mesh's
 //    FIRST primitive is the surface (TRIANGLES: POSITION + NORMAL, + indices
 //    when the kernel sent them); a sub-part with feature edges adds a SECOND
-//    primitive, mode LINES, POSITION only and no material — the kernel's edge
-//    segments in the same posed frame. A sub-part whose `edges` is empty or
-//    absent has no line primitive; a reader takes that as "no feature edges"
-//    (never "derive them"). Version-1 files have no line primitives at all.
-//    Both primitives share the mesh, so quantize() gives them ONE quantization
-//    volume and one node transform: the lines dequantize onto the faces.
+//    primitive, mode LINES, no material, whose POSITION is the SAME accessor as
+//    the surface's (version 3) and whose indices are the segments' endpoint
+//    pairs. Each endpoint is the surface vertex at its position — bit-exact
+//    first, else the nearest within one 14-bit quantization step of the mesh —
+//    and an endpoint on no vertex is APPENDED to that shared array, where no
+//    triangle references it, so the surface's triangles are unchanged and no
+//    edge is dropped.
+//    A sub-part whose `edges` is empty or absent has no line primitive; a reader
+//    takes that as "no feature edges" (never "derive them"). A reader must take
+//    the line primitive's INDICES, not its whole vertex array.
+//    Version 1 had no line primitives; version 2 gave the lines their own
+//    POSITION accessor on the same mesh (both still decode). Rare fallback, also
+//    in version 3: a sub-part whose lines would need either
+//      (a) an appended endpoint OUTSIDE the surface's bounds — it would widen
+//          the mesh's quantization volume and coarsen the surface — or
+//      (b) so many appended endpoints that quantize() compacts the surface
+//          (its condition: index count < vertex count / 2, the appended
+//          vertices counted), dropping them,
+//    writes its lines with vertices of their own (unindexed, float, added after
+//    quantize() in the node's quantized frame), so the surface quantizes
+//    exactly as it would with no edges at all.
 //  - every sub-part node under ONE root node, "partforge", rotated −90° about X:
 //    partforge models Z-up in millimetres and glTF is Y-up. Units stay mm — the
 //    file is for partforge's own viewer; metres would only matter for AR.
@@ -19,22 +34,29 @@
 //    and each node's extras carrying the sub-part's own `display` block, so a
 //    part-less viewer (mountPreview) can rebuild the exact look, realistic too
 //  - top-level extras { partforgeView, partforgeEncoder, partforgeMeta? }
-//  - weld() → quantize() → meshopt({ level: "medium" }): 5–8 bytes a triangle,
-//    the recipe measured in partforge-cloud's local_glb_benchmark.md
-// Not encoded: textures, patterns. (Feature edges since version 2.)
+//  - weld() → reorder() → quantize() → EXT_meshopt_compression ("medium",
+//    i.e. what meshopt({ level: "medium" }) does), 5–8 bytes a triangle, the
+//    recipe measured in partforge-cloud's local_glb_benchmark.md. The line
+//    primitives are added AFTER quantize(): weld(), reorder() and quantize()
+//    each clone a primitive's accessors (compactPrimitive / per-index-set
+//    compaction / attribute.clone()), which would split a shared POSITION back
+//    into two arrays. Endpoints are mapped after weld+reorder (the final vertex
+//    order) and appended before quantize (so they are quantized with the rest).
+// Not encoded: textures, patterns. (Feature edges since version 2, shared
+// vertices since version 3.)
 //
 // Runs in Node, a page and a Web Worker: no three.js, no DOM, no Blob
 // (test/gltf-layering.test.js). Deterministic: the same input writes the same
 // bytes, and nothing here mutates the input (exportPreview passes the viewer's
 // live buffers). Bump PREVIEW_ENCODER_VERSION whenever the bytes for the same
 // input change — downstream caches key on it.
-import { Document, Logger, Primitive, WebIO } from "@gltf-transform/core";
+import { Document, Logger, Node, Primitive, WebIO } from "@gltf-transform/core";
 import { EXTMeshoptCompression, KHRMeshQuantization } from "@gltf-transform/extensions";
-import { meshopt, quantize, weld } from "@gltf-transform/functions";
+import { quantize, reorder, weld } from "@gltf-transform/functions";
 import { MeshoptEncoder } from "meshoptimizer/encoder";
 import { cadAppearance, DISPLAY_KEYS } from "../materials/resolve.js";
 
-export const PREVIEW_ENCODER_VERSION = 2; // 2: feature edges as a LINES primitive
+export const PREVIEW_ENCODER_VERSION = 3; // 2: feature edges as a LINES primitive; 3: sharing the surface's vertices
 
 // −90° about X as [x, y, z, w]: model (x, y, z) → glTF (x, z, −y), the viewer's pivot.
 const Z_UP_TO_Y_UP = [-Math.SQRT1_2, 0, 0, Math.SQRT1_2];
@@ -66,6 +88,166 @@ function metaExtras(meta) {
   return Object.keys(out).length ? out : null;
 }
 
+// quantize()'s default POSITION precision; one step of it over the mesh's widest
+// extent is the snapping tolerance — closer than that, quantization itself may
+// put the two points on one grid value.
+const POSITION_BITS = 14;
+// quantize() compacts a primitive whose index count is under half its vertex
+// count — which would drop the appended endpoints no triangle references.
+const compactsAt = (indexCount, vertexCount) => indexCount < vertexCount / 2;
+
+const f32 = new Float32Array(1);
+const u32 = new Uint32Array(f32.buffer);
+const bitsOf = (x) => { f32[0] = x === 0 ? 0 : x; return u32[0]; }; // -0 and 0 alike
+
+// A bit-exact position → vertex lookup (open addressing; deterministic).
+function exactTable(capacity) {
+  let size = 16;
+  while (size < capacity * 2) size *= 2;
+  const keys = new Uint32Array(size * 3);
+  const values = new Int32Array(size).fill(-1);
+  const slot = (a, b, c) => (Math.imul(a, 73856093) ^ Math.imul(b, 19349663) ^ Math.imul(c, 83492791)) & (size - 1);
+  return {
+    get(a, b, c) {
+      for (let s = slot(a, b, c); values[s] !== -1; s = (s + 1) & (size - 1)) {
+        if (keys[s * 3] === a && keys[s * 3 + 1] === b && keys[s * 3 + 2] === c) return values[s];
+      }
+      return -1;
+    },
+    set(a, b, c, v) {
+      let s = slot(a, b, c);
+      while (values[s] !== -1) s = (s + 1) & (size - 1);
+      keys.set([a, b, c], s * 3);
+      values[s] = v;
+    },
+  };
+}
+
+// Map every edge endpoint to a vertex of `positions` (the welded, reordered
+// surface): bit-exact, else the nearest within `tol`, else a NEW vertex,
+// returned in `appended` (deduplicated, so two segments meeting off the surface
+// share one). Returns { pairs: Uint32Array of endpoint indices, appended: number[] }.
+function mapEdges(positions, edges, tol) {
+  const vertexCount = positions.length / 3;
+  const endpoints = edges.length / 3;
+  const exact = exactTable(vertexCount + endpoints);
+  for (let v = 0; v < vertexCount; v++) { // the first vertex at a position wins
+    const a = bitsOf(positions[v * 3]), b = bitsOf(positions[v * 3 + 1]), c = bitsOf(positions[v * 3 + 2]);
+    if (exact.get(a, b, c) === -1) exact.set(a, b, c, v);
+  }
+  let grid = null; // cell → vertex indices, built on the first miss
+  const cellOf = (x) => Math.floor(x / tol);
+  const cellKey = (i, j, k) => `${i},${j},${k}`;
+  const nearest = (x, y, z) => {
+    if (!(tol > 0)) return -1;
+    if (!grid) {
+      grid = new Map();
+      for (let v = 0; v < vertexCount; v++) {
+        const key = cellKey(cellOf(positions[v * 3]), cellOf(positions[v * 3 + 1]), cellOf(positions[v * 3 + 2]));
+        const list = grid.get(key);
+        if (list) list.push(v); else grid.set(key, [v]);
+      }
+    }
+    const ci = cellOf(x), cj = cellOf(y), ck = cellOf(z);
+    let best = -1;
+    let bestD = tol * tol;
+    for (let di = -1; di <= 1; di++) for (let dj = -1; dj <= 1; dj++) for (let dk = -1; dk <= 1; dk++) {
+      for (const v of grid.get(cellKey(ci + di, cj + dj, ck + dk)) ?? []) {
+        const dx = positions[v * 3] - x, dy = positions[v * 3 + 1] - y, dz = positions[v * 3 + 2] - z;
+        const d = dx * dx + dy * dy + dz * dz;
+        if (d < bestD || (d === bestD && best !== -1 && v < best)) { bestD = d; best = v; }
+      }
+    }
+    return best;
+  };
+  const pairs = new Uint32Array(endpoints);
+  const appended = [];
+  for (let e = 0; e < endpoints; e++) {
+    const x = edges[e * 3], y = edges[e * 3 + 1], z = edges[e * 3 + 2];
+    const a = bitsOf(x), b = bitsOf(y), c = bitsOf(z);
+    let v = exact.get(a, b, c);
+    if (v === -1) v = nearest(x, y, z);
+    if (v === -1) {
+      v = vertexCount + appended.length / 3;
+      appended.push(x, y, z);
+      exact.set(a, b, c, v);
+    }
+    pairs[e] = v;
+  }
+  return { pairs: sortSegments(pairs), appended };
+}
+
+// Segments as (low, high) pairs in ascending order: the same set of lines, but an
+// index stream meshopt's delta coding compresses far better than the kernel's order.
+export function sortSegments(pairs) {
+  const n = pairs.length / 2;
+  const keys = new BigUint64Array(n); // (low << 32) | high, exact for every Uint32 index
+  for (let s = 0; s < n; s++) {
+    const a = pairs[s * 2], b = pairs[s * 2 + 1];
+    keys[s] = (BigInt(Math.min(a, b)) << 32n) | BigInt(Math.max(a, b));
+  }
+  keys.sort();
+  const out = new Uint32Array(pairs.length);
+  for (let s = 0; s < n; s++) {
+    out[s * 2] = Number(keys[s] >> 32n);
+    out[s * 2 + 1] = Number(keys[s] & 0xffffffffn);
+  }
+  return out;
+}
+
+function boundsOf(positions) {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < positions.length; i += 3) {
+    for (let a = 0; a < 3; a++) {
+      if (positions[i + a] < min[a]) min[a] = positions[i + a];
+      if (positions[i + a] > max[a]) max[a] = positions[i + a];
+    }
+  }
+  return { min, max };
+}
+// Column-major 4×4 helpers (glTF's layout) for the fallback's frame change. A
+// node matrix is affine, so the inverse is the 3×3 block's inverse plus the
+// translation carried through it.
+function multiply(a, b) {
+  const out = new Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      let v = 0;
+      for (let k = 0; k < 4; k++) v += a[k * 4 + r] * b[c * 4 + k];
+      out[c * 4 + r] = v;
+    }
+  }
+  return out;
+}
+function invertAffine(m) {
+  const [a, b, c, d, e, f, g, h, i] = [m[0], m[4], m[8], m[1], m[5], m[9], m[2], m[6], m[10]]; // rows
+  const A = e * i - f * h, B = -(d * i - f * g), C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (!det) throw new Error("encodePreviewGlb: a mesh node's transform is not invertible");
+  const inv = [ // rows of the 3×3 inverse
+    A / det, -(b * i - c * h) / det, (b * f - c * e) / det,
+    B / det, (a * i - c * g) / det, -(a * f - c * d) / det,
+    C / det, -(a * h - b * g) / det, (a * e - b * d) / det,
+  ];
+  const t = [m[12], m[13], m[14]];
+  const out = new Array(16).fill(0);
+  for (let r = 0; r < 3; r++) {
+    for (let col = 0; col < 3; col++) out[col * 4 + r] = inv[r * 3 + col];
+    out[12 + r] = -(inv[r * 3] * t[0] + inv[r * 3 + 1] * t[1] + inv[r * 3 + 2] * t[2]);
+  }
+  out[15] = 1;
+  return out;
+}
+const meshNode = (mesh) => mesh.listParents().find((p) => p instanceof Node);
+
+const outside = (points, { min, max }) => {
+  for (let i = 0; i < points.length; i += 3) {
+    for (let a = 0; a < 3; a++) if (points[i + a] < min[a] || points[i + a] > max[a]) return true;
+  }
+  return false;
+};
+
 function checkMesh(m, seen) {
   if (!m || typeof m.name !== "string" || !m.name) throw new TypeError("encodePreviewGlb: every mesh needs a non-empty string name");
   if (seen.has(m.name)) throw new Error(`encodePreviewGlb: two meshes are named "${m.name}"`);
@@ -121,6 +303,7 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
     ...(meta ? { partforgeMeta: meta } : {}),
   });
 
+  const pending = []; // { mesh, surface, edges } — line primitives to add after quantize()
   for (const m of meshes) {
     if (m.positions.length === 0) continue; // glTF forbids a zero-count accessor
     // Copies throughout: setArray keeps the array it is handed, and the
@@ -141,10 +324,7 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
       .setRoughnessFactor(look.roughness)
       .setAlphaMode(look.opacity < 1 ? "BLEND" : "OPAQUE"));
     const mesh = doc.createMesh(m.name).addPrimitive(prim);
-    if (m.edges?.length) {
-      mesh.addPrimitive(doc.createPrimitive().setMode(Primitive.Mode.LINES).setAttribute(
-        "POSITION", doc.createAccessor().setType("VEC3").setArray(Float32Array.from(m.edges)).setBuffer(buffer)));
-    }
+    if (m.edges?.length) pending.push({ mesh, surface: prim, edges: Float32Array.from(m.edges) });
     const extras = displayExtras(display);
     root.addChild(doc.createNode(m.name)
       .setMesh(mesh)
@@ -152,7 +332,73 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
   }
   if (root.listChildren().length === 0) throw new Error("encodePreviewGlb: every mesh was empty");
 
-  await doc.transform(weld(), quantize(), meshopt({ encoder: MeshoptEncoder, level: "medium" }));
+  // The surfaces alone through weld + reorder: their vertex arrays are final after this.
+  await doc.transform(weld(), reorder({ encoder: MeshoptEncoder, target: "size" }));
+
+  // Map each endpoint onto those vertices; append the ones on none. Then quantize
+  // with the appended vertices in place, and only then add the line primitives.
+  const shared = [];
+  const ownVertices = []; // { mesh, edges, before } — the fallback, added after quantize()
+  for (const { mesh, surface, edges } of pending) {
+    const position = surface.getAttribute("POSITION");
+    const positions = position.getArray();
+    const bounds = boundsOf(positions);
+    const tol = Math.max(...bounds.max.map((hi, a) => hi - bounds.min[a])) / 2 ** POSITION_BITS;
+    const { pairs, appended } = mapEdges(positions, edges, tol);
+    const vertexCount = positions.length / 3 + appended.length / 3;
+    if (outside(appended, bounds) || compactsAt(surface.getIndices().getCount(), vertexCount)) {
+      // Appending would change the surface's quantization volume, or quantize()
+      // would compact the surface and drop the appended endpoints: these lines
+      // keep vertices of their own instead (see the file header).
+      ownVertices.push({ mesh, edges, before: meshNode(mesh).getWorldMatrix() });
+      continue;
+    }
+    if (appended.length) {
+      const grown = new Float32Array(vertexCount * 3);
+      grown.set(positions);
+      grown.set(appended, positions.length);
+      position.setArray(grown);
+      const normal = surface.getAttribute("NORMAL");
+      if (normal) { // unit +Z for vertices no triangle draws: a valid NORMAL, never read
+        const normals = new Float32Array(vertexCount * 3);
+        normals.set(normal.getArray());
+        for (let i = positions.length + 2; i < normals.length; i += 3) normals[i] = 1;
+        normal.setArray(normals);
+      }
+    }
+    shared.push({ mesh, surface, pairs, vertexCount });
+  }
+
+  await doc.transform(quantize());
+
+  // The fallback lines: float positions mapped into the frame quantize() left the
+  // mesh in. quantize() folds the mesh's offset and scale into the node holding it
+  // (or a new child node), so a vertex q now draws at after·q where it drew p at
+  // before·p: q = after⁻¹ · before · p, whatever transform the node carried.
+  for (const { mesh, edges, before } of ownVertices) {
+    const m = multiply(invertAffine(meshNode(mesh).getWorldMatrix()), before);
+    const local = new Float32Array(edges.length);
+    for (let i = 0; i < edges.length; i += 3) {
+      const [x, y, z] = [edges[i], edges[i + 1], edges[i + 2]];
+      for (let a = 0; a < 3; a++) local[i + a] = m[a] * x + m[4 + a] * y + m[8 + a] * z + m[12 + a];
+    }
+    mesh.addPrimitive(doc.createPrimitive().setMode(Primitive.Mode.LINES).setAttribute(
+      "POSITION", doc.createAccessor().setType("VEC3").setArray(local).setBuffer(buffer)));
+  }
+
+  for (const { mesh, surface, pairs, vertexCount } of shared) {
+    // quantize() replaced the surface's accessors; the vertex order and count did not change.
+    const position = surface.getAttribute("POSITION");
+    if (position.getCount() !== vertexCount) throw new Error("encodePreviewGlb: quantize() changed a surface's vertex count");
+    mesh.addPrimitive(doc.createPrimitive().setMode(Primitive.Mode.LINES)
+      .setAttribute("POSITION", position)
+      .setIndices(doc.createAccessor().setType("SCALAR")
+        .setArray(vertexCount < 65535 ? new Uint16Array(pairs) : pairs).setBuffer(buffer)));
+  }
+  // meshopt({ level: "medium" })'s last step: compress every buffer view, attributes as quantized.
+  doc.createExtension(EXTMeshoptCompression).setRequired(true)
+    .setEncoderOptions({ method: EXTMeshoptCompression.EncoderMethod.QUANTIZE });
+
   const io = new WebIO()
     .registerExtensions([EXTMeshoptCompression, KHRMeshQuantization])
     .registerDependencies({ "meshopt.encoder": MeshoptEncoder });

package/src/framework/lint/rules-build.js

@@ -1,7 +1,7 @@
 // Group 3 — how the build uses the kernel, discovered by executing build() against
 // the validating probe with no geometry kernel. Every error in this group already
 // throws at runtime; the value is reaching it in microseconds, before a WASM boot.
-import { err, warn } from "./finding.js";
+import { err, note, warn } from "./finding.js";
 import { ROUTED_CAD_OPS } from "../geometry/kernel.js";
 import { MAX_PROBE_OPS } from "../geometry/probe.js";
 
@@ -10,6 +10,19 @@ import { MAX_PROBE_OPS } from "../geometry/probe.js";
 const OCCT_ONLY = new Set(ROUTED_CAD_OPS);
 const unique = (xs) => [...new Set(xs)];
 
+// A throw after the call read a query the probe answers with a placeholder
+// (contains() always false, boundingBox() a unit box, area()/volume() 1, …) proves
+// nothing: the build may only have believed the placeholder — a part that scans
+// contains() to place ribs finds none and throws its own guard, then builds fine on
+// a real kernel. That is a NOTE (seen, never gating load, measure or --strict), the
+// way rules that cannot evaluate something stand down rather than guess. A throw
+// with no such read is the build's own logic and stays an error.
+const STUB_HINT = (queried) =>
+  `Nothing to fix if the part builds on a real kernel. Before throwing, this call read ${queried.join(", ")}, and with no kernel attached those answers are placeholders (Shape2D.contains() is always false, boundingBox() a unit box, area() and volume() 1), so a guard that depends on them can fire here and nowhere else. A genuine fault still surfaces when the real build runs.`;
+const stubbedThrow = (rule, what, message, queried, path) =>
+  note(rule, `${what} threw after reading ${queried.join(", ")}, so it could not be evaluated geometry-free: ${message}`,
+    STUB_HINT(queried), path);
+
 export const BUILD_RULES = [
   {
     id: "derive-throws",
@@ -45,10 +58,11 @@ export const BUILD_RULES = [
   },
   {
     id: "build-throws",
-    run: ({ probe }) => probe().throws.map(({ subpart, message }) =>
-      err("build-throws", `sub-part "${subpart}" threw during a geometry-free build: ${message}`,
+    run: ({ probe }) => probe().throws.map(({ subpart, message, queried }) => (queried.length
+      ? stubbedThrow("build-throws", `sub-part "${subpart}"`, message, queried, `parts.${subpart}.build`)
+      : err("build-throws", `sub-part "${subpart}" threw during a geometry-free build: ${message}`,
         "Fix the error in build(). This was raised with no kernel attached, so it is a fault in the build's own logic (bad arithmetic, a missing param, a null dereference) rather than a geometry failure.",
-        `parts.${subpart}.build`)),
+        `parts.${subpart}.build`))),
   },
   {
     // Same class of fault as build-throws, located at the probe. A throwing

package/src/framework/mount-preview.js

@@ -10,7 +10,8 @@
 // background/environment meta. The CAD look is exact; realistic mode uses each
 // sub-part's display only — no sheet stock, no layer-line print frames (a
 // residual of the format). CAD feature edges come from the file (encoder
-// version 2); a version-1 file decodes with none. The decoder loads on demand (it carries the
+// version 2, sharing the surface's vertices since version 3); a version-1 file
+// decodes with none. The decoder loads on demand (it carries the
 // GLTFLoader and meshopt), so a bundle that never mounts a preview never ships it.
 // Hence `ready`. Every handle method is safe before it resolves.
 import "./app.css";

package/src/framework/process/cnc-router/descriptor.js

@@ -1,4 +1,5 @@
-// CNC routing — process module #2. Flat stock machined from ONE face: through cuts
+// CNC routing — process module #2. Flat stock machined from either face — the near
+// face (z = t, the default) or the far face (z = 0, per op `face: "far"`): through cuts
 // (profile), flat-floored pockets at a depth, drilled holes at a depth, and `extra`
 // operations the operator does with another tool after the flat milling. The
 // drawing is one layered DXF per piece, depth on the layer name and colour.
@@ -12,8 +13,9 @@ import {
 } from "../../sheet/constants.js";
 import { err } from "../../lint/finding.js";
 
-// The preview: the profile extruded to the thickness, each pocket cut `depth` down from
-// the machined face (z = t), each drill as a cylinder from the face to its depth —
+// The preview: the profile extruded to the thickness, each pocket cut `depth` into the
+// stock from its face (down from z = t on the near face, up from z = 0 on the far
+// face), each drill as a cylinder from its face to its depth —
 // through holes and through pockets (depth = thickness) clear BOTH faces by MARK_OVERCUT so no cap is coplanar with a face
 // (OCCT's coplanar booleans are fragile) — each extra solid subtracted as given, and
 // the reference grooves cut like a laser score. A tool whose region turned out empty
@@ -29,10 +31,14 @@ function routedPreview(k, s) {
   const tools = [
     ...pockets.map((pk) => orEmpty(() => (pk.depth >= t
       ? pk.region.extrude({ h: t + 2 * MARK_OVERCUT }).translate([0, 0, -MARK_OVERCUT])
-      : pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, t - pk.depth])))),
+      : pk.face === "far"
+        ? pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, -MARK_OVERCUT])
+        : pk.region.extrude({ h: pk.depth + MARK_OVERCUT }).translate([0, 0, t - pk.depth])))),
     ...drills.map((dr) => (dr.through
       ? k.cylinder({ d: dr.d, h: t + 2 * MARK_OVERCUT }).translate([dr.at[0], dr.at[1], -MARK_OVERCUT])
-      : k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], t - dr.depth]))),
+      : dr.face === "far"
+        ? k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], -MARK_OVERCUT])
+        : k.cylinder({ d: dr.d, h: dr.depth + MARK_OVERCUT }).translate([dr.at[0], dr.at[1], t - dr.depth]))),
     ...extra.map((x) => x.solid),
     ...s.grooves.map((g) => orEmpty(() => g.extrude({ h: MARK_DEPTH + MARK_OVERCUT }).translate([0, 0, t - MARK_DEPTH]))),
   ].filter(Boolean);
@@ -74,21 +80,21 @@ function routedFacts(s) {
   for (const pk of pockets) {
     if (pk.region.isEmpty()) { empty++; continue; }
     const [w, h] = sizeOf(pk.region);
-    pocketRows.push({ label: pk.label, depth: pk.depth, w: round2(w), h: round2(h), area: round2(pk.region.area()) });
+    pocketRows.push({ label: pk.label, depth: pk.depth, w: round2(w), h: round2(h), area: round2(pk.region.area()), face: pk.face });
     noteOutside(pk.region);
   }
-  // Drills grouped by (d, depth, through): one row per tool setting, labels joined.
+  // Drills grouped by (d, depth, through, face): one row per tool setting, labels joined.
   const drillGroups = new Map();
   for (const dr of drills) {
-    const key = `${dr.d}|${dr.depth}|${dr.through}`;
-    const g = drillGroups.get(key) ?? { labels: [], d: dr.d, depth: dr.depth, through: dr.through, count: 0 };
+    const key = `${dr.d}|${dr.depth}|${dr.through}|${dr.face}`;
+    const g = drillGroups.get(key) ?? { labels: [], d: dr.d, depth: dr.depth, through: dr.through, face: dr.face, count: 0 };
     g.count++;
     if (dr.label && !g.labels.includes(dr.label)) g.labels.push(dr.label);
     drillGroups.set(key, g);
     noteOutside(dr.shape);
   }
-  const drillRows = [...drillGroups.values()].map(({ labels, d, depth, through, count }) =>
-    ({ label: labels.length ? labels.join(", ") : null, d, depth, through, count }));
+  const drillRows = [...drillGroups.values()].map(({ labels, d, depth, through, count, face }) =>
+    ({ label: labels.length ? labels.join(", ") : null, d, depth, through, count, face }));
   // An extra op whose footprint resolved to nothing draws nothing: counted under
   // `empty` with the empty pockets, never a row (its size has no bounding box).
   const extraRows = [];
@@ -96,12 +102,25 @@ function routedFacts(s) {
     if (x.footprint.isEmpty()) { empty++; continue; }
     const [w, h] = sizeOf(x.footprint);
     noteOutside(x.footprint);
-    // How deep the op reaches below the machined face (z = t), within the stock. An
-    // empty solid has no bounding box and reaches nothing.
+    // How deep the op reaches into the stock from its face — below z = t on the near
+    // face, above z = 0 on the far face — within the stock. An empty solid has no
+    // bounding box and reaches nothing.
     const bb = x.solid.boundingBox();
-    const bottom = bb?.min?.[2];
-    const reach = Number.isFinite(bottom) ? t - bottom : 0;
-    extraRows.push({ label: x.label, method: x.method, w: round2(w), h: round2(h), maxDepth: round2(Math.max(0, Math.min(t, reach))) });
+    const bound = x.face === "far" ? bb?.max?.[2] : bb?.min?.[2];
+    const reach = Number.isFinite(bound) ? (x.face === "far" ? bound : t - bound) : 0;
+    extraRows.push({ label: x.label, method: x.method, w: round2(w), h: round2(h), maxDepth: round2(Math.max(0, Math.min(t, reach))), face: x.face });
+  }
+
+  // Breakthrough: a near pocket and a far pocket whose regions overlap and whose depths
+  // together exceed the stock — the router breaks through between them. Depths adding
+  // up to exactly the thickness are a deliberate opening and never counted.
+  const live = pockets.filter((pk) => !pk.region.isEmpty());
+  const near = live.filter((pk) => pk.face !== "far"), far = live.filter((pk) => pk.face === "far");
+  let breakthrough = 0;
+  for (const a of near) {
+    for (const b of far) {
+      if (a.depth + b.depth > t + 1e-6 && a.region.intersect(b.region).area() > LOSS_TOL_MM2) breakthrough++;
+    }
   }
 
   return {
@@ -112,7 +131,7 @@ function routedFacts(s) {
     at: { bridge: null, gap: null, marks: null, outside: null },
     readErrors: { bridge: null, gap: null, marks: null, marksArea: null },
     evaluated: true,
-    routed: { profile: { w: round2(flat[0]), h: round2(flat[1]) }, pockets: pocketRows, drills: drillRows, extra: extraRows, outside, empty },
+    routed: { profile: { w: round2(flat[0]), h: round2(flat[1]) }, pockets: pocketRows, drills: drillRows, extra: extraRows, outside, empty, breakthrough },
   };
 }
 
@@ -130,10 +149,13 @@ const METRICS = {
   routedPieces: { kind: "warn", doc: ROUTED_DOC_ID,
     extract: (s) => s.sheet?.pieces ?? null,
     hint: "the profile is not exactly one piece — a routed part must cut out as one region; join the pieces or split them into separate routedPart sub-parts" },
+  routedBreakthrough: { kind: "warn", doc: ROUTED_DOC_ID,
+    extract: (s) => s.sheet?.routed?.breakthrough ?? null,
+    hint: "a pocket on the near face and one on the far face overlap and together go deeper than the stock, so the router breaks through between them — make the overlap a through cut in `profile`, or lower one depth; if the opening is intended, set the two depths to add up to exactly the thickness" },
 };
 
 // ── lint ──────────────────────────────────────────────────────────────────────
-const DRILL_DEPTH_HINT = "A drill's depth is measured from the machined face; a depth at or past the stock thickness is a through hole. Lower the depth, raise the stock thickness control, or set depth to the thickness to drill through.";
+const DRILL_DEPTH_HINT = "A drill's depth is measured from the op's own face (near or far); a depth at or past the stock thickness is a through hole. Lower the depth, raise the stock thickness control, or set depth to the thickness to drill through.";
 const ROUTER_RULES = [{
   id: "routed-drill-depth",
   run: ({ part, p, d, deriveError }) => {
@@ -168,7 +190,7 @@ export const ROUTER = {
   preview: routedPreview,
   destinations: [{ id: "cnc-router", cutFormat: "dxf" }],
   facts: routedFacts,
-  checks: () => ({ routedOutside: "0", routedEmpty: "0", routedPieces: "1" }),
+  checks: () => ({ routedOutside: "0", routedEmpty: "0", routedPieces: "1", routedBreakthrough: "0" }),
   metrics: METRICS,
   lintRules: ROUTER_RULES,
 };