partforge 0.23.0 → 0.25.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.25.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/viewer-lighting.js

@@ -1,13 +1,66 @@
 import * as THREE from "three";
 
+const KEY_COLOR = 0xffffff, KEY_INTENSITY = 1.45;
+const FILL_COLOR = 0xe5efff, FILL_INTENSITY = 0.65;
+
 export function addViewerLights(scene) {
   const hemisphere = new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
-  const key = new THREE.DirectionalLight(0xffffff, 1.45);
+  const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
   key.position.set(8, 14, 10);
-  const fill = new THREE.DirectionalLight(0xe5efff, 0.65);
+  const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);
   fill.position.set(-10, 6, -8);
 
   scene.add(hemisphere, key, fill);
 
   return { hemisphere, key, fill };
 }
+
+// The key/fill above are fixed in WORLD space, which is right for a user who orbits
+// into the lit hemisphere and wrong for an offscreen canonical-view capture: `bottom`,
+// `back`, and `left` stare at faces the key at (8,14,10) never reaches, so they come
+// back flat — hemisphere ambient only, with no shading gradient to reveal a chamfer or
+// a 1 mm snap barb. These two lights are the capture-time stand-ins, swapped in for the
+// duration of one offscreen render (see viewer.js renderOffscreen) and posed relative to
+// the view axis, so every canonical view is exposed and shaded the same way.
+export function createCaptureLights() {
+  const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
+  const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);
+  return { key, fill };
+}
+
+// Offsets from the camera, in camera-space multiples of the camera-to-target distance:
+// the key sits over the viewer's shoulder (up and to the right, ~41° off the view axis),
+// the fill opposes it from the left at eye level. Both still shine mostly ALONG the view
+// direction, so whatever the camera can see is lit.
+const KEY_OFFSET = { right: 0.45, up: 0.75 };
+const FILL_OFFSET = { right: -0.7, up: 0.15 };
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+const length = (v) => Math.hypot(v[0], v[1], v[2]);
+const norm = (v) => {
+  const l = length(v) || 1;
+  return [v[0] / l, v[1] / l, v[2] / l];
+};
+
+// World-space positions for the capture key/fill, given a camera pose (the same
+// `{position, up, target}` shape cameraPoseForView returns). Pure — no THREE, no scene.
+export function captureLightPoses({ position, up, target }) {
+  const forward = norm(sub(target, position));
+  // Camera basis. A canonical view never passes an `up` parallel to its own view axis,
+  // but a caller could, and a degenerate basis would put NaN into the light positions.
+  let right = cross(forward, up);
+  if (length(right) < 1e-6) right = cross(forward, [0, 0, 1]);
+  if (length(right) < 1e-6) right = cross(forward, [0, 1, 0]);
+  right = norm(right);
+  const trueUp = norm(cross(right, forward));
+  const dist = length(sub(target, position)) || 1;
+  const place = (offset) => [0, 1, 2].map(
+    (i) => position[i] + (right[i] * offset.right + trueUp[i] * offset.up) * dist,
+  );
+  return { key: place(KEY_OFFSET), fill: place(FILL_OFFSET) };
+}

package/src/framework/viewer.js

@@ -5,9 +5,35 @@ import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
-import { addViewerLights } from "./viewer-lighting.js";
+import { addViewerLights, captureLightPoses, createCaptureLights } from "./viewer-lighting.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
+// three renders into a render target in the LINEAR working colour space: as of r184
+// WebGLRenderer only applies `outputColorSpace` on the canvas path (WebGLPrograms
+// substitutes workingColorSpace whenever a render target is bound), so readback pixels
+// are linear no matter what the target texture's colorSpace says. Writing them straight
+// into a JPEG is what made captured views come back muddy and dark compared to the live
+// canvas. Encode the transfer function ourselves. The 8-bit LUT loses precision only in
+// the deepest shadows, which a quality-0.9 JPEG would not have preserved anyway.
+const SRGB8 = (() => {
+  const table = new Uint8Array(256);
+  for (let i = 0; i < 256; i++) {
+    const l = i / 255;
+    table[i] = Math.round(255 * (l <= 0.0031308 ? 12.92 * l : 1.055 * l ** (1 / 2.4) - 0.055));
+  }
+  return table;
+})();
+
+// Linear RGBA bytes → sRGB, in place. Alpha is a coverage value, not a colour: untouched.
+export function srgbEncodeInPlace(data) {
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = SRGB8[data[i]];
+    data[i + 1] = SRGB8[data[i + 1]];
+    data[i + 2] = SRGB8[data[i + 2]];
+  }
+  return data;
+}
+
 // Render a set of canonical views without disturbing the live camera/canvas.
 // `renderer.renderOffscreen(pose)` does the GL work (temp camera → offscreen
 // target → readback → JPEG data URL); injected so this is unit-testable without
@@ -57,7 +83,7 @@ export function createViewer(container, part) {
   controls.autoRotateSpeed = 1.6;
 
   // --- lights + grid --------------------------------------------------------
-  addViewerLights(scene);
+  const liveLights = addViewerLights(scene);
   // 1 cm grid (mm units): 300 mm wide, 30 divisions -> 10 mm (1 cm) squares.
   const GRID_SIZE = 300, GRID_DIVS = 30;
   let floorY = 0; // world Y of the grid plane; set to the part's bbox bottom in frameTo
@@ -288,19 +314,47 @@ export function createViewer(container, part) {
   // Offscreen render of the shared scene from an arbitrary pose → JPEG data URL.
   // A separate WebGLRenderTarget + temp camera means the visible canvas and the
   // live `camera` are never touched. WebGL pixels are bottom-up, so flip on encode.
-  const _rtSize = 512;
+  //
+  // These captures are read by a model, not shown as a thumbnail (partforge-cloud's
+  // render_part_views tool feeds them straight to the agent), so they are sized and lit
+  // for reading small features: 1024² is the largest square that fits Anthropic's
+  // ~1.15 MP no-downscale budget, 4× MSAA keeps a thin wall from aliasing into noise,
+  // and the light rig follows the camera so no view is a flat silhouette.
+  const _rtSize = 1024;
   let _rt = null;
+  let _capLights = null;
   function renderOffscreen({ position, up, target }) {
-    _rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize);
+    _rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, { samples: 4 });
+    _capLights = _capLights ?? createCaptureLights();
     const cam = new THREE.PerspectiveCamera(45, 1, 0.1, 1000);
     cam.position.set(position[0], position[1], position[2]);
     cam.up.set(up[0], up[1], up[2]);
     cam.lookAt(target[0], target[1], target[2]);
-    renderer.setRenderTarget(_rt);
-    renderer.render(scene, cam);
     const buf = new Uint8Array(_rtSize * _rtSize * 4);
-    renderer.readRenderTargetPixels(_rt, 0, 0, _rtSize, _rtSize, buf);
-    renderer.setRenderTarget(null);
+    // Swap the world-fixed key/fill for the camera-relative pair, for this one render
+    // only. A DirectionalLight aims at its `target`, whose matrixWorld only updates
+    // while it is in the scene graph, so both go in and both come back out.
+    const poses = captureLightPoses({ position, up, target });
+    const { key: capKey, fill: capFill } = _capLights;
+    capKey.position.set(poses.key[0], poses.key[1], poses.key[2]);
+    capFill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
+    for (const light of [capKey, capFill]) light.target.position.set(target[0], target[1], target[2]);
+    liveLights.key.visible = false;
+    liveLights.fill.visible = false;
+    scene.add(capKey, capKey.target, capFill, capFill.target);
+    try {
+      renderer.setRenderTarget(_rt);
+      renderer.render(scene, cam);
+      // render() resolves the multisample renderbuffer into the target texture, so this
+      // reads antialiased pixels.
+      renderer.readRenderTargetPixels(_rt, 0, 0, _rtSize, _rtSize, buf);
+    } finally {
+      // Never leave the user's own view unlit or pointed at the offscreen target.
+      renderer.setRenderTarget(null);
+      scene.remove(capKey, capKey.target, capFill, capFill.target);
+      liveLights.key.visible = true;
+      liveLights.fill.visible = true;
+    }
     const canvas = document.createElement("canvas");
     canvas.width = _rtSize; canvas.height = _rtSize;
     const ctx = canvas.getContext("2d");
@@ -310,8 +364,9 @@ export function createViewer(container, part) {
       const src = (_rtSize - 1 - y) * _rtSize * 4;
       img.data.set(buf.subarray(src, src + _rtSize * 4), y * _rtSize * 4);
     }
+    srgbEncodeInPlace(img.data);
     ctx.putImageData(img, 0, 0);
-    return canvas.toDataURL("image/jpeg", 0.8);
+    return canvas.toDataURL("image/jpeg", 0.9);
   }
 
   // Render the canonical camera angles offscreen, framed to whatever is visible,

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 }.