makersclaw 0.2.0 → 0.3.1

package/registry/blocks/flow-canvas/board.js

@@ -0,0 +1,819 @@
+// The board as data — plain functions, no React, no React Flow. They run
+// anywhere (the server, a script, an agent's tool) and never throw on a
+// partial board. FlowCanvas uses the same functions, so what an agent
+// reads with boardToText is what the person sees.
+//
+// A board is plain JSON an app stores in one jsonb column:
+//   { nodes: [{ id, type, position: { x, y }, width?, height?, data, zIndex?,
+//               draggable?, deletable?, selectable?, connectable? }],
+//     edges: [{ id, source, target, label?, data?: { line, arrow, dashed } }],
+//     viewport?: { x, y, zoom } }
+// Positions are absolute (a card in a frame is NOT stored relative to it):
+// a frame holds whatever lies inside its rectangle.
+
+export const GRID = 20;
+
+/** Colours a person can pick, as TOKEN names — the board stores these, never
+ *  a colour value, so a board repaints with the workspace theme. */
+export const COLORS = ["warning", "chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "success", "info", "destructive", "muted"];
+/** The sticky palette the rail and the toolbar offer by default. */
+export const STICKY_COLORS = ["warning", "chart-2", "chart-3", "chart-4", "chart-5", "muted"];
+export const COLOR_NAMES = {
+  warning: "Yellow",
+  "chart-1": "Theme colour",
+  "chart-2": "Colour 2",
+  "chart-3": "Colour 3",
+  "chart-4": "Colour 4",
+  "chart-5": "Colour 5",
+  success: "Green",
+  info: "Blue",
+  destructive: "Red",
+  muted: "Grey",
+};
+// The chart tokens are derived from each workspace's primary colour, so
+// they get numbers, not hue names: "Colour 3" is violet in one theme and
+// orange in another. Labels only; the board stores the token.
+
+export const SHAPES = ["rect", "ellipse", "diamond", "pill"];
+export const SHAPE_NAMES = { rect: "Rectangle", ellipse: "Ellipse", diamond: "Diamond", pill: "Pill" };
+export const TEXT_SIZES = ["sm", "md", "lg", "xl"];
+export const TEXT_SIZE_PX = { sm: 14, md: 18, lg: 24, xl: 36 };
+export const LINES = ["curved", "straight", "elbow"];
+export const ARROWS = ["end", "both", "none"];
+
+/** Default size per built-in type. `height: undefined` grows with content. */
+export const SIZES = {
+  sticky: { width: 200, height: 200 },
+  shape: { width: 160, height: 100 },
+  text: { width: 240, height: undefined },
+  frame: { width: 560, height: 360 },
+  card: { width: 260, height: undefined },
+  image: { width: 280, height: 180 },
+};
+const SHAPE_SIZES = { rect: [160, 100], ellipse: [160, 110], diamond: [160, 120], pill: [180, 64] };
+/** Types whose height follows their content unless someone resized them. */
+export const AUTO_HEIGHT = new Set(["text", "card"]);
+/** Types whose words edit in place on double-click / Enter. */
+export const EDITABLE = new Set(["sticky", "shape", "text", "frame", "card"]);
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const num = (v, d = 0) => (typeof v === "number" && Number.isFinite(v) ? v : d);
+
+let seq = 0;
+/** A fresh id: `sticky-lx3k9f2a`. Unique enough for a board. */
+export function makeId(prefix = "n") {
+  seq = (seq + 1) % 1296;
+  return `${prefix}-${Date.now().toString(36)}${seq.toString(36).padStart(2, "0")}${Math.floor(Math.random() * 1296)
+    .toString(36)
+    .padStart(2, "0")}`;
+}
+
+/** An empty board. */
+export function emptyBoard() {
+  return { nodes: [], edges: [] };
+}
+
+/** Nodes and edges out of anything board-shaped; never throws. */
+export function readBoard(board) {
+  const nodes = Array.isArray(board?.nodes) ? board.nodes.filter((n) => isObj(n) && n.id != null) : [];
+  const ids = new Set(nodes.map((n) => String(n.id)));
+  const edges = Array.isArray(board?.edges)
+    ? board.edges.filter((e) => isObj(e) && e.id != null && ids.has(String(e.source)) && ids.has(String(e.target)))
+    : [];
+  return { nodes, edges, viewport: isObj(board?.viewport) ? board.viewport : undefined };
+}
+
+const NODE_KEYS = ["id", "type", "position", "width", "height", "data", "zIndex", "draggable", "deletable", "selectable", "connectable"];
+const EDGE_KEYS = ["id", "source", "target", "label", "data"];
+
+/** The board as it is stored: React Flow's working fields (selected,
+ *  dragging, measured…) dropped, and nothing but JSON left. */
+export function cleanBoard(board, { viewport = true } = {}) {
+  const { nodes, edges, viewport: vp } = readBoard(board);
+  const out = {
+    nodes: nodes.map((n) => {
+      const o = {};
+      for (const k of NODE_KEYS) if (n[k] !== undefined && n[k] !== null) o[k] = n[k];
+      o.position = { x: Math.round(num(n.position?.x) * 100) / 100, y: Math.round(num(n.position?.y) * 100) / 100 };
+      if (typeof o.width === "number") o.width = Math.round(o.width);
+      if (typeof o.height === "number") o.height = Math.round(o.height);
+      o.data = isObj(n.data) ? n.data : {};
+      return o;
+    }),
+    edges: edges.map((e) => {
+      const o = {};
+      for (const k of EDGE_KEYS) if (e[k] !== undefined && e[k] !== null && e[k] !== "") o[k] = e[k];
+      return o;
+    }),
+  };
+  if (viewport && vp) out.viewport = { x: num(vp.x), y: num(vp.y), zoom: num(vp.zoom, 1) };
+  return out;
+}
+
+/** A string that changes when the board's content changes (not the view). */
+export function boardKey(board) {
+  const { nodes, edges } = cleanBoard(board, { viewport: false });
+  return JSON.stringify([nodes, edges]);
+}
+
+// ── geometry ─────────────────────────────────────────────────────────────
+
+/** A node's size: set, measured by React Flow, or its type's default. */
+export function nodeSize(node) {
+  const d = SIZES[node?.type] ?? { width: 200, height: 120 };
+  const width = num(node?.width, num(node?.measured?.width, d.width ?? 200));
+  const height = num(node?.height, num(node?.measured?.height, d.height ?? (node?.type === "text" ? 40 : 120)));
+  return { width, height };
+}
+
+/** { x, y, width, height } in board coordinates. */
+export function nodeRect(node) {
+  const { width, height } = nodeSize(node);
+  return { x: num(node?.position?.x), y: num(node?.position?.y), width, height };
+}
+
+const center = (r) => ({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+const inside = (p, r) => p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height;
+
+/** The rectangle around some nodes, or null. */
+export function boardBounds(nodes) {
+  const list = (nodes ?? []).filter(Boolean);
+  if (!list.length) return null;
+  let x1 = Infinity;
+  let y1 = Infinity;
+  let x2 = -Infinity;
+  let y2 = -Infinity;
+  for (const n of list) {
+    const r = nodeRect(n);
+    x1 = Math.min(x1, r.x);
+    y1 = Math.min(y1, r.y);
+    x2 = Math.max(x2, r.x + r.width);
+    y2 = Math.max(y2, r.y + r.height);
+  }
+  return { x: x1, y: y1, width: x2 - x1, height: y2 - y1 };
+}
+
+/** The ids of the nodes inside a frame: their centre lies in its rectangle.
+ *  Frames nested in it count, and so does what they hold. */
+export function frameContents(board, frameId) {
+  const { nodes } = readBoard(board);
+  const frame = nodes.find((n) => n.id === frameId);
+  if (!frame) return [];
+  const r = nodeRect(frame);
+  return nodes.filter((n) => n.id !== frameId && inside(center(nodeRect(n)), r) && area(nodeRect(n)) < area(r)).map((n) => n.id);
+}
+const area = (r) => r.width * r.height;
+
+/** The smallest frame each node sits in: Map(nodeId → frameId). */
+export function frameOf(board) {
+  const { nodes } = readBoard(board);
+  const frames = nodes.filter((n) => n.type === "frame").map((f) => ({ id: f.id, r: nodeRect(f) }));
+  const out = new Map();
+  for (const n of nodes) {
+    const c = center(nodeRect(n));
+    const a = area(nodeRect(n));
+    let best = null;
+    for (const f of frames) {
+      if (f.id === n.id || !inside(c, f.r) || area(f.r) <= a) continue;
+      if (!best || area(f.r) < area(best.r)) best = f;
+    }
+    if (best) out.set(n.id, best.id);
+  }
+  return out;
+}
+
+/** Round a point onto the grid. */
+export function snapPoint(p, grid = GRID) {
+  if (!grid) return { x: p.x, y: p.y };
+  return { x: Math.round(p.x / grid) * grid, y: Math.round(p.y / grid) * grid };
+}
+
+/**
+ * Put a rectangle into a cell — for boards with lanes or a grid (a journey
+ * map's stage × row). `cells` is [{ id, x, y, width, height }]. The cell
+ * is the one holding the rectangle's centre, else the nearest; the
+ * rectangle is kept inside it with `pad` to spare. Returns
+ * { x, y, cellId } or null when there are no cells.
+ */
+export function snapToCell(rect, cells, { pad = 8 } = {}) {
+  const list = (cells ?? []).filter((c) => c && num(c.width) > 0 && num(c.height) > 0);
+  if (!list.length) return null;
+  const c = center(rect);
+  let cell = list.find((k) => inside(c, k));
+  if (!cell) {
+    let best = Infinity;
+    for (const k of list) {
+      const dx = Math.max(k.x - c.x, 0, c.x - (k.x + k.width));
+      const dy = Math.max(k.y - c.y, 0, c.y - (k.y + k.height));
+      const d = dx * dx + dy * dy;
+      if (d < best) {
+        best = d;
+        cell = k;
+      }
+    }
+  }
+  const clamp = (v, lo, hi) => (hi < lo ? (lo + hi) / 2 : Math.min(Math.max(v, lo), hi));
+  return {
+    x: clamp(rect.x, cell.x + pad, cell.x + cell.width - pad - rect.width),
+    y: clamp(rect.y, cell.y + pad, cell.y + cell.height - pad - rect.height),
+    cellId: cell.id,
+  };
+}
+
+/** Where a connector leaves and enters: the sides of two rectangles that
+ *  face each other. → { source: "right", target: "left" } */
+export function facingSides(a, b) {
+  const ca = center(a);
+  const cb = center(b);
+  const dx = cb.x - ca.x;
+  const dy = cb.y - ca.y;
+  const horizontal = Math.abs(dx) / Math.max(1, a.width + b.width) >= Math.abs(dy) / Math.max(1, a.height + b.height);
+  if (horizontal) return dx >= 0 ? { source: "right", target: "left" } : { source: "left", target: "right" };
+  return dy >= 0 ? { source: "bottom", target: "top" } : { source: "top", target: "bottom" };
+}
+
+/** The midpoint of one side of a rectangle. */
+export function sidePoint(r, side) {
+  if (side === "left") return { x: r.x, y: r.y + r.height / 2 };
+  if (side === "right") return { x: r.x + r.width, y: r.y + r.height / 2 };
+  if (side === "top") return { x: r.x + r.width / 2, y: r.y };
+  return { x: r.x + r.width / 2, y: r.y + r.height };
+}
+
+/**
+ * The biggest font size (px) at which `text` fits a box — a sticky's words
+ * shrink as they grow. An estimate (no DOM): average glyph width `charWidth`
+ * em, lines wrap at words.
+ */
+export function fitFontSize(text, width, height, { min = 12, max = 30, lineHeight = 1.25, charWidth = 0.56 } = {}) {
+  const words = String(text ?? "").trim();
+  if (!words) return max;
+  const paras = words.split(/\n/);
+  const fits = (s) => {
+    const perLine = Math.max(1, Math.floor(width / (s * charWidth)));
+    let lines = 0;
+    for (const p of paras) {
+      let line = 0;
+      let count = 1;
+      for (const w of p.split(/\s+/).filter(Boolean)) {
+        if (w.length > perLine) {
+          // A long word breaks across lines.
+          const extra = Math.ceil(w.length / perLine);
+          count += line ? extra : extra - 1;
+          line = w.length % perLine;
+          continue;
+        }
+        const need = line ? line + 1 + w.length : w.length;
+        if (need > perLine) {
+          count += 1;
+          line = w.length;
+        } else line = need;
+      }
+      lines += count;
+    }
+    return lines * s * lineHeight <= height;
+  };
+  let lo = min;
+  let hi = max;
+  if (fits(hi)) return hi;
+  if (!fits(lo)) return lo;
+  while (hi - lo > 0.5) {
+    const mid = (lo + hi) / 2;
+    if (fits(mid)) lo = mid;
+    else hi = mid;
+  }
+  return Math.floor(lo);
+}
+
+// ── making and changing nodes ────────────────────────────────────────────
+
+const DATA = {
+  sticky: () => ({ text: "", color: "warning" }),
+  shape: () => ({ text: "", shape: "rect", color: "muted", textSize: "md" }),
+  text: () => ({ text: "", textSize: "md" }),
+  frame: () => ({ title: "Frame" }),
+  card: () => ({ title: "", body: "" }),
+  image: () => ({ src: "", alt: "" }),
+};
+
+/**
+ * A new node CENTRED on `point`, snapped to the grid, with its type's
+ * defaults (size, data). Custom types take `width`/`height` from opts
+ * (default 200×120).
+ *
+ *   createNode("sticky", { x: 400, y: 200 }, { data: { text: "Idea", color: "chart-3" } })
+ *   createNode("person", p, { width: 240, data: { name: "New person" } })
+ *
+ * With `rect` ({ x, y, width, height }) it fills that rectangle instead
+ * (a shape dragged out with the tool).
+ */
+export function createNode(type, point, { id, data, width, height, rect, grid = GRID, ...rest } = {}) {
+  const base = SIZES[type] ?? { width: 200, height: 120 };
+  const kind = type === "shape" ? data?.shape ?? "rect" : null;
+  const [sw, sh] = kind ? SHAPE_SIZES[kind] ?? SHAPE_SIZES.rect : [];
+  let w = num(rect?.width, num(width, sw ?? base.width));
+  let h = rect ? num(rect.height) : height !== undefined ? height : sh ?? base.height;
+  if (AUTO_HEIGHT.has(type) && !rect && height === undefined) h = undefined;
+  const at = rect ? { x: rect.x, y: rect.y } : { x: num(point?.x) - w / 2, y: num(point?.y) - num(h, 40) / 2 };
+  const node = {
+    id: id ?? makeId(type),
+    type,
+    position: snapPoint(at, grid),
+    data: { ...(DATA[type]?.() ?? {}), ...(data ?? {}) },
+    ...rest,
+  };
+  if (w !== undefined) node.width = grid ? Math.max(grid, Math.round(w / grid) * grid) : w;
+  if (h !== undefined) node.height = grid ? Math.max(grid, Math.round(h / grid) * grid) : h;
+  if (type === "frame" && node.zIndex === undefined) node.zIndex = -1;
+  return node;
+}
+
+/** A connector. `data`: { line: curved|straight|elbow, arrow: end|both|none, dashed }. */
+export function createEdge(source, target, { id, label, data } = {}) {
+  const e = { id: id ?? makeId("e"), source, target, type: "flow", data: { line: "curved", arrow: "end", ...(data ?? {}) } };
+  if (label) e.label = label;
+  return e;
+}
+
+/**
+ * Copies of some nodes (and the connectors between them), moved by
+ * `offset`, with new ids. Frames bring what they hold. Returns
+ * { nodes, edges } — only the new ones.
+ */
+export function duplicateNodes(board, ids, { offset = { x: GRID * 2, y: GRID * 2 } } = {}) {
+  const { nodes, edges } = readBoard(board);
+  const want = new Set(ids);
+  for (const id of ids) {
+    const n = nodes.find((x) => x.id === id);
+    if (n?.type === "frame") for (const c of frameContents(board, id)) want.add(c);
+  }
+  const map = new Map();
+  const out = [];
+  for (const n of nodes) {
+    if (!want.has(n.id)) continue;
+    const id = makeId(n.type || "n");
+    map.set(n.id, id);
+    const { selected, dragging, measured, ...rest } = n;
+    const copy = { ...rest, id, position: { x: num(n.position?.x) + offset.x, y: num(n.position?.y) + offset.y }, data: structuredCopy(n.data) };
+    if (copy.data?.locked) {
+      delete copy.data.locked;
+      delete copy.draggable;
+      delete copy.deletable;
+    }
+    out.push(copy);
+  }
+  const outEdges = edges
+    .filter((e) => map.has(e.source) && map.has(e.target))
+    .map((e) => ({ ...e, id: makeId("e"), source: map.get(e.source), target: map.get(e.target), selected: undefined }));
+  return { nodes: out, edges: outEdges };
+}
+
+function structuredCopy(v) {
+  try {
+    return JSON.parse(JSON.stringify(v ?? {}));
+  } catch {
+    return { ...(v ?? {}) };
+  }
+}
+
+/** The board without some nodes and every connector that touched them. */
+export function removeNodes(board, ids) {
+  const { nodes, edges } = readBoard(board);
+  const gone = new Set(ids);
+  return { ...board, nodes: nodes.filter((n) => !gone.has(n.id)), edges: edges.filter((e) => !gone.has(e.source) && !gone.has(e.target)) };
+}
+
+/**
+ * Line up nodes: how = left | center | right | top | middle | bottom.
+ * Returns the whole node list with those moved.
+ */
+export function alignNodes(nodes, ids, how) {
+  const set = new Set(ids);
+  const pick = (nodes ?? []).filter((n) => set.has(n.id));
+  const b = boardBounds(pick);
+  if (!b || pick.length < 2) return nodes;
+  return nodes.map((n) => {
+    if (!set.has(n.id) || n.data?.locked) return n;
+    const r = nodeRect(n);
+    const p = { ...n.position };
+    if (how === "left") p.x = b.x;
+    else if (how === "center") p.x = b.x + b.width / 2 - r.width / 2;
+    else if (how === "right") p.x = b.x + b.width - r.width;
+    else if (how === "top") p.y = b.y;
+    else if (how === "middle") p.y = b.y + b.height / 2 - r.height / 2;
+    else if (how === "bottom") p.y = b.y + b.height - r.height;
+    return { ...n, position: p };
+  });
+}
+
+/** Even gaps between nodes along an axis: "horizontal" | "vertical". */
+export function distributeNodes(nodes, ids, axis = "horizontal") {
+  const set = new Set(ids);
+  const h = axis === "horizontal";
+  const pick = (nodes ?? []).filter((n) => set.has(n.id)).map((n) => ({ n, r: nodeRect(n) }));
+  if (pick.length < 3) return nodes;
+  pick.sort((a, b) => (h ? a.r.x - b.r.x : a.r.y - b.r.y));
+  const first = pick[0].r;
+  const last = pick[pick.length - 1].r;
+  const span = h ? last.x + last.width - first.x : last.y + last.height - first.y;
+  const used = pick.reduce((s, p) => s + (h ? p.r.width : p.r.height), 0);
+  const gap = (span - used) / (pick.length - 1);
+  const at = new Map();
+  let cursor = h ? first.x : first.y;
+  for (const p of pick) {
+    at.set(p.n.id, cursor);
+    cursor += (h ? p.r.width : p.r.height) + gap;
+  }
+  return nodes.map((n) => (at.has(n.id) && !n.data?.locked ? { ...n, position: h ? { ...n.position, x: at.get(n.id) } : { ...n.position, y: at.get(n.id) } } : n));
+}
+
+/** Arrange: move nodes to the end (front) or start (back) of the list.
+ *  Paint order is list order; frames always sit under everything. */
+export function arrangeNodes(nodes, ids, where = "front") {
+  const set = new Set(ids);
+  const moved = nodes.filter((n) => set.has(n.id));
+  const rest = nodes.filter((n) => !set.has(n.id));
+  return where === "back" ? [...moved, ...rest] : [...rest, ...moved];
+}
+
+// ── layout ───────────────────────────────────────────────────────────────
+
+/**
+ * A layered layout (sources first, each step one rank further) with no
+ * dependency: cycles are broken, ranks are longest paths, and a few
+ * barycentre sweeps untangle crossings. Nodes nobody connects sit in a row
+ * after the rest. The result keeps the top-left corner the nodes had, so
+ * nothing flies off screen.
+ *
+ *   autoLayout(nodes, edges, { direction: "LR" | "TB", rankGap: 80, nodeGap: 40, ids })
+ *
+ * `ids` lays out only those nodes (default: every node but frames).
+ * Returns the whole node list with new positions.
+ */
+export function autoLayout(nodes, edges, { direction = "LR", rankGap = 80, nodeGap = 40, ids, grid = GRID } = {}) {
+  const all = nodes ?? [];
+  const pickIds = new Set(ids ?? all.filter((n) => n.type !== "frame").map((n) => n.id));
+  const pick = all.filter((n) => pickIds.has(n.id));
+  if (!pick.length) return all;
+  const before = boardBounds(pick);
+  const lr = direction !== "TB";
+  const size = new Map(pick.map((n) => [n.id, nodeSize(n)]));
+  const main = (id) => (lr ? size.get(id).width : size.get(id).height);
+  const cross = (id) => (lr ? size.get(id).height : size.get(id).width);
+
+  const order = pick.map((n) => n.id);
+  const index = new Map(order.map((id, i) => [id, i]));
+  const links = (edges ?? []).filter((e) => pickIds.has(e.source) && pickIds.has(e.target) && e.source !== e.target);
+
+  // Break cycles: a DFS in list order; an edge back into the stack is reversed.
+  const out = new Map(order.map((id) => [id, []]));
+  for (const e of links) out.get(e.source).push(e.target);
+  const state = new Map();
+  const dag = [];
+  const visit = (u) => {
+    state.set(u, 1);
+    for (const v of out.get(u)) {
+      if (state.get(v) === 1) dag.push([v, u]);
+      else {
+        dag.push([u, v]);
+        if (!state.get(v)) visit(v);
+      }
+    }
+    state.set(u, 2);
+  };
+  for (const id of order) if (!state.get(id)) visit(id);
+
+  const preds = new Map(order.map((id) => [id, []]));
+  const succs = new Map(order.map((id) => [id, []]));
+  const seen = new Set();
+  for (const [u, v] of dag) {
+    const k = `${u}>${v}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    succs.get(u).push(v);
+    preds.get(v).push(u);
+  }
+
+  // Components: connected groups, laid side by side on the cross axis.
+  const comp = new Map();
+  let compCount = 0;
+  for (const id of order) {
+    if (comp.has(id)) continue;
+    const stack = [id];
+    comp.set(id, compCount);
+    while (stack.length) {
+      const u = stack.pop();
+      for (const v of [...succs.get(u), ...preds.get(u)]) if (!comp.has(v)) (comp.set(v, compCount), stack.push(v));
+    }
+    compCount++;
+  }
+
+  // Ranks: longest path from a source (Kahn order).
+  const rank = new Map();
+  const indeg = new Map(order.map((id) => [id, preds.get(id).length]));
+  const queue = order.filter((id) => indeg.get(id) === 0);
+  for (const id of queue) rank.set(id, 0);
+  for (let i = 0; i < queue.length; i++) {
+    const u = queue[i];
+    for (const v of succs.get(u)) {
+      rank.set(v, Math.max(rank.get(v) ?? 0, rank.get(u) + 1));
+      indeg.set(v, indeg.get(v) - 1);
+      if (indeg.get(v) === 0) queue.push(v);
+    }
+  }
+
+  const loose = order.filter((id) => !preds.get(id).length && !succs.get(id).length);
+  const looseSet = new Set(loose);
+  const groups = [];
+  for (let c = 0; c < compCount; c++) {
+    const members = order.filter((id) => comp.get(id) === c && !looseSet.has(id));
+    if (members.length) groups.push(members);
+  }
+
+  const positions = new Map();
+  let crossCursor = 0;
+  for (const members of groups) {
+    const maxRank = Math.max(...members.map((id) => rank.get(id)));
+    const layers = Array.from({ length: maxRank + 1 }, () => []);
+    for (const id of members) layers[rank.get(id)].push(id);
+    for (const l of layers) l.sort((a, b) => index.get(a) - index.get(b));
+    // Barycentre sweeps: order each layer by the mean slot of its neighbours.
+    const slot = new Map();
+    const reslot = () => layers.forEach((l) => l.forEach((id, i) => slot.set(id, i)));
+    reslot();
+    const bary = (id, nbrs) => {
+      const s = nbrs.filter((x) => slot.has(x));
+      return s.length ? s.reduce((t, x) => t + slot.get(x), 0) / s.length : slot.get(id);
+    };
+    for (let pass = 0; pass < 4; pass++) {
+      for (let r = 1; r < layers.length; r++) {
+        layers[r].sort((a, b) => bary(a, preds.get(a)) - bary(b, preds.get(b)) || index.get(a) - index.get(b));
+        reslot();
+      }
+      for (let r = layers.length - 2; r >= 0; r--) {
+        layers[r].sort((a, b) => bary(a, succs.get(a)) - bary(b, succs.get(b)) || index.get(a) - index.get(b));
+        reslot();
+      }
+    }
+    // Place: ranks along the main axis, each layer centred on the widest.
+    const extent = layers.map((l) => l.reduce((s, id) => s + cross(id), 0) + nodeGap * Math.max(0, l.length - 1));
+    const widest = Math.max(...extent);
+    let mainCursor = 0;
+    layers.forEach((l, r) => {
+      const depth = Math.max(...l.map(main));
+      let c = crossCursor + (widest - extent[r]) / 2;
+      for (const id of l) {
+        const m = mainCursor + (depth - main(id)) / 2;
+        positions.set(id, lr ? { x: m, y: c } : { x: c, y: m });
+        c += cross(id) + nodeGap;
+      }
+      mainCursor += depth + rankGap;
+    });
+    crossCursor += widest + rankGap;
+  }
+  // The unconnected ones: one row (or column) after the groups.
+  if (loose.length) {
+    let m = 0;
+    const depth = Math.max(...loose.map(cross));
+    for (const id of loose) {
+      positions.set(id, lr ? { x: m, y: crossCursor + (depth - cross(id)) / 2 } : { x: crossCursor + (depth - cross(id)) / 2, y: m });
+      m += main(id) + nodeGap;
+    }
+  }
+
+  // Keep the old top-left corner.
+  const laid = pick.map((n) => ({ ...n, position: positions.get(n.id) }));
+  const after = boardBounds(laid);
+  const dx = before.x - after.x;
+  const dy = before.y - after.y;
+  const moved = new Map(laid.map((n) => [n.id, snapPoint({ x: n.position.x + dx, y: n.position.y + dy }, grid)]));
+  return all.map((n) => (moved.has(n.id) && !n.data?.locked ? { ...n, position: moved.get(n.id) } : n));
+}
+
+// ── words out ────────────────────────────────────────────────────────────
+
+/** The words a node shows: text, title, label or name. */
+export function nodeText(node) {
+  const d = node?.data ?? {};
+  for (const k of ["text", "title", "label", "name"]) if (typeof d[k] === "string" && d[k].trim()) return d[k].trim();
+  if (node?.type === "image") return String(d.alt || d.caption || "").trim();
+  return "";
+}
+
+const KIND = { sticky: "Sticky", shape: "Shape", text: "Text", frame: "Frame", card: "Card", image: "Image" };
+const quote = (s) => `"${String(s).replace(/\s+/g, " ").trim()}"`;
+const readingOrder = (a, b) => {
+  const ra = nodeRect(a);
+  const rb = nodeRect(b);
+  return Math.abs(ra.y - rb.y) > 24 ? ra.y - rb.y : ra.x - rb.x;
+};
+
+/** One line for a node: `Sticky (yellow): "Ship the beta"`. */
+export function describeNode(node, describe) {
+  const own = describe?.(node);
+  if (typeof own === "string" && own) return own;
+  const d = node?.data ?? {};
+  const text = nodeText(node);
+  if (node?.type === "shape") return `${SHAPE_NAMES[d.shape] ?? "Shape"}: ${text ? quote(text) : "(empty)"}`;
+  if (node?.type === "sticky") {
+    const extra = [d.badge != null && d.badge !== "" ? `${d.badge}` : null, d.meta || null].filter(Boolean).join(", ");
+    return `Sticky: ${text ? quote(text) : "(empty)"}${extra ? ` [${extra}]` : ""}`;
+  }
+  if (node?.type === "card") return `Card${d.kind ? ` (${d.kind})` : ""}: ${text ? quote(text) : "(untitled)"}${d.body ? ` — ${String(d.body).replace(/\s+/g, " ").trim()}` : ""}`;
+  if (node?.type === "image") return `Image: ${text ? quote(text) : "(no description)"}`;
+  const kind = KIND[node?.type] ?? String(node?.type ?? "Item").replace(/^\w/, (c) => c.toUpperCase());
+  return `${kind}: ${text ? quote(text) : "(empty)"}`;
+}
+
+function outline(board) {
+  const { nodes, edges } = readBoard(board);
+  const parent = frameOf(board);
+  const kids = new Map();
+  for (const n of nodes) {
+    const p = parent.get(n.id) ?? null;
+    if (!kids.has(p)) kids.set(p, []);
+    kids.get(p).push(n);
+  }
+  for (const list of kids.values()) list.sort((a, b) => (a.type === "frame") - (b.type === "frame") || readingOrder(a, b));
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  return { nodes, edges, kids, byId };
+}
+
+const edgeLine = (e, byId) => {
+  const a = nodeText(byId.get(e.source)) || byId.get(e.source)?.type || e.source;
+  const b = nodeText(byId.get(e.target)) || byId.get(e.target)?.type || e.target;
+  const arrow = e.data?.arrow === "both" ? "↔" : e.data?.arrow === "none" ? "—" : "→";
+  return `${quote(a)} ${arrow} ${quote(b)}${e.label ? ` (${String(e.label).trim()})` : ""}`;
+};
+
+/**
+ * The board as plain text, for an agent or a screen reader: frames with
+ * what they hold (in reading order, nested), loose items, connectors.
+ * `describe(node)` returns a line for a custom node type (or nothing, for
+ * the default).
+ */
+export function boardToText(board, { describe } = {}) {
+  const { nodes, edges, kids, byId } = outline(board);
+  if (!nodes.length) return "Empty board.";
+  const lines = [`Board: ${nodes.length} item${nodes.length === 1 ? "" : "s"}, ${edges.length} connector${edges.length === 1 ? "" : "s"}.`];
+  const walk = (parentId, depth) => {
+    for (const n of kids.get(parentId) ?? []) {
+      const pad = "  ".repeat(depth);
+      if (n.type === "frame") {
+        const count = (kids.get(n.id) ?? []).length;
+        lines.push(`${pad}Frame ${quote(n.data?.title || "Untitled")} (${count} item${count === 1 ? "" : "s"}):`);
+        walk(n.id, depth + 1);
+      } else lines.push(`${pad}- ${describeNode(n, describe)}`);
+    }
+  };
+  walk(null, 0);
+  if (edges.length) {
+    lines.push("Connectors:");
+    for (const e of edges) lines.push(`- ${edgeLine(e, byId)}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The board as GitHub markdown: `# title`, a heading per frame (nested
+ * frames one level down), a bullet per item, a Connections list.
+ */
+export function boardToMarkdown(board, { title, describe } = {}) {
+  const { nodes, edges, kids, byId } = outline(board);
+  const out = [];
+  if (title) out.push(`# ${title}`, "");
+  if (!nodes.length) return [...out, "_Empty board._"].join("\n");
+  const esc = (s) => String(s).replace(/([*_`[\]])/g, "\\$1").replace(/\s+/g, " ").trim();
+  const bullet = (n) => {
+    const own = describe?.(n);
+    if (typeof own === "string" && own) return `- ${own}`;
+    const d = n.data ?? {};
+    const text = nodeText(n);
+    if (n.type === "text") return `- ${esc(text) || "_(empty)_"}`;
+    if (n.type === "shape") return `- **${esc(text) || "(empty)"}** _(${(SHAPE_NAMES[d.shape] ?? "shape").toLowerCase()})_`;
+    if (n.type === "card") return `- **${esc(text) || "(untitled)"}**${d.body ? ` — ${esc(d.body)}` : ""}`;
+    if (n.type === "image") return d.src ? `- ![${esc(text)}](${d.src})` : `- _image: ${esc(text)}_`;
+    const extra = n.type === "sticky" && d.badge != null && d.badge !== "" ? ` (${d.badge})` : "";
+    return `- ${esc(text) || "_(empty)_"}${extra}`;
+  };
+  const loose = (kids.get(null) ?? []).filter((n) => n.type !== "frame");
+  for (const n of loose) out.push(bullet(n));
+  if (loose.length) out.push("");
+  const walk = (parentId, level) => {
+    for (const f of (kids.get(parentId) ?? []).filter((n) => n.type === "frame")) {
+      out.push(`${"#".repeat(Math.min(6, level))} ${esc(f.data?.title || "Untitled")}`, "");
+      const items = (kids.get(f.id) ?? []).filter((n) => n.type !== "frame");
+      for (const n of items) out.push(bullet(n));
+      if (items.length) out.push("");
+      walk(f.id, level + 1);
+    }
+  };
+  walk(null, title ? 2 : 1);
+  if (edges.length) {
+    out.push(`${"#".repeat(title ? 2 : 1)} Connections`, "");
+    for (const e of edges) out.push(`- ${edgeLine(e, byId)}`);
+    out.push("");
+  }
+  return out.join("\n").trimEnd() + "\n";
+}
+
+// ── history ──────────────────────────────────────────────────────────────
+
+/** Undo/redo as a reducer over board snapshots (use cleanBoard ones).
+ *    const [h, dispatch] = useReducer(historyReducer, board, historyInit)
+ *    dispatch({ type: "push", present })   a committed change (a no-op when equal)
+ *    dispatch({ type: "undo" }) · dispatch({ type: "redo" })
+ *    dispatch({ type: "reset", present })  a new document; no undo past it
+ *  h.present is the board to show; h.past / h.future the stacks. */
+export function historyInit(present) {
+  const p = cleanBoard(present ?? emptyBoard(), { viewport: false });
+  return { past: [], present: p, future: [], key: boardKey(p) };
+}
+
+export function historyReducer(h, action) {
+  const limit = action?.limit ?? 100;
+  switch (action?.type) {
+    case "push": {
+      const present = cleanBoard(action.present, { viewport: false });
+      const key = boardKey(present);
+      if (key === h.key) return h;
+      return { past: [...h.past, h.present].slice(-limit), present, future: [], key };
+    }
+    case "undo": {
+      if (!h.past.length) return h;
+      const present = h.past[h.past.length - 1];
+      return { past: h.past.slice(0, -1), present, future: [h.present, ...h.future].slice(0, limit), key: boardKey(present) };
+    }
+    case "redo": {
+      if (!h.future.length) return h;
+      const [present, ...future] = h.future;
+      return { past: [...h.past, h.present].slice(-limit), present, future, key: boardKey(present) };
+    }
+    case "reset":
+      return historyInit(action.present);
+    default:
+      return h;
+  }
+}
+
+// ── starters ─────────────────────────────────────────────────────────────
+
+/** The empty-state starters FlowCanvas offers by default. Each `board()`
+ *  makes fresh ids. Pass your own list in `templates`, or [] for none. */
+export function starterTemplates() {
+  return [
+    {
+      id: "brainstorm",
+      label: "Brainstorm",
+      description: "A frame and a few stickies to start from",
+      icon: "lightbulb",
+      board: () => {
+        const f = createNode("frame", null, { rect: { x: 0, y: 0, width: 720, height: 420 }, data: { title: "Ideas" } });
+        const s = (x, y, color, text) => createNode("sticky", { x, y }, { data: { color, text } });
+        return {
+          nodes: [
+            f,
+            s(140, 160, "warning", "What would make this a yes?"),
+            s(360, 160, "chart-2", ""),
+            s(580, 160, "chart-3", ""),
+            createNode("text", { x: 360, y: 360 }, { width: 480, data: { text: "Add one idea per sticky. Cluster them later.", textSize: "sm" } }),
+          ],
+          edges: [],
+        };
+      },
+    },
+    {
+      id: "flowchart",
+      label: "Flowchart",
+      description: "Start, steps, a decision, connected",
+      icon: "git-branch",
+      board: () => {
+        const sh = (x, y, shape, text, color) => createNode("shape", { x, y }, { data: { shape, text, color } });
+        const a = sh(100, 200, "pill", "Start", "chart-2");
+        const b = sh(340, 200, "rect", "Do the thing", "muted");
+        const c = sh(580, 200, "diamond", "Worked?", "warning");
+        const d = sh(820, 200, "pill", "Done", "success");
+        return {
+          nodes: [a, b, c, d],
+          edges: [createEdge(a.id, b.id), createEdge(b.id, c.id), createEdge(c.id, d.id, { label: "Yes" }), createEdge(c.id, b.id, { label: "No", data: { line: "elbow" } })],
+        };
+      },
+    },
+    {
+      id: "retro",
+      label: "Retro",
+      description: "Went well, to improve, actions",
+      icon: "history",
+      board: () => {
+        const col = (i, title, color) => {
+          const x = i * 340;
+          return [
+            createNode("frame", null, { rect: { x, y: 0, width: 320, height: 460 }, data: { title } }),
+            createNode("sticky", { x: x + 160, y: 140 }, { width: 180, height: 180, data: { color, text: "" } }),
+          ];
+        };
+        return { nodes: [...col(0, "Went well", "success"), ...col(1, "To improve", "warning"), ...col(2, "Actions", "chart-5")], edges: [] };
+      },
+    },
+  ];
+}