partforge 0.47.0 → 0.48.0

package/src/framework/panel/info.js

@@ -0,0 +1,76 @@
+// The ⓘ glyph and its per-panel popover. Shared by the control panel and the
+// animation transport bar (animation-controls.js), which is why it is its own
+// module rather than living inside the panel renderer.
+import { renderMarkdown } from "../markdown.js";
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Popover top edge: below the glyph when it fits, flipped above when the
+// viewport bottom would clip it (e.g. the animation transport bar's ⓘ, which
+// sits at the bottom of the stage). Pure, for direct unit testing — happy-dom
+// reports zero layout metrics, so the flip can't be exercised via the DOM.
+export function popoverTop({ glyphTop, glyphBottom, popHeight, viewportHeight }) {
+  const below = glyphBottom + 6;
+  if (below + popHeight <= viewportHeight - 8) return below;
+  return Math.max(8, glyphTop - 6 - popHeight);
+}
+
+// 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().
+export function createInfoPopover() {
+  const pop = el("div", "popover");
+  pop.hidden = true;
+  document.body.append(pop);
+  let owner = null; // the glyph whose description is showing
+
+  function close() {
+    if (pop.hidden) return;
+    pop.hidden = true;
+    if (owner) { owner.setAttribute("aria-expanded", "false"); owner = null; }
+  }
+  const onDocClick = (e) => {
+    if (!pop.hidden && !pop.contains(e.target) && !e.target.closest?.(".info")) close();
+  };
+  const onDocKeydown = (e) => { if (e.key === "Escape") close(); };
+  document.addEventListener("click", onDocClick);
+  document.addEventListener("keydown", onDocKeydown);
+
+  return {
+    toggle(glyph, description) {
+      if (owner === glyph) { close(); return; } // toggle off
+      close();
+      pop.innerHTML = renderMarkdown(description);
+      pop.hidden = false;
+      owner = glyph;
+      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`;
+    },
+    dispose() {
+      document.removeEventListener("click", onDocClick);
+      document.removeEventListener("keydown", onDocKeydown);
+      pop.remove();
+    },
+  };
+}
+
+// Append a focusable ⓘ glyph to `container` that toggles the panel's shared
+// popover with `description` (Markdown). No-op when description is empty.
+export function attachInfo(container, description, info) {
+  if (typeof description !== "string" || !description.trim()) return;
+  const glyph = document.createElement("button");
+  glyph.type = "button";
+  glyph.className = "info";
+  glyph.textContent = "ⓘ";
+  glyph.setAttribute("aria-label", "More info");
+  glyph.setAttribute("aria-expanded", "false");
+  glyph.addEventListener("click", (e) => { e.stopPropagation(); info.toggle(glyph, description); });
+  container.append(glyph);
+}

package/src/framework/panel/legacy.js

@@ -0,0 +1,146 @@
+// Everything this project knows about the ORIGINAL parameter-schema shapes —
+// `advanced`, `toggles`, `features`, and the `control:` field — lives here and
+// nowhere else. Those shapes still work and still ship; when they are eventually
+// retired, this is one file to delete rather than an archaeology dig through the
+// model.
+//
+// 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) ------------------
+// Guarded per-entry (`x && !x.hidden`) and per-section (`sec?.`) because a null
+// entry or a missing section is anticipated malformed input here: lint's
+// collectDescriptors walks the very same arrays with the same per-entry guard,
+// and it must be able to walk a broken part in order to report on it, rather
+// than have the walk itself throw.
+export const visibleAdvanced = (sec) => arr(sec?.advanced).filter((d) => d && !d.hidden);
+export const visibleFeatures = (sec) => arr(sec?.features).filter((f) => f && !f.hidden);
+export const visibleToggles = (sec) => arr(sec?.toggles).filter((t) => t && !t.hidden);
+
+export function sectionRenders(sec) {
+  if (sec?.hidden) return false;
+  if (sec?.features) return visibleFeatures(sec).length > 0;
+  const hasPresets = sec?.presets && Object.keys(sec.presets).length > 0;
+  return !!hasPresets || visibleAdvanced(sec).length > 0 || visibleToggles(sec).length > 0;
+}
+
+// --- desugaring -------------------------------------------------------------
+
+// One legacy control descriptor -> a control node. `marksCustom` records the
+// legacy split at controls.js:302 vs :346 — a preset-section control drops its
+// picker to "Custom" when synced externally, a feature's own slider does not.
+const toControl = (d, marksCustom) => ({
+  kind: "control",
+  key: d.key,
+  type: d.control ?? "slider",
+  label: d.label,
+  description: d.description,
+  unit: d.unit,
+  min: d.min,
+  max: d.max,
+  step: d.step,
+  hidden: !!d.hidden,
+  marksCustom,
+});
+
+const toCheckbox = (d, { preserveOn, on }) => ({
+  kind: "control",
+  key: d.key,
+  type: "checkbox",
+  label: d.label,
+  description: d.description,
+  on,
+  preserveOn,
+  hidden: !!d.hidden,
+});
+
+// A legacy feature -> [checkbox, bare group of its sliders gated on the checkbox].
+// This is the whole point of the exercise: a feature stops being a special
+// renderer path and becomes an ordinary conditional group.
+function featureNodes(f) {
+  const box = toCheckbox(f, { preserveOn: true, on: f.on });
+  const group = {
+    kind: "group",
+    bare: true,
+    hidden: !!f.hidden,
+    when: { [f.key]: { gt: 0 } },
+    children: arr(f.sliders).filter(Boolean).map((s) => toControl(s, false)),
+  };
+  return [box, group];
+}
+
+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
+    // exclusively to buildFeatureSection, which never reads `presets`,
+    // `toggles`, or `advanced` — so a features section desugars to ONLY its
+    // Advanced group of feature nodes, matching that legacy routing exactly.
+    if (sec?.features) {
+      const advChildren = [];
+      for (const f of arr(sec.features)) {
+        if (f) advChildren.push(...featureNodes(f));
+      }
+      if (advChildren.length) {
+        children.push({ kind: "group", title: "Advanced", collapsed: "auto",
+          legacyAdvanced: true, children: advChildren }); // read by nothing yet; phase 4's migration tooling will key on it
+      }
+      return {
+        kind: "group",
+        id: sec?.id,
+        title: sec?.title,
+        description: sec?.description,
+        collapsed: "auto",
+        hidden: !!sec?.hidden,
+        children,
+      };
+    }
+
+    // The picker is a node like everything else, placed first — which is exactly
+    // where controls.js:264-274 rendered it, so an existing part is unchanged
+    // while a new-style part can position one anywhere in `controls`.
+    const presetNames = sec?.presets ? Object.keys(sec.presets) : [];
+    if (presetNames.length) {
+      children.push({ kind: "preset", presets: sec.presets, hidden: false });
+    }
+
+    // Toggles sit directly in the section, before the Advanced fold, exactly as
+    // controls.js:278-289 rendered them.
+    for (const t of arr(sec?.toggles)) {
+      if (t) children.push(toCheckbox(t, { preserveOn: false, on: t.on ?? 1 }));
+    }
+
+    // Everything else lands inside an "Advanced" group. `collapsed: "auto"` is
+    // what later hands these folds to the small-panel auto-open rule.
+    const advChildren = [];
+    for (const d of arr(sec?.advanced)) {
+      if (d) advChildren.push(toControl(d, true));
+    }
+    if (advChildren.length) {
+      children.push({ kind: "group", title: "Advanced", collapsed: "auto",
+        legacyAdvanced: true, children: advChildren });
+    }
+
+    return {
+      kind: "group",
+      id: sec?.id,
+      title: sec?.title,
+      description: sec?.description,
+      collapsed: "auto",
+      hidden: !!sec?.hidden,
+      children,
+    };
+  });
+}

package/src/framework/panel/model.js

@@ -0,0 +1,84 @@
+// The pure panel model: canonical nodes in, render tree out, plus the condition
+// evaluator. No DOM, no dependencies — partforge/lint imports this and
+// test/lint-purity.test.js requires its whole closure to be dependency-free.
+
+// The operator table IS the grammar. evalWhen dispatches through it and (from
+// phase 5) `when-unknown-operator` builds its did-you-mean list from its keys,
+// so adding an operator can never leave lint behind.
+export const WHEN_OPS = {
+  gt: (a, b) => a > b,
+  gte: (a, b) => a >= b,
+  lt: (a, b) => a < b,
+  lte: (a, b) => a <= b,
+  ne: (a, b) => a !== b,
+  in: (a, b) => Array.isArray(b) && b.includes(a),
+};
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+// A condition against raw params. Never throws: a malformed condition reads as
+// false, because a panel that crashes is worse than a control that hides.
+export function evalWhen(cond, params) {
+  if (cond == null) return true;
+  if (!isPlainObject(cond)) return false;
+  for (const [key, want] of Object.entries(cond)) {
+    if (key === "allOf") {
+      if (!Array.isArray(want) || !want.every((c) => evalWhen(c, params))) return false;
+    } else if (key === "anyOf") {
+      if (!Array.isArray(want) || !want.some((c) => evalWhen(c, params))) return false;
+    } else if (key === "not") {
+      if (evalWhen(want, params)) return false;
+    } else if (isPlainObject(want)) {
+      const entries = Object.entries(want);
+      if (entries.length === 0) return false;
+      for (const [op, operand] of entries) {
+        const fn = WHEN_OPS[op];
+        if (!fn || !fn(params[key], operand)) return false;
+      }
+    } else if (params[key] !== want) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// --- tree building ----------------------------------------------------------
+
+// A group earns its place if anything survived inside it. Simpler than the
+// predicate it replaces (controls.js:36-41), which needed a "has presets but no
+// controls" special case — now a preset-only section just has one child.
+const renders = (node) => node.kind !== "group" || node.children.length > 0;
+
+// Drop hidden nodes and groups left empty, and stamp a stable id on everything.
+// Ids are positional, so they are stable across rebuilds of the same schema; an
+// authored `id` replaces the last segment.
+function assign(nodes, prefix) {
+  const out = [];
+  nodes.forEach((node, i) => {
+    if (node.hidden) return;
+    const id = node.id ?? (prefix ? `${prefix}/${i}` : String(i));
+    if (node.kind !== "group") {
+      out.push({ ...node, id });
+      return;
+    }
+    const built = { ...node, id, children: assign(node.children ?? [], id) };
+    if (renders(built)) out.push(built);
+  });
+  return out;
+}
+
+export const buildTree = (canonical) => assign(canonical ?? [], "");
+
+// Depth-first flat walk of the control leaves. Used by the renderer, by lint's
+// range checks, and by anything that needs "every parameter this panel binds".
+export function controlNodes(tree) {
+  const out = [];
+  const walk = (nodes) => {
+    for (const n of nodes ?? []) {
+      if (n.kind === "group") walk(n.children);
+      else if (n.kind === "control") out.push(n);
+    }
+  };
+  walk(tree);
+  return out;
+}

package/src/framework/panel/panel-state.js

@@ -0,0 +1,70 @@
+// Every cross-cutting decision the panel makes about a node, in one pure pass.
+// The renderer does nothing but apply the result.
+//
+// This is the rail-state.js / rail.js split applied to the panel: the tangled
+// part isn't drawing controls, it's deciding which are visible, which are
+// disabled and which are dimmed — three mechanisms acting on the same nodes.
+// Computing them together, without a DOM, is what makes their interaction
+// testable and keeps render.js small.
+//
+// The two mechanisms are deliberately independent and MUST stay visually
+// distinct (see the spec): `when` hides or disables, relevance only dims.
+import { evalWhen, controlNodes } from "./model.js";
+
+// A panel with a handful of sections should present itself fully, not make the
+// user click three times to see it. Beyond this many, collapsing wins: the rail
+// is a fixed-height column and an eight-section part scrolls forever.
+//
+// Counting SECTIONS rather than controls is deliberate — an author can predict
+// it at a glance, which matters because the rule shapes what their panel looks
+// like on first load.
+export const AUTO_OPEN_MAX_SECTIONS = 3;
+
+const resolveOpen = (node, autoOpen) => {
+  if (node.bare) return true;                    // no disclosure to open
+  if (node.collapsed === true) return false;
+  if (node.collapsed === false) return true;
+  return autoOpen;                               // "auto" or unset
+};
+
+export function computeState(tree, { params, relevant }) {
+  const state = new Map();
+  const showAll = !(relevant instanceof Set);
+  const autoOpen = tree.length <= AUTO_OPEN_MAX_SECTIONS;
+
+  const walk = (nodes, parentVisible, isTop, parentDisabled) => {
+    for (const node of nodes) {
+      const passes = evalWhen(node.when, params);
+      const hideOnFail = node.whenFalse !== "disable";
+      const visible = parentVisible && (passes || !hideOnFail);
+      // Disabled propagates like visible does: a disabled group disables its
+      // whole subtree in the state itself, so render.js never has to walk
+      // descendants (and get bitten by their sibling ordering) to apply it.
+      const disabled = parentDisabled || (!passes && !hideOnFail);
+
+      if (node.kind === "group") {
+        // A group is dimmed when nothing inside it is relevant — the
+        // .section-hidden behavior, generalized from sections to any group.
+        const keys = controlNodes([node]).map((c) => c.key);
+        const dimmed = !showAll && !keys.some((k) => relevant.has(k));
+        // Only a TOP-LEVEL group gets `.section-hidden` (display:none). An inner
+        // group merely dims, because collapsing an inner group out of the layout
+        // on a relevance change makes the panel jump under the user's cursor.
+        // Groups: only dimmedSection is consumed by the renderer today; inner-group dimmed is informational (controls dim individually).
+        state.set(node.id, { visible, disabled, dimmed, dimmedSection: dimmed && isTop, open: resolveOpen(node, autoOpen) });
+        walk(node.children, visible, false, disabled);
+      } else {
+        state.set(node.id, {
+          visible, disabled, dimmedSection: false, open: true,
+          // Relevance is computed over parameter keys, so only a control can be
+          // irrelevant. A preset node has no key; the legacy renderer never
+          // dims the picker, and neither do we.
+          dimmed: node.kind === "control" && !showAll && !relevant.has(node.key),
+        });
+      }
+    }
+  };
+
+  walk(tree, true, true, false);
+  return state;
+}

package/src/framework/panel/render.js

@@ -0,0 +1,289 @@
+// The DOM binder. Builds elements from the render tree, then applies whatever
+// panel-state.js decided. Everything about WHAT to show lives in the model and
+// state modules; this file only knows how to put it on screen.
+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) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+// Map every node id (groups and leaves alike) to its node, for the reveal
+// re-sync in applyState below.
+function indexNodes(nodes, map) {
+  for (const node of nodes ?? []) {
+    map.set(node.id, node);
+    if (node.kind === "group") indexNodes(node.children, map);
+  }
+}
+
+export function buildControls(root, parameters, params, onDirty) {
+  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, 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 }
+  indexNodes(tree, nodeById);
+  let relevant = null;
+
+  // Re-apply state after any change that could flip a condition. This is what
+  // reproduces the legacy feature behavior generically: ticking a feature's
+  // checkbox now simply makes its group's condition true. It also re-syncs any
+  // subtree that just went from hidden to visible, so a just-revealed slider
+  // shows the freshly-written value instead of a stale one (legacy
+  // controls.js ran `syncs.forEach((s) => s())` on a feature tick).
+  // The FIRST computed state decides which sections/folds start open, per the
+  // auto-open rule and any explicit `collapsed`. After that, the user's own
+  // clicks own it — re-running this on every param change would otherwise
+  // snap a section the user opened shut on the next slider drag.
+  let openApplied = false;
+  const applyOpenState = (state) => {
+    if (openApplied) return;
+    openApplied = true;
+    for (const [id, d] of disclosures) {
+      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} ▾`;
+    }
+  };
+
+  const applyState = () => {
+    const state = computeState(tree, { params, relevant });
+    applyOpenState(state);
+    for (const [id, node] of nodeEls) {
+      const s = state.get(id);
+      if (!s) continue;
+      const isGroup = groupIds.has(id);
+      node.classList.toggle("hidden", !s.visible);
+      node.classList.toggle("section-hidden", !!s.dimmedSection);
+      node.classList.toggle("irrelevant", !isGroup && s.dimmed && !s.dimmedSection);
+      node.classList.toggle("disabled", s.disabled);
+      // Only a control leaf's own inputs get `.disabled` written. `disabled`
+      // already propagates through the whole subtree in computeState, so a
+      // group never needs to (and must not) walk its descendants here — doing
+      // so made the outcome depend on `nodeEls` insertion order, which differs
+      // between a bare group/section (registers before its children) and a
+      // titled group (registers after, via its wrapper). Skipping the query
+      // 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) {
+        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);
+      }
+      if (!isGroup && s.dimmed && !s.dimmedSection) node.title = "Doesn't affect the parts in the current view";
+      else node.removeAttribute("title");
+
+      const wasVisible = lastVisible.get(id);
+      if (wasVisible === false && s.visible) {
+        for (const c of controlNodes([nodeById.get(id)])) widgetSyncs.get(c.id)?.();
+      }
+      lastVisible.set(id, s.visible);
+    }
+  };
+
+  const onEdit = () => { applyState(); onDirty?.(); };
+
+  // --- build ---------------------------------------------------------------
+  //
+  // TWO DIFFERENT THINGS USE `.hidden`, and conflating them is a real bug:
+  // conditions hide a node, and a disclosure closes a fold. `applyState` runs on
+  // every param change (mount.js:510), so if it toggled `.hidden` on the fold
+  // body, every slider drag would re-open a fold the user had closed.
+  //
+  // So: a titled group gets a WRAPPER. Conditions toggle the wrapper; the
+  // disclosure toggles the body inside it. A bare group has no fold, so it keeps
+  // the legacy `.feat-group.hidden` markup exactly and conditions own it.
+  function renderGroup(node, container, sectionCtx) {
+    groupIds.add(node.id);
+
+    if (node.bare) {
+      const box = el("div", "feat-group");
+      nodeEls.set(node.id, box);
+      for (const child of node.children) renderNode(child, box, sectionCtx);
+      container.append(box);
+      return;
+    }
+
+    const wrap = el("div", "adv-wrap");
+    const body = el("div", "adv hidden");   // starts closed — legacy parity
+    body.id = `pf-fold-${node.id.replaceAll("/", "-")}`;
+    const toggle = el("button", "adv-toggle", `${node.title} ▾`);
+    toggle.setAttribute("aria-controls", body.id);
+    toggle.addEventListener("click", () => {
+      const nowHidden = body.classList.toggle("hidden");
+      toggle.textContent = nowHidden ? `${node.title} ▾` : `${node.title} ▴`;
+      toggle.setAttribute("aria-expanded", String(!nowHidden));
+    });
+    for (const child of node.children) renderNode(child, body, sectionCtx);
+    wrap.append(toggle, body);
+    nodeEls.set(node.id, wrap);             // conditions act on the wrapper
+    disclosures.set(node.id, { body, button: toggle, label: node.title });
+    container.append(wrap);
+  }
+
+  // The preset picker. Applying a preset overwrites its keys and refreshes the
+  // 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";
+    for (const name of [...names, "Custom"]) {
+      const o = document.createElement("option");
+      o.value = name; o.textContent = name; select.append(o);
+    }
+    select.value = names[0];
+    select.addEventListener("change", () => {
+      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();
+      onEdit();
+    });
+    // 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.
+    if (sectionCtx && !sectionCtx.preset) sectionCtx.preset = select;
+    nodeEls.set(node.id, select);
+    container.append(select);
+  }
+
+  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
+
+    // Editing a control in a preset section diverges from the preset, so the
+    // picker falls back to Custom (controls.js:296). A feature's own slider and a
+    // toggle do NOT — `marksCustom` is false for them.
+    const markCustom = () => {
+      if (node.marksCustom && sectionCtx?.preset) sectionCtx.preset.value = "Custom";
+    };
+    const widget = factory(node, params, {
+      onChange: () => { markCustom(); onEdit(); },
+      info,
+    });
+    nodeEls.set(node.id, widget.el);
+    widgetSyncs.set(node.id, widget.sync);
+    container.append(widget.el);
+
+    // The raw sync is what a PRESET application uses — it must not mark itself
+    // Custom (controls.test.js:366). The registered sync is what an external
+    // syncValues() uses, and for a preset-section control it does drop the
+    // picker to Custom (controls.test.js:350), because a programmatic edit
+    // diverges from the preset exactly as a user edit does.
+    if (sectionCtx) rawSyncs.get(sectionCtx.id).push({ key: node.key, sync: widget.sync });
+    syncFns.push({
+      key: node.key,
+      sync: () => { widget.sync(); markCustom(); },
+    });
+  }
+
+  for (const section of tree) {
+    groupIds.add(section.id);
+    const secEl = el("div", "section");
+    nodeEls.set(section.id, secEl);
+
+    const header = el("div", "sec-header");
+    const title = el("button", "sec-title");
+    title.type = "button";
+    // The chev span carries NO text — its glyph comes from CSS (::before) —
+    // because sectionByTitle-style lookups match `.sec-title` by exact
+    // textContent === title (controls.test.js:210), and a text chevron here
+    // would break that match.
+    title.append(el("span", "sec-name", section.title ?? ""), el("span", "chev"));
+    header.append(title);
+    // 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);
+    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", () => {
+      const nowHidden = body.classList.toggle("hidden");
+      title.setAttribute("aria-expanded", String(!nowHidden));
+    });
+    disclosures.set(section.id, { body, button: title, label: null });
+
+    // `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, []);
+
+    for (const child of section.children) renderNode(child, body, ctx);
+    root.append(secEl);
+  }
+
+  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 {
+    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();
+      applyState();
+    },
+    dispose: () => { info.dispose(); root.replaceChildren(); },
+  };
+}