partforge 0.96.0 → 0.97.0

package/src/framework/images.js

@@ -0,0 +1,66 @@
+// Resolve a part's declared `images` ({ name: source }) to a decoded luminance
+// grid + a SHA-256 content digest, before the synchronous build — the third
+// asset sibling beside fonts.js and imports.js, on the shared resolution core in
+// asset-resolve.js. DOM-free and node:-free; crypto.subtle exists in workers and
+// Node.
+//
+// Registration is simpler than imports': every backend can consume a normalized
+// grid, so there are no per-format error entries and no crossover.
+import { makeAssetResolver, resolveDecl } from "./asset-resolve.js";
+import { decodePng } from "./geometry/png-decode.js";
+
+const PNG_SIG = [0x89, 0x50, 0x4e, 0x47];
+
+async function sha256Hex(bytes) {
+  const d = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const cache = new Map(); // source → Promise<{digest, width, height, data}>
+const resolveOne = makeAssetResolver(
+  cache,
+  async (bytes) => {
+    const u8 = new Uint8Array(bytes);
+    for (let i = 0; i < 4; i++) {
+      if (u8[i] !== PNG_SIG[i]) {
+        throw new Error(
+          "images: only PNG is supported — convert with imageToPng() from \"partforge\" before storing, " +
+          "or have the host normalize on upload",
+        );
+      }
+    }
+    const { width, height, data } = decodePng(u8);
+    return { digest: await sha256Hex(bytes), width, height, data };
+  },
+  "resolveImages: an image source must be bytes, a URL, or a thunk returning one",
+);
+
+// `images` may be a plain { name: source } map or a function of the resolved
+// params — the second form is what lets a `type: "image"` control drive the
+// source. Mirrors fontsFor.
+export function imagesFor(part, p) {
+  const decl = part?.images;
+  return typeof decl === "function" ? decl(p) : decl;
+}
+
+export async function resolveImages(imagesDecl) {
+  // A function reaching here means a caller passed `part.images` raw. It
+  // cannot be resolved without params — resolve it with imagesFor(part, p)
+  // first (mirrors resolveFonts's guard in fonts.js).
+  if (typeof imagesDecl === "function") {
+    throw new Error("resolveImages: `images` is a function of params — resolve it with imagesFor(part, p) first");
+  }
+  return resolveDecl(imagesDecl, resolveOne);
+}
+
+// Register a part's images on a booted kernel (idempotent per digest). Called in
+// the async phase before every job's synchronous build — worker (jobs.js) and
+// Node boots alike.
+export async function ensureImages(kernel, imagesDecl) {
+  if (!imagesDecl || typeof kernel?._registerImage !== "function") return;
+  const resolved = await resolveImages(imagesDecl);
+  for (const [name, a] of resolved) {
+    if (kernel._imageDigest?.(name) === a.digest) continue;
+    await kernel._registerImage({ name, digest: a.digest, width: a.width, height: a.height, data: a.data });
+  }
+}

package/src/framework/jobs.js

@@ -7,6 +7,8 @@ import { exportablePartNames } from "./export-select.js";
 import { fontControlAllows, fontSourceAllowed, isNoFontSource } from "./font-source.js";
 import { fontsFor, resolveFonts } from "./fonts.js";
 import { normalizeOpentype, parseFont } from "./geometry/opentype-interop.js";
+import { imageControlAllows, imageSourceAllowed, isNoImageSource } from "./image-source.js";
+import { imagesFor, ensureImages } from "./images.js";
 import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { ensureVectors } from "./vectors.js";
@@ -158,6 +160,25 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         jobWarnings.push({ part: null, message });   // …and the durable record
         params[key] = part.defaults?.[key];
       }
+      // Same shape for `type: "image"` controls — a param bound to one is user
+      // input, and on a shared link a STRING value is arbitrary attacker text
+      // that `images: (p) => …` would turn into a fetch URL. A BYTE value
+      // (ArrayBuffer/typed array) always passes imageSourceAllowed regardless of
+      // `allow` — see image-source.js's header: it cannot have arrived via a
+      // share link (a URL can't carry megabytes), only from the host's own
+      // trusted panel (the partforge-cloud sandbox path). Runs in this same
+      // sanitize hook, not after resolveParams returns, for the reason the
+      // comment above states: rewriting p[key] afterwards would leave derive()
+      // — and therefore `d` and the geometry — holding the refused value while
+      // build() saw the default.
+      for (const [key, allow] of imageControlAllows(part)) {
+        const v = params[key];
+        if (isNoImageSource(v) || imageSourceAllowed(v, allow)) continue;
+        const message = `image source for "${key}" is not allowed — using the default`;
+        onProgress(message);
+        jobWarnings.push({ part: null, message });
+        params[key] = part.defaults?.[key];
+      }
     });
     // Preload any part-declared fonts into the kernel before building. A lazy
     // dynamic import because this is async context (unlike the synchronous
@@ -227,6 +248,40 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // lazy-error policy that keeps a STEP import inert until a build actually
     // calls k.import on it.
     if (part.imports) await ensureImports(kernel, part.imports, opts.importMeshes ?? null);
+    // Register this part's declared images on the kernel running this job — the
+    // third asset sibling beside fonts and imports. The allow-check already ran
+    // as resolveParams' sanitize hook above, so `p` here already reflects any
+    // refusal (reset to the part's default) — this step only resolves and
+    // uploads the resulting bytes.
+    //
+    // Gated on the part DECLARING `images` at all, not on this job having a
+    // source to resolve — the prune below has to run on the empty declaration
+    // too (a cleared pick), and a part with no `images` field must not touch
+    // the kernel's image map (a host or test harness may have seeded it
+    // directly via _registerImage).
+    if (part.images && typeof kernel._registerImage === "function") {
+      const imagesDecl = imagesFor(part, p) ?? {};
+      const declared = Object.fromEntries(
+        Object.entries(imagesDecl).filter(([name, src]) => {
+          if (!isNoImageSource(src)) return true;
+          onProgress(`no image source declared for "${name}" — skipping`);
+          return false;
+        }),
+      );
+      if (Object.keys(declared).length) {
+        onProgress("resolving images");
+        await ensureImages(kernel, declared);
+      }
+      // Drop every registered name this build's declaration does not supply.
+      // `_pruneImages` is the images twin of the `kernel._fonts` prune above:
+      // `heightfield(name)` looks a name up by the part's declared key, not by
+      // content, so a relief the user picked and then CLEARED would otherwise
+      // stay registered under its old name and go on rendering instead of
+      // whatever a missing source actually does — the unknown-image throw, or
+      // a branch a part's own build() takes around the call — the
+      // stale-registration bug of spec §5, one asset over.
+      kernel._pruneImages?.(new Set(Object.keys(declared)));
+    }
     // Vector art, the third asset family after fonts and imports. Same pre-build
     // timing; ensureVectors owns the prune, so this stays one line. Call it
     // unconditionally, even when this part has no `vectors` at all: ensureVectors

package/src/framework/lint/index.js

@@ -17,10 +17,11 @@ import { ANIMATION_RULES } from "./rules-animations.js";
 import { PLACE_RULES } from "./rules-place.js";
 import { IMPORT_RULES } from "./rules-imports.js";
 import { FONT_RULES } from "./rules-fonts.js";
+import { IMAGE_RULES } from "./rules-images.js";
 import { SOURCE_RULES } from "./rules-source.js";
 import { VECTOR_RULES } from "./rules-vector.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...SOURCE_RULES, ...VECTOR_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...IMAGE_RULES, ...SOURCE_RULES, ...VECTOR_RULES];
 
 // A usable sources input, or null. Deliberately forgiving: lintPart's callers
 // include hosted paths handing over user/LLM-authored trees, so a malformed

package/src/framework/lint/rules-images.js

@@ -0,0 +1,109 @@
+// Group 10 — image-control well-formedness + heightfield name resolution. The
+// sibling of rules-fonts.js for the `type: "image"` control / `images` field /
+// `k.heightfield()` triangle: same silent-failure shapes, same source-scheme
+// concern, plus one this group owns alone — a `k.heightfield(name, opts)` call
+// naming an image the part never declared.
+//
+// image-control-not-in-images and heightfield-unknown-image are deliberately
+// COMPLEMENTARY, not overlapping: each fires in exactly the case the other
+// skips. A function-form `images` can depend on a param — good, but its return
+// value can't be read without calling it, so image-control-not-in-images
+// actually calls it (with a sentinel substituted for the control's key) rather
+// than settling for font-control-not-in-fonts's cheaper "is it a function at
+// all?" question; a static `images` object provably CANNOT depend on a
+// param — that mistake belongs to image-control-not-in-images too, and would
+// fire on every correctly-authored fixed-image part if this rule also ran
+// there, so it is skipped entirely for a static `images`. Conversely, only a
+// static `images` object has statically-knowable keys, so heightfield-unknown-
+// image runs only there and skips whenever `images` is a function.
+import { err, warn } from "./finding.js";
+import { imageControlAllows, imageSourceAllowed, isNoImageSource } from "../image-source.js";
+
+// A URL-shaped sentinel (has a "://"), not an arbitrary string — some `images`
+// functions run `new URL(v)` or similar on the value before deciding whether to
+// use it, and an arbitrary string would make that throw and short-circuit the
+// probe for reasons that have nothing to do with whether the key is read.
+const SENTINEL = "pf-lint-sentinel://image-control-not-in-images";
+
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+export const IMAGE_RULES = [
+  {
+    id: "image-control-not-in-images",
+    run: ({ part, p }) => {
+      // Static-object `images` always fails this check by construction — it
+      // cannot read a param at all — so it is a different mistake
+      // (image-source-scheme's business, or none) and not this rule's.
+      if (typeof part?.images !== "function") return [];
+      const controls = imageControlAllows(part);
+      if (controls.size === 0) return [];
+      const out = [];
+      for (const key of controls.keys()) {
+        let resolved;
+        try { resolved = part.images({ ...p, [key]: SENTINEL }); }
+        catch { continue; } // can't be probed safely — not evidence either way
+        const reached = isPlainObject(resolved) && Object.values(resolved).includes(SENTINEL);
+        if (reached) continue;
+        out.push(err("image-control-not-in-images",
+          `control "${key}" is an image picker, but this part's \`images\` function never returns the picked value — the picked value is never resolved.`,
+          `Reference p.${key} from images, e.g. images: (p) => ({ ${key}: p.${key} }), and consume it with k.heightfield("${key}", opts).`,
+          "images"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "heightfield-unknown-image",
+    run: ({ part, probe }) => {
+      // Only a static `images` object has statically-knowable names; a
+      // function's return value depends on params lint doesn't exhaustively
+      // enumerate, so it's skipped here (see file header).
+      if (typeof part?.images === "function") return [];
+      const known = new Set(isPlainObject(part?.images) ? Object.keys(part.images) : []);
+      const seen = new Set();
+      const out = [];
+      for (const call of probe().calls) {
+        if (call.scope !== "kernel" || call.op !== "heightfield") continue;
+        // k.heightfield(nameOrGrid, opts) also accepts an INLINE grid object as
+        // its first argument — args are recorded via JSON.stringify (probe.js's
+        // `describe`), so a grid parses back to an object, not a string. Only a
+        // string-literal first argument names a declared image; anything else
+        // (an inline grid, a computed/non-literal value the probe can't read)
+        // is silently skipped rather than flagged — flagging a supported inline
+        // grid as an "unknown image" would be a false positive.
+        let name;
+        try { name = JSON.parse(call.args[0]); } catch { name = null; }
+        if (typeof name !== "string" || known.has(name) || seen.has(name)) continue;
+        seen.add(name);
+        out.push(err("heightfield-unknown-image",
+          `build calls k.heightfield with name "${name}", which the part's images field does not declare: ${[...known].join(", ") || "(nothing)"}`,
+          "Declare the source under images: { name: source }, or fix the name to match an existing entry.",
+          "images"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "image-source-scheme",
+    run: ({ part }) => {
+      const out = [];
+      for (const [key, allow] of imageControlAllows(part)) {
+        const v = part?.defaults?.[key];
+        // An empty source declares no image (jobs.js's sanitize hook drops it
+        // before it reaches ensureImages, and a build() that still calls
+        // k.heightfield for it gets the ordinary unknown-image throw — there
+        // is no automatic "no relief" fallback) — a legitimate way to author
+        // an optional relief, not a source the allow list is refusing. A
+        // bytes source (ArrayBuffer/typed array) always
+        // passes imageSourceAllowed regardless of allow — see image-source.js's
+        // header — so it never reaches this branch either.
+        if (isNoImageSource(v) || imageSourceAllowed(v, allow)) continue;
+        out.push(warn("image-source-scheme",
+          `defaults.${key} is "${String(v).slice(0, 120)}", which control "${key}" would refuse (allow: ${allow.join(", ")}).`,
+          `Use a source the allow list accepts, or widen \`allow\` on the control. At build time this value is replaced by defaults.${key}, so as written the part has no usable image.`,
+          "defaults"));
+      }
+      return out;
+    },
+  },
+];

package/src/framework/measure/measure-mode.js

@@ -13,6 +13,7 @@ import { raycastViewer } from "../selection/raycast.js";
 import { createFeatureHighlight } from "../selection/feature-highlight.js";
 import { createDragTracker } from "../selection/drag-tracker.js";
 import { subPartReadKeys, RELEVANT_ALL } from "../param-deps.js";
+import { byteAwareReplacer } from "../geometry/solid-hash.js";
 import { classifyFeature, bboxSpec, unionBounds } from "./feature-dims.js";
 import { paramMatches } from "./param-link.js";
 import { createPinStore, occurrenceOf } from "./pins.js";
@@ -136,7 +137,7 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
   // direct test) falls back to the content hash.
   let readsKey = null, readsMap = null;
   function readsFor(view, params) {
-    const key = `${view}|${getParamsVersion ? getParamsVersion() : JSON.stringify(params)}`;
+    const key = `${view}|${getParamsVersion ? getParamsVersion() : JSON.stringify(params, byteAwareReplacer)}`;
     if (readsKey !== key) {
       readsKey = key;
       try { readsMap = subPartReadKeys(part, view, params); } catch { readsMap = null; }

package/src/framework/mount.js

@@ -304,6 +304,7 @@ function createCleanupStack() {
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
 export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
                               fontCatalog,
+                              imageCatalog,
                               viewerState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
@@ -963,7 +964,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog });
+      { fontCatalog, imageCatalog });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {

package/src/framework/oracle/verify.js

@@ -4,6 +4,7 @@ import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile } from "./dfm-profiles.js";
 import { expandExpectations, partGatesMinWall } from "./gates.js";
 import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../param-deps.js";
+import { byteAwareReplacer } from "../geometry/solid-hash.js";
 import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
 
 // Re-exported for backwards compatibility: the registries moved to framework/ so
@@ -208,9 +209,13 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   const expanded = expandExpectations(part);
   const needMinWall = partGatesMinWall(part, { process, expanded });
   const readKeys = subPartReadKeys(part, view, part.defaults);
+  // byteAwareReplacer on the RELEVANT_ALL branch too: an unattributable derive()
+  // still might read a byte-valued image param, and this memo key gates whether
+  // a case's geometry gets rebuilt or an earlier result reused (see the seeding
+  // block below) — the same collision the relevanceHash branch guards against.
   const signature = (params) =>
     readKeys === RELEVANT_ALL
-      ? JSON.stringify(params)
+      ? JSON.stringify(params, byteAwareReplacer)
       : [...readKeys.entries()].map(([name, keys]) => `${name}:${relevanceHash([...keys], params)}`).join("|");
 
   const memo = new Map();

package/src/framework/panel/image-picker.js

@@ -0,0 +1,152 @@
+// The `type: "image"` picker: a takeover panel over the rail — a search box
+// above a thumbnail grid — reusing the `.picker`/`.pk-head`/`.pk-search`
+// scaffolding font-picker.js built, since a search-then-pick takeover is the
+// same shape for either asset kind. No variants pane: an image source has no
+// weight/style axis to drill into, so choosing IS committing.
+//
+// Main-thread only — it is DOM-heavy and is NOT part of the worker graph. It
+// draws thumbnails through plain `<img src>`, so the browser's own decoder does
+// the work; nothing here imports `png-decode.js`.
+import { setImagePicker } from "./widgets/image.js";
+import { imageSourceAllowed } from "../image-source.js";
+
+const SEARCH_LIMIT = 60;
+const SEARCH_DEBOUNCE_MS = 120;
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// At most one picker is open at a time, and the previous one has to be CLOSED
+// rather than merely detached: its `keydown` listener lives on `document`, so
+// dropping the element off the DOM leaves the handler — and the whole closure —
+// alive forever, one more on every re-open. Only close() unregisters it.
+let openPicker = null;
+
+export function openImagePicker({ node, params, allow, imageCatalog, anchor, onPicked }) {
+  // Takeover: the picker covers the rail on desktop and the single visible pane
+  // below the narrow breakpoint, same as the font picker.
+  const host = anchor?.closest?.(".pf-rail") ?? anchor?.parentElement ?? document.body;
+  openPicker?.close();                                  // never two at once
+
+  let results = [];
+  let query = "";
+  let closed = false;
+  let searchSeq = 0;
+  let debounce = null;
+  let failed = false;
+
+  // ── DOM ─────────────────────────────────────────────────────────────────
+  const picker = el("div", "picker");
+  const head = el("div", "pk-head");
+  const titlebar = el("div", "pk-titlebar");
+  const closeBtn = el("button", "pk-x", "×");
+  closeBtn.type = "button";
+  closeBtn.title = "Close";
+  titlebar.append(el("b", "", node.label ?? node.key), closeBtn);
+  const search = document.createElement("input");
+  search.className = "pk-search";
+  search.type = "text";
+  search.placeholder = "Search images";
+  search.autocomplete = "off";
+  search.spellcheck = false;
+  head.append(titlebar, search);
+  const grid = el("div", "pk-img-grid");
+  const empty = el("p", "pk-empty");
+  empty.hidden = true;
+  picker.append(head, grid, empty);
+  host.append(picker);
+  search.focus?.();
+
+  // ── the grid ────────────────────────────────────────────────────────────
+  // Not virtualized like the font list: a search result page is bounded by
+  // SEARCH_LIMIT, so the DOM cost of every row existing at once stays small —
+  // no scroll-position bookkeeping to get wrong for what is, at most, one
+  // catalog page of thumbnails.
+  function render() {
+    if (closed) return;
+    grid.textContent = "";
+    // A catalog is host-supplied, not trusted — drop any asset the allowlist
+    // refuses, same rule the font picker applies to a family's variants.
+    const admissible = results.filter((a) => a && typeof a.url === "string" && imageSourceAllowed(a.url, allow));
+    for (const asset of admissible) {
+      const card = el("button", "pk-img-card");
+      card.type = "button";
+      card.dataset.sel = String(asset.url === params[node.key]);
+      const thumb = document.createElement("img");
+      thumb.className = "pk-img-thumb";
+      thumb.alt = "";
+      thumb.src = asset.thumbUrl || asset.url;
+      thumb.addEventListener("error", () => { thumb.hidden = true; });
+      const cap = el("span", "pk-img-cap", asset.label ?? "");
+      card.append(thumb, cap);
+      card.addEventListener("click", () => choose(asset));
+      grid.append(card);
+    }
+    empty.hidden = admissible.length > 0;
+    if (!admissible.length) {
+      empty.textContent = failed ? "The image catalog is unavailable."
+        : query.trim() ? `No images match "${query.trim()}".`
+        : "No images available.";
+    }
+  }
+
+  function choose(asset) {
+    params[node.key] = asset.url;
+    onPicked?.();
+    close();
+  }
+
+  function runSearch(q) {
+    const seq = ++searchSeq;
+    Promise.resolve()
+      .then(() => imageCatalog.search(q, { limit: SEARCH_LIMIT }))
+      .then((entries) => {
+        if (closed || seq !== searchSeq) return;        // a newer search already won
+        failed = false;
+        results = Array.isArray(entries) ? entries : [];
+        render();
+      })
+      .catch(() => {
+        if (closed || seq !== searchSeq) return;
+        failed = true;
+        results = [];
+        render();
+      });
+  }
+
+  search.addEventListener("input", () => {
+    query = search.value;
+    clearTimeout(debounce);
+    debounce = setTimeout(() => runSearch(query.trim()), SEARCH_DEBOUNCE_MS);
+  });
+
+  // ── closing ─────────────────────────────────────────────────────────────
+  const handle = { close };
+
+  function close() {
+    if (closed) return;                                  // idempotent
+    closed = true;
+    clearTimeout(debounce);
+    document.removeEventListener("keydown", onKey);
+    picker.remove();
+    if (openPicker === handle) openPicker = null;
+  }
+  function onKey(ev) {
+    if (ev.key !== "Escape") return;
+    ev.stopPropagation();
+    close();
+  }
+  document.addEventListener("keydown", onKey);
+  closeBtn.addEventListener("click", close);
+
+  runSearch("");
+  render();
+  openPicker = handle;
+  return handle;
+}
+
+setImagePicker(openImagePicker);

package/src/framework/panel/render.js

@@ -227,6 +227,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
       onCommit: () => commit([node.key]),
       info,
       fontCatalog: opts.fontCatalog,
+      imageCatalog: opts.imageCatalog,
     });
     nodeEls.set(node.id, widget.el);
     if (node.key && !keyToId.has(node.key)) keyToId.set(node.key, node.id);

package/src/framework/panel/widget-specs.js

@@ -37,6 +37,7 @@ export const WIDGET_SPECS = [
   { type: "select", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
   { type: "radio", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
   { type: "font", kind: "control", fields: [...AUTHOR_COMMON, "allow", "preview"] },
+  { type: "image", kind: "control", fields: [...AUTHOR_COMMON, "allow"] },
   { type: "readout", kind: "display", fields: ["type", "label", "description", "unit", "derivedKey", "hidden", "when", "whenFalse"] },
 ];
 
@@ -56,6 +57,7 @@ const AUTHOR_EXTRAS = {
   select: ["options"],
   radio: ["options"],
   font: ["allow", "preview"],
+  image: ["allow"],
 };
 const AUTHOR_FIELDS = new Map(Object.entries(AUTHOR_EXTRAS).map(
   ([type, extra]) => [type, [...AUTHOR_COMMON, ...extra]]));