partforge 0.87.0 → 0.88.0

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

@@ -4,14 +4,182 @@
 // 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.
+// changes needed. Elements render dark-core-over-light-halo so ink reads on
+// both themes and any model color; a tool-driven overlay (handles, guides,
+// labels, ...) is drawn on top in chrome colors, and is excluded from export.
 import { runCleanupSteps } from "../teardown.js";
+import { visibleRuns, handlesOf, INK_COLORS } from "./elements.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
 
+// Stage space -> pixels. Stage y ranges over [0,1] and spans the bitmap
+// height; stage x is pre-scaled by the viewport aspect (bitmap width =
+// aspect x height by construction, see elements.js), so the same factor
+// (target.height) maps both axes.
+const mapper = (target) => {
+  const s = target.height;
+  return (p) => [p.x * s, p.y * s];
+};
+
+// One halo-or-core pass over every element's visible runs. Shared by the
+// live draw and the elements-only export path.
+function strokePass(target, ctx, elements, widthScale, colorOf) {
+  const short = Math.min(target.width, target.height);
+  ctx.lineCap = "round";
+  ctx.lineJoin = "round";
+  const toPx = mapper(target);
+  for (const el of elements) {
+    const w = el.width * short * widthScale;
+    ctx.strokeStyle = colorOf(el);
+    ctx.fillStyle = ctx.strokeStyle;
+    ctx.lineWidth = w;
+    for (const run of visibleRuns(el)) {
+      if (run.length === 1) {
+        const [x, y] = toPx(run[0]);
+        ctx.beginPath();
+        ctx.arc(x, y, w / 2, 0, Math.PI * 2);
+        ctx.fill();
+        continue;
+      }
+      ctx.beginPath();
+      run.forEach((p, i) => {
+        const [x, y] = toPx(p);
+        if (i === 0) ctx.moveTo(x, y);
+        else ctx.lineTo(x, y);
+      });
+      ctx.stroke();
+    }
+  }
+}
+
+// Elements only — halo pass then core pass. This is both the export path
+// (toDataUrl draws only this into a scratch canvas) and the base of the live
+// draw.
+function drawElements(ctx, target, elements) {
+  ctx.clearRect(0, 0, target.width, target.height);
+  strokePass(target, ctx, elements, HALO_RATIO, () => HALO_COLOR);
+  strokePass(target, ctx, elements, 1, (el) => INK_COLORS[el.color]);
+}
+
+// Chrome (accent/surface/text) colors for overlay adornments, resolved from
+// CSS custom properties on the canvas so the ink layer follows the host's
+// theme. Falls back to literal defaults — required in bare test environments
+// where getComputedStyle may be absent or return unset custom properties.
+const chromeColor = (canvas, name, fallback) => {
+  try {
+    const v = globalThis.getComputedStyle?.(canvas)?.getPropertyValue(name)?.trim();
+    return v || fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+const chromeColors = (canvas) => ({
+  accent: chromeColor(canvas, "--pf-accent", "#3f7bf0"),
+  surface: chromeColor(canvas, "--pf-surface", "#ffffff"),
+  text: chromeColor(canvas, "--pf-text", "#111111"),
+});
+
+function drawGlow(ctx, target, glowEl, accent) {
+  if (!glowEl) return;
+  const short = Math.min(target.width, target.height);
+  const toPx = mapper(target);
+  const w = glowEl.width * short * HALO_RATIO * 1.6;
+  ctx.save();
+  ctx.globalAlpha = 0.35;
+  ctx.strokeStyle = accent;
+  ctx.fillStyle = accent;
+  ctx.lineCap = "round";
+  ctx.lineJoin = "round";
+  ctx.lineWidth = w;
+  for (const run of visibleRuns(glowEl)) {
+    if (run.length === 1) {
+      const [x, y] = toPx(run[0]);
+      ctx.beginPath();
+      ctx.arc(x, y, w / 2, 0, Math.PI * 2);
+      ctx.fill();
+      continue;
+    }
+    ctx.beginPath();
+    run.forEach((p, i) => {
+      const [x, y] = toPx(p);
+      if (i === 0) ctx.moveTo(x, y);
+      else ctx.lineTo(x, y);
+    });
+    ctx.stroke();
+  }
+  ctx.restore();
+}
+
+// Handles/labels/glyph geometry and the chrome stroke widths below are
+// specified as CSS pixels, but the bitmap they draw into is device pixels
+// (CSS size × dpr, see resize()) — the same distinction the ink strokes
+// already get for free via el.width being a fraction of the (dpr-scaled)
+// short edge. Every literal constant here is multiplied by `dpr` (the
+// current bitmap dpr, threaded in from draw()) so this chrome renders at its
+// intended CSS size instead of shrinking to half that on a dpr-2 display.
+function drawHandles(ctx, target, handlesEl, chrome, dpr) {
+  if (!handlesEl) return;
+  const toPx = mapper(target);
+  const HS = 7 * dpr;
+  ctx.fillStyle = chrome.surface;
+  ctx.strokeStyle = chrome.accent;
+  ctx.lineWidth = 1.5 * dpr;
+  for (const h of handlesOf(handlesEl)) {
+    const [x, y] = toPx(h);
+    ctx.fillRect(x - HS / 2, y - HS / 2, HS, HS);
+    ctx.strokeRect(x - HS / 2, y - HS / 2, HS, HS);
+  }
+}
+
+function drawGuide(ctx, target, guide, chrome, dpr) {
+  if (!guide) return;
+  const toPx = mapper(target);
+  ctx.strokeStyle = chrome.accent;
+  ctx.lineWidth = 1 * dpr;
+  ctx.setLineDash([4 * dpr, 3 * dpr]);
+  if (guide.kind === "rect") {
+    // w/h are stage-space extents, not a stroke width — map them with the
+    // same factor as points (target.height), not the short-edge convention
+    // strokePass/drawGlow use for line width.
+    const [x, y] = toPx({ x: guide.cx - guide.w / 2, y: guide.cy - guide.h / 2 });
+    const [x2, y2] = toPx({ x: guide.cx + guide.w / 2, y: guide.cy + guide.h / 2 });
+    ctx.strokeRect(x, y, x2 - x, y2 - y);
+  } else if (guide.kind === "cross") {
+    const [x, y] = toPx({ x: guide.cx, y: guide.cy });
+    const arm = 5 * dpr;
+    ctx.beginPath();
+    ctx.moveTo(x - arm, y);
+    ctx.lineTo(x + arm, y);
+    ctx.moveTo(x, y - arm);
+    ctx.lineTo(x, y + arm);
+    ctx.stroke();
+  }
+  ctx.setLineDash([]);
+}
+
+function drawLabel(ctx, target, label, chrome, dpr) {
+  if (!label) return;
+  const toPx = mapper(target);
+  const [x, y] = toPx(label);
+  ctx.font = `${10 * dpr}px monospace`;
+  const metrics = ctx.measureText(label.text);
+  const padX = 4 * dpr;
+  const padY = 3 * dpr;
+  const boxW = (metrics?.width || 0) + padX * 2;
+  const boxH = 10 * dpr + padY * 2;
+  // Offset the plate clear of the pointer: the label anchors at the dragged
+  // corner/handle, i.e. under the cursor, so 16px right + 12px up keeps it
+  // outside both the arrow cursor's body and the crosshair's arms.
+  const bx = x + 16 * dpr;
+  const by = y - 12 * dpr - boxH;
+  ctx.fillStyle = chrome.surface;
+  ctx.fillRect(bx, by, boxW, boxH);
+  ctx.fillStyle = chrome.accent;
+  ctx.fillText(label.text, bx + padX, by + boxH - padY);
+}
+
 export function createInkCanvas(stage, {
   getContext2d = (canvas) => canvas.getContext("2d"),
   createCanvas = () => document.createElement("canvas"),
@@ -21,52 +189,39 @@ export function createInkCanvas(stage, {
   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);
-  }
+  let scene = { elements: [], overlay: {} };
+  // The bitmap's current dpr, set by resize()/size() below and read by draw()
+  // to scale the overlay chrome's fixed-CSS-pixel constants (handles, label,
+  // chrome line widths) up to device pixels. Defaults to 1 so a
+  // draw() before the first resize() (there isn't one on this path, but
+  // belt-and-suspenders) doesn't under/over-scale.
+  let currentDpr = 1;
 
+  // Live draw order: glow -> all halos -> all cores -> handles -> guide ->
+  // label. Glow renders before the elements' own halo/core passes so it reads
+  // as a soft field behind the ink, not on top of it. Pointer-followers (the
+  // eraser ring, the rotate glyph) are deliberately NOT drawn here: anything
+  // that must track the cursor per-mousemove would force a full-canvas redraw
+  // per event — they are CSS cursors instead (app.css), rendered by the
+  // compositor at zero canvas cost.
   function draw() {
     if (!ctx) return;
-    drawInto(ctx, canvas);
+    const overlay = scene.overlay || {};
+    const chrome = chromeColors(canvas);
+    const dpr = currentDpr;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    drawGlow(ctx, canvas, overlay.glowEl, chrome.accent);
+    strokePass(canvas, ctx, scene.elements, HALO_RATIO, () => HALO_COLOR);
+    strokePass(canvas, ctx, scene.elements, 1, (el) => INK_COLORS[el.color]);
+    drawHandles(ctx, canvas, overlay.handlesEl, chrome, dpr);
+    drawGuide(ctx, canvas, overlay.guide, chrome, dpr);
+    drawLabel(ctx, canvas, overlay.label, chrome, dpr);
   }
 
   function resize() {
     const rect = stage.getBoundingClientRect();
     const dpr = globalThis.devicePixelRatio || 1;
+    currentDpr = dpr;
     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) {
@@ -77,11 +232,11 @@ export function createInkCanvas(stage, {
   }
 
   // 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.
+  // hook), so the overlay runs its own — 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();
@@ -93,27 +248,29 @@ export function createInkCanvas(stage, {
     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.
+    setScene(next) { scene = next; draw(); },
+    // The ink layer as a transparent PNG, elements only — overlay adornments
+    // (handles, guides, labels, the eraser ring, ...) are tool chrome, not
+    // part of the drawing, and must never reach the export. Since the live
+    // canvas now carries that overlay, export always re-rasterizes elements
+    // into a scratch canvas rather than reading the live bitmap directly.
+    // `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 elements are
+    // re-rasterized at the scaled-down size rather than resampled, so thin
+    // ink stays crisp instead of turning to mush.
     toDataUrl({ maxEdge } = {}) {
       const long = Math.max(canvas.width, canvas.height);
-      if (!maxEdge || long <= maxEdge) return canvas.toDataURL("image/png");
-      const scale = maxEdge / long;
+      const scale = maxEdge && long > maxEdge ? maxEdge / long : 1;
       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);
+      drawElements(scratchCtx, scratch, scene.elements);
       return scratch.toDataURL("image/png");
     },
     size: () => ({ width: canvas.width, height: canvas.height, dpr: globalThis.devicePixelRatio || 1 }),

package/src/framework/annotate/sketch-toolbar.js

@@ -0,0 +1,202 @@
+// Sketch-mode toolbar: the top-centre pill that OWNS the mode while sketch
+// mode is on (annotate-controls.js's viewbar pencil+actions is hidden for the
+// duration — mount toggles both). A direct sibling of annotate-controls.js:
+// same mode-object-owns-behavior split, same tooltip/cleanup idioms, same
+// `send: "host"` contract for a host that draws its own send affordance.
+//
+// Two DOM nodes are appended to the stage: the toolbar pill itself and a
+// `.pf-sketch-hint` sibling (not a child — see the CSS, which positions it
+// independently below the pill) carrying a one-line usage hint for the
+// active tool.
+import { attachButtonTooltips } from "../tooltip.js";
+import { runCleanupSteps } from "../teardown.js";
+import { INK_COLORS } from "./elements.js";
+
+// pen: the same pencil glyph as annotate-controls.js's toggle button.
+const PEN_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" 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 LINE_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 19 19 5"/></svg>`;
+const RECT_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="6" width="16" height="12" rx="1"/></svg>`;
+const ELLIPSE_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><ellipse cx="12" cy="12" rx="9" ry="6.5"/></svg>`;
+// hand: lucide "hand" glyph.
+const HAND_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 11V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 10.5V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2v8"/><path d="M18 8a2 2 0 1 1 4 0v6a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/></svg>`;
+// eraser: lucide "eraser" glyph.
+const ERASER_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m7 21-4.3-4.3c-1-1-1-2.5 0-3.4l9.6-9.6c1-1 2.5-1 3.4 0l5.6 5.6c1 1 1 2.5 0 3.4L13 21"/><path d="M22 21H7"/><path d="m5 11 9 9"/></svg>`;
+// undo: lucide "undo-2" glyph.
+const UNDO_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 14 4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 5.5 5.5v0a5.5 5.5 0 0 1-5.5 5.5H11"/></svg>`;
+// clear: lucide "trash-2" glyph.
+const CLEAR_ICON = `<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" y1="11" x2="10" y2="17"/><line x1="14" y1="11" x2="14" y2="17"/></svg>`;
+// close: lucide "x" glyph. The toolbar's own exit affordance — see its
+// wiring below for why the mode needs one now that #viewbar (and the pencil
+// toggle that used to sit on it) is hidden for the duration of sketch mode.
+const CLOSE_ICON = `<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>`;
+
+const TOOLS = [
+  { tool: "pen", icon: PEN_ICON, label: "Pen", hint: "drag to draw" },
+  { tool: "line", icon: LINE_ICON, label: "Line", hint: "drag endpoint to endpoint · snaps to 0/45/90° · shift forces" },
+  { tool: "rect", icon: RECT_ICON, label: "Rectangle", hint: "drag corner to corner · snaps to square · shift forces" },
+  { tool: "ellipse", icon: ELLIPSE_ICON, label: "Ellipse", hint: "drag corner to corner · snaps to circle · shift forces" },
+  { tool: "hand", icon: HAND_ICON, label: "Move", hint: "drag a shape to move it · handles resize · just outside rotates" },
+  { tool: "eraser", icon: ERASER_ICON, label: "Eraser", hint: "scrub to erase" },
+];
+
+const COLOR_LABELS = { red: "Red ink", blue: "Blue ink", green: "Green ink" };
+
+function makeButton({ className = "", dataset = {}, title, ariaLabel, html }) {
+  const button = document.createElement("button");
+  button.type = "button";
+  if (className) button.className = className;
+  for (const [key, value] of Object.entries(dataset)) button.dataset[key] = value;
+  if (html !== undefined) button.innerHTML = html;
+  if (title) button.title = title;
+  button.setAttribute("aria-label", ariaLabel ?? title ?? "");
+  return button;
+}
+
+function makeSeparator() {
+  const sep = document.createElement("span");
+  sep.className = "sep";
+  sep.setAttribute("aria-hidden", "true");
+  return sep;
+}
+
+export function attachSketchToolbar(mode, { stage, tooltip, send = "viewbar" } = {}) {
+  const element = document.createElement("div");
+  element.className = "pf-sketch-toolbar";
+  element.setAttribute("role", "toolbar");
+  element.hidden = true;
+
+  const hint = document.createElement("div");
+  hint.className = "pf-sketch-hint";
+  hint.hidden = true;
+
+  const toolButtons = TOOLS.map(({ tool, icon, label }) => makeButton({
+    dataset: { tool },
+    title: label,
+    html: icon,
+  }));
+  for (const button of toolButtons) button.setAttribute("aria-pressed", "false");
+  element.append(...toolButtons, makeSeparator());
+
+  const swatchButtons = Object.keys(INK_COLORS).map((color) => {
+    const button = makeButton({
+      className: "pf-swatch",
+      dataset: { color },
+      title: COLOR_LABELS[color] ?? color,
+    });
+    button.style.setProperty("--sw", INK_COLORS[color]);
+    return button;
+  });
+  element.append(...swatchButtons, makeSeparator());
+
+  const undoButton = makeButton({ dataset: { action: "undo" }, title: "Undo", html: UNDO_ICON });
+  const clearButton = makeButton({ dataset: { action: "clear" }, title: "Clear", html: CLEAR_ICON });
+  element.append(undoButton, clearButton);
+
+  let sendButton = null;
+  if (send !== "host") {
+    sendButton = makeButton({ dataset: { action: "send" }, title: "Send" });
+    sendButton.textContent = "Send";
+    element.append(sendButton);
+  }
+
+  // Close: the toolbar's own exit affordance, always the LAST button — it
+  // must outlive send's presence/absence so the mode is exitable in-UI
+  // regardless of the `send` variant. Never disabled (unlike undo/clear/
+  // send, which gate on stroke count): exiting has to work with an empty
+  // sketch. annotate-mode.js's document-capture Escape listener covers the
+  // keyboard path; this covers pointer/touch, including mobile, which has no
+  // Escape key at all.
+  const closeButton = makeButton({ dataset: { action: "close" }, title: "Exit sketch", html: CLOSE_ICON });
+  element.append(closeButton);
+
+  stage.append(element, hint);
+
+  const allButtons = [...toolButtons, ...swatchButtons, undoButton, clearButton, sendButton, closeButton].filter(Boolean);
+  const tooltipBinding = tooltip
+    ? attachButtonTooltips(tooltip, allButtons.map((btn) => ({ element: btn })))
+    : null;
+
+  function syncTools() {
+    const activeTool = mode.tool();
+    for (const button of toolButtons) {
+      const on = button.dataset.tool === activeTool;
+      button.classList.toggle("on", on);
+      button.setAttribute("aria-pressed", String(on));
+    }
+    const activeColor = mode.color();
+    for (const button of swatchButtons) {
+      button.classList.toggle("on", button.dataset.color === activeColor);
+    }
+    const entry = TOOLS.find((t) => t.tool === activeTool);
+    hint.textContent = entry?.hint ?? "";
+  }
+
+  function syncDisabled() {
+    const empty = mode.strokeCount() === 0;
+    undoButton.disabled = !mode.canUndo();
+    clearButton.disabled = empty;
+    if (sendButton) sendButton.disabled = empty;
+    tooltipBinding?.sync();
+  }
+
+  function syncVisibility() {
+    const on = mode.isEnabled();
+    element.hidden = !on;
+    hint.hidden = !on;
+  }
+
+  function sync() {
+    syncTools();
+    syncDisabled();
+    syncVisibility();
+  }
+
+  const onUndo = () => mode.undo();
+  const onClear = () => mode.clear();
+  const onSendClick = () => mode.send();
+  const onClose = () => mode.setEnabled(false);
+
+  const toolHandlers = toolButtons.map((button) => {
+    const handler = () => mode.setTool(button.dataset.tool);
+    button.addEventListener("click", handler);
+    return { button, handler };
+  });
+  const colorHandlers = swatchButtons.map((button) => {
+    const handler = () => mode.setColor(button.dataset.color);
+    button.addEventListener("click", handler);
+    return { button, handler };
+  });
+  undoButton.addEventListener("click", onUndo);
+  clearButton.addEventListener("click", onClear);
+  sendButton?.addEventListener("click", onSendClick);
+  closeButton.addEventListener("click", onClose);
+
+  const offTool = mode.onToolChange(sync);
+  const offInk = mode.onInkChange(sync);
+  const offMode = mode.onModeChange(sync);
+
+  sync();
+
+  let detached = false;
+  return {
+    element,
+    detach() {
+      if (detached) return;
+      detached = true;
+      runCleanupSteps([
+        offTool,
+        offInk,
+        offMode,
+        ...toolHandlers.map(({ button, handler }) => () => button.removeEventListener("click", handler)),
+        ...colorHandlers.map(({ button, handler }) => () => button.removeEventListener("click", handler)),
+        () => undoButton.removeEventListener("click", onUndo),
+        () => clearButton.removeEventListener("click", onClear),
+        () => sendButton?.removeEventListener("click", onSendClick),
+        () => closeButton.removeEventListener("click", onClose),
+        () => tooltipBinding?.detach(),
+        () => element.remove(),
+        () => hint.remove(),
+      ], "sketch toolbar cleanup failed");
+    },
+  };
+}

package/src/framework/app.css

@@ -278,7 +278,7 @@ 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-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);
 }
@@ -318,6 +318,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 +341,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 +529,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;