makersclaw 0.1.0 → 0.3.0

package/registry/blocks/mind-map/mind-map.jsx

@@ -0,0 +1,1125 @@
+"use client";
+
+// MindMap — a mind map you can drive from the keyboard alone, on
+// FlowCanvas. The centre topic, main branches balanced on both sides, each
+// branch a tidy tree in its own chart hue. Tab adds a subtopic, Enter the
+// next topic, typing renames, arrows walk the map, ⌘↑/⌘↓ fold; drag a
+// topic onto another to move its branch there.
+//
+// The map is a tree of topics (tree.js), and this component owns it: every
+// change makes a new tree, pushes the old one on the undo stack, lays the
+// tree out again and hands the canvas the result as its `value`. The
+// canvas runs read-only (its own tools, stickies and undo never see this
+// map); pointer and keys come through this component instead, and the
+// canvas pans, zooms, fits and draws.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Button, Icon, IconButton, Kbd, Menu, Popover, Separator, Sheet, ToggleGroup, Tooltip, cx, toast } from "../../ui";
+import { ColorDot, FlowCanvas, Palette, useFlowCanvas } from "../flow-canvas";
+import { MindContext, NODE_TYPES } from "./topic";
+import {
+  BRANCH_COLORS,
+  countTopics,
+  createTopic,
+  duplicateTopic,
+  estimateText,
+  findTopic,
+  indentTopic,
+  insertSibling,
+  insertTopic,
+  isWithin,
+  mindMapTemplates,
+  mindMapToBoard,
+  mindMapToMarkdown,
+  mindMapToText,
+  moveTopic,
+  normalizeMap,
+  outdentTopic,
+  outlineToTopics,
+  parentOf,
+  pathTo,
+  removeTopic,
+  setAllCollapsed,
+  shiftTopic,
+  updateTopic,
+} from "./tree";
+
+const HISTORY = 100;
+const EDITING_TARGET = 'input,textarea,select,[contenteditable="true"],[contenteditable="plaintext-only"],[role="dialog"],[role="menu"],[popover],button,a[href]';
+const EXTRA_COLORS = ["warning", "success", "info", "destructive"];
+const isMac = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent || "");
+
+// Measures words in the map's own font (a canvas's measureText), so a
+// topic's box fits its words exactly. Until the page is there (the
+// server), a guess. Measured again once mounted (the font of the element
+// the map sits in, not the body's) and when web fonts finish loading.
+function useMeasure(hostRef) {
+  const [tick, setTick] = useState(0);
+  const r = useRef({ ctx: null, family: null, cache: new Map() });
+  useEffect(() => {
+    let live = true;
+    const again = () => {
+      if (!live) return;
+      r.current.cache.clear();
+      r.current.family = null;
+      setTick((t) => t + 1);
+    };
+    again();
+    document.fonts?.ready?.then(again);
+    document.fonts?.addEventListener?.("loadingdone", again);
+    return () => {
+      live = false;
+      document.fonts?.removeEventListener?.("loadingdone", again);
+    };
+  }, []);
+  return useCallback(
+    (text, style) => {
+      if (typeof document === "undefined") return estimateText(text, style);
+      const c = r.current;
+      if (!c.ctx) c.ctx = document.createElement("canvas").getContext("2d");
+      if (!c.ctx) return estimateText(text, style);
+      if (!c.family) {
+        const cs = getComputedStyle(hostRef.current ?? document.body);
+        c.family = cs.fontFamily || "system-ui, sans-serif";
+        // A theme's tracking widens the words too (canvas text has it in
+        // current browsers; elsewhere the +2px slack covers a little).
+        if ("letterSpacing" in c.ctx) c.ctx.letterSpacing = cs.letterSpacing === "normal" ? "0px" : cs.letterSpacing;
+      }
+      const key = `${style.weight}|${style.font}|${text}`;
+      let w = c.cache.get(key);
+      if (w === undefined) {
+        c.ctx.font = `${style.weight} ${style.font}px ${c.family}`;
+        w = c.ctx.measureText(text).width;
+        if (c.cache.size > 4000) c.cache.clear();
+        c.cache.set(key, w);
+      }
+      return w;
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tick],
+  );
+}
+
+function useCoarsePointer() {
+  const [coarse, setCoarse] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia("(pointer: coarse)");
+    const on = () => setCoarse(mq.matches);
+    on();
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, []);
+  return coarse;
+}
+
+async function settle(fn, ...args) {
+  try {
+    const res = await fn(...args);
+    return res && res.ok === false ? { state: "error", error: res.error || "Couldn't save" } : { state: "saved" };
+  } catch (e) {
+    return { state: "error", error: e?.message || "Couldn't save" };
+  }
+}
+
+export function MindMap({
+  value,
+  defaultValue,
+  onChange,
+  onSave,
+  changeDelay = 400,
+  readOnly = false,
+  colors = BRANCH_COLORS,
+  templates,
+  placeholder = "New topic",
+  height = 600,
+  label = "Mind map",
+  onSelectionChange,
+  className,
+}) {
+  const boxRef = useRef(null);
+  const measure = useMeasure(boxRef);
+  const coarse = useCoarsePointer();
+  const canvas = useFlowCanvas();
+  const cbs = useRef({});
+  cbs.current = { onChange, onSave, onSelectionChange, changeDelay, readOnly };
+
+  // ── the tree and its history ─────────────────────────────────────────
+  const [tree, setTreeState] = useState(() => normalizeMap(value ?? defaultValue));
+  const treeRef = useRef(tree);
+  const setTree = (next) => {
+    treeRef.current = next;
+    setTreeState(next);
+  };
+  const [hist, setHistState] = useState({ past: [], future: [] });
+  const histRef = useRef(hist);
+  const setHist = (h) => {
+    histRef.current = h;
+    setHistState(h);
+  };
+
+  const [selectedId, setSelectedState] = useState(null);
+  const selectedRef = useRef(null);
+  const [editing, setEditingState] = useState(null); // { id, isNew, before, prevText }
+  const editingRef = useRef(null);
+  const setEditing = (e) => {
+    editingRef.current = e;
+    setEditingState(e);
+  };
+  const select = useCallback((id) => {
+    selectedRef.current = id;
+    setSelectedState(id);
+  }, []);
+
+  // ── saving ───────────────────────────────────────────────────────────
+  const [save, setSave] = useState({ state: "idle" });
+  const timer = useRef(0);
+  const dirty = useRef(false);
+  const seq = useRef(0);
+  const lastEmitted = useRef(null);
+  const runSave = async (t) => {
+    const fn = cbs.current.onSave;
+    if (!fn) return;
+    const n = ++seq.current;
+    setSave({ state: "saving" });
+    const res = await settle(fn, t);
+    if (n === seq.current) setSave(res);
+  };
+  const emitNow = () => {
+    clearTimeout(timer.current);
+    if (!dirty.current) return;
+    dirty.current = false;
+    const t = treeRef.current;
+    lastEmitted.current = t;
+    cbs.current.onChange?.(t);
+    runSave(t);
+  };
+  const scheduleEmit = () => {
+    if (cbs.current.readOnly) return;
+    dirty.current = true;
+    clearTimeout(timer.current);
+    timer.current = setTimeout(emitNow, cbs.current.changeDelay ?? 400);
+  };
+  useEffect(
+    () => () => {
+      if (dirty.current) emitNow();
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  // A change the person made: the old tree goes on the undo stack.
+  const commit = (next, { push = true } = {}) => {
+    const cur = treeRef.current;
+    if (next === cur) return false;
+    if (push) setHist({ past: [...histRef.current.past, cur].slice(-HISTORY), future: [] });
+    setTree(next);
+    scheduleEmit();
+    return true;
+  };
+
+  // Controlled: a `value` that is not our own echo replaces the map (and
+  // can be undone).
+  const lastProp = useRef(value);
+  useEffect(() => {
+    if (value === undefined || value === lastProp.current) return;
+    lastProp.current = value;
+    if (value === lastEmitted.current) return;
+    const next = normalizeMap(value);
+    setHist({ past: [...histRef.current.past, treeRef.current].slice(-HISTORY), future: [] });
+    setTree(next);
+    if (selectedRef.current && !findTopic(next, selectedRef.current)) select(null);
+    if (editingRef.current) setEditing(null);
+  }, [value, select]);
+
+  // ── what the canvas draws ────────────────────────────────────────────
+  const board = useMemo(() => mindMapToBoard(tree, { measure, colors }), [tree, measure, colors]);
+  const sizes = useMemo(() => new Map(board.nodes.map((n) => [n.id, n])), [board]);
+
+  // Fit the map in view once its words are measured. The canvas fits only
+  // on its own first mount, before the topics are sized in the map's font
+  // (and again when web fonts land), so without this the map opened off to
+  // the top-left of an empty-looking canvas (2026-09-24).
+  useEffect(() => {
+    // Two frames after a short settle: the canvas syncs the new sizes from
+    // `value` in an effect of its own, and fits against what it holds.
+    let raf = 0;
+    const t = setTimeout(() => {
+      raf = requestAnimationFrame(() => (raf = requestAnimationFrame(() => canvas.current?.fitView({ duration: 0 }))));
+    }, 300);
+    return () => (clearTimeout(t), cancelAnimationFrame(raf));
+  }, [measure]);
+
+  // The canvas pans with a plain drag (its hand tool): a mind map has
+  // nothing to lasso.
+  const hand = useCallback(() => {
+    const api = canvas.current;
+    if (api && api.getTool?.() !== "hand") api.setTool("hand");
+  }, [canvas]);
+  useEffect(() => {
+    let raf = 0;
+    let tries = 0;
+    const wait = () => {
+      if (canvas.current) return hand();
+      if (tries++ < 120) raf = requestAnimationFrame(wait);
+    };
+    wait();
+    return () => cancelAnimationFrame(raf);
+  }, [canvas, hand]);
+
+  // Keep a topic in view: centre it at the zoom there is, only when it is
+  // (partly) off screen.
+  const ensureVisible = useCallback(
+    (id, tries = 3) => {
+      const host = boxRef.current;
+      const el = host?.querySelector(`[data-topic="${CSS.escape(id)}"]`);
+      if (!el) {
+        if (tries > 0) setTimeout(() => ensureVisible(id, tries - 1), 60);
+        return;
+      }
+      const r = el.getBoundingClientRect();
+      const c = host.getBoundingClientRect();
+      const pad = 32;
+      if (r.left >= c.left + pad && r.right <= c.right - pad && r.top >= c.top + pad + 8 && r.bottom <= c.bottom - pad - 40) return;
+      const w = sizes.get(id)?.width;
+      const zoom = w ? r.width / w : 1;
+      canvas.current?.fitView({ nodes: [{ id }], minZoom: zoom, maxZoom: zoom, padding: 0.5 });
+    },
+    [canvas, sizes],
+  );
+
+  // ── editing words ────────────────────────────────────────────────────
+  const setText = useCallback((id, text) => {
+    const next = updateTopic(treeRef.current, id, { text });
+    setTree(next);
+    scheduleEmit();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const startEdit = useCallback(
+    (id, { replace, isNew = false, before } = {}) => {
+      if (readOnly) return;
+      const cur = treeRef.current;
+      const t = findTopic(cur, id);
+      if (!t) return;
+      select(id);
+      const ed = { id, isNew, before: before ?? cur, prevText: t.text };
+      if (replace !== undefined) setTree(updateTopic(cur, id, { text: replace }));
+      setEditing(ed);
+    },
+    [readOnly, select],
+  );
+
+  /** End the words' edit. Empty: a topic just made goes away (as if it
+   *  never was), an old one gets its words back. */
+  const finishEdit = useCallback((id) => {
+    const ed = editingRef.current;
+    if (!ed || (id && ed.id !== id)) return;
+    setEditing(null);
+    const cur = treeRef.current;
+    const t = findTopic(cur, ed.id);
+    if (!t) return;
+    const text = String(t.text ?? "").replace(/\s+$/, "").replace(/^\s+/, "");
+    if (!text) {
+      if (ed.isNew && ed.id !== cur.id) {
+        const prev = neighbourAfterRemove(cur, ed.id);
+        setTree(removeTopic(cur, ed.id));
+        const past = histRef.current.past;
+        if (past[past.length - 1] === ed.before) setHist({ past: past.slice(0, -1), future: histRef.current.future });
+        select(prev);
+      } else {
+        setTree(updateTopic(cur, ed.id, { text: ed.prevText }));
+      }
+      scheduleEmit();
+      return;
+    }
+    if (text !== t.text) setTree(updateTopic(cur, ed.id, { text }));
+    if (!ed.isNew && text !== ed.prevText) setHist({ past: [...histRef.current.past, ed.before].slice(-HISTORY), future: [] });
+    scheduleEmit();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // ── changing the map ─────────────────────────────────────────────────
+  const addChild = useCallback(
+    (parentId) => {
+      if (readOnly) return;
+      finishEdit();
+      const cur = treeRef.current;
+      if (!findTopic(cur, parentId)) return;
+      const t = createTopic("");
+      commit(insertTopic(cur, parentId, t));
+      startEdit(t.id, { isNew: true, before: cur });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [readOnly, finishEdit, startEdit],
+  );
+
+  const addSibling = useCallback(
+    (id, { before = false } = {}) => {
+      if (readOnly) return;
+      finishEdit();
+      const cur = treeRef.current;
+      if (id === cur.id) return addChild(id);
+      const t = createTopic("");
+      commit(insertSibling(cur, id, t, { before }));
+      startEdit(t.id, { isNew: true, before: cur });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [readOnly, finishEdit, startEdit, addChild],
+  );
+
+  const remove = useCallback(
+    (id) => {
+      if (readOnly) return;
+      const cur = treeRef.current;
+      const t = findTopic(cur, id);
+      if (!t || id === cur.id) return;
+      setEditing(null);
+      const next = neighbourAfterRemove(cur, id);
+      commit(removeTopic(cur, id));
+      select(next);
+      const n = countTopics(t);
+      toast(`Deleted “${clip(t.text) || "Untitled"}”${n ? ` and ${n} under it` : ""}`, { action: { label: "Undo", onClick: () => undoRef.current?.() } });
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [readOnly, select],
+  );
+
+  const toggleFold = useCallback(
+    (id, want) => {
+      const cur = treeRef.current;
+      const t = findTopic(cur, id);
+      if (!t || !t.children?.length || id === cur.id) return;
+      const on = want ?? !t.collapsed;
+      if (Boolean(t.collapsed) === on) return;
+      if (readOnly) setTree(updateTopic(cur, id, { collapsed: on }));
+      else commit(updateTopic(cur, id, { collapsed: on }));
+      // A fold under the selection hides it: the selection moves up.
+      const sel = selectedRef.current;
+      if (on && sel && sel !== id && isWithin(cur, id, sel)) select(id);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [readOnly, select],
+  );
+
+  const setColor = (id, color) => {
+    const cur = treeRef.current;
+    if (!findTopic(cur, id) || id === cur.id) return;
+    commit(updateTopic(cur, id, { color }));
+  };
+
+  const restructure = (fn, id, { keepEditing = false } = {}) => {
+    const cur = treeRef.current;
+    const next = fn(cur, id);
+    if (next === cur) return;
+    if (keepEditing && editingRef.current?.isNew) {
+      // A topic still being made: its creation is the undo step.
+      setTree(next);
+      scheduleEmit();
+    } else commit(next);
+    select(id);
+  };
+
+  const undo = () => {
+    finishEdit();
+    const h = histRef.current;
+    if (!h.past.length) return;
+    const prev = h.past[h.past.length - 1];
+    setHist({ past: h.past.slice(0, -1), future: [treeRef.current, ...h.future].slice(0, HISTORY) });
+    setTree(prev);
+    if (selectedRef.current && !findTopic(prev, selectedRef.current)) select(null);
+    scheduleEmit();
+    say("Undone");
+  };
+  const redo = () => {
+    finishEdit();
+    const h = histRef.current;
+    if (!h.future.length) return;
+    const [next, ...future] = h.future;
+    setHist({ past: [...h.past, treeRef.current].slice(-HISTORY), future });
+    setTree(next);
+    if (selectedRef.current && !findTopic(next, selectedRef.current)) select(null);
+    scheduleEmit();
+    say("Redone");
+  };
+  const undoRef = useRef(undo);
+  undoRef.current = undo;
+
+  const loadMap = (map) => {
+    finishEdit();
+    commit(normalizeMap(map));
+    select(null);
+    setTimeout(() => canvas.current?.fitView(), 80);
+  };
+
+  // ── announcements ────────────────────────────────────────────────────
+  const [announce, setAnnounce] = useState("");
+  const say = (msg) => setAnnounce((m) => (m === msg ? `${msg} ` : msg));
+
+  // Selection: tell the page, keep it in view, and keep the keyboard's
+  // focus on it (so a reader hears it).
+  useEffect(() => {
+    const t = selectedId ? findTopic(treeRef.current, selectedId) : null;
+    cbs.current.onSelectionChange?.(t ?? null);
+    if (!selectedId || editing) return;
+    if (t) {
+      const path = pathTo(treeRef.current, selectedId);
+      const kids = t.children?.length ?? 0;
+      say(`${t.text || "Untitled"}${path.length > 1 ? `, level ${path.length - 1}` : ", centre"}${kids ? `, ${kids} subtopic${kids === 1 ? "" : "s"}${t.collapsed ? ", folded" : ""}` : ""}`);
+    }
+    const raf = requestAnimationFrame(() => {
+      const host = boxRef.current;
+      if (!host) return;
+      const el = host.querySelector(`.react-flow__node[data-id="${CSS.escape(selectedId)}"]`);
+      if (el && host.contains(document.activeElement) && document.activeElement !== el && !document.activeElement?.closest?.("[role=textbox]")) el.focus({ preventScroll: true });
+      ensureVisible(selectedId);
+    });
+    return () => cancelAnimationFrame(raf);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedId, editing]);
+  useEffect(() => {
+    if (editing) ensureVisible(editing.id);
+  }, [editing, ensureVisible]);
+
+  // ── moving with the keys ─────────────────────────────────────────────
+  const itemsById = useMemo(() => new Map(board.nodes.map((n) => [n.id, n])), [board]);
+  const navigate = (key) => {
+    const cur = treeRef.current;
+    const id = selectedRef.current;
+    const me = itemsById.get(id);
+    if (!me) return select(cur.id);
+    const side = me.data.side;
+    const cy = me.position.y + me.height / 2;
+    const nearest = (list) => list.sort((a, b) => Math.abs(a.position.y + a.height / 2 - cy) - Math.abs(b.position.y + b.height / 2 - cy))[0];
+    const t = findTopic(cur, id);
+    const kidsOn = (s) => (t.children ?? []).map((c) => itemsById.get(c.id)).filter((n) => n && (s === undefined || n.data.side === s));
+    const outward = side === "left" ? "ArrowLeft" : "ArrowRight";
+    if (side === "root") {
+      if (key === "ArrowRight" || key === "ArrowLeft") {
+        const hit = nearest(kidsOn(key === "ArrowRight" ? "right" : "left"));
+        if (hit) select(hit.id);
+      }
+      return;
+    }
+    if (key === outward) {
+      if (t.collapsed && t.children?.length) {
+        toggleFold(id, false);
+        select(t.children[0].id);
+        return;
+      }
+      const hit = nearest(kidsOn());
+      if (hit) select(hit.id);
+      return;
+    }
+    if (key === "ArrowLeft" || key === "ArrowRight") return select(parentOf(cur, id)?.id ?? cur.id);
+    // Up and down: the nearest topic above or below in the same column
+    // (same side, same depth) — a sibling, or a cousin across a gap.
+    const down = key === "ArrowDown";
+    const column = board.nodes.filter((n) => n.id !== id && n.data.side === side && n.data.depth === me.data.depth);
+    const cand = column
+      .map((n) => ({ n, d: n.position.y + n.height / 2 - cy }))
+      .filter(({ d }) => (down ? d > 1 : d < -1))
+      .sort((a, b) => Math.abs(a.d) - Math.abs(b.d));
+    if (cand[0]) select(cand[0].n.id);
+  };
+
+  // ── the keyboard ─────────────────────────────────────────────────────
+  const [help, setHelp] = useState(false);
+  const onKeyDownCapture = (e) => {
+    if (e.nativeEvent.isComposing) return;
+    const target = e.target;
+    const k = e.key;
+    const mod = e.metaKey || e.ctrlKey;
+    const done = () => {
+      e.preventDefault();
+      e.stopPropagation();
+    };
+    const cur = treeRef.current;
+    const ed = editingRef.current;
+
+    // Typing a topic's words.
+    if (ed && target?.closest?.("[role=textbox]")) {
+      const t = findTopic(cur, ed.id);
+      const empty = !String(t?.text ?? "").trim();
+      const isRoot = ed.id === cur.id;
+      if (k === "Enter" && !e.shiftKey) {
+        done();
+        if (mod || isRoot) return finishEdit();
+        if (empty && ed.isNew) {
+          // An empty new line: step out a level, or stop.
+          if (pathTo(cur, ed.id).length >= 3) return restructure(outdentTopic, ed.id, { keepEditing: true });
+          return finishEdit();
+        }
+        finishEdit();
+        return addSibling(ed.id);
+      }
+      if (k === "Tab") {
+        done();
+        if (isRoot) {
+          finishEdit();
+          return addChild(cur.id);
+        }
+        if (e.shiftKey) return restructure(outdentTopic, ed.id, { keepEditing: true });
+        if (empty && ed.isNew) return restructure(indentTopic, ed.id, { keepEditing: true });
+        finishEdit();
+        return addChild(ed.id);
+      }
+      if (k === "Escape") {
+        done();
+        return finishEdit();
+      }
+      if (k === "Backspace" && empty && !isRoot && !(t?.children?.length)) {
+        done();
+        const prev = neighbourAfterRemove(cur, ed.id, { preferBefore: true });
+        setEditing(null);
+        if (ed.isNew) {
+          setTree(removeTopic(cur, ed.id));
+          const past = histRef.current.past;
+          if (past[past.length - 1] === ed.before) setHist({ past: past.slice(0, -1), future: histRef.current.future });
+          scheduleEmit();
+        } else commit(removeTopic(cur, ed.id));
+        if (prev && prev !== cur.id) startEdit(prev);
+        else select(prev);
+        return;
+      }
+      return;
+    }
+    if (target?.closest?.(EDITING_TARGET)) return;
+
+    const sel = selectedRef.current && findTopic(cur, selectedRef.current) ? selectedRef.current : null;
+    const low = k.length === 1 ? k.toLowerCase() : k;
+
+    if (k === "?" && !mod) return done(), setHelp(true);
+    if (mod && low === "z" && !readOnly) return done(), e.shiftKey ? redo() : undo();
+    if (mod && low === "y" && !readOnly) return done(), redo();
+    if (k === "Escape") {
+      if (sel) return done(), select(null);
+      setTimeout(hand, 0);
+      return;
+    }
+    if (!sel) {
+      if (k.startsWith("Arrow") || k === "Enter" || k === "Home") return done(), select(cur.id);
+      return;
+    }
+    if (k === "Home") return done(), select(cur.id);
+    if (k.startsWith("Arrow")) {
+      if (mod && (k === "ArrowUp" || k === "ArrowDown")) return done(), toggleFold(sel, k === "ArrowUp");
+      if (e.altKey && (k === "ArrowUp" || k === "ArrowDown")) return done(), !readOnly && restructure((r, id) => shiftTopic(r, id, k === "ArrowUp" ? -1 : 1), sel);
+      if (mod || e.altKey) return;
+      return done(), navigate(k);
+    }
+    if (readOnly) {
+      if (k === " " || k === "Enter") return done(), toggleFold(sel);
+      return;
+    }
+    if (k === "Tab") return done(), e.shiftKey ? restructure(outdentTopic, sel) : addChild(sel);
+    if (k === "Enter") return done(), addSibling(sel, { before: e.shiftKey });
+    if (k === " " || k === "F2") return done(), startEdit(sel);
+    if (k === "Delete" || k === "Backspace") return done(), remove(sel);
+    if (mod && low === "d") {
+      done();
+      const r = duplicateTopic(cur, sel);
+      if (r.id) {
+        commit(r.root);
+        select(r.id);
+      }
+      return;
+    }
+    // ⇧1 and ⇧2 stay the canvas's (fit, zoom to selection).
+    if (e.shiftKey && (e.code === "Digit1" || e.code === "Digit2")) return;
+    if (!mod && !e.altKey && k.length === 1) return done(), startEdit(sel, { replace: k });
+  };
+
+  // Copy, cut, paste: a branch as an outline, and an outline (from notes,
+  // a doc, an agent) as subtopics of the selection.
+  useEffect(() => {
+    const here = () => {
+      const a = document.activeElement;
+      return boxRef.current?.contains(a) && !a?.closest?.(EDITING_TARGET) && !a?.closest?.("[role=textbox]");
+    };
+    const copy = (e) => {
+      const id = selectedRef.current;
+      const t = id && findTopic(treeRef.current, id);
+      if (!here() || !t) return false;
+      e.clipboardData?.setData("text/plain", mindMapToText(t));
+      e.preventDefault();
+      e.stopPropagation();
+      return true;
+    };
+    const onCopy = (e) => {
+      if (copy(e)) say("Copied as an outline");
+    };
+    const onCut = (e) => {
+      if (readOnly) return;
+      const id = selectedRef.current;
+      if (id && id !== treeRef.current.id && copy(e)) remove(id);
+    };
+    const onPaste = (e) => {
+      if (!here() || readOnly) return;
+      const text = e.clipboardData?.getData("text/plain") ?? "";
+      const topics = outlineToTopics(text).slice(0, 200);
+      e.preventDefault();
+      e.stopPropagation();
+      if (!topics.length) return;
+      const cur = treeRef.current;
+      const parent = selectedRef.current && findTopic(cur, selectedRef.current) ? selectedRef.current : cur.id;
+      let next = cur;
+      for (const t of topics) next = insertTopic(next, parent, t);
+      commit(next);
+      select(topics[0].id);
+      say(`${topics.length} topic${topics.length === 1 ? "" : "s"} pasted`);
+    };
+    window.addEventListener("copy", onCopy, true);
+    window.addEventListener("cut", onCut, true);
+    window.addEventListener("paste", onPaste, true);
+    return () => {
+      window.removeEventListener("copy", onCopy, true);
+      window.removeEventListener("cut", onCut, true);
+      window.removeEventListener("paste", onPaste, true);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [readOnly]);
+
+  // ── the pointer: select, drag a topic onto another ───────────────────
+  const [drag, setDrag] = useState(null); // { id, text, x, y }
+  const [dropId, setDropId] = useState(null);
+  const onTopicPointerDown = useCallback(
+    (e, id) => {
+      if (editingRef.current && editingRef.current.id !== id) finishEdit();
+      select(id);
+      const cur = treeRef.current;
+      if (readOnly || id === cur.id || e.pointerType !== "mouse") return;
+      const start = { x: e.clientX, y: e.clientY };
+      let active = false;
+      let over = null;
+      const t = findTopic(cur, id);
+      const move = (ev) => {
+        if (!active && Math.hypot(ev.clientX - start.x, ev.clientY - start.y) < 5) return;
+        active = true;
+        const host = boxRef.current?.getBoundingClientRect();
+        if (!host) return;
+        const hit = document
+          .elementsFromPoint(ev.clientX, ev.clientY)
+          .map((el) => el.closest?.("[data-topic]"))
+          .find((el) => el && el.dataset.topic !== id);
+        const tid = hit?.dataset.topic ?? null;
+        over = tid && !isWithin(treeRef.current, id, tid) && parentOf(treeRef.current, id)?.id !== tid ? tid : null;
+        setDropId(over);
+        setDrag({ id, text: t?.text || "Untitled", x: ev.clientX - host.left, y: ev.clientY - host.top });
+      };
+      const up = () => {
+        window.removeEventListener("pointermove", move);
+        window.removeEventListener("pointerup", up);
+        window.removeEventListener("pointercancel", up);
+        if (!active) return;
+        setDrag(null);
+        setDropId(null);
+        if (!over) return;
+        const cur2 = treeRef.current;
+        const next = moveTopic(cur2, id, over);
+        if (next !== cur2) {
+          commit(next);
+          select(id);
+          const to = findTopic(next, over);
+          say(`Moved under ${to?.text || "Untitled"}`);
+        }
+      };
+      window.addEventListener("pointermove", move);
+      window.addEventListener("pointerup", up);
+      window.addEventListener("pointercancel", up);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [readOnly, finishEdit, select],
+  );
+
+  // A click on the empty canvas (not a pan) clears the selection.
+  const paneDown = useRef(null);
+  const onPointerDownCapture = (e) => {
+    paneDown.current = e.target?.classList?.contains("react-flow__pane") ? { x: e.clientX, y: e.clientY } : null;
+  };
+  const onPointerUpCapture = (e) => {
+    const p = paneDown.current;
+    paneDown.current = null;
+    if (!p || Math.hypot(e.clientX - p.x, e.clientY - p.y) > 4) return;
+    finishEdit();
+    select(null);
+  };
+
+  // ── the context the topics read ──────────────────────────────────────
+  const ctx = useMemo(
+    () => ({
+      selectedId,
+      editingId: editing?.id ?? null,
+      dropId,
+      dragId: drag?.id ?? null,
+      readOnly,
+      coarse,
+      placeholder,
+      onTopicPointerDown,
+      startEdit,
+      setText,
+      finishEdit,
+      toggleFold,
+      addChild,
+    }),
+    [selectedId, editing, dropId, drag, readOnly, coarse, placeholder, onTopicPointerDown, startEdit, setText, finishEdit, toggleFold, addChild],
+  );
+
+  // ── the chrome ───────────────────────────────────────────────────────
+  const [view, setView] = useState("map");
+  const selTopic = selectedId ? findTopic(tree, selectedId) : null;
+  const selIsRoot = selTopic?.id === tree.id;
+  const selColor = selectedId ? itemsById.get(selectedId)?.data.color : null;
+  const empty = !(tree.children?.length ?? 0);
+  const palette = useMemo(() => [...new Set([...colors, ...EXTRA_COLORS])], [colors]);
+  const starters = templates ?? mindMapTemplates();
+  const hint = editing
+    ? [["Enter", "next topic"], ["Tab", "subtopic"], ["Esc", "done"]]
+    : selTopic
+      ? readOnly
+        ? [["Arrows", "move"], ["Space", selTopic.collapsed ? "unfold" : "fold"]]
+        : [["Tab", "subtopic"], ["Enter", "topic"], ["Space", "rename"], ["⌫", "delete"]]
+      : [["Click", "a topic"], ["Drag", "to pan"], ["?", "shortcuts"]];
+  const copyMarkdown = async () => {
+    try {
+      await navigator.clipboard.writeText(mindMapToMarkdown(treeRef.current));
+      toast.success("Copied as Markdown");
+    } catch {
+      toast.error("Couldn't copy", { description: "Your browser kept the clipboard closed." });
+    }
+  };
+  const sized = /(^|\s)(h-|min-h-|size-|flex-1|grow)/.test(className ?? "");
+
+  return (
+    <section
+      aria-label={label}
+      className={cx("flex flex-col overflow-hidden rounded-lg border border-border bg-background text-foreground", className)}
+      style={sized ? undefined : { height }}
+    >
+      <header className="flex min-h-12 shrink-0 flex-wrap items-center gap-1 border-b border-border bg-card px-2 py-1.5 text-card-foreground">
+        {!readOnly ? (
+          <>
+            <Tooltip label={`Undo · ${isMac() ? "⌘" : "Ctrl+"}Z`}>
+              <IconButton icon="undo" label="Undo" size="sm" disabled={!hist.past.length} onClick={undo} />
+            </Tooltip>
+            <Tooltip label={`Redo · ${isMac() ? "⇧⌘Z" : "Ctrl+Shift+Z"}`}>
+              <IconButton icon="redo" label="Redo" size="sm" disabled={!hist.future.length} onClick={redo} />
+            </Tooltip>
+            <SaveState save={save} onRetry={() => runSave(treeRef.current)} />
+          </>
+        ) : (
+          <p className="px-2 text-sm font-medium">{clip(tree.text, 48) || "Mind map"}</p>
+        )}
+        <div className="flex-1" />
+        {view === "map" && !readOnly ? (
+          <div role="toolbar" aria-label="Topic" className="flex items-center gap-1">
+            <Tooltip label={selTopic && !selIsRoot ? "Add a topic below · Enter" : "Add a main topic"}>
+              <Button size="sm" variant="quiet" icon="plus" onClick={() => (selTopic ? addSibling(selTopic.id) : addChild(tree.id))} aria-label="Add topic">
+                <span className="max-sm:hidden">Topic</span>
+              </Button>
+            </Tooltip>
+            <Tooltip label="Add a subtopic · Tab">
+              <Button size="sm" variant="quiet" icon="git-branch" onClick={() => addChild(selTopic?.id ?? tree.id)} aria-label="Add subtopic">
+                <span className="max-sm:hidden">Subtopic</span>
+              </Button>
+            </Tooltip>
+            <Separator orientation="vertical" className="mx-0.5 h-5 max-sm:hidden" />
+            <Popover
+              label="Branch colour"
+              width="auto"
+              className="p-1.5"
+              trigger={(p) => (
+                <Button {...p} variant="quiet" size="sm" iconOnly aria-label="Branch colour" title="Branch colour" disabled={!selTopic || selIsRoot}>
+                  <ColorDot color={selColor ?? "muted"} />
+                </Button>
+              )}
+            >
+              <Palette colors={palette} value={selTopic?.color ?? selColor} swatch="dot" onPick={(c) => selTopic && setColor(selTopic.id, c)} label="Branch colour" />
+              {selTopic?.color ? (
+                <Button variant="quiet" size="sm" className="mt-1 w-full" onClick={() => setColor(selTopic.id, undefined)}>
+                  Use the branch's colour
+                </Button>
+              ) : null}
+            </Popover>
+            <Tooltip label={selTopic?.collapsed ? "Unfold · ⌘↓" : "Fold · ⌘↑"}>
+              <IconButton
+                icon={selTopic?.collapsed ? "eye" : "eye-off"}
+                label={selTopic?.collapsed ? "Unfold branch" : "Fold branch"}
+                size="sm"
+                disabled={!selTopic || selIsRoot || !selTopic.children?.length}
+                onClick={() => toggleFold(selTopic.id)}
+              />
+            </Tooltip>
+            <Tooltip label="Delete · ⌫">
+              <IconButton icon="trash" label="Delete topic" size="sm" disabled={!selTopic || selIsRoot} onClick={() => remove(selTopic.id)} />
+            </Tooltip>
+          </div>
+        ) : null}
+        <ToggleGroup
+          size="sm"
+          className="max-sm:hidden"
+          aria-label="View"
+          value={view}
+          onChange={setView}
+          items={[
+            { value: "map", label: "Map", icon: "git-branch", iconOnly: true },
+            { value: "outline", label: "Outline", icon: "list", iconOnly: true },
+          ]}
+        />
+        <Menu
+          label="Map actions"
+          items={[
+            { label: "Unfold everything", icon: "eye", onSelect: () => (readOnly ? setTree(setAllCollapsed(treeRef.current, false)) : commit(setAllCollapsed(treeRef.current, false))) },
+            { label: "Fold every branch", icon: "eye-off", onSelect: () => (readOnly ? setTree(setAllCollapsed(treeRef.current, true)) : commit(setAllCollapsed(treeRef.current, true))) },
+            { label: "Fit to screen", icon: "maximize", shortcut: "⇧1", onSelect: () => canvas.current?.fitView() },
+            { type: "checkbox", label: "Outline view", checked: view === "outline", onCheckedChange: (on) => setView(on ? "outline" : "map") },
+            { type: "separator" },
+            { label: "Copy as Markdown", icon: "copy", onSelect: copyMarkdown },
+            { label: "Keyboard shortcuts", icon: "keyboard", shortcut: "?", onSelect: () => setHelp(true) },
+          ]}
+        />
+      </header>
+
+      <div
+        ref={boxRef}
+        className="relative min-h-0 flex-1"
+        onKeyDownCapture={onKeyDownCapture}
+        onPointerDownCapture={onPointerDownCapture}
+        onPointerUpCapture={onPointerUpCapture}
+      >
+        <p className="sr-only" aria-live="polite">
+          {announce}
+        </p>
+        <div className="absolute inset-0" inert={view !== "map" || undefined} aria-hidden={view !== "map" || undefined}>
+          <MindContext.Provider value={ctx}>
+            <FlowCanvas
+              value={board}
+              readOnly
+              nodeTypes={NODE_TYPES}
+              canvasRef={canvas}
+              label={label}
+              height="100%"
+              bare
+              emptyState={false}
+              templates={[]}
+              describeNode={describeTopic}
+              className="[&_.react-flow__node]:transition-transform [&_.react-flow__node]:duration-200 [&_.react-flow__node]:ease-out motion-reduce:[&_.react-flow__node]:transition-none"
+            />
+          </MindContext.Provider>
+        </div>
+
+        {view === "map" && drag ? (
+          <div aria-hidden="true" className="pointer-events-none absolute z-20 grid -translate-x-1/2 -translate-y-[calc(100%+10px)] justify-items-center gap-1" style={{ left: drag.x, top: drag.y }}>
+            <span className="max-w-60 truncate rounded-lg border border-border bg-popover px-3 py-1.5 text-sm font-medium text-popover-foreground shadow-lg">{clip(drag.text, 40)}</span>
+            <span className="rounded-md bg-foreground px-2 py-0.5 text-xs text-background">{dropId ? `Move under “${clip(findTopic(tree, dropId)?.text, 24) || "Untitled"}”` : "Drop on a topic"}</span>
+          </div>
+        ) : null}
+
+        {view === "map" && empty && !readOnly && !editing ? (
+          <Starter templates={starters} onPick={(t) => loadMap(typeof t.map === "function" ? t.map() : t.map)} onStart={() => addChild(tree.id)} />
+        ) : null}
+
+        {view === "map" ? (
+          <div aria-hidden="true" className="pointer-events-none absolute bottom-3 left-3 z-10 hidden max-w-[calc(100%-12rem)] flex-wrap items-center gap-x-3 gap-y-1 rounded-lg border border-border bg-card/90 px-2.5 py-1.5 text-xs text-muted-foreground shadow-xs backdrop-blur-sm md:flex">
+            {hint.map(([key, what]) => (
+              <span key={key} className="flex items-center gap-1.5 whitespace-nowrap">
+                <Kbd>{key}</Kbd>
+                {what}
+              </span>
+            ))}
+          </div>
+        ) : null}
+
+        {view === "outline" ? (
+          <OutlineView
+            tree={tree}
+            items={itemsById}
+            onPick={(id) => {
+              setView("map");
+              // Open the folds on the way down, so the topic can be seen.
+              const path = pathTo(treeRef.current, id);
+              let next = treeRef.current;
+              for (const p of path.slice(0, -1)) if (p.collapsed) next = updateTopic(next, p.id, { collapsed: false });
+              if (next !== treeRef.current) (readOnly ? setTree(next) : commit(next));
+              select(id);
+            }}
+            onCopy={copyMarkdown}
+          />
+        ) : null}
+      </div>
+
+      <Shortcuts open={help} onClose={() => setHelp(false)} readOnly={readOnly} />
+    </section>
+  );
+}
+
+// ── pieces ─────────────────────────────────────────────────────────────
+
+const clip = (s, n = 60) => {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+};
+
+function describeTopic(n) {
+  if (n.type !== "topic") return undefined;
+  const d = n.data ?? {};
+  return `${d.depth === 0 ? "Centre" : `Level ${d.depth}`}: "${clip(d.text) || "Untitled"}"${d.collapsed ? ` (folded, ${d.hidden} hidden)` : ""}`;
+}
+
+/** Where the selection goes when a topic leaves: the next sibling, else
+ *  the one before, else the parent. */
+function neighbourAfterRemove(root, id, { preferBefore = false } = {}) {
+  const parent = parentOf(root, id);
+  if (!parent) return root.id;
+  const kids = parent.children;
+  const i = kids.findIndex((c) => c.id === id);
+  const order = preferBefore ? [kids[i - 1], kids[i + 1]] : [kids[i + 1], kids[i - 1]];
+  return (order.find(Boolean) ?? parent).id;
+}
+
+function SaveState({ save, onRetry }) {
+  if (save.state === "error") {
+    return (
+      <div role="alert" className="flex min-w-0 items-center gap-1 pl-1 text-xs">
+        <Icon name="warning" size={14} className="shrink-0 text-destructive" />
+        <span className="truncate max-md:sr-only">{save.error || "Couldn't save"}</span>
+        <Button variant="quiet" size="sm" onClick={onRetry}>
+          Retry
+        </Button>
+      </div>
+    );
+  }
+  if (save.state === "idle") return null;
+  const saving = save.state === "saving";
+  return (
+    <p role="status" className="flex shrink-0 items-center gap-1 px-1 text-xs text-muted-foreground">
+      <Icon name={saving ? "loader" : "check"} size={14} className={cx(saving && "motion-safe:animate-spin")} />
+      <span className="max-sm:sr-only">{saving ? "Saving…" : "Saved"}</span>
+    </p>
+  );
+}
+
+/** The first run: how the map works, and a few starting points. */
+function Starter({ templates, onPick, onStart }) {
+  return (
+    <div className="pointer-events-none absolute inset-x-3 bottom-3 z-10 flex justify-center md:bottom-14">
+      <div className="pointer-events-auto w-full max-w-md rounded-xl border border-border bg-popover p-4 text-popover-foreground shadow-lg">
+        <p className="text-sm font-semibold">Start with the big idea</p>
+        <p className="mt-1 text-sm text-muted-foreground">
+          Double-click the centre to name it. <Kbd>Tab</Kbd> adds a branch, <Kbd>Enter</Kbd> the next one — no mouse needed.
+        </p>
+        <div className="mt-3 flex flex-wrap gap-2">
+          <Button size="sm" variant="primary" icon="plus" onClick={onStart}>
+            Add a branch
+          </Button>
+          {templates.map((t) => (
+            <Tooltip key={t.id} label={t.description ?? t.label}>
+              <Button size="sm" icon={t.icon} onClick={() => onPick(t)}>
+                {t.label}
+              </Button>
+            </Tooltip>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** The map as a nested list: the reading of it for a screen reader, and
+ *  a quick way to jump to a topic. */
+function OutlineView({ tree, items, onPick, onCopy }) {
+  const rows = [];
+  const walk = (t, depth, color) => {
+    const c = items.get(t.id)?.data.color ?? color;
+    rows.push({ t, depth, color: c });
+    for (const k of t.children ?? []) walk(k, depth + 1, c);
+  };
+  walk(tree, 0, null);
+  return (
+    <div className="absolute inset-0 z-10 overflow-y-auto bg-background">
+      <div className="mx-auto grid max-w-2xl gap-4 px-4 py-6 sm:px-6">
+        <div className="flex flex-wrap items-center justify-between gap-2">
+          <div className="min-w-0">
+            <h3 className="truncate text-base font-semibold">{tree.text || "Untitled"}</h3>
+            <p className="text-sm text-muted-foreground">
+              {countTopics(tree)} topic{countTopics(tree) === 1 ? "" : "s"}. Choose one to find it on the map.
+            </p>
+          </div>
+          <Button size="sm" icon="copy" onClick={onCopy}>
+            Copy as Markdown
+          </Button>
+        </div>
+        {rows.length > 1 ? (
+          <ul className="grid gap-0.5" aria-label="Outline">
+            {rows.slice(1).map(({ t, depth, color }) => (
+              <li key={t.id} style={{ paddingLeft: (depth - 1) * 20 }}>
+                <Button variant="quiet" size="sm" align="start" className="w-full min-w-0" onClick={() => onPick(t.id)}>
+                  <ColorDot color={color ?? "muted"} className={depth > 1 ? "size-2" : "size-2.5"} />
+                  <span className={cx("truncate", depth === 1 ? "font-medium" : "font-normal")}>{t.text || "Untitled"}</span>
+                  {t.collapsed && t.children?.length ? <span className="ml-auto shrink-0 text-xs text-muted-foreground tabular-nums">{countTopics(t)} folded</span> : null}
+                </Button>
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <div className="grid justify-items-center gap-2 rounded-lg border border-dashed border-border px-4 py-10 text-center">
+            <p className="text-sm text-muted-foreground">Only the centre so far. Branches you add show up here as a list.</p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const KEYS = [
+  ["Tab", "Add a subtopic"],
+  ["Enter", "Add the next topic (⇧ above)"],
+  ["Space", "Rename (or just start typing)"],
+  ["⌫", "Delete the topic and its branch"],
+  ["← → ↑ ↓", "Move around the map"],
+  ["⌥↑ ⌥↓", "Move the topic up or down"],
+  ["⇧Tab", "Move the topic up a level"],
+  ["⌘↑ ⌘↓", "Fold, unfold"],
+  ["⌘D", "Duplicate the branch"],
+  ["⌘C ⌘V", "Copy a branch, paste an outline"],
+  ["⌘Z", "Undo (⇧⌘Z redo)"],
+  ["⇧1", "Fit the map to the screen"],
+];
+const TYPING = [
+  ["Enter", "Next topic (an empty one steps out a level)"],
+  ["Tab", "Subtopic (an empty one moves in a level)"],
+  ["⇧Enter", "A new line in the words"],
+  ["Esc", "Done"],
+];
+
+function Shortcuts({ open, onClose, readOnly }) {
+  const mac = isMac();
+  const key = (k) => (mac ? k : k.replace(/⌘/g, "Ctrl+").replace(/⌥/g, "Alt+").replace(/⇧/g, "Shift+"));
+  const rows = readOnly ? [["← → ↑ ↓", "Move around the map"], ["Space", "Fold, unfold"], ["⇧1", "Fit the map to the screen"]] : KEYS;
+  const list = (items) => (
+    <dl className="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2 text-sm">
+      {items.map(([k, what]) => (
+        <div key={k} className="contents">
+          <dt className="justify-self-start">
+            <Kbd>{key(k)}</Kbd>
+          </dt>
+          <dd className="text-muted-foreground">{what}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+  return (
+    <Sheet open={open} onClose={onClose} title="Keyboard shortcuts" description="A mind map you can build without the mouse.">
+      <div className="grid gap-6">
+        <section className="grid gap-3">
+          <h3 className="text-sm font-medium">With a topic selected</h3>
+          {list(rows)}
+        </section>
+        {!readOnly ? (
+          <section className="grid gap-3">
+            <h3 className="text-sm font-medium">While typing a topic</h3>
+            {list(TYPING)}
+          </section>
+        ) : null}
+      </div>
+    </Sheet>
+  );
+}