partforge 0.155.0 → 0.156.0

package/docs/AUTHORING-PARTS.md

@@ -3937,7 +3937,21 @@ shares build's `(k, p, d)` contract — against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
 `probe-throws`, `derive-throws`, `manifold-backend-uses-occt-op`,
 `build-runaway` (errors); `nondeterministic-build` (warning, from diffing two
-probe runs).
+probe runs). The probe has no geometry, so every **query** answers with a
+placeholder — `boundingBox()` a unit box, `area()` and `volume()` 1,
+`Shape2D.contains()` always `false`, `corners()`/`toRegions()` a unit square,
+`isEmpty()` `false`. A `build()` that throws *after* reading one of those may
+only have believed the placeholder — a helper that scans `contains()` to place
+ribs finds none and throws its own guard — so that throw is reported as a
+`build-throws` **note** naming the queries it read ("could not be evaluated
+geometry-free"), never an error: it does not block loading, `measure`, or
+`--strict`. A throw with no query read before it is the build's own logic and
+stays an error. Lint cannot tell which throws depended on the placeholder, so any
+throw after a query is a note; a real fault still surfaces when the real build
+runs. The ops the build would have called after the throw were never run, so lint
+did not check them (unknown ops, option keys, the Manifold pin, determinism). A
+declared probe that throws stays a `probe-throws` error whatever it read — at
+runtime a throwing probe only degrades quietly to `{ error }`.
 
 **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
 `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.155.0",
+  "version": "0.156.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/geometry/probe.js

@@ -42,8 +42,11 @@ export class ProbeRunawayError extends Error {
 }
 
 // Shared proxy construction. `onCall(scope, op, args)` observes every op; queries
-// return realistic dummy values the build may read.
-function makeProbe(onCall) {
+// return realistic dummy values the build may read, and `onQuery(scope, op)` hears
+// each one — every answer in the three query tables below is FABRICATED (a unit
+// box, area 1, contains() always false, …), so a build that read one and then threw
+// may only have believed the placeholder (lint's build-throws reads this).
+function makeProbe(onCall, onQuery = () => {}) {
   const solidQueries = {
     boundingBox: () => ({ min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }),
     volume: () => 1,
@@ -78,6 +81,7 @@ function makeProbe(onCall) {
     toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
     cleanup: () => {},
   };
+  const NOT_DATA = new Set(["cleanup"]); // answers nothing a build could act on
 
   // `ignore` keeps the proxy from masquerading as a thenable/internal/serializable
   // handle: symbols, `then` (so it's never await-unwrapped), `_`-prefixed internals,
@@ -100,7 +104,13 @@ function makeProbe(onCall) {
   const opProxy = (queries, scope, routeFor) => new Proxy({}, {
     get(_t, key) {
       if (ignore(key)) return undefined;
-      if (key in queries) return (...args) => { onCall(scope, key, args); return queries[key](...args); };
+      if (key in queries) {
+        return (...args) => {
+          onCall(scope, key, args);
+          if (!NOT_DATA.has(key)) onQuery(scope, key);
+          return queries[key](...args);
+        };
+      }
       return (...args) => { onCall(scope, key, args); return routeFor(key); };
     },
   });
@@ -135,6 +145,8 @@ export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
   const issues = [];
   const used = new Set();
   const solidUsed = new Set();  // same split as createProbeKernel: non-Shape2D-handle ops
+  const queried = [];           // fabricated data queries read, as "scope.op", first-read order;
+                                // runValidatingProbe empties it before each build/probe call
   let count = 0;
   let solidProxy = null;
   let shape2dProxy = null;
@@ -169,17 +181,23 @@ export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
     calls.push({ scope, op, args: args.map(describe) });
   };
 
-  const { kernel, proxy, shape2d } = makeProbe(onCall);
+  const onQuery = (scope, op) => {
+    const name = `${scope === "shape2d" ? "Shape2D" : scope === "kernel" ? "k" : "Solid"}.${op}()`;
+    if (!queried.includes(name)) queried.push(name);
+  };
+  const { kernel, proxy, shape2d } = makeProbe(onCall, onQuery);
   solidProxy = proxy;
   shape2dProxy = shape2d;
-  return { kernel, calls, issues, used, solidUsed };
+  return { kernel, calls, issues, used, solidUsed, queried };
 }
 
 /**
  * Execute every sub-part's build() — and every declared probe (`part.probes`,
  * same (k, p, d) contract, see oracle/measure.js) — against a validating probe.
  * Never throws: a build error becomes an entry in `throws` (probe entries land
- * in `probeThrows`), a runaway sets `runaway`.
+ * in `probeThrows`), a runaway sets `runaway`. Each entry carries `queried`: the
+ * fabricated data queries THAT call read before it threw (tracked per call, so one
+ * sub-part's reads never excuse another's throw).
  */
 export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {}) {
   const probe = createValidatingProbe({ maxOps });
@@ -187,22 +205,23 @@ export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {})
   const probeThrows = [];
   let runaway = false;
   const run = (fn, onThrow) => {
+    probe.queried.length = 0;
     try {
       fn(probe.kernel, p, d);
     } catch (e) {
       if (e instanceof ProbeRunawayError) { runaway = true; return false; }
-      onThrow(e?.message || String(e));
+      onThrow(e?.message || String(e), [...probe.queried]);
     }
     return true;
   };
   for (const [name, sp] of Object.entries(part?.parts ?? {})) {
     if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
-    if (!run(sp.build, (m) => throws.push({ subpart: name, message: m }))) break;
+    if (!run(sp.build, (m, queried) => throws.push({ subpart: name, message: m, queried }))) break;
   }
   if (!runaway) {
     for (const [name, fn] of Object.entries(part?.probes ?? {})) {
       if (typeof fn !== "function") continue; // invalid-probes already reports this
-      if (!run(fn, (m) => probeThrows.push({ probe: name, message: m }))) break;
+      if (!run(fn, (m, queried) => probeThrows.push({ probe: name, message: m, queried }))) break;
     }
   }
   return { calls: probe.calls, issues: probe.issues, used: probe.used, solidUsed: probe.solidUsed, throws, probeThrows, runaway };

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/types/gltf.d.ts

@@ -23,7 +23,10 @@ export interface PreviewMesh {
   /**
    * Feature-edge segments, endpoint pairs `[x0,y0,z0, x1,y1,z1, …]` in the same posed
    * frame as `positions` (encoder version 2+). Written as a LINES primitive on the
-   * sub-part's mesh. Empty or absent writes none, and decodes as "no feature edges".
+   * sub-part's mesh — since version 3, indices into the surface's own POSITION
+   * accessor (each endpoint snapped to the surface vertex at its position, or
+   * appended past the surface's vertices when it lies on none). Empty or absent
+   * writes none, and decodes as "no feature edges".
    */
   edges?: Float32Array | null;
 }
@@ -37,7 +40,7 @@ export interface EncodePreviewInput {
   view?: string | null;
 }
 
-/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges). */
+/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges; 3: edges as indices into the surface's vertices). */
 export const PREVIEW_ENCODER_VERSION: number;
 
 /** Encode one view's posed meshes as a welded, quantized, meshopt-compressed GLB (Y-up, millimetres). Deterministic. */