partforge 0.47.1 → 0.49.0

package/src/framework/app.css

@@ -53,46 +53,124 @@ canvas { display: block; }
    sits at the rail's own padding, so each slider gains the ~22px the old box
    border + padding used to take from both sides. */
 .section {
-  padding: 11px var(--pf-rail-pad);
+  /* No vertical padding at the top: the header band (below) owns the space
+     around the title so a section's title sits at the same offset whether
+     the section is open or collapsed — toggling must not move it. */
+  padding: 0 var(--pf-rail-pad) 11px;
 }
 /* Divider BETWEEN visible sections. `~` walks all preceding siblings, and a
    relevance-hidden section (.section-hidden, display:none) fails the :not(),
    so the topmost VISIBLE section never draws a hairline under the rail header.
-   Do not simplify this to `.section:first-child { border-top: 0 }` — that
+   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) ~ .section:not(.section-hidden) {
+.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden) {
   border-top: 1px solid var(--pf-border);
 }
-.sec-header { display: flex; align-items: center; gap: 4px; }
+/* Section disclosure header: the whole row is the click target (render.js
+   puts the toggle listener on the header; the title button's click bubbles
+   to it and the ⓘ stops propagation). Full-bleed: negative margins cancel
+   the rail padding so the hover band and the collapsed rules run edge to
+   edge while the text keeps the rail's alignment. Row order: title (flex:1),
+   ⓘ, chevron on the far right. */
+.sec-header {
+  display: flex; align-items: center; gap: 6px;
+  margin: 0 calc(-1 * var(--pf-rail-pad)) 6px;
+  /* The same 13px band open or collapsed: the title never moves on toggle
+     and the hover target keeps one size. */
+  padding: 13px var(--pf-rail-pad);
+  cursor: pointer;
+}
+.sec-header:hover { background: var(--pf-surface-2); }
 .sec-title {
-  flex: 1; display: flex; align-items: center; justify-content: space-between; gap: 8px;
-  width: 100%; margin: 0 0 9px; padding: 0; border: 0; background: transparent; cursor: pointer;
+  flex: 1; display: flex; align-items: center;
+  margin: 0; padding: 0; border: 0; background: transparent; cursor: pointer;
   text-align: left;
-  font-family: var(--pf-mono); font-size: 10px; font-weight: 600;
-  letter-spacing: 0.14em; text-transform: uppercase; color: var(--pf-muted-2);
-}
-.sec-title:hover { color: var(--pf-text-2); }
-.sec-title .chev { display: inline-block; transition: transform 0.15s ease; }
-.sec-title .chev::before { content: "▾"; }
-.sec-title[aria-expanded="false"] .chev { transform: rotate(-90deg); }
+  font-family: var(--pf-mono); font-size: 12px; font-weight: 600;
+  letter-spacing: 0.12em; text-transform: uppercase; color: var(--pf-text-2);
+}
+.sec-header:hover .sec-title { color: var(--pf-text); }
+/* Disclosure triangle: closes the header row on the right, after the ⓘ.
+   Glyph via ::before — the span must stay text-free (tests match .sec-title
+   by exact textContent). Rotation keys off the collapsed class because the
+   chevron sits beside, not inside, the aria-carrying button. */
+/* A real equilateral triangle (clip-path, not a font glyph): the box is
+   exactly the triangle's bounds, so rotating about the center is wobble-free
+   — a font's ▾ sits off-center in its em box and lurches when rotated.
+   Height = width × √3/2 keeps it equilateral. */
+.sec-header .chev, .adv-header .chev {
+  display: inline-block; width: 8px; height: 7px; color: var(--pf-muted-2);
+  transition: transform 0.15s ease;
+}
+.sec-header .chev::before, .adv-header .chev::before {
+  content: ""; display: block; width: 100%; height: 100%;
+  background: currentColor;
+  clip-path: polygon(50% 100%, 0 0, 100% 0);
+}
+.section.collapsed > .sec-header .chev, .adv-wrap.collapsed > .adv-header .chev { transform: rotate(-90deg); }
+/* Collapsed section: the header band sits flush between the section's top
+   divider and its own bottom rule — text vertically centered, hover and
+   click covering the entire band. The -1px bottom margin overlaps this rule
+   with the next section's border-top so they read as one line. */
+.section.collapsed {
+  padding-bottom: 0;
+  border-bottom: 1px solid var(--pf-border); margin-bottom: -1px;
+}
+.section.collapsed .sec-header { margin-bottom: 0; }
 .sec-body.hidden { display: none; }
-select.preset {
+/* Native menulist arrows hug the right border and ignore padding, so the
+   panel's selects draw their own — the header chevrons' equilateral triangle
+   as a data-URI, inset 10px from the edge. Fixed slate fill: url() can't
+   read theme variables, and this shade reads on both themes. */
+select.preset, select.select-input {
   width: 100%; background: var(--pf-input-bg); color: var(--pf-text-2);
-  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 7px 9px;
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control);
+  padding: 7px 26px 7px 9px;
   font-family: var(--pf-mono); font-size: 11px;
+  appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='7'%3E%3Cpolygon points='0,0 8,0 4,7' fill='%238b8b94'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 10px center;
 }
 .feat { display: flex; align-items: center; gap: 8px; margin: 6px 0;
   color: var(--pf-text-2); cursor: pointer; }
 .feat input { cursor: pointer; accent-color: var(--pf-accent); }
 .feat-group { margin: 2px 0 8px; padding-left: 10px; border-left: 1px solid var(--pf-border); }
 .feat-group.hidden { display: none; }
+/* Condition-hidden nodes. Disclosure state uses `.hidden` on `.adv` /
+   `.sec-body` (rules above); everything else carrying `.hidden` inside the
+   panel is a `when` that evaluated false. */
+.section.hidden, .slider.hidden, .feat.hidden, select.preset.hidden { display: none; }
+/* Inner fold header: same row anatomy as .sec-header (title left, chevron
+   right, whole row clickable) at the subordinate scale. Spans the fold's own
+   width — not full-bleed — so it never crosses a feat-group's left border;
+   small negative margins let the hover band breathe past the text without
+   moving it. */
+.adv-header {
+  display: flex; align-items: center; gap: 6px;
+  margin: 8px -6px 0; padding: 8px 6px;
+  /* Transparent borders reserve the collapsed rules' pixels so toggling
+     swaps only their color — the title never moves and the hover target
+     keeps one size, matching the section-header treatment. */
+  border-top: 1px solid transparent; border-bottom: 1px solid transparent;
+  border-radius: 6px; cursor: pointer;
+}
+.adv-header:hover { background: var(--pf-surface-2); }
 .adv-toggle {
-  margin-top: 8px; padding: 4px 0; width: 100%; border: 0; border-radius: 6px;
+  flex: 1; margin: 0; padding: 0; border: 0;
   background: transparent; color: var(--pf-muted); cursor: pointer;
-  font-family: var(--pf-mono); font-size: 10px; letter-spacing: 0.08em; text-transform: uppercase; text-align: left;
+  font-family: var(--pf-mono); font-size: 12px; font-weight: 600;
+  letter-spacing: 0.08em; text-transform: uppercase; text-align: left;
+}
+.adv-header:hover .adv-toggle { color: var(--pf-muted-2); }
+/* Collapsed fold: the reserved borders take color — rules above and below,
+   text vertically centered between them (the section-band treatment at fold
+   scale). Square corners while the rules show. */
+.adv-wrap.collapsed > .adv-header {
+  border-top-color: var(--pf-border); border-bottom-color: var(--pf-border);
+  border-radius: 0;
 }
-.adv-toggle:hover { color: var(--pf-muted-2); }
 .adv.hidden { display: none; }
 .adv { margin-top: 4px; }
 
@@ -139,6 +217,24 @@ input[type="range"]:focus-visible { outline: none; }
 input[type="range"]:focus-visible::-webkit-slider-thumb { box-shadow: 0 0 0 5px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 input[type="range"]:focus-visible::-moz-range-thumb { box-shadow: 0 0 0 5px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
+/* recommended band: a tinted span of the track between --band-lo and --band-hi */
+.slider.has-band input[type="range"]::-webkit-slider-runnable-track {
+  background: linear-gradient(to right,
+    var(--pf-border) var(--band-lo),
+    color-mix(in oklab, var(--pf-accent) 30%, var(--pf-border)) var(--band-lo),
+    color-mix(in oklab, var(--pf-accent) 30%, var(--pf-border)) var(--band-hi),
+    var(--pf-border) var(--band-hi));
+}
+.slider.has-band input[type="range"]::-moz-range-track {
+  background: linear-gradient(to right,
+    var(--pf-border) var(--band-lo),
+    color-mix(in oklab, var(--pf-accent) 30%, var(--pf-border)) var(--band-lo),
+    color-mix(in oklab, var(--pf-accent) 30%, var(--pf-border)) var(--band-hi),
+    var(--pf-border) var(--band-hi));
+}
+/* value box outside the recommended band */
+.row .num.warn { border-color: var(--pf-err); color: var(--pf-err); }
+
 button.action {
   width: 100%; margin-top: 8px; padding: 9px; border: 0; border-radius: var(--pf-radius-control);
   background: var(--pf-accent); color: var(--pf-on-accent); font-weight: 500; cursor: pointer;

package/src/framework/controls.js

@@ -10,6 +10,6 @@
 // This file stays at its path because animation-controls.js imports the popover
 // helpers from it, and because it is the documented import site.
 export { buildControls } from "./panel/render.js";
-export { popoverTop, createInfoPopover, attachInfo } from "./panel/info.js";
+export { popoverTop, popoverLeft, createInfoPopover, attachInfo } from "./panel/info.js";
 export { clampToRange } from "./panel/widgets/numeric.js";
 export { visibleAdvanced, visibleFeatures, visibleToggles, sectionRenders } from "./panel/legacy.js";

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

@@ -4,8 +4,12 @@
 // 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 { fieldsFor } from "../panel/widget-specs.js";
-import { sectionRenders } from "../panel/legacy.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";
+import { resolveDerived } from "../derive.js";
+
+export const SECTION_CONTROL_BUDGET = 12;
 
 // Legacy container descriptors aren't widget types, so they keep explicit lists.
 const FEATURE_FIELDS = ["key", "label", "on", "sliders", "hidden", "description"];
@@ -20,6 +24,39 @@ const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArr
 function collectDescriptors(part) {
   const out = [];
   sections(part).forEach((sec, si) => {
+    // The authored shape: children in `controls`, recursively. Field lists are
+    // the authored ones (authorFieldsFor) — the legacy lists stay untouched so
+    // `when` on a legacy descriptor still warns. A section routes to one shape
+    // or the other (desugar's winner-takes-all), so `return` before the legacy
+    // loops below rather than falling through to them.
+    function walkAuthored(list, base) {
+      arr(list).forEach((entry, i) => {
+        if (!entry) return;
+        const path = `${base}[${i}]`;
+        if (entry.type === "group") {
+          out.push({ d: entry, path, fields: GROUP_FIELDS, container: true, authored: true });
+          walkAuthored(entry.controls, `${path}.controls`);
+        } else if (entry.type === "preset") {
+          out.push({ d: entry, path, fields: PRESET_FIELDS, container: true, authored: true });
+        } else {
+          // A typo'd type (e.g. "grup") fails both branches above and lands
+          // here — authorFieldsFor falls back to AUTHOR_COMMON, and
+          // unknown-control-type (below) is what actually diagnoses it.
+          out.push({ d: entry, path, fields: authorFieldsFor(entry.type ?? "slider"), authored: true });
+        }
+      });
+    }
+    if (Array.isArray(sec?.controls)) {
+      // The section itself is a descriptor too, but only worth collecting when
+      // it carries a `when` — a section becomes a descriptor at all only in
+      // that case (a deliberate scope choice), and pushing every section
+      // unconditionally would produce findings with nothing to say. `when`-only
+      // rules just need it present when relevant.
+      if (sec?.when !== undefined) out.push({ d: sec, path: `parameters[${si}]`, fields: SECTION_FIELDS, container: true });
+      walkAuthored(sec.controls, `parameters[${si}].controls`);
+      return;
+    }
+
     arr(sec?.advanced).forEach((d, i) => {
       if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: fieldsFor("slider") });
     });
@@ -41,8 +78,51 @@ function collectDescriptors(part) {
   return out;
 }
 
+// Every preset bundle with its source path — the legacy `presets:` field and
+// authored `{ type: "preset" }` nodes both count.
+function collectPresetBundles(part) {
+  const out = [];
+  sections(part).forEach((sec, si) => {
+    if (isPlainObject(sec?.presets) && !Array.isArray(sec?.controls)) {
+      for (const [name, bundle] of Object.entries(sec.presets)) {
+        out.push({ name, bundle, path: `parameters[${si}].presets` });
+      }
+    }
+    const walk = (list, base) => arr(list).forEach((entry, i) => {
+      if (!entry) return;
+      if (entry.type === "group") walk(entry.controls, `${base}[${i}].controls`);
+      else if (entry.type === "preset" && isPlainObject(entry.presets)) {
+        for (const [name, bundle] of Object.entries(entry.presets)) {
+          out.push({ name, bundle, path: `${base}[${i}].presets` });
+        }
+      }
+    });
+    walk(sec?.controls, `parameters[${si}].controls`);
+  });
+  return out;
+}
+
 const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
 
+// Walk one WhenCondition, calling onKey(key) for every param key it reads and
+// onOp(op) for every operator name it uses. allOf/anyOf/not recurse; a bare
+// `{ key: value }` entry counts as reading `key` with no operator to check.
+function walkWhen(cond, onKey, onOp) {
+  if (cond === null || typeof cond !== "object" || Array.isArray(cond)) return;
+  for (const [key, want] of Object.entries(cond)) {
+    if (key === "allOf" || key === "anyOf") {
+      for (const c of Array.isArray(want) ? want : []) walkWhen(c, onKey, onOp);
+    } else if (key === "not") {
+      walkWhen(want, onKey, onOp);
+    } else {
+      onKey(key);
+      if (want !== null && typeof want === "object" && !Array.isArray(want)) {
+        for (const op of Object.keys(want)) onOp(op);
+      }
+    }
+  }
+}
+
 // These used to be hand-copied from controls.js, because importing it would have
 // dragged `marked`/`dompurify` into partforge/lint and broken its zero-dependency
 // guarantee. panel/legacy.js imports nothing, so lint can share the real
@@ -103,6 +183,7 @@ export const SCHEMA_RULES = [
       if (!isPlainObject(part?.defaults)) return [];
       const known = defaultKeys(part);
       return collectDescriptors(part)
+        .filter(({ container }) => !container)
         .filter(({ d }) => typeof d.key === "string" && !known.has(d.key))
         .map(({ d, path }) => err("control-key-not-in-defaults",
           `control key "${d.key}" is not in \`defaults\``,
@@ -118,21 +199,17 @@ export const SCHEMA_RULES = [
       if (!isPlainObject(part?.defaults)) return [];
       const known = defaultKeys(part);
       const out = [];
-      sections(part).forEach((sec, si) => {
-        const presets = sec?.presets;
-        if (!presets || typeof presets !== "object") return;
-        for (const [name, bundle] of Object.entries(presets)) {
-          if (!bundle || typeof bundle !== "object") continue;
-          for (const key of Object.keys(bundle)) {
-            if (known.has(key)) continue;
-            const hint = suggest(key, [...known]);
-            out.push(err("preset-key-not-in-defaults",
-              `preset "${name}" sets "${key}", which is not in \`defaults\``,
-              `Add "${key}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a preset field absent from defaults is dropped, so selecting the preset silently does nothing for it.`,
-              `parameters[${si}].presets[${JSON.stringify(name)}].${key}`));
-          }
+      for (const { name, bundle, path } of collectPresetBundles(part)) {
+        if (!bundle || typeof bundle !== "object") continue;
+        for (const key of Object.keys(bundle)) {
+          if (known.has(key)) continue;
+          const hint = suggest(key, [...known]);
+          out.push(err("preset-key-not-in-defaults",
+            `preset "${name}" sets "${key}", which is not in \`defaults\``,
+            `Add "${key}" to \`defaults\`${hint ? `, or correct it to "${hint}"` : ""} — a preset field absent from defaults is dropped, so selecting the preset silently does nothing for it.`,
+            `${path}[${JSON.stringify(name)}].${key}`));
         }
-      });
+      }
       return out;
     },
   },
@@ -141,6 +218,7 @@ export const SCHEMA_RULES = [
     run: ({ part }) => {
       const defaults = part?.defaults ?? {};
       return collectDescriptors(part)
+        .filter(({ container }) => !container)
         // A slider that shares its key with the feature that owns it (demo.js's
         // flange_d) is exempt ONLY when the default is actually the feature's
         // off-sentinel: controls.js sets `params[feat.key] = 0` on uncheck (and
@@ -177,12 +255,25 @@ export const SCHEMA_RULES = [
       return out;
     },
   },
+  {
+    id: "unknown-control-type",
+    run: ({ part }) => collectDescriptors(part)
+      .filter(({ container, authored, d }) => authored && !container && typeof d.type === "string" && !WIDGET_TYPES.includes(d.type))
+      .map(({ d, path }) => {
+        const hint = suggest(d.type, WIDGET_TYPES);
+        return err("unknown-control-type",
+          `unrecognised control type "${d.type}"`,
+          `${hint ? `Did you mean "${hint}"? ` : ""}Recognised types: ${WIDGET_TYPES.join(", ")}.`,
+          `${path}.type`);
+      }),
+  },
   {
     id: "duplicate-control-key",
     run: ({ part }) => {
       const seen = new Map();
       const out = [];
-      for (const { d, path } of collectDescriptors(part)) {
+      for (const { d, path, container } of collectDescriptors(part)) {
+        if (container) continue;
         if (typeof d.key !== "string") continue;
         // A feature and its own slider legitimately share a key (see demo.js's
         // flange_d), so only flag a repeat that crosses to a different owner path.
@@ -204,10 +295,8 @@ export const SCHEMA_RULES = [
     run: ({ part }) => {
       if (sections(part).length === 0) return []; // no panel declared at all — nothing to expose
       const exposed = new Set(collectDescriptors(part).map(({ d }) => d.key).filter(Boolean));
-      for (const sec of sections(part)) {
-        for (const bundle of Object.values(sec?.presets ?? {})) {
-          for (const key of Object.keys(bundle ?? {})) exposed.add(key);
-        }
+      for (const { bundle } of collectPresetBundles(part)) {
+        for (const key of Object.keys(bundle ?? {})) exposed.add(key);
       }
       return Object.keys(part?.defaults ?? {})
         .filter((key) => !exposed.has(key))
@@ -217,4 +306,253 @@ export const SCHEMA_RULES = [
           `defaults.${key}`));
     },
   },
+  {
+    id: "mixed-section-shape",
+    run: ({ part }) => {
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        if (!Array.isArray(sec?.controls)) return;
+        const legacy = ["advanced", "toggles", "features", "presets"].filter((k) => sec[k] != null);
+        if (legacy.length) {
+          out.push(err("mixed-section-shape",
+            `section "${sec.id ?? si}" mixes \`controls\` with legacy ${legacy.map((k) => `\`${k}\``).join(", ")}`,
+            "A section is either the new shape (everything in `controls`) or the legacy shape — 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 a `{ type: \"preset\" }` node), or drop `controls`.",
+            `parameters[${si}]`));
+        }
+      });
+      return out;
+    },
+  },
+  {
+    id: "duplicate-preset-name",
+    run: ({ part }) => {
+      const seen = new Map(); // name -> first path
+      const out = [];
+      for (const { name, path } of collectPresetBundles(part)) {
+        if (seen.has(name)) {
+          out.push(err("duplicate-preset-name",
+            `preset "${name}" is declared more than once (first at ${seen.get(name)})`,
+            "Preset names are global to the part: verify() expands one case per name and throws on a repeat, which is a worse place to find out. Rename one of them.",
+            path));
+        } else seen.set(name, path);
+      }
+      return out;
+    },
+  },
+  {
+    id: "select-options-missing",
+    run: ({ part }) => collectDescriptors(part)
+      .filter(({ d, container }) => !container && (d.type === "select" || d.type === "radio"))
+      .filter(({ d }) => normalizeOptions(d.options).length === 0)
+      .map(({ d, path }) => err("select-options-missing",
+        `${d.type} "${d.key}" has no options`,
+        "A `select` or `radio` needs an `options` array — either strings/numbers (value doubles as label) or `{ value, label }` objects. With none, the control renders empty and the parameter can never change.",
+        `${path}.options`)),
+  },
+  {
+    id: "select-default-not-in-options",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      return collectDescriptors(part)
+        .filter(({ d, container }) => !container && (d.type === "select" || d.type === "radio"))
+        .filter(({ d }) => {
+          const opts = normalizeOptions(d.options);
+          return opts.length > 0 && typeof d.key === "string" && d.key in part.defaults
+            && !opts.some((o) => o.value === part.defaults[d.key]);
+        })
+        .map(({ d, path }) => err("select-default-not-in-options",
+          `\`defaults.${d.key}\` is ${JSON.stringify(part.defaults[d.key])}, which is not one of the ${d.type}'s options`,
+          "The default value must be selectable, or the panel opens showing a value the user can never get back to. Add it to `options` or change the default.",
+          `${path}.options`));
+    },
+  },
+  {
+    id: "duplicate-node-id",
+    run: ({ part }) => {
+      // Ids key the renderer's element/state/disclosure maps — a collision
+      // silently cross-wires two nodes (one picker syncing another section's
+      // widgets). Catch it statically: build the tree and look for repeats.
+      const canonical = desugar(part?.parameters ?? []);
+      // A top-level section's built id is (authored ?? String(canonical index)),
+      // so this maps each built section back to its TRUE parameters[] index even
+      // after buildTree drops hidden/empty siblings.
+      const sourceIndex = new Map();
+      canonical.forEach((sec, i) => {
+        const key = sec.id ?? String(i);
+        if (!sourceIndex.has(key)) sourceIndex.set(key, i);
+      });
+      const seen = new Map(); // id -> [sectionIndex, ...]
+      const tree = buildTree(canonical);
+      tree.forEach((section) => {
+        const si = sourceIndex.get(section.id) ?? 0;
+        const walk = (nodes) => {
+          for (const n of nodes ?? []) {
+            if (!seen.has(n.id)) seen.set(n.id, []);
+            seen.get(n.id).push(si);
+            if (n.kind === "group") walk(n.children);
+          }
+        };
+        seen.set(section.id, [...(seen.get(section.id) ?? []), si]);
+        walk(section.children);
+      });
+      return [...seen].filter(([, secs]) => secs.length > 1).map(([id, secs]) =>
+        err("duplicate-node-id",
+          `two panel nodes share the id "${id}"`,
+          "Node ids must be unique across the whole panel — the renderer keys its element and state maps on them, and a collision silently cross-wires the two nodes. Rename one `id` (or drop it to use the positional default).",
+          `parameters[${secs[0]}]`));
+    },
+  },
+  {
+    id: "readout-unknown-derived-key",
+    run: ({ part }) => {
+      let derivedKeys = null;
+      try { derivedKeys = new Set(Object.keys(resolveDerived(part, { ...part?.defaults }))); }
+      catch { return []; } // a throwing derive() is diagnosed elsewhere
+      return collectDescriptors(part)
+        .filter(({ d, container }) => !container && d.type === "readout")
+        .filter(({ d }) => typeof d.derivedKey !== "string" || !derivedKeys.has(d.derivedKey))
+        .map(({ d, path }) => warn("readout-unknown-derived-key",
+          `readout names derived key "${d.derivedKey}", which derive() does not produce`,
+          "A readout displays one output of `derive()`. Name a key a derive group returns, or add that key to `derive` — as it stands the readout shows an em-dash forever.",
+          `${path}.derivedKey`));
+    },
+  },
+  {
+    id: "log-scale-needs-positive-min",
+    run: ({ part }) => collectDescriptors(part)
+      .filter(({ d, container }) => !container && d.scale === "log" && !(typeof d.min === "number" && d.min > 0))
+      .map(({ d, path }) => err("log-scale-needs-positive-min",
+        `"${d.key}" uses scale:"log" with min ${d.min}`,
+        "A logarithmic track needs min > 0 — log(0) is -Infinity and the mapping breaks. Raise `min` (e.g. 0.1) or drop `scale`.",
+        `${path}.scale`)),
+  },
+  {
+    id: "slider-refinement-invalid",
+    run: ({ part }) => {
+      const out = [];
+      for (const { d, path, container } of collectDescriptors(part)) {
+        if (container) continue;
+        const numeric = typeof d.min === "number" && typeof d.max === "number";
+        if (Array.isArray(d.ticks) && numeric && d.ticks.some((t) => t < d.min || t > d.max)) {
+          out.push(warn("slider-refinement-invalid",
+            `"${d.key}" has ticks outside its ${d.min}..${d.max} range`,
+            "Every tick must sit inside [min, max] — an out-of-range tick renders nowhere and, with snap, drags the value out of range.",
+            `${path}.ticks`));
+        }
+        if (Array.isArray(d.recommended)
+            && (d.recommended.length !== 2 || !(d.recommended[0] < d.recommended[1]))) {
+          out.push(warn("slider-refinement-invalid",
+            `"${d.key}" has a malformed recommended band`,
+            "`recommended` is [lo, hi] with lo < hi — the tinted span of the track the DFM checks consider safe.",
+            `${path}.recommended`));
+        }
+        if (d.scale === "log" && (d.ticks || d.recommended)) {
+          out.push(warn("slider-refinement-invalid",
+            `"${d.key}" combines scale:"log" with ticks/recommended`,
+            "Ticks and the recommended band render on a linear track only; on a log slider they are ignored. Drop one or the other.",
+            `${path}.scale`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "when-key-not-in-defaults",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = defaultKeys(part);
+      const out = [];
+      for (const { d, path, fields } of collectDescriptors(part)) {
+        if (!d.when) continue;
+        // A legacy descriptor's `when` isn't a real field (fields wouldn't
+        // list it) — controls.js silently drops it as an unknown key
+        // (unknown-control-field already says so), so validating its
+        // *contents* would imply fixing the key alone makes it work.
+        if (!fields.includes("when")) continue;
+        walkWhen(d.when, (key) => {
+          if (!known.has(key)) {
+            const hint = suggest(key, [...known]);
+            out.push(err("when-key-not-in-defaults",
+              `\`when\` references "${key}", which is not in \`defaults\``,
+              `Conditions read raw parameter keys only${hint ? ` — did you mean "${hint}"?` : "."} A key defaults doesn't have always reads undefined, so the condition is always false and the node never shows.`,
+              `${path}.when`));
+          }
+        }, () => {});
+      }
+      return out;
+    },
+  },
+  {
+    id: "when-unknown-operator",
+    run: ({ part }) => {
+      const ops = Object.keys(WHEN_OPS);
+      const out = [];
+      for (const { d, path, fields } of collectDescriptors(part)) {
+        if (!d.when) continue;
+        // Same reasoning as when-key-not-in-defaults: a legacy `when` is a
+        // dropped unknown field, not a condition to validate.
+        if (!fields.includes("when")) continue;
+        walkWhen(d.when, () => {}, (op) => {
+          if (!ops.includes(op)) {
+            const hint = suggest(op, ops);
+            out.push(err("when-unknown-operator",
+              `\`when\` uses unknown operator "${op}"`,
+              `evalWhen treats an unknown operator as false, so the node silently never shows. Recognised: ${ops.join(", ")}${hint ? ` — did you mean "${hint}"?` : "."}`,
+              `${path}.when`));
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "group-depth",
+    run: ({ part }) => {
+      // Depth counts AUTHORED nesting only, so it needs source paths — walk the
+      // raw sections, not the desugared tree (which adds the legacy Advanced
+      // group an author never wrote).
+      const out = [];
+      sections(part).forEach((sec, si) => {
+        const walk = (list, base, depth) => arr(list).forEach((entry, i) => {
+          if (!entry || entry.type !== "group") return;
+          const path = `${base}[${i}]`;
+          if (depth >= 2) {
+            out.push(warn("group-depth",
+              `group "${entry.title ?? i}" is nested ${depth + 1} levels deep`,
+              "Two levels (a section, one fold inside it) is as deep as a 300px rail stays readable. Flatten: promote the inner group to its own section, or fold its controls into the parent.",
+              path));
+          }
+          walk(entry.controls, `${path}.controls`, depth + 1);
+        });
+        walk(sec?.controls, `parameters[${si}].controls`, 1);
+      });
+      return out;
+    },
+  },
+  {
+    id: "section-too-many-controls",
+    run: ({ part }) => {
+      const out = [];
+      const countControls = (nodes) => {
+        let n = 0;
+        for (const node of nodes ?? []) {
+          if (node.hidden) continue;
+          if (node.kind === "group") n += countControls(node.children);
+          else if (node.kind === "control") n += 1;
+        }
+        return n;
+      };
+      desugar(part?.parameters ?? []).forEach((sec, si) => {
+        if (sec.hidden) return;
+        const n = countControls(sec.children);
+        if (n > SECTION_CONTROL_BUDGET) {
+          out.push(warn("section-too-many-controls",
+            `section "${sec.id ?? si}" shows ${n} controls`,
+            `More than ${SECTION_CONTROL_BUDGET} visible controls in one section reads as a wall. Split the section, or hide internals (\`hidden: true\`) — grouping organizes but does not reduce the count.`,
+            `parameters[${si}]`));
+        }
+      });
+      return out;
+    },
+  },
 ];

package/src/framework/mount.js

@@ -139,10 +139,16 @@ function createCleanupStack() {
 // onViewChange fires once synchronously during mount with the initial resolved
 // view (before ready), then again on every subsequent view change (user click
 // or a programmatic setView) — always the new view name.
+// onParamsCommit({ changed, params })   // the user FINISHED editing a panel control (slider
+//                                         // released, box committed, checkbox ticked, preset
+//                                         // applied): `changed` lists the keys written, `params`
+//                                         // is a snapshot copy. Never fired by setParams or
+//                                         // animation playback — hosts call setParams from their
+//                                         // own undo/reset, and firing here would loop.
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -487,9 +493,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     const panel = buildControls(els.controls, part.parameters, params, () => {
       animCtl?.notifyUserEdit();
       onParamChange();
-    });
+    }, onParamsCommit
+      ? (changed) => onParamsCommit({ changed, params: { ...params } })
+      : undefined);
     cleanup.defer(() => panel.dispose());
-    const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view(), params));
+    const updateRelevance = () => {
+      // A throwing derive() must not break every slider drag — mount's pick
+      // flow already guards its own resolveDerived call the same way
+      // (mount.js ~:250). Readouts simply stay em-dashed.
+      let derived = {};
+      try { derived = resolveDerived(part, params); } catch { /* diagnosed by lint/build */ }
+      panel.refresh({ relevant: relevantParamKeys(part, view(), params), derived });
+    };
     updateRelevance(); // initial view
 
     // The ONLY caller of fastPath.repair(). It must never move into the regen /