pixelweaver 0.1.0

package/todo/.done/audit-design-decisions.md

@@ -0,0 +1,812 @@
+# PixelWeaver Codebase Audit -- Architectural Design Decisions
+
+This document captures 10 design decisions arising from the PixelWeaver codebase audit.
+Each decision includes full context, the problem, the chosen solution, exact files to change,
+dependencies on other decisions, and effort estimates. The recommended implementation order
+at the bottom accounts for all inter-decision dependencies.
+
+---
+
+## Table of Contents
+
+- [Phase 1: DRY Factories (Isolated, No Dependencies)](#phase-1-dry-factories)
+  - [Decision #24: Create makeStrokeTool Factory](#decision-24-create-makestroketool-factory)
+  - [Decision #25: Create makeSnapshotUndo Factory](#decision-25-create-makesnapshotundo-factory)
+- [Phase 2: Type System Foundation](#phase-2-type-system-foundation)
+  - [Decision #20: Generic Command\<P\> + Separate Snapshot from Params](#decision-20-generic-commandp--separate-snapshot-from-params)
+- [Phase 3: Undoable Flag](#phase-3-undoable-flag)
+  - [Decision #1: Add undoable Flag to CommandDefinition](#decision-1-add-undoable-flag-to-commanddefinition)
+- [Phase 4: Dialog / UI Work](#phase-4-dialog--ui-work)
+  - [Decision #22: Native \<dialog\> Element for Modals](#decision-22-native-dialog-element-for-modals)
+  - [Decision #26: Build Reusable PromptDialog Component](#decision-26-build-reusable-promptdialog-component)
+- [Phase 5: God File Split](#phase-5-god-file-split)
+  - [Decision #14: Full 8-File Domain Split of menu-commands-plugin.ts](#decision-14-full-8-file-domain-split-of-menu-commands-plugints)
+- [Phase 6: Plugin API Expansion](#phase-6-plugin-api-expansion)
+  - [Decision #12: Add getSelection() to PluginAPI](#decision-12-add-getselection-to-pluginapi)
+  - [Decision #13: Add Mutator Methods to PluginAPI Incrementally](#decision-13-add-mutator-methods-to-pluginapi-incrementally)
+- [Phase 7: Strict TypeScript Flags](#phase-7-strict-typescript-flags)
+  - [Decision #19: Enable All 5 Strict TypeScript Flags](#decision-19-enable-all-5-strict-typescript-flags)
+- [Implementation Order Summary](#implementation-order-summary)
+- [Effort Summary](#effort-summary)
+
+---
+
+## Phase 1: DRY Factories
+
+These two decisions are fully isolated from every other decision and from each other.
+They can be implemented in parallel on day one.
+
+---
+
+### Decision #24: Create makeStrokeTool Factory
+
+**Effort:** Small
+
+**Depends on:** Nothing
+
+#### Problem
+
+`pencil-tool.ts` and `eraser-tool.ts` are structurally identical (~100 lines each).
+They differ only in:
+
+- Command name / description verb
+- Pixel color resolution (foreground color vs. transparent)
+- Icon
+- Toolbar order
+
+This is a textbook DRY violation. Any behavioral change to stroke tools must be
+applied twice, and they can silently drift.
+
+#### Solution
+
+Create a `makeStrokeTool(config)` factory function that produces an entire `PluginModule`.
+
+**Config interface:**
+
+```typescript
+interface StrokeToolConfig {
+  pluginName: string;
+  commandName: string;
+  toolId: string;
+  icon: any;
+  toolbarOrder: number;
+  describeVerb: string;
+  resolveColor: (ctx: ToolContext) => { r: number; g: number; b: number; a: number };
+}
+```
+
+**Color resolution per tool:**
+
+| Tool | resolveColor |
+|------|-------------|
+| Pencil | `(ctx) => hexToRgba(ctx.color)` |
+| Eraser | `() => ({ r: 0, g: 0, b: 0, a: 0 })` |
+
+Note: `pattern-stamp` stays separate -- it has a fundamentally different data flow
+and should not be forced into this factory.
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `plugins/builtin/make-stroke-tool.ts` | **Create** -- the factory function |
+| `plugins/builtin/pencil-tool.ts` | **Reduce** to ~15 lines calling the factory |
+| `plugins/builtin/eraser-tool.ts` | **Reduce** to ~15 lines calling the factory |
+
+#### Verification
+
+- Draw with pencil: pixels appear in foreground color
+- Draw with eraser: pixels become transparent
+- Undo/redo works for both tools
+- Both appear in toolbar at correct positions with correct icons
+
+---
+
+### Decision #25: Create makeSnapshotUndo Factory
+
+**Effort:** Small (mechanical find-and-replace)
+
+**Depends on:** Ideally done after #20 (if snapshot is separated from params, the undo
+handler signature changes). Can be done before #20 with the current signature and
+updated during #20.
+
+#### Problem
+
+32 out of 33 undo handlers across 23 files are byte-for-byte identical:
+
+1. Get the active buffer from context
+2. Bail if buffer is missing
+3. Apply the snapshot pixels from params
+
+This is massive duplication. A bug fix to the undo pattern would need 32 edits.
+
+#### Solution
+
+Add a `makeSnapshotUndo()` function to `drawing-utils.ts` that returns a reusable
+undo handler closure.
+
+```typescript
+export function makeSnapshotUndo(): UndoHandler {
+  return (params, ctx) => {
+    const buffer = ctx.getActiveBuffer?.();
+    if (!buffer) return;
+    applyPixels(buffer, params._snapshot);
+  };
+}
+```
+
+The single exception (`move_selection`) stays manual because it has custom undo logic
+beyond pixel restoration.
+
+#### Files to Change
+
+| File | Action | Occurrences |
+|------|--------|-------------|
+| `plugins/builtin/drawing-utils.ts` | **Add** `makeSnapshotUndo()` | 1 (definition) |
+| `plugins/builtin/drawing-primitives-plugin.ts` | **Replace** inline undo handlers | 6 |
+| `plugins/builtin/color-effects.ts` | **Replace** inline undo handlers | 5 |
+| ~9 other tool/effect files in `plugins/builtin/` | **Replace** inline undo handlers | ~21 |
+
+Total: 32 replacements across 15 files, plus 1 definition.
+
+#### Verification
+
+- Undo/redo works for all drawing tools and effects
+- `move_selection` undo still works (should be untouched)
+- No regressions in any tool's undo behavior
+
+---
+
+## Phase 2: Type System Foundation
+
+This is the most impactful single decision. It eliminates ~263 unsafe casts and makes
+the entire command/dispatch system type-safe. Must come before #1 and #19.
+
+---
+
+### Decision #20: Generic Command\<P\> + Separate Snapshot from Params
+
+**Effort:** Large
+
+**Depends on:** Nothing (foundational change, should be done early)
+
+#### Problem (Three Sub-Problems)
+
+**Sub-problem A -- Untyped params:** `Command.params` is `Record<string, unknown>`,
+forcing every plugin to write `params.x as number`, `params.color as string`, etc.
+This produces ~170 field casts across 23 plugin files. Any typo or type mismatch is
+invisible to the compiler.
+
+**Sub-problem B -- Snapshot smuggled into params:** The `_snapshot` field is shoved
+into `params` as a mutable side-channel by `execute()`, then read back in `undo()`.
+This makes params non-immutable and conflates invocation data with undo state.
+21 files use this convention.
+
+**Sub-problem C -- Untyped CommandContext:** `CommandContext` lacks a
+`getActiveBuffer` definition, causing 69 casts of the form
+`(ctx as { getActiveBuffer?: ... })` across plugin files.
+
+#### Solution
+
+**Part A -- Generic Command\<P\>:**
+
+- Make `Command<P>` and `CommandDefinition<P>` generic over a params type `P`
+- Each plugin declares a typed interface for its params:
+
+```typescript
+interface DrawRectParams {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  color: string;
+}
+```
+
+- The dispatcher and registries store `Command<any>` at the storage boundary
+  (type erasure at the collection level is expected and acceptable)
+- ~25 param interfaces to write; eliminates ~170 field casts
+
+**Part B -- Separate snapshot from params:**
+
+- Add a dedicated `snapshot: unknown` slot on the undo stack entry
+- `execute()` return value (or a callback/setter) provides the snapshot data:
+
+```typescript
+execute(params: P, ctx: CommandContext): SnapshotData | void;
+undo(params: P, ctx: CommandContext, snapshot: SnapshotData): void;
+```
+
+- Params become truly immutable invocation data
+- The `_snapshot` convention disappears from all 21 files
+
+**Part C -- Typed CommandContext:**
+
+- Add `getActiveBuffer?: () => PixelBuffer | null` to the `CommandContext` interface
+- Eliminates 69 casts of `(ctx as { getActiveBuffer?: ... })`
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/core/commands.ts` | Make `Command<P>` and `CommandDefinition<P>` generic; add typed `CommandContext` with `getActiveBuffer` |
+| `src/lib/core/dispatcher.ts` | Accept snapshot return from `execute()`, store on `UndoEntry`, pass to `undo()` |
+| `src/lib/core/registries.svelte.ts` | Store `CommandDefinition<any>` in the registry |
+| All 23 files in `plugins/builtin/` | Define param interfaces, remove `as` casts, remove `_snapshot` from params |
+| `src/lib/ui/menu-commands-plugin.ts` (or split successors) | Remove `ctx` casts |
+| `plugins/builtin/drawing-utils.ts` | Update `snapshotPixels`/`applyPixels` if the snapshot interface changes |
+
+#### Cast Elimination Summary
+
+| Cast Category | Count | Fix |
+|--------------|-------|-----|
+| `params.field as Type` | ~170 | Typed param interfaces |
+| `(ctx as { getActiveBuffer? })` | 69 | Typed CommandContext |
+| `_snapshot` mutations on params | ~24 | Dedicated snapshot slot |
+| **Total** | **~263** | |
+
+#### Verification
+
+- `tsc --noEmit` passes with zero errors
+- All tools, effects, and commands work as before
+- Undo/redo functions correctly for all commands
+- No `as unknown` or `as any` casts remain in plugin files (beyond the storage boundary)
+
+---
+
+## Phase 3: Undoable Flag
+
+Requires typed commands from Phase 2 for proper `dispatch()` call construction.
+
+---
+
+### Decision #1: Add undoable Flag to CommandDefinition
+
+**Effort:** Medium
+
+**Depends on:** #20 (Generic Command\<P\>) should ideally come first since the
+dispatch call sites need proper `Command` construction. Can be done independently
+with empty params/context as a stopgap.
+
+#### Problem
+
+All 4 UI entry points (menu bar, toolbar, context menu, command palette) call
+`cmd.execute({}, {})` directly, bypassing the dispatcher. For UI-only commands
+(zoom, theme, dialogs) this is fine and desirable. But destructive commands
+(flatten_image, resize_canvas, merge_down, cut, paste) triggered from menus
+are non-undoable because they never pass through the undo stack.
+
+#### Solution
+
+Add an `undoable?: boolean` field to `CommandDefinition`. UI entry points check the
+flag at invocation time:
+
+- `undoable: true` -- route through `dispatch()` (goes onto the undo stack)
+- `undoable: false` or `undefined` -- call `execute()` directly (current behavior)
+
+**Commands that need `undoable: true`** (~15 total):
+
+- `flatten_image`
+- `resize_canvas`
+- `crop_to_selection`
+- `merge_down`
+- `cut`
+- `paste`
+- `select_all`
+- `invert_selection`
+- `select_by_color`
+- Any other destructive or data-mutating command triggered from UI
+
+**Commands that must NOT be marked undoable:**
+
+- `undo` and `redo` (they call `undoLast`/`redoLast` directly -- marking them
+  undoable would create an infinite recursion)
+- All view/zoom commands (non-destructive, no undo needed)
+- Dialog-opening commands (no data mutation)
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/core/commands.ts` | Add `undoable?: boolean` to `CommandDefinition` |
+| `src/lib/ui/menu-builder.ts` | Check `undoable` flag; route through `dispatch()` if true |
+| `src/lib/ui/ToolbarPanel.svelte` | Same routing logic |
+| `src/lib/dock/TabAddMenu.svelte` | Same routing logic |
+| `src/lib/ui/ContextMenu.svelte` | Same routing logic |
+| `src/lib/ui/command-palette/command-palette-state.svelte.ts` | Same routing logic |
+| `src/lib/ui/menu-commands-plugin.ts` | Mark ~15 destructive commands as `undoable: true` |
+
+#### Verification
+
+- Trigger `flatten_image` from the menu: it should appear on the undo stack
+- Press Ctrl+Z: the flatten is undone
+- Trigger `zoom_in` from the menu: it should NOT appear on the undo stack
+- `undo`/`redo` commands still work as direct calls
+
+---
+
+## Phase 4: Dialog / UI Work
+
+Independent of the command system. Can be done in parallel with Phase 2/3 if
+different developers are available.
+
+---
+
+### Decision #22: Native \<dialog\> Element for Modals
+
+**Effort:** Medium (restyling `::backdrop`, testing in Tauri WebView)
+
+**Depends on:** Nothing
+
+#### Problem
+
+All 3 modal dialogs (NewProject, Export, About) plus CommandPalette lack:
+
+- Focus traps (Tab key escapes to elements behind the overlay)
+- `role="dialog"` attribute
+- `aria-modal="true"` attribute
+- Proper Escape key handling (AboutDialog has none at all)
+
+These are implemented as `<div class="modal-overlay">` with manual event handlers.
+
+#### Solution
+
+Replace `<div class="modal-overlay">` with the native `<dialog>` element using
+`.showModal()`. The browser provides all of the following for free:
+
+- Focus trap (Tab stays within the dialog)
+- Escape key closes the dialog
+- `::backdrop` pseudo-element for the overlay
+- `role="dialog"` and `aria-modal="true"` automatically
+- Top-layer rendering (no z-index wars)
+
+This is ideal for Tauri's Chromium WebView which has full `<dialog>` support.
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/ui/NewProjectDialog.svelte` | Replace `<div class="modal-overlay">` with `<dialog>`, restyle `::backdrop`, remove manual Escape handler, remove svelte-ignore comments |
+| `src/lib/ui/ExportDialog.svelte` | Same transformation |
+| `src/lib/ui/AboutDialog.svelte` | Same transformation; add Escape handling (currently missing entirely) |
+| `src/lib/ui/command-palette/CommandPalette.svelte` | Same pattern |
+| `src/lib/ui/dialog-state.svelte.ts` | May need to store dialog element refs for `.showModal()` / `.close()` |
+
+#### Key Implementation Notes
+
+- Use `dialog::backdrop` for overlay styling (replaces `.modal-overlay` CSS)
+- The `close` event on `<dialog>` fires on Escape; use it for cleanup
+- Call `.showModal()` in a Svelte `$effect` when the dialog state becomes open
+- Call `.close()` when the state becomes closed
+- Test in Tauri WebView specifically -- Chromium's `<dialog>` works but verify
+  backdrop click behavior
+
+#### Verification
+
+- Tab key stays within each dialog (focus trap works)
+- Escape closes each dialog
+- Backdrop click closes each dialog (if desired behavior)
+- Screen readers announce the dialogs correctly
+- Dialogs render correctly in Tauri desktop build
+
+---
+
+### Decision #26: Build Reusable PromptDialog Component
+
+**Effort:** Small-Medium
+
+**Depends on:** #22 (native \<dialog\>) -- the PromptDialog should use `<dialog>`
+from the start
+
+#### Problem
+
+Two `prompt()` calls exist in `menu-commands-plugin.ts`:
+
+1. Resize canvas (asks for new dimensions)
+2. Set frame duration (asks for milliseconds)
+
+`window.prompt()` has critical platform issues:
+
+- Fails silently on macOS in Tauri (returns null without showing)
+- Unreliable on Linux in Tauri
+- Ugly, non-themeable, blocks the main thread
+
+#### Solution
+
+Create a generic `PromptDialog.svelte` component with:
+
+- Title string
+- Message / label string
+- Default value
+- Validation callback (returns error string or null)
+- onConfirm / onCancel callbacks
+- Uses native `<dialog>` per Decision #22
+
+Wire through `dialogState` so any command can open a prompt:
+
+```typescript
+dialogState.openPrompt({
+  title: 'Resize Canvas',
+  message: 'Enter new width:',
+  defaultValue: '64',
+  validate: (v) => isNaN(Number(v)) ? 'Must be a number' : null,
+  onConfirm: (value) => { /* use value */ },
+});
+```
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/ui/PromptDialog.svelte` | **Create** -- generic single-input modal using native `<dialog>` |
+| `src/lib/ui/dialog-state.svelte.ts` | Add prompt dialog state: open/close, config object, callback storage |
+| `src/App.svelte` | Render `<PromptDialog>` when prompt state is open |
+| `src/lib/ui/menu-commands-plugin.ts` (or split successors) | Replace `prompt()` calls with `dialogState.openPrompt()` |
+
+#### Verification
+
+- Resize canvas command opens a themed dialog, not a browser prompt
+- Entering a valid number resizes the canvas
+- Entering invalid input shows a validation error
+- Pressing Escape or Cancel closes without action
+- Works on macOS Tauri, Linux Tauri, and web browser
+
+---
+
+## Phase 5: God File Split
+
+Easier after Phase 3 (#1, undoable flag) and Phase 4 (#26, PromptDialog replaces
+`prompt()` calls). This is the largest single decision by line count but is mostly
+mechanical.
+
+---
+
+### Decision #14: Full 8-File Domain Split of menu-commands-plugin.ts
+
+**Effort:** Large (but mostly mechanical cut-and-paste)
+
+**Depends on:**
+- #1 (undoable flag) -- the split files need to mark commands correctly
+- #26 (PromptDialog) -- should come first to eliminate `prompt()` calls during the split
+
+#### Problem
+
+`menu-commands-plugin.ts` is 1333 lines containing:
+
+- 42 commands
+- 55 menu items
+- 9 toolbar items
+- Duplicated zoom logic (also in `input-handler.ts` and `CanvasViewport.svelte`)
+- Clipboard state management
+- DOM queries for viewport center
+- `prompt()` calls
+
+This is a maintenance bottleneck. Any change to one domain (e.g., animation) requires
+navigating a 1300-line file. Merge conflicts are frequent because every feature
+touches this file.
+
+#### Solution
+
+Split into 8 domain files + 3 shared utilities. Delete the original file entirely.
+
+**New domain files** (each is a `PluginModule` auto-discovered by `bootstrap.ts`
+via the existing `import.meta.glob` pattern):
+
+| File | Contents | ~Lines |
+|------|----------|--------|
+| `src/lib/ui/file-commands.ts` | `new_project_dialog`, `open_file_dialog`, `save_project`, `export_dialog` | 80 |
+| `src/lib/ui/edit-commands.ts` | `undo`, `redo`, `cut`, `copy`, `paste`, `select_all` + deselect menu item | 150 |
+| `src/lib/ui/image-commands.ts` | `resize_canvas`, `crop_to_selection`, `flatten_image`, `canvas_size` | 120 |
+| `src/lib/ui/layer-menu-commands.ts` | `merge_down`, `move_layer_up`, `move_layer_down` + 3 menu-only items | 100 |
+| `src/lib/ui/animation-menu-commands.ts` | `play_animation`, `set_frame_duration_dialog` + 3 menu-only items | 80 |
+| `src/lib/ui/select-commands.ts` | `invert_selection`, `select_by_color` + shared menu items | 60 |
+| `src/lib/ui/view-commands.ts` | All 17 view commands + 9 toolbar items | 350 |
+| `src/lib/ui/help-commands.ts` | `about`, `keyboard_shortcuts`, `report_bug` | 70 |
+
+Note: Files use `-menu-commands` suffix where they would collide with existing
+domain command files (e.g., `layer-menu-commands.ts` avoids colliding with any
+existing `layer-commands.ts`).
+
+**Shared utilities to extract** (eliminates duplication beyond the god file):
+
+| File | Contents | Deduplication Benefit |
+|------|----------|---------------------|
+| `src/lib/canvas/zoom-utils.ts` | `ZOOM_STEPS`, `zoomStepUp()`, `zoomStepDown()`, `DEFAULT_ZOOM` | Eliminates triplication across `input-handler.ts`, `CanvasViewport.svelte`, and the god file |
+| `src/lib/canvas/viewport-utils.ts` | `viewportCenter()` function | Replaces `document.querySelector('.canvas-viewport')` DOM queries |
+| `src/lib/edit/clipboard-state.ts` | `clipboardBuffer` type and reactive state | Isolates clipboard concern |
+
+**The original `src/lib/ui/menu-commands-plugin.ts` is deleted entirely.**
+
+#### Migration Strategy
+
+1. Create the 3 shared utilities first
+2. Create the 8 domain files one at a time, moving commands and menu items
+3. After each file is created, verify `tsc --noEmit` passes and the commands work
+4. Delete `menu-commands-plugin.ts` only after all commands are migrated
+5. Verify `bootstrap.ts` discovers all new plugin modules
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/canvas/zoom-utils.ts` | **Create** -- shared zoom constants and functions |
+| `src/lib/canvas/viewport-utils.ts` | **Create** -- viewport center calculation |
+| `src/lib/edit/clipboard-state.ts` | **Create** -- clipboard buffer state |
+| `src/lib/ui/file-commands.ts` | **Create** |
+| `src/lib/ui/edit-commands.ts` | **Create** |
+| `src/lib/ui/image-commands.ts` | **Create** |
+| `src/lib/ui/layer-menu-commands.ts` | **Create** |
+| `src/lib/ui/animation-menu-commands.ts` | **Create** |
+| `src/lib/ui/select-commands.ts` | **Create** |
+| `src/lib/ui/view-commands.ts` | **Create** |
+| `src/lib/ui/help-commands.ts` | **Create** |
+| `src/lib/ui/menu-commands-plugin.ts` | **Delete** |
+| `src/lib/canvas/input-handler.ts` | **Update** -- import from `zoom-utils.ts` instead of local constants |
+| `src/lib/ui/CanvasViewport.svelte` | **Update** -- import from `zoom-utils.ts` instead of local constants |
+
+#### Verification
+
+- All 42 commands still appear in the command palette
+- All 55 menu items still appear in correct menus
+- All 9 toolbar items still appear in correct toolbars
+- Zoom from keyboard, mouse wheel, and menu all use the same step logic
+- `tsc --noEmit` passes
+- `bootstrap.ts` logs discovery of all 8 new plugin modules
+
+---
+
+## Phase 6: Plugin API Expansion
+
+Best done after the god file split (#14) since `menu-commands-plugin.ts` will have
+been reorganized into smaller files.
+
+---
+
+### Decision #12: Add getSelection() to PluginAPI
+
+**Effort:** Small
+
+**Depends on:** #14 (god file split) should happen first since `menu-commands-plugin.ts`
+will be reorganized
+
+#### Problem
+
+`menu-commands-plugin.ts` directly imports selection state (`hasSelection`,
+`getSelectedPixels`, `selectRect`, `deselect`) from
+`plugins/builtin/selection-tool.ts`. This breaks the plugin boundary -- one plugin
+reaches into another plugin's internal module.
+
+#### Solution
+
+Add a `getSelection()` method to `PluginAPI` returning a read-only selection interface:
+
+```typescript
+interface SelectionView {
+  hasSelection(): boolean;
+  getSelectedPixels(): ReadonlySet<string>;
+}
+
+// On PluginAPI:
+getSelection(): SelectionView;
+```
+
+For mutations (selecting, deselecting), replace direct function calls with
+`dispatch()` calls to the existing `select_rect` and `deselect` commands. This
+keeps the plugin boundary intact: reads go through the API, writes go through
+the command system.
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/core/plugin-types.ts` | Add `getSelection(): SelectionView` to `PluginAPI` interface |
+| `src/lib/core/plugin-api.ts` | Implement `getSelection()` by importing from `selection-tool.ts` internally |
+| `src/lib/ui/menu-commands-plugin.ts` (or split successors) | Replace direct imports with `api.getSelection()` reads and `api.dispatch()` mutations |
+| `plugins/builtin/selection-tool.ts` | No changes needed (exports remain for internal use within that plugin) |
+
+#### Verification
+
+- `cut` command still works (reads selection via API)
+- `crop_to_selection` still works
+- `select_all` and `deselect` still work (via dispatch)
+- No direct imports of `selection-tool.ts` remain in UI command files
+
+---
+
+### Decision #13: Add Mutator Methods to PluginAPI Incrementally
+
+**Effort:** Medium-Large (but each step is independently shippable)
+
+**Depends on:** Nothing (can be done incrementally at any time)
+
+#### Problem
+
+All 3 importers bypass the `PluginAPI` entirely to set canvas size, add layers/frames,
+and write pixel data. The API currently only has read-only getters that return `unknown`.
+Approximately 15 new methods are needed to let importers work through the API.
+
+#### Solution
+
+Add mutator methods in 6 incremental steps. Each step is independently shippable
+and testable.
+
+**Step 1 -- Canvas:**
+
+| Method | Signature |
+|--------|-----------|
+| `setCanvasSize` | `(width: number, height: number) => void` |
+
+**Step 2 -- Layers:**
+
+| Method | Signature |
+|--------|-----------|
+| `addLayer` | `(name: string, opts?: LayerOptions) => LayerId` |
+| `addGroup` | `(name: string, opts?: GroupOptions) => GroupId` |
+| `setLayerVisibility` | `(id: LayerId, visible: boolean) => void` |
+| `setLayerOpacity` | `(id: LayerId, opacity: number) => void` |
+| `resetLayers` | `() => void` |
+
+**Step 3 -- Frames:**
+
+| Method | Signature |
+|--------|-----------|
+| `addFrame` | `(opts?: FrameOptions) => FrameIndex` |
+| `getFrames` | `() => ReadonlyArray<FrameInfo>` |
+| `setFrameDuration` | `(index: number, ms: number) => void` |
+| `setCurrentFrame` | `(index: number) => void` |
+| `setGlobalFps` | `(fps: number) => void` |
+| `resetFrames` | `() => void` |
+
+**Step 4 -- Pixel Data:**
+
+| Method | Signature |
+|--------|-----------|
+| `createPixelBuffer` | `(width: number, height: number) => PixelBuffer` |
+| Pixel data setters | (exact API depends on PixelBuffer interface) |
+
+**Step 5 -- Palette:**
+
+| Method | Signature |
+|--------|-----------|
+| `setProjectPalette` | `(palette: Color[]) => void` |
+
+**Step 6 -- Composite:**
+
+| Method | Signature |
+|--------|-----------|
+| `resetProject` | `() => void` (clears layers + frames + canvas to defaults) |
+
+After each step, migrate one importer to use the new API methods. All implementations
+are thin wrappers around existing module functions.
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `src/lib/core/plugin-types.ts` | Expand `PluginAPI` interface with each step's methods |
+| `src/lib/core/plugin-api.ts` | Implement methods as thin wrappers around existing module functions |
+| `plugins/builtin/importers/aseprite-importer-plugin.ts` | Migrate to API calls |
+| `plugins/builtin/importers/piskel-importer-plugin.ts` | Migrate to API calls |
+| `plugins/builtin/importers/sky-spec-plugin.ts` | Migrate to API calls |
+
+#### Verification (per step)
+
+- After each step: `tsc --noEmit` passes
+- After migrating each importer: import a test file, verify layers/frames/pixels are correct
+- After all migrations: no direct imports of internal state modules remain in importer files
+
+---
+
+## Phase 7: Strict TypeScript Flags
+
+Last phase. Benefits from all prior type improvements (especially #20). Touches
+nearly every file in the codebase.
+
+---
+
+### Decision #19: Enable All 5 Strict TypeScript Flags
+
+**Effort:** Large (multi-hour, but can be done incrementally flag by flag)
+
+**Depends on:** #20 (Generic Command\<P\>) since the command params type changes
+will interact with index access patterns
+
+#### Problem
+
+`tsconfig.app.json` does not enable several strict flags that would catch real bugs
+at compile time. The current codebase has latent type safety issues that are invisible
+to the compiler.
+
+#### Solution
+
+Enable all 5 flags in `tsconfig.app.json`, in order of ascending blast radius:
+
+| Order | Flag | Current Errors | Fix Strategy | Estimated Time |
+|-------|------|---------------|-------------|----------------|
+| 1 | `noFallthroughCasesInSwitch` | 0 | Enable immediately, no fixes needed | 1 min |
+| 2 | `noUnusedLocals` + `noUnusedParameters` | 7 | Delete dead imports and unused variables | 10 min |
+| 3 | `exactOptionalPropertyTypes` | 11 | Narrow types before passing, or change the target type to accept `undefined` explicitly | 30-60 min |
+| 4 | `noUncheckedIndexedAccess` | 470 | 257 in tests (add `!` assertions where values are known to exist), 213 in prod (case-by-case null checks). Surfaces real latent bugs. | 2-3 hours |
+| 5 | `noPropertyAccessFromIndexSignature` | 698 | Force bracket notation on index signature access. Significant overlap with `noUncheckedIndexedAccess` fixes. | 2-3 hours |
+
+**Total: ~470 errors in 54+ files for `noUncheckedIndexedAccess`, ~698 errors in 44+
+files for `noPropertyAccessFromIndexSignature`.**
+
+#### Recommended Approach
+
+Enable one flag at a time. After each flag:
+
+1. Add the flag to `tsconfig.app.json`
+2. Run `tsc --noEmit` to get the error list
+3. Fix all errors
+4. Commit
+5. Move to the next flag
+
+This prevents a massive all-at-once PR and lets each flag's fixes be reviewed
+independently.
+
+#### Files to Change
+
+| File | Action |
+|------|--------|
+| `tsconfig.app.json` | Add flags incrementally |
+| 54+ files across the codebase | Fix `noUncheckedIndexedAccess` errors |
+| 44+ files across the codebase | Fix `noPropertyAccessFromIndexSignature` errors |
+| ~7 files | Fix unused locals/params |
+| ~11 files | Fix `exactOptionalPropertyTypes` errors |
+
+#### Important Notes
+
+- `noUncheckedIndexedAccess` will surface real latent bugs (array access without
+  bounds checking, map access without existence checking). These are worth fixing
+  properly, not just suppressing with `!`.
+- In test files, `!` assertions are acceptable since the test data is controlled.
+- In production code, prefer proper null checks or early returns.
+
+#### Verification
+
+- `tsc --noEmit` passes with all 5 flags enabled
+- No runtime regressions (the fixes should be compile-time only)
+- No `as any` or `@ts-ignore` comments added to suppress errors
+
+---
+
+## Implementation Order Summary
+
+| Phase | Decisions | Key Rationale | Parallel? |
+|-------|-----------|---------------|-----------|
+| 1 | #24 (makeStrokeTool) + #25 (makeSnapshotUndo) | DRY factories, fully isolated, no dependencies | Yes, both in parallel |
+| 2 | #20 (Generic Command\<P\> + snapshot + CommandContext) | Type system foundation -- all later phases benefit | Single item |
+| 3 | #1 (undoable flag) | Needs typed commands from #20 for proper dispatch | Single item |
+| 4 | #22 (native \<dialog\>) + #26 (PromptDialog) | Dialog/UI work, independent of command system | Yes, #22 first, then #26 |
+| 5 | #14 (god file split) | Easier after #1 (undoable flag) and #26 (PromptDialog) | Single item |
+| 6 | #12 (getSelection API) + #13 (mutator methods) | Plugin API expansion, benefits from split files | Yes, both in parallel |
+| 7 | #19 (strict TS flags) | Last -- touches everything, benefits from all prior type improvements | Single item, incremental |
+
+**Dependency graph** (read as "X must come before Y"):
+
+- #20 must come before #1 (undoable flag needs typed Command construction)
+- #20 should come before #19 (strict flags interact with command param types)
+- #22 must come before #26 (PromptDialog uses native \<dialog\>)
+- #1 should come before #14 (split files need undoable markings)
+- #26 should come before #14 (split eliminates prompt() calls)
+- #14 should come before #12 (split files are the consumers of getSelection API)
+- #25 may need updating after #20 (if snapshot signature changes)
+
+---
+
+## Effort Summary
+
+| Decision | Effort | Approximate Duration |
+|----------|--------|---------------------|
+| #24 makeStrokeTool | Small | 1-2 hours |
+| #25 makeSnapshotUndo | Small | 1-2 hours |
+| #20 Generic Command\<P\> | Large | 6-10 hours |
+| #1 Undoable flag | Medium | 3-4 hours |
+| #22 Native \<dialog\> | Medium | 3-4 hours |
+| #26 PromptDialog | Small-Medium | 2-3 hours |
+| #14 God file split | Large | 6-8 hours |
+| #12 getSelection API | Small | 1-2 hours |
+| #13 Mutator methods | Medium-Large | 6-8 hours |
+| #19 Strict TS flags | Large | 6-8 hours |
+| **Total** | | **~35-51 hours** |