# Paint UI - Implementation Plan

## Project Overview

**paint-ui** is a modern browser-based image editor built with Next.js 16 and Tailwind CSS 4, inspired by miniPaint. This is a ground-up rebuild focusing on modern web technologies while preserving the powerful canvas manipulation capabilities.

## Technology Stack

### Core Framework
- **Next.js 16** (App Router) - React framework with SSR/SSG capabilities
- **React 19** - UI library with modern hooks and server components
- **TypeScript 5.x** - Type safety and better DX

### Styling
- **Tailwind CSS 4** - Utility-first CSS framework
- **Radix UI** or **Shadcn/ui** - Accessible component primitives
- **CSS Modules** - For canvas-specific styling needs

### State Management
- **Zustand** - Lightweight state management for layers, history, and canvas state
- **React Context** - Global app configuration and theme

### Canvas & Image Processing
- **HTML5 Canvas API** - Core rendering
- **OffscreenCanvas** - Performance optimization
- **Web Workers** - Heavy image processing operations
- **pica** - High-quality image resizing
- **gif.js** - Animated GIF support
- **exif-js** - EXIF data handling

### Utilities
- **uuid** - Layer ID generation
- **file-saver** - File downloads
- **clsx** / **tailwind-merge** - Class name utilities

## Architecture

### Directory Structure

```
paint-ui/
├── src/
│   ├── app/                          # Next.js App Router
│   │   ├── layout.tsx               # Root layout
│   │   ├── page.tsx                 # Main editor page
│   │   └── globals.css              # Global styles + Tailwind
│   │
│   ├── components/                   # React components
│   │   ├── ui/                      # Shadcn/Radix components
│   │   │   ├── button.tsx
│   │   │   ├── dialog.tsx
│   │   │   ├── dropdown-menu.tsx
│   │   │   ├── slider.tsx
│   │   │   ├── tabs.tsx
│   │   │   └── ...
│   │   │
│   │   ├── editor/                  # Editor-specific components
│   │   │   ├── canvas-wrapper.tsx   # Main canvas component
│   │   │   ├── toolbar.tsx          # Top toolbar
│   │   │   ├── tool-palette.tsx     # Left sidebar tools
│   │   │   ├── layers-panel.tsx     # Right sidebar layers
│   │   │   ├── properties-panel.tsx # Layer properties
│   │   │   ├── color-picker.tsx     # Color selection
│   │   │   └── preview.tsx          # Preview panel
│   │   │
│   │   └── modals/                  # Modal dialogs
│   │       ├── new-image.tsx
│   │       ├── resize.tsx
│   │       ├── export.tsx
│   │       └── settings.tsx
│   │
│   ├── core/                         # Core canvas engine
│   │   ├── canvas-manager.ts        # Canvas lifecycle management
│   │   ├── layer-manager.ts         # Layer operations
│   │   ├── history-manager.ts       # Undo/redo system
│   │   ├── selection-manager.ts     # Selection handling
│   │   └── render-engine.ts         # Rendering pipeline
│   │
│   ├── tools/                        # Drawing tools
│   │   ├── base-tool.ts             # Abstract base class
│   │   ├── pencil.ts
│   │   ├── brush.ts
│   │   ├── eraser.ts
│   │   ├── fill.ts
│   │   ├── select.ts
│   │   ├── text.ts
│   │   ├── shape.ts
│   │   └── ...
│   │
│   ├── effects/                      # Image effects/filters
│   │   ├── base-effect.ts
│   │   ├── blur.ts
│   │   ├── brightness.ts
│   │   ├── contrast.ts
│   │   ├── grayscale.ts
│   │   └── ...
│   │
│   ├── store/                        # Zustand stores
│   │   ├── canvas-store.ts          # Canvas state
│   │   ├── layer-store.ts           # Layers state
│   │   ├── history-store.ts         # Undo/redo state
│   │   ├── tool-store.ts            # Active tool state
│   │   └── ui-store.ts              # UI state (panels, modals)
│   │
│   ├── workers/                      # Web Workers
│   │   ├── image-processor.worker.ts
│   │   └── gif-generator.worker.ts
│   │
│   ├── lib/                          # Utility functions
│   │   ├── canvas-utils.ts
│   │   ├── color-utils.ts
│   │   ├── file-utils.ts
│   │   ├── image-utils.ts
│   │   └── math-utils.ts
│   │
│   ├── types/                        # TypeScript types
│   │   ├── canvas.ts
│   │   ├── layer.ts
│   │   ├── tool.ts
│   │   ├── effect.ts
│   │   └── index.ts
│   │
│   └── config/                       # Configuration
│       ├── constants.ts
│       ├── keyboard-shortcuts.ts
│       └── default-settings.ts
│
├── public/                           # Static assets
│   ├── icons/
│   └── fonts/
│
├── docs/                             # Documentation
│   ├── architecture.md
│   ├── contributing.md
│   └── api.md
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── package.json
├── tsconfig.json
├── tailwind.config.ts
├── next.config.js
├── .gitignore
├── .eslintrc.json
├── .prettierrc
└── README.md
```

## Implementation Phases

### Phase 1: Project Foundation (Week 1)

**Goals**: Set up development environment and basic project structure

#### Tasks:
1. **Project Initialization**
   - [x] Create git repository
   - [ ] Initialize Next.js 16 with TypeScript
   - [ ] Configure Tailwind CSS 4
   - [ ] Set up ESLint + Prettier
   - [ ] Configure path aliases (@/ prefix)

2. **Core Dependencies**
   - [ ] Install Radix UI / Shadcn components
   - [ ] Install Zustand for state management
   - [ ] Install canvas utilities (pica, file-saver, etc.)
   - [ ] Set up Storybook (optional, for component development)

3. **Basic Layout**
   - [ ] Create root layout with header/sidebar structure
   - [ ] Implement responsive grid layout
   - [ ] Add dark/light theme toggle
   - [ ] Set up global CSS and Tailwind theme

4. **TypeScript Types**
   - [ ] Define core types (Layer, Canvas, Tool, Effect)
   - [ ] Create type definitions for canvas state
   - [ ] Set up strict TypeScript config

**Deliverables**:
- ✅ Working Next.js dev server
- ✅ Basic UI layout with panels
- ✅ Theme system working
- ✅ Type system foundation

---

### Phase 2: Core Canvas Engine (Week 2-3)

**Goals**: Build the fundamental canvas rendering and layer system

#### Tasks:
1. **Canvas Manager**
   - [ ] Create CanvasWrapper component with refs
   - [ ] Implement canvas initialization
   - [ ] Add zoom/pan functionality
   - [ ] Implement rulers and grid overlay
   - [ ] Handle canvas resize events

2. **Layer System**
   - [ ] Define Layer interface (id, name, visible, opacity, blendMode)
   - [ ] Create LayerManager class
   - [ ] Implement layer CRUD operations
   - [ ] Add layer ordering (move up/down)
   - [ ] Implement layer merging/flattening

3. **State Management**
   - [ ] Set up canvas-store (dimensions, zoom, offset)
   - [ ] Set up layer-store (layers array, active layer)
   - [ ] Create selectors for derived state
   - [ ] Add state persistence (localStorage)

4. **Rendering Pipeline**
   - [ ] Implement composite rendering (all layers → main canvas)
   - [ ] Add blend mode support
   - [ ] Optimize rendering with dirty rectangles
   - [ ] Implement preview rendering

**Deliverables**:
- ✅ Canvas displays correctly
- ✅ Can create/delete/reorder layers
- ✅ Zoom/pan works smoothly
- ✅ State persists on refresh

---

### Phase 3: History & Undo System (Week 3-4)

**Goals**: Implement robust undo/redo functionality

#### Tasks:
1. **History Manager**
   - [ ] Design history state structure (snapshots vs commands)
   - [ ] Implement undo/redo stack
   - [ ] Add history limits (max 50 states)
   - [ ] Create history middleware for Zustand

2. **Command Pattern**
   - [ ] Create abstract Command class
   - [ ] Implement layer commands (Add, Delete, Modify)
   - [ ] Implement drawing commands (Paint, Erase, Fill)
   - [ ] Add command batching for performance

3. **Keyboard Shortcuts**
   - [ ] Implement Ctrl+Z (undo)
   - [ ] Implement Ctrl+Shift+Z (redo)
   - [ ] Add keyboard shortcut manager
   - [ ] Create shortcuts config file

**Deliverables**:
- ✅ Undo/redo works for all operations
- ✅ Keyboard shortcuts functional
- ✅ History panel shows operation list

---

### Phase 4: Basic Drawing Tools (Week 4-6)

**Goals**: Implement fundamental drawing capabilities

#### Tasks:
1. **Tool Architecture**
   - [ ] Create BaseTool abstract class
   - [ ] Define tool lifecycle (activate, deactivate, mouseDown, mouseMove, mouseUp)
   - [ ] Implement tool cursor management
   - [ ] Add tool settings panel

2. **Core Tools**
   - [ ] **Pencil Tool** - Basic 1px drawing
   - [ ] **Brush Tool** - Variable size/opacity/hardness
   - [ ] **Eraser Tool** - Remove pixels
   - [ ] **Fill Tool** - Flood fill algorithm
   - [ ] **Eyedropper Tool** - Color picker from canvas

3. **Selection Tools**
   - [ ] **Rectangle Select** - Rectangular selection
   - [ ] **Ellipse Select** - Circular selection
   - [ ] **Lasso Select** - Freehand selection
   - [ ] Selection operations (move, cut, copy, paste)

4. **Tool UI**
   - [ ] Tool palette sidebar
   - [ ] Tool-specific settings panel
   - [ ] Brush preview
   - [ ] Size/opacity sliders

**Deliverables**:
- ✅ Can draw with pencil/brush
- ✅ Can erase pixels
- ✅ Can fill areas with color
- ✅ Can select and manipulate regions

---

### Phase 5: Color System (Week 6-7)

**Goals**: Comprehensive color management

#### Tasks:
1. **Color Picker**
   - [ ] HSV color wheel component
   - [ ] RGB/HSL/Hex input fields
   - [ ] Color history/swatches
   - [ ] Eyedropper integration

2. **Color Management**
   - [ ] Primary/secondary color state
   - [ ] Color palette presets
   - [ ] Recent colors storage
   - [ ] Color conversion utilities

**Deliverables**:
- ✅ Functional color picker
- ✅ Color swatches working
- ✅ Color history persists

---

### Phase 6: File Operations (Week 7-8)

**Goals**: Import/export image files

#### Tasks:
1. **File Opening**
   - [ ] Drag & drop support
   - [ ] File input dialog
   - [ ] Clipboard paste (Ctrl+V)
   - [ ] URL loading
   - [ ] Multiple file formats (PNG, JPG, WEBP, GIF)

2. **File Saving**
   - [ ] Export as PNG/JPG/WEBP
   - [ ] Quality settings for lossy formats
   - [ ] Transparent background support
   - [ ] Export current layer vs all layers

3. **Project Files**
   - [ ] Save/load project as JSON (with layers)
   - [ ] Preserve layer structure
   - [ ] Include metadata

4. **EXIF Support**
   - [ ] Read EXIF data on import
   - [ ] Display EXIF info
   - [ ] Preserve EXIF on export (optional)

**Deliverables**:
- ✅ Can open images via drag/drop/paste
- ✅ Can export to common formats
- ✅ Can save/load projects with layers

---

### Phase 7: Image Effects & Filters (Week 8-10)

**Goals**: Implement image manipulation effects

#### Tasks:
1. **Effect Architecture**
   - [ ] Create BaseEffect class
   - [ ] Implement effect preview system
   - [ ] Add Web Worker support for heavy effects
   - [ ] Create effect parameter UI

2. **Color Adjustments**
   - [ ] Brightness/Contrast
   - [ ] Hue/Saturation/Lightness
   - [ ] Levels
   - [ ] Curves
   - [ ] Auto color correction
   - [ ] Invert/Negative

3. **Blur Effects**
   - [ ] Gaussian Blur
   - [ ] Box Blur
   - [ ] Motion Blur
   - [ ] Zoom Blur

4. **Artistic Effects**
   - [ ] Grayscale
   - [ ] Sepia
   - [ ] Oil Painting
   - [ ] Pencil Sketch
   - [ ] Mosaic
   - [ ] Pixelate

5. **Distortion Effects**
   - [ ] Bulge/Pinch
   - [ ] Swirl
   - [ ] Ripple

6. **Other Effects**
   - [ ] Sharpen
   - [ ] Edge Detection
   - [ ] Emboss
   - [ ] Noise/Grain
   - [ ] Vignette

**Deliverables**:
- ✅ 20+ effects implemented
- ✅ Effect preview working
- ✅ Effects run in Web Workers

---

### Phase 8: Advanced Tools (Week 10-12)

**Goals**: Implement advanced editing tools

#### Tasks:
1. **Text Tool**
   - [ ] Text rendering on canvas
   - [ ] Font family selection
   - [ ] Font size/style/weight
   - [ ] Text color
   - [ ] Text alignment
   - [ ] Web font loading

2. **Shape Tools**
   - [ ] Rectangle (fill/stroke)
   - [ ] Ellipse (fill/stroke)
   - [ ] Line
   - [ ] Arrow
   - [ ] Polygon

3. **Advanced Tools**
   - [ ] Clone Stamp Tool
   - [ ] Healing Brush
   - [ ] Blur/Sharpen Tool (brush-based)
   - [ ] Smudge Tool
   - [ ] Dodge/Burn

4. **Transform Tools**
   - [ ] Free Transform
   - [ ] Rotate
   - [ ] Scale
   - [ ] Skew
   - [ ] Perspective

**Deliverables**:
- ✅ Text tool working with web fonts
- ✅ Shape tools functional
- ✅ Transform operations smooth

---

### Phase 9: Image Manipulation (Week 12-13)

**Goals**: Advanced image operations

#### Tasks:
1. **Canvas Operations**
   - [ ] Resize canvas
   - [ ] Crop canvas
   - [ ] Rotate canvas (90°, 180°, 270°)
   - [ ] Flip horizontal/vertical
   - [ ] Trim transparent pixels

2. **Image Resize**
   - [ ] Resize with quality options
   - [ ] Maintain aspect ratio
   - [ ] Hermite/Bicubic algorithms
   - [ ] Integration with pica library

3. **Layer Operations**
   - [ ] Merge layers
   - [ ] Flatten image
   - [ ] Duplicate layer
   - [ ] Layer from selection

**Deliverables**:
- ✅ All image operations working
- ✅ High-quality resize algorithm
- ✅ No quality loss on operations

---

### Phase 10: UI/UX Polish (Week 13-14)

**Goals**: Refine user interface and experience

#### Tasks:
1. **Responsive Design**
   - [ ] Mobile-friendly layout
   - [ ] Touch support for tools
   - [ ] Collapsible panels
   - [ ] Mobile menu

2. **Accessibility**
   - [ ] Keyboard navigation
   - [ ] ARIA labels
   - [ ] Focus management
   - [ ] Screen reader support

3. **UI Components**
   - [ ] Context menus (right-click)
   - [ ] Tooltips
   - [ ] Notification system
   - [ ] Loading states
   - [ ] Error boundaries

4. **Performance**
   - [ ] Lazy load tools
   - [ ] Code splitting
   - [ ] Image optimization
   - [ ] Bundle size analysis

**Deliverables**:
- ✅ Fully responsive on all devices
- ✅ Accessible (WCAG 2.1 AA)
- ✅ Fast load times (<3s)

---

### Phase 11: Advanced Features (Week 14-16)

**Goals**: Nice-to-have features

#### Tasks:
1. **Animation Support**
   - [ ] Frame timeline
   - [ ] Frame duplication
   - [ ] Onion skinning
   - [ ] Export as GIF
   - [ ] Export as APNG/WEBP animation

2. **Batch Operations**
   - [ ] Apply effect to multiple layers
   - [ ] Batch export
   - [ ] Actions/macros recording

3. **Plugins/Extensions**
   - [ ] Plugin API design
   - [ ] Custom tool registration
   - [ ] Custom effect registration

**Deliverables**:
- ✅ Basic animation support
- ✅ Plugin system foundation

---

### Phase 12: Testing & Documentation (Week 16-18)

**Goals**: Ensure quality and maintainability

#### Tasks:
1. **Testing**
   - [ ] Unit tests (Vitest)
   - [ ] Integration tests
   - [ ] E2E tests (Playwright)
   - [ ] Visual regression tests

2. **Documentation**
   - [ ] User documentation
   - [ ] API documentation
   - [ ] Architecture guide
   - [ ] Contributing guide

3. **CI/CD**
   - [ ] GitHub Actions setup
   - [ ] Automated testing
   - [ ] Build optimization
   - [ ] Deployment pipeline

**Deliverables**:
- ✅ 80%+ test coverage
- ✅ Complete documentation
- ✅ Automated deployments

---

## Performance Considerations

### Optimization Strategies

1. **Canvas Rendering**
   - Use OffscreenCanvas for layer compositing
   - Implement dirty rectangle optimization
   - Debounce render calls during drawing
   - Use requestAnimationFrame for smooth updates

2. **Web Workers**
   - Offload heavy image processing to workers
   - Use transferable objects for large image data
   - Implement worker pool for parallel processing

3. **Memory Management**
   - Limit undo history size
   - Clear unused canvases
   - Use image compression for layer storage
   - Implement layer thumbnail caching

4. **Code Splitting**
   - Lazy load tools on demand
   - Dynamic imports for effects
   - Separate chunks for large dependencies

## Compatibility

### Browser Support
- Chrome 100+
- Firefox 100+
- Safari 15+
- Edge 100+

### Required APIs
- Canvas 2D Context
- OffscreenCanvas
- Web Workers
- File API
- Clipboard API

## Success Metrics

### Performance Targets
- Initial load: <3 seconds
- Tool switch: <100ms
- Effect preview: <500ms
- Undo/redo: <50ms

### Quality Targets
- TypeScript: 100% coverage
- Test coverage: >80%
- Lighthouse score: >90
- Bundle size: <500KB (gzipped)

## Risk Mitigation

### Technical Risks
1. **Canvas Performance**: Use Web Workers and OffscreenCanvas
2. **Memory Leaks**: Implement proper cleanup in useEffect
3. **Browser Compatibility**: Polyfills and feature detection
4. **Large File Handling**: Stream processing and chunking

### Project Risks
1. **Scope Creep**: Stick to phased plan, MVP first
2. **Time Estimates**: Build in 20% buffer
3. **Dependency Issues**: Lock versions, test updates

## Future Enhancements

### Post-MVP Features
- [ ] Cloud storage integration
- [ ] Real-time collaboration
- [ ] AI-powered features (background removal, upscaling)
- [ ] Vector layer support
- [ ] 3D text rendering
- [ ] Advanced typography tools
- [ ] Print-ready export (CMYK support)
- [ ] Mobile native apps (React Native)

## Resources

### References
- miniPaint source: https://github.com/viliusle/miniPaint
- Next.js docs: https://nextjs.org/docs
- Tailwind CSS: https://tailwindcss.com
- Radix UI: https://radix-ui.com
- Canvas MDN: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

### Libraries to Evaluate
- **fabric.js** - Canvas object manipulation
- **konva.js** - 2D canvas framework
- **react-konva** - React wrapper for Konva
- **react-canvas-draw** - Drawing capabilities

---

## Getting Started

### Prerequisites
- Node.js 20+
- pnpm 9+
- Git

### Initial Setup
```bash
# Clone repository
git clone ssh://git@dev.pivoine.art:2222/valknar/paint-ui.git
cd paint-ui

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Open http://localhost:3000
```

### Development Workflow
1. Create feature branch from `main`
2. Make changes with conventional commits
3. Write tests for new features
4. Run linter and tests locally
5. Push and create pull request
6. Review and merge

---

## Conclusion

This implementation plan provides a roadmap for building a modern, high-performance browser-based image editor. The phased approach ensures steady progress while maintaining quality and allowing for adjustments based on learnings along the way.

**Estimated Timeline**: 16-18 weeks for MVP
**Team Size**: 1-2 developers
**Complexity**: High (canvas manipulation, performance optimization)

The end result will be a powerful, user-friendly image editor that rivals desktop applications while running entirely in the browser.