partforge 0.27.0 → 0.31.0

package/README.md

@@ -99,10 +99,11 @@ const runtime = mount(part, {
   createWorker,
   elements: {
     viewer, controls,                       // canvas host + param-panel host
+    rail,                                   // full-height resizable/collapsible controls rail
     status: { status, busy, phase },        // status chrome
     tabs,                                   // view-tab segmented control
     exports: { stl, step, threeMf },        // export buttons
-    chrome: { pause, reframe, theme },      // viewer buttons
+    chrome: { pause, reframe, theme, railToggle }, // viewer buttons + rail collapse/restore
   },
   onBuild: ({ status, ms, error }) => {},   // per accepted build: "success" | "error"
   onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
@@ -112,9 +113,20 @@ runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU
 ```
 
 Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,
-`#status`/`#busy`/`#phase`, `#part`, `#download`/`#download-step`/`#download-3mf`,
-`#pause`/`#reframe`/`#theme`), so a classic host page needs no changes. The viewer
-sizes from its container via ResizeObserver — no window coupling.
+`#panel` for `rail`, `#status`/`#busy`/`#phase`, `#part`,
+`#download`/`#download-step`/`#download-3mf`,
+`#pause`/`#reframe`/`#theme`/`#rail-toggle`), so a classic host page needs no
+changes. The viewer sizes from its container via ResizeObserver — no window
+coupling.
+
+`rail` is the full-height controls rail introduced by the resizable-panel
+layout (`docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md`);
+`chrome.railToggle` is its optional collapse/restore button. Both are optional
+— a host that lays out the framework itself (no rail markup) gets a no-op.
+The rail's resize seam is positioned against `rail.parentElement` by default,
+so **the rail must be a direct child of the positioned `.pf-shell`** unless
+the host also supplies `elements.shell` to point at the real containing block
+(e.g. when a wrapper div sits between them, as is common in a React layout).
 
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready

package/docs/AUTHORING-PARTS.md

@@ -30,8 +30,9 @@ OCCT-only fillet/chamfer/shell ops.
    `http://localhost:5173/<your-part>.html`.
 
 That's the whole loop. The chrome (panel, tabs, viewer, export buttons) is shared —
-your HTML is ~30 lines of structural markup and carries no CSS (the framework
-supplies it via `framework/app.css`, imported by `mount`).
+your HTML is structural markup only and carries no CSS (the framework supplies it via
+`framework/app.css`, imported by `mount`). See "Wiring a part into a runnable app"
+below for what that markup must contain.
 
 ---
 
@@ -336,6 +337,13 @@ their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`
 profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so
 changing any of them is a fresh cache node while an identical rebuild is a hit.
 
+This holds on **both backends** — and on OCCT, `translate`/`rotate` are additionally
+*pose-lazy*: the backend re-poses the cached solid's cached tessellation instead of
+re-running any B-rep work. A parameter that only feeds a final placement rotation (a
+lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
+slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
+rather than baking them into the geometry earlier.
+
 ---
 
 ## Parameters: the control-panel schema
@@ -688,37 +696,121 @@ stylesheet). `mount` looks up these element IDs:
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
 | `#viewbar` with `#pause` / `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
-
-Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
-(`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
+| `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
+| `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#pause`/`#theme` |
+
+Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two
+workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
+`"occt"` for STEP — handled for you).
+
+**The markup convention (`demo.html` is the canonical copy-me page):** `<body>` carries
+`class="pf-shell"`, the flex row that lays the viewer column next to the rail. `#app`
+(`class="pf-stage"`) *is* that viewer column, and now contains the floating chrome
+(`#topbar`, `#viewbar`, `#busy`) as absolutely-positioned siblings of the canvas, not
+page-level overlays. `#panel` (`class="pf-rail"`) is a full-height rail docked to the
+right edge, split into three children — `.pf-rail-head` / `.pf-rail-body` /
+`.pf-rail-foot` — of which head and foot are flex-fixed and only the body scrolls: put
+your heading in the head and the download row in the foot so the export buttons never
+scroll out of reach. The rail's drag/collapse seam is created by `rail.js` itself; don't
+add markup for it. This isn't decorative — get the head/body/foot split wrong and either
+the export buttons scroll away or a tall parameter list pushes them off-screen. See
+`docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md` for why the rail is
+shaped this way (resize/collapse behavior, breakpoints, the design rationale).
+
+**Keyboard (the seam is `role="separator"`, focusable, `tabIndex=0`):**
+
+| Key | Action |
+|---|---|
+| ← | widen the rail 16px (64px with Shift). No-op while collapsed. |
+| → | narrow the rail 16px (64px with Shift), clamped at the 240px minimum — never collapses. No-op while collapsed. |
+| Home | jump to the 240px minimum, animated. Reopens even while collapsed. |
+| End | jump to the clamped maximum (half the shell, capped at 560px), animated. Reopens even while collapsed. |
+| Enter / Space | toggle collapse — collapses if open; reopens at the remembered width if collapsed. |
+| double-click (on the seam) | reset to the 288px default, animated, and opens if collapsed. |
+
+Arrow keys move the **separator**, not the pane — standard `role="separator"`
+semantics, and why ← *widens* a right-hand rail. `Cmd`/`Ctrl`/`Alt` held with an
+arrow key passes through untouched (those are OS/browser-reserved combos, e.g.
+back navigation or window-switching); `Shift` alone still applies the larger
+step. Collapsed, the two arrow keys are deliberate no-ops rather than a reopen
+gesture — reopening would otherwise silently discard the remembered width and
+clamp to the minimum, and "press an arrow, get narrower" reads backwards for a
+rail that's already shut. Home/End and Enter/Space/double-click are exempt from
+that rule and always reopen, since jumping to an explicit width or toggling is
+an unambiguous, deliberate gesture either way. A held arrow-key repeat
+suppresses the 150ms width transition for the whole repeat window (not just one
+keydown), matching what happens during a drag.
+
+Legacy id-only markup (predating this class scheme) still renders: `app.css` keeps
+`:not(.pf-*)` fallbacks (`#app:not(.pf-stage)`, `#panel:not(.pf-rail)`, and
+placement-only ones for `#topbar`/`#viewbar`) that reproduce the old floating-card
+look — `:not()` rather than a plain id rule because an id selector outranks a class. New
+apps should still use the classed markup above; the fallback exists for pages that
+predate it, not as a second supported style.
+
+A host that builds its own DOM instead of using `mount`'s markup (e.g. an editor
+embedding the viewer/rail inside a larger UI) can adopt the same layout by importing
+**`partforge/chrome.css`** directly — it's deliberately class-based and id-free for that
+reason. It expects `partforge/tokens.css` to already be loaded for its `--pf-*` custom
+properties, and expects the host to size `.pf-shell` itself (`mount`'s own `app.css`,
+which `@import`s both, does both of these for you already).
 
 `#cutaway` is optional viewer chrome. When present, it toggles an interactive
 section plane whose exposed faces are hatched; changing views resets it. Cutaway
 is viewer-only and never changes STL, STEP, or 3MF exports. Hosts that omit the
 button get no cutaway UI.
 
-Programmatic hosts can provide the same optional control without relying on an
-ID by passing it beside the other chrome references:
+Programmatic hosts can provide the same optional controls, including the rail toggle,
+without relying on an ID by passing them beside the other chrome references — and can
+pass the rail itself as `elements.rail` instead of relying on `#panel`:
 
 ```js
 mount(part, {
   createWorker,
   elements: {
+    rail,
     chrome: {
       pause,
       reframe,
       cutaway,
       theme,
+      railToggle,
     },
   },
 });
 ```
 
+`rail`/`chrome.railToggle` are both optional; a host with no rail markup gets a
+no-op (the resize/collapse behavior below simply doesn't attach). **Constraint:**
+the rail element must be a direct child of the positioned `.pf-shell` — the
+resize seam is created and positioned against `rail.parentElement` by default,
+so an extra wrapper div between them (common in a React layout) puts the seam
+against the wrong ancestor and silently breaks `[data-pf-dragging] .pf-stage`.
+A host that can't make the rail a direct child of `.pf-shell` must also pass
+`elements.shell` pointing at the real positioned ancestor:
+
+```js
+mount(part, {
+  createWorker,
+  elements: { rail, shell, chrome: { railToggle } },
+});
+```
+
 > Production deploy compiles only the pages listed in `build.rollupOptions.input`
 > (currently the landing gallery + the demo part pages). Other root `*.html` files are
 > **dev-only** (Vite serves any root HTML in `npm run dev`) unless added there. To also
 > ship one, add it to `build.rollupOptions.input` in `vite.config.js`.
 
+**Styling hooks:** the rail/stage layout and palette are both plain `--pf-*` custom
+properties from `partforge/tokens.css`, overridable on `:root` (or
+`:root[data-theme="light"]`) without touching `chrome.css`. Layout/shape tokens added
+alongside the rail: `--pf-sans`, `--pf-rail-w`, `--pf-rail-pad`, `--pf-radius-control`,
+`--pf-radius-pill`, `--pf-shadow-float`, `--pf-shadow-rail`. The dev demos self-host
+Geist and Geist Mono (`@fontsource-variable/geist(-mono)`, a `devDependency`, imported
+from each `app-<part>.js` — see `src/app-demo.js`) so a standalone forge looks like the
+finished product; the published library ships no font files, and a consumer that loads
+none falls through `--pf-sans`/`--pf-mono` to system stacks by design.
+
 ### Developing against a local (linked) partforge
 
 A normal `npm install partforge` needs no extra config. But if you `npm link` a local

package/docs/ERROR-PATTERNS.md

@@ -47,7 +47,7 @@ test parses every one; keep prose like this as plain paragraphs):
 - **Cause:** replicad transforms and booleans (`translate`/`rotate`/`mirror`/`cut`/…) consume their operand — the input solid is deleted and a new one returned.
 - **Fix:** Never reuse a solid after transforming it; take a `.clone()` first when you need the original again. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (the `s.clone()` row).
 
-The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code.
+The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code. (Since the OCCT solid cache landed, the in-repo backend clones internally before every consuming replicad call, so wrapped `Solid`s effectively have value semantics and this crash should no longer reproduce through the kernel API — but the portable rule stands: per KERNEL-CONTRACT.md a backend MAY consume, so a part must still not rely on reuse.)
 
 ## probe-routed-to-occt
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.27.0",
+  "version": "0.31.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",
@@ -28,7 +28,8 @@
     "./lint": "./src/lint.js",
     "./derive": "./src/framework/derive.js",
     "./testing": "./src/testing.js",
-    "./tokens.css": "./src/framework/tokens.css"
+    "./tokens.css": "./src/framework/tokens.css",
+    "./chrome.css": "./src/framework/chrome.css"
   },
   "bin": {
     "partforge": "./bin/cli.js"
@@ -54,6 +55,8 @@
     "three": "^0.184.0"
   },
   "devDependencies": {
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
     "happy-dom": "^20.10.6",
     "playwright": "^1.49.0",
     "vite": "^8.0.16",

package/src/app-bracket.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/bracket.js";
 import { mount } from "./framework/index.js";
 

package/src/app-demo.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import demoPart from "./parts/demo.js";
 import { mount } from "./framework/index.js";
 

package/src/app-faceted-vase.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import vasePart from "./parts/faceted-vase.js";
 import { mount } from "./framework/index.js";
 

package/src/app-filleted-box.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/filleted-box.js";
 import { mount } from "./framework/index.js";
 

package/src/app-hull-sweep.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/hull-sweep.js";
 import { mount } from "./framework/index.js";
 

package/src/app-nameplate.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/nameplate.js";
 import { mount } from "./framework/index.js";
 

package/src/app-planter.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import planterPart from "./parts/planter.js";
 import { mount } from "./framework/index.js";
 

package/src/app-text-smoke.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/text-smoke.js";
 import { mount } from "./framework/index.js";
 

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;