partforge 0.72.0 → 0.73.0

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-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/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));
+}

package/src/framework/view-angles.js

@@ -15,13 +15,81 @@ const DIRS = {
   right:  { dir: [1, 0, 0],   up: [0, 1, 0] },
 };
 
+// The view cube's 26 orientations: 6 faces, 12 edges, 8 corners. Deliberately
+// SEPARATE from CANONICAL_VIEWS, which stays at 7 — captureViewsFromScene
+// slices against its length and the CLI names it, so growing that list would
+// change contracts the cube has no business touching. The seven canonical
+// names resolve to identical poses (iso === top-front-right).
+//
+// Face names are MODEL-frame (parts are authored Z-up); the world directions
+// below already carry the pivot's rotation.x = -PI/2, which maps model
+// (x, y, z) -> world (x, z, -y).
+const FACE_DIRS = {
+  right:  [1, 0, 0],   // model +X
+  left:   [-1, 0, 0],  // model -X
+  top:    [0, 1, 0],   // model +Z
+  bottom: [0, -1, 0],  // model -Z
+  front:  [0, 0, 1],   // model -Y
+  back:   [0, 0, -1],  // model +Y
+};
+
+// Canonical id ordering. A compound id always reads vertical, then depth, then
+// side — "top-front-right", never "right-front-top" — so cube-geom.js can
+// assemble an id from three independent axis choices and land on the same
+// string every time.
+const VERTICAL = ["top", "bottom"];
+const DEPTH = ["front", "back"];
+const SIDE = ["left", "right"];
+
+// A pure top or bottom view is degenerate against a +Y up vector, so those two
+// keep the special-cased ups DIRS already used. Every compound orientation has
+// a well-defined +Y up.
+//
+// These ups matter to the OFFSCREEN capture path, which builds a temp camera and
+// calls lookAt itself with no orbit frame to fall back on. The LIVE camera never
+// needs them: it is driven through OrbitControls, whose polar frame derives the
+// same roll on its own at azimuth 0 (a top cue lands with screen-up on world -Z,
+// which is exactly [0, 0, -1]). Handing the live camera a non-+Y `up` would also
+// re-base every subsequent orbit drag and would not survive getCameraState, so it
+// deliberately keeps the default.
+function upFor(parts) {
+  if (parts.length === 1 && parts[0] === "top") return [0, 0, -1];
+  if (parts.length === 1 && parts[0] === "bottom") return [0, 0, 1];
+  return [0, 1, 0];
+}
+
+function buildOrientations() {
+  const out = {};
+  const add = (parts) => {
+    const dir = [0, 0, 0];
+    for (const part of parts) {
+      const d = FACE_DIRS[part];
+      dir[0] += d[0];
+      dir[1] += d[1];
+      dir[2] += d[2];
+    }
+    const id = parts.join("-");
+    out[id] = { id, parts: [...parts], dir, up: upFor(parts) };
+  };
+  for (const face of Object.keys(FACE_DIRS)) add([face]);
+  for (const v of VERTICAL) for (const other of [...DEPTH, ...SIDE]) add([v, other]);
+  for (const d of DEPTH) for (const s of SIDE) add([d, s]);
+  for (const v of VERTICAL) for (const d of DEPTH) for (const s of SIDE) add([v, d, s]);
+  return out;
+}
+
+export const ORIENTATIONS = buildOrientations();
+export const ORIENTATION_IDS = Object.keys(ORIENTATIONS);
+
 const norm = (v) => {
   const l = Math.hypot(v[0], v[1], v[2]) || 1;
   return [v[0] / l, v[1] / l, v[2] / l];
 };
 
 export function cameraPoseForView(view, { center, radius }) {
-  const a = DIRS[view];
+  // DIRS first so the seven canonical names keep their exact existing poses;
+  // ORIENTATIONS covers the other nineteen the cube can reach.
+  const a = DIRS[view] ?? ORIENTATIONS[view];
   if (!a) throw new Error(`unknown canonical view "${view}"`);
   const d = norm(a.dir);
   const dist = radius * 2.6 + 6; // matches viewer.frameTo's framing distance

package/src/framework/view-state.js

@@ -11,6 +11,7 @@
 const KEY = {
   camera: "partforge:camera",
   theme: "partforge:theme",
+  projection: "partforge:projection",
 };
 
 const viewKey = (partKey) => `partforge:view:${partKey}`;
@@ -55,6 +56,14 @@ export function saveTheme(mode) {
   if (mode === "light" || mode === "dark") write(KEY.theme, mode);
 }
 
+export function loadProjection() {
+  return read(KEY.projection) === "orthographic" ? "orthographic" : "perspective";
+}
+
+export function saveProjection(mode) {
+  if (mode === "perspective" || mode === "orthographic") write(KEY.projection, mode);
+}
+
 // `partKey` identifies the part — createViewTabs passes `meta.title`. Without one
 // there is nothing safe to key on, so both calls no-op rather than falling back to a
 // shared key (the cross-part bleed this scoping exists to remove).