makersclaw 0.2.0 → 0.3.1

package/registry/blocks/sketch-canvas/sketch-canvas.jsx

@@ -0,0 +1,1188 @@
+"use client";
+
+// SketchCanvas — Excalidraw, in the workspace theme, behind one set of props.
+//
+// Client only, one static bundle. Excalidraw needs the DOM, and the app's
+// check refuses import() (so no next/dynamic): the modules load with the
+// page (on the server too — see excalidraw.js and ssr-shim.js for how that
+// is made safe), and the canvas itself mounts only after the first effect
+// (the mount guard). Until then — on the server and in the first client
+// paint — the same frame shows, with the sketch's words for a reader.
+//
+// What is ours and what is Excalidraw's: Excalidraw draws, selects, edits
+// text, keeps history and answers its own shortcuts. The tool rail, the
+// context toolbar (colours from the theme), the zoom and undo buttons, the
+// menu, the save state and the empty state are ours, in the kit; theme.js
+// hides the Excalidraw UI they replace. Where ours drives an Excalidraw
+// action that has no API (undo, zoom, layer order, duplicate, delete,
+// font size) it presses that action's own shortcut on the canvas, so the
+// behaviour is Excalidraw's exactly.
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { Button, Confirm, Icon, IconButton, Kbd, Menu, Popover, Separator, Toggle, Tooltip, cx } from "../../ui";
+import {
+  CaptureUpdateAction,
+  Excalidraw,
+  convertToExcalidrawElements,
+  exportToBlob,
+  getCommonBounds,
+  getSceneVersion,
+  newElementWith,
+  restoreElements,
+  sceneCoordsToViewportCoords,
+  viewportCoordsToSceneCoords,
+} from "./excalidraw";
+import { FILLS, STROKES, elementTokens, paletteKey, repaint, resolveColours, resolvePalette, tagTokens } from "./palette";
+import { BACKGROUND_ROLE, SKETCH_VERSION, SYSTEM_FONT, filesFor, isBackground, pickAppState, sketchToText, toSketch } from "./sketch";
+import { ROOT_VARS, THEME, TRIM_CSS } from "./theme";
+
+/** A ref for the canvas's handle: `const sketch = useSketchCanvas()`, then
+ *  `<SketchCanvas canvasRef={sketch} />` and `await sketch.current?.exportImage()`. */
+export function useSketchCanvas() {
+  return useRef(null);
+}
+
+/** The built-in tools, in rail order. `tools` picks a subset by id. */
+export const SKETCH_TOOLS = [
+  { id: "select", tool: "selection", label: "Select", icon: "mouse-pointer", key: "V" },
+  { id: "hand", tool: "hand", label: "Pan", icon: "hand", key: "H" },
+  { id: "draw", tool: "freedraw", label: "Draw", icon: "pencil", key: "P" },
+  { id: "rectangle", tool: "rectangle", label: "Rectangle", icon: "square", key: "R" },
+  { id: "ellipse", tool: "ellipse", label: "Ellipse", icon: "circle", key: "O" },
+  { id: "diamond", tool: "diamond", label: "Diamond", icon: "diamond", key: "D" },
+  { id: "arrow", tool: "arrow", label: "Arrow", icon: "arrow-right", key: "A" },
+  { id: "line", tool: "line", label: "Line", icon: "minus", key: "L" },
+  { id: "text", tool: "text", label: "Text", icon: "type", key: "T" },
+  { id: "image", tool: "image", label: "Image", icon: "image", key: null },
+  { id: "eraser", tool: "eraser", label: "Eraser", icon: "eraser", key: "E" },
+  { id: "frame", tool: "frame", label: "Frame", icon: "frame", key: "F" },
+];
+
+// Excalidraw's own single-key tool shortcuts; a tool left out of `tools`
+// has its keys swallowed so it cannot be reached by keyboard either.
+const TOOL_KEYS = {
+  selection: ["v", "1"],
+  rectangle: ["r", "2"],
+  diamond: ["d", "3"],
+  ellipse: ["o", "4"],
+  arrow: ["a", "5"],
+  line: ["l", "6"],
+  freedraw: ["p", "x", "7"],
+  text: ["t", "8"],
+  image: ["9"],
+  eraser: ["e", "0"],
+  hand: ["h"],
+  frame: ["f"],
+  laser: ["k"],
+};
+
+// Tailwind needs whole class names in the source: one per token.
+const SWATCH = {
+  foreground: "bg-foreground",
+  "muted-foreground": "bg-muted-foreground",
+  primary: "bg-primary",
+  destructive: "bg-destructive",
+  warning: "bg-warning",
+  success: "bg-success",
+  info: "bg-info",
+  "chart-2": "bg-chart-2",
+  "chart-3": "bg-chart-3",
+  "chart-4": "bg-chart-4",
+  "chart-5": "bg-chart-5",
+  none: "bg-background",
+  muted: "bg-muted",
+  "primary:soft": "bg-primary/25",
+  "destructive:soft": "bg-destructive/25",
+  "warning:soft": "bg-warning/25",
+  "success:soft": "bg-success/25",
+  "info:soft": "bg-info/25",
+  "chart-2:soft": "bg-chart-2/25",
+  "chart-3:soft": "bg-chart-3/25",
+  "chart-4:soft": "bg-chart-4/25",
+  "chart-5:soft": "bg-chart-5/25",
+};
+
+const WIDTHS = [
+  { value: 1, label: "Thin" },
+  { value: 2, label: "Medium" },
+  { value: 4, label: "Bold" },
+];
+
+const BG_ID = "sketch-background";
+const SHAPES = new Set(["rectangle", "ellipse", "diamond"]);
+const LINES = new Set(["arrow", "line", "freedraw"]);
+const isDarwin = () => typeof navigator !== "undefined" && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+const nonEmpty = (v) => (v && (Array.isArray(v) ? v.length : Array.isArray(v.elements) ? v.elements.length : false) ? v : null);
+
+/** A short stable hash (for a background file id). */
+function hash(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h.toString(36);
+}
+
+function mimeOf(src) {
+  const m = /^data:([^;,]+)/.exec(src);
+  if (m) return m[1];
+  const ext = /\.(png|jpe?g|webp|gif|svg)(?:[?#]|$)/i.exec(src)?.[1]?.toLowerCase();
+  return { png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif", svg: "image/svg+xml" }[ext] ?? "image/png";
+}
+
+/** The workspace's light or dark where the canvas sits. */
+function schemeOf(root) {
+  const scoped = root?.closest?.("[data-theme]")?.getAttribute("data-theme");
+  if (scoped === "light" || scoped === "dark") return scoped;
+  const cs = root ? getComputedStyle(root).colorScheme || "" : "";
+  if (/\bdark\b/.test(cs) && !/\blight\b/.test(cs)) return "dark";
+  if (/\blight\b/.test(cs) && !/\bdark\b/.test(cs)) return "light";
+  return typeof matchMedia !== "undefined" && matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+/** What is saved of the scene: live elements with their tokens, the
+ *  files they show, the appState a sketch keeps. */
+function sceneValue(api, palette) {
+  return valueOf(api.getSceneElements(), api.getFiles(), api.getAppState(), palette);
+}
+
+function valueOf(elements, files, appState, palette) {
+  const live = tagTokens(
+    elements.filter((el) => !el.isDeleted && !isBackground(el)),
+    palette,
+  );
+  return { type: "sketch", version: SKETCH_VERSION, elements: live, files: filesFor(live, files), appState: pickAppState(appState) };
+}
+
+/** A cheap fingerprint of a value's elements and files. */
+function signature(value) {
+  const s = toSketch(value);
+  return `${s.elements.map((e) => `${e.id}:${e.version}`).join(",")}|${Object.keys(s.files).sort().join(",")}`;
+}
+
+/** A box never shorter than the text bound inside it. Excalidraw re-wraps
+ *  and re-measures text as a scene loads (the system font, a narrower box)
+ *  but grows a container only while someone types, so text that wrapped to
+ *  an extra line hung out of its box ("Annual billing toggle" on the
+ *  whiteboard demo, seen in the pane 2026-09-24). Grows the box and centres
+ *  the text again; ellipses and diamonds need more room for the same text. */
+const BOUND_PAD = 5;
+function fitContainers(elements) {
+  const byId = new Map(elements.map((el) => [el.id, el]));
+  const grown = new Map();
+  for (const t of elements) {
+    if (t?.type !== "text" || !t.containerId || t.isDeleted) continue;
+    const box = grown.get(t.containerId) ?? byId.get(t.containerId);
+    if (!box || box.type === "arrow" || box.type === "line") continue;
+    // A rectangle needs the text plus its padding; an ellipse or diamond
+    // fits text of about 1/√2 of its height (a numbered pin: 18px of text
+    // in a 28px circle is fine, and must stay a circle).
+    const round = box.type === "ellipse" || box.type === "diamond";
+    const need = Math.ceil(round ? t.height * Math.SQRT2 : t.height + BOUND_PAD * 2);
+    if (box.height + 1 >= need) continue;
+    grown.set(box.id, { ...box, height: need, version: (box.version ?? 1) + 1 });
+  }
+  if (!grown.size) return elements;
+  return elements.map((el) => {
+    if (grown.has(el.id)) return grown.get(el.id);
+    if (el?.type === "text" && grown.has(el.containerId)) {
+      const box = grown.get(el.containerId);
+      return { ...el, y: box.y + (box.height - el.height) / 2, version: (el.version ?? 1) + 1 };
+    }
+    return el;
+  });
+}
+
+/** Elements as they should enter the scene: every text in the system
+ *  font (re-measured), tokened colours resolved in this theme. */
+function prepareElements(elements, palette) {
+  const fonted = (elements ?? []).map((el) => (el?.type === "text" && el.fontFamily !== SYSTEM_FONT ? { ...el, fontFamily: SYSTEM_FONT } : el));
+  const restored = fitContainers(restoreElements(fonted, null, { refreshDimensions: true, repairBindings: true }));
+  const patches = new Map(repaint(restored, palette, null).map((p) => [p.id, p.patch]));
+  return restored.map((el) => (patches.has(el.id) ? { ...el, ...patches.get(el.id) } : el));
+}
+
+/** A skeleton (convertToExcalidrawElements' input) ready to convert:
+ *  token colours resolved, texts in the system font. */
+function prepareSkeleton(sk, palette) {
+  const out = resolveColours(sk, palette);
+  if (out.type === "text" && !out.fontFamily) out.fontFamily = SYSTEM_FONT;
+  if (out.label && !out.label.fontFamily) out.label = { ...out.label, fontFamily: SYSTEM_FONT };
+  if (out.type !== "text" && !out.strokeColor && palette.foreground) out.strokeColor = palette.foreground;
+  if (out.type === "text" && !out.strokeColor && palette.foreground) out.strokeColor = palette.foreground;
+  return out;
+}
+
+function boundsOfSkeletons(sks) {
+  const boxes = sks.map((s) => {
+    const w = s.width ?? (s.type === "text" ? String(s.text ?? "").length * (s.fontSize ?? 20) * 0.55 : 0);
+    const h = s.height ?? (s.type === "text" ? (s.fontSize ?? 20) * 1.25 : 0);
+    return { x1: s.x ?? 0, y1: s.y ?? 0, x2: (s.x ?? 0) + w, y2: (s.y ?? 0) + h };
+  });
+  const x1 = Math.min(...boxes.map((b) => b.x1));
+  const y1 = Math.min(...boxes.map((b) => b.y1));
+  return { x: x1, y: y1, width: Math.max(...boxes.map((b) => b.x2)) - x1, height: Math.max(...boxes.map((b) => b.y2)) - y1 };
+}
+
+export function SketchCanvas(props) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  return <Frame {...props} mounted={mounted} />;
+}
+
+/** The frame, the same before and after the canvas mounts: server HTML
+ *  already has its size, border and text alternative; nothing jumps. */
+function Frame({ mounted, className, label = "Sketch", ...props }) {
+  const rootRef = useRef(null);
+  const descId = useId();
+  const [text, setText] = useState(() => sketchToText(nonEmpty(props.value) ?? nonEmpty(props.defaultValue)));
+  const sized = /(^|\s)(h-|min-h-|size-|flex-1|grow)/.test(className ?? "");
+  return (
+    <div
+      ref={rootRef}
+      data-sketch-canvas=""
+      role="group"
+      aria-label={label}
+      aria-describedby={descId}
+      className={cx(
+        "relative isolate overflow-hidden rounded-lg border border-border bg-background text-foreground",
+        !sized && "h-[32rem]",
+        ROOT_VARS,
+        THEME,
+        className,
+      )}
+    >
+      <style>{TRIM_CSS}</style>
+      <p id={descId} className="sr-only">
+        {text ? `The sketch says: ${text.replace(/\n+/g, ". ")}` : "The sketch is empty."}
+      </p>
+      {mounted ? (
+        <LiveSketch {...props} rootRef={rootRef} onText={setText} />
+      ) : (
+        <div className="grid h-full place-items-center text-sm text-muted-foreground" aria-busy="true">
+          Loading the canvas…
+        </div>
+      )}
+    </div>
+  );
+}
+
+function LiveSketch({
+  rootRef,
+  onText,
+  value,
+  defaultValue,
+  onChange,
+  onSave,
+  changeDelay = 600,
+  readOnly = false,
+  background,
+  tools,
+  stamps,
+  grid = true,
+  empty,
+  actions,
+  canvasRef,
+  onReady,
+}) {
+  const apiRef = useRef(null);
+  const [api, setApi] = useState(null);
+  // Excalidraw hands over its API before it has loaded initialData, then
+  // loads it asynchronously and replaces the scene. Anything laid before
+  // that is wiped: annotate's screenshot vanished that way (its file stayed,
+  // its image element went; seen in the pane 2026-09-24). `ready` turns true
+  // once the first load is done, and the effects that write the scene wait
+  // for it.
+  const [ready, setReady] = useState(false);
+  useEffect(() => {
+    if (!api) return;
+    if (!api.getAppState().isLoading) return setReady(true);
+    const off = api.onChange((_els, appState) => {
+      if (!appState.isLoading) setReady(true);
+    });
+    return () => off?.();
+  }, [api]);
+  const [palette, setPalette] = useState(() => resolvePalette(rootRef.current));
+  const paletteRef = useRef(palette);
+  const [scheme, setScheme] = useState(() => schemeOf(rootRef.current));
+  const [ui, setUi] = useState({ tool: "selection", zoom: 1, selected: [], box: null, count: 0, grid: false });
+  const uiKey = useRef("");
+  const [stamp, setStamp] = useState(null);
+  const [save, setSave] = useState({ state: "idle" });
+  const [clearing, setClearing] = useState(false);
+  const current = useRef({ strokeColor: "foreground", backgroundColor: "none" });
+
+  // What was last sent out / taken in, so a controlled `value` that is
+  // only our own echo never reloads the scene.
+  const initial = useRef(null);
+  if (!initial.current) initial.current = toSketch(nonEmpty(value) ?? nonEmpty(defaultValue));
+  const lastSig = useRef(null);
+  if (lastSig.current === null) lastSig.current = signature(initial.current);
+  const lastVersion = useRef(-1);
+  const timer = useRef(0);
+  const pending = useRef(false);
+  const latest = useRef(null);
+  const saveSeq = useRef(0);
+  const lastValue = useRef(initial.current);
+  const cbs = useRef({});
+  cbs.current = { onChange, onSave, onText, onReady };
+
+  const activeTools = useMemo(() => {
+    const want = Array.isArray(tools) && tools.length ? new Set(tools) : null;
+    return SKETCH_TOOLS.filter((t) => !want || want.has(t.id));
+  }, [tools]);
+  const blockedKeys = useMemo(() => {
+    const on = new Set(activeTools.map((t) => t.tool));
+    const keys = new Set();
+    for (const [tool, ks] of Object.entries(TOOL_KEYS)) if (!on.has(tool)) ks.forEach((k) => keys.add(k));
+    return keys;
+  }, [activeTools]);
+  const stampList = useMemo(() => (Array.isArray(stamps) ? stamps.filter((s) => s && s.id && typeof s.create === "function") : []), [stamps]);
+
+  const initialData = useMemo(() => {
+    const els = prepareElements(initial.current.elements, palette);
+    return {
+      elements: els,
+      files: initial.current.files,
+      appState: {
+        viewBackgroundColor: "transparent",
+        currentItemFontFamily: SYSTEM_FONT,
+        currentItemStrokeColor: palette.foreground,
+        currentItemBackgroundColor: "transparent",
+        currentItemFillStyle: "solid",
+        currentItemRoundness: "round",
+        gridModeEnabled: !!initial.current.appState.gridModeEnabled,
+      },
+      scrollToContent: true,
+    };
+    // Excalidraw reads initialData once.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ---- output -------------------------------------------------------------
+
+  const runSave = useCallback(async (v) => {
+    const fn = cbs.current.onSave;
+    if (!fn) return;
+    const seq = ++saveSeq.current;
+    setSave({ state: "saving" });
+    let res;
+    try {
+      res = await fn(v);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    if (seq !== saveSeq.current) return;
+    setSave(res?.ok ? { state: "saved" } : { state: "error", error: res?.error });
+  }, []);
+
+  const emit = useCallback(() => {
+    clearTimeout(timer.current);
+    pending.current = false;
+    // From what the last onChange handed us (so a flush while unmounting
+    // never reads a scene Excalidraw is tearing down), else the API.
+    const seen = latest.current;
+    const a = apiRef.current;
+    if (!seen && !a) return;
+    const v = seen ? valueOf(seen.elements, seen.files, seen.appState, paletteRef.current) : sceneValue(a, paletteRef.current);
+    lastValue.current = v;
+    lastSig.current = signature(v);
+    cbs.current.onText?.(sketchToText(v));
+    cbs.current.onChange?.(v);
+    runSave(v);
+  }, [runSave]);
+
+  const schedule = useCallback(() => {
+    clearTimeout(timer.current);
+    pending.current = true;
+    timer.current = setTimeout(emit, Math.max(0, changeDelay));
+  }, [emit, changeDelay]);
+
+  // Leaving with an edit still in its debounce: send it now, not never.
+  const flush = useRef(emit);
+  flush.current = emit;
+  useEffect(
+    () => () => {
+      clearTimeout(timer.current);
+      if (!pending.current) return;
+      try {
+        flush.current();
+      } catch {
+        // the canvas is already gone; nothing left to read
+      }
+    },
+    [],
+  );
+
+  // ---- the scene ----------------------------------------------------------
+
+  const quietUpdate = useCallback((elements, appState) => {
+    const a = apiRef.current;
+    if (!a) return;
+    a.updateScene({ elements, appState, captureUpdate: CaptureUpdateAction.NEVER });
+    lastVersion.current = getSceneVersion(a.getSceneElementsIncludingDeleted());
+  }, []);
+
+  /** Press one of Excalidraw's own shortcuts on the canvas. */
+  const press = useCallback((key, code, mods = {}) => {
+    const target = rootRef.current?.querySelector(".excalidraw");
+    if (!target) return;
+    const mac = isDarwin();
+    target.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key,
+        code,
+        bubbles: true,
+        cancelable: true,
+        metaKey: !!mods.cmd && mac,
+        ctrlKey: !!mods.cmd && !mac,
+        shiftKey: !!mods.shift,
+        altKey: !!mods.alt,
+      }),
+    );
+  }, [rootRef]);
+
+  const layer = useCallback(
+    (front) => {
+      const mac = isDarwin();
+      press(front ? "]" : "[", front ? "BracketRight" : "BracketLeft", mac ? { cmd: true, alt: true } : { cmd: true, shift: true });
+    },
+    [press],
+  );
+
+  // The locked background image, laid from the prop at the back.
+  const bgKey = background?.src ? `${background.src.length}:${hash(background.src)}:${background.width ?? ""}x${background.height ?? ""}` : "";
+  useEffect(() => {
+    const a = api;
+    if (!a || !ready) return;
+    const others = () => a.getSceneElementsIncludingDeleted().filter((el) => !isBackground(el));
+    if (!background?.src) {
+      if (a.getSceneElementsIncludingDeleted().some(isBackground)) quietUpdate(others());
+      return;
+    }
+    let cancelled = false;
+    const place = (width, height) => {
+      if (cancelled || !width || !height) return;
+      const fileId = `bg-${hash(background.src)}`;
+      a.addFiles([{ id: fileId, dataURL: background.src, mimeType: mimeOf(background.src), created: Date.now() }]);
+      const [bg] = convertToExcalidrawElements(
+        [{ type: "image", id: BG_ID, fileId, x: 0, y: 0, width, height, locked: true, status: "saved", customData: { role: BACKGROUND_ROLE } }],
+        { regenerateIds: false },
+      );
+      const rest = others();
+      quietUpdate([bg, ...rest]);
+      if (!rest.some((el) => !el.isDeleted)) a.scrollToContent(undefined, { fitToContent: true });
+    };
+    if (background.width && background.height) place(background.width, background.height);
+    else {
+      const img = new window.Image();
+      img.onload = () => place(img.naturalWidth, img.naturalHeight);
+      img.src = background.src;
+    }
+    return () => {
+      cancelled = true;
+    };
+    // bgKey stands for background's fields.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [api, ready, bgKey, quietUpdate]);
+
+  // Controlled: a `value` that is not what we last sent replaces the scene.
+  useEffect(() => {
+    const a = api;
+    if (!a || !ready || value === undefined) return;
+    const sig = signature(value);
+    if (sig === lastSig.current) return;
+    lastSig.current = sig;
+    const s = toSketch(value);
+    lastValue.current = s;
+    const bg = a.getSceneElementsIncludingDeleted().filter(isBackground);
+    const files = Object.values(s.files);
+    if (files.length) a.addFiles(files);
+    quietUpdate([...bg, ...prepareElements(s.elements, paletteRef.current)], { gridModeEnabled: !!s.appState.gridModeEnabled });
+    a.history.clear();
+    cbs.current.onText?.(sketchToText(s));
+  }, [api, ready, value, quietUpdate]);
+
+  // Theme and scheme: re-read the tokens when anything that sets them
+  // changes, and repaint what was drawn in them.
+  const refresh = useCallback(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    setScheme(schemeOf(root));
+    const next = resolvePalette(root);
+    const prev = paletteRef.current;
+    if (paletteKey(next) === paletteKey(prev)) return;
+    paletteRef.current = next;
+    setPalette(next);
+    const a = apiRef.current;
+    if (!a) return;
+    const all = a.getSceneElementsIncludingDeleted();
+    const patches = new Map(repaint(all, next, prev).map((p) => [p.id, p.patch]));
+    quietUpdate(
+      patches.size ? all.map((el) => (patches.has(el.id) ? newElementWith(el, patches.get(el.id)) : el)) : undefined,
+      {
+        currentItemStrokeColor: next[current.current.strokeColor] ?? next.foreground,
+        currentItemBackgroundColor: next[current.current.backgroundColor] ?? "transparent",
+      },
+    );
+  }, [rootRef, quietUpdate]);
+
+  useEffect(() => {
+    let t = 0;
+    const soon = () => {
+      clearTimeout(t);
+      t = setTimeout(refresh, 30);
+    };
+    const obs = new MutationObserver((records) => {
+      for (const r of records) for (const n of r.addedNodes ?? []) if (n.tagName === "LINK") n.addEventListener("load", soon, { once: true });
+      soon();
+    });
+    obs.observe(document.documentElement, { attributes: true, attributeFilter: ["data-theme", "class", "style"] });
+    obs.observe(document.head, { childList: true });
+    const scoped = rootRef.current?.closest("[data-theme]");
+    if (scoped && scoped !== document.documentElement) obs.observe(scoped, { attributes: true, attributeFilter: ["data-theme", "class", "style"] });
+    const mq = matchMedia("(prefers-color-scheme: dark)");
+    mq.addEventListener("change", soon);
+    soon();
+    return () => {
+      clearTimeout(t);
+      obs.disconnect();
+      mq.removeEventListener("change", soon);
+    };
+  }, [refresh, rootRef]);
+
+  // ---- Excalidraw's events -----------------------------------------------
+
+  const fontFix = useRef(0);
+  const handleChange = useCallback(
+    (elements, appState, files) => {
+      latest.current = { elements, appState, files };
+      // What our overlays show.
+      const selected = elements.filter((el) => appState.selectedElementIds[el.id] && !el.isDeleted);
+      const busy =
+        appState.newElement || appState.selectionElement || appState.selectedElementsAreBeingDragged || appState.resizingElement || appState.isResizing || appState.isRotating || appState.editingTextElement || appState.multiElement || appState.cursorButton === "down";
+      let box = null;
+      if (selected.length && !busy) {
+        const [x1, y1, x2, y2] = getCommonBounds(selected);
+        const a = sceneCoordsToViewportCoords({ sceneX: x1, sceneY: y1 }, appState);
+        const b = sceneCoordsToViewportCoords({ sceneX: x2, sceneY: y2 }, appState);
+        box = { x: a.x - appState.offsetLeft, y: a.y - appState.offsetTop, w: b.x - a.x, h: b.y - a.y, vw: appState.width, vh: appState.height };
+      }
+      const count = elements.reduce((n, el) => n + (!el.isDeleted && !isBackground(el) ? 1 : 0), 0);
+      const next = { tool: appState.activeTool.type, zoom: appState.zoom.value, selected: selected.map((el) => el.id), box, count, grid: !!appState.gridModeEnabled };
+      const key = JSON.stringify(next);
+      if (key !== uiKey.current) {
+        uiKey.current = key;
+        setUi(next);
+      }
+      // Output: only when the drawing changed, not on pan, zoom or select.
+      const v = getSceneVersion(elements);
+      if (lastVersion.current === -1) lastVersion.current = v;
+      else if (v !== lastVersion.current) {
+        lastVersion.current = v;
+        schedule();
+      }
+      // Text that arrived in another font (a paste, a dropped file): into
+      // the system font, once nothing is being edited.
+      if (!busy && elements.some((el) => el.type === "text" && !el.isDeleted && el.fontFamily !== SYSTEM_FONT)) {
+        clearTimeout(fontFix.current);
+        fontFix.current = setTimeout(() => {
+          const a = apiRef.current;
+          if (!a) return;
+          // The whole scene through restoreElements, as Excalidraw does on
+          // load: it re-measures text in its container (a subset would lose
+          // the bindings it cannot see).
+          const all = a.getSceneElementsIncludingDeleted();
+          const need = new Set(all.filter((el) => el.type === "text" && el.fontFamily !== SYSTEM_FONT).map((el) => el.id));
+          if (!need.size) return;
+          const fixed = restoreElements(
+            all.map((el) => (need.has(el.id) ? { ...el, fontFamily: SYSTEM_FONT } : el)),
+            null,
+            { refreshDimensions: true, repairBindings: true },
+          ).map((el) => (need.has(el.id) ? { ...el, version: el.version + 1, versionNonce: Math.floor(Math.random() * 2 ** 31) } : el));
+          a.updateScene({ elements: fixed, captureUpdate: CaptureUpdateAction.NEVER });
+        }, 0);
+      }
+    },
+    [schedule],
+  );
+
+  const handleScroll = useCallback(
+    (scrollX, scrollY, zoom) => {
+      const root = rootRef.current;
+      if (!root) return;
+      let gap = 24 * zoom.value;
+      while (gap < 10) gap *= 4;
+      root.style.setProperty("--sketch-dot-gap", `${gap}px`);
+      root.style.setProperty("--sketch-dot-x", `${(scrollX * zoom.value) % gap}px`);
+      root.style.setProperty("--sketch-dot-y", `${(scrollY * zoom.value) % gap}px`);
+    },
+    [rootRef],
+  );
+
+  // Pasted Excalidraw content keeps its own fonts: into the system font
+  // before it lands (no font is ever fetched from a CDN).
+  const handlePaste = useCallback((data) => {
+    for (const el of data?.elements ?? []) if (el?.type === "text") el.fontFamily = SYSTEM_FONT;
+    return true;
+  }, []);
+
+  // ---- the handle ---------------------------------------------------------
+
+  const viewCentre = useCallback(() => {
+    const st = apiRef.current.getAppState();
+    return viewportCoordsToSceneCoords({ clientX: st.offsetLeft + st.width / 2, clientY: st.offsetTop + st.height / 2 }, st);
+  }, []);
+
+  const insertElements = useCallback(
+    (skeletons, opts = {}) => {
+      const a = apiRef.current;
+      if (!a || !Array.isArray(skeletons) || !skeletons.length) return [];
+      const pal = paletteRef.current;
+      let sks = skeletons.map((sk) => prepareSkeleton(sk, pal));
+      if (opts.at !== false) {
+        const b = boundsOfSkeletons(sks);
+        const at = opts.at && typeof opts.at === "object" ? opts.at : null;
+        const c = at ? { x: at.x, y: at.y } : (() => { const v = viewCentre(); return { x: v.x, y: v.y }; })();
+        const dx = (opts.anchor === "top-left" && at ? c.x : c.x - b.width / 2) - b.x;
+        const dy = (opts.anchor === "top-left" && at ? c.y : c.y - b.height / 2) - b.y;
+        sks = sks.map((sk) => ({ ...sk, x: (sk.x ?? 0) + dx, y: (sk.y ?? 0) + dy }));
+      }
+      let els = convertToExcalidrawElements(sks, { regenerateIds: true });
+      const gid = opts.group || opts.stamp ? `g${Math.random().toString(36).slice(2, 10)}` : null;
+      els = els.map((el) => ({
+        ...el,
+        groupIds: gid ? [...(el.groupIds ?? []), gid] : el.groupIds,
+        customData: { ...(el.customData ?? {}), ...(opts.customData ?? {}), ...(opts.stamp ? { stamp: opts.stamp, stampId: gid } : {}) },
+      }));
+      if (opts.files?.length) a.addFiles(opts.files);
+      const select = opts.select !== false;
+      a.updateScene({
+        elements: [...a.getSceneElementsIncludingDeleted(), ...els],
+        appState: select ? { selectedElementIds: Object.fromEntries(els.filter((e) => !e.containerId).map((e) => [e.id, true])), selectedGroupIds: gid ? { [gid]: true } : {} } : undefined,
+        captureUpdate: CaptureUpdateAction.IMMEDIATELY,
+      });
+      return els.map((e) => e.id);
+    },
+    [viewCentre],
+  );
+
+  const exportImage = useCallback(async (opts = {}) => {
+    const a = apiRef.current;
+    if (!a) throw new Error("The canvas is not ready yet.");
+    const st = a.getAppState();
+    const all = a.getSceneElements();
+    const els = opts.onlySelected ? all.filter((el) => st.selectedElementIds[el.id]) : opts.withBackground === false ? all.filter((el) => !isBackground(el)) : all;
+    const scale = opts.scale ?? 2;
+    return exportToBlob({
+      elements: els,
+      files: a.getFiles(),
+      mimeType: "image/png",
+      exportPadding: opts.padding ?? 16,
+      appState: { ...st, exportBackground: opts.transparent !== true, viewBackgroundColor: paletteRef.current.background ?? "transparent", exportWithDarkMode: false, exportScale: scale },
+      getDimensions: (w, h) => ({ width: w * scale, height: h * scale, scale }),
+    });
+  }, []);
+
+  const handle = useMemo(() => {
+    if (!api) return null;
+    return {
+      api,
+      getScene: (opts = {}) => {
+        const v = sceneValue(api, paletteRef.current);
+        if (!opts.withBackground) return v;
+        const bg = api.getSceneElements().filter(isBackground);
+        return { ...v, elements: [...bg, ...v.elements], files: { ...v.files, ...filesFor(bg, api.getFiles()) } };
+      },
+      setScene: (v) => {
+        const s = toSketch(v);
+        const bg = api.getSceneElementsIncludingDeleted().filter(isBackground);
+        if (Object.keys(s.files).length) api.addFiles(Object.values(s.files));
+        api.updateScene({ elements: [...bg, ...prepareElements(s.elements, paletteRef.current)], captureUpdate: CaptureUpdateAction.IMMEDIATELY });
+      },
+      insertElements,
+      exportImage,
+      zoomToFit: (opts = {}) => api.scrollToContent(undefined, { fitToContent: true, animate: opts.animate !== false }),
+      setTool: (id) => {
+        const s = stampList.find((x) => x.id === id);
+        if (s) return setStamp(s);
+        const t = SKETCH_TOOLS.find((x) => x.id === id || x.tool === id);
+        setStamp(null);
+        if (t) api.setActiveTool({ type: t.tool });
+      },
+      clear: () => {
+        const bg = api.getSceneElementsIncludingDeleted().filter(isBackground);
+        api.updateScene({ elements: bg, captureUpdate: CaptureUpdateAction.IMMEDIATELY });
+      },
+      undo: () => press("z", "KeyZ", { cmd: true }),
+      redo: () => press("z", "KeyZ", { cmd: true, shift: true }),
+      focus: () => rootRef.current?.querySelector(".excalidraw")?.focus(),
+      palette: () => paletteRef.current,
+      repaint: refresh,
+      save: emit,
+    };
+  }, [api, insertElements, exportImage, stampList, press, rootRef, refresh, emit]);
+
+  useEffect(() => {
+    if (!canvasRef || !handle) return;
+    canvasRef.current = handle;
+    return () => {
+      if (canvasRef.current === handle) canvasRef.current = null;
+    };
+  }, [canvasRef, handle]);
+  useEffect(() => {
+    if (handle) cbs.current.onReady?.(handle);
+  }, [handle]);
+
+  // Open fitted: initialData's scrollToContent only centres the scene, so
+  // a board larger than the frame opened on its top-left corner at 100%.
+  // Fit once the canvas has its size; never zoom in past 100%.
+  useEffect(() => {
+    if (!api || !ready) return;
+    const t = setTimeout(() => {
+      const live = api.getSceneElements().filter((el) => !el.isDeleted);
+      if (!live.length) return;
+      api.scrollToContent(live, { fitToViewport: true, viewportZoomFactor: 0.9, maxZoom: 1, animate: false });
+    }, 150);
+    return () => clearTimeout(t);
+  }, [api, ready]);
+
+  // ---- our controls -------------------------------------------------------
+
+  const pickTool = (t) => {
+    setStamp(null);
+    apiRef.current?.setActiveTool({ type: t.tool });
+  };
+
+  const placeStamp = (s, at) => {
+    insertElements(s.create(), { stamp: s.id, at });
+    setStamp(null);
+    apiRef.current?.setActiveTool({ type: "selection" });
+  };
+
+  const selectedEls = () => {
+    const a = apiRef.current;
+    if (!a) return [];
+    const ids = a.getAppState().selectedElementIds;
+    return a.getSceneElements().filter((el) => ids[el.id]);
+  };
+
+  const setColour = (prop, token) => {
+    const a = apiRef.current;
+    const pal = paletteRef.current;
+    if (!a || !(token in pal)) return;
+    const sel = selectedEls();
+    const ids = new Set(sel.map((el) => el.id));
+    if (prop === "strokeColor") for (const el of sel) for (const b of el.boundElements ?? []) if (b.type === "text") ids.add(b.id);
+    const all = a.getSceneElementsIncludingDeleted();
+    a.updateScene({
+      elements: all.map((el) =>
+        ids.has(el.id) ? newElementWith(el, { [prop]: pal[token], customData: { ...(el.customData ?? {}), tokens: { ...(el.customData?.tokens ?? {}), [prop]: token } } }) : el,
+      ),
+      appState: prop === "strokeColor" ? { currentItemStrokeColor: pal[token] } : { currentItemBackgroundColor: pal[token] },
+      captureUpdate: CaptureUpdateAction.IMMEDIATELY,
+    });
+    current.current = { ...current.current, [prop]: token };
+  };
+
+  const setProp = (patch, only) => {
+    const a = apiRef.current;
+    if (!a) return;
+    const ids = new Set(selectedEls().filter(only ?? (() => true)).map((el) => el.id));
+    a.updateScene({ elements: a.getSceneElementsIncludingDeleted().map((el) => (ids.has(el.id) ? newElementWith(el, patch) : el)), captureUpdate: CaptureUpdateAction.IMMEDIATELY });
+  };
+
+  const download = async () => {
+    try {
+      const blob = await exportImage();
+      const url = URL.createObjectURL(blob);
+      const link = document.createElement("a");
+      link.href = url;
+      link.download = "sketch.png";
+      link.click();
+      setTimeout(() => URL.revokeObjectURL(url), 1000);
+    } catch {
+      setSave((s) => ({ ...s, exportError: true }));
+    }
+  };
+
+  // Keys on their way into the canvas: tools left out, the stamp being
+  // placed, Cmd/Ctrl+S.
+  const keyDown = (e) => {
+    const t = e.target;
+    if (t?.tagName === "TEXTAREA" || t?.tagName === "INPUT" || t?.isContentEditable) return;
+    const k = e.key?.toLowerCase();
+    if ((e.metaKey || e.ctrlKey) && k === "s") {
+      e.preventDefault();
+      e.stopPropagation();
+      if (!readOnly) emit();
+      return;
+    }
+    if ((e.metaKey || e.ctrlKey) && k === "f") {
+      e.stopPropagation(); // the browser's find, not Excalidraw's (hidden) search
+      return;
+    }
+    if (stamp) {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        e.stopPropagation();
+        setStamp(null);
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+        e.stopPropagation();
+        placeStamp(stamp);
+      }
+      return;
+    }
+    if (!e.metaKey && !e.ctrlKey && !e.altKey && blockedKeys.has(k)) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+
+  const selected = ui.selected.length ? selectedEls() : [];
+  const kinds = new Set(selected.map((el) => el.type));
+  const hasShape = [...kinds].some((k) => SHAPES.has(k));
+  const hasLine = [...kinds].some((k) => SHAPES.has(k) || LINES.has(k));
+  const hasText = kinds.has("text") || selected.some((el) => (el.boundElements ?? []).some((b) => b.type === "text"));
+  const hasStroke = [...kinds].some((k) => k !== "image" && k !== "frame" && k !== "magicframe");
+  const first = selected[0];
+  const tokens = first ? elementTokens(first, palette) : {};
+  const roughness = first?.roughness ?? 1;
+  const width = first?.strokeWidth ?? 2;
+  const empty_ = ui.count === 0;
+  const showEmpty = empty_ && !readOnly && empty !== false && !stamp && (ui.tool === "selection" || ui.tool === "hand");
+
+  return (
+    // raw: a plain box that hears keys on their way into Excalidraw (capture),
+    // to swallow the shortcuts of tools left out; no control of its own.
+    <div
+      className="absolute inset-0"
+      onKeyDownCapture={keyDown}
+      style={{ "--sketch-selection": palette.primary ?? "currentColor" }}
+    >
+      {grid ? (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 [background-image:radial-gradient(var(--color-border)_1.2px,transparent_1.3px)] [background-size:var(--sketch-dot-gap,24px)_var(--sketch-dot-gap,24px)] [background-position:var(--sketch-dot-x,0)_var(--sketch-dot-y,0)]"
+        />
+      ) : null}
+      <div className="absolute inset-0">
+        <Excalidraw
+          excalidrawAPI={(a) => {
+            apiRef.current = a;
+            setApi(a);
+          }}
+          initialData={initialData}
+          onChange={handleChange}
+          onScrollChange={handleScroll}
+          onPaste={handlePaste}
+          theme={scheme}
+          viewModeEnabled={readOnly}
+          aiEnabled={false}
+          detectScroll
+          handleKeyboardGlobally={false}
+          UIOptions={{
+            canvasActions: {
+              changeViewBackgroundColor: false,
+              clearCanvas: false,
+              export: false,
+              loadScene: false,
+              saveToActiveFile: false,
+              toggleTheme: false,
+              saveAsImage: false,
+            },
+            tools: { image: activeTools.some((t) => t.id === "image") },
+          }}
+          renderTopRightUI={() => null}
+        />
+      </div>
+
+      {showEmpty ? (
+        <div className="pointer-events-none absolute inset-0 z-10 grid place-items-center p-6">
+          {empty ?? (
+            <div className="flex max-w-xs flex-col items-center gap-2 text-center">
+              <span className="grid size-12 place-items-center rounded-full bg-muted text-muted-foreground">
+                <Icon name="pencil" size={22} />
+              </span>
+              <p className="text-base font-medium">Start sketching</p>
+              <p className="text-sm text-muted-foreground">
+                Pick a tool, or press <Kbd>P</Kbd> to draw, <Kbd>R</Kbd> for a box, <Kbd>T</Kbd> for text.
+              </p>
+            </div>
+          )}
+        </div>
+      ) : null}
+
+      {stamp ? (
+        <>
+          {/* raw: a click target laid over the canvas while a stamp waits to
+              land — the pointer picks the spot; Enter drops it in the middle. */}
+          <div
+            aria-hidden="true"
+            className="absolute inset-0 z-10 cursor-crosshair"
+            onPointerDown={(e) => {
+              e.preventDefault();
+              const st = apiRef.current?.getAppState();
+              if (!st) return;
+              placeStamp(stamp, viewportCoordsToSceneCoords({ clientX: e.clientX, clientY: e.clientY }, st));
+            }}
+          />
+          <div className="pointer-events-none absolute inset-x-0 top-3 z-20 flex justify-center px-3">
+            <p role="status" className="rounded-full border border-border bg-popover px-3 py-1 text-xs text-popover-foreground shadow-sm">
+              Click to place the {stamp.label.toLowerCase()} · Enter for the middle · Esc to cancel
+            </p>
+          </div>
+        </>
+      ) : null}
+
+      {!readOnly ? (
+        <Rail tools={activeTools} stamps={stampList} tool={ui.tool} stamp={stamp} onTool={pickTool} onStamp={(s) => setStamp((cur) => (cur?.id === s.id ? null : s))} />
+      ) : null}
+
+      {!readOnly && ui.box && selected.length ? (
+        <ContextBar
+          box={ui.box}
+          tokens={tokens}
+          hasShape={hasShape}
+          hasLine={hasLine}
+          hasText={hasText}
+          hasStroke={hasStroke}
+          roughness={roughness}
+          width={width}
+          onColour={setColour}
+          onWidth={(w) => setProp({ strokeWidth: w }, (el) => el.type !== "text")}
+          onRough={(r) => setProp({ roughness: r }, (el) => el.type !== "text")}
+          onFont={(bigger) => press(bigger ? ">" : "<", bigger ? "Period" : "Comma", { cmd: true, shift: true })}
+          onLayer={layer}
+          onDuplicate={() => press("d", "KeyD", { cmd: true })}
+          onDelete={() => press("Delete", "Delete")}
+        />
+      ) : null}
+
+      {/* top right: the host's actions, the save state, the menu */}
+      <div className="absolute right-3 top-3 z-20 flex items-center gap-2">
+        {onSave && !readOnly ? <SaveState save={save} onRetry={() => runSave(lastValue.current)} /> : null}
+        {actions}
+        <div className="rounded-lg border border-border bg-popover shadow-sm">
+          <Menu
+            label="Canvas menu"
+            size="sm"
+            items={[
+              { label: "Download PNG", icon: "download", onSelect: download },
+              !readOnly && { type: "checkbox", label: "Snap to grid", checked: ui.grid, onCheckedChange: (on) => apiRef.current?.updateScene({ appState: { gridModeEnabled: on } }) },
+              { label: "Fit to screen", icon: "maximize", shortcut: "⇧1", onSelect: () => handle?.zoomToFit() },
+              { label: "Keyboard shortcuts", icon: "keyboard", shortcut: "?", onSelect: () => apiRef.current?.updateScene({ appState: { openDialog: { name: "help" } } }) },
+              !readOnly && { type: "separator" },
+              !readOnly && { label: "Clear canvas", icon: "trash", tone: "danger", disabled: empty_, onSelect: () => setClearing(true) },
+            ]}
+          />
+        </div>
+      </div>
+
+      {/* bottom left: undo, redo */}
+      {!readOnly ? (
+        <div className="absolute bottom-3 left-3 z-20 flex items-center gap-0.5 rounded-lg border border-border bg-popover p-0.5 shadow-sm max-md:bottom-[4.25rem]">
+          <Tooltip label={`Undo — ${isDarwin() ? "⌘Z" : "Ctrl+Z"}`}>
+            <IconButton icon="undo" label="Undo" size="sm" onClick={() => handle?.undo()} />
+          </Tooltip>
+          <Tooltip label={`Redo — ${isDarwin() ? "⇧⌘Z" : "Ctrl+Shift+Z"}`}>
+            <IconButton icon="redo" label="Redo" size="sm" onClick={() => handle?.redo()} />
+          </Tooltip>
+        </div>
+      ) : null}
+
+      {/* bottom right: zoom */}
+      <div className="absolute bottom-3 right-3 z-20 flex items-center gap-0.5 rounded-lg border border-border bg-popover p-0.5 shadow-sm max-md:bottom-[4.25rem]">
+        <Tooltip label="Zoom out">
+          <IconButton icon="minus" label="Zoom out" size="sm" onClick={() => press("-", "Minus", { cmd: true })} />
+        </Tooltip>
+        <Tooltip label="Reset to 100%">
+          <Button variant="quiet" size="sm" className="min-w-14 tabular-nums" onClick={() => press("0", "Digit0", { cmd: true })} aria-label={`Zoom ${Math.round(ui.zoom * 100)}%, reset to 100%`}>
+            {Math.round(ui.zoom * 100)}%
+          </Button>
+        </Tooltip>
+        <Tooltip label="Zoom in">
+          <IconButton icon="plus" label="Zoom in" size="sm" onClick={() => press("=", "Equal", { cmd: true })} />
+        </Tooltip>
+        <Tooltip label="Fit to screen — ⇧1">
+          <IconButton icon="maximize" label="Fit to screen" size="sm" onClick={() => handle?.zoomToFit()} />
+        </Tooltip>
+      </div>
+
+      <Confirm
+        open={clearing}
+        onClose={() => setClearing(false)}
+        onConfirm={() => {
+          handle?.clear();
+          setClearing(false);
+        }}
+        title="Clear the canvas?"
+        body="Everything drawn here is removed. Undo brings it back."
+        confirmLabel="Clear"
+        tone="danger"
+      />
+    </div>
+  );
+}
+
+/** The tool rail: a vertical pill on the left; a bottom bar on a phone. */
+function Rail({ tools, stamps, tool, stamp, onTool, onStamp }) {
+  return (
+    <div
+      role="toolbar"
+      aria-label="Tools"
+      className={cx(
+        "absolute z-20 flex gap-0.5 rounded-xl border border-border bg-popover p-1 shadow-lg",
+        "bottom-3 left-1/2 max-w-[calc(100%-1.5rem)] -translate-x-1/2 flex-row overflow-x-auto",
+        "md:bottom-auto md:left-3 md:top-1/2 md:max-h-[calc(100%-1.5rem)] md:max-w-none md:-translate-x-0 md:-translate-y-1/2 md:flex-col md:overflow-y-auto md:overflow-x-visible",
+      )}
+    >
+      {tools.map((t) => (
+        <Tooltip key={t.id} label={t.key ? `${t.label} — ${t.key}` : t.label} side="right">
+          <Toggle variant="quiet" size="sm" icon={t.icon} label={t.label} pressed={!stamp && tool === t.tool} onPressedChange={() => onTool(t)} aria-keyshortcuts={t.key ?? undefined} />
+        </Tooltip>
+      ))}
+      {stamps.length ? (
+        <>
+          <span aria-hidden="true" className="mx-0.5 w-px shrink-0 self-stretch bg-border md:mx-0.5 md:my-0.5 md:h-px md:w-auto" />
+          {stamps.map((s) => (
+            <Tooltip key={s.id} label={`${s.label} — click the canvas to place`} side="right">
+              <Toggle variant="quiet" size="sm" icon={s.icon ?? "plus"} label={s.label} pressed={stamp?.id === s.id} onPressedChange={() => onStamp(s)} />
+            </Tooltip>
+          ))}
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+/** The floating toolbar above a selection: colours from the theme, stroke,
+ *  text size, order, duplicate, delete. */
+function ContextBar({ box, tokens, hasShape, hasLine, hasText, hasStroke, roughness, width, onColour, onWidth, onRough, onFont, onLayer, onDuplicate, onDelete }) {
+  const above = box.y > 64;
+  const left = Math.max(8, Math.min(box.vw - 8, box.x + box.w / 2));
+  const top = above ? box.y - 10 : Math.min(box.vh - 56, box.y + box.h + 10);
+  return (
+    <div
+      role="toolbar"
+      aria-label="Selection"
+      className={cx(
+        "absolute z-20 flex max-w-[calc(100%-1rem)] items-center gap-0.5 overflow-x-auto rounded-lg border border-border bg-popover p-0.5 text-popover-foreground shadow-lg",
+        "-translate-x-1/2 transition-opacity duration-150 motion-reduce:transition-none",
+        above && "-translate-y-full",
+      )}
+      style={{ left, top }}
+    >
+      {hasStroke ? <Swatches label="Colour" prop="strokeColor" list={STROKES} value={tokens.strokeColor} ring onPick={onColour} /> : null}
+      {hasShape ? <Swatches label="Fill" prop="backgroundColor" list={FILLS} value={tokens.backgroundColor} onPick={onColour} /> : null}
+      {hasLine ? (
+        <>
+          <Separator orientation="vertical" className="my-1" />
+          <Popover
+            label="Stroke"
+            variant="quiet"
+            size="sm"
+            width="auto"
+            className="p-2"
+            trigger={
+              <span className="inline-flex items-center gap-1" aria-label="Stroke">
+                <Icon name="minus" size={16} />
+              </span>
+            }
+          >
+            <div className="flex flex-col gap-2">
+              <div className="flex gap-1" role="group" aria-label="Stroke width">
+                {WIDTHS.map((w) => (
+                  <Toggle key={w.value} size="sm" pressed={width === w.value} onPressedChange={() => onWidth(w.value)}>
+                    {w.label}
+                  </Toggle>
+                ))}
+              </div>
+              <div className="flex gap-1" role="group" aria-label="Line style">
+                <Toggle size="sm" pressed={roughness === 0} onPressedChange={() => onRough(0)}>
+                  Clean
+                </Toggle>
+                <Toggle size="sm" pressed={roughness > 0} onPressedChange={() => onRough(1)}>
+                  Sketchy
+                </Toggle>
+              </div>
+            </div>
+          </Popover>
+        </>
+      ) : null}
+      {hasText ? (
+        <>
+          <Separator orientation="vertical" className="my-1" />
+          <Tooltip label="Smaller text">
+            <IconButton icon="minus" label="Smaller text" size="sm" onClick={() => onFont(false)} />
+          </Tooltip>
+          <Icon name="type" size={16} className="text-muted-foreground" />
+          <Tooltip label="Larger text">
+            <IconButton icon="plus" label="Larger text" size="sm" onClick={() => onFont(true)} />
+          </Tooltip>
+        </>
+      ) : null}
+      <Separator orientation="vertical" className="my-1" />
+      <Tooltip label="Bring to front">
+        <IconButton icon="bring-front" label="Bring to front" size="sm" onClick={() => onLayer(true)} />
+      </Tooltip>
+      <Tooltip label="Send to back">
+        <IconButton icon="send-back" label="Send to back" size="sm" onClick={() => onLayer(false)} />
+      </Tooltip>
+      <Tooltip label="Duplicate">
+        <IconButton icon="copy" label="Duplicate" size="sm" onClick={onDuplicate} />
+      </Tooltip>
+      <Tooltip label="Delete">
+        <IconButton icon="trash" label="Delete" size="sm" onClick={onDelete} />
+      </Tooltip>
+    </div>
+  );
+}
+
+function Swatches({ label, prop, list, value, ring, onPick }) {
+  const cur = list.find((s) => s.token === value);
+  return (
+    <Popover
+      label={label}
+      variant="quiet"
+      size="sm"
+      width="auto"
+      className="p-2"
+      trigger={
+        <span className="inline-flex items-center" aria-label={`${label}: ${cur?.label ?? "custom"}`}>
+          <span className={cx("inline-block size-5 rounded-full border border-border", ring && "ring-2 ring-inset ring-background", SWATCH[value] ?? "bg-muted")} />
+        </span>
+      }
+    >
+      <div className="grid grid-cols-6 gap-1" role="group" aria-label={label}>
+        {list.map((s) => (
+          <Tooltip key={s.token} label={s.label}>
+            <Button variant="quiet" size="sm" iconOnly aria-label={s.label} aria-pressed={value === s.token} className="aria-pressed:bg-accent" onClick={() => onPick(prop, s.token)}>
+              <span className={cx("grid size-6 place-items-center rounded-full border border-border", SWATCH[s.token])}>
+                {s.token === "none" ? <Icon name="x" size={14} className="text-muted-foreground" /> : null}
+              </span>
+            </Button>
+          </Tooltip>
+        ))}
+      </div>
+    </Popover>
+  );
+}
+
+function SaveState({ save, onRetry }) {
+  if (save.state === "idle") return null;
+  if (save.state === "error") {
+    return (
+      <div role="alert" className="flex items-center gap-1 rounded-lg border border-border bg-popover py-0.5 pl-2.5 pr-0.5 text-xs shadow-sm">
+        <Icon name="warning" size={14} className="text-destructive" />
+        <span>{save.error || "Couldn't save"}</span>
+        <Button variant="quiet" size="sm" onClick={onRetry}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+  return (
+    <p role="status" className="rounded-lg border border-border bg-popover px-2.5 py-1.5 text-xs text-muted-foreground shadow-sm">
+      {save.state === "saving" ? "Saving…" : "Saved"}
+    </p>
+  );
+}