pixelweaver 0.1.0

package/src/lib/core/command-params.ts

@@ -0,0 +1,20 @@
+/**
+ * Typed command dispatch infrastructure.
+ *
+ * CommandParamsMap is a global interface populated via module augmentation
+ * in command-params.generated.ts. Each command ID maps to its params shape.
+ *
+ * The string fallback overload allows dynamic dispatch (import_spec replay,
+ * layout_* dynamic commands, makeStrokeTool factory).
+ */
+
+// Re-export the generated augmentations so they're visible to the compiler.
+// The generated file uses `declare global { interface CommandParamsMap { ... } }`
+// which takes effect when this module is imported.
+import './command-params.generated.js';
+
+/** All statically-known command type strings. */
+export type CommandType = keyof CommandParamsMap;
+
+/** Look up the params type for a given command type. */
+export type ParamsOf<T extends CommandType> = CommandParamsMap[T];

package/src/lib/core/command-runner.ts

@@ -0,0 +1,79 @@
+/**
+ * Command runner -- shared helper for UI entry points (menu bar, toolbars,
+ * command palette, context menus, tab-add menu).
+ *
+ * Decides whether a command should be executed directly or routed through
+ * the dispatcher (so it is recorded in the undo stack) based on the
+ * `undoable` flag on its CommandDefinition.
+ *
+ * This lives in its own module to avoid a circular import between
+ * commands.ts and dispatcher.ts.
+ */
+
+import type { Command, CommandContext, CommandDefinition } from './commands.js';
+import type { CommandType, ParamsOf } from './command-params.js';
+import { dispatch } from './dispatcher.js';
+import { commandRegistry } from './registries.svelte.js';
+
+/**
+ * Look up a command by id and return it typed against the default P
+ * (Record<string, unknown>). The registry stores CommandDefinition<any>
+ * as a type-erasure boundary (heterogeneous P per command), and this
+ * helper is the narrowing seam for UI dispatch call sites so they
+ * don't leak `any` into no-unsafe-argument.
+ */
+export function getCommandForDispatch(
+  id: string,
+): CommandDefinition | undefined {
+  // Safe narrowing: the registry holds CommandDefinition<any> as a
+  // type-erasure seam; cast through unknown here so the narrow call
+  // sites see the default-P CommandDefinition they expect.
+  const def = commandRegistry.get(id);
+  return def as unknown as CommandDefinition | undefined;
+}
+
+/**
+ * Execute a command from a UI entry point. If `definition.undoable === true`,
+ * the command is routed through dispatch() (so it enters the undo stack);
+ * otherwise, execute() is called directly with the provided params and
+ * context.
+ *
+ * When routing through dispatch(), the plugin name is read from
+ * `definition._plugin` (populated by PluginAPI.addCommand). If unset, a
+ * placeholder is used so the Command is still well-formed.
+ */
+// Typed overload: compile-time param validation for known commands
+export function executeOrDispatch<T extends CommandType>(
+  name: T,
+  definition: CommandDefinition,
+  params?: ParamsOf<T>,
+  ctx?: CommandContext,
+): void;
+// String fallback: for dynamic dispatch (import_spec replay, etc.)
+export function executeOrDispatch(
+  name: string,
+  definition: CommandDefinition,
+  params?: Record<string, unknown>,
+  ctx?: CommandContext,
+): void;
+// Implementation
+export function executeOrDispatch(
+  name: string,
+  definition: CommandDefinition,
+  params: Record<string, unknown> = {},
+  ctx: CommandContext = {},
+): void {
+  if (definition.undoable) {
+    const command: Command = {
+      type: name,
+      plugin: definition._plugin ?? '_ui',
+      version: '1.0.0',
+      params,
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+    dispatch(command);
+  } else {
+    definition.execute(params, ctx);
+  }
+}

package/src/lib/core/commands.ts

@@ -0,0 +1,134 @@
+/**
+ * Core command types for the PixelWeaver command system.
+ *
+ * Every user action that modifies state flows through commands.
+ * Commands are dispatched, executed, recorded for undo, logged semantically,
+ * and serialized for spec export.
+ */
+
+import type { PixelBuffer } from '../canvas/pixel-buffer.js';
+
+// --- Command instance (a specific invocation) ---
+
+export interface Command<P extends Record<string, unknown> = Record<string, unknown>> {
+  type: string; // e.g. "draw_pixel", "add_layer"
+  plugin: string; // e.g. "builtin/pencil", "builtin/layers"
+  version: string; // plugin version for future migration
+  params: P;
+  timestamp: number; // Date.now()
+  id: string; // crypto.randomUUID()
+}
+
+// --- Undo tier ---
+
+/**
+ * Two-tier undo classification:
+ * - 'frame': drawing operations (pixel modifications within a frame/layer)
+ * - 'project': structural operations (add/delete layer, reorder, color changes, etc.)
+ */
+export type UndoTier = 'frame' | 'project';
+
+// --- Undo entry (wraps a command with tier, parent pointer, and snapshot) ---
+
+/**
+ * A single entry in the undo/redo stack. Wraps the command with its tier
+ * classification, a parent pointer for future branching (Phase 4), the
+ * command definition for direct undo/redo access, and the snapshot data
+ * captured from execute() for restoring state on undo.
+ */
+export interface UndoEntry {
+  command: Command;
+  definition: CommandDefinition;
+  tier: UndoTier;
+  id: string; // unique ID for this entry (matches command.id for simplicity)
+  parentId: string | null; // ID of the previous undo entry (for future branching)
+  snapshot?: unknown; // data returned by execute(), passed to undo() for state restoration
+}
+
+// --- Command definition (registered by plugins) ---
+
+export interface CommandDefinition<P extends object = Record<string, unknown>> {
+  /** Execute the command; return value (if any) is stored as snapshot for undo */
+  execute: (params: P, context: CommandContext) => unknown;
+  /** Undo the command; receives the snapshot returned by execute() */
+  undo: (params: P, context: CommandContext, snapshot?: unknown) => void;
+  /** Returns a human-readable description, e.g. "Drew pixel at (3,7)" */
+  describe: (params: P) => string;
+  /** Which undo tier this command belongs to. Defaults to 'frame' if omitted. */
+  tier?: UndoTier;
+  /**
+   * If true, UI entry points (menu, toolbar, palette) will route this command
+   * through dispatch() so it is recorded in the undo stack. Defaults to false.
+   * Commands with no meaningful undo logic should leave this unset.
+   */
+  undoable?: boolean;
+  // UI metadata for menus and command palette
+  /** Human-readable label for menus (e.g. "Blur", "Add Layer") */
+  label?: string;
+  /** Category for command palette grouping (e.g. "Effects", "Layer", "File") */
+  category?: string;
+  /** Default keyboard shortcut (e.g. "Ctrl+Shift+B"). Informational only. */
+  defaultShortcut?: string;
+  /** Icon for menus, toolbars, and command palette. Svelte component or icon name string. */
+  icon?: string | import('svelte').Component;
+  /**
+   * The plugin name that registered this command. Set automatically by
+   * PluginAPI.addCommand(); do NOT set manually. Used by executeOrDispatch()
+   * to construct Command objects when routing through the dispatcher.
+   */
+  _plugin?: string;
+}
+
+/**
+ * CommandContext gives commands access to canvas, layers, etc.
+ * The getActiveBuffer method is the primary interface for pixel-modifying commands.
+ *
+ * setActiveBuffer lets effects that change buffer dimensions (rotate 90/270 on
+ * non-square canvases, scale) replace the active layer's pixel data with a
+ * new buffer. The implementation is responsible for updating canvas size and
+ * the active frame/layer's pixel data. Effects must snapshot the old width,
+ * height, and pixel data themselves for undo.
+ *
+ * getActiveLayerId/getActiveFrameIndex let effects capture WHICH layer and
+ * frame they operated on at execute() time, so undo can restore into the
+ * original layer/frame even if the user has switched the active layer/frame
+ * in the meantime. Use setBufferForLayer to write a buffer into a specific
+ * (frame, layer) pair -- mirrors setActiveBuffer but targets an explicit
+ * pair instead of whatever is active right now.
+ */
+export interface CommandContext {
+  getActiveBuffer?: () => PixelBuffer | null;
+  setActiveBuffer?: (buffer: PixelBuffer) => void;
+  getActiveLayerId?: () => string | null;
+  getActiveFrameIndex?: () => number;
+  /**
+   * Write a buffer into a specific (frameIndex, layerId) pair. Resizes the
+   * canvas to match the new buffer dimensions (the last write wins if
+   * multiple pairs are updated -- callers doing whole-canvas ops should
+   * ensure every pair ends up with matching dims).
+   */
+  setBufferForLayer?: (frameIndex: number, layerId: string, buffer: PixelBuffer) => void;
+  /**
+   * Enumerate every (frameIndex, layerId, buffer) triple across the project.
+   * Used by whole-canvas effects (rotate_canvas, scale_canvas) to iterate
+   * all frames and layers consistently. Only includes pixel layers that
+   * actually have a buffer in the given frame.
+   */
+  getAllFrameLayerBuffers?: () => Array<{ frameIndex: number; layerId: string; buffer: PixelBuffer }>;
+  /**
+   * Set canvas dimensions explicitly. Used by whole-canvas effects after
+   * they finish writing all per-layer buffers, so the canvas size only
+   * changes once (setBufferForLayer updates it per-write, but a
+   * whole-canvas op needs a single authoritative final size).
+   */
+  setCanvasSize?: (width: number, height: number) => void;
+  [key: string]: unknown;
+}
+
+// --- Semantic log entry ---
+
+export interface SemanticLogEntry {
+  description: string;
+  timestamp: number;
+  commandId: string;
+}