@flighthq/command 0.4.1-edge.28.7f8e221

package/dist/explainCommandDispatch.js

@@ -0,0 +1,23 @@
+import { getCommandBinding } from './commandBinding';
+// Why `executeCommand` would refuse, as plain data rather than a message. A separately importable query,
+// so a caller who never asks pays nothing for it and the core carries no prose — the diagnostics inversion
+// rule. Descends into composites, because a composite whose child kind is unregistered dispatches into a
+// no-op that would otherwise look like a successful undo step.
+export function explainCommandDispatch(history, command) {
+    const missingKind = findMissingCommandKind(history, command);
+    return { missingKind, resolved: missingKind === null };
+}
+function findMissingCommandKind(history, command) {
+    if (getCommandBinding(history, command.kind) === null)
+        return command.kind;
+    const children = command.children;
+    if (children === undefined)
+        return null;
+    for (let i = 0; i < children.length; i++) {
+        const missing = findMissingCommandKind(history, children[i]);
+        if (missing !== null)
+            return missing;
+    }
+    return null;
+}
+//# sourceMappingURL=explainCommandDispatch.js.map

package/dist/explainCommandDispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainCommandDispatch.js","sourceRoot":"","sources":["../src/explainCommandDispatch.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,yGAAyG;AACzG,2GAA2G;AAC3G,yGAAyG;AACzG,+DAA+D;AAC/D,MAAM,UAAU,sBAAsB,CACpC,OAAiC,EACjC,OAA0B;IAE1B,MAAM,WAAW,GAAG,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,sBAAsB,CAAC,OAAiC,EAAE,OAA0B;IAC3F,IAAI,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,IAAI,CAAC;IAC3E,MAAM,QAAQ,GAAI,OAA+C,CAAC,QAAQ,CAAC;IAC3E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './command';
+export * from './commandBinding';
+export * from './commandHistory';
+export * from './commandHistorySignals';
+export * from './commandTransaction';
+export * from './explainCommandDispatch';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './command';
+export * from './commandBinding';
+export * from './commandHistory';
+export * from './commandHistorySignals';
+export * from './commandTransaction';
+export * from './explainCommandDispatch';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@flighthq/command",
+  "version": "0.4.1-edge.28.7f8e221",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/command"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/node": "0.4.1-edge.28.7f8e221",
+    "@flighthq/registry": "0.4.1-edge.28.7f8e221",
+    "@flighthq/signals": "0.4.1-edge.28.7f8e221",
+    "@flighthq/types": "0.4.1-edge.28.7f8e221"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Undo/redo command history — commands are plain kind-tagged data (property set, add/remove/reorder child, composite) whose execute/undo/merge are free functions registered per kind in a keyed table and resolved at dispatch, with a stack tracking applied/redoable entries, per-kind merge coalescing for drag sequences, nestable transaction brackets that fold many commands into one entry, an optional maxSize cap, and an opt-in onChange signal; no closures on the stack, so entries stay inspectable data",
+  "sideEffects": false
+}

package/src/command.test.ts

@@ -0,0 +1,115 @@
+import { addNodeChild, createNode, getNodeChildIndex } from '@flighthq/node/contract';
+import type { NodeAny } from '@flighthq/types/contract';
+import {
+  AddNodeChildCommandKind,
+  CompositeCommandKind,
+  RemoveNodeChildCommandKind,
+  ReorderNodeChildCommandKind,
+  SetNodePropertyCommandKind,
+} from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createAddNodeChildCommand,
+  createCompositeCommand,
+  createRemoveNodeChildCommand,
+  createReorderNodeChildCommand,
+  createSetNodePropertyCommand,
+  createSetNodePropertyCommandBatch,
+} from './command';
+
+describe('createAddNodeChildCommand', () => {
+  it('is plain data carrying its kind, and appends by default', () => {
+    const parent = node();
+    const child = node();
+    const command = createAddNodeChildCommand('Add sprite', parent, child);
+    expect(command).toEqual({ child, index: -1, kind: AddNodeChildCommandKind, label: 'Add sprite', parent });
+  });
+
+  it('records an explicit insertion index', () => {
+    expect(createAddNodeChildCommand('Add', node(), node(), 3).index).toBe(3);
+  });
+});
+
+describe('createCompositeCommand', () => {
+  it('copies the child list, so a later push by the caller cannot rewrite a recorded entry', () => {
+    const children = [createAddNodeChildCommand('Add', node(), node())];
+    const command = createCompositeCommand('Align', children);
+    children.push(createAddNodeChildCommand('Add again', node(), node()));
+    expect(command.kind).toBe(CompositeCommandKind);
+    expect(command.children).toHaveLength(1);
+  });
+});
+
+describe('createRemoveNodeChildCommand', () => {
+  // The index has to be captured while the child is still attached — this is why removal is a `create*`
+  // call before the mutation rather than a literal built afterwards.
+  it('captures the index the child currently occupies', () => {
+    const parent = node();
+    const first = node();
+    const second = node();
+    addNodeChild(parent, first);
+    addNodeChild(parent, second);
+
+    const command = createRemoveNodeChildCommand('Delete', parent, second);
+    expect(command.kind).toBe(RemoveNodeChildCommandKind);
+    expect(command.index).toBe(1);
+  });
+});
+
+describe('createReorderNodeChildCommand', () => {
+  it('captures where the child started as well as where it is going', () => {
+    const parent = node();
+    const first = node();
+    const second = node();
+    addNodeChild(parent, first);
+    addNodeChild(parent, second);
+
+    const command = createReorderNodeChildCommand('Move to front', parent, second, 0);
+    expect(command.kind).toBe(ReorderNodeChildCommandKind);
+    expect(command.fromIndex).toBe(1);
+    expect(command.toIndex).toBe(0);
+    // Creating a command must not itself move anything.
+    expect(getNodeChildIndex(parent, second)).toBe(1);
+  });
+});
+
+describe('createSetNodePropertyCommand', () => {
+  it('reads the current value as before and does not apply the change', () => {
+    const target = node();
+    (target as unknown as Record<string, unknown>).x = 5;
+
+    const command = createSetNodePropertyCommand('Move', target, 'x', 100);
+    expect(command.kind).toBe(SetNodePropertyCommandKind);
+    expect(command.entries).toEqual([{ after: 100, before: 5, property: 'x', target }]);
+    expect((target as unknown as Record<string, unknown>).x).toBe(5);
+  });
+
+  it('defaults to no merge window, so every change is its own undo entry', () => {
+    const command = createSetNodePropertyCommand('Move', node(), 'x', 1);
+    expect(command.mergeWindow).toBe(0);
+    expect(command.time).toBe(0);
+  });
+});
+
+describe('createSetNodePropertyCommandBatch', () => {
+  it('captures each before value in the order given', () => {
+    const target = node();
+    const record = target as unknown as Record<string, unknown>;
+    record.x = 1;
+    record.y = 2;
+
+    const command = createSetNodePropertyCommandBatch('Move', [
+      { property: 'x', target, value: 10 },
+      { property: 'y', target, value: 20 },
+    ]);
+    expect(command.entries.map((entry) => entry.before)).toEqual([1, 2]);
+    expect(command.entries.map((entry) => entry.after)).toEqual([10, 20]);
+  });
+});
+
+// A bare graph node from `node` itself — the package under test depends on `node` and nothing else in the
+// graph, so a test must not reach for scene2d to get a subject.
+function node(): NodeAny {
+  return createNode('test.CommandTarget') as NodeAny;
+}

package/src/commandBinding.test.ts

@@ -0,0 +1,219 @@
+import { addNodeChild, createNode, getNodeChildCount, getNodeChildIndex } from '@flighthq/node/contract';
+import type { CommandBinding, NodeAny, SetNodePropertyCommand } from '@flighthq/types/contract';
+import { SetNodePropertyCommandKind } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import {
+  createAddNodeChildCommand,
+  createCompositeCommand,
+  createRemoveNodeChildCommand,
+  createReorderNodeChildCommand,
+  createSetNodePropertyCommand,
+} from './command';
+import {
+  createCommandBindingTable,
+  getCommandBinding,
+  hasCommandBinding,
+  registerCommandBinding,
+  registerDefaultCommandBindings,
+} from './commandBinding';
+import { createCommandHistory, executeCommand, undoCommand } from './commandHistory';
+
+describe('createCommandBindingTable', () => {
+  it('starts empty, so nothing dispatches until a caller registers it', () => {
+    const history = createCommandHistory();
+    history.bindings = createCommandBindingTable();
+    expect(hasCommandBinding(history, SetNodePropertyCommandKind)).toBe(false);
+  });
+});
+
+describe('getCommandBinding', () => {
+  it('returns null for an unregistered kind rather than throwing', () => {
+    expect(getCommandBinding(createCommandHistory(), 'acme.Nothing')).toBeNull();
+  });
+});
+
+describe('hasCommandBinding', () => {
+  it('reports a registered kind', () => {
+    const history = createCommandHistory();
+    registerDefaultCommandBindings(history);
+    expect(hasCommandBinding(history, SetNodePropertyCommandKind)).toBe(true);
+  });
+});
+
+describe('registerCommandBinding', () => {
+  it('accepts a caller-defined vendor-prefixed kind', () => {
+    const history = createCommandHistory();
+    const seen: string[] = [];
+    registerCommandBinding(history, 'acme.Custom', {
+      execute: () => seen.push('execute'),
+      undo: () => seen.push('undo'),
+    });
+    executeCommand(history, { kind: 'acme.Custom', label: 'Custom' });
+    undoCommand(history);
+    expect(seen).toEqual(['execute', 'undo']);
+  });
+
+  // Last write wins, which is what lets a consumer replace a built-in binding without forking the package.
+  it('overrides an earlier binding for the same kind', () => {
+    const history = createCommandHistory();
+    const first: CommandBinding = { execute: () => undefined, undo: () => undefined };
+    const second: CommandBinding = { execute: () => undefined, undo: () => undefined };
+    registerCommandBinding(history, 'acme.Custom', first);
+    registerCommandBinding(history, 'acme.Custom', second);
+    expect(getCommandBinding(history, 'acme.Custom')).toBe(second);
+  });
+});
+
+describe('registerDefaultCommandBindings', () => {
+  it('applies and reverses an added child, restoring membership', () => {
+    const history = withDefaults();
+    const parent = node();
+    const child = node();
+
+    executeCommand(history, createAddNodeChildCommand('Add', parent, child));
+    expect(getNodeChildCount(parent)).toBe(1);
+    undoCommand(history);
+    expect(getNodeChildCount(parent)).toBe(0);
+  });
+
+  // Position, not merely membership: a delete that undoes to the end of the list has lost information the
+  // command captured on purpose.
+  it('restores a removed child to the index it came from', () => {
+    const history = withDefaults();
+    const parent = node();
+    const first = node();
+    const second = node();
+    const third = node();
+    addNodeChild(parent, first);
+    addNodeChild(parent, second);
+    addNodeChild(parent, third);
+
+    executeCommand(history, createRemoveNodeChildCommand('Delete', parent, second));
+    expect(getNodeChildCount(parent)).toBe(2);
+    undoCommand(history);
+    expect(getNodeChildIndex(parent, second)).toBe(1);
+  });
+
+  it('applies and reverses a reorder', () => {
+    const history = withDefaults();
+    const parent = node();
+    const first = node();
+    const second = node();
+    addNodeChild(parent, first);
+    addNodeChild(parent, second);
+
+    executeCommand(history, createReorderNodeChildCommand('Front', parent, second, 0));
+    expect(getNodeChildIndex(parent, second)).toBe(0);
+    undoCommand(history);
+    expect(getNodeChildIndex(parent, second)).toBe(1);
+  });
+
+  it('applies and reverses a property write', () => {
+    const history = withDefaults();
+    const target = node();
+    write(target, 'x', 5);
+
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'x', 100));
+    expect(read(target, 'x')).toBe(100);
+    undoCommand(history);
+    expect(read(target, 'x')).toBe(5);
+  });
+
+  it('runs composite children in order and reverses them in reverse order', () => {
+    const history = withDefaults();
+    const parent = node();
+    const child = node();
+
+    executeCommand(
+      history,
+      createCompositeCommand('Add and move', [
+        createAddNodeChildCommand('Add', parent, child),
+        createSetNodePropertyCommand('Move', child, 'x', 10),
+      ]),
+    );
+    expect(getNodeChildCount(parent)).toBe(1);
+    expect(read(child, 'x')).toBe(10);
+
+    // Reverse order matters: undoing forward would move a child that the add has not yet taken back.
+    undoCommand(history);
+    expect(getNodeChildCount(parent)).toBe(0);
+    expect(read(child, 'x')).toBeUndefined();
+  });
+
+  it('merges same-target same-property writes inside the window into one reversible entry', () => {
+    const history = withDefaults();
+    const target = node();
+    write(target, 'x', 0);
+
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 10, 300, 0));
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 20, 300, 100));
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 30, 300, 200));
+
+    expect(history.entries).toHaveLength(1);
+    expect(read(target, 'x')).toBe(30);
+    // One undo returns to where the gesture STARTED, not to the previous frame.
+    undoCommand(history);
+    expect(read(target, 'x')).toBe(0);
+  });
+
+  it('does not merge once the window has elapsed', () => {
+    const history = withDefaults();
+    const target = node();
+    write(target, 'x', 0);
+
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 10, 300, 0));
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 20, 300, 1000));
+    expect(history.entries).toHaveLength(2);
+  });
+
+  it('does not merge writes to a different property of the same node', () => {
+    const history = withDefaults();
+    const target = node();
+
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'x', 10, 300, 0));
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'y', 20, 300, 10));
+    expect(history.entries).toHaveLength(2);
+  });
+
+  it('does not merge when no window is given, which is the default', () => {
+    const history = withDefaults();
+    const target = node();
+
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'x', 10));
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'x', 20));
+    expect(history.entries).toHaveLength(2);
+  });
+
+  // The merged entry keeps the ORIGINAL before value; reading it back proves the merge is not simply
+  // dropping the earlier command.
+  it('keeps the original before value in the merged command', () => {
+    const history = withDefaults();
+    const target = node();
+    write(target, 'x', 7);
+
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 10, 300, 0));
+    executeCommand(history, createSetNodePropertyCommand('Drag', target, 'x', 20, 300, 50));
+    const merged = history.entries[0] as SetNodePropertyCommand;
+    expect(merged.entries[0].before).toBe(7);
+    expect(merged.entries[0].after).toBe(20);
+  });
+});
+
+function node(): NodeAny {
+  return createNode('test.CommandTarget') as NodeAny;
+}
+
+function read(target: Readonly<NodeAny>, property: string): unknown {
+  return (target as unknown as Readonly<Record<string, unknown>>)[property];
+}
+
+function withDefaults() {
+  const history = createCommandHistory();
+  registerDefaultCommandBindings(history);
+  return history;
+}
+
+function write(target: NodeAny, property: string, value: unknown): void {
+  (target as unknown as Record<string, unknown>)[property] = value;
+}

package/src/commandHistory.test.ts

@@ -0,0 +1,203 @@
+import { createNode, getNodeChildCount } from '@flighthq/node/contract';
+import { connectSignal } from '@flighthq/signals/contract';
+import type { Command, CommandHistory, NodeAny } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { createAddNodeChildCommand, createSetNodePropertyCommand } from './command';
+import { registerCommandBinding, registerDefaultCommandBindings } from './commandBinding';
+import {
+  canRedoCommand,
+  canUndoCommand,
+  clearCommandHistory,
+  createCommandHistory,
+  executeCommand,
+  getCommandHistoryEntries,
+  getCommandHistoryIndex,
+  getCommandHistoryRedoLabel,
+  getCommandHistoryUndoLabel,
+  notifyCommandHistoryChanged,
+  redoCommand,
+  undoCommand,
+} from './commandHistory';
+import { enableCommandHistorySignals } from './commandHistorySignals';
+
+describe('canRedoCommand', () => {
+  it('is false until something has been undone', () => {
+    const history = counting();
+    expect(canRedoCommand(history)).toBe(false);
+    executeCommand(history, counter('One'));
+    expect(canRedoCommand(history)).toBe(false);
+    undoCommand(history);
+    expect(canRedoCommand(history)).toBe(true);
+  });
+});
+
+describe('canUndoCommand', () => {
+  it('is false on an empty history and true once something is applied', () => {
+    const history = counting();
+    expect(canUndoCommand(history)).toBe(false);
+    executeCommand(history, counter('One'));
+    expect(canUndoCommand(history)).toBe(true);
+  });
+});
+
+describe('clearCommandHistory', () => {
+  // Clearing FORGETS how to reverse the work; it must not silently reverse it. An editor that cleared
+  // history on save would otherwise undo the document.
+  it('drops entries without undoing them', () => {
+    const history = withDefaults();
+    const parent = node();
+    executeCommand(history, createAddNodeChildCommand('Add', parent, node()));
+
+    clearCommandHistory(history);
+    expect(getCommandHistoryEntries(history)).toHaveLength(0);
+    expect(getCommandHistoryIndex(history)).toBe(0);
+    expect(getNodeChildCount(parent)).toBe(1);
+  });
+
+  it('emits nothing when there was nothing to forget', () => {
+    const history = counting();
+    let changes = 0;
+    connectSignal(enableCommandHistorySignals(history), () => changes++);
+    clearCommandHistory(history);
+    expect(changes).toBe(0);
+  });
+});
+
+describe('createCommandHistory', () => {
+  it('starts empty with no bindings and no signal allocated', () => {
+    const history = createCommandHistory();
+    expect(history.entries).toHaveLength(0);
+    expect(history.index).toBe(0);
+    expect(history.maxSize).toBe(0);
+    expect(history.onChange).toBeNull();
+  });
+});
+
+describe('executeCommand', () => {
+  it('refuses an unregistered kind rather than pushing an entry undo would skip', () => {
+    const history = createCommandHistory();
+    expect(executeCommand(history, { kind: 'acme.Unbound', label: 'Nope' })).toBe(false);
+    expect(getCommandHistoryEntries(history)).toHaveLength(0);
+  });
+
+  // A new action after an undo forks the timeline: the abandoned redo branch must not survive, or redo
+  // would re-apply work the user replaced.
+  it('discards the redo branch when a new command arrives after an undo', () => {
+    const history = counting();
+    executeCommand(history, counter('One'));
+    executeCommand(history, counter('Two'));
+    undoCommand(history);
+    executeCommand(history, counter('Three'));
+
+    expect(getCommandHistoryEntries(history).map((entry) => entry.label)).toEqual(['One', 'Three']);
+    expect(canRedoCommand(history)).toBe(false);
+  });
+
+  it('trims from the oldest end at maxSize, keeping the most recent history', () => {
+    const history = counting(2);
+    executeCommand(history, counter('One'));
+    executeCommand(history, counter('Two'));
+    executeCommand(history, counter('Three'));
+
+    expect(getCommandHistoryEntries(history).map((entry) => entry.label)).toEqual(['Two', 'Three']);
+    expect(getCommandHistoryIndex(history)).toBe(2);
+  });
+});
+
+describe('getCommandHistoryEntries', () => {
+  it('includes the reversed entries ahead of the cursor', () => {
+    const history = counting();
+    executeCommand(history, counter('One'));
+    undoCommand(history);
+    expect(getCommandHistoryEntries(history)).toHaveLength(1);
+    expect(getCommandHistoryIndex(history)).toBe(0);
+  });
+});
+
+describe('getCommandHistoryIndex', () => {
+  it('counts applied entries', () => {
+    const history = counting();
+    executeCommand(history, counter('One'));
+    executeCommand(history, counter('Two'));
+    expect(getCommandHistoryIndex(history)).toBe(2);
+  });
+});
+
+describe('getCommandHistoryRedoLabel', () => {
+  it('names the entry redo would re-apply, and is null with nothing to redo', () => {
+    const history = counting();
+    expect(getCommandHistoryRedoLabel(history)).toBeNull();
+    executeCommand(history, counter('One'));
+    undoCommand(history);
+    expect(getCommandHistoryRedoLabel(history)).toBe('One');
+  });
+});
+
+describe('getCommandHistoryUndoLabel', () => {
+  it('names the entry undo would reverse, and is null with nothing to undo', () => {
+    const history = counting();
+    expect(getCommandHistoryUndoLabel(history)).toBeNull();
+    executeCommand(history, counter('One'));
+    expect(getCommandHistoryUndoLabel(history)).toBe('One');
+  });
+});
+
+describe('notifyCommandHistoryChanged', () => {
+  it('is inert when no signal was enabled', () => {
+    expect(() => notifyCommandHistoryChanged(createCommandHistory())).not.toThrow();
+  });
+});
+
+describe('redoCommand', () => {
+  it('re-applies through the registered execute and returns false with nothing to redo', () => {
+    const history = withDefaults();
+    const target = node();
+    executeCommand(history, createSetNodePropertyCommand('Move', target, 'x', 100));
+    undoCommand(history);
+    expect(redoCommand(history)).toBe(true);
+    expect((target as unknown as Record<string, unknown>).x).toBe(100);
+    expect(redoCommand(history)).toBe(false);
+  });
+});
+
+describe('undoCommand', () => {
+  it('returns false with nothing to undo', () => {
+    expect(undoCommand(createCommandHistory())).toBe(false);
+  });
+
+  it('reverses entries newest first', () => {
+    const history = counting();
+    const order: string[] = [];
+    registerCommandBinding(history, 'test.Ordered', {
+      execute: () => undefined,
+      undo: (command) => order.push(command.label),
+    });
+    executeCommand(history, { kind: 'test.Ordered', label: 'One' });
+    executeCommand(history, { kind: 'test.Ordered', label: 'Two' });
+    undoCommand(history);
+    undoCommand(history);
+    expect(order).toEqual(['Two', 'One']);
+  });
+});
+
+function counter(label: string): Command {
+  return { kind: 'test.Counter', label };
+}
+
+// A history bound to one inert kind, so stack behaviour can be tested without any graph mutation.
+function counting(maxSize = 0): CommandHistory {
+  const history = createCommandHistory(maxSize);
+  registerCommandBinding(history, 'test.Counter', { execute: () => undefined, undo: () => undefined });
+  return history;
+}
+
+function node(): NodeAny {
+  return createNode('test.CommandTarget') as NodeAny;
+}
+
+function withDefaults(): CommandHistory {
+  const history = createCommandHistory();
+  registerDefaultCommandBindings(history);
+  return history;
+}