@heyramzi/ui 1.54.2 → 2.0.1

package/src/canvas/editor/keymap.ts

@@ -0,0 +1,151 @@
+// The canvas keyboard map, as a resolver rather than a switch in the editor.
+// Mirrors resolveMindmapKeyAction in mindmap-keyboard.ts, which the mode
+// controllers already read.
+
+export type EditorKeyAction =
+  | "undo"
+  | "redo"
+  | "copy"
+  | "paste"
+  | "select-all"
+  | "save"
+  | "delete"
+  | "duplicate"
+  | "group"
+  | "ungroup"
+  | "zoom-in"
+  | "zoom-out"
+  | "zoom-100"
+  | "zoom-fit"
+  | "zoom-selection"
+  | "bring-forward"
+  | "send-backward"
+  | "bring-to-front"
+  | "send-to-back"
+  | "lock"
+  | "copy-as-png"
+  | "present";
+
+/** True while the event's target owns its own text editing. */
+export function isEditingTarget(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null;
+  const tag = el?.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || el?.isContentEditable === true;
+}
+
+/** The action a key means on the canvas, or null when the canvas does not own it. */
+export function resolveEditorKeyAction(
+  event: KeyboardEvent,
+  hasSelection: boolean,
+): EditorKeyAction | null {
+  const key = event.key.toLowerCase();
+  const mod = event.metaKey || event.ctrlKey;
+  const editing = isEditingTarget(event.target);
+  if (mod) return modAction(key, event.shiftKey, editing);
+  if (event.key === "Delete" || event.key === "Backspace") {
+    return hasSelection && !editing ? "delete" : null;
+  }
+  return editing || event.altKey ? null : plainAction(event);
+}
+
+/** Shift with a digit zooms. Read by code, so a layout that moves the digits still works. */
+const SHIFT_ZOOM = new Map<string, EditorKeyAction>([
+  ["Digit0", "zoom-100"],
+  ["Digit1", "zoom-fit"],
+  ["Digit2", "zoom-selection"],
+]);
+
+const PLAIN_KEYS = new Map<string, EditorKeyAction>([
+  ["]", "bring-forward"],
+  ["[", "send-backward"],
+  ["+", "zoom-in"],
+  ["=", "zoom-in"],
+  ["-", "zoom-out"],
+  ["_", "zoom-out"],
+]);
+
+/** Zoom keys with no chord: + and -, and Shift with 0, 1 or 2. */
+function plainAction(event: KeyboardEvent): EditorKeyAction | null {
+  const zoom = event.shiftKey ? SHIFT_ZOOM.get(event.code) : undefined;
+  return zoom ?? PLAIN_KEYS.get(event.key) ?? null;
+}
+
+/** The move an arrow key asks for: 1px, or 10px with Shift. Null for anything else, or while a field owns the keys. */
+export function resolveNudge(event: KeyboardEvent): { dx: number; dy: number } | null {
+  if (event.metaKey || event.ctrlKey || event.altKey || isEditingTarget(event.target)) return null;
+  const step = event.shiftKey ? 10 : 1;
+  switch (event.key) {
+    case "ArrowLeft":
+      return { dx: -step, dy: 0 };
+    case "ArrowRight":
+      return { dx: step, dy: 0 };
+    case "ArrowUp":
+      return { dx: 0, dy: -step };
+    case "ArrowDown":
+      return { dx: 0, dy: step };
+    default:
+      return null;
+  }
+}
+
+/** What a chord means without Shift, then with it. Null where that variant is not ours. */
+type Chord = readonly [plain: EditorKeyAction | null, shifted: EditorKeyAction | null];
+
+const both = (action: EditorKeyAction): Chord => [action, action];
+
+const CHORDS = new Map<string, Chord>([
+  ["c", ["copy", "copy-as-png"]],
+  ["v", both("paste")],
+  ["a", both("select-all")],
+  ["d", ["duplicate", null]],
+  ["g", ["group", "ungroup"]],
+  ["l", [null, "lock"]],
+  ["]", both("bring-to-front")],
+  ["[", both("send-to-back")],
+  ["enter", both("present")],
+  ["=", both("zoom-in")],
+  ["+", both("zoom-in")],
+  ["-", both("zoom-out")],
+  ["_", both("zoom-out")],
+]);
+
+/** The chord half of the map. `editing` is true while a field owns the keys. */
+function modAction(key: string, shift: boolean, editing: boolean): EditorKeyAction | null {
+  if (key === "z") return shift ? "redo" : "undo";
+  if (key === "y") return "redo";
+  // Save works whatever has focus, and whatever the autosave preference is.
+  if (key === "s" && !shift) return "save";
+  // Cut, copy, paste and select-all belong to the focused field while one is
+  // being typed in; the canvas only claims them otherwise.
+  if (editing) return null;
+  return CHORDS.get(key)?.[shift ? 1 : 0] ?? null;
+}
+
+/** Tags and roles that activate on Space themselves, so the canvas must not steal it. */
+const SPACE_OWNING_TAGS = new Set(["BUTTON", "A", "SUMMARY", "SELECT", "OPTION"]);
+const SPACE_OWNING_ROLES = new Set([
+  "button",
+  "checkbox",
+  "switch",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "tab",
+]);
+
+/** Space means hand tool over the canvas, never in a field or on a Space-activating control. Reads code, so remapped layouts still pan. */
+export function isPanActivationKey(event: KeyboardEvent): boolean {
+  if (event.code !== "Space" && event.key !== " ") return false;
+  if (event.metaKey || event.ctrlKey || event.altKey) return false;
+  if (isEditingTarget(event.target)) return false;
+  return !ownsSpace(event.target as HTMLElement | null);
+}
+
+/** A control that already does something on Space: a button, a checkbox, a tab. */
+function ownsSpace(el: HTMLElement | null): boolean {
+  if (el?.tagName && SPACE_OWNING_TAGS.has(el.tagName)) return true;
+  const role = el?.getAttribute?.("role");
+  return Boolean(role && SPACE_OWNING_ROLES.has(role));
+}

package/src/canvas/editor/layout-actions.test.ts

@@ -0,0 +1,156 @@
+import { expectDefined } from "../test-utils.js";
+import { describe, it, expect } from "vite-plus/test";
+import { alignNodes, groupSelectionOps, tidyGroup } from "./layout-actions.js";
+
+function pos(id: string, x: number, y: number) {
+  return { id, position: { x, y } };
+}
+
+describe("alignNodes", () => {
+  it("returns empty map for fewer than 2 nodes", () => {
+    const result = alignNodes([pos("a", 10, 20)], "left");
+    expect(result.size).toBe(0);
+  });
+
+  it("aligns left to minimum x", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0), pos("c", 50, 0)], "left");
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(50);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(50);
+    expect(expectDefined(result.get("c"), "entry c").x).toBe(50);
+  });
+
+  it("aligns right to maximum x", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0)], "right");
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(200);
+  });
+
+  it("aligns top to minimum y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 50)], "top");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(50);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(50);
+  });
+
+  it("aligns bottom to maximum y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 200)], "bottom");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(200);
+  });
+
+  it("center-h aligns to minimum x (vertical center)", () => {
+    const result = alignNodes([pos("a", 100, 0), pos("b", 200, 0)], "center-h");
+    // alignNodesVertically sets all to min x
+    expect(expectDefined(result.get("a"), "entry a").x).toBe(100);
+    expect(expectDefined(result.get("b"), "entry b").x).toBe(100);
+  });
+
+  it("center-v aligns to average y", () => {
+    const result = alignNodes([pos("a", 0, 100), pos("b", 0, 200), pos("c", 0, 300)], "center-v");
+    expect(expectDefined(result.get("a"), "entry a").y).toBe(200);
+    expect(expectDefined(result.get("b"), "entry b").y).toBe(200);
+    expect(expectDefined(result.get("c"), "entry c").y).toBe(200);
+  });
+
+  it("does not mutate input positions", () => {
+    const nodes = [pos("a", 100, 0), pos("b", 200, 0)];
+    alignNodes(nodes, "left");
+    expect(nodes[0].position.x).toBe(100);
+    expect(nodes[1].position.x).toBe(200);
+  });
+});
+
+describe("groupSelectionOps", () => {
+  const box = (id: string, x: number, y: number, parentId?: string) => ({
+    id,
+    position: { x, y },
+    measured: { width: 100, height: 50 },
+    ...(parentId ? { parentId } : {}),
+  });
+
+  it("refuses to group fewer than two nodes", () => {
+    expect(groupSelectionOps([box("a", 0, 0)], "Group")).toEqual([]);
+  });
+
+  it("draws the box around the selection and re-parents every member", () => {
+    const ops = groupSelectionOps([box("a", 100, 100), box("b", 300, 200)], "Group");
+    const [add, ...rest] = ops;
+
+    expect(add).toMatchObject({
+      kind: "addNode",
+      node: {
+        type: "group",
+        // 32 of padding on every side, plus 36 of title row above.
+        position: { x: 68, y: 32 },
+        width: 364,
+        height: 250,
+      },
+    });
+
+    const groupId = (add as { node: { id: string } }).node.id;
+    expect(rest).toEqual([
+      { kind: "setParent", nodeId: "a", parentId: groupId, extent: "parent" },
+      { kind: "moveNode", nodeId: "a", position: { x: 32, y: 68 } },
+      { kind: "setParent", nodeId: "b", parentId: groupId, extent: "parent" },
+      { kind: "moveNode", nodeId: "b", position: { x: 232, y: 168 } },
+    ]);
+  });
+
+  it("takes only the members sharing the first one's parent, and joins it", () => {
+    const ops = groupSelectionOps(
+      [box("a", 0, 0, "p1"), box("b", 100, 0, "p1"), box("loose", 900, 900)],
+      "Group",
+    );
+    expect(ops).toHaveLength(5);
+    expect(ops[0]).toMatchObject({ kind: "addNode", node: { parentId: "p1" } });
+    expect(ops.some((op) => "nodeId" in op && op.nodeId === "loose")).toBe(false);
+  });
+});
+
+describe("tidyGroup", () => {
+  const box = (id: string, x: number, y: number, width: number, height: number) => ({
+    id,
+    position: { x, y },
+    measured: { width, height },
+  });
+
+  it("has nothing to tidy in an empty group", () => {
+    expect(tidyGroup([])).toBeNull();
+  });
+
+  it("keeps side-by-side cards in one row, stacks the rest, and fits the box", () => {
+    const result = expectDefined(
+      tidyGroup([
+        box("card2", 800, 110, 640, 220),
+        box("title", 0, 10, 200, 30),
+        box("card1", 5, 120, 750, 500),
+        box("subtitle", 5, 70, 600, 20),
+      ]),
+      "tidy result",
+    );
+
+    // 32 of padding, 36 of title row, 24 between rows and between cards.
+    expect(Object.fromEntries(result.positions)).toEqual({
+      title: { x: 32, y: 68 },
+      subtitle: { x: 32, y: 122 },
+      card1: { x: 32, y: 166 },
+      card2: { x: 806, y: 166 },
+    });
+    expect(result.size).toEqual({ width: 1478, height: 698 });
+  });
+
+  it("pulls overlapping nodes apart along their row", () => {
+    const result = expectDefined(
+      tidyGroup([box("b", 10, 5, 100, 50), box("a", 0, 0, 100, 50)]),
+      "tidy result",
+    );
+    expect(result.positions.get("a")).toEqual({ x: 32, y: 68 });
+    expect(result.positions.get("b")).toEqual({ x: 156, y: 68 });
+  });
+
+  it("never shrinks the box below the container minimum", () => {
+    expect(expectDefined(tidyGroup([box("a", 400, 400, 10, 10)]), "tidy result").size).toEqual({
+      width: 250,
+      height: 150,
+    });
+  });
+});

package/src/canvas/editor/layout-actions.ts

@@ -0,0 +1,219 @@
+import type { CanvasOp } from "../ops/ops.js";
+import type { CanvasNode } from "../types.js";
+import { alignNodesHorizontally, alignNodesVertically } from "../headless/alignment.js";
+
+/** The smallest a group frame gets. An app passes its own to `tidyGroup`. */
+const DEFAULT_GROUP_MIN = { width: 250, height: 150 } as const;
+
+type AlignDirection = "left" | "right" | "top" | "bottom" | "center-h" | "center-v";
+
+type Positioned = { id: string; position: { x: number; y: number } };
+
+function setX(nodes: Positioned[], x: number): void {
+  for (const n of nodes) n.position.x = x;
+}
+
+function setY(nodes: Positioned[], y: number): void {
+  for (const n of nodes) n.position.y = y;
+}
+
+const ALIGNERS: Record<AlignDirection, (nodes: Positioned[]) => void> = {
+  left: (nodes) => setX(nodes, Math.min(...nodes.map((n) => n.position.x))),
+  right: (nodes) => setX(nodes, Math.max(...nodes.map((n) => n.position.x))),
+  top: (nodes) => alignNodesHorizontally(nodes as CanvasNode[]),
+  bottom: (nodes) => setY(nodes, Math.max(...nodes.map((n) => n.position.y))),
+  "center-h": (nodes) => alignNodesVertically(nodes as CanvasNode[]),
+  "center-v": (nodes) =>
+    setY(nodes, nodes.reduce((sum, n) => sum + n.position.y, 0) / nodes.length),
+};
+
+/**
+ * Compute new positions for the given nodes based on alignment direction.
+ * Returns a Map of nodeId to new position.
+ */
+export function alignNodes(
+  selected: Positioned[],
+  direction: AlignDirection,
+): Map<string, { x: number; y: number }> {
+  if (selected.length < 2) return new Map();
+
+  const mutableNodes = selected.map((n) => ({
+    id: n.id,
+    position: { ...n.position },
+  }));
+  ALIGNERS[direction](mutableNodes);
+
+  return new Map(mutableNodes.map((n) => [n.id, n.position]));
+}
+
+const TIDY_GAP = 40;
+
+/**
+ * Distribute selected nodes evenly along their dominant axis.
+ * Detects whether nodes are mostly horizontal or vertical and
+ * equalizes gaps while preserving the cross-axis positions.
+ */
+export function tidySelectedNodes(
+  selected: Array<{
+    id: string;
+    position: { x: number; y: number };
+    measured?: { width?: number; height?: number };
+    width?: number;
+    height?: number;
+  }>,
+): Map<string, { x: number; y: number }> {
+  if (selected.length < 2) return new Map();
+
+  const xs = selected.map((n) => n.position.x);
+  const ys = selected.map((n) => n.position.y);
+  const xSpread = Math.max(...xs) - Math.min(...xs);
+  const ySpread = Math.max(...ys) - Math.min(...ys);
+
+  const horizontal = xSpread >= ySpread;
+
+  const sorted = [...selected].sort((a, b) =>
+    horizontal ? a.position.x - b.position.x : a.position.y - b.position.y,
+  );
+
+  return horizontal ? stackAlongX(sorted) : stackAlongY(sorted);
+}
+
+type Tidyable = Parameters<typeof tidySelectedNodes>[0][number];
+
+function stackAlongX(sorted: Tidyable[]): Map<string, { x: number; y: number }> {
+  const result = new Map<string, { x: number; y: number }>();
+  let cursorX = sorted[0].position.x;
+  for (const node of sorted) {
+    result.set(node.id, { x: cursorX, y: node.position.y });
+    cursorX += (node.measured?.width ?? node.width ?? 200) + TIDY_GAP;
+  }
+  return result;
+}
+
+function stackAlongY(sorted: Tidyable[]): Map<string, { x: number; y: number }> {
+  const result = new Map<string, { x: number; y: number }>();
+  let cursorY = sorted[0].position.y;
+  for (const node of sorted) {
+    result.set(node.id, { x: node.position.x, y: cursorY });
+    cursorY += (node.measured?.height ?? node.height ?? 100) + TIDY_GAP;
+  }
+  return result;
+}
+
+// A group box drawn around a selection: the padding on every side, plus the
+// room the container's own title row takes at the top.
+const GROUP_PADDING = 32;
+const GROUP_HEADER = 36;
+
+type Measurable = {
+  id: string;
+  position: { x: number; y: number };
+  measured?: { width?: number; height?: number };
+  width?: number;
+  height?: number;
+  parentId?: string;
+};
+
+const GROUP_GAP = 24;
+const ROW_TOLERANCE = 8;
+
+/**
+ * Tidy a group's direct children: rows by reading order, even gaps, then the
+ * box fitted around them. Null when the group is empty.
+ */
+export function tidyGroup(
+  children: Measurable[],
+  min: { width: number; height: number } = DEFAULT_GROUP_MIN,
+): {
+  positions: Map<string, { x: number; y: number }>;
+  size: { width: number; height: number };
+} | null {
+  if (children.length === 0) return null;
+  const width = (n: Measurable) => n.measured?.width ?? n.width ?? 200;
+  const height = (n: Measurable) => n.measured?.height ?? n.height ?? 100;
+
+  // A node joins the current row when it overlaps it vertically by more than a hair.
+  const rows: { bottom: number; items: Measurable[] }[] = [];
+  for (const n of [...children].sort((a, b) => a.position.y - b.position.y)) {
+    const row = rows.at(-1);
+    if (row && n.position.y < row.bottom - ROW_TOLERANCE) {
+      row.items.push(n);
+      row.bottom = Math.max(row.bottom, n.position.y + height(n));
+    } else {
+      rows.push({ bottom: n.position.y + height(n), items: [n] });
+    }
+  }
+
+  const positions = new Map<string, { x: number; y: number }>();
+  let y = GROUP_PADDING + GROUP_HEADER;
+  let right = 0;
+  for (const row of rows) {
+    let x = GROUP_PADDING;
+    for (const n of row.items.sort((a, b) => a.position.x - b.position.x)) {
+      positions.set(n.id, { x, y });
+      x += width(n) + GROUP_GAP;
+    }
+    right = Math.max(right, x - GROUP_GAP);
+    y += Math.max(...row.items.map(height)) + GROUP_GAP;
+  }
+
+  return {
+    positions,
+    size: {
+      width: Math.max(min.width, right + GROUP_PADDING),
+      height: Math.max(min.height, y - GROUP_GAP + GROUP_PADDING),
+    },
+  };
+}
+
+export type GroupOptions = {
+  /** The node type of the frame. Defaults to "group". */
+  type?: string;
+  /** Extra `data` on the frame beside its label. */
+  data?: Record<string, unknown>;
+};
+
+/** Wrap a selection in a frame node, or [] when there is nothing to group. */
+export function groupSelectionOps(
+  selected: Measurable[],
+  groupLabel: string,
+  { type = "group", data = {} }: GroupOptions = {},
+): CanvasOp[] {
+  if (selected.length < 2) return [];
+  const parentId = selected[0].parentId;
+  const members = selected.filter((n) => n.parentId === parentId);
+  if (members.length < 2) return [];
+
+  const width = (n: Measurable) => n.measured?.width ?? n.width ?? 200;
+  const height = (n: Measurable) => n.measured?.height ?? n.height ?? 100;
+  const minX = Math.min(...members.map((n) => n.position.x));
+  const minY = Math.min(...members.map((n) => n.position.y));
+  const maxX = Math.max(...members.map((n) => n.position.x + width(n)));
+  const maxY = Math.max(...members.map((n) => n.position.y + height(n)));
+
+  const origin = { x: minX - GROUP_PADDING, y: minY - GROUP_PADDING - GROUP_HEADER };
+  const groupId = crypto.randomUUID();
+
+  return [
+    {
+      kind: "addNode",
+      node: {
+        id: groupId,
+        type,
+        position: origin,
+        data: { ...data, label: groupLabel },
+        width: maxX - minX + GROUP_PADDING * 2,
+        height: maxY - minY + GROUP_PADDING * 2 + GROUP_HEADER,
+        ...(parentId ? { parentId } : {}),
+      },
+    },
+    ...members.flatMap((n): CanvasOp[] => [
+      { kind: "setParent", nodeId: n.id, parentId: groupId, extent: "parent" },
+      {
+        kind: "moveNode",
+        nodeId: n.id,
+        position: { x: n.position.x - origin.x, y: n.position.y - origin.y },
+      },
+    ]),
+  ];
+}

package/src/canvas/editor/lock.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vite-plus/test";
+import type { Node } from "@xyflow/svelte";
+import { deletableIds, refuseLockedOps, toggleLock, withLockFlags } from "./lock.js";
+
+function card(id: string, data: Record<string, unknown> = {}, extra: Partial<Node> = {}): Node {
+  return { id, type: "note", position: { x: 0, y: 0 }, data, ...extra };
+}
+
+describe("refuseLockedOps", () => {
+  const nodes = [card("free"), card("held", { locked: true })];
+
+  it("drops moves, edits and removals on a locked card", () => {
+    const ops = [
+      { kind: "moveNode", nodeId: "held", position: { x: 1, y: 1 } },
+      { kind: "patchNode", nodeId: "held", data: { content: "x" } },
+      { kind: "removeNode", nodeId: "held" },
+      { kind: "moveNode", nodeId: "free", position: { x: 1, y: 1 } },
+    ];
+    expect(refuseLockedOps(nodes, ops)).toEqual([ops[3]]);
+  });
+
+  it("lets a locked card be unlocked and linked", () => {
+    const ops = [
+      { kind: "patchNode", nodeId: "held", data: { locked: false } },
+      { kind: "addEdge", edge: { source: "held", target: "free" } },
+    ];
+    expect(refuseLockedOps(nodes, ops)).toEqual(ops);
+  });
+
+  it("refuses an unlock that also edits the card", () => {
+    const op = { kind: "patchNode", nodeId: "held", data: { locked: false, content: "x" } };
+    expect(refuseLockedOps(nodes, [op])).toEqual([]);
+  });
+});
+
+describe("toggleLock", () => {
+  it("locks, then unlocks when every pick is locked", () => {
+    const board = [card("a"), card("b", { locked: true })];
+    const locked = toggleLock(board, new Set(["a", "b"]));
+    expect(locked?.locked).toBe(true);
+    expect(locked?.nodes.every((n) => n.draggable === false && n.deletable === false)).toBe(true);
+    const unlocked = toggleLock(locked?.nodes ?? [], new Set(["a", "b"]));
+    expect(unlocked?.locked).toBe(false);
+    expect(unlocked?.nodes.some((n) => "draggable" in n)).toBe(false);
+  });
+
+  it("does nothing for an empty pick", () => {
+    expect(toggleLock([card("a")], new Set())).toBeNull();
+  });
+});
+
+describe("deletableIds", () => {
+  it("keeps a locked card and the group that holds one", () => {
+    const board = [
+      card("g", {}, { type: "wrapper" }),
+      card("held", { locked: true }, { parentId: "g" }),
+      card("free"),
+    ];
+    expect(deletableIds(board, ["g", "held", "free"])).toEqual(["free"]);
+  });
+});
+
+describe("withLockFlags", () => {
+  it("leaves a synced copy's own flags alone", () => {
+    const copy = card("c", { syncedCopy: true, locked: true });
+    expect(withLockFlags(copy)).toBe(copy);
+  });
+});

package/src/canvas/editor/lock.ts

@@ -0,0 +1,87 @@
+// A locked card can be selected, copied and connected, and nothing else. `data.locked` saves,
+// rebases and undoes with the card.
+
+import type { Node } from "@xyflow/svelte";
+import type { OpLike } from "../plugin.js";
+
+export function isLocked(node: { data?: unknown } | null | undefined): boolean {
+  const data = node?.data as Record<string, unknown> | undefined;
+  return data?.locked === true;
+}
+
+/** What xyflow needs to hold a locked card still. */
+export const LOCK_FLAGS = { draggable: false, deletable: false } as const;
+
+/** The card with its flow flags matching `data.locked`. A synced copy keeps its own flags. */
+export function withLockFlags<N extends Node>(node: N): N {
+  if ((node.data as Record<string, unknown> | undefined)?.syncedCopy) return node;
+  if (isLocked(node)) return { ...node, ...LOCK_FLAGS };
+  if (node.draggable !== false && node.deletable !== false) return node;
+  const { draggable: _drag, deletable: _delete, ...rest } = node;
+  return rest as N;
+}
+
+/** `locked` alone is the one data change a locked card takes: it is how it comes unlocked. */
+function onlyUnlocks(op: OpLike): boolean {
+  if (op.kind !== "patchNode") return false;
+  const patch = op as {
+    data?: Record<string, unknown>;
+    style?: unknown;
+    width?: unknown;
+    height?: unknown;
+  };
+  return (
+    patch.data !== undefined &&
+    patch.style === undefined &&
+    patch.width === undefined &&
+    patch.height === undefined &&
+    Object.keys(patch.data).every((key) => key === "locked")
+  );
+}
+
+/**
+ * The one gate every dispatched edit passes: ops that don't reach a locked card. An op on an
+ * arrow, or a card not on the board, passes.
+ */
+export function refuseLockedOps<Op extends OpLike>(
+  nodes: readonly Node[],
+  ops: readonly Op[],
+): Op[] {
+  const locked = new Set(nodes.filter(isLocked).map((node) => node.id));
+  if (locked.size === 0) return [...ops];
+  return ops.filter((op) => {
+    const nodeId = (op as { nodeId?: unknown }).nodeId;
+    return typeof nodeId !== "string" || !locked.has(nodeId) || onlyUnlocks(op);
+  });
+}
+
+/** Of these ids, the ones a delete may take: not locked, and not a group holding something locked. */
+export function deletableIds(nodes: readonly Node[], ids: readonly string[]): string[] {
+  const parentOf = new Map(nodes.map((node) => [node.id, node.parentId]));
+  const holdsLocked = new Set<string>();
+  for (const node of nodes) {
+    if (!isLocked(node)) continue;
+    for (let up = node.parentId; up; up = parentOf.get(up)) holdsLocked.add(up);
+  }
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  return ids.filter((id) => !isLocked(byId.get(id)) && !holdsLocked.has(id));
+}
+
+/** The board with the picked cards locked, or all unlocked when every one of them already was locked. */
+export function toggleLock(
+  nodes: readonly Node[],
+  picked: ReadonlySet<string>,
+): { nodes: Node[]; locked: boolean } | null {
+  const targets = nodes.filter(
+    (node) => picked.has(node.id) && !(node.data as { syncedCopy?: unknown }).syncedCopy,
+  );
+  if (targets.length === 0) return null;
+  const locked = !targets.every(isLocked);
+  const ids = new Set(targets.map((node) => node.id));
+  return {
+    locked,
+    nodes: nodes.map((node) =>
+      ids.has(node.id) ? withLockFlags({ ...node, data: { ...node.data, locked } }) : node,
+    ),
+  };
+}