partforge 0.96.0 → 0.98.0

package/src/framework/ingest/node-dom.js

@@ -0,0 +1,69 @@
+// src/framework/ingest/node-dom.js
+// A headless DOM for the `partforge ingest` CLI verb, promoted from the old
+// scripts/ingest-svg.mjs (deleted — see bin/cli.js's `ingest` command).
+// paper-core (imported by svg-ingest.js) builds a canvas and asks for a 2D
+// context at MODULE LOAD time, so installNodeDom() must run and finish BEFORE
+// svg-ingest.js is ever imported — the CLI installs this DOM first and only
+// then dynamically imports the converter (registry.js's `convert` thunk for
+// the "vector" kind).
+//
+// happy-dom is an OPTIONAL peer dependency (see package.json): most consumers
+// never touch the SVG ingest path, and this keeps its ~17 MB out of their
+// installs. It is imported dynamically, HERE, inside installNodeDom() — never
+// at this module's top level — so bin/cli.js (and every other CLI verb) keeps
+// loading and working when happy-dom isn't installed; the failure only
+// surfaces on this path, with a message naming the install command.
+//
+// stubCanvas2dContext is exported separately from installNodeDom's own DOM
+// setup: test/setup/happy-dom-patches.js needs the identical no-op 2D context
+// for VITEST's own happy-dom test environment (a wholly different Window than
+// the one installNodeDom() constructs here — vitest boots its own). Importing
+// this one function from both places is what replaces what used to be two
+// independently hand-typed copies of the same stub.
+export function stubCanvas2dContext() {
+  return {
+    save() {}, restore() {}, beginPath() {}, closePath() {}, moveTo() {}, lineTo() {},
+    bezierCurveTo() {}, quadraticCurveTo() {}, arc() {}, rect() {}, fill() {}, stroke() {},
+    clip() {}, translate() {}, scale() {}, rotate() {}, transform() {}, setTransform() {},
+    clearRect() {}, fillRect() {}, strokeRect() {}, setLineDash() {},
+    fillText() {}, strokeText() {},
+    measureText: () => ({ width: 0 }),
+    getImageData: () => ({ data: new Uint8ClampedArray(4) }),
+    createImageData: (w, h) => ({ data: new Uint8ClampedArray(Math.max(0, w) * Math.max(0, h) * 4), width: w, height: h }),
+    putImageData() {}, drawImage() {}, isPointInPath: () => false,
+    createLinearGradient: () => ({ addColorStop() {} }),
+    canvas: { width: 1, height: 1 },
+  };
+}
+
+// Installs a headless DOM as globals, for a plain Node process (the CLI) that
+// otherwise has none. Idempotent enough for the CLI's one-shot use — it is not
+// meant to be called more than once per process.
+export async function installNodeDom() {
+  let Window;
+  try {
+    ({ Window } = await import("happy-dom"));
+  } catch {
+    throw new Error(
+      "ingest: converting SVG headlessly needs happy-dom (an optional peer dependency) — " +
+      "install it with `npm install happy-dom`",
+    );
+  }
+  const window = new Window();
+  // Node 21+ defines a getter-only `navigator` global of its own, so a plain
+  // Object.assign throws ("Cannot set property navigator of #<Object> which
+  // has only a getter") the moment it reaches that key. Define each property
+  // explicitly instead, overriding whatever accessor Node already installed.
+  for (const [key, value] of Object.entries({
+    window, self: window, document: window.document, navigator: window.navigator,
+    DOMParser: window.DOMParser, HTMLCanvasElement: window.HTMLCanvasElement,
+    Image: window.Image, SVGElement: window.SVGElement,
+  })) {
+    Object.defineProperty(globalThis, key, { value, writable: true, configurable: true, enumerable: true });
+  }
+  // paper-core builds a canvas and asks for a 2D context at module load;
+  // happy-dom has no canvas backend, and paper never touches the raster
+  // context for geometry (see svg-ingest.js's own header for why a no-op
+  // stub is enough).
+  globalThis.HTMLCanvasElement.prototype.getContext = stubCanvas2dContext;
+}

package/src/framework/ingest/registry.js

@@ -0,0 +1,57 @@
+// src/framework/ingest/registry.js
+// The one table that answers "what does this file become?" — read by the panel's
+// drop widget AND by `partforge ingest`. It does NOT route to part fields: the
+// declaration-function pattern (`images: (p) => ({ relief: p.relief })`) already
+// does that, because a control writes into its own param key and the author's
+// declaration puts that key in the right field.
+//
+// DOM-free, node:-free, and converter-free AT MODULE SCOPE: `convert` is a thunk
+// returning a dynamic import, so reading the table costs nothing and the CLI
+// never loads paper.js for a font.
+import { sniffMediaType } from "./sniff.js";
+
+export const ASSET_KINDS = ["image", "vector", "font"];
+
+const ROWS = [
+  {
+    kind: "image",
+    name: "Image",                        // the human slot name — "Try the ${name} control" in a refusal message
+    label: "an image (PNG, JPG or WebP)",
+    accepts: ["image/png", "image/jpeg", "image/webp"],
+    convert: () => import("./image-ingest.js").then((m) => m.imageToPng),
+  },
+  {
+    kind: "vector",
+    name: "Artwork",
+    label: "artwork (SVG)",
+    accepts: ["image/svg+xml"],
+    convert: () => import("./svg-ingest.js").then((m) => m.ingestSvg),
+  },
+  {
+    kind: "font",
+    name: "Font",
+    label: "a font (TTF or OTF)",
+    accepts: ["font/ttf", "font/otf"],
+    convert: null,                        // used as-is; validated, never converted
+  },
+];
+
+export const rowFor = (kind) => ROWS.find((r) => r.kind === kind);
+
+// Which kind, if any, WOULD accept this media type — the "use the Artwork slot"
+// hint. null when no slot accepts it (an unsupported format, e.g. WOFF2).
+const kindAccepting = (mediaType) => ROWS.find((r) => r.accepts.includes(mediaType))?.kind ?? null;
+
+export function classify(bytes, kind) {
+  const mediaType = sniffMediaType(bytes);
+  const row = rowFor(kind);
+  if (row && mediaType && row.accepts.includes(mediaType)) return { ok: true, mediaType };
+  return { ok: false, reason: mediaType ? "wrong-type" : "unrecognised",
+           mediaType, suggestKind: mediaType ? kindAccepting(mediaType) : null };
+}
+
+export async function convertFor(kind, mediaType) {
+  const row = rowFor(kind);
+  if (!row || !row.accepts.includes(mediaType)) return null;
+  return row.convert ? row.convert() : null;
+}

package/src/framework/ingest/sniff.js

@@ -0,0 +1,96 @@
+// src/framework/ingest/sniff.js
+// Bytes -> media type. The whole point is that a caller passes BYTES, never a
+// filename: a file's claimed type is user input, and this is the path a
+// mislabelled upload would travel. Nothing here trusts an extension because
+// nothing here is given one.
+//
+// DOM-free and node:-free, and free of any converter import, so both the panel
+// and the CLI can read it without loading paper.js.
+
+const MAGIC = [
+  { type: "image/png",  bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+  { type: "image/jpeg", bytes: [0xff, 0xd8, 0xff] },
+  { type: "font/otf",   bytes: [0x4f, 0x54, 0x54, 0x4f] },              // "OTTO"
+  { type: "font/woff2", bytes: [0x77, 0x4f, 0x46, 0x32] },              // "wOF2"
+  { type: "font/ttf",   bytes: [0x00, 0x01, 0x00, 0x00] },
+  { type: "font/ttf",   bytes: [0x74, 0x72, 0x75, 0x65] },              // "true"
+];
+
+const startsWith = (u8, sig) => {
+  if (u8.length < sig.length) return false;
+  for (let i = 0; i < sig.length; i++) if (u8[i] !== sig[i]) return false;
+  return true;
+};
+
+// How far into a text file we look for an <svg root. Enough for an XML
+// declaration, a DOCTYPE and a licence comment; bounded so a huge non-SVG text
+// file is not scanned end to end. An SVG behind more than 4 KB of leading
+// comments returns null rather than being recognised — an accepted bounded false
+// negative.
+const SVG_SCAN = 4096;
+
+export function sniffMediaType(input) {
+  if (!input) return null;
+  const u8 = input instanceof Uint8Array ? input : new Uint8Array(input);
+  if (u8.length === 0) return null;
+
+  for (const m of MAGIC) if (startsWith(u8, m.bytes)) return m.type;
+
+  // WebP is RIFF????WEBP — the size field sits between the two tags.
+  if (u8.length >= 12 && startsWith(u8, [0x52, 0x49, 0x46, 0x46])
+      && u8[8] === 0x57 && u8[9] === 0x45 && u8[10] === 0x42 && u8[11] === 0x50) {
+    return "image/webp";
+  }
+
+  // SVG has no magic number. Look for an <svg ROOT element by skipping leading
+  // prologue (BOM, whitespace, XML declaration, comments, DOCTYPE), then
+  // requiring the next real tag to be <svg followed by whitespace, >, or /.
+  // This anchors to the document root and rejects HTML files with inline <svg>.
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  const head = decoder.decode(u8.subarray(0, SVG_SCAN));
+
+  let pos = 0;
+  const len = head.length;
+
+  // Skip UTF-8 BOM
+  if (head.charCodeAt(0) === 0xFEFF) pos = 1;
+
+  // Skip leading whitespace
+  while (pos < len && /\s/.test(head[pos])) pos++;
+
+  // Skip XML declaration
+  if (head.substring(pos).startsWith("<?xml")) {
+    const end = head.indexOf("?>", pos);
+    if (end !== -1) {
+      pos = end + 2;
+      while (pos < len && /\s/.test(head[pos])) pos++;
+    }
+  }
+
+  // Skip DOCTYPE
+  if (head.substring(pos).startsWith("<!DOCTYPE")) {
+    const end = head.indexOf(">", pos);
+    if (end !== -1) {
+      pos = end + 1;
+      while (pos < len && /\s/.test(head[pos])) pos++;
+    }
+  }
+
+  // Skip comments
+  while (head.substring(pos).startsWith("<!--")) {
+    const end = head.indexOf("-->", pos);
+    if (end !== -1) {
+      pos = end + 3;
+      while (pos < len && /\s/.test(head[pos])) pos++;
+    } else {
+      break;
+    }
+  }
+
+  // Check if the next real tag is <svg
+  if (head.substring(pos).match(/^<svg[\s>\/]/i)) {
+    return "image/svg+xml";
+  }
+
+  return null;
+}

package/src/framework/jobs.js

@@ -7,9 +7,12 @@ 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";
+import { vectorControlAllows, vectorSourceAllowed, isNoVectorSource } from "./vector-source.js";
+import { vectorsFor, ensureVectors } from "./vectors.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
 
 // The oracle loads LAZILY, per job family, never at worker boot. It is the largest
@@ -146,10 +149,14 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // default.
     const { p, d } = resolveParams(part, msg.params, (params) => {
       // A param bound to a `type: "font"` control is user input — on a shared
-      // link it is arbitrary attacker-supplied text that `fonts: (p) => …` would
-      // turn into a fetch URL. Refuse out-of-`allow` values back to the part's
-      // own default rather than failing the build: a bad link should show the
-      // part, not an error page.
+      // link a STRING value is arbitrary attacker-supplied text that
+      // `fonts: (p) => …` would turn into a fetch URL. A BYTE value
+      // (ArrayBuffer/typed array) always passes fontSourceAllowed regardless of
+      // `allow` — see font-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 drop-target path). Refuse out-of-`allow` values back
+      // to the part's own default rather than failing the build: a bad link
+      // should show the part, not an error page.
       for (const [key, allow] of fontControlAllows(part)) {
         const v = params[key];
         if (isNoFontSource(v) || fontSourceAllowed(v, allow)) continue;
@@ -158,6 +165,48 @@ 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];
+      }
+      // Same shape again for `type: "vector"` controls — a param bound to one
+      // is user input, and on a shared link a STRING value is arbitrary
+      // attacker text that `vectors: (p) => …` would turn into a fetch URL.
+      // Unlike the two blocks above, a non-string value here does NOT bypass
+      // the check on a "can't survive a link" plausibility argument — see
+      // vector-source.js's header: a parsed vector document is plain JSON and
+      // survives a link just fine. It's permitted for the narrower, still-
+      // sufficient structural reason that vectorSourceAllowed applies:
+      // asset-resolve.js only ever calls `fetch` for a string/URL source, so
+      // an object (or bytes) can never become the SSRF-style request `allow`
+      // exists to gate. Runs in this same sanitize hook, not after
+      // resolveParams returns, for the reason both comments above state:
+      // 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 vectorControlAllows(part)) {
+        const v = params[key];
+        if (isNoVectorSource(v) || vectorSourceAllowed(v, allow)) continue;
+        const message = `vector 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 +276,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
@@ -236,7 +319,25 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // prevent. Guarding this on `part.vectors` would skip exactly the case where
     // pruning matters most: a worker rebound from a part WITH artwork to one
     // WITHOUT would leave the old names resolvable forever.
-    await ensureVectors(kernel, part.vectors);
+    //
+    // Empty sources are filtered out first, exactly as the fonts and images
+    // blocks above do with their own isNo*Source helper: an empty default is
+    // the natural shape for a drop-target control (`defaults: { art: "" }`,
+    // with `vectors: (p) => ({ badge: p.art })`), and passing "" through to
+    // ensureVectors reaches `fetch("")` and fails with "Failed to parse URL
+    // from" — a first-run error message that names nothing an author can act
+    // on. An unset source declares NO artwork for that name; a build that
+    // still calls k.vector2d on it gets the ordinary unknown-vector throw, and
+    // the progress note keeps a genuine typo visible rather than swallowed.
+    const vectorsDecl = vectorsFor(part, p) ?? {};
+    const declaredVectors = Object.fromEntries(
+      Object.entries(vectorsDecl).filter(([name, src]) => {
+        if (!isNoVectorSource(src)) return true;
+        onProgress(`no vector source declared for "${name}" — skipping`);
+        return false;
+      }),
+    );
+    await ensureVectors(kernel, declaredVectors);
     // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
     const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
     // Explicit selection (headless exportParts) overrides view-derived selection.

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/lint/rules-vector.js

@@ -1,6 +1,8 @@
-// Group 10 — vector-art call well-formedness. All three conditions throw at
-// build time anyway; these rules move them ahead of the kernel boot, which is
-// where an authoring agent wants them.
+// Group 10 — vector-art call well-formedness, plus vector-control wiring. The
+// three call rules catch conditions that throw at build time anyway; they move
+// them ahead of the kernel boot, which is where an authoring agent wants them.
+// The fourth (vector-control-not-in-vectors) catches the one shape that never
+// throws at all — a picker wired to nothing.
 //
 // All read `probe().calls`, whose `args` are JSON.stringify of the RESOLVED
 // argument values under the part's default params (probe.js's `describe`), not
@@ -16,9 +18,19 @@
 // package's header), so without a supplied document neither rule can tell
 // units from shapes and both stay silent rather than guess.
 import { err } from "./finding.js";
+import { vectorControlAllows } from "../vector-source.js";
 
 const declaredVectors = (part) => Object.keys(part?.vectors ?? {});
 
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+// A URL-shaped sentinel (has a "://"), not an arbitrary string — some `vectors`
+// 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. Same
+// device, and the same reason, as rules-images.js's.
+const SENTINEL = "pf-lint-sentinel://vector-control-not-in-vectors";
+
 // The name arrives JSON-serialized, so JSON.parse recovers it — and yields null
 // for anything that is not a string (import-unknown-name reads its name the same way).
 const literalName = (src) => {
@@ -42,6 +54,15 @@ export const VECTOR_RULES = [
   {
     id: "vector-unknown-name",
     run: ({ part, probe }) => {
+      // Only a STATIC `vectors` object has statically-knowable names. A
+      // function's return value depends on params lint doesn't enumerate, and
+      // `Object.keys(fn)` is `[]` — without this guard every k.vector2d call in
+      // a function-form part reports as unknown, and since `partforge measure`
+      // runs lint first, the part cannot be measured at all. Exactly the guard
+      // rules-fonts.js and rules-images.js already carry; the function form of
+      // `vectors` arrived after this rule and nobody carried it across.
+      // vector-control-not-in-vectors below is what covers the function form.
+      if (typeof part?.vectors === "function") return [];
       const known = new Set(declaredVectors(part));
       const seen = new Set();
       const out = [];
@@ -109,4 +130,48 @@ export const VECTOR_RULES = [
       return out;
     },
   },
+  {
+    // The vectors twin of image-control-not-in-images / font-control-not-in-fonts:
+    // a `type: "vector"` control whose key never reaches `vectors:` changes a
+    // param and nothing else — the artwork never moves — and without this the
+    // mistake only shows up at build time, or not at all.
+    //
+    // It covers BOTH shapes of the mistake, because for vectors both are real:
+    // a static `vectors` object provably cannot read a param, so a vector
+    // control beside one is inert by construction (font-control-not-in-fonts's
+    // question); and a function-form `vectors` that simply never returns the
+    // picked value is inert too, which can only be established by calling it
+    // with a sentinel (image-control-not-in-images's question). Together with
+    // vector-unknown-name — which runs only for the static form — every part
+    // shape is judged by exactly one of the two rules.
+    id: "vector-control-not-in-vectors",
+    run: ({ part, p }) => {
+      const controls = vectorControlAllows(part);
+      if (controls.size === 0) return [];
+      const isFn = typeof part?.vectors === "function";
+      // A function may wrap the picked value (`new URL(p.art)`) rather than
+      // pass it through, so match on the sentinel appearing in the value, not
+      // on identity.
+      const mentions = (v) => (typeof v === "string" || v instanceof URL) && String(v).includes(SENTINEL);
+      const out = [];
+      for (const key of controls.keys()) {
+        if (isFn) {
+          let resolved;
+          try { resolved = part.vectors({ ...p, [key]: SENTINEL }); }
+          catch { continue; } // can't be probed safely — not evidence either way
+          if (isPlainObject(resolved) && Object.values(resolved).some(mentions)) continue;
+          out.push(err("vector-control-not-in-vectors",
+            `control "${key}" is a vector picker, but this part's \`vectors\` function never returns the picked value — the picked value is never resolved.`,
+            `Reference p.${key} from vectors, e.g. vectors: (p) => ({ ${key}: p.${key} }), and consume it with k.vector2d("${key}", { width: 20 }).`,
+            "vectors"));
+          continue;
+        }
+        out.push(err("vector-control-not-in-vectors",
+          `control "${key}" is a vector picker, but this part's \`vectors\` is ${part?.vectors ? "a static object" : "missing"} — the picked value is never resolved.`,
+          `Declare vectors as a function of params, e.g. vectors: (p) => ({ ${key}: p.${key} }), and reference it with k.vector2d("${key}", { width: 20 }).`,
+          "vectors"));
+      }
+      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

@@ -299,11 +299,24 @@ function createCleanupStack() {
 //                                         // message — and calls runtime.annotate.send() itself.
 //                                         // Ignored without onAnnotationSend (there is no toolbar
 //                                         // to place it in).
+// onAssetUpload(blob, { kind, filename }) // the drop widget's (widgets/file-drop.js) upload hook:
+//                                         // async, resolves to a source string (an https: URL or a
+//                                         // host token) that gets written into the param. `blob` is
+//                                         // the CONVERTED artifact — a PNG, a partforge-vector JSON
+//                                         // blob, or the original file for a font — never the user's
+//                                         // raw drop. Omit it and the converted bytes land straight
+//                                         // in the param instead (what the partforge-cloud sandbox
+//                                         // needs, since it cannot fetch URLs — a correct destination,
+//                                         // not a degraded one). A rejection is reported through the
+//                                         // control's own onError; the widget keeps the converted blob
+//                                         // so a retry costs a network call, not a reconvert.
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
 export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
                               fontCatalog,
+                              imageCatalog,
+                              onAssetUpload,
                               viewerState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
@@ -963,7 +976,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog });
+      { fontCatalog, imageCatalog, onAssetUpload });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {