partforge 0.113.0 → 0.114.0

package/docs/AUTHORING-PARTS.md

@@ -745,6 +745,7 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"font"` | a typeface picker with a catalog, else a drop target | `allow`, `preview`, `sourceField` |
 | `"image"` | an image picker with a catalog, else a drop target showing the artwork | `allow`, `sourceField` |
 | `"vector"` | a drop target showing the artwork — no catalog exists | `sourceField` |
+| `"custom"` | a widget the part draws itself — see "Custom controls" below | `widget`, `keys` |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and may sit **outside `[min, max]`**:
@@ -954,6 +955,132 @@ pickers in one section both need to show divergence, give each its own section.
 case per preset name (so every preset gets measured), and a repeated name throws
 there. `duplicate-preset-name` catches it at lint time instead.
 
+### Custom controls
+
+A `type: "custom"` control renders a widget the part draws itself — a clickable hex
+grid, an organizer whose walls toggle on click, a picture of the part's own outline
+with hot regions. Reach for it when the user configures **many similar things
+individually**, or makes a **spatial choice** no slider or select can express.
+Never for a value an existing control already covers: a slider is still a slider.
+
+```js
+// part.js
+import { tilePicker } from "./tile-picker.js";
+
+export default {
+  defaults: {
+    tileSize: 20,
+    tiles: [{ q: 0, r: 0, height: 10 }, { q: 1, r: 0, height: 14 }],
+  },
+  parameters: [{
+    title: "Tiles",
+    controls: [
+      { type: "slider", key: "tileSize", min: 10, max: 40 },
+      { type: "custom", key: "tiles", label: "Tile layout", widget: tilePicker,
+        description: "Click a tile to select it. Drag to move it." },
+    ],
+  }],
+  parts: { tiles: { build: (k, p) => /* p.tiles is the array */ } },
+};
+```
+
+- `key` names the param the widget owns. It may hold a **JSON value**: numbers,
+  strings, booleans, arrays and plain objects of those, at most 16 KB serialized and
+  8 levels deep, never `null` (`custom-default-not-json`). `build()` reads it like any
+  other param. This is the one place the "a control writes one scalar" rule is relaxed.
+- `keys` (optional) lists further scalar params the widget may also write.
+- `widget` is a function `(host) => …`, normally imported from a sibling file so
+  `part.js` stays readable (`custom-control-widget-not-function`).
+- `label`, `description`, `hidden`, `when` and `whenFalse` behave as on any control.
+
+**The widget function.** It runs once per mount and draws into `host.el` with plain
+DOM and SVG. It may return `{ update, dispose }`.
+
+```js
+// tile-picker.js
+export function tilePicker(host) {
+  const svg = host.h("svg", { viewBox: "0 0 200 160", width: "100%" });
+  const detail = host.h("div");
+  host.el.append(svg, detail);
+  let stopDetail = null;
+
+  function draw() {
+    const tiles = host.get();                 // a fresh clone of the owned value
+    const sel = host.state.selected ?? null;  // survives the remount an edit performs
+    svg.replaceChildren(...tiles.map((t, i) => host.h("polygon", {
+      points: hexPoints(t.q, t.r), class: i === sel ? "pf-hit selected" : "pf-hit",
+      onpointerdown: () => { host.setState({ selected: i }); draw(); },
+    })));
+    stopDetail?.();
+    stopDetail = sel === null ? null : host.controls(detail, [
+      { type: "slider", key: "height", label: "Height", min: 4, max: 30 },
+    ], { path: `${sel}` });
+  }
+  draw();
+  return { update: draw, dispose: () => stopDetail?.() };
+}
+```
+
+**The host.**
+
+| Member | Meaning |
+|---|---|
+| `host.el`, `host.doc` | The slot to draw into, and its document. |
+| `host.get(key?)` | A clone of the current value (default: the owned key). Any param is readable. |
+| `host.set(value, {key?, commit?})` | Replace a value with a **new** one — never mutate what `get` returned. Schedules the rebuild and commits, unless `commit: false`; then call `host.commit()` when the gesture ends (a drag). Throws for a key you do not own or a value outside the contract. On a **retired** widget (one whose code already threw) `set`, `commit` and `setState` are silent no-ops. |
+| `host.commit(keys?)` | Ends a deferred gesture. A no-op when nothing changed. |
+| `host.derived` | The latest `derive()` output, the same object readouts show. |
+| `host.state`, `host.setState(patch)` | Transient JSON (a selection, an open panel). Not a param, never persisted, but it **survives a remount**, which every edit performs. |
+| `host.controls(container, controls, {path})` | Mount ordinary built-in controls bound *inside* the owned value at a dotted `path` (`"3"`, `"walls.north"`). Their edits commit the owning key. Returns a disposer. One level: no custom control inside, and no `font`, `image` or `vector` sub-control at a path (their asset lookups are keyed on the part's real param names). |
+| `host.h(tag, attrs, ...children)` | Element builder. SVG tags get the SVG namespace; `on<event>` attrs become listeners; `class` and `style` pass through. |
+| `host.svg(text)` | Parse an SVG string to an element you can append and wire up. |
+| `host.svgFromVector(doc)` | A partforge-vector document → inline `<svg>` (the same renderer the `vector` control uses). |
+| `host.file(pathOrToken)` | Text of one of the part's own files, by path or a `pfc-tree://` token, or null. |
+| `host.disabled` | Whether a `when`/`whenFalse: "disable"` currently disables this control. |
+
+`update({reason, disabled})` is called when your key changes from outside the widget
+(`reason: "sync"` — a preset, undo, `setParams`), when `derived` changes
+(`"derived"`), and once after `host.state` was restored on mount (`"restore"`). It is
+**not** called for your own `set`. `dispose()` runs on teardown.
+
+**Rules that keep it working.**
+
+1. Size SVG with `viewBox` plus `width: 100%`. The rail is 288px wide by default and
+   narrower on a phone, where it is the bottom sheet.
+2. Use pointer events, not mouse events, and put `class="pf-drag"` (or
+   `touch-action: none`) on anything dragged — otherwise a finger scrolls the sheet.
+3. Keep selection and similar state in `host.state`, not in a closure: every edit
+   remounts the part and your function runs again.
+4. Hand `set` a new value. `get` returns a clone precisely so the stored value is never
+   edited in place.
+5. A throw in creation, `update`, or a listener installed through `host.h` replaces
+   the widget with an error card and reports it (a hosting agent sees it in the apply
+   result as `panelErrors`); other controls keep working. A throw in `dispose` is
+   reported the same way but leaves no card — there is nothing left to show it on. A
+   listener you attach yourself with `addEventListener`, rather than through `host.h`,
+   is **not** guarded — wire listeners through `host.h`, or wrap your own in try/catch.
+
+**Looking native.** The slot inherits the rail's font, colours and light/dark theme.
+Bare `<button>`, `<input>` and `<select>` elements pick up the built-in looks
+automatically; the built-in classes are available by name for the exact thing:
+`row`, `seg` (a segmented row of buttons), `action`, `ghost`, `num`, `text-input`,
+`select-input`; and for SVG, `pf-hit` (clickable, with a `selected` state) and
+`pf-drag`. Sub-controls mounted through `host.controls` *are* the built-in widgets.
+
+**Reading the part's own files.** Artwork can live beside the code (the tree is text,
+so an SVG, a `partforge-vector` JSON document or a JSON data file — not a PNG).
+Two routes: store the SVG as a string in a JS module (`assets/emblem.svg.js` exporting
+a template literal) and import it like any sibling file — no framework support
+needed; or read it with `host.file("assets/emblem.svg")` and inline it with
+`host.svg(text)`. Give regions ids and wire `pointerdown` on `#wall-3` to toggle
+`walls[3]` in the owned value.
+
+**What a widget cannot do.** Never `fetch` or otherwise reach the network — a widget
+is a pure function of the part and its params, and a hosted sandbox may refuse the
+request or have no credentials to make it with. Also: no imports beyond the part's
+own files, nothing outside `host.el`, and no reading of `params` except through
+`host`.
+
 ### Legacy section shapes (still supported)
 
 Everything above is what a **new part should write**. The original array-based shapes
@@ -1143,6 +1270,10 @@ defaulting everything to a slider:
   reason for a two-position slider to exist.
 - **A computed value the user should see but not set** → `"readout"`. It costs no
   parameter and answers the "so what did that do?" question in place.
+- **Many similar things configured individually, or a spatial choice** (which tiles
+  exist and how tall each is; which walls of an organizer are present) →
+  `"custom"`: a widget the part draws, holding one JSON value. See "Custom controls"
+  above; use it only when no built-in control expresses the choice.
 
 Then gate what doesn't always apply. A control that is meaningless in the current mode
 should carry a **`when`** rather than sit there inert — hide it by default, or use
@@ -2791,7 +2922,9 @@ previously didn't; that's the fix working as intended, not a regression.
 `preset-key-not-in-defaults`, `mixed-section-shape`,
 `duplicate-preset-name`, `duplicate-node-id`, `select-options-missing`,
 `select-default-not-in-options`, `log-scale-needs-positive-min`,
-`when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type` (errors);
+`when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type`,
+`custom-control-widget-not-function`, `custom-default-not-json`,
+`custom-keys-not-in-defaults` (errors);
 `slider-range-excludes-default`, `unknown-control-field`, `duplicate-control-key`,
 `default-not-exposed`, `readout-unknown-derived-key`, `slider-refinement-invalid`,
 `group-depth`, `section-too-many-controls` (warnings).
@@ -2802,6 +2935,10 @@ can't coexist, since mixing them would make the render order arbitrary. Move
 the legacy entries into `controls` (a toggle becomes a checkbox control,
 `advanced` becomes a nested group, `presets` becomes `{ type: "preset" }`
 nodes), or drop `controls` and stay legacy.
+`custom-default-not-json` is `control-default-not-primitive`'s counterpart for a
+`type: "custom"` control, whose key may hold a JSON value (see "Custom controls"):
+it names the first member that is not one — `null`, a function, a class instance,
+a forbidden key, or a value past the 16 KB / depth-8 caps.
 `duplicate-preset-name` fires when the same preset name is declared twice
 (legacy `presets` and/or `{ type: "preset" }` nodes both count) — preset names
 are global to the part, and `verify()` expands one case per name and throws on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.113.0",
+  "version": "0.114.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,10 @@
       "types": "./types/ingest.d.ts",
       "default": "./src/ingest.js"
     },
+    "./panel-values": {
+      "types": "./types/panel-values.d.ts",
+      "default": "./src/panel-values.js"
+    },
     "./tokens.css": "./src/framework/tokens.css",
     "./chrome.css": "./src/framework/chrome.css"
   },
@@ -83,6 +87,9 @@
       ],
       "ingest": [
         "./types/ingest.d.ts"
+      ],
+      "panel-values": [
+        "./types/panel-values.d.ts"
       ]
     }
   },

package/src/framework/app.css

@@ -64,8 +64,10 @@ canvas { display: block; }
    Condition-hidden sections (.hidden, a `when` that evaluated false) are excluded
    for the same reason. Do not simplify this to `.section:first-child { border-top: 0 }` — that
    matches DOM position rather than visibility, and leaves a stray divider
-   floating at the top whenever applyRelevance hides the first section. */
-.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden) {
+   floating at the top whenever applyRelevance hides the first section. A bare
+   sub-panel section (host.controls inside a custom control) never gets the divider
+   because the widget owns its framing. */
+.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden):not(.bare) {
   border-top: 1px solid var(--pf-border);
 }
 /* Section disclosure header: the whole row is the click target (render.js
@@ -382,6 +384,52 @@ button.ghost { background: transparent; border: 1px solid var(--pf-border); colo
 button.ghost:hover:not(:disabled) { background: var(--pf-surface-2); }
 button.action:disabled { opacity: .5; cursor: default; }
 
+/* Custom controls (type: "custom"): a part-authored widget in the rail. The
+   slot inherits the rail's cascade (font, colours, --pf-* tokens); these rules
+   give BARE elements the built-in controls' look so a widget written with
+   plain <button>/<input>/<select> still reads as native, and provide two
+   opt-in classes for SVG: .pf-hit (a clickable region) and .pf-drag (a
+   dragged one — touch-action: none is what lets a finger drag it on a phone
+   instead of scrolling the sheet). */
+.pf-custom { margin: 9px 0; }
+.pf-custom.hidden { display: none; }
+.pf-custom-slot { display: flow-root; }
+/* Every selector in this block is wrapped so the WHOLE thing resolves to
+   (0,0,0) — including the :not([type=...]) chain, which is otherwise an
+   attribute selector per :not() and would still out-specify a class rule
+   like .text-input (0,1,0) or .row .num (0,2,0). At true zero specificity,
+   any class rule wins, so a named built-in class (.seg button, .text-input,
+   select.select-input, …) always beats these bare-element defaults. */
+:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; }
+:where(.pf-custom) :where(button) {
+  font: inherit; font-size: 12px; padding: 5px 9px; cursor: pointer;
+  background: transparent; border: 1px solid var(--pf-border); color: var(--pf-text-2);
+  border-radius: var(--pf-radius-control);
+}
+:where(.pf-custom) :where(button:hover:not(:disabled)) { background: var(--pf-surface-2); }
+:where(.pf-custom) :where(button:disabled) { opacity: .5; cursor: default; }
+:where(.pf-custom) :where(input:not([type="range"]):not([type="checkbox"]):not([type="radio"]), select) {
+  font: 12px/1.4 var(--pf-mono);
+  background: var(--pf-input-bg); color: var(--pf-text-strong);
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 6px 8px;
+}
+:where(.pf-custom) :where(input:focus, select:focus, button:focus-visible) {
+  outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
+}
+.pf-custom .pf-hit { cursor: pointer; }
+.pf-custom .pf-hit:hover { fill: color-mix(in oklab, var(--pf-accent) 25%, transparent); }
+.pf-custom .pf-hit.selected { fill: color-mix(in oklab, var(--pf-accent) 45%, transparent); stroke: var(--pf-accent); }
+.pf-custom .pf-drag { touch-action: none; }
+.pf-custom-error {
+  margin: 4px 0; padding: 6px 8px; border: 1px solid var(--pf-err); border-radius: var(--pf-radius-control);
+  color: var(--pf-err); font-family: var(--pf-mono); font-size: 11px; line-height: 1.4; word-break: break-word;
+}
+.pf-custom-error-title { font-weight: 600; margin-bottom: 2px; }
+/* A sub-panel inside a custom control (host.controls): no header, no indent. */
+.section.bare > .sec-body { padding: 0; }
+.section.bare { padding: 0; border: 0; }
+
 .dl { margin-top: 14px; }
 .dl-head {
   font-family: var(--pf-mono); font-size: 10px; font-weight: 600;

package/src/framework/lint/rules-schema.js

@@ -4,6 +4,7 @@
 // resolve against `defaults`, which produce a control that silently does nothing.
 import { err, warn } from "./finding.js";
 import { suggest } from "../geometry/op-options.js";
+import { jsonValueProblem } from "../panel/json-value.js";
 import { fieldsFor, authorFieldsFor, WIDGET_TYPES, GROUP_FIELDS, PRESET_FIELDS, SECTION_FIELDS, normalizeOptions } from "../panel/widget-specs.js";
 import { sectionRenders, desugar } from "../panel/legacy.js";
 import { buildTree, WHEN_OPS } from "../panel/model.js";
@@ -253,6 +254,9 @@ export const SCHEMA_RULES = [
       const defaults = part.defaults;
       return collectDescriptors(part)
         .filter(({ container }) => !container)
+        // A custom control's OWN key may hold a JSON value; custom-default-not-json
+        // (below) is its rule. Its `keys` stay under this one via their own controls.
+        .filter(({ d }) => d.type !== "custom")
         .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
         .filter(({ d }) => !isEditableValue(defaults[d.key]))
         .map(({ d, path }) => err("control-default-not-primitive",
@@ -625,4 +629,56 @@ export const SCHEMA_RULES = [
       return out;
     },
   },
+  {
+    // The whole feature is the function: a missing or non-function `widget`
+    // renders the error card in the rail and nothing else, every time.
+    id: "custom-control-widget-not-function",
+    run: ({ part }) => collectDescriptors(part)
+      .filter(({ container, authored, d }) => authored && !container && d.type === "custom" && typeof d.widget !== "function")
+      .map(({ d, path }) => err("custom-control-widget-not-function",
+        `custom control "${d.key}" has no \`widget\` function`,
+        "Set `widget` to a function `(host) => …` — usually imported from a sibling file of the part — that draws into `host.el`. See \"Custom controls\" in AUTHORING-PARTS.md.",
+        `${path}.widget`)),
+  },
+  {
+    // The one relaxation of control-default-not-primitive: a custom control's
+    // key may hold a JSON value (json-value.js), and nothing else — a host that
+    // persists panel settings writes it back as a JSON literal.
+    id: "custom-default-not-json",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const defaults = part.defaults;
+      return collectDescriptors(part)
+        .filter(({ container, authored, d }) => authored && !container && d.type === "custom")
+        .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
+        .map(({ d }) => ({ d, problem: jsonValueProblem(defaults[d.key]) }))
+        .filter(({ problem }) => problem !== null)
+        .map(({ d, problem }) => err("custom-default-not-json",
+          `\`defaults.${d.key}\` ${problem}`,
+          `Give "${d.key}" a JSON value: numbers, strings, booleans, arrays and plain objects of those, at most 16 KB and 8 levels deep, with no null. A custom control stores and persists its value as JSON, so anything else is silently lost on reload.`,
+          `defaults.${d.key}`));
+    },
+  },
+  {
+    // `keys` are params the widget writes besides its own; each needs a
+    // default or the write lands on a key the build never reads.
+    id: "custom-keys-not-in-defaults",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      const out = [];
+      for (const { d, path, container, authored } of collectDescriptors(part)) {
+        if (!authored || container || d.type !== "custom" || !Array.isArray(d.keys)) continue;
+        d.keys.forEach((k, i) => {
+          if (typeof k === "string" && known.has(k)) return;
+          const hint = typeof k === "string" ? suggest(k, [...known]) : null;
+          out.push(err("custom-keys-not-in-defaults",
+            `custom control "${d.key}" lists key "${k}", which is not in \`defaults\``,
+            `Add "${k}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a key the widget writes must exist for the build to read it.`,
+            `${path}.keys[${i}]`));
+        });
+      }
+      return out;
+    },
+  },
 ];

package/src/framework/lint/source-scan.js

@@ -12,6 +12,9 @@
 // closure (test/lint-purity.test.js) so lintPart keeps running in Node, the
 // browser sandbox iframe, and Deno.
 //
+// The one exception is json-value.js, which itself imports nothing — the
+// shared predicate for a `type: "custom"` control's value.
+//
 // KNOWN BLIND SPOT — regex literals are not tokenized: a `/[/*]/` or `/x\/y/`
 // reads as a comment opener and can blank the rest of the file, and a regex
 // containing a quote can likewise derail string skipping.
@@ -19,6 +22,8 @@
 // FALSE NEGATIVES — a derailed scan finds no defaults literal and no tokens,
 // so a rule says nothing rather than something wrong.
 
+import { isJsonValue, CUSTOM_VALUE_MAX_DEPTH } from "../panel/json-value.js";
+
 // Span of the object literal after the first `defaults:` key (indices into
 // `source`, end exclusive, covering `{...}`). String- and comment-aware so a
 // "defaults: {" inside a string or comment can't fool the scan.
@@ -191,8 +196,9 @@ function decodeStringLiteral(raw) {
 // into a different spelling of themselves.
 const NUMBER_RE = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
 
-// One value's source text → { value }, or null when it is not a primitive
-// literal this module can read AND write back.
+// One value's source text → { value }, or null when it is not a literal this
+// module can read AND write back. Primitives first; then the JSON-literal
+// grammar a `type: "custom"` control's value is written in.
 function readValue(raw) {
   if (raw === "true") return { value: true };
   if (raw === "false") return { value: false };
@@ -205,6 +211,7 @@ function readValue(raw) {
     const s = decodeStringLiteral(raw);
     return s === null ? null : { value: s };
   }
+  if (q === "[" || q === "{") return readJsonLiteral(raw);
   return null;
 }
 
@@ -220,6 +227,113 @@ function readKey(text, i, end) {
   return m ? { key: m[0], next: i + m[0].length } : null;
 }
 
+// --- JSON literals ----------------------------------------------------------
+//
+// The grammar a custom control's owned value is spelled in inside `defaults`:
+// object and array literals of primitives, nested; bare or quoted keys; JS
+// string escapes (the same decoder as above); decimal numbers; true/false;
+// trailing commas; whitespace. NOTHING else — no comments inside the span, no
+// expressions, identifiers, templates, `null`, computed keys, spreads — so
+// every value this reads, writeJsonLiteral can write back and this can read
+// again. A parse failure is null, never a throw: the entry simply stays
+// unreadable, exactly as an expression does.
+//
+// `depth` is threaded through value/array/object and checked BEFORE
+// recursing into a container, so pathological nesting (thousands of `[`)
+// fails fast during parsing instead of blowing the JS call stack — a
+// RangeError would escape readJsonLiteral's try/catch (it only catches
+// JsonLiteralError) and reach a host outside runRules' own try/catch. The
+// threshold matches json-value.js's own depth check exactly (same "depth at
+// which this container sits" numbering), so this is a fast-fail that agrees
+// with the post-parse isJsonValue call below, never a stricter or looser one.
+
+class JsonLiteralError extends Error {}
+
+function jsonParser(text) {
+  let i = 0;
+  const fail = () => { throw new JsonLiteralError(); };
+  const ws = () => { while (i < text.length && /\s/.test(text[i])) i++; };
+  const value = (depth = 0) => {
+    ws();
+    const c = text[i];
+    if (c === "{") return object(depth);
+    if (c === "[") return array(depth);
+    if (c === '"' || c === "'") {
+      const end = skipQuoted(text, i, text.length);
+      const s = decodeStringLiteral(text.slice(i, end));
+      if (s === null) fail();
+      i = end;
+      return s;
+    }
+    const m = /^-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+    if (m) { i += m[0].length; const n = Number(m[0]); if (!Number.isFinite(n)) fail(); return n; }
+    if (text.startsWith("true", i)) { i += 4; return true; }
+    if (text.startsWith("false", i)) { i += 5; return false; }
+    return fail();
+  };
+  const array = (depth) => {
+    if (depth >= CUSTOM_VALUE_MAX_DEPTH) fail();
+    i++; // [
+    const out = [];
+    for (;;) {
+      ws();
+      if (text[i] === "]") { i++; return out; }
+      if (out.length) { if (text[i] !== ",") fail(); i++; ws(); if (text[i] === "]") { i++; return out; } }
+      out.push(value(depth + 1));
+    }
+  };
+  const object = (depth) => {
+    if (depth >= CUSTOM_VALUE_MAX_DEPTH) fail();
+    i++; // {
+    const out = {};
+    let n = 0;
+    for (;;) {
+      ws();
+      if (text[i] === "}") { i++; return out; }
+      if (n) { if (text[i] !== ",") fail(); i++; ws(); if (text[i] === "}") { i++; return out; } }
+      const k = readKey(text, i, text.length);
+      if (!k) fail();
+      i = k.next;
+      ws();
+      if (text[i] !== ":") fail();
+      i++;
+      const v = value(depth + 1);
+      Object.defineProperty(out, k.key, { value: v, enumerable: true, writable: true, configurable: true });
+      n++;
+    }
+  };
+  return { value, done: () => { ws(); return i === text.length; } };
+}
+
+// An array or object literal's source text → { value }, or null. Applies the
+// custom-value caps (json-value.js) so a literal lint accepts is one the panel
+// would accept too.
+export function readJsonLiteral(text) {
+  if (typeof text !== "string") return null;
+  const first = text.trimStart()[0];
+  if (first !== "[" && first !== "{") return null;
+  try {
+    const p = jsonParser(text);
+    const v = p.value();
+    if (!p.done()) return null;
+    return isJsonValue(v) ? { value: v } : null;
+  } catch (e) {
+    if (e instanceof JsonLiteralError) return null;
+    throw e;
+  }
+}
+
+// The source text for a JSON value being written into `defaults`: compact
+// when it fits on a line, else indented two spaces deeper than the entry's
+// own indentation (`indent`, the whitespace before the entry's key) so a large
+// layout diffs line by line. Always plain JSON — quoted keys — so the reader
+// above accepts it unchanged.
+export function writeJsonLiteral(value, { indent = "" } = {}) {
+  const compact = JSON.stringify(value);
+  if (compact.length <= 80) return compact;
+  return JSON.stringify(value, null, 2).replace(/\n/g, `\n${indent}`);
+}
+
 // Split `{ … }` into entries in source order. `readable` says whether the
 // value was interpreted; `raw` is its exact source text either way, and
 // valueStart/valueEnd are its span (indices into `text`), which is what a

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;