pixelweaver 0.1.0

package/todo/.done/happy-path-polish.md

@@ -0,0 +1,177 @@
+# Happy Path Polish: End-to-End UX Gaps
+
+The core user journey -- launch app, draw sprites, animate them, build
+isometric variants, compose a world, automate with MCP, export for a game
+engine -- is architecturally complete but feels like a tech demo rather than
+a product. Every phase has the plumbing but is missing the finish that makes
+the experience feel intentional and delightful. This document catalogs what
+a user actually bumps into when walking through that journey, without
+prescribing solutions.
+
+---
+
+## 1. First Launch & Project Setup
+
+- App opens to a silent 32x32 canvas with no context. A new user has no idea
+  what this app is or what to do first. There is no welcome, no onboarding,
+  no hint.
+- Recovery data from a prior crash is detected in code but never surfaced to
+  the user. Work is silently lost.
+- Creating a new project over existing work gives no "unsaved changes"
+  warning. The old state just vanishes.
+- The 300ms layout-settle delay for dockview can cause a visible reflow on
+  startup.
+- No recent-projects list or templates. Every session starts from scratch
+  unless the server is running.
+
+## 2. Drawing & Painting
+
+- Shape tools (rect, circle, line, diamond, gradient, dither) show nothing
+  while dragging. The result appears only on pointer-up. This makes precise
+  placement guesswork.
+- Every tool is locked to a 1px brush. There is no size control anywhere.
+- Pressure data is captured from the pointer event but never used by any tool.
+  Tablet users get no benefit from their hardware.
+- No modifier-key behaviors: Shift doesn't constrain to straight lines,
+  Alt doesn't eyedrop, Ctrl doesn't do anything contextual.
+- Eyedropper tool doesn't actually sample pixels from the canvas. A code
+  comment says "actual pixel sampling will be handled by canvas integration
+  layer" -- it was never finished.
+- Shape tools are hard-coded to outline mode. No filled-shape option.
+- Color picker is physically small (100x60 HSV area, 16x16 swatches).
+  Picking precise colors in that space is fiddly.
+
+## 3. Animation
+
+- No onion skinning. Drawing frame-by-frame animation without seeing the
+  previous/next frame as a ghost is the single biggest friction for
+  animators.
+- The preview panel has a speed multiplier (0.1x-10x) in the code but no
+  UI control to change it.
+- "Side-by-side" playback mode doesn't actually show frames side by side.
+  It just highlights the current frame in the strip.
+- Per-frame duration exists in the model but isn't displayed or editable
+  inline in the frame strip. Requires a separate dialog.
+- No frame copy-paste across non-adjacent positions. Only duplicate-in-place.
+- No bulk frame operations (select range, delete multiple, move a sequence).
+- Drag-to-reorder frames has no clear insertion indicator until you're
+  exactly over a target.
+
+## 4. Layers
+
+- No layer thumbnails. The layer panel is a text list. You can't visually
+  tell what's on a layer without selecting it and looking at the canvas.
+- Four blend modes are implemented in the compositor (normal, multiply,
+  screen, overlay) but there is no UI to change them. The dropdown doesn't
+  exist.
+- "Merge Down" removes the top layer but doesn't actually composite its
+  pixels into the layer below. It's a structural placeholder.
+- "Flatten Group" converts a group to a pixel layer but doesn't composite
+  the children. The resulting layer is empty.
+- The lock flag is stored per-layer but never enforced. Drawing tools don't
+  check it. You can paint on a "locked" layer.
+- No default keyboard shortcuts for any layer operation.
+
+## 5. Isometric Sprite Creation & Variants
+
+- Tile mode (3x3 seamless preview + coordinate wrapping) is fully
+  implemented but not connected to any UI toggle. Users can't activate it.
+- Seam checker (detect edge mismatches + suggest fixes) is implemented and
+  tested but has no panel or button. Users can't access it.
+- Variant generation only offers random mode in the UI. Interpolation
+  (smooth blending between two palettes) exists in code but isn't reachable
+  from the panel.
+- Individual variant colors can't be manually edited in the UI. After
+  generating a random variant, there's no way to tweak one color that came
+  out wrong without using API calls.
+- The bisection atlas exports immediately with no preview. Users can't
+  verify the layout before it downloads.
+- No isometric drawing guides or grid overlay on the sprite canvas to help
+  align edges to tile boundaries.
+
+## 6. Level Editor / World Builder
+
+- No tile picker. This is the critical missing piece. Users can't browse
+  available sprites, select one, and paint it onto the map. The
+  `activeTile` must be set programmatically. The level editor is basically
+  non-functional for real use without this.
+- No eraser tool. Once a tile is placed, the only way to remove it is to
+  paint over it with another tile.
+- No undo/redo. Every tile placement is permanent until overwritten.
+- No layer management UI. Tile, entity, and collision layers exist in state
+  but there are no visibility toggles, no reordering controls, no layer
+  list.
+- No entity placement or collision drawing UI. The data structures support
+  entities (free-positioned sprites with properties) and collision shapes
+  (rects, polygons), but no tools to create or edit them.
+- No map properties UI. Grid size, tile size, and grid mode (iso/ortho) can
+  only be changed in code.
+- No keyboard shortcuts for panning, zooming, or tool switching.
+- The level editor is a tab in the center dock but there's no prominent
+  mode-switch affordance. Users may not discover it exists.
+- Silent failures -- clicking with no active tile shows a fleeting
+  notification that auto-dismisses before many users would read it.
+- Tiled export produces one tileset per unique tile (non-standard) and
+  omits image file references, so the .tmj can't render in Tiled without
+  manual assembly.
+
+## 7. MCP Automation & Insight
+
+- The MCP server and the browser UI run as completely independent processes
+  with separate state. Changes made via MCP don't appear in the UI. Changes
+  in the UI aren't visible to MCP introspection tools. There is no shared
+  truth.
+- The concurrency lock (MCPLock) is created but never acquired in any tool
+  execution path. Concurrent MCP calls can corrupt project state.
+- The `--data-dir` flag is ignored due to a wrong-module import in the save
+  handler. Projects always write to `./projects` regardless.
+- Spritesheet export via MCP only returns the first frame. Multi-frame
+  export doesn't work.
+- No MCP resources -- only tools. There's no way to subscribe to project
+  state or access canvases as readable resources.
+- Broadcast from MCP tool execution goes to an empty WebSocket list (no
+  clients). The notification infrastructure is wired but has no audience.
+
+## 8. Export
+
+- PNG export is pure raster. No metadata is embedded in the file (no tEXt
+  chunks, no EXIF, nothing).
+- Spritesheet export options are hardcoded: always horizontal layout,
+  always zero padding, always PixelWeaver metadata format. The code supports
+  grid layout, custom padding, and four metadata formats (PixelWeaver,
+  TexturePacker, Aseprite, CSS) but the dialog doesn't expose any of them.
+- Metadata is generated in code but never downloadable as a companion file.
+  There's no way to get the .json alongside the .png.
+- No export preview. Users can't see the spritesheet layout before
+  downloading.
+- The "atlas" layout is identical to "horizontal" in code -- incomplete.
+- No Tauri native file dialog. Export uses browser download (file goes to
+  ~/Downloads, no "Save As" location picker).
+- File > Save is registered as a menu command but not implemented.
+- No batch export (all canvases, all variants, etc.).
+- Variant atlas export has no companion metadata.
+
+---
+
+## Cross-Cutting Concerns
+
+These problems span multiple phases:
+
+- **Discoverability**: Many implemented features (tile mode, seam checker,
+  interpolation variants, blend modes) are invisible because they have no
+  UI entry point. The code is there but users can't reach it.
+- **Feedback**: Silent failures and fleeting notifications throughout. When
+  something doesn't work (locked layer, no active tile, out-of-bounds
+  click), the app often does nothing with no explanation.
+- **Keyboard-first workflow**: Almost no default shortcuts beyond basic
+  tool selection. Power users have no fast path for layer operations,
+  frame management, mode switching, or map editing.
+- **State continuity**: No local file save/load (only server sync).
+  Recovery exists but doesn't surface. No "Save As" anywhere. Projects
+  feel ephemeral.
+- **Placeholder implementations**: Merge down, flatten group, eyedropper,
+  atlas layout, MCP lock, MCP save path -- multiple features exist as
+  structural shells without the core behavior wired up.
+- **UI density**: The layer panel, frame strip, and variant panel are all
+  text-heavy / thumbnail-light. Professional pixel art tools communicate
+  visually; PixelWeaver communicates textually.