makersclaw 0.1.0 → 0.3.0

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

@@ -0,0 +1,1329 @@
+"use client";
+
+// FlowCanvas — a Miro-like board on React Flow, in the workspace theme,
+// behind one set of props (README.md beside this file).
+//
+// Client only, one static bundle: the modules load with the page (the
+// app's check refuses import()), and the board itself mounts after the
+// first effect (the mount guard). Until then — on the server and in the
+// first client paint — a box of the same size holds the board as text, so
+// the server HTML already says what is on it.
+//
+// State: nodes and edges live here (React Flow's shape). A change that
+// should be undoable COMMITS: a drag ends, a card is placed, words stop
+// being edited, a colour is picked. A commit runs the block's constraints
+// (`constrain`, `beforeChange`), pushes a snapshot onto the history
+// (board.js historyReducer) and schedules one onChange/onSave after
+// `changeDelay` ms. Selection and the view never commit.
+import "@xyflow/react/dist/style.css";
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
+import {
+  Background,
+  BackgroundVariant,
+  ConnectionMode,
+  MiniMap,
+  ReactFlow,
+  ReactFlowProvider,
+  SelectionMode,
+  ViewportPortal,
+  applyEdgeChanges,
+  applyNodeChanges,
+  useConnection,
+  useReactFlow,
+  useStore,
+} from "@xyflow/react";
+import { ContextMenu, cx } from "../../ui";
+import {
+  AUTO_HEIGHT,
+  EDITABLE,
+  GRID,
+  SHAPE_NAMES,
+  STICKY_COLORS,
+  alignNodes,
+  arrangeNodes,
+  autoLayout,
+  boardBounds,
+  boardKey,
+  boardToMarkdown,
+  boardToText,
+  cleanBoard,
+  createEdge,
+  createNode,
+  distributeNodes,
+  duplicateNodes,
+  emptyBoard,
+  facingSides,
+  frameContents,
+  historyInit,
+  historyReducer,
+  makeId,
+  nodeRect,
+  readBoard,
+  sidePoint,
+  starterTemplates,
+} from "./board";
+import { ConnectMenu, EdgeToolbar, EmptyState, FloatAt, HistoryBar, ListView, PresentBar, SelectionToolbar, ShortcutsSheet, ToolFlyout, ToolRail, ZoomBar, modKey } from "./chrome";
+import { CanvasContext } from "./context";
+import { BUILT_IN_EDGES, connectorGeometry } from "./edges";
+import { BUILT_IN_NODES } from "./nodes";
+import { THEME } from "./theme";
+
+/** A ref for the canvas handle: `const board = useFlowCanvas()`, then
+ *  `<FlowCanvas canvasRef={board} />` and `board.current?.fitView()`. */
+export function useFlowCanvas() {
+  return useRef(null);
+}
+
+// The built-in tools. `place` names the node type a click puts down;
+// `sizable` ones can be dragged out to a size.
+const TOOLS = {
+  select: { id: "select", label: "Select", icon: "mouse-pointer", shortcut: "V", kind: "mode" },
+  hand: { id: "hand", label: "Hand", icon: "hand", shortcut: "H", kind: "mode" },
+  sticky: { id: "sticky", label: "Sticky note", icon: "sticky-note", shortcut: "N", kind: "mode", place: "sticky" },
+  shape: { id: "shape", label: "Shape", icon: "square", shortcut: "S", kind: "mode", place: "shape", sizable: true },
+  text: { id: "text", label: "Text", icon: "type", shortcut: "T", kind: "mode", place: "text", sizable: true },
+  connector: { id: "connector", label: "Connector", icon: "connector", shortcut: "L", kind: "mode" },
+  frame: { id: "frame", label: "Frame", icon: "frame", shortcut: "F", kind: "mode", place: "frame", sizable: true },
+  image: { id: "image", label: "Image", icon: "image", shortcut: "I", kind: "action" },
+};
+const SHAPE_ICON = { rect: "square", ellipse: "circle", diamond: "diamond", pill: "minus" };
+const DEFAULT_RAIL = ["select", "hand", "|", "sticky", "shape", "text", "connector", "frame"];
+// Props React Flow compares by identity: made once, not every render.
+const EDGE_DEFAULTS = { type: "flow" };
+const MULTI_KEYS = ["Shift", "Meta", "Control"];
+const MIDDLE_BUTTON = [1];
+const FIT_OPTIONS = { padding: 0.2, maxZoom: 1 };
+const EDITING_TARGET = '[contenteditable="true"],[contenteditable="plaintext-only"],input,textarea,select,[role="menu"],[role="dialog"],[popover]';
+
+/** Anything board-shaped → React Flow's nodes and edges. */
+function prepare(board) {
+  const { nodes, edges } = readBoard(board);
+  return {
+    nodes: nodes.map((n) => ({ ...n, position: { x: Number(n.position?.x) || 0, y: Number(n.position?.y) || 0 }, data: n.data ?? {}, ...(n.type === "frame" && n.zIndex === undefined ? { zIndex: -1 } : null) })),
+    edges: edges.map((e) => ({ ...e, type: e.type ?? "flow", data: e.data ?? {} })),
+  };
+}
+
+/**
+ * A floating toolbar over something on the board, placed in SCREEN space
+ * with left/top and no CSS transform (FloatAt): a kit Menu or Tooltip
+ * inside it anchors to its button, and CSS anchor positioning is not told
+ * about a transformed ancestor such as React Flow's viewport. Only this
+ * re-renders as the view pans and zooms.
+ */
+function Floating({ at, children }) {
+  const [tx, ty, z] = useStore((s) => s.transform);
+  return (
+    <FloatAt x={at.x * z + tx} top={at.top * z + ty - at.lift} bottom={at.bottom * z + ty + 14}>
+      {children}
+    </FloatAt>
+  );
+}
+
+/** The zoom as a percentage; re-renders alone as the view zooms. */
+function ZoomLevel() {
+  const z = useStore((s) => s.transform[2]);
+  return <>{Math.round((z || 1) * 100)}%</>;
+}
+
+function usePrefersReducedMotion() {
+  const [reduce, setReduce] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const on = () => setReduce(mq.matches);
+    on();
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, []);
+  return reduce;
+}
+
+export function FlowCanvas(props) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return <Placeholder {...props} />;
+  return (
+    <ReactFlowProvider>
+      <LiveCanvas {...props} />
+    </ReactFlowProvider>
+  );
+}
+
+/** The server's (and the first paint's) board: its box, and its words for
+ *  a reader. Not interactive. */
+function Placeholder({ value, defaultValue, height = 560, bare = false, className, label = "Board", describeNode }) {
+  const text = boardToText(value ?? defaultValue ?? emptyBoard(), { describe: describeNode });
+  return (
+    <div role="region" aria-label={label} aria-busy="true" className={cx("relative overflow-hidden bg-background", !bare && "rounded-lg border border-border", className)} style={{ height }}>
+      <p className="sr-only whitespace-pre-line">{text}</p>
+    </div>
+  );
+}
+
+function LiveCanvas(props) {
+  const {
+    value,
+    defaultValue,
+    readOnly: readOnlyProp = false,
+    presentation = false,
+    onExitPresentation,
+    nodeTypes: ownNodeTypes,
+    tools: ownTools,
+    rail,
+    topBar,
+    toolbarExtra,
+    contextMenuItems,
+    emptyState,
+    templates: templatesProp,
+    renderCard,
+    describeNode,
+    palette = STICKY_COLORS,
+    snap: snapProp = true,
+    grid = GRID,
+    minimap: minimapProp = false,
+    height = 560,
+    bare = false,
+    label = "Board",
+    hideAttribution = false,
+    className,
+    canvasRef,
+  } = props;
+  const readOnly = readOnlyProp || presentation;
+  const rf = useReactFlow();
+  const reduce = usePrefersReducedMotion();
+  const duration = reduce ? 0 : 220;
+  const propsRef = useRef(props);
+  propsRef.current = props;
+
+  // ── the board ──────────────────────────────────────────────────────────
+  const initial = useRef(null);
+  if (!initial.current) initial.current = prepare(value ?? defaultValue ?? emptyBoard());
+  const [nodes, setNodes] = useState(initial.current.nodes);
+  const [edges, setEdges] = useState(initial.current.edges);
+  const nodesRef = useRef(nodes);
+  const edgesRef = useRef(edges);
+  nodesRef.current = nodes;
+  edgesRef.current = edges;
+  const [history, dispatch] = useReducer(historyReducer, initial.current, historyInit);
+  const historyRef = useRef(history);
+  historyRef.current = history;
+  const lastKey = useRef(boardKey(initial.current));
+  const viewportRef = useRef(readBoard(value ?? defaultValue).viewport);
+
+  // ── ui state ───────────────────────────────────────────────────────────
+  const [tool, setTool] = useState("select");
+  const [stickyColor, setStickyColor] = useState(palette[0] ?? "warning");
+  const [shapeKind, setShapeKind] = useState("rect");
+  const [editing, setEditing] = useState({ node: null, edge: null });
+  const [connectMenu, setConnectMenu] = useState(null);
+  const [listView, setListView] = useState(false);
+  const [minimap, setMinimap] = useState(minimapProp);
+  const [snap, setSnap] = useState(snapProp);
+  const [sheet, setSheet] = useState(false);
+  const [save, setSave] = useState({ state: "idle" });
+  const [draft, setDraft] = useState(null);
+  const [narrow, setNarrow] = useState(false);
+  const [announce, setAnnounce] = useState("");
+  const [slide, setSlide] = useState(0);
+  const [ctxOn, setCtxOn] = useState("pane");
+  const wrapRef = useRef(null);
+  const frameMembers = useRef(new Map());
+  const clip = useRef(null);
+  const pasteCount = useRef(0);
+  const pointer = useRef(null);
+  const suppressClick = useRef(false);
+  const ctxPoint = useRef(null);
+  const connecting = useConnection((c) => c.inProgress);
+  const marquee = useStore((s) => s.userSelectionActive);
+  const say = (msg) => setAnnounce((m) => (m === msg ? `${msg} ` : msg));
+
+  useEffect(() => setSnap(snapProp), [snapProp]);
+  useEffect(() => setMinimap(minimapProp), [minimapProp]);
+
+  // The rail moves to the bottom when the CANVAS is narrow (not the window).
+  useEffect(() => {
+    const el = wrapRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(([e]) => setNarrow(e.contentRect.width < 768));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  // ── committing, history, onChange / onSave ─────────────────────────────
+  const emitTimer = useRef(0);
+  const dirty = useRef(false);
+  const saveSeq = useRef(0);
+  const currentBoard = () => cleanBoard({ nodes: nodesRef.current, edges: edgesRef.current, viewport: rf.getViewport?.() ?? viewportRef.current });
+
+  const runSave = async (board) => {
+    const onSave = propsRef.current.onSave;
+    if (!onSave) return;
+    const seq = ++saveSeq.current;
+    setSave({ state: "saving" });
+    let res;
+    try {
+      res = await onSave(board);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    if (seq !== saveSeq.current) return;
+    setSave(res && res.ok === false ? { state: "error", error: res.error || "Not saved" } : { state: "saved" });
+  };
+  const emitNow = () => {
+    clearTimeout(emitTimer.current);
+    if (!dirty.current) return;
+    dirty.current = false;
+    const board = currentBoard();
+    lastKey.current = boardKey(board);
+    propsRef.current.onChange?.(board);
+    runSave(board);
+  };
+  const scheduleEmit = () => {
+    dirty.current = true;
+    clearTimeout(emitTimer.current);
+    emitTimer.current = setTimeout(emitNow, propsRef.current.changeDelay ?? 400);
+  };
+  // Leaving with a change not yet sent: send it now.
+  useEffect(
+    () => () => {
+      if (dirty.current) emitNow();
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const [tick, setTick] = useState(0);
+  const pending = useRef(null);
+  const commit = useCallback((reason = "edit", ids) => {
+    const prev = pending.current;
+    pending.current = { reason, ids: [...(prev?.ids ?? []), ...(ids ?? [])] };
+    setTick((t) => t + 1);
+  }, []);
+
+  useEffect(() => {
+    const p = pending.current;
+    if (!p) return;
+    pending.current = null;
+    const { constrain, beforeChange } = propsRef.current;
+    let ns = nodesRef.current;
+    const touched = new Set(p.ids);
+    if (touched.size) {
+      ns = ns.map((n) => {
+        if (!touched.has(n.id)) return n;
+        let next = n;
+        // A card whose height follows its words drops the height a resize gave it.
+        if (p.reason === "resize" && AUTO_HEIGHT.has(n.type) && next.height !== undefined) {
+          const { height: _h, ...rest } = next;
+          next = rest;
+        }
+        if (constrain) {
+          const out = constrain(next, { reason: p.reason, board: { nodes: ns, edges: edgesRef.current } });
+          if (out && typeof out === "object") next = { ...next, ...out };
+        }
+        return next;
+      });
+    }
+    let next = { nodes: ns, edges: edgesRef.current };
+    if (beforeChange) {
+      const out = beforeChange(cleanBoard(next, { viewport: false }), historyRef.current.present, p.reason);
+      if (out === false) {
+        const back = prepare(historyRef.current.present);
+        const sel = new Set(ns.filter((n) => n.selected).map((n) => n.id));
+        setNodes(back.nodes.map((n) => (sel.has(n.id) ? { ...n, selected: true } : n)));
+        setEdges(back.edges);
+        return;
+      }
+      if (out && typeof out === "object") {
+        const sel = new Set(ns.filter((n) => n.selected).map((n) => n.id));
+        const b = prepare(out);
+        next = { nodes: b.nodes.map((n) => (sel.has(n.id) ? { ...n, selected: true } : n)), edges: b.edges };
+      }
+    }
+    if (next.nodes !== nodesRef.current) setNodes(next.nodes);
+    if (next.edges !== edgesRef.current) setEdges(next.edges);
+    const before = historyRef.current.key;
+    dispatch({ type: "push", present: next });
+    if (boardKey(next) !== before) scheduleEmit();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tick]);
+
+  const restore = (board) => {
+    const b = prepare(board);
+    setNodes(b.nodes);
+    setEdges(b.edges);
+    setEditing({ node: null, edge: null });
+  };
+  const undo = () => {
+    const h = historyRef.current;
+    if (!h.past.length) return;
+    restore(h.past[h.past.length - 1]);
+    dispatch({ type: "undo" });
+    scheduleEmit();
+    say("Undone");
+  };
+  const redo = () => {
+    const h = historyRef.current;
+    if (!h.future.length) return;
+    restore(h.future[0]);
+    dispatch({ type: "redo" });
+    scheduleEmit();
+    say("Redone");
+  };
+
+  // Controlled: a `value` that is not what we last sent replaces the board
+  // (and can be undone).
+  useEffect(() => {
+    if (value === undefined) return;
+    const k = boardKey(value);
+    if (k === lastKey.current) return;
+    lastKey.current = k;
+    const b = prepare(value);
+    const sel = new Set(nodesRef.current.filter((n) => n.selected).map((n) => n.id));
+    setNodes(b.nodes.map((n) => (sel.has(n.id) ? { ...n, selected: true } : n)));
+    setEdges(b.edges);
+    dispatch({ type: "push", present: b });
+  }, [value]);
+
+  // ── changing the board ─────────────────────────────────────────────────
+  const selectOnly = (ids = [], edgeIds = []) => {
+    const want = new Set(ids);
+    const wantE = new Set(edgeIds);
+    setNodes((ns) => ns.map((n) => (Boolean(n.selected) === want.has(n.id) ? n : { ...n, selected: want.has(n.id) })));
+    setEdges((es) => es.map((e) => (Boolean(e.selected) === wantE.has(e.id) ? e : { ...e, selected: wantE.has(e.id) })));
+  };
+
+  const addNodes = (list, { select = true, edit = false, reason = "create", edges: newEdges } = {}) => {
+    const arr = (Array.isArray(list) ? list : [list]).filter(Boolean).map((n) => ({
+      ...n,
+      id: n.id ?? makeId(n.type ?? "n"),
+      position: n.position ?? { x: 0, y: 0 },
+      data: n.data ?? {},
+      ...(n.type === "frame" && n.zIndex === undefined ? { zIndex: -1 } : null),
+      selected: select,
+    }));
+    if (!arr.length) return [];
+    setNodes((ns) => [...(select ? ns.map((n) => (n.selected ? { ...n, selected: false } : n)) : ns), ...arr]);
+    if (newEdges?.length) setEdges((es) => [...es.map((e) => (e.selected ? { ...e, selected: false } : e)), ...newEdges.map((e) => ({ ...e, type: e.type ?? "flow", data: e.data ?? {} }))]);
+    commit(reason, arr.map((n) => n.id));
+    if (edit && arr.length === 1) setEditing({ node: arr[0].id, edge: null });
+    return arr.map((n) => n.id);
+  };
+
+  const updateNodes = (ids, fn, { commit: doCommit = true, reason = "edit" } = {}) => {
+    const set = new Set(ids);
+    setNodes((ns) => ns.map((n) => (set.has(n.id) ? fn(n) : n)));
+    if (doCommit) commit(reason);
+  };
+
+  const removeNodes = (ids) => {
+    const gone = new Set(ids);
+    if (!gone.size) return;
+    setNodes((ns) => ns.filter((n) => !gone.has(n.id)));
+    setEdges((es) => es.filter((e) => !gone.has(e.source) && !gone.has(e.target)));
+    setEditing({ node: null, edge: null });
+    commit("delete");
+    say(`${gone.size} item${gone.size === 1 ? "" : "s"} deleted`);
+  };
+
+  const removeEdges = (ids) => {
+    const gone = new Set(ids);
+    setEdges((es) => es.filter((e) => !gone.has(e.id)));
+    setEditing((ed) => (gone.has(ed.edge) ? { node: null, edge: null } : ed));
+    commit("delete");
+  };
+
+  const deleteSelection = () => {
+    const ids = nodesRef.current.filter((n) => n.selected && n.deletable !== false && !n.data?.locked).map((n) => n.id);
+    const eids = edgesRef.current.filter((e) => e.selected && e.deletable !== false).map((e) => e.id);
+    if (!ids.length && !eids.length) return;
+    const gone = new Set(ids);
+    const goneE = new Set(eids);
+    setNodes((ns) => ns.filter((n) => !gone.has(n.id)));
+    setEdges((es) => es.filter((e) => !goneE.has(e.id) && !gone.has(e.source) && !gone.has(e.target)));
+    commit("delete");
+    say(`${ids.length + eids.length} deleted`);
+  };
+
+  const duplicate = (ids) => {
+    const src = { nodes: nodesRef.current, edges: edgesRef.current };
+    const copy = duplicateNodes(src, ids.filter((id) => nodesRef.current.some((n) => n.id === id)), { offset: { x: grid * 2, y: grid * 2 } });
+    if (!copy.nodes.length) return;
+    addNodes(copy.nodes, { reason: "paste", edges: copy.edges });
+    say(`${copy.nodes.length} duplicated`);
+  };
+
+  const pasteBoard = (data, at) => {
+    const b = readBoard(data);
+    if (!b.nodes.length) return;
+    const bounds = boardBounds(b.nodes);
+    pasteCount.current += 1;
+    const offset = at
+      ? { x: Math.round((at.x - bounds.x - bounds.width / 2) / grid) * grid, y: Math.round((at.y - bounds.y - bounds.height / 2) / grid) * grid }
+      : { x: grid * 2 * pasteCount.current, y: grid * 2 * pasteCount.current };
+    const copy = duplicateNodes(b, b.nodes.map((n) => n.id), { offset });
+    addNodes(copy.nodes, { reason: "paste", edges: copy.edges });
+    say(`${copy.nodes.length} pasted`);
+  };
+
+  const lock = (ids, on = true) => {
+    updateNodes(ids, (n) => {
+      const data = { ...n.data };
+      if (on) data.locked = true;
+      else delete data.locked;
+      const next = { ...n, data };
+      if (on) {
+        next.draggable = false;
+        next.deletable = false;
+      } else {
+        delete next.draggable;
+        delete next.deletable;
+      }
+      return next;
+    });
+    say(on ? "Locked" : "Unlocked");
+  };
+
+  const frameSelection = (ids) => {
+    const pick = nodesRef.current.filter((n) => ids.includes(n.id));
+    const b = boardBounds(pick);
+    if (!b) return;
+    const pad = grid * 2;
+    const f = createNode("frame", null, { rect: { x: b.x - pad, y: b.y - pad, width: b.width + pad * 2, height: b.height + pad * 2 }, grid, data: { title: "Frame" } });
+    addNodes(f, { edit: true });
+  };
+
+  const fitView = (opts) => rf.fitView({ padding: 0.2, maxZoom: 1.25, duration, ...opts });
+  const focusNode = (id) => {
+    selectOnly([id]);
+    const n = nodesRef.current.find((x) => x.id === id);
+    if (!n) return;
+    const r = nodeRect(n);
+    rf.setCenter(r.x + r.width / 2, r.y + r.height / 2, { zoom: Math.max(rf.getZoom(), 0.8), duration });
+    requestAnimationFrame(() => wrapRef.current?.querySelector(`.react-flow__node[data-id="${CSS.escape(id)}"]`)?.focus({ preventScroll: true }));
+  };
+  const centerPoint = () => {
+    const r = wrapRef.current?.getBoundingClientRect();
+    if (!r) return { x: 0, y: 0 };
+    return rf.screenToFlowPosition({ x: r.left + r.width / 2, y: r.top + r.height / 2 });
+  };
+
+  // The handle. One object for the canvas's life: every method reads the
+  // latest state through refs, so a block may keep it.
+  const apiRef = useRef(null);
+  if (!apiRef.current) apiRef.current = {};
+  const api = apiRef.current;
+  Object.assign(api, {
+    getBoard: currentBoard,
+    setBoard: (board, { fit = true } = {}) => {
+      restore(board);
+      commit("load");
+      if (fit) setTimeout(() => fitView(), 60);
+    },
+    getSelection: () => ({ nodes: nodesRef.current.filter((n) => n.selected), edges: edgesRef.current.filter((e) => e.selected) }),
+    addNodes,
+    addEdge: (edge) => {
+      const e = edge.id ? { type: "flow", data: {}, ...edge } : createEdge(edge.source, edge.target, edge);
+      setEdges((es) => [...es, e]);
+      commit("connect");
+      return e.id;
+    },
+    updateNode: (id, patch, opts) => updateNodes([id], (n) => ({ ...n, ...(typeof patch === "function" ? patch(n) : patch) }), opts),
+    updateNodeData: (id, patch, opts) => updateNodes([id], (n) => ({ ...n, data: { ...n.data, ...(typeof patch === "function" ? patch(n.data) : patch) } }), opts),
+    updateNodesData: (ids, patch, opts) => updateNodes(ids, (n) => ({ ...n, data: { ...n.data, ...patch } }), opts),
+    removeNodes,
+    updateEdge: (id, patch, { commit: doCommit = true } = {}) => {
+      setEdges((es) => es.map((e) => (e.id === id ? { ...e, ...(typeof patch === "function" ? patch(e) : patch) } : e)));
+      if (doCommit) commit("edit");
+    },
+    removeEdges,
+    select: (ids, edgeIds) => selectOnly(ids, edgeIds),
+    duplicate,
+    lock,
+    arrange: (ids, where) => {
+      setNodes((ns) => arrangeNodes(ns, ids, where));
+      commit("arrange");
+    },
+    align: (ids, how) => {
+      setNodes((ns) => alignNodes(ns, ids, how));
+      commit("align", ids);
+    },
+    distribute: (ids, axis) => {
+      setNodes((ns) => distributeNodes(ns, ids, axis));
+      commit("align", ids);
+    },
+    autoLayout: (opts = {}) => {
+      setNodes((ns) => autoLayout(ns, edgesRef.current, { grid, ...opts }));
+      commit("layout", opts.ids ?? nodesRef.current.map((n) => n.id));
+      if (!opts.ids) setTimeout(() => fitView(), 60);
+    },
+    frameSelection,
+    edit: (id) => setEditing({ node: id, edge: null }),
+    editEdge: (id) => setEditing({ node: null, edge: id }),
+    stopEditing: () => {
+      setEditing({ node: null, edge: null });
+      // Words emptied on a connector label go away with it.
+      setEdges((es) => es.map((e) => (typeof e.label === "string" && !e.label.trim() ? { ...e, label: undefined } : e)));
+      commit("edit");
+      requestAnimationFrame(() => {
+        if (!wrapRef.current?.contains(document.activeElement)) wrapRef.current?.focus({ preventScroll: true });
+      });
+    },
+    commit,
+    undo,
+    redo,
+    canUndo: () => historyRef.current.past.length > 0,
+    canRedo: () => historyRef.current.future.length > 0,
+    setTool: (id) => setTool(id),
+    getTool: () => tool,
+    fitView,
+    focusNode,
+    zoomIn: () => rf.zoomIn({ duration }),
+    zoomOut: () => rf.zoomOut({ duration }),
+    zoomTo: (z) => rf.zoomTo(z, { duration }),
+    centerPoint,
+    screenToFlow: (p) => rf.screenToFlowPosition(p),
+    toText: () => boardToText(currentBoard(), { describe: propsRef.current.describeNode }),
+    toMarkdown: (opts) => boardToMarkdown(currentBoard(), { describe: propsRef.current.describeNode, ...opts }),
+    save: () => {
+      dirty.current = true;
+      emitNow();
+    },
+    readOnly,
+  });
+
+  useEffect(() => {
+    if (!canvasRef) return;
+    canvasRef.current = api;
+    return () => {
+      if (canvasRef.current === api) canvasRef.current = null;
+    };
+  }, [canvasRef, api]);
+
+  // ── tools ──────────────────────────────────────────────────────────────
+  const customs = useMemo(
+    () =>
+      (ownTools ?? []).map((t) => ({ ...t, kind: t.onSelect && !t.create ? "action" : "mode", custom: true })),
+    [ownTools],
+  );
+  const toolById = useMemo(() => {
+    const m = new Map(Object.values(TOOLS).map((t) => [t.id, t]));
+    for (const t of customs) m.set(t.id, t);
+    return m;
+  }, [customs]);
+  const railItems = useMemo(() => {
+    const ids = rail ?? [...DEFAULT_RAIL, ...customs.map((t) => t.id), ...(props.pickImage ? ["image"] : [])];
+    return ids.map((id) => (id === "|" ? "|" : toolById.get(id))).filter(Boolean);
+  }, [rail, customs, toolById, props.pickImage]);
+  const active = toolById.get(tool) ?? TOOLS.select;
+  const placing = Boolean(active.place || active.create);
+  const cursorTool = tool === "hand" ? "hand" : tool === "connector" ? "connector" : tool === "text" ? "text" : placing ? "place" : "select";
+
+  const pickTool = (t) => {
+    if (!t || readOnly) return;
+    setConnectMenu(null);
+    if (t.id === "image") {
+      Promise.resolve(propsRef.current.pickImage?.())
+        .then((img) => {
+          if (!img?.src) return;
+          addNodes(createNode("image", centerPoint(), { grid, data: { src: img.src, alt: img.alt ?? "" }, width: img.width, height: img.height }));
+        })
+        .catch(() => {});
+      return;
+    }
+    if (t.kind === "action") {
+      t.onSelect?.(api);
+      return;
+    }
+    setTool((cur) => (cur === t.id && t.id !== "select" ? "select" : t.id));
+    if (t.id !== "select") selectOnly([]);
+  };
+
+  /** Put down what a tool makes, at a board point (or filling a rect). */
+  const place = (t, point, rect) => {
+    let made;
+    if (t.create) {
+      made = t.create(point, { rect, api, grid });
+    } else if (t.place) {
+      const data = t.place === "sticky" ? { color: stickyColor } : t.place === "shape" ? { shape: shapeKind } : undefined;
+      made = createNode(t.place, point, { grid: snap ? grid : 0, data, rect: t.place === "text" && rect ? { ...rect, height: undefined } : rect });
+      if (t.place === "text" && rect) delete made.height;
+    }
+    const list = (Array.isArray(made) ? made : [made]).filter(Boolean);
+    if (!list.length) return;
+    const one = list.length === 1 ? list[0] : null;
+    addNodes(list, { edit: Boolean(one && EDITABLE.has(one.type)) });
+    setTool("select");
+    say(`${t.label} added`);
+  };
+
+  // ── keyboard ───────────────────────────────────────────────────────────
+  const nudge = useRef(0);
+  const selectedNodes = nodes.filter((n) => n.selected);
+  const selectedEdges = edges.filter((e) => e.selected);
+
+  const frames = useMemo(
+    () =>
+      nodes
+        .filter((n) => n.type === "frame")
+        .sort((a, b) => {
+          const ra = nodeRect(a);
+          const rb = nodeRect(b);
+          return Math.abs(ra.y - rb.y) > 40 ? ra.y - rb.y : ra.x - rb.x;
+        }),
+    [nodes],
+  );
+  const goSlide = (i) => {
+    const f = frames[Math.max(0, Math.min(frames.length - 1, i))];
+    if (!f) return;
+    setSlide(frames.indexOf(f));
+    rf.fitView({ nodes: [{ id: f.id }], padding: 0.08, duration: reduce ? 0 : 400 });
+  };
+  useEffect(() => {
+    if (!presentation) return;
+    const t = setTimeout(() => (frames.length ? goSlide(0) : fitView()), 80);
+    return () => clearTimeout(t);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [presentation]);
+
+  const onKeyDownCapture = (e) => {
+    const t = e.target;
+    if (t?.closest?.(EDITING_TARGET)) return;
+    const mod = e.metaKey || e.ctrlKey;
+    const k = e.key;
+    const low = k.length === 1 ? k.toLowerCase() : k;
+    const onControl = Boolean(t?.closest?.("button, a[href]"));
+    const done = () => {
+      e.preventDefault();
+      e.stopPropagation();
+    };
+
+    // View keys work everywhere, read-only too.
+    if (e.shiftKey && !mod && (e.code === "Digit1" || k === "!")) return done(), fitView();
+    if (e.shiftKey && !mod && (e.code === "Digit2" || k === "@")) {
+      done();
+      const sel = nodesRef.current.filter((n) => n.selected);
+      return sel.length ? fitView({ nodes: sel.map((n) => ({ id: n.id })), maxZoom: 2 }) : fitView();
+    }
+    if ((mod && (k === "=" || k === "+")) || (!mod && !onControl && (k === "+" || k === "="))) return done(), rf.zoomIn({ duration });
+    if ((mod && k === "-") || (!mod && !onControl && k === "-")) return done(), rf.zoomOut({ duration });
+    if (mod && k === "0") return done(), rf.zoomTo(1, { duration });
+    if (k === "?" && !mod) return done(), setSheet(true);
+    if (presentation) {
+      if (k === "ArrowRight" || k === "PageDown" || (k === " " && !onControl)) return done(), goSlide(slide + 1);
+      if (k === "ArrowLeft" || k === "PageUp") return done(), goSlide(slide - 1);
+      if (k === "Escape") return done(), propsRef.current.onExitPresentation?.();
+      return;
+    }
+    if (k === "Escape") {
+      if (editing.node || editing.edge) return done(), setEditing({ node: null, edge: null });
+      if (connectMenu) return done(), setConnectMenu(null);
+      if (listView) return done(), setListView(false);
+      if (tool !== "select") return done(), setTool("select");
+      if (selectedNodes.length || selectedEdges.length) return done(), selectOnly([]);
+      return;
+    }
+    if (readOnly) return;
+
+    if (mod && low === "z") return done(), e.shiftKey ? redo() : undo();
+    if (mod && low === "y") return done(), redo();
+    if (mod && low === "s") return done(), api.save();
+    if (mod && low === "a") return done(), selectOnly(nodesRef.current.filter((n) => n.selectable !== false).map((n) => n.id));
+    const ids = nodesRef.current.filter((n) => n.selected).map((n) => n.id);
+    if (mod && low === "d") return done(), ids.length && duplicate(ids);
+    if (mod && e.shiftKey && low === "l") return done(), ids.length && lock(ids, !nodesRef.current.some((n) => n.selected && n.data?.locked));
+    if (mod && k === "]") return done(), ids.length && api.arrange(ids, "front");
+    if (mod && k === "[") return done(), ids.length && api.arrange(ids, "back");
+    if (mod) return;
+
+    if (!onControl && (k === "Delete" || k === "Backspace")) return done(), deleteSelection();
+    if (!onControl && k === "Enter") {
+      const focused = t?.classList?.contains("react-flow__node") ? t.dataset.id : null;
+      if (focused && !nodesRef.current.find((n) => n.id === focused)?.selected) return done(), selectOnly([focused]);
+      if (ids.length === 1) {
+        const n = nodesRef.current.find((x) => x.id === ids[0]);
+        if (n && !n.data?.locked) return done(), openNode(n);
+      }
+      const eid = edgesRef.current.filter((x) => x.selected).map((x) => x.id);
+      if (eid.length === 1) return done(), setEditing({ node: null, edge: eid[0] });
+      return;
+    }
+    if (!onControl && k.startsWith("Arrow") && ids.length) {
+      done();
+      const step = e.shiftKey ? 10 : 1;
+      const dx = k === "ArrowLeft" ? -step : k === "ArrowRight" ? step : 0;
+      const dy = k === "ArrowUp" ? -step : k === "ArrowDown" ? step : 0;
+      const movable = nodesRef.current.filter((n) => n.selected && n.draggable !== false && !n.data?.locked).map((n) => n.id);
+      updateNodes(movable, (n) => ({ ...n, position: { x: n.position.x + dx, y: n.position.y + dy } }), { commit: false });
+      clearTimeout(nudge.current);
+      nudge.current = setTimeout(() => commit("move", movable), 400);
+      return;
+    }
+    if (!e.altKey && k.length === 1) {
+      const hit = railItems.find((x) => x !== "|" && x.shortcut && x.shortcut.toLowerCase() === low);
+      if (hit) return done(), pickTool(hit);
+    }
+  };
+
+  // Tab onto a card selects it, so what the keys do is what is shown.
+  const onFocusCapture = (e) => {
+    const el = e.target;
+    if (!el?.classList?.contains("react-flow__node") || !el.matches(":focus-visible")) return;
+    const id = el.dataset.id;
+    const n = nodesRef.current.find((x) => x.id === id);
+    if (n && !n.selected && n.selectable !== false) selectOnly([id]);
+  };
+
+  // Copy, cut, paste: the board's own clipboard, with the text on the
+  // system one too (paste a list of lines from elsewhere = one sticky each).
+  useEffect(() => {
+    const MIME = "application/x-flow-canvas+json";
+    const activeHere = () => {
+      const a = document.activeElement;
+      return wrapRef.current?.contains(a) && !a?.closest?.(EDITING_TARGET);
+    };
+    const copy = (e) => {
+      if (!activeHere()) return false;
+      const ids = nodesRef.current.filter((n) => n.selected).map((n) => n.id);
+      if (!ids.length) return false;
+      const all = new Set(ids);
+      for (const id of ids) if (nodesRef.current.find((n) => n.id === id)?.type === "frame") for (const c of frameContents({ nodes: nodesRef.current }, id)) all.add(c);
+      const data = cleanBoard({ nodes: nodesRef.current.filter((n) => all.has(n.id)), edges: edgesRef.current.filter((x) => all.has(x.source) && all.has(x.target)) }, { viewport: false });
+      clip.current = data;
+      pasteCount.current = 0;
+      const text = boardToText(data, { describe: propsRef.current.describeNode });
+      clip.current.text = text;
+      e.clipboardData?.setData("text/plain", text);
+      try {
+        e.clipboardData?.setData(MIME, JSON.stringify(data));
+      } catch {}
+      e.preventDefault();
+      return true;
+    };
+    const onCopy = (e) => copy(e);
+    const onCut = (e) => {
+      if (propsRef.current.readOnly || propsRef.current.presentation) return;
+      if (copy(e)) deleteSelection();
+    };
+    const onPaste = (e) => {
+      if (!activeHere() || propsRef.current.readOnly || propsRef.current.presentation) return;
+      let data = null;
+      try {
+        const raw = e.clipboardData?.getData(MIME);
+        if (raw) data = JSON.parse(raw);
+      } catch {}
+      const text = e.clipboardData?.getData("text/plain") ?? "";
+      if (!data && clip.current && text === clip.current.text) data = clip.current;
+      e.preventDefault();
+      if (data) return pasteBoard(data, pointer.current);
+      const lines = text
+        .split(/\r?\n/)
+        .map((s) => s.replace(/^\s*(?:[-*•]|\d+[.)])\s+/, "").trim())
+        .filter(Boolean)
+        .slice(0, 24);
+      if (!lines.length) return;
+      const at = pointer.current ?? centerPoint();
+      const cols = Math.min(4, lines.length);
+      const made = lines.map((line, i) =>
+        createNode("sticky", { x: at.x + (i % cols) * 220 - ((cols - 1) * 220) / 2, y: at.y + Math.floor(i / cols) * 220 }, { grid, data: { text: line, color: stickyColor } }),
+      );
+      addNodes(made, { reason: "paste" });
+    };
+    document.addEventListener("copy", onCopy);
+    document.addEventListener("cut", onCut);
+    document.addEventListener("paste", onPaste);
+    return () => {
+      document.removeEventListener("copy", onCopy);
+      document.removeEventListener("cut", onCut);
+      document.removeEventListener("paste", onPaste);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [stickyColor]);
+
+  // ── pointer: focus, double-click, drag-to-size ─────────────────────────
+  const isPane = (el) => el?.classList?.contains("react-flow__pane");
+  const onPointerDownCapture = (e) => {
+    const a = document.activeElement;
+    if (!e.target.closest?.(EDITING_TARGET) && !wrapRef.current?.contains(a)) wrapRef.current?.focus({ preventScroll: true });
+    if (!isPane(e.target) || e.button !== 0 || readOnly) return;
+    if (connectMenu) setConnectMenu(null);
+    if (!active.sizable) return;
+    const start = rf.screenToFlowPosition({ x: e.clientX, y: e.clientY });
+    const origin = { x: e.clientX, y: e.clientY };
+    let moved = false;
+    const rectFrom = (ev) => {
+      const p = rf.screenToFlowPosition({ x: ev.clientX, y: ev.clientY });
+      const s = snap ? grid : 1;
+      const x1 = Math.round(Math.min(start.x, p.x) / s) * s;
+      const y1 = Math.round(Math.min(start.y, p.y) / s) * s;
+      const x2 = Math.round(Math.max(start.x, p.x) / s) * s;
+      const y2 = Math.round(Math.max(start.y, p.y) / s) * s;
+      return { x: x1, y: y1, width: Math.max(s, x2 - x1), height: Math.max(s, y2 - y1) };
+    };
+    const move = (ev) => {
+      if (!moved && Math.hypot(ev.clientX - origin.x, ev.clientY - origin.y) < 5) return;
+      moved = true;
+      setDraft(rectFrom(ev));
+    };
+    const up = (ev) => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", up);
+      setDraft(null);
+      if (!moved) return;
+      suppressClick.current = true;
+      const r = rectFrom(ev);
+      if (r.width < grid * 2 && r.height < grid * 2) return;
+      place(active, { x: r.x + r.width / 2, y: r.y + r.height / 2 }, r);
+    };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", up);
+  };
+
+  const onPaneClick = (e) => {
+    setConnectMenu(null);
+    if (editing.node || editing.edge) setEditing({ node: null, edge: null });
+    if (suppressClick.current) {
+      suppressClick.current = false;
+      return;
+    }
+    if (readOnly || !placing) return;
+    place(active, rf.screenToFlowPosition({ x: e.clientX, y: e.clientY }));
+  };
+
+  const onDoubleClick = (e) => {
+    if (readOnly || tool !== "select" || !isPane(e.target)) return;
+    const p = rf.screenToFlowPosition({ x: e.clientX, y: e.clientY });
+    const n = createNode("sticky", p, { grid: snap ? grid : 0, data: { color: stickyColor } });
+    addNodes(n, { edit: true });
+    say("Sticky added");
+  };
+
+  const openNode = (n) => {
+    const { onOpenNode } = propsRef.current;
+    const custom = !BUILT_IN_NODES[n.type];
+    if (onOpenNode && (custom || (n.type === "card" && renderCard) || readOnly)) return onOpenNode(n);
+    if (readOnly || n.data?.locked) return;
+    if (EDITABLE.has(n.type) || custom) setEditing({ node: n.id, edge: null });
+  };
+
+  // ── React Flow wiring ──────────────────────────────────────────────────
+  const onNodesChange = useCallback((changes) => {
+    const real = changes.filter((c) => c.type !== "remove");
+    setNodes((nds) => {
+      const members = frameMembers.current;
+      if (!members.size) return applyNodeChanges(real, nds);
+      const byId = new Map(nds.map((n) => [n.id, n]));
+      const moving = new Set(real.filter((c) => c.type === "position").map((c) => c.id));
+      const extra = [];
+      for (const c of real) {
+        if (c.type !== "position" || !c.position || !members.has(c.id)) continue;
+        const prev = byId.get(c.id);
+        if (!prev) continue;
+        const dx = c.position.x - prev.position.x;
+        const dy = c.position.y - prev.position.y;
+        if (!dx && !dy) continue;
+        for (const m of members.get(c.id)) {
+          const mn = byId.get(m);
+          if (!mn || moving.has(m)) continue;
+          moving.add(m);
+          extra.push({ type: "position", id: m, position: { x: mn.position.x + dx, y: mn.position.y + dy } });
+        }
+      }
+      return applyNodeChanges(extra.length ? [...real, ...extra] : real, nds);
+    });
+  }, []);
+  const onEdgesChange = useCallback((changes) => setEdges((es) => applyEdgeChanges(changes.filter((c) => c.type !== "remove"), es)), []);
+
+  const dragStart = (dragged) => {
+    setConnectMenu(null);
+    const ids = new Set((dragged ?? []).map((n) => n.id));
+    const m = new Map();
+    for (const n of dragged ?? []) {
+      if (n.type !== "frame") continue;
+      const inside = frameContents({ nodes: nodesRef.current }, n.id).filter((id) => !ids.has(id));
+      if (inside.length) m.set(n.id, inside);
+    }
+    frameMembers.current = m;
+  };
+  const dragStop = (dragged) => {
+    const ids = (dragged ?? []).map((n) => n.id);
+    for (const list of frameMembers.current.values()) ids.push(...list);
+    frameMembers.current = new Map();
+    commit("move", ids);
+  };
+
+  const isValidConnection = (c) => {
+    if (c.source === c.target) return false;
+    const can = propsRef.current.canConnect;
+    return can ? can(c, { nodes: nodesRef.current, edges: edgesRef.current }) !== false : true;
+  };
+  const onConnect = (c) => {
+    if (!isValidConnection(c)) return;
+    if (edgesRef.current.some((e) => e.source === c.source && e.target === c.target)) return;
+    const e = createEdge(c.source, c.target);
+    setEdges((es) => [...es, e]);
+    commit("connect");
+    say("Connected");
+  };
+  const onConnectEnd = (event, state) => {
+    if (readOnly || state?.isValid || state?.toNode || !state?.fromNode) return;
+    const pt = "changedTouches" in event && event.changedTouches?.length ? event.changedTouches[0] : event;
+    const box = wrapRef.current?.getBoundingClientRect();
+    if (!box) return;
+    const flow = rf.screenToFlowPosition({ x: pt.clientX, y: pt.clientY });
+    setConnectMenu({ at: { x: Math.min(pt.clientX - box.left, box.width - 200), y: Math.min(pt.clientY - box.top, box.height - 240) }, flow, from: state.fromNode.id });
+  };
+
+  const connectItems = useMemo(() => {
+    if (!connectMenu) return [];
+    const { flow, from } = connectMenu;
+    const make = (node) => {
+      if (!node) return;
+      const list = Array.isArray(node) ? node : [node];
+      const first = list[0];
+      addNodes(list, {
+        edges: first ? [createEdge(from, first.id)] : [],
+        edit: list.length === 1 && EDITABLE.has(first?.type),
+      });
+      setConnectMenu(null);
+    };
+    const built = [
+      { label: "Sticky note", icon: "sticky-note", onSelect: () => make(createNode("sticky", flow, { grid, data: { color: stickyColor } })) },
+      ...Object.entries(SHAPE_ICON).map(([k, icon]) => ({ label: SHAPE_NAMES[k], icon, onSelect: () => make(createNode("shape", flow, { grid, data: { shape: k } })) })),
+      { label: "Text", icon: "type", onSelect: () => make(createNode("text", flow, { grid })) },
+    ];
+    const own = customs.filter((t) => t.create && t.connectable !== false).map((t) => ({ label: t.label, icon: t.icon, onSelect: () => make(t.create(flow, { api, grid })) }));
+    return [...built, own.length ? { type: "separator" } : null, ...own];
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [connectMenu, customs, stickyColor]);
+
+  // ── the context menu (right-click, long press, Shift+F10) ───────────────
+  const ctxItems = (() => {
+    const m = modKey();
+    if (readOnly) {
+      return [
+        { label: "Fit to screen", icon: "maximize", shortcut: "⇧1", onSelect: () => fitView() },
+        { label: "List view", icon: "list", onSelect: () => setListView(true) },
+      ];
+    }
+    const sel = selectedNodes;
+    if (ctxOn === "edge" && selectedEdges.length) {
+      const ids = selectedEdges.map((x) => x.id);
+      return [
+        ids.length === 1 && { label: selectedEdges[0].label ? "Edit label" : "Add label", icon: "pencil", shortcut: "↵", onSelect: () => api.editEdge(ids[0]) },
+        { label: "Delete", icon: "trash", tone: "danger", shortcut: "⌫", onSelect: () => removeEdges(ids) },
+      ];
+    }
+    if (ctxOn === "selection" && sel.length) {
+      const ids = sel.map((n) => n.id);
+      const anyLocked = sel.some((n) => n.data?.locked);
+      const single = sel.length === 1 ? sel[0] : null;
+      const extra = typeof contextMenuItems === "function" ? contextMenuItems({ nodes: sel, edges: selectedEdges }, api) : null;
+      return [
+        single && !anyLocked && { label: "Edit", icon: "pencil", shortcut: "↵", onSelect: () => openNode(single) },
+        { label: "Duplicate", icon: "copy", shortcut: `${m}D`, onSelect: () => duplicate(ids) },
+        !sel.every((n) => n.type === "frame") && { label: "Frame selection", icon: "frame", onSelect: () => frameSelection(ids) },
+        { type: "separator" },
+        { label: "Bring to front", icon: "bring-front", shortcut: `${m}]`, onSelect: () => api.arrange(ids, "front") },
+        { label: "Send to back", icon: "send-back", shortcut: `${m}[`, onSelect: () => api.arrange(ids, "back") },
+        sel.length > 1 && {
+          label: "Align",
+          icon: "align-center",
+          items: [
+            { label: "Left", onSelect: () => api.align(ids, "left") },
+            { label: "Centre", onSelect: () => api.align(ids, "center") },
+            { label: "Right", onSelect: () => api.align(ids, "right") },
+            { type: "separator" },
+            { label: "Top", onSelect: () => api.align(ids, "top") },
+            { label: "Middle", onSelect: () => api.align(ids, "middle") },
+            { label: "Bottom", onSelect: () => api.align(ids, "bottom") },
+            sel.length > 2 && { type: "separator" },
+            sel.length > 2 && { label: "Distribute horizontally", onSelect: () => api.distribute(ids, "horizontal") },
+            sel.length > 2 && { label: "Distribute vertically", onSelect: () => api.distribute(ids, "vertical") },
+            { type: "separator" },
+            { label: "Tidy up", onSelect: () => api.autoLayout({ ids }) },
+          ],
+        },
+        { label: anyLocked ? "Unlock" : "Lock", icon: anyLocked ? "lock-open" : "lock", shortcut: `⇧${m}L`, onSelect: () => lock(ids, !anyLocked) },
+        ...(extra?.length ? [{ type: "separator" }, ...extra] : []),
+        { type: "separator" },
+        { label: "Delete", icon: "trash", tone: "danger", shortcut: "⌫", disabled: sel.every((n) => n.data?.locked || n.deletable === false), onSelect: deleteSelection },
+      ];
+    }
+    const at = () => ctxPoint.current ?? centerPoint();
+    const extra = typeof contextMenuItems === "function" ? contextMenuItems({ nodes: [], edges: [] }, api) : null;
+    return [
+      { label: "Add sticky here", icon: "sticky-note", onSelect: () => addNodes(createNode("sticky", at(), { grid, data: { color: stickyColor } }), { edit: true }) },
+      { label: "Add shape here", icon: "square", onSelect: () => addNodes(createNode("shape", at(), { grid, data: { shape: shapeKind } }), { edit: true }) },
+      { label: "Add text here", icon: "type", onSelect: () => addNodes(createNode("text", at(), { grid }), { edit: true }) },
+      { label: "Add frame here", icon: "frame", onSelect: () => addNodes(createNode("frame", at(), { grid }), { edit: true }) },
+      { type: "separator" },
+      clip.current && { label: "Paste here", icon: "copy", shortcut: `${m}V`, onSelect: () => pasteBoard(clip.current, at()) },
+      nodes.length > 0 && { label: "Select all", shortcut: `${m}A`, onSelect: () => selectOnly(nodesRef.current.map((n) => n.id)) },
+      nodes.length > 1 && { label: "Tidy up everything", icon: "sparkles", onSelect: () => api.autoLayout() },
+      ...(extra?.length ? [{ type: "separator" }, ...extra] : []),
+      { type: "separator" },
+      { label: "Fit to screen", icon: "maximize", shortcut: "⇧1", onSelect: () => fitView() },
+      { type: "checkbox", label: "Snap to grid", checked: snap, onCheckedChange: setSnap },
+      { label: "Keyboard shortcuts", icon: "keyboard", shortcut: "?", onSelect: () => setSheet(true) },
+    ];
+  })();
+
+  // ── node and edge types, context ───────────────────────────────────────
+  const nodeTypes = useMemo(() => ({ ...BUILT_IN_NODES, ...(ownNodeTypes ?? {}) }), [ownNodeTypes]);
+  const soleEdge = selectedEdges.length === 1 && !selectedNodes.length ? selectedEdges[0].id : null;
+  const ctx = useMemo(
+    () => ({ api, tool, editingNode: editing.node, editingEdge: editing.edge, soleEdge, readOnly, palette, renderCard, connecting, grid }),
+    [api, tool, editing.node, editing.edge, soleEdge, readOnly, palette, renderCard, connecting, grid],
+  );
+
+  // React Flow's event props, one stable function each: a new function per
+  // render would redraw every node on every render (a pan, a keystroke).
+  const live = useRef({});
+  live.current = {
+    onConnect,
+    onConnectEnd,
+    isValidConnection,
+    onNodeDragStart: (_, __, dragged) => dragStart(dragged),
+    onNodeDragStop: (_, __, dragged) => dragStop(dragged),
+    onSelectionDragStart: (_, dragged) => dragStart(dragged),
+    onSelectionDragStop: (_, dragged) => dragStop(dragged),
+    onNodeDoubleClick: (e, n) => {
+      e.stopPropagation();
+      openNode(n);
+    },
+    onEdgeDoubleClick: (e, ed) => {
+      e.stopPropagation();
+      if (!readOnly) setEditing({ node: null, edge: ed.id });
+    },
+    onPaneClick,
+    onPaneContextMenu: (e) => {
+      ctxPoint.current = rf.screenToFlowPosition({ x: e.clientX, y: e.clientY });
+      setCtxOn("pane");
+    },
+    onNodeContextMenu: (_, n) => {
+      if (!n.selected) selectOnly([n.id]);
+      setCtxOn("selection");
+    },
+    onSelectionContextMenu: () => setCtxOn("selection"),
+    onEdgeContextMenu: (_, ed) => {
+      if (!ed.selected) selectOnly([], [ed.id]);
+      setCtxOn("edge");
+    },
+    onSelectionChange: ({ nodes: sn, edges: se }) => propsRef.current.onSelectionChange?.(sn, se),
+    onMoveEnd: (_, vp) => {
+      viewportRef.current = vp;
+    },
+  };
+  const handlers = useMemo(() => Object.fromEntries(Object.keys(live.current).map((k) => [k, (...a) => live.current[k](...a)])), []);
+
+  const dragging = nodes.some((n) => n.dragging) || marquee;
+  const snapGrid = useMemo(() => [grid, grid], [grid]);
+  const proOptions = useMemo(() => ({ hideAttribution }), [hideAttribution]);
+  const showToolbar = !readOnly && tool === "select" && selectedNodes.length > 0 && !dragging && !editing.node && !connectMenu && !listView;
+  const templates = templatesProp ?? starterTemplates();
+
+  // Where the floating toolbars hang, in board coordinates (Floating turns
+  // them into screen ones as the view moves).
+  const selBounds = showToolbar ? boardBounds(selectedNodes) : null;
+  const selBox = selBounds
+    ? {
+        x: selBounds.x + selBounds.width / 2,
+        top: selBounds.y,
+        bottom: selBounds.y + selBounds.height,
+        // A frame's title sits above its box: clear it.
+        lift: selectedNodes.some((n) => n.type === "frame") ? 34 : 14,
+      }
+    : null;
+  const soleEdgeObj = !readOnly && tool === "select" && soleEdge && !editing.edge && !connectMenu && !listView ? selectedEdges[0] : null;
+  const edgeBar = (() => {
+    if (!soleEdgeObj) return null;
+    const s = nodes.find((n) => n.id === soleEdgeObj.source);
+    const t = nodes.find((n) => n.id === soleEdgeObj.target);
+    if (!s || !t) return null;
+    const ra = nodeRect(s);
+    const rb = nodeRect(t);
+    const sides = facingSides(ra, rb);
+    const g = connectorGeometry(sidePoint(ra, sides.source), sides.source, sidePoint(rb, sides.target), sides.target, soleEdgeObj.data?.line ?? "curved");
+    return { at: { x: g.mid.x, top: g.mid.y, bottom: g.mid.y, lift: 26 }, edge: soleEdgeObj };
+  })();
+  const isEmpty = nodes.length === 0;
+  const board = listView ? cleanBoard({ nodes, edges }, { viewport: false }) : null;
+
+  return (
+    <CanvasContext.Provider value={ctx}>
+      <div
+        ref={wrapRef}
+        role="region"
+        aria-label={label}
+        aria-roledescription="board"
+        tabIndex={-1}
+        data-tool={cursorTool}
+        data-connecting={connecting ? "true" : "false"}
+        className={cx("relative isolate overflow-hidden bg-background text-foreground outline-none", !bare && "rounded-lg border border-border", THEME, className)}
+        style={{ height }}
+        onKeyDownCapture={onKeyDownCapture}
+        onFocusCapture={onFocusCapture}
+        onPointerDownCapture={onPointerDownCapture}
+        onPointerMove={(e) => {
+          if (e.pointerType === "mouse") pointer.current = rf.screenToFlowPosition({ x: e.clientX, y: e.clientY });
+        }}
+        onPointerLeave={() => {
+          pointer.current = null;
+        }}
+        onDoubleClick={onDoubleClick}
+      >
+        <p className="sr-only" aria-live="polite">
+          {announce}
+        </p>
+        <ContextMenu items={ctxItems} label={`${label} actions`} className="absolute inset-0">
+          <ReactFlow
+            nodes={nodes}
+            edges={edges}
+            nodeTypes={nodeTypes}
+            edgeTypes={BUILT_IN_EDGES}
+            defaultEdgeOptions={EDGE_DEFAULTS}
+            onNodesChange={onNodesChange}
+            onEdgesChange={onEdgesChange}
+            {...handlers}
+            connectionMode={ConnectionMode.Loose}
+            connectionRadius={28}
+            snapToGrid={snap}
+            snapGrid={snapGrid}
+            panOnScroll
+            zoomOnScroll={false}
+            zoomOnPinch
+            zoomOnDoubleClick={false}
+            panOnDrag={tool === "hand" ? true : MIDDLE_BUTTON}
+            selectionOnDrag={tool === "select" && !readOnly}
+            selectionMode={SelectionMode.Full}
+            multiSelectionKeyCode={MULTI_KEYS}
+            deleteKeyCode={null}
+            nodesDraggable={!readOnly && (tool === "select" || placing)}
+            nodesConnectable={!readOnly}
+            elementsSelectable={!readOnly && tool !== "hand"}
+            elevateNodesOnSelect={false}
+            elevateEdgesOnSelect
+            minZoom={0.1}
+            maxZoom={4}
+            fitView={!viewportRef.current}
+            fitViewOptions={FIT_OPTIONS}
+            defaultViewport={viewportRef.current ?? undefined}
+            proOptions={proOptions}
+            attributionPosition={narrow ? "top-left" : "bottom-center"}
+            colorMode="light"
+            aria-label={label}
+          >
+            <Background variant={BackgroundVariant.Dots} gap={grid} size={1.6} />
+            {minimap && !narrow ? <MiniMap pannable zoomable ariaLabel="Minimap" position="bottom-right" nodeBorderRadius={6} className="bottom-14!" /> : null}
+            {draft ? (
+              <ViewportPortal>
+                <div
+                  aria-hidden="true"
+                  className="absolute top-0 left-0 rounded-md border-2 border-dashed border-primary bg-primary/5"
+                  style={{ transform: `translate(${draft.x}px, ${draft.y}px)`, width: draft.width, height: draft.height }}
+                />
+              </ViewportPortal>
+            ) : null}
+          </ReactFlow>
+        </ContextMenu>
+
+        {isEmpty && !readOnly && emptyState !== false && !listView && tool === "select" ? (
+          emptyState ? (
+            <div className="pointer-events-none absolute inset-0 grid place-items-center p-6">
+              <div className="fc-chrome pointer-events-auto">{emptyState}</div>
+            </div>
+          ) : (
+            <EmptyState
+              templates={templates}
+              narrow={narrow}
+              onTemplate={(t) => {
+                const b = typeof t.board === "function" ? t.board() : t.board;
+                api.setBoard(b);
+                say(`${t.label} template added`);
+              }}
+            />
+          )
+        ) : null}
+
+        {showToolbar && selBox ? (
+          <Floating at={selBox}>
+            <SelectionToolbar nodes={selectedNodes} api={api} palette={palette} extra={toolbarExtra} />
+          </Floating>
+        ) : null}
+        {edgeBar ? (
+          <Floating at={edgeBar.at}>
+            <EdgeToolbar id={edgeBar.edge.id} data={edgeBar.edge.data} label={edgeBar.edge.label} />
+          </Floating>
+        ) : null}
+
+        {topBar ? <div className="pointer-events-none absolute inset-x-3 top-3 z-10 flex justify-center [&>*]:pointer-events-auto">{topBar}</div> : null}
+
+        {!readOnly ? (
+          <div className={cx("pointer-events-none absolute z-10 flex gap-2", narrow ? "inset-x-3 bottom-3 flex-col-reverse items-center" : "inset-y-3 left-3 flex-row items-center")}>
+            <ToolRail items={railItems} tool={tool} onPick={pickTool} narrow={narrow} />
+            <ToolFlyout tool={tool} palette={palette} stickyColor={stickyColor} onStickyColor={setStickyColor} shapeKind={shapeKind} onShapeKind={setShapeKind} />
+          </div>
+        ) : null}
+
+        {!readOnly ? (
+          <div className={cx("absolute left-3 z-10", narrow ? (tool === "sticky" || tool === "shape" ? "bottom-32" : "bottom-20") : "bottom-3")}>
+            <HistoryBar canUndo={history.past.length > 0} canRedo={history.future.length > 0} onUndo={undo} onRedo={redo} save={save} onRetry={() => runSave(currentBoard())} />
+          </div>
+        ) : null}
+
+        <div className={cx("absolute right-3 z-10", narrow ? (topBar ? "top-16" : "top-3") : "bottom-3")}>
+          <ZoomBar
+            zoom={<ZoomLevel />}
+            narrow={narrow}
+            presentation={presentation}
+            onZoomIn={() => rf.zoomIn({ duration })}
+            onZoomOut={() => rf.zoomOut({ duration })}
+            onZoomTo={(z) => rf.zoomTo(z, { duration })}
+            onFit={() => fitView()}
+            onFitSelection={() => fitView({ nodes: selectedNodes.map((n) => ({ id: n.id })), maxZoom: 2 })}
+            hasSelection={selectedNodes.length > 0}
+            minimap={minimap}
+            onMinimap={setMinimap}
+            list={listView}
+            onList={setListView}
+            snap={snap}
+            onSnap={setSnap}
+            onShortcuts={() => setSheet(true)}
+          />
+        </div>
+
+        {presentation ? (
+          <div className="pointer-events-none absolute inset-x-3 bottom-3 z-10 flex justify-center">
+            <PresentBar
+              index={slide}
+              count={frames.length}
+              title={frames[slide]?.data?.title || "Untitled frame"}
+              onPrev={() => goSlide(slide - 1)}
+              onNext={() => goSlide(slide + 1)}
+              onExit={onExitPresentation}
+            />
+          </div>
+        ) : null}
+
+        {connectMenu ? <ConnectMenu at={connectMenu.at} items={connectItems} onClose={() => setConnectMenu(null)} /> : null}
+
+        {listView ? (
+          <ListView
+            board={board}
+            label={label}
+            describe={describeNode}
+            iconOf={(n) => toolById.get(n.type)?.icon}
+            onClose={() => setListView(false)}
+            onPick={(id) => {
+              setListView(false);
+              requestAnimationFrame(() => focusNode(id));
+            }}
+          />
+        ) : null}
+
+        <ShortcutsSheet open={sheet} onClose={() => setSheet(false)} tools={railItems} />
+      </div>
+    </CanvasContext.Provider>
+  );
+}
+