partforge 0.101.0 → 0.102.0

package/docs/AUTHORING-PARTS.md

@@ -731,9 +731,9 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"checkbox"` | an on/off box: ticked writes `on`, cleared writes `0` | `on` (default `1`) |
 | `"select"` | a dropdown | `options` |
 | `"radio"` | a segmented button row | `options` |
-| `"font"` | a typeface picker (or a URL field with no catalog), plus a drop target | `allow`, `preview` |
-| `"image"` | an image picker (or a URL field with no catalog), plus a drop target | `allow` |
-| `"vector"` | a URL field plus a drop target — no catalog exists | — |
+| `"font"` | a typeface picker with a catalog, else a drop target | `allow`, `preview`, `sourceField` |
+| `"image"` | an image picker with a catalog, else a drop target showing the artwork | `allow`, `sourceField` |
+| `"vector"` | a drop target showing the artwork — no catalog exists | `sourceField` |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and clamp to `[min, max]` on commit.
@@ -748,6 +748,18 @@ each entry is both value and label — or the long form
 types, `12` is not `"12"`). An option's `description` surfaces as a hover tooltip
 on that one option, not as a ⓘ popover.
 
+**`sourceField: true`** (font/image/vector) adds a raw source text box to the
+control. It is **off by default**: the drop target already carries the preview,
+the drag target and click-to-choose, and where a catalog is wired there is a
+picker too, so on a 288 px rail a text box is the affordance earning its space
+least. Turn it on when typing a source by hand is something your users will
+actually do — pasting an `https:` URL they already have, or a host `pfc-asset:`
+token. Hiding it changes nothing else: the same values are accepted by the same
+allow list, and a source set in `defaults` or by the host still applies.
+
+For a `"font"` control with no `fontCatalog` this is the only text entry there
+is, so a standalone app that expects users to paste font URLs should set it.
+
 **`allow` and `preview`** (font) configure the typeface control. `allow` lists the
 source kinds a **param-supplied** value may use — what the picker writes, or what
 arrives in a share link:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.101.0",
+  "version": "0.102.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/app.css

@@ -198,6 +198,101 @@ textarea.text-input { min-height: 64px; resize: vertical; }
 .text-input:focus { outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
+/* ── file drop targets ──────────────────────────────────────────────────────
+   Two forms of the same widget. The LABELLED form is a tile the user is meant
+   to find: it doubles as the thumbnail once there is something to show, so a
+   preview, a drop zone and a click-to-choose occupy one box rather than three.
+   The AMBIENT form is for a control that already has a visible way in (the font
+   control's catalog button) — it covers the control invisibly and only appears
+   while a file is over it, so dropping stays available without spending rail
+   height advertising itself. */
+.file-drop {
+  position: relative; display: flex; flex-direction: column;
+  align-items: center; justify-content: center; gap: 6px;
+  min-height: 56px; margin-top: 6px; padding: 8px;
+  background: var(--pf-input-bg); color: var(--pf-hint);
+  border: 1px dashed var(--pf-border); border-radius: var(--pf-radius-control);
+  text-align: center; cursor: pointer;
+}
+.file-drop:focus-visible { outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
+.file-drop-hint { font: 11px/1.35 var(--pf-sans); }
+
+/* `contain` rather than `cover` because artwork and depth maps are content, not
+   decoration — cropping one to fill the box would misrepresent what is about to
+   be built. The two preview kinds then diverge, because a photograph and a piece
+   of line art want opposite things from the box around them. */
+.file-drop > svg, .file-drop > img {
+  display: block; max-width: 100%; max-height: 96px; object-fit: contain;
+}
+.file-drop > svg { fill: var(--pf-text-2); }
+/* Once there IS a preview, the frame moves off the tile and onto the artwork.
+   The tile stays full width — it is the drop target, and a full-width one is
+   easier to hit — but goes invisible, so what the eye sees is a rounded box
+   hugging the picture with the hint underneath it, rather than a picture
+   floating inside a much larger box. The border stays at 1px and only loses its
+   colour, so nothing shifts when a thumbnail arrives. */
+.file-drop.has-thumb {
+  border-color: transparent; background: none; padding: 0; gap: 4px;
+}
+.file-drop.has-thumb > img, .file-drop.has-thumb > svg {
+  border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control);
+  background: var(--pf-input-bg);
+}
+/* A RASTER is a filled rectangle, so the border sits directly on the pixels —
+   padding around one reads as a mount around a picture. `border-radius` on an
+   `<img>` clips the image itself, which is what rounds the corners. Sized by
+   `max-height` rather than `height` so a small source is shown at its own size
+   instead of being upscaled into a blur.
+   `width: auto` is load-bearing: this element also carries `.image-preview`,
+   which pins it to `width: 100%` and letterboxes the picture inside a
+   rail-width box with `object-fit`. That is the right behaviour for a preview
+   that fills its container and the wrong one for a frame meant to hug, and it
+   is invisible in the markup — the box just silently stops matching the image. */
+.file-drop.has-thumb > img { max-height: 96px; max-width: 100%; width: auto; margin: 0; }
+/* A VECTOR is line art: strokes running into the border would collide with it
+   rather than be framed by it, so it keeps padding inside its own frame. Sizing
+   by height with `width: auto` lets the viewBox's aspect supply the width, so
+   the frame hugs the drawing instead of the SVG's default 300x150 box. */
+.file-drop.has-thumb > svg { height: 96px; width: auto; max-width: 100%; padding: 8px; }
+
+/* The empty-state hint and the replace hint trade places: exactly one is visible
+   in either state, so a tile is never without an instruction. */
+.file-drop-hint-replace { display: none; }
+.file-drop.has-thumb .file-drop-hint { display: none; }
+.file-drop.has-thumb .file-drop-hint-replace { display: block; }
+
+/* Ambient: no box of its own. Laid over the control, inert to the pointer so
+   every click still reaches the button underneath — the one affordance this
+   form exists to protect. */
+/* Only the controls that actually carry an ambient overlay become positioned —
+   `.slider` is shared by every widget in the rail, and making all of them a
+   containing block to serve one would be a wide change for a narrow need. */
+.slider:has(> .file-drop-ambient) { position: relative; }
+
+.file-drop-ambient {
+  position: absolute; inset: 0; margin: 0; padding: 0;
+  min-height: 0; background: none; border: 0; pointer-events: none;
+}
+/* `dragover` is the only thing that reveals it. Pointer events stay off even
+   then: the drop event still fires on the element, and turning them on would
+   swallow a click that merely passed through mid-drag. */
+.file-drop-ambient.file-drop-over {
+  border: 1px dashed var(--pf-accent); border-radius: var(--pf-radius-control);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+/* Shared drag feedback for the labelled form. */
+.file-drop.file-drop-over {
+  border-color: var(--pf-accent);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+.file-drop-error {
+  margin-top: 5px; font: 11px/1.35 var(--pf-sans); color: var(--pf-err);
+}
+
 /* the `type: "font"` control — a button that shows the current face IN it */
 .font-btn { width: 100%; display: flex; align-items: center; gap: 8px; text-align: left; cursor: pointer;
   background: var(--pf-input-bg); color: var(--pf-text-strong);

package/src/framework/mount.js

@@ -4,6 +4,7 @@ import { createViewer } from "./viewer.js";
 import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
+import { declaredSourceLookup } from "./panel/declared-source.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera, loadProjection, saveProjection } from "./view-state.js";
@@ -976,7 +977,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog, imageCatalog, onAssetUpload });
+      // What the part is actually using for each asset key, so a control opens
+      // showing the bundled default instead of an empty tile. Rebuilt per panel
+      // build, because the declaration is a function of the current params.
+      { fontCatalog, imageCatalog, onAssetUpload,
+        declaredSource: declaredSourceLookup(part, params) });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {

package/src/framework/panel/author.js

@@ -33,6 +33,17 @@ function authoredControl(c) {
     hidden: !!c.hidden,
     when: c.when,
     whenFalse: c.whenFalse,
+    // Asset-control fields. This list is an explicit allow-list, so anything
+    // missing from it is silently dropped rather than failing loudly — which is
+    // how `allow` came to be ignored: an authored `allow: ["asset"]` never
+    // reached the widget, so its own typed-URL check fell back to the default
+    // list and accepted values the worker then refused and reset underneath the
+    // user. The worker-side gate was never affected (imageControlAllows and its
+    // siblings walk the raw authored tree, not this node), so the enforcement
+    // held throughout — but the panel disagreed with it.
+    allow: c.allow,
+    preview: c.preview,
+    sourceField: c.sourceField,
     preserveOn: false,
     marksCustom: true,
   };

package/src/framework/panel/declared-source.js

@@ -0,0 +1,128 @@
+// What a part is ACTUALLY using for an asset key, when the control's own param
+// is empty.
+//
+// The problem this solves is not cosmetic. A part's bundled default lives in the
+// `images`/`vectors` DECLARATION, never in `defaults` — an author cannot move it
+// there, because the allow list passes only `https` and a bundled asset resolves
+// to a `file:`/dev URL, so `defaults: { relief: new URL(…) }` is refused and
+// reset. The declaration is therefore the only home for it, and the panel could
+// not see the declaration at all: `buildControls` receives `part.parameters`.
+// The result was a control that opened empty while the part was plainly building
+// from an image.
+//
+// Main-thread only, and deliberately import-free beyond what a lookup needs: it
+// runs during panel construction, on every rebuild.
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+// `images`/`vectors`/`fonts` may each be a plain map or a function of params —
+// the function form is what a control drives. Resolving it can throw (it is
+// author code running on every panel build), and a broken declaration must not
+// take the panel down: the control simply shows nothing, which is the same thing
+// it showed before this existed.
+function resolveDecl(decl, params) {
+  try {
+    return typeof decl === "function" ? decl(params) : decl;
+  } catch {
+    return undefined;
+  }
+}
+
+const FIELD = { image: "images", vector: "vectors", font: "fonts" };
+
+// URL-shaped for the same reason lint's probes are: a declaration may parse the
+// value it is handed, and an arbitrary string would make it throw for reasons
+// that have nothing to do with which asset the key feeds.
+const SENTINEL = "pf-panel-sentinel://declared-source";
+
+/**
+ * Build `(kind, key) => source | undefined` for one part and its current params.
+ *
+ * Returns `undefined` when the param already holds a value: the param IS the
+ * user's choice, and the declaration for that key is derived from it. Only an
+ * empty param falls through to whatever the part declared.
+ */
+export function declaredSourceLookup(part, params) {
+  return (kind, key) => {
+    const own = params?.[key];
+    if (own !== undefined && own !== null && own !== "") return undefined;
+
+    const decl = part?.[FIELD[kind]];
+    const resolved = resolveDecl(decl, params ?? {});
+    if (!resolved || typeof resolved !== "object") return undefined;
+
+    // A control's param key is NOT necessarily the asset's name. emblem.js
+    // declares `vectors: (p) => ({ emblem: p.art || bundled })` — key `art`,
+    // asset `emblem`. relief.js happens to use the same word for both, which is
+    // what makes the assumption look safe until it is not.
+    //
+    // So probe, the way lint's *-control-not-in-* rules already do: resolve the
+    // declaration once with a sentinel in this key and see which asset name it
+    // came out under. A URL-shaped sentinel, because a declaration is free to
+    // parse what it is handed and an arbitrary string would make it throw for
+    // reasons unrelated to the mapping.
+    let name = key;
+    if (typeof decl === "function" && !(key in resolved)) {
+      const probe = resolveDecl(decl, { ...(params ?? {}), [key]: SENTINEL });
+      const hit = probe && typeof probe === "object"
+        && Object.keys(probe).find((n) => probe[n] === SENTINEL);
+      if (!hit) return undefined;   // this key feeds nothing — not our asset
+      name = hit;
+    }
+
+    const source = resolved[name];
+    return source == null || source === "" ? undefined : source;
+  };
+}
+
+/**
+ * A declared image source -> something an `<img>` can load, or `undefined`.
+ *
+ * The allow list gates PARAMS, not author declarations, so a `file:` or dev URL
+ * is perfectly fine to display here — the browser is loading it, nothing is
+ * being accepted from an untrusted link.
+ */
+export async function declaredImageUrl(source) {
+  try {
+    let v = typeof source === "function" ? await source() : source;
+    // A Vite `() => import("./x.png")` resolves to `{ default: url }`.
+    if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+    if (v instanceof URL) return v.href;
+    if (typeof v === "string" && v) return v;
+    if (v instanceof ArrayBuffer || ArrayBuffer.isView(v)) {
+      return URL.createObjectURL(new Blob([v], { type: "image/png" }));
+    }
+    return undefined;
+  } catch {
+    return undefined;   // a thunk that rejects shows nothing, it does not propagate
+  }
+}
+
+/**
+ * A declared vector source -> its parsed document, or `undefined`.
+ *
+ * Unlike an image there is nothing to point at: the thumbnail is drawn from the
+ * document's own contours, so the file has to be fetched and parsed. Results are
+ * memoised per source, because a panel rebuild would otherwise refetch on every
+ * slider drag.
+ */
+const vectorDocs = new Map();
+export async function declaredVectorDoc(source) {
+  if (source == null) return undefined;
+  if (typeof source === "object" && !(source instanceof URL) && !("default" in source)) return source;
+  if (vectorDocs.has(source)) return vectorDocs.get(source);
+  const p = (async () => {
+    try {
+      let v = typeof source === "function" ? await source() : source;
+      if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+      if (v && typeof v === "object" && !(v instanceof URL)) return v;   // already parsed
+      const res = await fetch(v instanceof URL ? v.href : v);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;   // offline, 404, CORS, malformed JSON — all show nothing
+    }
+  })();
+  vectorDocs.set(source, p);
+  return p;
+}

package/src/framework/panel/render.js

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

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

package/src/framework/panel/widgets/file-drop.js

@@ -86,24 +86,47 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
+// `ambient` is for a control that already has a visible way in — the font
+// control's catalog button, say. A labelled drop zone under it would spend rail
+// height repeating the same offer, so the ambient form carries no hint, no click
+// target and no place in the tab order: it is an overlay that shows itself only
+// while a file is over it (see `.file-drop-ambient` in app.css). Dropping still
+// works, it is simply not advertised.
+//
+// The click path is dropped rather than hidden, deliberately: an invisible
+// overlay that still swallowed clicks would eat the button underneath it, which
+// is the one affordance ambient mode exists to protect.
+export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient = false }) {
   const row = rowFor(kind);
-  const wrap = el("div", "file-drop");
-  wrap.tabIndex = 0;
-  wrap.setAttribute("role", "button");
-  const hint = el("span", "file-drop-hint", `Drop ${row?.label ?? "a file"} here, or click to choose`);
-  wrap.append(hint);
+  const wrap = el("div", ambient ? "file-drop file-drop-ambient" : "file-drop");
+  if (!ambient) {
+    wrap.tabIndex = 0;
+    wrap.setAttribute("role", "button");
+    // Two hints, swapped by CSS on `.has-thumb`. The empty-state one is the only
+    // thing in an empty tile; the replace one takes over once a preview fills it.
+    // Without the second, a tile showing a part's declared artwork — now the
+    // state a control OPENS in — carried no instruction at all, because the
+    // first is hidden the moment a thumbnail appears.
+    wrap.append(el("span", "file-drop-hint", `Drop ${row?.label ?? "a file"} here, or click to choose`));
+    wrap.append(el("span", "file-drop-hint file-drop-hint-replace", "Drop to replace, or click to choose"));
+  }
 
   // The click/keyboard path to the same handler a drop uses. Hidden rather
   // than absent: a real `<input type="file">` is what gives this a native
   // "Choose File" affordance and OS-level type filtering (`accept`), neither
   // of which is worth hand-rolling.
-  const input = document.createElement("input");
-  input.type = "file";
-  input.className = "file-drop-input";
-  input.hidden = true;
-  if (row?.accepts?.length) input.accept = row.accepts.join(",");
-  wrap.append(input);
+  // Ambient mode has no click path, so it gets no input at all — an unused one
+  // would still be focusable in some browsers and would show up to a screen
+  // reader as a second, unlabelled file control.
+  let input = null;
+  if (!ambient) {
+    input = document.createElement("input");
+    input.type = "file";
+    input.className = "file-drop-input";
+    input.hidden = true;
+    if (row?.accepts?.length) input.accept = row.accepts.join(",");
+    wrap.append(input);
+  }
 
   // The converted artifact from the most recently accepted drop — a Blob (or,
   // for a `convert: null` kind like font, the original File, which already IS
@@ -266,10 +289,15 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
   wrap.addEventListener("drop", onDrop, { signal });
   wrap.addEventListener("dragover", onDragOver, { signal });
   wrap.addEventListener("dragleave", onDragLeave, { signal });
-  wrap.addEventListener("click", onClick, { signal });
-  wrap.addEventListener("keydown", onKeydown, { signal });
   wrap.addEventListener("paste", onPaste, { signal });
-  input.addEventListener("change", onChange, { signal });
+  // Click, keyboard and the input's own change only exist when there is an input
+  // to open — ambient mode is drop-and-paste only, so that the control's real
+  // button keeps every click.
+  if (input) {
+    wrap.addEventListener("click", onClick, { signal });
+    wrap.addEventListener("keydown", onKeydown, { signal });
+    input.addEventListener("change", onChange, { signal });
+  }
 
   return {
     el: wrap,
@@ -295,12 +323,13 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload }) {
 // Returns `{ el, errorEl, dispose }` rather than appending anything itself —
 // the caller still owns layout (where the drop target and error line sit
 // relative to the field/button), only the wiring is shared.
-export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommit, onRender }) {
+export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommit, onRender, ambient = false }) {
   const errorEl = el("div", "file-drop-error");
   errorEl.hidden = true;
 
   const drop = makeFileDrop({
     kind,
+    ambient,
     onAssetUpload,
     onSource: (source) => {
       errorEl.hidden = true;

package/src/framework/panel/widgets/font.js

@@ -86,7 +86,11 @@ export function makeFont(node, params, { onChange, onCommit, info, fontCatalog,
       onCommit?.();
     });
     paintField();
-    wrap.append(field);
+    // Same opt-in rule as image/vector: the URL box appears only for
+    // `sourceField: true`. This branch has no catalog button, so hiding it
+    // leaves the drop zone as the way in — which is why THIS branch keeps its
+    // labelled drop zone rather than going ambient like the catalog one below.
+    if (node.sourceField === true) wrap.append(field);
 
     const drop = mountDrop("font", {
       params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
@@ -146,7 +150,11 @@ export function makeFont(node, params, { onChange, onCommit, info, fontCatalog,
     picker = openFontPicker?.({ node, params, allow, fontCatalog, anchor: wrap, onPicked: () => { paint(); onChange?.(); onCommit?.(); } }) ?? null;
   });
 
-  const drop = mountDrop("font", { params, node, onAssetUpload, onChange, onCommit, onRender: paint });
+  // Ambient: this branch already has the catalog button as its visible way in, so
+  // the drop covers the control invisibly and reveals itself only while a file is
+  // over it. The no-catalog branch above stays labelled — there, the drop zone is
+  // the only affordance and hiding it would strand the user.
+  const drop = mountDrop("font", { params, node, onAssetUpload, onChange, onCommit, onRender: paint, ambient: true });
   wrap.append(drop.el, drop.errorEl);
 
   return {

package/src/framework/panel/widgets/image.js

@@ -18,6 +18,7 @@
 import { attachInfo } from "../info.js";
 import { IMAGE_ALLOW_DEFAULT, imageSourceAllowed } from "../../image-source.js";
 import { mountDrop } from "./file-drop.js";
+import { declaredImageUrl } from "../declared-source.js";
 
 function el(tag, className, text) {
   const node = document.createElement(tag);
@@ -40,21 +41,70 @@ export function imageLabel(source) {
   return file || source;
 }
 
-// Point (or unpoint) the live preview. A byte-valued param has no URL to hand
-// the browser, so the image stays hidden rather than trying to render it or
-// showing a broken-image glyph — same rule an empty/unset value gets. `onerror`
-// covers the other broken-image case: a URL that 404s or that CORS refuses.
-function paintPreview(img, source) {
-  if (typeof source === "string" && source) {
+// An object URL is a real resource, not a string: the browser pins the blob
+// behind it until it is revoked, and a panel rebuild constructs a fresh widget
+// every time. This owns the whole lifetime — one live URL at a time, the old one
+// revoked before a new one replaces it, and everything released on dispose — so
+// no caller has to remember. Returns `null` for a value that needs no URL.
+function makeObjectUrlSlot() {
+  let current = null;
+  const release = () => {
+    if (current) URL.revokeObjectURL(current);
+    current = null;
+  };
+  return {
+    forBytes(source) {
+      release();
+      if (!isBytes(source)) return null;
+      // Always image/png: `imageToPng` is what produced these bytes, whatever the
+      // user dropped. The type matters — a Blob with none renders nothing.
+      current = URL.createObjectURL(new Blob([source], { type: "image/png" }));
+      return current;
+    },
+    dispose: release,
+  };
+}
+
+// Point (or unpoint) the live preview. A string source is used directly. Bytes —
+// the partforge-cloud sandbox path, where the converted PNG travels in the param
+// because that sandbox cannot fetch URLs — become an object URL, so the cloud
+// gets the same thumbnail as everyone else rather than a blank tile. `onerror`
+// still covers the remaining broken-image case: a URL that 404s or CORS refuses.
+// Resolved ONCE per paint, never per image: the catalog rendering shows the same
+// source in two <img>s, and asking the slot twice would revoke the URL it had
+// just handed the first one, leaving it pointing at a dead blob.
+function previewSrc(source, urls) {
+  return typeof source === "string" && source ? source : urls.forBytes(source);
+}
+
+// When the control's own param is empty, show what the PART is using: its
+// bundled default lives in the `images` declaration, which is the only place it
+// can live (the allow list passes only https, so a file:/dev URL cannot sit in
+// `defaults`). Resolving it is async — a Vite thunk has to be called — so the
+// tile paints empty first and fills in, and a source that never resolves simply
+// leaves it empty. `seq` guards against a slow resolve landing after a newer one.
+function paintDeclared(img, declaredSource, node, apply) {
+  if (!declaredSource) return;
+  const source = declaredSource("image", node.key);
+  if (source === undefined) return;
+  const seq = ++img._pfDeclaredSeq;
+  declaredImageUrl(source).then((url) => {
+    if (url && seq === img._pfDeclaredSeq) apply(url);
+  });
+}
+
+function applyPreview(img, src) {
+  if (src) {
     img.hidden = false;
-    img.src = source;
+    img.src = src;
   } else {
     img.hidden = true;
     img.removeAttribute("src");
   }
 }
 
-export function makeImage(node, params, { onChange, onCommit, info, imageCatalog, onAssetUpload } = {}) {
+export function makeImage(node, params, { onChange, onCommit, info, imageCatalog, onAssetUpload, declaredSource } = {}) {
+  const urls = makeObjectUrlSlot();   // one live preview URL per widget; see makeObjectUrlSlot
   const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : IMAGE_ALLOW_DEFAULT;
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -65,12 +115,12 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
 
   const preview = document.createElement("img");
   preview.className = "image-preview";
+  preview._pfDeclaredSeq = 0;
   preview.alt = "";
   preview.hidden = true;
   // A URL that fails to load (404, CORS, revoked link) must degrade to hidden,
   // not the browser's broken-image glyph.
   preview.addEventListener("error", () => { preview.hidden = true; });
-  wrap.append(preview);
 
   if (!imageCatalog) {
     // Degraded path: a URL field. Unlike `text`, it does NOT write on every
@@ -88,7 +138,13 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
       field.value = isBytes(v) ? "" : String(v ?? "");
       field.placeholder = isBytes(v) ? "Uploaded image" : "";
       field.classList.remove("warn");
-      paintPreview(preview, v);
+      const own = previewSrc(v, urls);
+      applyPreview(preview, own);
+      preview.parentElement?.classList.toggle("has-thumb", !preview.hidden);
+      if (!own) paintDeclared(preview, declaredSource, node, (url) => {
+        applyPreview(preview, url);
+        preview.parentElement?.classList.toggle("has-thumb", true);
+      });
     };
     field.addEventListener("change", () => {
       if (!imageSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
@@ -98,14 +154,25 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
       onCommit?.();
     });
     paintField();
-    wrap.append(field);
+    // The URL box is OFF unless `sourceField: true`. The tile is already preview,
+    // drop target and click-to-choose in one, so on a 288 px rail a fourth
+    // affordance for the same job is the one earning its space least. Typing a
+    // source by hand is the rarer intent — a host token or an https URL someone
+    // already has — so it is the part that becomes opt-in, rather than the one
+    // every part pays rail height for.
+    if (node.sourceField === true) wrap.append(field);
 
     const drop = mountDrop("image", {
       params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
     });
+    // The tile IS the preview: dropping, clicking to choose, and showing what is
+    // currently selected become one box rather than three stacked ones.
+    // `has-thumb` swaps the dashed empty-state border for a solid frame.
+    drop.el.setAttribute("data-pf-thumb", "");
+    drop.el.prepend(preview);
     wrap.append(drop.el, drop.errorEl);
 
-    return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+    return { el: wrap, sync: paintField, dispose: () => { drop.dispose(); urls.dispose(); } };
   }
 
   const btn = el("button", "image-btn");
@@ -131,8 +198,15 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
   const paint = () => {
     const src = params[node.key];
     const seq = ++paintSeq;
-    paintPreview(preview, src);
-    paintPreview(thumb, src);
+    const url = previewSrc(src, urls);
+    applyPreview(preview, url);
+    applyPreview(thumb, url);
+    preview.parentElement?.classList.toggle("has-thumb", !preview.hidden);
+    if (!url) paintDeclared(preview, declaredSource, node, (u) => {
+      applyPreview(preview, u);
+      applyPreview(thumb, u);
+      preview.parentElement?.classList.toggle("has-thumb", true);
+    });
     const show = ({ label: text, width, height }) => {
       if (seq !== paintSeq) return;                  // a newer paint already won
       iname.textContent = width && height ? `${text} (${width}×${height})` : text;
@@ -162,12 +236,16 @@ export function makeImage(node, params, { onChange, onCommit, info, imageCatalog
   });
 
   const drop = mountDrop("image", { params, node, onAssetUpload, onChange, onCommit, onRender: paint });
+  // Same merge as the degraded branch — the large preview lives in the drop tile;
+  // the catalog button keeps its own small thumb.
+  drop.el.setAttribute("data-pf-thumb", "");
+  drop.el.prepend(preview);
   wrap.append(drop.el, drop.errorEl);
 
   return {
     el: wrap,
     sync: paint,
-    dispose: () => { picker?.close(); picker = null; drop.dispose(); },
+    dispose: () => { picker?.close(); picker = null; drop.dispose(); urls.dispose(); },
   };
 }
 

package/src/framework/panel/widgets/vector-thumb.js

@@ -0,0 +1,136 @@
+// A vector document -> a small inline <svg> preview, for the vector control's
+// thumbnail. MAIN-THREAD ONLY (it builds DOM), but deliberately free of any
+// heavy geometry import: `profile.js` is the one dependency and has no imports
+// of its own. Reaching for `vector-format.js`'s expander instead would pull in
+// contour-ops -> paper-bridge -> paper.js, ~1 MB of curve engine loaded on every
+// page that merely SHOWS a vector control, whether or not anyone drops a file.
+//
+// `tessellateContour` is the geometry's OWN tessellator, which matters more than
+// the saved bytes: a thumbnail that flattened curves its own way could show a
+// shape the kernel would not build. Arcs are the specific trap — the format
+// writes them as a point ON the arc, while SVG's `A` command wants radii and
+// sweep flags, so "just map it to A" is a second interpretation waiting to
+// diverge. At thumbnail size a tessellated arc is pixel-identical anyway.
+import { tessellateContour } from "../../geometry/profile.js";
+
+// Enough segments that a full circle reads as round at ~44 px, cheap enough that
+// a document with hundreds of contours still renders in one frame.
+const ARC_SEGS = 24;
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+const finite = (n) => typeof n === "number" && Number.isFinite(n);
+const finitePoint = (p) => Array.isArray(p) && p.length >= 2 && finite(p[0]) && finite(p[1]);
+
+// The four contour kinds, reduced to a ring of points. The three primitives are
+// sugar the format defines by expansion; `toInternalDocument` normally does this,
+// but it lives behind the paper.js import described above — and these expansions
+// are four lines each, so the thumbnail does them directly rather than paying
+// that cost. `path` delegates to the canonical tessellator.
+function ring(contour) {
+  if (!contour || typeof contour !== "object") return null;
+  switch (contour.kind) {
+    case "circle": {
+      const { center: c, r } = contour;
+      if (!finitePoint(c) || !finite(r) || r <= 0) return null;
+      return Array.from({ length: ARC_SEGS }, (_, i) => {
+        const t = (i / ARC_SEGS) * Math.PI * 2;
+        return [c[0] + Math.cos(t) * r, c[1] + Math.sin(t) * r];
+      });
+    }
+    case "rect": {
+      const { center: c, width: w, height: h } = contour;
+      if (!finitePoint(c) || !finite(w) || !finite(h) || w <= 0 || h <= 0) return null;
+      const hw = w / 2, hh = h / 2;
+      // Corner radius is ignored: at thumbnail scale the rounding is sub-pixel,
+      // and squaring it off never changes what the shape reads as.
+      return [[c[0] - hw, c[1] - hh], [c[0] + hw, c[1] - hh], [c[0] + hw, c[1] + hh], [c[0] - hw, c[1] + hh]];
+    }
+    case "polygon":
+      return Array.isArray(contour.points) && contour.points.length >= 3
+        && contour.points.every(finitePoint) ? contour.points.map((p) => [p[0], p[1]]) : null;
+    case "path":
+    default: {
+      if (!finitePoint(contour.start) || !Array.isArray(contour.segments)) return null;
+      // The FILE format names an arc's midpoint `through`; the internal contour
+      // IR names it `via`, and that is what `tessellateContour` reads. A document
+      // read off disk or returned by `ingestSvg` therefore speaks `through`, and
+      // a segment with neither key is treated as a straight line — so skipping
+      // this rename does not fail loudly, it silently replaces every curve with
+      // its chord. A circle becomes a triangle, which looks like a rendering bug
+      // rather than a parsing one.
+      const segments = contour.segments.map((seg) =>
+        seg && seg.through && !seg.via ? { ...seg, via: seg.through } : seg);
+      const pts = tessellateContour({ ...contour, segments }, ARC_SEGS);
+      return Array.isArray(pts) && pts.length >= 3 && pts.every(finitePoint) ? pts : null;
+    }
+  }
+}
+
+// One subpath. Y is negated because the model frame is y-up and SVG is y-down;
+// the viewBox is negated to match, so the flip is a coordinate convention rather
+// than a transform the caller has to know about.
+const subpath = (pts) =>
+  `M ${pts.map(([x, y], i) => `${i ? "L " : ""}${+x.toFixed(3)} ${+(-y).toFixed(3)}`).join(" ")} Z`;
+
+/**
+ * Render a partforge-vector document as an inline <svg>, or return `null` when
+ * there is nothing renderable — an empty document, or one whose coordinates are
+ * not finite. Returning null rather than throwing keeps a malformed document
+ * from taking the control down with it; the caller falls back to a placeholder.
+ */
+export function vectorThumb(doc) {
+  const shapes = doc?.shapes;
+  if (!shapes || typeof shapes !== "object") return null;
+
+  // Every region from every shape lands in ONE path so `evenodd` composes them:
+  // a `subtract` shape's regions then cut the shapes they overlap, which is what
+  // the document means. The known limitation is that two overlapping regions of
+  // the SAME role also cancel — real composition is a boolean the panel has no
+  // business running. At preview size that trade is invisible, and a missing hole
+  // would be far more misleading than a rare cancelled overlap.
+  const subpaths = [];
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+
+  for (const shape of Object.values(shapes)) {
+    // A shape is either an array of regions, or `{ role, regions }` — §2.3.
+    const regions = Array.isArray(shape) ? shape : shape?.regions;
+    if (!Array.isArray(regions)) continue;
+    for (const region of regions) {
+      for (const contour of [region?.outer, ...(region?.holes ?? [])]) {
+        if (contour === undefined) continue;
+        const pts = ring(contour);
+        if (!pts) return null;   // a bad coordinate anywhere means the preview would lie
+        for (const [x, y] of pts) {
+          if (x < minX) minX = x;
+          if (x > maxX) maxX = x;
+          if (y < minY) minY = y;
+          if (y > maxY) maxY = y;
+        }
+        subpaths.push(subpath(pts));
+      }
+    }
+  }
+  if (!subpaths.length) return null;
+
+  // `bbox` is optional and "recomputed when absent" (§2.1), so a hand-authored
+  // document routinely has none. Trusting it when present keeps the preview
+  // framed the way the document says it should be; deriving it otherwise is what
+  // makes an authored file previewable at all.
+  const b = doc.bbox;
+  const box = b && [b.minX, b.minY, b.maxX, b.maxY].every(finite)
+    ? b : { minX, minY, maxX, maxY };
+  const w = box.maxX - box.minX, h = box.maxY - box.minY;
+  if (!(w > 0) || !(h > 0)) return null;
+
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", `${+box.minX.toFixed(3)} ${+(-box.maxY).toFixed(3)} ${+w.toFixed(3)} ${+h.toFixed(3)}`);
+  svg.setAttribute("preserveAspectRatio", "xMidYMid meet");
+  svg.setAttribute("aria-hidden", "true");   // decorative; the control carries the label
+
+  const path = document.createElementNS(SVG_NS, "path");
+  path.setAttribute("d", subpaths.join(" "));
+  path.setAttribute("fill-rule", "evenodd");
+  svg.append(path);
+  return svg;
+}

package/src/framework/panel/widgets/vector.js

@@ -19,6 +19,8 @@
 import { attachInfo } from "../info.js";
 import { VECTOR_ALLOW_DEFAULT, vectorSourceAllowed } from "../../vector-source.js";
 import { mountDrop } from "./file-drop.js";
+import { vectorThumb } from "./vector-thumb.js";
+import { declaredVectorDoc } from "../declared-source.js";
 
 function el(tag, className, text) {
   const node = document.createElement(tag);
@@ -34,7 +36,7 @@ const isBytes = (v) => v instanceof ArrayBuffer || ArrayBuffer.isView(v);
 // byte-valued param.
 const isOpaque = (v) => isBytes(v) || (v != null && typeof v === "object");
 
-export function makeVector(node, params, { onChange, onCommit, info, onAssetUpload } = {}) {
+export function makeVector(node, params, { onChange, onCommit, info, onAssetUpload, declaredSource } = {}) {
   const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : VECTOR_ALLOW_DEFAULT;
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -66,12 +68,53 @@ export function makeVector(node, params, { onChange, onCommit, info, onAssetUplo
     onCommit?.();
   });
   paintField();
-  wrap.append(field);
+  // The URL box is OFF unless `sourceField: true` — same reasoning as
+  // widgets/image.js: the tile already carries preview, drop and click-to-choose,
+  // and typing a source by hand is the rarer intent.
+  if (node.sourceField === true) wrap.append(field);
 
+  // The thumbnail IS the drop target. A vector param holds a parsed document, so
+  // there is no URL an <img> could point at — the artwork is drawn inline
+  // instead, and that tile is what a file is dropped on and what opens the file
+  // picker. One element doing all three keeps the rail's 300 px from carrying a
+  // preview, a drop zone and a button that all mean the same thing.
   const drop = mountDrop("vector", {
-    params, node, onAssetUpload, onChange, onCommit, onRender: paintField,
+    params, node, onAssetUpload, onChange, onCommit, onRender: () => { paintField(); paintThumb(); },
   });
-  wrap.append(drop.el, drop.errorEl);
+  const thumb = drop.el;
+  thumb.setAttribute("data-pf-thumb", "");
 
-  return { el: wrap, sync: paintField, dispose: () => drop.dispose() };
+  // `vectorThumb` returns null for a document it cannot draw — malformed, empty,
+  // or carrying a coordinate that is not finite — rather than throwing. The tile
+  // stays either way, because it is the drop target: losing it on a bad document
+  // would strand the user with no way to replace it.
+  let thumbSeq = 0;
+  function showThumb(doc) {
+    const art = thumb.querySelector("svg");
+    if (art) art.remove();
+    const svg = doc ? vectorThumb(doc) : null;
+    thumb.classList.toggle("has-thumb", !!svg);
+    if (svg) thumb.prepend(svg);
+  }
+  function paintThumb() {
+    const own = params[node.key];
+    const seq = ++thumbSeq;
+    if (isOpaque(own)) { showThumb(own); return; }
+    showThumb(null);
+    // Nothing in the param — fall back to what the PART declares, which is where
+    // a bundled default has to live (the allow list passes only https, so a
+    // file:/dev URL cannot sit in `defaults`). Unlike an image there is nothing
+    // to point at: the document must be fetched and parsed before it can be
+    // drawn, so this lands a tick or two later, and a source that never resolves
+    // just leaves the tile empty — it stays a drop target either way.
+    const source = declaredSource?.("vector", node.key);
+    if (source === undefined) return;
+    declaredVectorDoc(source).then((doc) => { if (doc && seq === thumbSeq) showThumb(doc); });
+  }
+  paintThumb();
+
+  wrap.append(thumb, drop.errorEl);
+
+  const sync = () => { paintField(); paintThumb(); };
+  return { el: wrap, sync, dispose: () => drop.dispose() };
 }

package/src/parts/emblem.js

@@ -27,10 +27,14 @@ import plate from "./assets/plate.vector.json" with { type: "json" };
 
 export default {
   meta: { title: "Emblem", units: "mm", background: 0x15181d },
-  vectors: {
-    emblem: new URL("./assets/emblem.vector.json", import.meta.url),
+  // Function form, so the `type: "vector"` control below can drive the artwork.
+  // The bundled file is the default: dropping an SVG replaces it, clearing the
+  // control brings it back, and the part still builds with no network — which is
+  // what CI and `partforge measure` see.
+  vectors: (p) => ({
+    emblem: p.art || new URL("./assets/emblem.vector.json", import.meta.url),
     plate,
-  },
+  }),
   parameters: [
     {
       id: "plate",
@@ -45,15 +49,24 @@ export default {
       id: "art",
       title: "Artwork",
       description: "The embossed vector art. `emblem.svg` carries a filled circle and a stroked bar, so both of ingest's geometry paths are exercised.",
-      advanced: [
-        { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
-          description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
-        { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
-          description: "How far the artwork stands proud of the plate." },
+      // Converted from the legacy `advanced` array to the new shape: a section is
+      // one or the other, never both, because mixing them makes render order
+      // arbitrary (partforge lint's `mixed-section-shape`). `advanced` becomes a
+      // nested group, which renders the same way.
+      controls: [
+        { key: "art", type: "vector", label: "Source",
+          description: "Drop an SVG to replace the bundled emblem — it is converted to "
+            + "partforge-vector once, in the browser, at drop time. Clear it to go back to the bundled file." },
+        { type: "group", title: "Advanced", collapsed: "auto", controls: [
+          { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
+            description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
+          { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
+            description: "How far the artwork stands proud of the plate." },
+        ] },
       ],
     },
   ],
-  defaults: { plate_t: 3, emblem_w: 30, emboss: 1 },
+  defaults: { art: "", plate_t: 3, emblem_w: 30, emboss: 1 },
   parts: {
     plate: {
       label: "Plate",