partforge 0.72.0 → 0.73.0

package/docs/AUTHORING-PARTS.md

@@ -1480,14 +1480,30 @@ stylesheet). `mount` looks up these element IDs:
 | `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` and opens the resolved default (see the "Which view the viewer opens on" rule above) |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#reframe` / `#cutaway` / `#measure` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#annotate` / `#measure` / `#cutaway` / `#reframe` / `#theme` | optional viewer controls (omit any you don't want) |
 | `#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 `#reframe`/`#theme` |
+| `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#reframe`/`#theme`. A sibling of `#viewbar`, not a child of it: give it `class="pf-float-rail-toggle"` and it floats at the stage's top right |
 
 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).
 
+**`#reframe` is supported but no longer shipped.** The framework's own pages dropped
+the button on 2026-08-20: clicking a face, edge or corner on the view cube reframes
+too, so a separate control was one more thing in a crowded bottom-right corner. The
+wiring is untouched and fully optional — supply the button (by ID or as
+`elements.chrome.reframe`) and it works exactly as before — so a host with its own
+scaffold need change nothing.
+
+**`#rail-toggle` left the viewbar on 2026-08-20.** It used to be the pill's last
+button; it now floats alone at the stage's **top right**, opposite the pill's bottom
+right, as a bare icon that grows a background on hover. Nothing in the wiring changed —
+`mount` still resolves it by id (or `elements.chrome.railToggle`), and `rail.js` still
+hides it below the 720px narrow breakpoint, where the pane tab bar takes over. A host
+with its own scaffold gets the new look by moving the button out of `#viewbar` and adding
+`class="pf-float-rail-toggle"`; leaving it inside the pill keeps the old look and still
+works.
+
 **View control (the mount handle).** For an embedder driving the view tabs from its own UI
 instead of (or in addition to) the built-in `#part` bar:
 
@@ -1554,6 +1570,35 @@ pane's pixel size:
   counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.
 
+### `runtime.projection`
+
+`{ get(), set(mode), onChange(cb) }` where `mode` is `"perspective"` or
+`"orthographic"`. Drives the **live view** and `captureCurrent` only —
+`captureCanonicalViews`, `renderMeshPayloads`, and the CLI's `partforge render`
+stay perspective unconditionally, so agent-facing output does not depend on a UI
+toggle. The choice persists across reloads under `partforge:projection` and is
+restored before the first framing. The orientation cube and its projection
+button are hidden while Sketch (annotate) mode is active, but that only governs
+*user-driven* view changes — the framework does not police programmatic ones.
+The ink is a transparent overlay and the WebGL canvas keeps rendering beneath
+it, so a host that calls `runtime.projection.set()` mid-sketch **visibly
+re-frames the 3D view underneath ink the user may still be drawing**: the
+strokes stay where they were laid down while the model shifts out from under
+them, and the sketch that gets sent is misaligned, not merely mis-labelled.
+Deliberately unguarded, the same way it's always been free to call
+`setCameraState` during Sketch.
+
+### The annotation payload's camera block
+
+`onAnnotationSend(payload)` receives a `camera` block in two frames — `world`
+(replays exactly against the build that produced it) and `parts` (pinned to
+the CAD geometry, so it survives a later rebuild's bbox recentring; reread a
+sketch's camera intrinsics from `parts`, not `world`, once the model has been
+rebuilt). `ANNOTATION_VERSION` is **2**: both frames carry
+`projection: "perspective" | "orthographic"`, and under an orthographic camera
+`fov` is `null` while `orthoHeight` gives the frustum's world height instead.
+(v1 had `fov` only, and predates the projection toggle.)
+
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/animation-controls.js

@@ -44,6 +44,92 @@ export function planAnimBarPlacement({ stageWidth, barWidth, viewbarLeft }, { ga
   return barWidth > available ? { left, maxWidth: available } : { left };
 }
 
+// A rect with no area is not a claim on the stage — it is the ABSENCE of one,
+// and unioning it in would drag the union's left/top edges to 0. The concrete
+// case is Sketch mode hiding the cube stack via the `hidden` property: a
+// `display: none` element's getBoundingClientRect() is all zeros, which made
+// the union {left: 0, top: 0} and planned the transport bar to the stage's left
+// edge at max-width: 0. But a hidden ancestor is only one way to get that rect
+// — an unattached element and a `content-visibility: hidden` subtree report the
+// same — so the filter is on the rect's own emptiness rather than on any one
+// cause of it.
+const isEmptyRect = (r) => !r || r.right - r.left <= 0 || r.bottom - r.top <= 0;
+
+// The bottom-right chrome cluster is two elements now — #viewbar with the view
+// cube stacked above it — so the transport bar has to clamp against their union
+// or it slides under the cube on a narrow stage. Null-tolerant because either
+// element can be absent (a host that drops the viewbar; a mount before the cube
+// attaches) — and empty-tolerant per the rule above, which is the same "no
+// claim here" case arriving as a zero rect instead of as null.
+export function unionRect(a, b) {
+  if (isEmptyRect(a)) return isEmptyRect(b) ? null : b;
+  if (isEmptyRect(b)) return a;
+  return {
+    left: Math.min(a.left, b.left),
+    right: Math.max(a.right, b.right),
+    top: Math.min(a.top, b.top),
+    bottom: Math.max(a.bottom, b.bottom),
+  };
+}
+
+// The cluster's footprint AS IF THE CUBE WERE VISIBLE — what the CROWDING
+// decision is measured against, as opposed to the measured union above, which is
+// what the bar is actually PLACED against. Two rects, two purposes.
+//
+// Deciding "is the bar crowded?" from the measured union oscillates, because the
+// cube is part of that union and hiding it is the consequence of the answer:
+// cube visible → wide union → bar capped → crowded → hide the cube → its rect
+// is all zeros → unionRect drops it → the bar fits → not crowded → show the cube
+// → round again. Two frames per cycle, each one a ResizeObserver notification,
+// on screen as a flickering cube. This rect does not depend on whether the stack
+// is displayed, so the answer is a fixed point: hiding the cube cannot change
+// it.
+//
+// The stack's edges are derived from the viewbar's because chrome.css anchors
+// both to the same margin: `.pf-float-viewbar` is `bottom: 12px; right: 12px`
+// and `.pf-viewcube-stack` is `right: 12px` with its bottom resting on top of
+// the viewbar (`--pf-viewbar-clear` + a few px). So the stack shares the
+// viewbar's right edge, reaches a published width in from it, and occupies the
+// band directly above the viewbar's top. That small gap between them is
+// deliberately NOT subtracted: a hair taller than the truth is the safe
+// direction for a "would these two collide?" test — and this rect is therefore
+// unaffected the day chrome.css retunes it (2026-08-20 took it from 8px to 3).
+//
+// Null/empty-tolerant on exactly unionRect's terms — a zero-area rect is the
+// ABSENCE of a claim, not a claim on the stage's top-left corner:
+// - no viewbar rect (a host that drops #viewbar) → nothing to anchor a nominal
+//   stack on, so fall back to the cube's own measured rect; if that is empty
+//   too there is nothing to decide against at all. This one fallback is
+//   visibility-DEPENDENT and so not a fixed point — it is the best available
+//   answer without the viewbar anchor, and it only applies to a host that has
+//   removed the viewbar entirely.
+// - no published size (no cube attached, or none ever measured) → the stack
+//   makes no nominal claim and the viewbar's rect stands alone.
+export function nominalClusterRect(viewbarRect, cubeRect, size) {
+  if (isEmptyRect(viewbarRect)) return isEmptyRect(cubeRect) ? null : cubeRect;
+  const width = size?.width > 0 ? size.width : 0;
+  const height = size?.height > 0 ? size.height : 0;
+  if (!width || !height) return viewbarRect;
+  return unionRect(viewbarRect, {
+    left: viewbarRect.right - width,
+    right: viewbarRect.right,
+    top: viewbarRect.top - height,
+    bottom: viewbarRect.top,
+  });
+}
+
+// The stack's own size, read from where viewcube-controls.js publishes it rather
+// than measured: a hidden (display:none) stack measures all zeros, and the whole
+// point of the nominal rect above is to survive that. Integer CSS px in
+// data-pf-w / data-pf-h; anything missing or non-positive means "nothing
+// published yet".
+function publishedSize(element) {
+  if (!element) return null;
+  const width = Number(element.dataset.pfW);
+  const height = Number(element.dataset.pfH);
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
 // The scrubber's resolution: `t` is reported to the user as one of this many
 // steps, and read back the same way.
 export const SCRUB_STEPS = 1000;
@@ -97,7 +183,15 @@ function textSetter(element) {
   return (value) => { if (node.data !== value) node.data = value; };
 }
 
-export function attachAnimationControls(viewer, part, { container, applyValues, getParamValues, getView }) {
+export function attachAnimationControls(viewer, part, {
+  container, applyValues, getParamValues, getView,
+  // Called with `true` when the bar has run out of room beside the bottom-right
+  // cluster and has started capping its own width (see isCrowded below), and
+  // with `false` when it has not — on CHANGE only. mount uses it to stand the
+  // view cube down so the bar can have the space back. Defaulted, so a host or
+  // a test that does not care is unaffected.
+  onCrowded = () => {},
+}) {
   // A malformed animations block must degrade to "no transport bar", never a
   // crashed mount — lint reports the specifics; the viewer just goes without.
   let byView;
@@ -522,20 +616,34 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   syncStructure();
   syncUi();
 
-  // --- placement: keep clear of the viewbar ---------------------------------
+  // --- placement: keep clear of the bottom-right cluster ---------------------
   // chrome.css centers the bar (left: 50% / translateX(-50%)), and nothing in
-  // CSS can stop that centered position sliding under #viewbar when the stage
-  // narrows — the viewbar's width is dynamic (cutaway's Flip/Reset appear and
-  // disappear), so a static reservation would either overlap or waste centre
-  // space. Measure instead: when the two bars' vertical bands intersect, clamp
-  // the bar's left so a 10px gap to the viewbar holds, capping its width if
-  // even the stage's 12px margin isn't enough. Overrides are inline and
-  // cleared at the top of every pass, so chrome.css (or a host that
-  // re-anchors either bar out of the shared band) stays authoritative the
-  // moment the constraint stops binding. The clear-measure-apply sequence is
-  // loop-safe: it settles within one frame, so ResizeObserver — which reports
-  // rendered sizes at frame boundaries — never sees the intermediate state.
+  // CSS can stop that centered position sliding under the bottom-right cluster
+  // when the stage narrows — #viewbar's width is dynamic (cutaway's Flip/Reset
+  // appear and disappear), so a static reservation would either overlap or
+  // waste centre space. Measure instead: when the transport bar's vertical
+  // band intersects the CLUSTER's — #viewbar unioned with the view cube stack
+  // sitting above it, since that stack can be taller than the viewbar alone —
+  // clamp the bar's left so a 10px gap holds, capping its width if even the
+  // stage's 12px margin isn't enough. Overrides are inline and cleared at the
+  // top of every pass, so chrome.css (or a host that re-anchors any of these
+  // elements out of the shared band) stays authoritative the moment the
+  // constraint stops binding. The clear-measure-apply sequence is loop-safe: it
+  // settles within one frame, so ResizeObserver — which reports rendered sizes
+  // at frame boundaries — never sees the intermediate state.
+  //
+  // A pass also decides whether the bar is CROWDED — out of room to the point
+  // of capping its own width, which shrinks its controls below the 44px tap
+  // target — and reports that through onCrowded so the cube can give way. That
+  // decision is measured against the NOMINAL cluster rect, never the union used
+  // for placement: see nominalClusterRect for why the difference is the whole
+  // design. It is reported LAST in the pass, after the bar has been placed, so
+  // the hide it may cause lands on the next frame's pass rather than
+  // invalidating the rects this one just measured.
   const viewbarEl = container.querySelector("#viewbar");
+  // Looked up lazily on every pass rather than captured once: the cube stack is
+  // generated by viewcube-controls.js, which may attach after this bar does.
+  const cubeSelector = ".pf-viewcube-stack";
   let placementRaf = 0;
   function applyPlacement() {
     placementRaf = 0;
@@ -556,12 +664,57 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
       ? 0
       : Math.max(0, Math.round(stageRect.bottom - barRect.top));
     container.style.setProperty("--pf-anim-clear", `${clear}px`);
-    const vb = viewbarEl?.getBoundingClientRect();
-    if (!vb || barRect.top >= vb.bottom || barRect.bottom <= vb.top) return;
+    const cubeEl = container.querySelector(cubeSelector);
+    const viewbarRect = viewbarEl?.getBoundingClientRect() ?? null;
+    const cubeRect = cubeEl?.getBoundingClientRect() ?? null;
+    // Every measurement of the pass is taken before anything is written, and
+    // the crowding verdict is one of them — it must not read rects that the
+    // placement below has already moved.
+    const crowded = isCrowded({ stageRect, barRect, viewbarRect, cubeRect, cubeEl });
+    placeBar(stageRect, barRect, unionRect(viewbarRect, cubeRect));
+    reportCrowded(crowded);
+  }
+
+  // Is the bar out of room? Judged against the nominal cluster rather than the
+  // measured union, so that hiding the cube — which is what a `true` here causes
+  // — cannot flip the answer back. `barRect.width` is the bar's NATURAL width:
+  // applyPlacement clears maxWidth/overflow/pf-squeezed before measuring, and
+  // getBoundingClientRect forces layout, so a previous pass's cap is never read
+  // back in here.
+  function isCrowded({ stageRect, barRect, viewbarRect, cubeRect, cubeEl }) {
+    // A bar that is not on screen cannot be crowded by anything — the same
+    // condition the --pf-anim-clear calculation above uses.
+    if (bar.style.display === "none") return false;
+    const nominal = nominalClusterRect(viewbarRect, cubeRect, publishedSize(cubeEl));
+    // Same vertical-band test the placement path applies, against the nominal
+    // rect: bands that do not intersect cannot collide, so there is nothing to
+    // be crowded by.
+    if (!nominal || barRect.top >= nominal.bottom || barRect.bottom <= nominal.top) return false;
+    const plan = planAnimBarPlacement({
+      stageWidth: stageRect.width,
+      barWidth: barRect.width,
+      viewbarLeft: nominal.left - stageRect.left,
+    });
+    // The CAP is the crowded state, not the slide: a bar that only moves
+    // sideways keeps its full width and its full-size controls.
+    return plan?.maxWidth != null;
+  }
+
+  let reportedCrowded = null; // null: nothing said yet, so the first pass always reports
+  function reportCrowded(crowded) {
+    if (crowded === reportedCrowded) return;
+    reportedCrowded = crowded;
+    onCrowded(crowded);
+  }
+
+  // The write half of a placement pass. `cluster` is the MEASURED union, which
+  // is what lets the bar actually reclaim the space once the cube is gone.
+  function placeBar(stageRect, barRect, cluster) {
+    if (!cluster || barRect.top >= cluster.bottom || barRect.bottom <= cluster.top) return;
     const plan = planAnimBarPlacement({
       stageWidth: stageRect.width,
       barWidth: barRect.width,
-      viewbarLeft: vb.left - stageRect.left,
+      viewbarLeft: cluster.left - stageRect.left,
     });
     if (!plan) return;
     bar.style.left = `${plan.left}px`;
@@ -598,6 +751,8 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     placementObserver.observe(container);
     placementObserver.observe(bar);
     if (viewbarEl) placementObserver.observe(viewbarEl);
+    const cubeAtSetup = container.querySelector(cubeSelector);
+    if (cubeAtSetup) placementObserver.observe(cubeAtSetup);
   }
   onStructureChanged = schedulePlacement; // see the hook's declaration above
   schedulePlacement();

package/src/framework/annotate/annotate-mode.js

@@ -9,7 +9,12 @@ import { createInkStore, anchorSpecs, DEFAULT_STROKE_WIDTH } from "./ink.js";
 import { createInkCanvas } from "./ink-canvas.js";
 import { raycastViewer } from "../selection/raycast.js";
 
-export const ANNOTATION_VERSION = 1;
+// v2 added the camera block's `projection` / `orthoHeight` and made `fov`
+// nullable: the viewer gained an orthographic camera, and a user can switch to
+// it and THEN open Sketch. An additive optional field alone would have left any
+// consumer that reconstructs the camera from `fov` silently wrong rather than
+// loudly broken, so the version moves.
+export const ANNOTATION_VERSION = 2;
 // Long-edge bound on BOTH pictures in the payload. The ink canvas is stage
 // sized × devicePixelRatio, so an unbounded send on a large hi-DPI display
 // hands the host a multi-megabyte pair of base64 strings — slow to encode,
@@ -85,14 +90,37 @@ export function createAnnotateMode(viewer, { stage, getContext, onSend, createCa
   // it survives the per-view bbox recentring when the model is rebuilt later.
   function cameraBlock() {
     const { pos, target } = viewer.getCameraState();
-    const world = { pos, target, up: viewer.camera.up.toArray(), fov: viewer.camera.fov };
+    const cam = viewer.camera;
+    const ortho = !!cam.isOrthographicCamera;
+    const world = {
+      pos,
+      target,
+      up: cam.up.toArray(),
+      projection: ortho ? "orthographic" : "perspective",
+      fov: ortho ? null : cam.fov,
+      orthoHeight: ortho ? Math.abs(cam.top - cam.bottom) / Math.max(cam.zoom, 1e-6) : null,
+    };
     const parent = Object.values(viewer._subMeshes ?? {})[0]?.parent ?? null;
     if (!parent) return { world, parts: null };
     parent.updateWorldMatrix(true, false);
     const inv = parent.matrixWorld.clone().invert();
     const map = (v) => new THREE.Vector3(v[0], v[1], v[2]).applyMatrix4(inv).toArray();
     const up = new THREE.Vector3(world.up[0], world.up[1], world.up[2]).transformDirection(inv).toArray();
-    return { world, parts: { pos: map(world.pos), target: map(world.target), up, fov: world.fov } };
+    return {
+      world,
+      parts: {
+        pos: map(world.pos),
+        target: map(world.target),
+        up,
+        // Camera intrinsics, not coordinates: they describe the lens, so they
+        // cross frames unchanged. `fov` alone would leave a consumer reading
+        // only this frame with a null and no way to know an ortho camera
+        // caused it — the exact hole ANNOTATION_VERSION 2 exists to close.
+        projection: world.projection,
+        fov: world.fov,
+        orthoHeight: world.orthoHeight,
+      },
+    };
   }
 
   function send() {

package/src/framework/app.css

@@ -264,7 +264,8 @@ button.action:disabled { opacity: .5; cursor: default; }
 
 /* keyboard focus ring shared across the panel's interactive controls */
 .seg button:focus-visible, select.preset:focus-visible, .dl-row button:focus-visible,
-button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible, #viewbar button:focus-visible {
+button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible, #viewbar button:focus-visible,
+.pf-viewcube-toggle:focus-visible, .pf-float-rail-toggle:focus-visible {
   outline: none;
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
@@ -342,11 +343,128 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 #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
+/* ---- the rail toggle: a bare floating icon at the stage's top right --------
+   APPEARANCE only (placement lives in chrome.css, per the split at the top of
+   this file). Through 2026-08-20 this was the last button in #viewbar's pill;
+   it now floats on its own, in the corner diagonally opposite the pill.
+
+   Unadorned at rest — no background, no border, no shadow — so a control that
+   is always over the model reads as an icon the viewer carries rather than as a
+   second toolbar competing with the first. Explicitly a PLACEHOLDER ("just be a
+   floating icon for now"): the position is settled, the treatment is not.
+
+   38px is the MEASURED height of the centred view selector (`#topbar .seg`:
+   4px padding + a 28px tab + 4px + 2 hairlines, the same 38 on every page), and
+   the reference is that selector rather than #viewbar's 44px bar it briefly
+   matched: both floats sit at `top: 12px`, so equal heights put the two on one
+   line and their centres coincide by construction. Sizing to the selector is
+   also what keeps the hover chip from reading as oversized — the chip IS this
+   box. Note the trade: 38px is under the 44px tap-target floor
+   scripts/check-app.mjs enforces, and the check cannot see it, because it
+   measures targets at 320px where rail.js has already hidden this button.
+
+   A rounded rect, and deliberately NOT the view cube's projection circle: two
+   different controls in two different corners, where a shared silhouette would
+   invite reading one as the other. --pf-radius-control, the token `.seg` and its
+   tabs use, so the chip reads as part of the selector's family (the selector's
+   own outer corner is rounder — `#topbar .seg` overrides it to --pf-radius-pill).
+
+   The hover fill is WHITE, and that is a placeholder as well — asked for in as
+   many words, and true only over the dark viewer. Translucent rather than #fff
+   so it reads as a lift off the viewer instead of a hole punched in it, and so
+   the icon keeps its contrast on top; in the LIGHT theme a white fill is close
+   to invisible whatever the alpha. When this stops being a placeholder the fill
+   wants the --pf-surface family (--pf-surface-2, as `#viewbar button:hover`
+   uses) so both themes get a real surface — deliberately not substituted here.
+
+   The focus ring is NOT restated: the button joins the shared :focus-visible
+   selector list above. It used to inherit that through `#viewbar button`, which
+   no longer matches it. */
+.pf-float-rail-toggle {
+  width: 38px; height: 38px;
+  border: 0; border-radius: var(--pf-radius-control);
+  background: transparent; box-shadow: none;
+  color: var(--pf-muted-2); cursor: pointer;
+  font-size: 15px; line-height: 1;
+  display: flex; align-items: center; justify-content: center;
+}
+/* The same trap `#viewbar button[hidden]` guards against, inherited along with
+   the `display: flex` above: it is author-origin and beats the UA's
+   `[hidden] { display: none }`, so rail.js's `toggle.hidden = narrow` would
+   otherwise leave this fully visible below the narrow breakpoint — where the
+   pane tab bar owns pane selection and a second collapse affordance must not
+   compete with it. scripts/check-app.mjs asserts the computed display. */
+.pf-float-rail-toggle[hidden] { display: none; }
+.pf-float-rail-toggle:hover { color: var(--pf-text); background: rgb(255 255 255 / 14%); }
+/* GREY IN BOTH STATES, deliberately. rail.js still toggles `.on` when the rail
+   collapses, and inside #viewbar that class picked up the accent fill; there is
+   no rule for it here on purpose, so collapsed and expanded look identical. The
+   chevron `d` swap is the signal (it flips to point back out of the divider) and
+   aria-expanded carries it for assistive tech — a tint would have been a second
+   signal on a bare icon over the model, which is what the accent-coloured
+   version read as. Do not add one back without asking. */
+
+/* ---- view cube ------------------------------------------------------------
+   APPEARANCE only (placement lives in chrome.css, per the split at the top of
+   this file).
+
+   Through 2026-08-19 the projection toggle sat in its own `.pf-viewcube-pill`
+   card below the cube, deliberately borrowing #viewbar's chrome so it read as
+   one of the viewer controls. The 2026-08-20 revision moved it beside the
+   cube instead, at a size and a bottom-aligned baseline that a #viewbar-style
+   card could not shrink to — so it is now a small bare circle in its own
+   right (`.pf-viewcube-toggle`), no card, no border, no shadow.
+
+   A same-day follow-up moved it again, from beside the cube to OVER its
+   bottom-right corner (placement in chrome.css, as ever). Nothing here
+   changed: a bare transparent circle was already what made that legal — it
+   has no card edge to cut across the drawing underneath it, so overlapping
+   costs the cube nothing but the 24px it covers.
+
+   A later revision that same day took the resting fill away entirely: now
+   that the button sits ON the cube's drawing, a persistent accent-tinted
+   disc in orthographic mode read as a blob over the geometry rather than as
+   a control. A background appears on HOVER only, in both states.
+
+   The last revision of the day took the accent COLOUR away too, so the
+   orthographic state now carries exactly ONE visual signal: the icon GLYPH (a
+   perspective frustum becomes an axonometric box). The button is grey in both
+   projections, resting and hovered, and there is deliberately no `.on` rule
+   below — viewcube-controls.js still adds the class, and `aria-pressed` still
+   carries the state for assistive tech. That is a choice, not an oversight: a
+   blue icon sitting on the cube's own drawing read as a stray tint rather than
+   as a mode, and the glyph is the tell that survives any colour scheme anyway.
+   Do not reintroduce a tint without asking. */
+.pf-viewcube-canvas {
+  display: block;
+  touch-action: none;
+}
+.pf-viewcube-toggle {
+  /* 24px: the low end of "small" so the bare circle reads as understated next
+     to the cube rather than as a second focal point competing with it — a
+     card's border/background used to do that visual quieting; a transparent
+     shape has nothing else to lean on but size. */
+  width: 24px; height: 24px;
+  border: 0; border-radius: 50%;
+  background: transparent; box-shadow: none;
+  color: var(--pf-muted-2); cursor: pointer;
+  font-size: 14px; line-height: 1;
+  display: flex; align-items: center; justify-content: center;
+}
+.pf-viewcube-toggle:hover { color: var(--pf-text); background: var(--pf-surface-2); }
+/* The focus ring is NOT restated here: the toggle joins the shared
+   :focus-visible selector list above, beside #viewbar's own.
+
+   No narrow-width shrink rule here: unlike the old pill (which borrowed
+   #viewbar's chrome and had to shrink in lockstep with it, below), a bare
+   24px circle has no card to keep in step with a smaller viewbar — it stays
+   its one fixed size at every width. */
+
+/* At very narrow widths the full-size viewbar (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
+   Shrink the bar instead of letting it wrap — a two-row bar would need its
    own anchoring rework, while shrinking is a pure appearance change. */
 @media (max-width: 360px) {
   #viewbar { gap: 3px; }
@@ -355,7 +473,7 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
   #viewbar .pf-cutaway-actions button, #viewbar .pf-measure-actions button, #viewbar .pf-annotate-actions button { min-width: 44px; padding: 0 6px; }
   /* Annotate's three-button row (Undo/Clear/Send) is wider than cutaway's or
      measure's two-button rows at the shared size above, so it still clips the
-     pill's left edge at 320px — shrink it further than the shared rule. */
+     bar's left edge at 320px — shrink it further than the shared rule. */
   #viewbar .pf-annotate-actions button { min-width: 38px; padding: 0 4px; font-size: 10px; }
 }
 

package/src/framework/camera-orbit.js

@@ -0,0 +1,84 @@
+// Spherical orbit math, pure. Exists so the view cube can orbit the real camera
+// by handing the viewer a pixel delta, without importing three itself.
+//
+// The frame is the caller's `up`, not world +Y, because that is exactly what
+// OrbitControls does: it builds a quaternion taking object.up to +Y, once, at
+// construction. Working in the same frame is what makes orbitBy's answers agree
+// with a real drag on the canvas rather than merely resemble them.
+//
+// In today's viewer that `up` is always [0, 1, 0]: cameraPoseForView returns an
+// `up`, but tweenCameraTo drops it and camera-tween.js interpolates
+// {position, target} only, so nothing ever writes the live camera's `up` (bar
+// setProjection copying it across, and the throwaway capture cameras). The
+// antiparallel branch in upFrame is therefore defensive, not currently
+// reachable through the viewer — it is kept, and its equivariance test with it,
+// so this stays correct the day a caller does set `up`.
+//
+// Sign convention follows OrbitControls exactly: dragging right decreases theta,
+// dragging down decreases phi.
+
+const EPS = 1e-8;
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0],
+];
+const length = (a) => Math.hypot(a[0], a[1], a[2]);
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+
+// Rodrigues rotation of v about unit axis k by angle t.
+function rotate(v, k, t) {
+  const c = Math.cos(t), s = Math.sin(t);
+  const kv = cross(k, v);
+  const kd = dot(k, v) * (1 - c);
+  return [
+    v[0] * c + kv[0] * s + k[0] * kd,
+    v[1] * c + kv[1] * s + k[1] * kd,
+    v[2] * c + kv[2] * s + k[2] * kd,
+  ];
+}
+
+// A pair of functions taking `up` onto +Y and back again.
+function upFrame(up) {
+  const l = length(up);
+  if (l < EPS) return { to: (v) => v, from: (v) => v };
+  const u = [up[0] / l, up[1] / l, up[2] / l];
+  const axis = cross(u, [0, 1, 0]);
+  const al = length(axis);
+  if (al < EPS) {
+    // Parallel (already +Y) or antiparallel (upside down): a half turn about X.
+    if (dot(u, [0, 1, 0]) > 0) return { to: (v) => v, from: (v) => v };
+    const k = [1, 0, 0];
+    return { to: (v) => rotate(v, k, Math.PI), from: (v) => rotate(v, k, Math.PI) };
+  }
+  const k = [axis[0] / al, axis[1] / al, axis[2] / al];
+  const angle = Math.acos(clamp(dot(u, [0, 1, 0]), -1, 1));
+  return { to: (v) => rotate(v, k, angle), from: (v) => rotate(v, k, -angle) };
+}
+
+export function orbitPose(
+  { position, target, up = [0, 1, 0] },
+  { dx = 0, dy = 0 } = {},
+  { radiansPerPx = 0.005, minPolar = 1e-4, maxPolar = Math.PI - 1e-4 } = {},
+) {
+  const offset = sub(position, target);
+  const radius = length(offset);
+  // A camera sitting exactly on its target has no orbit to speak of; returning
+  // the pose untouched beats emitting NaN.
+  if (radius < EPS) return { position: [...position], target: [...target] };
+
+  const frame = upFrame(up);
+  const o = frame.to(offset);
+  const theta = Math.atan2(o[0], o[2]) - dx * radiansPerPx;
+  const phi = clamp(Math.acos(clamp(o[1] / radius, -1, 1)) - dy * radiansPerPx, minPolar, maxPolar);
+  const sinPhi = Math.sin(phi);
+  const next = [
+    radius * sinPhi * Math.sin(theta),
+    radius * Math.cos(phi),
+    radius * sinPhi * Math.cos(theta),
+  ];
+  return { position: add(target, frame.from(next)), target: [...target] };
+}

package/src/framework/camera-tween.js

@@ -1,18 +1,30 @@
 import * as THREE from "three";
 import { EASINGS } from "./animation.js";
 
-// Retargetable orbit-camera tween for animation camera cues: eased spherical
-// interpolation of {position, target} pairs about the (linearly moving) orbit
-// target, shortest-path in azimuth, clamped off the poles so OrbitControls
-// never gimbal-locks on a "top"/"bottom" cue. Pure math, no clock — the viewer
-// feeds dt seconds into update() each frame and applies the returned pose.
-const POLE_EPS = 0.01;
-
+// Retargetable orbit-camera tween for animation camera cues and view-cube
+// clicks: eased spherical interpolation of {position, target} pairs about the
+// (linearly moving) orbit target, shortest-path in azimuth. Pure math, no clock
+// — the viewer feeds dt seconds into update() each frame and applies the
+// returned pose.
+//
+// NOT clamped off the poles. It used to be, by 0.01 rad, to keep OrbitControls
+// off its gimbal — but the clamp applied to the DESTINATION too, so a "top" or
+// "bottom" cue landed 0.573° short of the axis every single time, in both
+// projections. That is the whole of the "clicking top doesn't view from the top"
+// bug: a spacer kept a sliver of side wall visible instead of reading as a flat
+// outline.
+//
+// Landing exactly on the pole is safe, because OrbitControls' own update() is
+// the backstop: Spherical.makeSafe() holds phi off 0 and PI by 1e-6 rad (a
+// 5.7e-5° tilt, three orders of magnitude under what the eye or a frustum can
+// resolve), so the camera is never left with a degenerate lookAt basis and the
+// roll stays deterministic. Azimuth at the pole is a no-op either way, and
+// atan2(0, 0) is 0 rather than NaN — which is also the azimuth the canonical
+// top/bottom poses ask for, so the roll OrbitControls derives there is exactly
+// the `up` view-angles.js names for them.
 function toSpherical(position, target) {
   const off = new THREE.Vector3().fromArray(position).sub(new THREE.Vector3().fromArray(target));
-  const sph = new THREE.Spherical().setFromVector3(off);
-  sph.phi = Math.min(Math.PI - POLE_EPS, Math.max(POLE_EPS, sph.phi));
-  return sph;
+  return new THREE.Spherical().setFromVector3(off);
 }
 
 export function createCameraTween() {