pixelweaver 0.1.0

package/src/lib/history/macros.svelte.ts

@@ -0,0 +1,320 @@
+/**
+ * Macro System -- record and replay sequences of commands.
+ *
+ * Macros capture commands as they are dispatched (via the onExecute hook) and
+ * can replay them later. Two coordinate modes are supported:
+ *
+ * - 'absolute': commands are replayed with their original coordinates.
+ * - 'relative': coordinate params are shifted by an offset from the recorded
+ *   origin (the first command's position), allowing the macro to be applied
+ *   at different canvas locations.
+ *
+ * Coordinate params are identified by naming convention: params named x, y,
+ * x0, y0, x1, y1, cx, cy, or items in a `pixels` array with x/y fields.
+ *
+ * Module-level singleton using Svelte 5 $state runes.
+ */
+
+import { dispatch as dispatchCommand, onExecute } from '../core/dispatcher.js';
+import type { Command } from '../core/commands.js';
+
+/**
+ * Deep-clone a plain object. Uses JSON round-trip instead of deepClone
+ * because command params may be Svelte 5 reactive proxies ($state) which
+ * deepClone cannot handle.
+ */
+function deepClone<T>(obj: T): T {
+  return JSON.parse(JSON.stringify(obj)) as T;
+}
+
+// --- Types ---
+
+export interface Macro {
+  id: string;
+  name: string;
+  commands: { type: string; params: Record<string, unknown> }[];
+  coordMode: 'absolute' | 'relative';
+  // For relative mode: the reference origin (first command's coordinate position)
+  originX?: number;
+  originY?: number;
+}
+
+interface RecordedCommand {
+  type: string;
+  params: Record<string, unknown>;
+}
+
+// --- Coordinate parameter names recognized for relative mode ---
+
+const COORD_X_NAMES = new Set(['x', 'x0', 'x1', 'cx']);
+const COORD_Y_NAMES = new Set(['y', 'y0', 'y1', 'cy']);
+
+// --- Reactive state ---
+
+let macros = $state<Macro[]>([]);
+let recording = $state<boolean>(false);
+let recordedCommands = $state<RecordedCommand[]>([]);
+
+/** Unsubscribe function for the onExecute hook during recording. */
+let unsubscribeHook: (() => void) | null = null;
+
+// --- Internal helpers ---
+
+/**
+ * Extract the first x/y coordinate pair from a command's params.
+ * Used to determine the origin for relative-mode macros.
+ */
+function extractOrigin(params: Record<string, unknown>): { x: number; y: number } | null {
+  // Check direct params first
+  for (const xName of COORD_X_NAMES) {
+    for (const yName of COORD_Y_NAMES) {
+      const xv = params[xName];
+      const yv = params[yName];
+      if (typeof xv === 'number' && typeof yv === 'number') {
+        return { x: xv, y: yv };
+      }
+    }
+  }
+
+  // Check pixels array
+  const pixels = params["pixels"];
+  if (Array.isArray(pixels) && pixels.length > 0) {
+    const first: unknown = pixels[0];
+    if (typeof first === 'object' && first !== null) {
+      const rec = first as Record<string, unknown>;
+      if (typeof rec["x"] === 'number' && typeof rec["y"] === 'number') {
+        return { x: rec["x"], y: rec["y"] };
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Shift coordinate params in a command by the given offset.
+ * Returns a new params object (does not mutate the original).
+ */
+function offsetParams(
+  params: Record<string, unknown>,
+  offsetX: number,
+  offsetY: number,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...params };
+
+  // Shift direct coordinate params
+  for (const xName of COORD_X_NAMES) {
+    if (typeof result[xName] === 'number') {
+      result[xName] = result[xName] + offsetX;
+    }
+  }
+  for (const yName of COORD_Y_NAMES) {
+    if (typeof result[yName] === 'number') {
+      result[yName] = result[yName] + offsetY;
+    }
+  }
+
+  // Shift pixels array entries
+  if (Array.isArray(result["pixels"])) {
+    result["pixels"] = (result["pixels"] as Array<Record<string, unknown>>).map((px) => {
+      const shifted: Record<string, unknown> = { ...px };
+      if (typeof shifted["x"] === 'number') shifted["x"] = shifted["x"] + offsetX;
+      if (typeof shifted["y"] === 'number') shifted["y"] = shifted["y"] + offsetY;
+      return shifted;
+    });
+  }
+
+  return result;
+}
+
+// --- Recording operations ---
+
+/** Start recording commands. Hooks into the dispatcher's onExecute. */
+function startRecording(): void {
+  if (recording) return;
+  recording = true;
+  recordedCommands = [];
+
+  unsubscribeHook = onExecute((command: Command) => {
+    recordedCommands.push({
+      type: command.type,
+      // Clone params to capture the state at recording time
+      params: deepClone(command.params),
+    });
+  });
+}
+
+/**
+ * Stop recording and create a macro from the recorded commands.
+ * Returns the new Macro.
+ */
+function stopRecording(name: string, coordMode: 'absolute' | 'relative'): Macro {
+  if (unsubscribeHook) {
+    unsubscribeHook();
+    unsubscribeHook = null;
+  }
+  recording = false;
+
+  // Determine origin for relative mode from the first command's coordinates
+  let originX: number | undefined;
+  let originY: number | undefined;
+
+  if (coordMode === 'relative' && recordedCommands.length > 0) {
+    const first = recordedCommands[0];
+    const origin = first ? extractOrigin(first.params) : null;
+    if (origin) {
+      originX = origin.x;
+      originY = origin.y;
+    }
+  }
+
+  // Omit originX/originY when absent (exactOptionalPropertyTypes)
+  const macro: Macro = {
+    id: crypto.randomUUID(),
+    name,
+    commands: recordedCommands.map((c) => ({
+      type: c.type,
+      params: deepClone(c.params),
+    })),
+    coordMode,
+  };
+  if (originX !== undefined) macro.originX = originX;
+  if (originY !== undefined) macro.originY = originY;
+
+  macros.push(macro);
+  recordedCommands = [];
+
+  return macro;
+}
+
+/** Cancel recording and discard any recorded commands. */
+function cancelRecording(): void {
+  if (unsubscribeHook) {
+    unsubscribeHook();
+    unsubscribeHook = null;
+  }
+  recording = false;
+  recordedCommands = [];
+}
+
+// --- Macro management ---
+
+/** Delete a macro by ID. */
+function deleteMacro(id: string): void {
+  const idx = macros.findIndex((m) => m.id === id);
+  if (idx !== -1) macros.splice(idx, 1);
+}
+
+/** Rename a macro. */
+function renameMacro(id: string, name: string): void {
+  const macro = macros.find((m) => m.id === id);
+  if (macro) macro.name = name;
+}
+
+/**
+ * Replay a macro by dispatching its commands through the dispatcher.
+ *
+ * For 'relative' mode, offsetX/offsetY shift all coordinate params
+ * relative to the macro's recorded origin.
+ *
+ * For 'absolute' mode, offsetX/offsetY are ignored.
+ */
+function replayMacro(
+  macro: Macro,
+  offsetX?: number,
+  offsetY?: number,
+): void {
+  for (const cmd of macro.commands) {
+    let params = deepClone(cmd.params);
+
+    if (macro.coordMode === 'relative' && (offsetX !== undefined || offsetY !== undefined)) {
+      // Compute the shift from the macro's origin to the target position
+      const dx = (offsetX ?? 0) - (macro.originX ?? 0);
+      const dy = (offsetY ?? 0) - (macro.originY ?? 0);
+      params = offsetParams(params, dx, dy);
+    }
+
+    const command: Command = {
+      type: cmd.type,
+      plugin: 'macro',
+      version: '1.0.0',
+      params,
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+
+    dispatchCommand(command);
+  }
+}
+
+// --- Serialization ---
+
+/** Serialize all macros to a plain object for persistence. */
+function serialize(): object {
+  return {
+    macros: macros.map((m) => ({
+      id: m.id,
+      name: m.name,
+      commands: m.commands,
+      coordMode: m.coordMode,
+      originX: m.originX,
+      originY: m.originY,
+    })),
+  };
+}
+
+/** Deserialize macros from a previously serialized object. */
+function deserialize(data: object): void {
+  // Type as Partial<Macro>[] since `data` came from untrusted JSON --
+  // the defensive fallbacks below only make sense when each field is
+  // possibly absent.
+  const d = data as { macros?: Partial<Macro>[] };
+  if (Array.isArray(d.macros)) {
+    // Omit originX/originY when absent (exactOptionalPropertyTypes)
+    macros = d.macros.map((m) => {
+      const restored: Macro = {
+        id: m.id ?? crypto.randomUUID(),
+        name: m.name ?? 'Unnamed',
+        commands: m.commands ?? [],
+        coordMode: m.coordMode ?? 'absolute',
+      };
+      if (m.originX !== undefined) restored.originX = m.originX;
+      if (m.originY !== undefined) restored.originY = m.originY;
+      return restored;
+    });
+  }
+}
+
+// --- Test helper ---
+
+/** Reset all macro state. Intended for tests only. */
+function _resetForTesting(): void {
+  if (unsubscribeHook) {
+    unsubscribeHook();
+    unsubscribeHook = null;
+  }
+  macros = [];
+  recording = false;
+  recordedCommands = [];
+}
+
+// --- Public API ---
+
+export const macroSystem = {
+  get macros() { return macros; },
+  get recording() { return recording; },
+  get recordedCommands() { return recordedCommands; },
+
+  startRecording,
+  stopRecording,
+  cancelRecording,
+  deleteMacro,
+  renameMacro,
+  replayMacro,
+  serialize,
+  deserialize,
+  _resetForTesting,
+};
+
+// Re-export the offsetParams helper for testing
+export { offsetParams as _offsetParamsForTesting };

package/src/lib/history/macros.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for the Macro System.
+ *
+ * Tests recording, replaying (absolute and relative modes), coordinate
+ * offsetting, cancellation, deletion, renaming, and serialization.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { CommandDefinition, CommandContext } from '../core/commands.js';
+import { commandRegistry } from '../core/registries.svelte.js';
+import { dispatch, _resetForTesting as resetDispatcher } from '../core/dispatcher.js';
+import type { Command } from '../core/commands.js';
+import type { CommandType, ParamsOf } from '../core/command-params.js';
+import { macroSystem, _offsetParamsForTesting as offsetParams } from './macros.svelte.js';
+
+// --- Helpers ---
+
+function registerTestCommand(name: string): void {
+  const def: CommandDefinition = {
+    execute(params, ctx: CommandContext) {
+      // Track execution for verification
+      const execLog = ctx["_execLog"] as Array<Record<string, unknown>> | undefined;
+      if (execLog) {
+        execLog.push({ type: name, ...params });
+      }
+    },
+    undo() {},
+    describe: (params) => `${name}(${JSON.stringify(params)})`,
+    tier: 'frame',
+  };
+  commandRegistry.set(name, def);
+}
+
+// Typed overload: validates params when type is a known command literal
+function makeAndDispatch<T extends CommandType>(type: T, params: ParamsOf<T>): Command;
+// String fallback: for dynamic/unknown command types in tests
+function makeAndDispatch(type: string, params?: Record<string, unknown>): Command;
+function makeAndDispatch(type: string, params: Record<string, unknown> = {}): Command {
+  const cmd: Command = {
+    type,
+    plugin: 'test/plugin',
+    version: '1.0.0',
+    params,
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  };
+  dispatch(cmd);
+  return cmd;
+}
+
+// --- Tests ---
+
+describe('Macro System', () => {
+  beforeEach(() => {
+    resetDispatcher();
+    macroSystem._resetForTesting();
+    registerTestCommand('draw_pixel');
+    registerTestCommand('draw_line');
+  });
+
+  it('should record commands and create a macro in absolute mode', () => {
+    macroSystem.startRecording();
+    expect(macroSystem.recording).toBe(true);
+
+    makeAndDispatch('draw_pixel', { x: 5, y: 10, color: '#ff0000' });
+    makeAndDispatch('draw_pixel', { x: 6, y: 11, color: '#00ff00' });
+
+    const macro = macroSystem.stopRecording('Test Macro', 'absolute');
+
+    expect(macroSystem.recording).toBe(false);
+    expect(macro.name).toBe('Test Macro');
+    expect(macro.coordMode).toBe('absolute');
+    expect(macro.commands).toHaveLength(2);
+    expect(macro.commands[0]?.type).toBe('draw_pixel');
+    expect(macro.commands[0]?.params["x"]).toBe(5);
+    expect(macro.commands[1]?.params["x"]).toBe(6);
+    expect(macroSystem.macros).toHaveLength(1);
+  });
+
+  it('should record commands and create a macro in relative mode with origin', () => {
+    macroSystem.startRecording();
+
+    makeAndDispatch('draw_pixel', { x: 10, y: 20, color: '#ff0000' });
+    makeAndDispatch('draw_pixel', { x: 12, y: 22, color: '#00ff00' });
+
+    const macro = macroSystem.stopRecording('Relative Macro', 'relative');
+
+    expect(macro.coordMode).toBe('relative');
+    expect(macro.originX).toBe(10);
+    expect(macro.originY).toBe(20);
+  });
+
+  it('should replay a macro in absolute mode dispatching commands', () => {
+    // Record
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 5, y: 10 });
+    const macro = macroSystem.stopRecording('Abs Macro', 'absolute');
+
+    // Replay -- should dispatch through the dispatcher
+    macroSystem.replayMacro(macro);
+
+    // The macro's commands were dispatched (we can check the macro system
+    // does not throw and commands exist)
+    expect(macro.commands).toHaveLength(1);
+  });
+
+  it('should replay a macro in relative mode with coordinate offset', () => {
+    // Record at origin (10, 20)
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 10, y: 20 });
+    makeAndDispatch('draw_pixel', { x: 12, y: 22 });
+    const macro = macroSystem.stopRecording('Rel Macro', 'relative');
+
+    // The macro's origin should be (10, 20)
+    expect(macro.originX).toBe(10);
+    expect(macro.originY).toBe(20);
+
+    // Verify coordinate offset logic directly
+    // Replay at (30, 40): shift = (30-10, 40-20) = (+20, +20)
+    const shifted = offsetParams({ x: 10, y: 20 }, 20, 20);
+    expect(shifted["x"]).toBe(30);
+    expect(shifted["y"]).toBe(40);
+  });
+
+  it('should correctly shift coordinate params including x0, y0, x1, y1, cx, cy', () => {
+    const params = { x: 0, y: 0, x0: 5, y0: 10, x1: 15, y1: 20, cx: 10, cy: 15 };
+    const shifted = offsetParams(params, 3, 7);
+
+    expect(shifted["x"]).toBe(3);
+    expect(shifted["y"]).toBe(7);
+    expect(shifted["x0"]).toBe(8);
+    expect(shifted["y0"]).toBe(17);
+    expect(shifted["x1"]).toBe(18);
+    expect(shifted["y1"]).toBe(27);
+    expect(shifted["cx"]).toBe(13);
+    expect(shifted["cy"]).toBe(22);
+  });
+
+  it('should offset pixels array entries in relative mode', () => {
+    const params = {
+      pixels: [
+        { x: 0, y: 0, color: '#ff0000' },
+        { x: 1, y: 2, color: '#00ff00' },
+      ],
+    };
+    const shifted = offsetParams(params, 10, 20);
+    const pixels = shifted["pixels"] as Array<{ x: number; y: number; color: string }>;
+
+    expect(pixels[0]?.x).toBe(10);
+    expect(pixels[0]?.y).toBe(20);
+    expect(pixels[0]?.color).toBe('#ff0000');
+    expect(pixels[1]?.x).toBe(11);
+    expect(pixels[1]?.y).toBe(22);
+  });
+
+  it('should cancel recording and discard commands', () => {
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 1, y: 1 });
+    makeAndDispatch('draw_pixel', { x: 2, y: 2 });
+
+    macroSystem.cancelRecording();
+
+    expect(macroSystem.recording).toBe(false);
+    expect(macroSystem.recordedCommands).toHaveLength(0);
+    expect(macroSystem.macros).toHaveLength(0);
+  });
+
+  it('should delete a macro by ID', () => {
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 1, y: 1 });
+    const macro = macroSystem.stopRecording('Delete Me', 'absolute');
+
+    expect(macroSystem.macros).toHaveLength(1);
+
+    macroSystem.deleteMacro(macro.id);
+    expect(macroSystem.macros).toHaveLength(0);
+  });
+
+  it('should rename a macro', () => {
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 1, y: 1 });
+    const macro = macroSystem.stopRecording('Old Name', 'absolute');
+
+    macroSystem.renameMacro(macro.id, 'New Name');
+
+    expect(macroSystem.macros[0]?.name).toBe('New Name');
+  });
+
+  it('should serialize and deserialize macros (roundtrip)', () => {
+    // Create two macros
+    macroSystem.startRecording();
+    makeAndDispatch('draw_pixel', { x: 5, y: 10 });
+    macroSystem.stopRecording('Macro A', 'absolute');
+
+    macroSystem.startRecording();
+    makeAndDispatch('draw_line', { x0: 0, y0: 0, x1: 10, y1: 10 });
+    macroSystem.stopRecording('Macro B', 'relative');
+
+    const serialized = macroSystem.serialize();
+
+    // Reset and restore
+    macroSystem._resetForTesting();
+    expect(macroSystem.macros).toHaveLength(0);
+
+    macroSystem.deserialize(serialized);
+    expect(macroSystem.macros).toHaveLength(2);
+    expect(macroSystem.macros[0]?.name).toBe('Macro A');
+    expect(macroSystem.macros[0]?.coordMode).toBe('absolute');
+    expect(macroSystem.macros[1]?.name).toBe('Macro B');
+    expect(macroSystem.macros[1]?.coordMode).toBe('relative');
+    expect(macroSystem.macros[1]?.commands[0]?.params["x0"]).toBe(0);
+  });
+
+  it('should not record commands when not in recording mode', () => {
+    // Dispatch without starting recording
+    makeAndDispatch('draw_pixel', { x: 1, y: 1 });
+
+    // Start recording, then stop immediately
+    macroSystem.startRecording();
+    const macro = macroSystem.stopRecording('Empty', 'absolute');
+
+    expect(macro.commands).toHaveLength(0);
+  });
+});