pixelweaver 0.1.0

package/todo/.done/pixelweaver-full-build.md

@@ -0,0 +1,937 @@
+# PixelWeaver -- Full Build Plan
+
+## Context
+
+PixelWeaver is a web-based pixel art sprite editor inspired by GameMaker's classic sprite editor, but with modern capabilities: semantic action history, layer-group-based variant generation, a full isometric level editor, MCP tool server for LLM integration, and a fully plugin-based architecture. It ships as a Tauri desktop application (with the browser+server option for Firefox compatibility).
+
+It is a personal tool -- opinionated, keyboard-driven, no hand-holding. The primary workflow is animation-focused: creating, editing, and previewing multi-frame sprite animations. Both raw pixel editing and structured spec awareness (semantic drawing commands) are first-class.
+
+Born out of dissatisfaction with existing pixel editors and the desire to close the loop between LLM-generated sprite specs and visual editing.
+
+### Key Design Decisions
+
+- All phases are parallel work units for subagents, not sequential releases. Everything ships together.
+- All built-in tools are plugins from day 1 -- there is no special "built-in" code path.
+- No separate "zone" concept exists. Layer groups replace zones entirely.
+- Projects support multiple canvases, each with an independent layer tree.
+- Tauri packaging is included from the start. The app expects the user has `uv` installed for the Python server.
+
+## Architecture
+
+| Layer | Technology | Role |
+|---|---|---|
+| Desktop Shell | Tauri | Native window, system integration, expects user has `uv` installed |
+| Frontend | Svelte 5 (runes) + Pure Vite SPA (no SvelteKit) | Dark creative tool UI, minimal canvas layout, collapsible panels |
+| Canvas | HTML Canvas 2D | All pixel editing, rendering, zoom/pan, pressure sensitivity via Pointer Events API |
+| Core | Command dispatcher (4 consumers from day 1) | Every action is a Command. Dispatch feeds canvas executor, undo system, semantic log, spec export |
+| Plugins | ES modules | Everything is a plugin (tools, panels, exporters, commands). Core is just canvas + dispatcher + plugin loader |
+| Server | Python FastAPI (API only) | File I/O, MCP endpoint, project management. Vite serves frontend (with HMR in dev) |
+| Protocol | WebSocket | All communication: commands, confirmations, MCP push, state sync |
+| Storage | PNG frames + JSON metadata | Project files on disk as a directory structure |
+
+### Sync Model: Server-Authoritative + Optimistic UI
+
+The server owns ALL state. The browser renders optimistically (applies commands locally for instant feedback), and the server confirms or rejects. On conflict, server state wins.
+
+- Commands flow: UI -> WebSocket -> Server (validates, persists, broadcasts) -> UI confirmation
+- MCP commands follow the same path through the server
+- Server state: in-memory + periodic disk flush (configurable debounce, e.g. 500ms after last command, + interval, e.g. every 30s)
+
+### WebSocket Protocol
+
+WebSocket is the sole communication channel between frontend and server. Covers:
+
+- Command submission and confirmation
+- MCP push notifications
+- State synchronization
+- Auto-reconnect with exponential backoff + full state reconciliation on reconnect
+
+### Command Dispatcher (Central Nervous System)
+
+Every user action -- whether triggered by mouse click, keyboard shortcut, or MCP tool call -- becomes a Command object that flows through a single dispatch system. All four consumers are active from day 1:
+
+- **Canvas executor**: applies the command to the pixel buffer
+- **Undo system**: records the command (with inverse) in the undo stack
+- **Semantic log**: appends a human-readable description ("drew line from (2,3) to (15,8) in #FF0000")
+- **Spec export**: serializes the command for pipeline-compatible output
+
+Adding a new tool means: define the command type, implement the executor, done -- it is automatically available via UI, MCP, undo, and export.
+
+### Plugin System (From Day 1)
+
+Everything is a plugin, including all built-in tools. There is no separate built-in code path. The core is minimal:
+
+- Canvas with zoom/pan/input routing
+- Command dispatcher
+- Plugin loader (respects declared dependency order)
+- Project format reader/writer
+
+Plugin boundary: ES modules. Each plugin exports registration functions:
+
+```js
+export function register(api) {
+  api.addCommand("draw_line", { execute, undo, describe });
+  api.addTool("line", { icon, cursor, onPointerDown, onPointerMove, onPointerUp });
+  api.addPanel("line-options", { component: LineOptionsPanel });
+}
+```
+
+No manifest files, no sandboxing (trust-based). Plugins declare explicit dependency arrays in `register()`. Dynamic imports from a plugins directory. Built-in plugins ship in the same format as third-party ones.
+
+### Migration Strategy
+
+Each command is tagged with plugin name + version. Each plugin owns its own schema compatibility -- there is no global migration system. When a plugin's command format changes, that plugin is responsible for reading its own older formats.
+
+### Companion Server (Python FastAPI)
+
+Required because File System Access API is Chrome/Edge only (Firefox will never support it). The server is API-only -- Vite serves the frontend (with HMR in dev).
+
+Server responsibilities:
+
+- **File CRUD**: read/write/list/delete project files on disk
+- **Project management**: list projects, create new, open existing
+- **File watching**: detect external changes (e.g. edits in VS Code)
+- **MCP endpoint**: exposes the same Command dispatch as the UI over MCP protocol
+- **State authority**: server is the single source of truth for all project state
+- **Periodic flush**: in-memory state with configurable debounce + interval disk writes
+
+Server discovery: configurable port with sensible default (e.g. 7779).
+
+### CLI
+
+Full CLI interface:
+
+| Command | Description |
+|---|---|
+| `pixelweaver serve` | Start the server (API + file serving) |
+| `pixelweaver export` | Export project from command line |
+| `pixelweaver new` | Create a new project |
+| (extensible) | Additional subcommands as needed |
+
+### Tauri Packaging
+
+Tauri wraps the application from the start. The Tauri shell:
+
+- Launches the Python FastAPI server as a sidecar process (expects user has `uv` installed)
+- Opens the frontend in a native window
+- Provides system integration (native menus, file dialogs, etc.)
+
+The browser+server option remains available for Firefox users or those who prefer it.
+
+### Project Format (PNG + JSON)
+
+Each project is a directory on disk. Projects support multiple canvases, each with an independent layer tree.
+
+```
+my-project/
+  project.json          -- metadata: project name, canvas list, global palette, settings
+  canvases/
+    main/
+      canvas.json       -- canvas size, layer tree structure, origin point
+      frames/
+        0/
+          layer-0.png   -- pixel data for layer 0, frame 0
+          layer-1.png   -- pixel data for layer 1, frame 0
+          ...
+        1/
+          layer-0.png
+          ...
+      history.json      -- command history for this canvas
+    attack/
+      canvas.json
+      frames/
+        ...
+      history.json
+  variants/
+    gold-armor.json     -- layer group palette overrides
+  exports/              -- generated output (PNG, spritesheets)
+```
+
+Command history is persisted from day 1. Each command is tagged with its plugin name + version for forward compatibility.
+
+### Crash Safety
+
+- Service worker + IndexedDB auto-recovery
+- On crash or unexpected close, unsaved state is recoverable from IndexedDB
+- On next launch, the app detects incomplete state and offers recovery
+
+## Layers
+
+Layers are a cross-cutting feature that affects canvas, tools, undo, project format, animation, and export.
+
+### Layer Model
+
+- Layer structure is shared across all frames within a canvas (same tree, different pixel content per frame)
+- Each frame has independent pixel data for each layer
+- Layer types: pixel layer, layer group
+- Layer groups are nestable (groups can contain groups)
+- Layer groups REPLACE zones entirely -- there is no separate zone concept
+
+### Layer Properties
+
+| Property | Description |
+|---|---|
+| Name | User-defined label |
+| Visibility | Show/hide toggle |
+| Opacity | 0-100% |
+| Blend mode | Normal, Multiply, Screen, etc. (extensible via plugins) |
+| Lock | Prevent edits |
+
+### Layer Panel UI
+
+- Tree view with indentation for nested groups
+- Expand/collapse groups
+- Drag-and-drop reordering (including into/out of groups)
+- Right-click context menu: rename, duplicate, merge down, flatten group, delete
+- Layer thumbnail preview
+
+### Layer Implications
+
+| System | Impact |
+|---|---|
+| Canvas rendering | Composite layers in order with blend modes and opacity |
+| Drawing tools | Operate on the active layer only |
+| Undo | Layer operations are undoable commands (add, delete, reorder, merge, etc.) |
+| Project format | Per-layer PNG files within each frame directory |
+| Animation | Layer tree is shared across frames; pixel data is per-frame-per-layer |
+| Export | Flatten layers on export; optionally export individual layers |
+| Variants | Palette swaps apply per layer group (see Variants phase) |
+| Selection | Selection tools operate within the active layer |
+
+## Multi-Canvas Projects
+
+A single project can contain multiple canvases, each with:
+
+- Independent canvas dimensions
+- Independent layer tree
+- Independent frame set and animation timeline
+- Independent command history and undo stack
+- An origin point for composite preview positioning
+
+### Multi-Canvas Preview
+
+A composite preview mode shows multiple canvases rendered together at their respective origin points. Useful for checking how separate sprite parts (body, weapon, effects) align when composited in-game.
+
+## UI Design
+
+### Layout: Minimal Canvas
+
+Canvas dominates the screen. All panels are collapsible overlays/sidebars:
+
+- **Menu bar** (top): File, Edit, View, Tools, Plugins
+- **Tool bar** (left): tool icons, vertical, collapsible
+- **Properties panel** (right): context-sensitive (color picker, tool options, layer list), collapsible
+- **Layer panel** (right or left): tree view of layers with expand/collapse for groups
+- **Frame strip** (bottom): classic GM horizontal filmstrip, collapsible
+- **Status bar** (bottom): coords, zoom %, color, frame #, active layer
+- All panels can be hidden for maximum canvas space
+
+### Theming
+
+- Dark + light themes
+- Implemented via CSS variables, switchable at runtime
+- Default: dark theme (dark gray panels, accent colors for selection/active states, high contrast canvas area)
+- Modeled after Blender/Aseprite/Figma dark themes
+
+### Guides and Grids
+
+- Custom configurable grids (pixel grid at high zoom, user-defined spacing)
+- Draggable horizontal and vertical guide lines
+- Snap-to-guide for drawing tools and selections
+
+## Phase 1 -- Core Editor
+
+**Milestone: you can draw, layer, and save pixel art.**
+
+### Canvas System
+
+- HTML Canvas 2D rendering
+- Zoom: scroll wheel or +/- keys, pixel grid visible at high zoom levels
+- Pan: middle-click drag or spacebar + drag
+- Canvas sizes: up to 512x512 (arbitrary dimensions within this limit)
+- Cursor shows current tool shape and color
+- Pixel coordinates displayed in status bar
+- Tile/wrap mode: drawing wraps across canvas edges (for seamless tile creation)
+- Pressure sensitivity via Pointer Events API (affects brush size/opacity for supporting tools)
+
+### Layers (Core Feature)
+
+- Full layer system as described in the Layers section above
+- Layer groups (nestable)
+- Layer panel with tree view UI
+- Layer operations: add, delete, duplicate, merge, reorder, group/ungroup
+- All layer operations are commands in the dispatcher (undoable, logged, etc.)
+
+### Drawing Tools (Phase 1 Subset -- All Plugins)
+
+All tools are plugins from day 1. Phase 1 ships these built-in plugins:
+
+- **Pencil**: single pixel placement, click-drag for freehand, pressure-sensitive size
+- **Eraser**: set pixels to transparent, variable size, pressure-sensitive
+- **Eyedropper**: pick color from canvas, activate with Alt+click from any tool
+- **Fill bucket**: flood fill contiguous same-color region
+- **Line**: click-drag, Bresenham rendering
+- **Rectangle**: click-drag for filled or outline, hold Shift for square
+- **Circle/Ellipse**: click-drag for filled or outline, hold Shift for perfect circle
+- **Diamond**: isometric diamond shape, essential for terrain tiles
+
+### Perfect Pixel Lines
+
+Two modes available as separate plugins, user chooses which to enable:
+
+- **Standard Bresenham**: classic pixel line rendering
+- **No-doubles Bresenham**: prevents two adjacent pixels on the minor axis to avoid staircase artifacts
+
+### Color System
+
+- Color picker: headless color library (`culori`) + custom Svelte UI
+- All color spaces: HSV + HSL + RGB + Hex input
+- Foreground/background color (swap with X key)
+- Recent colors strip (last N used colors)
+- **Palette lock** (from the start): define a fixed palette, restrict drawing to those colors
+- Smart palette tracking: auto-collects all colors used in the project, supports bulk recolor
+- **Global palettes**: app-wide palettes including presets (PICO-8, GameBoy, etc.) AND per-project palettes
+- **Palette interpolation**: lerp between palette presets for variant generation
+
+### Command Dispatcher
+
+- Command objects: `{ type, plugin, version, params, timestamp }`
+- Execute + inverse for every command (enables undo)
+- Dispatch pipeline: validate -> execute -> record (4 consumers)
+- Human-readable `describe()` for each command type
+- Commands tagged with plugin name + version for migration
+
+### Undo/Redo
+
+- **Linear stack with parent pointers** for future branching capability
+- Two-tier undo:
+  - Per-frame drawing undo (pixel operations within a single frame/layer)
+  - Project-level operation undo (add/delete frame, reorder layers, canvas operations)
+- Per-canvas undo (switching canvases does not mix histories)
+- Command history persisted from day 1
+
+### Keyboard Shortcut System
+
+Custom shortcut system from day 1 (no tinykeys/mousetrap dependency):
+
+- Fully remappable shortcuts
+- Default keybindings inspired by Aseprite (single letter for tools: B=brush, E=eraser, G=fill, etc.)
+- Shortcut editor panel: search, rebind, reset to defaults
+- Support for modifier combos (Ctrl+, Shift+, Alt+)
+- Conflict detection
+- Import/export shortcut profiles
+
+### Command Palette (Standalone Plugin)
+
+- Ctrl+P (or configurable) opens fuzzy search
+- Searches all commands, tools, panels, recent files
+- Shows current keybinding for each item
+- Execute on Enter
+
+### Companion Server
+
+- FastAPI app, API-only (Vite serves frontend)
+- WebSocket for all communication (commands, confirmations, state sync)
+- Server-authoritative state model
+- In-memory state + periodic disk flush (configurable debounce + interval)
+- Configurable port (default 7779)
+- CLI: `pixelweaver serve`, `pixelweaver new`, etc.
+
+### Crash Safety and Auto-Save
+
+- Service worker + IndexedDB auto-recovery
+- Auto-save: configurable debounce (e.g. 500ms after last command) + interval (e.g. every 30s), both configurable
+- Recovery dialog on next launch if incomplete state detected
+
+### Save/Load
+
+- Save project to disk via companion server (directory structure with PNG + JSON)
+- Load existing project
+- New project dialog: name, canvas width, canvas height
+- Multi-canvas support: add/remove canvases within a project
+
+### Export
+
+- Export current frame as PNG
+- Export all frames as individual PNGs
+
+### Reference Image
+
+- Overlay a reference image on the canvas at adjustable opacity
+- Does not affect output -- purely a visual aid while drawing
+
+### Tauri Shell
+
+- Tauri desktop wrapper
+- Launches Python server as sidecar (expects `uv` installed)
+- Native window with system integration
+
+### Files/Dirs That Will Change
+
+- `src/` -- Svelte 5 frontend app (pure Vite SPA)
+  - `src/lib/core/` -- command dispatcher, undo stack, project format, plugin loader, plugin API
+  - `src/lib/canvas/` -- canvas rendering, zoom/pan, input handling, tile/wrap mode, pressure input
+  - `src/lib/layers/` -- layer model, layer tree, compositing, layer panel UI
+  - `src/lib/tools/` -- drawing tool plugins (pencil, eraser, line, etc.) -- all ES module plugins
+  - `src/lib/ui/` -- panels, toolbar, status bar, dialogs, command palette, theming
+  - `src/lib/color/` -- color picker (culori-based), palette management, palette lock, interpolation
+  - `src/lib/shortcuts/` -- custom shortcut system, editor panel, profiles
+  - `src/lib/sync/` -- WebSocket client, optimistic UI, reconnection logic
+  - `src/lib/recovery/` -- service worker, IndexedDB crash recovery
+- `server/` -- Python FastAPI companion server
+- `src-tauri/` -- Tauri configuration and native shell
+- `plugins/builtin/` -- all built-in tools as ES module plugins
+- `package.json`, `vite.config.js` -- project config
+- `pyproject.toml` -- server dependencies (managed with `uv`)
+- `src-tauri/tauri.conf.json` -- Tauri config
+
+### Effort: Large
+
+This is the foundational phase. Everything else builds on it. Includes canvas, layers, tools, colors, undo, shortcuts, command palette, server, WebSocket protocol, Tauri shell, crash recovery, and the full plugin system. The command dispatcher and plugin API shape everything downstream.
+
+## Phase 2 -- Animation
+
+**Milestone: you can create and export sprite animations.**
+
+### Frame Strip
+
+- Classic GM horizontal filmstrip at the bottom of the screen
+- Thumbnail preview of each frame (shows flattened layer composite)
+- Click to select and edit a frame
+- Right-click context menu: duplicate, delete, insert before/after, move left/right
+- Drag-and-drop reordering
+- Frame number labels
+- Current frame highlighted
+
+### Frame Operations
+
+- Add frame (blank or duplicate current)
+- Remove frame (with confirmation if it has content)
+- Duplicate frame
+- Reorder via drag-and-drop
+- Copy/paste frames (including across projects via clipboard -- see cross-project clipboard)
+- Unlimited frame count
+
+### Frame Timing
+
+- Global FPS setting for the animation
+- Per-frame duration overrides (individual frames can have custom timing)
+- Timing displayed in frame strip
+
+### Frame Tags
+
+- Tag ranges of frames with labels (e.g. "idle", "walk", "attack")
+- Tags support nesting (tags can contain sub-tags, e.g. "attack" contains "windup" and "strike")
+- Tags visible in the frame strip
+- Export respects tags (export tagged ranges as separate animations)
+
+### Onion Skinning
+
+- Configurable frame range (how many frames before/after to show)
+- Adjustable opacity for onion skin layers
+- Tint control (e.g. red for previous frames, blue for next frames)
+- Toggle on/off
+
+### Animation Preview
+
+- **Loop preview**: plays frames in sequence at configured FPS (respects per-frame overrides)
+- **Ping-pong**: forward then backward, common for idle animations
+- **Side-by-side**: all frames laid out next to each other simultaneously for comparison
+- **Multi-sprite preview**: load multiple canvases/projects and preview them animating side by side
+- Play/pause/step controls
+- Speed slider
+- Preview window resizable, dockable
+
+### Spritesheet Export
+
+Multiple layout options:
+
+| Layout | Description |
+|---|---|
+| Horizontal strip | All frames in a single row |
+| Grid | Configurable number of columns |
+| Texture atlas | Packed layout (minimize wasted space) |
+
+Spritesheet metadata export formats:
+
+| Format | Description |
+|---|---|
+| Custom JSON | PixelWeaver native metadata |
+| TexturePacker-compatible | For engines that import TexturePacker format |
+| Aseprite-compatible | For engines that import Aseprite JSON format |
+| CSS | For web usage (sprite positions as CSS classes) |
+
+Additional export options:
+
+- Configurable padding between frames
+- Export dialog with preview
+- Export tagged frame ranges as separate spritesheets
+
+### Origin Point
+
+- Draggable crosshair on canvas marking the sprite's origin/pivot
+- Snaps to pixel grid
+- Displayed in animation preview (useful for alignment)
+- Stored per canvas in project metadata
+
+### Cross-Project Clipboard
+
+- **Internal clipboard**: rich copy that preserves layers, commands, and metadata
+- **System clipboard**: copies as flattened PNG for pasting into other applications
+- Works for frames, selections, and layer content
+
+### Import
+
+- PNG import (single frame)
+- Spritesheet import (split into frames with configurable grid/strip settings)
+- Aseprite `.ase` import (implemented as a built-in importer plugin)
+- Piskel `.piskel` import (implemented as a built-in importer plugin)
+
+### Files/Dirs That Will Change
+
+- `src/lib/animation/` -- frame strip, preview, timeline logic, frame tags, onion skinning
+- `src/lib/export/` -- spritesheet stitcher, metadata writers (all 4 formats), layout algorithms
+- `src/lib/import/` -- PNG import, spritesheet splitter
+- `src/lib/ui/` -- frame strip panel, preview panel, export dialog, onion skin controls
+- `src/lib/clipboard/` -- cross-project clipboard (internal rich + system PNG)
+
+### Effort: Medium-Large
+
+Frame management is straightforward. Animation preview with multi-sprite support, spritesheet layouts, multiple metadata formats, frame tags with nesting, and onion skinning add up to substantial work.
+
+## Phase 3 -- Pro Drawing Tools
+
+**Milestone: full drawing toolkit for professional pixel art.**
+
+### Additional Drawing Tools (All Plugins)
+
+- **Gradient**: both dithered (Bayer pattern) and smooth (RGB interpolation), user chooses mode
+- **Noise/scatter**: random pixel placement from a color palette within a region
+- **Dither**: ordered 2x2 Bayer dither between two colors
+- **Symmetry/mirror drawing**: full system -- axis H/V/both + radial 3/4/6/8-way + custom angle. Live mirroring while drawing with any tool
+- **Contiguous fill modes**: fill same-color-only, fill with tolerance slider, fill-to-edge
+- **Selection tools**: rectangular select, lasso (freehand), move selection, copy/paste within canvas, cut, delete selection
+- **Pattern stamp**: define a small repeating pattern and paint with it as a brush
+
+### GM Classic Effects (All Plugins)
+
+All classic GameMaker sprite effects, each as a separate plugin:
+
+- Rotate, flip, stretch, skew
+- Invert colors, grayscale, colorize
+- Brightness/contrast
+- Blur (1px box blur for pixel art softening)
+
+### Effects Pipeline (Broad System)
+
+Destructive effects with live preview before committing:
+
+- Blur, sharpen
+- Outline, shadow, glow
+- All effects show a live preview on the canvas; user confirms or cancels
+- Effects operate on the active layer
+
+### Files/Dirs That Will Change
+
+- `src/lib/tools/` -- new tool plugins (gradient, noise, dither, symmetry, selection, pattern stamp)
+- `plugins/builtin/effects/` -- GM effects and pipeline effects as individual plugins
+
+### Effort: Medium-Large
+
+Many individual tools/effects to implement, but each is independent. Symmetry system with radial modes is the most complex single piece.
+
+## Phase 4 -- Semantic History
+
+**Milestone: the action log IS the spec. LLM-readable, replayable history.**
+
+### Semantic Action Log
+
+Every command's `describe()` output forms a human-readable narrative:
+
+```
+1. Created new canvas 32x32
+2. Drew diamond fill at center (16,16) radius 15x7 in #5B8C3E
+3. Applied noise scatter in region (2,2)-(30,14) with colors [#4A7A2E, #6B9C4E] at 20% density
+4. Drew isometric outline in #3D6B22
+```
+
+This is not just for display -- it IS the spec format. Exporting the log produces a document that `render.py` (or a compatible renderer) can replay. The `render.py` script exists externally; its spec format will be defined separately.
+
+### Action Log Panel
+
+- Scrollable list of all actions in the current canvas/frame
+- Each entry shows: icon, description, timestamp
+- Click to select (highlights affected pixels on canvas)
+- Right-click: edit parameters, delete, disable (skip without removing), duplicate
+- Drag to reorder (with live preview of result)
+- Filter/search within log
+
+### Command Reordering
+
+Full replay from scratch: when commands are reordered, all commands are replayed from a blank canvas in the new order. This guarantees correctness regardless of command interdependencies.
+
+### Command Replay/Modification
+
+- Select a range of commands and replay them (useful for applying a sequence to a different frame)
+- Edit command parameters inline (change a color, move a coordinate) with live preview
+
+### Macros
+
+Included as part of semantic history work:
+
+- Record a command sequence as a reusable macro
+- Macro coordinate mode: user chooses absolute or relative per macro
+- Replay macros with parameter overrides
+
+### Spec Export from History
+
+- Export the semantic log as a JSON spec compatible with `render.py`'s format
+- Round-trip: import a spec -> appears as a command sequence in the log -> edit visually -> export back to spec
+- Diff two specs visually (highlight what changed between versions)
+
+### Files/Dirs That Will Change
+
+- `src/lib/core/` -- enhanced command dispatcher with `describe()`, semantic log store
+- `src/lib/history/` -- action log panel, macro system, command replay/reorder
+- `src/lib/export/` -- spec format exporter
+- `src/lib/import/` -- spec format importer (parse `render.py` JSON specs into command sequences)
+
+### Effort: Large
+
+The semantic history is architecturally central and touches everything. Getting `describe()` right for every command, making the log editable and reorderable with live preview (full replay from scratch), macro recording, and the spec round-trip all require careful design.
+
+## Phase 5 -- MCP Integration
+
+**Milestone: Claude Code can draw, edit, and manage sprites.**
+
+### MCP Tool Strategy: Dual Layer
+
+Both auto-generated raw tools AND curated high-level LLM-friendly tools:
+
+| Tool Layer | Description |
+|---|---|
+| Auto-generated raw tools | Every command type in the registry becomes an MCP tool automatically. Parameters match command params exactly. |
+| Curated high-level tools | Hand-written LLM-friendly tools that combine multiple commands for common workflows (e.g. "draw a character outline" = multiple line/curve commands) |
+
+### MCP Concurrency
+
+Sequential locking: a mutex is held when MCP is executing a command. UI input during MCP execution is queued and processed after the MCP command completes.
+
+### MCP Read Tools
+
+Both approaches:
+
+- Separate read-only tools for querying state (get_canvas_info, get_layer_tree, get_palette, etc.)
+- Thumbnails included in mutation responses (base64 thumbnail of the affected region returned with every write operation)
+
+### Tool Categories
+
+- **Drawing tools**: draw_pixel, draw_line, draw_rect, draw_circle, draw_diamond, fill, noise, dither, gradient (all command types)
+- **Layer tools**: add_layer, remove_layer, set_active_layer, get_layer_tree, reorder_layers, group_layers
+- **Frame management**: add_frame, remove_frame, duplicate_frame, reorder_frames, set_frame
+- **Project management**: list_projects, open_project, create_project, save_project, get_project_info
+- **Canvas operations**: get_canvas_size, resize_canvas, get_pixel, get_region, list_canvases, add_canvas
+- **History operations**: undo, redo, get_action_log, replay_commands
+- **Variant operations**: set_group_palette, list_variants, generate_variant
+- **Export**: export_png, export_spritesheet, export_spec
+
+### Live Sync
+
+When an MCP tool modifies the canvas, the browser UI updates in real-time via WebSocket push. Conversely, when the user draws in the browser, the MCP state stays current. The server-authoritative model ensures consistency.
+
+### Files/Dirs That Will Change
+
+- `server/mcp.py` -- MCP server implementation, auto-tool-generation from command registry + curated tools
+- `server/sync.py` -- WebSocket sync, sequential locking / mutex
+- `src/lib/core/` -- command registry introspection API
+- `src/lib/sync/` -- client-side WebSocket listener for server-pushed updates
+
+### Effort: Medium
+
+The command dispatcher does most of the heavy lifting. MCP is a thin layer on top. The dual-layer tool strategy (auto + curated) and sequential locking add some complexity.
+
+## Phase 6 -- Variants
+
+**Milestone: layer-group-based palette swapping, bisection export, and variant generation.**
+
+Layer groups replace the former "zone" concept entirely. A layer group serves dual purpose: organizational grouping of layers AND the semantic unit for palette swapping and variant generation.
+
+### Palette Swap Panel
+
+- Each layer group has an associated color palette (the actual colors used in layers within that group)
+- Swap any color in the palette to create a variant
+- Live preview: canvas updates in real-time as you adjust group colors
+- "Extract palette" button: auto-detects the colors used within a layer group
+
+### Bisection (Export Groups Separately)
+
+Split a single finished sprite into composable overlay exports:
+
+- Select layer groups to export separately (e.g. export "armor" group as its own spritesheet)
+- The exported group contains only its layers' pixels on transparent background
+- Multiple groups can be exported and recombined by the consuming game engine
+- Preview shows the composite (all groups) animating together
+
+### Variant Generation
+
+- Define variant presets: named palette overrides per layer group (e.g. "gold armor" = armor group palette swapped to gold tones)
+- **Palette interpolation**: lerp between palette presets to generate intermediate variants
+- Variant grid: see all variants side by side
+- Randomize button: generates random palette combinations across all layer groups for rapid exploration
+- Export variants as individual spritesheets or a combined variant atlas
+
+### Files/Dirs That Will Change
+
+- `src/lib/variants/` -- palette swap engine, variant grid, randomizer, preset management, interpolation
+- `src/lib/export/` -- variant export (individual + atlas), bisection export
+- Project format: variants stored as JSON in `variants/` subdirectory
+
+### Effort: Medium-Large
+
+Palette swapping per layer group is straightforward given the layer system. Variant generation, interpolation, grid preview, and bisection export are moderately complex.
+
+## Phase 7 -- Level Editor
+
+**Milestone: full isometric level editor for placing and composing sprites.**
+
+This is a full level editor, not just a preview tool. It provides a separate editing mode for building isometric scenes/maps using sprites created in PixelWeaver.
+
+### Live Tile Tessellation
+
+- While editing a terrain tile, a preview panel shows the tile repeated in an isometric grid
+- Adjustable grid size (3x3, 5x5, custom)
+- Updates in real-time as you draw
+
+### Seam Checker
+
+- Automated analysis of tile edges
+- Highlights pixels that would create visible seams when tiled
+- Auto-fix suggestions (color-match adjacent edge pixels)
+- Works for all four isometric edges (NE, SE, SW, NW)
+
+### Level Editor Features
+
+| Feature | Description |
+|---|---|
+| Multiple map layers | Separate layers for terrain, objects, entities, overlays, etc. |
+| Per-tile height values | All modes: integer steps, half-steps, continuous |
+| Entity properties | Key-value metadata per placed entity |
+| Collision regions | Define collision shapes on the map |
+| Depth sorting | Automatic layer ordering: terrain -> buildings -> entities |
+
+### Level Editor Assets
+
+- Assets reference PixelWeaver projects directly -- no separate tileset format
+- Terrain tiles snap to isometric grid positions
+- Entity sprites placed freely (with optional grid snap)
+- Building sprites placed with correct height offset
+
+### Level Editor Export
+
+- **Tiled-compatible JSON (.tmj)**: export maps in Tiled's native format for direct game engine consumption
+- Scene layouts saved as part of the project directory
+
+### Files/Dirs That Will Change
+
+- `src/lib/leveleditor/` -- map editor, tile placement, entity placement, collision regions
+- `src/lib/iso/` -- tessellation preview, seam checker, isometric math
+- `src/lib/export/` -- Tiled .tmj export
+- `src/lib/ui/` -- level editor mode, tile palette panel, entity panel, height editor
+
+### Effort: Large
+
+This is a full level editor with multiple map layers, height values, entity properties, collision regions, and Tiled export. Significantly more complex than the original "preview tool" concept.
+
+## Phase 8 -- Plugin System Formalization
+
+**Milestone: third-party plugins work, plugin management UI complete.**
+
+Note: the plugin system itself exists from day 1 (Phase 1). This phase formalizes the API documentation, adds the management UI, and ensures the API surface is stable and complete for third-party developers.
+
+### Plugin Loader
+
+- Scans a `plugins/` directory (on disk, via companion server) for ES modules
+- Each module exports a `register(api)` function
+- Plugins loaded at startup, can be enabled/disabled at runtime
+- Load order respects declared dependency arrays
+- Trust-based: no sandboxing
+
+### Plugin API Surface
+
+```js
+api.addCommand(name, { execute, undo, describe, params })
+api.addTool(name, { icon, cursor, handlers, optionsPanel })
+api.addPanel(name, { component, position, defaultVisible })
+api.addExporter(name, { extension, export })
+api.addImporter(name, { extensions, import })
+api.addShortcut(name, { defaultKey, command })
+api.getCanvas()         // read/write pixel data
+api.getProject()        // project metadata
+api.getActiveFrame()    // current frame data
+api.getActiveLayers()   // layer tree and active layer
+api.dispatch(command)   // execute a command
+api.onCommand(callback) // listen to all commands
+```
+
+### Plugin Management UI
+
+- Settings panel listing all plugins (built-in and third-party)
+- Enable/disable toggle per plugin
+- Plugin info: name, description, author, version, commands/tools/panels it registers, dependencies
+- "Open plugins folder" button (opens file manager via companion server)
+
+### Files/Dirs That Will Change
+
+- `src/lib/core/plugin-api.js` -- API surface documentation and stability guarantees
+- `src/lib/ui/` -- plugin management panel
+- `plugins/` -- third-party plugin directory
+
+### Effort: Small-Medium
+
+Most of the API surface already exists from Phase 1. This phase adds the management UI, documents the API, and ensures stability for third-party use.
+
+## Cross-Cutting Concerns
+
+### Performance
+
+- Canvas operations must be responsive at 60fps up to 512x512
+- Layer compositing must be efficient (cache flattened composites, invalidate on change)
+- Undo stack should not grow unbounded in memory -- consider snapshots + command replay for deep histories
+- WebSocket message throughput must handle rapid drawing input
+
+### Crash Safety and Auto-Save
+
+- Service worker + IndexedDB auto-recovery
+- Auto-save: configurable debounce (e.g. 500ms after last command) + interval (e.g. every 30s)
+- Recovery dialog on next launch if incomplete state detected
+
+### Theming
+
+- Dark + light themes via CSS variables
+- Switchable at runtime
+- All UI components respect theme variables
+
+### Accessibility
+
+- All tools accessible via keyboard shortcuts
+- Color picker supports all input modes (hex, RGB, HSL, HSV)
+- Status bar announces tool changes and coordinates
+
+### Error Handling
+
+- Companion server down: frontend shows clear message, allows limited offline work (in-memory, export to download)
+- Invalid project files: graceful error with details, never crash silently
+- Plugin errors: caught and reported, never crash the editor
+- WebSocket disconnection: auto-reconnect with exponential backoff + full state reconciliation
+
+### Testing Strategy
+
+| Category | Framework | Scope |
+|---|---|---|
+| Unit tests | Vitest | Core (dispatcher, undo, commands, layer model) |
+| Tool integration tests | Vitest | Execute command -> verify pixel buffer state |
+| Server API tests | pytest + httpx | All server endpoints and WebSocket protocol |
+| E2E tests | Playwright | Critical flows (draw, save, load, export, tools, menus, undo-redo) |
+
+### Browser Support
+
+- Firefox: required (primary reason the companion server exists)
+- Chrome/Edge: supported
+- Safari: best-effort
+
+## Dependencies
+
+### Frontend (npm)
+
+- svelte (v5, runes)
+- @sveltejs/vite-plugin-svelte
+- culori (headless color library for color picker)
+- (No shadcn-svelte, no msgpack, no tinykeys/mousetrap -- custom UI, JSON format, custom shortcuts)
+
+### Server (Python, managed with uv)
+
+- fastapi
+- uvicorn
+- websockets (for WebSocket protocol)
+- watchfiles (for file watching)
+- Pillow (for PNG read/write if needed server-side)
+
+### Desktop
+
+- @tauri-apps/cli
+- @tauri-apps/api
+- Rust toolchain (for Tauri build)
+
+### Dev
+
+- vite
+- vitest (unit/integration tests)
+- playwright (e2e tests)
+- ruff (Python linting)
+- eslint + prettier (JS/Svelte linting)
+- pytest + httpx (server tests)
+
+## Summary Table
+
+| Phase | What | Effort | Key Dependencies |
+|---|---|---|---|
+| 1 | Core Editor (canvas, layers, tools, colors, undo, shortcuts, command palette, server, WebSocket, Tauri, crash recovery, plugin system) | Large | -- |
+| 2 | Animation (frames, onion skinning, tags, preview, spritesheet export, import, clipboard) | Medium-Large | Phase 1 |
+| 3 | Pro Drawing Tools (gradient, dither, noise, symmetry, selection, effects pipeline, GM effects) | Medium-Large | Phase 1 |
+| 4 | Semantic History (action log, command replay/reorder, macros, spec round-trip) | Large | Phase 1 |
+| 5 | MCP Integration (dual-layer tool server, sequential locking, live sync) | Medium | Phase 1, 4 |
+| 6 | Variants (layer group palette swap, bisection export, variant generation/grid/randomization, interpolation) | Medium-Large | Phase 1, 2 |
+| 7 | Level Editor (tile tessellation, seam checker, multi-layer maps, height, entities, collision, Tiled export) | Large | Phase 1, 2 |
+| 8 | Plugin Formalization (management UI, API documentation, third-party stability) | Small-Medium | Phase 1 |
+
+All phases are parallel work units. They are NOT sequential releases -- everything ships together. Dependencies indicate which phases' foundations must be architecturally complete before work can begin on dependent phases, not release order.
+
+Phases 2, 3, 4, 8 can be worked in parallel after Phase 1 foundations are in place.
+Phases 5, 6, 7 have additional dependencies as noted but are otherwise independent of each other.
+
+## Implementation Status
+
+*Last updated: 2026-04-10*
+
+### Phase Status
+
+| Phase | Name | Status | Notes |
+|---|---|---|---|
+| 1 | Core Editor | Complete | Canvas, layers, tools, colors, undo, shortcuts, command palette, server, WebSocket, crash recovery, plugin system |
+| 2 | Animation | Complete | Frame strip, preview, onion skinning, tags, spritesheet export, import, clipboard |
+| 3 | Pro Drawing Tools | Complete | Gradient, dither, noise, symmetry, selection, effects pipeline, GM effects |
+| 4 | Semantic History | Complete | Action log, command replay/reorder, macros, spec export |
+| 5 | MCP Integration | Complete | Dual-layer tool server, sequential locking, live sync |
+| 6 | Variants | Complete | Palette swap, interpolation, bisection export |
+| 7 | Level Editor | Complete | Isometric editor, tile tessellation, seam checker, Tiled export |
+| 8 | Plugin Formalization | Complete | API docs, plugin discovery, management state |
+| -- | App Assembly / Wiring | Complete | Bootstrap, system plugins, plugin API getters, render state, input handler, canvas viewport |
+| -- | UI Components | Complete | ToolBar, LayerPanel, ColorPicker, FrameStrip, StatusBar, MenuBar, NewProjectDialog, ExportDialog, App.svelte layout |
+
+### Remaining Work
+
+The backing state, commands, registries, and plugin logic for each of the
+items below already exist. What is missing is the Svelte component that
+renders them in a dockview panel.
+
+| Item | Category | Priority |
+|---|---|---|
+| ActionLogPanel | UI | Low |
+| VariantPanel | UI | Low |
+| PluginManagerPanel | UI | Low |
+| LevelEditorViewport | UI | Low |
+| AnimationPreviewPanel | UI | Low |
+| ShortcutEditorPanel | UI | Low |
+
+### Recently Completed
+
+Items previously listed as remaining that have since landed:
+
+| Item | Landed |
+|---|---|
+| Tauri sidecar wiring (auto-start Python server via `uv run pixelweaver serve`, port 7779 health check in `src-tauri/src/lib.rs`) | 2026-04-10 |
+| Aseprite `.ase` import (`plugins/builtin/importers/aseprite-importer-plugin.ts` with `aseprite-parser.ts`) | 2026-04-10 |
+| Piskel `.piskel` import (`plugins/builtin/importers/piskel-importer-plugin.ts`) | 2026-04-10 |
+| Playwright E2E tests (`e2e/app-launch.test.ts`, `tools.test.ts`, `menus.test.ts`, `undo-redo.test.ts`, `playwright.config.ts`) | 2026-04-10 |
+| `render.py` spec format compatibility (native export/import via `src/lib/history/spec-format.ts`; Sky JSON ingestion via `plugins/builtin/importers/sky-spec-plugin.ts`) | 2026-04-10 |
+| AnimationPreview panel | UI | Low |