partforge 0.96.0 → 0.97.0

package/bin/cli.js

@@ -10,6 +10,8 @@ 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";
@@ -100,9 +102,20 @@ const readSources = (partPath) => {
 // 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.
+//
+// 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 = (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 opts = { fonts: fontsFor(part, p), imports: part.imports, images, vectors: part.vectors };
   const backend = process.env.PARTFORGE_BACKEND || detectBackend(part); // env: crash()'s NEEDS_OCCT retry
   return backend === "occt" ? bootOcctKernel(opts) : bootManifoldKernel(opts);
 };

package/docs/AUTHORING-PARTS.md

@@ -712,6 +712,7 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"select"` | a dropdown | `options` |
 | `"radio"` | a segmented button row | `options` |
 | `"font"` | a typeface picker, or a URL field with no catalog | `allow`, `preview` |
+| `"image"` | an image picker, or a URL field with no catalog | `allow` |
 
 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.
@@ -1735,6 +1736,181 @@ 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"` (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 —
+this is how a host that cannot fetch URLs (the partforge-cloud sandbox is the
+motivating case) gets an uploaded image into a part: its own trusted panel
+puts the bytes straight into `params`. Byte values **bypass the `allow` check
+entirely**, for every `allow` list, including the default — not a hole, but
+the deliberate consequence of what a byte value in `params` can mean: a URL
+cannot carry megabytes, so an `ArrayBuffer` arriving there cannot have come
+from a pasted link or a shared URL; it can only have been placed there by the
+host's own code. `allow` exists to keep a shared link from turning into an
+arbitrary fetch — a concern that doesn't apply to a value the host already
+has in hand.
+
+**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.
+
 ## Host jobs: extending the worker
 
 The worker's job loop handles a closed set of message types (`generate`, the exports,
@@ -1950,6 +2126,11 @@ 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.
+
 **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 +2658,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

package/docs/ERROR-PATTERNS.md

@@ -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" before storing, or have the host normalize on upload` thrown while resolving a part's `images`.
+- **Cause:** The image resolver checks the first four bytes against the PNG magic number before decoding; a JPEG, WEBP, or any other format fails that check immediately; a heightfield source is a depth map and needs a single well-defined decode path, so no other format is attempted.
+- **Fix:** Convert the source to PNG before it reaches `images` — call `imageToPng()` (exported from `"partforge"`, browser-only: it draws through a `<canvas>`) in the host's upload/panel handler, or pre-convert with any image tool. Bytes that are already PNG (the 4-byte signature `89 50 4E 47`) skip this check entirely.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.96.0",
+  "version": "0.97.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",

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/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)