partforge 0.97.0 → 0.98.0

package/src/framework/{image-ingest.js → ingest/image-ingest.js}

@@ -3,8 +3,8 @@
 //
 // 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.
+// enforces that. It is exported from src/ingest.js (`partforge/ingest`), not
+// from the main entry — see that file's header for why.
 //
 // 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

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

@@ -11,7 +11,8 @@ import { imageControlAllows, imageSourceAllowed, isNoImageSource } from "./image
 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
@@ -148,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;
@@ -179,6 +184,29 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         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
@@ -291,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/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/mount.js

@@ -299,12 +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 } = {}) {
@@ -964,7 +976,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog, imageCatalog });
+      { fontCatalog, imageCatalog, onAssetUpload });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {

package/src/framework/panel/render.js

@@ -228,6 +228,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
       info,
       fontCatalog: opts.fontCatalog,
       imageCatalog: opts.imageCatalog,
+      onAssetUpload: opts.onAssetUpload,
     });
     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

@@ -38,6 +38,7 @@ export const WIDGET_SPECS = [
   { 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: "vector", kind: "control", fields: [...AUTHOR_COMMON, "allow"] },
   { type: "readout", kind: "display", fields: ["type", "label", "description", "unit", "derivedKey", "hidden", "when", "whenFalse"] },
 ];
 
@@ -58,6 +59,7 @@ const AUTHOR_EXTRAS = {
   radio: ["options"],
   font: ["allow", "preview"],
   image: ["allow"],
+  vector: ["allow"],
 };
 const AUTHOR_FIELDS = new Map(Object.entries(AUTHOR_EXTRAS).map(
   ([type, extra]) => [type, [...AUTHOR_COMMON, ...extra]]));