partforge 0.96.0 → 0.98.0

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
 
@@ -761,6 +761,30 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** The source contains `Math.random`, `Date.now`, `performance.now`, or an argless `new Date()`. A build must be a pure function of `(k, p, d)`; the memoizing kernel hashes inputs, so an impure value silently serves stale geometry (see impure-build-stale-preview, above). The behavioral lint probe catches impurity only when it changes the recorded call sequence between two probe runs; a value stable within one pass escapes it, which is why the source scan warns on the token itself.
 - **Fix:** Replace the impure value with a parameter or a `derive()` output. `new Date(0)` and other argument-carrying forms are deterministic and not flagged; only `.js`/`.mjs` files are scanned, so the same words in a `README.md` are prose. One finding is emitted per (file, token) pair, carrying the occurrence count and the first occurrence's line. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Caching & determinism".
 
+## heightfield-unknown-image
+
+- **Symptom:** `heightfield: unknown image "<name>"` — declare it in the part's `images` field — thrown from a build calling `k.heightfield(name, opts)`, identical text on both backends.
+- **Cause:** `k.heightfield` was called with a string name that isn't a key in the part's `images` field (or `images` is missing entirely) — a typo, or the declaration was never added. Same failure shape as `k.import`'s unknown-name error and `text2d`'s unknown-font error.
+- **Fix:** Add the name to `images`, or fix the typo. `npx partforge lint <part>` catches this statically when `images` is a static object (rule `heightfield-unknown-image` — a function-form `images` has no statically-knowable keys, so lint skips it there and this throw remains the runtime authority). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Linting" (Rule catalog → Image controls).
+
+## images-only-png-supported
+
+- **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/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
+
+- **Symptom:** `decodePng: interlaced (Adam7) PNGs are not supported — re-save without interlacing` thrown while resolving a part's `images`.
+- **Cause:** The bundled PNG decoder implements only the non-interlaced scanline layout (interlace method 0); an Adam7-interlaced PNG (interlace method 1 — some export tools and "optimized" PNGs default to it) stores pixels in seven interleaved passes the decoder doesn't reassemble.
+- **Fix:** Re-save the PNG without interlacing (most editors/optimizers have a plain "none"/"no interlace" option), or run it back through `imageToPng()` — canvas re-encoding never interlaces.
+
+## heightfield-sew-failed
+
+- **Symptom:** `heightfield: could not sew <n> triangles into a B-rep solid (<reason>). Raise \`pitch\` to reduce the triangle count, or build this sub-part on the Manifold backend.` thrown on the OCCT backend.
+- **Cause:** OCCT's heightfield path triangulates the depth-map grid the same way Manifold does, then goes mesh → STL → B-rep (`StlAPI_Reader` + `ShapeUpgrade_UnifySameDomain` + `MakeSolid`) so the result can boolean/fillet/export to STEP like any other B-rep shape. That sewing step can fail outright on a large or high-frequency grid — before failure, a triangle count above the plan's measured threshold already emits a slow-sew/large-STEP warning on the same build (see `feature-skipped-warning`'s sibling channel), and this is what happens when the grid is pushed further still.
+- **Fix:** Raise `pitch` on the `k.heightfield` call to coarsen the grid (fewer triangles to sew), or keep this sub-part on the Manifold backend (drop the `meta.backend`/CAD-op pin forcing OCCT) — Manifold's heightfield path never sews through OCCT, so it has no equivalent failure mode. STEP export specifically needs OCCT, so a part that must export a relief to STEP has to bring the triangle count under the sewable range rather than avoid OCCT.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -289,6 +289,7 @@ above. All ops return a `Solid`.
 | `helixSweptTube({pathR, profileR, pitch, turns, z0, lefthand})` | Circle of radius `profileR` swept along a helix (e.g. a rope groove). Circular profile on a frenet frame that rolls with the helix — **not for threads**; use `screwSweep`. |
 | `screwSweep({profile, pitch, turns, lefthand})` | Screw-motion sweep of an axial lathe profile `[[r, z], …]` (r ≥ 0) — threads. The profile travels to `(r·cosθ, r·sinθ, z + pitch·θ/2π)`; `h = pitch · turns`. Axial extent must not exceed `pitch` or consecutive turns interpenetrate (throws). A profile spanning exactly `pitch` is **periodic**: first and last radius must agree, and it yields a complete threaded body needing no boolean. Compound: the polar-remapped, densified section extruded with `twist = 360 · turns`, exactly as composed in `kernel-front.js`; a backend may override only for caching, never for different geometry. Options-only. Parity: **within tolerance, not by construction** — both backends receive the identical densified polygon, but the mesh backend facets the twist at its own resolution while the B-rep backend builds an exact spline (`hull`'s parity class). |
 | `loftSmooth({sections, stations?, samples?, shading?, closed?})` | Spline-interpolated loft of ≥2 sparse control sections — loft-style ring specs `{polygon\|sides+radius\|curve contour\|Shape2D, z, rotate?, scale?, sharp?}`; vertex counts **may differ**. A point section may tag `sharp: [indices]` as true corners (integers in `0…points.length-1`, sorted/deduped silently); a curve/`Shape2D` section takes corners implicitly from its non-smooth joints (single-region, hole-free, `loftSmooth:`-prefixed `k.loft` validation) and rejects an explicit `sharp`. Every section must resolve to the **same corner count `m`** (frozen error otherwise); with `m ≥ 1` corner 0 anchors the seam (replacing vertex 0), with `m = 0` v1's vertex-0 anchor holds verbatim. Compound (`kernel-front.js` + `loft-smooth.js`): each section's outline is a closed centripetal Catmull-Rom split into `m` clamped open arcs at its corners (or one closed periodic CR when `m = 0`); the `samples` budget is apportioned across arcs by mean arc-length fraction (largest-remainder, min 1 span/arc) and each arc resampled by arc length — total ring vertex count is `samples`, identical across sections, exactly v1's invariant now corner-anchored. The cross-station direction is v1 verbatim (shared centroid-spine knots, per-vertex CR, reflection phantoms at the ends, or periodic knots when `closed: true`). What's new is emission: every station — the dense list and the sparse `stations:"controls"` list alike — is fitted back to an **all-cubic Bézier contour**, arc-by-arc, via exact 4-point CR→Bézier inversion, so **both backends receive identical curve rings**. A B-rep kernel lofts the sparse control wires with its native smooth skin (`ruled: false`) — curve-exact around each ring in STEP (the densified-*point*-wire alternative measured 23 s / WASM-abort territory, which curve wires don't hit). A mesh kernel densifies `stations` rings and lofts them through `k.loft`'s curve-mode per-segment sampling, creasing sharp/corner columns via loft's geometric corner policy. `closed: true` (default false; needs ≥3 control sections, frozen error otherwise) makes the cross-station CR periodic (no reflection phantoms, ring 0 not repeated) and is **Manifold-only**, same restriction as `loft` `closed: true`: a B-rep kernel throws `loftSmooth: closed:true loops are only supported on the Manifold backend` in the composition, before building any rings; combining `closed: true` with `stations:"controls"` is rejected as a defensive invariant (reachable only by explicitly passing the internal `stations:"controls"` value; the composition never produces the combination itself). Options-only. Defaults `stations = (n−1)·8+1` open / `n·8` closed (raised to the section count `n` when lower), `samples = max(64, largest section)` (raised to the corner count `m` when lower); clamps 2…1024 / 8…2048 — the defaults cap themselves at the ceilings, only explicit out-of-range values throw. The surface interpolates every control section exactly. Parity: **within tolerance** (`screwSweep`'s class, unchanged from v1 — ~0.4% measured on the propeller reference part, test-gated at 2%). STEP is now curve-exact around each ring (previously faceted at the `samples` LOD); the cross-station skin remains ThruSections' native fit, not the shared CR — exact cross-station B-splines are a v3 candidate. Additive: `sharp`, curve/`Shape2D` sections, and `closed` are new options on top of v1's `{sections, stations?, samples?, shading?}`; `CONTRACT_VERSION` stays 4 — the same non-bump precedent as `import` above, a refinement inside the op's already-stated tolerance class rather than a new one. |
+| `heightfield(nameOrGrid, {w, d, base?, maxZ?, pitch?, invert?, range?, origin?})` | A depth map as a relief solid: a sampled grid top at `z = base + maxZ·f(v)`, skirt walls, and a flat base cap at `z = 0`. `nameOrGrid` is a name declared in the part's `images` field, or an inline `{width, height, data}` grid. Sample count per axis is `max(2, ceil(w/pitch))` and `max(2, ceil(d/pitch))`; if their product exceeds a vertex budget, `pitch` is scaled up uniformly to fit and, if still over, the two counts are shrunk in lockstep — with a `takeBuildWarnings` message rather than an error. `range` is a remap with clamped ends (`range[0]`→0, `range[1]`→1); `invert` applies after, as `1−v`. `origin` positions the footprint in XY only — the base always sits at `z = 0`. The image stretches to `w × d`; aspect is not preserved. **Axis convention:** sample row 0 (a source PNG's first scanline, i.e. its visual top in an image viewer) maps to the footprint's **−Y** edge — Y increases with row, the standard texture-coordinate mapping — so a depth map viewed from +Z looks vertically mirrored relative to the same file opened in a viewer; flip the source pixels before declaring the image if that orientation is unwanted (`invert` remaps height values, not position, and does not affect this). Fed by an underscore-prefixed side-channel (`_registerImage`), not part authors — see [Conformance classes](#conformance-classes). Required on both in-repo backends: Manifold imports the triangles directly, OCCT sews them into a faceted B-rep via `importSTL`, so STEP export carries a triangulated surface rather than an analytic one. Parity: **exact** — both backends receive byte-identical triangle data. Additive: `CONTRACT_VERSION` stays 4, the same precedent as `import` and `loftSmooth`. |
 | `union(solids[])` | Boolean union of one or more solids. |
 | `text2d(string, {size, font?, align?, valign?, lineHeight?, tracking?, kerning?})` | Outline-font text → `Shape2D`. `size` = cap height (mm). `font` = declared name / inline bytes / default. Build-time; curve-exact on OCCT, faceted on Manifold. |
 | `vector2d(name, {shape?, width\|height\|fit, align?, valign?})` | A declared vector document → `Shape2D`. `name` = a declared name in the part's `vectors` field (`partforge-vector` JSON — authored by hand or ingested from an `.svg`; never raw `.svg`). With no `shape`, the document's own composition: every `"add"` shape unioned minus every `"subtract"` shape; `shape` selects one named shape's geometry whatever its role. Sizing follows the document's required `units`: `"artwork"` requires exactly one of `width`/`height`/`fit` in millimetres, `"mm"` places as authored (scale 1, no translate) and accepts a size option optionally; more than one is refused. Uniform scale in every case (`fit` = larger extent); `align`/`valign` position it, same as `text2d`, defaulting to centre/middle for `"artwork"` and to no translate for `"mm"`. **The composed call derives ONE transform from every region in the document**, `"add"` and `"subtract"` alike, so a size or align option cannot scale the subtracts relative to the adds; a `shape` call is measured against that shape alone. **Primitive contours (`circle`/`rect`/`polygon`) expand to ordinary path contours at the format boundary, in `vector-format.js`, so this op's kernel-facing contract is unchanged by them** — nothing below the loader learns primitives exist. Conformance: **both backends** (it lowers to `shape2d` + `union`, exactly like `text2d`). Parity: **identical across backends by construction** — the regions are curve-native (arcs/cubics), so there is no sampling step for the two backends to diverge over. |

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.96.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/app-relief.js

@@ -0,0 +1,16 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import reliefPart from "./parts/relief.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the relief reference part. `npm run dev`, then open /relief.html.
+// The `new Worker(new URL(...))` call must stay inline here or Vite will not bundle it.
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(reliefPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./relief-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/app.css

@@ -211,6 +211,36 @@ textarea.text-input { min-height: 64px; resize: vertical; }
 .font-btn .caret { flex: none; opacity: .5; }
 .text-input.warn { border-color: var(--pf-err); color: var(--pf-err); }
 
+/* the `type: "image"` control — a live preview above either a URL field or a
+   picker button (mirrors .font-btn; a thumbnail stands in for the in-face name). */
+.image-preview { display: block; width: 100%; max-height: 120px; object-fit: contain;
+  margin-bottom: 6px; border-radius: var(--pf-radius-control); background: var(--pf-input-bg); }
+.image-btn { width: 100%; display: flex; align-items: center; gap: 8px; text-align: left; cursor: pointer;
+  background: var(--pf-input-bg); color: var(--pf-text-strong);
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 7px 9px; }
+.image-btn:hover { border-color: color-mix(in oklab, var(--pf-accent) 45%, var(--pf-border)); }
+.image-btn:focus-visible { outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
+.image-btn-thumb { flex: none; width: 28px; height: 28px; object-fit: cover;
+  border-radius: calc(var(--pf-radius-control) - 2px); background: var(--pf-surface-2); }
+.image-btn .iname { flex: 1; min-width: 0; font-size: 13px; line-height: 1.25;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.image-btn .caret { flex: none; opacity: .5; }
+
+/* the image picker's thumbnail grid — same takeover chrome as the font picker
+   (.picker/.pk-head/.pk-search), a grid in place of the virtualized list. */
+.pk-img-grid { flex: 1; overflow-y: auto; display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(84px, 1fr)); gap: 8px;
+  padding: 10px var(--pf-rail-pad) 12px; align-content: start; }
+.pk-img-card { display: flex; flex-direction: column; gap: 4px; border: 1px solid transparent;
+  border-radius: var(--pf-radius-control); background: transparent; cursor: pointer; padding: 4px; }
+.pk-img-card:hover { border-color: color-mix(in oklab, var(--pf-accent) 45%, var(--pf-border)); }
+.pk-img-card[data-sel="true"] { border-color: var(--pf-accent); background: var(--pf-accent-soft); }
+.pk-img-thumb { width: 100%; aspect-ratio: 1; object-fit: cover;
+  border-radius: calc(var(--pf-radius-control) - 2px); background: var(--pf-surface-2); }
+.pk-img-cap { font: 9px/1.3 var(--pf-mono); color: var(--pf-hint);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
 /* crafted range slider — hairline track + CAD-blue handle (the panel's signature control) */
 input[type="range"] { -webkit-appearance: none; appearance: none; width: 100%; height: 18px; margin: 0; background: transparent; cursor: pointer; }
 input[type="range"]::-webkit-slider-runnable-track { height: 3px; border-radius: 2px; background: var(--pf-border); }

package/src/framework/backend-select.js

@@ -4,6 +4,7 @@
 // everything in geometry/, which is part-agnostic.
 import { createProbeKernel } from "./geometry/probe.js";
 import { isZeroMagnitudeCadOp } from "./geometry/op-options.js";
+import { byteAwareReplacer } from "./geometry/solid-hash.js";
 import { resolveDerived } from "./derive.js";
 
 /**
@@ -57,8 +58,12 @@ export function detectBackend(part, params = {}) {
 export function createBackendPolicy(part, { forced = null } = {}) {
   let latchedParams = null;  // JSON snapshot of the params proven at runtime to need OCCT
   let latchedNames = null;   // the sub-parts that proved it (null = all of them)
+  // byteAwareReplacer: an image param carried as raw bytes must fingerprint by
+  // content here too, or a swapped image either silently reuses a stale OCCT
+  // latch (ArrayBuffer → the same "{}" for any image) or the reroute check
+  // spends its time re-stringifying megabytes of typed-array bytes every regen.
   const latched = (params, name) =>
-    latchedParams !== null && latchedParams === JSON.stringify(params) &&
+    latchedParams !== null && latchedParams === JSON.stringify(params, byteAwareReplacer) &&
     (latchedNames === null || latchedNames.has(name));
   return {
     // name → backend for a preview generate; mount groups sub-parts by this.
@@ -78,7 +83,7 @@ export function createBackendPolicy(part, { forced = null } = {}) {
     // `subparts` names the failed job's sub-parts; omitted (an export job, which
     // doesn't carry them) it latches the whole part for these params.
     noteNeedsOcct(params, subparts) {
-      latchedParams = JSON.stringify(params);
+      latchedParams = JSON.stringify(params, byteAwareReplacer);
       latchedNames = subparts ? new Set(subparts) : null;
     },
   };

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/geometry/heightfield.js

@@ -0,0 +1,129 @@
+// Pure grid → triangle mesh for k.heightfield. Backend-agnostic by design: it
+// returns plain {positions, indices} that Manifold takes via manifoldFromMesh
+// and OCCT takes via meshToStl → importSTL, so both backends build from
+// byte-identical triangle data. DOM-free and node:-free (worker graph).
+//
+// fanCap is reused verbatim from mesh-build.js (it takes a ringStart). sideQuads
+// is NOT reusable here: it derives ring bases as i*ringSegs, which assumes rings
+// start at V[0], and our vertex array leads with the grid. The skirt is the
+// explicit loop below.
+import { fanCap } from "./mesh-build.js";
+
+// Ceiling on grid vertices, so an ambitious pitch degrades instead of hanging.
+export const HEIGHTFIELD_VERTEX_BUDGET = 400000;
+
+const U16 = 65535;
+
+// FNV-1a over a Uint16Array's raw sample values — same fold as solid-hash.js's `h`,
+// but a dedicated loop: `h`'s generic `canon()` treats a typed array as a plain
+// object (Object.keys on it), which works but is wasteful for a heightfield grid
+// that may hold up to HEIGHTFIELD_VERTEX_BUDGET samples. Used only to give an
+// UNCACHED inline heightfield grid a real content fingerprint in its solid's own
+// `_hash`, so composing it with another op afterward (union/cut) doesn't inherit
+// the same "two different things, one key" collision risk the cache bypass exists
+// to avoid. Lives here, beside the grid contract itself, so BOTH backends
+// fingerprint an inline grid the same way (it started out module-local in
+// manifold-backend.js; the OCCT backend needs the identical bypass).
+export function hashGridData(data) {
+  let hsh = 0x811c9dc5;
+  for (let i = 0; i < data.length; i++) { hsh ^= data[i]; hsh = Math.imul(hsh, 0x01000193); }
+  return (hsh >>> 0).toString(36);
+}
+
+// Bilinear sample of a row-major Uint16 grid. u/v in 0..1 → 0..1.
+export function sampleGrid(grid, u, v) {
+  const { width: W, height: H, data } = grid;
+  const x = Math.min(Math.max(u, 0), 1) * (W - 1);
+  const y = Math.min(Math.max(v, 0), 1) * (H - 1);
+  const x0 = Math.floor(x), y0 = Math.floor(y);
+  const x1 = Math.min(x0 + 1, W - 1), y1 = Math.min(y0 + 1, H - 1);
+  const fx = x - x0, fy = y - y0;
+  const a = data[y0 * W + x0], b = data[y0 * W + x1];
+  const c = data[y1 * W + x0], d = data[y1 * W + x1];
+  return ((a + (b - a) * fx) + ((c + (d - c) * fx) - (a + (b - a) * fx)) * fy) / U16;
+}
+
+export function heightfieldMesh(grid, opts = {}) {
+  const { w, d, base = 1, maxZ = 1, invert = false, range = [0, 1], origin = "center" } = opts;
+  let { pitch = 0.5 } = opts;
+  const warnings = [];
+
+  if (!(w > 0) || !(d > 0)) throw new Error("heightfield: w and d must be positive");
+  if (!(base > 0)) throw new Error("heightfield: base must be > 0 (a zero base is degenerate)");
+  if (!(pitch > 0)) throw new Error("heightfield: pitch must be > 0");
+
+  // Floor of 2 samples per axis: X()/Y()/Z() divide by (nx-1)/(ny-1) to map
+  // sample indices to 0..1, so nx or ny === 1 would divide by zero. 2 is also
+  // the minimum for a meaningful grid (one quad).
+  const count = (len, p) => Math.max(2, Math.ceil(len / p));
+  let nx = count(w, pitch), ny = count(d, pitch);
+  if (nx * ny > HEIGHTFIELD_VERTEX_BUDGET) {
+    // Scale pitch up uniformly until the grid fits, then recompute.
+    const scale = Math.sqrt((nx * ny) / HEIGHTFIELD_VERTEX_BUDGET);
+    const clamped = pitch * scale;
+    warnings.push(`heightfield: pitch ${pitch} clamped to ${clamped.toFixed(3)} (vertex budget ${HEIGHTFIELD_VERTEX_BUDGET})`);
+    pitch = clamped;
+    nx = count(w, pitch); ny = count(d, pitch);
+    // An extreme aspect ratio (e.g. d <= pitch pins ny at its floor of 2
+    // while w/pitch is still huge) can leave the uniform pitch-scale above
+    // unable to bring nx*ny under budget on its own, since a floored axis
+    // has nothing left to give up proportionally. Decrementing both axes
+    // unconditionally would then walk the pinned one straight through the
+    // count() floor to 1 or 0 — reintroducing the divide-by-(n-1) and empty
+    // top-grid failures that floor exists to prevent. Hold each axis at 2.
+    while (nx * ny > HEIGHTFIELD_VERTEX_BUDGET && (nx > 2 || ny > 2)) {
+      if (nx > 2) nx--;
+      if (ny > 2) ny--;
+    }
+  }
+
+  const [lo, hi] = range;
+  const span = hi - lo;
+  // range is a REMAP with clamped ends: lo→0, hi→1. invert applies after.
+  const f = (v) => {
+    const t = span === 0 ? 0 : Math.min(Math.max((v - lo) / span, 0), 1);
+    return invert ? 1 - t : t;
+  };
+
+  const x0 = origin === "corner" ? 0 : -w / 2;
+  const y0 = origin === "corner" ? 0 : -d / 2;
+  const X = (i) => x0 + (i / (nx - 1)) * w;
+  const Y = (j) => y0 + (j / (ny - 1)) * d;
+  const Z = (i, j) => base + maxZ * f(sampleGrid(grid, i / (nx - 1), j / (ny - 1)));
+
+  const V = [], Tr = [];
+
+  // 1. Top grid, row-major. CCW from +Z.
+  for (let j = 0; j < ny; j++) for (let i = 0; i < nx; i++) V.push(X(i), Y(j), Z(i, j));
+  for (let j = 0; j < ny - 1; j++) for (let i = 0; i < nx - 1; i++) {
+    const a = j * nx + i, b = a + 1, c = a + nx, dd = c + 1;
+    Tr.push(a, b, dd, a, dd, c);
+  }
+
+  // 2. Perimeter, CCW viewed from +Z, as grid indices.
+  const per = [];
+  for (let i = 0; i < nx; i++) per.push(i);
+  for (let j = 1; j < ny; j++) per.push(j * nx + (nx - 1));
+  for (let i = nx - 2; i >= 0; i--) per.push((ny - 1) * nx + i);
+  for (let j = ny - 2; j >= 1; j--) per.push(j * nx);
+  const P = per.length;
+
+  // 3. Bottom ring: one new vertex per perimeter vertex, dropped to z = 0. The
+  //    top ring of the skirt reuses the ORIGINAL grid perimeter indices (not a
+  //    duplicate) — that's what makes the top-face boundary edge and the
+  //    skirt's top edge the same index pair, so the mesh is watertight by
+  //    index alone with no separate weld/merge step required.
+  const bot0 = V.length / 3;
+  for (const p of per) V.push(V[p * 3], V[p * 3 + 1], 0);
+
+  // 4. Skirt.
+  for (let k = 0; k < P; k++) {
+    const k2 = (k + 1) % P;
+    Tr.push(per[k], bot0 + k, bot0 + k2, per[k], bot0 + k2, per[k2]);
+  }
+
+  // 5. Bottom cap — flip=true so it faces −Z. Centre is the footprint centroid.
+  fanCap(V, Tr, bot0, P, [x0 + w / 2, y0 + d / 2, 0], true);
+
+  return { positions: Float32Array.from(V), indices: Uint32Array.from(Tr), warnings };
+}

package/src/framework/geometry/kernel.js

@@ -25,6 +25,8 @@ export const KERNEL_OPS = [
   "roundedCylinder", "torus", "roundedBox", "import",
   // Additive in 0.84 (no CONTRACT_VERSION bump — the import-op precedent).
   "loftSmooth",
+  // Additive in 0.92 (same precedent): both backends implement it.
+  "heightfield",
 ];
 
 // Backend-optional kernel ops: the sub-part cache brackets + WASM lifetime hooks.
@@ -150,6 +152,7 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(o:{profile:number[][],pitch:number,turns:number,lefthand?:boolean}) => Solid} screwSweep   screw-motion sweep of an axial [[r,z]] profile — threads; options-only
  * @property {(o:{sections:object[],stations?:number,samples?:number,shading?:string,closed?:boolean}) => Solid} loftSmooth   Catmull-Rom-densified loft of sparse control sections; options-only
+ * @property {(nameOrGrid: string|{width:number,height:number,data:Uint16Array}, opts: {w:number,d:number,base?:number,maxZ?:number,pitch?:number,invert?:boolean,range?:number[],origin?:"center"|"corner"}) => Solid} heightfield   depth-map relief solid; nameOrGrid is a name declared in the part's `images` field or an inline grid
  * @property {(solids:Solid[]) => Solid} union
  * @property {(profile: number[][]|{outer:number[][],holes?:number[][][]}|{start:number[],segments:object[]}|Shape2D) => Shape2D} shape2d   2-D boolean value; one shared contour-storage implementation on both backends
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hull   convex hull of all inputs → a convex Shape2D (faceted; pure-JS monotone chain)

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

@@ -19,6 +19,7 @@ import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
 import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
 import { KernelCapabilityError } from "./errors.js";
+import { heightfieldMesh, hashGridData } from "./heightfield.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
@@ -89,6 +90,10 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // registers pre-build (ensureImports, Task 8). Kernel-lifetime, NOT tracked/T()'d:
   // these masters must survive cleanup() and be read again on every subsequent build.
   const imports = new Map();
+  // name -> { digest, width, height, data } — depth-map grids the framework registers
+  // pre-build via `_registerImage` (ensureImages, Task 4). Kernel-lifetime like
+  // `imports` above: plain data, not WASM, so there is nothing to T()/dispose.
+  const images = new Map();
   // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
   // tracks the result, and returns the triple the cache needs to pin/dispose it.
   const cached = (hash, computeM) => cache.lookup(hash, () => {
@@ -614,6 +619,45 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
         // X and drives Y to 0, squishing the top to a line). Broadcast for a uniform taper.
         return T(cs.extrude(height, nDiv, twist, [scaleTop, scaleTop]));
       }),
+    // Height-map relief. The grid → triangle conversion is a pure leaf shared with
+    // the OCCT backend (heightfield.js), so both kernels build from identical
+    // triangle data. `manifoldFromMesh`'s output is NOT self-tracked (see its own
+    // header comment — "caller tracks `out`") so, unlike `import`'s master, this
+    // build wraps it in T() itself: a heightfield solid is an ordinary per-build
+    // result, not a kernel-lifetime master.
+    heightfield: (src, opts = {}) => {
+      const grid = typeof src === "string" ? images.get(src) : src;
+      if (!grid) throw new Error(`heightfield: unknown image "${src}" — declare it in the part's \`images\` field`);
+      const build = () => {
+        const { positions, indices, warnings } = heightfieldMesh(grid, opts);
+        // Only runs on a cache MISS for a registered image (every call for an
+        // inline grid, which always takes the bypass below). A repeat build of
+        // the same registered image at the same options is a cache HIT and never
+        // re-enters this closure, so a pitch-clamp warning is NOT re-emitted on
+        // a warm rebuild — intentional dedup (same call, same warning, once),
+        // not a missed re-warn.
+        for (const w of warnings) recordWarning(w);
+        return T(manifoldFromMesh(wasm, positions, indices));
+      };
+      // Only a registered image carries a content digest to key the cache on. An
+      // inline {width,height,data} grid has no identity of its own — keying it on a
+      // literal string like "inline" would let two DIFFERENT inline grids at the
+      // same options collide on the same cache key, and the second call would
+      // silently get back the FIRST call's solid. Skip the cache for those; the
+      // inline path is the test/low-level path and isn't performance-sensitive.
+      // (The returned solid still gets a real content-fingerprint hash below, so a
+      // downstream union/cut composing two different inline heightfields doesn't
+      // inherit the same collision risk one level up.)
+      if (typeof src !== "string") {
+        return wrap(build(), h("heightfield-inline", grid.width, grid.height, hashGridData(grid.data),
+          opts.w, opts.d, opts.base, opts.maxZ, opts.pitch, opts.invert, opts.range, opts.origin));
+      }
+      return cached(
+        h("heightfield", grid.digest, opts.w, opts.d, opts.base, opts.maxZ,
+          opts.pitch, opts.invert, opts.range, opts.origin),
+        build,
+      );
+    },
     // Polygon-with-holes extrude in one op: even/odd fill turns the extra contours into
     // holes regardless of their winding (outer + holes, no per-hole boolean cut).
     // A Shape2D `profile` (curve-native, possibly multi-region) materializes through
@@ -716,6 +760,23 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // Registration memo: undefined for an error entry, so a later registration with
     // the same digest can upgrade it rather than being treated as a no-op repeat.
     _importDigest: (name) => { const e = imports.get(name); return e?.error ? undefined : e?.digest; },
+    // Depth-map grids, registered pre-build by the framework via `_registerImage`
+    // (ensureImages, Task 4). Unlike imports there is no per-format error entry:
+    // every backend can consume a normalized grid, so registration never fails.
+    _registerImage: ({ name, digest, width, height, data }) => {
+      images.set(name, { digest, width, height, data });
+    },
+    _imageDigest: (name) => images.get(name)?.digest,
+    // Drop every registered name NOT in `keep` (a Set) — the images-map twin of
+    // fonts' kernel._fonts prune in jobs.js. `images` is keyed on the part's
+    // declared name (e.g. "relief"), not on content, so without this a name
+    // the user cleared — or a different part that reuses the same key across a
+    // worker-rebind — would silently keep resolving to a prior build's grid.
+    // A method rather than exposing `images` itself: jobs.js only ever needs
+    // "keep exactly this set", never raw Map access.
+    _pruneImages: (keep) => {
+      for (const name of [...images.keys()]) if (!keep.has(name)) images.delete(name);
+    },
     _acceptsMesh: true,
     shape2d,
     // Backend-internal region adapter: the shared native engine (contour-offset.js)