partforge 0.97.0 → 0.98.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

@@ -711,8 +711,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 +1580,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 +1889,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 +1915,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 +1941,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 +2276,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 +2869,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.
 

package/docs/ERROR-PATTERNS.md

@@ -673,7 +673,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 +769,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.98.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",

package/src/framework/font-source.js

@@ -3,6 +3,20 @@
 // for the other case — a value that arrived in `params`, which on a shared link
 // is attacker-controlled text that would otherwise become a fetch URL.
 //
+// Bytes bypass the allow check. This file's older rule refused every non-string
+// on the grounds that "bytes/thunks are never param-supplied"; that stopped
+// being true when the panel gained a drop target. The replacement rule is
+// sound and is the same one image-source.js states: an ArrayBuffer in params
+// definitionally did not arrive via a shared link, because a URL cannot carry
+// megabytes — so it can only have been placed there by the host's own panel,
+// which is trusted code. That plausibility argument isn't the load-bearing
+// one, though — the structural fact is that asset-resolve.js's resolver
+// fetches only a `string`/`URL` source; a byte source is consumed directly
+// and never becomes a request. Bytes therefore cannot reach the network no
+// matter how they got into params, which is what the allow list exists to
+// gate, and is what still holds even if a host someday puts a few bytes of
+// base64 in a link.
+//
 // DOM-free and node:-free: jobs.js (worker graph) and the panel both import it.
 
 export const FONT_ALLOW_DEFAULT = ["https"];
@@ -21,13 +35,16 @@ export const isNoFontSource = (v) => v === undefined || v === null || v === "";
 const GSTATIC_HOST = "fonts.gstatic.com";
 const ASSET_SCHEME = "pfc-asset:";
 
+const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
 // Parse once; an unparseable string is refused rather than guessed at.
 function parse(source) {
   try { return new URL(source); } catch { return null; }
 }
 
 export function fontSourceAllowed(source, allow = FONT_ALLOW_DEFAULT) {
-  if (typeof source !== "string") return false;   // bytes/thunks are never param-supplied
+  if (isBytes(source)) return true; // see the file header — bytes always bypass the allow check
+  if (typeof source !== "string") return false;
   const u = parse(source);
   if (!u) return false;
   for (const kind of allow) {

package/src/framework/image-source.js

@@ -2,14 +2,18 @@
 // code and get no restriction; this file exists only for the other case — a
 // value that arrived in `params`.
 //
-// This deliberately diverges from font-source.js in one place. That file refuses
-// every non-string on the grounds that "bytes/thunks are never param-supplied".
-// For images they ARE: the partforge-cloud sandbox cannot fetch URLs and puts PNG
-// bytes straight in the param. The replacement rule is sound — an ArrayBuffer in
-// params definitionally did not arrive via a shared link, because a URL cannot
-// carry megabytes, so it can only have been placed there by the host's own panel,
-// which is trusted code. Bytes therefore bypass the allow check entirely, for
-// every allow list. Do NOT copy font-source.js's non-string refusal here.
+// font-source.js states and follows the same rule, and its header explains why
+// it holds: an ArrayBuffer in params definitionally did not arrive via a shared
+// link, because a URL cannot carry megabytes — so it can only have been placed
+// there by the host's own panel, which is trusted code (the partforge-cloud
+// sandbox cannot fetch URLs and puts PNG bytes straight in the param, which is
+// exactly this case). That plausibility argument isn't the load-bearing one,
+// though — the structural fact is that asset-resolve.js's resolver fetches
+// only a `string`/`URL` source; a byte source is consumed directly and never
+// becomes a request. Bytes therefore cannot reach the network no matter how
+// they got into params, which is what the allow list exists to gate, and is
+// what still holds even if a host someday puts a few bytes of base64 in a
+// link. Bytes bypass the allow check entirely, for every allow list.
 //
 // DOM-free and node:-free: jobs.js (worker graph) and the panel both import it.
 

package/src/framework/images.js

@@ -24,7 +24,7 @@ const resolveOne = makeAssetResolver(
     for (let i = 0; i < 4; i++) {
       if (u8[i] !== PNG_SIG[i]) {
         throw new Error(
-          "images: only PNG is supported — convert with imageToPng() from \"partforge\" before storing, " +
+          "images: only PNG is supported — convert with imageToPng() from \"partforge/ingest\" before storing, " +
           "or have the host normalize on upload",
         );
       }