partforge 0.72.0 → 0.73.1

package/src/framework/chrome.css

@@ -225,9 +225,119 @@
    (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; }
+.pf-float-tabs, .pf-float-viewbar, .pf-float-rail-toggle { position: absolute; z-index: 15; }
+/* Every inset below is SHARED with whichever other float sits on that edge, so
+   the stage's margin is stated once per edge and not once per element. The rail
+   toggle (2026-08-20: out of #viewbar's pill, floating on its own at the top
+   right) is the tab strip's `top` with the viewbar's `right` — a corner
+   symmetric with the viewbar's, by construction rather than by two numbers that
+   happen to agree today. Retune the margin and all three corners follow.
+   Appearance, including the `[hidden]` guard that lets rail.js hide the toggle
+   below the narrow breakpoint, is in app.css. */
+.pf-float-tabs, .pf-float-rail-toggle { top: 12px; }
+.pf-float-viewbar, .pf-float-rail-toggle { right: 12px; }
+.pf-float-tabs { left: 50%; transform: translateX(-50%); }
+.pf-float-viewbar { bottom: 12px; }
+
+/* ---- view cube stack: PLACEMENT ONLY (see the rule above) ----------------
+   Bottom-right, stacked above #viewbar. The offset is measured, not
+   hardcoded: mount.js publishes --pf-viewbar-clear on the stage from a
+   ResizeObserver on #viewbar, mirroring --pf-anim-clear. It sits there rather
+   than in viewcube-controls.js (the precedent being animation-controls.js,
+   which publishes its own --pf-anim-clear) because the value describes the
+   VIEWBAR's vertical claim, not the cube's, and mount owns both elements. The
+   56px fallback is the standard viewbar's 12px bottom + 44px height, so the
+   stack still sits right if the observer never fires.
+
+   The projection toggle has moved twice. Through 2026-08-19 it sat in its own
+   `.pf-viewcube-pill` card BELOW the cube, making the stack a column. Earlier
+   on 2026-08-20 it became a bare circle BESIDE the cube, making the stack a
+   `row-reverse` flex row (`canvas + gap + button`, 167px wide at the full
+   135px cube). It now sits OVER the cube's bottom-right corner instead:
+   absolutely positioned within the stack, right edge on the stack's right edge
+   and bottom edge on its bottom baseline, so the stack's width collapses back
+   to the canvas alone (135px, or 101 below the narrow breakpoint).
+
+   That is also what satisfies "aligned with the right of the toolbar" without a
+   second offset: `.pf-float-viewbar` above is `right: 12px` too, so making the
+   button's right edge the STACK's right edge lines it up with the viewbar's by
+   construction — and it keeps doing so if that margin is ever retuned.
+
+   The button is a later sibling than the cube's wrapper, so it paints over the
+   canvas with no z-index of its own; 24px over the corner cell — the least
+   informative part of the drawing — is small enough not to hide anything worth
+   clicking, and the canvas keeps receiving pointer events everywhere else.
+
+   The 8px that used to sit between the stack and the viewbar is now 3px
+   (2026-08-20: "lower the whole box so it's closer to the bottom bar"). 3
+   rather than 0 because the stack's own box MUST NOT overlap #viewbar: the
+   stack is a later sibling at the same z-index, and its canvas is
+   pointer-events:auto across its whole footprint, so any vertical overlap
+   would silently swallow clicks on the viewbar's rightmost buttons (both are
+   right: 12px). --pf-viewbar-clear is published rounded to whole px, so a
+   fractional viewbar height can move this by half a pixel either way; 3px
+   absorbs that and still reads as a deliberate gap rather than a collision.
+   The other ~5px of the lowering comes from inside the canvas — see
+   cube-geom.js's CUBE_DOWN_BIAS_PX; that is where the rest of the perceived
+   gap actually lives, and it is capped by the axis labels' clearance, so
+   this pair (3 + 5) is the whole slack that exists without either overlapping
+   the viewbar or shrinking the cube.
+
+   The stack itself is pointer-transparent. With the button back inside the
+   canvas's footprint there is no dead gap left at all: the stack's box IS the
+   canvas's box, and both the canvas and the button opt back in below. The
+   declaration stays because the stack's own box is still an element over the
+   viewer, and a stray hit on it (its padding-free edges, or a future child
+   before it opts in) should reach the model behind rather than be swallowed. */
+.pf-viewcube-stack {
+  position: absolute;
+  right: 12px;
+  bottom: calc(var(--pf-viewbar-clear, 56px) + 3px);
+  z-index: 15;
+  display: flex;
+  pointer-events: none;
+}
+.pf-viewcube-stack[hidden] { display: none; }
+.pf-viewcube-canvas, .pf-viewcube-toggle { pointer-events: auto; }
+/* Over the cube's bottom-right corner. Absolute against the stack, which is
+   itself absolute and so already the containing block. */
+.pf-viewcube-toggle { position: absolute; right: 0; bottom: 0; }
+
+/* The keyboard surface: six per-view buttons standing in for the DOM focus a
+   canvas cannot give us. Visually hidden rather than display:none — the latter
+   takes them out of the tab order, which is the whole point of them.
+
+   The hiding properties are on the BUTTONS, not on their wrapper, so that
+   :focus-visible can undo them. A non-`none` clip-path clips the element's
+   whole SUBTREE and makes the element a containing block for fixed-position
+   descendants, so with the clip on the wrapper no rule on a focused child
+   could escape it — the reveal below was dead CSS, and six buttons sat in the
+   tab order with no visible focus indicator at all. On the buttons themselves
+   there is no clipping ancestor to get out of.
+
+   The wrapper keeps only `position: absolute`, which takes it out of the
+   stack's flex flow. That mattered when the stack had a gap (a zero-height
+   flex item still earned it, pushing the cube out of place); it still matters
+   now that it does not, because an in-flow second item would widen the stack
+   past the canvas — and the stack's width is what the crowding rule reads. */
+.pf-viewcube-key { position: absolute; }
+.pf-viewcube-key button {
+  position: absolute;
+  width: 1px; height: 1px;
+  margin: -1px; padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+.pf-viewcube-key button:focus-visible {
+  position: fixed;
+  width: auto; height: auto;
+  margin: 0; padding: 2px 6px;
+  overflow: visible;
+  clip-path: none;
+  pointer-events: auto; /* the stack is pointer-transparent; a revealed control is not */
+}
 
 /* --- animation transport bar (generated by animation-controls.js) ----------
    PLACEMENT ONLY, per the rule above; appearance lives in app.css next to

package/src/framework/cutaway-gizmo.js

@@ -44,7 +44,7 @@ const WHITE = new THREE.Color(0xffffff);
 export function createCutawayGizmo({
   scene,
   overlayScene,
-  camera,
+  camera: initialCamera,
   domElement,
   orbitControls,
   onPoseChange = () => {},
@@ -53,6 +53,10 @@ export function createCutawayGizmo({
   onDragChange = () => {},
   pickHandle,
 }) {
+  // Reassignable: the viewer swaps cameras when the projection toggle flips,
+  // and this module holds fifteen references to it. One binding to move beats
+  // threading a getter through all of them.
+  let camera = initialCamera;
   const sceneGraph = buildGizmoScene(THEMES.dark);
   const {
     group,
@@ -535,6 +539,7 @@ export function createCutawayGizmo({
     setActiveAppearance,
     setTheme,
     updateForCamera,
+    setCamera(next) { if (next) camera = next; },
     dispose,
   };
 }

package/src/framework/cutaway.js

@@ -32,7 +32,7 @@ function validBounds(getBounds) {
 export function createCutaway({
   renderer,
   scene,
-  camera,
+  camera: initialCamera,
   orbitControls,
   domElement,
   getBounds,
@@ -40,6 +40,9 @@ export function createCutaway({
   schedule = defaultSchedule,
   now,
 }) {
+  // Reassignable: a projection swap (perspective <-> ortho) hands the cutaway
+  // a new camera after construction, and the gizmo must follow it too.
+  let camera = initialCamera;
   let supported = false;
   try {
     supported = Boolean(
@@ -522,6 +525,11 @@ export function createCutaway({
     updateForCamera,
     renderOverlay,
     onHandleHoverChange,
+    setCamera(next) {
+      if (!next) return;
+      camera = next;
+      gizmo?.setCamera(next);
+    },
     dispose,
     _renderSetFor: (name) => renderSets.get(name)?.renderSet ?? null,
     _setDragging: setDragging,

package/src/framework/measure/dim3-place.js

@@ -221,22 +221,91 @@ export function choicesEqual(a, b) {
 // The vertex realizing the extreme along `axis` over the posed meshes; ties
 // within tolerance (a flat base is all "the minimum") break toward `near`, so
 // the anchor lands on the side of the part the dimension is drawn on.
+//
+// placeBox asks for all six ±axis directions, and the naive shape of this —
+// one pass to find the extreme, a second to tie-break, per call — walked every
+// vertex twelve times over. On a soup carrying three points per triangle that
+// is the dominant cost of a placement, so the walk happens ONCE per (geometry,
+// pose) and every later call is answered from `extremeCache`: the six extreme
+// VALUES, plus, per direction, the posed vertices tied with that direction's
+// own extreme. `near` varies per call (it is the side the dim hangs off), so
+// the tie-break itself still runs — over the handful of tied points instead of
+// the whole soup.
+//
+// Per-mesh candidates are exact for the multi-mesh scan they feed: a vertex
+// within TIE_TOL of the GLOBAL extreme is necessarily within TIE_TOL of its own
+// mesh's extreme too (the mesh extreme sits between them), so nothing that
+// could win is missing from the union — and the loop below re-filters against
+// the global value regardless.
+//
+// A candidate is stored as its INDEX into the soup, not as a posed point: four
+// bytes instead of twenty-four, and the tie-break still runs the same f64
+// transform the un-cached version did, so the anchor it picks is bit-identical.
+// The size question that buys is a real one — most parts sit on a flat face, so
+// one direction's tie set can be a whole face of the mesh — and on the parts
+// this was measured against the whole cache lands around 0.1% of the soup.
+const TIE_TOL = 1e-3;
+// The extremes and the tie sets are both POSED, so a record is only valid for
+// the pose it was built from. A mesh's `matrix` is mutated in place by the
+// viewer's pose fast path (setSubPose), so identity says nothing about it — the
+// sixteen elements do.
+const extremeCache = new WeakMap(); // positions -> { pose, lo, hi, cand: Uint32Array[6] }
 const _sv = new THREE.Vector3();
-export function extremeVertex(meshData, axis, sign, near) {
-  let bestVal = sign > 0 ? -Infinity : Infinity;
-  for (const { positions, matrix } of meshData) {
+
+const dirIndex = (axis, sign) => axis * 2 + (sign > 0 ? 0 : 1);
+
+const samePose = (a, b) => {
+  for (let i = 0; i < 16; i++) if (a[i] !== b[i]) return false;
+  return true;
+};
+
+function meshExtremes(positions, matrix) {
+  const hit = extremeCache.get(positions);
+  if (hit && samePose(hit.pose, matrix.elements)) return hit;
+  const lo = [Infinity, Infinity, Infinity];
+  const hi = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < positions.length; i += 3) {
+    _sv.set(positions[i], positions[i + 1], positions[i + 2]).applyMatrix4(matrix);
+    for (let a = 0; a < 3; a++) {
+      const v = _sv.getComponent(a);
+      if (v < lo[a]) lo[a] = v;
+      if (v > hi[a]) hi[a] = v;
+    }
+  }
+  const cand = [[], [], [], [], [], []];
+  if (Number.isFinite(lo[0])) {
     for (let i = 0; i < positions.length; i += 3) {
       _sv.set(positions[i], positions[i + 1], positions[i + 2]).applyMatrix4(matrix);
-      const val = _sv.getComponent(axis);
-      if (sign > 0 ? val > bestVal : val < bestVal) bestVal = val;
+      for (let a = 0; a < 3; a++) {
+        const v = _sv.getComponent(a);
+        if (Math.abs(v - hi[a]) <= TIE_TOL) cand[a * 2].push(i);
+        if (Math.abs(v - lo[a]) <= TIE_TOL) cand[a * 2 + 1].push(i);
+      }
     }
   }
+  const rec = { pose: matrix.elements.slice(), lo, hi, cand: cand.map((c) => Uint32Array.from(c)) };
+  extremeCache.set(positions, rec);
+  return rec;
+}
+
+export function extremeVertex(meshData, axis, sign, near) {
+  const dir = dirIndex(axis, sign);
+  let bestVal = sign > 0 ? -Infinity : Infinity;
+  const scan = [];
+  for (const { positions, matrix } of meshData) {
+    const rec = meshExtremes(positions, matrix);
+    const v = sign > 0 ? rec.hi[axis] : rec.lo[axis];
+    if (!Number.isFinite(v)) continue; // empty mesh
+    scan.push({ positions, matrix, cand: rec.cand[dir] });
+    if (sign > 0 ? v > bestVal : v < bestVal) bestVal = v;
+  }
   if (!Number.isFinite(bestVal)) return null;
   let best = null, bestD = Infinity;
-  for (const { positions, matrix } of meshData) {
-    for (let i = 0; i < positions.length; i += 3) {
+  for (const { positions, matrix, cand } of scan) {
+    for (let k = 0; k < cand.length; k++) {
+      const i = cand[k];
       _sv.set(positions[i], positions[i + 1], positions[i + 2]).applyMatrix4(matrix);
-      if (Math.abs(_sv.getComponent(axis) - bestVal) > 1e-3) continue;
+      if (Math.abs(_sv.getComponent(axis) - bestVal) > TIE_TOL) continue;
       const d = _sv.distanceToSquared(near);
       if (d < bestD) { bestD = d; best = _sv.clone(); }
     }

package/src/framework/measure/dim3-scene.js

@@ -58,6 +58,13 @@ export function worldPerPx(dist, fovDeg, viewportPx) {
   return (2 * dist * Math.tan((fovDeg * Math.PI) / 360)) / viewportPx;
 }
 
+// The orthographic twin of worldPerPx. An ortho camera's scale is a property of
+// its frustum and zoom alone — distance does not enter — which is exactly why
+// the perspective formula cannot be reused with a substituted fov.
+export function orthoWorldPerPx(top, bottom, zoom, viewportPx) {
+  return Math.abs(top - bottom) / Math.max(zoom, 1e-6) / Math.max(viewportPx, 1);
+}
+
 // Kept for compatibility with earlier callers/tests: the world height that
 // renders as `targetPx` on screen.
 export function labelWorldHeight(dist, fovDeg, viewportPx, targetPx = LABEL_SCREEN_PX) {
@@ -319,8 +326,14 @@ export function createDimScene(viewer, { paintLabel = defaultPaintLabel } = {})
     // One shared reference distance — camera to the dim group's origin (the
     // recentred model centre) — sizes the whole drawing.
     group.getWorldPosition(_gp);
-    const dist = viewer.camera.position.distanceTo(_gp);
-    const wpp = worldPerPx(dist, viewer.camera.fov ?? 45, h);
+    // `viewer.camera.fov ?? 45` was the bug this branch removes: under an ortho
+    // camera fov is undefined, so the fallback produced a plausible-but-wrong
+    // scale and every label, arrow and standoff drifted as the user dollied.
+    // The ortho formula matches cutaway-gizmo.js:485's worldUnitsPerPixelAt.
+    const cam = viewer.camera;
+    const wpp = cam.isOrthographicCamera
+      ? orthoWorldPerPx(cam.top, cam.bottom, cam.zoom, h)
+      : worldPerPx(cam.position.distanceTo(_gp), cam.fov ?? 45, h);
     if (wpp > 0) {
       const hStar = LABEL_SCREEN_PX * wpp;
       const aw = ARROW_SCREEN_PX * wpp;

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

@@ -19,6 +19,35 @@ import { createPinStore, occurrenceOf } from "./pins.js";
 import { evaluateChoices, choicesEqual, placeDims, specSig, laneCounts } from "./dim3-place.js";
 import { createDimScene } from "./dim3-scene.js";
 
+// How many distinct placements each cache holds. An orbit sweeps a bounded set
+// of side choices, and a session hovers a bounded set of features; anything
+// past that is ground the user has moved on from. Entries are plain drawing
+// records (numbers, no GL objects), so the ceiling is about retention hygiene
+// on a memory-tight device, not about a runaway.
+const PLACEMENT_CACHE_LIMIT = 32;
+
+// Bounded LRU. A Map iterates in insertion order, so re-inserting on a hit
+// moves the entry to the back and the oldest key is always the first one out.
+function keyedCache(limit) {
+  const entries = new Map();
+  return {
+    get(key) {
+      if (!entries.has(key)) return undefined;
+      const value = entries.get(key);
+      entries.delete(key);
+      entries.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      entries.delete(key);
+      entries.set(key, value);
+      if (entries.size > limit) entries.delete(entries.keys().next().value);
+      return value;
+    },
+    clear() { entries.clear(); },
+  };
+}
+
 export function createMeasureMode(viewer, { part, getContext, revealParams, getParamsVersion, schedule = (cb) => requestAnimationFrame(cb) }) {
   const pins = createPinStore();
   const pinListeners = new Set();
@@ -218,7 +247,23 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
   // hover dim, which changes on every pointer move. placeBox scans every
   // vertex of the meshes it covers (tens of ms on a big part), so re-placing
   // the whole set per hover frame is the one path that must not exist.
-  const baseCache = { key: null, drawings: [] };
+  //
+  // Both caches are KEYED and bounded rather than one slot each. A one-slot
+  // cache is right for a monotonic sequence and wrong for an orbit, which
+  // sweeps back and forth over the same handful of side choices — measured at
+  // ~15 flips per 360° turn, every one of them a full re-place of ground
+  // already covered. Keyed, an orbit places each distinct choice once.
+  const baseCache = keyedCache(PLACEMENT_CACHE_LIMIT);
+  // ...and the PAINTED list — base plus the hover dim — cached the same way, on
+  // the base key plus everything the hover pass alone depends on. The hover
+  // spec is identical for every pointer position over one feature, so without
+  // this a pointer resting on a face re-ran that item's vertex scan and its
+  // surface raycasts on every single rAF.
+  const paintCache = keyedCache(PLACEMENT_CACHE_LIMIT);
+  // The drawing list currently on screen, held by IDENTITY: scene.update()
+  // rebuilds every child object (and repaints every label texture), so a list
+  // the cache just handed back unchanged must not reach it.
+  let painted = null;
   const _rc = new THREE.Raycaster();
   const _origin = new THREE.Vector3();
   const _dir = new THREE.Vector3();
@@ -274,12 +319,26 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
     return key;
   }
 
+  // The hover half of the choice table, which baseCacheKey deliberately omits
+  // (hover entries come and go with the pointer and must not evict the base).
+  // A camera move that flips which side the hovered dim hangs off has to
+  // re-place it, so the paint key carries them.
+  function hoverChoiceKey() {
+    let key = "";
+    for (const ck of Object.keys(choices)) {
+      if (!ck.startsWith("hover|")) continue;
+      const c = choices[ck];
+      key += `|${ck}=${c.key ?? ""}${c.du ? `,${c.du.map((n) => n.toFixed(4))}` : ""}`;
+    }
+    return key;
+  }
+
   function rebuild() {
     if (!enabled || !scene) return;
     const { items, meshes, bounds } = buildItems();
     lastItems = items;
     lastBounds = bounds ?? null;
-    if (!items.length || !bounds) { scene.clear(); baseCache.key = null; return; }
+    if (!items.length || !bounds) { scene.clear(); painted = null; return; }
     const env = buildEnv(meshes);
     choices = evaluateChoices(items, { camPos: env.camPos, center: centerOf(bounds), prev: choices });
     const place = (list, suppress, lanes) =>
@@ -287,10 +346,8 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
     const hoverItem = items.find((i) => i.id === "hover");
     const baseItems = hoverItem ? items.filter((i) => i !== hoverItem) : items;
     const key = baseCacheKey(`${units}|${meshSig()}`, baseItems);
-    if (baseCache.key !== key) {
-      baseCache.key = key;
-      baseCache.drawings = place(baseItems);
-    }
+    let baseDrawings = baseCache.get(key);
+    if (!baseDrawings) baseDrawings = baseCache.set(key, place(baseItems));
     // The hover pass can't see the base pass's items (they're cached), so it
     // hands over (a) their sigs as `suppress` — a hover duplicating an
     // already-drawn measurement (the sub-part bounds over the overall, a
@@ -298,13 +355,20 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
     // occupancy, so a hovered dim staggers into the SAME lane it will occupy
     // once pinned (pins append after the base items in the same order) and
     // clicking never moves it.
-    scene.update(hoverItem
-      ? baseCache.drawings.concat(place(
-          [hoverItem],
-          new Set(baseItems.map((i) => specSig(i.spec))),
-          laneCounts(baseCache.drawings),
-        ))
-      : baseCache.drawings);
+    const paintKey = hoverItem
+      ? `h|${key}|${specSig(hoverItem.spec)}|${hoverChoiceKey()}`
+      : `b|${key}`;
+    let drawings = paintCache.get(paintKey);
+    if (!drawings) {
+      drawings = paintCache.set(paintKey, hoverItem
+        ? baseDrawings.concat(place(
+            [hoverItem],
+            new Set(baseItems.map((i) => specSig(i.spec))),
+            laneCounts(baseDrawings),
+          ))
+        : baseDrawings);
+    }
+    if (painted !== drawings) { painted = drawings; scene.update(drawings); }
   }
 
   // ---- frame dirty check ---------------------------------------------------
@@ -500,8 +564,9 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
       scene?.clear();
       lastItems = [];
       lastBounds = null;
-      baseCache.key = null;
-      baseCache.drawings = [];
+      baseCache.clear();
+      paintCache.clear();
+      painted = null;
       dom.style.cursor = "";
     }
     notifyMode();

package/src/framework/mount.js

@@ -6,7 +6,7 @@ import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
-import { loadCamera } from "./view-state.js";
+import { loadCamera, loadProjection, saveProjection } from "./view-state.js";
 import { buildControls } from "./controls.js";
 import { relevantParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
@@ -30,6 +30,7 @@ import { createMeasureMode } from "./measure/measure-mode.js";
 import { attachMeasureControls } from "./measure/measure-controls.js";
 import { createAnnotateMode } from "./annotate/annotate-mode.js";
 import { attachAnnotateControls } from "./annotate/annotate-controls.js";
+import { attachViewcubeControls } from "./viewcube/viewcube-controls.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
@@ -59,7 +60,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -106,6 +107,13 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // the built-in pencil button. send() delivers to onAnnotationSend and
     // returns false when there is no ink or the capture failed.
     annotate: annotate ?? NOOP_ANNOTATE,
+    // Projection is a viewer-wide display mode, not a part property — same
+    // shape as `measure` and `annotate` so a host reads one convention.
+    projection: projection ?? {
+      get: () => "perspective",
+      set: () => {},
+      onChange: () => () => {},
+    },
   };
 }
 
@@ -203,6 +211,10 @@ function createCleanupStack() {
 //                                 // subscribes return an unsubscribe; onInkChange fires on
 //                                 // every stroke/undo/clear, which is what a host driving its
 //                                 // own Send button gates that button on (strokeCount() > 0).
+//   runtime.projection: { get, set, onChange }
+//                                         // "perspective" | "orthographic". Drives the LIVE view
+//                                         // and captureCurrent only — captureCanonicalViews,
+//                                         // renderMeshPayloads and the CLI stay perspective.
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
@@ -412,6 +424,55 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       annotate: els.chrome.annotate,
     }, { tooltip, escapeScope: els.viewer, send: annotateSend });
     cleanup.defer(() => annotateChrome.detach());
+    // Orientation cube + projection toggle. Generated chrome — no host markup
+    // declares it, so an embedder gets it for free. Restored BEFORE any framing
+    // happens so a reload into ortho frames once instead of framing in
+    // perspective and then visibly re-framing.
+    viewer.setProjection(loadProjection());
+    const viewcube = attachViewcubeControls(viewer, { stage: els.viewer }, { tooltip });
+    cleanup.defer(() => viewcube.detach());
+    cleanup.defer(viewer.onProjectionChange((mode) => saveProjection(mode)));
+    // setHidden takes one boolean, and there are two independent reasons to hide
+    // the cube: Sketch mode (below) and a crowded transport bar (wired into the
+    // animation controls further down). Applied straight, whichever fires last
+    // would win — leaving Sketch would reveal a cube that crowding still wants
+    // gone. Track a flag per reason and OR them through one place, the
+    // syncHoverSuppression precedent below.
+    let cubeHiddenForSketch = false;
+    let cubeHiddenForCrowding = false;
+    const syncViewcubeHidden = () =>
+      viewcube.setHidden(cubeHiddenForSketch || cubeHiddenForCrowding);
+    // Sketch freezes the view on purpose: ink is stored in screen space and is
+    // meaningful only against the pose it was drawn over. A live camera control
+    // on top of that — orbit OR a projection swap — invalidates the drawing.
+    if (annotateMode) {
+      cleanup.defer(annotateMode.onModeChange(() => {
+        cubeHiddenForSketch = annotateMode.isEnabled();
+        syncViewcubeHidden();
+      }));
+    }
+    // Publish the viewbar's vertical claim so chrome.css can stack the cube on
+    // top of it without hardcoding a height that cutaway/measure/annotate
+    // action rows can change.
+    const viewbarEl = els.viewer.querySelector("#viewbar");
+    if (viewbarEl && typeof ResizeObserver === "function") {
+      const publishViewbarClear = () => {
+        const stageRect = els.viewer.getBoundingClientRect();
+        const barRect = viewbarEl.getBoundingClientRect();
+        els.viewer.style.setProperty(
+          "--pf-viewbar-clear",
+          `${Math.max(0, Math.round(stageRect.bottom - barRect.top))}px`,
+        );
+      };
+      const viewbarObserver = new ResizeObserver(publishViewbarClear);
+      viewbarObserver.observe(viewbarEl);
+      viewbarObserver.observe(els.viewer);
+      publishViewbarClear();
+      cleanup.defer(() => {
+        viewbarObserver.disconnect();
+        els.viewer.style.removeProperty("--pf-viewbar-clear");
+      });
+    }
     // escapeScope: cutaway's Flip/Reset buttons are canvas SIBLINGS inside
     // #viewbar, not descendants of the canvas — attaching Escape to
     // viewer.domElement alone would leave a guarded Escape from those buttons
@@ -836,6 +897,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       applyValues: applyAnimationValues,
       getParamValues: (keys) => Object.fromEntries(keys.map((k) => [k, params[k]])),
       getView: view,
+      // On a narrow stage the transport bar has to cap its own width to stay
+      // clear of the bottom-right cluster, and under that cap its controls fall
+      // below the 44px tap target. The cube gives way instead — it is the
+      // reclaimable half of that cluster. Nothing here keys on the viewport
+      // width: a part with no animations, or one whose bar fits, keeps its cube
+      // at every size. syncViewcubeHidden and the viewcube itself are both
+      // declared above this point, so this can never fire into a hole.
+      onCrowded: (crowded) => {
+        cubeHiddenForCrowding = crowded;
+        syncViewcubeHidden();
+      },
     });
     if (animCtl) cleanup.defer(() => animCtl.detach());
 
@@ -944,6 +1016,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         onInkChange: annotateMode.onInkChange,
         onModeChange: annotateMode.onModeChange,
       } : null,
+      projection: {
+        get: () => viewer.getProjection(),
+        set: (mode) => viewer.setProjection(mode),
+        onChange: (cb) => viewer.onProjectionChange(cb),
+      },
     });
   } catch (error) {
     try {

package/src/framework/projection.js

@@ -0,0 +1,19 @@
+// The perspective <-> orthographic framing pair. Pure, so the swap's only
+// interesting property — that the part does not change size the instant the
+// user hits the toggle — is unit-testable without a renderer.
+//
+// Perspective frames by DISTANCE; orthographic frames by a frustum height plus
+// a zoom (OrbitControls dollies an ortho camera by changing camera.zoom, not by
+// moving it). These two functions convert between the two descriptions.
+
+const halfHeightAt = (fovDeg, distance) => distance * Math.tan((fovDeg * Math.PI) / 360);
+
+export function orthoFrustum({ fovDeg, distance, aspect = 1 }) {
+  const halfH = halfHeightAt(fovDeg, distance);
+  const halfW = halfH * aspect;
+  return { halfW, halfH, left: -halfW, right: halfW, top: halfH, bottom: -halfH };
+}
+
+export function perspectiveDistance({ halfH, zoom = 1, fovDeg }) {
+  return halfH / (zoom * Math.tan((fovDeg * Math.PI) / 360));
+}