pixelweaver 0.1.0

package/todo/.done/audit-implementation-plan.md

@@ -0,0 +1,1235 @@
+# PixelWeaver Audit -- Implementation Plan
+
+This document transforms the 10 design decisions from `audit-design-decisions.md` into
+a concrete, step-by-step execution plan. Each item includes exact file paths, function
+names, interface modifications, and line-level references to the current codebase.
+
+---
+
+## Table of Contents
+
+- [I-01: makeStrokeTool Factory (old #24)](#i-01-makestroketool-factory)
+- [I-02: makeSnapshotUndo Factory (old #25)](#i-02-makesnapshotundo-factory)
+- [I-03: Generic Command\<P\>, Typed CommandContext, Separate Snapshot (old #20+#23)](#i-03-generic-commandp-typed-commandcontext-separate-snapshot)
+- [I-04: Undoable Flag on CommandDefinition (old #1)](#i-04-undoable-flag-on-commanddefinition)
+- [I-05: Native \<dialog\> for Modals (old #22)](#i-05-native-dialog-for-modals)
+- [I-06: Reusable PromptDialog Component (old #26)](#i-06-reusable-promptdialog-component)
+- [I-07: God File Split (old #14)](#i-07-god-file-split)
+- [I-08: Add getSelection() to PluginAPI (old #12)](#i-08-add-getselection-to-pluginapi)
+- [I-09: Add Mutator Methods to PluginAPI (old #13)](#i-09-add-mutator-methods-to-pluginapi)
+- [I-10: Enable Strict TypeScript Flags (old #19)](#i-10-enable-strict-typescript-flags)
+- [Internal Consistency Check](#internal-consistency-check)
+
+---
+
+## Re-indexed Items in Implementation Order
+
+| New Index | Old # | Title |
+|-----------|-------|-------|
+| I-01 | #24 | makeStrokeTool factory |
+| I-02 | #25 | makeSnapshotUndo factory |
+| I-03 | #20+#23 | Generic Command\<P\>, typed CommandContext, separate snapshot |
+| I-04 | #1 | Undoable flag on CommandDefinition |
+| I-05 | #22 | Native \<dialog\> for modals |
+| I-06 | #26 | Reusable PromptDialog component |
+| I-07 | #14 | God file split (8 domain files + 3 utilities) |
+| I-08 | #12 | Add getSelection() to PluginAPI |
+| I-09 | #13 | Add mutator methods to PluginAPI |
+| I-10 | #19 | Enable strict TypeScript flags |
+
+---
+
+## I-01: makeStrokeTool Factory
+
+### Summary
+
+`pencil-tool.ts` (128 lines) and `eraser-tool.ts` (123 lines) are structurally
+identical. They differ only in command name, description verb, pixel color resolution,
+icon, and toolbar order. Both maintain identical stroke state (`drawing`, `lastX`,
+`lastY`, `strokePixels`, `strokeLayerId`), identical `onPointerDown`/`onPointerMove`/
+`onPointerUp` handlers with Bresenham interpolation, and identical command
+`execute`/`undo`/`describe` definitions using the `_snapshot` pattern. A factory
+function will eliminate this duplication and make it trivial to add future stroke-based
+tools (e.g., pixel-perfect pencil, tinted eraser).
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `plugins/builtin/make-stroke-tool.ts` | Create | New factory function `makeStrokeTool(config: StrokeToolConfig): PluginModule` containing the shared command definition (execute/undo/describe), stroke state management, pointer handlers, and toolbar registration |
+| `plugins/builtin/pencil-tool.ts` | Modify | Reduce from ~128 lines to ~20 lines. Remove all inline command definition, stroke state, and pointer handlers. Import `makeStrokeTool` and call it with config: `{ pluginName: 'builtin/pencil', commandName: 'draw_pixels', toolId: 'pencil', icon: PencilIcon, toolbarOrder: 10, toolbarGroup: 'draw', describeVerb: 'Drew', resolveColor: (ctx) => hexToRgba(ctx.color) }` |
+| `plugins/builtin/eraser-tool.ts` | Modify | Reduce from ~123 lines to ~20 lines. Same transformation as pencil. Config: `{ pluginName: 'builtin/eraser', commandName: 'erase_pixels', toolId: 'eraser', icon: EraserIcon, toolbarOrder: 20, toolbarGroup: 'draw', describeVerb: 'Erased', resolveColor: () => ({ r: 0, g: 0, b: 0, a: 0 }) }` |
+
+### Step-by-Step Instructions
+
+- Define the `StrokeToolConfig` interface in `make-stroke-tool.ts`:
+  - `pluginName: string` -- used in `Command.plugin` field (e.g., `'builtin/pencil'`)
+  - `commandName: string` -- used in `api.addCommand(name, ...)` (e.g., `'draw_pixels'`)
+  - `toolId: string` -- used in `api.addTool(name, ...)` (e.g., `'pencil'`)
+  - `icon: string | Component` -- the Svelte icon component
+  - `toolbarOrder: number` -- the `order` field in `ToolbarContribution`
+  - `toolbarGroup: string` -- the `group` field in `ToolbarContribution`
+  - `describeVerb: string` -- used in `describe()` like `"${verb} ${n} pixel(s)"`
+  - `resolveColor: (ctx: ToolContext) => { r: number; g: number; b: number; a: number }` -- returns RGBA for each stroke pixel
+- Import shared dependencies from `drawing-utils.ts`: `bresenhamLine`, `snapshotPixels`, `applyPixels`; import types `PluginModule` from `plugin-loader.js`, `PixelBuffer` from `pixel-buffer.ts`, `PixelData` from `drawing-utils.ts`, `ToolContext` from `plugin-types.js`
+- Implement `makeStrokeTool(config)` returning a `PluginModule`:
+  - The `register(api)` function body is extracted from the current `pencil-tool.ts` lines 23-127
+  - Command definition (lines 23-53 of pencil-tool.ts): `execute` uses `snapshotPixels` + `applyPixels`, `undo` restores snapshot, `describe` returns `"${config.describeVerb} ${pixels.length} pixel(s)"`
+  - Stroke state variables (lines 56-61): `drawing`, `lastX`, `lastY`, `strokePixels`, `strokeColor`, `strokeLayerId`
+  - Tool definition (lines 71-126): `onPointerDown` calls `config.resolveColor(ctx)` instead of hardcoded `hexToRgba(strokeColor)` or `{r:0,g:0,b:0,a:0}`, `onPointerMove` uses bresenham interpolation with resolved color, `onPointerUp` dispatches the command using `config.commandName` and `config.pluginName`
+  - Toolbar registration uses `config.toolId`, `config.toolbarGroup`, `config.toolbarOrder`
+- In `pencil-tool.ts`, replace the entire body with:
+  - Import `makeStrokeTool` from `./make-stroke-tool.js`
+  - Import `hexToRgba` from `./drawing-utils.js`
+  - Import `PencilIcon` from `~icons/lucide/pencil`
+  - Export `pencilToolPlugin = makeStrokeTool({ ... })`
+- In `eraser-tool.ts`, same pattern but with eraser-specific config
+- Handle `strokeColor` capturing: in pencil, `resolveColor` receives the `ToolContext` on each call, so it can read `ctx.color` at pointer-down time. The factory should call `resolveColor(ctx)` in `onPointerDown` and cache the result for the duration of the stroke (the current pencil does this with `strokeColor = ctx.color` on line 79)
+
+### Preconditions
+
+- None. This is fully independent.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- Draw with pencil: pixels appear in foreground color
+- Draw with eraser: pixels become transparent (r=0,g=0,b=0,a=0)
+- Undo pencil stroke: pixels revert to pre-stroke state
+- Undo eraser stroke: pixels revert to pre-erase state
+- Both tools appear in the drawing-tools toolbar at their correct positions (pencil order=10, eraser order=20)
+- Both tools display correct icons
+- `grep -r "let drawing = false" plugins/builtin/` returns only `make-stroke-tool.ts` (no duplication)
+
+### Risks and Edge Cases
+
+- The factory must capture `resolveColor(ctx)` once at `onPointerDown` and reuse the cached RGBA for the entire stroke, matching current pencil behavior (line 79: `strokeColor = ctx.color`). If `resolveColor` is called per-pixel in `onPointerMove`, the eraser will work fine (constant output) but the pencil could produce mixed colors if the user changes foreground color mid-stroke.
+- The `pattern-stamp-tool.ts` should NOT use this factory; it has fundamentally different data flow (pattern buffers, tiling modes). Verify it remains unchanged.
+- The `_snapshot` convention is still used here. I-02 (makeSnapshotUndo) and I-03 (Generic Command) will update this later.
+
+---
+
+## I-02: makeSnapshotUndo Factory
+
+### Summary
+
+32 out of 33 undo handlers across plugin files are byte-for-byte identical: get the
+active buffer from context, bail if missing, apply snapshot pixels. This factory
+extracts the pattern into a single reusable function in `drawing-utils.ts`. The single
+exception (`move_selection` in `selection-tool.ts`) has custom undo logic and remains
+manual. After I-03 changes the snapshot architecture (separate slot on UndoEntry), this
+factory's signature will be updated, but it can be built now against the current
+`_snapshot`-in-params pattern.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `plugins/builtin/drawing-utils.ts` | Modify | Add `makeSnapshotUndo()` function after the existing `applyPixels` function (after line 399). Returns `(params: Record<string, unknown>, ctx: CommandContext) => void` |
+| `plugins/builtin/make-stroke-tool.ts` | Modify | Import and use `makeSnapshotUndo()` as the `undo` handler in the command definition (created in I-01) |
+| `plugins/builtin/pencil-tool.ts` | Modify | If not already using factory from I-01, replace inline undo handler. If using I-01 factory, no change needed here |
+| `plugins/builtin/eraser-tool.ts` | Modify | Same as pencil-tool.ts |
+| `plugins/builtin/rect-tool.ts` | Modify | Replace lines 56-60 (undo handler) with `undo: makeSnapshotUndo()` |
+| `plugins/builtin/circle-tool.ts` | Modify | Replace inline undo handler with `makeSnapshotUndo()` |
+| `plugins/builtin/line-tool.ts` | Modify | Replace inline undo handler with `makeSnapshotUndo()` |
+| `plugins/builtin/diamond-tool.ts` | Modify | Replace inline undo handler with `makeSnapshotUndo()` |
+| `plugins/builtin/fill-tool.ts` | Modify | Replace lines 41-46 (undo handler) with `undo: makeSnapshotUndo()` |
+| `plugins/builtin/advanced-fill-tool.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/noise-tool.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/gradient-tool.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/dither-tool.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/pattern-stamp-tool.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/drawing-primitives-plugin.ts` | Modify | Replace 6 inline undo handlers (one per primitive command) |
+| `plugins/builtin/effects/blur.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/sharpen.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/glow.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/shadow.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/scale.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/flip.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/outline.ts` | Modify | Replace inline undo handler |
+| `plugins/builtin/effects/color-effects.ts` | Modify | Replace 5 inline undo handlers |
+| `plugins/builtin/effects/rotate.ts` | Modify | Replace inline undo handler |
+
+### Step-by-Step Instructions
+
+- In `plugins/builtin/drawing-utils.ts`, after `applyPixels` (line 399), add:
+  ```
+  export function makeSnapshotUndo(): (params: Record<string, unknown>, ctx: Record<string, unknown>) => void {
+    return (params, ctx) => {
+      const buffer = (ctx as { getActiveBuffer?: () => PixelBuffer }).getActiveBuffer?.();
+      if (!buffer) return;
+      const snapshot = params._snapshot as PixelData[];
+      applyPixels(buffer, snapshot);
+    };
+  }
+  ```
+  - Note: The `ctx` cast pattern `(ctx as { getActiveBuffer?: () => PixelBuffer })` matches the current pattern used in all 32 call sites. This will be cleaned up in I-03 when `CommandContext` gets a proper `getActiveBuffer` definition.
+- For each of the 23 files listed above, perform the following mechanical replacement:
+  - Add `makeSnapshotUndo` to the import from `./drawing-utils.js` (or `../../plugins/builtin/drawing-utils.js` for files under `src/`)
+  - Replace the inline `undo(params, ctx) { ... }` block with `undo: makeSnapshotUndo(),`
+  - The replaced block always follows this exact 4-line pattern:
+    ```
+    undo(params, ctx) {
+      const buffer = (ctx as { getActiveBuffer?: () => PixelBuffer }).getActiveBuffer?.();
+      if (!buffer) return;
+      const snapshot = params._snapshot as PixelData[];
+      applyPixels(buffer, snapshot);
+    },
+    ```
+- Verify that `selection-tool.ts` `move_selection` undo handler is NOT touched (it has custom logic: restoring selected pixel positions, not just pixel colors)
+- If I-01 has been completed, update `make-stroke-tool.ts` to use `makeSnapshotUndo()` in its command definition instead of the inline handler
+
+### Preconditions
+
+- None strictly required. Ideally done after I-01 so the stroke tool factory can benefit immediately.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- All 39 tests pass (run `npx vitest run`)
+- Undo/redo works for every drawing tool: pencil, eraser, rect, circle, line, diamond, fill, advanced fill, noise, gradient, dither, pattern stamp
+- Undo/redo works for all effects: blur, sharpen, glow, shadow, scale, flip, outline, rotate, and all color effects (brightness, contrast, hue shift, saturation, invert colors)
+- Undo for `move_selection` still works (untouched)
+- `grep -rn "const buffer = (ctx as" plugins/builtin/ | grep -v "make-stroke-tool\|drawing-utils\|selection-tool" | grep undo` returns 0 results (all inline undo handlers eliminated except the factory definition and the selection exception)
+
+### Risks and Edge Cases
+
+- The `drawing-primitives-plugin.ts` has 6 commands (`draw_line_prim`, `draw_rect_prim`, etc.) sharing the same file. Each needs its `undo` replaced individually. Count them carefully during implementation.
+- The `color-effects.ts` has 5 commands (`brightness`, `contrast`, `hue_shift`, `saturation`, `invert_colors`). Same careful counting applies.
+- When I-03 moves `_snapshot` out of `params` into a dedicated `UndoEntry.snapshot` slot, this factory will need updating. The update is mechanical: change from `params._snapshot` to a `snapshot` argument. This is a known forward dependency.
+
+---
+
+## I-03: Generic Command\<P\>, Typed CommandContext, Separate Snapshot
+
+### Summary
+
+This is the most impactful single change. It addresses three sub-problems: (A) untyped
+`Command.params` (currently `Record<string, unknown>`) forcing ~170 `params.field as Type`
+casts, (B) the `_snapshot` field smuggled into `params` as a mutable side-channel
+(used in 21+ files), and (C) untyped `CommandContext` lacking `getActiveBuffer`,
+causing 73 `(ctx as { getActiveBuffer?: ... })` casts across 24 plugin files.
+After this change, each plugin defines a typed params interface, the snapshot lives on
+the undo stack entry, and `CommandContext.getActiveBuffer` is properly typed.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/core/commands.ts` | Modify | Make `Command<P = Record<string, unknown>>` generic (line 11); make `CommandDefinition<P = Record<string, unknown>>` generic (line 44); `execute` returns `unknown` (snapshot data) instead of `void`; `undo` takes a third `snapshot: unknown` argument; add `getActiveBuffer` to `CommandContext` interface (line 67) |
+| `src/lib/core/dispatcher.ts` | Modify | Capture `execute()` return value as snapshot data (line 118); store `snapshot` field on `UndoEntry` (add to interface around line 35); pass snapshot to `undo()` call (line 165); pass snapshot to `redo()` re-execution |
+| `src/lib/core/registries.svelte.ts` | Modify | Change `commandRegistry` type from `ReactiveRegistry<CommandDefinition>` to `ReactiveRegistry<CommandDefinition<any>>` (line 66). This is the type-erasure boundary. |
+| `src/lib/core/plugin-types.ts` | Modify | Update `PluginAPI.addCommand` signature: `addCommand<P>(name: string, definition: CommandDefinition<P>): void` (line 15) |
+| `src/lib/core/plugin-api.ts` | Modify | Update `addCommand` implementation to accept `CommandDefinition<any>` for the registry `.set()` call; import `PixelBuffer` and wire `getActiveBuffer` into the `context` object |
+| `plugins/builtin/drawing-utils.ts` | Modify | Update `makeSnapshotUndo` (from I-02) to accept `snapshot: unknown` as third param instead of reading `params._snapshot`; remove `PixelData[]` cast from params, cast from snapshot instead |
+| All 23 tool/effect plugin files | Modify | Define typed params interfaces (e.g., `DrawPixelsParams`, `DrawRectParams`, `FloodFillParams`); remove all `params.field as Type` casts; remove `_snapshot: []` from dispatch params; change `execute` to return snapshot data instead of mutating params; change `undo` to accept third `snapshot` arg; remove `(ctx as { getActiveBuffer? })` casts |
+| `src/lib/canvas/canvas-init-plugin.ts` | Modify | Remove the manual ctx cast for `getActiveBuffer`; it will now be a first-class `CommandContext` method |
+| Test files: `tool-plugins.test.ts`, `effects.test.ts`, `gradient.test.ts`, etc. | Modify | Update mock `CommandContext` objects to include `getActiveBuffer`; update test dispatch calls to not include `_snapshot` in params |
+
+### Step-by-Step Instructions
+
+- **Step 1: Update `commands.ts` (lines 11-68)**
+  - Make `Command` generic: `export interface Command<P = Record<string, unknown>>` with `params: P` instead of `params: Record<string, unknown>`
+  - Make `CommandDefinition` generic: `export interface CommandDefinition<P = Record<string, unknown>>`
+  - Change `execute` signature from `(params: Record<string, unknown>, context: CommandContext) => void` to `(params: P, context: CommandContext) => unknown | void`
+  - Change `undo` signature from `(params: Record<string, unknown>, context: CommandContext) => void` to `(params: P, context: CommandContext, snapshot: unknown) => void`
+  - Change `describe` signature from `(params: Record<string, unknown>) => string` to `(params: P) => string`
+  - Add to `CommandContext` interface (currently empty index signature at line 67):
+    ```
+    getActiveBuffer?: () => PixelBuffer | null;
+    ```
+  - Import `PixelBuffer` type: `import type { PixelBuffer } from '../canvas/pixel-buffer.js';`
+
+- **Step 2: Update `UndoEntry` in `commands.ts` (line 35)**
+  - Add `snapshot: unknown;` field to the `UndoEntry` interface
+
+- **Step 3: Update `dispatcher.ts`**
+  - In `dispatch()` (line 118): capture execute return value: `const snapshot = definition.execute(command.params, context);`
+  - In the `UndoEntry` construction (lines 121-126): add `snapshot` field: `snapshot,`
+  - In `undoLast()` (line 165): pass snapshot: `definition.undo(entry.command.params, context, entry.snapshot);`
+  - In `redoLast()` (line 185): capture new snapshot from re-execution: `const newSnapshot = definition.execute(entry.command.params, context);` and update: `entry.snapshot = newSnapshot;`
+
+- **Step 4: Update `registries.svelte.ts` (line 66)**
+  - Change `createRegistry<CommandDefinition>()` to `createRegistry<CommandDefinition<any>>()`
+  - Update the import to use the generic type
+
+- **Step 5: Update `plugin-types.ts` (line 15)**
+  - Change `addCommand(name: string, definition: CommandDefinition): void` to `addCommand<P>(name: string, definition: CommandDefinition<P>): void`
+
+- **Step 6: Wire `getActiveBuffer` into `CommandContext`**
+  - In `plugin-api.ts` or `canvas-init-plugin.ts`, ensure the dispatcher context includes `getActiveBuffer`. Currently `canvas-init-plugin.ts` sets this on the context; verify it uses the proper interface method name.
+
+- **Step 7: Define param interfaces and update plugins (23 files)**
+  - For each plugin file, define a params interface at the top. Example for `rect-tool.ts`:
+    ```
+    interface DrawRectParams {
+      x: number;
+      y: number;
+      w: number;
+      h: number;
+      filled: boolean;
+      color: string;
+      layerId: string;
+    }
+    ```
+  - Change `execute(params, ctx)` to `execute(params: DrawRectParams, ctx)` and remove all `as` casts
+  - Change `execute` to return snapshot data: `return snapshotPixels(buffer, points);` instead of `params._snapshot = snapshotPixels(buffer, points);`
+  - Change `undo(params, ctx)` to `undo(params: DrawRectParams, ctx, snapshot)` and use `snapshot as PixelData[]` instead of `params._snapshot as PixelData[]`
+  - Remove `_snapshot: []` from all `api.dispatch()` calls (e.g., rect-tool.ts line 120)
+  - Remove `(ctx as { getActiveBuffer?: () => PixelBuffer })` casts; use `ctx.getActiveBuffer?.()` directly
+
+- **Step 8: Update `makeSnapshotUndo` (from I-02)**
+  - Change signature to accept `snapshot: unknown` as third argument:
+    ```
+    export function makeSnapshotUndo(): (params: unknown, ctx: CommandContext, snapshot: unknown) => void {
+      return (_params, ctx, snapshot) => {
+        const buffer = ctx.getActiveBuffer?.();
+        if (!buffer) return;
+        applyPixels(buffer, snapshot as PixelData[]);
+      };
+    }
+    ```
+
+- **Step 9: Update test files**
+  - All test mocks that create a `CommandContext` need `getActiveBuffer` added
+  - All test dispatch calls need `_snapshot` removed from params
+  - Mock `getActiveBuffer` should return a test `PixelBuffer` instance
+
+### Preconditions
+
+- I-01 and I-02 should be completed first (they create `make-stroke-tool.ts` and `makeSnapshotUndo`, which both need updating here). However, I-03 can be done independently if the implementor is willing to handle the duplication in pencil/eraser at the same time.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes with zero errors
+- All tests pass (`npx vitest run`)
+- `grep -rn "params\.\w\+ as " plugins/builtin/` returns 0 results (all param casts eliminated)
+- `grep -rn "(ctx as {" plugins/builtin/` returns 0 results (all context casts eliminated)
+- `grep -rn "_snapshot" plugins/builtin/` returns 0 results (snapshot no longer stored in params)
+- Undo/redo works correctly for all tools and effects
+- The dispatcher correctly captures snapshot from `execute()` and passes it to `undo()`
+
+### Risks and Edge Cases
+
+- **Redo snapshot freshness:** When redoing, the re-execution of `execute()` must return a fresh snapshot (the buffer state has changed since the original execution). The plan handles this by capturing `newSnapshot` in `redoLast()`.
+- **Type erasure boundary:** The `commandRegistry` stores `CommandDefinition<any>`. This means the registry itself does not enforce param types. Type safety exists at the plugin registration boundary (each plugin's `register()` function) and at dispatch time (the `Command` object carries typed params). This is acceptable and standard for heterogeneous registries.
+- **Incremental migration:** All 23 plugin files must be updated atomically because the `execute` return type and `undo` signature change globally. A partial migration would cause type errors. Consider doing the dispatcher + commands.ts change first (backward compatible with `void` return from execute), then migrating plugins file by file.
+- **`_snapshot` on first-execute guard:** Currently, plugins check `if (!(params._snapshot as PixelData[])?.length)` to avoid re-snapshotting on redo. With the separate snapshot slot, this guard is unnecessary -- on first execute, snapshot is `undefined`; on redo, the dispatcher manages it. But the `execute` function must always return a snapshot, even on redo. Verify the snapshot is taken before pixels are modified (current order: snapshot first, then applyPixels).
+
+---
+
+## I-04: Undoable Flag on CommandDefinition
+
+### Summary
+
+All 4 UI entry points (menu-builder.ts line 66, ToolbarPanel.svelte line 184,
+ContextMenu.svelte line 49, command-palette-state.svelte.ts line 54) call
+`cmd.execute({}, {})` directly, bypassing the dispatcher. This means destructive
+commands triggered from the menu (flatten_image, resize_canvas, merge_down, cut, paste)
+never enter the undo stack. Adding an `undoable` flag to `CommandDefinition` lets each
+UI entry point check the flag and route through `dispatch()` for commands that need
+undo tracking.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/core/commands.ts` | Modify | Add `undoable?: boolean` to `CommandDefinition` interface (after `tier?` on line 50) |
+| `src/lib/ui/menu-builder.ts` | Modify | In `buildMenuItem` (line 55), change `action` from `cmd.execute({}, {})` to a conditional: if `cmd.undoable`, dispatch through the dispatcher; otherwise, call `execute` directly |
+| `src/lib/ui/ToolbarPanel.svelte` | Modify | In `executeCommand` function (line 182), add the same conditional routing |
+| `src/lib/ui/ContextMenu.svelte` | Modify | In the action handler (line 49), add the same conditional routing |
+| `src/lib/ui/command-palette/command-palette-state.svelte.ts` | Modify | In the execute callback (line 54), add the same conditional routing |
+| `src/lib/ui/menu-commands-plugin.ts` (or split successors after I-07) | Modify | Mark ~15 destructive commands with `undoable: true`: `flatten_image`, `resize_canvas`, `crop_to_selection`, `merge_down`, `cut`, `paste`, `select_all`, `invert_selection`, `select_by_color` |
+
+### Step-by-Step Instructions
+
+- **Step 1: Add field to `commands.ts`**
+  - After the `tier?: UndoTier` field (line 50), add:
+    ```
+    /** Whether this command should be routed through the dispatcher (undo stack) when triggered from UI. Default: false. */
+    undoable?: boolean;
+    ```
+
+- **Step 2: Create a shared dispatch helper**
+  - To avoid repeating the routing logic in 4 places, create a helper function in a new module or in `dispatcher.ts`:
+    ```
+    export function executeOrDispatch(commandId: string): void {
+      const def = commandRegistry.get(commandId);
+      if (!def) return;
+      if (def.undoable) {
+        dispatch({
+          type: commandId,
+          plugin: 'ui',
+          version: '1.0.0',
+          params: {},
+          id: crypto.randomUUID(),
+          timestamp: Date.now(),
+        });
+      } else {
+        def.execute({} as any, {} as any);
+      }
+    }
+    ```
+  - Alternatively, add this to `dispatcher.ts` since it already has access to `commandRegistry` and `dispatch`. Place it after `redoLast()` (line 204).
+
+- **Step 3: Update menu-builder.ts (line 66)**
+  - Change: `action: cmd ? () => cmd.execute({}, {}) : undefined,`
+  - To: `action: cmd ? () => executeOrDispatch(contrib.commandId) : undefined,`
+  - Import `executeOrDispatch` from `../core/dispatcher.js`
+
+- **Step 4: Update ToolbarPanel.svelte (line 184)**
+  - Change: `cmd?.execute({}, {});`
+  - To: `if (targetId) executeOrDispatch(targetId);`
+  - Import `executeOrDispatch`
+
+- **Step 5: Update ContextMenu.svelte (line 49)**
+  - Change: `cmd.execute({}, {})`
+  - To: `executeOrDispatch(item.commandId)` (or however the command ID is referenced)
+
+- **Step 6: Update command-palette-state.svelte.ts (line 54)**
+  - Change: `execute: () => def.execute({}, {}),`
+  - To: `execute: () => executeOrDispatch(commandId),`
+  - Import `executeOrDispatch`
+
+- **Step 7: Mark destructive commands as undoable**
+  - In `menu-commands-plugin.ts` (or its split successors), add `undoable: true` to the command definitions for:
+    - `flatten_image`
+    - `resize_canvas`
+    - `crop_to_selection`
+    - `merge_down`
+    - `cut`
+    - `paste`
+    - `select_all`
+    - `invert_selection`
+    - `select_by_color`
+  - Do NOT mark as undoable:
+    - `undo` / `redo` (would cause infinite recursion)
+    - View/zoom commands (non-destructive)
+    - Dialog-opening commands (`new_project_dialog`, `export_dialog`, `open_file_dialog`)
+    - `about`, `keyboard_shortcuts`, `report_bug`
+
+### Preconditions
+
+- I-03 should be completed first so that `CommandDefinition` is already generic and the `execute`/`undo` signatures are correct. The `executeOrDispatch` helper needs to construct a properly typed `Command` object.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- Trigger `flatten_image` from the Image menu: it appears on the undo stack; Ctrl+Z undoes it
+- Trigger `zoom_in` from the View menu: it does NOT appear on the undo stack
+- Trigger `undo` from the Edit menu: it calls `undoLast()` directly, does not recurse
+- The command palette's execute callbacks respect the `undoable` flag
+- Context menu actions respect the `undoable` flag
+
+### Risks and Edge Cases
+
+- **`undo`/`redo` recursion:** These commands must NEVER be marked `undoable: true`. The `executeOrDispatch` helper would dispatch them, which would push them onto the undo stack, and undoing them would call undo again. Add a runtime guard in `executeOrDispatch` that throws if `commandId === 'undo' || commandId === 'redo'` and `undoable` is true.
+- **Params for undoable menu commands:** Some undoable commands need params (e.g., `resize_canvas` needs width/height from the prompt). Currently they call `execute({}, {})` with empty params because they gather input internally. After I-03, these commands will have typed params. The `executeOrDispatch` helper passes `{}` as params, which works for commands that gather their own input but breaks for commands that expect typed params. This is acceptable for now because all current menu-triggered destructive commands handle their own input gathering inside `execute()`.
+- **Future work:** Eventually, commands like `resize_canvas` should be refactored so that the dialog gathers input and passes it as typed params to `dispatch()`. This is outside the scope of I-04.
+
+---
+
+## I-05: Native \<dialog\> for Modals
+
+### Summary
+
+All 3 modal dialogs (`NewProjectDialog.svelte`, `ExportDialog.svelte`,
+`AboutDialog.svelte`) plus `CommandPalette.svelte` use manual `<div class="modal-overlay">`
+or `<div class="about-backdrop">` patterns. These lack focus traps, proper ARIA
+attributes, and consistent Escape handling (AboutDialog has no Escape handler at all).
+Replacing with the native `<dialog>` element and `.showModal()` provides free focus
+trapping, `::backdrop` pseudo-element, `aria-modal="true"`, Escape-to-close, and
+top-layer rendering. Tauri's Chromium WebView fully supports `<dialog>`.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/ui/NewProjectDialog.svelte` | Modify | Replace `<div class="modal-overlay">` (line 117) with `<dialog>` element; add `bind:this` for dialog ref; use `$effect` to call `.showModal()` / `.close()` based on `open` prop; replace `.modal-overlay` CSS with `dialog::backdrop`; remove manual Escape handler (lines 48-53) and `<svelte:window>` binding (line 203) since `<dialog>` handles Escape natively; remove `<!-- svelte-ignore a11y_no_static_element_interactions -->` comment (line 115) |
+| `src/lib/ui/ExportDialog.svelte` | Modify | Same transformation as NewProjectDialog |
+| `src/lib/ui/AboutDialog.svelte` | Modify | Replace `<div class="about-backdrop">` (line 8 in template) with `<dialog>`; add Escape support (currently missing); add `bind:this` + `$effect` for showModal/close; restyle with `dialog::backdrop` |
+| `src/lib/ui/command-palette/CommandPalette.svelte` | Modify | Replace the overlay `<div>` with `<dialog>`; the existing Escape handler (line 20-22) can delegate to the `close` event; add `bind:this` + `$effect` |
+| `src/lib/ui/dialog-state.svelte.ts` | Modify | No changes strictly needed (dialog refs are local to each component, not global state). However, if `.showModal()` needs to be called externally, add optional `HTMLDialogElement` ref storage. |
+| `src/app.css` (or relevant global CSS) | Modify | Add base `dialog` and `dialog::backdrop` styles using design tokens. Remove any `.modal-overlay` global styles if they exist. |
+
+### Step-by-Step Instructions
+
+- **Step 1: Establish the `<dialog>` pattern**
+  - The pattern for each dialog component is:
+    ```svelte
+    <script>
+      let dialogEl: HTMLDialogElement | undefined = $state();
+
+      $effect(() => {
+        if (!dialogEl) return;
+        if (open) {
+          dialogEl.showModal();
+        } else {
+          dialogEl.close();
+        }
+      });
+
+      function handleClose() {
+        // Native <dialog> fires 'close' event on Escape and on .close()
+        onClose();
+      }
+    </script>
+
+    <dialog bind:this={dialogEl} onclose={handleClose}>
+      <!-- dialog content -->
+    </dialog>
+    ```
+
+- **Step 2: Convert NewProjectDialog.svelte**
+  - Add `let dialogEl: HTMLDialogElement | undefined = $state();` to the script block
+  - Add the `$effect` for showModal/close (see pattern above)
+  - Replace lines 116-201 (the `{#if open}` block containing `<div class="modal-overlay">`) with a `<dialog bind:this={dialogEl}>` containing the `.modal` div content directly
+  - Remove the `{#if open}` guard -- the `<dialog>` element is always in the DOM; visibility is controlled by `.showModal()` / `.close()`
+  - Remove the `handleKeydown` function (lines 48-53) and the `<svelte:window>` binding (line 203)
+  - Remove the `onclick={onClose}` on the overlay div (replace with backdrop click handling via `dialogEl.addEventListener('click', ...)` that checks if click target is the dialog itself, indicating a backdrop click)
+  - Replace `.modal-overlay` CSS (lines 206-217) with:
+    ```css
+    dialog::backdrop {
+      background: rgba(0, 0, 0, 0.5);
+    }
+    dialog {
+      border: none;
+      padding: 0;
+      background: transparent;
+      max-width: 90vw;
+    }
+    ```
+  - Keep the `.modal` class CSS for the inner content box
+
+- **Step 3: Convert ExportDialog.svelte**
+  - Same transformation as NewProjectDialog. Examine the first 30 lines; it has the same `Props` interface with `open` and `onClose`.
+
+- **Step 4: Convert AboutDialog.svelte**
+  - Currently uses `<div class="about-backdrop">` with no `open` prop -- it is mounted/unmounted by `menu-commands-plugin.ts` using Svelte's `mount`/`unmount` API
+  - Two options:
+    - Option A: Add an `open` prop and use the same `<dialog>` pattern
+    - Option B: Keep mount/unmount but have `onMount` call `.showModal()`
+  - Option B is simpler since it preserves the existing mount/unmount flow in `menu-commands-plugin.ts`. Add:
+    ```svelte
+    import { onMount } from 'svelte';
+    let dialogEl: HTMLDialogElement;
+    onMount(() => dialogEl.showModal());
+    ```
+  - Replace `<div class="about-backdrop">` with `<dialog bind:this={dialogEl}>`
+  - Add `onclose={onClose}` to the `<dialog>` element for Escape handling
+
+- **Step 5: Convert CommandPalette.svelte**
+  - Currently uses `commandPaletteState.isOpen` to conditionally render
+  - Add `dialogEl` ref and `$effect` like the pattern above, keyed on `commandPaletteState.isOpen`
+  - The existing Escape handler (line 20-22) can be simplified: instead of manually checking `e.key === 'Escape'`, rely on the native `<dialog>` close event. But keep the ArrowDown/ArrowUp/Enter handlers.
+
+- **Step 6: Handle backdrop clicks**
+  - Native `<dialog>` does not close on backdrop click by default. Add a click handler:
+    ```svelte
+    function handleDialogClick(e: MouseEvent) {
+      if (e.target === dialogEl) onClose();
+    }
+    ```
+  - This works because clicking the `::backdrop` pseudo-element fires the click on the `<dialog>` element itself, not on any child.
+
+### Preconditions
+
+- None. This is fully independent of the command system changes.
+
+### Postconditions / Verification
+
+- Tab key stays within each dialog (focus trap works natively)
+- Escape closes each dialog (including AboutDialog, which currently lacks this)
+- Backdrop click closes each dialog
+- Screen readers announce `role="dialog"` and `aria-modal="true"` (provided automatically by `<dialog>`)
+- No `z-index: 1000` hacks remain in dialog CSS (top-layer handles stacking)
+- No `<!-- svelte-ignore a11y_no_static_element_interactions -->` comments remain in dialog components
+- Dialogs render correctly in Tauri desktop build (test on macOS and Linux if possible)
+- `tsc --noEmit` passes
+
+### Risks and Edge Cases
+
+- **Tauri WebView compatibility:** Chromium-based WebView supports `<dialog>` fully. Test the `::backdrop` styling in Tauri specifically, as some older WebView versions may not render `::backdrop` with CSS custom properties.
+- **Double-close guard:** If `onClose()` sets `open = false` and the `$effect` calls `.close()`, but `.close()` fires the `close` event which calls `onClose()` again, there could be a loop. Guard against this by checking `dialogEl.open` before calling `.close()` in the effect.
+- **Focus restoration:** When a `<dialog>` is closed, the browser restores focus to the element that was focused before `.showModal()`. Verify this works correctly with the dockview panel system.
+- **CommandPalette auto-focus:** The CommandPalette currently uses a `$effect` with `queueMicrotask` to focus the input (line 15). With `<dialog>`, the browser auto-focuses the first focusable element inside the dialog. Adding `autofocus` attribute to the input element may be sufficient, eliminating the manual focus code.
+
+---
+
+## I-06: Reusable PromptDialog Component
+
+### Summary
+
+Two `window.prompt()` calls exist in `menu-commands-plugin.ts`: one for `resize_canvas`
+(line 382) and one for `set_frame_duration_dialog` (line 669). `window.prompt()` fails
+silently on macOS in Tauri (returns null without showing) and is unreliable on Linux.
+This item creates a generic `PromptDialog.svelte` component using native `<dialog>`
+(from I-05) and wires it through `dialogState` so any command can open a themed,
+validatable prompt.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/ui/PromptDialog.svelte` | Create | New Svelte component: native `<dialog>`, text input, validation error display, confirm/cancel buttons, all themed with design tokens |
+| `src/lib/ui/dialog-state.svelte.ts` | Modify | Add prompt state: `promptOpen` boolean, `promptConfig` object with `title`, `message`, `defaultValue`, `validate`, `onConfirm`, `onCancel` fields; add `openPrompt(config)` and `closePrompt()` methods |
+| `src/App.svelte` | Modify | Import and render `<PromptDialog>` alongside existing dialogs (after line 29); bind to `dialogState.promptOpen` and `dialogState.promptConfig` |
+| `src/lib/ui/menu-commands-plugin.ts` (or split successors) | Modify | Replace `prompt()` call on line 382 (resize_canvas) with `dialogState.openPrompt({...})`. Replace `prompt()` call on line 669 (set_frame_duration_dialog) with `dialogState.openPrompt({...})` |
+
+### Step-by-Step Instructions
+
+- **Step 1: Extend dialog-state.svelte.ts**
+  - Define a `PromptConfig` interface:
+    ```
+    export interface PromptConfig {
+      title: string;
+      message: string;
+      defaultValue: string;
+      validate?: (value: string) => string | null; // returns error message or null
+      onConfirm: (value: string) => void;
+      onCancel?: () => void;
+    }
+    ```
+  - Add reactive state:
+    ```
+    let promptOpen = $state(false);
+    let promptConfig = $state<PromptConfig | null>(null);
+    ```
+  - Add methods to `dialogState`:
+    ```
+    get promptOpen() { return promptOpen; },
+    get promptConfig() { return promptConfig; },
+
+    openPrompt(config: PromptConfig) {
+      promptConfig = config;
+      promptOpen = true;
+    },
+    closePrompt() {
+      promptOpen = false;
+      promptConfig = null;
+    },
+    ```
+
+- **Step 2: Create PromptDialog.svelte**
+  - Props: `open: boolean`, `config: PromptConfig | null`, `onClose: () => void`
+  - Local state: `inputValue` (initialized from `config.defaultValue`), `errorMessage: string`
+  - Use `<dialog>` with `bind:this` + `$effect` for showModal/close (same pattern as I-05)
+  - Template structure:
+    - `<h2>` with `config.title`
+    - `<p>` with `config.message`
+    - `<input>` bound to `inputValue`, with `autofocus`
+    - Error display `<p class="error">` shown when `errorMessage` is non-empty
+    - Cancel and Confirm buttons
+  - On confirm: call `config.validate(inputValue)` if provided; if validation fails, set `errorMessage`; if passes, call `config.onConfirm(inputValue)` and close
+  - On cancel: call `config.onCancel?.()` and close
+  - Style with design tokens (--bg-panel, --border, --accent, etc.)
+
+- **Step 3: Wire into App.svelte**
+  - Import `PromptDialog` from `./lib/ui/PromptDialog.svelte`
+  - Add after line 29:
+    ```svelte
+    <PromptDialog
+      open={dialogState.promptOpen}
+      config={dialogState.promptConfig}
+      onClose={() => dialogState.closePrompt()}
+    />
+    ```
+
+- **Step 4: Replace prompt() calls in menu-commands-plugin.ts**
+  - For `resize_canvas` (line 382):
+    ```
+    dialogState.openPrompt({
+      title: 'Resize Canvas',
+      message: 'Enter new canvas size (WxH):',
+      defaultValue: `${canvasState.canvasWidth}x${canvasState.canvasHeight}`,
+      validate: (v) => {
+        const match = v.match(/^\s*(\d+)\s*[xX]\s*(\d+)\s*$/);
+        if (!match) return 'Format must be WxH (e.g., 64x64)';
+        const w = parseInt(match[1], 10);
+        const h = parseInt(match[2], 10);
+        if (w < 1 || w > 4096 || h < 1 || h > 4096) return 'Dimensions must be 1-4096';
+        return null;
+      },
+      onConfirm: (value) => {
+        const match = value.match(/^\s*(\d+)\s*[xX]\s*(\d+)\s*$/)!;
+        const newW = parseInt(match[1], 10);
+        const newH = parseInt(match[2], 10);
+        // ... existing resize logic ...
+      },
+    });
+    ```
+  - For `set_frame_duration_dialog` (line 669):
+    ```
+    dialogState.openPrompt({
+      title: 'Set Frame Duration',
+      message: 'Enter frame duration in ms (empty for global FPS):',
+      defaultValue: '',
+      validate: (v) => {
+        if (v.trim() === '') return null; // empty is valid (means global FPS)
+        const n = Number(v);
+        if (isNaN(n) || n <= 0) return 'Must be a positive number';
+        return null;
+      },
+      onConfirm: (value) => {
+        // ... existing frame duration logic ...
+      },
+    });
+    ```
+  - Import `dialogState` if not already imported (it is already imported on line 33)
+
+### Preconditions
+
+- I-05 must be completed first (PromptDialog uses native `<dialog>`)
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- Resize canvas command (Image menu) opens a themed prompt dialog, not a browser prompt
+- Entering a valid "WxH" format resizes the canvas
+- Entering invalid input (e.g., "abc") shows inline validation error
+- Pressing Escape or Cancel closes without action
+- Set Frame Duration command opens a themed prompt dialog
+- Entering a valid number sets the frame duration
+- Entering empty string resets to global FPS
+- `grep -rn "window\.prompt\|= prompt(" src/ plugins/` returns 0 results
+- Works in Tauri on macOS and Linux (where `window.prompt()` fails)
+
+### Risks and Edge Cases
+
+- **Async flow:** `window.prompt()` is synchronous and blocking. `dialogState.openPrompt()` is async (callback-based). The `execute()` function for `resize_canvas` currently does the resize inline after `prompt()` returns. With the callback pattern, the resize logic moves into `onConfirm`. This changes the control flow but not the end result. Ensure `onConfirm` captures all needed closure variables.
+- **Multiple prompts:** If two commands try to open prompts simultaneously, the second would overwrite the first. This is unlikely in practice since prompts are modal. Add a guard: if `promptOpen` is already true, queue the second or reject it.
+- **Enter key:** The prompt should submit on Enter key press (in addition to clicking Confirm). Add `onkeydown` handler on the input that checks for Enter.
+
+---
+
+## I-07: God File Split
+
+### Summary
+
+`menu-commands-plugin.ts` is 1333 lines containing 42 commands, 55 menu items,
+9 toolbar items, duplicated zoom logic, clipboard state, DOM queries, and now-replaced
+`prompt()` calls. This item splits it into 8 domain-specific plugin files + 3 shared
+utility modules, then deletes the original. Each new file is a `PluginModule`
+auto-discovered by `bootstrap.ts` via the existing `import.meta.glob` pattern
+(which matches `src/lib/**/*-commands.ts`).
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/canvas/zoom-utils.ts` | Create | Export `ZOOM_STEPS`, `zoomStepUp()`, `zoomStepDown()`, `DEFAULT_ZOOM` (currently duplicated in menu-commands-plugin.ts lines 96-113 and input-handler.ts) |
+| `src/lib/canvas/viewport-utils.ts` | Create | Export `viewportCenter()` function (currently at menu-commands-plugin.ts lines 116-120, duplicated as DOM query) |
+| `src/lib/edit/clipboard-state.ts` | Create | Export `clipboardBuffer` reactive state and its type (currently at menu-commands-plugin.ts line 92) |
+| `src/lib/ui/file-commands.ts` | Create | `PluginModule` with commands: `new_project_dialog`, `open_file_dialog`, `save_project`, `export_dialog`; menu items for File menu (~80 lines) |
+| `src/lib/ui/edit-commands.ts` | Create | `PluginModule` with commands: `undo`, `redo`, `cut`, `copy`, `paste`, `select_all`, `deselect`; menu items for Edit menu (~150 lines). Imports `clipboardBuffer` from `clipboard-state.ts` |
+| `src/lib/ui/image-commands.ts` | Create | `PluginModule` with commands: `resize_canvas`, `crop_to_selection`, `flatten_image`, `canvas_size`; menu items for Image menu (~120 lines). Uses `dialogState.openPrompt()` instead of `prompt()` (from I-06) |
+| `src/lib/ui/layer-menu-commands.ts` | Create | `PluginModule` with commands: `merge_down`, `move_layer_up`, `move_layer_down`; menu items referencing existing layer commands from `layer-commands.ts` (~100 lines) |
+| `src/lib/ui/animation-menu-commands.ts` | Create | `PluginModule` with commands: `play_animation`, `set_frame_duration_dialog`; menu items for Animation menu (~80 lines). Uses `dialogState.openPrompt()` for frame duration |
+| `src/lib/ui/select-commands.ts` | Create | `PluginModule` with commands: `invert_selection`, `select_by_color`; shared menu items for Select menu (~60 lines) |
+| `src/lib/ui/view-commands.ts` | Create | `PluginModule` with all 17 view/zoom commands + 9 toolbar items (~350 lines). Imports from `zoom-utils.ts` and `viewport-utils.ts` |
+| `src/lib/ui/help-commands.ts` | Create | `PluginModule` with commands: `about`, `keyboard_shortcuts`, `report_bug`; menu items for Help menu (~70 lines) |
+| `src/lib/ui/menu-commands-plugin.ts` | Delete | Entire file removed after all commands migrated |
+| `src/lib/canvas/input-handler.ts` | Modify | Replace local `ZOOM_STEPS`/`zoomStepUp`/`zoomStepDown` with imports from `zoom-utils.ts` |
+| `src/lib/ui/CanvasViewport.svelte` | Modify | Replace local zoom constants with imports from `zoom-utils.ts` if applicable |
+
+### Step-by-Step Instructions
+
+- **Step 1: Create the 3 shared utilities**
+  - `zoom-utils.ts`: Copy `ZOOM_STEPS`, `zoomStepUp`, `zoomStepDown`, `DEFAULT_ZOOM` from menu-commands-plugin.ts lines 96-113. Export all four.
+  - `viewport-utils.ts`: Copy `viewportCenter()` from menu-commands-plugin.ts lines 116-120. Export it.
+  - `clipboard-state.ts`: Move the clipboard buffer declaration from line 92. Make it a reactive `$state` if needed for Svelte reactivity, or keep as plain `let` since it is module-level.
+  - Run `tsc --noEmit` to verify these utility files compile.
+
+- **Step 2: Create domain files one at a time**
+  - For each domain file:
+    - Create the file with a `PluginModule` export (matching the `*-commands.ts` glob pattern)
+    - Move relevant `api.addCommand()` and `api.addMenuItem()` calls from `menu-commands-plugin.ts`
+    - Move relevant imports (icons, state modules)
+    - Do NOT import from `menu-commands-plugin.ts` -- each file is self-contained
+    - Run `tsc --noEmit` after each file
+
+  - Order of creation (to minimize broken imports):
+    1. `file-commands.ts` -- simplest, fewest dependencies
+    2. `help-commands.ts` -- self-contained, only icons and mount/unmount for AboutDialog
+    3. `view-commands.ts` -- largest but self-contained, imports from `zoom-utils.ts` and `viewport-utils.ts`
+    4. `edit-commands.ts` -- depends on `clipboard-state.ts` and dispatcher
+    5. `select-commands.ts` -- depends on selection-tool imports
+    6. `layer-menu-commands.ts` -- references existing layer commands
+    7. `animation-menu-commands.ts` -- references existing animation commands, uses PromptDialog
+    8. `image-commands.ts` -- uses PromptDialog for resize, references selection and layer state
+
+- **Step 3: Update `input-handler.ts`**
+  - Replace local zoom logic with: `import { ZOOM_STEPS, zoomStepUp, zoomStepDown } from './zoom-utils.js';`
+  - Remove the duplicated zoom constants and functions
+
+- **Step 4: Verify bootstrap discovery**
+  - All 8 new files match the glob pattern `src/lib/**/*-commands.ts` used in `bootstrap.ts` (line 23)
+  - Exception: files with `-menu-commands.ts` suffix also match `*-commands.ts`
+  - Verify each file exports a `PluginModule` with `name`, `version`, and `register` fields, which passes the `isPluginModule` type guard in `bootstrap.ts` (lines 28-39)
+
+- **Step 5: Delete `menu-commands-plugin.ts`**
+  - Only after ALL commands and menu items are accounted for in the new files
+  - Verify by counting: 42 commands, 55 menu items, 9 toolbar items must all exist across the 8 new files
+
+- **Step 6: Verify no remaining references**
+  - `grep -rn "menu-commands-plugin" src/` should return 0 results
+  - `grep -rn "menuCommandsPlugin" src/ plugins/` should return 0 results
+
+### Preconditions
+
+- I-04 (undoable flag) should be completed so destructive commands are already marked `undoable: true` before being moved
+- I-06 (PromptDialog) should be completed so `prompt()` calls are already replaced before the split
+- I-05 (native dialog) should be completed so AboutDialog already uses `<dialog>`
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- All 42 commands appear in the command palette (verify count)
+- All menus render correctly: File (4 items), Edit (7 items), Image (4 items), Layer (6 items), Animation (5 items), Select (4 items), View (17+ items), Help (3 items), Context menus
+- All 9 view toolbar items appear in the view-controls toolbar
+- Zoom from keyboard, mouse wheel, and menu all use the same step logic from `zoom-utils.ts`
+- `bootstrap.ts` discovers all 8 new plugin modules (check console or debugger)
+- `grep -rn "menu-commands-plugin" src/` returns 0 results
+- No duplicated zoom constants remain in the codebase
+
+### Risks and Edge Cases
+
+- **Plugin load order:** The new domain files may have implicit dependencies (e.g., `edit-commands.ts` assumes `selection-tool` commands are already registered for menu items). Add explicit `dependencies` arrays to each `PluginModule` if needed. For example, `edit-commands.ts` might need `dependencies: ['builtin/selection']` if it references `deselect` commands.
+- **AboutDialog mount/unmount:** The `help-commands.ts` file needs to import `mount`/`unmount` from Svelte and the `AboutDialog.svelte` component. This cross-concern import is acceptable for now. After I-05 converts it to `<dialog>`, it may become a simpler dialogState-driven flow.
+- **Context menu items:** Some context menu items (e.g., `context/canvas/cut`, `context/layer/delete`) are currently registered in `menu-commands-plugin.ts`. These need to be distributed to the correct domain file (cut goes to `edit-commands.ts`, layer delete goes to `layer-menu-commands.ts`).
+- **Clipboard state reactivity:** If `clipboardBuffer` is used in `$derived` expressions anywhere, moving it to a separate module needs careful handling. Currently it is a plain `let` variable, not a `$state`, so no reactivity concern.
+
+---
+
+## I-08: Add getSelection() to PluginAPI
+
+### Summary
+
+`menu-commands-plugin.ts` line 38 directly imports `selectRect`, `deselectAll`,
+`hasSelection`, and `getSelectedPixels` from `plugins/builtin/selection-tool.ts`. This
+breaks the plugin boundary -- one plugin reaches into another's internal module.
+Adding `getSelection()` to `PluginAPI` provides a proper read-only interface for
+selection state. Mutations (selecting, deselecting) should go through `dispatch()` to
+existing `select_rect` and `deselect` commands.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/core/plugin-types.ts` | Modify | Add `SelectionView` interface and `getSelection(): SelectionView` to `PluginAPI` interface (after `getActiveLayers()` on line 39) |
+| `src/lib/core/plugin-api.ts` | Modify | Implement `getSelection()` by importing `hasSelection` and `getSelectedPixels` from `plugins/builtin/selection-tool.ts` internally; return a `SelectionView` object |
+| `src/lib/ui/edit-commands.ts` (or `menu-commands-plugin.ts` if I-07 not done) | Modify | Replace `import { hasSelection, getSelectedPixels } from '...selection-tool.js'` with `api.getSelection()` calls inside command handlers. Replace `selectRect(...)` calls with `api.dispatch({ type: 'select_rect', ... })`. Replace `deselectAll()` calls with `api.dispatch({ type: 'deselect', ... })` |
+| `src/lib/ui/image-commands.ts` (or `menu-commands-plugin.ts`) | Modify | Same replacement for `crop_to_selection` and any other selection-reading commands |
+| `src/lib/ui/select-commands.ts` (or `menu-commands-plugin.ts`) | Modify | Same replacement for `invert_selection` and `select_by_color` |
+
+### Step-by-Step Instructions
+
+- **Step 1: Define `SelectionView` in `plugin-types.ts`**
+  - Add before the `PluginAPI` interface (or inside it as a nested type):
+    ```
+    export interface SelectionView {
+      hasSelection(): boolean;
+      getSelectedPixels(): ReadonlySet<string>;
+    }
+    ```
+  - Add to `PluginAPI` interface (after `getActiveLayers(): unknown`):
+    ```
+    getSelection(): SelectionView;
+    ```
+
+- **Step 2: Implement in `plugin-api.ts`**
+  - Import from selection-tool: `import { hasSelection, getSelectedPixels } from '../../../plugins/builtin/selection-tool.js';`
+  - Add to the returned object:
+    ```
+    getSelection() {
+      return {
+        hasSelection: () => hasSelection(),
+        getSelectedPixels: () => getSelectedPixels(),
+      };
+    },
+    ```
+
+- **Step 3: Update consumer files**
+  - In each consumer (edit-commands, image-commands, select-commands), the `register(api)` function has access to `api`. Inside command `execute()` bodies:
+    - Replace `hasSelection()` with `api.getSelection().hasSelection()` -- but note that `api` is available in `register()` scope, not inside `execute(params, ctx)`. Options:
+      - Option A: Store `api` reference in closure: `const sel = api.getSelection;` then use `sel().hasSelection()`
+      - Option B: Add `getSelection` to `CommandContext` as well
+    - Option A is simpler and maintains the current pattern where closures capture the `api` reference.
+  - Replace direct `selectRect(x, y, w, h)` calls with:
+    ```
+    api.dispatch({
+      type: 'select_rect',
+      plugin: 'ui/edit-commands',
+      version: '1.0.0',
+      params: { x, y, w, h },
+    });
+    ```
+  - Replace `deselectAll()` calls with:
+    ```
+    api.dispatch({
+      type: 'deselect',
+      plugin: 'ui/edit-commands',
+      version: '1.0.0',
+      params: {},
+    });
+    ```
+
+- **Step 4: Remove direct imports**
+  - Remove `import { selectRect, deselect as deselectAll, hasSelection, getSelectedPixels } from '../../../plugins/builtin/selection-tool.js';` from all consumer files
+
+### Preconditions
+
+- I-07 (god file split) should be completed first so the consumers are already in separate files, making the import changes cleaner. If I-07 is not done, the changes apply to `menu-commands-plugin.ts` instead.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes
+- `cut` command works: reads selection via `api.getSelection()`, copies pixels to clipboard, clears them
+- `crop_to_selection` works: reads selection bounds, resizes canvas
+- `select_all` and `deselect` work via `api.dispatch()`
+- `grep -rn "from.*selection-tool" src/lib/ui/` returns 0 results (no direct imports from UI command files)
+- `grep -rn "from.*selection-tool" src/lib/core/plugin-api.ts` returns 1 result (the internal implementation import, which is acceptable)
+
+### Risks and Edge Cases
+
+- **Circular import risk:** `plugin-api.ts` imports from `selection-tool.ts`, which imports from `plugin-loader.ts` (for `PluginModule` type), which imports from `plugin-api.ts`. Check this chain:
+  - `plugin-api.ts` -> `selection-tool.ts` -> `plugin-loader.ts` -> `plugin-api.ts`
+  - `plugin-loader.ts` only imports the TYPE `PluginAPI` from `plugin-api.ts`, not the value. Since TypeScript erases type-only imports, there is no runtime circular dependency. But verify with `import type` usage.
+- **Selection state timing:** `getSelection()` returns a live view (calls `hasSelection()` at invocation time). If selection state changes between the read and the subsequent operation, the command could operate on stale data. This matches the current behavior (direct function calls have the same timing) so it is not a regression.
+- **Dispatch for mutations:** Using `api.dispatch()` for `select_rect` and `deselect` means these operations go through the undo stack. If the consuming command is itself on the undo stack (e.g., `select_all` dispatches `select_rect`), this creates nested undo entries. Verify this is the desired behavior. If `select_all` should be a single undo entry, it may need to call the selection functions directly or use a transaction pattern.
+
+---
+
+## I-09: Add Mutator Methods to PluginAPI
+
+### Summary
+
+All 3 importers (`aseprite-importer-plugin.ts`, `piskel-importer-plugin.ts`,
+`sky-spec-plugin.ts`) bypass the `PluginAPI` entirely to set canvas size, add layers
+and frames, and write pixel data via direct imports of internal modules. The API
+currently only has read-only getters that return `unknown`. Adding ~15 mutator methods
+lets importers work through the API, enforcing encapsulation and enabling future
+validation/event hooks.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `src/lib/core/plugin-types.ts` | Modify | Add 15 new method signatures to `PluginAPI` interface, organized in 6 groups (canvas, layers, frames, pixel data, palette, composite) |
+| `src/lib/core/plugin-api.ts` | Modify | Implement all 15 methods as thin wrappers around existing module functions. Add imports for `canvasState`, `layerTree`, `frameModel`, `PixelBuffer`, color palette state |
+| `plugins/builtin/importers/aseprite-importer-plugin.ts` | Modify | Replace direct imports of internal modules with `api.*` method calls |
+| `plugins/builtin/importers/piskel-importer-plugin.ts` | Modify | Same replacement |
+| `plugins/builtin/importers/sky-spec-plugin.ts` | Modify | Same replacement |
+
+### Step-by-Step Instructions
+
+- **Step 1: Canvas methods**
+  - Add to `PluginAPI` in `plugin-types.ts`:
+    ```
+    setCanvasSize(width: number, height: number): void;
+    ```
+  - Implement in `plugin-api.ts`:
+    ```
+    setCanvasSize(width, height) {
+      canvasState.canvasWidth = width;
+      canvasState.canvasHeight = height;
+    },
+    ```
+  - `canvasState` is already imported in `plugin-api.ts` (line 22)
+
+- **Step 2: Layer methods**
+  - Add to `PluginAPI`:
+    ```
+    addLayer(name: string): unknown;  // returns the new layer object
+    resetLayers(): void;
+    setLayerVisibility(id: string, visible: boolean): void;
+    setLayerOpacity(id: string, opacity: number): void;
+    ```
+  - Implement using `layerTree` module functions (already partially imported via `getLayers`, `getActiveLayer` on lines 24-25 of plugin-api.ts):
+    ```
+    addLayer(name) {
+      return layerTree.addLayer(name);
+    },
+    resetLayers() {
+      layerTree.deserialize({ layers: [], activeLayerId: '' });
+    },
+    ```
+  - Add missing `layerTree` imports: `addLayer`, `deserialize`, `setVisibility`, `setOpacity`
+
+- **Step 3: Frame methods**
+  - Add to `PluginAPI`:
+    ```
+    addFrame(): unknown;  // returns the new frame object
+    resetFrames(): void;
+    setFrameDuration(index: number, ms: number): void;
+    setCurrentFrame(index: number): void;
+    setGlobalFps(fps: number): void;
+    getFrames(): unknown;
+    ```
+  - Implement using `frameModel` module (import `addFrame`, `deserialize`, `setFrameDuration`, `setCurrentFrameIndex`, `setGlobalFps`, `getFrames` from `frame-model.svelte.js`)
+
+- **Step 4: Pixel data methods**
+  - Add to `PluginAPI`:
+    ```
+    createPixelBuffer(width: number, height: number): unknown;  // returns PixelBuffer
+    ```
+  - Implement:
+    ```
+    createPixelBuffer(width, height) {
+      return new PixelBuffer(width, height);
+    },
+    ```
+  - Import `PixelBuffer` from `pixel-buffer.ts`
+
+- **Step 5: Palette method**
+  - Add to `PluginAPI`:
+    ```
+    setProjectPalette(colors: string[]): void;
+    ```
+  - Implement by importing the palette state module and calling its setter
+
+- **Step 6: Composite method**
+  - Add to `PluginAPI`:
+    ```
+    resetProject(): void;
+    ```
+  - Implement as a convenience that calls `resetLayers()`, `resetFrames()`, and resets canvas to defaults
+
+- **Step 7: Migrate importers one at a time**
+  - For each importer:
+    - Identify all direct imports of internal modules (`canvasState`, `layerTree`, `frameModel`, `PixelBuffer`)
+    - Replace with `api.*` method calls
+    - The `api` is available as the parameter to `register(api)`; importer functions that are called later (e.g., the `import()` method in `ImporterDefinition`) need access to `api` via closure
+    - Remove the direct imports
+    - Run `tsc --noEmit` after each importer migration
+
+### Preconditions
+
+- None strictly required. However, doing this after I-07 (god file split) means the `plugin-api.ts` is cleaner and easier to modify. Also, I-03 (typed CommandContext) should be done first so the `PluginAPI` interface is already updated with `getActiveBuffer`.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes after each incremental step
+- Import an Aseprite file: layers, frames, and pixel data appear correctly
+- Import a Piskel file: same verification
+- Import a Sky Spec file: same verification
+- `grep -rn "from.*canvas-state" plugins/builtin/importers/` returns 0 results
+- `grep -rn "from.*layer-tree" plugins/builtin/importers/` returns 0 results
+- `grep -rn "from.*frame-model" plugins/builtin/importers/` returns 0 results
+
+### Risks and Edge Cases
+
+- **Return types:** The methods return `unknown` to avoid coupling the `PluginAPI` interface to internal implementation types. This is acceptable for now. In the future, define stable return interfaces (e.g., `LayerInfo`, `FrameInfo`) that are part of the public API contract.
+- **Importer closure pattern:** Importers define their `import()` function inside `register(api)`, capturing `api` in the closure. This is the same pattern used by tools that capture `api` for dispatch. Verify that all 3 importers follow this pattern and have access to `api` inside their import function.
+- **Incremental shippability:** Each step (canvas, layers, frames, etc.) can be shipped independently. Do not wait for all 6 steps before migrating any importer -- migrate one importer per step if possible.
+
+---
+
+## I-10: Enable Strict TypeScript Flags
+
+### Summary
+
+`tsconfig.app.json` currently extends `@tsconfig/svelte/tsconfig.json` with `target: "es2023"`,
+`module: "esnext"`, `allowJs: true`, `checkJs: true`, but does not enable several strict
+flags. This item enables 5 additional flags in ascending blast-radius order:
+`noFallthroughCasesInSwitch`, `noUnusedLocals`, `noUnusedParameters`,
+`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`. Each flag is added
+independently with all resulting errors fixed before moving to the next.
+
+### Files Touched
+
+| File Path | Action | What Changes |
+|-----------|--------|--------------|
+| `tsconfig.app.json` | Modify | Add 5 flags incrementally to `compilerOptions` |
+| ~7 files | Modify | Fix `noUnusedLocals` / `noUnusedParameters` errors (delete dead imports, prefix unused params with `_`) |
+| ~11 files | Modify | Fix `exactOptionalPropertyTypes` errors (narrow optional properties before passing, or change types to explicitly include `undefined`) |
+| ~54 files | Modify | Fix `noUncheckedIndexedAccess` errors (add null checks, non-null assertions in tests, guard clauses) |
+
+### Step-by-Step Instructions
+
+- **Step 1: `noFallthroughCasesInSwitch`**
+  - Add to `tsconfig.app.json` compilerOptions: `"noFallthroughCasesInSwitch": true`
+  - Run `tsc --noEmit` -- expected 0 errors (no switch statements with fallthrough in the codebase)
+  - Commit
+
+- **Step 2: `noUnusedLocals` + `noUnusedParameters`**
+  - Add both flags: `"noUnusedLocals": true, "noUnusedParameters": true`
+  - Run `tsc --noEmit` -- expected ~7 errors
+  - Fix each:
+    - Delete unused imports (e.g., an imported icon that is no longer used)
+    - Prefix unused function parameters with `_` (e.g., `_name` in menu-builder.ts `resolveLabel` at line 46, which already uses `_name`)
+    - Delete unused local variables
+  - Commit
+
+- **Step 3: `exactOptionalPropertyTypes`**
+  - Add: `"exactOptionalPropertyTypes": true`
+  - Run `tsc --noEmit` -- expected ~11 errors
+  - This flag means `{ x?: number }` does not accept `{ x: undefined }`. Fixes:
+    - Where a value might be `undefined`, change the type to `x?: number | undefined` or narrow before assignment
+    - Common in PanelConfig, ToolbarContribution, MenuContribution where optional fields are sometimes explicitly set to `undefined`
+  - Commit
+
+- **Step 4: `noUncheckedIndexedAccess`**
+  - Add: `"noUncheckedIndexedAccess": true`
+  - Run `tsc --noEmit` -- expected ~470 errors
+  - This is the highest-impact flag. For each error:
+    - **In test files** (~257 errors): Add non-null assertion `!` where test data is controlled and values are known to exist
+    - **In production code** (~213 errors): Add proper null checks with early returns or fallback values. Categories:
+      - Array index access: add bounds check or use `.at()` with null check
+      - Map `.get()` followed by property access: add undefined check
+      - `ZOOM_STEPS[i]` access: add bounds check (already handled by `zoomStepUp`/`zoomStepDown` logic)
+      - `Object.entries()` destructuring: values are now `T | undefined`
+    - Some of these will surface real latent bugs (array access without bounds checking). Fix those properly.
+  - Commit after all errors fixed
+
+- **Step 5: Evaluate `noPropertyAccessFromIndexSignature`**
+  - This flag has ~698 errors and forces bracket notation on all index signature access. It is the most invasive and arguably lowest value.
+  - Evaluate whether the benefits justify the churn after all other flags are enabled. If the prior I-03 changes have eliminated most `Record<string, unknown>` usage, the error count may be significantly lower.
+  - If enabled: add to `tsconfig.app.json` and fix all resulting errors by switching to bracket notation where needed
+  - If deferred: document the decision and the remaining error count
+
+### Preconditions
+
+- I-03 (Generic Command\<P\>) must be completed first. The generic params eliminate many `Record<string, unknown>` index access patterns that would otherwise generate hundreds of `noUncheckedIndexedAccess` errors.
+- All prior items should ideally be done so the codebase is stable before the flag-by-flag sweep.
+
+### Postconditions / Verification
+
+- `tsc --noEmit` passes with all enabled flags
+- All tests pass (`npx vitest run`)
+- No `as any` or `@ts-ignore` comments added to suppress errors (unless documented with justification)
+- No runtime regressions (all fixes are compile-time type narrowing)
+- The `noUncheckedIndexedAccess` fixes have surfaced and fixed any real latent bugs (document which bugs were found)
+
+### Risks and Edge Cases
+
+- **Blast radius of `noUncheckedIndexedAccess`:** 470 errors across 54 files is a large changeset. Consider doing it in multiple commits: one per directory (e.g., `plugins/builtin/`, `src/lib/core/`, `src/lib/ui/`, etc.).
+- **Test file noise:** 257 of the 470 errors are in test files. Using `!` assertions in tests is acceptable since test data is controlled, but it should be done thoughtfully (only where the value is truly guaranteed).
+- **`noPropertyAccessFromIndexSignature` cost-benefit:** 698 errors with minimal type-safety benefit for most cases. Strongly consider deferring this flag or enabling it only for new code via eslint rules instead.
+- **Interaction with Svelte:** Svelte 5's `$state`, `$derived`, and `$props` runes may interact with strict flags in unexpected ways. Test compilation of `.svelte` files specifically after enabling each flag.
+- **Third-party types:** The `@tsconfig/svelte` base config and `dockview-core` types may not be compatible with all strict flags. If a third-party type causes errors, use targeted type overrides or `d.ts` augmentations rather than disabling the flag.
+
+---
+
+## Internal Consistency Check
+
+### 1. Dependency Validation
+
+| Item | Precondition | What Precondition Produces | Verified? |
+|------|-------------|---------------------------|-----------|
+| I-01 | None | N/A | Yes |
+| I-02 | None (ideally after I-01) | I-01 produces `make-stroke-tool.ts` which I-02 will import `makeSnapshotUndo` into | Yes -- I-02's file list includes `make-stroke-tool.ts` as a modification target |
+| I-03 | I-01 + I-02 (ideally) | I-01 produces the factory, I-02 produces `makeSnapshotUndo`. I-03 updates both to use generic params and separate snapshot. | Yes -- I-03's step 8 explicitly updates `makeSnapshotUndo` |
+| I-04 | I-03 | I-03 produces typed `CommandDefinition<P>`, `Command<P>`, and updated dispatcher with snapshot support. I-04 needs the typed `Command` for `executeOrDispatch` to construct properly. | Yes -- I-04's `executeOrDispatch` helper constructs a `Command` object using the interface from I-03 |
+| I-05 | None | N/A | Yes |
+| I-06 | I-05 | I-05 establishes the `<dialog>` pattern. I-06's `PromptDialog.svelte` uses native `<dialog>`. | Yes -- I-06's step 2 uses `<dialog>` with `.showModal()` |
+| I-07 | I-04 + I-06 | I-04 provides `undoable` flag so destructive commands are marked before splitting. I-06 provides `dialogState.openPrompt()` so `prompt()` calls are already replaced. | Yes -- I-07 references `undoable: true` on destructive commands and `dialogState.openPrompt()` for resize and frame duration |
+| I-08 | I-07 | I-07 splits `menu-commands-plugin.ts` into domain files, making it cleaner to replace direct selection-tool imports. | Yes -- I-08 references `edit-commands.ts`, `image-commands.ts`, `select-commands.ts` (products of I-07) |
+| I-09 | I-03 + I-07 (ideally) | I-03 provides typed `CommandContext` with `getActiveBuffer`. I-07 provides a clean `plugin-api.ts`. | Yes -- I-09 builds on the `PluginAPI` interface already modified by I-03 (adding `getActiveBuffer` to context) and I-08 (adding `getSelection`) |
+| I-10 | I-03 | I-03 eliminates ~263 type casts, dramatically reducing the error count for strict flags (especially `noUncheckedIndexedAccess` which would flag `Record<string, unknown>` index access). | Yes -- without I-03, `noUncheckedIndexedAccess` would have ~263 more errors from the cast patterns |
+
+### 2. File Conflict Check
+
+Files touched by more than one item:
+
+| File Path | Touched By | Conflict Analysis |
+|-----------|-----------|-------------------|
+| `src/lib/core/commands.ts` | I-03 (generic Command, typed CommandContext, UndoEntry.snapshot), I-04 (add `undoable` field) | **Safe.** I-03 runs first and restructures the interfaces. I-04 adds one new field (`undoable?: boolean`) to `CommandDefinition`, which is additive and does not conflict with I-03's generic params. |
+| `src/lib/core/dispatcher.ts` | I-03 (snapshot capture/pass), I-04 (add `executeOrDispatch` helper) | **Safe.** I-03 modifies `dispatch()`, `undoLast()`, and `redoLast()` internals. I-04 adds a new `executeOrDispatch()` function. No overlap in modified lines. |
+| `src/lib/core/plugin-types.ts` | I-03 (generic `addCommand`), I-08 (`getSelection`), I-09 (mutator methods) | **Safe.** Each item adds new members to the `PluginAPI` interface. I-03 modifies the `addCommand` signature (line 15) and adds `getActiveBuffer` to `CommandContext` (line 67). I-08 adds `getSelection()`. I-09 adds 15 mutator methods. All additive, no conflicts. Order: I-03 first, then I-08, then I-09. |
+| `src/lib/core/plugin-api.ts` | I-03 (implement `getActiveBuffer` on context), I-08 (implement `getSelection`), I-09 (implement 15 mutators) | **Safe.** Same analysis as plugin-types.ts -- all additive implementations. |
+| `src/lib/core/registries.svelte.ts` | I-03 (change to `CommandDefinition<any>`) | Only I-03 touches this. No conflict. |
+| `plugins/builtin/drawing-utils.ts` | I-02 (add `makeSnapshotUndo`), I-03 (update `makeSnapshotUndo` signature) | **Safe.** I-02 adds the function. I-03 updates its signature (params type, adds snapshot arg). Order is correct: I-02 creates, I-03 updates. |
+| `plugins/builtin/pencil-tool.ts` | I-01 (reduce to factory call), I-02 (if I-01 not done, replace undo handler), I-03 (add typed params) | **Safe.** I-01 reduces the file to ~20 lines (factory call). I-02 may be absorbed into I-01 if done together. I-03 adds typed params to the factory config. No conflict because I-01's output is a thin wrapper that I-03 updates. |
+| `plugins/builtin/eraser-tool.ts` | I-01, I-02, I-03 | Same analysis as pencil-tool.ts. |
+| All 23 plugin files | I-02 (replace undo handlers), I-03 (generic params, remove casts) | **Safe.** I-02 replaces the `undo` function body. I-03 replaces the `execute` and `describe` function signatures and removes `_snapshot` from params. Different lines in the same files. Order is correct: I-02 simplifies undo first, I-03 changes signatures second. |
+| `src/lib/ui/menu-builder.ts` | I-04 (change `action` routing) | Only I-04 touches the `action` field. No conflict. |
+| `src/lib/ui/dialog-state.svelte.ts` | I-06 (add prompt state) | Only I-06 touches this. I-05 does not need to modify it (dialog refs are local to components). |
+| `src/App.svelte` | I-06 (add PromptDialog rendering) | Only I-06 touches this. I-05 converts existing dialog components but does not change App.svelte. |
+| `src/lib/ui/menu-commands-plugin.ts` | I-04 (mark undoable), I-06 (replace prompt), I-07 (delete) | **Safe if ordered correctly.** I-04 adds `undoable: true` to some commands. I-06 replaces `prompt()` calls. I-07 splits and deletes the file. All three happen in order: I-04 first, I-06 second, I-07 third (which deletes the file). No simultaneous conflict. |
+| `tsconfig.app.json` | I-10 (add strict flags) | Only I-10 touches this. |
+| `src/lib/canvas/input-handler.ts` | I-07 (replace zoom imports) | Only I-07 touches this. |
+
+### 3. Import Chain Validation
+
+Key import chains after all changes:
+
+- **Plugin registration chain:**
+  `pencil-tool.ts` -> `make-stroke-tool.ts` -> `drawing-utils.ts` -> `pixel-buffer.ts`
+  `pencil-tool.ts` -> `make-stroke-tool.ts` -> `plugin-loader.ts` -> `plugin-api.ts` -> `plugin-types.ts`
+  No circularity. `plugin-types.ts` does not import from `plugin-api.ts`.
+
+- **Dispatcher chain:**
+  `dispatcher.ts` -> `commands.ts` (types only)
+  `dispatcher.ts` -> `registries.svelte.ts` -> `commands.ts` (types only)
+  No circularity.
+
+- **PluginAPI -> selection-tool chain (after I-08):**
+  `plugin-api.ts` -> `selection-tool.ts` -> `plugin-loader.ts` -> `plugin-api.ts`
+  This looks circular but is safe: `plugin-loader.ts` imports only the TYPE `PluginAPI` from `plugin-api.ts` (using `import type`). TypeScript erases type-only imports at compile time, so there is no runtime circular dependency. `selection-tool.ts` imports `PluginModule` (a type) from `plugin-loader.ts`. Verified: `plugin-loader.ts` line 12 uses `import type { PluginAPI }`.
+
+- **Menu builder -> dispatcher chain (after I-04):**
+  `menu-builder.ts` -> `dispatcher.ts` (for `executeOrDispatch`)
+  `menu-builder.ts` -> `registries.svelte.ts` (already imported, line 10)
+  No new circularity.
+
+- **Domain command files -> zoom-utils chain (after I-07):**
+  `view-commands.ts` -> `zoom-utils.ts` (new)
+  `input-handler.ts` -> `zoom-utils.ts` (new)
+  No circularity. `zoom-utils.ts` is a pure utility with no imports from the project.
+
+### 4. Type System Coherence
+
+After I-03 (Generic Command\<P\>) and I-10 (strict flags):
+
+- **Generic param flow through dispatch:**
+  - Plugin calls `api.dispatch({ type: 'draw_rect', plugin: '...', version: '...', params: { x: 1, y: 2, ... } })`
+  - `PluginAPI.dispatch` accepts `Omit<Command, 'id' | 'timestamp'>` which after I-03 becomes `Omit<Command<any>, 'id' | 'timestamp'>` since the dispatch API does type erasure at the boundary
+  - `dispatcher.dispatch()` receives `Command` (type-erased to `Command<any>`) and calls `definition.execute(command.params, context)` where `definition` is `CommandDefinition<any>` from the registry
+  - This means: type safety exists at plugin registration time (the `CommandDefinition<DrawRectParams>` enforces that `execute` receives `DrawRectParams`), but is erased at the registry/dispatcher boundary. This is correct and expected.
+
+- **Snapshot flow through undo stack:**
+  - `execute(params: P, ctx: CommandContext)` returns `unknown | void`
+  - Dispatcher captures return value and stores as `UndoEntry.snapshot: unknown`
+  - `undo(params: P, ctx: CommandContext, snapshot: unknown)` receives it
+  - Each plugin's undo handler casts `snapshot as PixelData[]` (or its specific snapshot type)
+  - This is one `as` cast per undo handler, which is acceptable at the boundary between the generic undo system and the specific plugin data. `makeSnapshotUndo` centralizes this cast.
+
+- **`noUncheckedIndexedAccess` interaction:**
+  - After I-03, `Command.params` is typed as `P` (not `Record<string, unknown>`), so index access on params is no longer needed. The ~170 `params.field as Type` casts are gone, replaced by typed property access.
+  - Remaining index access patterns (arrays, Maps) will need null checks under `noUncheckedIndexedAccess`. These are independent of the generic Command changes.
+
+### 5. Plugin System Coherence
+
+After I-08 (`getSelection`) and I-09 (mutator methods):
+
+- **Pattern consistency:** The existing `PluginAPI` methods follow two patterns:
+  - Registrars: `addCommand`, `addTool`, `addPanel`, etc. -- take a name + definition, store in registry
+  - Getters: `getCanvas`, `getProject`, `getActiveFrame`, `getActiveLayers` -- return current state
+
+  The new methods add two more patterns:
+  - Query: `getSelection` -- returns a view object with methods (consistent with `getActiveLayers` which returns `{ all, active }`)
+  - Mutators: `setCanvasSize`, `addLayer`, `addFrame`, etc. -- thin wrappers around internal modules
+
+  All patterns are consistent: methods are verb-prefixed (`add`, `get`, `set`, `reset`), take simple parameters, and return simple values or `unknown`.
+
+- **No overlap between getter return types and mutator inputs:** `getActiveLayers()` returns `unknown` (not a typed layer object). `addLayer(name)` takes a string. There is no type inconsistency between reads and writes because both sides use `unknown` or simple primitives.
+
+- **`api` instance scoping:** Each plugin receives its own `api` instance from `createPluginAPI(pluginName)`. However, all instances share the same registries and state. The `_pluginName` parameter (line 34 of plugin-api.ts) is currently unused (`eslint-disable-next-line @typescript-eslint/no-unused-vars`). The new methods do not use it either, which is consistent. If namespace scoping is needed later, all methods have access to `_pluginName` via closure.
+
+### 6. Dead Code Check
+
+| Item | Potential Dead Code | Resolution |
+|------|-------------------|------------|
+| I-01 | The full `register()` bodies in `pencil-tool.ts` and `eraser-tool.ts` are replaced by factory calls. The old code (130+ lines) is deleted, not orphaned. | No dead code. |
+| I-02 | All 32 inline undo handler bodies are replaced by `makeSnapshotUndo()` calls. The old code is deleted. | No dead code. |
+| I-03 | The `_snapshot` field in dispatch `params` objects (21+ files) is removed. The old snapshot-in-params convention is fully eliminated. However, verify no external code reads `command.params._snapshot` from the undo stack for display purposes. | Check: does any UI component (e.g., a history panel) read `_snapshot` from `Command.params`? If so, update it to read from `UndoEntry.snapshot`. |
+| I-03 | The current `CommandContext` empty interface `{ [key: string]: unknown }` (line 67 of commands.ts) is replaced with typed members. If any code relies on adding arbitrary keys to the context, the index signature removal could break it. | Check: `dispatcher.ts` `setContext()` (line 253) uses `Object.assign(context, partial)`. The typed `CommandContext` must still allow extension. Keep the index signature alongside the typed members: `{ getActiveBuffer?: ...; [key: string]: unknown; }` |
+| I-04 | The `executeOrDispatch` helper is new code, not dead code. The old direct `.execute({}, {})` calls in 4 files are replaced. | No dead code. |
+| I-05 | The `.modal-overlay` CSS class and the manual Escape handlers are removed from 3 dialog components. Any global `.modal-overlay` styles in `app.css` become dead CSS. | Check: `grep -rn "modal-overlay" src/` after I-05 should return 0 results. Remove any orphaned global styles. |
+| I-06 | The `window.prompt()` calls are replaced. No dead code created (the replacement is `dialogState.openPrompt()`). | No dead code. |
+| I-07 | The original `menu-commands-plugin.ts` is deleted. All its exports (`menuCommandsPlugin`) become dead references. | Check: `grep -rn "menuCommandsPlugin" src/` should return 0 after deletion. The `bootstrap.ts` glob discovers modules by file pattern, not by explicit import, so deletion is safe. |
+| I-07 | The `ZOOM_STEPS`, `zoomStepUp`, `zoomStepDown`, and `viewportCenter` functions are moved to new utility files. The originals in `menu-commands-plugin.ts` are deleted with the file. But duplicates in `input-handler.ts` must also be removed and replaced with imports. | Check: after I-07, `grep -rn "ZOOM_STEPS" src/` should return only `zoom-utils.ts` and its importers. |
+| I-08 | The direct imports of `selectRect`, `deselectAll`, `hasSelection`, `getSelectedPixels` from `selection-tool.ts` in UI command files are removed. The functions themselves in `selection-tool.ts` remain (they are used by `plugin-api.ts` internally and by the tool's own `register()` function). | No dead code in `selection-tool.ts`. Orphaned imports in consumer files are removed. |
+| I-09 | No dead code created. New methods are additive. The direct imports in importers are removed and replaced with `api.*` calls. | No dead code. |
+| I-10 | Unused locals and parameters are deleted (step 2). No new dead code is created by the other flags. | Step 2 specifically eliminates dead code. |