partforge 0.87.0 → 0.88.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/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;

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;
-}