pixelweaver 0.1.0

package/src/lib/core/dispatcher.ts

@@ -0,0 +1,361 @@
+/**
+ * Command Dispatcher -- the central routing system of PixelWeaver.
+ *
+ * When a command is dispatched:
+ *   1. Validate: ensure the command type is registered
+ *   2. Execute: call the command definition's execute()
+ *   3. Record: push onto the undo stack (with tier + parent pointer) and notify onExecute subscribers
+ *   4. Log: call describe() and append to the semantic log
+ *   5. Serialize: notify onSpecExport subscribers
+ *
+ * Two-tier undo: each command is tagged 'frame' (drawing ops) or 'project'
+ * (structural ops). Ctrl+Z always undoes the most recent command regardless
+ * of tier. The tier tag exists for future UI grouping and tier-filtered
+ * undo operations.
+ *
+ * Module-level singleton -- one dispatcher per app instance.
+ */
+
+import type {
+  Command,
+  CommandContext,
+  CommandDefinition,
+  SemanticLogEntry,
+  UndoEntry,
+} from './commands.js';
+import type { CommandType, ParamsOf } from './command-params.js';
+import { commandRegistry } from './registries.svelte.js';
+
+// --- Sync hook ---
+// Called after every successful command dispatch so the sync layer can
+// forward commands to the collaboration server without tight coupling.
+
+type DispatchHook = (command: Command) => void;
+let dispatchHook: DispatchHook | null = null;
+
+/** Register (or clear) the post-dispatch hook used by the sync layer. */
+export function setDispatchHook(hook: DispatchHook | null): void {
+  dispatchHook = hook;
+}
+
+/**
+ * Notify subscribers using a defensive copy so callbacks that add/remove
+ * other subscribers during iteration don't corrupt the loop.
+ */
+function notify<T>(callbacks: ReadonlyArray<(arg: T) => void>, arg: T): void {
+  for (const cb of [...callbacks]) cb(arg);
+}
+
+// --- Consumer hook types ---
+
+type ExecuteCallback = (command: Command) => void;
+type UndoCallback = (command: Command) => void;
+type LogCallback = (entry: SemanticLogEntry) => void;
+type SpecExportCallback = (command: Command) => void;
+
+// --- Dispatcher state ---
+
+/** The shared command context; later phases will populate with canvas, layers, etc. */
+let context: CommandContext = {};
+
+/** Undo stack with tier and parent pointers (most recent entry last) */
+const undoStack: UndoEntry[] = [];
+
+/** Redo stack with tier and parent pointers (most recently undone entry last) */
+const redoStack: UndoEntry[] = [];
+
+/** Semantic log of all executed commands */
+const semanticLog: SemanticLogEntry[] = [];
+
+/** Maximum number of entries in the undo stack; oldest entries are dropped when exceeded */
+let maxUndoSize = 500;
+
+/**
+ * Save checkpoint: the ID of the undo stack's top entry at the time of the
+ * last save. Comparing the current top-of-stack ID against this value tells
+ * us whether the project has unsaved changes -- correctly handling undo past
+ * the save point, redo back to it, and new commands after undo.
+ *
+ * null means "saved at empty state" (fresh/new project).
+ */
+let saveCheckpointId: string | null = null;
+
+// --- Consumer hook subscriptions ---
+
+const executeCallbacks: ExecuteCallback[] = [];
+const undoCallbacks: UndoCallback[] = [];
+const logCallbacks: LogCallback[] = [];
+const specExportCallbacks: SpecExportCallback[] = [];
+
+// --- Internal helpers ---
+
+/** Resolve the tier for a command from its definition, defaulting to 'frame'. */
+function resolveTier(commandType: string): UndoEntry['tier'] {
+  const def = commandRegistry.get(commandType);
+  return def?.tier ?? 'frame';
+}
+
+/** Get the ID of the topmost undo entry, or null if the stack is empty. */
+function topUndoId(): string | null {
+  return undoStack[undoStack.length - 1]?.id ?? null;
+}
+
+// --- Public API ---
+
+/** Subscribe to command execution events. Returns an unsubscribe function. */
+export function onExecute(callback: ExecuteCallback): () => void {
+  executeCallbacks.push(callback);
+  return () => {
+    const idx = executeCallbacks.indexOf(callback);
+    if (idx !== -1) executeCallbacks.splice(idx, 1);
+  };
+}
+
+/** Subscribe to command undo events. Returns an unsubscribe function. */
+export function onUndo(callback: UndoCallback): () => void {
+  undoCallbacks.push(callback);
+  return () => {
+    const idx = undoCallbacks.indexOf(callback);
+    if (idx !== -1) undoCallbacks.splice(idx, 1);
+  };
+}
+
+/** Subscribe to semantic log events. Returns an unsubscribe function. */
+export function onLog(callback: LogCallback): () => void {
+  logCallbacks.push(callback);
+  return () => {
+    const idx = logCallbacks.indexOf(callback);
+    if (idx !== -1) logCallbacks.splice(idx, 1);
+  };
+}
+
+/** Subscribe to spec-export events. Returns an unsubscribe function. */
+export function onSpecExport(callback: SpecExportCallback): () => void {
+  specExportCallbacks.push(callback);
+  return () => {
+    const idx = specExportCallbacks.indexOf(callback);
+    if (idx !== -1) specExportCallbacks.splice(idx, 1);
+  };
+}
+
+/**
+ * Dispatch a command: validate, execute, record, log, and notify consumers.
+ * Throws if the command type is not registered.
+ */
+// Typed overload: compile-time param validation for known commands
+export function dispatch<T extends CommandType>(command: Command & { type: T; params: ParamsOf<T> }): void;
+// String fallback: for dynamic dispatch (import_spec replay, etc.)
+export function dispatch(command: Command): void;
+// Implementation
+export function dispatch(command: Command): void {
+  // Registry stores CommandDefinition<any> as a type-erasure seam;
+  // narrow through unknown to the default-P shape so unsafe-assignment
+  // does not fire on the UndoEntry.definition assignment below.
+  const definition = commandRegistry.get(command.type) as unknown as
+    | CommandDefinition
+    | undefined;
+  if (!definition) {
+    throw new Error(
+      `Unknown command type "${command.type}". ` +
+        `Has the plugin that provides it been loaded?`,
+    );
+  }
+
+  // Execute and capture snapshot for undo
+  const snapshot = definition.execute(command.params, context);
+
+  // Build undo entry with tier, parent pointer, definition, and snapshot
+  const entry: UndoEntry = {
+    command,
+    definition,
+    tier: resolveTier(command.type),
+    id: command.id,
+    parentId: topUndoId(),
+    snapshot,
+  };
+
+  // Record for undo; new dispatch clears the redo stack
+  undoStack.push(entry);
+  redoStack.length = 0;
+
+  // Enforce max undo size by dropping oldest entries
+  while (undoStack.length > maxUndoSize) {
+    undoStack.shift();
+  }
+
+  // Semantic log
+  const logEntry: SemanticLogEntry = {
+    description: definition.describe(command.params),
+    timestamp: command.timestamp,
+    commandId: command.id,
+  };
+  semanticLog.push(logEntry);
+
+  // Notify consumers
+  notify(executeCallbacks, command);
+  notify(logCallbacks, logEntry);
+  notify(specExportCallbacks, command);
+
+  // Forward to the sync layer (best-effort, won't block local dispatch)
+  dispatchHook?.(command);
+}
+
+/**
+ * Undo the most recent command. Returns the undone command, or undefined if
+ * the undo stack is empty.
+ */
+export function undoLast(): Command | undefined {
+  const entry = undoStack.pop();
+  if (!entry) return undefined;
+
+  entry.definition.undo(entry.command.params, context, entry.snapshot);
+  redoStack.push(entry);
+
+  notify(undoCallbacks, entry.command);
+  return entry.command;
+}
+
+/**
+ * Redo the most recently undone command. Returns the redone command, or
+ * undefined if the redo stack is empty.
+ */
+export function redoLast(): Command | undefined {
+  const entry = redoStack.pop();
+  if (!entry) return undefined;
+
+  // Re-execute and capture a fresh snapshot (buffer state may differ from original)
+  const newSnapshot = entry.definition.execute(entry.command.params, context);
+  entry.snapshot = newSnapshot;
+
+  // Update parent pointer to current top of undo stack before pushing
+  entry.parentId = topUndoId();
+  undoStack.push(entry);
+
+  // Log the redo as a new semantic entry
+  const logEntry: SemanticLogEntry = {
+    description: entry.definition.describe(entry.command.params),
+    timestamp: Date.now(),
+    commandId: entry.command.id,
+  };
+  semanticLog.push(logEntry);
+
+  notify(executeCallbacks, entry.command);
+  notify(logCallbacks, logEntry);
+  notify(specExportCallbacks, entry.command);
+
+  return entry.command;
+}
+
+// --- Two-tier undo query API ---
+
+/** Read-only access to the undo stack (entries with tier + parent pointers). */
+export function getUndoStack(): readonly UndoEntry[] {
+  return undoStack;
+}
+
+/** Read-only access to the redo stack (entries with tier + parent pointers). */
+export function getRedoStack(): readonly UndoEntry[] {
+  return redoStack;
+}
+
+/** Whether there is at least one command to undo. */
+export function canUndo(): boolean {
+  return undoStack.length > 0;
+}
+
+/** Whether there is at least one command to redo. */
+export function canRedo(): boolean {
+  return redoStack.length > 0;
+}
+
+// --- Save checkpoint API ---
+
+/**
+ * Mark the current undo position as the save checkpoint. Call this after a
+ * successful save so that hasUnsavedChanges() returns false until the next
+ * dispatch/undo/redo changes the position.
+ */
+export function markSaveCheckpoint(): void {
+  saveCheckpointId = topUndoId();
+}
+
+/**
+ * Whether the project has been modified since the last save (or since
+ * creation, if never saved). Compares the current top-of-stack entry ID
+ * against the checkpoint recorded at save time.
+ *
+ * Correctly handles:
+ * - Undo past the save point (dirty again)
+ * - Redo back to the save point (clean again)
+ * - New commands diverging from the save point (dirty)
+ */
+export function hasUnsavedChanges(): boolean {
+  return topUndoId() !== saveCheckpointId;
+}
+
+// --- Undo stack size configuration ---
+
+/** Set the maximum undo stack size. Oldest entries are dropped when exceeded. */
+export function setMaxUndoSize(size: number): void {
+  if (size < 1) throw new Error('Max undo size must be at least 1');
+  maxUndoSize = size;
+  // Trim if current stack exceeds the new limit
+  while (undoStack.length > maxUndoSize) {
+    undoStack.shift();
+  }
+}
+
+/** Get the current maximum undo stack size. */
+export function getMaxUndoSize(): number {
+  return maxUndoSize;
+}
+
+// --- History management ---
+
+/**
+ * Clear all undo/redo history and the semantic log.
+ * Call this when creating a new project so stale commands from the
+ * previous project cannot trigger false unsaved-changes warnings or
+ * corrupt state via undo replay.
+ */
+export function clearHistory(): void {
+  undoStack.length = 0;
+  redoStack.length = 0;
+  semanticLog.length = 0;
+  // Reset checkpoint so a fresh project is not considered dirty
+  saveCheckpointId = null;
+}
+
+// --- Existing API ---
+
+/** Read-only access to the semantic log */
+export function getSemanticLog(): readonly SemanticLogEntry[] {
+  return semanticLog;
+}
+
+/** Set (or merge into) the shared command context */
+export function setContext(partial: CommandContext): void {
+  Object.assign(context, partial);
+}
+
+/** Get the shared command context */
+export function getContext(): CommandContext {
+  return context;
+}
+
+/**
+ * Reset all dispatcher state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  undoStack.length = 0;
+  redoStack.length = 0;
+  semanticLog.length = 0;
+  executeCallbacks.length = 0;
+  undoCallbacks.length = 0;
+  logCallbacks.length = 0;
+  specExportCallbacks.length = 0;
+  context = {};
+  maxUndoSize = 500;
+  dispatchHook = null;
+  saveCheckpointId = null;
+}

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

@@ -0,0 +1,7 @@
+import { describe, it, expect } from 'vitest';
+
+describe('PixelWeaver scaffolding', () => {
+  it('should pass a basic sanity check', () => {
+    expect(1 + 1).toBe(2);
+  });
+});

package/src/lib/core/notification-state.svelte.ts

@@ -0,0 +1,119 @@
+/**
+ * Notification State -- reactive singleton for the in-app notification banner.
+ * Manages a priority-ordered queue of notifications with auto-dismiss support.
+ *
+ * Lives in core so that plugin-api.ts and plugin-types.ts can depend on it
+ * without a core-to-UI layer violation. The UI component (NotificationBanner)
+ * imports via the re-export barrel in ui/notifications/.
+ */
+
+// --- Types ---
+
+export interface AppNotification {
+  id: string;
+  message: string;
+  type: 'info' | 'warning' | 'success';
+  /** Priority for ordering (higher = shown first). Default: 0 */
+  priority?: number;
+  /** Optional action button displayed alongside the message */
+  action?: {
+    label: string;
+    callback: () => void;
+  };
+  /** Called when the notification is dismissed (manually or via auto-dismiss) */
+  onDismiss?: () => void;
+  /** Auto-dismiss after this many ms. If absent, stays until manually dismissed. */
+  autoDismissMs?: number;
+}
+
+/** Union of allowed notification severity values */
+export type NotificationLevel = AppNotification['type'];
+
+// --- Reactive state ---
+
+let notifications: AppNotification[] = $state([]);
+
+/** Active auto-dismiss timers keyed by notification id (not reactive). */
+// eslint-disable-next-line svelte/prefer-svelte-reactivity -- internal timer bookkeeping
+const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+// --- Internal helpers ---
+
+/** Sort by priority descending (higher priority first) */
+function sorted(list: AppNotification[]): AppNotification[] {
+  return [...list].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
+
+function clearTimer(id: string): void {
+  const timer = timers.get(id);
+  if (timer !== undefined) {
+    clearTimeout(timer);
+    timers.delete(id);
+  }
+}
+
+function startAutoDismiss(notification: AppNotification): void {
+  if (notification.autoDismissMs == null || notification.autoDismissMs <= 0) return;
+  clearTimer(notification.id);
+  timers.set(
+    notification.id,
+    setTimeout(() => {
+      notificationState.dismiss(notification.id);
+    }, notification.autoDismissMs),
+  );
+}
+
+// --- Public API ---
+
+export const notificationState = {
+  /** Add a notification. If one with the same id exists, it is replaced. */
+  push(notification: AppNotification): void {
+    // Replace existing notification with same id
+    const idx = notifications.findIndex((n) => n.id === notification.id);
+    if (idx !== -1) {
+      clearTimer(notification.id);
+      notifications[idx] = notification;
+      // Trigger reactivity by reassigning the array
+      notifications = [...notifications];
+    } else {
+      notifications = [...notifications, notification];
+    }
+    startAutoDismiss(notification);
+  },
+
+  /** Remove a notification by id and invoke its onDismiss callback. */
+  dismiss(id: string): void {
+    const target = notifications.find((n) => n.id === id);
+    if (!target) return;
+    clearTimer(id);
+    notifications = notifications.filter((n) => n.id !== id);
+    target.onDismiss?.();
+  },
+
+  /** Remove all notifications, invoking each onDismiss callback. */
+  dismissAll(): void {
+    const copy = [...notifications];
+    for (const n of copy) {
+      clearTimer(n.id);
+    }
+    notifications = [];
+    for (const n of copy) {
+      n.onDismiss?.();
+    }
+  },
+
+  /** Sorted notification list (highest priority first). Reactive. */
+  get notifications(): AppNotification[] {
+    return sorted(notifications);
+  },
+
+  /** The highest-priority notification, or undefined if empty. Reactive. */
+  get current(): AppNotification | undefined {
+    return sorted(notifications)[0];
+  },
+
+  /** Total number of active notifications. Reactive. */
+  get count(): number {
+    return notifications.length;
+  },
+};

package/src/lib/core/plugin-api.ts

@@ -0,0 +1,210 @@
+/**
+ * Plugin API -- the object passed to each plugin's register() function.
+ *
+ * Provides methods to register commands, tools, panels, exporters, importers,
+ * and shortcuts, plus helpers to dispatch commands and query app state.
+ */
+
+import type { Command } from './commands.js';
+import type { PluginAPI } from './plugin-types.js';
+import {
+  commandRegistry,
+  toolRegistry,
+  panelRegistry,
+  exporterRegistry,
+  importerRegistry,
+  shortcutRegistry,
+  menuRegistry,
+  toolbarRegistry,
+} from './registries.svelte.js';
+import { dispatch as dispatchCommand, onExecute } from './dispatcher.js';
+import { notificationState } from './notification-state.svelte.js';
+import { canvasState } from '../canvas/canvas-state.svelte.js';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import {
+  getCurrentFrame,
+  getFrames as getFramesInternal,
+  addFrame as addFrameInternal,
+  setFrameDuration as setFrameDurationInternal,
+  setCurrentFrame as setCurrentFrameInternal,
+  setGlobalFps as setGlobalFpsInternal,
+  deserialize as deserializeFramesInternal,
+} from '../animation/frame-model.svelte.js';
+import {
+  getLayers,
+  getActiveLayer,
+  addLayer as addLayerInternal,
+  addGroup as addGroupInternal,
+  setVisibility as setVisibilityInternal,
+  setOpacity as setOpacityInternal,
+  deserialize as deserializeLayersInternal,
+} from '../layers/layer-tree.svelte.js';
+import { setProjectPalette as setProjectPaletteInternal } from '../color/palette-state.svelte.js';
+import {
+  hasSelection as selectionHasSelection,
+  getSelectedPixels as selectionGetSelectedPixels,
+} from '../../../plugins/builtin/selection-tool.js';
+
+// Re-export so existing consumers can import PluginAPI from either location
+export type { PluginAPI } from './plugin-types.js';
+
+/**
+ * Create a PluginAPI instance scoped to a specific plugin.
+ * The pluginName is used to namespace registrations and fill command metadata.
+ */
+export function createPluginAPI(pluginName: string): PluginAPI {
+  // Method parameter types are inferred from the PluginAPI return type
+  return {
+    addCommand(name, definition) {
+      // Stamp the plugin name onto the definition so executeOrDispatch() can
+      // construct well-formed Command objects when routing through dispatch().
+      commandRegistry.set(name, { ...definition, _plugin: pluginName });
+    },
+
+    addTool(name, definition) {
+      toolRegistry.set(name, definition);
+    },
+
+    addPanel(name, definition) {
+      panelRegistry.set(name, definition);
+    },
+
+    addExporter(name, definition) {
+      exporterRegistry.set(name, definition);
+    },
+
+    addImporter(name, definition) {
+      importerRegistry.set(name, definition);
+    },
+
+    addShortcut(name, definition) {
+      shortcutRegistry.set(name, definition);
+    },
+
+    addMenuItem(name, contribution) {
+      menuRegistry.set(name, contribution);
+    },
+
+    addToolbarItem(name, contribution) {
+      toolbarRegistry.set(name, contribution);
+    },
+
+    notify(notification) {
+      notificationState.push(notification);
+    },
+
+    dismissNotification(id) {
+      notificationState.dismiss(id);
+    },
+
+    dispatch(partial: Omit<Command, 'id' | 'timestamp'>) {
+      const command: Command = {
+        ...partial,
+        id: crypto.randomUUID(),
+        timestamp: Date.now(),
+      };
+      dispatchCommand(command);
+    },
+
+    onCommand(callback) {
+      return onExecute(callback);
+    },
+
+    getCanvas() {
+      return canvasState;
+    },
+    getProject() {
+      return {
+        name: 'default',
+        width: canvasState.canvasWidth,
+        height: canvasState.canvasHeight,
+      };
+    },
+    getActiveFrame() {
+      return getCurrentFrame();
+    },
+    getActiveLayers() {
+      return { all: getLayers(), active: getActiveLayer() };
+    },
+    getSelection() {
+      // Return a stable object of bound methods so callers can capture it once
+      // at register time; each method invocation reads live selection state.
+      return {
+        hasSelection: selectionHasSelection,
+        getSelectedPixels: selectionGetSelectedPixels,
+      };
+    },
+
+    // --- Mutators ---
+
+    setCanvasSize(width, height) {
+      canvasState.canvasWidth = width;
+      canvasState.canvasHeight = height;
+    },
+
+    addLayer(name, options) {
+      return addLayerInternal(name, options).id;
+    },
+
+    addGroup(name, options) {
+      return addGroupInternal(name, options).id;
+    },
+
+    setLayerVisibility(id, visible) {
+      setVisibilityInternal(id, visible);
+    },
+
+    setLayerOpacity(id, opacity) {
+      setOpacityInternal(id, opacity);
+    },
+
+    deserializeLayers(state) {
+      deserializeLayersInternal(state);
+    },
+
+    addFrame(options) {
+      return addFrameInternal(options).index;
+    },
+
+    getFrames() {
+      return getFramesInternal();
+    },
+
+    setFrameDuration(index, durationMs) {
+      setFrameDurationInternal(index, durationMs);
+    },
+
+    setCurrentFrame(index) {
+      setCurrentFrameInternal(index);
+    },
+
+    setGlobalFps(fps) {
+      setGlobalFpsInternal(fps);
+    },
+
+    deserializeFrames(data) {
+      deserializeFramesInternal(data);
+    },
+
+    createPixelBuffer(width, height) {
+      return new PixelBuffer(width, height);
+    },
+
+    setFramePixelData(frameIndex, layerId, buffer) {
+      // Write pixel data directly into the frame's per-layer map. This is the
+      // single supported way for plugins to populate raw pixels for a given
+      // (frame, layer) pair -- importers rely on this.
+      const frames = getFramesInternal();
+      if (frameIndex < 0 || frameIndex >= frames.length) {
+        throw new Error(`Frame index ${String(frameIndex)} out of range (0..${String(frames.length - 1)}).`);
+      }
+      const frame = frames[frameIndex];
+      if (!frame) throw new Error(`Frame ${String(frameIndex)} missing`);
+      frame.pixelData.set(layerId, buffer);
+    },
+
+    setProjectPalette(palette) {
+      setProjectPaletteInternal(palette);
+    },
+  };
+}