paint-ui/IMPLEMENTATION_PLAN.md

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

   • 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

# 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.