pixelweaver 0.1.0

package/todo/.done/unified-toolbar-and-action-system.md

@@ -0,0 +1,323 @@
+# Unified Toolbar & Action System
+
+## Context
+
+PixelWeaver's current toolbar is a hardcoded 44px vertical strip (`src/lib/ui/ToolBar.svelte`) that sits outside the dockview system. It renders every registered tool from `toolRegistry` in insertion order with no ability to reorder, group, hide, or customize items. It only understands `ToolDefinition` entries -- there is no concept of non-tool toolbar items (zoom, undo/redo, separators).
+
+Additionally, there are two overlapping panel registration systems (`PanelDefinition` in `plugin-types.ts` and `DockPanelConfig` in `dock-types.ts`) that serve similar purposes but aren't connected.
+
+This plan unifies these systems into a fully data-driven, config-driven UI where:
+- Commands are self-describing (with icons)
+- Toolbars are dockable panels with configurable contents, orientation, thickness, and icon size
+- Multiple toolbars are supported from day one
+- Plugin defaults can be overridden by user config
+- The two panel systems are merged into one
+
+## Design Decisions (locked in)
+
+| Decision | Choice |
+|----------|--------|
+| Icon location | On `CommandDefinition` -- single source of truth |
+| Toolbar count | Multi-toolbar from day one |
+| Orientation | Both horizontal and vertical, auto-detected from dock position |
+| Thickness | Configurable items-per-row (1, 2, 3, ...) |
+| Icon size | Configurable per toolbar |
+| Customization model | Plugin-driven defaults + user overrides via config file |
+| Panel systems | Merge `PanelDefinition` and `DockPanelConfig` into a single unified registry |
+
+## Problem
+
+1. **No action abstraction**: Tools, commands, and shortcuts are separate concepts with no shared "action" identity. A pencil tool and an undo command cannot both be toolbar items.
+2. **Toolbar is not dockable**: Hardcoded in `App.svelte` as a sibling of the dock area. Cannot be moved, resized, or hidden by the user.
+3. **No toolbar configuration**: No way to specify which items appear, in what order, with what grouping. Every tool is always shown.
+4. **No structural metadata on tools**: `ToolDefinition` lacks `order`, `group`, `category` fields.
+5. **Commands lack icons**: `CommandDefinition` has `label` and `category` but no `icon` field, so commands can't self-render in toolbars.
+6. **Two panel systems**: `PanelDefinition` (plugin-facing, `component: unknown`) and `DockPanelConfig` (dock-internal, `component: Component`) coexist without a bridge.
+7. **Dockview theme bug**: `themePixelWeaver` is exported but never passed to the `DockviewComponent` constructor, causing dockview's blue-tinted default theme to leak through.
+
+## Solution
+
+### Architecture Overview
+
+```
+ToolbarContribution (plugin-declared)
+         |
+         v
+toolbarRegistry (reactive SvelteMap)
+         |
+         v
+ToolbarConfig (merged: plugin defaults + user overrides)
+         |
+         v
+ToolbarPanel.svelte (generic dockable component)
+         |
+    reads from:
+    - commandRegistry (for command actions + icons)
+    - toolRegistry (for tool activators)
+    - shortcutRegistry (for keybinding display)
+```
+
+### New/Modified Types
+
+**`CommandDefinition`** -- add `icon` field:
+- `icon?: string | import('svelte').Component` -- optional icon for menus, toolbars, palette
+
+**`ToolbarItemKind`** -- union discriminator:
+- `'tool'` -- activates a tool from `toolRegistry`
+- `'command'` -- executes a command from `commandRegistry`
+- `'separator'` -- visual divider
+- `'widget'` -- custom Svelte component (e.g. zoom slider)
+
+**`ToolbarContribution`** -- what plugins register:
+- `toolbarId: string` -- which toolbar this item belongs to
+- `kind: ToolbarItemKind`
+- `targetId?: string` -- tool name or command name (not needed for separator/widget)
+- `group: string` -- grouping bucket (items in same group are together, separators between groups)
+- `order: number` -- sort position within group
+- `label?: string` -- override label
+- `icon?: string | Component` -- override icon (falls back to command/tool icon)
+- `widget?: Component` -- Svelte component for `kind: 'widget'`
+
+**`ToolbarConfig`** -- per-toolbar configuration:
+- `id: string` -- unique toolbar ID
+- `title: string` -- display title for the dock tab
+- `orientation: 'auto' | 'horizontal' | 'vertical'` -- `auto` detects from dock position
+- `iconSize: number` -- icon dimensions in px (default 20)
+- `thickness: number` -- items per row/column (default 1)
+- `items?: ToolbarContribution[]` -- user overrides (replaces plugin defaults for this toolbar)
+- `closeable?: boolean` -- whether user can close this toolbar (default true)
+
+**`PanelConfig`** -- unified panel type (replaces both `PanelDefinition` and `DockPanelConfig`):
+- `id: string`
+- `title: string`
+- `component: Component`
+- `props?: Record<string, unknown>`
+- `position?: 'left' | 'right' | 'bottom' | 'center'`
+- `minWidth?: number`
+- `minHeight?: number`
+- `closeable?: boolean` -- default true
+
+## Phases
+
+### Phase 0: Dockview Theme Fix
+
+**Effort**: Trivial (one-liner)
+
+**Files changed**:
+- `src/lib/dock/DockLayout.svelte` -- import `themePixelWeaver`, pass to constructor
+
+This is a standalone bug fix that should be done first regardless of the rest of the plan.
+
+---
+
+### Phase 1: Merge Panel Systems
+
+**Effort**: Small
+
+Unify `PanelDefinition` (plugin-types.ts) and `DockPanelConfig` (dock-types.ts) into a single `PanelConfig` type and a single registration path.
+
+**Files changed**:
+- `src/lib/core/plugin-types.ts` -- replace `PanelDefinition` with `PanelConfig` (add `closeable`, `props`, `center` position, type `component` as `Component`)
+- `src/lib/dock/dock-types.ts` -- delete `DockPanelConfig`, re-export `PanelConfig` from plugin-types for backward compat or just delete
+- `src/lib/core/registries.svelte.ts` -- `panelRegistry` now stores `PanelConfig`
+- `src/lib/core/plugin-api.ts` -- `addPanel()` now registers into the unified registry used by the dock system
+- `src/lib/dock/dock-state.svelte.ts` -- remove its own `SvelteMap<string, DockPanelConfig>`; read from `panelRegistry` instead. `registerPanel()` becomes a thin wrapper or is removed in favor of `api.addPanel()`
+- `src/lib/dock/dock-plugin.ts` -- switch from `dockState.registerPanel()` to `api.addPanel()`
+- `src/lib/dock/DockLayout.svelte` -- read from `panelRegistry` instead of `dockState.panels`
+- `src/lib/dock/dock-presets.ts` -- update references if needed
+- `src/lib/ui/menu-commands-plugin.ts` -- update `isPanelVisible`/`addPanel`/`removePanel` calls if API changes
+
+---
+
+### Phase 2: Add Icon to CommandDefinition
+
+**Effort**: Small-medium
+
+Add the `icon` field to `CommandDefinition` and update all existing command registrations to include icons where appropriate.
+
+**Files changed**:
+- `src/lib/core/commands.ts` -- add `icon?: string | import('svelte').Component` to `CommandDefinition`
+- `plugins/builtin/effects/blur.ts` -- add icon
+- `plugins/builtin/effects/sharpen.ts` -- add icon
+- `plugins/builtin/effects/glow.ts` -- add icon
+- `plugins/builtin/effects/shadow.ts` -- add icon
+- `plugins/builtin/effects/outline.ts` -- add icon
+- `plugins/builtin/effects/color-effects.ts` -- add icons (invert, grayscale, colorize, brightness_contrast, hue_shift)
+- `plugins/builtin/effects/flip.ts` -- add icon
+- `plugins/builtin/effects/rotate.ts` -- add icon
+- `plugins/builtin/effects/scale.ts` -- add icon
+- `src/lib/ui/menu-commands-plugin.ts` -- add icons to system commands (new_project, open, save, export, undo, redo, zoom_in, zoom_out, zoom_reset, toggle_theme, panel toggles, layout presets, etc.)
+- `plugins/builtin/drawing-primitives-plugin.ts` -- add icons if it registers commands
+- `plugins/builtin/importers/*.ts` -- add icons to importer commands
+- `src/lib/ui/command-palette/command-palette-state.svelte.ts` -- render command icons in palette items
+- `src/lib/ui/menu-builder.ts` -- optionally include icon in menu tree for rendering
+- `src/lib/ui/MenuBar.svelte` -- optionally render command icon next to menu item label
+
+---
+
+### Phase 3: Toolbar Contribution Registry
+
+**Effort**: Medium
+
+Create the `ToolbarContribution` type, `toolbarRegistry`, and `api.addToolbarItem()` method. Update plugins to declare toolbar contributions.
+
+**Files changed**:
+- `src/lib/core/plugin-types.ts` -- add `ToolbarItemKind`, `ToolbarContribution`, `ToolbarConfig` types. Add `addToolbarItem(name: string, contribution: ToolbarContribution): void` to `PluginAPI`
+- `src/lib/core/registries.svelte.ts` -- add `toolbarRegistry = createRegistry<ToolbarContribution>()`
+- `src/lib/core/plugin-api.ts` -- implement `addToolbarItem()` delegating to `toolbarRegistry.set()`
+- All 15 tool plugins (`plugins/builtin/*-tool.ts`) -- each registers a `ToolbarContribution` with `kind: 'tool'`, targeting the default `'drawing-tools'` toolbar
+- `src/lib/ui/menu-commands-plugin.ts` -- register toolbar contributions for undo, redo, zoom_in, zoom_out, zoom_reset in a `'view-controls'` toolbar
+
+---
+
+### Phase 4: ToolbarPanel Component
+
+**Effort**: Medium-large
+
+Build the generic `ToolbarPanel.svelte` that replaces `ToolBar.svelte`. This is a dockable panel that reads its config and renders items with support for both orientations, configurable thickness, and icon sizes.
+
+**Files changed**:
+- `src/lib/ui/ToolbarPanel.svelte` -- new file, the core component:
+  - Accepts a `toolbarId` prop
+  - Reads contributions from `toolbarRegistry` filtered by `toolbarId`
+  - Groups items by `group`, sorts by `order`, inserts separators between groups
+  - Renders tool activators, command buttons, separators, and widgets
+  - Detects orientation from container aspect ratio (or explicit config)
+  - Supports configurable `iconSize` and `thickness` (items per row)
+  - Tool activators: highlight active tool, call onDeactivate/setActiveTool/onActivate
+  - Command buttons: execute command on click, show tooltip with shortcut
+  - Icons resolved from: contribution icon override -> command/tool icon -> fallback
+- `src/lib/ui/ToolBar.svelte` -- delete (replaced by ToolbarPanel)
+- `src/App.svelte` -- remove hardcoded `<ToolBar />` from the layout
+
+---
+
+### Phase 5: Register Toolbars as Dockable Panels
+
+**Effort**: Small-medium
+
+Create a toolbar dock plugin that registers toolbar panels into the unified panel system, and define default toolbar configurations.
+
+**Files changed**:
+- `src/lib/ui/toolbar-plugin.ts` -- new file. Registers:
+  - `'drawing-tools'` toolbar panel (position: left, not closeable, thickness: 1, iconSize: 20)
+  - `'view-controls'` toolbar panel (position: top or bottom, closeable, thickness: 1, iconSize: 18)
+  - Uses `api.addPanel()` to register each as a dockable `PanelConfig` with `component: ToolbarPanel` and `props: { toolbarId: '...' }`
+- `src/lib/dock/dock-presets.ts` -- update presets to include toolbar panels in their layouts
+- `src/lib/ui/menu-commands-plugin.ts` -- add View > Toolbars submenu with toggle commands for each toolbar
+
+**Default toolbar contents**:
+
+`drawing-tools` (the main tool palette):
+
+| Group | Items |
+|-------|-------|
+| draw | pencil, eraser, fill, line |
+| shapes | rect, circle, diamond |
+| select | rect-select, lasso-select |
+| color | eyedropper, gradient, noise, dither |
+| advanced | advanced-fill, pattern-stamp, symmetry |
+
+`view-controls` (view/edit actions):
+
+| Group | Items |
+|-------|-------|
+| history | undo, redo |
+| zoom | zoom_in, zoom_out, zoom_reset |
+
+---
+
+### Phase 6: Toolbar Configuration Persistence
+
+**Effort**: Small-medium
+
+Allow user overrides of toolbar configs via a JSON configuration file, persisted alongside the dock layout.
+
+**Files changed**:
+- `src/lib/ui/toolbar-config.ts` -- new file:
+  - `ToolbarUserConfig` type: `{ toolbars: Record<string, Partial<ToolbarConfig>> }`
+  - `loadToolbarConfig()` -- reads from localStorage key `pixelweaver:toolbar-config`
+  - `saveToolbarConfig()` -- writes to localStorage
+  - `getEffectiveConfig(toolbarId)` -- merges plugin defaults with user overrides
+  - `resetToolbarConfig(toolbarId)` -- removes user overrides for a toolbar
+- `src/lib/ui/ToolbarPanel.svelte` -- read effective config instead of raw contributions
+- `src/lib/ui/toolbar-plugin.ts` -- register a "Reset Toolbar" command per toolbar
+- `src/lib/ui/menu-commands-plugin.ts` -- add "Reset Toolbars" menu item under View
+
+**Config format** (stored in localStorage, editable via dev tools or future settings UI):
+```json
+{
+  "toolbars": {
+    "drawing-tools": {
+      "thickness": 2,
+      "iconSize": 24,
+      "items": [
+        { "kind": "tool", "targetId": "pencil", "group": "draw", "order": 10 },
+        { "kind": "tool", "targetId": "eraser", "group": "draw", "order": 20 },
+        { "kind": "separator", "group": "divider-1", "order": 30 },
+        { "kind": "command", "targetId": "undo", "group": "history", "order": 40 }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### Phase 7: Add Missing Action Icons & Toolbar-Eligible Commands
+
+**Effort**: Small
+
+Register additional commands that are useful as toolbar items but don't exist yet (fit-to-view, zoom-to-selection, etc.) and ensure all commands that should be toolbar-eligible have icons.
+
+**Files changed**:
+- `src/lib/ui/menu-commands-plugin.ts` -- add new commands:
+  - `fit_to_view` (icon: lucide/maximize, category: View)
+  - `zoom_to_selection` (icon: lucide/scan, category: View)
+  - `center_canvas` (icon: lucide/crosshair, category: View)
+  - `toggle_grid` (icon: pixelarticons/grid, category: View)
+  - `toggle_pixel_grid` (icon: lucide/grid-3x3, category: View)
+  - Register toolbar contributions for these in the `view-controls` toolbar
+- Audit all existing commands for missing icons and add them
+
+---
+
+## File Change Summary
+
+| File | Phase | Action |
+|------|-------|--------|
+| `src/lib/dock/DockLayout.svelte` | 0 | Fix: pass theme to constructor |
+| `src/lib/core/plugin-types.ts` | 1, 3 | Modify: merge PanelConfig, add toolbar types |
+| `src/lib/dock/dock-types.ts` | 1 | Delete or gut |
+| `src/lib/core/registries.svelte.ts` | 1, 3 | Modify: update panelRegistry type, add toolbarRegistry |
+| `src/lib/core/plugin-api.ts` | 1, 3 | Modify: update addPanel, add addToolbarItem |
+| `src/lib/dock/dock-state.svelte.ts` | 1 | Modify: read from panelRegistry |
+| `src/lib/dock/dock-plugin.ts` | 1 | Modify: use api.addPanel instead of dockState.registerPanel |
+| `src/lib/dock/dock-presets.ts` | 1, 5 | Modify: update references, add toolbar panels |
+| `src/lib/core/commands.ts` | 2 | Modify: add icon field |
+| 9 effect plugin files | 2 | Modify: add icons to commands |
+| 3 importer plugin files | 2 | Modify: add icons to commands |
+| `src/lib/ui/menu-commands-plugin.ts` | 2, 5, 6, 7 | Modify: add icons, toolbar contributions, new commands |
+| `src/lib/ui/command-palette/command-palette-state.svelte.ts` | 2 | Modify: render icons |
+| `src/lib/ui/menu-builder.ts` | 2 | Modify: include icon in tree |
+| `src/lib/ui/MenuBar.svelte` | 2 | Modify: render icons |
+| 15 tool plugin files | 3 | Modify: register toolbar contributions |
+| `src/lib/ui/ToolbarPanel.svelte` | 4 | New file |
+| `src/lib/ui/ToolBar.svelte` | 4 | Delete |
+| `src/App.svelte` | 4 | Modify: remove hardcoded toolbar |
+| `src/lib/ui/toolbar-plugin.ts` | 5 | New file |
+| `src/lib/ui/toolbar-config.ts` | 6 | New file |
+| `plugins/builtin/drawing-primitives-plugin.ts` | 2 | Modify: add icons if applicable |
+
+## Relative Effort
+
+| Phase | Effort | Dependencies |
+|-------|--------|-------------|
+| Phase 0: Dockview theme fix | Trivial | None |
+| Phase 1: Merge panel systems | Small | None |
+| Phase 2: Add icon to CommandDefinition | Small-medium | None |
+| Phase 3: Toolbar contribution registry | Medium | Phase 2 (icons exist) |
+| Phase 4: ToolbarPanel component | Medium-large | Phase 3 (registry exists) |
+| Phase 5: Register toolbars as dock panels | Small-medium | Phase 1 (unified panels), Phase 4 (component exists) |
+| Phase 6: Config persistence | Small-medium | Phase 4 (component reads config) |
+| Phase 7: Additional actions & icons | Small | Phase 2, Phase 3 |

package/todo/.obsolete/comprehensive-audit-obsolete-items.md

@@ -0,0 +1,33 @@
+# Comprehensive Audit -- Obsolete Items
+
+**Reason:** These items were specific to the Tauri 2 / FastAPI / uvicorn stack, which has been replaced by wesktop (granian ASGI server + pywebview). They no longer apply to the current architecture.
+
+**Source:** Extracted from `todo/comprehensive-audit.md` (audit dated 2026-04-10).
+
+---
+
+## C4. Server: No CORS middleware
+
+**Severity:** Critical
+**Impact:** The frontend in Tauri dev mode (`localhost:1420`) cannot reach the server (`localhost:7779`). Showstopper for the intended local-server use case.
+
+`server/src/pixelweaver/main.py` has no `CORSMiddleware` configured.
+
+**Files to change:** `server/src/pixelweaver/main.py`
+**Effort:** Small -- add `CORSMiddleware` from `starlette.middleware.cors` with appropriate origins.
+
+**Why obsolete:** Tauri dev mode is gone. The wesktop architecture serves the frontend through the same granian server, eliminating cross-origin requests entirely. No CORS middleware is needed.
+
+---
+
+## H12. reload=True always on in uvicorn
+
+**Severity:** High
+**Impact:** Every Python file save drops all WebSocket connections and wipes in-memory state. No flag to disable.
+
+`cli.py:99` hardcodes `reload=True` in the uvicorn configuration.
+
+**Files to change:** `server/src/pixelweaver/cli.py`
+**Effort:** Small -- make reload a CLI flag, default to `False` (or `True` only when `--dev` is passed).
+
+**Why obsolete:** uvicorn has been replaced by granian via wesktop. The `serve` command now passes `reload` as an explicit CLI flag (`--reload`), and the new `dev` command handles development mode separately. The original hardcoded-reload problem no longer exists.