partforge 0.113.0 → 0.114.0

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;
+    },
+  };
+}

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

@@ -7,6 +7,7 @@ import { makeSelect, makeRadio } from "./select.js";
 import { makeFont } from "./font.js";
 import { makeImage } from "./image.js";
 import { makeVector } from "./vector.js";
+import { makeCustom } from "./custom.js";
 // Side-effect imports: font-picker.js / image-picker.js call setFontPicker() /
 // setImagePicker() at module scope, so each widget's button finds a picker to
 // open. They live HERE and not in font.js/image.js because the dependency has
@@ -27,4 +28,5 @@ export const WIDGET_FACTORIES = {
   font: makeFont,
   image: makeImage,
   vector: makeVector,
+  custom: makeCustom,
 };

package/src/panel-values.js

@@ -0,0 +1,6 @@
+// Public entry for `partforge/panel-values`: the value contract of a
+// `type: "custom"` control, for hosts that persist panel settings (partforge-
+// cloud rewrites `defaults` with these). Dependency-free, DOM-free, tiny — a
+// host imports this without pulling partforge/lint's rule set into its bundle.
+export { isJsonValue, jsonValueProblem, CUSTOM_VALUE_MAX_BYTES, CUSTOM_VALUE_MAX_DEPTH } from "./framework/panel/json-value.js";
+export { readJsonLiteral, writeJsonLiteral } from "./framework/lint/source-scan.js";

package/types/index.d.ts

@@ -199,6 +199,17 @@ export interface MountOptions {
    * part cannot support is dropped, never fatal.
    */
   viewerState?: ViewerState | null;
+  /**
+   * 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.
+   */
+  panelState?: PanelState | null;
+  /**
+   * The part's own source tree as text, for custom controls' `host.file(path)`.
+   * Omit and `host.file` answers null.
+   */
+  files?: Record<string, string>;
   /**
    * A provider backing every `type: "font"` control in the part. partforge
    * ships none — without one, a font control renders as a plain URL field.
@@ -256,6 +267,57 @@ export interface ViewerState {
   cutaway: CutawayState | null;
 }
 
+/** Custom controls' transient state, keyed by the param each control owns. Plain JSON. */
+export type PanelState = Record<string, Record<string, unknown>>;
+
+export interface PanelError {
+  /** The param the failing control owns. */
+  key: string;
+  label: string;
+  phase: "create" | "update" | "event" | "dispose" | "state";
+  message: string;
+}
+
+/** What a `type: "custom"` control's `widget(host)` receives. */
+export interface CustomControlHost {
+  /** The slot to draw into, inside the rail. */
+  el: HTMLElement;
+  doc: Document;
+  /** The param this control owns. */
+  key: string;
+  /** A structured clone of the current value of `key` (default: the owned key). */
+  get(key?: string): unknown;
+  /**
+   * Replace a value. Refused (throws TypeError) for a key the control does not
+   * own or a value outside the contract (owned key: a JSON value; `keys`: a
+   * scalar). Stores a clone, schedules a rebuild, and commits unless
+   * `commit: false` — then call `commit()` when the gesture ends.
+   */
+  set(value: unknown, opts?: { key?: string; commit?: boolean }): void;
+  commit(keys?: string[]): void;
+  /** The latest `derive()` output. */
+  derived: Record<string, unknown>;
+  /** Transient JSON state that survives a remount; never a param. */
+  state: Record<string, unknown>;
+  setState(patch: Record<string, unknown>): void;
+  /** Mount built-in controls bound at `path` inside the owned value. Returns a disposer. */
+  controls(container: HTMLElement, controls: import("./part.js").PanelEntry[], opts?: { path?: string }): () => void;
+  /** Element builder; SVG tags get the SVG namespace, `on*` attrs become listeners. */
+  h(tag: string, attrs?: Record<string, unknown>, ...children: unknown[]): Element;
+  /** Parse an SVG string to its root element, or null. */
+  svg(text: string): SVGSVGElement | null;
+  /** Render a partforge-vector document to an inline `<svg>`, or null. */
+  svgFromVector(doc: unknown): SVGSVGElement | null;
+  /** Text of one of the part's own files, by path or `pfc-tree://` token, or null. */
+  file(pathOrToken: string): string | null;
+  readonly disabled: boolean;
+}
+
+export interface CustomControlInstance {
+  update?(ctx: { reason: "sync" | "derived" | "restore"; disabled: boolean }): void;
+  dispose?(): void;
+}
+
 export interface ExportPartsOptions {
   /** Sub-part names, as `listExportableParts()` reports them. */
   parts: string[];
@@ -472,6 +534,10 @@ export interface PartRuntime {
    * view-cube click, Reframe, or an animation cue).
    */
   getViewerState(): ViewerState;
+  /** Every custom control's non-empty transient state, keyed by param. Hand back as `panelState`. */
+  getPanelState(): PanelState;
+  /** What custom controls reported failing this mount, in order. */
+  getPanelErrors(): PanelError[];
   /**
    * Subscribe to WebGL context loss — i.e. the GPU or the OS gave up — so a host
    * can say so rather than showing a dead canvas. The listener takes no

package/types/panel-values.d.ts

@@ -0,0 +1,18 @@
+// partforge/panel-values — the value contract of a `type: "custom"` control.
+
+export const CUSTOM_VALUE_MAX_BYTES: 16384;
+export const CUSTOM_VALUE_MAX_DEPTH: 8;
+
+export interface JsonValueLimits { maxBytes?: number; maxDepth?: number }
+
+/** A string, boolean, finite number, or an array / plain object of those. */
+export type JsonValue = string | number | boolean | JsonValue[] | { [key: string]: JsonValue };
+
+/** Why `v` is not a JSON value within the caps (a fragment such as `is null at tiles[2].h`), or null. */
+export function jsonValueProblem(v: unknown, limits?: JsonValueLimits): string | null;
+export function isJsonValue(v: unknown, limits?: JsonValueLimits): v is JsonValue;
+
+/** Parse an array/object literal's source text (bare or quoted keys, trailing commas, JS string escapes). Null on anything else. */
+export function readJsonLiteral(text: string): { value: JsonValue } | null;
+/** Source text for a value: compact under 80 chars, else indented JSON relative to `indent`. */
+export function writeJsonLiteral(value: JsonValue, opts?: { indent?: string }): string;