partforge 0.47.1 → 0.49.0

package/src/framework/oracle/cases.js

@@ -1,15 +1,26 @@
 // Enumerate the parameter configurations verify() checks: the default config plus
 // every declared preset (or an explicit part.verify.cases list).
 
+import { desugar } from "../panel/legacy.js";
+
+// Preset name -> overrides, discovered from the desugared node tree so both the
+// legacy `presets:` field and authored `{ type: "preset" }` nodes count. The
+// duplicate-name guard predates the duplicate-preset-name lint rule and stays:
+// verify must fail loudly even on an unlinted part.
 function presetMap(part) {
   const map = {};
-  for (const section of part.parameters ?? []) {
-    if (!section.presets) continue;
-    for (const [name, overrides] of Object.entries(section.presets)) {
-      if (name in map) throw new Error(`duplicate preset name across sections: "${name}"`);
-      map[name] = overrides;
+  const walk = (nodes) => {
+    for (const node of nodes ?? []) {
+      if (node.kind === "preset") {
+        for (const [name, overrides] of Object.entries(node.presets ?? {})) {
+          if (name in map) throw new Error(`duplicate preset name across sections: "${name}"`);
+          map[name] = overrides;
+        }
+      }
+      if (node.kind === "group") walk(node.children);
     }
-  }
+  };
+  walk(desugar(part.parameters ?? []));
   return map;
 }
 

package/src/framework/panel/author.js

@@ -0,0 +1,88 @@
+// The NEW authored parameter-schema shape — a section (or nested group) whose
+// children live in a `controls: []` array — normalized to canonical nodes.
+// This file is author.js's mirror of legacy.js: legacy.js is the only code that
+// knows the OLD shapes, this is the only code that knows the new one. Hidden
+// nodes are RETAINED (lint needs them; buildTree drops them).
+//
+// No bare imports: partforge/lint consumes this through desugar() and
+// test/lint-purity.test.js requires a dependency-free closure.
+
+const arr = (x) => (Array.isArray(x) ? x : []);
+
+// Uniform rule for the new shape: every control marks Custom. The legacy
+// exemptions (feature sliders, toggles) encoded legacy-renderer history, not a
+// design principle — preset application still goes through raw syncs, so
+// applying a preset never marks itself Custom.
+function authoredControl(c) {
+  return {
+    kind: "control",
+    key: c.key,
+    type: c.type ?? "slider",
+    label: c.label,
+    description: c.description,
+    unit: c.unit,
+    min: c.min,
+    max: c.max,
+    step: c.step,
+    on: c.type === "checkbox" ? (c.on ?? 1) : c.on,
+    options: c.options,
+    scale: c.scale,
+    ticks: c.ticks,
+    snap: c.snap,
+    recommended: c.recommended,
+    hidden: !!c.hidden,
+    when: c.when,
+    whenFalse: c.whenFalse,
+    preserveOn: false,
+    marksCustom: true,
+  };
+}
+
+function authoredPreset(p) {
+  const names = p.presets ? Object.keys(p.presets) : [];
+  if (!names.length) return null; // a picker with only "Custom" in it is useless
+  return {
+    kind: "preset", id: p.id, label: p.label, presets: p.presets,
+    hidden: !!p.hidden, when: p.when, whenFalse: p.whenFalse,
+  };
+}
+
+function authoredGroup(g) {
+  // No description on inner groups: the fold toggle is itself a button, so
+  // there is nowhere to hang an info glyph. Sections keep theirs.
+  return {
+    kind: "group", id: g.id, title: g.title,
+    collapsed: g.collapsed ?? "auto", bare: !!g.bare, hidden: !!g.hidden,
+    when: g.when, whenFalse: g.whenFalse,
+    children: authoredChildren(g.controls),
+  };
+}
+
+function authoredChildren(list) {
+  const out = [];
+  for (const entry of arr(list)) {
+    if (!entry) continue; // lint must be able to walk a broken part
+    if (entry.type === "group") out.push(authoredGroup(entry));
+    else if (entry.type === "preset") {
+      const node = authoredPreset(entry);
+      if (node) out.push(node);
+    } else if (entry.type === "readout") out.push({
+      kind: "display", type: "readout", label: entry.label, description: entry.description,
+      unit: entry.unit, derivedKey: entry.derivedKey,
+      hidden: !!entry.hidden, when: entry.when, whenFalse: entry.whenFalse,
+    });
+    else out.push(authoredControl(entry));
+  }
+  return out;
+}
+
+export function authoredSection(sec) {
+  return {
+    kind: "group", id: sec?.id, title: sec?.title, description: sec?.description,
+    collapsed: sec?.collapsed ?? "auto", hidden: !!sec?.hidden,
+    when: sec?.when, whenFalse: sec?.whenFalse,
+    children: authoredChildren(sec?.controls),
+  };
+}
+// Authored `id` is honored on containers only; a control entry's `id` is
+// dropped (positional ids serve) and lint warns on the unknown field.

package/src/framework/panel/info.js

@@ -20,6 +20,15 @@ export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight })
   return Math.max(8, glyphTop - 6 - popHeight);
 }
 
+// Popover left edge: aligned 8px left of the glyph when that fits, pulled
+// left so the popover's right edge keeps a 10px margin from the viewport
+// edge, and never past a 10px margin on the left (left margin wins when both
+// would be violated). Pure, for direct unit testing — happy-dom reports zero
+// layout metrics, same as popoverTop above.
+export function popoverLeft({ glyphLeft, popWidth, viewportWidth }) {
+  return Math.max(10, Math.min(glyphLeft - 8, viewportWidth - 10 - popWidth));
+}
+
 // One popover element per panel, shared by all its glyphs (only one open at a
 // time). Document-level dismiss listeners are registered per panel and removed
 // by panel.dispose().
@@ -51,7 +60,7 @@ export function createInfoPopover() {
       glyph.setAttribute("aria-expanded", "true");
       const r = glyph.getBoundingClientRect();
       pop.style.top = `${popoverTop({ glyphTop: r.top, glyphBottom: r.bottom, popHeight: pop.offsetHeight, viewportHeight: window.innerHeight })}px`;
-      pop.style.left = `${Math.max(8, r.left - 8)}px`;
+      pop.style.left = `${popoverLeft({ glyphLeft: r.left, popWidth: pop.offsetWidth, viewportWidth: window.innerWidth })}px`;
     },
     dispose() {
       document.removeEventListener("click", onDocClick);

package/src/framework/panel/legacy.js

@@ -4,10 +4,12 @@
 // retired, this is one file to delete rather than an archaeology dig through the
 // model.
 //
-// Imports nothing, on purpose: partforge/lint consumes desugar() and
+// Imports author.js, on purpose: partforge/lint consumes desugar() and
 // test/lint-purity.test.js asserts lint's whole import closure has zero bare
 // dependencies.
 
+import { authoredSection } from "./author.js";
+
 const arr = (x) => (Array.isArray(x) ? x : []);
 
 // --- the legacy visibility predicates (unchanged behavior) ------------------
@@ -74,6 +76,12 @@ function featureNodes(f) {
 
 export function desugar(parameters) {
   return arr(parameters).map((sec) => {
+    // The NEW shape: children live in `controls`. author.js owns it entirely;
+    // when both `controls` and legacy arrays appear (a lint error,
+    // mixed-section-shape), `controls` wins — same winner-takes-all routing the
+    // features branch below applies to the legacy shapes.
+    if (Array.isArray(sec?.controls)) return authoredSection(sec);
+
     const children = [];
 
     // controls.js:180 routes any section with a truthy `features` field

package/src/framework/panel/render.js

@@ -5,6 +5,7 @@ import { desugar } from "./legacy.js";
 import { buildTree, controlNodes } from "./model.js";
 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";
 
 function el(tag, className, text) {
@@ -23,22 +24,25 @@ function indexNodes(nodes, map) {
   }
 }
 
-export function buildControls(root, parameters, params, onDirty) {
+export function buildControls(root, parameters, params, onDirty, onCommit) {
   const info = createInfoPopover();
   const tree = buildTree(desugar(parameters));
 
   const nodeEls = new Map();      // id -> the element whose visibility we toggle
+  const displayUpdates = new Map(); // id -> a display widget's update(derived)
   const groupIds = new Set();     // ids that are group/section wrappers, never controls
   const syncFns = [];             // { key, sync } for every widget
-  const rawSyncs = new Map();     // sectionId -> { key -> raw sync } for preset application
+  const rawSyncs = new Map();     // sectionId -> [{ key, sync }] for preset application
   const widgetSyncs = new Map();  // id -> the RAW widget sync (no markCustom)
   const nodeById = new Map();     // id -> node, for the reveal re-sync
   const lastVisible = new Map();  // id -> previous `visible`, to detect a reveal
   const lastDisabled = new Map(); // id -> previous `disabled`, to skip a no-op input pass
   // Containers that own a disclosure: sections, and titled inner groups (the
-  // legacy "Advanced" fold). `label` is set only for the inner groups, whose
-  // button text carries the ▾/▴ instead of a chevron span.
-  const disclosures = new Map(); // id -> { body, button, label }
+  // legacy "Advanced" fold). Both share the same anatomy — a header row with
+  // the aria-carrying button and a text-free chevron span — so `el` (the
+  // section element / the fold wrapper) mirrors the disclosure with a
+  // `.collapsed` class and CSS draws the closed-band affordance off that.
+  const disclosures = new Map(); // id -> { body, button, el }
   indexNodes(tree, nodeById);
   let relevant = null;
 
@@ -60,7 +64,7 @@ export function buildControls(root, parameters, params, onDirty) {
       const open = state.get(id)?.open ?? true;
       d.body.classList.toggle("hidden", !open);
       d.button.setAttribute("aria-expanded", String(open));
-      if (d.label) d.button.textContent = open ? `${d.label} ▴` : `${d.label} ▾`;
+      d.el.classList.toggle("collapsed", !open);
     }
   };
 
@@ -84,7 +88,15 @@ export function buildControls(root, parameters, params, onDirty) {
       // entirely when `disabled` hasn't changed also keeps this off the hot
       // path (applyState runs on every slider drag and relevance update).
       if (!isGroup && lastDisabled.get(id) !== s.disabled) {
-        for (const input of node.querySelectorAll("input, select, textarea")) {
+        if (node.matches?.("input, select, textarea")) node.disabled = s.disabled;
+        // `.seg button` is in the list for the radio widget, whose options are
+        // <button>s: without it a disabled radio stayed keyboard-focusable and
+        // only LOOKED disabled. Scoped to `.seg` rather than every button so a
+        // disabled control's ⓘ glyph stays reachable — the popover is where the
+        // author explains what has to be enabled first, which is exactly what
+        // the reader wants here. (Group nodes skip this branch entirely, so the
+        // section and fold disclosure buttons are never touched either way.)
+        for (const input of node.querySelectorAll("input, select, textarea, .seg button")) {
           input.disabled = s.disabled;
         }
         lastDisabled.set(id, s.disabled);
@@ -102,6 +114,15 @@ export function buildControls(root, parameters, params, onDirty) {
 
   const onEdit = () => { applyState(); onDirty?.(); };
 
+  // A commit = the user FINISHED an interaction (slider released, box
+  // committed, checkbox ticked, preset applied). Distinct from onDirty, which
+  // fires on every input event mid-drag. Wrapped: a throwing host handler
+  // must never break the panel.
+  const commit = (keys) => {
+    if (!onCommit) return;
+    try { onCommit(keys); } catch { /* host's problem, not the panel's */ }
+  };
+
   // --- build ---------------------------------------------------------------
   //
   // TWO DIFFERENT THINGS USE `.hidden`, and conflating them is a real bug:
@@ -125,16 +146,25 @@ export function buildControls(root, parameters, params, onDirty) {
 
     const wrap = el("div", "adv-wrap");
     const body = el("div", "adv hidden");   // starts closed — legacy parity
-    const toggle = el("button", "adv-toggle", `${node.title} ▾`);
-    toggle.addEventListener("click", () => {
+    body.id = `pf-fold-${node.id.replaceAll("/", "-")}`;
+    // Same row anatomy as a section header — title button (text-free of any
+    // arrow, same exact-textContent reasoning), chevron span on the right,
+    // whole row clickable — at the fold's subordinate scale.
+    const foldHeader = el("div", "adv-header");
+    const toggle = el("button", "adv-toggle");
+    toggle.type = "button";
+    toggle.append(el("span", "adv-name", node.title));
+    toggle.setAttribute("aria-controls", body.id);
+    foldHeader.append(toggle, el("span", "chev"));
+    foldHeader.addEventListener("click", () => {
       const nowHidden = body.classList.toggle("hidden");
-      toggle.textContent = nowHidden ? `${node.title} ▾` : `${node.title} ▴`;
       toggle.setAttribute("aria-expanded", String(!nowHidden));
+      wrap.classList.toggle("collapsed", nowHidden);
     });
     for (const child of node.children) renderNode(child, body, sectionCtx);
-    wrap.append(toggle, body);
+    wrap.append(foldHeader, body);
     nodeEls.set(node.id, wrap);             // conditions act on the wrapper
-    disclosures.set(node.id, { body, button: toggle, label: node.title });
+    disclosures.set(node.id, { body, button: toggle, el: wrap });
     container.append(wrap);
   }
 
@@ -142,6 +172,11 @@ export function buildControls(root, parameters, params, onDirty) {
   // section's controls through their RAW syncs — a preset application must not
   // mark itself Custom (controls.test.js:366).
   function renderPreset(node, container, sectionCtx) {
+    if (node.label) {
+      const row = el("div", "row");
+      row.append(el("label", "", node.label));
+      container.append(row);
+    }
     const names = Object.keys(node.presets);
     const select = document.createElement("select");
     select.className = "preset";
@@ -154,8 +189,9 @@ export function buildControls(root, parameters, params, onDirty) {
       const bundle = node.presets[select.value];
       if (!bundle) return; // "Custom"
       Object.assign(params, bundle);
-      for (const [key, sync] of rawSyncs.get(sectionCtx.id)) if (key in params) sync();
+      for (const { key, sync } of rawSyncs.get(sectionCtx.id)) if (key in params) sync();
       onEdit();
+      commit(Object.keys(bundle));
     });
     // The section's controls need a handle on the picker to drop it to Custom
     // when one of them is edited. First picker in the section wins.
@@ -167,6 +203,13 @@ export function buildControls(root, parameters, params, onDirty) {
   function renderNode(node, container, sectionCtx) {
     if (node.kind === "group") { renderGroup(node, container, sectionCtx); return; }
     if (node.kind === "preset") { renderPreset(node, container, sectionCtx); return; }
+    if (node.kind === "display") {
+      const widget = makeReadout(node, { info });
+      nodeEls.set(node.id, widget.el);
+      displayUpdates.set(node.id, widget.update);
+      container.append(widget.el);
+      return;
+    }
 
     const factory = WIDGET_FACTORIES[node.type];
     if (!factory) return; // unknown type: lint reports it; the panel skips it
@@ -179,6 +222,7 @@ export function buildControls(root, parameters, params, onDirty) {
     };
     const widget = factory(node, params, {
       onChange: () => { markCustom(); onEdit(); },
+      onCommit: () => commit([node.key]),
       info,
     });
     nodeEls.set(node.id, widget.el);
@@ -190,7 +234,7 @@ export function buildControls(root, parameters, params, onDirty) {
     // 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.
-    if (sectionCtx) rawSyncs.get(sectionCtx.id).set(node.key, widget.sync);
+    if (sectionCtx) rawSyncs.get(sectionCtx.id).push({ key: node.key, sync: widget.sync });
     syncFns.push({
       key: node.key,
       sync: () => { widget.sync(); markCustom(); },
@@ -209,27 +253,35 @@ export function buildControls(root, parameters, params, onDirty) {
     // 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 ?? ""), el("span", "chev"));
+    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);
 
-    title.addEventListener("click", () => {
+    // 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, label: null });
+    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.
     const ctx = { id: section.id, preset: null };
-    rawSyncs.set(section.id, new Map());
+    rawSyncs.set(section.id, []);
 
     for (const child of section.children) renderNode(child, body, ctx);
     root.append(secEl);
@@ -237,8 +289,22 @@ export function buildControls(root, parameters, params, onDirty) {
 
   applyState();
 
+  // The single entry point for a param change: relevance dims/undims controls,
+  // derived pushes fresh values into every readout. Either argument may be
+  // omitted (mount.js's initial call, or a syncValues-only path) — only what's
+  // passed updates. `applyRelevance` is the old name, kept as a thin delegate
+  // so existing callers (and mount.test.js) don't have to change.
+  const refresh = ({ relevant: nextRelevant, derived } = {}) => {
+    if (nextRelevant !== undefined) relevant = nextRelevant;
+    if (derived !== undefined) {
+      for (const update of displayUpdates.values()) update(derived);
+    }
+    applyState();
+  };
+
   return {
-    applyRelevance: (next) => { relevant = next; applyState(); },
+    refresh,
+    applyRelevance: (next) => refresh({ relevant: next }),
     syncValues: (keys) => {
       const only = keys && new Set(keys);
       for (const { key, sync } of syncFns) if (!only || only.has(key)) sync();

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

@@ -21,12 +21,22 @@ const LEGACY_CONTROL = ["key", "label", "unit", "min", "max", "step", "control",
 // 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]));
@@ -34,3 +44,51 @@ 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

@@ -14,7 +14,7 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeCheckbox(node, params, { onChange, info }) {
+export function makeCheckbox(node, params, { onChange, onCommit, info }) {
   const row = el("label", "feat");
   const box = document.createElement("input");
   box.type = "checkbox";
@@ -30,6 +30,7 @@ export function makeCheckbox(node, params, { onChange, info }) {
       params[node.key] = 0;
     }
     onChange?.();
+    onCommit?.();
   });
 
   const sync = () => { box.checked = params[node.key] > 0; };

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

@@ -3,6 +3,7 @@
 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,
@@ -10,4 +11,6 @@ export const WIDGET_FACTORIES = {
   text: makeText,
   textarea: makeText,
   checkbox: makeCheckbox,
+  select: makeSelect,
+  radio: makeRadio,
 };

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

@@ -19,7 +19,7 @@ function el(tag, className, text) {
   return node;
 }
 
-export function makeNumeric(node, params, { onChange, info }) {
+export function makeNumeric(node, params, { onChange, onCommit, info }) {
   const numeric = node.type === "number";
   const wrap = el("div", "slider");
   const row = el("div", "row");
@@ -38,26 +38,83 @@ export function makeNumeric(node, params, { onChange, info }) {
   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 = node.min; slider.max = node.max; slider.step = node.step;
-    slider.value = params[node.key];
+    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", () => {
-      params[node.key] = +slider.value;
-      box.value = numStr(+slider.value);
+      const v = log ? toValue(+slider.value) : snapTo(+slider.value);
+      params[node.key] = v;
+      box.value = numStr(v);
+      paintWarn();
       onChange?.();
     });
+    slider.addEventListener("change", () => onCommit?.());
     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 = v;
+    if (slider) slider.value = log ? toPosSafe(v) : v;
+    paintWarn();
     onChange?.();
   });
   box.addEventListener("change", () => {
@@ -65,13 +122,17 @@ export function makeNumeric(node, params, { onChange, info }) {
     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 = v;
+    if (slider) slider.value = log ? toPosSafe(v) : v;
+    paintWarn();
     onChange?.();
+    onCommit?.();
   });
 
   const sync = () => {
     box.value = numStr(params[node.key]);
-    if (slider) slider.value = 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 };
+}