partforge 0.74.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.74.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/animation-controls.js

@@ -350,11 +350,20 @@ export function attachAnimationControls(viewer, part, {
   // even where ResizeObserver is absent.
   let onStructureChanged = null;
 
+  // Sketch mode takes this slot over: the app floats its own composer where the
+  // bar sits, and a frozen sketch over a playing animation is meaningless
+  // anyway. Its own flag rather than a straight write to `display`, for the
+  // reason mount.js spells out for the view cube's two hide reasons: with one
+  // assignment shared between causes, whichever fires last wins, and a view
+  // switch back to an animated view would reveal a bar that sketch mode still
+  // wants gone.
+  let hiddenForSketch = false;
+
   // Per-view + per-animation chrome: which chooser shows, the picker's options,
   // title, ⓘ description, pager labels, scrubber ticks. A view with no
   // animations hides the whole bar rather than showing an empty transport.
   function syncStructure() {
-    bar.style.display = current ? "" : "none";
+    bar.style.display = current && !hiddenForSketch ? "" : "none";
     onStructureChanged?.();
     hideChapterBubble();
     if (!current) return;
@@ -791,6 +800,15 @@ export function attachAnimationControls(viewer, part, {
       playback?.userEdited();
       syncUi();
     },
+    // Hide/reveal for SKETCH mode only. `--pf-anim-clear` follows for free:
+    // syncStructure notifies the placement pass, which derives the clearance
+    // from this same `display` value and publishes 0px for a hidden bar.
+    setHidden(hidden) {
+      const next = hidden === true;
+      if (next === hiddenForSketch) return;
+      hiddenForSketch = next;
+      syncStructure();
+    },
     // Mount calls this from the view-tab onChange, BEFORE it refreshes the
     // view: the outgoing animation's params and opacity overrides must be
     // restored before the incoming view composes its assembly.

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 }) => {

package/src/framework/mount.js

@@ -912,6 +912,21 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       },
     });
     if (animCtl) cleanup.defer(() => animCtl.detach());
+    // Sketch mode takes the transport bar's slot: the host floats its own
+    // composer there (partforge-cloud's sketch composer), and ink is stored in
+    // screen space against the pose it was drawn over — a playing animation
+    // under it is meaningless. STOP first, then hide: hiding first leaves a
+    // frame where an animation still drives the model beneath a bar that is
+    // already gone. Playback does not resume on the way out; "stop" is the
+    // contract, and notifyUserEdit is the same pause a user's own control edit
+    // performs.
+    if (annotateMode && animCtl) {
+      cleanup.defer(annotateMode.onModeChange(() => {
+        const on = annotateMode.isEnabled();
+        if (on) animCtl.notifyUserEdit();
+        animCtl.setHidden(on);
+      }));
+    }
 
     // Re-run the active view under the current caching setting, so toggling the
     // ?debug switch updates the readout for the same design without a param change.