partforge 0.78.0 → 0.80.0

package/docs/AUTHORING-PARTS.md

@@ -1596,17 +1596,18 @@ different next actions for whoever is rebuilding the part.
 arcs, holes, dress-ups, sweeps, patterns, symmetry — covers the tool's full detection
 vocabulary; a feature can be *reported* there regardless of shape. The RECONSTRUCTION
 score (`explainedVolumeFraction`, and every accepted feature's own `volumeShare`) is
-narrower: `toCandidate` only proposes box and cylinder footprints as acceptance
-candidates today, so it currently reconstructs prismatic parts built from roughly fewer
-than eight box/cylinder features well, and does not yet reconstruct round bosses,
+narrower: `toCandidate` proposes prismatic candidates from each feature's own measured
+footprint — the cap's boundary loops extruded directly, arbitrary polygon outlines and
+interior holes included, alongside the circle/cylinder path — so ordinary prismatic
+parts now reconstruct well regardless of footprint shape. It does not yet reconstruct
 revolves, fillets, chamfers, or shells — those are detected and reported (with
 `volumeShareReason: "not-proposed"`) but never turned into a candidate that could win
 volume back. Measured directly on this repo's own reference parts: `demo.js`
-reconstructs 65.7% of its volume, `filleted-box.js` 36.2%, `bracket.js` 23.6%, a plain
-tube 0.0%, and a hollow box 1.9%. The low-coverage banner fires on every one of these, so
-nothing here is misreported — but a low `explainedVolumeFraction` on a turned or
-feature-dense part means **"not yet reconstructable by this tool"**, not "not
-understood" or "broken." Read the FACTS (features, surfaces, patterns) as the ground
+reconstructs 100% of its volume, `filleted-box.js` 94.9%, `bracket.js` 100%; a plain
+tube and a hollow box still score ~0%, because curved-wall extrusions and shells remain
+unproposed. The low-coverage banner fires wherever the worse score is low, so nothing
+here is misreported — but a low `explainedVolumeFraction` on a turned or shelled part
+means **"not yet reconstructable by this tool"**, not "not understood" or "broken." Read the FACTS (features, surfaces, patterns) as the ground
 truth regardless of the volume score; read the volume score as a measure of how much of
 that ground truth also comes with a working, boolean-verified rebuild recipe.
 
@@ -1948,7 +1949,11 @@ access. It's harmless to leave in when partforge is a normal install.)
 ## Testing a part
 
 Tests run under **Node 24** (`nvm use` first; the default shell Node is too old) via
-`npx vitest run`. Build geometry directly off your part with a Manifold kernel:
+`npx vitest run`. The oracle half of this surface — `measure`, `verify`,
+`describe`, gaps, match scoring — is also published on its own as
+`partforge/oracle` (browser-safe import closure); `partforge/testing` re-exports
+it, so either import works. Build geometry directly off your part with a Manifold
+kernel:
 
 ```js
 import { bootManifoldKernel, resolveDerived } from "partforge/testing";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.78.0",
+  "version": "0.80.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",
@@ -45,6 +45,10 @@
       "types": "./types/derive.d.ts",
       "default": "./src/framework/derive.js"
     },
+    "./oracle": {
+      "types": "./types/oracle.d.ts",
+      "default": "./src/oracle.js"
+    },
     "./testing": {
       "types": "./types/testing.d.ts",
       "default": "./src/testing.js"
@@ -66,6 +70,9 @@
       "derive": [
         "./types/derive.d.ts"
       ],
+      "oracle": [
+        "./types/oracle.d.ts"
+      ],
       "testing": [
         "./types/testing.d.ts"
       ]

package/src/framework/jobs.js

@@ -10,20 +10,32 @@ import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
-import { measure } from "./oracle/measure.js";
-import { verify } from "./oracle/verify.js";
-import { buildView } from "./oracle/build.js";
-import { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./oracle/silhouette.js";
-import { matchViews } from "./oracle/match.js";
-import { describe as describeMesh, describeMemo } from "./oracle/describe.js";
-import { compactDescribe } from "./oracle/describe/report.js";
 
-// One describe memo for the life of this worker. Deliberately NOT swept on setPart the
-// way solid-cache is: describe is pure in the mesh bytes (spec §4.1), so an edit can
-// never invalidate it, and dropping it on rebind would throw away the single most
-// expensive thing this worker computes for no reason at all. Keyed by content digest, so
-// a genuinely changed file misses correctly.
-const DESCRIBE_MEMO = describeMemo();
+// The oracle loads LAZILY, per job family, never at worker boot. It is the largest
+// JS payload in the worker's graph (measure/verify/build, silhouette/match, and the
+// describe stack), and only the `inspect` and `describe` jobs run any of it — the
+// generate/export hot path touches none. Each family below is a literal dynamic
+// import(), which Vite splits into its own chunk under `worker.format: "es"` (this
+// repo's config and partforge-cloud's both), so a user who never runs an oracle job
+// never downloads or parses one. The module loader caches the namespace after the
+// first await, so repeat jobs pay a resolved-promise tick, not a re-fetch.
+// test/worker-layering.test.js's eager-closure guard holds this in place.
+const loadInspect = () => Promise.all([
+  import("./oracle/build.js"),
+  import("./oracle/measure.js"),
+  import("./oracle/verify.js"),
+]);
+const loadDescribe = () => Promise.all([
+  import("./oracle/describe.js"),
+  import("./oracle/describe/report.js"),
+]);
+
+// One describe memo for the life of this worker, created alongside the stack's first
+// load. Deliberately NOT swept on setPart the way solid-cache is: describe is pure in
+// the mesh bytes (spec §4.1), so an edit can never invalidate it, and dropping it on
+// rebind would throw away the single most expensive thing this worker computes for no
+// reason at all. Keyed by content digest, so a genuinely changed file misses correctly.
+let DESCRIBE_MEMO = null;
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -47,7 +59,7 @@ const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 // cannot cost the others their scores (or the caller their geometry report).
 //   {kind: "profile", rings: [[[x,y], ...], ...]}  — millimetres, so it carries scale
 //   {kind: "image",   mask: {data, width, height}} — a photo, so it carries none
-function referenceMask(target) {
+function referenceMask(target, rasterizeRingsMask) {
   if (target?.kind === "profile") return Array.isArray(target.rings) ? rasterizeRingsMask(target.rings) : null;
   if (target?.kind === "image") {
     const m = target.mask;
@@ -70,9 +82,15 @@ function referenceMask(target) {
 //
 // The six mesh masks are rasterized ONCE and shared across every target — the targets
 // are the cheap side of this (a couple of reference masks), the part is not.
-function scoreMatchTargets(built, targets, onProgress) {
+async function scoreMatchTargets(built, targets, onProgress) {
   if (!targets?.length) return null;
   try {
+    // Loaded here, past the early return: an inspect with no matchTargets — the
+    // common case — never pays for the rasterizer.
+    const [{ MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask }, { matchViews }] = await Promise.all([
+      import("./oracle/silhouette.js"),
+      import("./oracle/match.js"),
+    ]);
     const meshes = built.map((b) => b.mesh);
     const viewMasks = {};
     for (const view of MATCH_VIEWS) viewMasks[view] = rasterizeMeshMask(meshes, view);
@@ -80,7 +98,7 @@ function scoreMatchTargets(built, targets, onProgress) {
     const out = [];
     for (const target of targets) {
       try {
-        const reference = referenceMask(target);
+        const reference = referenceMask(target, rasterizeRingsMask);
         if (!reference) continue;
         // scaleAware is the CALLER's promise that both sides are in millimetres, and
         // this is the caller: rings are mm and the mesh masks carry mmPerPx, so a
@@ -365,6 +383,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // unrecognized value must never quietly buy less checking than the caller
       // asked for.
       const quick = msg.checks === "quick";
+      const [{ buildView }, { measure }, { verify }] = await loadInspect();
       const view = msg.view ?? Object.keys(part.views)[0];
       const built = buildView(kernel, part, view, msg.params ?? {});
       const measured = measure(kernel, part, view, msg.params ?? {},
@@ -375,13 +394,18 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           // The defaulted view, not msg.view: the seed below was measured on it, and
           // verify's seed reuse is only sound when both name the same view.
           view,
+          // This job's own (lazily-imported) measure, not verify's static fallback:
+          // the two are different module instances once measure.js loads through a
+          // dynamic import, and the seeding test's call-count mock only sees this
+          // one. One binding for the whole inspect keeps that countable — and true.
+          measureFn: measure,
           quick,
           seed: { params: msg.params ?? {}, result: measured },
         }),
       };
       // `match` is present only when the caller asked for it AND something scored, so
       // an inspect with no `matchTargets` answers on exactly the shape it always has.
-      const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
+      const match = await scoreMatchTargets(built, msg.matchTargets, onProgress);
       if (match) report.match = match;
       post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
     } else if (msg.type === "describe") {
@@ -393,10 +417,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // Manifold only, and not by choice on this path: mesh imports on OCCT are never
       // attempted, so a describe job posted to an OCCT worker is a routing bug, not a
       // fallback opportunity. It surfaces as an ordinary error rather than a reroute.
+      const [{ describe: describeMesh, describeMemo }, { compactDescribe }] = await loadDescribe();
       const solid = kernel.import(msg.importName);      // throws on an unknown name
       // `_importDigest` is the backend's existing underscore side-channel (KERNEL-CONTRACT
       // "Conformance classes") — the same digest already folded into every import cache key.
       const digest = kernel._importDigest?.(msg.importName) ?? null;
+      DESCRIBE_MEMO ??= describeMemo();
       const full = describeMesh(kernel, solid, {
         name: msg.importName,
         digest,

package/src/framework/oracle/describe.js

@@ -180,6 +180,66 @@ function surfaceVertices(topo, surfById, ids, faceScope) {
   return out;
 }
 
+// A deterministic unit vector perpendicular to `w`: orthogonalize the world axis
+// with the smallest |component| along `w`. Deterministic matters — describe is memoed
+// by content digest, so a candidate's frame must be a pure function of the mesh.
+const perpTo = (w) => {
+  const ax = Math.abs(w[0]) <= Math.abs(w[1]) && Math.abs(w[0]) <= Math.abs(w[2]) ? [1, 0, 0]
+    : Math.abs(w[1]) <= Math.abs(w[2]) ? [0, 1, 0] : [0, 0, 1];
+  return orthogonalize(ax, w);
+};
+
+// The cap's own measured boundary loops as ABSOLUTE (u,v) coordinates in the cap's
+// plane — the real footprint, where the box branch below can only offer the
+// footprint's bounding rectangle (mostly air on an L-bracket or a sword-shaped
+// bookmark, so the candidate loses on xor-gain and the feature reconstructs
+// nothing). `surface-graph.js` already chained these loops per surface; a merged
+// surface's list can carry OTHER islands' rims too (mergeCoFamily joins co-planar
+// patches that never touch), so when the feature carries a `faceScope` the loops are
+// filtered to those whose every vertex belongs to this island's own triangles.
+// The largest-area survivor is the outer contour; the rest are holes (an annular
+// cap's second loop — exactly the signal the hole/pocket rules already read).
+// Winding is normalized to CCW for both, the orientation `kernel.extrude` expects
+// of a contour. Returns null when no loop survives — callers fall back to the
+// bounding-box candidate, honest about being one.
+function footprintLoops(topo, cap, scopeFaces, u, v, claimedVerts) {
+  let allowed = null;
+  if (scopeFaces) {
+    allowed = new Set();
+    for (const t of scopeFaces) for (let c = 0; c < 3; c++) allowed.add(topo.tris[3 * t + c]);
+  }
+  const loops = [];
+  for (const loop of cap.loops ?? []) {
+    if (loop.length < 3) continue;
+    if (allowed && !loop.every((vi) => allowed.has(vi))) continue;
+    const pts = loop.map((vi) => {
+      const pnt = [topo.verts[3 * vi], topo.verts[3 * vi + 1], topo.verts[3 * vi + 2]];
+      return [dot3(pnt, u), dot3(pnt, v)];
+    });
+    let a2 = 0; // shoelace, signed — sign is the winding, magnitude ranks outer vs holes
+    for (let i = 0; i < pts.length; i++) {
+      const a = pts[i], q = pts[(i + 1) % pts.length];
+      a2 += a[0] * q[1] - a[1] * q[0];
+    }
+    loops.push({ pts, vis: loop, area: Math.abs(a2) / 2, ccw: a2 > 0 });
+  }
+  if (!loops.length) return null;
+  loops.sort((a, b) => b.area - a.area);
+  const ccw = (l) => (l.ccw ? l.pts : [...l.pts].reverse());
+  // An interior loop whose rim another feature CLAIMS (a detected hole's bore — the
+  // rim ring is shared between the cap and the bore wall, so every loop vertex sits
+  // in the bore surface's own vertex set) is left OUT of the footprint: that hole's
+  // own cut candidate owns it. Without this, an annular cap rebuilt hole-included
+  // leaves the hole feature nothing to explain — measured on the washer fixture,
+  // whose through-hole's volumeShare went to null the moment footprints landed,
+  // exactly the double-explanation this guard prevents. A parametric author would
+  // decompose it the same way: base profile, then a bore with its own diameter.
+  // Unclaimed interior loops (a square cutout no hole rule recognizes) stay in the
+  // footprint — better an honest hole in the prism than 12.5% unexplained volume.
+  const unclaimed = (l) => !claimedVerts || !l.vis.every((vi) => claimedVerts.has(vi));
+  return { outer: ccw(loops[0]), holes: loops.slice(1).filter(unclaimed).map(ccw) };
+}
+
 export function describe(kernel, solid, opts = {}) {
   // A live Solid in, not a mesh. The kernel exposes no public mesh->solid constructor —
   // geometry only enters through `_registerImport` + `import(name)` — and acceptance needs
@@ -270,8 +330,21 @@ export function describe(kernel, solid, opts = {}) {
   // world Z, or — round 2 review's CRITICAL finding — reading the whole mesh's bounds
   // for every feature and building every candidate the same full-part size.
   const surfById = new Map(graph.surfaces.map((s) => [s.id, s]));
+  // Every vertex belonging to a surface some HOLE feature claims — the set
+  // footprintLoops consults so a footprint never re-explains a rim a hole's own cut
+  // candidate owns (see its comment for the washer measurement that forced this).
+  const claimedVerts = new Set();
+  for (const f of features) {
+    if (f.type !== "throughHole" && f.type !== "blindHole") continue;
+    for (const id of f.surfaces ?? []) {
+      const surf = surfById.get(id);
+      for (const t of surf?.faces ?? []) {
+        for (let c = 0; c < 3; c++) claimedVerts.add(topo.tris[3 * t + c]);
+      }
+    }
+  }
   const candidates = features
-    .map((f) => toCandidate(kernel, f, b, { surfById, topo }))
+    .map((f) => toCandidate(kernel, f, b, { surfById, topo, claimedVerts }))
     .filter(Boolean);
 
   const graded = acceptCandidates(kernel, solid, candidates, { budget: opts.budget });
@@ -497,6 +570,38 @@ function toCandidate(kernel, f, b, ctx) {
     // projected onto that exact (u, v, direction) frame — `projectedBounds`, this
     // file's general-frame twin of mesh.js's `bounds()` — rather than the world-axis
     // bbox `size`/`f.depth` used above for the (rotation-insensitive) circle case.
+    // Loop-based candidate first: the cap's own measured boundary loops ARE the
+    // footprint (footprintLoops above), so when they are available the candidate is
+    // the real prism — outer contour extruded, hole contours honoured — rather than
+    // either rectangle below. The frame's in-plane axis is arbitrary (perpTo): the
+    // loop coordinates are absolute projections onto (u, v), so any orthonormal pair
+    // perpendicular to `direction` reproduces the same world-space solid after
+    // orientOnto. Depth still comes from THIS FEATURE'S OWN vertices projected onto
+    // `direction` (the same projectedBounds discipline as the box branch, round 2
+    // review's CRITICAL finding). A candidate whose loops were mis-chained or span a
+    // merged surface's other island simply scores a poor xor-gain and is rejected —
+    // the same honesty the box fallback has always leaned on.
+    const cap = ctx?.surfById?.get(f.floorFace);
+    if (cap?.loops?.length && ctx?.topo) {
+      const u = perpTo(direction);
+      const v = cross3(direction, u);
+      const fp = footprintLoops(ctx.topo, cap, f.faceScope?.[f.floorFace], u, v, ctx.claimedVerts);
+      if (fp) {
+        const ownSurfaces = [f.floorFace, ...(f.wallFaces ?? [])].filter(Boolean);
+        return {
+          key: f.key, featureKey: f.key, op, explains: [f.id],
+          dimension: f.depth, paramName: "height", hintOp: f.type === "boss" ? "union" : f.type === "pocket" ? "cut" : "box",
+          hintArgs: { shape: f.profile.kind, depth: f.depth },
+          build: () => {
+            const verts = surfaceVertices(ctx.topo, ctx.surfById, ownSurfaces, f.faceScope);
+            const bnd = projectedBounds(verts, [u, v, direction]);
+            const local = kernel.extrude({ profile: { outer: fp.outer, holes: fp.holes }, h: bnd.max[2] - bnd.min[2] });
+            const oriented = orientOnto(local, direction, u);
+            return oriented.translate(scale3(direction, bnd.min[2]));
+          },
+        };
+      }
+    }
     const wallPlane = ctx?.surfById && f.wallFaces
       ? f.wallFaces.map((id) => ctx.surfById.get(id)).find((s) => s?.type === "plane")
       : null;

package/src/oracle.js

@@ -0,0 +1,27 @@
+// partforge/oracle — the geometric oracle as its own published entry.
+//
+// This is the SEAM between the oracle and everything that consumes it. The same
+// modules serve three callers: the geometry worker lazy-loads them per job family
+// (see jobs.js — an `inspect` pulls measure/verify/build, a `describe` pulls the
+// describe stack, and the generate/export hot path pulls none), the CLI and Node
+// harnesses import them here directly, and partforge/testing re-exports this whole
+// surface so an existing downstream import keeps working. Everything below is
+// DOM-free, three-free and node:-free — test/oracle-entry.test.js walks the closure
+// and holds that, so the entry stays importable from a worker, a browser, or Node
+// alike. If the oracle ever moves to its own package, this file is the boundary
+// consumers are already importing through.
+export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
+export { meshVolume, bboxSize } from "./framework/oracle/mesh.js";
+export { buildView } from "./framework/oracle/build.js";
+export { measure } from "./framework/oracle/measure.js";
+export { verify } from "./framework/oracle/verify.js";
+export { buildBVH } from "./framework/oracle/bvh.js";
+export { minWall } from "./framework/oracle/min-wall.js";
+// Silhouette match scoring — the `inspect` job scores `matchTargets` with exactly
+// these, re-exported so a downstream harness can reproduce a score outside the job loop.
+export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
+export { matchMasks, matchViews } from "./framework/oracle/match.js";
+// The semantic mesh oracle — what the `describe` job runs.
+export { describe, describeMemo, DESCRIBE_ERRORS } from "./framework/oracle/describe.js";
+export { compactDescribe, LOW_COVERAGE } from "./framework/oracle/describe/report.js";
+export { DESCRIBE_LIMITS } from "./framework/oracle/describe/limits.js";

package/src/testing.js

@@ -14,22 +14,9 @@ export { viewSubParts } from "./framework/part-model.js";
 export { resolveDerived } from "./framework/derive.js";
 export { relevantParamKeys, RELEVANT_ALL } from "./framework/param-deps.js";
 export { assemblyOverlaps } from "./framework/assembly.js";
-export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
 export { bootOcctKernel } from "./testing/occt.js";
-export { meshVolume, bboxSize } from "./framework/oracle/mesh.js";
-export { buildView } from "./framework/oracle/build.js";
-export { measure } from "./framework/oracle/measure.js";
 export { renderViews, RENDER_VIEWS } from "./testing/render.js";
-export { verify } from "./framework/oracle/verify.js";
-export { buildBVH } from "./framework/oracle/bvh.js";
-export { minWall } from "./framework/oracle/min-wall.js";
-// Silhouette match scoring — also worker-reachable (the `inspect` job scores
-// `matchTargets` with exactly these), re-exported so a downstream harness can build
-// the same masks and reproduce a score outside the job loop.
-export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
-export { matchMasks, matchViews } from "./framework/oracle/match.js";
-// The semantic mesh oracle. Worker-reachable like the rest of the oracle (the
-// `describe` job runs it); re-exported so a downstream harness can run it directly.
-export { describe, describeMemo, DESCRIBE_ERRORS } from "./framework/oracle/describe.js";
-export { compactDescribe, LOW_COVERAGE } from "./framework/oracle/describe/report.js";
-export { DESCRIBE_LIMITS } from "./framework/oracle/describe/limits.js";
+// The whole oracle surface (measure/verify/buildView, gaps/BVH/min-wall, silhouette
+// match scoring, and the semantic mesh oracle) comes through partforge/oracle — one
+// list of names, two doors. See src/oracle.js for what each group is.
+export * from "./oracle.js";

package/types/oracle.d.ts

@@ -0,0 +1,27 @@
+// partforge/oracle — types for the oracle's own entry (src/oracle.js).
+//
+// The declarations themselves live in testing.d.ts, where this surface was first
+// published; this file re-exports exactly the names src/oracle.js exports, plus the
+// report/mask/gap types a caller needs to annotate results. If the oracle ever moves
+// to its own package, the declarations migrate here and testing.d.ts re-exports
+// instead — the direction flips, the names don't.
+export type { GeometryKernel, Mesh, PartDefinition, ResolvedParams, Solid } from "./testing.js";
+export {
+  // measurement + verification
+  measure, verify, buildView,
+  type MeasureReport, type SubPartFacts, type AggregateFacts, type BuiltSubPart,
+  type VerifyReport, type VerifyCaseResult, type VerifyCheck, type CheckStatus,
+  // mesh facts, gaps, BVH, min wall
+  meshVolume, bboxSize, assemblyGaps, meshGaps, buildBVH, minWall,
+  type Gap, type BVH,
+  // silhouette match scoring
+  MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask, matchMasks, matchViews,
+  type SilhouetteMask, type MatchScores, type MatchDelta,
+  // the semantic mesh oracle
+  describe, describeMemo, compactDescribe,
+  DESCRIBE_ERRORS, DESCRIBE_LIMITS, LOW_COVERAGE,
+  type DescribeReport, type DescribeCompactReport, type DescribeFailure,
+  type DescribeSurface, type DescribeArc, type DescribeFeature, type DescribePattern,
+  type DescribeResidualRegion, type DescribeSuggestion, type DescribeSuggestionStep,
+  type DescribeScore, type DescribeTruncated, type Snapped,
+} from "./testing.js";