partforge 0.87.0 → 0.89.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");
+    },
+  };
+}