pixelweaver 0.1.0

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

@@ -0,0 +1,286 @@
+/**
+ * Type definitions for plugin-registered extensions: tools, panels, exporters,
+ * importers, and shortcuts. Separated from plugin-api.ts to avoid circular
+ * imports -- registries.ts needs these types but should not depend on the API.
+ */
+
+import type { Command, CommandDefinition } from './commands.js';
+import type { CommandType, ParamsOf } from './command-params.js';
+import type { AppNotification } from './notification-state.svelte.js';
+import type { PixelBuffer } from '../canvas/pixel-buffer.js';
+import type { LayerTreeState } from '../layers/layer-types.js';
+import type { Frame, FramesSerialized } from '../animation/frame-model.svelte.js';
+import type { Palette } from '../color/palette.js';
+
+// --- Plugin API interface ---
+// Defined here (not in plugin-api.ts) so that ToolContext can reference it
+// without creating a circular import: plugin-api.ts imports from this file.
+
+export interface PluginAPI {
+  addCommand<T extends CommandType>(name: T, definition: CommandDefinition<ParamsOf<T>>): void;
+  addCommand<P extends object = Record<string, unknown>>(name: string, definition: CommandDefinition<P>): void;
+  addTool(name: string, definition: ToolDefinition): void;
+  addPanel(name: string, definition: PanelConfig): void;
+  addExporter(name: string, definition: ExporterDefinition): void;
+  addImporter(name: string, definition: ImporterDefinition): void;
+  addShortcut(name: string, definition: ShortcutDefinition): void;
+  addMenuItem(name: string, contribution: MenuContribution): void;
+  addToolbarItem(name: string, contribution: ToolbarContribution): void;
+
+  /** Push a notification into the banner system */
+  notify(notification: AppNotification): void;
+  /** Dismiss a notification by id */
+  dismissNotification(id: string): void;
+
+  /** Dispatch a command (id and timestamp are auto-filled) */
+  dispatch<T extends CommandType>(command: Omit<Command, 'id' | 'timestamp'> & { type: T; params: ParamsOf<T> }): void;
+  dispatch(command: Omit<Command, 'id' | 'timestamp'>): void;
+
+  /** Listen to all executed commands */
+  onCommand(callback: (command: Command) => void): () => void;
+
+  // Getters -- return placeholders until real systems are connected
+  getCanvas(): unknown;
+  getProject(): unknown;
+  getActiveFrame(): unknown;
+  getActiveLayers(): unknown;
+  /**
+   * Read-only view of the current pixel selection. The returned object is
+   * stable (safe to capture once at register time); its methods read live
+   * state on each call.
+   */
+  getSelection(): {
+    hasSelection(): boolean;
+    getSelectedPixels(): ReadonlySet<string>;
+  };
+
+  // --- Mutators (used by importers and project-loading plugins) ---
+
+  /** Set the canvas pixel dimensions. Values are clamped to the [MIN_CANVAS_SIZE, MAX_CANVAS_SIZE] range. */
+  setCanvasSize(width: number, height: number): void;
+
+  /** Add a new pixel layer to the tree. Returns the new layer's id. */
+  addLayer(name: string, options?: { parentId?: string; index?: number; id?: string }): string;
+
+  /** Add a new group layer to the tree. Returns the new group's id. */
+  addGroup(name: string, options?: { parentId?: string; index?: number; id?: string }): string;
+
+  /** Set a layer's visibility flag. */
+  setLayerVisibility(id: string, visible: boolean): void;
+
+  /** Set a layer's opacity (0-100). */
+  setLayerOpacity(id: string, opacity: number): void;
+
+  /** Replace the entire layer tree with the given serialized state. */
+  deserializeLayers(state: LayerTreeState): void;
+
+  /** Append a new frame. Returns the new frame's index. */
+  addFrame(options?: { afterIndex?: number; duplicate?: boolean }): number;
+
+  /** Read-only access to the current frame list. */
+  getFrames(): Frame[];
+
+  /** Set a frame's per-frame duration override (or null to use global FPS). */
+  setFrameDuration(index: number, durationMs: number | null): void;
+
+  /** Make `index` the current frame. */
+  setCurrentFrame(index: number): void;
+
+  /** Set the global animation FPS (1..120). */
+  setGlobalFps(fps: number): void;
+
+  /** Replace all animation state with the given serialized data. */
+  deserializeFrames(data: FramesSerialized): void;
+
+  /** Factory for a blank RGBA pixel buffer. */
+  createPixelBuffer(width: number, height: number): PixelBuffer;
+
+  /** Write pixel data for a specific layer in a specific frame. */
+  setFramePixelData(frameIndex: number, layerId: string, buffer: PixelBuffer): void;
+
+  /** Set the project palette (or clear it by passing null). */
+  setProjectPalette(palette: Palette | null): void;
+}
+
+// --- Tool ---
+
+export interface ToolContext {
+  canvasX: number; // pixel coordinate on the canvas
+  canvasY: number;
+  pressure: number; // 0-1, from Pointer Events API
+  color: string; // current foreground color
+  api: PluginAPI;
+}
+
+/** A declarative toggle option rendered as a single sub-button in the toolbar. */
+export interface ToolOptionToggle {
+  /** Unique id within the tool, e.g. 'filled' */
+  id: string;
+  /** Human-readable label shown in tooltip */
+  label: string;
+  /** Icon shown on the sub-button (Svelte component or text) */
+  icon?: string | import('svelte').Component;
+  /** Option type */
+  type: 'toggle';
+  /** Default value when the tool is first activated */
+  defaultValue: boolean;
+}
+
+/** A declarative select option rendered as a row of choice buttons in the toolbar. */
+export interface ToolOptionSelect {
+  /** Unique id within the tool, e.g. 'size' */
+  id: string;
+  /** Human-readable label shown in tooltip */
+  label: string;
+  /** Option type */
+  type: 'select';
+  /** Available choices the user can pick from */
+  choices: { value: number; label: string }[];
+  /** Default value when the tool is first activated */
+  defaultValue: number;
+}
+
+/** A declarative option that a tool exposes (rendered as sub-buttons in the toolbar). */
+export type ToolOption = ToolOptionToggle | ToolOptionSelect;
+
+export interface ToolDefinition {
+  icon: string | import('svelte').Component; // text label or Svelte icon component
+  cursor: string; // CSS cursor value, e.g. "crosshair"
+  onPointerDown?: (e: PointerEvent, ctx: ToolContext) => void;
+  onPointerMove?: (e: PointerEvent, ctx: ToolContext) => void;
+  onPointerUp?: (e: PointerEvent, ctx: ToolContext) => void;
+  onActivate?: () => void;
+  onDeactivate?: () => void;
+  /** Declarative options rendered as sub-buttons in the toolbar */
+  options?: ToolOption[];
+  /** Svelte component for tool-specific options (placeholder type for now) */
+  optionsPanel?: unknown;
+}
+
+// --- Panel ---
+
+export interface PanelConfig {
+  /** Display title shown in the panel header / dock tab */
+  title: string;
+  /** Svelte component to render inside the panel (props passed via `props` field) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- props are passed dynamically at mount time
+  component: import('svelte').Component<any>;
+  /** Props to pass to the component */
+  props?: Record<string, unknown>;
+  /** Default dock position */
+  position?: 'left' | 'right' | 'bottom' | 'top' | 'center';
+  /** Minimum width in px (for side panels) */
+  minWidth?: number;
+  /** Minimum height in px (for bottom panels) */
+  minHeight?: number;
+  /** Maximum width in px (for side panels) */
+  maxWidth?: number;
+  /** Maximum height in px (for bottom panels) */
+  maxHeight?: number;
+  /** Whether this panel can be closed. Default: true */
+  closeable?: boolean;
+}
+
+// --- Exporter ---
+
+export interface ExporterDefinition {
+  /** Human-readable label, e.g. "PNG Image" */
+  label: string;
+  /** File extension, e.g. "png" */
+  extension: string;
+  /** MIME type, e.g. "image/png" */
+  mimeType: string;
+  /** Performs the export and returns the result as a Blob or Uint8Array */
+  export: (context: ExportContext) => Promise<Blob | Uint8Array>;
+}
+
+export interface ExportContext {
+  /** Placeholder -- will contain canvas data, frame selection, etc. */
+  [key: string]: unknown;
+}
+
+// --- Importer ---
+
+export interface ImporterDefinition {
+  /** Human-readable label, e.g. "PNG Image" */
+  label: string;
+  /** File extensions this importer handles, e.g. ["png", "jpg"] */
+  extensions: string[];
+  /** Performs the import from a File or ArrayBuffer */
+  import: (data: File | ArrayBuffer, context: ImportContext) => Promise<void>;
+}
+
+export interface ImportContext {
+  /** Placeholder -- will contain project handle, etc. */
+  [key: string]: unknown;
+}
+
+// --- Shortcut ---
+
+export interface ShortcutDefinition {
+  /** Key combination, e.g. "Ctrl+Z", "B", "Shift+X" */
+  key: string;
+  /** Human-readable description for the shortcut list */
+  description: string;
+  /** Callback when the shortcut is triggered */
+  action: () => void;
+}
+
+// --- Menu contribution ---
+
+export interface MenuContribution {
+  /** ID of the command to execute (must be registered in commandRegistry) */
+  commandId: string;
+  /**
+   * Slash-separated menu path. First segment = top-level menu, rest = submenus.
+   * Examples: "effects", "file/import", "layer", "context/canvas"
+   */
+  menuPath: string;
+  /** Grouping within the menu. Items in the same group are together, separated by dividers. */
+  group: string;
+  /** Sort order within the group (lower = earlier). Default: 100. */
+  order: number;
+  /** Human-readable label override. If omitted, uses CommandDefinition.label or the commandId. */
+  label?: string;
+  /** Conditional visibility. Return false to hide the item. */
+  when?: () => boolean;
+  /** Conditional enabled state. Return false to disable/gray out. */
+  enabled?: () => boolean;
+}
+
+// --- Toolbar contribution ---
+
+/** Discriminator for toolbar item kinds */
+export type ToolbarItemKind = 'tool' | 'command' | 'separator' | 'widget';
+
+/** A plugin-declared item for a toolbar */
+export interface ToolbarContribution {
+  /** Which toolbar this item belongs to (e.g. 'drawing-tools', 'view-controls') */
+  toolbarId: string;
+  /** What kind of item this is */
+  kind: ToolbarItemKind;
+  /** Tool name or command name (not needed for separator/widget) */
+  targetId?: string;
+  /** Grouping bucket -- items in the same group are together, separators between groups */
+  group: string;
+  /** Sort position within the group (lower = earlier) */
+  order: number;
+  /** Override label */
+  label?: string;
+  /** Override icon (falls back to command/tool icon) */
+  icon?: string | import('svelte').Component;
+  /** Svelte component for kind: 'widget' */
+  widget?: import('svelte').Component;
+}
+
+/** Per-toolbar configuration */
+export interface ToolbarConfig {
+  /** Unique toolbar ID */
+  id: string;
+  /** Display title for the dock tab */
+  title: string;
+  /** Icon dimensions in px */
+  iconSize: number;
+  /** Whether user can close this toolbar. Default: true */
+  closeable?: boolean;
+}

package/src/lib/core/registries.svelte.ts

@@ -0,0 +1,74 @@
+/**
+ * Central registries for all plugin-registered extensions.
+ *
+ * Each registry is a reactive Map (using Svelte 5 $state) so that UI
+ * components can reactively list registered tools, panels, etc.
+ *
+ * Module-level singletons -- one set of registries per app instance.
+ */
+
+import { SvelteMap } from 'svelte/reactivity';
+import type { CommandDefinition } from './commands.js';
+import type {
+  ToolDefinition,
+  PanelConfig,
+  ExporterDefinition,
+  ImporterDefinition,
+  ShortcutDefinition,
+  MenuContribution,
+  ToolbarContribution,
+} from './plugin-types.js';
+
+// --- Reactive registry factory ---
+
+/**
+ * Creates a reactive registry backed by SvelteMap.
+ * SvelteMap is inherently reactive in Svelte 5 -- mutations automatically
+ * trigger re-renders in any component that reads from the map.
+ */
+function createRegistry<T>(): ReactiveRegistry<T> {
+  const entries = new SvelteMap<string, T>();
+
+  return {
+    get(name: string): T | undefined {
+      return entries.get(name);
+    },
+    set(name: string, value: T): void {
+      entries.set(name, value);
+    },
+    has(name: string): boolean {
+      return entries.has(name);
+    },
+    delete(name: string): boolean {
+      return entries.delete(name);
+    },
+    /** Returns the underlying map for read-only iteration */
+    getAll(): ReadonlyMap<string, T> {
+      return entries;
+    },
+    get size(): number {
+      return entries.size;
+    },
+  };
+}
+
+export interface ReactiveRegistry<T> {
+  get(name: string): T | undefined;
+  set(name: string, value: T): void;
+  has(name: string): boolean;
+  delete(name: string): boolean;
+  getAll(): ReadonlyMap<string, T>;
+  readonly size: number;
+}
+
+// --- Singleton registries ---
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- type-erasure boundary: registry stores heterogeneous CommandDefinition<P> values
+export const commandRegistry = createRegistry<CommandDefinition<any>>();
+export const toolRegistry = createRegistry<ToolDefinition>();
+export const panelRegistry = createRegistry<PanelConfig>();
+export const exporterRegistry = createRegistry<ExporterDefinition>();
+export const importerRegistry = createRegistry<ImporterDefinition>();
+export const shortcutRegistry = createRegistry<ShortcutDefinition>();
+export const menuRegistry = createRegistry<MenuContribution>();
+export const toolbarRegistry = createRegistry<ToolbarContribution>();

package/src/lib/core/tool-options-state.svelte.ts

@@ -0,0 +1,61 @@
+/**
+ * Reactive state for tool option values.
+ *
+ * Tracks per-tool option values (e.g. filled toggle for shape tools).
+ * Values persist across tool switches within a session -- switching away
+ * from a tool and back preserves the user's choices.
+ *
+ * Module-level singleton using Svelte 5 $state via SvelteMap.
+ */
+
+import { SvelteMap } from 'svelte/reactivity';
+import { toolRegistry } from './registries.svelte.js';
+
+/** Supported option value types: boolean for toggles, number for selects. */
+export type ToolOptionValue = boolean | number;
+
+/**
+ * Nested map: toolName -> optionId -> current value.
+ * Outer SvelteMap is reactive so toolbar UI updates when tools change.
+ * Inner SvelteMap is reactive so sub-buttons update when toggled.
+ */
+const optionValues = new SvelteMap<string, SvelteMap<string, ToolOptionValue>>();
+
+/**
+ * Ensure a tool's options are initialized with defaults (idempotent).
+ * Called when a tool becomes active or when reading its options.
+ */
+function ensureDefaults(toolName: string): SvelteMap<string, ToolOptionValue> {
+  let toolOpts = optionValues.get(toolName);
+  if (toolOpts) return toolOpts;
+
+  toolOpts = new SvelteMap<string, ToolOptionValue>();
+  const def = toolRegistry.get(toolName);
+  if (def?.options) {
+    for (const opt of def.options) {
+      toolOpts.set(opt.id, opt.defaultValue);
+    }
+  }
+  optionValues.set(toolName, toolOpts);
+  return toolOpts;
+}
+
+/** Get the current value of a tool option. Returns the default if not yet set. */
+export function getToolOptionValue(toolName: string, optionId: string): ToolOptionValue {
+  const toolOpts = ensureDefaults(toolName);
+  return toolOpts.get(optionId) ?? false;
+}
+
+/** Set the value of a tool option (e.g. when the user clicks a toggle or picks a select choice). */
+export function setToolOptionValue(toolName: string, optionId: string, value: ToolOptionValue): void {
+  const toolOpts = ensureDefaults(toolName);
+  toolOpts.set(optionId, value);
+}
+
+/** Toggle a boolean tool option and return the new value. */
+export function toggleToolOption(toolName: string, optionId: string): boolean {
+  const current = getToolOptionValue(toolName, optionId);
+  const next = !current;
+  setToolOptionValue(toolName, optionId, next);
+  return next;
+}