partforge 0.96.0 → 0.98.0

package/src/framework/panel/widgets/image.js

@@ -0,0 +1,178 @@
+// The `type: "image"` control. Its VALUE is an image source — either a URL
+// string (the same grammar `PartDefinition.images` already accepts) or raw PNG
+// bytes (an ArrayBuffer/typed array): the partforge-cloud sandbox cannot fetch
+// URLs, so it puts the bytes straight in the param. Everything downstream
+// (presets, undo, the params hash, `when`) works with either shape, no special
+// case — this widget is the only place on the main thread that has to look at
+// the difference.
+//
+// Two renderings, mirroring widgets/font.js exactly. With a host-supplied
+// `imageCatalog` it is a button — a thumbnail + label — opening the picker.
+// Without one it degrades to a URL text field, so a standalone partforge app
+// (which ships no catalog) still exposes the parameter.
+//
+// Main-thread only: the preview is a plain `<img>` bound to the source URL —
+// the browser decodes the PNG natively. Do NOT import `png-decode.js` (or
+// anything from images.js) here; that decoder belongs to the worker's build
+// path, not the panel.
+import { attachInfo } from "../info.js";
+import { IMAGE_ALLOW_DEFAULT, imageSourceAllowed } from "../../image-source.js";
+import { mountDrop } from "./file-drop.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
+// A URL source → its filename, for a label with no catalog to ask. A byte
+// value has no filename — callers check `isBytes` first and never reach this
+// for one. Not a source to fetch, never a source to warn about: `isNoImageSource`
+// values (unset/"") read as "No image" rather than a broken link.
+export function imageLabel(source) {
+  if (typeof source !== "string" || !source) return "No image";
+  let path = source;
+  try { path = new URL(source).pathname; } catch { /* not a URL — use the raw string */ }
+  const file = path.split("/").filter(Boolean).pop();
+  return file || source;
+}
+
+// Point (or unpoint) the live preview. A byte-valued param has no URL to hand
+// the browser, so the image stays hidden rather than trying to render it or
+// showing a broken-image glyph — same rule an empty/unset value gets. `onerror`
+// covers the other broken-image case: a URL that 404s or that CORS refuses.
+function paintPreview(img, source) {
+  if (typeof source === "string" && source) {
+    img.hidden = false;
+    img.src = source;
+  } else {
+    img.hidden = true;
+    img.removeAttribute("src");
+  }
+}
+
+export function makeImage(node, params, { onChange, onCommit, info, imageCatalog, onAssetUpload } = {}) {
+  const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : IMAGE_ALLOW_DEFAULT;
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label ?? node.key);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+
+  const preview = document.createElement("img");
+  preview.className = "image-preview";
+  preview.alt = "";
+  preview.hidden = true;
+  // A URL that fails to load (404, CORS, revoked link) must degrade to hidden,
+  // not the browser's broken-image glyph.
+  preview.addEventListener("error", () => { preview.hidden = true; });
+  wrap.append(preview);
+
+  if (!imageCatalog) {
+    // Degraded path: a URL field. Unlike `text`, it does NOT write on every
+    // keystroke — a half-typed URL is a guaranteed failed fetch, and the
+    // rebuild loop would chase every one of them.
+    const field = document.createElement("input");
+    field.type = "text";
+    field.className = "text-input";
+    const paintField = () => {
+      const v = params[node.key];
+      // Bytes cannot round-trip through a text field — `String(arrayBuffer)`
+      // is "[object ArrayBuffer]", not a value anyone typed. Show an honest
+      // placeholder instead of that, and leave the field free to type a
+      // replacement URL over it.
+      field.value = isBytes(v) ? "" : String(v ?? "");
+      field.placeholder = isBytes(v) ? "Uploaded image" : "";
+      field.classList.remove("warn");
+      paintPreview(preview, v);
+    };
+    field.addEventListener("change", () => {
+      if (!imageSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
+      field.classList.remove("warn");
+      params[node.key] = field.value;
+      onChange?.();
+      onCommit?.();
+    });
+    paintField();
+    wrap.append(field);
+
+    const drop = mountDrop("image", {
+      params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
+    });
+    wrap.append(drop.el, drop.errorEl);
+
+    return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+  }
+
+  const btn = el("button", "image-btn");
+  btn.type = "button";
+  const thumb = document.createElement("img");
+  thumb.className = "image-btn-thumb";
+  thumb.alt = "";
+  thumb.hidden = true;
+  thumb.addEventListener("error", () => { thumb.hidden = true; });
+  const iname = el("span", "iname");
+  btn.append(thumb, iname);
+  btn.insertAdjacentHTML("beforeend",
+    '<svg class="caret" width="8" height="7" viewBox="0 0 8 7" aria-hidden="true"><polygon points="0,0 8,0 4,7" fill="currentColor"/></svg>');
+  wrap.append(btn);
+
+  // The value alone cannot describe a byte-valued source, and even a URL's
+  // filename is a guess a catalog can improve on. `describe` is optional and
+  // may be async, so the label is painted twice: an immediate honest guess,
+  // then the catalog's answer when it lands (same two-pass shape as font.js's
+  // `paint`, `paintSeq` included so a stale describe() can't win a race
+  // against a newer one).
+  let paintSeq = 0;
+  const paint = () => {
+    const src = params[node.key];
+    const seq = ++paintSeq;
+    paintPreview(preview, src);
+    paintPreview(thumb, src);
+    const show = ({ label: text, width, height }) => {
+      if (seq !== paintSeq) return;                  // a newer paint already won
+      iname.textContent = width && height ? `${text} (${width}×${height})` : text;
+    };
+    show(isBytes(src) ? { label: "Uploaded image" } : { label: imageLabel(src) });
+    if (typeof imageCatalog.describe !== "function") return;
+    Promise.resolve()
+      .then(() => imageCatalog.describe(src))
+      .then((d) => {
+        if (!d) return;
+        show({ label: d.label ?? (isBytes(src) ? "Uploaded image" : imageLabel(src)), width: d.width, height: d.height });
+      })
+      .catch(() => { /* a failed lookup keeps the immediate label */ });
+  };
+  paint();
+
+  // The picker registers itself through setImagePicker (see below); with no
+  // picker in the bundle the button is inert rather than broken.
+  //
+  // The handle is kept because the picker is a TAKEOVER: it appends itself to
+  // the rail, outside the panel root, so tearing the panel down does not take it
+  // with it. Without dispose() the element — and the `document` keydown listener
+  // that only close() unhooks — would outlive the panel holding a stale `params`.
+  let picker = null;
+  btn.addEventListener("click", () => {
+    picker = openImagePicker?.({ node, params, allow, imageCatalog, anchor: wrap, onPicked: () => { paint(); onChange?.(); onCommit?.(); } }) ?? null;
+  });
+
+  const drop = mountDrop("image", { params, node, onAssetUpload, onChange, onCommit, onRender: paint });
+  wrap.append(drop.el, drop.errorEl);
+
+  return {
+    el: wrap,
+    sync: paint,
+    dispose: () => { picker?.close(); picker = null; drop.dispose(); },
+  };
+}
+
+// Assigned by image-picker.js, which widgets/index.js imports for the side
+// effect. Kept as a mutable binding rather than a static import so this file
+// stays usable — and testable — without dragging the whole picker in.
+export let openImagePicker = null;
+export const setImagePicker = (fn) => { openImagePicker = fn; };

package/src/framework/panel/widgets/index.js

@@ -5,12 +5,16 @@ import { makeText } from "./text.js";
 import { makeCheckbox } from "./checkbox.js";
 import { makeSelect, makeRadio } from "./select.js";
 import { makeFont } from "./font.js";
-// Side-effect import: font-picker.js calls setFontPicker() at module scope, so
-// the font widget's button finds a picker to open. It lives HERE and not in
-// font.js because the dependency has to run picker → widget and never back —
-// font.js must stay importable (and testable) without dragging the whole
-// DOM-heavy picker in. See the note at the bottom of font.js.
+import { makeImage } from "./image.js";
+import { makeVector } from "./vector.js";
+// Side-effect imports: font-picker.js / image-picker.js call setFontPicker() /
+// setImagePicker() at module scope, so each widget's button finds a picker to
+// open. They live HERE and not in font.js/image.js because the dependency has
+// to run picker → widget and never back — those files must stay importable
+// (and testable) without dragging the whole DOM-heavy picker in. See the note
+// at the bottom of font.js.
 import "../font-picker.js";
+import "../image-picker.js";
 
 export const WIDGET_FACTORIES = {
   slider: makeNumeric,
@@ -21,4 +25,6 @@ export const WIDGET_FACTORIES = {
   select: makeSelect,
   radio: makeRadio,
   font: makeFont,
+  image: makeImage,
+  vector: makeVector,
 };

package/src/framework/panel/widgets/vector.js

@@ -0,0 +1,77 @@
+// The `type: "vector"` control. Its VALUE is vector artwork — either a URL
+// string (the same grammar `PartDefinition.vectors` already accepts) or the
+// PARSED partforge-vector document object a drop/paste conversion produces
+// (see file-drop.js's vector-kind handling and vectors.js's `asParsedFile`,
+// "the in-tree form" — a source that IS the parsed contents of its file
+// rather than a way to reach its bytes). `vectorsFor` (vectors.js) is what
+// lets a `type: "vector"` control drive the artwork: a part declares
+// `vectors: (p) => ({ name: p.art })` and this control writes `p.art`.
+//
+// Unlike font.js/image.js there is NO catalog provider for artwork — no
+// `vectorCatalog` exists (see the design doc's "no vector catalog provider"
+// note) — so this control has exactly ONE rendering: a URL field plus a
+// drop target. There is no picker button and nothing here degrades from a
+// richer form; this IS the whole control.
+//
+// Main-thread only: the real SVG -> partforge-vector conversion (paper.js)
+// runs inside `makeFileDrop` -> the registry's "vector" convert thunk,
+// never here.
+import { attachInfo } from "../info.js";
+import { VECTOR_ALLOW_DEFAULT, vectorSourceAllowed } from "../../vector-source.js";
+import { mountDrop } from "./file-drop.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+// A dropped/pasted SVG with no `onAssetUpload` host hook lands as the PARSED
+// document object (task-9 addendum, Ruling D) — an opaque value with nothing
+// a text field can show, the same rule image.js/font.js apply to a
+// byte-valued param.
+const isOpaque = (v) => isBytes(v) || (v != null && typeof v === "object");
+
+export function makeVector(node, params, { onChange, onCommit, info, onAssetUpload } = {}) {
+  const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : VECTOR_ALLOW_DEFAULT;
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label ?? node.key);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+
+  // The URL field. Unlike `text`, it does NOT write on every keystroke — a
+  // half-typed URL is a guaranteed failed fetch, and the rebuild loop would
+  // chase every one of them. Mirrors widgets/image.js's/font.js's own field.
+  const field = document.createElement("input");
+  field.type = "text";
+  field.className = "text-input";
+  const paintField = () => {
+    const v = params[node.key];
+    // A parsed document (or bytes) cannot round-trip through a text field —
+    // show an honest placeholder instead, and leave the field free to type a
+    // replacement URL over it.
+    field.value = isOpaque(v) ? "" : String(v ?? "");
+    field.placeholder = isOpaque(v) ? "Uploaded artwork" : "";
+    field.classList.remove("warn");
+  };
+  field.addEventListener("change", () => {
+    if (!vectorSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
+    field.classList.remove("warn");
+    params[node.key] = field.value;
+    onChange?.();
+    onCommit?.();
+  });
+  paintField();
+  wrap.append(field);
+
+  const drop = mountDrop("vector", {
+    params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
+  });
+  wrap.append(drop.el, drop.errorEl);
+
+  return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+}

package/src/framework/param-deps.js

@@ -3,6 +3,7 @@
 // affect what's visible. Pure — no DOM, no real geometry (reuses the geometry-free
 // probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
 import { createProbeKernel } from "./geometry/probe.js";
+import { byteAwareReplacer } from "./geometry/solid-hash.js";
 import { viewSubParts } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
 
@@ -125,7 +126,11 @@ export function subPartReadKeys(part, view, params) {
 }
 
 // Stable string of the given param keys' current values — the cache-validity key
-// for one sub-part. Sorted so key order never affects the result.
+// for one sub-part. Sorted so key order never affects the result. `byteAwareReplacer`
+// substitutes a content fingerprint for a byte-valued param (an ArrayBuffer/typed-array
+// image source — see its own header) so JSON.stringify's default handling doesn't
+// collapse every image to the same "{}" (cache never invalidates) or expand a typed
+// array to one JSON number per byte (see solid-hash.js).
 export function relevanceHash(keys, params) {
-  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]));
+  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]), byteAwareReplacer);
 }

package/src/framework/vector-source.js

@@ -0,0 +1,127 @@
+// What a PARAM-supplied vector source may be. Author-declared `vectors`
+// sources are code and get no restriction; this file exists only for the
+// other case — a value that arrived in `params`, which on a shared link is
+// attacker-controlled input that `vectors: (p) => …` would turn into a fetch
+// URL.
+//
+// This file's allow rule differs from its two siblings
+// (font-source.js/image-source.js) in ONE place, and getting that difference
+// right matters: those two exempt every non-string (bytes) source from the
+// allow check on the reasoning that an ArrayBuffer cannot survive a share
+// link — a URL can't carry megabytes, so bytes in params can only have been
+// placed there by the host's own trusted panel. That reasoning does NOT
+// transfer to vector artwork: `type: "vector"`'s drop target writes a PARSED
+// partforge-vector document — plain JSON — into params when there is no upload
+// hook, and unlike raw bytes, plain JSON round-trips a share link perfectly
+// (it's just more of the same params payload). Do not copy the
+// bytes-can't-survive-a-link justification here; it would be wrong.
+//
+// So the exemption this file grants is NOT "any object". The gate has to be
+// read against what asset-resolve.js actually does, in its order:
+// `unwrapModule(v)` runs FIRST, and only THEN does the resolver dispatch on
+// shape. A `{ default: "http://169.254.169.254/…" }` wrapper is therefore
+// unwrapped to a plain string and handed to `fetch` — arbitrary scheme,
+// arbitrary host, in ~40 bytes of JSON a share link carries effortlessly. An
+// earlier version of this file exempted every object on the claim that "an
+// object never reaches the fetch branch"; that claim was FALSE for exactly
+// this shape, and it is deleted rather than qualified.
+//
+// The rule that does hold, and what this file gates on, is: unwrap first, then
+// judge the value the RESOLVER will see.
+//
+//   - a string or `URL` — fetchable, so it gets the full `allow` treatment;
+//   - bytes (ArrayBuffer/view) — never handed to `fetch`, and (unlike JSON)
+//     genuinely cannot ride a link, so exempt;
+//   - a function/thunk — refused outright. Its return value is a fetch source
+//     that cannot be known at check time, so there is nothing to gate on;
+//   - a plain object that does NOT unwrap to any of the above — the genuinely
+//     inert case, the already-parsed partforge-vector document vectors.js's
+//     `asParsedFile` claims. It is validated downstream by `toInternalDocument`,
+//     a pure shape check that never touches the network, so it is exempt;
+//   - anything else (arrays, numbers, booleans) — refused. None of them is a
+//     valid source, and a refusal simply restores the part's default.
+//
+// `unwrapModule` is imported, never re-implemented: this gate is only sound
+// while it unwraps by exactly the same rule the resolver does.
+//
+// DOM-free and node:-free: jobs.js (worker graph) and the panel both import it.
+// asset-resolve.js is itself dependency-free, so importing it keeps
+// partforge/lint's zero-dependency closure intact.
+import { unwrapModule } from "./asset-resolve.js";
+
+export const VECTOR_ALLOW_DEFAULT = ["https"];
+
+const ASSET_SCHEME = "pfc-asset:";
+
+// The "unset" vector source. An empty value declares NO artwork for that
+// name — mirrors isNoFontSource/isNoImageSource exactly. Never a source to
+// fetch, and never a source to refuse.
+export const isNoVectorSource = (v) => v === undefined || v === null || v === "";
+
+const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
+
+// An already-parsed partforge-vector document: object-shaped, and not any of
+// the shapes the resolver reads as a way to REACH bytes. Deliberately the same
+// structural test vectors.js's `asParsedFile` applies (arrays excluded — an
+// array is never a file), so "what this gate exempts" and "what the resolver
+// adopts without fetching" stay the same set.
+const isParsedDocument = (v) =>
+  v != null && typeof v === "object" && !Array.isArray(v)
+  && !isBytes(v) && !(v instanceof URL);
+
+// Parse once; an unparseable string is refused rather than guessed at.
+function parse(source) {
+  try { return new URL(source); } catch { return null; }
+}
+
+export function vectorSourceAllowed(source, allow = VECTOR_ALLOW_DEFAULT) {
+  // Unwrap FIRST — asset-resolve.js does, before it dispatches on shape, so a
+  // `{ default: … }` wrapper must be judged by what it unwraps to. See header.
+  const v = unwrapModule(source);
+  // A thunk (before or after unwrapping) resolves to a source this check cannot
+  // see, so there is nothing to gate; refuse rather than trust it.
+  if (typeof source === "function" || typeof v === "function") return false;
+  if (isBytes(v)) return true;                    // never handed to `fetch`
+  if (isParsedDocument(v)) return true;           // inert; validated, never fetched
+  // Everything the resolver would fetch — a string or a `URL` — gets the full
+  // allow treatment. Everything else (arrays, numbers, booleans) is refused.
+  if (!(typeof v === "string" || v instanceof URL)) return false;
+  const u = v instanceof URL ? v : parse(v);
+  if (!u) return false;
+  for (const kind of allow) {
+    // hostname/protocol, never a substring of the raw string — same rule
+    // font-source.js's header explains: a URL merely CONTAINING
+    // "pfc-asset://" must not pass, and neither must a lookalike host.
+    if (kind === "https" && u.protocol === "https:") return true;
+    if (kind === "asset" && u.protocol === ASSET_SCHEME) return true;
+  }
+  return false;
+}
+
+// paramKey → allow list, for every `type: "vector"` control in the authored
+// tree — new-shape (`controls`, including nested groups) AND legacy-shape
+// (`advanced`/`toggles`/`features`, where panel/legacy.js desugars a
+// descriptor's `control:` field to `type:`), mirroring
+// imageControlAllows/fontControlAllows exactly. Missing the legacy arrays
+// here would leave a `{key, control:"vector"}` descriptor with no entry in
+// the returned map, and jobs.js's check only looks at keys present in the
+// map — so a legacy-declared vector control would get silently
+// unrestricted. Tolerant of any array being absent or malformed; it must
+// never throw on an existing part.
+export function vectorControlAllows(part) {
+  const out = new Map();
+  const visit = (nodes) => {
+    for (const n of nodes ?? []) {
+      if (!n || typeof n !== "object") continue;
+      if (Array.isArray(n.controls)) visit(n.controls);
+      if (Array.isArray(n.advanced)) visit(n.advanced);
+      if (Array.isArray(n.toggles)) visit(n.toggles);
+      if (Array.isArray(n.features)) visit(n.features);
+      if ((n.type === "vector" || n.control === "vector") && typeof n.key === "string") {
+        out.set(n.key, Array.isArray(n.allow) && n.allow.length ? n.allow : VECTOR_ALLOW_DEFAULT);
+      }
+    }
+  };
+  visit(part?.parameters);
+  return out;
+}

package/src/framework/vectors.js

@@ -83,6 +83,15 @@ const resolveOne = makeAssetResolver(
   (value) => asParsedFile(value) ?? undefined,
 );
 
+// `vectors` may be a plain { name: source } map, or a function of the resolved
+// params — the second form is what lets a `type: "vector"` control drive the
+// artwork. Resolving it needs `p`, which is why this is a separate step from
+// resolveVectors rather than folded into it. Mirrors fontsFor/imagesFor.
+export function vectorsFor(part, p) {
+  const decl = part?.vectors;
+  return typeof decl === "function" ? decl(p) : decl;
+}
+
 export async function resolveVectors(vectorsDecl) {
   // A function reaching here means a caller passed `part.vectors` raw, the way
   // fonts.js's resolveFonts guards against the same mistake for `part.fonts`.

package/src/ingest.js

@@ -6,3 +6,4 @@
 // Deliberately NOT re-exported from `partforge` (the main entry) or from
 // `partforge/geometry`: this must stay unreachable from the geometry worker.
 export { ingestSvg } from "./framework/ingest/svg-ingest.js";
+export { imageToPng } from "./framework/ingest/image-ingest.js";

package/src/parts/emblem.js

@@ -19,7 +19,8 @@
 //   work under Vite and fail in the CLI.
 //
 // The source artwork lives beside it as emblem.svg, and the .json is regenerated
-// with `node scripts/ingest-svg.mjs src/parts/assets/emblem.svg`. plate.vector.json
+// with `npx partforge ingest src/parts/assets/emblem.svg --out
+// src/parts/assets/emblem.vector.json`. plate.vector.json
 // is hand-authored — no ingest step, no source SVG — and is kept legible enough
 // to serve as documentation's worked example of a multi-shape, role-composed file.
 import plate from "./assets/plate.vector.json" with { type: "json" };

package/src/parts/relief.js

@@ -0,0 +1,84 @@
+// Reference part for the `images` field / `type: "image"` control / `k.heightfield`
+// (docs/AUTHORING-PARTS.md "Image controls"): a depth map becomes a printable relief
+// plate. `relief` is a `type: "image"` control — pick a replacement PNG from the
+// panel, or leave it empty and the bundled `assets/relief-demo.png` (a synthetic
+// concentric-ripple depth map) is used, so the part builds with no network access
+// and `partforge measure`/CI never need to fetch anything. `pitch` trades sampling
+// detail against triangle count — and therefore STEP size, since a fine pitch on a
+// high-frequency image produces many non-coplanar faces (see heightfieldMesh's own
+// STEP-size warning in the OCCT backend).
+//
+// DEMO_RELIEF_RANGE: the bundled asset's luminance only spans ~39–75% of the
+// 16-bit sample range (measured: 25443–48830 of 65535) — the ripple formula that
+// generated it decays toward its 50%-gray baseline away from the first ring, so
+// most pixels sit close to mid-gray. `k.heightfield`'s default `range: [0, 1]` is
+// an IDENTITY map (raw sample value straight to 0..1), not an auto-normalize, so
+// left alone the demo would use well under half of `maxZ`. This stretches the
+// default asset's own measured extent to the full 0..1 span so the shipped demo
+// shows the full relief amplitude. Applied only when the bundled default is in
+// use (`p.relief` empty) — a picked custom image's tonal range is unknown ahead
+// of build time, so it gets the identity range instead.
+export const DEMO_RELIEF_RANGE = [25443 / 65535, 48830 / 65535];
+
+export default {
+  meta: { title: "Relief plate", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "image",
+      title: "Image",
+      description: "The depth map the relief is sampled from. Bright = high, dark = low, unless inverted.",
+      controls: [
+        { key: "relief", type: "image", label: "Depth map",
+          description: "Pick a PNG from the catalog or paste a URL. Empty falls back to the bundled sample ripple." },
+        { key: "invert", type: "checkbox", label: "Invert",
+          description: "Swap which end of the image is raised — bright becomes low, dark becomes high." },
+      ],
+    },
+    {
+      id: "plate",
+      title: "Plate",
+      description: "Footprint and relief depth of the printed plate.",
+      advanced: [
+        { key: "w", label: "Width", unit: "mm", min: 20, max: 200, step: 1,
+          description: "Plate footprint along X." },
+        { key: "d", label: "Depth", unit: "mm", min: 20, max: 200, step: 1,
+          description: "Plate footprint along Y." },
+        { key: "base", label: "Base", unit: "mm", min: 0.5, max: 10, step: 0.1,
+          description: "Solid slab thickness under the relief — keep it thick enough to print flat and stay rigid." },
+        { key: "maxZ", label: "Relief height", unit: "mm", min: 0.2, max: 10, step: 0.1,
+          description: "How far the tallest sample rises above the base." },
+        { key: "pitch", label: "Detail", unit: "mm", min: 0.2, max: 2, step: 0.1,
+          description: "Grid spacing of the height sampling. Smaller is crisper but costs more triangles — see the file header." },
+      ],
+    },
+  ],
+  defaults: { relief: "", invert: 0, w: 60, d: 60, base: 1.5, maxZ: 3, pitch: 0.5 },
+  // The default is the bundled asset, so the part builds offline; a picked value
+  // (a URL or catalog source from the `type: "image"` control) replaces it.
+  images: (p) => ({
+    relief: p.relief || new URL("./assets/relief-demo.png", import.meta.url),
+  }),
+  parts: {
+    plate: {
+      label: "Relief plate",
+      views: ["relief"],
+      export: { name: "relief" },
+      build: (k, p) => k.heightfield("relief", {
+        w: p.w, d: p.d, base: p.base, maxZ: p.maxZ, pitch: p.pitch, invert: p.invert,
+        ...(p.relief ? {} : { range: DEMO_RELIEF_RANGE }),
+      }),
+    },
+  },
+  views: { relief: { label: "Relief" } },
+  // Self-verification: a heightfield solid is watertight and hole-free by
+  // construction (grid + skirt + cap, no cuts) — this pins that invariant rather
+  // than asserting anything image-specific. bbox bounds catch a runaway parameter;
+  // fdm-pla opts into the bed-fit gate for a plate meant to actually be printed.
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      plate: { watertight: true, holes: 0, bbox: "<=[200,200,20]" },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/relief-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/relief.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/testing/manifold.js

@@ -6,11 +6,12 @@ import { createManifoldKernel } from "../framework/geometry/manifold-backend.js"
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureImages } from "../framework/images.js";
 import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, vectors } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, images, vectors } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
@@ -25,6 +26,11 @@ export async function bootManifoldKernel({ quality = "preview", fonts, imports,
     const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
     await ensureImports(kernel, decl, meshes);
   }
+  // Third asset sibling: register declared images the same way as fonts/imports
+  // above, so a part using `k.heightfield` builds headlessly instead of hitting
+  // `heightfield: unknown image "…"` — file: sources need the same Node mapping
+  // (global fetch can't read them) that fonts/imports get from nodeAssetSources.
+  if (images && Object.keys(images).length) await ensureImages(kernel, nodeAssetSources(images));
   if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/src/testing/occt.js

@@ -8,10 +8,11 @@ import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureImages } from "../framework/images.js";
 import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes, images, vectors } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -23,6 +24,8 @@ export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } =
   if (fonts) { const opentype = normalizeOpentype(await import("opentype.js"));
     for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, parseFont(opentype, buf, name)); }
   if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
+  // Third asset sibling: see bootManifoldKernel's matching comment.
+  if (images && Object.keys(images).length) await ensureImages(kernel, nodeAssetSources(images));
   if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }