partforge 0.26.1 → 0.28.0

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

@@ -0,0 +1,288 @@
+// Group 4 — the verify block's own well-formedness. Each condition here currently
+// throws from verify() mid-run, AFTER measure has printed and the kernel has booted,
+// which is also the documented reason CLI stdout isn't pure JSON in that case.
+// Catching them statically removes both the wasted boot and the stdout caveat.
+import { err } from "./finding.js";
+import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
+import { PROFILES } from "../../testing/dfm-profiles.js";
+import { parseAssertion } from "../../testing/assert-dsl.js";
+import { suggest } from "../geometry/op-options.js";
+
+// Resolve `expect` to a plain object. The function form (p, d) => ({…}) is invoked
+// once with the probe's params so per-preset topology can be linted like any other.
+// Returns { expect, threw }.
+//
+// Exported so `lintContext` (index.js) can memoize a single call per lint pass and
+// share it across every Group 4 rule below — `expect` is user-supplied code, and
+// without memoization a function-form `expect` that throws only on its first call
+// would fire both `verify-expect-throws` (first call) and whatever rule calls it
+// next (second call succeeds), a cascading double-report.
+export function resolveExpect(verify, p, d) {
+  if (typeof verify?.expect !== "function") return { expect: verify?.expect, threw: null };
+  try { return { expect: verify.expect(p, d), threw: null }; }
+  catch (e) { return { expect: null, threw: e?.message || String(e) }; }
+}
+
+const isExpectation = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && "expr" in v;
+const exprOf = (v) => (isExpectation(v) ? v.expr : v);
+
+// `contacts` (must-touch pairs) and `clearance` (free-fit gaps) live under
+// `verify.expect._view` but are pair-wise checks, not scalar VIEW_METRICS — mirror
+// verify.js's own peel (verify.js:143) so they never hit the scalar-metric /
+// assertion-expression checks below. Validated for real by `verify-bad-pair-check`.
+const peelPairKeys = (metrics) => {
+  const { contacts, clearance, ...rest } = metrics;
+  return rest;
+};
+
+// `JSON.stringify` can itself throw (BigInt, circular refs) — lintPart must never
+// throw, so fall back to `String` for anything that won't serialize.
+const describe = (v) => { try { return JSON.stringify(v); } catch { return String(v); } };
+
+// `suggest` calls `.toLowerCase()` on the key; guard against non-string pair names
+// (a runtime `contacts`/`clearance` entry can contain anything).
+const safeSuggest = (key, valid) => (typeof key === "string" ? suggest(key, valid) : null);
+
+// `requirePair` (verify.js:41) throws before it even looks at `part.parts` when a
+// pair names the same sub-part twice — a pair describes a relationship between two
+// distinct sub-parts, so self-pairs are never legal.
+function checkSameName(a, b, path) {
+  return a === b
+    ? [err("verify-bad-pair-check",
+        `\`${path}\` names the same sub-part twice ("${a}")`,
+        "A pair must name two different sub-parts. Change one side to the other sub-part it should be checked against, or remove the entry if it doesn't describe a real relationship.",
+        path)]
+    : [];
+}
+
+// Both `contacts` pairs and `clearance` keys ultimately name two sub-parts; a name
+// absent from `part.parts` is what the runtime `requirePair` throws for.
+function checkPairNames(a, b, names, path) {
+  const out = [];
+  for (const n of [a, b]) {
+    if (names.includes(n)) continue;
+    const hint = safeSuggest(n, names);
+    out.push(err("verify-unknown-subpart",
+      `\`${path}\` references "${n}", which is not a sub-part`,
+      `Use one of the sub-part names (${names.join(", ")})${hint ? ` — did you mean "${hint}"?` : "."}`,
+      path));
+  }
+  return out;
+}
+
+// Static analogue of verify.js's `pairGapChecks` contacts handling (verify.js:61-66).
+function checkContacts(contacts, names, path) {
+  if (contacts === undefined || contacts === null) return [];
+  if (!Array.isArray(contacts)) {
+    return [err("verify-bad-pair-check",
+      `\`${path}\` must be an array of ["a", "b"] pairs, got ${describe(contacts)}`,
+      `Set \`contacts\` to an array of two-element sub-part name pairs, e.g. \`contacts: [["lid", "body"]]\`.`,
+      path)];
+  }
+  const out = [];
+  contacts.forEach((pair, i) => {
+    const pairPath = `${path}[${i}]`;
+    if (!Array.isArray(pair) || pair.length !== 2) {
+      out.push(err("verify-bad-pair-check",
+        `\`${pairPath}\` must be an ["a", "b"] pair, got ${describe(pair)}`,
+        `Each \`contacts\` entry must be a two-element array naming the two sub-parts that should touch, e.g. \`["lid", "body"]\`.`,
+        pairPath));
+      return;
+    }
+    out.push(...checkSameName(pair[0], pair[1], pairPath));
+    // `requirePair` (verify.js:41) checks the same-name case first and throws
+    // before ever looking at `part.parts` — so a same-name pair never reaches the
+    // unknown-name check at runtime either. Skip it here too, or an unknown
+    // self-paired name would double-report (once per identical position).
+    if (pair[0] !== pair[1]) out.push(...checkPairNames(pair[0], pair[1], names, pairPath));
+  });
+  return out;
+}
+
+// Static analogue of verify.js's `pairGapChecks` clearance handling (verify.js:85-87).
+// Note the separator is the multiplication sign "×" (U+00D7), not the letter x.
+function checkClearance(clearance, names, path) {
+  if (clearance === undefined || clearance === null || typeof clearance !== "object") return [];
+  const out = [];
+  for (const key of Object.keys(clearance)) {
+    const pairPath = `${path}[${JSON.stringify(key)}]`;
+    const pair = key.split("×").map((s) => s.trim());
+    if (pair.length !== 2 || !pair[0] || !pair[1]) {
+      out.push(err("verify-bad-pair-check",
+        `\`${pairPath}\` key must be "a×b" (sub-part names joined by the multiplication sign ×), got ${JSON.stringify(key)}`,
+        `Rename the key to \`"a×b"\` using the two sub-part names that should have a declared clearance, e.g. \`"lid×body"\`. The separator is U+00D7 (×), not the letter x.`,
+        pairPath));
+      continue;
+    }
+    out.push(...checkSameName(pair[0], pair[1], pairPath));
+    // Same short-circuit as `checkContacts` above: a same-name pair never reaches
+    // the unknown-name check at runtime (or here), so it can't double-report.
+    if (pair[0] !== pair[1]) out.push(...checkPairNames(pair[0], pair[1], names, pairPath));
+  }
+  return out;
+}
+
+// `clearance`'s values genuinely are assertion expressions run through the DSL
+// (verify.js:96), unlike `contacts` (pair arrays with nothing to parse). Mirror
+// verify.js's own normalization — a bare value or an `{ expr, hint }` wrapper,
+// via `normalizeExpectation` (verify.js:91) — using the same `isExpectation` /
+// `exprOf` helpers the scalar-metric loop below uses. Reported under
+// `verify-bad-expr`, not `verify-bad-pair-check`: a malformed key is a pair-naming
+// problem, but a malformed value is an assertion-DSL problem, same as any other
+// metric's expectation.
+function checkClearanceExprs(clearance, path) {
+  if (clearance === undefined || clearance === null || typeof clearance !== "object") return [];
+  const out = [];
+  for (const [key, spec] of Object.entries(clearance)) {
+    try { parseAssertion(exprOf(spec)); }
+    catch (e) {
+      out.push(err("verify-bad-expr",
+        `the expectation for _view.clearance["${key}"] is not a valid assertion: ${e?.message || String(e)}`,
+        "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
+        `${path}[${JSON.stringify(key)}]`));
+    }
+  }
+  return out;
+}
+
+// Static walk of `resolveProfile`'s (dfm-profiles.js) `base` chain, mirroring its
+// exact throw conditions at every level: a string not in `PROFILES` ("unknown
+// process profile"), or — recursively — a bad `base` nested inside a `base`
+// object. A falsy `base` resolves to `{}` at runtime (`spec.base ? … : {}`) and
+// is never reached, so it's left alone here too. `seen` records every `base`
+// value already visited so a self-referential or cyclic chain (`base.base ===
+// base`) cannot recurse forever — `lintPart` must always terminate. `depth` is a
+// second, cheap belt-and-suspenders cap for the same reason.
+function checkProcessSpec(spec, path, valid, seen, depth = 0) {
+  if (depth > 50) return []; // pathological chain — bail rather than hang
+  if (typeof spec === "string") {
+    if (valid.includes(spec)) return [];
+    const hint = suggest(spec, valid);
+    return [err("verify-unknown-process",
+      `\`${path}\` names "${spec}", which is not a known DFM profile`,
+      `Use one of: ${valid.join(", ")}${hint ? ` — did you mean "${hint}"?` : ""}, or pass an inline profile object such as \`{ bed: [220, 220, 250], minWall: 1.2 }\`.`,
+      path)];
+  }
+  if (spec && typeof spec === "object") {
+    if (!spec.base) return []; // no base (or a falsy one) — nothing further to resolve
+    if (seen.has(spec.base)) return []; // already visited — self-referential/cyclic, stop
+    seen.add(spec.base);
+    return checkProcessSpec(spec.base, `${path}.base`, valid, seen, depth + 1);
+  }
+  // Anything else truthy (number, boolean, …) is what resolveProfile's final
+  // branch throws "invalid process profile" for.
+  return [err("verify-unknown-process",
+    `\`${path}\` is not a valid DFM profile: ${describe(spec)}`,
+    `Use one of: ${valid.join(", ")}, or an inline profile object such as \`{ bed: [220, 220, 250], minWall: 1.2 }\`.`,
+    path)];
+}
+
+export const VERIFY_RULES = [
+  {
+    id: "verify-expect-throws",
+    run: ({ resolveExpectOnce }) => {
+      const { threw } = resolveExpectOnce();
+      return threw ? [err("verify-expect-throws",
+        `\`verify.expect(p, d)\` threw: ${threw}`,
+        "The function form of `expect` must return an expectation object for any parameter set. Guard whatever it reads, or switch to the static object form.",
+        "verify.expect")] : [];
+    },
+  },
+  {
+    id: "verify-unknown-subpart",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      return Object.keys(expect)
+        .filter((key) => key !== "_view" && !names.includes(key))
+        .map((key) => {
+          const hint = suggest(key, names);
+          return err("verify-unknown-subpart",
+            `\`verify.expect\` targets "${key}", which is not a sub-part`,
+            `Use one of the sub-part names (${names.join(", ")}) or the literal \`_view\` for whole-assembly metrics${hint ? ` — did you mean "${hint}"?` : "."}`,
+            `verify.expect.${key}`);
+        });
+    },
+  },
+  {
+    id: "verify-unknown-metric",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      const out = [];
+      for (const [target, metricsRaw] of Object.entries(expect)) {
+        if (target !== "_view" && !names.includes(target)) continue; // reported by verify-unknown-subpart
+        if (!metricsRaw || typeof metricsRaw !== "object") continue;
+        // contacts/clearance are pair checks, not scalar view metrics — validated
+        // separately by verify-bad-pair-check, and excluded here.
+        const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
+        const registry = target === "_view" ? VIEW_METRICS : SUBPART_METRICS;
+        const valid = Object.keys(registry);
+        for (const metric of Object.keys(metrics)) {
+          if (valid.includes(metric)) continue;
+          const hint = suggest(metric, valid);
+          out.push(err("verify-unknown-metric",
+            `"${metric}" is not a ${target === "_view" ? "view" : "sub-part"} metric`,
+            `Valid ${target === "_view" ? "view" : "sub-part"} metrics are: ${valid.join(", ")}${hint ? ` — did you mean "${hint}"?` : "."}`,
+            `verify.expect.${target}.${metric}`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "verify-bad-expr",
+    run: ({ resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      if (!expect || typeof expect !== "object") return [];
+      const out = [];
+      for (const [target, metricsRaw] of Object.entries(expect)) {
+        if (!metricsRaw || typeof metricsRaw !== "object") continue;
+        // `contacts` is pair arrays with no expression to parse, and `clearance`'s
+        // values are keyed by pair name rather than metric name — both are peeled
+        // from this scalar-metric loop. `clearance`'s values are still assertions
+        // though, so they get their own pass (with a pair-shaped path) below.
+        const metrics = target === "_view" ? peelPairKeys(metricsRaw) : metricsRaw;
+        for (const [metric, spec] of Object.entries(metrics)) {
+          try { parseAssertion(exprOf(spec)); }
+          catch (e) {
+            out.push(err("verify-bad-expr",
+              `the expectation for ${target}.${metric} is not a valid assertion: ${e?.message || String(e)}`,
+              "Use the assertion DSL: a bare value for equality, a comparison like `>=3`, a range like `2..5`, or a componentwise vector like `<=[60,60,60]` (with `*` to skip an axis).",
+              `verify.expect.${target}.${metric}`));
+          }
+        }
+      }
+      out.push(...checkClearanceExprs(expect?._view?.clearance, "verify.expect._view.clearance"));
+      return out;
+    },
+  },
+  {
+    id: "verify-bad-pair-check",
+    run: ({ part, resolveExpectOnce }) => {
+      const { expect } = resolveExpectOnce();
+      const view = expect?._view;
+      if (!view || typeof view !== "object") return [];
+      const names = Object.keys(part?.parts ?? {});
+      return [
+        ...checkContacts(view.contacts, names, "verify.expect._view.contacts"),
+        ...checkClearance(view.clearance, names, "verify.expect._view.clearance"),
+      ];
+    },
+  },
+  {
+    id: "verify-unknown-process",
+    run: ({ part }) => {
+      const process = part?.verify?.process;
+      // verify.js:163-164 — `profileSpec ?? part.verify?.process` then
+      // `profileSpec ? resolveProfile(profileSpec) : null` — that second check is
+      // truthiness, not a null/undefined check, so ANY falsy `process` (undefined,
+      // null, "", 0, false) never reaches `resolveProfile` and can't throw.
+      if (!process) return [];
+      const valid = Object.keys(PROFILES);
+      return checkProcessSpec(process, "verify.process", valid, new Set());
+    },
+  },
+];

package/src/framework/mount.js

@@ -3,6 +3,7 @@ import { triggerDownload, downloadParts } from "./download.js";
 import { createViewer } from "./viewer.js";
 import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
+import { attachRail } from "./rail.js";
 import { createTooltipPresenter } from "./tooltip.js";
 import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
@@ -68,6 +69,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
   const els = {
     viewer: elements.viewer ?? legacyContainer ?? byId("app"),
     controls: elements.controls ?? legacyControls ?? byId("controls"),
+    rail: elements.rail ?? byId("panel"),
+    // No id fallback: attachRail defaults shell to rail.parentElement, which is
+    // right for the standard markup (rail is a direct child of .pf-shell). A
+    // host that wraps its rail in an extra element (e.g. a React layout div)
+    // must pass this explicitly, or the seam ends up positioned against the
+    // wrong ancestor. Left undefined (not null) when unsupplied so rail.js's
+    // own default still applies.
+    shell: elements.shell,
     status: {
       status: elements.status?.status ?? byId("status"),
       busy: elements.status?.busy ?? byId("busy"),
@@ -84,6 +93,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
       reframe: elements.chrome?.reframe ?? byId("reframe"),
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
+      railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
     },
   };
 
@@ -97,6 +107,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick,
       cutaway: els.chrome.cutaway,
     }, { tooltip });
     cleanup.defer(() => cutawayChrome.detach());
+    // Resizable/collapsible controls rail. No-ops when the host lays out the
+    // framework itself (no #panel / no elements.rail).
+    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell });
+    cleanup.defer(() => railChrome.detach());
     const hover = attachHoverLabels(viewer, { part, tooltip }); // always-on hover inspection (no-op on touch-only devices)
     cleanup.defer(() => hover.detach());
     const ui = createStatusUi({ ...els.status, exports: [els.exports.stl, els.exports.step, els.exports.threeMf] });

package/src/framework/rail-state.js

@@ -0,0 +1,73 @@
+// Pure state for the controls rail: width clamping, the drag state machine
+// (including snap-to-collapsed), and the stored preference. No DOM here on
+// purpose — this is the part worth testing exhaustively, and a pointer drag in a
+// headless DOM proves very little (scripts/check-app.mjs covers that path in
+// real Chromium).
+//
+// Mirror image of partforge-cloud's left-hand chat pane: this rail is on the
+// RIGHT, so callers convert a pointer position into an intended rail WIDTH
+// (shellRect.right - clientX, grab-offset corrected) before calling in. Nothing
+// here ever sees a raw clientX.
+export const RAIL_DEFAULT_WIDTH = 288;
+export const RAIL_MIN_WIDTH = 240; // a slider label + its numeric field, still readable
+export const RAIL_MAX_WIDTH = 560;
+// Two thresholds rather than one: the 60px between them is hysteresis, so a
+// shaky hand at the boundary can't flap the rail open and shut. Kept
+// PROPORTIONAL to RAIL_MIN_WIDTH (58%-83%) rather than copying the cloud's
+// literals, which are sized against its wider 280px floor.
+export const RAIL_COLLAPSE_AT = 140;
+export const RAIL_REOPEN_AT = 200;
+// Below this the rail stacks under the viewer and resize is absent entirely.
+export const RAIL_NARROW_BREAKPOINT = 720;
+export const RAIL_STORAGE_KEY = "partforge:rail";
+
+// The rail may never take more than half the shell, so the viewer can't be
+// squeezed narrower than the rail. Floored at RAIL_MIN_WIDTH so the function
+// stays total (and max >= min) for a transient zero-width measurement.
+export function railMaxWidth(shellWidth) {
+  const half = Number.isFinite(shellWidth) ? Math.floor(shellWidth / 2) : RAIL_MAX_WIDTH;
+  return Math.max(RAIL_MIN_WIDTH, Math.min(RAIL_MAX_WIDTH, half));
+}
+
+export function clampRailWidth(width, shellWidth) {
+  const w = Number.isFinite(width) ? Math.round(width) : RAIL_DEFAULT_WIDTH;
+  return Math.min(railMaxWidth(shellWidth), Math.max(RAIL_MIN_WIDTH, w));
+}
+
+// railX is the pointer's intended rail width. Returns the SAME state object
+// when nothing changes, so a caller can cheaply skip redundant DOM writes.
+export function resolveRailDrag(railX, state, shellWidth) {
+  const open = () => ({ collapsed: false, width: clampRailWidth(railX, shellWidth) });
+  if (state.collapsed) {
+    // Reopening takes a deliberate push past the far threshold.
+    return railX < RAIL_REOPEN_AT ? state : open();
+  }
+  // Collapsing keeps the last open width, so the toggle restores it later.
+  if (railX < RAIL_COLLAPSE_AT) return { collapsed: true, width: state.width };
+  return open();
+}
+
+export function readRailPref(storage, shellWidth) {
+  const fallback = { width: RAIL_DEFAULT_WIDTH, collapsed: false };
+  let raw;
+  try { raw = storage.getItem(RAIL_STORAGE_KEY); } catch { return fallback; }
+  if (!raw) return fallback;
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return fallback; }
+  if (!parsed || typeof parsed !== "object") return fallback;
+  return {
+    // Re-clamp on read: a width saved on a wide monitor must not leave a laptop
+    // with a 560px rail and no room for the viewer.
+    width: clampRailWidth(parsed.width, shellWidth),
+    collapsed: parsed.collapsed === true,
+  };
+}
+
+export function writeRailPref(state, storage) {
+  try {
+    storage.setItem(RAIL_STORAGE_KEY, JSON.stringify({
+      width: state.width,
+      collapsed: state.collapsed,
+    }));
+  } catch { /* storage unavailable — no-op, matching view-state.js */ }
+}