pixelweaver 0.1.0

package/src/lib/core/dispatcher.test.ts

@@ -0,0 +1,548 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { Command, CommandDefinition, UndoTier } from './commands.js';
+import type { CommandType, ParamsOf } from './command-params.js';
+import { commandRegistry } from './registries.svelte.js';
+import {
+  dispatch,
+  undoLast,
+  redoLast,
+  getSemanticLog,
+  getUndoStack,
+  getRedoStack,
+  canUndo,
+  canRedo,
+  setMaxUndoSize,
+  getMaxUndoSize,
+  onExecute,
+  onUndo,
+  onLog,
+  onSpecExport,
+  _resetForTesting,
+} from './dispatcher.js';
+
+// --- Helpers ---
+
+/** Create a minimal command for testing */
+// Typed overload: validates params when type is a known command literal
+function makeCommand<T extends CommandType>(type: T, params: ParamsOf<T>): Command;
+// String fallback: for dynamic/unknown command types in tests
+function makeCommand(type: string, params?: Record<string, unknown>): Command;
+function makeCommand(type: string, params: Record<string, unknown> = {}): Command {
+  return {
+    type,
+    plugin: 'test/plugin',
+    version: '1.0.0',
+    params,
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  };
+}
+
+/** Create a command definition with spies, optionally specifying a tier */
+function makeDefinition(
+  descriptionText = 'test command',
+  tier?: UndoTier,
+): CommandDefinition & { execute: ReturnType<typeof vi.fn>; undo: ReturnType<typeof vi.fn> } {
+  return {
+    execute: vi.fn(),
+    undo: vi.fn(),
+    describe: () => descriptionText,
+    ...(tier !== undefined ? { tier } : {}),
+  };
+}
+
+// --- Tests ---
+
+describe('Command Dispatcher', () => {
+  beforeEach(() => {
+    _resetForTesting();
+    // Clear command registry between tests by removing known keys
+    // (registry has no reset, so we delete entries we add)
+  });
+
+  it('should execute a dispatched command with correct params', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd', { x: 10, y: 20 });
+    dispatch(cmd);
+
+    expect(def.execute).toHaveBeenCalledOnce();
+    expect(def.execute).toHaveBeenCalledWith({ x: 10, y: 20 }, expect.any(Object));
+  });
+
+  it('should throw when dispatching an unknown command type', () => {
+    const cmd = makeCommand('nonexistent_cmd');
+    expect(() => { dispatch(cmd); }).toThrow('Unknown command type "nonexistent_cmd"');
+  });
+
+  it('should fire the onExecute consumer hook', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const callback = vi.fn();
+    onExecute(callback);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    expect(callback).toHaveBeenCalledOnce();
+    expect(callback).toHaveBeenCalledWith(cmd);
+  });
+
+  it('should fire the onLog consumer hook with a semantic log entry', () => {
+    const def = makeDefinition('Drew a pixel');
+    commandRegistry.set('test_cmd', def);
+
+    const callback = vi.fn();
+    onLog(callback);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    expect(callback).toHaveBeenCalledOnce();
+    expect(callback).toHaveBeenCalledWith(
+      expect.objectContaining({
+        description: 'Drew a pixel',
+        commandId: cmd.id,
+      }),
+    );
+  });
+
+  it('should fire the onSpecExport consumer hook', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const callback = vi.fn();
+    onSpecExport(callback);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    expect(callback).toHaveBeenCalledOnce();
+    expect(callback).toHaveBeenCalledWith(cmd);
+  });
+
+  it('should fire all 4 consumer hooks on dispatch', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const executeCb = vi.fn();
+    const undoCb = vi.fn();
+    const logCb = vi.fn();
+    const specCb = vi.fn();
+
+    onExecute(executeCb);
+    onUndo(undoCb);
+    onLog(logCb);
+    onSpecExport(specCb);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    // Execute, log, and spec-export fire on dispatch; undo does not
+    expect(executeCb).toHaveBeenCalledOnce();
+    expect(logCb).toHaveBeenCalledOnce();
+    expect(specCb).toHaveBeenCalledOnce();
+    expect(undoCb).not.toHaveBeenCalled();
+  });
+
+  it('should create a semantic log entry on dispatch', () => {
+    const def = makeDefinition('Added layer "Background"');
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    const log = getSemanticLog();
+    expect(log).toHaveLength(1);
+    expect(log[0]).toEqual({
+      description: 'Added layer "Background"',
+      timestamp: cmd.timestamp,
+      commandId: cmd.id,
+    });
+  });
+
+  it('should undo the last command by calling its undo function', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd', { x: 5 });
+    dispatch(cmd);
+
+    const undone = undoLast();
+
+    expect(undone).toBe(cmd);
+    expect(def.undo).toHaveBeenCalledOnce();
+    expect(def.undo).toHaveBeenCalledWith({ x: 5 }, expect.any(Object), undefined);
+  });
+
+  it('should fire the onUndo consumer hook when undoing', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const callback = vi.fn();
+    onUndo(callback);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+    undoLast();
+
+    expect(callback).toHaveBeenCalledOnce();
+    expect(callback).toHaveBeenCalledWith(cmd);
+  });
+
+  it('should return undefined when undoing with an empty stack', () => {
+    const result = undoLast();
+    expect(result).toBeUndefined();
+  });
+
+  it('should redo the last undone command', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd', { value: 42 });
+    dispatch(cmd);
+    undoLast();
+
+    def.execute.mockClear();
+    const redone = redoLast();
+
+    expect(redone).toBe(cmd);
+    expect(def.execute).toHaveBeenCalledOnce();
+    expect(def.execute).toHaveBeenCalledWith({ value: 42 }, expect.any(Object));
+  });
+
+  it('should return undefined when redoing with an empty stack', () => {
+    const result = redoLast();
+    expect(result).toBeUndefined();
+  });
+
+  it('should clear the redo stack when a new command is dispatched', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    dispatch(makeCommand('test_cmd'));
+    undoLast();
+
+    // Now dispatch a new command -- redo should be cleared
+    dispatch(makeCommand('test_cmd'));
+    const result = redoLast();
+    expect(result).toBeUndefined();
+  });
+
+  it('should undo multiple commands in LIFO order', () => {
+    const defA = makeDefinition('Command A');
+    const defB = makeDefinition('Command B');
+    const defC = makeDefinition('Command C');
+
+    commandRegistry.set('cmd_a', defA);
+    commandRegistry.set('cmd_b', defB);
+    commandRegistry.set('cmd_c', defC);
+
+    const cmdA = makeCommand('cmd_a');
+    const cmdB = makeCommand('cmd_b');
+    const cmdC = makeCommand('cmd_c');
+
+    dispatch(cmdA);
+    dispatch(cmdB);
+    dispatch(cmdC);
+
+    expect(undoLast()).toBe(cmdC);
+    expect(undoLast()).toBe(cmdB);
+    expect(undoLast()).toBe(cmdA);
+    expect(undoLast()).toBeUndefined();
+
+    expect(defC.undo).toHaveBeenCalledOnce();
+    expect(defB.undo).toHaveBeenCalledOnce();
+    expect(defA.undo).toHaveBeenCalledOnce();
+  });
+
+  it('should allow unsubscribing from consumer hooks', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const callback = vi.fn();
+    const unsub = onExecute(callback);
+
+    dispatch(makeCommand('test_cmd'));
+    expect(callback).toHaveBeenCalledOnce();
+
+    unsub();
+
+    dispatch(makeCommand('test_cmd'));
+    // Should still be 1 call, not 2
+    expect(callback).toHaveBeenCalledOnce();
+  });
+});
+
+describe('Two-Tier Undo System', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should assign tier from command definition', () => {
+    const frameDef = makeDefinition('draw', 'frame');
+    const projectDef = makeDefinition('add layer', 'project');
+    commandRegistry.set('draw_pixel', frameDef);
+    commandRegistry.set('add_layer', projectDef);
+
+    dispatch(makeCommand('draw_pixel'));
+    dispatch(makeCommand('add_layer'));
+
+    const stack = getUndoStack();
+    expect(stack).toHaveLength(2);
+    expect(stack[0]?.tier).toBe('frame');
+    expect(stack[1]?.tier).toBe('project');
+  });
+
+  it('should default tier to "frame" when not specified in definition', () => {
+    const def = makeDefinition('no tier');
+    commandRegistry.set('untagged_cmd', def);
+
+    dispatch(makeCommand('untagged_cmd'));
+
+    const stack = getUndoStack();
+    expect(stack[0]?.tier).toBe('frame');
+  });
+
+  it('should preserve tier when moving entries to redo stack', () => {
+    const projectDef = makeDefinition('project cmd', 'project');
+    commandRegistry.set('project_cmd', projectDef);
+
+    dispatch(makeCommand('project_cmd'));
+    undoLast();
+
+    const redo = getRedoStack();
+    expect(redo).toHaveLength(1);
+    expect(redo[0]?.tier).toBe('project');
+  });
+
+  it('should preserve tier when redoing', () => {
+    const projectDef = makeDefinition('project cmd', 'project');
+    commandRegistry.set('project_cmd', projectDef);
+
+    dispatch(makeCommand('project_cmd'));
+    undoLast();
+    redoLast();
+
+    const stack = getUndoStack();
+    expect(stack).toHaveLength(1);
+    expect(stack[0]?.tier).toBe('project');
+  });
+});
+
+describe('canUndo / canRedo', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should return false when stacks are empty', () => {
+    expect(canUndo()).toBe(false);
+    expect(canRedo()).toBe(false);
+  });
+
+  it('should return true for canUndo after dispatch', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+    dispatch(makeCommand('test_cmd'));
+
+    expect(canUndo()).toBe(true);
+    expect(canRedo()).toBe(false);
+  });
+
+  it('should return true for canRedo after undo', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+    dispatch(makeCommand('test_cmd'));
+    undoLast();
+
+    expect(canUndo()).toBe(false);
+    expect(canRedo()).toBe(true);
+  });
+
+  it('should return correct values after mixed operations', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    dispatch(makeCommand('test_cmd'));
+    dispatch(makeCommand('test_cmd'));
+
+    expect(canUndo()).toBe(true);
+    expect(canRedo()).toBe(false);
+
+    undoLast();
+    expect(canUndo()).toBe(true);
+    expect(canRedo()).toBe(true);
+
+    undoLast();
+    expect(canUndo()).toBe(false);
+    expect(canRedo()).toBe(true);
+
+    redoLast();
+    expect(canUndo()).toBe(true);
+    expect(canRedo()).toBe(true);
+  });
+});
+
+describe('getUndoStack / getRedoStack', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should return empty arrays initially', () => {
+    expect(getUndoStack()).toHaveLength(0);
+    expect(getRedoStack()).toHaveLength(0);
+  });
+
+  it('should return undo entries with correct command references', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    const stack = getUndoStack();
+    expect(stack).toHaveLength(1);
+    expect(stack[0]?.command).toBe(cmd);
+    expect(stack[0]?.id).toBe(cmd.id);
+  });
+
+  it('should move entries between stacks on undo/redo', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd = makeCommand('test_cmd');
+    dispatch(cmd);
+
+    expect(getUndoStack()).toHaveLength(1);
+    expect(getRedoStack()).toHaveLength(0);
+
+    undoLast();
+    expect(getUndoStack()).toHaveLength(0);
+    expect(getRedoStack()).toHaveLength(1);
+
+    redoLast();
+    expect(getUndoStack()).toHaveLength(1);
+    expect(getRedoStack()).toHaveLength(0);
+  });
+});
+
+describe('Undo Stack Size Limits', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should enforce max undo size by dropping oldest entries', () => {
+    setMaxUndoSize(3);
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmds = Array.from({ length: 5 }, (_, i) =>
+      makeCommand('test_cmd', { index: i }),
+    );
+    for (const cmd of cmds) dispatch(cmd);
+
+    const stack = getUndoStack();
+    expect(stack).toHaveLength(3);
+    // Oldest two (index 0, 1) should be dropped; remaining are index 2, 3, 4
+    expect(stack[0]?.command.params["index"]).toBe(2);
+    expect(stack[1]?.command.params["index"]).toBe(3);
+    expect(stack[2]?.command.params["index"]).toBe(4);
+  });
+
+  it('should trim existing stack when max size is reduced', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    for (let i = 0; i < 10; i++) dispatch(makeCommand('test_cmd', { i }));
+    expect(getUndoStack()).toHaveLength(10);
+
+    setMaxUndoSize(5);
+    expect(getUndoStack()).toHaveLength(5);
+    // The 5 most recent entries should remain
+    expect(getUndoStack()[0]?.command.params["i"]).toBe(5);
+  });
+
+  it('should throw when setting max size to zero or negative', () => {
+    expect(() => { setMaxUndoSize(0); }).toThrow('Max undo size must be at least 1');
+    expect(() => { setMaxUndoSize(-1); }).toThrow('Max undo size must be at least 1');
+  });
+
+  it('should report the current max size', () => {
+    expect(getMaxUndoSize()).toBe(500); // default
+    setMaxUndoSize(100);
+    expect(getMaxUndoSize()).toBe(100);
+  });
+
+  it('should reset max size on _resetForTesting', () => {
+    setMaxUndoSize(10);
+    _resetForTesting();
+    expect(getMaxUndoSize()).toBe(500);
+  });
+});
+
+describe('Parent Pointers', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should set parentId to null for the first entry', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    dispatch(makeCommand('test_cmd'));
+
+    const stack = getUndoStack();
+    expect(stack[0]?.parentId).toBeNull();
+  });
+
+  it('should chain parent pointers through a sequence of dispatches', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    dispatch(makeCommand('test_cmd'));
+    dispatch(makeCommand('test_cmd'));
+    dispatch(makeCommand('test_cmd'));
+
+    const stack = getUndoStack();
+    expect(stack[0]?.parentId).toBeNull();
+    expect(stack[1]?.parentId).toBe(stack[0]?.id);
+    expect(stack[2]?.parentId).toBe(stack[1]?.id);
+  });
+
+  it('should update parent pointer on redo to reflect current stack top', () => {
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    const cmd1 = makeCommand('test_cmd');
+    const cmd2 = makeCommand('test_cmd');
+    dispatch(cmd1);
+    dispatch(cmd2);
+
+    // Undo cmd2, then redo it -- its parentId should point to cmd1
+    undoLast();
+    redoLast();
+
+    const stack = getUndoStack();
+    expect(stack[1]?.parentId).toBe(stack[0]?.id);
+    expect(stack[1]?.command).toBe(cmd2);
+  });
+
+  it('should maintain correct parent pointers when oldest entries are dropped', () => {
+    setMaxUndoSize(2);
+    const def = makeDefinition();
+    commandRegistry.set('test_cmd', def);
+
+    dispatch(makeCommand('test_cmd')); // entry 0
+    dispatch(makeCommand('test_cmd')); // entry 1 (parent -> 0)
+    dispatch(makeCommand('test_cmd')); // entry 2 (parent -> 1); entry 0 is dropped
+
+    const stack = getUndoStack();
+    expect(stack).toHaveLength(2);
+    // The remaining entries should still have their original parent pointers
+    // (entry 1's parentId points to a now-dropped entry, which is fine --
+    // the pointer is a historical reference for future branching)
+    expect(stack[1]?.parentId).toBe(stack[0]?.id);
+  });
+});