partforge 0.67.4 → 0.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.67.4",
+  "version": "0.68.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/app-demo.js

@@ -14,4 +14,8 @@ import { mount } from "./framework/index.js";
 window.__pfRuntime = mount(demoPart, {
   createWorker: (name) =>
     new Worker(new URL("./demo-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
 });

package/src/framework/annotate/annotate-controls.js

@@ -0,0 +1,134 @@
+// Viewbar chrome for annotation mode: the pencil toggle + contextual actions
+// (Undo / Clear / Send) shown while the mode is on. A direct sibling of
+// measure-controls.js — same no-op-without-button contract, same attribute
+// restore discipline on detach. The mode object (annotate-mode.js) owns all
+// behavior; this file only puts it on screen. One extra contract: a host whose
+// markup HAS the button but whose mount passed no onAnnotationSend gets the
+// button hidden entirely (spec: no dead Send) — mount passes mode = null.
+//
+// `send: "host"` drops the Send button from the row and leaves Undo/Clear.
+// It is for a host that draws its own send affordance (partforge-cloud pairs
+// the sketch with a typed prompt in its own composer, then calls
+// runtime.annotate.send()) — two Send buttons in two places, one of which
+// ignores the typed message, is the failure this avoids.
+import { attachButtonTooltips } from "../tooltip.js";
+import { runCleanupSteps, captureAttributes, restoreAttributes } from "../teardown.js";
+
+const BUTTON_ATTRIBUTES = ["type", "aria-pressed", "aria-label", "title", "disabled", "hidden"];
+const PENCIL_ICON = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/></svg>`;
+
+const noop = () => {};
+
+export function attachAnnotateControls(viewer, mode, { annotate: button } = {}, { tooltip, escapeScope, send = "viewbar" } = {}) {
+  if (!button) return { detach: noop };
+
+  const hostAttributes = captureAttributes(button, BUTTON_ATTRIBUTES);
+  if (!mode) {
+    button.hidden = true;
+    let restored = false;
+    return {
+      detach() {
+        if (restored) return;
+        restored = true;
+        restoreAttributes(button, hostAttributes);
+      },
+    };
+  }
+  const hostHtml = button.innerHTML;
+  const hostOn = button.classList.contains("on");
+
+  button.type = "button";
+  button.innerHTML = PENCIL_ICON;
+  button.setAttribute("aria-pressed", "false");
+  if (!tooltip && !button.hasAttribute("title")) button.title = "Sketch";
+
+  const actions = document.createElement("span");
+  actions.className = "pf-annotate-actions";
+  const undoButton = document.createElement("button");
+  undoButton.type = "button";
+  undoButton.textContent = "Undo";
+  undoButton.title = "Remove the last stroke";
+  undoButton.setAttribute("aria-label", "Remove the last stroke");
+  const clearButton = document.createElement("button");
+  clearButton.type = "button";
+  clearButton.textContent = "Clear";
+  clearButton.title = "Remove all strokes";
+  clearButton.setAttribute("aria-label", "Remove all strokes");
+  let sendButton = null;
+  if (send !== "host") {
+    sendButton = document.createElement("button");
+    sendButton.type = "button";
+    sendButton.className = "pf-annotate-send";
+    sendButton.textContent = "Send";
+    sendButton.title = "Send the annotation";
+    sendButton.setAttribute("aria-label", "Send the annotation");
+  }
+  actions.append(...[undoButton, clearButton, sendButton].filter(Boolean));
+  button.after(actions);
+
+  const buttons = [button, undoButton, clearButton, sendButton].filter(Boolean);
+  const tooltipBinding = tooltip
+    ? attachButtonTooltips(tooltip, buttons.map((element) => ({ element })))
+    : null;
+
+  function sync() {
+    const on = mode.isEnabled();
+    button.setAttribute("aria-pressed", String(on));
+    button.setAttribute("aria-label", on ? "Stop sketching" : "Sketch");
+    button.classList.toggle("on", on);
+    actions.hidden = !on;
+    const empty = mode.strokeCount() === 0;
+    undoButton.disabled = empty;
+    clearButton.disabled = empty;
+    if (sendButton) sendButton.disabled = empty;
+    tooltipBinding?.sync();
+  }
+
+  const onToggle = () => { mode.setEnabled(!mode.isEnabled()); sync(); };
+  const onUndo = () => { mode.undo(); sync(); };
+  const onClear = () => { mode.clear(); sync(); };
+  const onSendClick = () => { mode.send(); sync(); };
+  const onEscape = (event) => {
+    if (event.key !== "Escape" || !mode.isEnabled()) return;
+    event.preventDefault();
+    // Consume the keystroke — same order-independence contract as
+    // measure-controls.js vs cutaway (which covers itself with escapeGuard;
+    // mount extends that guard to include annotate).
+    event.stopImmediatePropagation();
+    mode.setEnabled(false);
+    sync();
+    tooltipBinding?.hide();
+  };
+  const offInk = mode.onInkChange(sync);
+  const offMode = mode.onModeChange(sync);
+
+  button.addEventListener("click", onToggle);
+  undoButton.addEventListener("click", onUndo);
+  clearButton.addEventListener("click", onClear);
+  sendButton?.addEventListener("click", onSendClick);
+  const escapeTargets = [escapeScope ?? viewer.domElement, ...buttons];
+  for (const element of escapeTargets) element.addEventListener("keydown", onEscape);
+  sync();
+
+  let detached = false;
+  return {
+    detach() {
+      if (detached) return;
+      detached = true;
+      runCleanupSteps([
+        offInk,
+        offMode,
+        () => button.removeEventListener("click", onToggle),
+        () => undoButton.removeEventListener("click", onUndo),
+        () => clearButton.removeEventListener("click", onClear),
+        () => sendButton?.removeEventListener("click", onSendClick),
+        ...escapeTargets.map((element) => () => element.removeEventListener("keydown", onEscape)),
+        () => tooltipBinding?.detach(),
+        () => actions.remove(),
+        () => restoreAttributes(button, hostAttributes),
+        () => { button.innerHTML = hostHtml; },
+        () => button.classList.toggle("on", hostOn),
+      ], "annotate control cleanup failed");
+    },
+  };
+}

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

@@ -0,0 +1,165 @@
+// Annotation-mode orchestrator — the one annotate module touching both the DOM
+// and the viewer (the measure-mode.js stance). Owns pointer→ink, the mode
+// lifecycle, and payload assembly. The overlay canvas is lazy-created on first
+// enable and kept across toggles; INK is not — exiting the mode discards it,
+// because screen-space ink is only meaningful against the camera pose it was
+// drawn over (deliberately unlike measure pins).
+import * as THREE from "three";
+import { createInkStore, anchorSpecs, DEFAULT_STROKE_WIDTH } from "./ink.js";
+import { createInkCanvas } from "./ink-canvas.js";
+import { raycastViewer } from "../selection/raycast.js";
+
+export const ANNOTATION_VERSION = 1;
+// Long-edge bound on BOTH pictures in the payload. The ink canvas is stage
+// sized × devicePixelRatio, so an unbounded send on a large hi-DPI display
+// hands the host a multi-megabyte pair of base64 strings — slow to encode,
+// and past the ceiling a host that ships them anywhere has to enforce. 2048
+// is captureCurrent's own default and comfortably above what any reviewer
+// (human or model) reads a sketch at; a smaller stage exports at its own size
+// and pays nothing.
+const SEND_MAX_EDGE = 2048;
+
+export function createAnnotateMode(viewer, { stage, getContext, onSend, createCanvas = createInkCanvas } = {}) {
+  const ink = createInkStore();
+  let canvas = null; // lazy; created on first enable
+  let enabled = false;
+  let drawing = false;
+  const modeListeners = new Set();
+  const notifyMode = () => { for (const cb of [...modeListeners]) cb(); };
+  const offInk = ink.onChange(() => canvas?.setStrokes(ink.strokes()));
+
+  const rectOf = () => canvas.element.getBoundingClientRect();
+  const normalized = (event, rect) => [
+    Math.min(1, Math.max(0, (event.clientX - rect.left) / rect.width)),
+    Math.min(1, Math.max(0, (event.clientY - rect.top) / rect.height)),
+  ];
+
+  // isPrimary === false (a second simultaneous touch) is ignored; undefined
+  // (plain MouseEvent, some test environments) draws normally.
+  const onPointerDown = (event) => {
+    if (event.isPrimary === false || drawing) return;
+    const rect = rectOf();
+    if (!rect.width || !rect.height) return;
+    drawing = true;
+    canvas.element.setPointerCapture?.(event.pointerId);
+    const [nx, ny] = normalized(event, rect);
+    ink.begin(nx, ny, { width: DEFAULT_STROKE_WIDTH, aspect: rect.width / rect.height });
+  };
+  const onPointerMove = (event) => {
+    if (!drawing || event.isPrimary === false) return;
+    const [nx, ny] = normalized(event, rectOf());
+    ink.extend(nx, ny);
+  };
+  const onPointerEnd = (event) => {
+    if (!drawing || event.isPrimary === false) return;
+    drawing = false;
+    ink.end();
+  };
+
+  function ensureCanvas() {
+    if (canvas) return;
+    canvas = createCanvas(stage);
+    canvas.element.addEventListener("pointerdown", onPointerDown);
+    canvas.element.addEventListener("pointermove", onPointerMove);
+    canvas.element.addEventListener("pointerup", onPointerEnd);
+    canvas.element.addEventListener("pointercancel", onPointerEnd);
+  }
+
+  function setEnabled(on) {
+    if (on === enabled) return;
+    enabled = on;
+    if (on) {
+      ensureCanvas();
+      canvas.show();
+    } else {
+      drawing = false;
+      ink.clear(); // spec: ink never survives an exit
+      canvas?.hide();
+    }
+    notifyMode();
+  }
+
+  // The camera pose in two frames. World replays exactly against THIS build;
+  // the parts frame (through the inverse of the shared parts parent's
+  // matrixWorld — the measure-mode idiom) stays pinned to the CAD geometry, so
+  // it survives the per-view bbox recentring when the model is rebuilt later.
+  function cameraBlock() {
+    const { pos, target } = viewer.getCameraState();
+    const world = { pos, target, up: viewer.camera.up.toArray(), fov: viewer.camera.fov };
+    const parent = Object.values(viewer._subMeshes ?? {})[0]?.parent ?? null;
+    if (!parent) return { world, parts: null };
+    parent.updateWorldMatrix(true, false);
+    const inv = parent.matrixWorld.clone().invert();
+    const map = (v) => new THREE.Vector3(v[0], v[1], v[2]).applyMatrix4(inv).toArray();
+    const up = new THREE.Vector3(world.up[0], world.up[1], world.up[2]).transformDirection(inv).toArray();
+    return { world, parts: { pos: map(world.pos), target: map(world.target), up, fov: world.fov } };
+  }
+
+  function send() {
+    if (!enabled || ink.isEmpty()) return false;
+    const rect = rectOf();
+    if (!rect.width || !rect.height) return false;
+    const { width, height, dpr } = canvas.size();
+    // Model render FIRST: on a lost WebGL context captureCurrent returns null
+    // and we abort with the ink intact — nothing is silently dropped.
+    const model = viewer.captureCurrent({ size: Math.min(Math.max(width, height), SEND_MAX_EDGE) });
+    if (!model) return false;
+    const strokes = ink.strokes();
+    const aspect = rect.width / rect.height;
+    const anchors = strokes.flatMap((stroke, index) =>
+      anchorSpecs(stroke.points, aspect).map((spec) => {
+        const hit = raycastViewer(
+          viewer,
+          rect.left + spec.screen[0] * rect.width,
+          rect.top + spec.screen[1] * rect.height,
+        );
+        return {
+          stroke: index,
+          ...(spec.kind ? { kind: spec.kind } : { t: spec.t }),
+          screen: spec.screen,
+          // a miss is kept as null — "circled empty space" is signal
+          hit: hit ? { subPart: hit.subPart, pointLocal: hit.pointLocal } : null,
+        };
+      }));
+    const { view, params } = getContext();
+    onSend?.({
+      version: ANNOTATION_VERSION,
+      strokes,
+      anchors,
+      images: { drawing: canvas.toDataUrl({ maxEdge: SEND_MAX_EDGE }), model },
+      camera: cameraBlock(),
+      viewport: { width: rect.width, height: rect.height, dpr },
+      context: { view, params: { ...params } },
+    });
+    setEnabled(false); // sent: exit and discard
+    return true;
+  }
+
+  let detached = false;
+  return {
+    setEnabled,
+    isEnabled: () => enabled,
+    undo: () => ink.undo(),
+    clear: () => ink.clear(),
+    strokeCount: () => ink.strokeCount(),
+    send,
+    onInkChange: (cb) => ink.onChange(cb),
+    onModeChange: (cb) => { modeListeners.add(cb); return () => modeListeners.delete(cb); },
+    detach() {
+      if (detached) return;
+      detached = true;
+      // Leave the state machine honest: a detach while enabled must not
+      // strand isEnabled() at true forever. Runs before listeners/canvas
+      // teardown below — setEnabled(false) notifies mode listeners and hides
+      // the canvas, both of which still need to be live for this call.
+      setEnabled(false);
+      offInk();
+      if (!canvas) return;
+      canvas.element.removeEventListener("pointerdown", onPointerDown);
+      canvas.element.removeEventListener("pointermove", onPointerMove);
+      canvas.element.removeEventListener("pointerup", onPointerEnd);
+      canvas.element.removeEventListener("pointercancel", onPointerEnd);
+      canvas.dispose();
+    },
+  };
+}

package/src/framework/annotate/ink-canvas.js

@@ -0,0 +1,129 @@
+// The annotation ink layer: a transparent 2D canvas stacked over the viewer
+// canvas (the first screen-space overlay canvas in the framework — everything
+// else that follows the model is in-scene, see dim3-scene.js). Appended to the
+// STAGE, not document.body, so it lives in .pf-stage's positioning context and
+// behaves under the narrow-pane layout. While visible it owns all pointer
+// events, which is what freezes orbit controls during annotation — no viewer
+// changes needed. Strokes render dark-core-over-light-halo so ink reads on
+// both themes and any model color.
+import { runCleanupSteps } from "../teardown.js";
+
+const CORE_COLOR = "#d92d20";
+const HALO_COLOR = "rgba(255, 255, 255, 0.85)";
+const HALO_RATIO = 2.2; // halo pass width relative to the core width
+
+export function createInkCanvas(stage, {
+  getContext2d = (canvas) => canvas.getContext("2d"),
+  createCanvas = () => document.createElement("canvas"),
+} = {}) {
+  const canvas = createCanvas();
+  canvas.className = "pf-ink-canvas";
+  canvas.hidden = true;
+  stage.appendChild(canvas);
+  const ctx = getContext2d(canvas);
+  let strokes = [];
+
+  // Strokes are normalized, so a pass is written against whatever bitmap it is
+  // handed — the live canvas, or the scratch one toDataUrl uses to bound an
+  // export. Width scales with the target's short edge for the same reason.
+  function drawPass(target, targetCtx, color, widthScale) {
+    targetCtx.strokeStyle = color;
+    targetCtx.fillStyle = color;
+    targetCtx.lineCap = "round";
+    targetCtx.lineJoin = "round";
+    const short = Math.min(target.width, target.height);
+    for (const stroke of strokes) {
+      const w = stroke.width * short * widthScale;
+      if (stroke.points.length === 1) {
+        const [nx, ny] = stroke.points[0];
+        targetCtx.beginPath();
+        targetCtx.arc(nx * target.width, ny * target.height, w / 2, 0, Math.PI * 2);
+        targetCtx.fill();
+        continue;
+      }
+      targetCtx.lineWidth = w;
+      targetCtx.beginPath();
+      stroke.points.forEach(([nx, ny], i) => {
+        const x = nx * target.width;
+        const y = ny * target.height;
+        if (i === 0) targetCtx.moveTo(x, y);
+        else targetCtx.lineTo(x, y);
+      });
+      targetCtx.stroke();
+    }
+  }
+
+  function drawInto(targetCtx, target) {
+    targetCtx.clearRect(0, 0, target.width, target.height);
+    drawPass(target, targetCtx, HALO_COLOR, HALO_RATIO);
+    drawPass(target, targetCtx, CORE_COLOR, 1);
+  }
+
+  function draw() {
+    if (!ctx) return;
+    drawInto(ctx, canvas);
+  }
+
+  function resize() {
+    const rect = stage.getBoundingClientRect();
+    const dpr = globalThis.devicePixelRatio || 1;
+    const width = Math.max(1, Math.round(rect.width * dpr));
+    const height = Math.max(1, Math.round(rect.height * dpr));
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width;
+      canvas.height = height;
+    }
+    draw();
+  }
+
+  // The viewer's own ResizeObserver is internal (viewer.js exposes no resize
+  // hook), so the overlay runs its own — ink is normalized, so a resize is
+  // just a re-rasterize at the new bitmap size. Skip it while hidden: the
+  // stage keeps resizing (rail drags, window resizes) whether or not
+  // annotate mode is on, and re-rasterizing an invisible canvas is wasted
+  // work; show() already calls resize() so nothing is missed on re-entry.
+  const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+    if (canvas.hidden) return;
+    resize();
+  });
+  observer?.observe(stage);
+
+  let disposed = false;
+  return {
+    element: canvas,
+    show() { canvas.hidden = false; resize(); },
+    hide() { canvas.hidden = true; },
+    setStrokes(next) { strokes = next; draw(); },
+    // The ink layer as a transparent PNG. `maxEdge` bounds the exported
+    // bitmap: the live canvas is stage-sized × devicePixelRatio, so on a large
+    // hi-DPI display it runs to several thousand pixels a side, and a PNG that
+    // big is both slow to encode and large enough that a host with a payload
+    // ceiling would have to drop it — losing the drawing while keeping the
+    // picture of the model, which is the one outcome worse than failing. Above
+    // the bound the strokes are re-rasterized into a scratch canvas rather than
+    // resampled, so thin ink stays crisp instead of turning to mush. Under it
+    // (the ordinary case) nothing is copied and the live canvas exports
+    // directly.
+    toDataUrl({ maxEdge } = {}) {
+      const long = Math.max(canvas.width, canvas.height);
+      if (!maxEdge || long <= maxEdge) return canvas.toDataURL("image/png");
+      const scale = maxEdge / long;
+      const scratch = createCanvas();
+      scratch.width = Math.max(1, Math.round(canvas.width * scale));
+      scratch.height = Math.max(1, Math.round(canvas.height * scale));
+      const scratchCtx = getContext2d(scratch);
+      if (!scratchCtx) return canvas.toDataURL("image/png");
+      drawInto(scratchCtx, scratch);
+      return scratch.toDataURL("image/png");
+    },
+    size: () => ({ width: canvas.width, height: canvas.height, dpr: globalThis.devicePixelRatio || 1 }),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      runCleanupSteps([
+        () => observer?.disconnect(),
+        () => canvas.remove(),
+      ], "ink canvas cleanup failed");
+    },
+  };
+}

package/src/framework/annotate/ink.js

@@ -0,0 +1,124 @@
+// 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;
+}

package/src/framework/app.css

@@ -323,6 +323,20 @@ 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); }
@@ -337,8 +351,12 @@ 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 { gap: 3px; }
-  #viewbar .pf-cutaway-actions button, #viewbar .pf-measure-actions button { min-width: 44px; padding: 0 6px; }
+  #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
+     pill'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; }
 }
 
 /* ---- measurement mode -----------------------------------------------------

package/src/framework/chrome.css

@@ -356,3 +356,21 @@
 @media (prefers-reduced-motion: reduce) {
   .pf-rail, .pf-rail-seam > span { transition: none; }
 }
+
+/* ---- 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. */
+.pf-ink-canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 10;
+  /* Pencil cursor (the viewbar toggle's lucide pencil), hotspot at the tip.
+     White halo under a dark stroke keeps it readable over both the model and
+     the backdrop; crosshair is the no-custom-cursor fallback. */
+  cursor: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24' fill='none' stroke-linecap='round' stroke-linejoin='round'%3E%3Cg stroke='white' stroke-width='4.5'%3E%3Cpath d='M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z'/%3E%3Cpath d='m15 5 4 4'/%3E%3C/g%3E%3Cg stroke='%231d232b' stroke-width='2'%3E%3Cpath d='M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z'/%3E%3Cpath d='m15 5 4 4'/%3E%3C/g%3E%3C/svg%3E") 2 22, crosshair;
+  touch-action: none;
+}
+.pf-ink-canvas[hidden] { display: none; }

package/src/framework/mount.js

@@ -28,6 +28,8 @@ import { attachAnimationControls } from "./animation-controls.js";
 import { resolveDefaultView } from "./default-view.js";
 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";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
@@ -37,6 +39,14 @@ const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {}
 // Same no-op-default stance as attachTooltips/setHostPane below, for a
 // makeHandle caller (or a direct test) that doesn't wire measure mode.
 const NOOP_MEASURE = { isEnabled: () => false, setEnabled: () => {}, clearPins: () => {}, pinCount: () => 0 };
+// Same stance as NOOP_MEASURE: the handle's annotate surface exists whether or
+// not this mount wired the mode (it wires only when the host passes
+// onAnnotationSend — without a sink, Send would have nowhere to go).
+const NOOP_ANNOTATE = {
+  isEnabled: () => false, setEnabled: () => {}, undo: () => {}, clear: () => {},
+  strokeCount: () => 0, send: () => false,
+  onInkChange: () => () => {}, onModeChange: () => () => {},
+};
 // The STEP-on-Manifold import crossover's broken-state message (a second
 // needs-import-mesh after the mesh is already primed — see the "needs-import-mesh"
 // case below). One shared string so the status line, onBuild, and the ready
@@ -49,7 +59,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 }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -91,6 +101,11 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // button. Dimensions render in the scene, so a dimensioned capture is just
     // captureCurrent() taken while the mode is on.
     measure: measure ?? NOOP_MEASURE,
+    // Annotation-mode API (spec 2026-08-18): { isEnabled, setEnabled, clear,
+    // strokeCount, send, onModeChange } — an embedder drives the mode without
+    // 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,
   };
 }
 
@@ -182,6 +197,12 @@ function createCleanupStack() {
 //   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
 //                                 // OS gave up — surface it rather than showing a dead
 //                                 // canvas. Returns an unsubscribe.
+//   runtime.annotate: { isEnabled, setEnabled, undo, clear, strokeCount, send, onInkChange,
+//                       onModeChange } — drive annotation mode without the built-in button;
+//                                 // no-op when onAnnotationSend was not supplied. Both
+//                                 // 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.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.
@@ -194,10 +215,27 @@ function createCleanupStack() {
 //                                         // is a snapshot copy. Never fired by setParams or
 //                                         // animation playback — hosts call setParams from their
 //                                         // own undo/reset, and firing here would loop.
+// onAnnotationSend(payload)              // receive user annotations (freehand ink over the frozen
+//                                         // view). Supplying this reveals the #annotate viewbar
+//                                         // button; omitting it hides the button entirely.
+//                                         // payload.images carries two data URLs (the ink drawing
+//                                         // and the rendered model), each bounded to a 2048px long
+//                                         // edge — a stage bigger than that exports scaled down
+//                                         // rather than at its own hi-DPI size. Still hundreds of
+//                                         // 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).
 // 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.
-export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit,
+export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
+                              annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -228,6 +266,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
       measure: elements.chrome?.measure ?? byId("measure"),
+      annotate: elements.chrome?.annotate ?? byId("annotate"),
       railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
     },
   };
@@ -349,6 +388,30 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       getParamsVersion: () => loop.version(),
     });
     cleanup.defer(() => measureMode.detach());
+    // Annotation mode (spec 2026-08-18): freehand ink over the frozen view,
+    // delivered to the host via onAnnotationSend. Wired only when the host
+    // passes the sink; the chrome hides the button otherwise (mode = null).
+    let annotateMode = null;
+    if (onAnnotationSend) {
+      annotateMode = createAnnotateMode(viewer, {
+        stage: els.viewer,
+        getContext: () => ({ view: view(), params }),
+        onSend: onAnnotationSend,
+      });
+      cleanup.defer(() => annotateMode.detach());
+      // Annotate and measure both claim canvas pointer input — mutually
+      // exclusive, whichever turns on turns the other off.
+      cleanup.defer(annotateMode.onModeChange(() => {
+        if (annotateMode.isEnabled()) measureMode.setEnabled(false);
+      }));
+      cleanup.defer(measureMode.onModeChange(() => {
+        if (measureMode.isEnabled()) annotateMode.setEnabled(false);
+      }));
+    }
+    const annotateChrome = attachAnnotateControls(viewer, annotateMode, {
+      annotate: els.chrome.annotate,
+    }, { tooltip, escapeScope: els.viewer, send: annotateSend });
+    cleanup.defer(() => annotateChrome.detach());
     // 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
@@ -360,13 +423,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => measureChrome.detach());
     const cutawayChrome = attachCutawayControls(viewer, {
       cutaway: els.chrome.cutaway,
-    }, { tooltip, escapeGuard: () => measureMode.isEnabled() });
+    }, { tooltip, escapeGuard: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false) });
     cleanup.defer(() => cutawayChrome.detach());
-    // Suppress the always-on hover tooltip while measure mode is active — its
-    // own feature highlight + dims take over the pointer.
-    const offMeasureHover = measureMode.onModeChange(() =>
-      hover.setSuppressed(measureMode.isEnabled()));
-    cleanup.defer(offMeasureHover);
+    // Suppress the always-on hover tooltip while measure OR annotate mode is
+    // active — measure's highlight + dims take the pointer; annotate's overlay
+    // canvas takes it entirely.
+    const syncHoverSuppression = () =>
+      hover.setSuppressed(measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false));
+    cleanup.defer(measureMode.onModeChange(syncHoverSuppression));
+    if (annotateMode) cleanup.defer(annotateMode.onModeChange(syncHoverSuppression));
 
     // Current selection context for the pickers: the active view + live params +
     // derived values. Shared by every pick mode below.
@@ -392,7 +457,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         // resync on mode changes. The ?pick/?pickserver harnesses below are
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
-        suppressed: () => measureMode.isEnabled(),
+        suppressed: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
         onPick: (selection) => onPick({
           selection,
           label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
@@ -869,6 +934,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         clearPins: measureMode.clearPins,
         pinCount: measureMode.pinCount,
       },
+      annotate: annotateMode ? {
+        isEnabled: annotateMode.isEnabled,
+        setEnabled: annotateMode.setEnabled,
+        undo: annotateMode.undo,
+        clear: annotateMode.clear,
+        strokeCount: annotateMode.strokeCount,
+        send: annotateMode.send,
+        onInkChange: annotateMode.onInkChange,
+        onModeChange: annotateMode.onModeChange,
+      } : null,
     });
   } catch (error) {
     try {

package/types/index.d.ts

@@ -88,6 +88,7 @@ export interface MountElements {
     theme?: HTMLElement | null;
     cutaway?: HTMLElement | null;
     measure?: HTMLElement | null;
+    annotate?: HTMLElement | null;
     railToggle?: HTMLElement | null;
   };
 }
@@ -110,6 +111,19 @@ export interface MountOptions {
   onDownload?: (file: DownloadPayload) => void;
   /** The active view (tab) name — emitted once on mount, then on every change. */
   onViewChange?: (view: string) => void;
+  /**
+   * Receive user annotations (freehand ink over the frozen view). Supplying
+   * this reveals the `#annotate` viewbar button; omitting it hides the button
+   * entirely.
+   */
+  onAnnotationSend?: (payload: AnnotationPayload) => void;
+  /**
+   * Who owns annotation mode's Send affordance. `"viewbar"` (the default) puts
+   * Send beside Undo/Clear in the actions row. `"host"` drops it and leaves
+   * Undo/Clear: the host draws its own send control — e.g. a composer pairing
+   * the sketch with a typed message — and calls `runtime.annotate.send()`.
+   */
+  annotateSend?: "viewbar" | "host";
   /** @deprecated alias for `elements.viewer`. */
   container?: HTMLElement | null;
   /** @deprecated alias for `elements.controls`. */
@@ -156,6 +170,66 @@ export interface MeasureRuntime {
   pinCount(): number;
 }
 
+/** One freehand stroke: points normalized 0..1 in viewport space; width as a
+ *  fraction of the viewport's short edge. */
+export interface AnnotationStroke {
+  points: [number, number][];
+  width: number;
+}
+
+/** A raycast sample grounding a stroke in the model. `t` anchors sit at the
+ *  stroke's start/mid/end by arc length; `kind: "centroid"` anchors sit at the
+ *  enclosed-region centroid of a closed stroke. `hit` is null when the sample
+ *  ray missed all geometry — a deliberate signal, not an error. */
+export interface AnnotationAnchor {
+  stroke: number;
+  t?: number;
+  kind?: "centroid";
+  screen: [number, number];
+  hit: { subPart: string; pointLocal: [number, number, number] } | null;
+}
+
+/** A camera pose. `world` replays exactly against the annotated build; `parts`
+ *  is the same pose in the shared CAD frame (survives per-view recentring when
+ *  the model is rebuilt), or null when no meshes were live. */
+export interface AnnotationCamera {
+  world: { pos: number[]; target: number[]; up: number[]; fov: number };
+  parts: { pos: number[]; target: number[]; up: number[]; fov: number } | null;
+}
+
+/** What onAnnotationSend receives. The drawing and the 3D render are separate
+ *  images over the same framing, so a host can composite them now and
+ *  re-render the model from the same camera against later updates. */
+export interface AnnotationPayload {
+  version: 1;
+  strokes: AnnotationStroke[];
+  anchors: AnnotationAnchor[];
+  /** Two base64 data URLs. On a large hi-DPI stage the drawing PNG alone can
+   *  run several MB of base64 — hosts should not assume this payload is small. */
+  images: { drawing: string; model: string };
+  camera: AnnotationCamera;
+  viewport: { width: number; height: number; dpr: number };
+  context: { view: string; params: Record<string, unknown> };
+}
+
+export interface AnnotateRuntime {
+  isEnabled(): boolean;
+  setEnabled(on: boolean): void;
+  /** Drop the most recent stroke. */
+  undo(): void;
+  clear(): void;
+  strokeCount(): number;
+  /**
+   * Assemble the payload and hand it to `onAnnotationSend`, then exit the mode
+   * and discard the ink. Returns false — delivering nothing and keeping the ink
+   * — when the mode is off, the canvas is empty, or the render failed.
+   */
+  send(): boolean;
+  /** Every stroke, undo and clear. Returns an unsubscribe. */
+  onInkChange(cb: () => void): () => void;
+  onModeChange(cb: () => void): () => void;
+}
+
 /** Where playback is: idle, swinging the camera to an intro cue, playing, or paused. */
 export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
 
@@ -269,6 +343,8 @@ export interface PartRuntime {
   animation: AnimationRuntime | null;
   /** Measurement mode's runtime-controls API — mode on/off, unit, and pin state; dimensioned captures come from `captureCurrent()` while enabled. Always present (a no-op stand-in outside `makeHandle` tests). */
   measure: MeasureRuntime;
+  /** Annotation mode's runtime-controls API — mode on/off, ink state, and send. Always present; a no-op stand-in when `onAnnotationSend` was not supplied. */
+  annotate: AnnotateRuntime;
 }
 
 /** Mount a full parametric-part app from a `PartDefinition`. */