partforge 0.47.0 → 0.48.0

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

@@ -4,11 +4,15 @@
 // 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, 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";
 
-// Fields controls.js reads on a slider/number descriptor.
-const CONTROL_FIELDS = ["key", "label", "unit", "min", "max", "step", "control", "hidden", "description"];
+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"];
-const TOGGLE_FIELDS = ["key", "label", "on", "hidden", "description"];
 
 const sections = (part) => (Array.isArray(part?.parameters) ? part.parameters : []);
 const arr = (x) => (Array.isArray(x) ? x : []);
@@ -20,8 +24,41 @@ 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: CONTROL_FIELDS });
+      if (d) out.push({ d, path: `parameters[${si}].advanced[${i}]`, fields: fieldsFor("slider") });
     });
     arr(sec?.features).forEach((f, i) => {
       if (!f) return;
@@ -31,34 +68,66 @@ function collectDescriptors(part) {
         // recognise the demo.js flange_d pattern below: a slider sharing its key
         // with the feature is not an independent parameter, it's the feature's own
         // magnitude, and `defaults[key] === 0` there means "off", not "out of range".
-        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: CONTROL_FIELDS, featureKey: f.key });
+        if (s) out.push({ d: s, path: `parameters[${si}].features[${i}].sliders[${j}]`, fields: fieldsFor("slider"), featureKey: f.key });
       });
     });
     arr(sec?.toggles).forEach((t, i) => {
-      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: TOGGLE_FIELDS });
+      if (t) out.push({ d: t, path: `parameters[${si}].toggles[${i}]`, fields: fieldsFor("checkbox") });
     });
   });
   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 ?? {}));
 
-// Mirrors src/framework/controls.js's own visibility predicates (visibleFeatures /
-// sectionRenders, controls.js:32,36-41) — NOT imported, because controls.js pulls in
-// `marked`/`dompurify` (via markdown.js) for its description popovers, which would
-// break partforge/lint's zero-bare-dependency purity guarantee (test/lint-purity.test.js).
-// `features-requires-sliders` must not flag a `feat.sliders.filter(...)` the panel
-// will never reach: controls.js only iterates `visibleFeatures(sec)` (skipping any
-// feature marked `hidden: true`), and only builds a section at all when
-// `sectionRenders(sec)` is true.
-const visibleFeatures = (sec) => arr(sec?.features).filter((f) => f && !f.hidden);
-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 || arr(sec?.advanced).some((d) => d && !d.hidden) || arr(sec?.toggles).some((t) => t && !t.hidden);
+// 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
+// implementation and the two can no longer drift.
+
 export const SCHEMA_RULES = [
   {
     id: "features-requires-sliders",
@@ -114,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\``,
@@ -129,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;
     },
   },
@@ -152,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
@@ -188,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.
@@ -215,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))
@@ -228,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.