partforge 0.26.1 → 0.28.0

package/src/framework/app.css

@@ -6,42 +6,63 @@
    accent, shadcn-shaped radii/shadows/focus rings — plain CSS on --pf-*.
    See docs/AUTHORING-PARTS.md. */
 @import "./tokens.css"; /* palette + light overrides; also exported standalone as partforge/tokens.css */
+@import "./chrome.css";  /* reusable layout; also exported as partforge/chrome.css */
 
 * { box-sizing: border-box; }
 html, body { margin: 0; height: 100%; overflow: hidden;
-  font: 13px/1.4 -apple-system, system-ui, sans-serif; }
-#app { position: fixed; inset: 0; background: var(--pf-bg); }
+  font: 13px/1.4 var(--pf-sans); }
+/* Legacy fallback: a page whose markup predates .pf-stage keeps the old
+   full-window viewer. :not() rather than a plain #app rule because an id would
+   outrank .pf-stage's positioning and win the cascade. */
+#app:not(.pf-stage) { position: fixed; inset: 0; background: var(--pf-bg); }
 canvas { display: block; }
 
-#panel {
+/* Legacy fallback: the pre-rail floating card, for markup without .pf-rail. */
+#panel:not(.pf-rail) {
   position: fixed; top: 12px; left: 12px; width: 256px;
   max-height: calc(100vh - 24px); overflow-y: auto; z-index: 10;
   background: var(--pf-surface); border: 1px solid var(--pf-border); border-radius: 16px;
   padding: 14px; color: var(--pf-text);
-  /* shadow-lg, matching the partforge-cloud chat pane so the two floating
-     panes read as siblings (was the smaller shadow-md). */
-  box-shadow: 0 10px 15px -3px rgb(0 0 0 / .1), 0 4px 6px -4px rgb(0 0 0 / .1);
+  box-shadow: var(--pf-shadow-float);
 }
+/* Legacy fallback only: pre-rail markup has a bare <h1>/.sub directly inside
+   #panel, with no .pf-rail-head wrapper, so chrome.css's classed
+   .pf-rail-head h1/.sub rule (the single source of truth for that typography)
+   can't reach it — chrome.css is deliberately id-free (see test/tokens.test.js)
+   so this id-scoped restatement has to live here instead. Classed markup never
+   hits this rule (its h1 is inside .pf-rail-head, already styled by
+   chrome.css); keep the two in sync if the typography ever changes. */
 #panel h1 { font-size: 14px; margin: 0 0 2px; color: var(--pf-text-strong); letter-spacing: -0.01em; }
 #panel .sub {
   font-family: var(--pf-mono); color: var(--pf-muted); font-size: 10px;
   letter-spacing: 0.04em; text-transform: uppercase;
-  margin: 0 0 12px; padding-bottom: 12px; border-bottom: 1px solid var(--pf-border);
+  margin: 2px 0 0;
 }
 
 .seg { display: flex; gap: 2px; margin-bottom: 12px;
-  background: var(--pf-surface-2); border-radius: 10px; padding: 3px; }
+  background: var(--pf-surface-2); border-radius: var(--pf-radius-control); padding: 3px; }
 .seg button {
-  flex: 1; padding: 6px 0; border: 0; border-radius: 8px;
+  flex: 1; padding: 6px 0; border: 0; border-radius: var(--pf-radius-control);
   background: transparent; color: var(--pf-muted); cursor: pointer;
   font-family: var(--pf-mono); font-size: 11px; letter-spacing: 0.02em;
 }
 .seg button:hover { color: var(--pf-text-2); }
 .seg button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
 
+/* Full-bleed rows: the divider spans the rail's whole width while the content
+   sits at the rail's own padding, so each slider gains the ~22px the old box
+   border + padding used to take from both sides. */
 .section {
-  border: 1px solid var(--pf-border); border-radius: 10px; padding: 10px;
-  margin-bottom: 8px; background: var(--pf-surface-2);
+  padding: 11px var(--pf-rail-pad);
+}
+/* Divider BETWEEN visible sections. `~` walks all preceding siblings, and a
+   relevance-hidden section (.section-hidden, display:none) fails the :not(),
+   so the topmost VISIBLE section never draws a hairline under the rail header.
+   Do not simplify this to `.section:first-child { border-top: 0 }` — that
+   matches DOM position rather than visibility, and leaves a stray divider
+   floating at the top whenever applyRelevance hides the first section. */
+.section:not(.section-hidden) ~ .section:not(.section-hidden) {
+  border-top: 1px solid var(--pf-border);
 }
 .sec-title {
   font-family: var(--pf-mono); font-size: 10px; font-weight: 600;
@@ -49,13 +70,13 @@ canvas { display: block; }
 }
 select.preset {
   width: 100%; background: var(--pf-input-bg); color: var(--pf-text-2);
-  border: 1px solid var(--pf-border); border-radius: 8px; padding: 7px 9px;
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 7px 9px;
   font-family: var(--pf-mono); font-size: 11px;
 }
 .feat { display: flex; align-items: center; gap: 8px; margin: 6px 0;
   color: var(--pf-text-2); cursor: pointer; }
 .feat input { cursor: pointer; accent-color: var(--pf-accent); }
-.feat-group { margin: 2px 0 8px; padding-left: 10px; border-left: 2px solid var(--pf-border); }
+.feat-group { margin: 2px 0 8px; padding-left: 10px; border-left: 1px solid var(--pf-border); }
 .feat-group.hidden { display: none; }
 .adv-toggle {
   margin-top: 8px; padding: 4px 0; width: 100%; border: 0; border-radius: 6px;
@@ -74,7 +95,7 @@ select.preset {
 .row .num {
   width: 54px; text-align: right; font-family: var(--pf-mono); font-size: 12px; font-variant-numeric: tabular-nums;
   background: var(--pf-input-bg); color: var(--pf-text-strong);
-  border: 1px solid var(--pf-border); border-radius: 6px; padding: 3px 6px;
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 3px 6px;
 }
 .row .num:focus { outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
@@ -84,7 +105,7 @@ select.preset {
 .text-input {
   display: block; width: 100%; font: 12px/1.4 var(--pf-mono);
   background: var(--pf-input-bg); color: var(--pf-text-strong);
-  border: 1px solid var(--pf-border); border-radius: 6px; padding: 6px 8px;
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 6px 8px;
 }
 textarea.text-input { min-height: 64px; resize: vertical; }
 .text-input:focus { outline: none; border-color: var(--pf-accent);
@@ -97,12 +118,12 @@ input[type="range"]::-moz-range-track { height: 3px; border-radius: 2px; backgro
 input[type="range"]::-moz-range-progress { height: 3px; border-radius: 2px; background: var(--pf-accent); }
 input[type="range"]::-webkit-slider-thumb {
   -webkit-appearance: none; appearance: none; width: 14px; height: 14px; margin-top: -5.5px;
-  border-radius: 50%; background: var(--pf-accent); border: 2px solid var(--pf-surface-2); box-shadow: 0 0 0 1px var(--pf-accent);
+  border-radius: 50%; background: var(--pf-accent); border: 2px solid var(--pf-surface); box-shadow: 0 0 0 1px var(--pf-accent);
   transition: box-shadow .12s ease;
 }
 input[type="range"]::-moz-range-thumb {
   width: 14px; height: 14px; border-radius: 50%; background: var(--pf-accent);
-  border: 2px solid var(--pf-surface-2); box-shadow: 0 0 0 1px var(--pf-accent);
+  border: 2px solid var(--pf-surface); box-shadow: 0 0 0 1px var(--pf-accent);
 }
 input[type="range"]:hover::-webkit-slider-thumb { box-shadow: 0 0 0 5px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 input[type="range"]:focus-visible { outline: none; }
@@ -110,7 +131,7 @@ input[type="range"]:focus-visible::-webkit-slider-thumb { box-shadow: 0 0 0 5px
 input[type="range"]:focus-visible::-moz-range-thumb { box-shadow: 0 0 0 5px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
 button.action {
-  width: 100%; margin-top: 8px; padding: 9px; border: 0; border-radius: 8px;
+  width: 100%; margin-top: 8px; padding: 9px; border: 0; border-radius: var(--pf-radius-control);
   background: var(--pf-accent); color: var(--pf-on-accent); font-weight: 500; cursor: pointer;
 }
 button.action:hover:not(:disabled) { background: color-mix(in oklab, var(--pf-accent) 90%, black); }
@@ -125,7 +146,7 @@ button.action:disabled { opacity: .5; cursor: default; }
 }
 .dl-row { display: flex; gap: 6px; }
 .dl-row button {
-  flex: 1; padding: 8px 0; border: 1px solid var(--pf-border); border-radius: 8px;
+  flex: 1; padding: 8px 0; border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control);
   background: transparent; color: var(--pf-text-2);
   font-family: var(--pf-mono); font-weight: 600; font-size: 11px; letter-spacing: 0.06em; cursor: pointer;
 }
@@ -143,28 +164,28 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
 
-/* part tabs, floated top-centre over the viewport */
-#topbar {
-  position: fixed; top: 12px; left: 50%; transform: translateX(-50%);
-  z-index: 15;
-}
+/* part tabs (placement: .pf-float-tabs; legacy markup keeps the old float) */
+#topbar:not(.pf-float-tabs) { position: fixed; top: 12px; left: 50%; transform: translateX(-50%); z-index: 15; }
 #topbar .seg {
   margin: 0; padding: 4px; background: var(--pf-surface); border: 1px solid var(--pf-border);
-  border-radius: 14px;
-  box-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);
+  border-radius: var(--pf-radius-pill);
+  box-shadow: var(--pf-shadow-float);
 }
 #topbar .seg button { min-width: 70px; padding: 7px 10px; }
 
-/* viewer controls, top-right */
+/* viewer controls. APPEARANCE is ungated: partforge-cloud re-anchors #viewbar's
+   position in sandbox.css but inherits this pill chrome, so gating it on a class
+   the cloud never sets would strip the editor's viewbar. PLACEMENT comes from
+   .pf-float-viewbar; the :not() keeps legacy markup's old top-right float. */
 #viewbar {
-  position: fixed; top: 12px; right: 12px; z-index: 15;
   display: flex; gap: 4px; padding: 4px;
   background: var(--pf-surface); border: 1px solid var(--pf-border);
-  border-radius: 14px;
-  box-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);
+  border-radius: var(--pf-radius-pill);
+  box-shadow: var(--pf-shadow-float);
 }
+#viewbar:not(.pf-float-viewbar) { position: fixed; top: 12px; right: 12px; z-index: 15; }
 #viewbar button {
-  width: 34px; height: 34px; border: 0; border-radius: 10px;
+  width: 34px; height: 34px; border: 0; border-radius: var(--pf-radius-control);
   background: transparent; color: var(--pf-muted-2); cursor: pointer;
   font-size: 15px; line-height: 1;
   display: flex; align-items: center; justify-content: center;
@@ -177,16 +198,36 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
 #viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
 
+/* At very narrow widths the full-size pill (5 icon buttons + cutaway's
+   Flip/Reset, ~314px) is wider than a small phone's viewport minus the
+   stage's 12px margins, and .pf-shell { overflow: hidden } clips the excess
+   off its left edge (caught by scripts/check-app.mjs's containment check).
+   Shrink the pill instead of letting it wrap — a two-row pill would need its
+   own anchoring rework, while shrinking is a pure appearance change. */
+@media (max-width: 360px) {
+  #viewbar { gap: 3px; }
+  #viewbar button { width: 30px; height: 30px; font-size: 13px; }
+  #viewbar .pf-cutaway-actions { gap: 3px; }
+  #viewbar .pf-cutaway-actions button { min-width: 44px; padding: 0 6px; }
+}
+
+/* Legacy id-only markup only: classed markup's viewbar lives inside .pf-stage
+   (bottom-right, see chrome.css's .pf-float-viewbar) so it never meets the
+   top-left floating #panel card. Legacy markup still floats #viewbar top-right
+   and #panel top-left (both `position: fixed`), which collide once the window
+   gets narrow enough — restore the old narrow-width rule that moves #viewbar
+   to bottom-centre and gives #panel room, scoped with :not(.pf-*) so it can't
+   affect the new layout. */
 @media (max-width: 680px) {
-  #panel { max-height: calc(100vh - 80px); }
-  #viewbar {
+  #panel:not(.pf-rail) { max-height: calc(100vh - 80px); }
+  #viewbar:not(.pf-float-viewbar) {
     top: auto; right: auto; bottom: 12px; left: 50%;
     transform: translateX(-50%);
   }
 }
 
 #busy {
-  position: fixed; inset: 0; z-index: 20; pointer-events: none;
+  position: absolute; inset: 0; z-index: 20; pointer-events: none;
   display: none; flex-direction: column; align-items: center;
   justify-content: center; gap: 14px;
 }
@@ -211,8 +252,8 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 .popover {
   position: fixed; z-index: 50; max-width: 280px; max-height: 50vh; overflow: auto;
   background: var(--pf-surface); color: var(--pf-text); border: 1px solid var(--pf-border);
-  border-radius: 14px; padding: 10px 12px;
-  box-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);
+  border-radius: var(--pf-radius-pill); padding: 10px 12px;
+  box-shadow: var(--pf-shadow-float);
   font-size: 12px; line-height: 1.5;
 }
 .popover[hidden] { display: none; }
@@ -246,12 +287,12 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 /* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
    laid out like a chat message (avatar + text). Slides/fades in when shown; themed. */
 #pf-pick-banner {
-  position: fixed; top: 78px; left: 50%; transform: translateX(-50%);
+  position: fixed; top: 78px; left: calc(50% - var(--pf-rail-w) / 2); transform: translateX(-50%);
   z-index: 30; max-width: min(56ch, calc(100vw - 24px));
   padding: 10px 36px 10px 12px;
   background: var(--pf-surface); color: var(--pf-text);
-  border: 1px solid var(--pf-border); border-radius: 14px;
-  box-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-pill);
+  box-shadow: var(--pf-shadow-float);
   font-size: 12px; line-height: 1.45;
   animation: pf-pick-in .18s ease;
 }
@@ -264,6 +305,11 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #pf-pick-banner .pf-pick-msg { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
 #pf-pick-banner .pf-pick-label { color: var(--pf-muted); font-size: 11px; }
 #pf-pick-banner .pf-pick-prompt { color: var(--pf-text-strong); font-weight: 600; }
+/* Below the rail's breakpoint the rail stacks under the viewer, so the stage is
+   full width again and the banner centres on the window. */
+@media (max-width: 719px) {
+  #pf-pick-banner { left: 50%; }
+}
 #pf-pick-close {
   position: absolute; top: 6px; right: 6px; appearance: none;
   width: 20px; height: 20px; padding: 0;

package/src/framework/chrome.css

@@ -0,0 +1,180 @@
+/* Reusable chrome LAYOUT for a partforge app: the shell, the viewer column
+   ("stage"), the full-height controls rail, its resize seam, and the two
+   floating pill groups. This file owns the shell's layout and its structural
+   surfaces — the rail's/head's/foot's background, border, shadow, and text
+   color, and the seam pill's background — all expressed through overridable
+   --pf-* tokens. Appearance of the controls INSIDE the rail (the panel
+   widgets themselves) stays in app.css.
+
+   Class-based on purpose. partforge-cloud's sandbox builds its own DOM
+   (#viewer / #pfc-controls) and could never reuse an id-keyed sheet, so the
+   layout is expressed as .pf-* classes and exported standalone as
+   "partforge/chrome.css". app.css keeps :not(.pf-*) fallbacks so legacy
+   id-only markup renders its previous floating look untouched.
+
+   Prerequisite: this sheet consumes --pf-* custom properties (--pf-rail-w,
+   --pf-rail-pad, --pf-border, --pf-surface, --pf-bg, --pf-text, --pf-muted,
+   --pf-shadow-rail) but does not import them — a standalone consumer must
+   also load "partforge/tokens.css" (kept separate so the two stay
+   independently composable). The host is also responsible for giving
+   .pf-shell a height (e.g. `height: 100%` on an ancestor chain rooted at
+   `html, body`, or `position: absolute; inset: 0`); this sheet does not size
+   the shell itself.
+
+   See docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md. */
+
+/* ---- shell: viewer column + rail, side by side --------------------------- */
+.pf-shell {
+  display: flex;
+  /* containing block for the absolutely-positioned seam */
+  position: relative;
+  overflow: hidden;
+}
+
+/* ---- stage: the viewer column, which owns its floating chrome ------------
+   min-width: 0 lets the column shrink past the canvas's intrinsic width, so
+   dragging the rail wider actually narrows the viewer instead of overflowing. */
+.pf-stage {
+  flex: 1;
+  position: relative;
+  min-width: 0;
+  background: var(--pf-bg);
+}
+
+/* ---- rail: a full-height right edge, set back from the viewer ------------
+   Square-cornered: it is an edge, not a card. The shadow is INSET on its left
+   side — the viewer casts onto the rail, which is what makes the rail read as
+   set back. An outer shadow would read as floating above the viewer. */
+.pf-rail {
+  flex: none;
+  width: var(--pf-rail-w);
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  overflow: hidden;
+  background: var(--pf-surface);
+  border-left: 1px solid var(--pf-border);
+  box-shadow: var(--pf-shadow-rail);
+  color: var(--pf-text);
+  /* Discrete changes (toggle, Home/End, double-click) animate; a drag never
+     does — an animated width fights the pointer and costs an extra WebGL
+     buffer reallocation every frame. */
+  transition: width .15s ease;
+}
+.pf-rail[inert] { border-left-width: 0; }
+
+/* Head and foot are flex-fixed rather than sticky, so the scroll container is
+   exactly .pf-rail-body. On a full-height rail the export buttons must never
+   scroll out of reach. */
+.pf-rail-head, .pf-rail-foot { flex: none; }
+.pf-rail-head { padding: 12px var(--pf-rail-pad); border-bottom: 1px solid var(--pf-border); }
+.pf-rail-foot { padding: 12px var(--pf-rail-pad); border-top: 1px solid var(--pf-border); }
+.pf-rail-body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* Rail-head title/subtitle typography — class-only (see this file's header:
+   no host-supplied id can be assumed), so a host that adopts this sheet with
+   its own ids (e.g. partforge-cloud) gets a correctly-shaped rail head with
+   correctly-styled text, not just a correctly-shaped empty box. Legacy
+   id-only markup (a bare <h1>/.sub with no .pf-rail-head wrapper) can't be
+   reached from here without an id selector, so app.css restates the same
+   two rules scoped to #panel for that one case — see the comment there. */
+.pf-rail-head h1 {
+  font-size: 14px; margin: 0 0 2px; color: var(--pf-text-strong); letter-spacing: -0.01em;
+}
+.pf-rail-head .sub {
+  font-family: var(--pf-mono); color: var(--pf-muted); font-size: 10px;
+  letter-spacing: 0.04em; text-transform: uppercase;
+  margin: 2px 0 0;
+}
+
+/* ---- resize seam --------------------------------------------------------
+   An OVERLAY, not a flex item. partforge-cloud's seam is a real 12px column
+   because its card is inset from the window with a gutter to live in; this rail
+   is flush against the viewer behind a hairline, so a flex item would open a
+   visible stripe of page background.
+
+   max(0px, …) is what parks the seam flush at the window edge when the rail is
+   collapsed, so a fresh drag can pull it back out. The element is created by
+   rail.js — no host markup declares it. */
+.pf-rail-seam {
+  position: absolute;
+  top: 0; bottom: 0;
+  right: max(0px, calc(var(--pf-rail-w) - 6px));
+  z-index: 20;
+  width: 12px;
+  display: flex; align-items: center; justify-content: center;
+  touch-action: none;
+  cursor: ew-resize;
+}
+/* Collapsed, the only legal direction is left. */
+.pf-rail-seam[data-collapsed] { cursor: w-resize; }
+.pf-rail-seam:focus-visible { outline: none; }
+/* Invisible at rest; the affordance is a short centred pill that appears only
+   on hover, keyboard focus, or during a drag. */
+.pf-rail-seam > span {
+  pointer-events: none;
+  width: 3px; height: 100px; border-radius: 999px;
+  background: transparent;
+  transition: background-color .12s ease;
+  /* Nudges only the pill 5px off the divider hairline it otherwise sits flush
+     against — the seam's own 12px hit target stays centred on the boundary
+     (that line is what a user aims at to drag) and must NOT move. */
+  transform: translateX(-5px);
+}
+.pf-rail-seam:hover > span,
+[data-pf-dragging] .pf-rail-seam > span { background: var(--pf-muted); }
+/* Keyboard focus must read as distinct from hover/drag, not just present —
+   the accent pill, not the muted one, is the only thing that says "focus
+   landed here" for a keyboard user. */
+.pf-rail-seam:focus-visible > span { background: var(--pf-accent); }
+
+/* While dragging, the cursor must stay correct even when the pointer is out
+   over the viewer, and the viewer must not react to it. Pointer capture keeps
+   the events coming; these two rules are the second belt. */
+[data-pf-dragging] { cursor: ew-resize; user-select: none; }
+[data-pf-dragging] .pf-stage { pointer-events: none; }
+[data-pf-dragging] .pf-rail,
+[data-pf-key-resizing] .pf-rail { transition: none; }
+
+/* ---- floating chrome: PLACEMENT ONLY, absolute within the stage ----------
+   Deliberately no appearance here. partforge-cloud's sandbox.css re-anchors
+   #viewbar's position with its own rules but inherits the pill's chrome
+   (background/border/radius/shadow) from app.css, so that chrome must live in
+   app.css ungated — not be duplicated into a class the cloud never sets. This
+   file owns where things sit; app.css owns what they look like. */
+.pf-float-tabs, .pf-float-viewbar { position: absolute; z-index: 15; }
+.pf-float-tabs { top: 12px; left: 50%; transform: translateX(-50%); }
+.pf-float-viewbar { bottom: 12px; right: 12px; }
+
+/* ---- stacked layout: no room for a rail beside the viewer ----------------
+   The seam is hidden and resize is absent at this width (rail.js also refuses
+   to start a drag); the #rail-toggle still collapses and restores. */
+@media (max-width: 719px) {
+  .pf-shell { flex-direction: column; }
+  .pf-rail {
+    width: auto; height: 45vh;
+    border-left: 0; border-top: 1px solid var(--pf-border);
+    box-shadow: none;
+  }
+  .pf-rail-seam { display: none; }
+  /* Collapsed, --pf-rail-w has no effect here (width is auto, height is 45vh),
+     so hide the rail outright — otherwise the toggle's first tap leaves a
+     full-size rail on screen that is inert and unresponsive. */
+  .pf-rail[inert] { display: none; }
+}
+
+/* ---- reduced motion -----------------------------------------------------
+   Collapsing the rail slides 288px of layout across the screen — the first
+   layout-scale animation in the framework, and the kind of movement a
+   vestibular-sensitive user actually feels. Honour the preference: the rail
+   still collapses and still resizes, it just arrives instead of travelling.
+   Scoped to what this layout introduces; the pre-existing busy spinner is a
+   state indicator and is left alone. */
+@media (prefers-reduced-motion: reduce) {
+  .pf-rail, .pf-rail-seam > span { transition: none; }
+}

package/src/framework/debug-overlay.js

@@ -5,8 +5,23 @@
 export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
   const box = document.createElement("div");
   box.id = "pf-debug";
+  // Left edge, below the top tab row: #viewbar is bottom-right and
+  // #pf-pick/#pf-pick-toast are bottom-left, so the top-left corner has no
+  // OTHER fixed element competing for it — but #topbar's tabs are centred in
+  // the stage, and the stage starts flush at the window's left edge, so a top
+  // offset of 12px (matching the tabs') is not actually free of them: at
+  // narrow/medium widths this ~240px-wide box reaches past the stage's
+  // horizontal centre and touches the tabs no matter which top corner it
+  // anchors to (measured — see .superpowers/sdd/debug-overlay-fix.md).
+  // #topbar's pill is a fixed 38px tall regardless of viewport or label width
+  // (12px top + 38px), so clearing it VERTICALLY is what's actually
+  // width-independent: sit below the tabs instead of racing them
+  // horizontally. That also drops any dependency on --pf-rail-w, so no media
+  // query is needed for the stacked layout below 720px.
+  // Positioned inline (not in chrome.css) because this box is dev-only chrome
+  // specific to partforge itself, never exported for a host to skin or reuse.
   Object.assign(box.style, {
-    position: "fixed", bottom: "12px", right: "12px", zIndex: "9999",
+    position: "fixed", top: "58px", left: "12px", zIndex: "9999",
     font: "12px ui-monospace, monospace", background: "rgba(0,0,0,0.7)",
     color: "#e6e6e6", padding: "8px 10px", borderRadius: "6px",
     lineHeight: "1.5", whiteSpace: "pre",

package/src/framework/geometry/op-options.js

@@ -28,7 +28,9 @@ function editDistance(a, b) {
 // Prefix match first so long-form names hit their short key (radius→r,
 // height→h, diameter→d), then edit distance ≤ 2 for plain typos. A digit
 // suffix is peeled and re-attached so radius1 hints r1, not r.
-function suggest(key, valid) {
+// Exported so partforge/lint's `unknown-control-field` rule reuses this exact
+// suggester rather than carrying a second copy of the edit-distance logic.
+export function suggest(key, valid) {
   const lk = key.toLowerCase();
   const m = /^([a-z]+)(\d+)$/.exec(lk);
   if (m) for (const v of valid) if (m[1].startsWith(v.toLowerCase()) && valid.includes(v + m[2])) return v + m[2];

package/src/framework/geometry/probe.js

@@ -1,22 +1,44 @@
-// Geometry-free backend detection. A probe kernel records every op a part's
-// build() invokes (returning chainable no-op proxies, dummy values for queries);
-// if an OCCT-only op was used, the part needs the OCCT backend. The op list lives
-// in kernel.js — the same list generates the Manifold backend's throwing stubs.
-import { OCCT_ONLY_OPS } from "./kernel.js";
+// Geometry-free build execution. Two consumers share one Proxy implementation:
+//
+//  • createProbeKernel() — records op NAMES so detectBackend() can route a part to
+//    OCCT when it uses fillet/chamfer/shell.
+//  • createValidatingProbe() — additionally checks op names against the kernel
+//    contract's op lists and routes options-form calls through the same op-options
+//    normalizers the real backends use, so partforge/lint can catch a bad call in
+//    microseconds instead of after a WASM boot.
+//
+// Catch-all proxies (rather than a hand-listed allowlist) mean new kernel/solid
+// methods never have to be mirrored here — the probe can't drift out of sync with
+// the real backends. (That drift previously broke the panel's relevance dimming
+// when the build-step vocabulary was added but not taught to the probe.) The
+// validating probe DOES need an allowlist, so it takes one from kernel.js's op
+// lists, which test/kernel-contract.test.js pins to both backend implementations.
+import {
+  OCCT_ONLY_OPS, KERNEL_OPS, KERNEL_OPTIONAL_OPS,
+  SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS,
+} from "./kernel.js";
+import { KERNEL_OP_SPECS, SOLID_OP_SPECS, isPlainOptions } from "./op-options.js";
 import { resolveDerived } from "../derive.js";
 
 const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
 
-export function createProbeKernel() {
-  const used = new Set();
-  const note = (name) => used.add(name);
+// The probe returns ONE chainable handle for every non-query op, so it cannot tell a
+// Solid from a Shape2D — k.box() and k.shape2d() yield the same object. The solid-scope
+// allowlist is therefore the union of all three surfaces: deliberately permissive, so
+// it never false-positives on an error-severity rule.
+const KERNEL_ALLOWED = new Set([...KERNEL_OPS, ...KERNEL_OPTIONAL_OPS]);
+const SOLID_ALLOWED = new Set([...SOLID_OPS, ...SOLID_OPTIONAL_OPS, ...SHAPE2D_OPS]);
+
+export const MAX_PROBE_OPS = 100000;
+
+// Thrown to unwind a runaway build. Never escapes runValidatingProbe.
+export class ProbeRunawayError extends Error {
+  constructor(message) { super(message); this.name = "ProbeRunawayError"; }
+}
 
-  // Catch-all proxies: any method records its name and returns the chainable solid
-  // proxy, EXCEPT the queries below, which return realistic dummy values the build may
-  // read. Using a Proxy (rather than a hand-listed allowlist) means new kernel/solid
-  // methods never have to be mirrored here — the probe can't drift out of sync with the
-  // real backends. (That drift previously broke the panel's relevance dimming/hiding when
-  // the build-step vocabulary was added but not taught to the probe.)
+// Shared proxy construction. `onCall(scope, op, args)` observes every op; queries
+// return realistic dummy values the build may read.
+function makeProbe(onCall) {
   const solidQueries = {
     boundingBox: () => ({ min: [0, 0, 0], max: [1, 1, 1], center: [0.5, 0.5, 0.5], size: [1, 1, 1] }),
     volume: () => 1,
@@ -29,24 +51,101 @@ export function createProbeKernel() {
     cleanup: () => {},
   };
 
-  // `ignore` keeps the proxy from masquerading as a thenable/internal handle: symbols,
-  // `then` (so it's never await-unwrapped), and `_`-prefixed internals resolve to
-  // undefined rather than a chainable op.
-  const ignore = (key) => typeof key !== "string" || key === "then" || key[0] === "_";
+  // `ignore` keeps the proxy from masquerading as a thenable/internal/serializable
+  // handle: symbols, `then` (so it's never await-unwrapped), `_`-prefixed internals,
+  // and `toJSON` all resolve to undefined rather than a chainable op. `toJSON` matters
+  // because a handle nested inside an options object (the normal calling convention,
+  // e.g. `k.extrude({ profile: someShape, h: 5 })`) isn't caught by the `describe()`
+  // identity check below — that only sees the top-level options object, not the
+  // nested handle — so `JSON.stringify` walks into it and probes for `toJSON` per the
+  // spec. Without this, that probe would be recorded as a real op and then flagged as
+  // an unknown one.
+  const ignore = (key) => typeof key !== "string" || key === "then" || key === "toJSON" || key[0] === "_";
 
-  const opProxy = (queries) => new Proxy({}, {
+  // A query (boundingBox, volume, toMesh, …) must count against `onCall`'s ceiling
+  // exactly like any other op — returning `queries[key]` directly here used to let
+  // every query bypass the counter entirely, so a query-only loop (`for(;;)
+  // s.volume()`) never tripped MAX_PROBE_OPS and hung forever. Wrap it the same
+  // way as the chaining branch below: observe the call, then run the real query.
+  const opProxy = (queries, scope) => new Proxy({}, {
     get(_t, key) {
       if (ignore(key)) return undefined;
-      if (key in queries) return queries[key];
-      return (..._args) => { note(key); return proxy; };
+      if (key in queries) return (...args) => { onCall(scope, key, args); return queries[key](...args); };
+      return (...args) => { onCall(scope, key, args); return proxy; };
     },
   });
 
-  const proxy = opProxy(solidQueries);   // a solid handle: every op chains back to itself
-  const kernel = opProxy(kernelQueries); // factory ops (cylinder/box/prism/…) return a solid
+  const proxy = opProxy(solidQueries, "solid");   // a solid handle: every op chains back to itself
+  const kernel = opProxy(kernelQueries, "kernel"); // factory ops (cylinder/box/prism/…) return a solid
+  return { kernel, proxy };
+}
+
+export function createProbeKernel() {
+  const used = new Set();
+  const { kernel } = makeProbe((_scope, key) => used.add(key));
   return { kernel, used };
 }
 
+export function createValidatingProbe({ maxOps = MAX_PROBE_OPS } = {}) {
+  const calls = [];
+  const issues = [];
+  const used = new Set();
+  let count = 0;
+  let solidProxy = null;
+
+  // Args are recorded as strings so two probe runs can be compared for determinism.
+  // The chainable handle is a single shared object, so identity is enough to spot it —
+  // and checking identity FIRST matters, because JSON.stringify would trip its traps.
+  const describe = (a) => {
+    if (a === solidProxy) return "<solid>";
+    if (typeof a === "function") return "<fn>";
+    try { return JSON.stringify(a) ?? String(a); } catch { return "<unserializable>"; }
+  };
+
+  const onCall = (scope, op, args) => {
+    if (++count > maxOps) throw new ProbeRunawayError(`build exceeded ${maxOps} kernel operations`);
+    used.add(op);
+    const allowed = scope === "kernel" ? KERNEL_ALLOWED : SOLID_ALLOWED;
+    if (!allowed.has(op)) issues.push({ kind: "unknown-op", scope, op });
+    // Validate ONLY the options form — the normative rule (KERNEL-CONTRACT.md
+    // "Calling convention") is that a call is options form when it receives exactly
+    // one plain-object argument. Legacy positional calls have no options contract to
+    // check against. We run `toArgs` (key + required validation) but never the spec's
+    // separate `check` hook: `check` inspects real geometry (revolve's calls
+    // boundingBox() on its profile), which is meaningless against a proxy.
+    const specs = scope === "kernel" ? KERNEL_OP_SPECS : SOLID_OP_SPECS;
+    if (specs[op] && args.length === 1 && isPlainOptions(args[0])) {
+      try { specs[op].toArgs(args[0]); }
+      catch (e) { issues.push({ kind: "invalid-options", scope, op, message: e?.message || String(e) }); }
+    }
+    calls.push({ scope, op, args: args.map(describe) });
+  };
+
+  const { kernel, proxy } = makeProbe(onCall);
+  solidProxy = proxy;
+  return { kernel, calls, issues, used };
+}
+
+/**
+ * Execute every sub-part's build() against a validating probe.
+ * Never throws: a build error becomes an entry in `throws`, a runaway sets `runaway`.
+ */
+export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {}) {
+  const probe = createValidatingProbe({ maxOps });
+  const throws = [];
+  let runaway = false;
+  for (const [name, sp] of Object.entries(part?.parts ?? {})) {
+    if (typeof sp?.build !== "function") continue; // no-buildable-parts already reports this
+    try {
+      sp.build(probe.kernel, p, d);
+    } catch (e) {
+      if (e instanceof ProbeRunawayError) { runaway = true; break; }
+      throws.push({ subpart: name, message: e?.message || String(e) });
+    }
+  }
+  return { calls: probe.calls, issues: probe.issues, used: probe.used, throws, runaway };
+}
+
 export function detectBackend(part, params = {}) {
   if (part.meta?.backend) return part.meta.backend;
   const p = { ...part.defaults, ...params };