@heyramzi/ui 1.54.1 → 2.0.0

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,
+    ),
+  };
+}

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

@@ -0,0 +1,208 @@
+import { expectDefined } from "../test-utils.js";
+import { describe, expect, it } from "vite-plus/test";
+import { applyOps } from "../ops/ops.js";
+import { diffToOps, rebaseDiagram, type DiagramDoc } from "./rebase.js";
+
+function doc(nodes: DiagramDoc["nodes"], edges: DiagramDoc["edges"] = []): DiagramDoc {
+  return { nodes, edges };
+}
+
+function n(id: string, overrides: Record<string, unknown> = {}): DiagramDoc["nodes"][number] {
+  return { id, type: "node", position: { x: 0, y: 0 }, data: { label: id }, ...overrides };
+}
+
+describe("diffToOps", () => {
+  it("returns no ops for identical docs", () => {
+    expect(diffToOps(doc([n("a")]), doc([n("a")]))).toEqual([]);
+  });
+
+  it("replaying the diff on the base reproduces the current doc", () => {
+    const base = doc(
+      [n("stay"), n("move"), n("gone"), n("container", { type: "space" })],
+      [{ id: "e1", source: "stay", target: "move" }],
+    );
+    const current = doc(
+      [
+        n("stay"),
+        n("move", { position: { x: 120, y: 80 }, data: { label: "renamed" } }),
+        n("container", { type: "space", style: { width: 400, height: 300 } }),
+        n("child", { parentId: "container", position: { x: 20, y: 60 } }),
+      ],
+      [
+        { id: "e1", source: "stay", target: "move", label: "flows" },
+        { id: "e2", source: "stay", target: "child" },
+      ],
+    );
+
+    const ops = diffToOps(base, current);
+    const replayed = applyOps({ nodes: base.nodes, edges: base.edges }, ops);
+
+    const byId = new Map(replayed.nodes.map((node) => [node.id, node]));
+    expect(byId.has("gone")).toBe(false);
+    expect(byId.get("move")?.position).toEqual({ x: 120, y: 80 });
+    expect(
+      (expectDefined(byId.get("move"), "entry move").data as Record<string, unknown>).label,
+    ).toBe("renamed");
+    expect(byId.get("container")?.style).toEqual({ width: 400, height: 300 });
+    expect(byId.get("child")?.parentId).toBe("container");
+    // parentId implies extent at the op seam
+    expect(byId.get("child")?.extent).toBe("parent");
+    const edgeById = new Map(replayed.edges.map((edge) => [edge.id, edge]));
+    expect(edgeById.get("e1")?.label).toBe("flows");
+    expect(edgeById.has("e2")).toBe(true);
+  });
+
+  it("orders added parents before added children", () => {
+    const base = doc([]);
+    const current = doc([
+      n("child", { parentId: "parent", position: { x: 10, y: 10 } }),
+      n("parent", { type: "space" }),
+    ]);
+    // Would throw "Unknown parentId" if the child op ran first.
+    const replayed = applyOps({ nodes: [], edges: [] }, diffToOps(base, current));
+    expect(replayed.nodes).toHaveLength(2);
+  });
+});
+
+describe("rebaseDiagram", () => {
+  const lastSaved = doc([n("a"), n("b")]);
+
+  it("replays local changes on top of the server doc", () => {
+    // Server: an agent added "agent-node". Local: the user renamed "a".
+    const serverDoc = doc([n("a"), n("b"), n("agent-node")]);
+    const local = doc([n("a", { data: { label: "renamed" } }), n("b")]);
+
+    const rebased = expectDefined(rebaseDiagram(serverDoc, lastSaved, local), "rebased doc");
+    const byId = new Map(rebased.nodes.map((node) => [node.id, node]));
+    expect(byId.has("agent-node")).toBe(true);
+    expect((expectDefined(byId.get("a"), "entry a").data as Record<string, unknown>).label).toBe(
+      "renamed",
+    );
+  });
+
+  it("returns the server doc unchanged when there are no local changes", () => {
+    const serverDoc = doc([n("a"), n("b"), n("agent-node")]);
+    const rebased = expectDefined(rebaseDiagram(serverDoc, lastSaved, lastSaved), "rebased doc");
+    expect(rebased.nodes.map((node) => node.id)).toEqual(["a", "b", "agent-node"]);
+  });
+
+  it("keeps a locally re-pointed edge endpoint and handles", () => {
+    const base = doc([n("a"), n("b"), n("c")], [{ id: "e1", source: "a", target: "b" }]);
+    const server = doc(
+      [n("a"), n("b"), n("c"), n("agent")],
+      [{ id: "e1", source: "a", target: "b" }],
+    );
+    const local = doc(
+      [n("a"), n("b"), n("c")],
+      [{ id: "e1", source: "a", target: "c", targetHandle: "left" }],
+    );
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    expect(rebased.edges).toEqual([{ id: "e1", source: "a", target: "c", targetHandle: "left" }]);
+  });
+
+  it("returns null when a re-pointed edge's new endpoint was deleted on the server", () => {
+    const base = doc([n("a"), n("b"), n("c")], [{ id: "e1", source: "a", target: "b" }]);
+    const server = doc([n("a"), n("b")], [{ id: "e1", source: "a", target: "b" }]);
+    const local = doc([n("a"), n("b"), n("c")], [{ id: "e1", source: "a", target: "c" }]);
+
+    expect(rebaseDiagram(server, base, local)).toBeNull();
+  });
+
+  it("patches zIndex and type changes, and a removed zIndex", () => {
+    const base = doc([n("a", { zIndex: 1 }), n("b"), n("c", { zIndex: 4 })]);
+    const server = doc([n("a", { zIndex: 1 }), n("b"), n("c", { zIndex: 4 }), n("agent")]);
+    const local = doc([n("a", { zIndex: 9 }), n("b", { type: "sticky" }), n("c")]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    const byId = new Map(rebased.nodes.map((node) => [node.id, node]));
+    expect(byId.get("a")?.zIndex).toBe(9);
+    expect(byId.get("b")?.type).toBe("sticky");
+    expect(byId.get("c")).not.toHaveProperty("zIndex");
+    expect(byId.has("agent")).toBe(true);
+  });
+
+  it("keeps both sides' edits to different data keys of the same node", () => {
+    const base = doc([n("a", { data: { label: "a", note: "old" } })]);
+    const server = doc([n("a", { data: { label: "a", note: "server note" } })]);
+    const local = doc([n("a", { data: { label: "local label", note: "old" } })]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    expect(rebased.nodes[0].data).toEqual({ label: "local label", note: "server note" });
+  });
+
+  it("lets local win when both sides edit the same data key", () => {
+    const base = doc([n("a", { data: { label: "a" } })]);
+    const server = doc([n("a", { data: { label: "server" } })]);
+    const local = doc([n("a", { data: { label: "local" } })]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    expect(rebased.nodes[0].data).toEqual({ label: "local" });
+  });
+
+  it("replaces a changed top-level data key whole, without merging inside it", () => {
+    const base = doc([n("a", { data: { shape: { kind: "box", fill: "red" } } })]);
+    const server = doc([n("a", { data: { shape: { kind: "box", fill: "red", ring: 2 } } })]);
+    const local = doc([n("a", { data: { shape: { kind: "box", fill: "blue" } } })]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    expect(rebased.nodes[0].data).toEqual({ shape: { kind: "box", fill: "blue" } });
+  });
+
+  it("removes a data key the local side deleted, and keeps the server's other keys", () => {
+    const base = doc([n("a", { data: { label: "a", icon: "x", note: "old" } })]);
+    const server = doc([n("a", { data: { label: "a", icon: "x", note: "server note" } })]);
+    const local = doc([n("a", { data: { label: "a", note: "old" } })]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    expect(rebased.nodes[0].data).toEqual({ label: "a", note: "server note" });
+    expect(rebased.nodes[0].data).not.toHaveProperty("icon");
+  });
+
+  it("returns null when a field-only change hits a node the server deleted", () => {
+    const base = doc([n("a"), n("b")]);
+    const server = doc([n("a")]);
+    const local = doc([n("a"), n("b", { zIndex: 3 })]);
+
+    expect(rebaseDiagram(server, base, local)).toBeNull();
+  });
+
+  it("keeps parents before children when a local reparent targets a later server node", () => {
+    const base = doc([n("child"), n("box", { type: "space" })]);
+    const server = doc([n("child"), n("box", { type: "space" })]);
+    const local = doc([
+      n("box", { type: "space" }),
+      n("child", { parentId: "box", position: { x: 10, y: 10 } }),
+    ]);
+
+    const rebased = expectDefined(rebaseDiagram(server, base, local), "rebased doc");
+    const ids = rebased.nodes.map((node) => node.id);
+    expect(ids.indexOf("box")).toBeLessThan(ids.indexOf("child"));
+  });
+
+  it("returns null when the replay is impossible", () => {
+    // Server deleted "b"; local patched it. patchNode on a missing node throws.
+    const serverDoc = doc([n("a")]);
+    const local = doc([n("a"), n("b", { data: { label: "edited" } })]);
+    expect(rebaseDiagram(serverDoc, lastSaved, local)).toBeNull();
+  });
+});
+
+describe("a new edge keeps everything it was drawn with", () => {
+  it("carries label, animated, style and data through a rebase", () => {
+    const base = doc([n("a"), n("b")]);
+    const styled = {
+      id: "e9",
+      source: "a",
+      target: "b",
+      type: "smoothstep",
+      label: "pays",
+      animated: true,
+      style: { stroke: "#f00", strokeWidth: 3 },
+      data: { dash: "dotted", arrow: "both" },
+    };
+    const local = doc([n("a"), n("b")], [styled]);
+    const rebased = rebaseDiagram(doc([n("a"), n("b"), n("c")]), base, local);
+    expect(rebased?.edges).toEqual([styled]);
+  });
+});

package/src/canvas/editor/rebase.ts

@@ -0,0 +1,272 @@
+// Conflict rebase for the autosave PUT. On a 409, local changes since the last
+// save replay as ops on the server document, instead of overwriting the other writer.
+
+import { tryCatch } from "../../lib/result.js";
+import { applyOps, type CanvasOp } from "../ops/ops.js";
+import type { RawCanvasData } from "../types.js";
+import { sortParentsFirst } from "../headless/canvas-cleanup.js";
+
+type DocNode = Record<string, unknown> & {
+  id: string;
+  position?: { x: number; y: number };
+  parentId?: string;
+  data?: Record<string, unknown>;
+  style?: unknown;
+  width?: unknown;
+  height?: unknown;
+  type?: unknown;
+};
+type DocEdge = Record<string, unknown> & { id: string };
+export type DiagramDoc = { nodes: DocNode[]; edges: DocEdge[] };
+
+const EDGE_PATCH_FIELDS = [
+  "source",
+  "target",
+  "label",
+  "animated",
+  "type",
+  "style",
+  "sourceHandle",
+  "targetHandle",
+] as const;
+
+function json(value: unknown): string {
+  return JSON.stringify(value ?? null);
+}
+
+type SizePatch = { style?: Record<string, unknown>; width?: number; height?: number };
+
+function objectStyle(node: DocNode): Record<string, unknown> | undefined {
+  return node.style && typeof node.style === "object"
+    ? (node.style as Record<string, unknown>)
+    : undefined;
+}
+
+function numberOrUndefined(value: unknown): number | undefined {
+  return typeof value === "number" ? value : undefined;
+}
+
+function addNodeOp(node: DocNode): CanvasOp {
+  const style = objectStyle(node);
+  const width = numberOrUndefined(node.width);
+  const height = numberOrUndefined(node.height);
+  return {
+    kind: "addNode",
+    node: {
+      id: node.id,
+      type: String(node.type ?? "node"),
+      position: node.position ?? { x: 0, y: 0 },
+      data: node.data ?? {},
+      ...(style ? { style } : {}),
+      ...(width !== undefined ? { width } : {}),
+      ...(height !== undefined ? { height } : {}),
+      ...(node.parentId ? { parentId: node.parentId } : {}),
+    },
+  };
+}
+
+function sizePatchOf(before: DocNode, node: DocNode): SizePatch {
+  const patch: SizePatch = {};
+  const style = objectStyle(node);
+  if (style && json(before.style) !== json(node.style)) patch.style = style;
+  const width = numberOrUndefined(node.width);
+  if (width !== undefined && before.width !== node.width) patch.width = width;
+  const height = numberOrUndefined(node.height);
+  if (height !== undefined && before.height !== node.height) patch.height = height;
+  return patch;
+}
+
+/** Only the top-level keys local changed, so a key the server edited alone keeps its value. */
+function changedData(
+  before: Record<string, unknown> | undefined,
+  data: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!data) return undefined;
+  const changed = Object.entries(data).filter(
+    ([key, value]) => json(before?.[key]) !== json(value),
+  );
+  return changed.length > 0 ? Object.fromEntries(changed) : undefined;
+}
+
+function changedNodeOps(before: DocNode, node: DocNode): CanvasOp[] {
+  const ops: CanvasOp[] = [];
+  if (node.position && json(before.position) !== json(node.position)) {
+    ops.push({ kind: "moveNode", nodeId: node.id, position: node.position });
+  }
+  const parentId = node.parentId ?? null;
+  if ((before.parentId ?? null) !== parentId) {
+    ops.push({ kind: "setParent", nodeId: node.id, parentId });
+  }
+  const data = changedData(before.data, node.data);
+  if (data) ops.push({ kind: "patchNode", nodeId: node.id, data });
+  const sizePatch = sizePatchOf(before, node);
+  if (Object.keys(sizePatch).length > 0) {
+    ops.push({ kind: "patchNode", nodeId: node.id, ...sizePatch });
+  }
+  return ops;
+}
+
+function nodeOps(base: DiagramDoc, current: DiagramDoc): CanvasOp[] {
+  const baseNodes = new Map(base.nodes.map((n) => [n.id, n]));
+  const currentIds = new Set(current.nodes.map((n) => n.id));
+  const removed: CanvasOp[] = base.nodes
+    .filter((n) => !currentIds.has(n.id))
+    .map((n) => ({ kind: "removeNode", nodeId: n.id }));
+
+  // WHY parents first: an added child references its added parent in the same
+  // batch, and applyOps validates parent existence at each step.
+  const added = sortParentsFirst(current.nodes.filter((n) => !baseNodes.has(n.id))).map(addNodeOp);
+
+  const changed = current.nodes.flatMap((node) => {
+    const before = baseNodes.get(node.id);
+    return before ? changedNodeOps(before, node) : [];
+  });
+  return [...removed, ...added, ...changed];
+}
+
+function addEdgeOp(edge: DocEdge): CanvasOp {
+  const optional = (key: "sourceHandle" | "targetHandle" | "type" | "label") =>
+    typeof edge[key] === "string" ? { [key]: edge[key] } : {};
+  const record = (key: "style" | "data") => {
+    const value = edge[key];
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? { [key]: value as Record<string, unknown> }
+      : {};
+  };
+  return {
+    kind: "addEdge",
+    edge: {
+      id: edge.id,
+      source: String(edge.source),
+      target: String(edge.target),
+      ...optional("sourceHandle"),
+      ...optional("targetHandle"),
+      ...optional("type"),
+      ...optional("label"),
+      ...(typeof edge.animated === "boolean" ? { animated: edge.animated } : {}),
+      ...record("style"),
+      ...record("data"),
+    },
+  };
+}
+
+function patchEdgeOps(before: DocEdge, edge: DocEdge): CanvasOp[] {
+  const patch: Record<string, unknown> = {};
+  for (const field of EDGE_PATCH_FIELDS) {
+    if (edge[field] !== undefined && json(before[field]) !== json(edge[field])) {
+      patch[field] = edge[field];
+    }
+  }
+  if (Object.keys(patch).length === 0) return [];
+  return [{ kind: "patchEdge", edgeId: edge.id, patch } as CanvasOp];
+}
+
+function edgeOps(base: DiagramDoc, current: DiagramDoc): CanvasOp[] {
+  const baseEdges = new Map(base.edges.map((e) => [e.id, e]));
+  const currentIds = new Set(current.edges.map((e) => e.id));
+  const removed: CanvasOp[] = base.edges
+    .filter((e) => !currentIds.has(e.id))
+    .map((e) => ({ kind: "removeEdge", edgeId: e.id }));
+  const upserted = current.edges.flatMap((edge) => {
+    const before = baseEdges.get(edge.id);
+    return before ? patchEdgeOps(before, edge) : [addEdgeOp(edge)];
+  });
+  return [...removed, ...upserted];
+}
+
+/**
+ * Diff two persisted documents into ops. Data patches carry only changed keys. A deleted
+ * data key, and a node's `type` or `zIndex`, have no op: `nodeFieldPatches` carries those.
+ */
+export function diffToOps(base: DiagramDoc, current: DiagramDoc): CanvasOp[] {
+  return [...nodeOps(base, current), ...edgeOps(base, current)];
+}
+
+type NodeFieldPatch = {
+  nodeId: string;
+  set: Record<string, unknown>;
+  unset: string[];
+  unsetData: string[];
+};
+
+const NODE_FIELDS = ["type", "zIndex"] as const;
+
+/** What changed on a node that `patchNode` can't say: `type`, `zIndex` and deleted data keys. */
+function nodeFieldPatches(base: DiagramDoc, current: DiagramDoc): NodeFieldPatch[] {
+  const baseNodes = new Map(base.nodes.map((n) => [n.id, n]));
+  const patches: NodeFieldPatch[] = [];
+  for (const node of current.nodes) {
+    const before = baseNodes.get(node.id);
+    if (!before) continue;
+    const set: Record<string, unknown> = {};
+    const unset: string[] = [];
+    for (const field of NODE_FIELDS) {
+      if (json(before[field]) === json(node[field])) continue;
+      if (node[field] === undefined) unset.push(field);
+      else set[field] = node[field];
+    }
+    const unsetData = Object.keys(before.data ?? {}).filter((key) => !(key in (node.data ?? {})));
+    if (unset.length + unsetData.length + Object.keys(set).length > 0) {
+      patches.push({ nodeId: node.id, set, unset, unsetData });
+    }
+  }
+  return patches;
+}
+
+function withoutKeys(record: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(record).filter(([key]) => !keys.includes(key)));
+}
+
+/** Null when a patched node is gone, the same answer `applyOps` gives for an op on a missing node. */
+function applyNodeFieldPatches(
+  nodes: Record<string, unknown>[],
+  patches: NodeFieldPatch[],
+): Record<string, unknown>[] | null {
+  const byId = new Map(patches.map((patch) => [patch.nodeId, patch]));
+  const seen = new Set<string>();
+  const next = nodes.map((node) => {
+    const patch = typeof node.id === "string" ? byId.get(node.id) : undefined;
+    if (!patch) return node;
+    seen.add(patch.nodeId);
+    const patched = withoutKeys({ ...node, ...patch.set }, patch.unset);
+    if (patch.unsetData.length === 0 || typeof node.data !== "object" || node.data === null) {
+      return patched;
+    }
+    return { ...patched, data: withoutKeys(node.data as Record<string, unknown>, patch.unsetData) };
+  });
+  return seen.size === byId.size ? next : null;
+}
+
+/** A local reparent can name a container that sits later in the server's order. */
+function parentsFirst(nodes: Record<string, unknown>[]): Record<string, unknown>[] {
+  const ids = new Set(nodes.map((node) => node.id));
+  const seen = new Set<unknown>();
+  const misordered = nodes.some((node) => {
+    const early = ids.has(node.parentId) && !seen.has(node.parentId);
+    seen.add(node.id);
+    return early;
+  });
+  if (!misordered) return nodes;
+  const wrapped = nodes.map((node) => ({
+    id: String(node.id),
+    parentId: typeof node.parentId === "string" ? node.parentId : undefined,
+    node,
+  }));
+  return sortParentsFirst(wrapped).map(({ node }) => node);
+}
+
+/**
+ * Replay local changes (lastSaved -> local) on the server document. Returns
+ * null when impossible, like a patched node deleted, so the save error shows.
+ */
+export function rebaseDiagram(
+  serverDoc: DiagramDoc,
+  lastSaved: DiagramDoc,
+  local: DiagramDoc,
+): RawCanvasData | null {
+  const ops = diffToOps(lastSaved, local);
+  const res = tryCatch(() => applyOps({ nodes: serverDoc.nodes, edges: serverDoc.edges }, ops));
+  if (!res.ok) return null;
+  const nodes = applyNodeFieldPatches(res.value.nodes, nodeFieldPatches(lastSaved, local));
+  return nodes ? { ...res.value, nodes: parentsFirst(nodes) } : null;
+}