@multiplatform.one/node-graph 7.7.2

package/src/model/connect.ts

@@ -0,0 +1,281 @@
+/* oxlint-disable typescript/no-explicit-any -- the built-in rules are schema
+   agnostic by design (§4.4 writes them `ConnectionRule<any, any>`). A generic
+   parameter here would make them invariant in N and E, so `defaultRules` could
+   not be dropped into any consumer's schema — which is the one thing they are
+   for. The brand still bites: `DropOnlyRule<any, any>` is refused by
+   `validateConnection` because it lacks `tickSafe`, not because of variance. */
+
+/**
+ * Connection rules, design §4.4. Cheap and expensive kept apart, as a TYPE.
+ *
+ * React Flow calls `isValidConnection` on every pointer tick of a connection
+ * drag, so anything on that path is paid per mouse move. Every rule here is
+ * O(1) or O(edges of one port) and carries the `tickSafe` marker.
+ * `refuseCycle` is O(V+E) and does NOT carry it, so `validateConnection` will
+ * not take it — the compiler refuses, rather than a comment asking nicely.
+ * `connect.spec.ts` pins that with a `@ts-expect-error` that fails if the two
+ * types ever collapse.
+ */
+
+import type { EdgeKindDefs, GraphDocument, NodeKindDefs, PortRef } from "./document";
+import type { GraphSchema, PortSpec } from "./schema";
+import { portArity, resolvePorts } from "./schema";
+
+export type ConnectionVerdict =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: string; readonly message: string };
+
+export interface ConnectionContext<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly document: GraphDocument<N, E>;
+  readonly schema: GraphSchema<N, E>;
+  /** The candidate. Not yet in `document.edges`. */
+  readonly source: PortRef;
+  readonly target: PortRef;
+}
+
+export type ConnectionCheck<N extends NodeKindDefs, E extends EdgeKindDefs> = (
+  ctx: ConnectionContext<N, E>,
+) => ConnectionVerdict;
+
+/**
+ * A rule cheap enough for the pointer-tick path.
+ *
+ * The marker is real at runtime, not a phantom, so a rule array can be checked
+ * as well as typed — and so `defineConnectionRule` is the only way to claim it
+ * without reaching for a cast, which makes the claim a deliberate act.
+ */
+export type ConnectionRule<N extends NodeKindDefs, E extends EdgeKindDefs> = ConnectionCheck<
+  N,
+  E
+> & { readonly tickSafe: true };
+
+/**
+ * A rule that runs once, on drop. Every `ConnectionRule` is also one of these;
+ * the reverse is what the type refuses.
+ */
+export type DropOnlyRule<N extends NodeKindDefs, E extends EdgeKindDefs> = ConnectionCheck<N, E>;
+
+export function defineConnectionRule<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  check: ConnectionCheck<N, E>,
+): ConnectionRule<N, E> {
+  return Object.assign(check, { tickSafe: true } as const);
+}
+
+const pass: ConnectionVerdict = { ok: true };
+
+function refuse(code: string, message: string): ConnectionVerdict {
+  return { ok: false, code, message };
+}
+
+interface Resolved {
+  readonly port: PortSpec;
+}
+
+type Lookup = Resolved | { readonly problem: ConnectionVerdict };
+
+function lookup<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  ctx: ConnectionContext<N, E>,
+  ref: PortRef,
+  end: "source" | "target",
+): Lookup {
+  const node = ctx.document.nodes.find((candidate) => candidate.id === ref.node);
+  if (!node) {
+    return {
+      problem: refuse(
+        "unknown-node",
+        `the ${end} names node ${JSON.stringify(ref.node)}, which is not in this document`,
+      ),
+    };
+  }
+  const port = resolvePorts(ctx.schema, node).find((candidate) => candidate.id === ref.port);
+  if (!port) {
+    return {
+      problem: refuse(
+        "unknown-port",
+        `node ${JSON.stringify(ref.node)} has no port ${JSON.stringify(ref.port)}`,
+      ),
+    };
+  }
+  return { port };
+}
+
+function isResolved(value: Lookup): value is Resolved {
+  return "port" in value;
+}
+
+/**
+ * Out to in, and nothing else.
+ *
+ * This rule is FIRST in `defaultRules`, which is also why it owns the two
+ * lookup failures. Every other rule treats an unresolvable end as none of its
+ * business and passes, so each rule refuses exactly its own case and the
+ * "refuses its own, passes the other four" matrix in the spec stays honest.
+ */
+export const refuseDirection: ConnectionRule<any, any> = defineConnectionRule((ctx) => {
+  const source = lookup(ctx, ctx.source, "source");
+  if (!isResolved(source)) return source.problem;
+  const target = lookup(ctx, ctx.target, "target");
+  if (!isResolved(target)) return target.problem;
+  if (source.port.direction !== "out") {
+    return refuse(
+      "wrong-direction",
+      `${ctx.source.port} is an input; a connection starts at an output`,
+    );
+  }
+  if (target.port.direction !== "in") {
+    return refuse(
+      "wrong-direction",
+      `${ctx.target.port} is an output; a connection ends at an input`,
+    );
+  }
+  return pass;
+});
+
+export const refuseSelfLoop: ConnectionRule<any, any> = defineConnectionRule((ctx) =>
+  ctx.source.node === ctx.target.node
+    ? refuse("self-loop", `node ${JSON.stringify(ctx.source.node)} cannot connect to itself`)
+    : pass,
+);
+
+/** "one" means one edge on that port, in that direction. */
+export const refusePortArity: ConnectionRule<any, any> = defineConnectionRule((ctx) => {
+  const source = lookup(ctx, ctx.source, "source");
+  const target = lookup(ctx, ctx.target, "target");
+  if (isResolved(source) && portArity(source.port) === "one") {
+    const taken = ctx.document.edges.some(
+      (edge) => edge.source.node === ctx.source.node && edge.source.port === ctx.source.port,
+    );
+    if (taken) {
+      return refuse(
+        "port-arity",
+        `port ${JSON.stringify(ctx.source.port)} takes one connection and already has it`,
+      );
+    }
+  }
+  if (isResolved(target) && portArity(target.port) === "one") {
+    const taken = ctx.document.edges.some(
+      (edge) => edge.target.node === ctx.target.node && edge.target.port === ctx.target.port,
+    );
+    if (taken) {
+      return refuse(
+        "port-arity",
+        `port ${JSON.stringify(ctx.target.port)} takes one connection and already has it`,
+      );
+    }
+  }
+  return pass;
+});
+
+export const refuseDuplicate: ConnectionRule<any, any> = defineConnectionRule((ctx) =>
+  ctx.document.edges.some(
+    (edge) =>
+      edge.source.node === ctx.source.node &&
+      edge.source.port === ctx.source.port &&
+      edge.target.node === ctx.target.node &&
+      edge.target.port === ctx.target.port,
+  )
+    ? refuse("duplicate-edge", "these two ports are already connected")
+    : pass,
+);
+
+/**
+ * An untyped port connects to anything, so `dataType` stays opt-in: a schema
+ * that never sets it never trips this rule.
+ */
+export function refuseDataTypeMismatch(
+  compatible: (from: string, to: string) => boolean = (from, to) => from === to,
+): ConnectionRule<any, any> {
+  return defineConnectionRule((ctx) => {
+    const source = lookup(ctx, ctx.source, "source");
+    const target = lookup(ctx, ctx.target, "target");
+    if (!isResolved(source) || !isResolved(target)) return pass;
+    const from = source.port.dataType;
+    const to = target.port.dataType;
+    if (from === undefined || to === undefined) return pass;
+    return compatible(from, to)
+      ? pass
+      : refuse("data-type-mismatch", `a ${from} output does not fit a ${to} input`);
+  });
+}
+
+/**
+ * O(V+E) DFS from the candidate's target back to its source. NOT a
+ * `ConnectionRule` — see the type above. Its cost at 200 nodes / 400 edges is
+ * unmeasured, and it is a bench line before it is ever recommended.
+ */
+export function refuseCycle(): DropOnlyRule<any, any> {
+  return (ctx) => {
+    if (ctx.source.node === ctx.target.node) {
+      return refuse("cycle", "a node cannot feed itself");
+    }
+    const out = new Map<string, string[]>();
+    for (const edge of ctx.document.edges) {
+      const list = out.get(edge.source.node);
+      if (list) list.push(edge.target.node);
+      else out.set(edge.source.node, [edge.target.node]);
+    }
+    // Walk forward from where the candidate LANDS. Reaching where it starts
+    // means the candidate closes a loop.
+    const seen = new Set<string>();
+    const stack = [ctx.target.node];
+    while (stack.length > 0) {
+      const current = stack.pop() as string;
+      if (current === ctx.source.node) {
+        return refuse(
+          "cycle",
+          `connecting these would make ${JSON.stringify(ctx.source.node)} reachable from itself`,
+        );
+      }
+      if (seen.has(current)) continue;
+      seen.add(current);
+      const next = out.get(current);
+      if (next) stack.push(...next);
+    }
+    return pass;
+  };
+}
+
+/**
+ * Order matters: first refusal wins, and `refuseDirection` is first so an
+ * impossible pair reports the reason a user can act on rather than whichever
+ * rule happened to be checked first.
+ */
+export const defaultRules: readonly ConnectionRule<any, any>[] = [
+  refuseDirection,
+  refuseSelfLoop,
+  refusePortArity,
+  refuseDuplicate,
+  refuseDataTypeMismatch(),
+];
+
+export const defaultDropRules: readonly DropOnlyRule<any, any>[] = [refuseCycle()];
+
+/**
+ * The pointer-tick path. Takes `ConnectionRule`s only; a `DropOnlyRule` is a
+ * compile error, which is the whole point of the split.
+ */
+export function validateConnection<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  ctx: ConnectionContext<N, E>,
+  rules: readonly ConnectionRule<N, E>[] = ctx.schema.rules,
+): ConnectionVerdict {
+  for (const rule of rules) {
+    const verdict = rule(ctx);
+    if (!verdict.ok) return verdict;
+  }
+  return pass;
+}
+
+/** The drop path. Takes both, tick-safe rules first. */
+export function validateDrop<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  ctx: ConnectionContext<N, E>,
+  rules: readonly ConnectionRule<N, E>[] = ctx.schema.rules,
+  dropRules: readonly DropOnlyRule<N, E>[] = ctx.schema.dropRules,
+): ConnectionVerdict {
+  const cheap = validateConnection(ctx, rules);
+  if (!cheap.ok) return cheap;
+  for (const rule of dropRules) {
+    const verdict = rule(ctx);
+    if (!verdict.ok) return verdict;
+  }
+  return pass;
+}

package/src/model/document.ts

@@ -0,0 +1,121 @@
+/**
+ * The document. Types only — no React, no DOM, no `@xyflow`, no runtime.
+ *
+ * Design §4.1 and §4.2. This is what a server, a CLI, a Frappe hook or the CI
+ * bench imports when it wants the shape of a graph and nothing else.
+ */
+
+/**
+ * Ids are deliberately unbranded. They cross a JSON bridge, become React keys
+ * and CSS selectors, and a cast at every wire boundary would be noise.
+ * `PortRef` already removes the bug branding would have caught.
+ */
+export type NodeId = string;
+export type EdgeId = string;
+export type PortId = string;
+
+export interface XY {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface Size {
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface Rect extends XY, Size {}
+
+export interface Viewport extends XY {
+  readonly zoom: number;
+}
+
+/** The struct is what prevents id confusion, so ids stay plain strings. */
+export interface PortRef {
+  readonly node: NodeId;
+  readonly port: PortId;
+}
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+  | JsonPrimitive
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/**
+ * A literal, on purpose. Bumping it to `2` is a compile error at every
+ * construction site in the repo, which is the review moment a schema change
+ * deserves. There is no migration chain in v1 because there is nothing to
+ * migrate from, and a speculative one is the kind of generality that rots.
+ */
+export type GraphDocumentVersion = 1;
+
+export type NodeKindDefs = Record<string, unknown>;
+export type EdgeKindDefs = Record<string, unknown>;
+
+export type GraphNodeOf<N extends NodeKindDefs> = {
+  [K in keyof N & string]: {
+    readonly id: NodeId;
+    readonly kind: K;
+    readonly position: XY;
+    readonly data: N[K];
+    /** Seeded from `NodeKindSpec.measure` + resolved knobs BEFORE first paint. */
+    readonly size?: Size;
+    readonly parent?: NodeId;
+    readonly locked?: boolean;
+  };
+}[keyof N & string];
+
+export type GraphEdgeOf<E extends EdgeKindDefs> = {
+  [K in keyof E & string]: {
+    readonly id: EdgeId;
+    readonly kind: K;
+    readonly source: PortRef;
+    readonly target: PortRef;
+    readonly data: E[K];
+    readonly label?: string;
+  };
+}[keyof E & string];
+
+export interface GraphDocument<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly version: GraphDocumentVersion;
+  readonly nodes: readonly GraphNodeOf<N>[];
+  readonly edges: readonly GraphEdgeOf<E>[];
+  readonly viewport?: Viewport;
+  readonly meta?: Readonly<Record<string, JsonValue>>;
+}
+
+/**
+ * The slice of a schema `parseDocument` actually reads: which kinds exist.
+ *
+ * Design §4.6 writes `parseDocument(raw, schema: GraphSchema<N, E>)`, and that
+ * call shape is unchanged — task 1.3's `GraphSchema` extends this. The split
+ * exists because parsing needs kind NAMES and nothing else: no `render`, no
+ * `measure`, no rules. So `serialize.ts` does not have to import a module full
+ * of React component types to check that `"wormhole"` is not a node kind, and
+ * the model's serialization half stays importable on its own.
+ *
+ * `__types` is phantom. It is never read at runtime; it exists so `N` and `E`
+ * flow from the schema into the parsed document's type.
+ */
+export interface DocumentSchema<
+  N extends NodeKindDefs = NodeKindDefs,
+  E extends EdgeKindDefs = EdgeKindDefs,
+> {
+  readonly nodes: Readonly<Record<string, unknown>>;
+  readonly edges: Readonly<Record<string, unknown>>;
+  readonly __types?: { readonly nodes: N; readonly edges: E };
+}
+
+/** One thing wrong with a document, and where. */
+export interface DocumentProblem {
+  /** A JSON-ish path into the input, e.g. `nodes[1].position.x`. */
+  readonly path: string;
+  /** Stable, machine-readable. Messages are for humans and may be reworded. */
+  readonly code: string;
+  readonly message: string;
+}
+
+export type Result<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };

package/src/model/history.spec.ts

@@ -0,0 +1,278 @@
+/**
+ * The undo journal, design §4.5.
+ *
+ * "A drag is one undo. A relayout is one undo, and it never coalesces with a
+ * drag." Both halves are here, and so is the reason the second half is not
+ * automatic: a pointer drag emits a `moveNodes` per frame, so without
+ * coalescing a two-second drag buries the stack under 120 entries and undo
+ * becomes useless. Coalescing too eagerly is the opposite failure — a tidy
+ * swallowed into the drag before it, and one undo that cannot get the old
+ * arrangement back.
+ *
+ * Time is injected rather than faked globally: the module is pure, so a `now`
+ * function is a smaller seam than `vi.useFakeTimers` and it cannot leak.
+ */
+
+import { describe, expect, it } from "vitest";
+import { applyCommand } from "./commands";
+import type { GraphCommand } from "./commands";
+import type { GraphDocument } from "./document";
+import { createHistory } from "./history";
+
+type Nodes = { readonly task: { readonly title: string } };
+type Edges = { readonly flow: Record<string, never> };
+type Doc = GraphDocument<Nodes, Edges>;
+
+const doc: Doc = {
+  version: 1,
+  nodes: [
+    { id: "a", kind: "task", position: { x: 0, y: 0 }, data: { title: "a" } },
+    { id: "b", kind: "task", position: { x: 100, y: 0 }, data: { title: "b" } },
+  ],
+  edges: [],
+};
+
+function clock(start = 1_000) {
+  let t = start;
+  return { now: () => t, tick: (ms: number) => (t += ms) };
+}
+
+const drag = (dx: number): GraphCommand<Nodes, Edges> => ({
+  t: "moveNodes",
+  deltas: { a: { x: dx, y: 0 }, b: { x: dx, y: 0 } },
+});
+
+const relayout: GraphCommand<Nodes, Edges> = {
+  t: "setPositions",
+  positions: { a: { x: 0, y: 0 }, b: { x: 0, y: 60 } },
+};
+
+describe("a 30-step drag", () => {
+  // 20 ms a step, so the gesture runs 580 ms — LONGER than the 400 ms default.
+  // That is deliberate: the window measures the gap since the last movement,
+  // not since the gesture began, and a fixed window would break this drag into
+  // 21 entries while a 290 ms one would pass either way.
+  it("coalesces to one entry", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    let current = doc;
+    for (let i = 0; i < 30; i++) {
+      current = history.commit(current, drag(1));
+      time.tick(20);
+    }
+    expect(history.depth()).toBe(1);
+  });
+
+  it("composes the deltas by addition", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    let current = doc;
+    for (let i = 0; i < 30; i++) {
+      current = history.commit(current, drag(1));
+      time.tick(20);
+    }
+    expect(current.nodes.map((n) => n.position.x)).toEqual([30, 130]);
+    const entry = history.entries()[0];
+    expect(entry.redo).toEqual({
+      t: "moveNodes",
+      deltas: { a: { x: 30, y: 0 }, b: { x: 30, y: 0 } },
+    });
+    expect(entry.undo).toEqual({
+      t: "moveNodes",
+      deltas: { a: { x: -30, y: 0 }, b: { x: -30, y: 0 } },
+    });
+  });
+
+  it("is one undo, all the way back", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    let current = doc;
+    for (let i = 0; i < 30; i++) {
+      current = history.commit(current, drag(1));
+      time.tick(20);
+    }
+    expect(history.undo(current)).toEqual(doc);
+  });
+
+  it("starts a new entry once the pointer has been still longer than coalesceMs", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    let current = history.commit(doc, drag(1));
+    time.tick(401);
+    current = history.commit(current, drag(1));
+    expect(history.depth()).toBe(2);
+  });
+
+  it("does not coalesce two drags of DIFFERENT node sets", () => {
+    // Two nodes dragged one after the other is two undos, not one.
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    let current = history.commit(doc, { t: "moveNodes", deltas: { a: { x: 1, y: 0 } } });
+    time.tick(10);
+    current = history.commit(current, { t: "moveNodes", deltas: { b: { x: 1, y: 0 } } });
+    expect(history.depth()).toBe(2);
+  });
+});
+
+describe("a relayout", () => {
+  it("is one entry", () => {
+    const history = createHistory<Nodes, Edges>({ now: clock().now });
+    history.commit(doc, relayout);
+    expect(history.depth()).toBe(1);
+  });
+
+  it("never coalesces with the drag before it, even inside coalesceMs", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    let current = history.commit(doc, drag(5));
+    time.tick(1);
+    current = history.commit(current, relayout);
+    expect(history.depth()).toBe(2);
+  });
+
+  it("never coalesces with the drag after it either", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    let current = history.commit(doc, relayout);
+    time.tick(1);
+    current = history.commit(current, drag(5));
+    expect(history.depth()).toBe(2);
+  });
+
+  it("never coalesces with another relayout", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    let current = history.commit(doc, relayout);
+    time.tick(1);
+    current = history.commit(current, relayout);
+    expect(history.depth()).toBe(2);
+  });
+
+  it("restores the whole pre-layout arrangement in one undo", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    const scattered = applyCommand(doc, {
+      t: "setPositions",
+      positions: { a: { x: 7, y: 7 }, b: { x: 9, y: 9 } },
+    });
+    const tidied = history.commit(scattered, relayout);
+    expect(tidied.nodes.map((n) => n.position)).toEqual([
+      { x: 0, y: 0 },
+      { x: 0, y: 60 },
+    ]);
+    expect(history.undo(tidied)).toEqual(scattered);
+  });
+});
+
+describe("the limit", () => {
+  it("evicts the oldest entry", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, limit: 3 });
+    let current = doc;
+    for (let i = 0; i < 5; i++) {
+      current = history.commit(current, drag(1));
+      time.tick(1_000);
+    }
+    expect(history.depth()).toBe(3);
+  });
+
+  it("cannot undo past what it evicted", () => {
+    // Powers of two, not five identical steps: with 1,1,1,1,1 the sum of the
+    // last three equals the sum of the first three, so evicting the WRONG end
+    // lands on the same number and the test proves nothing.
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, limit: 3 });
+    let current = doc;
+    for (const step of [1, 2, 4, 8, 16]) {
+      current = history.commit(current, drag(step));
+      time.tick(1_000);
+    }
+    expect(current.nodes[0].position.x).toBe(31);
+    for (let i = 0; i < 3; i++) current = history.undo(current);
+    expect(history.canUndo()).toBe(false);
+    // 4, 8 and 16 are undoable; 1 and 2 were evicted and are gone for good.
+    expect(current.nodes[0].position.x).toBe(3);
+  });
+});
+
+describe("redo", () => {
+  it("comes back to where undo left", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    const moved = history.commit(doc, drag(5));
+    const undone = history.undo(moved);
+    expect(undone).toEqual(doc);
+    expect(history.canRedo()).toBe(true);
+    expect(history.redo(undone)).toEqual(moved);
+  });
+
+  it("clears on a new command", () => {
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now });
+    const moved = history.commit(doc, drag(5));
+    const undone = history.undo(moved);
+    expect(history.canRedo()).toBe(true);
+    time.tick(1_000);
+    history.commit(undone, drag(2));
+    expect(history.canRedo()).toBe(false);
+  });
+
+  it("does not coalesce into an earlier entry when a redo is pending", () => {
+    // The guard only matters when the past is non-empty TOO. A drag on `a`, a
+    // drag on `b`, one undo, then another drag on `a` inside coalesceMs of the
+    // first: without the guard that folds into entry A while B still sits on
+    // the redo stack, and redo would then replay B onto a document that never
+    // had it.
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    const onlyA = (dx: number): GraphCommand<Nodes, Edges> => ({
+      t: "moveNodes",
+      deltas: { a: { x: dx, y: 0 } },
+    });
+    let current = history.commit(doc, onlyA(5));
+    time.tick(1);
+    current = history.commit(current, { t: "moveNodes", deltas: { b: { x: 5, y: 0 } } });
+    expect(history.depth()).toBe(2);
+    current = history.undo(current);
+    expect(history.canRedo()).toBe(true);
+    time.tick(1);
+    current = history.commit(current, onlyA(2));
+    expect(history.depth()).toBe(2);
+    expect(history.canRedo()).toBe(false);
+    current = history.undo(current);
+    current = history.undo(current);
+    expect(current).toEqual(doc);
+  });
+
+  it("does not coalesce a new command into an entry the user has undone past", () => {
+    // Otherwise a drag, an undo, and another drag inside coalesceMs would fold
+    // into the entry that is no longer applied and the document would drift.
+    const time = clock();
+    const history = createHistory<Nodes, Edges>({ now: time.now, coalesceMs: 400 });
+    const moved = history.commit(doc, drag(5));
+    const undone = history.undo(moved);
+    time.tick(1);
+    const again = history.commit(undone, drag(2));
+    expect(history.depth()).toBe(1);
+    expect(again.nodes[0].position.x).toBe(2);
+    expect(history.undo(again)).toEqual(doc);
+  });
+});
+
+describe("nothing to do", () => {
+  it("returns the same document when there is nothing to undo or redo", () => {
+    const history = createHistory<Nodes, Edges>({ now: clock().now });
+    expect(history.canUndo()).toBe(false);
+    expect(history.undo(doc)).toBe(doc);
+    expect(history.redo(doc)).toBe(doc);
+  });
+
+  it("clear() empties both stacks", () => {
+    const history = createHistory<Nodes, Edges>({ now: clock().now });
+    const moved = history.commit(doc, drag(5));
+    history.undo(moved);
+    history.clear();
+    expect(history.canUndo()).toBe(false);
+    expect(history.canRedo()).toBe(false);
+  });
+});