@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/markup-editor.tsx

@@ -0,0 +1,1333 @@
+import {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ChangeEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import * as Icon from "./icons.js";
+import {
+  DEFAULT_HIGHLIGHT,
+  DEFAULT_INK,
+  MARKUP_COLORS,
+  commitHistory,
+  contrastText,
+  createHistory,
+  createMeasure,
+  drawSelection,
+  drawShapes,
+  flattenMarkup,
+  hitTest,
+  isMeaningful,
+  loadImage,
+  markupFont,
+  markupMetrics,
+  moveShape,
+  normalizeBox,
+  redoHistory,
+  shapeBounds,
+  snapAngle,
+  textLayout,
+  undoHistory,
+  type MarkupHistory,
+  type MarkupShape,
+  type MarkupSize,
+  type MarkupTool,
+  type MeasureText,
+  type Point,
+  type TextShape,
+} from "./markup.js";
+
+export type MarkupResult =
+  | {
+      /** The image with the markup flattened in. */
+      blob: Blob;
+      /** File name for `blob` (`flattenedName` of the original). */
+      name: string;
+      /** The shapes, kept so the image can be marked up again from the original. */
+      shapes: MarkupShape[];
+    }
+  /** Every shape was removed: the attachment goes back to the original file. */
+  | { blob: null; name: string; shapes: [] };
+
+/** What an inline editor's owner can ask of it (see `MarkupEditorProps.mode`). */
+export type MarkupEditorHandle = {
+  /**
+   * Flattens what has been drawn since the editor opened or last saved. Resolves null when nothing changed, and
+   * rejects when the image can't be flattened (the reason is shown in the editor).
+   */
+  save(): Promise<MarkupResult | null>;
+};
+
+export type MarkupEditorProps = {
+  /**
+   * `dialog` (default): a header with Cancel and Done; Done hands the result over once and the owner closes the
+   * editor. `inline`: no header, the editor stays open after a save, its owner saves through `ref` (`save`) and
+   * Cmd+Enter calls `onSubmit`. Escape with nothing drawn still calls `onCancel`.
+   */
+  mode?: "dialog" | "inline";
+  /** Inline mode's handle on the editor (`save`), for an owner that flattens on its own schedule. */
+  handle?: Ref<MarkupEditorHandle>;
+  /** URL of the original, unmarked image (a blob: URL from the draft tray). */
+  src: string;
+  /** The original's file name, shown in the header and used to name the result. */
+  name: string;
+  /** Shapes from an earlier markup of this image; the editor starts with them so they stay editable. */
+  shapes: MarkupShape[];
+  /** Largest file the result may be (the upload limit). */
+  maxBytes: number;
+  /** Leaves without changing the attachment. */
+  onCancel: () => void;
+  /** Called once with the flattened image. The editor stays mounted until the parent closes it. */
+  onSave: (result: MarkupResult) => void;
+  /** Inline mode's Cmd+Enter: the result of saving first (null when nothing changed), then the owner's turn. */
+  onSubmit?: (result: MarkupResult | null) => void;
+  /** Every change to the shapes, as they stand, so the owner can keep them somewhere safe. */
+  onChange?: (shapes: MarkupShape[]) => void;
+  /** Inline mode's ribbon draws its own groups; the owner's groups (captures, narration) go after them. */
+  ribbon?: ReactNode;
+};
+
+const ZOOM_STEP = 1.25;
+const ZOOM_MIN = 0.5;
+const ZOOM_MAX = 6;
+
+/**
+ * `.cs-markup-stage` pads 9px a side and 6px at the bottom, kept inside its box by `box-sizing: border-box`. The
+ * frame fits inside what is left, so a wide image never slides under the padding.
+ */
+const PAD_X = 18;
+const PAD_Y = 6;
+/** How far off a line a press still counts as a hit, in screen px. */
+const HIT_SLOP = 6;
+/** Below this many screen px a shape is a stray tap, not a drawing. */
+const TAP_SIZE = 4;
+const MAX_STROKE_POINTS = 4000;
+
+const SIZE_ORDER: MarkupSize[] = ["s", "m", "l"];
+const SIZE_LABELS: Record<MarkupSize, string> = { s: "Small", m: "Medium", l: "Large" };
+const TOOL_KEYS: Record<string, MarkupTool> = {
+  v: "select",
+  p: "pen",
+  h: "highlight",
+  a: "arrow",
+  r: "rect",
+  o: "ellipse",
+  t: "text",
+};
+const TOOLS: Array<{ tool: MarkupTool; label: string; icon: ReactNode }> = [
+  { tool: "select", label: "Select", icon: <Icon.Cursor /> },
+  { tool: "pen", label: "Pen", icon: <Icon.Pencil size={12} /> },
+  { tool: "highlight", label: "Highlighter", icon: <Icon.Highlighter /> },
+  { tool: "arrow", label: "Arrow", icon: <Icon.ArrowTool /> },
+  { tool: "rect", label: "Rectangle", icon: <Icon.Square /> },
+  { tool: "ellipse", label: "Ellipse", icon: <Icon.Circle /> },
+  { tool: "text", label: "Text", icon: <Icon.TextTool /> },
+];
+
+type DrawTool = "pen" | "highlight" | "arrow" | "rect" | "ellipse";
+type Status = "loading" | "ready" | "failed";
+type Editing = { seq: number; shape: TextShape | null; at: Point; value: string };
+
+/** A stroke in flight: the points so far plus the newest cursor position and the Shift state there. */
+type Stroke = {
+  mode: "draw";
+  pointerId: number;
+  tool: DrawTool;
+  id: string;
+  color: string;
+  size: MarkupSize;
+  start: Point;
+  points: Point[];
+  point: Point;
+  shift: boolean;
+};
+
+/** A selected shape being dragged. `origin` is where the press found it, so each move is one exact offset. */
+type Slide = {
+  mode: "move";
+  pointerId: number;
+  start: Point;
+  origin: MarkupShape;
+  shape: MarkupShape;
+  moved: boolean;
+};
+
+type Drag = Stroke | Slide;
+
+function nextId() {
+  const unique = globalThis.crypto?.randomUUID;
+  if (typeof unique === "function") return unique.call(globalThis.crypto);
+  return `m-${String(Math.random()).slice(2)}`;
+}
+
+function clamp(value: number, min: number, max: number) {
+  if (!Number.isFinite(value)) return min;
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Text for a shape list that ignores key order, so a re-serialised copy still reads as unchanged. */
+function fingerprint(shapes: MarkupShape[]) {
+  return JSON.stringify(shapes, (_key, value: unknown) =>
+    value && typeof value === "object" && !Array.isArray(value)
+      ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : 1)))
+      : value,
+  );
+}
+
+/** One measuring context for the editor's life; jsdom has none, and `createMeasure` estimates without it. */
+function makeMeasure(): MeasureText {
+  let ctx: CanvasRenderingContext2D | null = null;
+  try {
+    ctx = document.createElement("canvas").getContext("2d");
+  } catch {
+    ctx = null;
+  }
+  return createMeasure(ctx);
+}
+
+/** The shape a stroke would commit as it stands. */
+function strokeShape(stroke: Stroke): MarkupShape {
+  const base = { id: stroke.id, color: stroke.color, size: stroke.size };
+  if (stroke.tool === "pen" || stroke.tool === "highlight") {
+    // Shift turns a highlighter drag into one straight segment from where it started.
+    const straight = stroke.shift && stroke.tool === "highlight";
+    return {
+      ...base,
+      kind: stroke.tool,
+      points: straight ? [stroke.start, stroke.point] : stroke.points,
+    };
+  }
+  if (stroke.tool === "arrow") {
+    const to = stroke.shift ? snapAngle(stroke.start, stroke.point) : stroke.point;
+    return { ...base, kind: "arrow", from: stroke.start, to };
+  }
+  return {
+    ...base,
+    kind: stroke.tool,
+    box: normalizeBox(stroke.start, stroke.point, stroke.shift),
+  };
+}
+
+/** The shape list a finished label produces: added, edited in place, or dropped when emptied. */
+function applyText(
+  shapes: MarkupShape[],
+  edit: Editing,
+  ink: string,
+  size: MarkupSize,
+): MarkupShape[] {
+  const value = edit.value.trim();
+  const existing = edit.shape;
+  if (!existing) {
+    if (!value) return shapes;
+    const label: TextShape = {
+      id: nextId(),
+      kind: "text",
+      at: edit.at,
+      text: value,
+      color: ink,
+      size,
+    };
+    return [...shapes, label];
+  }
+  // An emptied label goes; anything else keeps the shape's id, and the colour and size it has now (a swatch
+  // pressed while typing restyles the shape under the input, not the snapshot taken when it opened).
+  const current = shapes.find((shape) => shape.id === existing.id);
+  if (!current || current.kind !== "text") return shapes;
+  if (!value) return shapes.filter((shape) => shape.id !== existing.id);
+  if (value === current.text) return shapes;
+  return shapes.map((shape) => (shape.id === existing.id ? { ...current, text: value } : shape));
+}
+
+/** Markup mode for an image in the media pane: replaces the pane's header and stage while open. */
+export function MarkupEditor({
+  mode,
+  handle,
+  src,
+  name,
+  shapes: initialShapes,
+  maxBytes,
+  onCancel,
+  onSave,
+  onSubmit,
+  onChange: onChangeProp,
+  ribbon,
+}: MarkupEditorProps) {
+  const root = useRef<HTMLDivElement>(null);
+  const stage = useRef<HTMLDivElement>(null);
+  const frame = useRef<HTMLDivElement>(null);
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const textarea = useRef<HTMLTextAreaElement>(null);
+  const mounted = useRef(true);
+  const submitting = useRef(false);
+  const editingRef = useRef<Editing | null>(null);
+  const editSeq = useRef(0);
+  const drag = useRef<Drag | null>(null);
+
+  const inline = mode === "inline";
+  const [stageBox, setStageBox] = useState({ w: 0, h: 0 });
+  /** 1 fits the stage; more shows the picture larger than that, with the stage scrolling. */
+  const [zoom, setZoom] = useState(1);
+  /** Space held: the pointer pans the zoomed stage instead of drawing. */
+  const spaceHeld = useRef(false);
+  const [panning, setPanning] = useState(false);
+  // The shapes the editor opened with (or, inline, last saved); Done and Escape compare against them.
+  const [initial, setInitial] = useState(() => fingerprint(initialShapes));
+  const initialRef = useRef(initial);
+  // Tagged with its source, so a stale load for another src reads as still loading.
+  const [loaded, setLoaded] = useState<
+    { src: string; image: HTMLImageElement } | { src: string; image: null } | null
+  >(null);
+  const image = loaded?.src === src ? loaded.image : null;
+  const status: Status = loaded?.src !== src ? "loading" : loaded.image ? "ready" : "failed";
+  const [history, setHistory] = useState<MarkupHistory>(() => createHistory(initialShapes));
+  // The same list, kept current synchronously: a blur and the click that follows it land in one tick, and the
+  // click's save must already see the label the blur just committed.
+  const historyRef = useRef(history);
+  const [tool, setTool] = useState<MarkupTool>("pen");
+  const [ink, setInk] = useState(DEFAULT_INK);
+  const [highlight, setHighlight] = useState(DEFAULT_HIGHLIGHT);
+  const [size, setSize] = useState<MarkupSize>("m");
+  const [selection, setSelected] = useState<string | null>(null);
+  const [draft, setDraft] = useState<MarkupShape | null>(null);
+  const [sliding, setSliding] = useState<MarkupShape | null>(null);
+  const [editing, setEditing] = useState<Editing | null>(null);
+  const [overShape, setOverShape] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+
+  const onChange = useRef(onChangeProp);
+  useEffect(() => {
+    onChange.current = onChangeProp;
+  });
+  const apply = useCallback((update: (current: MarkupHistory) => MarkupHistory) => {
+    const next = update(historyRef.current);
+    if (next === historyRef.current) return;
+    const changed = next.present !== historyRef.current.present;
+    historyRef.current = next;
+    setHistory(next);
+    if (changed) onChange.current?.(next.present);
+  }, []);
+  const commit = useCallback(
+    (next: MarkupShape[]) => apply((current) => commitHistory(current, next)),
+    [apply],
+  );
+
+  const [measure] = useState(makeMeasure);
+  const natural = useMemo(() => {
+    const w = image?.naturalWidth ?? 0;
+    const h = image?.naturalHeight ?? 0;
+    return w > 0 && h > 0 ? { w, h } : null;
+  }, [image]);
+  const metrics = useMemo(() => markupMetrics(natural?.w ?? 1, natural?.h ?? 1), [natural]);
+  const fitScale = useMemo(() => {
+    if (!natural) return 1;
+    const fit = Math.min((stageBox.w - PAD_X) / natural.w, (stageBox.h - PAD_Y) / natural.h);
+    // An unmeasured stage (jsdom, or a pane that has not laid out yet) shows the image at 1:1.
+    return Number.isFinite(fit) && fit > 0 ? fit : 1;
+  }, [natural, stageBox]);
+  const scale = fitScale * zoom;
+  const zoomTo = useCallback((next: number) => {
+    setZoom(Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, next)));
+  }, []);
+  /** The zoom that shows the picture at one image pixel per screen pixel. */
+  const actualZoom = natural ? 1 / fitScale : 1;
+
+  // ⌘/Ctrl + wheel (a trackpad pinch arrives the same way) zooms the picture, never the page behind.
+  useEffect(() => {
+    const node = stage.current;
+    if (!node || !inline) return;
+    const onWheel = (event: WheelEvent) => {
+      if (!(event.ctrlKey || event.metaKey)) return;
+      event.preventDefault();
+      setZoom((current) =>
+        Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, current * Math.exp(-event.deltaY * 0.004))),
+      );
+    };
+    node.addEventListener("wheel", onWheel, { passive: false });
+    return () => node.removeEventListener("wheel", onWheel);
+  }, [inline]);
+
+  // Space + drag pans the zoomed stage. The press is read at the window (the toolbar's shield stops it before
+  // React), and while Space is down the canvas draws nothing.
+  useEffect(() => {
+    const node = stage.current;
+    if (!node || !inline) return;
+    let pan: { pointerId: number; x: number; y: number; left: number; top: number } | null = null;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.code !== "Space" || !root.current?.contains(document.activeElement)) return;
+      const target = event.target;
+      if (target instanceof HTMLTextAreaElement || target instanceof HTMLInputElement) return;
+      event.preventDefault();
+      const held = event.type === "keydown";
+      if (spaceHeld.current !== held) {
+        spaceHeld.current = held;
+        setPanning(held);
+      }
+    };
+    const onDown = (event: PointerEvent) => {
+      const middle = event.pointerType === "mouse" && event.button === 1;
+      if (!(spaceHeld.current || middle)) return;
+      if (!(event.target instanceof Node) || !node.contains(event.target)) return;
+      event.preventDefault();
+      pan = {
+        pointerId: event.pointerId,
+        x: event.clientX,
+        y: event.clientY,
+        left: node.scrollLeft,
+        top: node.scrollTop,
+      };
+    };
+    const onMove = (event: PointerEvent) => {
+      if (!pan || event.pointerId !== pan.pointerId) return;
+      node.scrollLeft = pan.left - (event.clientX - pan.x);
+      node.scrollTop = pan.top - (event.clientY - pan.y);
+    };
+    const onUp = (event: PointerEvent) => {
+      if (pan && event.pointerId === pan.pointerId) pan = null;
+    };
+    window.addEventListener("keydown", onKey, true);
+    window.addEventListener("keyup", onKey, true);
+    window.addEventListener("pointerdown", onDown, true);
+    window.addEventListener("pointermove", onMove, true);
+    window.addEventListener("pointerup", onUp, true);
+    window.addEventListener("pointercancel", onUp, true);
+    return () => {
+      window.removeEventListener("keydown", onKey, true);
+      window.removeEventListener("keyup", onKey, true);
+      window.removeEventListener("pointerdown", onDown, true);
+      window.removeEventListener("pointermove", onMove, true);
+      window.removeEventListener("pointerup", onUp, true);
+      window.removeEventListener("pointercancel", onUp, true);
+    };
+  }, [inline]);
+
+  const present = history.present;
+  const changed = useMemo(() => fingerprint(present) !== initial, [initial, present]);
+  // A selection undone or deleted out from under the select tool simply stops being one.
+  const selectedShape = useMemo(
+    () => present.find((shape) => shape.id === selection) ?? null,
+    [present, selection],
+  );
+  const selected = selectedShape?.id ?? null;
+  // A label being typed follows its live shape, so a swatch pressed mid-edit shows on it straight away.
+  const editingShape = editing?.shape
+    ? (present.find((shape) => shape.id === editing.shape?.id) ?? editing.shape)
+    : null;
+  // The style buttons show what they would change: the open label, else the selection, else the next shape.
+  const styled = editingShape ?? (tool === "select" ? selectedShape : null);
+  const activeColor = styled ? styled.color : tool === "highlight" ? highlight : ink;
+  const activeSize = styled ? styled.size : size;
+  const failed = status === "failed" || (status === "ready" && !natural);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  // Every shortcut lands on the root, so it takes focus before one can arrive.
+  useEffect(() => {
+    root.current?.focus({ preventScroll: true });
+  }, []);
+
+  useEffect(() => {
+    let stale = false;
+    loadImage(src)
+      .then((decoded) => {
+        if (!stale) setLoaded({ src, image: decoded });
+      })
+      .catch(() => {
+        if (!stale) setLoaded({ src, image: null });
+      });
+    return () => {
+      stale = true;
+    };
+  }, [src]);
+
+  useEffect(() => {
+    const node = stage.current;
+    if (!node) return;
+    const read = () => {
+      const box = node.getBoundingClientRect();
+      const w = Number.isFinite(box.width) ? box.width : 0;
+      const h = Number.isFinite(box.height) ? box.height : 0;
+      setStageBox((current) => (current.w === w && current.h === h ? current : { w, h }));
+    };
+    read();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(read);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, []);
+
+  const drawn = useMemo(() => {
+    // A label being typed is the textarea's to paint, not the canvas's.
+    const hidden = editing?.shape?.id;
+    const base = hidden ? present.filter((shape) => shape.id !== hidden) : present;
+    const preview = sliding
+      ? base.map((shape) => (shape.id === sliding.id ? sliding : shape))
+      : base;
+    return draft ? [...preview, draft] : preview;
+  }, [draft, editing, present, sliding]);
+  const outlined = sliding ?? selectedShape;
+
+  useEffect(() => {
+    // One frame per change keeps a fast stroke from repainting for every coalesced sample.
+    const pending = requestAnimationFrame(() => {
+      const node = canvas.current;
+      if (!node || !natural) return;
+      const ratio = window.devicePixelRatio || 1;
+      const width = Math.max(1, Math.round(natural.w * scale * ratio));
+      const height = Math.max(1, Math.round(natural.h * scale * ratio));
+      if (node.width !== width) node.width = width;
+      if (node.height !== height) node.height = height;
+      const ctx = node.getContext("2d");
+      if (!ctx) return;
+      // The transform carries both the pane's scale and the backing store's pixel ratio, so shapes stay in
+      // image pixels and the file matches what is on screen.
+      ctx.setTransform(1, 0, 0, 1, 0, 0);
+      ctx.clearRect(0, 0, width, height);
+      ctx.setTransform(scale * ratio, 0, 0, scale * ratio, 0, 0);
+      drawShapes(ctx, drawn, metrics);
+      if (outlined) drawSelection(ctx, shapeBounds(outlined, metrics, measure), scale);
+    });
+    return () => cancelAnimationFrame(pending);
+  }, [drawn, measure, metrics, natural, outlined, scale]);
+
+  const startEditor = useCallback((shape: TextShape | null, at: Point, value: string) => {
+    editSeq.current += 1;
+    const next = { seq: editSeq.current, shape, at, value };
+    editingRef.current = next;
+    setEditing(next);
+  }, []);
+
+  const closeEditor = useCallback(
+    (edit: Editing) => {
+      editingRef.current = null;
+      setEditing(null);
+      const next = applyText(historyRef.current.present, edit, ink, size);
+      if (next !== historyRef.current.present) commit(next);
+      root.current?.focus({ preventScroll: true });
+    },
+    [commit, ink, size],
+  );
+
+  const typeText = useCallback((value: string) => {
+    const current = editingRef.current;
+    if (!current) return;
+    const next = { ...current, value };
+    editingRef.current = next;
+    setEditing(next);
+  }, []);
+
+  const commitText = useCallback(() => {
+    const current = editingRef.current;
+    if (current) closeEditor(current);
+  }, [closeEditor]);
+
+  useEffect(() => {
+    const frameNode = frame.current;
+    const canvasNode = canvas.current;
+    if (!natural || !frameNode || !canvasNode) return;
+
+    const toImage = (clientX: number, clientY: number): Point => {
+      const box = frameNode.getBoundingClientRect();
+      return {
+        x: clamp((clientX - box.left) / scale, 0, natural.w),
+        y: clamp((clientY - box.top) / scale, 0, natural.h),
+      };
+    };
+    const coalesced = (event: PointerEvent): PointerEvent[] => {
+      try {
+        return event.getCoalescedEvents?.() ?? [];
+      } catch {
+        return [];
+      }
+    };
+    const find = (id: string | null) =>
+      id ? (historyRef.current.present.find((shape) => shape.id === id) ?? null) : null;
+    const hitAt = (point: Point) =>
+      find(hitTest(historyRef.current.present, point, HIT_SLOP / scale, metrics, measure));
+    // Text presses only ever find labels, so a box drawn over one does not swallow the double-click.
+    const hitLabel = (point: Point) =>
+      find(
+        hitTest(
+          historyRef.current.present.filter((shape) => shape.kind === "text"),
+          point,
+          HIT_SLOP / scale,
+          metrics,
+          measure,
+        ),
+      );
+    // Coalesced samples keep a fast stroke smooth; one nearer than a screen px to the last is dropped.
+    // The list grows in place: the drag owns it, and copying it per sample made long strokes quadratic.
+    const extend = (points: Point[], event: PointerEvent) => {
+      for (const sample of [...coalesced(event), event]) {
+        if (points.length >= MAX_STROKE_POINTS) break;
+        const point = toImage(sample.clientX, sample.clientY);
+        const last = points[points.length - 1]!;
+        if (Math.hypot((point.x - last.x) * scale, (point.y - last.y) * scale) < 1) continue;
+        points.push(point);
+      }
+      return points;
+    };
+
+    const onDown = (event: PointerEvent) => {
+      if (event.target !== canvasNode) return;
+      if (event.pointerType === "mouse" && event.button !== 0) return;
+      if (spaceHeld.current) return;
+      if (status !== "ready" || saving) return;
+      // A second finger or a resting palm must not take over the stroke in flight. The same pointer pressing
+      // again means its release was lost, so that press starts over.
+      if (drag.current && drag.current.pointerId !== event.pointerId) return;
+      if (drag.current) {
+        drag.current = null;
+        setDraft(null);
+        setSliding(null);
+      }
+      // A label being typed only closes here; a press must not open a second one under it.
+      if (editingRef.current) {
+        commitText();
+        return;
+      }
+      const point = toImage(event.clientX, event.clientY);
+      root.current?.focus({ preventScroll: true });
+
+      if (tool === "text") {
+        const label = hitLabel(point);
+        if (label?.kind === "text") startEditor(label, label.at, label.text);
+        else startEditor(null, point, "");
+        return;
+      }
+      if (tool === "select") {
+        const hit = hitAt(point);
+        setSelected(hit?.id ?? null);
+        if (!hit) return;
+        drag.current = {
+          mode: "move",
+          pointerId: event.pointerId,
+          start: point,
+          origin: hit,
+          shape: hit,
+          moved: false,
+        };
+        try {
+          canvasNode.setPointerCapture(event.pointerId);
+        } catch {
+          // jsdom has no pointer capture, and a press can end before capture lands.
+        }
+        return;
+      }
+      drag.current = {
+        mode: "draw",
+        pointerId: event.pointerId,
+        tool,
+        id: nextId(),
+        color: tool === "highlight" ? highlight : ink,
+        size,
+        start: point,
+        points: [point],
+        point,
+        shift: event.shiftKey,
+      };
+      setDraft(strokeShape(drag.current));
+      try {
+        canvasNode.setPointerCapture(event.pointerId);
+      } catch {
+        // jsdom has no pointer capture, and a press can end before capture lands.
+      }
+    };
+
+    const onMove = (event: PointerEvent) => {
+      const current = drag.current;
+      if (!current) {
+        if (tool !== "select") return;
+        setOverShape(
+          event.target === canvasNode && Boolean(hitAt(toImage(event.clientX, event.clientY))),
+        );
+        return;
+      }
+      if (event.pointerId !== current.pointerId) return;
+      const point = toImage(event.clientX, event.clientY);
+      if (current.mode === "move") {
+        const moved = moveShape(
+          current.origin,
+          point.x - current.start.x,
+          point.y - current.start.y,
+        );
+        const far =
+          Math.hypot((point.x - current.start.x) * scale, (point.y - current.start.y) * scale) >= 1;
+        drag.current = { ...current, shape: moved, moved: current.moved || far };
+        setSliding(moved);
+        return;
+      }
+      const points =
+        current.tool === "pen" || current.tool === "highlight"
+          ? extend(current.points, event)
+          : current.points;
+      drag.current = { ...current, points, point, shift: event.shiftKey };
+      setDraft(strokeShape(drag.current));
+    };
+
+    const onUp = (event: PointerEvent) => {
+      const current = drag.current;
+      if (!current || event.pointerId !== current.pointerId) return;
+      drag.current = null;
+      // The release point counts: a fast flick can lift before any move arrives.
+      const point = toImage(event.clientX, event.clientY);
+      if (current.mode === "move") {
+        setSliding(null);
+        const moved = moveShape(
+          current.origin,
+          point.x - current.start.x,
+          point.y - current.start.y,
+        );
+        const far =
+          Math.hypot((point.x - current.start.x) * scale, (point.y - current.start.y) * scale) >= 1;
+        if (!current.moved && !far) return;
+        commit(historyRef.current.present.map((shape) => (shape.id === moved.id ? moved : shape)));
+        return;
+      }
+      setDraft(null);
+      const finished: Stroke = {
+        ...current,
+        points:
+          current.tool === "pen" || current.tool === "highlight"
+            ? extend([...current.points], event)
+            : current.points,
+        // Shift is read while dragging; letting go of it a moment before the button must not change the shape.
+        point,
+      };
+      const shape = strokeShape(finished);
+      // A tap is a slip of the mouse, not a mark worth keeping or an undo step worth spending.
+      if (!isMeaningful(shape, TAP_SIZE / scale)) return;
+      commit([...historyRef.current.present, shape]);
+    };
+
+    const onCancel = (event: PointerEvent) => {
+      const current = drag.current;
+      if (current && event.pointerId !== current.pointerId) return;
+      drag.current = null;
+      setDraft(null);
+      setSliding(null);
+    };
+
+    const onDouble = (event: MouseEvent) => {
+      if (event.target !== canvasNode) return;
+      if (tool !== "select" && tool !== "text") return;
+      const label = hitLabel(toImage(event.clientX, event.clientY));
+      if (label?.kind === "text") startEditor(label, label.at, label.text);
+    };
+
+    window.addEventListener("pointerdown", onDown, true);
+    window.addEventListener("pointermove", onMove, true);
+    window.addEventListener("pointerup", onUp, true);
+    window.addEventListener("pointercancel", onCancel, true);
+    window.addEventListener("dblclick", onDouble, true);
+    return () => {
+      window.removeEventListener("pointerdown", onDown, true);
+      window.removeEventListener("pointermove", onMove, true);
+      window.removeEventListener("pointerup", onUp, true);
+      window.removeEventListener("pointercancel", onCancel, true);
+      window.removeEventListener("dblclick", onDouble, true);
+    };
+  }, [
+    commit,
+    commitText,
+    highlight,
+    ink,
+    measure,
+    metrics,
+    natural,
+    saving,
+    scale,
+    size,
+    startEditor,
+    status,
+    tool,
+  ]);
+
+  const openSeq = editing?.seq ?? 0;
+  useEffect(() => {
+    const node = textarea.current;
+    if (!openSeq || !node) return;
+    node.focus({ preventScroll: true });
+    node.setSelectionRange(node.value.length, node.value.length);
+  }, [openSeq]);
+
+  const editingColor = editingShape?.color ?? ink;
+  const editingSize = editingShape?.size ?? size;
+  const editingFont = metrics.font(editingSize);
+  const layout = editing
+    ? textLayout(
+        {
+          id: "draft",
+          kind: "text",
+          at: editing.at,
+          text: editing.value,
+          color: editingColor,
+          size: editingSize,
+        },
+        metrics,
+        measure,
+      )
+    : null;
+  // The input must look exactly like the label it becomes, drawn at the pane's scale.
+  const textStyle: CSSProperties | null =
+    editing && layout
+      ? {
+          left: editing.at.x * scale,
+          top: editing.at.y * scale,
+          // Room for the caret even before the first character lands.
+          width: Math.max(layout.box.w, editingFont * 1.2) * scale,
+          height: layout.box.h * scale,
+          background: editingColor,
+          color: contrastText(editingColor),
+          font: markupFont(editingFont * scale),
+          lineHeight: 1.25,
+          padding: "0.4em",
+          borderRadius: "0.3em",
+        }
+      : null;
+
+  const restyle = (target: string, patch: { color?: string; size?: MarkupSize }) =>
+    apply((current) => {
+      const shape = current.present.find((candidate) => candidate.id === target);
+      if (!shape) return current;
+      if (patch.color !== undefined && shape.color === patch.color) return current;
+      if (patch.size !== undefined && shape.size === patch.size) return current;
+      return commitHistory(current, [
+        ...current.present.map((candidate) =>
+          candidate.id === target ? { ...candidate, ...patch } : candidate,
+        ),
+      ]);
+    });
+
+  // A selection belongs to the select tool; drawing with another must not recolour or delete it.
+  const chooseTool = (next: MarkupTool) => {
+    setTool(next);
+    if (next !== "select") setSelected(null);
+  };
+
+  // The shape the style buttons act on: the label being typed, else the selection.
+  const styleTarget = () => editingRef.current?.shape?.id ?? selected;
+
+  const applyColor = (color: string) => {
+    if (tool === "highlight") setHighlight(color);
+    else setInk(color);
+    // Recolouring a selected shape takes the clicked colour whatever the active tool is.
+    const target = styleTarget();
+    if (target) restyle(target, { color });
+  };
+
+  const applySize = (next: MarkupSize) => {
+    setSize(next);
+    const target = styleTarget();
+    if (target) restyle(target, { size: next });
+  };
+
+  const removeSelected = () => {
+    const target = selected;
+    if (!target) return;
+    setSelected(null);
+    commit(historyRef.current.present.filter((shape) => shape.id !== target));
+  };
+
+  const nudge = (dx: number, dy: number) => {
+    const target = selected;
+    if (!target) return;
+    apply((current) => {
+      const shape = current.present.find((candidate) => candidate.id === target);
+      if (!shape) return current;
+      return commitHistory(current, [
+        ...current.present.map((candidate) =>
+          candidate.id === target ? moveShape(candidate, dx, dy) : candidate,
+        ),
+      ]);
+    });
+  };
+
+  /** The current shapes with any open label committed, as `done` and `save` read them. */
+  const settledShapes = useCallback(() => {
+    const open = editingRef.current;
+    const shapes = open
+      ? applyText(historyRef.current.present, open, ink, size)
+      : historyRef.current.present;
+    if (open) {
+      editingRef.current = null;
+      setEditing(null);
+      if (shapes !== historyRef.current.present) commit(shapes);
+    }
+    return shapes;
+  }, [commit, ink, size]);
+
+  /**
+   * Starts a save. Settled at once when nothing has to be flattened (nothing changed, or every shape is gone),
+   * so Done and Cancel paths that need no work still answer in the same tick; a flatten comes back as a promise
+   * that rejects when the image can't be flattened (the reason is shown in the editor).
+   */
+  const startSave = useCallback((): MarkupResult | null | Promise<MarkupResult> => {
+    // A second press lands before `saving` renders, so the ref is the guard, not the state.
+    if (submitting.current) return null;
+    submitting.current = true;
+    const shapes = settledShapes();
+    const mark = fingerprint(shapes);
+    const finish = <T extends MarkupResult | null>(result: T): T => {
+      // Inline, the editor stays open: the next save compares against what was just saved.
+      if (inline) {
+        initialRef.current = mark;
+        setInitial(mark);
+        submitting.current = false;
+      }
+      return result;
+    };
+    if (mark === initialRef.current) return finish(null);
+    if (!shapes.length) return finish({ blob: null, name: name, shapes: [] });
+    if (!image || !natural) {
+      submitting.current = false;
+      return null;
+    }
+    setSaving(true);
+    setSaveError(null);
+    return flattenMarkup({
+      image,
+      width: natural.w,
+      height: natural.h,
+      shapes,
+      name: name,
+      maxBytes: maxBytes,
+    }).then(
+      (flat) => {
+        if (!mounted.current) throw new Error("unmounted");
+        if (inline) setSaving(false);
+        return finish({ blob: flat.blob, name: flat.name, shapes });
+      },
+      (caught: unknown) => {
+        if (!mounted.current) throw caught;
+        // Anything but a successful hand-off leaves the editor open with the reason on screen.
+        submitting.current = false;
+        setSaving(false);
+        setSaveError(caught instanceof Error ? caught.message : "Couldn’t save this image.");
+        throw caught;
+      },
+    );
+  }, [image, inline, natural, maxBytes, name, settledShapes]);
+
+  useImperativeHandle(
+    handle,
+    () => ({
+      save: () => {
+        const outcome = startSave();
+        return outcome instanceof Promise ? outcome : Promise.resolve(outcome);
+      },
+    }),
+    [startSave],
+  );
+
+  const done = () => {
+    if (submitting.current) return;
+    const deliver = (result: MarkupResult | null) => {
+      if (inline) {
+        onSubmit?.(result);
+        return;
+      }
+      if (result === null) {
+        onCancel();
+        return;
+      }
+      onSave(result);
+    };
+    const outcome = startSave();
+    if (outcome instanceof Promise) {
+      outcome.then(deliver, () => {});
+      return;
+    }
+    deliver(outcome);
+  };
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    // Nothing typed at the toolbar belongs to the page behind it.
+    event.stopPropagation();
+    // Mid-drag, the release is what commits; undo or Done landing first would lose the shape or the redo steps.
+    if (saving || drag.current) {
+      if (drag.current) event.preventDefault();
+      return;
+    }
+    const command = event.metaKey || event.ctrlKey;
+    const key = event.key;
+    if (command && key === "Enter") {
+      event.preventDefault();
+      done();
+      return;
+    }
+    if (command && (key === "z" || key === "Z")) {
+      event.preventDefault();
+      apply(event.shiftKey ? redoHistory : undoHistory);
+      return;
+    }
+    if (command && (key === "y" || key === "Y")) {
+      event.preventDefault();
+      apply(redoHistory);
+      return;
+    }
+    if (command || event.altKey) return;
+    if (key === "Escape") {
+      if (selected) {
+        event.preventDefault();
+        setSelected(null);
+      } else if (!changed) {
+        // Leaving with nothing drawn is a cancel; leaving with drawings would silently lose them.
+        event.preventDefault();
+        onCancel();
+      }
+      return;
+    }
+    if (key === "Delete" || key === "Backspace") {
+      if (!selected) return;
+      event.preventDefault();
+      removeSelected();
+      return;
+    }
+    if (key.startsWith("Arrow")) {
+      if (!selected) return;
+      event.preventDefault();
+      // Nudges are measured on screen, so they feel the same whatever the image scale.
+      const step = (event.shiftKey ? 10 : 1) / scale;
+      const dx = key === "ArrowLeft" ? -step : key === "ArrowRight" ? step : 0;
+      const dy = key === "ArrowUp" ? -step : key === "ArrowDown" ? step : 0;
+      nudge(dx, dy);
+      return;
+    }
+    if (inline && (key === "+" || key === "=")) {
+      event.preventDefault();
+      zoomTo(zoom * ZOOM_STEP);
+      return;
+    }
+    if (inline && (key === "-" || key === "_")) {
+      event.preventDefault();
+      zoomTo(zoom / ZOOM_STEP);
+      return;
+    }
+    if (inline && key === "0") {
+      event.preventDefault();
+      zoomTo(1);
+      return;
+    }
+    if (event.shiftKey || key.length !== 1) return;
+    const next = TOOL_KEYS[key.toLowerCase()];
+    if (!next) return;
+    event.preventDefault();
+    chooseTool(next);
+  };
+
+  // The same controls in both layouts: the dialog's strip at the bottom, inline the ribbon at the top.
+  const toolButtons = (big: boolean) =>
+    TOOLS.map((entry) => (
+      <button
+        key={entry.tool}
+        type="button"
+        className={big ? "cs-ribbon-big" : "cs-icon-button"}
+        data-cs-ui="markup-tool"
+        data-tool={entry.tool}
+        data-tip={big ? undefined : entry.label}
+        aria-label={entry.label}
+        aria-pressed={tool === entry.tool}
+        onClick={() => chooseTool(entry.tool)}
+      >
+        {entry.icon}
+        {big ? <span>{entry.label}</span> : null}
+      </button>
+    ));
+  const colorButtons = MARKUP_COLORS.map((entry) => (
+    <button
+      key={entry.value}
+      type="button"
+      className="cs-markup-color"
+      data-cs-ui="markup-color"
+      data-color={entry.value}
+      aria-label={entry.name}
+      aria-pressed={activeColor.toLowerCase() === entry.value.toLowerCase()}
+      onClick={() => applyColor(entry.value)}
+    >
+      <span
+        className={entry.value.toLowerCase() === "#ffffff" ? "is-light" : undefined}
+        style={{ background: entry.value }}
+      />
+    </button>
+  ));
+  const sizeButtons = SIZE_ORDER.map((entry) => (
+    <button
+      key={entry}
+      type="button"
+      className="cs-markup-size"
+      data-cs-ui="markup-size"
+      data-size={entry}
+      aria-label={SIZE_LABELS[entry]}
+      aria-pressed={activeSize === entry}
+      onClick={() => applySize(entry)}
+    >
+      <span />
+    </button>
+  ));
+  const undo = () => {
+    if (!drag.current) apply(undoHistory);
+  };
+  const redo = () => {
+    if (!drag.current) apply(redoHistory);
+  };
+  const clearAll = () => commit([]);
+  const historyButtons = (big: boolean) => {
+    const cls = big ? "cs-ribbon-small" : "cs-icon-button";
+    return (
+      <>
+        <button
+          type="button"
+          className={cls}
+          data-cs-ui="markup-undo"
+          data-tip={big ? undefined : "Undo"}
+          aria-label="Undo"
+          disabled={!history.past.length}
+          onClick={undo}
+        >
+          <Icon.Undo />
+          {big ? "Undo" : null}
+        </button>
+        <button
+          type="button"
+          className={cls}
+          data-cs-ui="markup-redo"
+          data-tip={big ? undefined : "Redo"}
+          aria-label="Redo"
+          disabled={!history.future.length}
+          onClick={redo}
+        >
+          <Icon.Redo />
+          {big ? "Redo" : null}
+        </button>
+        <button
+          type="button"
+          className={cls}
+          data-cs-ui="markup-delete"
+          data-tip={big ? undefined : "Delete shape"}
+          aria-label="Delete shape"
+          disabled={!selected}
+          onClick={removeSelected}
+        >
+          <Icon.Trash />
+          {big ? "Delete" : null}
+        </button>
+        <button
+          type="button"
+          className={cls}
+          data-cs-ui="markup-clear"
+          data-tip={big ? undefined : "Clear all"}
+          aria-label="Clear all"
+          disabled={!present.length}
+          onClick={clearAll}
+        >
+          <Icon.Close />
+          {big ? "Clear all" : null}
+        </button>
+      </>
+    );
+  };
+
+  return (
+    <div
+      ref={root}
+      className={`cs-markup${inline ? " is-inline" : ""}`}
+      data-cs-ui="markup"
+      tabIndex={-1}
+      onKeyDown={onKeyDown}
+    >
+      {inline ? null : (
+        <header className="cs-media-bar cs-markup-bar">
+          <span className="cs-media-name" title={name}>
+            {name}
+          </span>
+          <button
+            type="button"
+            className="cs-markup-cancel"
+            data-cs-ui="markup-cancel"
+            onClick={onCancel}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            className="cs-markup-done"
+            data-cs-ui="markup-done"
+            disabled={!natural || saving}
+            onClick={done}
+          >
+            {saving ? "Saving…" : "Done"}
+          </button>
+        </header>
+      )}
+      {inline ? (
+        <div className="cs-ribbon" data-cs-ui="markup-ribbon" role="toolbar" aria-label="Tools">
+          <div className="cs-ribbon-body">
+            <div className="cs-ribbon-group">
+              <div className="cs-ribbon-row">{toolButtons(true)}</div>
+              <div className="cs-ribbon-name">Draw</div>
+            </div>
+            <div className="cs-ribbon-group">
+              <div className="cs-ribbon-row">
+                <div className="cs-ribbon-swatches">{colorButtons}</div>
+                <div className="cs-ribbon-sizes">{sizeButtons}</div>
+              </div>
+              <div className="cs-ribbon-name">Style</div>
+            </div>
+            <div className="cs-ribbon-group">
+              <div className="cs-ribbon-row cs-ribbon-stack">{historyButtons(true)}</div>
+              <div className="cs-ribbon-name">Edit</div>
+            </div>
+            {ribbon}
+          </div>
+        </div>
+      ) : null}
+      <div
+        ref={stage}
+        className={`cs-markup-stage${zoom > 1 ? " is-zoomed" : ""}${panning ? " is-panning" : ""}`}
+      >
+        {natural ? (
+          <div
+            ref={frame}
+            className="cs-markup-frame"
+            style={{ width: natural.w * scale, height: natural.h * scale }}
+          >
+            <img src={src} alt="" draggable={false} />
+            <canvas
+              ref={canvas}
+              className="cs-markup-canvas"
+              data-cs-ui="markup-canvas"
+              data-tool={tool}
+              data-over={overShape || sliding ? "" : undefined}
+            />
+            {editing && textStyle ? (
+              <textarea
+                ref={textarea}
+                className="cs-markup-text"
+                data-cs-ui="markup-text-input"
+                aria-label="Label text"
+                spellCheck={false}
+                wrap="off"
+                value={editing.value}
+                style={textStyle}
+                onChange={(event: ChangeEvent<HTMLTextAreaElement>) => typeText(event.target.value)}
+                onBlur={commitText}
+                onKeyDown={(event) => {
+                  // The page and the toolbar's own shortcuts never see typing in a label.
+                  event.stopPropagation();
+                  if (event.key === "Enter" && !event.shiftKey) {
+                    event.preventDefault();
+                    commitText();
+                    return;
+                  }
+                  if (event.key === "Escape") {
+                    event.preventDefault();
+                    // Backing out of an existing label leaves its text as it was; a new one keeps what was typed.
+                    const open = editingRef.current;
+                    if (open?.shape) {
+                      editingRef.current = null;
+                      setEditing(null);
+                      root.current?.focus({ preventScroll: true });
+                    } else commitText();
+                  }
+                }}
+              />
+            ) : null}
+          </div>
+        ) : failed ? (
+          <p className="cs-markup-status" role="alert" data-cs-ui="markup-error">
+            Couldn’t open this image.
+          </p>
+        ) : (
+          <p className="cs-markup-status">Loading image…</p>
+        )}
+      </div>
+      {inline ? (
+        <div className="cs-markup-statusbar" data-cs-ui="markup-statusbar">
+          <span className="cs-markup-zoom" role="group" aria-label="Zoom">
+            <button
+              type="button"
+              className={zoom === 1 ? "is-on" : undefined}
+              data-cs-ui="markup-zoom-fit"
+              onClick={() => zoomTo(1)}
+            >
+              Fit
+            </button>
+            <button
+              type="button"
+              className={Math.abs(zoom - actualZoom) < 0.01 ? "is-on" : undefined}
+              data-cs-ui="markup-zoom-actual"
+              onClick={() => zoomTo(actualZoom)}
+            >
+              100%
+            </button>
+            <button
+              type="button"
+              aria-label="Zoom out"
+              data-cs-ui="markup-zoom-out"
+              onClick={() => zoomTo(zoom / ZOOM_STEP)}
+            >
+              −
+            </button>
+            <input
+              type="range"
+              aria-label="Zoom"
+              min={Math.round(ZOOM_MIN * 100)}
+              max={Math.round(ZOOM_MAX * 100)}
+              value={Math.round(zoom * 100)}
+              onChange={(event: ChangeEvent<HTMLInputElement>) =>
+                zoomTo(Number(event.target.value) / 100)
+              }
+            />
+            <button
+              type="button"
+              aria-label="Zoom in"
+              data-cs-ui="markup-zoom-in"
+              onClick={() => zoomTo(zoom * ZOOM_STEP)}
+            >
+              +
+            </button>
+            <span className="cs-markup-zoom-level" data-cs-ui="markup-zoom-level">
+              {Math.round(scale * 100)}%
+            </span>
+          </span>
+        </div>
+      ) : (
+        <div className="cs-markup-tools" role="toolbar" aria-label="Markup tools">
+          <div className="cs-markup-group" role="group" aria-label="Tools">
+            {toolButtons(false)}
+          </div>
+          <span className="cs-markup-sep" aria-hidden="true" />
+          <div className="cs-markup-group" role="group" aria-label="Colours">
+            {colorButtons}
+          </div>
+          <span className="cs-markup-sep" aria-hidden="true" />
+          <div className="cs-markup-group" role="group" aria-label="Sizes">
+            {sizeButtons}
+          </div>
+          <span className="cs-markup-sep" aria-hidden="true" />
+          <div className="cs-markup-group" role="group" aria-label="History">
+            {historyButtons(false)}
+          </div>
+        </div>
+      )}
+      {saveError ? (
+        <p className="cs-markup-error" role="alert" data-cs-ui="markup-error">
+          {saveError}
+        </p>
+      ) : null}
+    </div>
+  );
+}