partforge 0.47.1 → 0.48.0

package/src/framework/app.css

@@ -58,10 +58,11 @@ canvas { display: block; }
 /* 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; }
@@ -82,11 +83,20 @@ select.preset {
   border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 7px 9px;
   font-family: var(--pf-mono); font-size: 11px;
 }
+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;
+  font-family: var(--pf-mono); font-size: 11px;
+}
 .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; }
 .adv-toggle {
   margin-top: 8px; padding: 4px 0; width: 100%; border: 0; border-radius: 6px;
   background: transparent; color: var(--pf-muted); cursor: pointer;
@@ -139,6 +149,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/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

@@ -489,7 +489,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       onParamChange();
     });
     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 /

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/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