partforge 0.96.0 → 0.97.0

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)

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

@@ -33,8 +33,80 @@ import { createSolidCache } from "./solid-cache.js";
 import { composePose, transformPositions, rotateNormals } from "./pose.js";
 import { filterBrepEdges } from "./brep-edges.js";
 import { meshToStl } from "./mesh-stl.js";
+import { heightfieldMesh, hashGridData } from "./heightfield.js";
 const MESH = { preview: { tolerance: 0.1, angularTolerance: 0.25 }, print: { tolerance: 0.01, angularTolerance: 0.1 } };
 
+// Heightfield sew-time warning threshold, in triangles. Measured by the plan's
+// Task 1 probe against this exact sequence: 24,182 triangles sewed in 8.2-8.6s
+// (the largest size that stayed under ~10s), 29,750 took 10.4-10.6s. 24000 is a
+// round number just under the last confirmed-under-10s measurement, leaving
+// headroom for slower hardware than the probe ran on.
+const STEP_TRIANGLE_WARN = 24000;
+// STEP bytes per input triangle, from the same probe: 2.3-2.6 KB/triangle across
+// 7,670 -> 81,590 triangles (~37 STEP entities per triangle), linear in triangle
+// count. Only used to put an order-of-magnitude figure in the warning below.
+const STEP_KB_PER_TRIANGLE = 2.4;
+// Monotonic scratch-filename counter for the emscripten FS round trip in
+// stlBufferToShape. A counter, not Date.now()/Math.random(): `build` must be a
+// pure function of (k, p, d), and the name never reaches geometry or a cache key.
+// Collision-free within a process, which is all that matters — the file is
+// written and unlinked inside one synchronous call.
+let stlSeq = 0;
+
+// Binary STL ArrayBuffer -> replicad Solid, SYNCHRONOUSLY. This is replicad's own
+// `importSTL` body with the `await blob.arrayBuffer()` removed (we already hold an
+// ArrayBuffer from meshToStl) — verified against replicad 0.23.1 by the plan's
+// Task 1 probe at every grid size up to 81,590 triangles. Synchronous matters:
+// `build(k, p, d)` is a synchronous pure function, so a part author cannot await,
+// and the Manifold backend's `heightfield` is synchronous too.
+//
+// `getOC`, `localGC` and `cast` are all public replicad exports. Every
+// intermediate native object is registered with localGC's `r()` and freed by
+// `gc()` in a `finally` — unconditional, unlike the real importSTL, which frees
+// only on its two known exit paths and would leak if e.g. `Build()` threw.
+// `cast()` hands back a fresh JS handle onto the same reference-counted OCCT
+// TShape, so freeing `asSolid` does not invalidate the returned shape.
+function stlBufferToShape(replicad, arrayBuffer) {
+  const oc = replicad.getOC();
+  const [r, gc] = replicad.localGC();
+  const fileName = `hf-${stlSeq++}.stl`;
+  try {
+    oc.FS.writeFile(`/${fileName}`, new Uint8Array(arrayBuffer));
+    const reader = r(new oc.StlAPI_Reader());
+    const readShape = r(new oc.TopoDS_Shell());
+    if (!reader.Read(readShape, fileName)) throw new Error("StlAPI_Reader rejected the mesh");
+    const shapeUpgrader = r(new oc.ShapeUpgrade_UnifySameDomain_2(readShape, true, true, false));
+    shapeUpgrader.Build();
+    const upgradedShape = r(shapeUpgrader.Shape());
+    // Watertightness gate. MakeSolid will happily build a "solid" from an OPEN
+    // shell and report nothing wrong, which is the silent-corruption mode this
+    // guards. Two tempting alternatives were probed on the installed OCCT build
+    // and BOTH are inadequate — do not swap this for either:
+    //   - `BRepBuilderAPI_MakeSolid.IsDone()` returns true on a freshly
+    //     constructed maker before any Add(), and true for a holed shell. It
+    //     reports "a maker exists", not "the shell closed".
+    //   - A positive-volume check passes too: a 20,790-triangle shell with 40
+    //     triangles removed still measured positive volume, only ~3% low.
+    // `BRep_Tool.IsClosed_1` is a topological free-edge pass with no geometry —
+    // measured at 0 ms (below timer resolution) against a 6.9 s sew. It must be
+    // applied to the UPGRADED SHELL, BEFORE MakeSolid: on the resulting solid it
+    // falls through to a never-set Closed() flag and answers false even when the
+    // shape is watertight. Throwing here lands in heightfield's catch, so the
+    // author gets the triangle-count-and-`pitch` message, not a raw OCCT error.
+    if (!oc.BRep_Tool.IsClosed_1(upgradedShape)) throw new Error("the sewn shell is not watertight (it has free edges)");
+    const solidSTL = r(new oc.BRepBuilderAPI_MakeSolid_1());
+    // Shell_1 returns a distinct embind handle with its own .delete(), so it is
+    // registered like every other intermediate. Safe: Add() copies the shell into
+    // the builder before gc() runs.
+    solidSTL.Add(r(oc.TopoDS.Shell_1(upgradedShape)));
+    const asSolid = r(solidSTL.Solid());
+    return replicad.cast(asSolid);
+  } finally {
+    try { oc.FS.unlink(`/${fileName}`); } catch { /* writeFile may never have run */ }
+    gc();
+  }
+}
+
 export function createOcctKernel(replicad) {
   const { makeCylinder, makeBox, makeCircle, makeHelix, assembleWire, genericSweep,
           loft, draw, exportSTEP, importSTEP, measureVolume, makeSphere, makeLine, Plane } = replicad;
@@ -53,6 +125,11 @@ export function createOcctKernel(replicad) {
   // registers pre-build via `_registerImport` (kernel-lifetime, untracked by the
   // solid cache: imports are the framework's own memo, keyed by name+digest).
   const imports = new Map();
+  // name -> { digest, width, height, data } — depth-map grids the framework
+  // registers pre-build via `_registerImage` (ensureImages). Kernel-lifetime like
+  // `imports` above, and plain data rather than OCCT objects, so there is nothing
+  // to free.
+  const images = new Map();
 
   const cache = createSolidCache();
   // Boundary ops route through cache.lookup. pin is unused here (no cleanup() —
@@ -486,11 +563,69 @@ export function createOcctKernel(replicad) {
     });
   };
 
+  // Height-map relief. The grid -> triangle conversion is the SAME pure leaf the
+  // Manifold backend uses (heightfield.js), so both kernels build from identical
+  // triangle data; the difference is only what happens next. Here the triangles go
+  // out through meshToStl and back in through OCCT's own mesh->B-rep path
+  // (StlAPI_Reader + ShapeUpgrade_UnifySameDomain + MakeSolid — see
+  // stlBufferToShape above). The result booleans, fillets and exports to STEP like
+  // any other B-rep shape; its surface is triangulated rather than analytic, which
+  // is the accepted trade for STEP support on a depth map.
+  const 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 = (key) => {
+      const { positions, indices, warnings } = heightfieldMesh(grid, opts);
+      // Only runs on a cache MISS for a registered image (and on every call for an
+      // inline grid, which always takes the bypass below), so a pitch clamp is not
+      // re-warned on a warm rebuild — the same intentional dedup as Manifold's.
+      for (const w of warnings) recordWarning(w);
+      const tris = indices.length / 3;
+      // ONE warning carrying both facts, because sew time and STEP size are both
+      // linear in triangle count — a second threshold would buy nothing. The size
+      // figure is deliberately hedged: ShapeUpgrade_UnifySameDomain merges only
+      // genuinely coplanar faces, so a flat relief compresses far better than a
+      // high-frequency one at the same triangle count.
+      if (tris > STEP_TRIANGLE_WARN) {
+        const mb = (tris * STEP_KB_PER_TRIANGLE) / 1024;
+        recordWarning(`heightfield: ${tris} triangles on the B-rep backend — sewing is slow above ${STEP_TRIANGLE_WARN} and STEP export will be roughly ${mb.toFixed(0)} MB (a content-dependent estimate: only coplanar faces merge, so a flat relief exports far smaller than a high-frequency one). Raise \`pitch\` to reduce the triangle count.`);
+      }
+      // Written OUTSIDE the try below: an allocation failure here is a mesh-size
+      // problem, not a sewing failure, and must not be reported as one.
+      const stl = meshToStl(positions, indices);
+      let shape;
+      try {
+        shape = stlBufferToShape(replicad, stl);
+      } catch (e) {
+        throw new Error(
+          `heightfield: could not sew ${tris} triangles into a B-rep solid (${e.message}). ` +
+          "Raise `pitch` to reduce the triangle count, or build this sub-part on the Manifold backend.",
+        );
+      }
+      return wrap(shape, [], key);
+    };
+    // 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, so keying it on
+    // a literal would let two DIFFERENT inline grids at the same options collide
+    // and hand the second caller the first one's solid. Bypass the cache for those
+    // — the inline path is the test/low-level path and isn't performance-sensitive
+    // — but still give the solid a real content fingerprint in its `_hash`, since
+    // that hash feeds DOWNSTREAM boolean cache keys (cut/union). Matches the
+    // Manifold backend exactly.
+    if (typeof src !== "string") {
+      return 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));
+    }
+    const key = h("heightfield", grid.digest, opts.w, opts.d, opts.base, opts.maxZ,
+      opts.pitch, opts.invert, opts.range, opts.origin);
+    return cached(key, () => build(key));
+  };
+
   const kernel = finishKernel({
     cylinder, // boredCylinder: the kernel front's default composition is exactly right here
     box: (min, max) => cached(h("box", min, max), () => wrap(makeBox(min, max), [], h("box", min, max))),
     roundedBox,
-    prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube,
+    prism, extrude, revolve, loft: loftOp, sweep, helixSweptTube, heightfield,
     sphere: (r) => cached(h("sphere", r), () => wrap(makeSphere(r), [], h("sphere", r))),
     union: (solids) => {
       const key = h("union", solids.map((s) => s._hash));
@@ -536,6 +671,18 @@ export function createOcctKernel(replicad) {
     // 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). 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) — see the identical
+    // comment on the Manifold backend's `_pruneImages` for why this exists.
+    _pruneImages: (keep) => {
+      for (const name of [...images.keys()]) if (!keep.has(name)) images.delete(name);
+    },
     _acceptsStep: true,
     beginSubPart: (name) => cache.begin(name),
     endSubPart: () => cache.end(),

package/src/framework/geometry/op-options.js

@@ -281,6 +281,16 @@ export const KERNEL_OP_SPECS = {
   },
   // loftSmooth: range checks live in loft-smooth.js, next to the defaults they guard.
   loftSmooth: { toArgs: passThrough("loftSmooth", ["sections", "stations", "samples", "shading", "closed"], ["sections"]) },
+  // heightfield: (nameOrGrid, opts) is a two-positional call, not the options-object
+  // convention — toArgs only normalizes a bare single-arg call (kernel-front.js's
+  // wrapper invokes it as `toArgs(a[0], k._recordWarning)`, so the second
+  // parameter here is always the kernel's warning recorder, never a real `opts`
+  // — do not thread it through as one). The rest of the range/positivity checks
+  // (base, pitch) live in heightfield.js next to the defaults they guard, same
+  // split as loftSmooth above.
+  heightfield: { toArgs: (a) => [a, {}], check: (_src, o = {}) => {
+    if (!(o.w > 0) || !(o.d > 0)) throw new Error("heightfield: w and d must be positive");
+  } },
   roundedBox:      { toArgs: roundedBoxArgs },
   roundedCylinder: { toArgs: roundedCylinderArgs },
   torus:           { toArgs: torusArgs },

package/src/framework/geometry/png-decode.js

@@ -0,0 +1,107 @@
+// Pure-JS PNG → luminance grid. Lives in the worker graph, so it must be DOM-free
+// and node:-free: no createImageBitmap/OffscreenCanvas (browser-only), no pngjs
+// (Node-only). One decoder in one place is what keeps the browser, the CLI and CI
+// from disagreeing about geometry. Inflate comes from fflate, already in this
+// closure via threemf-parse.js.
+import { unzlibSync } from "fflate";
+
+const SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const U16 = 65535;
+
+// Rec. 709 luma, the same weighting a viewer would show.
+const luma = (r, g, b) => 0.2126 * r + 0.7152 * g + 0.0722 * b;
+
+function paeth(a, b, c) {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+export function decodePng(input) {
+  const u8 = input instanceof Uint8Array ? input : new Uint8Array(input);
+  for (let i = 0; i < 8; i++) if (u8[i] !== SIG[i]) throw new Error("decodePng: not a PNG (bad signature)");
+
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+  let off = 8, width = 0, height = 0, depth = 8, colorType = 6, interlace = 0;
+  let palette = null;
+  const idat = [];
+
+  while (off + 8 <= u8.length) {
+    const len = dv.getUint32(off);
+    const type = String.fromCharCode(u8[off + 4], u8[off + 5], u8[off + 6], u8[off + 7]);
+    const body = off + 8;
+    if (body + len > u8.length) throw new Error(`decodePng: truncated file (chunk ${type} runs past the end)`);
+    if (type === "IHDR") {
+      width = dv.getUint32(body); height = dv.getUint32(body + 4);
+      depth = u8[body + 8]; colorType = u8[body + 9]; interlace = u8[body + 12];
+    } else if (type === "PLTE") palette = u8.subarray(body, body + len);
+    // tRNS (alpha) is intentionally not parsed: ignoring alpha is correct for a
+    // depth map, and this chunk still falls through to the unconditional
+    // `off` advance below like any other chunk type we don't care about.
+    else if (type === "IDAT") idat.push(u8.subarray(body, body + len));
+    else if (type === "IEND") break;
+    off = body + len + 4; // + CRC
+  }
+
+  if (!width || !height) throw new Error("decodePng: truncated file (no IHDR)");
+  if (interlace) throw new Error("decodePng: interlaced (Adam7) PNGs are not supported — re-save without interlacing");
+
+  const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colorType];
+  if (!CHANNELS) throw new Error(`decodePng: unsupported colour type ${colorType}`);
+  if (colorType === 3 && !palette) throw new Error("decodePng: palette image with no PLTE chunk");
+
+  // Concatenate IDAT then inflate.
+  let total = 0; for (const c of idat) total += c.length;
+  if (!total) throw new Error("decodePng: truncated file (no IDAT)");
+  const z = new Uint8Array(total);
+  { let p = 0; for (const c of idat) { z.set(c, p); p += c.length; } }
+  const raw = unzlibSync(z);
+
+  const bpp = Math.max(1, (CHANNELS * depth) >> 3);
+  const rowBytes = Math.ceil((CHANNELS * depth * width) / 8);
+  if (raw.length < (rowBytes + 1) * height) throw new Error("decodePng: truncated file (short image data)");
+
+  // Un-filter in place, row by row.
+  const img = new Uint8Array(rowBytes * height);
+  for (let y = 0; y < height; y++) {
+    const ft = raw[y * (rowBytes + 1)];
+    const src = y * (rowBytes + 1) + 1;
+    const dst = y * rowBytes, up = dst - rowBytes;
+    for (let x = 0; x < rowBytes; x++) {
+      const v = raw[src + x];
+      const a = x >= bpp ? img[dst + x - bpp] : 0;
+      const b = y > 0 ? img[up + x] : 0;
+      const c = x >= bpp && y > 0 ? img[up + x - bpp] : 0;
+      img[dst + x] = (ft === 0 ? v : ft === 1 ? v + a : ft === 2 ? v + b
+                   : ft === 3 ? v + ((a + b) >> 1) : v + paeth(a, b, c)) & 0xff;
+    }
+  }
+
+  // Read samples → luminance, scaled to 0..65535.
+  const out = new Uint16Array(width * height);
+  const maxIn = depth === 16 ? 65535 : (1 << depth) - 1;
+  const readSample = (row, i) => {
+    if (depth === 16) return (img[row + i * 2] << 8) | img[row + i * 2 + 1];
+    if (depth === 8) return img[row + i];
+    const per = 8 / depth, byte = img[row + ((i / per) | 0)];
+    const shift = 8 - depth * ((i % per) + 1);
+    return (byte >> shift) & maxIn;
+  };
+
+  for (let y = 0; y < height; y++) {
+    const row = y * rowBytes;
+    for (let x = 0; x < width; x++) {
+      let v;
+      if (colorType === 3) {
+        const idx = readSample(row, x) * 3;
+        v = luma(palette[idx], palette[idx + 1], palette[idx + 2]) / 255;
+      } else if (colorType === 0 || colorType === 4) {
+        v = readSample(row, x * CHANNELS) / maxIn;
+      } else {
+        const b0 = x * CHANNELS;
+        v = luma(readSample(row, b0), readSample(row, b0 + 1), readSample(row, b0 + 2)) / maxIn;
+      }
+      out[y * width + x] = Math.round(Math.min(Math.max(v, 0), 1) * U16);
+    }
+  }
+  return { width, height, data: out };
+}

package/src/framework/geometry/solid-hash.js

@@ -19,3 +19,99 @@ function fnv(s) {
   for (let i = 0; i < s.length; i++) { hsh ^= s.charCodeAt(i); hsh = Math.imul(hsh, 0x01000193); }
   return (hsh >>> 0).toString(36);
 }
+
+// ── byte-aware JSON.stringify support ───────────────────────────────────────
+// A shared home for param-deps.js's relevanceHash, backend-select.js's
+// reroute-latch snapshot, and oracle/verify.js's memo signature — none of
+// which should import one another's concerns. All three wholesale-hash a
+// params object with JSON.stringify, and a byte-valued param — an
+// ArrayBuffer, a SharedArrayBuffer, or a typed-array/DataView view
+// (Buffer included — the shape a param-supplied image takes on the
+// partforge-cloud sandbox path, which cannot fetch URLs and puts PNG bytes
+// straight into a param, and the shape `fs.readFileSync` hands the CLI) —
+// breaks JSON.stringify's default handling two different ways: an
+// ArrayBuffer/SharedArrayBuffer has no enumerable own properties, so it
+// always serializes as the same "{}" regardless of content (two different
+// images collide on one cache/route key); a typed-array VIEW goes the other
+// way, expanding to one JSON number per byte (tens of thousands of
+// characters for a small PNG, on every hash). `byteAwareReplacer` is a
+// JSON.stringify replacer — pass it as the second argument — that
+// substitutes a stable content fingerprint for any of these shapes instead.
+//
+// MUST be a plain function, not an arrow: JSON.stringify calls the replacer
+// with `this` bound to the holder (the object/array currently being
+// serialized), and `this[key]` is how a replacer recovers the RAW value —
+// before `Buffer.prototype.toJSON()` (or any other .toJSON) has already run
+// on it. `value`, the second argument, has ALREADY been through that
+// conversion: for a Node Buffer, `value` here is
+// `{type:"Buffer",data:[...]}`, JSON.stringify's default expansion, one
+// number per byte — exactly the pathology this function exists to avoid,
+// reached through a different door. `this[key]` bypasses toJSON entirely, an
+// ordinary property read of the holder returns whatever object is actually
+// stored there.
+export function byteAwareReplacer(key, value) {
+  const raw = this ? this[key] : value;
+  return isByteish(raw) ? fingerprintBytes(raw) : value;
+}
+
+// Object.prototype.toString.call(...), not `instanceof`/typed-array
+// constructor checks: `instanceof ArrayBuffer` is false for an ArrayBuffer
+// from another realm (a different vm context/iframe/worker — Node's `vm`
+// module and Electron both make this reachable), and it silently falls back
+// to the original bug ("{}") rather than throwing. The [[Class]] internal
+// slot Object.prototype.toString reads is realm-independent.
+// `ArrayBuffer.isView` itself IS already realm-independent (it checks for a
+// [[ViewedArrayBuffer]] internal slot, not a prototype chain), so it is kept
+// as-is for the view case — including a Buffer, which is a Uint8Array
+// subclass and so already passes it.
+function isByteish(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (ArrayBuffer.isView(v)) return true;
+  const tag = Object.prototype.toString.call(v);
+  return tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]";
+}
+
+// Memoized per buffer/view IDENTITY (not content) in a WeakMap, mirroring
+// kernel-front.js's byteCache: the params object these callers hash is
+// mutated in place and re-hashed on every regen (mesh-cache.js's hashFor, a
+// backend-select reroute check), so re-walking megabytes of image bytes on
+// every slider tick that touches some OTHER param would be its own
+// regression. A given buffer is fingerprinted once and the string reused for
+// as long as that identity survives.
+const byteFingerprints = new WeakMap(); // ArrayBuffer|SharedArrayBuffer|ArrayBufferView -> fingerprint string
+
+// Two independent FNV-1a streams over the same bytes (different offset
+// bases, same prime), concatenated — a cheap ~64-bit fold. A single 32-bit
+// fold (what h() uses, and what this used through fix round 1) collides at
+// ~2⁻³² for two same-length buffers, which is fine for h(): that graph is
+// rebuilt fresh every build, nothing accumulates. This fingerprint is
+// different — it is retained in the mesh cache for a whole session — so a
+// collision here means silently stale geometry, the exact failure class
+// fix round 1 existed to eliminate. Widening makes it negligible instead of
+// merely unlikely.
+function fnvBytes64(u8) {
+  let h1 = 0x811c9dc5;      // FNV-1a's standard 32-bit offset basis
+  let h2 = 0x9e3779b9;      // a distinct, unrelated 32-bit constant (golden-ratio mix constant)
+  for (let i = 0; i < u8.length; i++) {
+    const b = u8[i];
+    h1 ^= b; h1 = Math.imul(h1, 0x01000193);
+    h2 ^= b; h2 = Math.imul(h2, 0x01000193);
+  }
+  return (h1 >>> 0).toString(36) + (h2 >>> 0).toString(36);
+}
+
+function fingerprintBytes(value) {
+  let cached = byteFingerprints.get(value);
+  if (cached !== undefined) return cached;
+  const u8 = ArrayBuffer.isView(value)
+    ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+    : new Uint8Array(value); // ArrayBuffer or SharedArrayBuffer
+  // "bytes:" prefix plus the raw byte length folded in alongside the ~64-bit
+  // digest. No ordinary control value is a string shaped exactly like this
+  // (the panel's own control types are numbers/booleans/strings/enums), so
+  // this fingerprint only ever competes with OTHER buffers' fingerprints,
+  // not a genuine string param's value.
+  cached = `bytes:${fnvBytes64(u8)}:${u8.length}`;
+  byteFingerprints.set(value, cached);
+  return cached;
+}

package/src/framework/image-ingest.js

@@ -0,0 +1,41 @@
+// MAIN-THREAD ONLY. Converts any image the browser can decode into a PNG a part's
+// `images` field can consume, downsampling on the way.
+//
+// This file uses createImageBitmap and a canvas, so it must NEVER be reachable
+// from the geometry worker's import closure — test/worker-layering.test.js
+// enforces that. It is exported from src/index.js, the DOM entry documented as
+// one a part's `build` must never import.
+//
+// Why PNG and not the source format: core decodes PNG only, in pure JS, so one
+// decoder produces the geometry in the browser, the CLI and CI alike. Converting
+// once at ingest keeps that single decoder authoritative — the browser's codec
+// output is baked into an immutable PNG rather than racing ours at build time.
+//
+// Why downsample instead of switching to JPEG: pitch caps useful resolution
+// anyway (a 60mm plate at 0.3mm pitch samples 200x200), and JPEG is 8-bit and
+// DCT-ringing — in a depth map those are geometric artifacts, height terracing
+// and 8x8 block bumps, not cosmetic ones.
+
+export async function imageToPng(fileOrBlob, { maxSize = 1024 } = {}) {
+  const bmp = await createImageBitmap(fileOrBlob);
+  try {
+    const scale = Math.min(1, maxSize / Math.max(bmp.width, bmp.height));
+    const w = Math.max(1, Math.round(bmp.width * scale));
+    const h = Math.max(1, Math.round(bmp.height * scale));
+
+    if (typeof OffscreenCanvas === "function") {
+      const c = new OffscreenCanvas(w, h);
+      c.getContext("2d").drawImage(bmp, 0, 0, w, h);
+      return await c.convertToBlob({ type: "image/png" });
+    }
+    // Safari and older engines: fall back to a detached <canvas>.
+    const c = document.createElement("canvas");
+    c.width = w;
+    c.height = h;
+    c.getContext("2d").drawImage(bmp, 0, 0, w, h);
+    return await new Promise((res, rej) =>
+      c.toBlob((b) => (b ? res(b) : rej(new Error("imageToPng: canvas encoding failed"))), "image/png"));
+  } finally {
+    bmp.close?.();
+  }
+}

package/src/framework/image-source.js

@@ -0,0 +1,72 @@
+// What a PARAM-supplied image source may be. Author-declared `images` sources are
+// code and get no restriction; this file exists only for the other case — a
+// value that arrived in `params`.
+//
+// This deliberately diverges from font-source.js in one place. That file refuses
+// every non-string on the grounds that "bytes/thunks are never param-supplied".
+// For images they ARE: the partforge-cloud sandbox cannot fetch URLs and puts PNG
+// bytes straight in the param. The replacement rule is sound — an ArrayBuffer in
+// params definitionally did not arrive via a shared link, because a URL cannot
+// carry megabytes, so it can only have been placed there by the host's own panel,
+// which is trusted code. Bytes therefore bypass the allow check entirely, for
+// every allow list. Do NOT copy font-source.js's non-string refusal here.
+//
+// DOM-free and node:-free: jobs.js (worker graph) and the panel both import it.
+
+export const IMAGE_ALLOW_DEFAULT = ["https"];
+
+const ASSET_SCHEME = "pfc-asset:";
+
+// The "unset" image source. An empty value declares NO image — the documented
+// way to leave a relief off; the op itself has no fallback, so a build() that
+// still calls k.heightfield for an unset name gets the ordinary unknown-image
+// throw. Never a source to fetch, and never a source to refuse.
+export const isNoImageSource = (v) => v === undefined || v === null || v === "";
+
+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 imageSourceAllowed(source, allow = IMAGE_ALLOW_DEFAULT) {
+  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) {
+    // hostname/protocol, never a substring of the raw string: a URL merely
+    // CONTAINING "pfc-asset://" (e.g. in its path) must not pass, and neither
+    // must a lookalike host like `pfc-asset.evil.test` — see font-source.js's
+    // header comment, which explains the two bugs this rule has already
+    // caused when a check compared the raw string instead of the parsed URL.
+    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: "image"` control in the authored tree,
+// new-shape (`controls`, including nested groups) and legacy-shape
+// (`advanced`/`toggles`/`features`, where panel/legacy.js desugars `control:` to
+// `type:`). Missing the legacy arrays would leave such a control silently
+// unrestricted. Tolerant of any array being absent or malformed — it must never
+// throw on an existing part.
+export function imageControlAllows(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 === "image" || n.control === "image") && typeof n.key === "string") {
+        out.set(n.key, Array.isArray(n.allow) && n.allow.length ? n.allow : IMAGE_ALLOW_DEFAULT);
+      }
+    }
+  };
+  visit(part?.parameters);
+  return out;
+}