pixelweaver 0.1.0

package/src/lib/history/replay-engine.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Tests for the Command Replay Engine.
+ *
+ * Registers test commands that set pixels on a PixelBuffer, then exercises
+ * the replay engine's core operations: replay, reorder, toggle, and
+ * parameter editing.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { CommandDefinition, CommandContext } from '../core/commands.js';
+import { commandRegistry } from '../core/registries.svelte.js';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { replayCommands, previewReorder } from './replay-engine.js';
+import type { ActionLogEntry } from './action-log.svelte.js';
+
+// --- Test command: sets a single pixel ---
+
+function registerSetPixelCommand(): void {
+  const def: CommandDefinition = {
+    execute(params, ctx: CommandContext) {
+      // CommandContext's index signature means ctx["pixelBuffer"] is
+      // typed as unknown but may actually be undefined at runtime if
+      // the context was built without one, hence the guard.
+      const buf = ctx["pixelBuffer"] as PixelBuffer | undefined;
+      if (!buf) return;
+      const x = params["x"] as number;
+      const y = params["y"] as number;
+      const r = (params["r"] ?? 255) as number;
+      const g = (params["g"] ?? 0) as number;
+      const b = (params["b"] ?? 0) as number;
+      const a = (params["a"] ?? 255) as number;
+      buf.setPixel(x, y, r, g, b, a);
+    },
+    undo() { /* not needed for replay tests */ },
+    describe(params) {
+      return `Set pixel at (${String(params["x"])}, ${String(params["y"])})`;
+    },
+    tier: 'frame',
+  };
+  commandRegistry.set('set_pixel', def);
+}
+
+// --- Test command: fills a rect ---
+
+function registerFillRectCommand(): void {
+  const def: CommandDefinition = {
+    execute(params, ctx: CommandContext) {
+      const buf = ctx["pixelBuffer"] as PixelBuffer | undefined;
+      if (!buf) return;
+      buf.fillRect(
+        params["x"] as number,
+        params["y"] as number,
+        params["w"] as number,
+        params["h"] as number,
+        (params["r"] ?? 0) as number,
+        (params["g"] ?? 255) as number,
+        (params["b"] ?? 0) as number,
+        (params["a"] ?? 255) as number,
+      );
+    },
+    undo() {},
+    describe(params) {
+      return `Fill rect at (${String(params["x"])}, ${String(params["y"])})`;
+    },
+    tier: 'frame',
+  };
+  commandRegistry.set('fill_rect', def);
+}
+
+/** Create a mock ActionLogEntry for testing. */
+function makeLogEntry(
+  type: string,
+  params: Record<string, unknown>,
+  enabled = true,
+): ActionLogEntry {
+  return {
+    commandId: crypto.randomUUID(),
+    type,
+    plugin: 'test/plugin',
+    description: `Test ${type}`,
+    timestamp: Date.now(),
+    enabled,
+    params,
+  };
+}
+
+// --- Tests ---
+
+describe('Replay Engine', () => {
+  beforeEach(() => {
+    registerSetPixelCommand();
+    registerFillRectCommand();
+  });
+
+  it('should replay a single command and produce correct pixels', () => {
+    const buf = replayCommands(
+      [{ type: 'set_pixel', params: { x: 2, y: 3, r: 100, g: 150, b: 200, a: 255 } }],
+      8, 8, 'layer1',
+    );
+
+    expect(buf.getPixel(2, 3)).toEqual([100, 150, 200, 255]);
+    // Other pixels should be untouched (default zero)
+    expect(buf.getPixel(0, 0)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should replay multiple commands in order', () => {
+    const buf = replayCommands(
+      [
+        { type: 'set_pixel', params: { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 } },
+        { type: 'set_pixel', params: { x: 1, y: 0, r: 0, g: 255, b: 0, a: 255 } },
+        { type: 'set_pixel', params: { x: 2, y: 0, r: 0, g: 0, b: 255, a: 255 } },
+      ],
+      8, 8, 'layer1',
+    );
+
+    expect(buf.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(1, 0)).toEqual([0, 255, 0, 255]);
+    expect(buf.getPixel(2, 0)).toEqual([0, 0, 255, 255]);
+  });
+
+  it('should replay overlapping commands where later overwrites earlier', () => {
+    const buf = replayCommands(
+      [
+        { type: 'set_pixel', params: { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 } },
+        { type: 'set_pixel', params: { x: 0, y: 0, r: 0, g: 255, b: 0, a: 255 } },
+      ],
+      8, 8, 'layer1',
+    );
+
+    // Second command overwrites the first at (0,0)
+    expect(buf.getPixel(0, 0)).toEqual([0, 255, 0, 255]);
+  });
+
+  it('should produce different result when overlapping commands are reordered', () => {
+    const entry1 = makeLogEntry('set_pixel', { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 });
+    const entry2 = makeLogEntry('set_pixel', { x: 0, y: 0, r: 0, g: 255, b: 0, a: 255 });
+
+    // Original order: entry1 then entry2 -> pixel is green
+    const buf1 = previewReorder(
+      [entry1, entry2],
+      [entry1.commandId, entry2.commandId],
+      8, 8, 'layer1',
+    );
+    expect(buf1.getPixel(0, 0)).toEqual([0, 255, 0, 255]);
+
+    // Reversed order: entry2 then entry1 -> pixel is red
+    const buf2 = previewReorder(
+      [entry1, entry2],
+      [entry2.commandId, entry1.commandId],
+      8, 8, 'layer1',
+    );
+    expect(buf2.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+  });
+
+  it('should skip disabled entries during replay', () => {
+    const entry1 = makeLogEntry('set_pixel', { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 });
+    const entry2 = makeLogEntry('set_pixel', { x: 1, y: 0, r: 0, g: 255, b: 0, a: 255 }, false);
+
+    const buf = previewReorder(
+      [entry1, entry2],
+      [entry1.commandId, entry2.commandId],
+      8, 8, 'layer1',
+    );
+
+    // entry1 pixel should be set
+    expect(buf.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+    // entry2 is disabled, so pixel should be untouched
+    expect(buf.getPixel(1, 0)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should handle previewReorder without modifying original entries', () => {
+    const entry1 = makeLogEntry('set_pixel', { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 });
+    const entry2 = makeLogEntry('set_pixel', { x: 1, y: 0, r: 0, g: 255, b: 0, a: 255 });
+
+    const originalEntries = [entry1, entry2];
+    const originalIds = originalEntries.map((e) => e.commandId);
+
+    // Preview with reversed order
+    previewReorder(
+      originalEntries,
+      [entry2.commandId, entry1.commandId],
+      8, 8, 'layer1',
+    );
+
+    // Original entries should be unchanged
+    expect(originalEntries.map((e) => e.commandId)).toEqual(originalIds);
+    expect(originalEntries).toHaveLength(2);
+  });
+
+  it('should preview parameter edit with modified params', () => {
+    // We need entries in the action log for previewParamEdit.
+    // Use previewReorder to test param editing at the replay level directly.
+    const entry1 = makeLogEntry('set_pixel', { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 });
+
+    // Replay with modified params: change color from red to blue
+    const commands = [
+      { type: entry1.type, params: { x: 0, y: 0, r: 0, g: 0, b: 255, a: 255 } },
+    ];
+    const buf = replayCommands(commands, 8, 8, 'layer1');
+
+    expect(buf.getPixel(0, 0)).toEqual([0, 0, 255, 255]);
+  });
+
+  it('should create a fresh buffer of the correct dimensions', () => {
+    const buf = replayCommands([], 16, 32, 'layer1');
+
+    expect(buf.width).toBe(16);
+    expect(buf.height).toBe(32);
+    // Empty replay produces a blank buffer
+    expect(buf.getPixel(0, 0)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should skip unknown command types gracefully', () => {
+    const buf = replayCommands(
+      [
+        { type: 'nonexistent_command', params: {} },
+        { type: 'set_pixel', params: { x: 0, y: 0, r: 255, g: 0, b: 0, a: 255 } },
+      ],
+      8, 8, 'layer1',
+    );
+
+    // Unknown command skipped, known command still executed
+    expect(buf.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+  });
+
+  it('should replay fill_rect command covering multiple pixels', () => {
+    const buf = replayCommands(
+      [{ type: 'fill_rect', params: { x: 0, y: 0, w: 3, h: 2, r: 128, g: 64, b: 32, a: 255 } }],
+      8, 8, 'layer1',
+    );
+
+    // All pixels in the 3x2 rect should be filled
+    for (let y = 0; y < 2; y++) {
+      for (let x = 0; x < 3; x++) {
+        expect(buf.getPixel(x, y)).toEqual([128, 64, 32, 255]);
+      }
+    }
+    // Pixel outside the rect should be untouched
+    expect(buf.getPixel(3, 0)).toEqual([0, 0, 0, 0]);
+  });
+});

package/src/lib/history/replay-engine.ts

@@ -0,0 +1,149 @@
+/**
+ * Command Replay Engine -- the core of the semantic history system.
+ *
+ * Instead of traditional undo/redo that walks backward through state snapshots,
+ * the replay engine re-executes commands from scratch on a fresh PixelBuffer.
+ * This enables powerful operations like reordering, toggling, and parameter
+ * editing that would be impossible with snapshot-based undo.
+ *
+ * The engine looks up command definitions in the command registry and calls
+ * their execute() functions with a temporary command context containing a
+ * fresh PixelBuffer.
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { commandRegistry } from '../core/registries.svelte.js';
+import type { CommandContext } from '../core/commands.js';
+import type { ActionLogEntry } from './action-log.svelte.js';
+import { actionLog } from './action-log.svelte.js';
+
+// --- Types ---
+
+export interface ReplayCommand {
+  type: string;
+  params: Record<string, unknown>;
+}
+
+// --- Core replay ---
+
+/**
+ * Replay a sequence of commands on a fresh pixel buffer.
+ *
+ * Creates a new PixelBuffer and a temporary CommandContext, then executes
+ * each command in order. Commands that are not registered are skipped with
+ * a warning rather than throwing, to be resilient to missing plugins.
+ */
+export function replayCommands(
+  commands: ReplayCommand[],
+  width: number,
+  height: number,
+  layerId: string,
+): PixelBuffer {
+  const buffer = new PixelBuffer(width, height);
+
+  // Build a temporary context with the fresh buffer
+  const ctx: CommandContext = {
+    pixelBuffer: buffer,
+    layerId,
+    width,
+    height,
+  };
+
+  for (const cmd of commands) {
+    const def = commandRegistry.get(cmd.type);
+    if (!def) {
+      console.warn(`[replay-engine] Skipping unknown command type "${cmd.type}"`);
+      continue;
+    }
+    // Clone params to avoid mutation of the source data during execute
+    const params = { ...cmd.params };
+    def.execute(params, ctx);
+  }
+
+  return buffer;
+}
+
+// --- Preview / apply operations ---
+
+/**
+ * Preview a reorder: replay entries in a proposed new order and return the
+ * resulting buffer. Does NOT modify the action log state.
+ *
+ * Only enabled entries are replayed; disabled entries are skipped.
+ */
+export function previewReorder(
+  entries: ActionLogEntry[],
+  newOrder: string[],
+  width: number,
+  height: number,
+  layerId: string,
+): PixelBuffer {
+  const entryMap = new Map(entries.map((e) => [e.commandId, e]));
+
+  const commands: ReplayCommand[] = [];
+  for (const id of newOrder) {
+    const entry = entryMap.get(id);
+    if (!entry || !entry.enabled) continue;
+    commands.push({ type: entry.type, params: entry.params });
+  }
+
+  return replayCommands(commands, width, height, layerId);
+}
+
+/**
+ * Apply a reorder: update the action log entries to the new order and
+ * return the replayed buffer. The caller is responsible for applying the
+ * buffer to the canvas.
+ */
+export function applyReorder(
+  newOrder: string[],
+  width: number,
+  height: number,
+  layerId: string,
+): PixelBuffer {
+  const currentEntries = actionLog.getEntries();
+  const entryMap = new Map(currentEntries.map((e) => [e.commandId, e]));
+
+  // Reorder entries according to newOrder
+  const reordered: ActionLogEntry[] = [];
+  for (const id of newOrder) {
+    const entry = entryMap.get(id);
+    if (entry) reordered.push(entry);
+  }
+
+  // Update the action log
+  actionLog.setEntries(reordered);
+
+  // Replay enabled entries in the new order
+  const commands: ReplayCommand[] = reordered
+    .filter((e) => e.enabled)
+    .map((e) => ({ type: e.type, params: e.params }));
+
+  return replayCommands(commands, width, height, layerId);
+}
+
+/**
+ * Preview a parameter edit: replay the full action log with one entry's
+ * params replaced. Does NOT modify the action log state.
+ */
+export function previewParamEdit(
+  entryId: string,
+  newParams: Record<string, unknown>,
+  width: number,
+  height: number,
+  layerId: string,
+): PixelBuffer {
+  const entries = actionLog.getEntries();
+
+  const commands: ReplayCommand[] = [];
+  for (const entry of entries) {
+    if (!entry.enabled) continue;
+    if (entry.commandId === entryId) {
+      commands.push({ type: entry.type, params: newParams });
+    } else {
+      commands.push({ type: entry.type, params: entry.params });
+    }
+  }
+
+  return replayCommands(commands, width, height, layerId);
+}

package/src/lib/history/spec-format.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Tests for the Spec Export/Import module.
+ *
+ * Exercises export, import, roundtrip, and diff operations on spec documents.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { ActionLogEntry } from './action-log.svelte.js';
+import type { SpecDocument, SpecCommand } from './spec-format.js';
+import { exportSpec, importSpec, diffSpecs } from './spec-format.js';
+
+// --- Helpers ---
+
+function makeEntry(
+  type: string,
+  params: Record<string, unknown>,
+  description: string,
+  enabled = true,
+): ActionLogEntry {
+  return {
+    commandId: crypto.randomUUID(),
+    type,
+    plugin: 'test/plugin',
+    description,
+    timestamp: Date.now(),
+    enabled,
+    params,
+  };
+}
+
+function makeSpec(commands: SpecCommand[], width = 32, height = 32): SpecDocument {
+  return {
+    version: '1.0.0',
+    canvasWidth: width,
+    canvasHeight: height,
+    commands,
+  };
+}
+
+// --- Tests ---
+
+describe('Spec Format', () => {
+  describe('Export', () => {
+    it('should produce a valid spec document from action log entries', () => {
+      const entries = [
+        makeEntry('draw_pixel', { x: 5, y: 10, color: '#ff0000' }, 'Drew pixel at (5, 10)'),
+        makeEntry('fill_rect', { x: 0, y: 0, w: 8, h: 8 }, 'Filled 8x8 rect'),
+      ];
+
+      const spec = exportSpec(entries, 32, 32);
+
+      expect(spec.version).toBe('1.0.0');
+      expect(spec.canvasWidth).toBe(32);
+      expect(spec.canvasHeight).toBe(32);
+      expect(spec.commands).toHaveLength(2);
+      expect(spec.commands[0]?.type).toBe('draw_pixel');
+      expect(spec.commands[0]?.description).toBe('Drew pixel at (5, 10)');
+      expect(spec.commands[0]?.params["x"]).toBe(5);
+      expect(spec.commands[1]?.type).toBe('fill_rect');
+    });
+
+    it('should exclude disabled entries from the export', () => {
+      const entries = [
+        makeEntry('draw_pixel', { x: 0, y: 0 }, 'Enabled'),
+        makeEntry('draw_pixel', { x: 1, y: 1 }, 'Disabled', false),
+        makeEntry('draw_pixel', { x: 2, y: 2 }, 'Also enabled'),
+      ];
+
+      const spec = exportSpec(entries, 16, 16);
+
+      expect(spec.commands).toHaveLength(2);
+      expect(spec.commands[0]?.description).toBe('Enabled');
+      expect(spec.commands[1]?.description).toBe('Also enabled');
+    });
+
+    it('should strip internal params (underscore-prefixed) from export', () => {
+      const entries = [
+        makeEntry('draw_pixel', {
+          x: 5,
+          y: 10,
+          _oldPixel: [0, 0, 0, 0],
+          _snapshot: { data: 'internal' },
+        }, 'Drew pixel'),
+      ];
+
+      const spec = exportSpec(entries, 32, 32);
+
+      expect(spec.commands[0]?.params).toEqual({ x: 5, y: 10 });
+      expect(spec.commands[0]?.params["_oldPixel"]).toBeUndefined();
+      expect(spec.commands[0]?.params["_snapshot"]).toBeUndefined();
+    });
+  });
+
+  describe('Import', () => {
+    it('should parse a spec document into a command sequence', () => {
+      const spec = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+        { type: 'fill_rect', description: 'Filled rect', params: { w: 8, h: 8 } },
+      ]);
+
+      const commands = importSpec(spec);
+
+      expect(commands).toHaveLength(2);
+      expect(commands[0]?.type).toBe('draw_pixel');
+      expect(commands[0]?.params["x"]).toBe(0);
+      expect(commands[1]?.type).toBe('fill_rect');
+      expect(commands[1]?.params["w"]).toBe(8);
+    });
+
+    it('should throw on invalid spec document', () => {
+      expect(() => importSpec(null as unknown as SpecDocument)).toThrow('Invalid spec document');
+      expect(() => importSpec({} as SpecDocument)).toThrow('Invalid spec document');
+    });
+  });
+
+  describe('Roundtrip', () => {
+    it('should produce identical spec after export -> import -> export', () => {
+      const entries = [
+        makeEntry('draw_pixel', { x: 5, y: 10, color: '#ff0000' }, 'Drew red pixel'),
+        makeEntry('fill_rect', { x: 0, y: 0, w: 16, h: 16, color: '#00ff00' }, 'Filled green rect'),
+      ];
+
+      const spec1 = exportSpec(entries, 64, 64);
+      const commands = importSpec(spec1);
+
+      // Recreate entries from imported commands
+      const reimportedEntries = commands.map((cmd, i) => ({
+        commandId: crypto.randomUUID(),
+        type: cmd.type,
+        plugin: 'test/plugin',
+        description: spec1.commands[i]?.description ?? '',
+        timestamp: Date.now(),
+        enabled: true,
+        params: cmd.params,
+      }));
+
+      const spec2 = exportSpec(reimportedEntries, 64, 64);
+
+      // Compare the command data (ignoring version/canvas metadata which are set by exportSpec)
+      expect(spec2.commands).toHaveLength(spec1.commands.length);
+      for (let i = 0; i < spec1.commands.length; i++) {
+        expect(spec2.commands[i]?.type).toBe(spec1.commands[i]?.type);
+        expect(spec2.commands[i]?.description).toBe(spec1.commands[i]?.description);
+        expect(spec2.commands[i]?.params).toEqual(spec1.commands[i]?.params);
+      }
+    });
+  });
+
+  describe('Diff', () => {
+    it('should return no differences for identical specs', () => {
+      const commands = [
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+      ];
+      const spec1 = makeSpec(commands);
+      const spec2 = makeSpec([...commands]);
+
+      const diffs = diffSpecs(spec1, spec2);
+      expect(diffs).toHaveLength(0);
+    });
+
+    it('should detect an added command', () => {
+      const spec1 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+      ]);
+      const spec2 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+        { type: 'fill_rect', description: 'Filled rect', params: { w: 8, h: 8 } },
+      ]);
+
+      const diffs = diffSpecs(spec1, spec2);
+
+      expect(diffs).toHaveLength(1);
+      expect(diffs[0]?.type).toBe('added');
+      expect(diffs[0]?.index).toBe(1);
+      expect(diffs[0]?.command?.type).toBe('fill_rect');
+    });
+
+    it('should detect a removed command', () => {
+      const spec1 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+        { type: 'fill_rect', description: 'Filled rect', params: { w: 8, h: 8 } },
+      ]);
+      const spec2 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+      ]);
+
+      const diffs = diffSpecs(spec1, spec2);
+
+      expect(diffs).toHaveLength(1);
+      expect(diffs[0]?.type).toBe('removed');
+      expect(diffs[0]?.index).toBe(1);
+      expect(diffs[0]?.oldCommand?.type).toBe('fill_rect');
+    });
+
+    it('should detect modified params', () => {
+      const spec1 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0, color: '#ff0000' } },
+      ]);
+      const spec2 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 5, y: 0, color: '#ff0000' } },
+      ]);
+
+      const diffs = diffSpecs(spec1, spec2);
+
+      expect(diffs).toHaveLength(1);
+      expect(diffs[0]?.type).toBe('modified');
+      expect(diffs[0]?.changes).toContain('x');
+      expect(diffs[0]?.changes).not.toContain('color');
+      expect(diffs[0]?.changes).not.toContain('y');
+    });
+
+    it('should detect type change as a modification', () => {
+      const spec1 = makeSpec([
+        { type: 'draw_pixel', description: 'Drew pixel', params: { x: 0, y: 0 } },
+      ]);
+      const spec2 = makeSpec([
+        { type: 'fill_rect', description: 'Filled rect', params: { x: 0, y: 0 } },
+      ]);
+
+      const diffs = diffSpecs(spec1, spec2);
+
+      expect(diffs).toHaveLength(1);
+      expect(diffs[0]?.type).toBe('modified');
+      expect(diffs[0]?.changes).toContain('type');
+    });
+
+    it('should handle complex diffs with multiple changes', () => {
+      const spec1 = makeSpec([
+        { type: 'cmd_a', description: 'A', params: { v: 1 } },
+        { type: 'cmd_b', description: 'B', params: { v: 2 } },
+        { type: 'cmd_c', description: 'C', params: { v: 3 } },
+      ]);
+      const spec2 = makeSpec([
+        { type: 'cmd_a', description: 'A', params: { v: 1 } },     // same
+        { type: 'cmd_b', description: 'B', params: { v: 99 } },    // modified
+        { type: 'cmd_c', description: 'C', params: { v: 3 } },     // same
+        { type: 'cmd_d', description: 'D', params: { v: 4 } },     // added
+      ]);
+
+      const diffs = diffSpecs(spec1, spec2);
+
+      expect(diffs).toHaveLength(2);
+      expect(diffs[0]?.type).toBe('modified');
+      expect(diffs[0]?.index).toBe(1);
+      expect(diffs[0]?.changes).toContain('v');
+      expect(diffs[1]?.type).toBe('added');
+      expect(diffs[1]?.index).toBe(3);
+    });
+  });
+});