partforge 0.154.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`,
@@ -4267,11 +4281,11 @@ are skipped. Switch it off under an FDM profile with an inline
 `{ base: "fdm-pla", overhang: null }`. **What `expect` gives you:** per-sub-part
 assertions on the facts `measure` already reports — `holes` (through-bores / genus),
 `volume`, `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`,
-`overhangArea`, `wall` (a range — see below), `boundsMin` / `boundsMax`
-(the axis-aligned `{min,max}` corner positions — where the geometry sits, vs
-`bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
+`overhangArea`, `wall` (a range — see below), `bounds` (the axis-aligned corner
+positions, written in the same `{ min, max }` shape `measure` reports them — where
+the geometry sits, vs `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
 centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
-`volume`, `overlaps`, `centerOfMass`, `boundsMin`, `boundsMax`, plus the pair-wise
+`volume`, `overlaps`, `centerOfMass`, `bounds`, plus the pair-wise
 `contacts` / `clearance` below.
 
 Passing these checks does **not** prove structural strength, fatigue life, stability,
@@ -4283,9 +4297,13 @@ unverified.
 
 **Assertion DSL:** a bare number means equality (`holes: 1`); `">=n"`, `"<=n"`, `">n"`,
 `"<n"`, or a range `"a..b"`; an optional unit suffix `mm`/`cm`/`mm3`/`cm3`; and for
-`bbox`, `centerOfMass`, `boundsMin`, `boundsMax`, a componentwise vector `"<=[x,y,z]"` /
-`">=[x,y,z]"` where `*` skips an axis. The parser is strict — a malformed assertion
-fails loudly.
+`bbox`, `centerOfMass` and each side of `bounds`, a componentwise vector `"<=[x,y,z]"` /
+`">=[x,y,z]"` — exactly 3 components, each a plain number in mm or `*` to skip an axis.
+A vector is always one-sided: a bare `[40,40,10]` (meaning "exactly this size") is
+rejected, since a mesh's box shifts with tessellation and no tolerance would be honest
+for every part — pick `<=` for a limit or `>=` for a floor. `bounds` takes an object
+with `min` and/or `max`, each such a vector: `bounds: { min: ">=[0,0,0]", max:
+"<=[220,220,250]" }`. The parser is strict — a malformed assertion fails loudly.
 
 **A part whose typeface is a parameter needs band assertions, not points.** Glyph
 advance widths differ by family, so a `text2d` sub-part's `bbox`/`volume` shifts with
@@ -4297,8 +4315,8 @@ need this, but a part whose default already names a specific face does.
 
 ```js
 verify: { expect: {
-  stand: { boundsMin: ">=[0,0,0]", centerOfMass: "<=[*,*,25]" },   // sits in +octant, mass kept low
-  _view: { boundsMax: "<=[220,220,250]" },                          // whole assembly fits the bed
+  stand: { bounds: { min: ">=[0,0,0]" }, centerOfMass: "<=[*,*,25]" },   // sits in +octant, mass kept low
+  _view: { bounds: { max: "<=[220,220,250]" } },                          // whole assembly fits the bed
 } }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.154.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/lint/rules-verify.js

@@ -3,9 +3,9 @@
 // which is also the documented reason CLI stdout isn't pure JSON in that case.
 // Catching them statically removes both the wasted boot and the stdout caveat.
 import { err } from "./finding.js";
-import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
+import { SUBPART_METRICS, VIEW_METRICS, BOUNDS_FORM, teachableMetrics, sidesSpecError } from "../verify-metrics.js";
 import { PROFILES, ORIENTATIONS } from "../oracle/dfm-profiles.js";
-import { parseAssertion } from "../oracle/assert-dsl.js";
+import { parseAssertion, bareVectorHint } from "../oracle/assert-dsl.js";
 import { suggest } from "../geometry/op-options.js";
 import { PROCESS_IDS } from "../process/registry.js";
 import { SHEET_DOC_ID } from "../sheet/constants.js";
@@ -187,6 +187,46 @@ function checkProcessSpec(spec, path, valid, seen, depth = 0) {
     path)];
 }
 
+// One expectation's well-formedness against its registry entry: it parses, and it has the form the
+// metric reads — a range for `wall`, a componentwise vector for bbox/centerOfMass/the
+// sides of bounds. A bare vector gets the two legal spellings back, in its own numbers.
+const DSL_HINT = "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).";
+const capitalize = (t) => t.charAt(0).toUpperCase() + t.slice(1);
+
+function checkExpr(target, metric, spec, reg) {
+  const path = `verify.expect.${target}.${metric}`;
+  const expr = exprOf(spec);
+  let parsed;
+  try { parsed = parseAssertion(expr); }
+  catch (e) {
+    const bare = bareVectorHint(expr);
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} is not a valid assertion: ${e?.message || String(e)}`,
+      bare ? `${capitalize(bare)}. A vector expectation is one-sided: "<=" for a limit, ">=" for a floor.` : DSL_HINT,
+      path)];
+  }
+  const form = reg?.form;
+  if (form === "range" && parsed.op !== "range") {
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} must be a range like "1.8..2.2" — the ${metric} metric needs both ends of its band`,
+      `Write ${metric} as \`"<min>..<max>"\` in mm.`,
+      path)];
+  }
+  if (form === "range" && parsed.min > parsed.max) {
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} must be a range with min <= max, got "${expr}"`,
+      `Write ${metric} as \`"<min>..<max>"\` with min <= max, in mm.`,
+      path)];
+  }
+  if (form === "vector" && parsed.op !== "vle" && parsed.op !== "vge") {
+    return [err("verify-bad-expr",
+      `the expectation for ${target}.${metric} must be a componentwise vector, got ${describe(expr)} — ${metric} is an [x,y,z] reading`,
+      `Write ${metric} as \`"<=[x,y,z]"\` or \`">=[x,y,z]"\` (componentwise; * skips an axis).`,
+      path)];
+  }
+  return [];
+}
+
 export const VERIFY_RULES = [
   {
     id: "verify-expect-throws",
@@ -229,9 +269,12 @@ export const VERIFY_RULES = [
         // separately by verify-bad-pair-check, and excluded here.
         const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
         const registry = target === "_view" ? VIEW_METRICS : SUBPART_METRICS;
-        const valid = Object.keys(registry);
+        // Legacy spellings (boundsMin/boundsMax) still pass this rule, since verify
+        // still evaluates them, but are never listed or suggested: the vocabulary a
+        // reader is shown is the one the docs teach.
+        const valid = teachableMetrics(registry);
         for (const metric of Object.keys(metrics)) {
-          if (valid.includes(metric)) continue;
+          if (Object.hasOwn(registry, metric)) continue;
           const hint = suggest(metric, valid);
           out.push(err("verify-unknown-metric",
             `"${metric}" is not a ${target === "_view" ? "view" : "sub-part"} metric`,
@@ -256,28 +299,28 @@ export const VERIFY_RULES = [
         // though, so they get their own pass (with a pair-shaped path) below.
         const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
         const registry = target === "_view" ? VIEW_METRICS : SUBPART_METRICS;
-        for (const [metric, spec] of Object.entries(metrics)) {
-          let parsed;
-          try { parsed = parseAssertion(exprOf(spec)); }
-          catch (e) {
-            out.push(err("verify-bad-expr",
-              `the expectation for ${target}.${metric} is not a valid assertion: ${e?.message || String(e)}`,
-              "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
-              `verify.expect.${target}.${metric}`));
+        for (const [metric, specRaw] of Object.entries(metrics)) {
+          // A compound metric (`bounds: { min, max }`) is checked side by side, each
+          // side an ordinary expectation against its own registry entry.
+          // An unknown metric is verify-unknown-metric's finding; parsing its value
+          // too would only add a second, vaguer error for the same key.
+          if (!Object.hasOwn(registry, metric)) continue;
+          const reg = registry[metric];
+          if (reg.sides) {
+            const bad = sidesSpecError(metric, reg, specRaw);
+            if (bad) {
+              out.push(err("verify-bad-expr",
+                `the expectation for ${target}.${metric} is malformed: ${bad}`,
+                `Write \`${BOUNDS_FORM}\` — the same { min, max } shape measure reports. Either side may be left out, and \`*\` skips an axis.`,
+                `verify.expect.${target}.${metric}`));
+              continue;
+            }
+            for (const [side, sideSpec] of Object.entries(specRaw)) {
+              out.push(...checkExpr(target, `${metric}.${side}`, sideSpec, reg.sides[side]));
+            }
             continue;
           }
-          const form = registry[metric]?.form;
-          if (form === "range" && parsed.op !== "range") {
-            out.push(err("verify-bad-expr",
-              `the expectation for ${target}.${metric} must be a range like "1.8..2.2" — the ${metric} metric needs both ends of its band`,
-              `Write ${metric} as \`"<min>..<max>"\` in mm.`,
-              `verify.expect.${target}.${metric}`));
-          } else if (form === "range" && parsed.op === "range" && parsed.min > parsed.max) {
-            out.push(err("verify-bad-expr",
-              `the expectation for ${target}.${metric} must be a range with min <= max, got "${exprOf(spec)}"`,
-              `Write ${metric} as \`"<min>..<max>"\` with min <= max, in mm.`,
-              `verify.expect.${target}.${metric}`));
-          }
+          out.push(...checkExpr(target, metric, specRaw, reg));
         }
       }
       out.push(...checkClearanceExprs(expect?._view?.clearance, "verify.expect._view.clearance"));

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/oracle/assert-dsl.js

@@ -19,15 +19,47 @@ const reScalar = new RegExp(`^(>=|<=|>|<)?\\s*(${NUM})\\s*${U}$`);
 const reRange = new RegExp(`^(${NUM})\\s*\\.\\.\\s*(${NUM})\\s*${U}$`);
 const reVec = /^(>=|<=)\s*\[\s*(.+?)\s*\]$/;
 
+// A vector with no comparison — `[40,40,10]` or `"[40,40,10]"` (or `"=[…]"`) — is the
+// commonest slip: the writer means "exactly this size". A vector is only ever
+// one-sided, so the error hands back both legal spellings built from the writer's
+// own numbers, which is a one-step fix. Returns that hint, or null when `expr` is
+// not a bare vector. An exact vector is deliberately not offered: a mesh's box is
+// tessellation-dependent (a curved face chords inside its true extent), so no
+// tolerance would be honest for every part.
+const reBareVec = /^(?:==?)?\s*\[(.*)\]$/;
+const VEC_TAIL = "(componentwise; * skips an axis)";
+
+export function bareVectorHint(expr) {
+  let comps;
+  if (Array.isArray(expr)) comps = expr.map((c) => String(c).trim());
+  else if (typeof expr === "string") {
+    const m = expr.trim().match(reBareVec);
+    if (!m) return null;
+    comps = m[1].split(",").map((t) => t.trim());
+  } else return null;
+  comps = comps.map((c) => c.replace(/\s*mm$/, ""));
+  const ok = comps.length === 3 && comps.every((c) => c === "*" || (c !== "" && Number.isFinite(Number(c))));
+  if (!ok) return `use "<=[x,y,z]" or ">=[x,y,z]" (exactly 3 plain numbers in mm; componentwise; * skips an axis)`;
+  const v = `[${comps.join(",")}]`;
+  return `use "<=${v}" or ">=${v}" ${VEC_TAIL}`;
+}
+
+const show = (expr) => (typeof expr === "string" ? `"${expr}"` : JSON.stringify(expr));
+
 export function parseAssertion(expr) {
   if (typeof expr === "number" || typeof expr === "boolean") return { op: "eq", value: expr };
+  const bare = bareVectorHint(expr);
+  if (bare) throw new Error(`assertion: a vector needs a comparison, got ${show(expr)} — ${bare}`);
   if (typeof expr !== "string") throw new Error(`assertion: unsupported value ${JSON.stringify(expr)}`);
   const s = expr.trim();
 
   const vec = s.match(reVec);
   if (vec) {
     const parts = vec[2].split(",").map((t) => t.trim());
-    if (parts.length !== 3) throw new Error(`assertion: vector needs 3 components: "${expr}"`);
+    const plain = (t) => t === "*" || (t !== "" && Number.isFinite(Number(t)));
+    if (parts.length !== 3 || !parts.every(plain)) {
+      throw new Error(`assertion: a vector takes exactly 3 components, each a plain number in mm or *: "${expr}"`);
+    }
     return { op: vec[1] === "<=" ? "vle" : "vge", vec: parts.map((t) => (t === "*" ? null : toBase(t, undefined))) };
   }
   const range = s.match(reRange);

package/src/framework/oracle/verify.js

@@ -4,7 +4,7 @@ import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile, overhangAngleFor } from "./dfm-profiles.js";
 import { expandExpectations, partGatesMinWall } from "./gates.js";
 import { relevanceHash } from "../param-deps.js";
-import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
+import { SUBPART_METRICS, VIEW_METRICS, sidesSpecError } from "../verify-metrics.js";
 import { processById } from "../process/registry.js";
 import { SHEET_DOC_ID, SHEET_CHECKS_NOTICE, SHEET_READ_ERROR_HINT } from "../sheet/constants.js";
 // Re-exported for the callers that read them from here; their one home is sheet/constants.js.
@@ -173,6 +173,21 @@ function check(scope, subpart, metric, spec, registry, factsObj) {
   return out;
 }
 
+// Every check one declared metric yields: one, or one per side of a compound metric
+// (`bounds: { min, max }` → `bounds.min`, `bounds.max`), each judged by `check()` against
+// its side's own registry entry. A malformed compound value throws, as a malformed
+// expression does.
+function checksFor(scope, subpart, metric, spec, registry, factsObj) {
+  const reg = registry[metric];
+  if (!reg?.sides) return [check(scope, subpart, metric, spec, registry, factsObj)];
+  const bad = sidesSpecError(metric, reg, spec);
+  if (bad) throw new Error(`${scope === "view" ? "_view" : subpart}: ${bad}`);
+  return Object.entries(spec).map(([side, sideSpec]) => {
+    const name = `${metric}.${side}`;
+    return check(scope, subpart, name, sideSpec, { [name]: reg.sides[side] }, factsObj);
+  });
+}
+
 // ── sheet parts ──────────────────────────────────────────────────────────────
 // A view holding a sheet part (sheetPart(), partforge/geometry — measure() stamps
 // its row with `sheet`) is judged per part: the process profile's bed fits each
@@ -220,8 +235,7 @@ function sheetRowChecks(s, declaredExp) {
   const budgeted = (metric) => SUBPART_METRICS[metric]?.budgeted === true;
   const unread = (c, metric) => (c.actual == null ? SUBPART_METRICS[metric]?.readError?.(s) ?? null : null);
   const readFailure = (c, why) => ({ ...c, message: `not measured — ${why}`, hint: SHEET_READ_ERROR_HINT, pattern: SHEET_DOC_ID });
-  for (const [metric, expr] of Object.entries(declaredExp)) {
-    const c = check("subpart", s.name, metric, expr, SUBPART_METRICS, s);
+  for (const [metric, expr] of Object.entries(declaredExp)) for (const c of checksFor("subpart", s.name, metric, expr, SUBPART_METRICS, s)) {
     if (PRINT_ONLY.has(metric)) {
       out.push({ scope: c.scope, subpart: c.subpart, metric, kind: c.kind, expr: c.expr, actual: null, status: "skip", pass: null,
         message: "not measured on a sheet part", hint: PRINT_ONLY_HINT, pattern: SHEET_DOC_ID });
@@ -269,7 +283,7 @@ export function evaluateCase(facts, { profile, expect, subPartNames, overhang =
     ...(profile?.bed && !anySheet ? { bbox: `<=[${profile.bed.join(",")}]` } : {}),
     ...viewScalarExp,
   };
-  for (const [metric, expr] of Object.entries(viewExp)) checks.push(check("view", null, metric, expr, VIEW_METRICS, facts));
+  for (const [metric, expr] of Object.entries(viewExp)) checks.push(...checksFor("view", null, metric, expr, VIEW_METRICS, facts));
   checks.push(...pairGapChecks(facts, { contacts, clearance }, subPartNames));
 
   // Same rule as gapsSkipped above, one metric over: a min-wall gate with no reading
@@ -297,8 +311,7 @@ export function evaluateCase(facts, { profile, expect, subPartNames, overhang =
       ...(overhang != null ? { overhangArea: "<=1" } : {}),
       ...(expect?.[s.name] ?? {}),
     };
-    for (const [metric, expr] of Object.entries(merged)) {
-      const c = check("subpart", s.name, metric, expr, SUBPART_METRICS, s);
+    for (const [metric, expr] of Object.entries(merged)) for (const c of checksFor("subpart", s.name, metric, expr, SUBPART_METRICS, s)) {
       if (minWallSkipped && (metric === "minWall" || metric === "wall") && c.actual == null) {
         checks.push({ ...c, unevaluated: true, message: "not measured (quick check)",
           hint: `re-run this check without \`quick\` to measure ${metric === "wall" ? "the wall band" : "min wall"}` });

package/src/framework/verify-metrics.js

@@ -15,6 +15,54 @@
 // sheet/constants.js, lint/finding.js) — so the linter's stays kernel-free.
 import { SHEET_METRICS } from "./process/registry.js";
 
+// `bounds` is written the way measure() reports it — `bounds: { min: [x,y,z], max:
+// [x,y,z] }` — so a reader who copies the shape of a measurement gets a legal
+// expectation: `bounds: { min: ">=[0,0,0]", max: "<=[220,220,250]" }`. It is the one
+// COMPOUND metric: its value is an object of `sides`, each an ordinary vector
+// expectation checked on its own and reported as `bounds.min` / `bounds.max`. Either
+// side may be left out; nothing else may sit under it (boundsSpecError).
+export const BOUNDS_FORM = 'bounds: { min: ">=[x,y,z]", max: "<=[x,y,z]" }';
+const BOUNDS_HINT = `write ${BOUNDS_FORM} — either side may be left out, and * skips an axis`;
+
+function boundsMetric(bounds, minHint, maxHint) {
+  return { kind: "gate", hint: BOUNDS_HINT, sides: {
+    min: { kind: "gate", form: "vector", extract: (f) => bounds(f)?.min, hint: minHint },
+    max: { kind: "gate", form: "vector", extract: (f) => bounds(f)?.max, hint: maxHint },
+  } };
+}
+
+// The flat spellings `bounds` replaced. Still evaluated, so a part written against
+// them keeps verifying, but `legacy` keeps them out of everything that TEACHES the
+// vocabulary: lint's list of valid metrics and its did-you-mean (teachableMetrics).
+function legacyBounds(bounds, minHint, maxHint) {
+  return {
+    boundsMin: { kind: "gate", form: "vector", legacy: "bounds", extract: (f) => bounds(f)?.min, hint: minHint },
+    boundsMax: { kind: "gate", form: "vector", legacy: "bounds", extract: (f) => bounds(f)?.max, hint: maxHint },
+  };
+}
+
+// The metric names a reader should be shown: every registry key but the legacy ones.
+export const teachableMetrics = (registry) => Object.keys(registry).filter((k) => !registry[k].legacy);
+
+// Why a compound metric's value is malformed, or null when it is well formed. verify
+// throws with it and lint reports it, so both say the same thing.
+export function sidesSpecError(metric, reg, spec) {
+  const sides = Object.keys(reg.sides);
+  const form = metric === "bounds" ? BOUNDS_FORM : `${metric}: { ${sides.join(", ")} }`;
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
+    let shown;
+    try { shown = JSON.stringify(spec); } catch { shown = String(spec); }
+    return `${metric} takes an object { ${sides.join(", ")} }, got ${shown} — write ${form}`;
+  }
+  const keys = Object.keys(spec);
+  const unknown = keys.filter((k) => !sides.includes(k));
+  if (unknown.length) {
+    return `${metric} accepts only ${sides.map((k) => `"${k}"`).join(" and ")}, got ${unknown.map((k) => `"${k}"`).join(", ")} — write ${form}`;
+  }
+  if (!keys.length) return `${metric} needs at least one of ${sides.join(" or ")} — write ${form}`;
+  return null;
+}
+
 export const SUBPART_METRICS = {
   holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes,
     hint: "genus is wrong — an unintended tunnel exists or an intended bore is blocked; make cut tools pierce fully (overcut past the faces)" },
@@ -27,14 +75,16 @@ export const SUBPART_METRICS = {
     hint: "surface area is out of range — detail features (facets, ribs, textures) are missing or doubled" },
   triangleCount: { kind: "gate", extract: (s) => s.triangleCount,
     hint: "triangle count is out of range — tessellation quality or feature count changed unexpectedly" },
-  bbox: { kind: "gate", extract: (s) => s.bbox,
+  bbox: { kind: "gate", form: "vector", extract: (s) => s.bbox,
     hint: "bounding box is out of range — check the governing dimensions and the part's orientation" },
-  centerOfMass: { kind: "gate", extract: (s) => s.centerOfMass,
+  centerOfMass: { kind: "gate", form: "vector", extract: (s) => s.centerOfMass,
     hint: "center of mass is outside the expected region — mass is distributed differently than intended; check feature placement or a mis-scaled sub-part" },
-  boundsMin: { kind: "gate", extract: (s) => s.bounds?.min,
-    hint: "the low corner is out of range — the part is positioned or oriented differently than expected" },
-  boundsMax: { kind: "gate", extract: (s) => s.bounds?.max,
-    hint: "the high corner is out of range — the part is positioned or oriented differently than expected" },
+  bounds: boundsMetric((s) => s.bounds,
+    "the low corner is out of range — the part is positioned or oriented differently than expected",
+    "the high corner is out of range — the part is positioned or oriented differently than expected"),
+  ...legacyBounds((s) => s.bounds,
+    "the low corner is out of range — the part is positioned or oriented differently than expected",
+    "the high corner is out of range — the part is positioned or oriented differently than expected"),
   minWall: { kind: "warn", extract: (s) => s.minWall,
     hint: "thinnest wall is at the reported location — increase the governing wall/thickness parameter or reduce the intersecting feature's depth",
     pattern: "minwall-sliver-triangles",
@@ -87,17 +137,19 @@ export const SUBPART_METRICS = {
   ...SHEET_METRICS,
 };
 export const VIEW_METRICS = {
-  bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,
+  bbox: { kind: "gate", form: "vector", extract: (r) => r.aggregate.bbox,
     hint: "the assembled view exceeds its size limit — shrink the assembly or pick a process with a larger bed" },
   volume: { kind: "gate", extract: (r) => r.aggregate.volume,
     hint: "total assembly volume is out of range — a sub-part is missing, doubled, or mis-scaled" },
   overlaps: { kind: "gate", extract: (r) => r.overlaps.length,
     hint: "sub-parts interpenetrate near the reported location — adjust placement or add clearance in derive()",
     locate: (r) => r.overlaps[0]?.location ?? null },
-  centerOfMass: { kind: "gate", extract: (r) => r.aggregate.centerOfMass,
+  centerOfMass: { kind: "gate", form: "vector", extract: (r) => r.aggregate.centerOfMass,
     hint: "the assembly's center of mass is outside the expected region — a sub-part is mis-placed or mis-scaled" },
-  boundsMin: { kind: "gate", extract: (r) => r.aggregate.bounds?.min,
-    hint: "the assembly's low corner is out of range — check placement or orientation" },
-  boundsMax: { kind: "gate", extract: (r) => r.aggregate.bounds?.max,
-    hint: "the assembly's high corner is out of range — check placement or orientation" },
+  bounds: boundsMetric((r) => r.aggregate.bounds,
+    "the assembly's low corner is out of range — check placement or orientation",
+    "the assembly's high corner is out of range — check placement or orientation"),
+  ...legacyBounds((r) => r.aggregate.bounds,
+    "the assembly's low corner is out of range — check placement or orientation",
+    "the assembly's high corner is out of range — check placement or orientation"),
 };

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. */

package/types/part.d.ts

@@ -506,6 +506,16 @@ export type AssertionExpr = number | string | boolean;
 /** An expectation, optionally carrying a part-authored corrective `hint`. */
 export type Expectation = AssertionExpr | { expr: AssertionExpr; hint?: string };
 
+/**
+ * `bounds`: where the geometry sits, written in the same `{ min, max }` shape
+ * `measure` reports — `{ min: ">=[0,0,0]", max: "<=[220,220,250]" }`. Each side is
+ * a componentwise vector expectation (`*` skips an axis); either may be left out.
+ */
+export interface BoundsExpectation {
+  min?: Expectation;
+  max?: Expectation;
+}
+
 /**
  * Per-sub-part expectations. The keys are exactly `SUBPART_METRICS` in
  * src/framework/verify-metrics.js. `holes`/`watertight` are Manifold-only and
@@ -519,7 +529,11 @@ export interface SubPartExpectations {
   triangleCount?: Expectation;
   bbox?: Expectation;
   centerOfMass?: Expectation;
+  /** The axis-aligned corners: `{ min: ">=[x,y,z]", max: "<=[x,y,z]" }`, as `measure` reports `bounds`. */
+  bounds?: BoundsExpectation;
+  /** @deprecated Write `bounds: { min }` — still evaluated, no longer taught. */
   boundsMin?: Expectation;
+  /** @deprecated Write `bounds: { max }` — still evaluated, no longer taught. */
   boundsMax?: Expectation;
   minWall?: Expectation;
   /**
@@ -574,7 +588,11 @@ export interface ViewExpectations {
   volume?: Expectation;
   overlaps?: Expectation;
   centerOfMass?: Expectation;
+  /** The axis-aligned corners: `{ min: ">=[x,y,z]", max: "<=[x,y,z]" }`, as `measure` reports `bounds`. */
+  bounds?: BoundsExpectation;
+  /** @deprecated Write `bounds: { min }` — still evaluated, no longer taught. */
   boundsMin?: Expectation;
+  /** @deprecated Write `bounds: { max }` — still evaluated, no longer taught. */
   boundsMax?: Expectation;
   /** Pairs that must touch, as `[["a", "b"], …]`. */
   contacts?: Array<[string, string]>;