partforge 0.27.0 → 0.31.0

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 */ }
+}

package/src/framework/rail.js

@@ -0,0 +1,321 @@
+import {
+  RAIL_DEFAULT_WIDTH, RAIL_MIN_WIDTH, RAIL_NARROW_BREAKPOINT,
+  clampRailWidth, railMaxWidth, readRailPref, resolveRailDrag, writeRailPref,
+} from "./rail-state.js";
+
+const KEY_STEP = 16;
+const KEY_STEP_SHIFT = 64;
+// A held arrow-key repeat must not animate either, so the suppression flag
+// covers the whole repeat window rather than just the instant of a keydown.
+const KEY_SETTLE_MS = 200;
+
+// lucide v1.25.0 `panel-right-close` / `panel-right-open` node data (ISC
+// licence) - inlined rather than adding an icon-library dependency for two
+// paths. Both icons share the same 18x18 rounded rect and vertical divider at
+// x=15; they differ only in the chevron, so the SVG is built once (below) and
+// only this `d` is swapped on state change.
+const SVG_NS = "http://www.w3.org/2000/svg";
+// panel-right-close: rail OPEN, chevron points right (toward the divider) -
+// clicking pushes the rail shut.
+const CHEVRON_RAIL_OPEN = "m8 9 3 3-3 3";
+// panel-right-open: rail COLLAPSED, chevron points left (away from the
+// divider) - clicking pulls the rail back open.
+const CHEVRON_RAIL_COLLAPSED = "m10 15-3-3 3-3";
+
+// Builds the toggle's icon once; apply() swaps the returned chevron path's
+// `d` between CHEVRON_RAIL_OPEN and CHEVRON_RAIL_COLLAPSED. `stroke="currentColor"`
+// is load-bearing: it's how the icon inherits the button's themed colour and
+// its `.on` active state for free, with no icon-specific CSS anywhere.
+function buildToggleIcon() {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("width", "16");
+  svg.setAttribute("height", "16");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("stroke-width", "2");
+  svg.setAttribute("stroke-linecap", "round");
+  svg.setAttribute("stroke-linejoin", "round");
+  svg.setAttribute("aria-hidden", "true");
+
+  const rect = document.createElementNS(SVG_NS, "rect");
+  rect.setAttribute("width", "18");
+  rect.setAttribute("height", "18");
+  rect.setAttribute("x", "3");
+  rect.setAttribute("y", "3");
+  rect.setAttribute("rx", "2");
+  svg.append(rect);
+
+  const divider = document.createElementNS(SVG_NS, "path");
+  divider.setAttribute("d", "M15 3v18");
+  svg.append(divider);
+
+  const chevron = document.createElementNS(SVG_NS, "path");
+  svg.append(chevron);
+
+  return { svg, chevron };
+}
+
+// Touching the localStorage PROPERTY can throw (opaque origin, blocked site
+// data) — not just its methods. view-state.js guards it the same way; the
+// framework runs in an iframe in production, where this is reachable.
+function safeStorage() {
+  try { return globalThis.localStorage ?? null; } catch { return null; }
+}
+
+// Make the controls rail resizable and collapsible, with partforge-cloud's seam
+// affordance: a 12px hit target holding a pill that is invisible until hover,
+// keyboard focus, or a drag.
+//
+// The seam is created here, so no host markup declares it. Width is written
+// straight onto :root as --pf-rail-w during a drag with no state layer in
+// between: every width change resizes the viewer, whose ResizeObserver
+// reallocates the WebGL drawing buffer. One reallocation per frame is inherent
+// to live resizing; anything on top of it is not.
+//
+// Everything is optional. With no rail this returns a no-op, so hosts that lay
+// the framework out themselves (see embed-test.html) are unaffected.
+export function attachRail({ rail, toggle, shell = rail?.parentElement, storage = safeStorage() } = {}) {
+  if (!rail || !shell) {
+    // No rail to resolve in this document: --pf-rail-w still defaults to 288px
+    // from tokens.css, but nothing is reserving that space, so anything that
+    // reads the token to centre itself against the rail (app.css's
+    // #pf-pick-banner) would otherwise sit 144px off-centre for no reason.
+    // Zero is the truth here — a legacy id-only page or a custom host running
+    // ?pickserver with no #panel/elements.rail hits this path.
+    const root = document.documentElement;
+    root.style.setProperty("--pf-rail-w", "0px");
+    return { detach: () => root.style.removeProperty("--pf-rail-w") };
+  }
+
+  const root = document.documentElement;
+  const shellBox = () => shell.getBoundingClientRect();
+  const shellWidth = () => shellBox().width;
+  let state = readRailPref(storage, shellWidth());
+  // Captured before the first apply() mutates the toggle, so detach() can
+  // hand back a plain, unwired button rather than a dead "Show controls" one.
+  // innerHTML (not textContent) so a host's original content - markup, not
+  // just text - genuinely round-trips; the icon apply() writes is markup too.
+  const toggleOriginal = toggle ? { html: toggle.innerHTML, title: toggle.title } : null;
+  // Built once here rather than inside apply() (which reruns on every resize/
+  // key/drag tick); apply() only ever swaps toggleChevron's `d`.
+  let toggleChevron = null;
+  if (toggle) {
+    const { svg, chevron } = buildToggleIcon();
+    toggle.replaceChildren(svg);
+    toggleChevron = chevron;
+  }
+
+  const seam = document.createElement("div");
+  seam.className = "pf-rail-seam";
+  seam.setAttribute("role", "separator");
+  seam.setAttribute("aria-orientation", "vertical");
+  seam.setAttribute("aria-label", "Resize controls");
+  seam.setAttribute("aria-valuemin", "0");
+  seam.tabIndex = 0;
+  seam.append(document.createElement("span")); // the hover/focus affordance
+  rail.before(seam);
+
+  // shellW lets a caller that already measured the shell this frame (the
+  // pointermove handler) thread that width through instead of forcing a
+  // second synchronous layout here — apply() writes --pf-rail-w onto :root
+  // just below, so any un-measured read after that point is a style+layout
+  // flush, not a cached value.
+  function apply({ persist = false, shellW } = {}) {
+    const sw = shellW ?? shellWidth();
+    const width = state.collapsed ? 0 : clampRailWidth(state.width, sw);
+    // Written on :root, not the rail/shell, so body-appended overlays (the
+    // pick banner, the ?debug overlay) inherit it — see spec §4.4. This
+    // assumes ONE rail per document: attachRail is written for a single
+    // instance, and mounting two on one page would fight over --pf-rail-w
+    // (both write :root; whichever's detach() runs last wins, clearing the
+    // survivor's width too). README's "multiple mounts" claim is about
+    // multiple mount() calls in general (e.g. cross-fade swaps), which is
+    // fine as long as at most one has a resolvable rail at a time.
+    root.style.setProperty("--pf-rail-w", `${width}px`);
+    rail.toggleAttribute("inert", state.collapsed);
+    seam.toggleAttribute("data-collapsed", state.collapsed);
+    seam.setAttribute("aria-valuenow", String(width));
+    seam.setAttribute("aria-valuemax", String(railMaxWidth(sw)));
+    if (toggle) {
+      toggleChevron?.setAttribute("d", state.collapsed ? CHEVRON_RAIL_COLLAPSED : CHEVRON_RAIL_OPEN);
+      const label = state.collapsed ? "Show controls" : "Hide controls";
+      toggle.setAttribute("aria-expanded", String(!state.collapsed));
+      toggle.setAttribute("aria-label", label);
+      toggle.title = label;
+      toggle.classList.toggle("on", state.collapsed);
+    }
+    if (persist) writeRailPref(state, storage);
+  }
+
+  // --- discrete changes: animate, and commit immediately ---
+  // The same "transient, debounced" flag suppresses the width transition for
+  // both a held arrow-key repeat and a window resize (below) — either can
+  // fire several times in a burst, and an animated width would fight the
+  // last one before the previous animation finishes.
+  let keyTimer = 0;
+  function settleKeys() {
+    clearTimeout(keyTimer);
+    shell.removeAttribute("data-pf-key-resizing");
+  }
+  function markTransientResize() {
+    shell.toggleAttribute("data-pf-key-resizing", true);
+    clearTimeout(keyTimer);
+    keyTimer = setTimeout(settleKeys, KEY_SETTLE_MS);
+  }
+  function commit(next) {
+    settleKeys(); // a discrete change interrupting a key repeat animates normally
+    state = next;
+    apply({ persist: true });
+  }
+  const toggleCollapsed = () => commit({ collapsed: !state.collapsed, width: state.width });
+
+  // --- keyboard: move the SEPARATOR (standard role="separator" semantics), so
+  // ArrowLeft widens a right-hand rail. Arrows clamp at the minimum and never
+  // collapse; Enter/Space is the collapse gesture.
+  function onKeyDown(e) {
+    // Cmd/Alt/Ctrl+Arrow are browser/OS reserved (back, tab switch, ...); don't
+    // eat them just because the seam happens to hold focus.
+    if (e.metaKey || e.altKey || e.ctrlKey) return;
+    // Enter/Space is the deliberate reopen gesture (below); arrows must not
+    // also reopen a collapsed rail — that would clamp it to the 240px minimum
+    // and silently discard the remembered width, and "narrower" reopening the
+    // rail at all is backwards.
+    if (state.collapsed && (e.key === "ArrowLeft" || e.key === "ArrowRight")) return;
+    const step = e.shiftKey ? KEY_STEP_SHIFT : KEY_STEP;
+    // Re-clamp on READ rather than reconciling state.width on resize: a width
+    // that no longer fits the current shell is still the user's preference and
+    // should come back if the window grows again, so only the transient value
+    // used for this keypress is clamped.
+    const from = state.collapsed ? 0 : clampRailWidth(state.width, shellWidth());
+    let width;
+    switch (e.key) {
+      case "ArrowLeft": width = from + step; break;
+      case "ArrowRight": width = from - step; break;
+      case "Home": case "End": {
+        e.preventDefault();
+        // Route through commit() — the path onDoubleClick uses — so these
+        // jumps animate. Only a debounced arrow-key repeat (below) suppresses
+        // the width transition.
+        commit({
+          collapsed: false,
+          width: e.key === "Home" ? RAIL_MIN_WIDTH : railMaxWidth(shellWidth()),
+        });
+        return;
+      }
+      case "Enter": case " ": e.preventDefault(); toggleCollapsed(); return;
+      default: return;
+    }
+    e.preventDefault();
+    state = { collapsed: false, width: clampRailWidth(width, shellWidth()) };
+    shell.toggleAttribute("data-pf-key-resizing", true);
+    clearTimeout(keyTimer);
+    keyTimer = setTimeout(() => {
+      shell.removeAttribute("data-pf-key-resizing");
+      writeRailPref(state, storage);
+    }, KEY_SETTLE_MS);
+    apply();
+  }
+
+  const onDoubleClick = () => commit({ collapsed: false, width: RAIL_DEFAULT_WIDTH });
+  const onToggleClick = () => toggleCollapsed();
+
+  // --- drag ---
+  let grabOffset = 0;
+  function onPointerDown(e) {
+    if (e.button !== 0) return;
+    // Stacked layout: the rail is under the viewer, so there is no vertical seam
+    // to drag (chrome.css hides it). The toggle still works.
+    if (window.innerWidth < RAIL_NARROW_BREAKPOINT) return;
+    e.preventDefault();
+    // setPointerCapture is load-bearing: without it the pointer crosses into the
+    // viewer (an iframe, in the cloud editor) whose document eats the move
+    // events, and the drag dies the moment it reaches the thing being resized.
+    seam.setPointerCapture?.(e.pointerId);
+    const box = seam.getBoundingClientRect();
+    // Where inside the 12px seam the grab landed, so the rail edge doesn't jump.
+    grabOffset = e.clientX - (box.left + box.width / 2);
+    shell.toggleAttribute("data-pf-dragging", true);
+    // Safety net: setPointerCapture is load-bearing (see above), but it is
+    // still an optional call — if it's unavailable or the browser fails to
+    // honour it, the pointerup can land on the canvas instead of the seam,
+    // onPointerUp never runs, data-pf-dragging is stuck forever, and
+    // chrome.css's [data-pf-dragging] .pf-stage { pointer-events: none } dead-
+    // locks the viewer with no recovery. Also listening on window guarantees
+    // the drag always terminates regardless of where the pointer ends up.
+    // Bound only for the duration of a drag (removed in onPointerUp/detach)
+    // so there is never a permanently-bound window listener.
+    window.addEventListener("pointerup", onPointerUp);
+    window.addEventListener("pointercancel", onPointerUp);
+  }
+  function onPointerMove(e) {
+    if (!shell.hasAttribute("data-pf-dragging")) return;
+    // Measure the shell once per move and thread it through resolveRailDrag
+    // and apply(), instead of re-measuring after apply() has already mutated
+    // :root's style (which would force a synchronous style+layout flush).
+    const box = shellBox();
+    const railX = box.right - (e.clientX - grabOffset);
+    const next = resolveRailDrag(railX, state, box.width);
+    if (next === state) return; // unchanged — skip the redundant DOM writes
+    state = next;
+    apply({ shellW: box.width });
+  }
+  function onPointerUp(e) {
+    // Guards against running end-of-drag logic twice for one gesture: whichever
+    // of the seam's own pointerup and the window safety-net fires first clears
+    // the attribute, so the second (if it fires at all) is a no-op.
+    if (!shell.hasAttribute("data-pf-dragging")) return;
+    seam.releasePointerCapture?.(e.pointerId);
+    shell.removeAttribute("data-pf-dragging");
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerUp);
+    apply({ persist: true });
+  }
+
+  seam.addEventListener("pointerdown", onPointerDown);
+  seam.addEventListener("pointermove", onPointerMove);
+  seam.addEventListener("pointerup", onPointerUp);
+  seam.addEventListener("pointercancel", onPointerUp);
+  seam.addEventListener("keydown", onKeyDown);
+  seam.addEventListener("dblclick", onDoubleClick);
+  toggle?.addEventListener("click", onToggleClick);
+  // A window resize can invalidate the clamp (max is half the shell). Narrowing
+  // the window with a maxed-out rail can genuinely change --pf-rail-w, and
+  // without suppression that change would animate — fighting the resize with
+  // a trailing 150ms transition and an extra WebGL buffer reallocation.
+  const onResize = () => {
+    markTransientResize();
+    apply();
+  };
+  window.addEventListener("resize", onResize);
+
+  apply();
+
+  return {
+    detach: () => {
+      settleKeys();
+      seam.removeEventListener("pointerdown", onPointerDown);
+      seam.removeEventListener("pointermove", onPointerMove);
+      seam.removeEventListener("pointerup", onPointerUp);
+      seam.removeEventListener("pointercancel", onPointerUp);
+      seam.removeEventListener("keydown", onKeyDown);
+      seam.removeEventListener("dblclick", onDoubleClick);
+      toggle?.removeEventListener("click", onToggleClick);
+      window.removeEventListener("resize", onResize);
+      // In case detach() happens mid-drag, so the safety net doesn't outlive it.
+      window.removeEventListener("pointerup", onPointerUp);
+      window.removeEventListener("pointercancel", onPointerUp);
+      seam.remove();
+      shell.removeAttribute("data-pf-dragging");
+      rail.removeAttribute("inert");
+      root.style.removeProperty("--pf-rail-w");
+      if (toggle) {
+        toggle.innerHTML = toggleOriginal.html;
+        toggle.title = toggleOriginal.title;
+        toggle.removeAttribute("aria-expanded");
+        toggle.removeAttribute("aria-label");
+        toggle.classList.remove("on");
+      }
+    },
+  };
+}

package/src/framework/tokens.css

@@ -7,7 +7,19 @@
   --pf-text: oklch(0.985 0 0); --pf-text-strong: oklch(1 0 0); --pf-text-2: oklch(0.92 0.004 286.32);
   --pf-muted: oklch(0.705 0.015 286.067); --pf-muted-2: oklch(0.80 0.01 286); --pf-status: oklch(0.705 0.015 286.067); --pf-hint: oklch(0.552 0.016 285.938);
   --pf-accent: #3f7bf0; --pf-accent-soft: #26314a; --pf-on-accent: #fff; --pf-input-bg: oklch(0.165 0.009 262); --pf-err: oklch(0.704 0.191 22.216);
-  --pf-mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+  --pf-sans: "Geist Variable", system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --pf-mono: "Geist Mono Variable", ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+  /* Layout + shape, matching partforge-cloud's control scale (--r-control /
+     --r-pill) so a rail nested in the cloud editor reads as one product. */
+  --pf-rail-w: 288px; --pf-rail-pad: 14px;
+  --pf-radius-control: 7px; --pf-radius-pill: 12px;
+  /* Floating pills: cloud's --shadow-editor. Larger and near-even, so a pill
+     doesn't pool weight at its bottom edge the way a downward shadow does. */
+  --pf-shadow-float: 0 0 6px rgb(0 0 0 / .04), 0 2px 14px rgb(0 0 0 / .072);
+  /* The rail is SET BACK: the viewer casts onto it, so this is inset on the
+     rail's left edge. An outer shadow would read as the rail floating above the
+     viewer — the opposite. Deeper in dark, where black reads weaker. */
+  --pf-shadow-rail: inset 9px 0 16px -10px rgb(0 0 0 / .38);
 }
 :root[data-theme="light"] {
   color-scheme: light;
@@ -15,4 +27,5 @@
   --pf-text: oklch(0.141 0.005 285.823); --pf-text-strong: oklch(0.10 0.005 285.823); --pf-text-2: oklch(0.21 0.006 285.885);
   --pf-muted: oklch(0.552 0.016 285.938); --pf-muted-2: oklch(0.44 0.015 285.9); --pf-status: oklch(0.552 0.016 285.938); --pf-hint: oklch(0.705 0.015 286.067);
   --pf-accent: #1f5bd6; --pf-accent-soft: #e6edfc; --pf-on-accent: #fff; --pf-input-bg: #ffffff; --pf-err: oklch(0.577 0.245 27.325);
+  --pf-shadow-rail: inset 9px 0 14px -10px rgb(0 0 0 / .12);
 }