partforge 0.153.0 → 0.155.0

package/docs/AUTHORING-PARTS.md

@@ -4267,11 +4267,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 +4283,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 +4301,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.153.0",
+  "version": "0.155.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/gltf/decode-preview.js

@@ -11,6 +11,16 @@
 // 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
+// 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
+// the same matrix as the positions; a node with no line primitive — version 1,
+// or a sub-part whose edges were empty — decodes to an EMPTY Float32Array,
+// which the viewer reads as "no feature edges" (never undefined, which would
+// make it derive lines by angle).
+//
 // Rejects on anything that is not a decodable GLB; the callers (mount's
 // `preview`, mountPreview) decide what a failure means for them.
 import { Matrix3, Matrix4, Vector3 } from "three";
@@ -50,15 +60,50 @@ function metaOf(extras) {
   return Object.keys(out).length ? out : null;
 }
 
+// The object standing for a glTF node: the object itself when its node had one
+// primitive, else the Group GLTFLoader made for a multi-primitive mesh — the
+// one carrying the node's extras / name (a primitive's own Mesh has neither).
+function nodeObjectOf(obj) {
+  const own = obj.userData ?? {};
+  if ("partforgeSubPart" in own || "name" in own) return obj;
+  const parent = obj.parent;
+  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).
+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;
+  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);
+  return out;
+}
+
 export async function decodePreviewGlb(bytes) {
   const data = toArrayBuffer(bytes);
   const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);
   const gltf = await loader.parseAsync(data, "");
   gltf.scene.updateMatrixWorld(true);
   const meshes = [];
+  const edgesByNode = new Map(); // node object → model-frame segment arrays
+  const meshByNode = new Map(); // node object → its surface payload
   const toModel = new Matrix4();
   const normalMatrix = new Matrix3();
   gltf.scene.traverse((obj) => {
+    if (obj.isLineSegments) {
+      toModel.multiplyMatrices(Y_UP_TO_Z_UP, obj.matrixWorld);
+      const segments = readSegments(obj.geometry, toModel);
+      if (segments) {
+        const node = nodeObjectOf(obj);
+        edgesByNode.set(node, [...(edgesByNode.get(node) ?? []), segments]);
+      }
+      obj.geometry.dispose();
+      return;
+    }
     if (!obj.isMesh) return;
     const geometry = obj.geometry;
     const position = geometry.getAttribute("position");
@@ -67,19 +112,31 @@ export async function decodePreviewGlb(bytes) {
     normalMatrix.getNormalMatrix(toModel);
     const normal = geometry.getAttribute("normal");
     const indices = geometry.index ? Uint32Array.from(geometry.index.array) : null;
-    const { partforgeSubPart, partforgeDisplay, name: originalName } = obj.userData;
-    meshes.push({
+    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 ?? obj.name),
+      name: typeof partforgeSubPart === "string" ? partforgeSubPart : (originalName ?? node.name),
       positions: readVec3(position, toModel, false),
       normals: normal ? readVec3(normal, normalMatrix, true) : null,
       indices,
       triangles: (indices ? indices.length : position.count) / 3,
-      edges: new Float32Array(0), // previews carry no feature edges (v1)
+      edges: new Float32Array(0), // filled below from the node's LINES primitive, if any
       display: partforgeDisplay && typeof partforgeDisplay === "object" ? partforgeDisplay : null,
-    });
+    };
+    meshes.push(payload);
+    if (!meshByNode.has(node)) meshByNode.set(node, payload);
     geometry.dispose();
   });
+  for (const [node, parts] of edgesByNode) {
+    const payload = meshByNode.get(node);
+    if (!payload) continue; // lines with no surface: nothing to draw them on
+    const total = parts.reduce((n, p) => n + p.length, 0);
+    const edges = new Float32Array(total);
+    let at = 0;
+    for (const p of parts) { edges.set(p, at); at += p.length; }
+    payload.edges = edges;
+  }
   const extras = gltf.userData ?? {};
   return {
     view: typeof extras.partforgeView === "string" ? extras.partforgeView : null,

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

@@ -3,8 +3,15 @@
 // buildView all hold) as a small GLB a viewer can show before the kernel boots.
 //
 // The file, which a reader may rely on:
-//  - one node + mesh + primitive per sub-part, all three named by the sub-part
-//    key; POSITION + NORMAL (+ indices when the kernel sent them)
+//  - 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.
 //  - 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.
@@ -14,20 +21,20 @@
 //  - 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 (v1): feature edges, textures, patterns.
+// Not encoded: textures, patterns. (Feature edges since version 2.)
 //
 // 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, WebIO } from "@gltf-transform/core";
+import { Document, Logger, Primitive, WebIO } from "@gltf-transform/core";
 import { EXTMeshoptCompression, KHRMeshQuantization } from "@gltf-transform/extensions";
 import { meshopt, quantize, weld } from "@gltf-transform/functions";
 import { MeshoptEncoder } from "meshoptimizer/encoder";
 import { cadAppearance, DISPLAY_KEYS } from "../materials/resolve.js";
 
-export const PREVIEW_ENCODER_VERSION = 1;
+export const PREVIEW_ENCODER_VERSION = 2; // 2: feature edges as a LINES primitive
 
 // −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];
@@ -72,6 +79,13 @@ function checkMesh(m, seen) {
   if (m.normals != null && m.normals.length > 0 && m.normals.length !== m.positions.length) {
     throw new Error(`encodePreviewGlb: "${m.name}" normals do not match its positions`);
   }
+  // Any zero-length edges (typed or plain) mean "no feature edges": nothing to check.
+  if (m.edges != null && m.edges.length !== 0) {
+    if (!ArrayBuffer.isView(m.edges) && !Array.isArray(m.edges)) {
+      throw new TypeError(`encodePreviewGlb: "${m.name}" edges must be a typed array or an array of numbers`);
+    }
+    if (m.edges.length % 6 !== 0) throw new Error(`encodePreviewGlb: "${m.name}" edges are not whole segments`);
+  }
   if (indexed) {
     const vertexCount = m.positions.length / 3;
     for (let i = 0; i < m.indices.length; i++) {
@@ -126,9 +140,14 @@ export async function encodePreviewGlb({ meshes, part = null, view = null } = {}
       .setMetallicFactor(look.metalness)
       .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)));
+    }
     const extras = displayExtras(display);
     root.addChild(doc.createNode(m.name)
-      .setMesh(doc.createMesh(m.name).addPrimitive(prim))
+      .setMesh(mesh)
       .setExtras(extras ? { partforgeSubPart: m.name, partforgeDisplay: extras } : { partforgeSubPart: m.name }));
   }
   if (root.listChildren().length === 0) throw new Error("encodePreviewGlb: every mesh was empty");

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

@@ -8,8 +8,9 @@
 // built once the GLB has decoded, from a synthetic part: one sub-part per glTF
 // mesh, carrying the `display` block the writer stored beside it, and the file's
 // 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 v1
-// residual alongside "no edges"). The decoder loads on demand (it carries the
+// 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
 // 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/src/framework/viewer.js

@@ -1741,9 +1741,12 @@ export function createViewer(container, part) {
     // draw none rather than falling back. Only a payload with NO edge data at
     // all (edges === undefined; no current backend does this) derives by angle.
     const lg = new LineSegmentsGeometry();
-    if (edges) lg.setPositions(edges); // edges is already a well-formed (possibly zero-length) Float32Array
-    else lg.fromEdgesGeometry(new THREE.EdgesGeometry(out, EDGE_ANGLE));
+    // The raw segment pairs drawn, kept for getSubMeshPayload (reading them back
+    // out of LineSegmentsGeometry's interleaved instance buffer is awkward).
+    const segments = edges ?? new THREE.EdgesGeometry(out, EDGE_ANGLE).getAttribute("position").array;
+    lg.setPositions(segments); // a well-formed (possibly zero-length) Float32Array
     out.userData.edges = lg;
+    out.userData.edgePositions = segments;
     return out;
   }
 
@@ -1790,7 +1793,9 @@ export function createViewer(container, part) {
   // The geometry drawn for one sub-part, as a fresh worker-style payload with its
   // fast-path pose (setSubPose) baked in — the posed mesh a headless buildView
   // would return. Copies: the caller (exportPreview → partforge/gltf) may keep or
-  // transfer them. null when nothing has been delivered under that name.
+  // transfer them. null when nothing has been delivered under that name. Its
+  // `edges` are the lines shown on screen: the kernel's segments, or — when the
+  // delivery carried no edge data at all — the angle-derived fallback lines.
   const _payloadV = new THREE.Vector3();
   const _payloadNormal = new THREE.Matrix3();
   function getSubMeshPayload(name) {
@@ -1811,10 +1816,17 @@ export function createViewer(container, part) {
         _payloadV.fromBufferAttribute(nor, i).applyMatrix3(_payloadNormal).normalize().toArray(normals, i * 3);
       }
     }
+    // Feature edges, posed by the same matrix (an empty array stays empty: "none").
+    const rawEdges = geo.userData.edgePositions ?? new Float32Array(0);
+    const edges = new Float32Array(rawEdges.length);
+    for (let i = 0; i < rawEdges.length; i += 3) {
+      _payloadV.fromArray(rawEdges, i).applyMatrix4(pose).toArray(edges, i);
+    }
     return {
       name,
       positions,
       normals,
+      edges,
       indices: geo.index ? Uint32Array.from(geo.index.array) : null,
       triangles: geo.userData.triangles ?? (geo.index ? geo.index.count : pos.count) / 3,
     };

package/types/gltf.d.ts

@@ -20,7 +20,11 @@ export interface PreviewMesh {
   /** Absent for a non-indexed soup (Manifold); OCCT sends indices. */
   indices?: Uint32Array | null;
   triangles?: number;
-  /** Ignored: feature edges are not encoded in this version. */
+  /**
+   * 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".
+   */
   edges?: Float32Array | null;
 }
 
@@ -33,7 +37,7 @@ export interface EncodePreviewInput {
   view?: string | null;
 }
 
-/** Bumped whenever the encoder writes different bytes for the same input. */
+/** Bumped whenever the encoder writes different bytes for the same input (2: feature edges). */
 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]>;