partforge 0.63.0 → 0.64.0

package/bin/cli.js

@@ -80,10 +80,9 @@ async function loadPart(partPath, usage) {
 // otherwise a part using a named font builds in the browser but dies headlessly
 // with `text2d: unknown font …`.
 const bootKernel = (part) => {
+  const opts = { fonts: part.fonts, imports: part.imports };
   const backend = process.env.PARTFORGE_BACKEND || detectBackend(part); // env: crash()'s NEEDS_OCCT retry
-  return backend === "occt"
-    ? bootOcctKernel({ fonts: part.fonts })
-    : bootManifoldKernel({ fonts: part.fonts });
+  return backend === "occt" ? bootOcctKernel(opts) : bootManifoldKernel(opts);
 };
 
 const commands = {

package/docs/AUTHORING-PARTS.md

@@ -73,6 +73,7 @@ export default {
   parameters,                              // the control-panel schema (array of sections — see below)
   defaults,                                // flat { paramKey: value } — seeds params + control values
   fonts?,                                  // { name: source } — fonts a part's k.text2d() needs; framework preloads before build (see below)
+  imports?,                                // { name: source } — STEP/STL/3MF files a part's k.import() needs; same preload timing as fonts (see below)
   derive?,                                 // (p) => d, or { group: (p, d) => {…}, … } — dependent values computed once per build
   parts: {                                 // named sub-parts; each builds ONE solid
     <name>: {
@@ -83,6 +84,7 @@ export default {
       enabled?: (p) => boolean,            // optional — gate a conditional sub-part
       display?: { color?, opacity? },      // optional viewer-only override (0xRRGGBB / 0..1) — e.g. a reference/ghost part
       export?: { name },                   // filename/object name on export; defaults to the key
+      reference?: string,                  // name of a declared import — measure() computes a deviation fact against it (see below)
     },
   },
   views: { <name>: { label, default?, animations? } },  // view tabs; a view may own animations (below)
@@ -126,6 +128,10 @@ export default {
   })` can look the font up by name. See `src/framework/fonts.js` (`resolveFonts`) and
   `k.text2d` in `docs/KERNEL-CONTRACT.md` for the full contract; fuller authoring guidance
   (recommended font sourcing, licensing notes) lands in a follow-up pass.
+- `imports` declares the STEP/STL/3MF files a part's `k.import()` calls need, same source
+  grammar and preload timing as `fonts` above. See "Importing geometry (STEP/STL/3MF)"
+  below for the full contract — backend matrix, units, the `reference` field + the
+  deviation gate, and caching.
 
 ---
 
@@ -1317,6 +1323,121 @@ Both backends produce watertight emboss/deboss geometry; the difference is expor
 
 ---
 
+## Importing geometry (STEP/STL/3MF)
+
+`k.import(name)` returns a previously-registered imported file as an ordinary `Solid` — the same handle a `k.box()` or `k.loft()` call would give you. It exists for two uses: a **reference** the agent workflow measures and rebuilds a parametric part around (with a verify-time deviation gate holding the rebuild to it), or a **component** — a real body that participates in booleans, scaling, and export like any other solid. `src/parts/import-demo.js` is the worked example for both; read it alongside this section.
+
+**Declaring imports (the `imports` PartDefinition field):**
+
+Exactly the `fonts` grammar, one level up in the contract — a map of names to sources:
+
+```js
+imports: {
+  scan: new URL("./assets/import-demo-scan.stl", import.meta.url), // Vite serves it; Node reads disk
+  lid:  "https://…/signed-url.step",                               // URL string
+  chip: bytesOrThunk,                                               // ArrayBuffer/Uint8Array, or a (possibly async) thunk returning one
+},
+```
+
+The framework resolves these — fetch/read bytes, detect the format (filename extension when the source has one; a magic-bytes sniff otherwise — the `ISO-10303-21` STEP header, a `PK` zip signature for 3MF, else STL), and content-hash them — before the synchronous `build` runs, registering the parsed result on the kernel through an underscore-prefixed side-channel (see `docs/KERNEL-CONTRACT.md` § "Conformance classes"). Reference an import by name: `k.import("scan")`. An undeclared name throws (mirrors `text2d`'s unknown-font error) — see [ERROR-PATTERNS.md#import-unknown-name](ERROR-PATTERNS.md#import-unknown-name).
+
+**Backend matrix:**
+
+- **STEP on OCCT** — native: `replicad.importSTEP` builds a real B-rep, exact into STEP export.
+- **STEP on Manifold** — tessellated transparently: the framework routes an OCCT-worker tessellation pass behind the scenes (the "crossover" — see caching, below) and hands Manifold the resulting triangle mesh. Exactness is lost on this path; the STEP curves become facets at print quality, same as any other mesh geometry.
+- **STL/3MF on Manifold** — native: parsed, repaired (vertex merge + winding/orientation fix), and handed to `Manifold.ofMesh`. A mesh still non-manifold after repair throws loudly with the open-edge count — see [ERROR-PATTERNS.md#import-mesh-not-solid](ERROR-PATTERNS.md#import-mesh-not-solid).
+- **STL/3MF on OCCT** — never attempted: mesh-to-B-rep conversion isn't in scope for v1. Declaring a mesh import on a part (or sub-part, under per-sub-part routing) that routes to OCCT is an error — see [ERROR-PATTERNS.md#import-mesh-on-occt](ERROR-PATTERNS.md#import-mesh-on-occt).
+
+`import` is not in `OCCT_ONLY_OPS` — a STEP import does not by itself force OCCT routing (the crossover exists precisely so it doesn't have to); backend selection is still driven by `fillet`/`chamfer`/`shell` on a `Solid`, or `meta.backend`.
+
+**Units:** everything normalizes to millimetres at parse time — STEP units are honored by the OCCT importer, a 3MF file's `unit` attribute is converted, and **STL is assumed to already be in millimetres** (the format carries no unit metadata).
+
+**Registration is total; errors are lazy.** Every declared import registers on whichever kernel runs a job, regardless of whether that kernel can actually use it — this is what keeps a mixed-format part (an OCCT sub-part and a Manifold sub-part with different import formats) from having one format's registration break the other's job. A format the running kernel can't use registers as an **error entry** instead of throwing at registration; the error throws from `k.import(name)` itself, at the point in a `build` that actually calls it. Two cases surface this way:
+
+- **mesh import on OCCT** — throws immediately, every time (see the backend matrix above).
+- **unprimed STEP import on Manifold** — throws once, then self-heals: the framework's crossover machinery notices, arranges the OCCT-side tessellation (a `tessellate-imports` worker job in the browser, a `node:worker_threads` hop in the CLI/tests, since the two WASM kernels may never share a process), and retries the build. A build whose params never actually reach a `k.import()` call on that STEP file never triggers the crossover at all — the cost is paid only when the import is really used. If the crossover itself fails to produce a usable mesh, that surfaces as [ERROR-PATTERNS.md#import-step-tessellation-failed](ERROR-PATTERNS.md#import-step-tessellation-failed).
+
+**Caching & content-stability:** import sources are **content-stable for a session** — the same rule as `fonts`. Bytes are memoized process-wide by source identity (not by digest) the first time a source resolves, and stay resident for the life of that worker/process: the raw bytes in the resolver's cache, and the parsed master (a Manifold mesh or an OCCT B-rep shape) in the kernel that parsed it. A multi-megabyte STEP or STL file is read and parsed once, not on every slider drag or view switch — but it also means a changed file on disk needs a fresh worker/process to be picked up (a rebind/remount, same as changing a font). Downstream, every op built from an import folds the file's content digest into its cache key (`h("import", name, digest)`), so an actually-changed file (a new digest) still invalidates every dependent cache node correctly. On the STEP-on-Manifold crossover, note that the file is fetched **independently by both workers** — the Manifold worker resolves it to get a digest, and the OCCT worker resolves it again to tessellate — so a large STEP file used this way is held in memory twice, once per worker.
+
+**Performance:** a `reference` deviation check (below) costs one solid boolean per verify run. On a Manifold-routed part that's cheap; on an **OCCT-routed** part it's a full OpenCASCADE boolean against the entire imported B-rep, and `docs/geometry-backend-strategy.md` measures OCCT booleans at 75–1486× slower than the equivalent Manifold operation. A `reference`-bound sub-part on OCCT is a deliberate trade — exactness for STEP export vs. a slower `measure`/`verify` loop — worth knowing about before wiring one up on a large imported assembly.
+
+**The `reference` field and the deviation gate:**
+
+A sub-part can bind itself to an import by name; `measure()` then computes a `deviation` fact against it (symmetric-difference volume, volume delta %, and per-axis bbox-corner drift), which three `ref*` metrics in `verify.expect` can gate on — the same `SUBPART_METRICS` registry `holes`/`volume`/`bbox` live in, so they take the same assertion DSL:
+
+```js
+parts: {
+  body: {
+    reference: "scan",   // an import name — measure() computes s.deviation against it
+    build: (k, p) => k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }),
+  },
+},
+verify: {
+  expect: {
+    body: {
+      refXorVolume: "<=5mm3",          // symmetric-difference volume — the real match check
+      refVolumeDeltaPct: "<=1",        // cheap sanity gate, % of the reference's volume
+      refBboxDelta: "<=[0.2,0.2,0.2]", // mm, per-axis max of |min|/|max| corner deltas
+    },
+  },
+},
+```
+
+Deviation is measured in build coordinates on the posed display solid — aligning the rebuild to the reference is the part author's job, and the ghost overlay (next) is how you check it by eye. A sub-part with no `reference` gets `deviation: null` and skips any `ref*` assertion rather than failing it; `npx partforge lint` catches the inverse mistake — a `ref*` assertion on a sub-part that declares no `reference` — statically, as `ref-metric-without-reference` (see "Linting" → Rule catalog → "Geometry imports", below).
+
+**The two-view ghost pattern:** `measure()`'s `ok` gate is **view-scoped and overlap-strict** — it requires zero sub-part overlaps among whatever the *current* view shows. A translucent ghost of the raw import, shown in the same view as its parametric rebuild, is by construction coincident with that rebuild — so that view's `overlaps` would always read greater than zero, failing `verify` on a part that is otherwise exactly correct. The fix is not a bigger overlap tolerance; it's two views:
+
+```js
+parts: {
+  // Ghost overlay: only in "reference" — never coincides with body in "assembly".
+  ref: {
+    label: "Reference (ghost)",
+    views: ["reference"],
+    exportable: false,
+    display: { opacity: 0.3 },
+    build: (k) => k.import("scan"),
+  },
+  // The parametric rebuild — shown alone in "assembly", and against the ghost
+  // in "reference" for visual alignment checking.
+  body: {
+    label: "Rebuild",
+    views: ["assembly", "reference"],
+    reference: "scan",
+    build: (k, p) => k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }),
+  },
+},
+views: { assembly: { label: "Assembly" }, reference: { label: "Reference overlay" } },
+verify: {
+  expect: {
+    body: { refXorVolume: "<=5mm3", /* … */ },
+    _view: { overlaps: 0 },   // checked against the DEFAULT ("assembly") view only
+  },
+},
+```
+
+`assembly` is listed first so `measure`/`verify`/`render` — which all default to the **first** view key, `default: true` notwithstanding — see only the real, non-overlapping parts. `reference` is the ghost-overlay view: browse it by hand in the viewer, or pass it explicitly to `measure`/`render`, to eyeball how closely the rebuild tracks the scan. Declare `ref` `exportable: false` (it's not a real part of the design) and give it a `display.opacity` well under 1 so it reads as an overlay rather than an opaque duplicate. This is exactly `src/parts/import-demo.js`'s shape — read its `parts.ref`/`parts.body`/`views`/`verify` blocks for the fully worked, commented version.
+
+**Using an import as a real component** — the other use, no ghost involved — is an ordinary boolean, chainable like any `Solid`: `import-demo.js`'s `mount` sub-part cuts a through-socket shaped to the scan itself (scaled up slightly for clearance) out of a plate:
+
+```js
+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);
+},
+```
+
+**Linting:** `npx partforge lint` learns `import` as a known op and adds four static checks — `import-unknown-name`, `import-mesh-on-occt`, `reference-unknown`, `ref-metric-without-reference` — described in full under "Linting" → Rule catalog → "Geometry imports", below; this section only points there rather than repeating it.
+
+**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.
+
+---
+
 ## Wiring a part into a runnable app
 
 Three tiny glue files per part (copy from the demo). The worker statically imports
@@ -1795,6 +1916,20 @@ motion — translate/rotate — never a reshape) (both errors). An untrusted pro
 nothing either way and stays silent, matching `animation-track-rebuilds`'s own
 trust handling.
 
+**Geometry imports** — `import-unknown-name` (a build calls `k.import` with a
+name the part's `imports` field doesn't declare — this throws at build time;
+lint reaches it in microseconds instead), `import-mesh-on-occt` (a declared
+STL/3MF import on a part that routes to OCCT — mesh imports need the Manifold
+backend; the message names whether `meta.backend` or a CAD op forced OCCT.
+Only extension-detectable `imports` sources — a `URL` or string path — are
+checked; a bytes/thunk source's format can't be known without resolving it, so
+lint skips it and the lazy `k.import` error entry at build time remains the
+runtime authority for those cases), `reference-unknown` (a sub-part's
+`reference` names no declared import) (all errors); `ref-metric-without-reference`
+(a sub-part's `verify.expect` uses a `ref*` metric — `refXorVolume`,
+`refVolumeDeltaPct`, `refBboxDelta` — but the sub-part declares no `reference`,
+so the deviation gate always reports status "skip") (warning).
+
 A rule that itself throws yields an `internal-rule-error` **warning** and the run
 continues: `lintPart` never throws and never blocks a part because of a linter bug.
 

package/docs/ERROR-PATTERNS.md

@@ -545,6 +545,35 @@ exposure is a `build()` that queries a twisted solid's box itself, which is the
 normal idiom for placing something relative to a solid and now silently disagrees
 between the Manifold preview and the OCCT STEP export.
 
+## import-mesh-not-solid
+
+- **Symptom:** `import "<name>": mesh is not a solid after repair (<n> open edges) — repair it in a mesh tool or re-export watertight (<reason>)` thrown while registering a part's `imports` on the Manifold backend — the trailing `(<reason>)` always appears (it wraps the underlying Manifold error, e.g. `non-manifold edge` or `empty result`), never omitted.
+- **Cause:** Basic repair (vertex merge + winding/orientation fix) couldn't close the mesh into a solid — the source STL/3MF has an open shell, missing faces, or another defect beyond what v1's repair pass attempts. The open-edge count and the wrapped `<reason>` in the message together narrow down the gap.
+- **Fix:** Close the mesh in a dedicated mesh-repair tool, or re-export it watertight from the tool that produced it; there is no in-framework hole-filling/remeshing. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Importing geometry (STEP/STL/3MF)".
+
+## import-unrecognized-format
+
+- **Symptom:** `unrecognized import format for "<path>" — use a .step/.stl/.3mf extension or non-empty bytes` (the `for "<path>"` clause is omitted for a bytes/thunk source with no path) thrown while resolving a part's `imports`.
+- **Cause:** Format detection couldn't identify the source: no `.step`/`.stp`/`.stl`/`.3mf` extension on a URL/string source, and the bytes are empty or start with neither a STEP header (`ISO-10303-21`) nor a zip signature (3MF) — the ASCII/binary STL fallback needs non-empty bytes too.
+- **Fix:** Give the source a recognized extension, or make sure inline/fetched bytes are non-empty and actually STEP/STL/3MF content. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Importing geometry (STEP/STL/3MF)".
+
+## import-unknown-name
+
+- **Symptom:** `import: unknown import "<name>"` — declare it in the part's `imports` field — thrown from a build, identical text on both backends.
+- **Cause:** `k.import(name)` was called with a name that isn't a key in the part's `imports` field — a typo, or the declaration was never added. Same failure shape as `text2d`'s unknown-font error.
+- **Fix:** Add the name to `imports`, or fix the typo. `npx partforge lint <part>` catches this statically, in microseconds, before any kernel boots (`import-unknown-name`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Importing geometry (STEP/STL/3MF)" and § "Linting" (Rule catalog → Geometry imports).
+
+## import-mesh-on-occt
+
+- **Symptom:** `import "<name>": STL/3MF imports need the Manifold backend — this build routes to OCCT (shell or meta.backend, or a fillet/chamfer rerouted for an unsupported edge class); use the mesh import from a Manifold-routed build` thrown from a build calling `k.import(name)`.
+- **Cause:** STL/3MF imports are mesh geometry; mesh-to-B-rep conversion is never attempted, so a declared mesh import registers as an unusable error entry wherever the routed kernel is OCCT — thrown lazily, at the `k.import()` call inside `build`, not when the import is registered (registration itself never throws — see "Registration is total; errors are lazy" in [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Importing geometry (STEP/STL/3MF)").
+- **Fix:** Per-sub-part Manifold/OCCT coexistence is a **browser-preview-only** convenience — `npx partforge lint`/`measure`, and any single-worker export (STL/STEP/3MF), route by `detectBackend`, the **max over every sub-part**, so a mesh import still fails there even while sitting on a nominally Manifold-routed sub-part, as long as some OTHER sub-part in the same part routes to OCCT (a `shell` call or `meta.backend: "occt"` statically; since contract v3 a `fillet`/`chamfer` routes only at runtime, when its edge class falls outside the mesh blend — see mesh-fillet-unsupported-edge, below). Putting the import on a Manifold sub-part only helps the live preview; it does not clear this error. Pick one: split the mesh-importing sub-part out into its **own separate part** (a different `PartDefinition`) that has no OCCT-only ops, replace the source with a STEP file instead (STEP tessellates transparently on Manifold via the crossover — see import-step-tessellation-failed, below), or drop the CAD-only op / `meta.backend` pin so the whole part routes to Manifold. `npx partforge lint <part>` catches an extension-detectable case statically, before any kernel boots (`import-mesh-on-occt`).
+
+## import-step-tessellation-failed
+
+- **Symptom:** `STEP import tessellation failed to satisfy the import — see console` in the browser (a build's status/error), or `step tessellation thread exited <n>` from a failed Node CLI/test run.
+- **Cause:** A STEP import used on the Manifold backend needs OCCT-tessellated triangles first (the "crossover" described in [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Importing geometry (STEP/STL/3MF)"). This hop is meant to self-heal — the browser worker requests a `tessellate-imports` job from the OCCT worker, Node hops through a `node:worker_threads` isolate (the two WASM kernels may never share a process) — but it surfaces here when the tessellation either delivered a mesh whose digest didn't match what Manifold now expects (a genuinely broken state, not a retry loop) or the worker/thread exited without completing.
+- **Fix:** This should be rare and self-resolving on the next build; if it persists, confirm the STEP file parses under OCCT on its own (e.g. `meta.backend: "occt"` temporarily, or `npx partforge measure` against an OCCT-routed copy of the part) to rule out a malformed STEP file, and check the console/thread output for the underlying tessellation error being wrapped.
 ## mesh-fillet-unsupported-edge
 
 - **Symptom:** `fillet: ` or `chamfer: ` followed by an edge-class reason — e.g. `edge curve is not circular`, `flank angle varies along the arc`, `selector matched no sharp edges`, `~180° knife edge` — thrown as a `KernelCapabilityError`, or a preview sub-part silently rebuilding on the slow OCCT worker.
@@ -556,7 +585,6 @@ between the Manifold preview and the OCCT STEP export.
 - **Symptom:** A Manifold-built fillet/chamfer produces a mangled or over-cut shape (no error), where the same part on OCCT would skip the feature with a `fillet(…) failed` warning.
 - **Cause:** The mesh fillet does not validate radius feasibility — a magnitude larger than the local geometry self-intersects its cutter solids and the booleans happily apply them.
 - **Fix:** Clamp the magnitude against local dimensions in the part (`Math.min(p.fillet, halfWidth - 0.5, …)` — see `src/parts/filleted-box.js`), which is required practice on the mesh class per [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) § "Mesh degrade policy".
-
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -93,6 +93,15 @@ them loses sub-part caching and mesh-topology gates (`holes`, emptiness), nothin
 a part (never inside a `beginSubPart`/`endSubPart` bracket), it drops cache partitions that
 have gone unbuilt for three consecutive rebinds.
 
+**`import`.** `kernel.import(name) → Solid` returns previously-registered imported geometry
+(STL/STEP/3MF geometry declared in a part's `imports` field); `_registerImport`/
+`_importDigest`/`_acceptsStep`/`_acceptsMesh` are the underscore-prefixed side-channel the
+framework uses to feed it — not a part author's calling surface. It is a required op
+(`KERNEL_OPS`) on both in-repo backends: the Manifold backend accepts mesh formats
+(`_acceptsMesh: true`) and the OCCT backend accepts STEP (`_acceptsStep: true`); a format
+neither backend accepts for the routed kernel registers as an `{error}` entry that
+`import(name)` throws lazily at call time, not at registration.
+
 `KernelCapabilityError` is a *routing signal*, not a failure: partforge's geometry-free
 probe (`probe.js`) runs `build` against a fake kernel, and any use of a
 `ROUTED_CAD_OPS` op (`shell`, since v3) **on a Solid handle** routes the build to a
@@ -248,6 +257,7 @@ above. All ops return a `Solid`.
 | `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |
 | `hullChain(inputs[])` | Swept hull over an ordered sequence of ≥2 inputs (same input forms as `hull`): the union of `hull([inᵢ, inᵢ₊₁])` for each consecutive pair — e.g. a tapered link connecting a row of circles. Throws with fewer than 2 inputs. |
 | `toSTEP(named[])` | `[{name, solid}]` → `Promise<ArrayBuffer>` of a STEP assembly. B-rep class only. |
+| `import(name)` | Previously-registered imported geometry (STEP/STL/3MF, declared in the part's `imports` field) as an ordinary `Solid`. Required on both in-repo backends (Manifold accepts mesh formats, OCCT accepts STEP); a format the routed backend can't use throws lazily, at this call, not at registration. Fed by an underscore-prefixed side-channel, not part authors — see [Conformance classes](#conformance-classes). Additive: not in `OCCT_ONLY_OPS`; needed no `CONTRACT_VERSION` bump of its own (v3 came from the mesh fillet/chamfer change, not this op). |
 
 `hull`/`hullChain` parity: point-list and curve-contour inputs hull bit-identically
 across backends (pure-JS sampling, no backend materialization involved). A `Shape2D`
@@ -666,7 +676,11 @@ other posts — `progress`, `error`, `needs-occt` — are not gated and still re
 that survived the rebind: a stale `error` would mark a perfectly good new part failed, and
 a stale `needs-occt` would stickily flip the host's backend for a part that never asked for
 it. Handling `superseded` fixes the stuck spinner but not that crosstalk, which is why
-detaching the listener is the recommended pattern.
+detaching the listener is the recommended pattern. `needs-import-mesh` — posted when a
+build throws an error carrying code `NEEDS_IMPORT_MESH` (an unprimed STEP import on the
+Manifold backend, thrown from `imports.js`'s registration policy, not `errors.js`'s
+`KernelCapabilityError`/`NEEDS_OCCT`) — is the same message shape and the same
+non-epoch-gated risk as `needs-occt`; a host handling one should handle both the same way.
 
 **Cancellation granularity is the sub-part.** The guard is checked only between
 sub-parts (one macrotask yield each), so a single long WASM op — a big boolean, an OCCT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.63.0",
+  "version": "0.64.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/app-import-demo.js

@@ -0,0 +1,18 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import importDemoPart from "./parts/import-demo.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the import-demo part (geometry import reference
+// example). Identical wiring to app.js — the only thing that differs per part
+// is which definition you import and which worker entry you point at.
+// `npm run dev`, then open /import-demo.html.
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(importDemoPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./import-demo-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/app.css

@@ -285,7 +285,14 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
   border-radius: var(--pf-radius-pill);
   box-shadow: var(--pf-shadow-float);
 }
-#topbar .seg button { min-width: 70px; padding: 7px 10px; }
+/* nowrap: `.seg button` is `flex: 1` (equal-width columns), and a part with
+   two views where one label is long (e.g. import-demo's "Reference overlay")
+   would otherwise wrap onto a second line, making this pill taller than the
+   single fixed height debug-overlay.js positions itself below (see its
+   comment) — the overlay would then overlap the now-two-row tabs. Letting the
+   label force the column wider instead keeps the pill single-row regardless
+   of label length. */
+#topbar .seg button { min-width: 70px; padding: 7px 10px; white-space: nowrap; }
 
 /* viewer controls. APPEARANCE is ungated: partforge-cloud re-anchors #viewbar's
    position in sandbox.css but inherits this pill chrome, so gating it on a class

package/src/framework/asset-resolve.js

@@ -0,0 +1,71 @@
+// Shared source-resolution core for fonts.js and imports.js. Both resolve a
+// part's declared `{ name: source }` map before the synchronous build, where a
+// source is: an ArrayBuffer/typed-array view (bytes), a URL string, a `URL`
+// instance (fetched), or a thunk (possibly async) returning any of those —
+// including the `{ default: … }` shape a Vite dynamic `import('./x.ttf')`
+// yields. The two callers differ only in what they do with the resolved bytes
+// (fonts keep the raw ArrayBuffer; imports also stamp a digest + format), so
+// each owns its own cache Map and result shape; this module owns just the
+// source→bytes grammar and the identity-memoization rule (a source, e.g. a
+// thunk, is content-stable for a session — resolve it once). DOM-free and
+// node:-free so it stays safe in the geometry worker's import closure.
+
+export function toBuffer(v) {
+  if (v instanceof ArrayBuffer) return v;
+  // A view may not span its whole backing buffer — slice to its exact range (Node
+  // Buffer pooling makes byteOffset>0 common for small files; v.buffer alone would
+  // be garbage).
+  if (ArrayBuffer.isView(v)) return v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength);
+  return null;
+}
+
+// A source string/URL for an error message — truncated so a very long signed
+// Storage URL (query string full of credentials-shaped junk) doesn't blow up
+// the message.
+function describeSource(v) {
+  const s = String(v);
+  return s.length > 200 ? `${s.slice(0, 200)}…` : s;
+}
+
+// Build a memoized `resolveOne(source)` for one caller. `finish(bytes, value,
+// source)` turns the resolved bytes into that caller's result shape (may be
+// async); `errorMessage` is thrown when `source` doesn't match the grammar.
+// Results are cached on the caller-supplied `cache` Map, keyed by source
+// identity, so a repeated declaration resolves (and fetches) only once.
+export function makeAssetResolver(cache, finish, errorMessage) {
+  return function resolveOne(source) {
+    if (cache.has(source)) return cache.get(source);
+    const p = (async () => {
+      let v = source;
+      if (typeof v === "function") v = await v();
+      if (v && typeof v === "object" && "default" in v && !toBuffer(v) && !(v instanceof URL)) v = v.default; // dynamic-import module
+      let bytes = toBuffer(v);
+      if (!bytes) {
+        if (v instanceof URL || typeof v === "string") {
+          const res = await fetch(v);
+          // A signed Storage URL (cloud's designed source shape) expires and
+          // then 404s/403s — without this check the error body resolves as
+          // geometry/font bytes and fails downstream as a misleading parse
+          // error instead of naming the real problem.
+          if (!res.ok) {
+            throw new Error(`fetch failed (${res.status}${res.statusText ? ` ${res.statusText}` : ""}) for ${describeSource(v)}`);
+          }
+          bytes = await res.arrayBuffer();
+        }
+        else throw new Error(errorMessage);
+      }
+      return finish(bytes, v, source);
+    })();
+    cache.set(source, p);
+    return p;
+  };
+}
+
+// Resolve a `{ name: source }` declaration to `Map<name, result>` using a
+// `resolveOne` built by `makeAssetResolver`.
+export async function resolveDecl(decl, resolveOne) {
+  const out = new Map();
+  if (!decl) return out;
+  await Promise.all(Object.entries(decl).map(async ([name, src]) => out.set(name, await resolveOne(src))));
+  return out;
+}

package/src/framework/capture-build.js

@@ -29,15 +29,23 @@ export function createCaptureBuild({ send }) {
   // caller — mount.js's onWorkerMessage — can skip it entirely). Keyed on
   // membership in `pending` first: the namespaced jobId guarantees another
   // channel's message never matches, so a hit here is always ours. A failed
-  // build (the worker's shared catch posts a generic error/needs-occt, jobId
-  // intact) resolves to null rather than leaving the caller hanging forever —
-  // captureView treats null as "capture failed, skip".
+  // build (the worker's shared catch posts a generic error/needs-occt/
+  // needs-import-mesh, jobId intact) resolves to null rather than leaving the
+  // caller hanging forever — captureView treats null as "capture failed, skip".
+  // needs-import-mesh MUST be claimed here rather than falling through to
+  // mount's live-loop crossover case: this capture job never went through the
+  // regen loop, so treating its reply as a live crossover would call
+  // loop.buildDone() for a build the live loop never dispatched, and could
+  // fire a stray tessellate-imports request or flip the live importMeshState
+  // latch. A capture-generate hit on an unprimed STEP import is not itself
+  // retried — the v1 behavior is "fail this off-loop op cleanly"; the import
+  // gets primed by the next live build instead.
   function handleMessage(data) {
     const jobId = data?.jobId;
     if (jobId == null || !pending.has(jobId)) return false;
     if (data.type === "capture-meshes") {
       pending.get(jobId)(data.meshes);
-    } else if (data.type === "error" || data.type === "needs-occt") {
+    } else if (data.type === "error" || data.type === "needs-occt" || data.type === "needs-import-mesh") {
       pending.get(jobId)(null);
     } else {
       return false;

package/src/framework/export-controller.js

@@ -50,6 +50,18 @@ export function createExportController({ send, currentView, title, defaultBacken
     }
     if (m.type === "error") { pending.delete(m.jobId); entry.reject(new Error(m.message)); return true; }
     if (m.type === "needs-occt") { pending.delete(m.jobId); entry.reject(new Error("needs OCCT backend")); return true; }
+    // needs-import-mesh MUST be claimed here (jobId intact from the worker's
+    // shared catch) rather than falling through to mount's live-loop crossover
+    // case: this export job never went through the regen loop, so treating its
+    // reply as a live crossover would call loop.buildDone() for a build the
+    // live loop never dispatched. v1 behavior is to fail this off-loop op
+    // cleanly rather than build a second crossover flow for it — the import
+    // gets primed by the next live build instead.
+    if (m.type === "needs-import-mesh") {
+      pending.delete(m.jobId);
+      entry.reject(new Error("STEP import needs tessellation — retry after the first preview build primes it"));
+      return true;
+    }
     return false;
   }
 

package/src/framework/fonts.js

@@ -1,36 +1,18 @@
 // Resolve a part's declared `fonts` ({ name: source }) to ArrayBuffers, before the
 // synchronous build. A source is: an ArrayBuffer/Uint8Array (bytes), a URL string
-// (fetched — a Vite `import('./x.ttf')` yields { default: url }), or a thunk
-// returning any of those (possibly async). Memoized process-wide by source so
-// repeated builds don't refetch. DOM-free (uses global fetch, present in workers).
-const cache = new Map(); // source (string|object) → Promise<ArrayBuffer>
-
-function toBuffer(v) {
-  if (v instanceof ArrayBuffer) return v;
-  // A view may not span its whole backing buffer — slice to its exact range (Node Buffer
-  // pooling makes byteOffset>0 common for small files; v.buffer alone would be garbage).
-  if (ArrayBuffer.isView(v)) return v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength);
-  return null;
-}
+// or `URL` instance (fetched — a Vite `import('./x.ttf')` yields { default: url }),
+// or a thunk returning any of those (possibly async). Memoized process-wide by
+// source so repeated builds don't refetch. DOM-free (uses global fetch, present in
+// workers). Built on the shared resolution core in asset-resolve.js.
+import { makeAssetResolver, resolveDecl } from "./asset-resolve.js";
 
-async function resolveOne(source) {
-  if (cache.has(source)) return cache.get(source);
-  const p = (async () => {
-    let v = source;
-    if (typeof v === "function") v = await v();
-    if (v && typeof v === "object" && "default" in v && !toBuffer(v)) v = v.default; // dynamic-import module
-    const buf = toBuffer(v);
-    if (buf) return buf;
-    if (typeof v === "string") return await (await fetch(v)).arrayBuffer();
-    throw new Error("resolveFonts: a font source must be bytes, a URL string, or a thunk returning one");
-  })();
-  cache.set(source, p);
-  return p;
-}
+const cache = new Map(); // source (string|object) → Promise<ArrayBuffer>
+const resolveOne = makeAssetResolver(
+  cache,
+  (bytes) => bytes,
+  "resolveFonts: a font source must be bytes, a URL, or a thunk returning one",
+);
 
 export async function resolveFonts(fontsDecl) {
-  const out = new Map();
-  if (!fontsDecl) return out;
-  await Promise.all(Object.entries(fontsDecl).map(async ([name, src]) => out.set(name, await resolveOne(src))));
-  return out;
+  return resolveDecl(fontsDecl, resolveOne);
 }

package/src/framework/geometry/kernel.js

@@ -22,7 +22,7 @@ export const CONTRACT_VERSION = 4;
 export const KERNEL_OPS = [
   "cylinder", "boredCylinder", "sphere", "box", "prism", "extrude", "revolve",
   "loft", "sweep", "helixSweptTube", "screwSweep", "union", "shape2d", "text2d", "hull", "hullChain", "toSTEP",
-  "roundedCylinder", "torus", "roundedBox",
+  "roundedCylinder", "torus", "roundedBox", "import",
 ];
 
 // Backend-optional kernel ops: the sub-part cache brackets + WASM lifetime hooks.
@@ -146,6 +146,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hull   convex hull of all inputs → a convex Shape2D (faceted; pure-JS monotone chain)
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hullChain   swept hull over an ordered sequence (≥2): union of hull([inᵢ,inᵢ₊₁])
  * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError)
+ * @property {(name: string) => Solid} import   imported geometry declared in the part's imports field (registered pre-build by the framework via the underscore-prefixed `_registerImport`/`_importDigest`/`_acceptsStep`/`_acceptsMesh` side-channel, not a part author's calling surface)
  * @property {(name:string) => void} [beginSubPart]   open a per-sub-part solid-cache round (both backends)
  * @property {() => void} [endSubPart]                close the cache round (always pair with beginSubPart)
  * @property {() => void} [sweepCache]   drop cache partitions idle for 3 rebinds; call once per setPart, never mid-bracket

package/src/framework/geometry/manifold-backend.js

@@ -4,6 +4,8 @@ import { sweepMesh } from "./sweep.js";
 import { roundedBoxRings } from "./rounded-solids.js";
 import { tessellateContour, tessellateProfile } from "./profile.js";
 import { h } from "./solid-hash.js";
+import { ensureOutward, openEdgeCount } from "./mesh-repair.js";
+import { manifoldFromMesh } from "./mesh-build.js";
 import { createSolidCache } from "./solid-cache.js";
 import { addSugar } from "./solid-sugar.js";
 import { makeShape2dFactory } from "./shape2d.js";
@@ -49,6 +51,10 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const cache = createSolidCache();
   const featureLabels = new Map(); // originalID -> label string (grows per label(); tiny)
   const oidPolicies = new Map();   // originalID -> shading policy (grows per faceted/hinted loft; tiny)
+  // name -> { m, digest, hash } | { error, digest } — imported geometry the framework
+  // registers pre-build (ensureImports, Task 8). Kernel-lifetime, NOT tracked/T()'d:
+  // these masters must survive cleanup() and be read again on every subsequent build.
+  const imports = new Map();
   // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
   // tracks the result, and returns the triple the cache needs to pin/dispose it.
   const cached = (hash, computeM) => cache.lookup(hash, () => {
@@ -330,6 +336,41 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     union: (solids) => solids.length === 1
       ? solids[0]
       : cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
+    // Imported geometry, registered pre-build by the framework via `_registerImport`
+    // (ensureImports, Task 8). The master Manifold is kernel-lifetime (untracked —
+    // see `imports` above); wrap() is free, so every call is cheap.
+    import: (name) => {
+      const e = imports.get(name);
+      if (!e) throw new Error(`import: unknown import "${name}" — declare it in the part's \`imports\` field`);
+      if (e.error) throw e.error; // lazy: unusable-format entries fail at use, not at registration
+      return wrap(e.m, e.hash);
+    },
+    // Side-channel (underscore = off-contract, probe-invisible). Registration is
+    // TOTAL — it never throws for an unusable format; an `{error}` entry is stored
+    // verbatim and thrown by `import(name)` above at call time (spec: "Registration
+    // is total; errors are lazy"). Re-registering the same name+digest is a no-op
+    // EXCEPT an error entry is always upgradable (the post-crossover retry depends
+    // on this — see `_importDigest`).
+    _registerImport: ({ name, digest, positions, indices, error }) => {
+      const prev = imports.get(name);
+      if (!prev?.error && prev?.digest === digest) return; // error entries are always upgradable
+      if (error) { imports.set(name, { error, digest }); return; }
+      ensureOutward(positions, indices);
+      let m;
+      try {
+        m = manifoldFromMesh(wasm, positions, indices);
+        if (m.isEmpty()) throw new Error("empty result");
+      } catch (err) {
+        const open = openEdgeCount(positions, indices);
+        throw new Error(`import "${name}": mesh is not a solid after repair (${open} open edges) — repair it in a mesh tool or re-export watertight (${err?.message || err})`);
+      }
+      prev?.m?.delete?.(); // prev may be an error entry with no manifold
+      imports.set(name, { m, digest, hash: h("import", name, digest) });
+    },
+    // Registration memo: undefined for an error entry, so a later registration with
+    // the same digest can upgrade it rather than being treated as a no-op repeat.
+    _importDigest: (name) => { const e = imports.get(name); return e?.error ? undefined : e?.digest; },
+    _acceptsMesh: true,
     shape2d,
     // Backend-internal region adapter: the shared native engine (contour-offset.js)
     // that Shape2D.offset itself runs on — published here for callers that want the