pixelweaver 0.1.0

package/src/lib/shortcuts/default-bindings.ts

@@ -0,0 +1,61 @@
+/**
+ * Default keyboard bindings for PixelWeaver.
+ *
+ * Each entry has a unique name (used for profile export/import and rebinding),
+ * a default key combination, and a human-readable description.
+ *
+ * Key strings use the format: "Ctrl+Shift+Z", "B", etc.
+ * Modifier names: Ctrl, Shift, Alt, Meta.
+ */
+
+export interface DefaultBinding {
+  /** Unique action name, e.g. "tool.pencil" or "edit.undo" */
+  name: string;
+  /** Default key combination */
+  key: string;
+  /** Human-readable description for UI display */
+  description: string;
+}
+
+export const DEFAULT_BINDINGS: DefaultBinding[] = [
+  // -- Tools --
+  { name: 'tool.pencil', key: 'B', description: 'Pencil tool' },
+  { name: 'tool.eraser', key: 'E', description: 'Eraser tool' },
+  { name: 'tool.eyedropper', key: 'I', description: 'Eyedropper tool' },
+  { name: 'tool.fill', key: 'G', description: 'Fill bucket' },
+  { name: 'tool.line', key: 'L', description: 'Line tool' },
+  { name: 'tool.rect', key: 'R', description: 'Rectangle tool' },
+  { name: 'tool.ellipse', key: 'C', description: 'Circle/Ellipse tool' },
+  { name: 'tool.diamond', key: 'D', description: 'Diamond tool' },
+
+  // -- Edit --
+  { name: 'edit.undo', key: 'Ctrl+Z', description: 'Undo' },
+  { name: 'edit.redo', key: 'Ctrl+Shift+Z', description: 'Redo' },
+
+  // -- Colors --
+  { name: 'color.swap', key: 'X', description: 'Swap foreground/background colors' },
+
+  // -- View --
+  { name: 'view.zoom-in', key: '=', description: 'Zoom in' },
+  { name: 'view.zoom-out', key: '-', description: 'Zoom out' },
+  { name: 'view.command-palette', key: 'Ctrl+P', description: 'Command palette' },
+  { name: 'view.toggle-editor-mode', key: 'Ctrl+Tab', description: 'Toggle editor mode' },
+
+  // -- Layers --
+  { name: 'layer.add', key: 'Ctrl+Shift+N', description: 'Add new layer' },
+  { name: 'layer.delete', key: 'Delete', description: 'Delete active layer' },
+  { name: 'layer.duplicate', key: 'Ctrl+J', description: 'Duplicate active layer' },
+  { name: 'layer.merge-down', key: 'Ctrl+E', description: 'Merge layer down' },
+  { name: 'layer.move-up', key: 'Alt+]', description: 'Move layer up' },
+  { name: 'layer.move-down', key: 'Alt+[', description: 'Move layer down' },
+
+  // -- Animation --
+  { name: 'anim.play-pause', key: 'Space', description: 'Play/Pause animation' },
+  { name: 'anim.step-prev', key: ',', description: 'Previous frame' },
+  { name: 'anim.step-next', key: '.', description: 'Next frame' },
+  { name: 'anim.first-frame', key: 'Home', description: 'Go to first frame' },
+  { name: 'anim.last-frame', key: 'End', description: 'Go to last frame' },
+
+  // -- File --
+  { name: 'file.save', key: 'Ctrl+S', description: 'Save project' },
+];

package/src/lib/shortcuts/shortcut-editor-panel-plugin.ts

@@ -0,0 +1,25 @@
+/**
+ * Shortcut Editor Panel plugin -- registers the ShortcutEditorPanel with the
+ * central panel registry so it can be docked alongside other right-side panels.
+ *
+ * Discovery is automatic via the `*-plugin.ts` glob in bootstrap.ts.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import ShortcutEditorPanel from './ShortcutEditorPanel.svelte';
+
+export const shortcutEditorPanelPlugin: PluginModule = {
+  name: 'ui/shortcut-editor',
+  version: '1.0.0',
+  description: 'Searchable table of keyboard shortcuts with rebind support',
+  dependencies: ['builtin/shortcuts'],
+  register(api) {
+    api.addPanel('shortcut-editor', {
+      title: 'Shortcuts',
+      component: ShortcutEditorPanel,
+      position: 'right',
+      minWidth: 220,
+      maxWidth: 420,
+    });
+  },
+};

package/src/lib/shortcuts/shortcut-init.ts

@@ -0,0 +1,380 @@
+/**
+ * Shortcut Initialization -- wires up the ShortcutManager with default bindings
+ * and connects shortcut actions to actual app functions.
+ *
+ * Call initializeShortcuts() once at app startup (e.g., in the root layout).
+ * Call teardownShortcuts() to remove the global listener (e.g., during HMR cleanup).
+ */
+
+import { ShortcutManager, normalizeShortcut } from './shortcut-manager.js';
+import { DEFAULT_BINDINGS } from './default-bindings.js';
+import {
+  getBindings,
+  setBindings,
+  updateBindingKey,
+  setEnabled as setStateEnabled,
+  setActiveTool,
+  type BindingInfo,
+} from './shortcut-state.svelte.js';
+import { toolRegistry, commandRegistry } from '../core/registries.svelte.js';
+import type { CommandDefinition } from '../core/commands.js';
+import type { CommandType, ParamsOf } from '../core/command-params.js';
+import { undoLast, redoLast } from '../core/dispatcher.js';
+import { executeOrDispatch } from '../core/command-runner.js';
+
+// The registry stores CommandDefinition<any> (a type-erasure boundary --
+// see registries.svelte.ts). executeOrDispatch expects the default P, so
+// cast through this helper at the read site.
+type AnyCommand = CommandDefinition;
+import { swapColors } from '../color/color-state.svelte.js';
+import * as layerTree from '../layers/layer-tree.svelte.js';
+import { isInteracting } from '../canvas/input-handler.js';
+import * as animPreview from '../animation/animation-preview.svelte.js';
+import * as frameModel from '../animation/frame-model.svelte.js';
+
+// --- Singleton manager instance ---
+
+let manager: ShortcutManager | null = null;
+let keydownHandler: ((e: KeyboardEvent) => void) | null = null;
+let focusInHandler: ((e: FocusEvent) => void) | null = null;
+let focusOutHandler: ((e: FocusEvent) => void) | null = null;
+
+/** Get the global ShortcutManager instance (null before initialization). */
+export function getShortcutManager(): ShortcutManager | null {
+  return manager;
+}
+
+// --- Action resolvers ---
+// These functions resolve action names to their implementations.
+// Tool shortcuts activate the corresponding tool from the tool registry.
+// Edit, color, and view shortcuts call the app subsystems directly.
+
+function resolveToolAction(toolName: string): () => void {
+  return () => {
+    // Activate the tool via its onActivate callback if registered
+    const tool = toolRegistry.get(toolName);
+    if (tool?.onActivate) {
+      tool.onActivate();
+    }
+    setActiveTool(toolName);
+  };
+}
+
+/**
+ * Dispatch a layer command via executeOrDispatch so undoable commands
+ * go through the dispatcher and non-undoable ones execute directly.
+ */
+// Typed overload: compile-time param validation for known commands
+function dispatchLayerCommand<T extends CommandType>(commandId: T, params: ParamsOf<T>): void;
+// String fallback: for dynamic dispatch where command type is a variable
+function dispatchLayerCommand(commandId: string, params?: Record<string, unknown>): void;
+function dispatchLayerCommand(commandId: string, params: Record<string, unknown> = {}): void {
+  const def = commandRegistry.get(commandId) as AnyCommand | undefined;
+  if (!def) return;
+  executeOrDispatch(commandId, def, params);
+}
+
+/** Map of action name prefixes/patterns to their resolution logic */
+function resolveAction(name: string): (() => void) | null {
+  // Tool shortcuts: "tool.pencil" -> activate tool "pencil"
+  if (name.startsWith('tool.')) {
+    const toolName = name.slice('tool.'.length);
+    return resolveToolAction(toolName);
+  }
+
+  // Edit shortcuts
+  if (name === 'edit.undo') return () => undoLast();
+  if (name === 'edit.redo') return () => redoLast();
+
+  // Color shortcuts
+  if (name === 'color.swap') return () => { swapColors(); };
+
+  // Layer shortcuts: dispatch layer commands through the command system.
+  // Commands that operate on the active layer resolve the ID at invocation
+  // time so the shortcut always targets the current selection.
+  if (name === 'layer.add') {
+    return () => {
+      const count = layerTree.getFlatList().length;
+      dispatchLayerCommand('add_layer', { name: `Layer ${String(count + 1)}` });
+    };
+  }
+  if (name === 'layer.delete') {
+    return () => {
+      const activeId = layerTree.getActiveLayerId();
+      if (!activeId) return;
+      // Prevent deleting the last pixel layer
+      const pixelCount = layerTree.getFlatList().filter((l) => l.type === 'pixel').length;
+      if (pixelCount <= 1) return;
+      dispatchLayerCommand('remove_layer', { id: activeId });
+    };
+  }
+  if (name === 'layer.duplicate') {
+    return () => {
+      const activeId = layerTree.getActiveLayerId();
+      if (!activeId) return;
+      dispatchLayerCommand('duplicate_layer', { id: activeId });
+    };
+  }
+  if (name === 'layer.merge-down') {
+    return () => { dispatchLayerCommand('merge_down', {}); };
+  }
+  if (name === 'layer.move-up') {
+    return () => { dispatchLayerCommand('move_layer_up', {}); };
+  }
+  if (name === 'layer.move-down') {
+    return () => { dispatchLayerCommand('move_layer_down', {}); };
+  }
+
+  // Animation shortcuts
+  // Play/pause is guarded by isInteracting() so Space does not toggle playback
+  // while the user is mid-stroke or panning (Space+click = pan in input-handler).
+  if (name === 'anim.play-pause') {
+    return () => {
+      if (isInteracting()) return;
+      const def = commandRegistry.get('play_animation') as AnyCommand | undefined;
+      if (def) {
+        executeOrDispatch('play_animation', def, {});
+      }
+    };
+  }
+  if (name === 'anim.step-prev') {
+    return () => { animPreview.step(-1); };
+  }
+  if (name === 'anim.step-next') {
+    return () => { animPreview.step(1); };
+  }
+  if (name === 'anim.first-frame') {
+    return () => {
+      const frames = frameModel.getFrames();
+      if (frames.length > 0) frameModel.setCurrentFrame(0);
+    };
+  }
+  if (name === 'anim.last-frame') {
+    return () => {
+      const frames = frameModel.getFrames();
+      if (frames.length > 0) frameModel.setCurrentFrame(frames.length - 1);
+    };
+  }
+
+  // View/file shortcuts -- placeholders that will be connected in later phases
+  if (name === 'view.zoom-in') return () => { /* connected in canvas phase */ };
+  if (name === 'view.zoom-out') return () => { /* connected in canvas phase */ };
+  if (name === 'view.command-palette') return () => { /* connected in UI phase */ };
+  if (name === 'file.save') return () => { /* connected in persistence phase */ };
+
+  // Toggle between Canvas and Level Editor center panels
+  if (name === 'view.toggle-editor-mode') {
+    return () => {
+      const def = commandRegistry.get('toggle_editor_mode') as AnyCommand | undefined;
+      if (def) executeOrDispatch('toggle_editor_mode', def, {});
+    };
+  }
+
+  return null;
+}
+
+// --- Focus tracking ---
+// Disable shortcuts when a text input, textarea, or contenteditable has focus.
+
+const TEXT_INPUT_TYPES = new Set([
+  'text', 'password', 'email', 'number', 'search', 'tel', 'url',
+]);
+
+function isTextInputElement(el: EventTarget | null): boolean {
+  if (!el || !(el instanceof HTMLElement)) return false;
+
+  if (el instanceof HTMLTextAreaElement) return true;
+  if (el.isContentEditable) return true;
+  if (el instanceof HTMLInputElement && TEXT_INPUT_TYPES.has(el.type)) return true;
+
+  return false;
+}
+
+// --- Initialization ---
+
+/**
+ * Initialize the shortcut system: create manager, load default bindings,
+ * attach global listeners, and sync reactive state.
+ */
+export function initializeShortcuts(): ShortcutManager {
+  // Guard against double initialization
+  if (manager) {
+    teardownShortcuts();
+  }
+
+  manager = new ShortcutManager();
+
+  // Load default bindings and resolve actions
+  const bindingInfos: BindingInfo[] = [];
+
+  for (const binding of DEFAULT_BINDINGS) {
+    const action = resolveAction(binding.name);
+    if (action) {
+      manager.bind(binding.key, action, binding.description, binding.name);
+      bindingInfos.push({
+        name: binding.name,
+        key: binding.key,
+        description: binding.description,
+      });
+    }
+  }
+
+  // Sync reactive state
+  setBindings(bindingInfos);
+
+  // Capture the non-null manager in closure so handlers don't need to re-check
+  // the module-level variable (which is typed as nullable).
+  const activeManager = manager;
+
+  // Attach global keydown listener
+  keydownHandler = (event: KeyboardEvent) => {
+    activeManager.handleKeyDown(event);
+  };
+  window.addEventListener('keydown', keydownHandler);
+
+  // Attach focus tracking to auto-disable shortcuts in text inputs
+  focusInHandler = (event: FocusEvent) => {
+    if (isTextInputElement(event.target)) {
+      activeManager.setEnabled(false);
+      setStateEnabled(false);
+    }
+  };
+
+  focusOutHandler = (event: FocusEvent) => {
+    if (isTextInputElement(event.target)) {
+      activeManager.setEnabled(true);
+      setStateEnabled(true);
+    }
+  };
+
+  window.addEventListener('focusin', focusInHandler);
+  window.addEventListener('focusout', focusOutHandler);
+
+  return manager;
+}
+
+// --- Rebinding / reset helpers ---
+
+/**
+ * Result of attempting a rebind. On success, the manager and reactive state
+ * have been updated. On conflict, the caller receives the conflicting action
+ * name so it can offer a swap.
+ */
+export interface RebindResult {
+  ok: boolean;
+  /** Name of the already-bound action that owns the requested key, if any. */
+  conflictName?: string;
+  /** Description of the conflicting action, for UI display. */
+  conflictDescription?: string;
+  /** Reason for failure when not a conflict (e.g. manager missing). */
+  reason?: string;
+}
+
+/**
+ * Rebind a named action to a new key combination.
+ * Keeps the ShortcutManager and the reactive state module in sync.
+ *
+ * If `newKey` is already bound to a different action, returns a conflict
+ * without mutating anything. Callers that want to swap must call
+ * `rebindShortcut` twice (once to clear the other action, once to set this).
+ */
+export function rebindShortcut(name: string, newKey: string): RebindResult {
+  if (!manager) return { ok: false, reason: 'shortcut-manager-not-initialized' };
+
+  const currentBinding = getBindings().get(name);
+  if (!currentBinding) return { ok: false, reason: 'unknown-action' };
+
+  const normalizedNew = normalizeShortcut(newKey);
+  const normalizedCurrent = normalizeShortcut(currentBinding.key);
+
+  // No-op: already bound to that key
+  if (normalizedNew === normalizedCurrent) return { ok: true };
+
+  // Check for conflict with a different action
+  const existingShortcutName = findBindingNameForKey(normalizedNew);
+  if (existingShortcutName && existingShortcutName !== name) {
+    const conflicting = getBindings().get(existingShortcutName);
+    return {
+      ok: false,
+      conflictName: existingShortcutName,
+      conflictDescription: conflicting?.description ?? '',
+    };
+  }
+
+  // Apply the rebind to manager and reactive state
+  manager.rebind(currentBinding.key, newKey);
+  updateBindingKey(name, newKey);
+  return { ok: true };
+}
+
+/**
+ * Unbind a named action entirely (used as a building block for swap flows
+ * in the shortcut editor -- strip the incumbent before assigning the new key).
+ */
+export function clearShortcut(name: string): void {
+  if (!manager) return;
+  const current = getBindings().get(name);
+  if (!current) return;
+  manager.unbind(current.key);
+  updateBindingKey(name, '');
+}
+
+/**
+ * Reset a single binding back to the default key shipped in DEFAULT_BINDINGS.
+ * If the default collides with another action's current key, the other action
+ * is cleared so the default can be restored cleanly.
+ */
+export function resetShortcutToDefault(name: string): void {
+  if (!manager) return;
+  const defaultBinding = DEFAULT_BINDINGS.find((b) => b.name === name);
+  if (!defaultBinding) return;
+
+  // Clear any other action currently occupying the default key
+  const occupant = findBindingNameForKey(normalizeShortcut(defaultBinding.key));
+  if (occupant && occupant !== name) {
+    clearShortcut(occupant);
+  }
+
+  const current = getBindings().get(name);
+  if (current && current.key) {
+    manager.rebind(current.key, defaultBinding.key);
+  } else {
+    // Previously cleared -- re-bind from scratch using the resolved action
+    const action = resolveAction(name);
+    if (action) {
+      manager.bind(defaultBinding.key, action, defaultBinding.description, name);
+    }
+  }
+  updateBindingKey(name, defaultBinding.key);
+}
+
+/** Lookup the action name currently bound to a normalized key, if any. */
+function findBindingNameForKey(normalizedKey: string): string | undefined {
+  for (const [actionName, info] of getBindings()) {
+    if (info.key && normalizeShortcut(info.key) === normalizedKey) {
+      return actionName;
+    }
+  }
+  return undefined;
+}
+
+/** Remove all global listeners and reset the manager. */
+export function teardownShortcuts(): void {
+  if (keydownHandler) {
+    window.removeEventListener('keydown', keydownHandler);
+    keydownHandler = null;
+  }
+  if (focusInHandler) {
+    window.removeEventListener('focusin', focusInHandler);
+    focusInHandler = null;
+  }
+  if (focusOutHandler) {
+    window.removeEventListener('focusout', focusOutHandler);
+    focusOutHandler = null;
+  }
+
+  if (manager) {
+    manager.reset();
+    manager = null;
+  }
+}