partforge 0.119.0 → 0.120.0

package/bin/cli.js

@@ -13,8 +13,6 @@ import { fontsFor } from "../src/framework/fonts.js";
 import { imagesFor } from "../src/framework/images.js";
 import { isNoImageSource } from "../src/framework/image-source.js";
 import { viewAnimations, evaluate, cueAt } from "../src/framework/animation.js";
-import { measure } from "../src/framework/oracle/measure.js";
-import { verify } from "../src/framework/oracle/verify.js";
 import { renderViews } from "../src/testing/render.js";
 import {
   createPickServer, requestPicks, formatPickResult,
@@ -114,7 +112,20 @@ const readSources = (partPath) => {
 // `ingest` itself never touches these three. Deferring the import to the
 // commands that actually need them keeps every other verb's behavior
 // unchanged and keeps paper-core.js's first load in `ingest`'s hands.
+//
+// oracle/measure.js and oracle/verify.js join that list for the same reason,
+// since measure.js now statically imports oracle/shape-probe.js, which reaches
+// geometry/contour-ops.js -> geometry/paper-bridge.js -> paper-core just like
+// vectors.js does (verify.js reaches the same path through its own static
+// import of measure.js). A top-level `import { measure } ...`/`import { verify }
+// ...` here would load paper-core before `ingest`'s installNodeDom() runs on
+// every invocation, not only `measure`'s — deferring both to the one verb that
+// calls them keeps `ingest` first in line for paper-core's environment probe.
 const importVectors = () => import("../src/framework/vectors.js");
+const importOracle = () => Promise.all([
+  import("../src/framework/oracle/measure.js"),
+  import("../src/framework/oracle/verify.js"),
+]);
 
 // Pass the part's declared fonts through, mirroring the worker path (jobs.js) —
 // otherwise a part using a named font builds in the browser but dies headlessly
@@ -210,6 +221,7 @@ const commands = {
         }
       }
       const kernel = await bootKernel(part);
+      const [{ measure }, { verify }] = await importOracle();
       const report = measure(kernel, part, view);
       if (!flags.json) printMeasure(report);
       // Write --out right after measure succeeds, then re-write once verify has

package/docs/AUTHORING-PARTS.md

@@ -89,7 +89,7 @@ export default {
     },
   },
   views: { <name>: { label, default?, animations? } },  // view tabs; a view may own animations (below)
-  probes?,                                 // { name: (k, p, d) => Solid | plain JSON } — measurements reported by
+  probes?,                                 // { name: (k, p, d) => Solid | Shape2D | plain JSON } — measurements reported by
                                            // measure/inspect, never rendered or exported (see "Probes" below)
 };
 ```
@@ -2419,6 +2419,45 @@ declare a probe that reads the value, run `measure`, and bake the reported
 number into `defaults` — the probe then keeps watching it on every regen, so a
 swapped import shows up as a probe delta instead of silently stale defaults.
 
+**Reading a 2-D shape's arcs and corners.** Return the `Shape2D` itself and the
+report carries a summary instead of the object: a flat `rings` list — one entry
+per ring, each naming where it came from (`region`, `ring: "outer" | "hole"`,
+plus `hole` on a hole ring) — every arc as `{ center, r, from, to, sweepDeg }`
+(exact for a `{to, via}` arc; a cubic is fitted through its start, midpoint and
+end and tagged `fit: "cubic"`), every corner as `{ position, point,
+interiorAngleDeg, convex }`, plus `area`, `bbox`, and a straight-segment count
+per ring. `position` is a running count across every ring in that same order —
+region by region, outer then holes — which is exactly the positional index
+`fillet({corners: {indices}})` and `shape.corners()` select on, so a corner read
+here can be fed straight back into a fillet call.
+
+Fillet itself never emits a cubic — paper.js has no arc primitive, so an
+exactly-constructed `{to, via}` arc only becomes a cubic once the shape has been
+through a **boolean** (union/cut/intersect), a non-uniform transform, or
+`simplify`. So after any of those, every arc in the summary is `fit: "cubic"`,
+including ones a fillet placed exactly. For an unclipped arc that cubic fit is
+still exact to the reporting grid; when a boolean clips an arc **mid-sweep**,
+the fit's centre and radius drift, and the drift grows as the kept fragment
+shortens. So when you need an exact centre, read it off the **unclipped**
+shape and use a clip only to find which arc to look at — don't trust the centre
+reported on the clipped fragment itself:
+
+```js
+probes: {
+  fullBend: (k, p, d) => trayPocket(k, p, d),
+  // Clip only to locate the arc; read its numbers off fullBend above, not here.
+  bendNear: (k, p, d) => trayPocket(k, p, d).intersect(k.shape2d([[18, -6], [28, -6], [28, 4], [18, 4]])),
+}
+// → probes.fullBend.rings[0].arcs: [{ center: [23.75, -3], r: 4, … }, …]
+```
+
+This is the instrument for any question a render cannot settle to a fraction of
+a millimetre: whether two arcs share a centre (a bend's inner and outer radii),
+what radius a `fillet` actually took after clamping, whether a corner is still
+a corner. The summary lists at most 64 arcs and 64 corners **in total**, across
+every ring — not 64 each per ring — and says `truncated` when it had to cut, so
+keep the probe to the region in question.
+
 **Cost.** Probes run on every `measure`/`inspect` (including quick checks — the
 agent loop is exactly who reads them), so keep them proportionate: a handful of
 thin-slab booleans is cheap; a dense sweep of whole-part XORs is not. `verify`'s

package/package.json

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

@@ -49,13 +49,13 @@ export const SHAPE_RULES = [
       if (part?.probes === undefined) return [];
       if (!isPlainObject(part.probes)) {
         return [err("invalid-probes", "`probes` must be an object mapping names to functions",
-          "Declare probes as `probes: { name: (k, p, d) => Solid | plain JSON }` — each is measured into the report by `partforge measure` and the inspect job.",
+          "Declare probes as `probes: { name: (k, p, d) => Solid | Shape2D | plain JSON }` — each is measured into the report by `partforge measure` and the inspect job.",
           "probes")];
       }
       return Object.entries(part.probes)
         .filter(([, fn]) => typeof fn !== "function")
         .map(([name]) => err("invalid-probes", `probe "${name}" is not a function`,
-          "Every entry in `probes` must be a `(k, p, d)` function returning a Solid (measured into facts) or plain JSON (reported verbatim).",
+          "Every entry in `probes` must be a `(k, p, d)` function returning a Solid (measured into facts), a Shape2D (summarised into its arcs and corners), or plain JSON (reported verbatim).",
           `probes.${name}`));
     },
   },

package/src/framework/oracle/measure.js

@@ -7,6 +7,7 @@ import { bounds, meshArea, meshCentroid } from "./mesh.js";
 import { minWall, DIAGNOSTIC_SAMPLES } from "./min-wall.js";
 import { overhang } from "./overhang.js";
 import { partGatesMinWall, partOverhangAngle } from "./gates.js";
+import { summarizeContours } from "./shape-probe.js";
 
 const size = ({ min, max }) => [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
 const unionBounds = (list) => list.reduce(
@@ -15,20 +16,37 @@ const unionBounds = (list) => list.reduce(
 );
 
 // ── probes ──────────────────────────────────────────────────────────────────
-// Part-declared measurements: `probes: { name: (k, p, d) => Solid | JSON }`,
+// Part-declared measurements: `probes: { name: (k, p, d) => Solid | Shape2D | JSON }`,
 // pure functions with build's exact contract but whose result lands in the
 // REPORT instead of the scene. The instrument a rebuild-against-reference
 // workflow needs — before this, getting a cross-section's numbers out of the
 // pipeline meant authoring throwaway `exportable: false` sub-parts and fishing
 // their facts out of the sub-part list (the "Probes" feedback report).
 // A Solid anywhere in the return value (duck-typed on volume+toMesh, the two
-// queries the facts need) is replaced by a fact object; scalars/arrays/objects
-// pass through; a throw becomes `{ error }` — probes are instrumentation, so
-// they never crash the measurement and never gate `ok`.
+// queries the facts need) is replaced by a fact object; a Shape2D by its arc/corner
+// summary (shape-probe.js); scalars/arrays/objects pass through; a throw becomes
+// `{ error }` — probes are instrumentation, so they never crash the measurement and
+// never gate `ok`.
 
 const isSolid = (v) => v !== null && typeof v === "object"
   && typeof v.volume === "function" && typeof v.toMesh === "function";
 
+// A Shape2D is a plain object carrying a `_shape2d` marker, not a class instance, but
+// walking it as generic JSON would still leak its storage fields (`_regions`, `_hash`)
+// and turn its methods into `{error}` entries. Duck-typed on the two reads the summary
+// needs, so a foreign shape-like value (same two methods, no marker) is still summarised.
+const isShape2D = (v) => v !== null && typeof v === "object"
+  && typeof v.toContours === "function" && typeof v.area === "function";
+
+const shapeProbeFacts = (shape) => {
+  const empty = typeof shape.isEmpty === "function" ? shape.isEmpty() : false;
+  return summarizeContours(shape.toContours(), {
+    isEmpty: empty,
+    area: empty ? 0 : shape.area(),
+    bbox: empty ? null : (typeof shape.boundingBox === "function" ? shape.boundingBox() : null),
+  });
+};
+
 function solidProbeFacts(solid) {
   const mesh = solid.toMesh();
   // Empty = the probe's boolean found nothing (a slab that misses the part).
@@ -60,8 +78,9 @@ function solidProbeFacts(solid) {
 const MAX_PROBE_VALUE_DEPTH = 4;
 function resolveProbeValue(v, depth = 0) {
   if (isSolid(v)) return solidProbeFacts(v);
+  if (isShape2D(v)) return shapeProbeFacts(v);
   if (v === null || typeof v !== "object") {
-    return typeof v === "function" ? { error: "probe returned a function — return a Solid or plain JSON" } : v;
+    return typeof v === "function" ? { error: "probe returned a function — return a Solid, a Shape2D or plain JSON" } : v;
   }
   if (depth >= MAX_PROBE_VALUE_DEPTH) return { error: `probe value deeper than ${MAX_PROBE_VALUE_DEPTH} levels` };
   if (Array.isArray(v)) return v.map((x) => resolveProbeValue(x, depth + 1));

package/src/framework/oracle/shape-probe.js

@@ -0,0 +1,146 @@
+// The probe-report summary of a Shape2D: its arcs as centre + radius, its corners as
+// point + angle. A reader asking "do these two arcs share a centre?" or "what radius
+// did that fillet actually take?" reads the numbers here instead of a render.
+//
+// Arcs come from the contour IR, never from tessellation: a {to, via} segment is exact
+// (circumcircle of from/via/to). A cubic is FITTED through its start, midpoint and end
+// and tagged `fit: "cubic"` so the reader knows it is an approximation. Fillet itself
+// never emits a cubic — paper.js has no arc primitive, so a shape stores one only once
+// it has been through a BOOLEAN (union/cut/intersect), a non-uniform transform, or
+// simplify. `fit: "cubic"` therefore means "this shape passed through one of those",
+// not "this arc came from a curve-adjacent fillet". For an unclipped arc the cubic fit
+// is exact to the reporting grid; when a boolean clips an arc mid-sweep the fit's error
+// grows as the kept fragment shortens (measured: a r=4 fillet corner clipped at x=18
+// read back centre [16.0063, 16.0184] r 3.9816; a r=100 arc clipped to a 20 mm band read
+// back centre off by 0.59 mm, r 100.586) — compare centres on the UNCLIPPED shape and
+// use a clip only to find which arcs to look at, never to read an exact centre off the
+// clipped fragment itself. See docs/AUTHORING-PARTS.md's probes section.
+//
+// Either recovery (via or cubic) can also produce a near-infinite-radius circle from
+// residual curvature on a segment that reads as straight — most visibly after
+// `simplify`, which can leave a nominally-straight edge with a fraction of a micron
+// of real (not floating-point-noise) bow. A segment whose sagitta (the arc's peak
+// deviation from its own chord, r·(1 − cos(Δ/2))) falls below STRAIGHT_SAGITTA_MM
+// (1e-3 mm, a micron — below anything a print or a reader can act on; an r=100 arc on
+// a 20 mm chord has 0.5 mm of sagitta and an r=1000 one 0.05 mm, so a real bend is
+// nowhere near this floor) is reported as a line instead of a kilometre-radius arc.
+//
+// Corners are profileCorners' reader-facing fields, plus `position`: a running count
+// across every ring in the summary's own order (region by region, outer then holes) —
+// exactly the positional index `fillet({corners: {indices}})` and `shape.corners()`
+// use (both resolve against profileCorners' own flattened order), computed by that same
+// function here rather than re-derived. The `index` field (profileCorners' vertex
+// number within its own contour, not a position into this list) is deliberately
+// dropped — carrying it here is what invites the {indices} mistake.
+//
+// The summary is a FLAT list of rings (each one names its own `region`/`ring`/`hole?`)
+// rather than nested `{outer, holes}` objects, and the two caps below are counted
+// across the WHOLE summary, not per ring: partforge-cloud drops a probe value that
+// grows past its JSON budget or nests past its depth cap. Flat, the summary bottoms
+// out at rings[] → ring → arcs[] → arc → center[] — 4 containers below the summary
+// object itself (5 including it), against the cloud's `DESCRIBE_MAX_DEPTH = 8`, with
+// headroom even wrapped in the paired-probe `{pair: {mine, ref}}` form.
+import { arcCenterAndSweep } from "../geometry/paper-bridge.js";
+import { cubicAt, profileCorners } from "../geometry/contour-ops.js";
+
+export const MAX_ARCS = 64;
+export const MAX_CORNERS = 64;
+// A micron: below anything a print or a reader can act on. An r=100 arc on a 20 mm
+// chord has 0.5 mm of sagitta and an r=1000 one 0.05 mm, so a real bend is nowhere
+// near this floor — only residual curvature left by simplify/boolean noise is.
+export const STRAIGHT_SAGITTA_MM = 1e-3;
+
+const round = (x) => {
+  const v = Math.round(x * 1e4) / 1e4;
+  return v === 0 ? 0 : v; // normalize -0 so the report never prints a bare minus sign
+};
+const pt = ([x, y]) => [round(x), round(y)];
+const toDeg = (rad) => (rad * 180) / Math.PI;
+
+// A recovered circle → an arc record, or null when its sagitta (peak deviation from
+// its own chord) is below STRAIGHT_SAGITTA_MM — a near-straight segment reads as a
+// line rather than a many-kilometre arc.
+function arcFromCircle(c, from, to, fit) {
+  const sagitta = c.r * (1 - Math.cos(Math.abs(c.dA) / 2));
+  if (sagitta < STRAIGHT_SAGITTA_MM) return null;
+  const rec = { center: pt(c.center), r: round(c.r), from: pt(from), to: pt(to), sweepDeg: round(toDeg(c.dA)) };
+  if (fit) rec.fit = fit;
+  return rec;
+}
+
+// One segment → an arc record, or null for a straight (degenerate or near-straight) segment.
+function arcOf(from, seg) {
+  if (seg.c1 && seg.c2) {
+    const mid = cubicAt(from, seg.c1, seg.c2, seg.to, 0.5);
+    const c = arcCenterAndSweep(from, mid, seg.to);
+    return c ? arcFromCircle(c, from, seg.to, "cubic") : null;
+  }
+  if (seg.via) {
+    const c = arcCenterAndSweep(from, seg.via, seg.to);
+    return c ? arcFromCircle(c, from, seg.to, null) : null;
+  }
+  return null;
+}
+
+// One ring's segments → { segments, arcs, lines }. `state.arcsUsed` is the
+// WHOLE-SUMMARY arc budget (MAX_ARCS), shared across every ring's call so the cap is
+// counted across the whole summary rather than restarting per ring; `segments`/`lines`
+// stay exact counts regardless of truncation.
+function ringArcs(contour, state) {
+  const arcs = [];
+  let lines = 0;
+  let from = contour.start;
+  for (const seg of contour.segments) {
+    const a = arcOf(from, seg);
+    if (a) {
+      if (state.arcsUsed < MAX_ARCS) { arcs.push(a); state.arcsUsed++; } else state.truncated = true;
+    } else lines++;
+    from = seg.to;
+  }
+  return { segments: contour.segments.length, arcs, lines };
+}
+
+// The key a ring is filed under, shared between the rings[] list this function builds
+// and the bucketing of profileCorners' flattened output back onto the ring it came from.
+const ringKey = (region, kind, hole) => (kind === "outer" ? `${region}:outer` : `${region}:hole:${hole}`);
+
+/**
+ * Summarise a Shape2D's stored contour regions (the `toContours()` value) for the
+ * probe report. `isEmpty`, `area` and `bbox` are read by the caller from the shape
+ * itself so this stays a pure function of plain data.
+ */
+export function summarizeContours(regions, { isEmpty, area, bbox }) {
+  if (isEmpty || !regions?.length) return { kind: "shape2d", empty: true, area: 0, bbox: null, rings: [], truncated: false };
+  const state = { arcsUsed: 0, truncated: false };
+
+  // profileCorners(regions) walks every ring in the SAME region-by-region,
+  // outer-then-holes order this function does, and its `position` field is already
+  // the flattened index {corners: {indices}} and shape.corners() agree on — computed
+  // once here, over the whole shape, rather than restarting the count per ring.
+  const allCorners = profileCorners(regions);
+  if (allCorners.length > MAX_CORNERS) state.truncated = true;
+  const cornersByRing = new Map();
+  for (let i = 0; i < allCorners.length && i < MAX_CORNERS; i++) {
+    const c = allCorners[i];
+    const key = c.ring === "outer" ? ringKey(c.regionIndex, "outer") : ringKey(c.regionIndex, "hole", c.ring.hole);
+    const bucket = cornersByRing.get(key) ?? [];
+    bucket.push({ position: c.position, point: pt(c.point), interiorAngleDeg: round(c.interiorAngleDeg), convex: c.convex });
+    cornersByRing.set(key, bucket);
+  }
+
+  const rings = [];
+  regions.forEach((rg, region) => {
+    const outerFacts = ringArcs(rg.outer, state);
+    rings.push({ region, ring: "outer", ...outerFacts, corners: cornersByRing.get(ringKey(region, "outer")) ?? [] });
+    (rg.holes ?? []).forEach((h, hole) => {
+      const holeFacts = ringArcs(h, state);
+      rings.push({ region, ring: "hole", hole, ...holeFacts, corners: cornersByRing.get(ringKey(region, "hole", hole)) ?? [] });
+    });
+  });
+
+  return {
+    kind: "shape2d", empty: false, area: round(area),
+    bbox: bbox ? { min: pt(bbox.min), max: pt(bbox.max) } : null,
+    rings, truncated: state.truncated,
+  };
+}

package/types/testing.d.ts

@@ -304,6 +304,57 @@ export interface AggregateFacts {
   triangleCount: number;
 }
 
+/** One arc of a probed `Shape2D` ring: centre and radius from the contour IR. */
+export interface ProbeArc {
+  center: [number, number];
+  r: number;
+  from: [number, number];
+  to: [number, number];
+  /** Signed; positive counter-clockwise. */
+  sweepDeg: number;
+  /** Present when the segment was a cubic and the circle is a fit, not a construction. */
+  fit?: "cubic";
+}
+
+export interface ProbeRing {
+  /** 0-based index into the shape's `regions` — which region this ring belongs to. */
+  region: number;
+  /** Whether this is the region's outer boundary or one of its holes. */
+  ring: "outer" | "hole";
+  /** 0-based hole index within its region; present only when `ring === "hole"`. */
+  hole?: number;
+  /** Total segment count, before any cap. */
+  segments: number;
+  /** At most 64 across the WHOLE summary (all rings combined), not per ring;
+   * `truncated` on the summary says when the list was cut. */
+  arcs: ProbeArc[];
+  /** Straight segments, count only. */
+  lines: number;
+  corners: Array<{
+    /** Running index across every ring in the summary's own order (region by region,
+     * outer then holes) — the positional index `fillet({corners: {indices}})` and
+     * `shape.corners()` select on. */
+    position: number;
+    point: [number, number];
+    interiorAngleDeg: number;
+    convex: boolean;
+  }>;
+}
+
+/** What a `Shape2D` returned from a probe becomes in the report. */
+export interface ShapeProbeFacts {
+  kind: "shape2d";
+  empty: boolean;
+  area: number;
+  bbox: { min: [number, number]; max: [number, number] } | null;
+  /** A flat list of every ring across every region — region by region, outer then
+   * holes — never nested `{outer, holes}` objects. */
+  rings: ProbeRing[];
+  /** At most 64 arcs and 64 corners total, across every ring; true when either
+   * budget was spent and something was cut. */
+  truncated: boolean;
+}
+
 export interface MeasureReport {
   /** `part.meta.title`, falling back to the view name. */
   part: string;
@@ -319,6 +370,12 @@ export interface MeasureReport {
   gaps: Gap[];
   /** The pairs with an unintended-looking gap under the threshold. */
   nearMisses: Gap[];
+  /**
+   * Declared probes' values, present only when the part declares probes and this
+   * run evaluated them. A Solid in a probe's return value becomes a fact object, a
+   * Shape2D becomes a `ShapeProbeFacts`, plain JSON passes through, a throw is `{error}`.
+   */
+  probes?: Record<string, unknown>;
   /** Every sub-part watertight and nothing interpenetrating. Near misses never affect it. */
   ok: boolean;
 }