partforge 0.87.0 → 0.89.0

package/src/framework/app.css

@@ -278,7 +278,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,
-.pf-viewcube-toggle:focus-visible, .pf-float-rail-toggle:focus-visible {
+.pf-view-select:focus-visible,
+.pf-viewcube-toggle:focus-visible, .pf-float-rail-toggle:focus-visible, .pf-sketch-toolbar button:focus-visible {
   outline: none;
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
@@ -299,14 +300,65 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
   border-radius: var(--pf-radius-pill);
   box-shadow: var(--pf-shadow-float);
 }
-/* nowrap: `.seg button` is `flex: 1` (equal-width columns), and a part with
-   two views where one label is long (e.g. import-demo's "Reference overlay")
-   would otherwise wrap onto a second line, making this pill taller than the
-   single fixed height debug-overlay.js positions itself below (see its
-   comment) — the overlay would then overlap the now-two-row tabs. Letting the
-   label force the column wider instead keeps the pill single-row regardless
-   of label length. */
-#topbar .seg button { min-width: 70px; padding: 7px 10px; white-space: nowrap; }
+/* flex: the panel's `.seg button` is `flex: 1 1 0%` — equal-width columns,
+   which is right for a radio group in the rail and wrong here. With a zero
+   basis every tab gets the SAME width, so the widest label does not get to
+   size its own column: import-demo's two tabs came out 106px each while
+   "Reference overlay" needs ~127, and the text simply drew outside the pill's
+   rounded background (measured in Chromium: scrollWidth 238 against
+   clientWidth 221). Sizing each tab to its own content is what the nowrap note
+   below always claimed happened, and is also what makes the pill's natural
+   width honest — view-tabs.js's collapse measures exactly this.
+
+   nowrap: with content-sized columns a long label would otherwise wrap onto a
+   second line, making this pill taller than the single fixed height
+   debug-overlay.js positions itself below (see its comment) — the overlay
+   would then overlap the now-two-row tabs. Letting the label force the column
+   wider instead keeps the pill single-row regardless of label length, and
+   hands the overflow to the collapse rather than to a second row.
+
+   view-tabs.js ALSO sets nowrap inline on every button it generates, and that is
+   the copy that actually protects the rule: a host restyling the pill from
+   scratch (partforge-cloud's `#viewer #part button`, with no `.seg` class)
+   never sees this selector, and long labels wrapped there for exactly that
+   reason. This one still covers hand-written markup on partforge's own pages. */
+#topbar .seg button { flex: 0 0 auto; min-width: 70px; padding: 7px 10px; white-space: nowrap; }
+
+/* The tabs' narrow-stage fallback. When view-tabs.js measures the segmented
+   pill as wider than the stage's top-centre slot it flips `data-pf-tabs` to
+   "menu", and this dropdown stands in for the buttons.
+
+   Ungated on `.seg` / `#topbar` for the same reason #viewbar's chrome below is:
+   partforge-cloud dresses the pill with its own `#viewer #part` rules and
+   neither of those selectors reaches it — and it is the host that most needs
+   this, since its stage is a column beside an editor rather than a full window.
+
+   27px tall, which is what the buttons it replaces measure (11px mono + 7px of
+   padding top and bottom). Matched rather than approximated so the pill's own
+   height does not change as it swaps — it sits at the stage's top centre, where
+   a 1px jump on every resize past the threshold would read as a twitch — and so
+   the collapsed pill stays under the fixed height debug-overlay.js parks itself
+   below. Capped in width so a long label ellipsizes rather than pushing the
+   pill back out to the width that collapsed it in the first place. */
+.pf-view-select {
+  box-sizing: border-box;
+  height: 27px; max-width: min(220px, 100%);
+  padding: 0 24px 0 9px;
+  border: 0; border-radius: var(--pf-radius-control);
+  background: transparent; color: var(--pf-text-2);
+  font-family: var(--pf-mono); font-size: 11px; letter-spacing: 0.02em;
+  cursor: pointer; appearance: none; text-overflow: ellipsis;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='8' height='7'%3E%3Cpolygon points='0,0 8,0 4,7' fill='%238b8b94'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 9px center;
+}
+/* `hidden` is the switch view-tabs.js flips between the two representations,
+   and a host that gives tab buttons a `display` of their own would beat the
+   UA's [hidden] rule — the trap `#viewbar button[hidden]` below already guards
+   against. Said again here against the layout state, which lives on the
+   element itself and so holds whatever a host does to the pill around it. */
+[data-pf-tabs="menu"] > button[data-part] { display: none; }
+[data-pf-tabs="segmented"] > .pf-view-select { display: none; }
 
 /* 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
@@ -318,6 +370,10 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
   border-radius: var(--pf-radius-pill);
   box-shadow: var(--pf-shadow-float);
 }
+/* Sketch mode hides the whole bar while it owns the stage (mount.js) — the
+   display: flex above is author-origin and beats the UA's [hidden] rule, the
+   same trap the buttons' own [hidden] rule below already guards against. */
+#viewbar[hidden] { display: none; }
 #viewbar:not(.pf-float-viewbar) { position: fixed; top: 12px; right: 12px; z-index: 15; }
 #viewbar button {
   width: 34px; height: 34px; border: 0; border-radius: var(--pf-radius-control);
@@ -337,25 +393,68 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 #viewbar .pf-measure-actions { display: flex; gap: 4px; }
 #viewbar .pf-measure-actions[hidden] { display: none; }
 #viewbar .pf-measure-actions button { width: auto; min-width: 56px; padding: 0 8px; }
-#viewbar .pf-annotate-actions { display: flex; gap: 4px; }
-#viewbar .pf-annotate-actions[hidden] { display: none; }
-#viewbar .pf-annotate-actions button { width: auto; min-width: 56px; padding: 0 8px; }
-/* Annotate's actions row has three buttons (Undo/Clear/Send) against
-   cutaway's/measure's two, so it is the first to overflow the stage's left
-   edge as the viewport narrows — the full-size pill (5 icon buttons + this
-   row, ~374px) already exceeds a 375-390px phone's usable width (viewport
-   minus the stage's 12px margins on both sides) before the shared 360px
-   rule below ever engages. Shrink only this row here; the icon buttons and
-   the other two action rows still have room down to 360px. */
-@media (max-width: 430px) {
-  #viewbar .pf-annotate-actions { gap: 3px; }
-  #viewbar .pf-annotate-actions button { min-width: 40px; padding: 0 5px; font-size: 11px; }
-}
 #viewbar button:disabled { opacity: .38; cursor: not-allowed; }
 #viewbar button:disabled:hover { color: var(--pf-muted-2); background: transparent; }
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
 #viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
 
+/* Sketch-mode toolbar: the #viewbar pill idiom, top-centre, owning the mode
+   while the viewbar itself is hidden (mount toggles both).
+
+   `left: 50%` is a shrink-to-fit trap for an absolutely positioned element:
+   its auto width shrink-wraps against the space between `left` and the
+   containing block's right edge, which here is only HALF the stage, not the
+   whole stage — so the row wraps (stranding the close button on its own
+   centred second line, on top of .pf-sketch-hint) well before it actually
+   needs to. `width: max-content` opts back into sizing to the row's
+   preferred (unwrapped) width; `max-width` below still caps that on stages
+   too narrow for the full row, so genuine wrapping on narrow stages still
+   works. */
+.pf-sketch-toolbar {
+  position: absolute; top: 12px; left: 50%; transform: translateX(-50%);
+  display: flex; align-items: center; gap: 4px; padding: 4px;
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-pill); box-shadow: var(--pf-shadow-float);
+  z-index: 20; width: max-content; max-width: calc(100% - 16px); flex-wrap: wrap; justify-content: center;
+}
+.pf-sketch-toolbar[hidden] { display: none; }
+.pf-sketch-toolbar .sep { width: 1px; align-self: stretch; margin: 4px 2px; background: var(--pf-border); }
+.pf-sketch-toolbar button {
+  width: 34px; height: 34px; border: 0; border-radius: var(--pf-radius-control);
+  background: transparent; color: var(--pf-muted-2); cursor: pointer;
+  display: flex; align-items: center; justify-content: center;
+}
+.pf-sketch-toolbar button[data-action="send"] { width: auto; min-width: 56px; padding: 0 10px; }
+.pf-sketch-toolbar button:hover { color: var(--pf-text-2); background: var(--pf-surface-2); }
+.pf-sketch-toolbar button:disabled { opacity: .35; cursor: default; background: transparent; color: var(--pf-muted); }
+.pf-sketch-toolbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
+.pf-sketch-toolbar .pf-swatch { width: 26px; height: 26px; margin: 4px 1px; border-radius: 50%; }
+.pf-sketch-toolbar .pf-swatch::before {
+  content: ""; width: 14px; height: 14px; border-radius: 50%;
+  background: var(--sw); box-shadow: 0 0 0 2px color-mix(in oklab, var(--sw) 25%, transparent);
+}
+.pf-sketch-toolbar .pf-swatch.on { background: var(--pf-surface-2); }
+.pf-sketch-toolbar .pf-swatch.on::before { box-shadow: 0 0 0 2.5px var(--pf-bg), 0 0 0 4.5px var(--sw); }
+.pf-sketch-hint {
+  position: absolute; top: 58px; left: 50%; transform: translateX(-50%);
+  font-family: var(--pf-mono); font-size: 10px; letter-spacing: .04em;
+  color: var(--pf-hint); z-index: 19; pointer-events: none; white-space: nowrap;
+}
+.pf-sketch-hint[hidden] { display: none; }
+/* hand-tool cursors on the ink canvas */
+.pf-ink-canvas.hand { cursor: default; }
+.pf-ink-canvas.hand.over { cursor: grab; }
+.pf-ink-canvas.hand.handle { cursor: crosshair; }
+/* Pointer-followers are CSS cursors, not canvas drawings: anything that must
+   track the pointer per-mousemove would force a full-canvas redraw per event
+   (annotate-mode used to do exactly that for the rotate glyph and eraser
+   ring, and it read as lag). The compositor renders cursors for free. */
+.pf-ink-canvas.hand.rotate { cursor: url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%2224%22 height=%2224%22 viewBox=%220 0 24 24%22 fill=%22none%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22%3E%3Cg stroke=%22%23000%22 stroke-width=%224.5%22 opacity=%22.55%22%3E%3Cpath d=%22M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8%22/%3E%3Cpath d=%22M21 3v5h-5%22/%3E%3C/g%3E%3Cg stroke=%22%23fff%22 stroke-width=%222%22%3E%3Cpath d=%22M21 12a9 9 0 1 1-9-9c2.52 0 4.93 1 6.74 2.74L21 8%22/%3E%3Cpath d=%22M21 3v5h-5%22/%3E%3C/g%3E%3C/svg%3E") 12 12, alias; }
+.pf-ink-canvas.hand.dragging { cursor: grabbing; }
+/* The ring's 16px radius mirrors annotate-mode.js's ERASER_PX — keep them
+   in step so the cursor shows the true brush footprint. */
+.pf-ink-canvas.erasing { cursor: url("data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%2236%22 height=%2236%22 viewBox=%220 0 36 36%22 fill=%22none%22%3E%3Ccircle cx=%2218%22 cy=%2218%22 r=%2216%22 stroke=%22%23000%22 stroke-width=%223.5%22 opacity=%22.55%22/%3E%3Ccircle cx=%2218%22 cy=%2218%22 r=%2216%22 stroke=%22%23fff%22 stroke-width=%221.5%22/%3E%3C/svg%3E") 18 18, crosshair; }
+
 /* ---- 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;
@@ -482,12 +581,8 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 @media (max-width: 360px) {
   #viewbar { gap: 3px; }
   #viewbar button { width: 30px; height: 30px; font-size: 13px; }
-  #viewbar .pf-cutaway-actions, #viewbar .pf-measure-actions, #viewbar .pf-annotate-actions { gap: 3px; }
-  #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
-     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; }
+  #viewbar .pf-cutaway-actions, #viewbar .pf-measure-actions { gap: 3px; }
+  #viewbar .pf-cutaway-actions button, #viewbar .pf-measure-actions button { min-width: 44px; padding: 0 6px; }
 }
 
 /* ---- measurement mode -----------------------------------------------------

package/src/framework/chrome.css

@@ -469,8 +469,10 @@
 
 /* ---- annotation ink layer: a transparent 2D canvas over the viewer --------
    Shown only while annotation mode is on. It deliberately owns pointer events
-   while visible — that is what freezes orbit/pan/zoom during drawing. Below
-   the viewbar (z 15) so Undo/Clear/Send stay clickable. */
+   while visible — that is what freezes orbit/pan/zoom during drawing. #viewbar
+   itself is hidden for the duration (mount.js toggles both), replaced by
+   .pf-sketch-toolbar (app.css, z 20) which now holds Undo/Clear/Send; this
+   layer sits below that at z 10 so the toolbar stays clickable over it. */
 .pf-ink-canvas {
   position: absolute;
   inset: 0;

package/src/framework/mount.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 { attachSketchToolbar } from "./annotate/sketch-toolbar.js";
 import { attachViewcubeControls } from "./viewcube/viewcube-controls.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
@@ -245,12 +246,12 @@ function createCleanupStack() {
 //                                         // KB of base64 apiece, so a host should not assume this
 //                                         // payload is small, only that it is bounded.
 // annotateSend: "viewbar" | "host"       // who owns the Send affordance. "viewbar" (default) puts
-//                                         // Send beside Undo/Clear in the annotate actions row.
-//                                         // "host" drops it and leaves Undo/Clear: the host draws
-//                                         // its own send control — e.g. a composer that pairs the
-//                                         // sketch with a typed message — and calls
-//                                         // runtime.annotate.send() itself. Ignored without
-//                                         // onAnnotationSend (there is no button to place).
+//                                         // Send in the sketch toolbar alongside the other tools.
+//                                         // "host" drops it: the host draws its own send control —
+//                                         // e.g. a composer that pairs the sketch with a typed
+//                                         // message — and calls runtime.annotate.send() itself.
+//                                         // Ignored without onAnnotationSend (there is no toolbar
+//                                         // to place it in).
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
@@ -431,8 +432,30 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }
     const annotateChrome = attachAnnotateControls(viewer, annotateMode, {
       annotate: els.chrome.annotate,
-    }, { tooltip, escapeScope: els.viewer, send: annotateSend });
+    }, { tooltip, escapeScope: els.viewer });
     cleanup.defer(() => annotateChrome.detach());
+    // Sketch owns the top of the stage: the toolbar replaces the viewbar while
+    // the mode is on (spec 2026-08-27). Restore honors whatever hidden state
+    // the host had set before entering. Attached only when annotateMode
+    // exists — a mode-less mount (no onAnnotationSend) has nothing for the
+    // toolbar to drive.
+    if (annotateMode) {
+      const sketchToolbar = attachSketchToolbar(annotateMode, {
+        stage: els.viewer, tooltip, send: annotateSend,
+      });
+      cleanup.defer(() => sketchToolbar.detach());
+      const viewbarForSketch = els.viewer.querySelector("#viewbar");
+      let viewbarWasHidden = false;
+      cleanup.defer(annotateMode.onModeChange(() => {
+        if (!viewbarForSketch) return;
+        if (annotateMode.isEnabled()) {
+          viewbarWasHidden = viewbarForSketch.hidden;
+          viewbarForSketch.hidden = true;
+        } else {
+          viewbarForSketch.hidden = viewbarWasHidden;
+        }
+      }));
+    }
     // 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

package/src/framework/oracle/annotation-ray.js

@@ -0,0 +1,92 @@
+// Reconstruct pick rays from a sketch annotation payload (ANNOTATION_VERSION 3)
+// and intersect them with planes — the consumer-side half of the payload's
+// camera block (spec: docs/superpowers/specs/2026-08-28-annotation-ray-design.md).
+//
+// Pure vector math on arrays: no three, no DOM, no node:, no imports at all
+// (worker-layering holds this folder to that). The math mirrors
+// THREE.Raycaster.setFromCamera exactly, with one deliberate normalization:
+// an orthographic ray's origin sits on the plane through the camera POSITION
+// (three puts it on the near plane) — the same canonicalization annotate-mode
+// applies to the rays it embeds per anchor, so embedded and reconstructed rays
+// are definitionally identical. Two stated caveats: perspective assumes
+// camera zoom 1 (the viewer dollies perspective cameras, never zooms them;
+// orthoHeight already folds zoom in at send time), and payload numbers are
+// rounded to 4 decimals, so reconstruction agrees with the live raycaster to
+// ~1e-4 relative — sub-micrometre at part scale.
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add3 = (a, b, c) => [a[0] + b[0] + c[0], a[1] + b[1] + c[1], a[2] + b[2] + c[2]];
+const scale = (a, s) => [a[0] * s, a[1] * s, a[2] * s];
+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 norm = (a) => scale(a, 1 / Math.hypot(a[0], a[1], a[2]));
+
+// screen: [sx, sy] in the payload's anchor screen frame (nominally 0..1, y
+// down), or any object carrying such a `screen` array (an anchor passes
+// directly). Off-viewport values (e.g. x = 1.03) are legal: the hand tool can
+// move a committed shape partly off-stage, and the projection math is
+// well-defined outside [0, 1] (three's Raycaster extrapolates the same way).
+export function annotationRay(payload, screen, { frame = "parts" } = {}) {
+  if (frame !== "parts" && frame !== "world") {
+    throw new Error('annotationRay: frame must be "parts" or "world"');
+  }
+  const s = Array.isArray(screen) ? screen : screen?.screen;
+  if (!Array.isArray(s) || s.length !== 2 || !s.every((v) => Number.isFinite(v))) {
+    throw new Error("annotationRay: screen must be [x, y] finite numbers");
+  }
+  if (frame === "parts" && payload?.camera?.parts === null) {
+    throw new Error("annotationRay: payload.camera.parts is null — the sketch was sent with no meshes (use { frame: \"world\" })");
+  }
+  const cam = payload?.camera?.[frame];
+  const aspect = payload?.viewport?.aspect;
+  if (!cam?.pos || !cam.target || !cam.up || !Number.isFinite(aspect)) {
+    throw new Error("annotationRay: payload has no camera/viewport block");
+  }
+  // Basis orthonormalized the way three's lookAt does it: `up` is a hint, not
+  // trusted to be orthogonal to forward.
+  const forward = norm(sub(cam.target, cam.pos));
+  const right = norm(cross(forward, cam.up));
+  const trueUp = cross(right, forward);
+  const nx = 2 * s[0] - 1;
+  const ny = 1 - 2 * s[1];
+  if (cam.projection === "orthographic") {
+    const halfH = cam.orthoHeight / 2;
+    return {
+      origin: add3(cam.pos, scale(right, nx * halfH * aspect), scale(trueUp, ny * halfH)),
+      dir: forward,
+    };
+  }
+  const t = Math.tan((cam.fov * Math.PI) / 360); // vertical fov, degrees
+  return {
+    origin: [cam.pos[0], cam.pos[1], cam.pos[2]],
+    dir: norm(add3(forward, scale(right, nx * t * aspect), scale(trueUp, ny * t))),
+  };
+}
+
+const PLANES = {
+  xy: { point: [0, 0, 0], normal: [0, 0, 1] },
+  yz: { point: [0, 0, 0], normal: [1, 0, 0] },
+  zx: { point: [0, 0, 0], normal: [0, 1, 0] },
+};
+
+// Miss semantics match the payload's `hit: null`: parallel rays and
+// intersections at/behind the origin return null rather than throwing. `t` is
+// in units of |dir| (unit for payload/annotationRay rays).
+export function rayPlane(ray, plane) {
+  if (!Array.isArray(ray?.origin) || !Array.isArray(ray?.dir)) {
+    throw new Error("rayPlane: ray must be {origin, dir}");
+  }
+  const p = typeof plane === "string" ? PLANES[plane] : plane;
+  if (!Array.isArray(p?.point) || !Array.isArray(p?.normal)) {
+    throw new Error('rayPlane: plane must be {point, normal} or "xy"|"yz"|"zx"');
+  }
+  const denom = dot(ray.dir, p.normal);
+  if (Math.abs(denom) < 1e-9) return null;
+  const t = dot(sub(p.point, ray.origin), p.normal) / denom;
+  if (t <= 1e-6) return null;
+  return { point: add3(ray.origin, scale(ray.dir, t), [0, 0, 0]), t };
+}

package/src/framework/view-tabs.js

@@ -7,10 +7,89 @@ import { loadView, saveView } from "./view-state.js";
 // hand-wrote. Which tab opens is resolveDefaultView's call, not key order. The
 // active tab then persists per part for the rest of the browser session, so a
 // Vite dev reload doesn't throw you back mid-edit.
-export function createViewTabs(el, part, { onChange }) {
+//
+// The bar has TWO representations of the same choice, and both exist from the
+// start: the segmented buttons, and a dropdown that takes over when the pill no
+// longer fits the stage's top-centre slot. Which one shows is `data-pf-tabs` on
+// the element, kept current by the measurement below. They are built together
+// and switched together rather than rebuilt on each swap, so a click and a
+// dropdown change are the same commit path and neither can drift from the other.
+
+// The slot must clear the pill by this much before the buttons come back. Purely
+// an anti-flap margin: a pill whose natural width lands within a subpixel of the
+// slot would otherwise swap layouts on every ResizeObserver notification.
+const EXPAND_MARGIN = 2;
+// chrome.css's `.pf-float-tabs { top: 12px; left: 50% }` inset — the margin the
+// bar keeps from the stage edge when nothing else competes for the corner.
+const STAGE_MARGIN = 12;
+// Breathing room between the pill's edge and the rail toggle it must not reach.
+const TOGGLE_GAP = 8;
+
+// Which representation to show. Pure, and deliberately a function of the pill's
+// NATURAL width rather than its current one — see `natural` below for why that
+// distinction is what stops the swap oscillating.
+//
+// A non-positive measurement is the ABSENCE of a reading, not a claim that
+// nothing fits: happy-dom reports zeros for every box, and so does a real
+// browser before first layout. Segmented is the honest fallback — it is what
+// the bar looked like before this measurement existed.
+export function pickLayout({ natural, available, collapsed }) {
+  if (!(natural > 0) || !(available > 0)) return "segmented";
+  if (collapsed) return available >= natural + EXPAND_MARGIN ? "segmented" : "menu";
+  return natural > available ? "menu" : "segmented";
+}
+
+// How much of each stage edge is spoken for. Doubled by the caller because the
+// pill is centre-anchored: the tighter side governs both halves. Derived from
+// the rail toggle's measured box rather than from a second copy of its offsets,
+// the same way animation-controls.js derives the view cube's claim from the
+// viewbar's — retune chrome.css and this follows. The toggle is `[hidden]`
+// below the narrow breakpoint, where the stage margin stands alone.
+function sideClearance(stage, stageRect) {
+  const toggle = stage?.querySelector?.(".pf-float-rail-toggle");
+  if (!toggle || toggle.hidden || !stageRect) return STAGE_MARGIN;
+  const rect = toggle.getBoundingClientRect?.();
+  if (!(rect?.width > 0)) return STAGE_MARGIN;
+  return Math.max(STAGE_MARGIN, stageRect.right - rect.left + TOGGLE_GAP);
+}
+
+// `segWidth` is what the pill measures RIGHT NOW, which is near nothing once the
+// buttons are hidden. Reporting it raw rather than smoothing it here keeps this
+// a plain reading; remembering the last meaningful one is the orchestrator's job.
+function domMeasure(el) {
+  return () => {
+    const stage = el.closest?.(".pf-stage") ?? el.offsetParent ?? el.ownerDocument?.documentElement;
+    const stageRect = stage?.getBoundingClientRect?.() ?? null;
+    const stageWidth = stageRect?.width || stage?.clientWidth || 0;
+    return {
+      segWidth: el.scrollWidth || 0,
+      available: stageWidth ? stageWidth - 2 * sideClearance(stage, stageRect) : 0,
+    };
+  };
+}
+
+// Built from the buttons rather than from part.views so a page with hand-written
+// markup gets a working dropdown too — the buttons are the one description of
+// the choice that both paths share. Option text goes through textContent for the
+// same reason the buttons do: view labels are untrusted data.
+function buildSelect(doc, tabs) {
+  const select = doc.createElement("select");
+  select.className = "pf-view-select";
+  select.setAttribute("aria-label", "View");
+  for (const btn of tabs) {
+    const option = doc.createElement("option");
+    option.value = btn.dataset.part;
+    option.textContent = btn.textContent;
+    select.append(option);
+  }
+  return select;
+}
+
+export function createViewTabs(el, part, { onChange, measure } = {}) {
   const generated = !!(el && part.views);
   const partKey = part?.meta?.title ?? "";
   const resolved = resolveDefaultView(part);
+  const doc = el.ownerDocument ?? document;
   if (generated) {
     // Built node-by-node with textContent/dataset rather than an innerHTML
     // template — view keys and labels come from the part, which is untrusted
@@ -20,32 +99,113 @@ export function createViewTabs(el, part, { onChange }) {
       const btn = document.createElement("button");
       btn.dataset.part = key;
       btn.textContent = v?.label ?? key;
+      // Inline, not a stylesheet rule, because this one is load-bearing rather
+      // than decorative and a host can drop a stylesheet rule by accident.
+      // partforge-cloud restyles the pill from scratch (`#viewer #part button`,
+      // no `.seg` class), which is exactly how app.css's `white-space: nowrap`
+      // stopped applying there and let long labels wrap onto a second line. A
+      // wrapping label makes the pill NARROWER, not wider, so the collapse
+      // below would never trip — the overflow it is meant to catch would show
+      // up as a two-row pill instead. On the element, it is out of reach.
+      btn.style.whiteSpace = "nowrap";
       if (key === resolved) btn.classList.add("on");
       return btn;
     }));
   }
 
-  const setActive = (btn) => { for (const b of el.children) b.classList.toggle("on", b === btn); };
+  const buttons = () => [...el.querySelectorAll("button[data-part]")];
+  const tabs = buttons();
+  // Below two tabs there is nothing to choose, and an empty pill must stay
+  // empty: partforge-cloud hides the bar with `#viewer #part:empty`, so a part
+  // with no views would otherwise gain a one-option dropdown and a visible pill.
+  const select = tabs.length >= 2 ? buildSelect(doc, tabs) : null;
+  if (select) el.append(select);
+
+  const setActive = (btn) => {
+    for (const b of buttons()) b.classList.toggle("on", b === btn);
+    if (select) select.value = btn.dataset.part;
+  };
 
   // Initial view: the session-saved one if it still matches a tab, else the active
   // button — the resolved default for a generated bar, or whatever the page's own
   // markup marked `on` for a hand-written one.
   const defaultView = el.querySelector("button.on")?.dataset.part ?? el.querySelector("button")?.dataset.part;
   const saved = loadView(partKey);
-  const savedBtn = saved ? [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === saved) : null;
+  const savedBtn = saved ? tabs.find((b) => b.dataset.part === saved) : null;
   let view = savedBtn ? saved : defaultView;
-  if (savedBtn) setActive(savedBtn);
+  // Unconditional now (it used to run only for a restored view): the dropdown
+  // has to open showing the same tab the buttons do, and for a generated bar
+  // the button half of this is the no-op it always was.
+  const activeBtn = savedBtn ?? tabs.find((b) => b.dataset.part === view);
+  if (activeBtn) setActive(activeBtn);
 
-  const onClick = (e) => {
-    const btn = e.target.closest("button[data-part]");
-    if (!btn) return;
+  const commit = (btn) => {
     view = btn.dataset.part;
     saveView(partKey, view);
     setActive(btn);
     onChange(view);
   };
+
+  const onClick = (e) => {
+    const btn = e.target.closest("button[data-part]");
+    if (!btn) return;
+    commit(btn);
+  };
   el.addEventListener("click", onClick);
 
+  const onSelectChange = () => {
+    const btn = buttons().find((b) => b.dataset.part === select.value);
+    if (btn) commit(btn);
+  };
+  select?.addEventListener("change", onSelectChange);
+
+  // ---- layout: which representation is on screen --------------------------
+  let detached = false;
+  let mode = null;
+  // The pill's width AS IF THE BUTTONS WERE SHOWING — the fixed point the swap
+  // turns on, and the same trick animation-controls.js's nominalClusterRect
+  // plays for the view cube. Re-reading the live pill while collapsed would
+  // measure the dropdown instead, decide the buttons fit, expand, overflow, and
+  // collapse again: two frames per cycle, on screen as a flickering bar. This
+  // value cannot change while collapsed, so the collapsed state is stable.
+  // Caching is exact rather than approximate here because the buttons are
+  // content-sized (`min-width` + padding + nowrap, no percentages), so their
+  // natural width does not depend on the viewport at all.
+  let natural = 0;
+  const read = measure ?? domMeasure(el);
+
+  const setMode = (next) => {
+    if (next === mode) return;
+    mode = next;
+    el.dataset.pfTabs = next;
+    const menu = next === "menu";
+    for (const b of buttons()) b.hidden = menu;
+    if (select) select.hidden = !menu;
+  };
+
+  const relayout = () => {
+    if (detached) return;
+    if (!select) { setMode("segmented"); return; }
+    const { segWidth, available } = read();
+    if (mode !== "menu" && segWidth > 0) natural = segWidth;
+    setMode(pickLayout({ natural, available, collapsed: mode === "menu" }));
+  };
+  setMode("segmented"); // measure from the state the cache is only valid in
+  relayout();
+
+  // ResizeObserver is the precise trigger; the resize listener is the belt that
+  // also fires where it is absent, mirroring animation-controls.js's placement
+  // pair. Both land on the same idempotent relayout, so a doubled notification
+  // costs one measurement and no DOM write.
+  const win = doc.defaultView ?? globalThis;
+  win.addEventListener?.("resize", relayout);
+  const stage = el.closest?.(".pf-stage") ?? el.parentElement;
+  const observer = typeof win.ResizeObserver === "function" ? new win.ResizeObserver(relayout) : null;
+  if (observer && stage) observer.observe(stage);
+  // A webfont swap changes every label's width, and so the pill's natural width,
+  // after the first layout the measurement above ran against.
+  doc.fonts?.ready?.then(relayout).catch(() => {});
+
   return {
     current: () => view,
     // Programmatic switch — the click path without the click. Used by an
@@ -53,17 +213,21 @@ export function createViewTabs(el, part, { onChange }) {
     // Returns false for a name that isn't a tab so callers can validate.
     select: (name) => {
       if (name === view) return true; // already active — nothing to do
-      const btn = [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === name);
+      const btn = buttons().find((b) => b.dataset.part === name);
       if (!btn) return false;
-      view = name;
-      saveView(partKey, view);
-      setActive(btn);
-      onChange(view);
+      commit(btn);
       return true;
     },
     detach: () => {
+      detached = true;
       el.removeEventListener("click", onClick);
+      select?.removeEventListener("change", onSelectChange);
+      win.removeEventListener?.("resize", relayout);
+      observer?.disconnect();
+      select?.remove(); // ours in both paths — hand-written markup never has one
+      delete el.dataset.pfTabs;
       if (generated) el.innerHTML = ""; // we generated these buttons; hand-written markup stays
+      else for (const b of buttons()) b.hidden = false; // leave the page's own buttons as we found them
     },
   };
 }

package/src/oracle.js

@@ -29,3 +29,7 @@ export { parse3MF } from "./framework/geometry/threemf-parse.js";
 // these, re-exported so a downstream harness can reproduce a score outside the job loop.
 export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
 export { matchMasks, matchViews } from "./framework/oracle/match.js";
+// Sketch-annotation ray reconstruction — the consumer-side half of the
+// annotation payload's camera block: rebuild the pick ray for any screen
+// point, intersect it with a plane in parts-frame millimetres.
+export { annotationRay, rayPlane } from "./framework/oracle/annotation-ray.js";

package/types/oracle.d.ts

@@ -19,4 +19,7 @@ export {
   // silhouette match scoring
   MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask, matchMasks, matchViews,
   type SilhouetteMask, type MatchScores, type MatchDelta,
+  // sketch-annotation rays
+  annotationRay, rayPlane,
+  type AnnotationRay, type RayPlaneHit, type PlaneSpec,
 } from "./testing.js";

package/types/testing.d.ts

@@ -499,3 +499,18 @@ export function renderViews(
     opacity?: Record<string, number>;
   },
 ): Promise<string[]>;
+
+// --- sketch-annotation rays --------------------------------------------------
+export interface AnnotationRay { origin: [number, number, number]; dir: [number, number, number] }
+export interface RayPlaneHit { point: [number, number, number]; t: number }
+export type PlaneSpec =
+  | { point: [number, number, number]; normal: [number, number, number] }
+  | "xy" | "yz" | "zx";
+/** Rebuild the pick ray for a screen point of an ANNOTATION_VERSION 3 payload. */
+export function annotationRay(
+  payload: { camera: unknown; viewport: { aspect: number } },
+  screen: [number, number] | { screen: [number, number] },
+  opts?: { frame?: "parts" | "world" },
+): AnnotationRay;
+/** Intersect a ray with a plane; null on parallel / behind-origin misses. */
+export function rayPlane(ray: AnnotationRay, plane: PlaneSpec): RayPlaneHit | null;