partforge 0.112.0 → 0.114.0

package/src/framework/mount.js

@@ -63,7 +63,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -101,6 +101,14 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       projection: viewer.getProjection?.() ?? "perspective",
       cutaway: viewer.getCutawayState?.() ?? null,
     }),
+    // Every custom control's transient state (selection, a scroll position),
+    // keyed by param, as plain JSON — the panel's twin of getViewerState. Hand
+    // it back as mount()'s `panelState` and a remount comes up with the same
+    // tile selected. {} when the mount resolved no panel.
+    getPanelState: getPanelState ?? (() => ({})),
+    // What custom controls reported failing this mount ({key, label, phase,
+    // message}), for a host to relay to whoever authored the part.
+    getPanelErrors: getPanelErrors ?? (() => []),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
@@ -305,6 +313,13 @@ function createCleanupStack() {
 //                                         // first mount — the viewer then restores its own persisted
 //                                         // camera as before. Restore is best-effort per field: a pose
 //                                         // this part cannot support is dropped, never fatal.
+// panelState: PanelState                 // a previous mount's runtime.getPanelState(): the transient
+//                                         // state of the part's custom controls (a selected tile), keyed
+//                                         // by param. Same remount story as viewerState; omit on a first
+//                                         // mount. Never persisted by partforge.
+// files: { [path]: string }              // the part's own source tree as text, for custom controls'
+//                                         // host.file(path) — an SVG or a vector document that lives
+//                                         // beside the code. Omit and host.file answers null.
 // annotateSend: "viewbar" | "host"       // who owns the Send affordance. "viewbar" (default) puts
 //                                         // Send in the sketch toolbar alongside the other tools.
 //                                         // "host" drops it: the host draws its own send control —
@@ -331,6 +346,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
                               imageCatalog,
                               onAssetUpload,
                               viewerState,
+                              files, panelState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
@@ -1017,7 +1033,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       // 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) });
+        declaredSource: declaredSourceLookup(part, params),
+        files, panelState });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {
@@ -1194,6 +1211,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       getView: view,                         // () => tabsCtl.current()
       setView: (name) => tabsCtl.select(name),
       captureView,
+      getPanelState: () => panelRef?.getState() ?? {},
+      getPanelErrors: () => panelRef?.errors() ?? [],
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),

package/src/framework/panel/author.js

@@ -44,6 +44,11 @@ function authoredControl(c) {
     allow: c.allow,
     preview: c.preview,
     sourceField: c.sourceField,
+    // Custom controls (type: "custom"): the author's widget function and the
+    // extra scalar keys it may write. Both are on this allow-list for the same
+    // reason `allow` is (see above) — a field missing here is silently dropped.
+    widget: c.widget,
+    keys: c.keys,
     preserveOn: false,
     marksCustom: true,
   };

package/src/framework/panel/json-value.js

@@ -0,0 +1,55 @@
+//
+// The ONE predicate for the value a `type: "custom"` control may own. The panel
+// (host.set, panel state), lint (custom-default-not-json) and partforge-cloud's
+// persistence (through the `partforge/panel-values` export) all ask this module,
+// so "the linter accepts it" and "the save can write it" cannot drift apart.
+//
+// Imports nothing: it sits inside partforge/lint's pure closure
+// (test/lint-purity.test.js) and inside the sandbox iframe.
+
+export const CUSTOM_VALUE_MAX_BYTES = 16384;
+export const CUSTOM_VALUE_MAX_DEPTH = 8;
+
+// Keys a JSON value may never carry: on a plain object each of these reaches
+// Object.prototype, so a value that round-trips through JSON.parse and a
+// plain-object assignment could change what `params.x.constructor` means.
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+const at = (path) => (path ? ` at ${path}` : "");
+
+function shapeProblem(v, depth, maxDepth, path) {
+  if (v === null) return `is null${at(path)}`;
+  const t = typeof v;
+  if (t === "number") return Number.isFinite(v) ? null : `is a non-finite number${at(path)}`;
+  if (t === "string" || t === "boolean") return null;
+  if (t !== "object") return `is a ${t}${at(path)}`;
+  if (depth >= maxDepth) return `nests deeper than ${maxDepth} levels${at(path)}`;
+  if (Array.isArray(v)) {
+    for (let i = 0; i < v.length; i++) {
+      const p = shapeProblem(v[i], depth + 1, maxDepth, `${path}[${i}]`);
+      if (p) return p;
+    }
+    return null;
+  }
+  const proto = Object.getPrototypeOf(v);
+  if (proto !== Object.prototype && proto !== null) return `is not a plain object${at(path)}`;
+  for (const k of Object.keys(v)) {
+    if (FORBIDDEN_KEYS.has(k)) return `uses the forbidden key "${k}"${at(path)}`;
+    const p = shapeProblem(v[k], depth + 1, maxDepth, path ? `${path}.${k}` : k);
+    if (p) return p;
+  }
+  return null;
+}
+
+// Why `v` is not a JSON value — a sentence fragment that reads after the
+// value's name ("`defaults.tiles` is null at tiles[2].h") — or null when it is.
+export function jsonValueProblem(v, { maxBytes = CUSTOM_VALUE_MAX_BYTES, maxDepth = CUSTOM_VALUE_MAX_DEPTH } = {}) {
+  const shape = shapeProblem(v, 0, maxDepth, "");
+  if (shape) return shape;
+  if (maxBytes === Infinity) return null;
+  const bytes = new TextEncoder().encode(JSON.stringify(v)).length;
+  if (bytes > maxBytes) return `is ${bytes} bytes serialized; the cap is ${maxBytes}`;
+  return null;
+}
+
+export const isJsonValue = (v, opts) => jsonValueProblem(v, opts) === null;

package/src/framework/panel/render.js

@@ -7,6 +7,10 @@ import { computeState } from "./panel-state.js";
 import { WIDGET_FACTORIES } from "./widgets/index.js";
 import { makeReadout } from "./widgets/readout.js";
 import { createInfoPopover, attachInfo } from "./info.js";
+import { isJsonValue } from "./json-value.js";
+
+// The budget every custom control's transient state shares (getState below).
+export const PANEL_STATE_MAX_BYTES = 65536;
 
 function el(tag, className, text) {
   const node = document.createElement(tag);
@@ -48,6 +52,22 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
   indexNodes(tree, nodeById);
   let relevant = null;
 
+  const panelErrors = [];         // {key, label, phase, message} from custom controls
+  const customWidgets = new Map(); // param key -> { label, getState } for custom controls
+  const reportedStateDrops = new Set(); // keys already recorded as a dropped getState() — getState may be called many times
+  // What a custom control's host reaches back into the panel for: the part's
+  // own files (host.file), the state a previous mount left (host.state), the
+  // error sink, and the sub-panel builder — a re-entry into buildControls with
+  // a scoped params view and no section header (opts.bare, Task 5).
+  const customCtx = {
+    files: opts.files ?? null,
+    panelState: opts.panelState ?? null,
+    onError: (e) => { panelErrors.push(e); opts.onPanelError?.(e); },
+    buildSubPanel: (container, controls, scoped, onSubDirty, onSubCommit) =>
+      buildControls(container, [{ controls }], scoped, onSubDirty, onSubCommit,
+        { ...opts, bare: true, panelState: null, onPanelError: customCtx.onError }),
+  };
+
   // Re-apply state after any change that could flip a condition. This is what
   // reproduces the legacy feature behavior generically: ticking a feature's
   // checkbox now simply makes its group's condition true. It also re-syncs any
@@ -224,67 +244,87 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
     };
     const widget = factory(node, params, {
       onChange: () => { markCustom(); onEdit(); },
-      onCommit: () => commit([node.key]),
+      // A factory may name the keys it committed (custom controls own several);
+      // the built-ins call onCommit() bare and get their own key, as before.
+      onCommit: (keys) => commit(Array.isArray(keys) && keys.length ? keys : [node.key]),
       info,
       fontCatalog: opts.fontCatalog,
       imageCatalog: opts.imageCatalog,
       onAssetUpload: opts.onAssetUpload,
       declaredSource: opts.declaredSource,
+      custom: customCtx,
     });
     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);
+    // A custom control reads derive() output like a readout does, and keeps
+    // transient state the host may carry across a remount.
+    if (typeof widget.onDerived === "function") displayUpdates.set(node.id, widget.onDerived);
+    if (typeof widget.getState === "function" && node.key) {
+      customWidgets.set(node.key, { label: node.label ?? node.key, getState: widget.getState });
+    }
     container.append(widget.el);
 
     // The raw sync is what a PRESET application uses — it must not mark itself
     // Custom (controls.test.js:366). The registered sync is what an external
     // syncValues() uses, and for a preset-section control it does drop the
     // picker to Custom (controls.test.js:350), because a programmatic edit
-    // diverges from the preset exactly as a user edit does.
+    // diverges from the preset exactly as a user edit does. A widget that owns
+    // several keys (custom's `keys`) registers under each of them.
     if (sectionCtx) rawSyncs.get(sectionCtx.id).push({ key: node.key, sync: widget.sync });
-    syncFns.push({
-      key: node.key,
-      sync: () => { widget.sync(); markCustom(); },
-    });
+    const ownedKeys = Array.isArray(widget.keys) && widget.keys.length ? widget.keys : [node.key];
+    for (const key of ownedKeys) {
+      syncFns.push({ key, sync: () => { widget.sync(); markCustom(); } });
+    }
   }
 
   for (const section of tree) {
     groupIds.add(section.id);
     const secEl = el("div", "section");
     nodeEls.set(section.id, secEl);
-
-    const header = el("div", "sec-header");
-    const title = el("button", "sec-title");
-    title.type = "button";
-    // The chev span carries NO text — its glyph comes from CSS (::before) —
-    // because sectionByTitle-style lookups match `.sec-title` by exact
-    // textContent === title (controls.test.js:210), and a text chevron here
-    // would break that match.
-    title.append(el("span", "sec-name", section.title ?? ""));
-    header.append(title);
-    // Row order: title (flex:1), then ⓘ, then the chevron on the far right.
-    // The ⓘ is a SIBLING of the button, never a child: attachInfo appends a
-    // <button>, and a button nested in a button is invalid HTML that never
-    // receives clicks.
-    attachInfo(header, section.description, info);
-    header.append(el("span", "chev"));
-    secEl.append(header);
-
     const body = el("div", "sec-body");
-    body.id = `pf-sec-${section.id.replaceAll("/", "-")}`;
-    title.setAttribute("aria-controls", body.id);
-    secEl.append(body);
 
-    // The whole header row toggles: the title button's own click bubbles up
-    // here, the chevron and the empty row space hit it directly, and the ⓘ
-    // stops propagation in attachInfo. aria state stays on the title button.
-    header.addEventListener("click", () => {
-      const nowHidden = body.classList.toggle("hidden");
-      title.setAttribute("aria-expanded", String(!nowHidden));
-      secEl.classList.toggle("collapsed", nowHidden);
-    });
-    disclosures.set(section.id, { body, button: title, el: secEl });
+    if (opts.bare) {
+      // A sub-panel inside a custom control (host.controls): controls only,
+      // no header row and no disclosure — the widget owns the framing, so
+      // there is no aria-controls to point at the body and it gets no id
+      // (a mounted sub-panel would otherwise collide with the outer panel's
+      // own pf-sec-<id>, or with another sub-panel's, since ids are not
+      // scoped to a mount).
+      secEl.classList.add("bare");
+      secEl.append(body);
+    } else {
+      body.id = `pf-sec-${section.id.replaceAll("/", "-")}`;
+      const header = el("div", "sec-header");
+      const title = el("button", "sec-title");
+      title.type = "button";
+      // The chev span carries NO text — its glyph comes from CSS (::before) —
+      // because sectionByTitle-style lookups match `.sec-title` by exact
+      // textContent === title (controls.test.js:210), and a text chevron here
+      // would break that match.
+      title.append(el("span", "sec-name", section.title ?? ""));
+      header.append(title);
+      // Row order: title (flex:1), then ⓘ, then the chevron on the far right.
+      // The ⓘ is a SIBLING of the button, never a child: attachInfo appends a
+      // <button>, and a button nested in a button is invalid HTML that never
+      // receives clicks.
+      attachInfo(header, section.description, info);
+      header.append(el("span", "chev"));
+      secEl.append(header);
+      title.setAttribute("aria-controls", body.id);
+      secEl.append(body);
+
+      // The whole header row toggles: the title button's own click bubbles up
+      // here, the chevron and the empty row space hit it directly, and the ⓘ
+      // stops propagation in attachInfo. aria state stays on the title button.
+      header.addEventListener("click", () => {
+        const nowHidden = body.classList.toggle("hidden");
+        title.setAttribute("aria-expanded", String(!nowHidden));
+        secEl.classList.toggle("collapsed", nowHidden);
+      });
+      disclosures.set(section.id, { body, button: title, el: secEl });
+    }
 
     // `preset` is filled in when a preset node renders. Controls read it late, so
     // one appearing after them in the children array still works.
@@ -357,6 +397,49 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
       }
       return true;
     },
+    // What custom controls reported failing this mount, in order. A host that
+    // remounts per edit (partforge-cloud) reads this after mount and hands it
+    // to the agent beside the build's own warnings.
+    errors: () => panelErrors.map((e) => ({ ...e })),
+    // Every custom control's non-empty transient state, keyed by param, as
+    // plain JSON — hand it back as mount({ panelState }) so a selection survives
+    // the remount an edit performs. One shared budget: a state that would push
+    // the total past it is dropped and recorded (phase "state") rather than
+    // silently lost.
+    getState: () => {
+      const out = {};
+      let budget = PANEL_STATE_MAX_BYTES;
+      for (const [key, w] of customWidgets) {
+        try {
+          const state = w.getState();
+          if (!state || typeof state !== "object" || Object.keys(state).length === 0) continue;
+          if (!isJsonValue(state, { maxBytes: Infinity })) {
+            if (!reportedStateDrops.has(key)) {
+              reportedStateDrops.add(key);
+              customCtx.onError({ key, label: w.label, phase: "state", message: "panel state is not a JSON value; dropped" });
+            }
+            continue;
+          }
+          const size = new TextEncoder().encode(JSON.stringify(state)).length;
+          if (size > budget) {
+            if (!reportedStateDrops.has(key)) {
+              reportedStateDrops.add(key);
+              customCtx.onError({ key, label: w.label, phase: "state", message: `panel state (${size} bytes) exceeds the ${PANEL_STATE_MAX_BYTES}-byte budget; dropped` });
+            }
+            continue;
+          }
+          budget -= size;
+          out[key] = structuredClone(state);
+        } catch (e) {
+          if (!reportedStateDrops.has(key)) {
+            reportedStateDrops.add(key);
+            const message = (e && typeof e.message === "string" && e.message) || String(e);
+            customCtx.onError({ key, label: w.label, phase: "state", message: `panel state could not be read: ${message}` });
+          }
+        }
+      }
+      return out;
+    },
     // 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/scoped-params.js

@@ -0,0 +1,52 @@
+// A params-shaped view INTO a custom control's owned value, so the built-in
+// control factories — which read and write `params[node.key]` and nothing
+// else — can edit `tiles[3].height` without knowing they are inside a JSON
+// value. Every read clones the owned value (read()) and every write hands a
+// whole new value back (write(next)): the stored value is never mutated in
+// place, which is what keeps the worker's cache keys and the relevance
+// recorder honest.
+//
+// `path` is dotted from the owned value's root: "" (the root itself), "3"
+// (the fourth array element), "walls.north". A write whose parent does not
+// exist is refused and reported through onError, never thrown — a throwing
+// params write inside a slider's input handler would take the panel down.
+export function scopedParams({ read, write, path = "", onError }) {
+  const segs = path === "" ? [] : String(path).split(".");
+  const parentOf = (root) => {
+    let cur = root;
+    for (const s of segs) {
+      if (cur === null || typeof cur !== "object") return null;
+      cur = cur[s];
+    }
+    return cur !== null && typeof cur === "object" ? cur : null;
+  };
+  return new Proxy({}, {
+    get(_, key) {
+      if (typeof key !== "string") return undefined;
+      const p = parentOf(read());
+      return p ? p[key] : undefined;
+    },
+    has(_, key) {
+      const p = parentOf(read());
+      return typeof key === "string" && !!p && Object.hasOwn(p, key);
+    },
+    ownKeys() {
+      const p = parentOf(read());
+      return p ? Object.keys(p) : [];
+    },
+    getOwnPropertyDescriptor(_, key) {
+      const p = parentOf(read());
+      if (!p || typeof key !== "string" || !Object.hasOwn(p, key)) return undefined;
+      return { value: p[key], enumerable: true, configurable: true, writable: true };
+    },
+    set(_, key, value) {
+      if (typeof key !== "string") return false;
+      const root = read();
+      const p = parentOf(root);
+      if (!p) { onError?.(`no value at path "${path}" to write "${key}" into`); return true; }
+      p[key] = value;
+      write(root);
+      return true;
+    },
+  });
+}

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

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

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

@@ -0,0 +1,253 @@
+// A part-authored widget in the rail (type: "custom"). The author's `widget`
+// function draws whatever it wants into the slot — DOM, SVG, canvas — through
+// a small host object; the framework's job is to make that function safe to
+// run (a throw lands on a card, never on the panel), to route its writes
+// through the ordinary dirty/commit chain, and to keep its transient state
+// across the remount every edit performs (getState/panelState).
+//
+// The widget runs in the panel's own realm: mount() receives the part module
+// directly, so `node.widget` is the author's real function, never a clone.
+// It must never reach the geometry worker — it does not: only `params` cross.
+import { attachInfo } from "../info.js";
+import { vectorThumb } from "./vector-thumb.js";
+import { isJsonValue, jsonValueProblem } from "../json-value.js";
+import { scopedParams } from "../scoped-params.js";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const SVG_TAGS = new Set([
+  "svg", "g", "path", "polygon", "polyline", "circle", "ellipse", "rect", "line", "text", "tspan",
+  "use", "defs", "clipPath", "mask", "pattern", "marker", "symbol", "image", "title", "desc",
+  "foreignObject", "linearGradient", "radialGradient", "stop",
+]);
+// `pfc-tree://<path>?v=<stamp>` — the token a `vector` control writes into a
+// param when the artwork lives as a file in the part (partforge-cloud's
+// treeTokens.js). The stamp is content-addressed and irrelevant here: the
+// files map is the tree as of THIS mount.
+const TREE_TOKEN_RE = /^pfc-tree:\/\/([^?#]+)(?:[?#].*)?$/i;
+
+const isScalar = (v) => typeof v === "string" || typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v));
+const errorText = (e) => (e && typeof e.message === "string" && e.message) || String(e);
+const cloneValue = (v) => (v !== null && typeof v === "object" ? structuredClone(v) : v);
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Drop any `type: "custom"` entry (recursively through groups) from a
+// sub-control list: a widget inside a widget is refused, one level only.
+function stripNested(controls, report) {
+  const out = [];
+  for (const c of Array.isArray(controls) ? controls : []) {
+    if (!c) continue;
+    if (c.type === "custom") { report(typeof c.key === "string" ? c.key : "?"); continue; }
+    if (c.type === "group") { out.push({ ...c, controls: stripNested(c.controls, report) }); continue; }
+    out.push(c);
+  }
+  return out;
+}
+
+export function makeCustom(node, params, { onChange, onCommit, info, custom = {} } = {}) {
+  const { files = null, panelState = null, onError, buildSubPanel } = custom;
+  const label = node.label ?? node.key;
+  const wrap = el("div", "pf-custom");
+  if (node.label) {
+    const row = el("div", "row");
+    const lbl = el("label", "", node.label);
+    attachInfo(lbl, node.description, info);
+    row.append(lbl);
+    wrap.append(row);
+  }
+  const slot = el("div", "pf-custom-slot");
+  wrap.append(slot);
+
+  const ownedKeys = [node.key, ...(Array.isArray(node.keys) ? node.keys.filter((k) => typeof k === "string") : [])];
+  const pending = new Set();    // keys set since the last commit
+  const subPanels = new Set();  // disposers of open host.controls panels
+  let instance = null;
+  let retired = false;
+  let lastDerived = "{}";
+
+  const report = (phase, message) => onError?.({ key: node.key, label, phase, message });
+
+  // A throw anywhere in widget code: record it, retire the widget for this
+  // mount, tear down its sub-panels, and put the card in the slot. Every other
+  // control keeps working; the geometry keeps rendering.
+  const fail = (phase, e) => {
+    if (retired) return;
+    retired = true;
+    const message = errorText(e);
+    report(phase, message);
+    for (const d of [...subPanels]) { try { d(); } catch { /* already failing */ } }
+    subPanels.clear();
+    const card = el("div", "pf-custom-error");
+    card.append(el("div", "pf-custom-error-title", `${label}: custom control failed`));
+    card.append(el("div", "pf-custom-error-message", message));
+    slot.replaceChildren(card);
+  };
+  const guarded = (phase, fn) => {
+    if (retired) return undefined;
+    try { return fn(); } catch (e) { fail(phase, e); return undefined; }
+  };
+
+  const restoredState = panelState && typeof panelState === "object" && Object.hasOwn(panelState, node.key)
+    && panelState[node.key] && typeof panelState[node.key] === "object" && !Array.isArray(panelState[node.key])
+    && isJsonValue(panelState[node.key], { maxBytes: Infinity })
+    ? structuredClone(panelState[node.key])
+    : null;
+
+  const host = {
+    el: slot,
+    doc: slot.ownerDocument,
+    key: node.key,
+    state: restoredState ?? {},
+    derived: {},
+    get disabled() { return wrap.classList.contains("disabled"); },
+
+    get(key = node.key) { return cloneValue(params[key]); },
+
+    set(value, { key = node.key, commit = true } = {}) {
+      if (retired) return;
+      if (!ownedKeys.includes(key)) {
+        throw new TypeError(`custom control "${node.key}" may not write "${key}" — list it in \`keys\``);
+      }
+      if (key === node.key) {
+        const problem = jsonValueProblem(value);
+        if (problem) throw new TypeError(`value for "${key}" ${problem}`);
+      } else if (!isScalar(value)) {
+        throw new TypeError(`value for "${key}" must be a finite number, string or boolean`);
+      }
+      params[key] = cloneValue(value);
+      pending.add(key);
+      onChange?.();
+      if (commit) host.commit([key]);
+    },
+
+    commit(keys = [node.key]) {
+      if (retired) return;
+      const changed = keys.filter((k) => pending.has(k));
+      if (!changed.length) return;
+      for (const k of changed) pending.delete(k);
+      onCommit?.(changed);
+    },
+
+    setState(patch) { if (retired) return; Object.assign(host.state, patch); },
+
+    // Element builder: SVG tags get the SVG namespace, `on<event>` attrs
+    // become listeners (wrapped: a throw retires the widget), everything else
+    // is set verbatim; `true` → a bare attribute, null/undefined/false → omitted.
+    h(tag, attrs = {}, ...children) {
+      const doc = slot.ownerDocument;
+      const elm = SVG_TAGS.has(tag) ? doc.createElementNS(SVG_NS, tag) : doc.createElement(tag);
+      for (const [name, v] of Object.entries(attrs ?? {})) {
+        if (v === null || v === undefined || v === false) continue;
+        if (name.startsWith("on") && typeof v === "function") {
+          elm.addEventListener(name.slice(2).toLowerCase(), (ev) => guarded("event", () => v(ev)));
+        } else {
+          elm.setAttribute(name, v === true ? "" : String(v));
+        }
+      }
+      const append = (c) => {
+        if (c === null || c === undefined || c === false) return;
+        if (Array.isArray(c)) { c.forEach(append); return; }
+        elm.append(typeof c === "object" ? c : doc.createTextNode(String(c)));
+      };
+      children.forEach(append);
+      return elm;
+    },
+
+    // An SVG string → its root element (HTML parsing puts `<svg>` in the SVG
+    // namespace), or null. No sanitizer: this is the same author's code that
+    // already runs here.
+    svg(text) {
+      if (typeof text !== "string") return null;
+      const tpl = slot.ownerDocument.createElement("template");
+      tpl.innerHTML = text.trim();
+      const root = tpl.content.firstElementChild;
+      return root && root.tagName.toLowerCase() === "svg" ? root : null;
+    },
+
+    svgFromVector: (doc) => vectorThumb(doc),
+
+    // The text of one of the part's own files, by path or pfc-tree:// token.
+    file(pathOrToken) {
+      if (!files || typeof pathOrToken !== "string") return null;
+      const m = TREE_TOKEN_RE.exec(pathOrToken);
+      const path = (m ? m[1] : pathOrToken).replace(/^\.\//, "");
+      return Object.hasOwn(files, path) && typeof files[path] === "string" ? files[path] : null;
+    },
+
+    // Built-in controls bound INSIDE the owned value (scoped-params.js). One
+    // level: a custom control in the list is dropped and reported.
+    controls(container, controls, { path = "" } = {}) {
+      if (!buildSubPanel || retired) return () => {};
+      const stripped = stripNested(controls, (key) =>
+        report("create", `custom control "${key}" cannot be nested inside "${node.key}"`));
+      const scoped = scopedParams({
+        read: () => host.get(),
+        // A sub-control write can push the owned value past the JSON cap —
+        // that is the value contract refusing one edit, not widget code
+        // failing, so it is reported and swallowed rather than left to throw
+        // out of the built-in factory's own (unguarded) input handler.
+        write: (next) => {
+          try { host.set(next, { commit: false }); } catch (e) { report("event", errorText(e)); }
+        },
+        path,
+        onError: (message) => report("event", message),
+      });
+      const sub = buildSubPanel(container, stripped, scoped, () => {}, () => host.commit());
+      const dispose = () => { subPanels.delete(dispose); sub.dispose(); };
+      subPanels.add(dispose);
+      return dispose;
+    },
+  };
+
+  guarded("create", () => {
+    if (typeof node.widget !== "function") throw new TypeError("`widget` is not a function");
+    const r = node.widget(host);
+    instance = r && typeof r === "object" ? r : null;
+  });
+
+  const update = (reason) => guarded("update", () => instance?.update?.({ reason, disabled: host.disabled }));
+
+  // Restoring panel state is not part of creation: a throw here is a bad
+  // `update`, not a bad `create` — the widget did construct successfully.
+  if (restoredState && !retired) update("restore");
+
+  return {
+    el: wrap,
+    keys: ownedKeys,
+    sync: () => update("sync"),
+    onDerived: (derived) => {
+      const next = derived ?? {};
+      host.derived = next;
+      let s;
+      try {
+        s = JSON.stringify(next);
+      } catch {
+        // Not everything is stringifiable (a cycle, a BigInt). Treat that as
+        // "changed" rather than let it escape into panel.refresh().
+        update("derived");
+        return;
+      }
+      if (s === lastDerived) return;
+      lastDerived = s;
+      update("derived");
+    },
+    getState: () => host.state,
+    dispose: () => {
+      for (const d of [...subPanels]) { try { d(); } catch { /* disposing anyway */ } }
+      subPanels.clear();
+      // Attempted even when retired: a widget that already failed once (a
+      // throwing listener, say) still owns resources — timers, observers,
+      // an open sub-panel's DOM — that its own dispose() is the only code
+      // that knows how to release.
+      try { instance?.dispose?.(); } catch (e) { report("dispose", errorText(e)); }
+      // A disposed panel's host must stop accepting writes: host.set/commit
+      // are silent no-ops once retired, same as after a widget's own throw.
+      retired = true;
+    },
+  };
+}