partforge 0.23.0 → 0.24.0

package/docs/AUTHORING-PARTS.md

@@ -35,6 +35,33 @@ supplies it via `framework/app.css`, imported by `mount`).
 
 ---
 
+## Before geometry: state the engineering intent
+
+For a decorative or low-consequence part, a short dimensional description may be
+enough. For anything that mates with another object, carries load, or could cause harm
+if it fails, write down the engineering intent **before** writing `build`:
+
+- the coordinate frame, origin, and named datums;
+- the allowed envelope and the interfaces that must align (mating faces, axes, hole
+  patterns, fits, clearances, and tolerances);
+- the manufacturing process and material assumptions;
+- load cases, support regions, intended load paths, and safety factors when structural
+  behavior matters;
+- numbered acceptance claims with units and thresholds; and
+- unresolved assumptions that need the user or an engineer to answer.
+
+This may live in the task/specification, a companion design note, or comments next to
+the part — partforge does not prescribe a blueprint schema yet. Do not silently invent
+missing loads, material properties, tolerances, or safety factors. Ask, or record the
+property as unverified.
+
+Treat user/specification acceptance claims as **higher authority** than agent-authored
+geometry and checks. An agent may add conservative checks, but must not delete a claim
+or loosen its threshold merely to make a failing design pass; changing the contract
+requires explicit approval.
+
+---
+
 ## The `PartDefinition` contract
 
 A part is a default-exported object. Full shape (optional fields marked `?`):
@@ -744,7 +771,9 @@ empty/degenerate results; `holes` is the informative topology number.)
 
 `render` writes one PNG per angle (`iso`, `front`, `top` by default; choose with
 `--views iso,front`, output dir with `--out`) to `render/`. The view defaults to
-the part's first declared view.
+the part's first declared view. Treat renders as complementary evidence, not a ruler:
+use several views for complex parts and the interactive viewer's cutaway for hidden
+interfaces, but rely on `measure` / `verify` for dimensions, contact, and clearance.
 
 The `measure` function is also exported for vitest (boot a Manifold kernel as in
 "Testing a part", then `measure(kernel, part, "<view>")`):
@@ -797,6 +826,12 @@ JSON is pretty-printed across multiple lines) for robust machine parsing. With
 so even if a later `verify` throw crashes the run the file is there — it just
 lacks the `verify` key.
 
+**Fresh-evidence rule.** A passing report is evidence only for the source, parameters,
+view, backend, and framework version that produced it. Any relevant edit makes the old
+result stale. Before reporting a part complete, run `measure` / `verify` again on the
+current source and inspect current renders where visual requirements remain. Do not cite
+a command that ran before the last geometry or expectation change as evidence.
+
 **Part-authored hints.** Any `verify.expect` metric accepts `{ expr, hint }` in
 place of a bare expression — use it to name the governing parameter:
 
@@ -813,8 +848,8 @@ verify: {
 ## Self-verification (the `verify` block)
 
 A part can declare how it should be checked, co-located with its schema, so
-`partforge measure` (and vitest) can prove it is both **printable** and **correct**.
-Add an optional top-level `verify` block:
+`partforge measure` (and vitest) can enforce selected **geometric**, **assembly**, and
+**DFM** properties. Add an optional top-level `verify` block:
 
 ```js
 verify: {
@@ -833,13 +868,32 @@ verify: {
 **What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`)
 and a **min-wall** warning. **What `expect` gives you:** per-sub-part assertions on the
 facts `measure` already reports — `holes` (through-bores / genus), `volume`,
-`surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`; and `_view` assertions
-`bbox`, `volume`, `overlaps`, plus the pair-wise `contacts` / `clearance` below.
+`surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`, `bounds` (per-sub-part
+and aggregate 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
+centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
+`volume`, `overlaps`, `centerOfMass`, `boundsMin`, `boundsMax`, plus the pair-wise
+`contacts` / `clearance` below.
+
+Passing these checks does **not** prove structural strength, fatigue life, stability,
+manufacturing tolerance stack-up, regulatory compliance, or safe real-world use.
+Load-bearing or safety-relevant parts need appropriate analytical/simulation evidence
+(for example FEA with declared materials, loads, supports, and safety factors) plus
+qualified human review. If no such evidence exists, say that physical performance is
+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`, a componentwise vector `"<=[x,y,z]"` / `">=[x,y,z]"` where `*` skips an axis.
-The parser is strict — a malformed assertion fails loudly.
+`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.
+
+```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
+} }
+```
 
 **Gates vs. warnings:** exact facts are **gates** (a failure sets a non-zero exit code);
 `minWall` is computed (a ray/shot wall-thickness measurement) and reported as a
@@ -915,6 +969,12 @@ Checks run across the **default config plus every preset** (or your `cases` list
 preset that changes only parameters no on-screen sub-part reads is deduplicated, so
 coverage is cheap.
 
+When an agent authors both geometry and `verify`, the check is useful feedback but not
+an independent oracle. Preserve externally supplied acceptance claims verbatim (ideally
+with stable IDs in the surrounding specification), and test boundary/tolerance cases in
+addition to friendly defaults and presets. A repair should change the design, not relax
+the requirement that exposed the failure.
+
 ---
 
 ## Fillet & chamfer (automatic OCCT backend)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.23.0",
+  "version": "0.24.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/testing/measure.js

@@ -1,7 +1,7 @@
 import { buildView } from "./build.js";
 import { assemblyOverlaps } from "../framework/assembly.js";
 import { meshGaps, pairKey, CONTACT_EPS, GAP_THRESHOLD } from "./gaps.js";
-import { bounds, meshArea } from "./mesh.js";
+import { bounds, meshArea, meshCentroid } from "./mesh.js";
 import { minWall } from "./min-wall.js";
 
 const size = ({ min, max }) => [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
@@ -26,6 +26,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     return {
       name,
       bbox: size(b),
+      bounds: { min: b.min, max: b.max },
+      centerOfMass: meshCentroid(mesh.positions, mesh.indices),
       volume: solid.volume(),
       surfaceArea: meshArea(mesh.positions, mesh.indices),
       triangleCount: mesh.triangles,
@@ -54,8 +56,16 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     (g) => g.distance > CONTACT_EPS && g.distance < gapThreshold && !overlapping.has(pairKey(g.a, g.b)),
   );
 
+  const ub = subparts.length ? unionBounds(subBounds) : { min: [0, 0, 0], max: [0, 0, 0] };
+  const weighted = subparts.filter((s) => s.centerOfMass !== null);
+  const totalVol = weighted.reduce((a, s) => a + s.volume, 0);
+  const aggCom = weighted.length && Math.abs(totalVol) > 1e-9
+    ? [0, 1, 2].map((i) => weighted.reduce((a, s) => a + s.volume * s.centerOfMass[i], 0) / totalVol)
+    : null;
   const aggregate = {
-    bbox: subparts.length ? size(unionBounds(subBounds)) : [0, 0, 0],
+    bbox: size(ub),
+    bounds: { min: ub.min, max: ub.max },
+    centerOfMass: aggCom,
     volume: subparts.reduce((a, s) => a + s.volume, 0),
     surfaceArea: subparts.reduce((a, s) => a + s.surfaceArea, 0),
     triangleCount: subparts.reduce((a, s) => a + s.triangleCount, 0),

package/src/testing/mesh.js

@@ -12,6 +12,31 @@ export function meshVolume(positions, indices) {
   }
   return Math.abs(V);
 }
+// Volume-weighted centroid (uniform-density center of mass) of a triangle mesh,
+// via the same signed-tetrahedron decomposition as meshVolume. `indices` is
+// optional: omit for a flat soup (3 verts/triangle). Returns [x,y,z], or null when
+// the mesh encloses ~no volume (open/degenerate), where a centroid is undefined.
+// Signed V (not abs) is used so the winding sign cancels in C/V.
+export function meshCentroid(positions, indices) {
+  const n = indices ? indices.length : positions.length / 3;
+  let V = 0, cx = 0, cy = 0, cz = 0;
+  for (let i = 0; i < n; i += 3) {
+    const a = (indices ? indices[i] : i) * 3, b = (indices ? indices[i + 1] : i + 1) * 3, c = (indices ? indices[i + 2] : i + 2) * 3;
+    const ax = positions[a], ay = positions[a + 1], az = positions[a + 2];
+    const bx = positions[b], by = positions[b + 1], bz = positions[b + 2];
+    const dx = positions[c], dy = positions[c + 1], dz = positions[c + 2];
+    // signed volume of tetra (origin, a, b, c) = a · (b × c) / 6
+    const v = (ax * (by * dz - bz * dy) - ay * (bx * dz - bz * dx) + az * (bx * dy - by * dx)) / 6;
+    V += v;
+    // tetra centroid = (0 + a + b + c) / 4, weighted by its signed volume
+    cx += v * (ax + bx + dx) / 4;
+    cy += v * (ay + by + dy) / 4;
+    cz += v * (az + bz + dz) / 4;
+  }
+  if (Math.abs(V) < 1e-9) return null;
+  return [cx / V, cy / V, cz / V];
+}
+
 export function bboxSize(positions) {
   const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
   for (let i = 0; i < positions.length; i += 3) for (let a = 0; a < 3; a++) {

package/src/testing/verify.js

@@ -25,6 +25,12 @@ export const SUBPART_METRICS = {
     hint: "triangle count is out of range — tessellation quality or feature count changed unexpectedly" },
   bbox: { kind: "gate", 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,
+    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" },
   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",
@@ -38,6 +44,12 @@ export const VIEW_METRICS = {
   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,
+    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" },
 };
 
 // An expectation is a bare expression (string/number/boolean) or { expr, hint }.