partforge 0.62.1 → 0.64.0

package/src/parts/import-demo.js

@@ -0,0 +1,134 @@
+// Reference part for docs/AUTHORING-PARTS.md's "Importing geometry" section —
+// the worked example for BOTH import uses in one part:
+//   • reference — `ref` is a translucent ghost of the imported scan (never
+//     exported); `body` is a parametric rebuild of the same block, bound to
+//     the scan via `reference: "scan"` and held to it by the three ref*
+//     deviation metrics in `verify.expect.body`.
+//   • component — `mount` uses the import as a real boolean tool: a plate
+//     with a through-socket cut to the scan's own shape (scaled up by `fit`
+//     for clearance), exported like any other sub-part.
+// `src/parts/assets/import-demo-scan.stl` is a small hand-written ascii STL —
+// a 20×14×8 mm block, origin-cornered, outward-wound. `body`'s defaults
+// reproduce those dimensions exactly, so the deviation gate passes with real
+// margin. Open /import-demo.html after `npm run dev`.
+export default {
+  meta: { title: "Import demo", units: "mm", background: 0x15181d },
+  imports: {
+    scan: new URL("./assets/import-demo-scan.stl", import.meta.url),
+  },
+  parameters: [
+    {
+      id: "scan",
+      title: "Scan",
+      description: "Dimensions of the parametric rebuild (`body`). Defaults match the imported reference block exactly — drag one and watch the deviation gate in `partforge measure` react.",
+      advanced: [
+        { key: "scanW", label: "Width", unit: "mm", min: 10, max: 40, step: 0.5,
+          description: "Rebuild width (X). Matches the scan's width at the default." },
+        { key: "scanD", label: "Depth", unit: "mm", min: 10, max: 40, step: 0.5,
+          description: "Rebuild depth (Y). Matches the scan's depth at the default." },
+        { key: "scanH", label: "Height", unit: "mm", min: 4, max: 20, step: 0.5,
+          description: "Rebuild height (Z). Matches the scan's height at the default." },
+      ],
+    },
+    {
+      id: "mount",
+      title: "Mount",
+      description: "A plate with a through-socket cut to the scan's own shape — the import used as a real boolean component, not just a reference.",
+      advanced: [
+        { key: "fit", label: "Socket clearance", unit: "×", min: 1, max: 1.2, step: 0.01,
+          description: "Uniform scale applied to the imported scan before it's used as the cutting tool, so the block seats with a slip fit." },
+        { key: "margin", label: "Plate margin", unit: "mm", min: 1, max: 10, step: 0.5,
+          description: "Solid plate border kept around the socket on every side." },
+        // The socket is the scan's own (fixed, ~8mm-tall) imported geometry scaled
+        // by `fit` and overcut 1mm past the plate's bottom face — see `mount.build`
+        // below. It only stays a genuine through-hole (not a blind pocket) while
+        // plateH < scanH*fit - 1; at the worst-case corner (fit at its slider
+        // minimum, 1) that's plateH < 7. max is capped at 6.5, half a millimetre
+        // inside that bound, so every reachable (plateH, fit) combination — not
+        // just the defaults — keeps `mount: { holes: 1 }` true.
+        { key: "plateH", label: "Plate thickness", unit: "mm", min: 2, max: 6.5, step: 0.5,
+          description: "Mount plate thickness. The socket cuts all the way through it." },
+        { key: "gap", label: "Gap from rebuild", unit: "mm", min: 5, max: 30, step: 1,
+          description: "Presentation-only spacing between `body` and `mount` in the assembly view, so the two never overlap." },
+      ],
+    },
+  ],
+  defaults: { scanW: 20, scanD: 14, scanH: 8, fit: 1.05, margin: 3, plateH: 4, gap: 10 },
+  // mountOffsetX: how far along X the mount plate sits from the rebuild, so
+  // the two solids never interpenetrate regardless of the current dimensions.
+  derive: (p) => ({ mountOffsetX: p.scanW + p.gap }),
+  parts: {
+    // Ghost overlay of the raw import — ref* deviation is computed against
+    // this by name (`reference: "scan"` on `body`, below) regardless of which
+    // view is active, so `ref` only needs to appear in the "reference" view,
+    // where it's shown translucent over `body` for visual alignment checking.
+    // It is deliberately absent from "assembly": measure()'s `ok` requires
+    // zero sub-part overlaps in the measured view, and a ghost coincident
+    // with its rebuild always overlaps by design.
+    ref: {
+      label: "Reference (ghost)",
+      views: ["reference"],
+      exportable: false,
+      display: { opacity: 0.3 },
+      build: (k) => k.import("scan"),
+    },
+    // Parametric rebuild of the scanned block. `reference: "scan"` tells
+    // measure() to compute deviation facts (xorVolume / volumeDeltaPct /
+    // bboxDelta) against the import; verify.expect.body below gates on them.
+    // Shown in both views: alone (fitted with `mount`) in "assembly", and
+    // against the ghost in "reference".
+    body: {
+      label: "Rebuild",
+      views: ["assembly", "reference"],
+      export: { name: "body" },
+      reference: "scan",
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }),
+    },
+    // The import used as a real component: a plate with a through-socket cut
+    // to the (clearance-scaled) scan shape. Offset along X so it never
+    // overlaps `body` in the assembly view.
+    mount: {
+      label: "Mount plate",
+      views: ["assembly"],
+      export: { name: "mount" },
+      build: (k, p, d) => {
+        const plate = k.box({
+          min: [d.mountOffsetX - p.margin, -p.margin, -p.plateH],
+          max: [d.mountOffsetX + p.scanW * p.fit + p.margin, p.scanD * p.fit + p.margin, 0],
+        });
+        const socket = k.import("scan")
+          .scale(p.fit)
+          .translate([d.mountOffsetX, 0, -p.plateH - 1]); // overcut past both plate faces
+        return plate.cut(socket);
+      },
+    },
+  },
+  // "assembly" is first so `measure`/`verify`/`render` (which default to the
+  // first view key) see only the two real, non-overlapping parts — `mount`'s
+  // socket never touches `body` (see `mountOffsetX`). "reference" is the
+  // ghost-overlay view, browsed by hand or with an explicit view argument.
+  views: { assembly: { label: "Assembly" }, reference: { label: "Reference overlay" } },
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      body: {
+        holes: 0,
+        watertight: true,
+        bbox: "<=[30,20,15]",
+        // Deviation gate: at the defaults, body reproduces the scan's exact
+        // box dimensions, so all three read near-zero — thresholds below
+        // leave real margin rather than sitting on the exact values.
+        refXorVolume: "<=5mm3",
+        refVolumeDeltaPct: "<=1",
+        refBboxDelta: "<=[0.2,0.2,0.2]",
+      },
+      mount: { holes: 1, watertight: true, bbox: "<=[40,25,10]" },
+      // Checked against the default ("assembly") view only — `body` and
+      // `mount` are real, non-overlapping parts by construction (see
+      // `mountOffsetX`). The "reference" view's ghost is deliberately
+      // coincident with `body` (that's the point of the overlay) and would
+      // always read overlaps > 0, which is why it isn't the default view.
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/assets.js

@@ -0,0 +1,19 @@
+// Node-side source mapping for part asset declarations (fonts + imports):
+// framework resolvers use global fetch, which cannot read file: URLs in Node,
+// so map those to bytes here before handing the decl down. Everything else
+// (http(s) strings, bytes, thunks) passes through untouched.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function nodeAssetSources(decl) {
+  if (!decl) return decl;
+  const out = {};
+  for (const [name, src] of Object.entries(decl)) {
+    const u = src instanceof URL ? src : typeof src === "string" && src.startsWith("file:") ? new URL(src) : null;
+    if (u?.protocol === "file:") {
+      const b = readFileSync(fileURLToPath(u));
+      out[name] = b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+    } else out[name] = src;
+  }
+  return out;
+}

package/src/testing/manifold.js

@@ -4,12 +4,24 @@
 import Module from "manifold-3d";
 import { createManifoldKernel } from "../framework/geometry/manifold-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
+import { ensureImports } from "../framework/imports.js";
+import { nodeAssetSources } from "./assets.js";
+import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
   if (fonts) { const opentype = (await import("opentype.js")).default;
-    for (const [name, buf] of await resolveFonts(fonts)) kernel._fonts.set(name, opentype.parse(buf)); }
+    for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, opentype.parse(buf)); }
+  if (imports) {
+    const decl = nodeAssetSources(imports);
+    const { resolveImports } = await import("../framework/imports.js");
+    const resolved = await resolveImports(decl);
+    const stepEntries = [...resolved].filter(([, a]) => a.format === "step")
+      .map(([name, a]) => ({ name, bytes: a.bytes, digest: a.digest }));
+    const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
+    await ensureImports(kernel, decl, meshes);
+  }
   return kernel;
 }

package/src/testing/occt.js

@@ -6,8 +6,10 @@ import path from "path";
 import fs from "fs";
 import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
+import { ensureImports } from "../framework/imports.js";
+import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -17,6 +19,7 @@ export async function bootOcctKernel({ fonts } = {}) {
   replicad.setOC(OC);
   const kernel = createOcctKernel(replicad);
   if (fonts) { const opentype = (await import("opentype.js")).default;
-    for (const [name, buf] of await resolveFonts(fonts)) kernel._fonts.set(name, opentype.parse(buf)); }
+    for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, opentype.parse(buf)); }
+  if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
   return kernel;
 }

package/src/testing/step-mesh-thread.js

@@ -0,0 +1,15 @@
+// src/testing/step-mesh-thread.js — runs INSIDE the worker_thread only.
+import { parentPort, workerData } from "node:worker_threads";
+import { bootOcctKernel } from "./occt.js";
+
+const kernel = await bootOcctKernel();
+const out = [];
+const transfer = [];
+for (const { name, bytes, digest } of workerData) {
+  await kernel._registerImport({ name, digest, step: bytes });
+  const { positions, indices } = kernel.import(name).toIndexedMesh({ quality: "print" });
+  out.push({ name, digest, positions, indices });
+  transfer.push(positions.buffer, indices.buffer);
+}
+parentPort.postMessage(out, transfer);
+process.exit(0);

package/src/testing/step-mesh.js

@@ -0,0 +1,17 @@
+// STEP → triangle mesh for the Node crossover (Manifold part importing STEP).
+// OCCT boots in a worker_thread — a separate isolate is a separate WASM world,
+// so the "never both kernels in one process" invariant holds by construction.
+import { Worker } from "node:worker_threads";
+
+export function tessellateStepAssets(entries) {
+  return new Promise((resolve, reject) => {
+    const w = new Worker(new URL("./step-mesh-thread.js", import.meta.url),
+      { workerData: entries.map(({ name, bytes, digest }) => ({ name, bytes, digest })) });
+    w.once("message", (out) => {
+      resolve(new Map(out.map((m) => [m.name, { digest: m.digest, positions: m.positions, indices: m.indices }])));
+      w.terminate();
+    });
+    w.once("error", reject);
+    w.once("exit", (code) => { if (code !== 0) reject(new Error(`step tessellation thread exited ${code}`)); });
+  });
+}

package/types/kernel.d.ts

@@ -269,6 +269,12 @@ export interface Solid {
    * Closed (no open face) hollows are not supported.
    */
   shell(o: { t: number; open: FaceSelector }): Solid;
+  /**
+   * Morphological close-then-open with a ball of radius `r`: rounds EVERY edge
+   * (convex and concave). Implemented natively on both backends — never routes,
+   * never throws `KernelCapabilityError`. `roundAll(0)` is the identity.
+   */
+  roundAll(r: number | { r: number }): Solid;
   /** Through-hole count (Manifold only). */
   genus?(): number;
   /** No geometry at all (Manifold only). */
@@ -471,6 +477,12 @@ export interface GeometryKernel {
   hullChain(inputs: HullInput[]): Shape2D;
   /** STEP bytes — OCCT only (Manifold throws `KernelCapabilityError`). */
   toSTEP(named: Array<{ name: string; solid: Solid }>): Promise<ArrayBuffer>;
+  /**
+   * Imported geometry declared in the part's `imports` field, registered
+   * pre-build by the framework via the underscore-prefixed `_registerImport`
+   * side-channel (not a part author's calling surface).
+   */
+  import(name: string): Solid;
 
   // Backend-optional: the sub-part cache brackets and WASM lifetime hooks. Every
   // framework caller reaches these through `?.`, so a third-party backend may

package/types/part.d.ts

@@ -300,6 +300,14 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
   enabled?: (p: P) => unknown;
   /** `false` = reference/preview-only: shown in the viewer, never exported. */
   exportable?: boolean;
+  /**
+   * Name of a declared `imports` entry this sub-part is held to. When set,
+   * `measure()` computes a `deviation` fact (symmetric-difference volume,
+   * volume delta %, bbox-corner drift) against that import's posed solid, and
+   * `verify.expect.<subpart>` may use the `refXorVolume` / `refVolumeDeltaPct`
+   * / `refBboxDelta` gate metrics.
+   */
+  reference?: string;
   /** Viewer-only override — `color` is `0xRRGGBB`, `opacity` is 0..1. */
   display?: { color?: number; opacity?: number };
   /** Filename / object name on export; defaults to the key. */
@@ -362,6 +370,12 @@ export interface SubPartExpectations {
   boundsMin?: Expectation;
   boundsMax?: Expectation;
   minWall?: Expectation;
+  /** Symmetric-difference volume vs. the sub-part's declared `reference` import. */
+  refXorVolume?: Expectation;
+  /** Percent volume delta vs. the sub-part's declared `reference` import. */
+  refVolumeDeltaPct?: Expectation;
+  /** Bounding-box corner drift `[dx, dy, dz]` vs. the sub-part's declared `reference` import. */
+  refBboxDelta?: Expectation;
 }
 
 /**