partforge 0.75.0 → 0.76.0

package/docs/AUTHORING-PARTS.md

@@ -609,7 +609,12 @@ parameters: [
 ```
 
 Every control `key` must exist in `defaults`, or the control is silently dead —
-`control-key-not-in-defaults` is an error for exactly that reason.
+`control-key-not-in-defaults` is an error for exactly that reason. Its value there must
+be a **number, string or boolean** — a control writes one scalar, so a control bound to
+an array, an object, `null` or `NaN` is dead in the same silent way
+(`control-default-not-primitive`), and a host that saves panel settings back into
+`defaults` cannot write that value either. A non-primitive `defaults` entry that no
+control is bound to is fine: `defaults` also seeds `p` for `build()`.
 
 **Ids.** A section, a group and a preset may carry an `id`; the renderer keys its
 element, state and disclosure maps on ids, so they must be unique across the whole
@@ -1896,7 +1901,8 @@ about the definition as a whole use `""`.
 behave as authored — whether or not that shows up as a thrown exception. Some error
 findings do correspond to a runtime throw (`build-throws`, `verify-expect-throws`),
 but others catch **silent** wrongness: `missing-meta-title`, `part-view-unknown`,
-`control-key-not-in-defaults`, `preset-key-not-in-defaults`, and
+`control-key-not-in-defaults`, `control-default-not-primitive`,
+`preset-key-not-in-defaults`, and
 `verify-unknown-subpart` all fire on parts that build, measure, and verify cleanly —
 a dead control that's silently unreachable, a view that renders nothing, or a
 `verify` expectation that's silently dropped so its gate never runs. That's still an
@@ -1913,7 +1919,8 @@ previously didn't; that's the fix working as intended, not a regression.
 `default-view-ambiguous` (warnings).
 
 **Parameter schema** — `features-requires-sliders`, `features-requires-on`,
-`control-key-not-in-defaults`, `preset-key-not-in-defaults`, `mixed-section-shape`,
+`control-key-not-in-defaults`, `control-default-not-primitive`,
+`preset-key-not-in-defaults`, `mixed-section-shape`,
 `duplicate-preset-name`, `duplicate-node-id`, `select-options-missing`,
 `select-default-not-in-options`, `log-scale-needs-positive-min`,
 `when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type` (errors);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

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

@@ -104,6 +104,22 @@ function collectPresetBundles(part) {
 
 const defaultKeys = (part) => new Set(Object.keys(part?.defaults ?? {}));
 
+// What a control can actually edit: one finite scalar. Non-finite numbers are out
+// with the rest — a slider cannot show NaN, and neither NaN nor Infinity survives
+// a round trip through JSON or a source rewrite.
+const isEditableValue = (v) =>
+  typeof v === "string" || typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v));
+
+// Name a value for a finding's message: the reader needs to know WHICH default is
+// wrong and what it is, and `typeof []` ("object") tells them neither.
+const describeValue = (v) => {
+  if (Array.isArray(v)) return "an array";
+  if (v === null) return "a null";
+  if (typeof v === "number") return `a ${Number.isNaN(v) ? "NaN" : String(v)}`;
+  if (v === undefined) return "an undefined";
+  return `a ${typeof v}`;
+};
+
 // 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.
@@ -191,6 +207,32 @@ export const SCHEMA_RULES = [
           `${path}.key`));
     },
   },
+  {
+    // A control edits ONE value, and the widgets read and write it as a scalar:
+    // a slider over an array renders NaN, a checkbox over an object writes
+    // `true` over it. It is dead in the same silent way control-key-not-in-defaults
+    // is — the part builds, the panel renders, the control does nothing usable —
+    // which is why this is an error rather than a warning.
+    //
+    // Only a key a CONTROL is bound to. `defaults` also seeds `p` for build(), so
+    // parking a table or a point list there for the build to read is legitimate
+    // authoring and none of lint's business.
+    id: "control-default-not-primitive",
+    run: ({ part }) => {
+      // Same guard as control-key-not-in-defaults: bail only when `defaults`
+      // isn't a plain object at all (missing-defaults already reports that).
+      if (!isPlainObject(part?.defaults)) return [];
+      const defaults = part.defaults;
+      return collectDescriptors(part)
+        .filter(({ container }) => !container)
+        .filter(({ d }) => typeof d.key === "string" && Object.hasOwn(defaults, d.key))
+        .filter(({ d }) => !isEditableValue(defaults[d.key]))
+        .map(({ d, path }) => err("control-default-not-primitive",
+          `control "${d.key}" is bound to ${describeValue(defaults[d.key])} default`,
+          `Give "${d.key}" a number, string or boolean default — a control writes one scalar, so it cannot edit this, and a host that saves panel settings back into \`defaults\` cannot write it either.`,
+          `${path}.key`));
+    },
+  },
   {
     id: "preset-key-not-in-defaults",
     run: ({ part }) => {