partforge 0.85.4 → 0.87.0

package/bin/cli.js

@@ -26,25 +26,7 @@ import { lintPart } from "../src/lint.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 
-// The semantic mesh oracle (`describe`) lives in a separate, closed package — this
-// CLI names it only here, and resolves it at CALL time so every other verb works
-// without it installed. PARTFORGE_ORACLE overrides the specifier (a path or module
-// name) — how the oracle package's own repo points this CLI at its working tree.
-const ORACLE_PACKAGE = "@pixiteapps/partforge-oracle";
-async function loadOracle() {
-  const spec = process.env.PARTFORGE_ORACLE ?? ORACLE_PACKAGE;
-  const target = spec.startsWith(".") || spec.startsWith("/")
-    ? pathToFileURL(resolve(process.cwd(), spec)).href
-    : spec;
-  try {
-    return await import(target);
-  } catch (e) {
-    die(`describe needs the mesh-oracle package (${ORACLE_PACKAGE}), which is not installed.\n` +
-        `Install it from the private registry (or set PARTFORGE_ORACLE to a local path) and retry.\n` +
-        `(import of ${spec} failed: ${e?.message ?? e})`);
-  }
-}
-const USAGE = "usage: partforge <lint|measure|render|describe|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
@@ -205,52 +187,6 @@ const commands = {
     }
   },
 
-  async describe(args) {
-    const usage = "usage: partforge describe <part-module#importName> [--surfaces] [--json] [--budget N] [--out <file>]";
-    const { values: flags, positionals: [target] } = parse(args, {
-      surfaces: { type: "boolean" },
-      json: { type: "boolean" },
-      budget: { type: "string" },
-      out: { type: "string" },
-    }, usage);
-    if (!target) die(usage);
-    // `part.js#importName` — describe reads a FILE, and a file only reaches the kernel
-    // through a part's `imports` declaration, so the part is how we find it. A bare mesh
-    // path is deliberately not accepted in v1: it would need its own resolver, its own
-    // format sniffing, and its own unit assumptions, all of which the import pipeline
-    // already owns.
-    const [partPath, importName] = target.split("#");
-    if (!importName) die(`describe needs an import name: <part-module>#<importName>\n${usage}`);
-    try {
-      const part = await loadPart(partPath, usage);
-      if (!part.imports?.[importName]) {
-        die(`describe: "${importName}" is not a declared import of ${partPath} ` +
-            `(have: ${Object.keys(part.imports ?? {}).join(", ") || "none"})`);
-      }
-      const { describe: describeMesh, compactDescribe } = await loadOracle();
-      const kernel = await bootKernel(part);
-      const solid = kernel.import(importName);
-      const report = describeMesh(kernel, solid, {
-        name: importName,
-        digest: kernel._importDigest?.(importName) ?? null,
-        budget: flags.budget ? Number(flags.budget) : undefined,
-      });
-      if (flags.out) {
-        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
-        writeFileSync(flags.out, JSON.stringify(report, null, 2));
-      }
-      if (flags.json) console.log(JSON.stringify(report, null, 2));
-      else printDescribe(report, { surfaces: !!flags.surfaces }, compactDescribe);
-      if (flags.out) console.log(`\nwrote ${flags.out}`);
-      // A closed-set error exits non-zero; LOW COVERAGE does not. Coverage is a finding
-      // the caller must be able to read, and an exit code that conflated the two would
-      // train an agent to discard exactly the reports it most needs to look at.
-      process.exit(report.error ? 1 : 0);
-    } catch (e) {
-      crash("describe", e, !!flags.json);
-    }
-  },
-
   async render(args) {
     const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>] " +
       "[--params <json>] [--animation <name>] [--at <t[,t…]>] [--step <index|label>]";
@@ -488,83 +424,6 @@ function printVerify(v) {
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
 
-// Human/agent-readable summary. Features, patterns, symmetry, score, residual — the
-// compact shape (spec §3.4), because a 24k-triangle part yields hundreds of surfaces and
-// dumping them buries the reader in the noise the oracle exists to remove. `--surfaces`
-// opts back in; `--json` always has everything. Reads the SAME compactDescribe() output
-// a model reads (not a hand-rolled subset), so what a human sees here and what an agent
-// sees over `--json` cannot drift apart.
-function printDescribe(report, { surfaces }, compactDescribe) {
-  if (report.error) {
-    console.error(`describe: ${report.error}${report.detail ? ` — ${report.detail}` : ""}`);
-    return;
-  }
-  const c = compactDescribe(report);
-  if (c.warning) console.log(`\n!! ${c.warning}\n`);
-  console.log(`${c.source.name ?? "mesh"} — ${c.source.triangles} triangles, ` +
-              `${c.bounds.size.map((v) => v.toFixed(2)).join(" x ")} mm, ${c.frame.up} up`);
-  // The `share` hint lives HERE, at the point of use, not several lines below beside
-  // Score (fix round 2, IMPORTANT 1 — a prior version printed the full `score.note`
-  // paragraph under Score and it dominated the report: measured at 36-43% of a typical
-  // run's line count, the single largest visual element, bigger than the feature list,
-  // banners, and score line combined — burying findings instead of clarifying them). One
-  // line, next to the column it explains; the full note is still in `--json` unabridged
-  // (`buildScore` in report.js attaches it unconditionally — nothing lost there).
-  console.log(`\nFeatures (${c.features.length}):` +
-              (c.features.length ? `   share = fraction of part volume this feature ` +
-                `accounts for — a size measure, not certainty` : ""));
-  // `volumeShareReason` (fix round 2, IMPORTANT 2): `volumeShare: null` alone doesn't
-  // say whether this feature type is never proposed at all, was proposed but never
-  // reached before the search ran out of budget, or was reached and built but simply
-  // didn't win — three different signals to a rebuilder deciding what to do next. See
-  // describe.js's own comment on the field for the exact three-way split.
-  const REASON_LABEL = { "not-proposed": "not proposed", budget: "budget", rejected: "rejected" };
-  for (const f of c.features) {
-    const dim = f.diameter ?? f.radius ?? f.width ?? f.thickness ?? f.depth;
-    const snap = f.snapped?.diameter?.note ? `  [${f.snapped.diameter.note}]` : "";
-    const share = f.volumeShare != null
-      ? `${(100 * f.volumeShare).toFixed(1)}%`
-      : `n/a (${REASON_LABEL[f.volumeShareReason] ?? f.volumeShareReason ?? "unknown"})`;
-    console.log(`  ${f.id.padEnd(5)} ${f.type.padEnd(14)} ` +
-                `${dim != null ? dim.toFixed(3) : ""}`.padEnd(10) +
-                `share ${share}${snap}`);
-  }
-  if (c.patterns.length) {
-    console.log(`\nPatterns (${c.patterns.length}):`);
-    for (const p of c.patterns) {
-      console.log(`  ${p.id.padEnd(5)} ${p.type.padEnd(9)} x${p.counts.join("x")} ` +
-                  `pitch ${p.pitch.map((v) => v.toFixed(2)).join(", ")}  [${p.members.length} members]`);
-    }
-  }
-  if (c.symmetry.length) {
-    console.log(`\nSymmetry:`);
-    for (const s of c.symmetry) console.log(`  ${s.type} coverage ${s.coverage}`);
-  }
-  if (surfaces) {
-    console.log(`\nSurfaces (${report.surfaces.length}):`);
-    for (const s of report.surfaces) {
-      console.log(`  ${s.id.padEnd(5)} ${s.type.padEnd(9)} area ${s.area.toFixed(2)}`.padEnd(40) +
-                  `rms ${s.rms.toExponential(2)}`);
-    }
-  }
-  // TWO DIFFERENT NUMBERS, printed as two: explainedArea is how much of the mesh's
-  // SURFACE segmentation fitted to some primitive; explainedVolumeFraction is how much
-  // of the part's actual SHAPE the accepted features reconstruct. They can diverge
-  // totally — a dome segments to ~100% area and 0% volume, since a sphere is not a
-  // candidate-eligible feature type — so printing only one (or a blended "xor%") would
-  // hide exactly the gap the LOW COVERAGE banner above exists to catch. The wording here
-  // ("surface area explained" vs. "volume reconstructed") already carries that
-  // distinction; `score.note`'s full prose (this point, plus the volumeShare aside now
-  // covered at the Features header instead) stays JSON-only — fix round 2, IMPORTANT 1.
-  console.log(`\nScore: ${(100 * c.score.explainedArea).toFixed(1)}% surface area explained, ` +
-              `${(100 * c.score.explainedVolumeFraction).toFixed(1)}% volume reconstructed ` +
-              `(residual xor ${(100 * c.score.xorFraction).toFixed(2)}% of volume)`);
-  console.log(`Residual: ${(100 * c.residual.areaFraction).toFixed(2)}% of area in ` +
-              `${c.residual.regions.length} region(s)`);
-  const truncated = Object.entries(report.truncated ?? {}).filter(([, v]) => v).map(([k]) => k);
-  if (truncated.length) console.log(`Truncated (caps hit): ${truncated.join(", ")}`);
-}
-
 function printLint(r) {
   const all = [...r.errors, ...r.warnings, ...(r.notes ?? [])];
   if (all.length === 0) { console.log("lint: clean"); return; }

package/docs/AUTHORING-PARTS.md

@@ -1559,30 +1559,26 @@ build: (k, p, d) => {
 
 **CLI:** `partforge measure|render|lint` work on an importing part exactly as on any other — the `imports` field resolves in the CLI's Node boot the same way `fonts` does, no extra flags.
 
-## Describing an imported mesh
-
-`npx partforge describe <part-module>#<importName>` reads an already-declared import
-and emits a semantic feature report — holes, bosses, pockets, extrusions, patterns,
-symmetry — rather than a triangle soup, so an agent can rebuild an STL parametrically.
-
-The engine behind it — the semantic mesh oracle — is **not part of this package**: it
-ships as a separate, closed package (`@pixiteapps/partforge-oracle`) whose docs carry
-the full report contract (the two report shapes, feature vocabulary, `volumeShare`
-semantics, coverage scores, budget behavior, and the closed error set). This repo
-keeps only the seams:
-
-- **CLI** — `partforge describe` resolves the oracle package at call time and prints
-  an install pointer when it is absent (`PARTFORGE_ORACLE` overrides the module
-  specifier, which is how the oracle's own repo points this CLI at its working tree).
-- **Worker** — the `describe` job runs whatever `runWorker(part, { loadOracle })`
-  injected; without a loader it answers a structured
-  `{error: "oracle-unavailable"}` report (see
-  [ERROR-PATTERNS.md#describe-oracle-unavailable](ERROR-PATTERNS.md#describe-oracle-unavailable)),
-  never a stall. The loader resolves the oracle barrel: `describe`, `describeMemo`,
-  `compactDescribe`.
-- **Helpers** — the oracle package peer-depends on this one and consumes
-  `partforge/oracle`'s mesh/BVH helpers and file parsers (`bounds`, `meshArea`,
-  `meshTriangles`, `parseStl`, `parse3MF`); those exports are part of its contract.
+## Host jobs: extending the worker
+
+The worker's job loop handles a closed set of message types (`generate`, the exports,
+`inspect`, …). A host app can add its own: `runWorker(part, { jobs: { <type>:
+handler } })`. A message whose `type` matches no built-in is handed to the matching
+handler as `handler(kernel, part, msg, post, { isStale })` — the live kernel (so the
+handler can `kernel.import(name)` a declared import, or read `kernel._importDigest`),
+the part current when the message arrived, the message, and the poster for results
+(`post(msg, transferables?)`). A throw is posted as the ordinary `{type: "error",
+message, jobId}`; built-in types cannot be overridden; a type with no handler is
+ignored.
+
+This is the seam through which a host adds a capability this open framework does not
+ship. The semantic mesh oracle — imported mesh → feature report, for rebuilding an
+STL parametrically — is one: it is a separate, closed package with its own CLI, and
+the app that installs it registers its job here. This repo carries nothing
+oracle-shaped: no verb, no message types, no error codes. The one direction that
+does exist is the oracle peer-depending on this package for `partforge/oracle`'s
+mesh/BVH helpers and file parsers (`bounds`, `meshArea`, `meshTriangles`, `parseStl`,
+`parse3MF`); those exports are part of its contract.
 
 
 ## Probes: measuring geometry into the report
@@ -1774,7 +1770,7 @@ framing offscreen at a resolution independent of the window size and devicePixel
 for gallery/preview images, where grabbing the live canvas would be capped at the viewer
 pane's pixel size:
 
-- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9 } = {}) → string | null` —
+- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {}) → string | null` —
   one offscreen render from the live camera's pose (position, up, and orbit target — not a
   canonical pose) with the live viewport's aspect ratio, `size` px on the long edge
   (clamped into `[256, maxTextureSize]`). Renders with 4× MSAA and the same
@@ -1787,6 +1783,16 @@ pane's pixel size:
   in the scene, so a dimensioned capture needs no special handling — enable measure
   mode (`runtime.measure.setEnabled(true)`) and call `captureCurrent()`; the dims are
   just part of the rendered frame.
+  `recenter: true` centres the part: the capture becomes the largest centred
+  sub-window of the current framing that still holds every visible vertex (equal
+  margins on both axes, rendered at the full `size` resolution through a view
+  offset, so it is a pixel-exact crop of what the user framed — same
+  perspective, no re-encode). The extent is the projection of the actual mesh
+  vertices, not a bounding box, so it is exact at any angle. The framing is
+  kept as-is when the geometry runs past any frame edge (a user who zoomed in
+  past the part's silhouette cropped it on purpose), when it is already centred,
+  or when measurement dimensions are pinned (their labels sit beside the part and
+  could otherwise be cut off).
 - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle
   counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.
@@ -1947,8 +1953,8 @@ 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`. The oracle half of this surface — `measure`, `verify`,
-`describe`, gaps, match scoring — is also published on its own as
+`npx vitest run`. The oracle half of this surface — `measure`, `verify`, 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:

package/docs/ERROR-PATTERNS.md

@@ -652,42 +652,6 @@ between the Manifold preview and the OCCT STEP export.
 
   The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
 
-## describe-oracle-unavailable
-
-- **Symptom:** A `describe` job answers `{"error": "oracle-unavailable"}`, or `partforge describe` exits with "describe needs the mesh-oracle package".
-- **Cause:** The semantic mesh oracle is a separate, closed package (`@pixiteapps/partforge-oracle`), and this app or shell doesn't have it: the worker was started without `runWorker(part, { loadOracle })`, or the CLI could not import the package.
-- **Fix:** Install the oracle package from the private registry and inject it — `runWorker(part, { loadOracle: () => import("@pixiteapps/partforge-oracle") })` in the app's worker file, or plain `npm install` for the CLI. In the oracle package's own repo, set `PARTFORGE_ORACLE` to a local path instead. Every other job (generate, export, inspect) works without it.
-
-## describe-not-manifold
-
-- **Symptom:** `describe` returns `{"error": "not-manifold"}`.
-- **Cause:** The mesh still has open edges after vertex-merge and winding repair, so it does not bound a solid and acceptance cannot diff against it.
-- **Fix:** Repair the mesh before describing it — Meshmixer, `meshlabserver`, or the slicer's own repair. `describe` will not repair geometry it was asked to report on; silently sealing a hole would make the report a description of a mesh the user does not have.
-
-## describe-too-large
-
-- **Symptom:** `{"error": "too-large"}` naming a triangle count.
-- **Cause:** Above 400,000 triangles the segmentation pass stops being usable in an interactive loop.
-- **Fix:** Decimate first. A CAD-exported STL re-exported at a coarser chord tolerance loses nothing the describer uses; the feature vocabulary reads surfaces, not facets.
-
-## describe-empty
-
-- **Symptom:** `{"error": "empty"}`.
-- **Cause:** The mesh has zero triangles — usually an import that resolved to an empty file, or a `k.import` name that registered as an error entry.
-- **Fix:** Check the `imports` source actually resolves. See [import-unknown-name](#import-unknown-name).
-
-## describe-budget-exceeded
-
-- **Symptom:** The report carries `warning: "budget-exceeded"` and `score.xorFraction` is higher than expected.
-- **Cause:** The acceptance loop hit its boolean budget before the residual converged. The report is partial but honestly scored — not wrong, just incomplete.
-- **Fix:** Raise `--budget`, or accept the partial description. A part needing far more than the default is usually one where a residual region is being attacked by many near-identical candidates; check `residual.regions` first.
-
-## describe-unreadable
-
-- **Symptom:** `{"error": "unreadable"}`.
-- **Cause:** `solid.toMesh()` threw rather than returning geometry — a corrupt or otherwise unrepresentable solid.
-- **Fix:** Confirm the source file parses cleanly upstream (`k.import` itself throws separately for an unparseable STL/3MF/STEP — see [import-unknown-name](#import-unknown-name)); re-export the file if the kernel cannot read back what it just built. STL is assumed to be in millimetres (the format carries no unit metadata) — see the import section of AUTHORING-PARTS.md.
-
 ## control-default-not-literal
 
 - **Symptom:** A control works live — the slider moves, the geometry updates — but the user's panel edits are gone when the part is reopened. Nothing throws anywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.85.4",
+  "version": "0.87.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/capture-frame.js

@@ -0,0 +1,118 @@
+// Framing math for the showcase capture (viewer.js captureCurrentFromScene):
+// where the visible geometry lands in the rendered frame, and the centred
+// sub-window that puts it in the middle. Pure three.js math, no GL — the
+// renderer builds its camera through makeCaptureCamera too, so what this
+// module projects through is exactly what renderOffscreen draws with.
+//
+// Why vertices and not bounding boxes: the projection of a triangle mesh is a
+// union of projected triangles, and a triangle's projected extremes are its
+// corners — so the min/max over projected VERTICES is the exact 2-D extent of
+// the rendered silhouette at any angle, where a projected 3-D bounding box
+// over-reports by up to the box's slack at diagonal views.
+//
+// Why a view offset and not a pixel crop: three's setViewOffset renders a
+// sub-window of a larger virtual frame with the same projection, so the
+// recentred image is a pixel-exact crop of what the user framed — at the full
+// requested resolution and with no second JPEG encode.
+import * as THREE from "three";
+
+const NEAR = 0.1;
+const FAR = 1000;
+
+// The temp camera an offscreen capture renders with. `aspect` is the FULL
+// frame's aspect; a recentred sub-window is applied afterwards by the caller
+// via setViewOffset, which (for a PerspectiveCamera) keeps this aspect as the
+// virtual full frame's. Matrices are updated so a caller can project through
+// matrixWorldInverse without a render having happened first.
+export function makeCaptureCamera(
+  { position, up, target },
+  { aspect = 1, fov = 45, projection = "perspective", orthoHalfH = 1 } = {},
+) {
+  const cam = projection === "orthographic"
+    ? new THREE.OrthographicCamera(-orthoHalfH * aspect, orthoHalfH * aspect, orthoHalfH, -orthoHalfH, NEAR, FAR)
+    : new THREE.PerspectiveCamera(fov, aspect, NEAR, FAR);
+  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]);
+  cam.updateMatrixWorld(true);
+  return cam;
+}
+
+// Exact 2-D extent of the meshes' projected vertices, as fractions of the
+// frame with a top-left origin ({ left, top, right, bottom }; values outside
+// [0, 1] mean the geometry runs past that edge). Null when there is nothing
+// to project, or when ANY vertex would be clipped by the frustum's near/far
+// planes or sits behind the camera — such a vertex is not in the picture, so
+// no honest extent exists and the caller should leave the framing alone.
+export function projectedExtent(camera, meshes) {
+  const toClip = new THREE.Matrix4();
+  const v = new THREE.Vector4();
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  let any = false;
+  for (const mesh of meshes ?? []) {
+    const pos = mesh?.geometry?.attributes?.position;
+    if (!pos || !pos.count) continue;
+    mesh.updateWorldMatrix(true, false);
+    toClip.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).multiply(mesh.matrixWorld);
+    for (let i = 0; i < pos.count; i++) {
+      v.set(pos.getX(i), pos.getY(i), pos.getZ(i), 1).applyMatrix4(toClip);
+      const w = v.w;
+      if (!(w > 0) || v.z < -w || v.z > w) return null;
+      const x = v.x / w, y = v.y / w;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      any = true;
+    }
+  }
+  if (!any) return null;
+  return { left: (minX + 1) / 2, right: (maxX + 1) / 2, top: (1 - maxY) / 2, bottom: (1 - minY) / 2 };
+}
+
+// The largest sub-window centred on the extent's centre that still fits the
+// frame, as { x, y, width, height } fractions. Centring on the extent with
+// maximal half-extents min(c, 1 - c) gives equal margins on both sides of each
+// axis and is guaranteed to contain the extent (which always lies within
+// [0, 2c] and [2c - 1, 1]). Null — leave the framing alone — when the extent
+// runs past any edge (the user zoomed in on purpose), when it already fills the
+// frame symmetrically (nothing to do), or when there is no usable extent.
+// `eps` forgives the ~1 px feature-edge line that can overhang a vertex.
+export function centeredCropView(extent, { eps = 0.002 } = {}) {
+  if (!extent) return null;
+  const { left, top, right, bottom } = extent;
+  if (![left, top, right, bottom].every(Number.isFinite)) return null;
+  if (left < -eps || top < -eps || right > 1 + eps || bottom > 1 + eps) return null;
+  if (!(right > left) || !(bottom > top)) return null;
+  const cx = (left + right) / 2, cy = (top + bottom) / 2;
+  const hw = Math.min(cx, 1 - cx), hh = Math.min(cy, 1 - cy);
+  if (hw >= 0.5 - eps && hh >= 0.5 - eps) return null;
+  return { x: Math.max(0, cx - hw), y: Math.max(0, cy - hh), width: 2 * hw, height: 2 * hh };
+}
+
+// Turn a fractional crop of a frame with the given aspect into what
+// renderOffscreen needs: the output size (crop rendered at `long` px on its
+// long edge, so recentring costs no resolution) and the setViewOffset
+// arguments describing it as a sub-window of a larger virtual frame.
+export function cropRenderFrame(crop, { aspect, long }) {
+  const cropAspect = (crop.width * aspect) / crop.height;
+  const width = cropAspect >= 1 ? long : Math.max(1, Math.round(long * cropAspect));
+  const height = cropAspect >= 1 ? Math.max(1, Math.round(long / cropAspect)) : long;
+  const fullWidth = width / crop.width;
+  const fullHeight = height / crop.height;
+  return {
+    width, height,
+    viewOffset: { fullWidth, fullHeight, x: crop.x * fullWidth, y: crop.y * fullHeight },
+  };
+}
+
+// The whole pipeline for captureCurrentFromScene: the render frame that puts
+// the visible geometry in the middle, or null when the current framing should
+// be kept as-is (part cropped by the viewport, already centred, or nothing to
+// measure). `meshes` are the visible sub-part meshes; the camera parameters
+// must be the same ones the render will use.
+export function recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }) {
+  const camera = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+  const crop = centeredCropView(projectedExtent(camera, meshes));
+  return crop ? cropRenderFrame(crop, { aspect, long }) : null;
+}

package/src/framework/jobs.js

@@ -26,22 +26,16 @@ const loadInspect = () => Promise.all([
   import("./oracle/verify.js"),
 ]);
 
-// The DESCRIBE stack is not part of this package at all: the semantic mesh oracle
-// lives in a separate, closed package, and this open framework never names it. A
-// host that has it INJECTS a loader — `runWorker(part, { loadOracle })`, threaded
-// here as `opts.loadOracle`, resolving to the oracle package's barrel (describe,
-// describeMemo, compactDescribe). Injection rather than a bare import specifier is
-// deliberate: a literal `import("@scope/pkg")` in open source would fail every
-// downstream Vite build where the package isn't installed, while an injected thunk
-// is simply absent — and an absent oracle answers the job with the structured
-// `oracle-unavailable` report below instead of stalling or throwing.
-
-// 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;
+// HOST JOBS — the extension seam. A host registers its own job types with
+// `runWorker(part, { jobs: { <type>: handler } })`, threaded here as `opts.jobs`, and
+// a message whose type matches no built-in below is handed to that handler with the
+// live kernel, the current part, the message and the poster. This is how a host adds
+// a capability the open framework does not ship — partforge-cloud's semantic
+// mesh-oracle describe job lives entirely in its own closed package and arrives here
+// as one of these — without this repo naming it, importing it, or knowing its message
+// shapes. Built-ins win a name clash (a host cannot redefine `generate`); a type with
+// no handler at all is ignored, as unknown types always were. A handler's throw is
+// posted as the ordinary `{type: "error"}` any failed job posts.
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -414,47 +408,8 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       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") {
-      // Semantic description of an IMPORTED mesh — not of the built part. The two are
-      // different questions: `inspect` asks "what did this source build?", `describe`
-      // asks "what is this file?". describe never touches the part's own geometry, which
-      // is why it takes an import name rather than a view.
-      //
-      // 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.
-      if (!opts.loadOracle) {
-        // Same closed-set, returned-not-thrown error contract describe itself keeps
-        // (its errors are findings, not crashes) — shaped as the structured triple the
-        // whole repo emits, so a caller can act on the code. ERROR-PATTERNS.md#describe-
-        // oracle-unavailable carries the fix.
-        post({ type: "describe-report", report: {
-          error: "oracle-unavailable",
-          detail: "this app was built without the mesh oracle package",
-          diagnostic: {
-            cause: "the describe job needs the closed oracle package, and no loadOracle loader was injected into runWorker",
-            location: `describe "${msg.importName}"`,
-            correctiveAction: "install the oracle package and pass runWorker(part, { loadOracle: () => import(...) }); see ERROR-PATTERNS.md#describe-oracle-unavailable",
-          },
-          source: { name: msg.importName, digest: null },
-        } });
-        return;
-      }
-      const { describe: describeMesh, describeMemo, compactDescribe } = await opts.loadOracle();
-      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,
-        budget: msg.budget,
-        memo: DESCRIBE_MEMO,
-      });
-      // The compact shape is derived, never memoised separately: one memo entry per
-      // mesh, two views of it, no way for the two to drift.
-      post({ type: "describe-report", report: msg.compact ? compactDescribe(full) : full });
+    } else if (opts.jobs && Object.hasOwn(opts.jobs, msg.type)) {
+      await opts.jobs[msg.type](kernel, part, msg, post, { isStale: opts.isStale });
     }
   } catch (err) {
     // `subparts` (generate jobs only) tells the reroute policy which sub-parts the

package/src/framework/mount.js

@@ -75,7 +75,15 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // Offscreen render of a named view (default when omitted, or on an unknown name).
     captureView,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
-    captureCurrent: (opts) => viewer.captureCurrent(opts),
+    // `recenter` reads the sub-part geometry only, so with measurement pins on
+    // screen the dimension labels — which sit beside the part, not on it —
+    // could land outside the centred window. A dimensioned capture therefore
+    // keeps the user's exact framing; a host wanting both re-frames first.
+    captureCurrent: (opts) => viewer.captureCurrent(
+      opts?.recenter && (measure ?? NOOP_MEASURE).isEnabled() && (measure ?? NOOP_MEASURE).pinCount() > 0
+        ? { ...opts, recenter: false }
+        : opts,
+    ),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —

package/src/framework/viewer.js

@@ -9,6 +9,7 @@ import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
 import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
+import { makeCaptureCamera, recenteredView } from "./capture-frame.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
 // three renders into a render target in the LINEAR working colour space: as of r184
@@ -98,9 +99,17 @@ export function thumbnailBackground(background = THUMBNAIL_BG) {
 // context: pose comes from the live camera (never a canonical pose), the output
 // long edge is `size` clamped into [256, maxTextureSize], and the short edge
 // follows the live camera's aspect so the capture matches what the user framed.
+//
+// `recenter: true` (opt-in; the default keeps the exact viewport framing) renders
+// the largest centred sub-window that still holds every visible vertex — a
+// showcase image with the part in the middle and equal margins — and leaves the
+// framing alone when the geometry runs off the frame, since a user who zoomed
+// past the part's edge framed that crop on purpose. The extent is projected
+// through the same camera the render uses (capture-frame.js), so it is exact;
+// `meshes` are the visible sub-part meshes it reads.
 export function captureCurrentFromScene(
-  { size = 2048, hideGrid = true, quality = 0.9 } = {},
-  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH },
+  { size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {},
+  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH, meshes },
 ) {
   const MIN_SIZE = 256;
   // WebGL2 guarantees MAX_TEXTURE_SIZE >= 2048; only trust a larger reported cap.
@@ -115,17 +124,20 @@ export function captureCurrentFromScene(
     || 1;
   const width = aspect >= 1 ? long : Math.max(1, Math.round(long * aspect));
   const height = aspect >= 1 ? Math.max(1, Math.round(long / aspect)) : long;
+  const pose = { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target };
+  // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
+  // CANONICAL capture path deliberately never passes either — agent-facing
+  // renders stay perspective regardless of what the user is looking at.
+  const fov = liveCamera.fov ?? 45;
+  // Null means "keep the viewport framing": part cropped by the viewport,
+  // already centred, or nothing to measure.
+  const frame = (recenter && recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }))
+    || { width, height };
   const before = liveCamera.position.clone();
   const gridWasVisible = grid?.visible;
   if (grid && hideGrid) grid.visible = false;
   try {
-    return renderer.renderOffscreen(
-      { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target },
-      // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
-      // CANONICAL capture path deliberately never passes either — agent-facing
-      // renders stay perspective regardless of what the user is looking at.
-      { width, height, fov: liveCamera.fov ?? 45, quality, projection, orthoHalfH },
-    );
+    return renderer.renderOffscreen(pose, { ...frame, fov, quality, projection, orthoHalfH });
   } finally {
     if (grid && hideGrid) grid.visible = gridWasVisible;
     liveCamera.position.copy(before); // belt-and-suspenders: never leak camera state
@@ -822,9 +834,15 @@ export function createViewer(container, part) {
   // the mask silently no-ops and every cap floods its whole plane with hatch —
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
-  function renderOffscreen({ position, up, target },
+  //
+  // `viewOffset` ({ fullWidth, fullHeight, x, y }) renders the width×height
+  // output as that sub-window of a larger virtual frame — the recentred
+  // showcase capture (captureCurrentFromScene). The camera's aspect is then the
+  // VIRTUAL frame's, so the projection is exactly the un-offset one and the
+  // output is a pixel-exact crop of what the user framed.
+  function renderOffscreen(pose,
                            { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9,
-                             projection = "perspective", orthoHalfH = 1 } = {},
+                             projection = "perspective", orthoHalfH = 1, viewOffset } = {},
                            renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
@@ -832,15 +850,13 @@ export function createViewer(container, part) {
       : new THREE.WebGLRenderTarget(width, height, RT_OPTIONS);
     _capLights = _capLights ?? createCaptureLights();
     // Canonical captures never pass `projection`, so agent-facing renders and
-    // the CLI stay perspective no matter what the user is looking at.
-    const cam = projection === "orthographic"
-      ? new THREE.OrthographicCamera(
-          -orthoHalfH * (width / height), orthoHalfH * (width / height),
-          orthoHalfH, -orthoHalfH, 0.1, 1000)
-      : new THREE.PerspectiveCamera(fov, width / height, 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]);
+    // the CLI stay perspective no matter what the user is looking at. Built
+    // through the same helper the recentring math projects through, so the two
+    // can never disagree about where a vertex lands.
+    const aspect = viewOffset ? viewOffset.fullWidth / viewOffset.fullHeight : width / height;
+    const cam = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+    if (viewOffset) cam.setViewOffset(viewOffset.fullWidth, viewOffset.fullHeight, viewOffset.x, viewOffset.y, width, height);
+    const { position, up, target } = pose;
     const buf = new Uint8Array(width * height * 4);
     // 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
@@ -923,6 +939,9 @@ export function createViewer(container, part) {
       target: controls.target.toArray(),
       grid,
       maxTextureSize: renderer.capabilities?.maxTextureSize,
+      // For `recenter`: the geometry that is actually in the picture. Sub-part
+      // meshes only — dimension labels and section caps are overlays on them.
+      meshes: Object.values(subMesh).filter((m) => m.visible),
       projection: projectionMode,
       // Divided by zoom, because OrbitControls dollies an ortho camera with
       // `zoom` and leaves the frustum alone: the raw frustum is the un-dollied

package/src/framework/worker.js

@@ -36,9 +36,9 @@ async function occtKernel() {
   return createOcctKernel(replicad);
 }
 
-// `opts.loadOracle` — the injection seam for the closed mesh-oracle package (see
-// jobs.js's describe branch): a thunk resolving to the oracle barrel. Apps without
-// the package simply omit it and describe jobs answer `oracle-unavailable`.
+// `opts.jobs` — host-registered job handlers, `{ <type>: (kernel, part, msg, post,
+// ctx) => … }` (see jobs.js's HOST JOBS comment). A message type no built-in claims
+// goes to the matching handler; apps with nothing to add simply omit it.
 export function runWorker(part, opts = {}) {
   const backend = self.name === "occt" ? "occt" : "manifold";
   let manifold = null; // { preview, print }
@@ -102,7 +102,7 @@ export function runWorker(part, opts = {}) {
           const kernel = await kernelFor(job.data);
           // handle() declares each message's transferables (the big binary buffers).
           const post = (m, transfer = []) => postMessage(m, transfer);
-          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, loadOracle: opts.loadOracle }); continue; }
+          if (job.epoch === null) { await handle(kernel, job.part, job.data, post, { importMeshes, jobs: opts.jobs }); continue; }
           const isStale = () => job.epoch !== epoch;
           // Post gate. The boundary check cannot catch a generate that goes stale during
           // its FINAL sub-part — there is no boundary after it — nor a single-sub-part
@@ -111,7 +111,7 @@ export function runWorker(part, opts = {}) {
           // contract simple: a `meshes` post is current as of the moment it is posted.
           const gated = (m, transfer = []) =>
             (m.type === "meshes" && isStale() ? post({ type: "superseded" }) : post(m, transfer));
-          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, loadOracle: opts.loadOracle });
+          await handle(kernel, job.part, job.data, gated, { isStale, importMeshes, jobs: opts.jobs });
         } catch (err) {
           // Same shape jobs.js posts for a failed build, so hosts need no new branch.
           // Carry the job's jobId when it has one (capture/export are correlated by it):

package/src/oracle.js

@@ -9,11 +9,11 @@
 // test/oracle-entry.test.js walks the closure and holds that, so the entry stays
 // importable from a worker, a browser, or Node alike.
 //
-// The SEMANTIC MESH ORACLE (`describe`) is NOT here: it lives in its own closed
-// package, which peer-depends on this one and consumes exactly this entry — the
-// mesh/BVH helpers and file parsers below are exported for it. The framework
-// reaches it only through injection (`runWorker(part, { loadOracle })`, jobs.js)
-// and the CLI resolves it at call time; neither ever bundles it.
+// The SEMANTIC MESH ORACLE (imported mesh -> feature report) is NOT here, and this
+// framework has no verb, job or import for it: it is its own closed package, which
+// peer-depends on this one and consumes exactly this entry — the mesh/BVH helpers
+// and file parsers below are exported for it. A host that installs it registers its
+// job through the generic `runWorker(part, { jobs })` seam (jobs.js).
 export { assemblyGaps, meshGaps } from "./framework/oracle/gaps.js";
 export { meshVolume, bboxSize, bounds, meshArea } from "./framework/oracle/mesh.js";
 export { buildView } from "./framework/oracle/build.js";

package/types/index.d.ts

@@ -146,6 +146,14 @@ export interface CaptureCurrentOptions {
   hideGrid?: boolean;
   /** JPEG quality, 0..1. */
   quality?: number;
+  /**
+   * Centre the visible geometry: render the largest centred sub-window of the
+   * current framing that still holds every visible vertex (equal margins, full
+   * `size` resolution). When the geometry runs past a frame edge — the user
+   * zoomed in on purpose — or dimensions are pinned, the framing is kept as-is.
+   * Default false.
+   */
+  recenter?: boolean;
 }
 
 export interface CaptureViewOptions {

package/types/worker.d.ts

@@ -17,13 +17,29 @@ export interface WorkerHandle {
   setPart(newPart: PartDefinition): void;
 }
 
+/**
+ * A host-registered job handler (`runWorker`'s `opts.jobs`): receives the live
+ * kernel, the part current when the message arrived, the message itself, the
+ * poster for results (`post(msg, transferables?)`), and a context with `isStale`
+ * (set for jobs that can be superseded by a rebind). A throw is posted as the
+ * ordinary `{type: "error", message, jobId}`.
+ */
+export type HostJob = (
+  kernel: unknown,
+  part: PartDefinition,
+  msg: { type: string; jobId?: number; [key: string]: unknown },
+  post: (msg: object, transfer?: Transferable[]) => void,
+  ctx: { isStale?: () => boolean },
+) => void | Promise<void>;
+
 /**
  * Run the worker job loop for `part`. Call once, at worker module top level.
- * `opts.loadOracle` injects the closed semantic-mesh-oracle package (a thunk
- * resolving its barrel: `describe`, `describeMemo`, `compactDescribe`); omitted,
- * describe jobs answer with a structured `oracle-unavailable` report.
+ * `opts.jobs` registers host job types by message `type`: a message no built-in
+ * job claims is handed to the matching handler; built-ins are not overridable and
+ * a type with no handler is ignored. This is how a host adds capabilities the open
+ * framework does not ship.
  */
 export function runWorker(
   part: PartDefinition,
-  opts?: { loadOracle?: () => Promise<{ describe: Function; describeMemo: () => Map<string, unknown>; compactDescribe: Function }> },
+  opts?: { jobs?: Record<string, HostJob> },
 ): WorkerHandle;