partforge 0.47.0 → 0.48.0

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

@@ -0,0 +1,94 @@
+// The control-type registry. Declaring a type here is what makes it real: the
+// renderer looks up its DOM factory by type, and partforge/lint derives its
+// accepted-field list from `fields` instead of hardcoding one.
+//
+// Before this existed, rules-schema.js carried three hand-maintained allow-lists
+// (CONTROL_FIELDS / FEATURE_FIELDS / TOGGLE_FIELDS) that had to be edited in
+// lockstep with the renderer — and when they weren't, `unknown-control-field`
+// warned on legitimate fields. Adding a type or a field is now one edit here.
+//
+// The lists deliberately mirror the legacy lint allow-lists EXACTLY: `when`,
+// `whenFalse` and `type` are NOT accepted yet — they join when the phases that
+// make them functional land (type: phase 4; when/whenFalse: phase 6). Accepting
+// a field the panel ignores would trade one silent-dead-field bug for another.
+//
+// Imports nothing: lint consumes this and test/lint-purity.test.js requires a
+// dependency-free closure.
+
+// What legacy rules-schema.js called CONTROL_FIELDS: every descriptor that can
+// appear in `advanced` or a feature's `sliders`, whatever its `control` value.
+const LEGACY_CONTROL = ["key", "label", "unit", "min", "max", "step", "control", "hidden", "description"];
+// What it called TOGGLE_FIELDS.
+const LEGACY_TOGGLE = ["key", "label", "on", "hidden", "description"];
+
+// The authored shape (author.js's normalized node tree): every control carries
+// `type`, and `when`/`whenFalse` are real fields there (phase 6 landed them for
+// this shape only — the legacy lists above stay frozen so a legacy `when` still
+// warns). select/radio are new-shape-only types (no legacy equivalent), so
+// their WIDGET_SPECS `fields` use this list directly rather than a legacy one.
+const AUTHOR_COMMON = ["key", "type", "label", "description", "hidden", "when", "whenFalse"];
+
+export const WIDGET_SPECS = [
+  { type: "slider", kind: "control", fields: LEGACY_CONTROL },
+  { type: "number", kind: "control", fields: LEGACY_CONTROL },
+  { type: "text", kind: "control", fields: LEGACY_CONTROL },
+  { type: "textarea", kind: "control", fields: LEGACY_CONTROL },
+  { type: "checkbox", kind: "control", fields: LEGACY_TOGGLE },
+  { type: "select", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
+  { type: "radio", kind: "control", fields: [...AUTHOR_COMMON, "options"] },
+  { type: "readout", kind: "display", fields: ["type", "label", "description", "unit", "derivedKey", "hidden", "when", "whenFalse"] },
+];
+
+const BY_TYPE = new Map(WIDGET_SPECS.map((s) => [s.type, s]));
+
+export const WIDGET_TYPES = WIDGET_SPECS.map((s) => s.type);
+export const specFor = (type) => BY_TYPE.get(type);
+export const fieldsFor = (type) => BY_TYPE.get(type)?.fields ?? [];
+
+// Per-type extras beyond AUTHOR_COMMON.
+const AUTHOR_EXTRAS = {
+  slider: ["unit", "min", "max", "step", "scale", "ticks", "snap", "recommended"],
+  number: ["unit", "min", "max", "step", "scale", "ticks", "snap", "recommended"],
+  text: [],
+  textarea: [],
+  checkbox: ["on"],
+  select: ["options"],
+  radio: ["options"],
+};
+const AUTHOR_FIELDS = new Map(Object.entries(AUTHOR_EXTRAS).map(
+  ([type, extra]) => [type, [...AUTHOR_COMMON, ...extra]]));
+// readout is a display, not a control — it has no `key`, so it doesn't compose
+// with AUTHOR_COMMON like the control types above. Its author-facing fields
+// are exactly its WIDGET_SPECS fields.
+AUTHOR_FIELDS.set("readout", specFor("readout").fields);
+// An unrecognised type (a typo like "sldier") falls back to AUTHOR_COMMON
+// rather than []: with [], every field on the descriptor — including "key"
+// and "label" — reads as unrecognised, so a single typo cascades into a wall
+// of unknown-control-field warnings with nothing pointing at the real cause.
+// lint's unknown-control-type rule (rules-schema.js) is what actually names
+// the typo; this fallback just keeps the field-level noise from drowning it.
+export const authorFieldsFor = (type) => AUTHOR_FIELDS.get(type) ?? AUTHOR_COMMON;
+
+// Container node types in the authored tree. Not widget types — no DOM factory
+// looks them up — so, like the legacy FEATURE_FIELDS/TOGGLE_FIELDS, they keep
+// explicit field lists here rather than living in WIDGET_SPECS.
+export const GROUP_FIELDS = ["type", "id", "title", "collapsed", "bare", "when", "whenFalse", "hidden", "controls"];
+// NB: no "description" — renderGroup has nowhere to hang an info glyph (the
+// toggle is itself a button). Sections keep descriptions (SECTION_FIELDS).
+export const PRESET_FIELDS = ["type", "id", "label", "presets", "when", "whenFalse", "hidden"];
+// A section itself, in the authored shape — collectDescriptors pushes it as a
+// descriptor only when it carries a `when`, so `when-key-not-in-defaults` and
+// `when-unknown-operator` cover section-level conditions too.
+export const SECTION_FIELDS = ["id", "title", "description", "hidden", "collapsed", "when", "whenFalse", "controls"];
+
+// select/radio option normalization: long form [{ value, label?, description? }]
+// or shorthand ["round", 8, ...] where each entry is both value and label. Lives
+// here rather than in the select widget because lint's validators consume it
+// and must stay DOM-free (widgets/select.js imports info.js -> markdown.js).
+export function normalizeOptions(options) {
+  return (Array.isArray(options) ? options : [])
+    .filter((o) => o != null)
+    .map((o) => (typeof o === "object"
+      ? { value: o.value, label: o.label ?? String(o.value), description: o.description }
+      : { value: o, label: String(o) }));
+}

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

@@ -0,0 +1,37 @@
+// A bare on/off checkbox, writing `on` when ticked and 0 when cleared.
+//
+// `preserveOn` is the one behavioral difference between the two legacy shapes it
+// replaces. A `features` checkbox only wrote `on` when the value wasn't already
+// positive (controls.js:352), so re-ticking a feature restored the magnitude the
+// user had dialled in. A `toggles` checkbox always wrote it (controls.js:286),
+// because its `on` is a flag, not a magnitude.
+import { attachInfo } from "../info.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+export function makeCheckbox(node, params, { onChange, info }) {
+  const row = el("label", "feat");
+  const box = document.createElement("input");
+  box.type = "checkbox";
+  box.checked = params[node.key] > 0;
+  const lbl = el("span", "", node.label);
+  attachInfo(lbl, node.description, info);
+  row.append(box, lbl);
+
+  box.addEventListener("change", () => {
+    if (box.checked) {
+      if (!node.preserveOn || !(params[node.key] > 0)) params[node.key] = node.on ?? 1;
+    } else {
+      params[node.key] = 0;
+    }
+    onChange?.();
+  });
+
+  const sync = () => { box.checked = params[node.key] > 0; };
+  return { el: row, sync };
+}

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

@@ -0,0 +1,16 @@
+// The DOM half of the widget registry. Its keys must match widget-specs.js
+// exactly — test/framework/panel/registry.test.js proves they do.
+import { makeNumeric } from "./numeric.js";
+import { makeText } from "./text.js";
+import { makeCheckbox } from "./checkbox.js";
+import { makeSelect, makeRadio } from "./select.js";
+
+export const WIDGET_FACTORIES = {
+  slider: makeNumeric,
+  number: makeNumeric,
+  text: makeText,
+  textarea: makeText,
+  checkbox: makeCheckbox,
+  select: makeSelect,
+  radio: makeRadio,
+};

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

@@ -0,0 +1,136 @@
+// slider + number: a range input (omitted for `number`) beside an editable value
+// box. The box accepts exact values finer than `step`; typed values clamp to
+// [min, max] on commit (blur/Enter).
+import { attachInfo } from "../info.js";
+
+// Short numeric string without float noise (4 dp max) for the value box.
+const numStr = (v) => String(Math.round(v * 1e4) / 1e4);
+
+export function clampToRange(raw, min, max) {
+  const v = parseFloat(raw);
+  if (!Number.isFinite(v)) return null;
+  return Math.min(max, Math.max(min, v));
+}
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+export function makeNumeric(node, params, { onChange, info }) {
+  const numeric = node.type === "number";
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label);
+  attachInfo(label, node.description, info);
+  row.append(label);
+
+  const val = el("div", "val");
+  const box = document.createElement("input");
+  box.type = "number";
+  box.className = "num";
+  box.min = node.min; box.max = node.max; box.step = node.step;
+  box.value = numStr(params[node.key]);
+  val.append(box);
+  if (node.unit) val.append(el("span", "unit", node.unit));
+  row.append(val);
+  wrap.append(row);
+
+  // A log track maps thumb position 0..LOG_STEPS onto [min, max] geometrically —
+  // the value box stays linear and exact (see AUTHORING-PARTS.md's "Slider
+  // refinements" section). Only valid when min > 0; lint's log-scale-needs-positive-min
+  // catches an authored part that violates that before it ever reaches here.
+  const LOG_STEPS = 1000;
+  const log = node.scale === "log" && node.min > 0;
+  const toValue = (t) => Math.exp(Math.log(node.min) + (t / LOG_STEPS) * (Math.log(node.max) - Math.log(node.min)));
+  const toPos = (v) => Math.round(LOG_STEPS * (Math.log(v) - Math.log(node.min)) / (Math.log(node.max) - Math.log(node.min)));
+  // toPos(0) is -Infinity and a non-finite assignment to slider.value snaps the
+  // thumb to mid-track instead of an end — guard the live-typed, unclamped box
+  // value before it reaches the slider.
+  const toPosSafe = (v) => {
+    if (!(v > 0)) return 0;
+    const t = toPos(v);
+    return Math.max(0, Math.min(LOG_STEPS, Number.isFinite(t) ? t : 0));
+  };
+
+  let slider = null;
+  if (!numeric) {
+    slider = document.createElement("input");
+    slider.type = "range";
+    slider.min = log ? 0 : node.min; slider.max = log ? LOG_STEPS : node.max; slider.step = log ? 1 : node.step;
+    slider.value = log ? toPosSafe(params[node.key]) : params[node.key];
+    slider.addEventListener("input", () => {
+      const v = log ? toValue(+slider.value) : snapTo(+slider.value);
+      params[node.key] = v;
+      box.value = numStr(v);
+      paintWarn();
+      onChange?.();
+    });
+    wrap.append(slider);
+  }
+
+  // ticks: native datalist marks; snap quantizes input to the nearest tick.
+  // The datalist id derives from the node id (assigned by buildTree before
+  // factories run) — stable across re-renders, no randomness.
+  if (slider && !log && Array.isArray(node.ticks) && node.ticks.length) {
+    const dl = document.createElement("datalist");
+    dl.id = `pf-ticks-${node.id.replaceAll("/", "-")}`;
+    for (const t of node.ticks) {
+      const o = document.createElement("option");
+      o.value = String(t);
+      dl.append(o);
+    }
+    wrap.append(dl);
+    slider.setAttribute("list", dl.id);
+  }
+  const snapTo = (v) => {
+    if (!node.snap || !Array.isArray(node.ticks) || !node.ticks.length) return v;
+    return node.ticks.reduce((best, t) => Math.abs(t - v) < Math.abs(best - v) ? t : best);
+  };
+
+  // recommended: a tinted band of the track, and a warning on the value box
+  // when the current value sits outside it. Linear tracks only (like ticks).
+  const band = !log && Array.isArray(node.recommended) && node.recommended.length === 2
+    ? node.recommended : null;
+  if (band) {
+    wrap.classList.add("has-band");
+    const pct = (v) => {
+      const raw = Math.max(0, Math.min(100, ((v - node.min) / (node.max - node.min)) * 100));
+      return `${Math.round(raw * 1e4) / 1e4}%`; // trim float noise (e.g. 12.499999999999996)
+    };
+    wrap.style.setProperty("--band-lo", pct(band[0]));
+    wrap.style.setProperty("--band-hi", pct(band[1]));
+  }
+  const paintWarn = () => {
+    if (band) box.classList.toggle("warn", params[node.key] < band[0] || params[node.key] > band[1]);
+  };
+
+  // live preview while typing (unclamped); clamp + reformat on commit
+  box.addEventListener("input", () => {
+    const v = parseFloat(box.value);
+    if (!Number.isFinite(v)) return;
+    params[node.key] = v;
+    if (slider) slider.value = log ? toPosSafe(v) : v;
+    paintWarn();
+    onChange?.();
+  });
+  box.addEventListener("change", () => {
+    const v = clampToRange(box.value, node.min, node.max);
+    if (v == null) { box.value = numStr(params[node.key]); return; } // revert invalid input
+    params[node.key] = v;
+    box.value = numStr(v);
+    if (slider) slider.value = log ? toPosSafe(v) : v;
+    paintWarn();
+    onChange?.();
+  });
+
+  const sync = () => {
+    box.value = numStr(params[node.key]);
+    if (slider) slider.value = log ? toPosSafe(params[node.key]) : params[node.key];
+    paintWarn();
+  };
+  paintWarn();
+  return { el: wrap, sync };
+}

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

@@ -0,0 +1,31 @@
+// readout: a read-only display of one derive() output, named by `derivedKey`.
+// A display node, not a control — it has no key, never writes params, and gets
+// its value pushed via panel.refresh({ derived }), not pulled from params.
+import { attachInfo } from "../info.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Same float-noise trim the numeric widgets use (4 dp max).
+const numStr = (v) => String(Math.round(v * 1e4) / 1e4);
+
+export function makeReadout(node, { info }) {
+  const wrap = el("div", "slider readout");
+  const row = el("div", "row");
+  const label = el("label", "", node.label);
+  attachInfo(label, node.description, info);
+  const val = el("div", "val", "—");
+  row.append(label, val);
+  wrap.append(row);
+  const update = (derived) => {
+    const v = derived?.[node.derivedKey];
+    val.textContent = v == null ? "—"
+      : typeof v === "number" ? numStr(v) + (node.unit ? ` ${node.unit}` : "")
+      : String(v);
+  };
+  return { el: wrap, update };
+}

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

@@ -0,0 +1,71 @@
+// select: a dropdown over `options`. radio: the same data as a segmented
+// control (reuses the app's existing `.seg` styling), for 2–4 options where
+// seeing all of them matters. Option values may be strings or numbers; the DOM
+// only speaks strings, so both widgets map String(value) back to the real
+// value on the way out.
+import { attachInfo } from "../info.js";
+import { normalizeOptions } from "../widget-specs.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+function labeledRow(node, info) {
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+  return wrap;
+}
+
+export function makeSelect(node, params, { onChange, info }) {
+  const wrap = labeledRow(node, info);
+  const opts = normalizeOptions(node.options);
+  const byString = new Map(opts.map((o) => [String(o.value), o.value]));
+  const select = document.createElement("select");
+  select.className = "select-input";
+  for (const o of opts) {
+    const opt = document.createElement("option");
+    opt.value = String(o.value);
+    opt.textContent = o.label;
+    if (o.description) opt.title = o.description; // long-form option descriptions surface as tooltips
+    select.append(opt);
+  }
+  select.value = String(params[node.key]);
+  select.addEventListener("change", () => {
+    params[node.key] = byString.get(select.value);
+    onChange?.();
+  });
+  wrap.append(select);
+  const sync = () => { select.value = String(params[node.key]); };
+  return { el: wrap, sync };
+}
+
+export function makeRadio(node, params, { onChange, info }) {
+  const wrap = labeledRow(node, info);
+  const opts = normalizeOptions(node.options);
+  const seg = el("div", "seg");
+  const buttons = opts.map((o) => {
+    const b = el("button", "", o.label);
+    b.type = "button";
+    if (o.description) b.title = o.description;
+    b.addEventListener("click", () => {
+      params[node.key] = o.value;
+      paint();
+      onChange?.();
+    });
+    seg.append(b);
+    return { b, value: o.value };
+  });
+  const paint = () => {
+    for (const { b, value } of buttons) b.classList.toggle("on", params[node.key] === value);
+  };
+  paint();
+  wrap.append(seg);
+  return { el: wrap, sync: paint };
+}

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

@@ -0,0 +1,33 @@
+// text / textarea: a live-updating string field. Every edit writes params
+// immediately so the existing rebuild loop previews the new string.
+import { attachInfo } from "../info.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+export function makeText(node, params, { onChange, info }) {
+  const multiline = node.type === "textarea";
+  const wrap = el("div", "slider");
+  const row = el("div", "row");
+  const label = el("label", "", node.label);
+  attachInfo(label, node.description, info);
+  row.append(label);
+  wrap.append(row);
+
+  const field = document.createElement(multiline ? "textarea" : "input");
+  if (!multiline) field.type = "text";
+  field.className = "text-input";
+  field.value = String(params[node.key] ?? "");
+  field.addEventListener("input", () => {
+    params[node.key] = field.value;
+    onChange?.();
+  });
+  wrap.append(field);
+
+  const sync = () => { field.value = String(params[node.key] ?? ""); };
+  return { el: wrap, sync };
+}

package/src/parts/bracket.js

@@ -42,12 +42,12 @@ export default {
     {
       id: "shape",
       title: "Shape ops",
-      toggles: [
-        { key: "clip", label: "Clip arms to a disc (intersect)", on: 1,
+      controls: [
+        { key: "clip", type: "radio", label: "Arm tips",
+          options: [{ value: 0, label: "Square" }, { value: 1, label: "Clipped" }],
           description: "**Intersect** the cross with a circle so the four arm tips are rounded off to a common radius." },
-      ],
-      advanced: [
-        { key: "clearance", label: "Print-clearance offset", unit: "mm", min: 0, max: 1, step: 0.1,
+        { key: "clearance", type: "slider", label: "Print-clearance offset", unit: "mm",
+          min: 0, max: 1, step: 0.1,
           description: "**Offset** the whole outline outward (round corners) for a looser slip fit. 0 = none." },
       ],
     },

package/src/parts/planter.js

@@ -30,28 +30,33 @@ export default {
       id: "body",
       title: "Body",
       description:
-        "The faceted vessel. Pick a preset to start, or open **Advanced** for exact dimensions. " +
-        "**Facets** and **Twist** are pure styling; **Wall** is the one that decides whether it prints cleanly.",
-      presets: {
-        "Pen cup": { facets: 6, dia: 80, height: 100, taper: 1.0, twist: 0, drain: 0 },
-        Planter: { facets: 8, dia: 90, height: 80, taper: 0.9, twist: 0, drain: 8 },
-        Vase: { facets: 5, dia: 70, height: 150, taper: 1.12, twist: 40, drain: 0 },
-      },
-      advanced: [
-        { key: "facets", label: "Facets", min: 3, max: 12, step: 1,
+        "The faceted vessel. Pick a preset to start, or dial exact dimensions below — " +
+        "**Facets** and **Twist** are pure styling; open **Wall** for the one that decides whether it prints cleanly.",
+      controls: [
+        { type: "preset", presets: {
+          "Pen cup": { facets: 6, dia: 80, height: 100, taper: 1.0, twist: 0, drain: 0 },
+          Planter: { facets: 8, dia: 90, height: 80, taper: 0.9, twist: 0, drain: 8 },
+          Vase: { facets: 5, dia: 70, height: 150, taper: 1.12, twist: 40, drain: 0 },
+        } },
+        { key: "facets", type: "slider", label: "Facets", min: 3, max: 12, step: 1,
           description: "Number of flat sides around the body. Low counts read as crystalline; high counts approach a smooth cylinder." },
-        { key: "dia", label: "Diameter", unit: "mm", min: 30, max: 150, step: 1,
+        { key: "dia", type: "slider", label: "Diameter", unit: "mm", min: 30, max: 150, step: 1,
           description: "Across-corners diameter at the base. Size it to the plant, pens, or shelf it has to fit." },
-        { key: "height", label: "Height", unit: "mm", min: 20, max: 200, step: 1,
+        { key: "height", type: "slider", label: "Height", unit: "mm", min: 20, max: 200, step: 1,
           description: "Overall height along the axis." },
-        { key: "taper", label: "Top taper", min: 0.6, max: 1.4, step: 0.02,
+        { key: "taper", type: "slider", label: "Top taper", min: 0.6, max: 1.4, step: 0.02,
           description: "Rim size relative to the base: below 1 tapers inward (planter), 1 is straight (cup), above 1 flares out (vase)." },
-        { key: "wall", label: "Wall thickness", unit: "mm", min: 0.8, max: 4, step: 0.1,
-          description: "Side-wall thickness. The fdm-pla profile wants **≥ 1.2 mm** — go thinner and partforge flags a min-wall warning." },
-        { key: "twist", label: "Twist", unit: "°", min: 0, max: 180, step: 5,
+        { key: "twist", type: "slider", label: "Twist", unit: "°", min: 0, max: 180, step: 5,
           description: "Rotates the facets from base to rim for a spiral look. 0 keeps the facets vertical." },
-        { key: "floor", label: "Floor thickness", unit: "mm", min: 1, max: 6, step: 0.5, hidden: true,
-          description: "Internal: solid base thickness, fixed by the design. Hidden from the end user but still drives the geometry." },
+        { type: "group", title: "Wall", collapsed: "auto", controls: [
+          { key: "wall", type: "slider", label: "Wall thickness", unit: "mm", min: 0.8, max: 4, step: 0.1,
+            recommended: [1.2, 4],
+            description: "Side-wall thickness. The fdm-pla profile wants **≥ 1.2 mm** — go thinner and partforge flags a min-wall warning." },
+          { type: "readout", label: "Inner diameter", derivedKey: "innerDia", unit: "mm",
+            description: "Clear inside width at the base, after the walls." },
+          { key: "floor", type: "slider", label: "Floor thickness", unit: "mm", min: 1, max: 6, step: 0.5, hidden: true,
+            description: "Internal: solid base thickness, fixed by the design. Hidden from the end user but still drives the geometry." },
+        ] },
       ],
     },
     {
@@ -87,6 +92,7 @@ export default {
       // pick it so inner_radius(top) = outer_radius(top) − wall.
       innerTaper: 1 + (Rout * (p.taper - 1)) / Rin,
       drainR: (p.drain + 0.2) / 2, // nominal hole + 0.2 mm print clearance, as a radius
+      innerDia: 2 * Rin, // across-corners inner diameter at the base, after the wall inset
     };
   },
   parts: {

package/types/part.d.ts

@@ -57,10 +57,99 @@ export interface PartMeta {
 /** Which input a control renders as. Omit for a slider + number box. */
 export type ControlKind = "slider" | "number" | "text" | "textarea";
 
+/** Every control type the panel can render. */
+export type ControlType = "slider" | "number" | "text" | "textarea" | "checkbox" | "select" | "radio";
+
+/** A declarative visibility condition, evaluated against raw parameters. */
+export type WhenCondition =
+  | { allOf: WhenCondition[] }
+  | { anyOf: WhenCondition[] }
+  | { not: WhenCondition }
+  | Record<string, ParamValue | {
+      gt?: number; gte?: number; lt?: number; lte?: number;
+      ne?: ParamValue; in?: ParamValue[];
+    }>;
+
+/** One entry in a `controls` array: a control, a nested group, a preset picker, or a readout. */
+export type PanelEntry = PanelControlEntry | PanelGroupEntry | PanelPresetEntry | PanelReadoutEntry;
+
+/** A control bound to one key in `defaults`. `type` defaults to `"slider"`. */
+export interface PanelControlEntry {
+  key: string;
+  type?: ControlType;
+  label?: string;
+  description?: string;
+  unit?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** checkbox: the value written when ticked (default 1). */
+  on?: number;
+  /** select / radio: the choices. Strings are both value and label. */
+  options?: Array<ParamValue | { value: ParamValue; label?: string; description?: string }>;
+  /** slider: logarithmic response. Requires min > 0. */
+  scale?: "log";
+  /** slider: marked values on the track; `snap: true` makes the thumb prefer them. */
+  ticks?: number[];
+  snap?: boolean;
+  /** slider: [lo, hi] band drawn on the track; outside it the value box takes a warning tint. */
+  recommended?: [number, number];
+  hidden?: boolean;
+  when?: WhenCondition;
+  whenFalse?: "disable";
+  /** These two discriminate against the container entries. */
+  controls?: undefined;
+  presets?: undefined;
+}
+
+/** A nested group. `collapsed` defaults to `"auto"` (the small-panel auto-open rule). */
+export interface PanelGroupEntry {
+  type: "group";
+  id?: string;
+  title?: string;
+  collapsed?: boolean | "auto";
+  /** No title, no disclosure — just an indented block. */
+  bare?: boolean;
+  controls: PanelEntry[];
+  hidden?: boolean;
+  when?: WhenCondition;
+  whenFalse?: "disable";
+}
+
+/** A preset picker, positionable anywhere among the controls. */
+export interface PanelPresetEntry {
+  type: "preset";
+  id?: string;
+  label?: string;
+  /** Preset name -> the param overrides it applies. */
+  presets: Record<string, Record<string, ParamValue>>;
+  hidden?: boolean;
+  when?: WhenCondition;
+  whenFalse?: "disable";
+}
+
+/** A read-only display of one `derive()` output. Not bound to `defaults`. */
+export interface PanelReadoutEntry {
+  type: "readout";
+  label?: string;
+  description?: string;
+  unit?: string;
+  derivedKey: string;
+  hidden?: boolean;
+  when?: WhenCondition;
+  whenFalse?: "disable";
+  key?: undefined;
+  controls?: undefined;
+  presets?: undefined;
+}
+
 /**
- * One parameter control. The recognised field list mirrors
- * `CONTROL_FIELDS` in src/framework/lint/rules-schema.js — anything else is
- * ignored by the panel and warned about by `partforge lint`.
+ * One parameter control in a legacy `advanced` / `sliders` array. The recognised
+ * field list is the registry's, `fieldsFor("slider")` in
+ * src/framework/panel/widget-specs.js — anything else is ignored by the panel and
+ * warned about by `partforge lint`.
+ *
+ * @deprecated Prefer a `controls` array of control nodes. Still fully supported.
  */
 export interface ControlDef {
   /** Must exist in `defaults`, or the control is silently dead. */
@@ -82,6 +171,8 @@ export interface ControlDef {
  * A feature: a checkbox that sets `key` to `on` (or `0`) and reveals its own
  * controls. `sliders` is REQUIRED — the panel reads `feat.sliders.filter(...)`
  * unguarded. A bare on/off control belongs in `toggles` instead.
+ *
+ * @deprecated Prefer a `controls` array of control nodes. Still fully supported.
  */
 export interface FeatureDef {
   key: string;
@@ -96,6 +187,8 @@ export interface FeatureDef {
 /**
  * A standalone on/off checkbox shown below the preset picker, outside the
  * Advanced fold. Checked writes `on` (default `1`); unchecked writes `0`.
+ *
+ * @deprecated Prefer a `controls` array of control nodes. Still fully supported.
  */
 export interface ToggleDef {
   key: string;
@@ -123,14 +216,31 @@ export interface PresetSection extends SectionBase {
   advanced?: ControlDef[];
   /** A section with `features` is a feature section; `advanced` is ignored there. */
   features?: undefined;
+  /** Discriminator: a PresetSection carries no `controls` array. */
+  controls?: undefined;
 }
 
 /** A feature-toggle section: each feature is a checkbox plus its own controls. */
 export interface FeatureSection extends SectionBase {
   features: FeatureDef[];
+  /** Discriminator: a FeatureSection carries no `controls` array. */
+  controls?: undefined;
+}
+
+/** The new section shape: everything in `controls`, in render order. */
+export interface NodeSection extends SectionBase {
+  controls: PanelEntry[];
+  collapsed?: boolean | "auto";
+  when?: WhenCondition;
+  whenFalse?: "disable";
+  /** Discriminators: a NodeSection carries none of the legacy arrays. */
+  features?: undefined;
+  advanced?: undefined;
+  toggles?: undefined;
+  presets?: undefined;
 }
 
-export type ParameterSection = PresetSection | FeatureSection;
+export type ParameterSection = PresetSection | FeatureSection | NodeSection;
 
 // --- fonts ------------------------------------------------------------------