partforge 0.96.0 → 0.98.0

package/bin/cli.js

@@ -10,9 +10,9 @@ import { resolve, dirname, basename } from "node:path";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { detectBackend } from "../src/framework/backend-select.js";
 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";
@@ -23,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
@@ -94,17 +98,52 @@ 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
 // the CLI's base params; see "CLI limitation" in the design doc — a verify case
 // or animation frame that CHANGES the font param still builds with the
 // base-params face, because the kernel is booted once.
-const bootKernel = (part, params = {}) => {
+//
+// Same story for `images` — the third asset sibling (fonts.js / imports.js /
+// images.js), resolved with `imagesFor` exactly like `fonts` is with `fontsFor`,
+// since a part's `images` is commonly function-form (that's what lets a
+// `type: "image"` control drive the source). An unset control (isNoImageSource)
+// 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 = async (part, params = {}) => {
   const p = { ...(part.defaults ?? {}), ...params };
-  const opts = { fonts: fontsFor(part, p), imports: part.imports, vectors: part.vectors };
+  const imagesDecl = part.images ? (imagesFor(part, p) ?? {}) : undefined;
+  const images = imagesDecl &&
+    Object.fromEntries(Object.entries(imagesDecl).filter(([, src]) => !isNoImageSource(src)));
+  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 = {
@@ -120,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) {
@@ -150,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));
@@ -358,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,7 +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` |
+| `"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.
@@ -1578,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
@@ -1735,6 +1763,299 @@ build: (k, p, d) => {
 
 **CLI:** `partforge measure|render|lint` work on an importing part exactly as on any other — the `imports` field resolves in the CLI's Node boot the same way `fonts` does, no extra flags.
 
+## Height maps and images
+
+`k.heightfield(nameOrGrid, opts)` turns a grayscale depth map into a relief
+solid: a sampled grid on top, skirt walls down the sides, a flat cap at
+`z = 0`. It exists for one thing — a printable relief plate from a picture —
+and `src/parts/relief.js` is the worked example; read it alongside this
+section.
+
+**Declaring images (the `images` PartDefinition field):**
+
+Same grammar as `fonts` and `imports`, one more asset sibling:
+
+```js
+images: {
+  relief: new URL("./assets/relief-demo.png", import.meta.url), // Vite serves it; Node reads disk
+  logo:   "https://…/signed-url.png",                            // URL string
+  scan:   bytesOrThunk,                                           // ArrayBuffer/Uint8Array, or a (possibly async) thunk returning one
+},
+```
+
+`images` may also be a **function of the resolved params** — `images: (p) => ({...})`
+— which is what lets a `type: "image"` control pick the source. `relief.js` uses
+exactly this to fall back to a bundled sample when the control is empty:
+
+```js
+images: (p) => ({
+  relief: p.relief || new URL("./assets/relief-demo.png", import.meta.url),
+}),
+```
+
+**The empty-value fallback:** `p.relief` starts as `""` (its `defaults` entry),
+which reads as "no image chosen" — never a source to fetch, never a source
+`npx partforge lint`/the runtime warn about. A part is responsible for
+supplying its own fallback when a key resolves empty, exactly as above; an
+`images` entry that stays empty is simply dropped from registration (with a
+progress note, not an error), so a `build()` that still calls
+`k.heightfield(name, …)` for that name gets the same
+[`heightfield-unknown-image`](ERROR-PATTERNS.md#heightfield-unknown-image)
+throw as a typo'd name — the framework has no automatic "flat slab" behavior of
+its own; a part that wants one branches around the `k.heightfield` call itself
+when its source param is empty, the same way it would branch around any other
+optional feature.
+
+**The `type: "image"` control:** the control-types table above lists `"image"`
+— an image picker with a host-supplied catalog, or a plain URL text field
+without one. `allow` restricts what a **param-supplied** value (from the
+picker, or a pasted/shared URL) may be — the same shape as `font`'s `allow`,
+but with one fewer kind, since there's no image equivalent of Google Fonts'
+CDN allowance:
+
+| value | accepts |
+|---|---|
+| `"https"` | any `https:` URL. **The default** — omitting `allow` means `["https"]` |
+| `"asset"` | a `pfc-asset://` token — an image the host has stored for this part |
+
+A refused param falls back to `defaults[key]`, with a build warning naming the
+key — `image-source-scheme` (lint) catches a `defaults` value the control's own
+`allow` would itself refuse. As with `fonts`, `allow` only gates values that
+arrive as **params**; a source you write into `images` yourself is code, not
+user input, and is never checked against it.
+
+**`k.heightfield`'s options:**
+
+```js
+k.heightfield("relief", {
+  w: 60, d: 60,        // footprint, mm — REQUIRED, both > 0 (no default)
+  base: 1.5,            // solid slab thickness under the relief, mm (default 1; must be > 0 — zero is degenerate)
+  maxZ: 3,               // how far the tallest sample rises above base, mm (default 1)
+  pitch: 0.5,             // grid spacing, mm (default 0.5) — see "pitch" below
+  invert: false,           // swap high/low (default false)
+  range: [0, 1],            // remap the raw sample range before invert (default [0, 1] — identity)
+  origin: "center",         // "center" | "corner" — footprint placement in XY (default "center")
+});
+```
+
+`nameOrGrid` is either a name declared in `images`, or an inline
+`{ width, height, data: Uint16Array }` grid (bypassing `images`/PNG entirely —
+useful for procedural depth maps, as CI fixtures use).
+
+- **`range` is a remap with clamped ends, not an output clamp.** `range[0]` maps
+  to sample value 0, `range[1]` maps to sample value 1, and everything outside
+  `[range[0], range[1]]` clamps to the nearer end — it does not pass the raw
+  0..1 sample through unclamped and then chop the *output* height. `range: [0, 1]`
+  (the default) is the identity map: a raw sample stays exactly what it was.
+  This is exactly the tool for a source whose luminance never reaches the
+  extremes — `relief.js`'s bundled demo asset only spans roughly 39–75% of the
+  16-bit range (the ripple pattern that generated it decays toward mid-gray),
+  so left at the default `range` the demo would use well under half of `maxZ`;
+  it sets `range` to the asset's own measured extent to stretch that into the
+  full 0..1 span. **`invert` applies after the remap**, as `1 − t` on the
+  remapped value — it flips which end is raised, not which end of the source
+  range is used.
+- **`origin` positions the footprint in XY only.** `"corner"` puts the minimum
+  corner at `(0, 0)`; `"center"` (the default) centers the footprint on the
+  origin. Either way the **base always sits at `z = 0`** — `origin` never moves
+  the part vertically, only in X/Y.
+- **The image stretches to `w × d`.** Sampling maps the image's own aspect
+  ratio onto whatever rectangle `w`/`d` describe — a square source on a
+  non-square footprint stretches, it is not letterboxed or cropped.
+- **Axis convention:** a source PNG's row 0 (its first scanline — the visual
+  top of the file in an image viewer) maps to the footprint's **−Y** edge, with
+  Y increasing down the rows — the standard texture-coordinate convention, and
+  not something this framework special-cases. In practice: a depth map viewed
+  in the app from above (+Z) reads vertically flipped relative to the same file
+  open in an image viewer. If a source contains text or a logo and that
+  orientation matters, flip the source pixels before declaring it — `invert`
+  will not do this for you, since it remaps sampled *height*, not pixel
+  position.
+- **Vertex budget:** the sampled grid is `max(2, ceil(w/pitch))` ×
+  `max(2, ceil(d/pitch))` vertices. If that product would exceed 400,000,
+  `pitch` is scaled up uniformly until it fits (and, if still over, the two
+  counts are shrunk in lockstep) — a build warning names the clamped pitch
+  rather than the build hanging or throwing.
+
+**PNG only, in core.** `images` resolves exactly one format — a source that
+doesn't start with the PNG signature throws
+[`images-only-png-supported`](ERROR-PATTERNS.md#images-only-png-supported) —
+and the decoder itself rejects Adam7-interlaced files
+([`png-interlaced-unsupported`](ERROR-PATTERNS.md#png-interlaced-unsupported)).
+This is deliberate, not an oversight: the same pure-JS decoder
+(`src/framework/geometry/png-decode.js`) runs in the browser worker, the CLI,
+and CI alike, so the geometry a user previews, the geometry `partforge measure`
+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/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
+anyway and downsampling avoids shipping detail no `heightfield` call will ever
+sample.
+
+**`pitch` is the throttle for both triangle count and STEP size.** Every
+`w/pitch × d/pitch` grid cell becomes two triangles, plus a skirt and a cap —
+halving `pitch` roughly quadruples the triangle count. On a 60×60 mm plate,
+pitch 1.0 produces about 7,670 triangles and (on the OCCT backend) a STEP file
+around 17.6 MB; pitch 0.3 produces about 81,590 triangles and a STEP file
+around 206.5 MB, for the same footprint. STEP size is content-dependent — only
+genuinely coplanar faces merge during sewing, so a flat relief compresses far
+better than a high-frequency one at the same triangle count — but the linear
+relationship to triangle count holds regardless of content. Above 24,000
+triangles the OCCT backend's sewing step also slows down and warns on the same
+build; past a further, content-dependent point sewing can fail outright
+([`heightfield-sew-failed`](ERROR-PATTERNS.md#heightfield-sew-failed)), fixed
+by raising `pitch` or keeping the sub-part on the Manifold backend, which never
+sews through OCCT. Manifold's own preview has no such ceiling, so a fine
+`pitch` is always safe there — it only becomes expensive at STEP-export /
+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 —
+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. 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`,
+`image-source-scheme` — described in full under "Linting" → Rule catalog →
+"Image controls", below; this section only points there rather than repeating
+it.
+
+**CLI:** `partforge measure|render|lint` resolve `images` in the CLI's Node
+boot exactly the way `fonts`/`imports` do — no extra flags — with the same
+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,
@@ -1950,6 +2271,26 @@ yourself (e.g. to download from a different origin) instead of partforge's own D
   partforge ships no provider — a host supplies one, and without it every font
   control renders as a URL field.
 
+- `imageCatalog` — a provider backing every `type: "image"` control in the part:
+  `{ search(query, { limit }) → Promise<ImageAsset[]>, describe?(source) → { label, width, height } | null }`,
+  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
@@ -2477,7 +2818,24 @@ control that the control's own `allow` list would refuse — at build time it's
 swapped for `defaults[key]`, i.e. itself, so the part boots with no usable
 font; use a source `allow` accepts, or widen `allow`) (warning).
 
-**Source rules** — the ninth group, which runs only when the caller hands over
+**Image controls** — the sibling group for `type: "image"` controls, `images`,
+and `k.heightfield()`. `image-control-not-in-images` (a `type: "image"`
+control's `key` is never returned by `images` — unlike the font rule above,
+this one actually calls a function-form `images` with the control's key set to
+a sentinel value and checks whether the sentinel comes back out, because a
+picker only silently does nothing if the function ignores that specific key,
+not just any key; a static `images` object provably can't depend on any param,
+so it is skipped there — that is a different mistake, not this rule's business)
+(error); `heightfield-unknown-image` (a build calls `k.heightfield(name, opts)`
+with a string `name` absent from a **static** `images` object — skipped when
+`images` is a function, since its keys aren't statically known; an inline
+`{width, height, data}` grid as the first argument is never flagged, since that
+is a supported call shape, not a name) (error); `image-source-scheme`
+(`defaults` holds a value for an image control that the control's own `allow`
+list would refuse — same shape as `font-source-scheme` above, including the
+empty-string and raw-bytes exemptions from `image-source.js`) (warning).
+
+**Source rules** — the tenth group, which runs only when the caller hands over
 `sources` (above) — `control-default-not-literal` (a control's `defaults` entry is
 written as something other than a plain literal: an expression like `13 / 3`, an
 array or object, a template literal, a `0x10`/`1_000` spelling. Hosts persist a
@@ -2511,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.