partforge 0.73.1 → 0.75.0

package/src/framework/mount.js

@@ -247,6 +247,7 @@ function createCleanupStack() {
 // 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,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
@@ -835,7 +836,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       onParamChange();
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
-      : undefined);
+      : undefined,
+      { fontCatalog });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {
@@ -910,6 +912,21 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       },
     });
     if (animCtl) cleanup.defer(() => animCtl.detach());
+    // Sketch mode takes the transport bar's slot: the host floats its own
+    // composer there (partforge-cloud's sketch composer), and ink is stored in
+    // screen space against the pose it was drawn over — a playing animation
+    // under it is meaningless. STOP first, then hide: hiding first leaves a
+    // frame where an animation still drives the model beneath a bar that is
+    // already gone. Playback does not resume on the way out; "stop" is the
+    // contract, and notifyUserEdit is the same pause a user's own control edit
+    // performs.
+    if (annotateMode && animCtl) {
+      cleanup.defer(annotateMode.onModeChange(() => {
+        const on = annotateMode.isEnabled();
+        if (on) animCtl.notifyUserEdit();
+        animCtl.setHidden(on);
+      }));
+    }
 
     // Re-run the active view under the current caching setting, so toggling the
     // ?debug switch updates the readout for the same design without a param change.

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

@@ -0,0 +1,400 @@
+// The `type: "font"` picker: a takeover panel over the rail with two sliding
+// panes (families, then that family's weights) and a shared footer.
+//
+// Main-thread only — it is DOM-heavy and is NOT part of the worker graph.
+// It draws list rows in each family's own face by loading Google's name-only
+// `menuUrl` subset through a FontFace, which is why a row costs a few KB and
+// not the whole family.
+//
+// Ported from spike/font-picker.html, whose layout and interaction were settled
+// against a running build over the real 1,942-family catalog (spec §6). The
+// spike's own data path — a bundled catalog.json plus the Google CSS API — does
+// NOT come along: here the families arrive from the host's `fontCatalog` and
+// every face is a `FontFace` over a URL that catalog handed us.
+import { fontLabel, variantLabel, setFontPicker } from "./widgets/font.js";
+import { fontSourceAllowed } from "../font-source.js";
+
+const ROW_H = 44;                  // comfortable density (spec §6)
+const OVERSCAN = 4;                // rows rendered above/below the viewport
+const SEARCH_LIMIT = 200;
+const SEARCH_DEBOUNCE_MS = 120;
+const SAMPLE = "Hamburgefonstiv 0123";   // the default variant-pane sample; `preview` overrides it
+// A variants pane can hold 18 weights; auto-loading every real face for a CJK
+// family would be tens of megabytes on one click. Past this, the sample line
+// falls back to the panel font with the weight synthesized.
+const VARIANT_FACE_MAX_BYTES = 1_500_000;
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Family names come from the host and land in a `font-family` declaration, so
+// strip the two characters that could end the quoted string early.
+const faceStack = (...names) =>
+  [...names.map((n) => `"${String(n).replace(/["\\]/g, "")}"`), "var(--pf-sans)"].join(", ");
+
+const kbLabel = (bytes) => (Number.isFinite(bytes) ? `${Math.round(bytes / 1024)}K` : "");
+
+// The face a row advertises, and the one a click lands on when the user has no
+// standing weight preference. Kept separate from `pickVariant` so the row's
+// size caption does not change under the user as they audition weights.
+const listVariant = (f) =>
+  f.variants.find((v) => v.variant === "400" || v.variant === "regular") ?? f.variants[0];
+
+// At most one picker is open at a time, and the previous one has to be CLOSED
+// rather than merely detached: its `keydown` listener lives on `document`, so
+// dropping the element off the DOM leaves the handler — and the whole closure,
+// up to 200 admitted families — alive forever, one more on every re-open.
+// Only close() unregisters it, so every path that supersedes a picker goes
+// through here.
+let openPicker = null;
+
+export function openFontPicker({ node, params, allow, fontCatalog, anchor, onPicked }) {
+  // Takeover: the picker covers the rail on desktop and the single visible pane
+  // below the narrow breakpoint. One layout for both widths (spec §6).
+  const host = anchor?.closest?.(".pf-rail") ?? anchor?.parentElement ?? document.body;
+  openPicker?.close();                                  // never two at once
+
+  // ── state ───────────────────────────────────────────────────────────────
+  // The author's `preview` string, when they set one. A part lettered in digits,
+  // or in a script "Hamburgefonstiv" cannot even render, is auditioned against
+  // the wrong glyphs by the generic sample — which is the whole point of the
+  // field (spec §1). Blank or non-string falls back to the default.
+  const sampleText = typeof node.preview === "string" && node.preview.trim() ? node.preview : SAMPLE;
+  let results = [];          // what the catalog last returned…
+  let resultsQuery = "";     // …for this query
+  let query = "";            // what is in the box right now
+  let rows = [];             // what the list is showing
+  let closed = false;
+  let searchSeq = 0;
+  let debounce = null;
+  let failed = false;
+  // The value alone cannot name a live-picked face (a gstatic filename is a
+  // content hash), so start from `fontLabel` and sharpen it the moment the
+  // catalog hands us a family whose variant URL is this exact value.
+  const initial = fontLabel(params[node.key]);
+  let selFamily = initial.family;
+  let selVariant = initial.variant ?? "400";
+  let selBytes = null;
+  let openFamily = null;     // the family the variants pane is showing
+
+  const faceRequested = new Set();   // families whose menu face we have asked for
+  // …and the ones we are no longer waiting on: arrived, or definitively failed.
+  // A row is dimmed while its face is PENDING; a 404 is settled, not pending,
+  // so it goes back to full strength in the panel font rather than staying grey.
+  const faceSettled = new Set();
+  const variantFaces = new Set();    // variant URLs already loaded
+
+  // ── DOM ─────────────────────────────────────────────────────────────────
+  const picker = el("div", "picker");
+  const panes = el("div", "pk-panes");
+
+  const browse = el("div", "pk-pane");
+  browse.dataset.pane = "browse";
+  const head = el("div", "pk-head");
+  const titlebar = el("div", "pk-titlebar");
+  const closeBtn = el("button", "pk-x", "\u00d7");
+  closeBtn.type = "button";
+  closeBtn.title = "Close";
+  titlebar.append(el("b", "", node.label ?? node.key), closeBtn);
+  const search = document.createElement("input");
+  search.className = "pk-search";
+  search.type = "text";
+  search.placeholder = "Search fonts";
+  search.autocomplete = "off";
+  search.spellcheck = false;
+  head.append(titlebar, search);
+  const hint = el("div", "pk-hint");
+  hint.hidden = true;
+  const list = el("div", "pk-list");
+  const spacer = el("div", "pk-spacer");
+  const empty = el("p", "pk-empty");
+  empty.hidden = true;
+  list.append(spacer, empty);
+  browse.append(head, hint, list);
+
+  const variants = el("div", "pk-pane");
+  variants.dataset.pane = "variants";
+  const vhead = el("div", "pk-head");
+  const back = el("button", "pk-back", "\u2190 all families");
+  back.type = "button";
+  const vtitlebar = el("div", "pk-titlebar");
+  const vtitle = el("b");
+  vtitlebar.append(vtitle);
+  vhead.append(back, vtitlebar);
+  const vlist = el("div", "pk-vlist");
+  variants.append(vhead, vlist);
+
+  panes.append(browse, variants);
+
+  // The footer sits BELOW the sliding pane box, not inside it, so Done stays
+  // reachable from either pane — picking a weight never has to exit to commit.
+  const foot = el("div", "pk-foot");
+  const sel = el("span", "pk-sel");
+  const done = el("button", "pk-done", "Done");
+  done.type = "button";
+  foot.append(sel, done);
+
+  picker.append(panes, foot);
+  host.append(picker);
+  paintSel();
+  search.focus?.();
+
+  // ── faces ───────────────────────────────────────────────────────────────
+  // happy-dom (and any non-browser host) may not implement FontFace at all; a
+  // missing one must degrade to un-styled rows, never throw.
+  const canLoadFaces = () => typeof FontFace === "function" && typeof document.fonts?.add === "function";
+
+  function settle(family) {
+    faceSettled.add(family);
+    if (closed) return;
+    for (const row of spacer.children) {
+      if (row.dataset.family === family) row.classList.remove("loading");
+    }
+  }
+
+  function requestFaces(families) {
+    if (!canLoadFaces()) return;
+    for (const f of families) {
+      if (faceRequested.has(f.family)) continue;
+      faceRequested.add(f.family);
+      // The menu file is fetched, so it goes through the same allowlist as the
+      // value itself — a catalog is host-supplied, not trusted.
+      if (!f.menuUrl || !fontSourceAllowed(f.menuUrl, allow)) { settle(f.family); continue; }
+      let face;
+      try { face = new FontFace(f.family, `url(${f.menuUrl})`); } catch { settle(f.family); continue; }
+      face.load()
+        .then((loaded) => { document.fonts.add(loaded); })
+        .catch(() => { /* a family that will not load stays in the panel font */ })
+        .then(() => settle(f.family));
+    }
+  }
+
+  // The variants pane needs the REAL weights — the menu subset carries only the
+  // family name's glyphs at one weight, so it cannot show what 700 looks like.
+  // Each face is registered under `<family> <variant>` so the weights do not
+  // collide with each other or with the menu face.
+  function requestVariantFace(family, v) {
+    if (!canLoadFaces()) return;
+    if (variantFaces.has(v.url) || !fontSourceAllowed(v.url, allow)) return;
+    if (Number.isFinite(v.bytes) && v.bytes > VARIANT_FACE_MAX_BYTES) return;
+    variantFaces.add(v.url);
+    let face;
+    try { face = new FontFace(`${family} ${v.variant}`, `url(${v.url})`); } catch { return; }
+    face.load().then((loaded) => document.fonts.add(loaded)).catch(() => {});
+  }
+
+  // ── the list ────────────────────────────────────────────────────────────
+  // Reconcile by (index, family, selected) — index ALONE is wrong: after a
+  // search the same index holds a different family, and an index-keyed row
+  // keeps rendering the old one. The spike paid a screenshot to find this.
+  const rowKey = (i, f) => `${i}|${f.family}|${f.family === selFamily ? 1 : 0}`;
+
+  function rowEl(i, f) {
+    const row = el("div", "pk-row" + (f.family === selFamily ? " sel" : ""));
+    row.dataset.i = String(i);
+    row.dataset.key = rowKey(i, f);
+    row.dataset.family = f.family;
+    if (canLoadFaces() && !faceSettled.has(f.family)) row.classList.add("loading");
+    const main = el("div", "pk-main");
+    const face = el("div", "pk-face", f.family);
+    face.style.fontFamily = faceStack(f.family);
+    const n = f.variants.length;
+    main.append(face, el("div", "pk-sub", `${n} style${n === 1 ? "" : "s"} · ${f.category ?? "—"}`));
+    row.append(main, el("div", "pk-meta", kbLabel(listVariant(f)?.bytes)));
+    row.addEventListener("click", () => choose(f));
+    return row;
+  }
+
+  function render() {
+    if (closed) return;
+    spacer.style.height = `${rows.length * ROW_H}px`;
+    const top = list.scrollTop || 0;
+    const vh = list.clientHeight || 360;
+    const first = Math.max(0, Math.floor(top / ROW_H) - OVERSCAN);
+    const last = Math.min(rows.length, Math.ceil((top + vh) / ROW_H) + OVERSCAN);
+
+    const wanted = new Map();
+    for (let i = first; i < last; i++) wanted.set(i, rows[i]);
+    requestFaces([...wanted.values()]);
+
+    for (const node_ of [...spacer.children]) {
+      const i = Number(node_.dataset.i);
+      if (!wanted.has(i) || node_.dataset.key !== rowKey(i, wanted.get(i))) node_.remove();
+      else wanted.delete(i);
+    }
+    for (const [i, f] of wanted) spacer.append(rowEl(i, f));
+    for (const node_ of spacer.children) {
+      node_.style.height = `${ROW_H}px`;
+      node_.style.transform = `translateY(${Number(node_.dataset.i) * ROW_H}px)`;
+    }
+
+    empty.hidden = rows.length > 0;
+    if (!rows.length) {
+      empty.textContent = failed ? "The font catalog is unavailable."
+        : query.trim() ? `No families match "${query.trim()}".`
+        : "No families available.";
+    }
+    hint.hidden = !query.trim() || !rows.length;
+    if (!hint.hidden) hint.textContent = `${rows.length.toLocaleString()} match${rows.length === 1 ? "" : "es"}`;
+  }
+
+  // Drop variants the allowlist refuses, and drop a family left with none — the
+  // UI half of the font-source check. A family we cannot legally write must not
+  // be offered, not merely fail on click.
+  function admissible(entries) {
+    const out = [];
+    for (const f of entries ?? []) {
+      if (!f || typeof f.family !== "string" || !Array.isArray(f.variants)) continue;
+      const ok = f.variants.filter((v) => v && fontSourceAllowed(v.url, allow));
+      if (!ok.length) continue;
+      out.push({ ...f, variants: ok });
+      if (!selBytes) {
+        const hit = ok.find((v) => v.url === params[node.key]);
+        if (hit) { selFamily = f.family; selVariant = hit.variant; selBytes = hit.bytes; paintSel(); }
+      }
+    }
+    return out;
+  }
+
+  // While the user is typing ahead of the catalog, narrow what is already in
+  // hand rather than blanking the list; once the catalog has answered for this
+  // exact query, show precisely what it returned (its matching may be fuzzier
+  // than a substring test, and second-guessing it would drop real hits).
+  function recompute() {
+    // Compare TRIMMED against trimmed: runSearch stores the trimmed query, so a
+    // trailing space would otherwise never match and the list would stay stuck
+    // on the client-side narrowing instead of showing the catalog's answer.
+    const q = query.trim();
+    rows = resultsQuery === q || !q
+      ? results
+      : results.filter((f) => f.family.toLowerCase().includes(q.toLowerCase()));
+    render();
+  }
+
+  function runSearch(q) {
+    const seq = ++searchSeq;
+    Promise.resolve()
+      .then(() => fontCatalog.search(q, { limit: SEARCH_LIMIT }))
+      .then((entries) => {
+        if (closed || seq !== searchSeq) return;         // a newer search already won
+        failed = false;
+        results = admissible(entries);
+        resultsQuery = q;
+        recompute();
+      })
+      .catch(() => {
+        if (closed || seq !== searchSeq) return;
+        failed = true;
+        results = [];
+        resultsQuery = q;
+        recompute();
+      });
+  }
+
+  search.addEventListener("input", () => {
+    query = search.value;
+    list.scrollTop = 0;                                  // a new query starts at the top
+    recompute();                                         // instant, from what we hold
+    clearTimeout(debounce);
+    debounce = setTimeout(() => runSearch(query.trim()), SEARCH_DEBOUNCE_MS);
+  });
+  list.addEventListener("scroll", render);
+
+  // ── choosing ────────────────────────────────────────────────────────────
+  const pickVariant = (f) =>
+    f.variants.find((v) => v.variant === selVariant) ?? listVariant(f);
+
+  function choose(f) {
+    commit(f, pickVariant(f));
+    // 1,036 of the 1,942 catalog families ship a single face. Stepping into a
+    // one-row weight list you immediately back out of is pure friction, so for
+    // those the row click IS the selection and the list stays put (spec §6).
+    if (f.variants.length > 1) openVariants(f);
+  }
+
+  function commit(f, v) {
+    if (!v) return;
+    params[node.key] = v.url;
+    selFamily = f.family;
+    selVariant = v.variant;
+    selBytes = v.bytes;
+    onPicked?.();
+    paintSel();
+    paintVariantRows();
+    render();
+  }
+
+  function paintSel() {
+    sel.textContent = "";
+    const strong = el("b", "", selFamily);
+    const rest = ` · ${variantLabel(selVariant)}` + (selBytes ? ` · ${kbLabel(selBytes)}` : "");
+    sel.append(strong, document.createTextNode(rest));
+  }
+
+  function openVariants(f) {
+    openFamily = f;
+    vtitle.textContent = f.family;
+    vlist.textContent = "";
+    for (const v of f.variants) {
+      const b = el("button", "vrow" + (v.variant === selVariant ? " on" : ""));
+      b.type = "button";
+      b.dataset.v = v.variant;
+      const sample = el("span", "vsample", sampleText);
+      sample.style.fontFamily = faceStack(`${f.family} ${v.variant}`, f.family);
+      sample.style.fontWeight = String(v.variant).replace(/i$/, "") || "400";
+      sample.style.fontStyle = /i$/.test(String(v.variant)) ? "italic" : "normal";
+      b.append(sample, el("span", "vlabel", v.label ?? variantLabel(v.variant)));
+      // Commit WITHOUT leaving — you audition weights against the live
+      // geometry, so committing and navigating are separate actions (spec §6).
+      b.addEventListener("click", () => commit(f, v));
+      requestVariantFace(f.family, v);
+      vlist.append(b);
+    }
+    vlist.scrollTop = 0;
+    picker.classList.add("at-variants");
+  }
+
+  // Repaint which weight is current without rebuilding the list — the pane
+  // stays put while you audition, so the rows must not be torn down under you.
+  function paintVariantRows() {
+    if (openFamily?.family !== selFamily) return;
+    for (const b of vlist.children) b.classList.toggle("on", b.dataset.v === selVariant);
+  }
+
+  const leaveVariants = () => { openFamily = null; picker.classList.remove("at-variants"); render(); };
+  back.addEventListener("click", leaveVariants);
+
+  // ── closing ─────────────────────────────────────────────────────────────
+  // Named here so close() can clear the module-level handle; `close` is a
+  // hoisted function declaration, so this captures it.
+  const handle = { close };
+
+  function close() {
+    if (closed) return;                                  // idempotent
+    closed = true;
+    clearTimeout(debounce);
+    document.removeEventListener("keydown", onKey);
+    picker.remove();
+    if (openPicker === handle) openPicker = null;
+  }
+  function onKey(ev) {
+    if (ev.key !== "Escape") return;
+    ev.stopPropagation();
+    if (picker.classList.contains("at-variants")) leaveVariants();
+    else close();
+  }
+  document.addEventListener("keydown", onKey);
+  closeBtn.addEventListener("click", close);
+  done.addEventListener("click", close);
+
+  runSearch("");
+  render();
+  openPicker = handle;
+  return handle;
+}
+
+setFontPicker(openFontPicker);

package/src/framework/panel/render.js

@@ -24,7 +24,7 @@ function indexNodes(nodes, map) {
   }
 }
 
-export function buildControls(root, parameters, params, onDirty, onCommit) {
+export function buildControls(root, parameters, params, onDirty, onCommit, opts = {}) {
   const info = createInfoPopover();
   const tree = buildTree(desugar(parameters));
 
@@ -34,6 +34,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
   const syncFns = [];             // { key, sync } for every widget
   const rawSyncs = new Map();     // sectionId -> [{ key, sync }] for preset application
   const widgetSyncs = new Map();  // id -> the RAW widget sync (no markCustom)
+  const disposers = [];           // widget teardown — a font picker lives OUTSIDE root
   const nodeById = new Map();     // id -> node, for the reveal re-sync
   const lastVisible = new Map();  // id -> previous `visible`, to detect a reveal
   const lastDisabled = new Map(); // id -> previous `disabled`, to skip a no-op input pass
@@ -225,10 +226,12 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
       onChange: () => { markCustom(); onEdit(); },
       onCommit: () => commit([node.key]),
       info,
+      fontCatalog: opts.fontCatalog,
     });
     nodeEls.set(node.id, widget.el);
     if (node.key && !keyToId.has(node.key)) keyToId.set(node.key, node.id);
     widgetSyncs.set(node.id, widget.sync);
+    if (widget.dispose) disposers.push(widget.dispose);
     container.append(widget.el);
 
     // The raw sync is what a PRESET application uses — it must not mark itself
@@ -351,6 +354,8 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
       }
       return true;
     },
-    dispose: () => { info.dispose(); root.replaceChildren(); },
+    // replaceChildren() only reaches what is INSIDE root; a widget that parked
+    // DOM (or a document-level listener) elsewhere has to be told to let go.
+    dispose: () => { info.dispose(); for (const d of disposers) d(); root.replaceChildren(); },
   };
 }

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

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

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

@@ -0,0 +1,125 @@
+// The `type: "font"` control. Its VALUE is a font source string — the same
+// grammar `PartDefinition.fonts` already accepts — so everything downstream
+// (presets, undo, the params hash, `when`) works with no special case.
+//
+// Two renderings. With a host-supplied `fontCatalog` it is a button showing the
+// current face IN that face, opening the picker. Without one it degrades to a
+// URL text field, so a standalone partforge app (which ships no catalog) still
+// exposes the parameter.
+import { attachInfo } from "../info.js";
+import { FONT_ALLOW_DEFAULT, fontSourceAllowed } from "../../font-source.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+const WEIGHTS = { 100: "Thin", 200: "ExtraLight", 300: "Light", 400: "Regular", 500: "Medium",
+                  600: "SemiBold", 700: "Bold", 800: "ExtraBold", 900: "Black" };
+export const variantLabel = (v) => {
+  if (!v) return "Regular";
+  const w = String(v).replace(/i$/, ""), italic = /i$/.test(String(v));
+  return `${WEIGHTS[w] ?? w}${italic ? " Italic" : ""}`;
+};
+
+// A source string → something human. Cloud's fetch_web_font stores files as
+// `<family-slug>[-<variant>].ttf`, so the filename round-trips the label for
+// free on the vendored path; a bare URL falls back to its filename stem.
+export function fontLabel(source) {
+  if (typeof source !== "string" || !source) return { family: "—", variant: null };
+  let path = source;
+  try { path = new URL(source).pathname; } catch { /* not a URL — use the raw string */ }
+  const file = path.split("/").filter(Boolean).pop() ?? source;
+  const stem = file.replace(/\.(ttf|otf)$/i, "");
+  const m = /^(.*)-(\d{3}i?|italic)$/i.exec(stem);
+  const slug = m ? m[1] : stem;
+  const family = slug.split("-").filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ") || "—";
+  return { family, variant: m ? m[2] : null };
+}
+
+export function makeFont(node, params, { onChange, onCommit, info, fontCatalog } = {}) {
+  const allow = Array.isArray(node.allow) && node.allow.length ? node.allow : FONT_ALLOW_DEFAULT;
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label ?? node.key);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+
+  if (!fontCatalog) {
+    // Degraded path: a URL field. Unlike `text`, it does NOT write on every
+    // keystroke — a half-typed URL is a guaranteed failed fetch, and the
+    // rebuild loop would chase every one of them.
+    const field = document.createElement("input");
+    field.type = "text";
+    field.className = "text-input";
+    field.value = String(params[node.key] ?? "");
+    field.addEventListener("change", () => {
+      if (!fontSourceAllowed(field.value, allow)) { field.classList.add("warn"); return; }
+      field.classList.remove("warn");
+      params[node.key] = field.value;
+      onChange?.();
+      onCommit?.();
+    });
+    wrap.append(field);
+    return { el: wrap, sync: () => { field.value = String(params[node.key] ?? ""); field.classList.remove("warn"); } };
+  }
+
+  const btn = el("button", "font-btn");
+  btn.type = "button";
+  const fname = el("span", "fname");
+  const fvar = el("span", "fvar");
+  btn.append(fname, fvar);
+  btn.insertAdjacentHTML("beforeend",
+    '<svg class="caret" width="8" height="7" viewBox="0 0 8 7" aria-hidden="true"><polygon points="0,0 8,0 4,7" fill="currentColor"/></svg>');
+  wrap.append(btn);
+
+  // The value alone cannot name a live-picked face: a gstatic filename is a
+  // content hash. Ask the catalog first (it holds the reverse lookup), and fall
+  // back to the filename — which is right for a vendored `<family>-<variant>.ttf`
+  // and merely ugly for a hash. `describe` is optional and may be async, so the
+  // label is painted twice: filename immediately, catalog answer when it lands.
+  let paintSeq = 0;
+  const paint = () => {
+    const src = params[node.key];
+    const seq = ++paintSeq;
+    const show = ({ family, variant }) => {
+      if (seq !== paintSeq) return;                  // a newer paint already won
+      fname.textContent = family;
+      fvar.textContent = variantLabel(variant);
+      fname.style.fontFamily = `"${family}", var(--pf-sans)`;
+    };
+    show(fontLabel(src));
+    if (typeof fontCatalog.describe !== "function") return;
+    Promise.resolve()
+      .then(() => fontCatalog.describe(src))
+      .then((d) => { if (d?.family) show(d); })
+      .catch(() => { /* a failed lookup keeps the filename label */ });
+  };
+  paint();
+
+  // The picker registers itself through setFontPicker (see below); with no
+  // picker in the bundle the button is inert rather than broken.
+  //
+  // The handle is kept because the picker is a TAKEOVER: it appends itself to
+  // the rail, outside the panel root, so tearing the panel down does not take it
+  // with it. Without dispose() the element — and the `document` keydown listener
+  // that only close() unhooks — would outlive the panel holding a stale `params`.
+  let picker = null;
+  btn.addEventListener("click", () => {
+    picker = openFontPicker?.({ node, params, allow, fontCatalog, anchor: wrap, onPicked: () => { paint(); onChange?.(); onCommit?.(); } }) ?? null;
+  });
+
+  return { el: wrap, sync: paint, dispose: () => { picker?.close(); picker = null; } };
+}
+
+// Assigned by font-picker.js, which widgets/index.js imports for the side
+// effect. Kept
+// as a mutable binding rather than a static import so this file stays usable —
+// and testable — without dragging the whole picker in.
+export let openFontPicker = null;
+export const setFontPicker = (fn) => { openFontPicker = fn; };

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

@@ -4,6 +4,13 @@ import { makeNumeric } from "./numeric.js";
 import { makeText } from "./text.js";
 import { makeCheckbox } from "./checkbox.js";
 import { makeSelect, makeRadio } from "./select.js";
+import { makeFont } from "./font.js";
+// Side-effect import: font-picker.js calls setFontPicker() at module scope, so
+// the font widget's button finds a picker to open. It lives HERE and not in
+// font.js because the dependency has to run picker → widget and never back —
+// font.js must stay importable (and testable) without dragging the whole
+// DOM-heavy picker in. See the note at the bottom of font.js.
+import "../font-picker.js";
 
 export const WIDGET_FACTORIES = {
   slider: makeNumeric,
@@ -13,4 +20,5 @@ export const WIDGET_FACTORIES = {
   checkbox: makeCheckbox,
   select: makeSelect,
   radio: makeRadio,
+  font: makeFont,
 };

package/src/framework/part-model.js

@@ -32,8 +32,16 @@ export function exportSubParts(part, view, params) {
 
 // Resolve a part's effective params + derived values for a build: the user's params
 // layered over the part defaults, and derive() run once over the result.
-export function resolveParams(part, params) {
+//
+// `sanitize(p)` is an optional hook that may rewrite the layered params IN PLACE —
+// the seam a caller uses to refuse an untrusted value before it means anything.
+// It runs BEFORE resolveDerived deliberately: derive() must see exactly the params
+// build() will see, or a refused value still reaches the geometry through `d`.
+// A hook rather than a second copy of this function in the caller, so "resolve a
+// part's params" keeps one definition.
+export function resolveParams(part, params, sanitize) {
   const p = { ...part.defaults, ...params };
+  sanitize?.(p);
   return { p, d: resolveDerived(part, p) };
 }