partforge 0.86.0 → 0.88.0

package/src/framework/capture-frame.js

@@ -0,0 +1,118 @@
+// Framing math for the showcase capture (viewer.js captureCurrentFromScene):
+// where the visible geometry lands in the rendered frame, and the centred
+// sub-window that puts it in the middle. Pure three.js math, no GL — the
+// renderer builds its camera through makeCaptureCamera too, so what this
+// module projects through is exactly what renderOffscreen draws with.
+//
+// Why vertices and not bounding boxes: the projection of a triangle mesh is a
+// union of projected triangles, and a triangle's projected extremes are its
+// corners — so the min/max over projected VERTICES is the exact 2-D extent of
+// the rendered silhouette at any angle, where a projected 3-D bounding box
+// over-reports by up to the box's slack at diagonal views.
+//
+// Why a view offset and not a pixel crop: three's setViewOffset renders a
+// sub-window of a larger virtual frame with the same projection, so the
+// recentred image is a pixel-exact crop of what the user framed — at the full
+// requested resolution and with no second JPEG encode.
+import * as THREE from "three";
+
+const NEAR = 0.1;
+const FAR = 1000;
+
+// The temp camera an offscreen capture renders with. `aspect` is the FULL
+// frame's aspect; a recentred sub-window is applied afterwards by the caller
+// via setViewOffset, which (for a PerspectiveCamera) keeps this aspect as the
+// virtual full frame's. Matrices are updated so a caller can project through
+// matrixWorldInverse without a render having happened first.
+export function makeCaptureCamera(
+  { position, up, target },
+  { aspect = 1, fov = 45, projection = "perspective", orthoHalfH = 1 } = {},
+) {
+  const cam = projection === "orthographic"
+    ? new THREE.OrthographicCamera(-orthoHalfH * aspect, orthoHalfH * aspect, orthoHalfH, -orthoHalfH, NEAR, FAR)
+    : new THREE.PerspectiveCamera(fov, aspect, NEAR, FAR);
+  cam.position.set(position[0], position[1], position[2]);
+  cam.up.set(up[0], up[1], up[2]);
+  cam.lookAt(target[0], target[1], target[2]);
+  cam.updateMatrixWorld(true);
+  return cam;
+}
+
+// Exact 2-D extent of the meshes' projected vertices, as fractions of the
+// frame with a top-left origin ({ left, top, right, bottom }; values outside
+// [0, 1] mean the geometry runs past that edge). Null when there is nothing
+// to project, or when ANY vertex would be clipped by the frustum's near/far
+// planes or sits behind the camera — such a vertex is not in the picture, so
+// no honest extent exists and the caller should leave the framing alone.
+export function projectedExtent(camera, meshes) {
+  const toClip = new THREE.Matrix4();
+  const v = new THREE.Vector4();
+  let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+  let any = false;
+  for (const mesh of meshes ?? []) {
+    const pos = mesh?.geometry?.attributes?.position;
+    if (!pos || !pos.count) continue;
+    mesh.updateWorldMatrix(true, false);
+    toClip.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse).multiply(mesh.matrixWorld);
+    for (let i = 0; i < pos.count; i++) {
+      v.set(pos.getX(i), pos.getY(i), pos.getZ(i), 1).applyMatrix4(toClip);
+      const w = v.w;
+      if (!(w > 0) || v.z < -w || v.z > w) return null;
+      const x = v.x / w, y = v.y / w;
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      any = true;
+    }
+  }
+  if (!any) return null;
+  return { left: (minX + 1) / 2, right: (maxX + 1) / 2, top: (1 - maxY) / 2, bottom: (1 - minY) / 2 };
+}
+
+// The largest sub-window centred on the extent's centre that still fits the
+// frame, as { x, y, width, height } fractions. Centring on the extent with
+// maximal half-extents min(c, 1 - c) gives equal margins on both sides of each
+// axis and is guaranteed to contain the extent (which always lies within
+// [0, 2c] and [2c - 1, 1]). Null — leave the framing alone — when the extent
+// runs past any edge (the user zoomed in on purpose), when it already fills the
+// frame symmetrically (nothing to do), or when there is no usable extent.
+// `eps` forgives the ~1 px feature-edge line that can overhang a vertex.
+export function centeredCropView(extent, { eps = 0.002 } = {}) {
+  if (!extent) return null;
+  const { left, top, right, bottom } = extent;
+  if (![left, top, right, bottom].every(Number.isFinite)) return null;
+  if (left < -eps || top < -eps || right > 1 + eps || bottom > 1 + eps) return null;
+  if (!(right > left) || !(bottom > top)) return null;
+  const cx = (left + right) / 2, cy = (top + bottom) / 2;
+  const hw = Math.min(cx, 1 - cx), hh = Math.min(cy, 1 - cy);
+  if (hw >= 0.5 - eps && hh >= 0.5 - eps) return null;
+  return { x: Math.max(0, cx - hw), y: Math.max(0, cy - hh), width: 2 * hw, height: 2 * hh };
+}
+
+// Turn a fractional crop of a frame with the given aspect into what
+// renderOffscreen needs: the output size (crop rendered at `long` px on its
+// long edge, so recentring costs no resolution) and the setViewOffset
+// arguments describing it as a sub-window of a larger virtual frame.
+export function cropRenderFrame(crop, { aspect, long }) {
+  const cropAspect = (crop.width * aspect) / crop.height;
+  const width = cropAspect >= 1 ? long : Math.max(1, Math.round(long * cropAspect));
+  const height = cropAspect >= 1 ? Math.max(1, Math.round(long / cropAspect)) : long;
+  const fullWidth = width / crop.width;
+  const fullHeight = height / crop.height;
+  return {
+    width, height,
+    viewOffset: { fullWidth, fullHeight, x: crop.x * fullWidth, y: crop.y * fullHeight },
+  };
+}
+
+// The whole pipeline for captureCurrentFromScene: the render frame that puts
+// the visible geometry in the middle, or null when the current framing should
+// be kept as-is (part cropped by the viewport, already centred, or nothing to
+// measure). `meshes` are the visible sub-part meshes; the camera parameters
+// must be the same ones the render will use.
+export function recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }) {
+  const camera = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+  const crop = centeredCropView(projectedExtent(camera, meshes));
+  return crop ? cropRenderFrame(crop, { aspect, long }) : null;
+}

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
@@ -75,7 +76,15 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // Offscreen render of a named view (default when omitted, or on an unknown name).
     captureView,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
-    captureCurrent: (opts) => viewer.captureCurrent(opts),
+    // `recenter` reads the sub-part geometry only, so with measurement pins on
+    // screen the dimension labels — which sit beside the part, not on it —
+    // could land outside the centred window. A dimensioned capture therefore
+    // keeps the user's exact framing; a host wanting both re-frames first.
+    captureCurrent: (opts) => viewer.captureCurrent(
+      opts?.recenter && (measure ?? NOOP_MEASURE).isEnabled() && (measure ?? NOOP_MEASURE).pinCount() > 0
+        ? { ...opts, recenter: false }
+        : opts,
+    ),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
@@ -237,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.
@@ -423,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/viewer.js

@@ -9,6 +9,7 @@ import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
 import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphereLight } from "./viewer-lighting.js";
+import { makeCaptureCamera, recenteredView } from "./capture-frame.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
 // three renders into a render target in the LINEAR working colour space: as of r184
@@ -98,9 +99,17 @@ export function thumbnailBackground(background = THUMBNAIL_BG) {
 // context: pose comes from the live camera (never a canonical pose), the output
 // long edge is `size` clamped into [256, maxTextureSize], and the short edge
 // follows the live camera's aspect so the capture matches what the user framed.
+//
+// `recenter: true` (opt-in; the default keeps the exact viewport framing) renders
+// the largest centred sub-window that still holds every visible vertex — a
+// showcase image with the part in the middle and equal margins — and leaves the
+// framing alone when the geometry runs off the frame, since a user who zoomed
+// past the part's edge framed that crop on purpose. The extent is projected
+// through the same camera the render uses (capture-frame.js), so it is exact;
+// `meshes` are the visible sub-part meshes it reads.
 export function captureCurrentFromScene(
-  { size = 2048, hideGrid = true, quality = 0.9 } = {},
-  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH },
+  { size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {},
+  { renderer, liveCamera, target, grid, maxTextureSize, projection = "perspective", orthoHalfH, meshes },
 ) {
   const MIN_SIZE = 256;
   // WebGL2 guarantees MAX_TEXTURE_SIZE >= 2048; only trust a larger reported cap.
@@ -115,17 +124,20 @@ export function captureCurrentFromScene(
     || 1;
   const width = aspect >= 1 ? long : Math.max(1, Math.round(long * aspect));
   const height = aspect >= 1 ? Math.max(1, Math.round(long / aspect)) : long;
+  const pose = { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target };
+  // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
+  // CANONICAL capture path deliberately never passes either — agent-facing
+  // renders stay perspective regardless of what the user is looking at.
+  const fov = liveCamera.fov ?? 45;
+  // Null means "keep the viewport framing": part cropped by the viewport,
+  // already centred, or nothing to measure.
+  const frame = (recenter && recenteredView(pose, { aspect, fov, projection, orthoHalfH, meshes, long }))
+    || { width, height };
   const before = liveCamera.position.clone();
   const gridWasVisible = grid?.visible;
   if (grid && hideGrid) grid.visible = false;
   try {
-    return renderer.renderOffscreen(
-      { position: liveCamera.position.toArray(), up: liveCamera.up.toArray(), target },
-      // fov is meaningless under an ortho camera; orthoHalfH replaces it. The
-      // CANONICAL capture path deliberately never passes either — agent-facing
-      // renders stay perspective regardless of what the user is looking at.
-      { width, height, fov: liveCamera.fov ?? 45, quality, projection, orthoHalfH },
-    );
+    return renderer.renderOffscreen(pose, { ...frame, fov, quality, projection, orthoHalfH });
   } finally {
     if (grid && hideGrid) grid.visible = gridWasVisible;
     liveCamera.position.copy(before); // belt-and-suspenders: never leak camera state
@@ -822,9 +834,15 @@ export function createViewer(container, part) {
   // the mask silently no-ops and every cap floods its whole plane with hatch —
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
-  function renderOffscreen({ position, up, target },
+  //
+  // `viewOffset` ({ fullWidth, fullHeight, x, y }) renders the width×height
+  // output as that sub-window of a larger virtual frame — the recentred
+  // showcase capture (captureCurrentFromScene). The camera's aspect is then the
+  // VIRTUAL frame's, so the projection is exactly the un-offset one and the
+  // output is a pixel-exact crop of what the user framed.
+  function renderOffscreen(pose,
                            { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9,
-                             projection = "perspective", orthoHalfH = 1 } = {},
+                             projection = "perspective", orthoHalfH = 1, viewOffset } = {},
                            renderScene = scene) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
@@ -832,15 +850,13 @@ export function createViewer(container, part) {
       : new THREE.WebGLRenderTarget(width, height, RT_OPTIONS);
     _capLights = _capLights ?? createCaptureLights();
     // Canonical captures never pass `projection`, so agent-facing renders and
-    // the CLI stay perspective no matter what the user is looking at.
-    const cam = projection === "orthographic"
-      ? new THREE.OrthographicCamera(
-          -orthoHalfH * (width / height), orthoHalfH * (width / height),
-          orthoHalfH, -orthoHalfH, 0.1, 1000)
-      : new THREE.PerspectiveCamera(fov, width / height, 0.1, 1000);
-    cam.position.set(position[0], position[1], position[2]);
-    cam.up.set(up[0], up[1], up[2]);
-    cam.lookAt(target[0], target[1], target[2]);
+    // the CLI stay perspective no matter what the user is looking at. Built
+    // through the same helper the recentring math projects through, so the two
+    // can never disagree about where a vertex lands.
+    const aspect = viewOffset ? viewOffset.fullWidth / viewOffset.fullHeight : width / height;
+    const cam = makeCaptureCamera(pose, { aspect, fov, projection, orthoHalfH });
+    if (viewOffset) cam.setViewOffset(viewOffset.fullWidth, viewOffset.fullHeight, viewOffset.x, viewOffset.y, width, height);
+    const { position, up, target } = pose;
     const buf = new Uint8Array(width * height * 4);
     // Swap the world-fixed key/fill for the camera-relative pair, for this one render
     // only. A DirectionalLight aims at its `target`, whose matrixWorld only updates
@@ -923,6 +939,9 @@ export function createViewer(container, part) {
       target: controls.target.toArray(),
       grid,
       maxTextureSize: renderer.capabilities?.maxTextureSize,
+      // For `recenter`: the geometry that is actually in the picture. Sub-part
+      // meshes only — dimension labels and section caps are overlays on them.
+      meshes: Object.values(subMesh).filter((m) => m.visible),
       projection: projectionMode,
       // Divided by zoom, because OrbitControls dollies an ortho camera with
       // `zoom` and leaves the frustum alone: the raw frustum is the un-dollied

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/index.d.ts

@@ -146,6 +146,14 @@ export interface CaptureCurrentOptions {
   hideGrid?: boolean;
   /** JPEG quality, 0..1. */
   quality?: number;
+  /**
+   * Centre the visible geometry: render the largest centred sub-window of the
+   * current framing that still holds every visible vertex (equal margins, full
+   * `size` resolution). When the geometry runs past a frame edge — the user
+   * zoomed in on purpose — or dimensions are pinned, the framing is kept as-is.
+   * Default false.
+   */
+  recenter?: boolean;
 }
 
 export interface CaptureViewOptions {

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;

package/src/framework/annotate/ink.js

@@ -1,124 +0,0 @@
-// Pure stroke model for annotation mode: normalized-coordinate polylines with
-// point thinning while drawing, undo/clear, closed-stroke detection and anchor
-// selection. No DOM, no three — unit-testable directly (the feature-dims.js
-// stance). Points are [nx, ny] normalized 0..1 per viewport axis; distances
-// are measured in viewport-DIAGONAL units so thresholds mean the same thing
-// horizontally and vertically regardless of aspect.
-
-// Stroke width as a fraction of the viewport's short edge (spec: payload
-// carries this unit so any re-render can reproduce line weight).
-export const DEFAULT_STROKE_WIDTH = 0.004;
-// Spec: endpoints within 5% of the viewport diagonal = closed stroke.
-const CLOSED_THRESHOLD = 0.05;
-// pointermove fires per-pixel; keep only points this far (in diagonal units)
-// from the previous kept point. ~2px at 1080p.
-const MIN_POINT_DISTANCE = 0.0015;
-
-export function diagDistance(a, b, aspect = 1) {
-  const dx = (a[0] - b[0]) * aspect;
-  const dy = a[1] - b[1];
-  return Math.hypot(dx, dy) / Math.hypot(aspect, 1);
-}
-
-export function createInkStore({ minDistance = MIN_POINT_DISTANCE } = {}) {
-  const strokes = [];
-  let active = null;
-  const listeners = new Set();
-  const notify = () => { for (const cb of [...listeners]) cb(); };
-  return {
-    begin(nx, ny, { width = DEFAULT_STROKE_WIDTH, aspect = 1 } = {}) {
-      active = { points: [[nx, ny]], width, aspect };
-      strokes.push(active);
-      notify();
-    },
-    extend(nx, ny) {
-      if (!active) return;
-      const last = active.points[active.points.length - 1];
-      if (diagDistance([nx, ny], last, active.aspect) < minDistance) return;
-      active.points.push([nx, ny]);
-      notify();
-    },
-    end() {
-      if (!active) return;
-      active = null; // one-point strokes stay: a click leaves a visible dot
-      notify();
-    },
-    strokes: () => strokes.map((s) => ({ points: s.points.map((p) => [...p]), width: s.width })),
-    isEmpty: () => strokes.length === 0,
-    strokeCount: () => strokes.length,
-    undo() {
-      if (!strokes.length) return;
-      strokes.pop();
-      active = null;
-      notify();
-    },
-    clear() {
-      if (!strokes.length && !active) return;
-      strokes.length = 0;
-      active = null;
-      notify();
-    },
-    onChange(cb) { listeners.add(cb); return () => listeners.delete(cb); },
-  };
-}
-
-export function pointAt(points, t, aspect = 1) {
-  if (points.length === 1) return [...points[0]];
-  const lengths = [0];
-  for (let i = 1; i < points.length; i++) {
-    lengths.push(lengths[i - 1] + diagDistance(points[i], points[i - 1], aspect));
-  }
-  const total = lengths[lengths.length - 1];
-  if (total === 0) return [...points[0]];
-  const target = t * total;
-  let i = 1;
-  while (i < lengths.length - 1 && lengths[i] < target) i++;
-  const span = lengths[i] - lengths[i - 1];
-  const f = span === 0 ? 0 : (target - lengths[i - 1]) / span;
-  const [ax, ay] = points[i - 1];
-  const [bx, by] = points[i];
-  return [ax + (bx - ax) * f, ay + (by - ay) * f];
-}
-
-export function isClosedStroke(points, aspect = 1) {
-  if (points.length < 3) return false;
-  return diagDistance(points[0], points[points.length - 1], aspect) <= CLOSED_THRESHOLD;
-}
-
-// Area-weighted polygon centroid (shoelace); for a degenerate (near-zero-area)
-// point set, fall back to the plain point average.
-export function strokeCentroid(points) {
-  let area2 = 0, cx = 0, cy = 0;
-  for (let i = 0; i < points.length; i++) {
-    const [x0, y0] = points[i];
-    const [x1, y1] = points[(i + 1) % points.length];
-    const cross = x0 * y1 - x1 * y0;
-    area2 += cross;
-    cx += (x0 + x1) * cross;
-    cy += (y0 + y1) * cross;
-  }
-  if (Math.abs(area2) < 1e-9) {
-    let sx = 0, sy = 0;
-    for (const [x, y] of points) { sx += x; sy += y; }
-    return [sx / points.length, sy / points.length];
-  }
-  return [cx / (3 * area2), cy / (3 * area2)];
-}
-
-// Anchor sample points for one stroke: start / arc-length-midpoint / end, plus
-// the enclosed-region centroid when the stroke closes on itself ("what did
-// they circle"). A one-point dot gets a single anchor. The orchestrator turns
-// each spec's normalized `screen` point into a raycast.
-export function anchorSpecs(points, aspect = 1) {
-  if (points.length === 0) return [];
-  if (points.length === 1) return [{ t: 0, screen: [...points[0]] }];
-  const specs = [
-    { t: 0, screen: [...points[0]] },
-    { t: 0.5, screen: pointAt(points, 0.5, aspect) },
-    { t: 1, screen: [...points[points.length - 1]] },
-  ];
-  if (isClosedStroke(points, aspect)) {
-    specs.push({ kind: "centroid", screen: strokeCentroid(points) });
-  }
-  return specs;
-}