partforge 0.97.0 → 0.99.0

package/bin/cli.js

@@ -13,8 +13,6 @@ import { fontsFor } from "../src/framework/fonts.js";
 import { imagesFor } from "../src/framework/images.js";
 import { isNoImageSource } from "../src/framework/image-source.js";
 import { viewAnimations, evaluate, cueAt } from "../src/framework/animation.js";
-import { bootOcctKernel } from "../src/testing/occt.js";
-import { bootManifoldKernel } from "../src/testing/manifold.js";
 import { measure } from "../src/framework/oracle/measure.js";
 import { verify } from "../src/framework/oracle/verify.js";
 import { renderViews } from "../src/testing/render.js";
@@ -25,11 +23,15 @@ import {
 import { savePickToken, loadPickToken, clearPickToken, pickTokenPath } from "../src/framework/pick-request/token-store.js";
 import { matchPattern } from "../src/testing/error-patterns.js";
 import { lintPart } from "../src/lint.js";
-import { resolveVectorDocs } from "../src/framework/vectors.js";
+import { sniffMediaType } from "../src/framework/ingest/sniff.js";
+import { ASSET_KINDS, rowFor, convertFor } from "../src/framework/ingest/registry.js";
+import { installNodeDom } from "../src/framework/ingest/node-dom.js";
+import * as opentypeNamespace from "opentype.js";
+import { normalizeOpentype, parseFont } from "../src/framework/geometry/opentype-interop.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 
-const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick|ingest> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
@@ -96,6 +98,24 @@ const readSources = (partPath) => {
   }
 };
 
+// vectors.js, testing/occt.js and testing/manifold.js are imported DYNAMICALLY
+// here rather than statically at the top of this file — not for laziness'
+// sake, but because all three transitively reach paper-core.js (vectors.js ->
+// geometry/vector-format.js -> geometry/contour-ops.js -> geometry/paper-bridge.js
+// -> "paper/dist/paper-core.js"; testing/occt.js and testing/manifold.js the
+// same, via their *-backend.js's own contour-ops.js use). paper-core does a
+// canvas + 2D context probe at MODULE LOAD time (svg-ingest.js's header) and
+// caches what it finds about its environment for the lifetime of the process —
+// load it before `ingest`'s installNodeDom() has set up a DOM and every later
+// SVG conversion fails deep inside paper's importSVG with an opaque "Cannot
+// read properties of undefined (reading 'body')", even after the DOM exists.
+// A static import here runs before `commands[cmd](args)` is ever called, no
+// matter which verb was requested, so it would poison `ingest` even though
+// `ingest` itself never touches these three. Deferring the import to the
+// commands that actually need them keeps every other verb's behavior
+// unchanged and keeps paper-core.js's first load in `ingest`'s hands.
+const importVectors = () => import("../src/framework/vectors.js");
+
 // Pass the part's declared fonts through, mirroring the worker path (jobs.js) —
 // otherwise a part using a named font builds in the browser but dies headlessly
 // with `text2d: unknown font …`. A function-form `fonts` is resolved against
@@ -110,14 +130,20 @@ const readSources = (partPath) => {
 // is dropped rather than handed to ensureImages, mirroring jobs.js's own filter —
 // `k.heightfield` throws unknown-image for a name never registered; a part
 // that wants to build with no image branches around the call itself.
-const bootKernel = (part, params = {}) => {
+const bootKernel = async (part, params = {}) => {
   const p = { ...(part.defaults ?? {}), ...params };
   const imagesDecl = part.images ? (imagesFor(part, p) ?? {}) : undefined;
   const images = imagesDecl &&
     Object.fromEntries(Object.entries(imagesDecl).filter(([, src]) => !isNoImageSource(src)));
-  const opts = { fonts: fontsFor(part, p), imports: part.imports, images, vectors: part.vectors };
+  const { vectorsFor } = await importVectors();
+  const opts = { fonts: fontsFor(part, p), imports: part.imports, images, vectors: vectorsFor(part, p) };
   const backend = process.env.PARTFORGE_BACKEND || detectBackend(part); // env: crash()'s NEEDS_OCCT retry
-  return backend === "occt" ? bootOcctKernel(opts) : bootManifoldKernel(opts);
+  if (backend === "occt") {
+    const { bootOcctKernel } = await import("../src/testing/occt.js");
+    return bootOcctKernel(opts);
+  }
+  const { bootManifoldKernel } = await import("../src/testing/manifold.js");
+  return bootManifoldKernel(opts);
 };
 
 const commands = {
@@ -133,7 +159,11 @@ const commands = {
       const part = await loadPart(partPath, usage);
       const params = flags.params ? JSON.parse(flags.params) : undefined;
       const sources = readSources(partPath);
-      const vectorDocs = Object.fromEntries(await resolveVectorDocs(part.vectors));
+      // Same `p` derivation as bootKernel — needed here only to resolve a
+      // function-form `vectors` against params before handing it to lint.
+      const p = { ...(part.defaults ?? {}), ...params };
+      const { resolveVectorDocs, vectorsFor } = await importVectors();
+      const vectorDocs = Object.fromEntries(await resolveVectorDocs(vectorsFor(part, p)));
       const report = lintPart(part, { params, sources, vectorDocs });
       if (!flags.json) printLint(report);
       if (flags.out) {
@@ -163,7 +193,11 @@ const commands = {
       // milliseconds with a precise message rather than after a WASM boot and a
       // downstream error that doesn't name the cause. Warnings never gate measure.
       if (!flags["no-lint"]) {
-        const vectorDocs = Object.fromEntries(await resolveVectorDocs(part.vectors));
+        // Same `p` derivation as bootKernel below — measure has no --params
+        // flag, so this is just the part's own defaults.
+        const p = { ...(part.defaults ?? {}) };
+        const { resolveVectorDocs, vectorsFor } = await importVectors();
+        const vectorDocs = Object.fromEntries(await resolveVectorDocs(vectorsFor(part, p)));
         const lint = lintPart(part, { sources: readSources(partPath), vectorDocs });
         if (!lint.ok) {
           if (flags.json) console.log(JSON.stringify({ ok: false, lint }, null, 2));
@@ -371,6 +405,78 @@ const commands = {
     console.log(formatPickResult(out));
     process.exit(out.status === "done" ? 0 : 1);
   },
+
+  // Command-line surface over the same drop-target machinery the control
+  // panel uses (registry.js's ASSET_KINDS/rowFor/convertFor) — so an agent
+  // handed a raw SVG, font, or PNG can get it into a part's asset tree without
+  // a browser. --out is REQUIRED, not defaulted: this command writes a file,
+  // and for the pass-through cases (PNG, font) a computed "next to the input"
+  // default would land on the exact same path as the input itself — a
+  // surprising same-path overwrite is worse than making the destination
+  // explicit every time.
+  async ingest(args) {
+    const usage = "usage: partforge ingest <file> --out <output-file> [--strokes ignore]";
+    const { values: flags, positionals: [inPath] } = parse(args, {
+      out: { type: "string" },
+      strokes: { type: "string" },
+    }, usage);
+    try {
+      if (!inPath) die(usage);
+      if (!flags.out) die(`ingest writes a file, so it needs an explicit destination — pass --out\n${usage}`);
+      const resolvedIn = resolve(process.cwd(), inPath);
+      const bytes = readFileSync(resolvedIn);
+      const mediaType = sniffMediaType(bytes);
+      // Which slot, if any, this media type belongs to — same lookup registry.js's
+      // own kindAccepting() does internally, but that helper isn't exported (the
+      // panel never needs it: a drop target already knows its own kind).
+      const kind = mediaType ? ASSET_KINDS.find((k) => rowFor(k).accepts.includes(mediaType)) : undefined;
+      if (!kind) {
+        throw new Error(`ingest: unrecognised file "${inPath}"${mediaType ? ` (looks like ${mediaType}, but no asset slot accepts it)` : ""} — expected a PNG, JPEG, WebP, SVG, TTF, or OTF`);
+      }
+      const outPath = resolve(process.cwd(), flags.out);
+      mkdirSync(dirname(outPath), { recursive: true });
+
+      if (kind === "vector") {
+        // Must install the DOM BEFORE the dynamic import below: paper-core
+        // (loaded by svg-ingest.js, resolved through convertFor's thunk)
+        // builds a canvas and asks for a 2D context at MODULE LOAD time.
+        await installNodeDom();
+        const ingestSvg = await convertFor(kind, mediaType);
+        const doc = ingestSvg(bytes.toString("utf8"), {
+          strokes: flags.strokes ?? "outline",
+          source: basename(inPath),
+        });
+        writeFileSync(outPath, `${JSON.stringify(doc, null, 2)}\n`);
+      } else if (kind === "font") {
+        // Identity + validation, no DOM: fonts have no converter (registry.js's
+        // "font" row declares `convert: null`) — used as-is, so the only thing
+        // to do here is prove opentype.js can actually read it.
+        parseFont(normalizeOpentype(opentypeNamespace), bytes, basename(inPath));
+        writeFileSync(outPath, bytes);
+      } else if (mediaType === "image/png") {
+        // Already the target format: pass through unchanged. "Validation"
+        // here is the classification above (sniffMediaType's real signature
+        // check, the same gate the drop target uses) — NOT a full structural
+        // PNG decode: decodePng (src/framework/geometry/png-decode.js) rejects
+        // anything short of a complete IHDR/IDAT/IEND file, which is stricter
+        // than what a PNG-slot asset needs to satisfy and would refuse
+        // otherwise-fine files a real decoder tolerates (trailing junk after
+        // IEND, unusual-but-legal ancillary chunk ordering, ...).
+        writeFileSync(outPath, bytes);
+      } else {
+        // JPEG/WebP/other raster: converting to PNG needs createImageBitmap and
+        // a real canvas encoder (image-ingest.js's imageToPng) — happy-dom has
+        // no canvas raster backend, so this cannot run headlessly. Do not add
+        // an image-processing dependency to work around that; point at the
+        // browser path instead.
+        throw new Error(`ingest: ${mediaType} images can't be converted headlessly — happy-dom has no canvas raster backend, so imageToPng only runs in a browser. Drop "${inPath}" onto the app's Image control instead, or convert it to PNG yourself first.`);
+      }
+      console.log(`wrote ${outPath}`);
+      process.exit(0);
+    } catch (e) {
+      crash("ingest", e, false);
+    }
+  },
 };
 
 function printMeasure(r) {

package/docs/AUTHORING-PARTS.md

@@ -523,6 +523,26 @@ magic vectors. Three habits:
   body.cutAll([a, b, c])          // and k.union([base, f1, f2]) for additive batches
   ```
 
+- **Size cut tools so no two of them land on exactly the same surface.** Booleans are
+  cheap right up until two operands share a coincident face, at which point OCCT has to
+  classify a surface belonging to both and the search degenerates — seconds become
+  minutes, with no error and no warning. Manifold's mesh CSG is unaffected, so the trap
+  is invisible until a STEP export (the one format pinned to OCCT) or an OCCT-routed
+  build. The classic is a threaded cap: a bore sized straight off the thread's root
+  diameter puts the bore wall and the thread root on the same cylinder.
+
+  ```js
+  // ✗  the bore wall lands exactly on the thread root
+  const boreD = threadRootD;
+  cap.cutAll([k.cylinder({ d: boreD, h }), thread]);
+  // ✓  a deliberate gap, far below a printable layer
+  const boreD = threadRootD - 2 * 0.05;
+  ```
+
+  The same applies to a cut that stops exactly flush with a face — overshoot it instead,
+  which is why cut tools throughout this guide carry `+ 0.4` / `- 0.2` slop. See
+  [boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang).
+
 The bare `rotate(deg, center, axis)` remains available as the low-level primitive for
 anything `rotateX/Y/Z`/`rotateAbout` can't express, but prefer the vocabulary above.
 
@@ -711,8 +731,9 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"checkbox"` | an on/off box: ticked writes `on`, cleared writes `0` | `on` (default `1`) |
 | `"select"` | a dropdown | `options` |
 | `"radio"` | a segmented button row | `options` |
-| `"font"` | a typeface picker, or a URL field with no catalog | `allow`, `preview` |
-| `"image"` | an image picker, or a URL field with no catalog | `allow` |
+| `"font"` | a typeface picker (or a URL field with no catalog), plus a drop target | `allow`, `preview` |
+| `"image"` | an image picker (or a URL field with no catalog), plus a drop target | `allow` |
+| `"vector"` | a URL field plus a drop target — no catalog exists | — |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and clamp to `[min, max]` on commit.
@@ -1579,6 +1600,32 @@ resolve — with a URL they stay silent until the bytes arrive. And the object i
 on every resolve, so a malformed one fails with the same message its fetched twin would;
 it is read and never written, so `build` stays pure.
 
+**`vectors` may also be a function of params — and must be, for a `type: "vector"`
+control.** Exactly like `fonts` and `images`, the field takes either a static
+`{ name: source }` object (everything above) or a function called with the resolved
+params, so a picked or dropped source can reach the build:
+
+```js
+parameters: [{ id: "art", title: "Artwork", controls: [{ key: "art", type: "vector" }] }],
+defaults: { art: "" },                        // empty = no artwork yet; the build must cope
+vectors: (p) => (p.art ? { badge: p.art } : {}),
+build: (k, p) => {
+  const plate = k.box({ w: 60, d: 40, h: p.plate_t });
+  if (!p.art) return plate;                   // nothing dropped yet
+  return plate.union(k.vector2d("badge", { width: 30 })
+    .extrude({ h: 1 }).translate([0, 0, p.plate_t]));
+},
+```
+
+A static object provably cannot read a param, so a `type: "vector"` control beside
+one is inert — the picker changes a param and the artwork never moves.
+`vector-control-not-in-vectors` (lint) catches both halves of that mistake: a static
+`vectors` beside a vector control, and a function-form `vectors` that never returns
+the picked value. An empty `p.art` declares **no** artwork for that name (the same
+"unset, not refused" rule `fonts`/`images` use) — the job skips it with a progress
+note rather than fetching `""`, so a build that guards on it, as above, still runs
+with nothing dropped.
+
 **Sizing is against the tight geometric bounding box, not a `viewBox`.** Icon sets pad
 their `viewBox` inconsistently, so sizing relative to `viewBox` makes two icons declared at
 the same nominal size look different on the plate. `width`/`height`/`fit` instead measure
@@ -1862,7 +1909,7 @@ gates, and the geometry a regression test pins can never disagree about how a
 given file decodes — a second format would mean a second decode path, and a
 second place for the three to drift apart. The escape hatch is
 `imageToPng(fileOrBlob, { maxSize = 1024 }) → Promise<Blob>`, exported from
-`"partforge"` (main-thread only — it draws through a `<canvas>`, never import
+`"partforge/ingest"` (main-thread only — it draws through a `<canvas>`, never import
 it from a part or a worker): convert any format the browser can decode into a
 PNG before it reaches `images`, in a host's upload handler. It downsamples to
 `maxSize` on the long edge on the way, since `pitch` caps useful resolution
@@ -1888,16 +1935,19 @@ OCCT time.
 
 **Bytes in params — the sandbox path.** A `type: "image"` control's value may
 also be raw PNG bytes (an `ArrayBuffer`/typed array) rather than a URL string —
-this is how a host that cannot fetch URLs (the partforge-cloud sandbox is the
-motivating case) gets an uploaded image into a part: its own trusted panel
-puts the bytes straight into `params`. Byte values **bypass the `allow` check
+either dropped onto the control (see "Getting files into a part", below) or
+placed there directly by a host that cannot fetch URLs (the partforge-cloud
+sandbox is the motivating case). Byte values **bypass the `allow` check
 entirely**, for every `allow` list, including the default — not a hole, but
 the deliberate consequence of what a byte value in `params` can mean: a URL
 cannot carry megabytes, so an `ArrayBuffer` arriving there cannot have come
-from a pasted link or a shared URL; it can only have been placed there by the
-host's own code. `allow` exists to keep a shared link from turning into an
-arbitrary fetch — a concern that doesn't apply to a value the host already
-has in hand.
+from a pasted link or a shared URL. That plausibility argument isn't the
+load-bearing one, though — the structural fact is that `asset-resolve.js`'s
+resolver (shared by `images`/`fonts`/`vectors`) calls `fetch` only for a
+`string`/`URL` source, so bytes are consumed directly and can never become a
+request no matter how they arrived in `params`. `allow` exists to keep a
+shared link from turning into an arbitrary fetch — a concern that structurally
+cannot apply to a byte-valued param.
 
 **Linting:** `npx partforge lint` adds an "Image controls" group of static
 checks — `image-control-not-in-images`, `heightfield-unknown-image`,
@@ -1911,6 +1961,121 @@ function-form caveat: a `verify` case or animation frame that changes the
 image-control param still builds against the base-params source, because the
 CLI boots its kernel once.
 
+## Getting files into a part
+
+`"image"`, `"vector"` and `"font"` controls each carry a drop target, on top of
+the URL/catalog paths documented for them above — a file dropped, pasted, or
+picked (a native file-input dialog behind a click, for a mouse/keyboard user
+with no drag-and-drop) lands in the same param a URL or a picker selection
+would. There is no drop target for `imports` (STEP/STL/3MF) — those are
+reference geometry, checked in or fetched, not something a panel field takes a
+file for. `src/framework/panel/widgets/file-drop.js` is the shared
+implementation behind all three; this section documents its contract, not its
+code.
+
+**What each control's drop target accepts.** A dropped file is classified by
+its actual bytes — never its extension or the browser's claimed MIME type —
+against a fixed sniff table (`src/framework/ingest/sniff.js`), because a
+file's claimed type is exactly the input a mislabelled or hostile upload would
+travel as:
+
+| Control | Accepts | Lands as |
+|---|---|---|
+| `"image"` | PNG, JPEG, WebP | a PNG (JPEG/WebP re-encoded through a `<canvas>`; PNG passes through unchanged) |
+| `"vector"` | SVG | a parsed `partforge-vector` document (paper.js — the same conversion `partforge/ingest`'s `ingestSvg` performs) |
+| `"font"` | TTF, OTF | the file itself — nothing to convert |
+
+A file that doesn't match its own control's list is refused with a message
+naming what it actually is; when another control's slot *would* take it (an
+SVG dropped on the Image control), the message names that control instead of
+just saying no. A file over 25 MB is refused before being read into memory to
+classify at all.
+
+**Where the result goes — `onAssetUpload`, or straight into the param.** After
+conversion, the drop widget looks for `onAssetUpload` (a `mount()` option —
+see "Wiring a part into a runnable app", above, for its full signature):
+
+- **With the hook**, it hands over the converted artifact — a PNG blob, the
+  partforge-vector document serialized as a JSON blob, or the original font
+  file — and writes whatever source string the hook resolves to into the
+  param, exactly as if that string had been typed into the URL field or
+  chosen from a catalog.
+- **Without it**, the artifact itself becomes the param value directly: raw
+  bytes (an `ArrayBuffer`) for `"image"`/`"font"`, and the **parsed
+  `partforge-vector` document object** — not its serialized bytes — for
+  `"vector"`, because `vectors.js`'s resolver already accepts an in-tree
+  parsed object directly (`asParsedFile`, see "Vector geometry", above);
+  serializing it only for the resolver to re-parse would be pure waste. This
+  is the path a host that cannot fetch URLs needs — the partforge-cloud
+  sandbox is the motivating case — and it is a first-class destination, not a
+  degraded fallback for a host that hasn't wired anything up: nothing about
+  presets, undo, the params hash, or `when` cares which shape a control's
+  value takes.
+
+**The `allow` list, and what bypasses it.** All three controls take the same
+`allow` list already documented for `"font"` in the control-types table above
+(`"https"` — the default; `"gstatic"`, font-only, `https://fonts.gstatic.com`
+exactly; `"asset"`, a `pfc-asset://` token the host has stored for this part),
+gating what a **param-supplied** value may be. It never restricts a source an
+author writes into `images`/`fonts`/`vectors` themselves — that's code, not
+user input.
+
+A value that lands with no `onAssetUpload` hook — bytes for image/font, the
+parsed document object for vector — bypasses `allow` entirely, for every allow
+list including the default. **This rests on a structural fact, not on "a URL
+can't carry megabytes."** That plausibility argument is true, but it isn't
+what the check actually rests on: `asset-resolve.js`'s resolver — the code
+every `fonts`/`images`/`vectors` declaration resolves through, no matter which
+control produced the value — calls `fetch` **only** for a `string`/`URL`
+source. Bytes and parsed objects are consumed directly and never reach that
+branch, so neither can become an outbound request no matter how it got into
+`params` — which is exactly the class of harm `allow` exists to gate, and
+still holds even if a host someday finds a way to put a few bytes of base64 on
+a share link.
+
+**Read that fact in the resolver's own order, though.** The resolver unwraps a
+`{ default: … }` module namespace **before** it dispatches on shape, so
+"object ⇒ never fetched" is not true of every object: `{ default:
+"http://…" }` unwraps to a plain string and is fetched. The vector check
+therefore unwraps first and judges what the resolver will actually see — a
+string or `URL` gets the full `allow` treatment however it was wrapped, a
+thunk is refused outright (its return value cannot be known at check time),
+and only a value that genuinely does not unwrap to a fetchable source is
+exempt.
+
+**`npx partforge ingest`** runs the same classify/convert step outside a
+browser, for an agent (or a script) handed a raw file with nowhere to drop it:
+
+```bash
+npx partforge ingest logo.svg   --out logo.vector.json
+npx partforge ingest scan.ttf   --out src/parts/assets/scan.ttf
+```
+
+`--out` is required, always — for a pass-through case (PNG, font) a computed
+"beside the input" default would land on the exact same path as the input
+itself, and a surprising same-path overwrite is worse than an explicit
+destination every time. The four cases the drop widget's classification can
+produce, resolved to a file instead of a param:
+
+| Input | Result |
+|---|---|
+| SVG | converted to a `partforge-vector` JSON document (`--strokes outline`, the default, turns strokes into filled geometry; `--strokes ignore` drops them) |
+| PNG | passed through unchanged — validated by the same magic-byte sniff the drop target uses, not a full structural PNG decode |
+| JPEG / WebP / other raster | refused, naming the browser path instead |
+| TTF / OTF | parsed with opentype.js to prove it's readable, then copied through unchanged |
+
+**Headless raster conversion is out of scope, not merely unimplemented.** SVG
+conversion runs headlessly by installing `happy-dom` — an **optional peer
+dependency** (`npm install happy-dom`) — as a stand-in DOM and importing the
+same paper.js converter the drop widget uses; paper.js never touches the
+raster context for its geometry work, so a no-op `getContext` stub
+(`src/framework/ingest/node-dom.js`) is enough to satisfy it. Converting
+JPEG/WebP to PNG has no equivalent escape: it needs `createImageBitmap` and a
+real `<canvas>` to encode through, and happy-dom implements no canvas raster
+backend at all — there's no stub for a missing pixel pipeline the way there is
+for missing DOM structure. Convert those in a browser (drop the file onto the
+app's Image control) or with your own tooling before ingesting.
+
 ## Host jobs: extending the worker
 
 The worker's job loop handles a closed set of message types (`generate`, the exports,
@@ -2131,6 +2296,21 @@ yourself (e.g. to download from a different origin) instead of partforge's own D
   where `ImageAsset` is `{ id, label, url, width, height, thumbUrl }`. With no
   provider a `type: "image"` control degrades to a URL field.
 
+- `onAssetUpload(blob, { kind, filename }) → Promise<string>` — the drop target
+  shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files into a
+  part", below) calls this with the converted artifact after a drop, paste, or
+  file-picker choice, and writes whatever it resolves to into the param.
+  `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob, or the
+  original file for a font — never the user's raw drop; `kind` is `"image"`,
+  `"vector"`, or `"font"`. Must resolve to a non-empty source string (an
+  `https:` URL or a host-defined `pfc-asset:` token); anything else is treated
+  as a contract violation and reported through the control's own error line,
+  not written into the param. Omit it and the converted bytes land straight in
+  the param instead — the path a host that cannot fetch URLs (the
+  partforge-cloud sandbox) needs, not a degraded fallback. A rejection is
+  likewise reported through the control's error line, and the widget keeps the
+  converted artifact so a retry costs a network call, not a re-decode/re-parse.
+
 **Showcase capture (the mount handle).** The handle can also render the user's *current*
 framing offscreen at a resolution independent of the window size and devicePixelRatio —
 for gallery/preview images, where grabbing the live canvas would be capped at the viewer
@@ -2709,11 +2889,19 @@ the named file's `units` is `"artwork"` — unlike `k.text2d`'s cap-height `size
 artwork units carry no physical meaning, so there is no safe default to fall
 back on; an `"mm"` file's coordinates already are millimetres, so a size is
 genuinely optional there), `vector-unknown-shape` (a `k.vector2d(name, { shape })`
-call names a shape the file's `shapes` object doesn't contain) (all errors).
+call names a shape the file's `shapes` object doesn't contain), and
+`vector-control-not-in-vectors` (a `type: "vector"` control whose key never reaches
+`vectors:` — either because `vectors` is a static object, which cannot read a param
+at all, or because the function form never returns the picked value; the picker then
+changes a param and nothing else) (all errors). `vector-unknown-name` runs only for a
+static `vectors` object, whose names are statically knowable; for the function form
+`vector-control-not-in-vectors` asks the answerable question instead, by calling the
+function with a sentinel — the same complementary split `heightfield-unknown-image`
+and `image-control-not-in-images` use.
 `vector-size-missing` and `vector-unknown-shape` need `vectorDocs` (above) to
 read the file's `units`/`shapes` — without it, both stay silent rather than
-fire on every correct millimetre file or guess at shape names. All three judge
-the argument values the probe resolves under the part's default params, the
+fire on every correct millimetre file or guess at shape names. All three call
+rules judge the argument values the probe resolves under the part's default params, the
 same basis `import-unknown-name` uses; a call that only goes wrong for
 non-default params still fails correctly at build time.
 
@@ -3182,6 +3370,11 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
 - **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT
   ([probe-routed-to-occt](ERROR-PATTERNS.md#probe-routed-to-occt),
   [occt-holes-watertight-na](ERROR-PATTERNS.md#occt-holes-watertight-na)).
+- **Never let two cut tools share an exactly coincident face** — a bore whose radius
+  equals a thread's root radius, a cut ending flush with a face. Give them 0.05-0.1 mm
+  of deliberate clearance, or overshoot the cut. Mesh CSG shrugs; OCCT's boolean
+  degenerates, so the part previews instantly and the STEP export runs for minutes
+  ([boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang)).
 
 ---
 

package/docs/ERROR-PATTERNS.md

@@ -61,6 +61,12 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** OCCT fillet/chamfer cost scales with the number of selected edges, and an `inPlane` rim selector on a many-point extruded profile selects every polygon edge (hundreds for a gear), so one op call costs seconds — and re-runs on every parameter change while that path is active.
 - **Fix:** Use `extrude`'s `bevel` option instead of `chamfer` — same geometry, stays on the fast Manifold backend. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Beveling profile rims: extrude's bevel option".
 
+## boolean-coincident-faces-hang
+
+- **Symptom:** A part previews instantly but a STEP export (or any OCCT-path build) of one sub-part runs for minutes and never finishes, with no error, no warning, and no progress. Cutting each tool on its own is fast; only the combination hangs. Threaded parts are the usual victims.
+- **Cause:** Two cut tools in the same `cutAll` (or a tool and the body) share an *exactly* coincident face — most often a bore whose radius equals a thread's root radius, so the bore wall and the thread root lie on the same cylinder. OCCT's boolean has to classify a surface that is simultaneously on both operands, and the intersection search degenerates. Manifold's mesh CSG does not care, which is why the preview is fine and only the exact kernel suffers. Measured on one real part: bore alone 0.4 s, thread alone 5.4 s, both together did not finish in fifteen minutes; moving the bore 0.05 mm brought the pair to 12.6 s.
+- **Fix:** Give the surfaces a deliberate clearance instead of letting them land on the same number. Derive one from the other with an explicit gap — `const boreD = threadRootD - 2 * boreClearance;` with `boreClearance` around 0.05-0.1 mm — rather than reusing the same expression for both. The gap is far below a printable layer, so the fit is unchanged. The same rule covers a cut that ends exactly flush with a face (overshoot it by a few tenths, as the surrounding examples do with `+ 0.4` / `- 0.2`) and two tools that abut exactly end-to-end.
+
 ## chamfer-rescue-bisection
 
 - **Symptom:** `partforge: chamfer` warning saying the distance `over-ran the geometry — reduced to` a smaller one (or `has no valid distance`), with an attempt count and elapsed seconds, alongside slow builds.
@@ -673,7 +679,7 @@ between the Manifold preview and the OCCT STEP export.
 
 - **Symptom:** `vector2d: "` followed by the declared `vectors` name and a validation complaint — a bad `format` or `version`, a contour with no `kind` or an unknown one, a malformed `"path"` contour or segment (missing `start`, too few segments, an `arc` with no `through`, a `cubic` missing `c1`/`c2`, a non-numeric coordinate), a primitive with a bad `center`/`r`/`width`/`height`, a shape that is neither a region array nor a `{ role, regions }` object, an unknown `role`, a `bbox` that disagrees with the geometry, or (a different message, same `vector2d: "<name>"` lead) `vector2d: "<name>" is not valid JSON — <parse error>` — thrown while resolving a part's `vectors`, before `build` even runs.
 - **Cause:** The stored document isn't a well-formed `partforge-vector` file. The single most common case for the "is not valid JSON" variant: `vectors` points at the raw `.svg` file instead of an ingested `.vector.json` — an SVG document is not JSON at all, so it fails to parse before validation ever gets a chance to name a more specific problem.
-- **Fix:** If the message says "is not valid JSON," check the source points at the ingested `<name>.vector.json`, not the original `.svg` — re-ingest with `partforge/ingest` (or `node scripts/ingest-svg.mjs <file.svg>` in this repo) if you don't have it yet. Otherwise the message names the shape, the 1-indexed region, the role (`outer` / `hole n`), and where applicable the 1-indexed segment, so the fix is a single edit. Several specific cases have their own entries below (vector-units-missing, vector-stale-regions-array, vector-rect-radius-too-large). See [docs/VECTOR-FORMAT.md](VECTOR-FORMAT.md) for the full schema and what each field means.
+- **Fix:** If the message says "is not valid JSON," check the source points at the ingested `<name>.vector.json`, not the original `.svg` — re-ingest with `partforge/ingest` (or `npx partforge ingest <file.svg> --out <file.vector.json>`) if you don't have it yet. Otherwise the message names the shape, the 1-indexed region, the role (`outer` / `hole n`), and where applicable the 1-indexed segment, so the fix is a single edit. Several specific cases have their own entries below (vector-units-missing, vector-stale-regions-array, vector-rect-radius-too-large). See [docs/VECTOR-FORMAT.md](VECTOR-FORMAT.md) for the full schema and what each field means.
 
 ## vector-units-missing
 
@@ -769,9 +775,9 @@ between the Manifold preview and the OCCT STEP export.
 
 ## images-only-png-supported
 
-- **Symptom:** `images: only PNG is supported — convert with imageToPng() from "partforge" before storing, or have the host normalize on upload` thrown while resolving a part's `images`.
+- **Symptom:** `images: only PNG is supported — convert with imageToPng() from "partforge/ingest" before storing, or have the host normalize on upload` thrown while resolving a part's `images`.
 - **Cause:** The image resolver checks the first four bytes against the PNG magic number before decoding; a JPEG, WEBP, or any other format fails that check immediately; a heightfield source is a depth map and needs a single well-defined decode path, so no other format is attempted.
-- **Fix:** Convert the source to PNG before it reaches `images` — call `imageToPng()` (exported from `"partforge"`, browser-only: it draws through a `<canvas>`) in the host's upload/panel handler, or pre-convert with any image tool. Bytes that are already PNG (the 4-byte signature `89 50 4E 47`) skip this check entirely.
+- **Fix:** Convert the source to PNG before it reaches `images` — call `imageToPng()` (exported from `"partforge/ingest"`, browser-only: it draws through a `<canvas>`) in the host's upload/panel handler, or pre-convert with any image tool. Bytes that are already PNG (the 4-byte signature `89 50 4E 47`) skip this check entirely.
 
 ## png-interlaced-unsupported
 

package/docs/VECTOR-FORMAT.md

@@ -10,8 +10,10 @@ There are two ways a file gets here, and this document leads with the first:
   a triangular keyway. Coordinates are millimetres, and they place exactly where
   you drew them. This is the path an agent should reach for when the geometry is
   *drawn* rather than computed.
-- **Ingested.** Convert an existing `.svg` once, in a browser, with
-  `partforge/ingest`, and check the resulting JSON in beside the part. The
+- **Ingested.** Convert an existing `.svg` once — in a browser with
+  `partforge/ingest`, or headlessly with `npx partforge ingest <file.svg> --out
+  <file.vector.json>` (needs `happy-dom`, an optional peer dependency: `npm
+  install happy-dom`) — and check the resulting JSON in beside the part. The
   artwork keeps its own unitless coordinates and gets sized at every call site.
 
 Both produce the same format, load through the same validator, and behave
@@ -19,14 +21,15 @@ identically downstream.
 
 **Why this document is normative and not merely helpful.** Ingest needs a real
 DOM (it resolves `<use>`, `<defs>`, CSS, and bakes ancestor transforms, all of
-which require one), so partforge deliberately ships **no headless SVG
-conversion path** — `partforge measure|render|lint` read a part's already-stored
-JSON, but nothing headless can *create* it from an `.svg`. That trade was
-accepted only because this file is complete enough that someone — or some agent
-— with no browser and no access to partforge's source can write a compliant
-converter from it alone. Everything below is written to hold that property.
-`scripts/ingest-svg.mjs` (dev-only, not shipped) is the reference
-implementation, described in §6.
+which require one) — `partforge measure|render|lint` read a part's
+already-stored JSON, but neither of ingest's two entry points *creates* one
+without a DOM somewhere: a real browser for `partforge/ingest`, or a headless
+one (`happy-dom`) for the CLI. That trade was accepted only because this file
+is complete enough that someone — or some agent — with neither a browser nor
+happy-dom installed, and no access to partforge's source, can still write a
+compliant converter from it alone. Everything below is written to hold that
+property. The `ingest` verb in `bin/cli.js` is the reference implementation,
+described in §6.
 
 ## 1. A worked authored example
 
@@ -494,8 +497,9 @@ Shapes are named, regions and segments are 1-indexed, and the role (`outer` /
 One filled circle, and one **stroked, open** polyline — deliberately, so this one
 file exercises both of ingest's geometry paths (a fill, and a stroke that has to
 be outlined into a filled shape; see §6). Ingesting it
-(`node scripts/ingest-svg.mjs src/parts/assets/emblem.svg`) produces
-`src/parts/assets/emblem.vector.json`, checked in beside it. Here it is with the
+(`npx partforge ingest src/parts/assets/emblem.svg --out
+src/parts/assets/emblem.vector.json`) produces that file, checked in beside it.
+Here it is with the
 `note` field elided for brevity and the coordinate arrays put on one line —
 nothing else is changed:
 
@@ -662,12 +666,14 @@ followed by the one already-written reference to check your output against.
    file stays diffable and so a stored `bbox` matches a later recomputation from
    the *rounded* coordinates rather than drifting past the tolerance.
 
-`scripts/ingest-svg.mjs` in the partforge repository is the worked reference
-implementation of exactly this pipeline — it runs `partforge/ingest`'s real
-`ingestSvg()` (paper.js's `importSVG` for steps 1–2 and 4–5, this repo's own
+The `ingest` verb in `bin/cli.js` (`npx partforge ingest <file.svg> --out
+<file.vector.json>`) is the worked reference implementation of exactly this
+pipeline — it runs `partforge/ingest`'s real `ingestSvg()` (paper.js's
+`importSVG` for steps 1–2 and 4–5, this repo's own
 `contour-offset.js`/`stroke-outline.js` for step 3, and its own `arc-fit.js` for
-step 7) inside a headless DOM (`happy-dom`, a devDependency), specifically so
-that repository's own fixtures — including the worked example in §4 — are
+step 7) inside a headless DOM (`happy-dom`, an optional peer dependency —
+`src/framework/ingest/node-dom.js` installs it), specifically so that
+repository's own fixtures — including the worked example in §4 — are
 reproducible instead of being hand-maintained blobs, and so there is a second
 thing (besides this document) to check a from-scratch converter's output
 against: ingest the same SVG both ways and diff the JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.97.0",
+  "version": "0.99.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",
@@ -99,6 +99,14 @@
     "check": "node scripts/check-app.mjs",
     "offset-rates": "node scripts/offset-rates.mjs"
   },
+  "peerDependencies": {
+    "happy-dom": ">=20"
+  },
+  "peerDependenciesMeta": {
+    "happy-dom": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "dompurify": "^3.4.11",
     "fflate": "^0.8.3",