partforge 0.118.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)
 };
 ```
@@ -1534,20 +1534,32 @@ its coordinates, and the max that would work — rather than silently clamping:
 |---|---|
 | `filletProfile(input, r, opts?)` | `r`: number, or an array matched positionally with `opts.corners.indices` |
 | `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
-| `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+| `profileCorners(input)` | `[{index, position, point, interiorAngleDeg, convex, segTypes}]` — `position` is the entry's place in this list, `index` the joint's vertex number within its contour |
 
 `opts.corners` selects which corners an op touches (default `"all"`):
 
 - `"all"` · `"convex"` · `"concave"`
-- `{indices: [...]}` — positions into `profileCorners(input)`'s own return order; pair
-  with an array `r`/`dist` for per-corner radii (the `roundedProfile` pattern)
-- `{near: [x,y], count?: 1}` — nearest-corner selection; the hook for a human pick or
-  an agent resolving "the top-left corner" from bbox reasoning
+- `{indices: [...]}` — each corner's **`position`** in `profileCorners(input)`'s return
+  list, never its `index`; pair with an array `r`/`dist` for per-corner radii (the
+  `roundedProfile` pattern). Any entry out of range throws, naming the range.
+- `{near: [x,y], count?: 1, within?: mm}` — nearest-corner selection; the hook for a
+  human pick or an agent resolving "the top-left corner" from bbox reasoning. **Without
+  `within` the nearest corner is always selected, however far away** — `count: 4`
+  applied around a small pocket rounds the four corners nearest it, which may all
+  belong to the outer wall. Pass `within` when the pick must be local; a `near` with
+  nothing inside `within` throws instead of reaching further.
+
+**`index` and `position` are different numbers.** `index` is the vertex number within
+the contour; `position` is the corner's place in the returned list. They agree only
+while every joint is a corner — the moment a contour has a smooth joint (a collinear
+midpoint, a G1 arc-to-line join, a fillet already applied) the vertex numbers skip
+ahead of the positions, and `.map((c) => c.index)` fed to `{indices}` fillets the
+wrong corners or throws out of range. Always map to `c.position`.
 
 ```js
 // Fillet only the two corners nearest the profile's top edge, 3mm and 1.5mm:
 const corners = profileCorners(outline);
-const top = corners.filter((c) => c.point[1] > 20).map((c) => c.index);
+const top = corners.filter((c) => c.point[1] > 20).map((c) => c.position);   // position, NOT index
 const rounded = filletProfile(outline, [3, 1.5], { corners: { indices: top } });
 
 // Fillet every convex corner of a Shape2D by the same amount:
@@ -2407,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/docs/KERNEL-CONTRACT.md

@@ -614,9 +614,9 @@ backwards for the holes (see the migration note below).
 | `simple()` | `toRegions()` unwrapped — throws unless the result is exactly one region. |
 | `regions()` | Scission: each disjoint region as its own live `Shape2D[]` (each further boolean-able), vs `toRegions()` which returns raw `{outer, holes}` data. Goes through `toRegions()`, so the pieces are tessellated at the backend's LOD — curves do not survive scission. |
 | `translate([dx,dy])` / `rotate(deg, center?)` / `scale(f\|[sx,sy], center?)` / `mirror(axis)` | Rigid/similarity transforms on the contours (curve-preserving). `center` defaults to the origin; `axis` is `"x"`, `"y"`, or `{point, dir}`. `scale`'s factor is uniform when a bare number, per-axis when `[sx,sy]`. |
-| `fillet(r, {corners?})` / `chamfer(d, {corners?})` | Round (true arcs) or bevel (straight chords) selected corners. `corners` = `"all"` (default) / `"convex"` / `"concave"` / `{indices}` / `{near, count?}`; `r`/`d` may be an array paired positionally with `{indices}`. Throws when no corner matches. |
+| `fillet(r, {corners?})` / `chamfer(d, {corners?})` | Round (true arcs) or bevel (straight chords) selected corners. `corners` = `"all"` (default) / `"convex"` / `"concave"` / `{indices}` / `{near, count?, within?}`; `r`/`d` may be an array paired positionally with `{indices}`. `{indices}` entries are each corner's `position` in `corners()` and any entry out of range throws (never silently dropped). `{near}` takes the `count` (default 1) nearest corners; without `within` (mm) the nearest is always selected however far away, with it a pick that finds nothing inside the radius throws. Throws when no corner matches. |
 | `simplify(tolerance)` | Corner-preserving decimation/refit within `tolerance` mm — dense point rings become fewer segments (and refit arcs/cubics) without moving corners. |
-| `corners()` | The corner list — `{index, point, interiorAngleDeg, convex, segTypes}[]`. This positional order is what `fillet`/`chamfer`'s `{indices}` selects into. |
+| `corners()` | The corner list — `{index, position, point, interiorAngleDeg, convex, segTypes}[]`. `position` is the entry's place in this list and is what `fillet`/`chamfer`'s `{indices}` selects by; `index` is the joint's vertex number within its own contour (what smooth joints are skipped from), and the two diverge past any smooth joint. |
 | `contains([x,y])` | Point-in-shape test (inside an outer, not inside a hole). |
 | `isEmpty()` | `true` when the shape has no regions at all — a `cut`/`intersect` legitimately removed everything. Pure JS on the stored IR, backend-identical. See "Empty shapes" below. |
 | `extrude({h, twist?, scaleTop?})` | Sugar for `k.extrude({profile: this, …})` → `Solid`. Throws on an empty shape (see "Empty shapes"). |
@@ -766,7 +766,7 @@ being single-contour by nature, they throw on a region. The full set: `translate
 | | `mirrorProfile(input, axis)` | `axis: "x" \| "y" \| {point, dir}` |
 | Corners | `filletProfile(input, r, opts?)` | `r` may be an array paired with `{indices}` |
 | | `chamferProfile(input, dist, opts?)` | symmetric setback, straight connector |
-| | `profileCorners(input)` | `[{index, point, interiorAngleDeg, convex, segTypes}]` |
+| | `profileCorners(input)` | `[{index, position, point, interiorAngleDeg, convex, segTypes}]`; `{indices}` selects by `position` |
 | Queries | `profileLength(contour)` | mm; single contour only |
 | | `profilePointAt(contour, {t} \| {length})` | single contour only |
 | | `profileTangentAt(contour, {t} \| {length})` | unit vector; single contour only |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.118.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/geometry/contour-ops.js

@@ -188,15 +188,23 @@ function contourCorners(contour) {
   return out;
 }
 
+// Two numbers on every corner, and they are NOT interchangeable. `index` is the joint's
+// vertex number within its own contour (what buildCornerOpRing, simplify and the lofts
+// key on); `position` is the corner's place in THIS returned list — the one
+// `{corners: {indices}}` selects by. They diverge as soon as a contour has a smooth
+// joint (a collinear midpoint, a G1 arc-line join), and on region input `index`
+// restarts per ring while `position` runs on through the flattened order.
+const withPositions = (corners) => corners.map((c, position) => ({ ...c, position }));
+
 export function profileCorners(input) {
   const { kind, regions } = liftProfile(input);
-  if (kind === "points" || kind === "contour") return contourCorners(regions[0].outer);
+  if (kind === "points" || kind === "contour") return withPositions(contourCorners(regions[0].outer));
   const out = [];
   regions.forEach((rg, regionIndex) => {
     for (const c of contourCorners(rg.outer)) out.push({ regionIndex, ring: "outer", ...c });
     rg.holes.forEach((h, hi) => { for (const c of contourCorners(h)) out.push({ regionIndex, ring: { hole: hi }, ...c }); });
   });
-  return out;
+  return withPositions(out);
 }
 
 // ── Fillet / chamfer ─────────────────────────────────────────────────────────
@@ -205,6 +213,19 @@ export function profileCorners(input) {
 // indexes this array POSITIONALLY, matching profileCorners' documented contract).
 // r/dist may be an array paired positionally with {indices}; every other selector
 // broadcasts the scalar to every match. Throws when nothing matches.
+//
+// {indices} REJECTS any entry outside 0…corners.length-1 rather than dropping it.
+// It used to filter silently, and the author who wrote `.map((c) => c.index)` —
+// a vertex number, not a position — then filleted the wrong corners with no error
+// once the out-of-range ones fell away (partforge-cloud feedback #95: ~15 applies
+// chasing an L-bend whose arcs would not come out concentric). A throw that names
+// the two fields is the coaching that ends that loop on the first attempt.
+//
+// {near} takes an optional `within` (mm). WITHOUT it the nearest `count` corners
+// are always selected, however far away — "round the four outer corners" applied per
+// compartment happily rounds the four corners nearest a small pocket that touches
+// none of them. `within` turns a far pick into the same no-match error as any
+// other empty selector.
 function resolveCornerSelector(corners, param, opts, label) {
   const sel = (opts && opts.corners) ?? "all";
   const isArrayParam = Array.isArray(param);
@@ -218,14 +239,28 @@ function resolveCornerSelector(corners, param, opts, label) {
     const perCorner = isArrayParam ? param : null;
     if (perCorner && perCorner.length !== sel.indices.length)
       throw new Error(`${label}: per-corner radius array has ${perCorner.length} entries but {indices} has ${sel.indices.length}`);
-    picked = sel.indices
-      .map((idx, j) => ({ corner: corners[idx], param: perCorner ? perCorner[j] : param }))
-      .filter((p) => p.corner);
+    const n = corners.length;
+    picked = sel.indices.map((idx, j) => {
+      if (!Number.isInteger(idx))
+        throw new Error(`${label}: {indices} entry ${idx} is not an integer — {indices} takes each corner's \`position\` from profileCorners()`);
+      if (idx < 0 || idx >= n)
+        throw new Error(
+          `${label}: {indices} entry ${idx} is out of range — profileCorners() reported ${n} corner${n === 1 ? "" : "s"} (positions 0…${Math.max(0, n - 1)}). ` +
+          "{indices} takes each corner's `position` (its place in that list), not its `index` (its vertex number within the contour)",
+        );
+      return { corner: corners[idx], param: perCorner ? perCorner[j] : param };
+    });
   } else if (sel && Array.isArray(sel.near)) {
     const [nx, ny] = sel.near;
     const count = sel.count ?? 1;
+    const within = sel.within;
+    if (within !== undefined && !(Number.isFinite(within) && within > 0))
+      throw new Error(`${label}: {near} within must be a positive number of mm (got ${within})`);
     const distSq = (c) => (c.point[0] - nx) ** 2 + (c.point[1] - ny) ** 2;
-    picked = corners.slice().sort((a, b) => distSq(a) - distSq(b)).slice(0, count).map((corner) => ({ corner, param }));
+    const candidates = within === undefined ? corners.slice() : corners.filter((c) => distSq(c) <= within * within);
+    if (candidates.length === 0)
+      throw new Error(`${label}: no corner within ${within}mm of (${nx}, ${ny}) — the nearest is ${Math.sqrt(Math.min(...corners.map(distSq))).toFixed(3)}mm away`);
+    picked = candidates.sort((a, b) => distSq(a) - distSq(b)).slice(0, count).map((corner) => ({ corner, param }));
   } else picked = [];
   if (picked.length === 0) throw new Error(`${label}: no corner matched selector ${JSON.stringify(sel)}`);
   return picked;

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/geometry.d.ts

@@ -175,9 +175,11 @@ export function filletProfile(input: ProfileInput, r: number | number[], opts?:
 export function chamferProfile(input: ProfileInput, dist: number | number[], opts?: { corners?: CornerSelector }): ProfileInput;
 
 /**
- * The corner list — `{index, point, interiorAngleDeg, convex, segTypes}[]`,
- * plus `{regionIndex, ring}` for region/regions input. This positional order
- * is what `filletProfile`/`chamferProfile`'s `{indices}` selects into.
+ * The corner list — `{index, position, point, interiorAngleDeg, convex,
+ * segTypes}[]`, plus `{regionIndex, ring}` for region/regions input. `position`
+ * (the entry's place in this list) is what `filletProfile`/`chamferProfile`'s
+ * `{indices}` selects by; `index` is the joint's vertex number within its
+ * contour, and the two diverge past any smooth joint.
  */
 export function profileCorners(input: ProfileInput): Corner2D[];
 

package/types/kernel.d.ts

@@ -103,8 +103,15 @@ export interface ContourRegion {
 
 /** One corner of a `Shape2D`, as `Shape2D.corners()` reports it. */
 export interface Corner2D {
-  /** Index of the joint within its own contour. */
+  /**
+   * The joint's vertex number within its own contour. NOT what `fillet`/
+   * `chamfer`'s `{ indices }` takes — that is `position`. The two diverge as
+   * soon as a contour has a smooth joint (a collinear midpoint, a G1 arc-line
+   * join), and on region input `index` restarts per ring.
+   */
   index: number;
+  /** This corner's place in the `corners()` list — what `{ indices }` selects by. */
+  position: number;
   point: Point2;
   interiorAngleDeg: number;
   convex: boolean;
@@ -121,9 +128,17 @@ export type CornerSelector =
   | "all"
   | "convex"
   | "concave"
-  /** Positional indices into `corners()`; a per-corner `r`/`d` array pairs with these. */
+  /**
+   * Each corner's `position` in `corners()` (never its `index`); a per-corner
+   * `r`/`d` array pairs with these. Any entry out of range throws.
+   */
   | { indices: number[] }
-  | { near: Point2; count?: number };
+  /**
+   * The `count` (default 1) corners nearest `near`, optionally only those
+   * `within` mm of it. Without `within` the nearest corner is always selected,
+   * however far away it is.
+   */
+  | { near: Point2; count?: number; within?: number };
 
 /** A mirror line for `Shape2D.mirror`. */
 export type MirrorAxis2 = "x" | "y" | { point: Point2; dir: Point2 };
@@ -195,7 +210,7 @@ export interface Shape2D {
   chamfer(d: number | number[], opts?: { corners?: CornerSelector }): Shape2D;
   /** Corner-preserving decimation/refit within `tolerance` mm. */
   simplify(tolerance: number): Shape2D;
-  /** The corner list — the positional order `fillet`/`chamfer`'s `{ indices }` selects into. */
+  /** The corner list; each entry's `position` is what `fillet`/`chamfer`'s `{ indices }` selects by. */
   corners(): Corner2D[];
   /** Is `[x, y]` inside the shape (inside an outer, not inside a hole)? */
   contains(p: Point2): boolean;

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