paint-ui/IMPLEMENTATION_PLAN.md

Paint UI - Implementation Plan

📊 Current Status

Progress: Phases 1-11 Complete + Performance & Accessibility (95% of MVP features) ✅

✅ Completed Features

• Core Foundation: Next.js 16, React 19, TypeScript, Tailwind CSS 4
• Canvas Engine: Multi-layer system with zoom/pan, rulers, blend modes
• Undo/Redo: Command pattern with full history support
• Drawing Tools: Pencil, Brush (with flow/hardness), Eraser, Fill, Eyedropper
• Advanced Brush Tools: Clone Stamp, Smudge, Dodge/Burn (with Alt key modifiers)
• Selection Tools: Rectangle, Ellipse, Lasso, Magic Wand with full operations
• Transform Tools: Move, Free Transform, Rotate, Scale, Skew
• Shape Tools: Rectangle, Ellipse, Line, Arrow, Polygon, Star, Triangle
• Text Tool: On-canvas editing, 16 fonts, Bold/Italic, Alignment, Line height, Letter spacing, Delete
• Color System: HSV picker, swatches, history, color adjustments
• File Operations: Open (drag/drop/paste), Export (PNG/JPG/WEBP), Project files
• Effects & Filters: 15+ filters (Blur, Sharpen, Color adjustments, Artistic effects) with Web Worker support
• UI/UX: Professional layout, Theme toggle, State persistence, Custom scrollbars
• Performance: Web Workers for heavy filters, Code splitting for tools, Lazy loading, Dirty rect infrastructure
• Accessibility: ARIA labels, Keyboard shortcuts (1-0 for tools), Focus indicators, Context menus, Toast notifications
• UX Enhancements: Loading overlays, Right-click context menus, Toast notification system

🚧 In Progress / TODO

• Testing & Documentation (Phase 12)
• Web Font Integration (Google Fonts for text tool) - Optional enhancement
• Touch Support (Mobile optimization) - Optional enhancement

📅 Last Updated

November 21, 2025 - Completed Advanced Brush Tools + Performance Optimizations + Accessibility Improvements

---

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) ✅ COMPLETE

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) - SKIPPED

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) ✅ COMPLETE

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) - via Zustand persist

4. Rendering Pipeline

   • Implement composite rendering (all layers → main canvas)
   • Add blend mode support
   • Optimize rendering with dirty rectangles - TODO: Performance optimization
   • 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) ✅ COMPLETE

Goals: Implement robust undo/redo functionality

Tasks:

1. History Manager

   • Design history state structure (snapshots vs commands) - Command pattern
   • Implement undo/redo stack
   • Add history limits (max 50 states)
   • Create history middleware for Zustand

2. Command Pattern

   • Create abstract Command class (BaseCommand)
   • Implement layer commands (Add, Delete, Modify)
   • Implement drawing commands (Paint, Erase, Fill) - DrawCommand
   • Implement move commands - MoveCommand
   • Implement transform commands - TransformCommand
   • Implement filter commands - FilterCommand
   • Add command batching for performance - TODO: Future optimization

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) ✅ COMPLETE

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 (tool-options bar)

2. Core Tools

   • Pencil Tool - Basic 1px drawing
   • Brush Tool - Variable size/opacity/hardness/flow
   • Eraser Tool - Remove pixels
   • Fill Tool - Flood fill algorithm with color/opacity
   • Eyedropper Tool - Color picker from canvas

3. Selection Tools

   • Rectangle Select - Rectangular selection
   • Ellipse Select - Circular selection
   • Lasso Select - Freehand selection
   • Magic Wand - Color-based selection
   • Selection operations (move, cut, copy, paste, fill, stroke, delete)

4. Tool UI

   • Tool palette sidebar
   • Tool-specific settings panel
   • Brush preview
   • Size/opacity/hardness/flow 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) ✅ COMPLETE

Goals: Comprehensive color management

Tasks:

1. Color Picker

   • HSV color wheel component
   • RGB/HSL/Hex input fields
   • Color history/swatches
   • Eyedropper integration
   • Alpha/opacity control

2. Color Management

   • Primary/secondary color state
   • Color palette presets
   • Recent colors storage
   • Color conversion utilities
   • Color adjustments (Hue/Saturation/Lightness/Brightness)

Deliverables:

• ✅ Functional color picker
• ✅ Color swatches working
• ✅ Color history persists

---

Phase 6: File Operations (Week 7-8) ✅ COMPLETE

Goals: Import/export image files

Tasks:

1. File Opening

   • Drag & drop support
   • File input dialog
   • Clipboard paste (Ctrl+V)
   • URL loading - TODO: Future enhancement
   • 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 - TODO: Future enhancement
   • Display EXIF info - TODO: Future enhancement
   • Preserve EXIF on export (optional) - TODO: Future enhancement

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) ✅ COMPLETE

Goals: Implement image manipulation effects

Tasks:

1. Effect Architecture

   • Create BaseEffect class
   • Implement effect preview system
   • Add Web Worker support for heavy effects - TODO: Performance optimization
   • Create effect parameter UI (FilterDialog)

2. Color Adjustments

   • Brightness/Contrast
   • Hue/Saturation/Lightness
   • Levels - TODO: Advanced feature
   • Curves - TODO: Advanced feature
   • Auto color correction
   • Invert/Negative

3. Blur Effects

   • Gaussian Blur
   • Box Blur
   • Motion Blur - TODO: Future enhancement
   • Zoom Blur - TODO: Future enhancement

4. Artistic Effects

   • Grayscale
   • Sepia
   • Oil Painting - TODO: Future enhancement
   • Pencil Sketch - TODO: Future enhancement
   • Mosaic - TODO: Future enhancement
   • Pixelate

5. Distortion Effects

   • Bulge/Pinch - TODO: Future enhancement
   • Swirl - TODO: Future enhancement
   • Ripple - TODO: Future enhancement

6. Other Effects

   • Sharpen
   • Edge Detection
   • Emboss
   • Noise/Grain
   • Vignette

Deliverables:

• ✅ 15+ effects implemented (core set complete)
• ✅ Effect preview working
• ⚠️ Effects run in main thread (Worker optimization TODO)

---

Phase 8: Advanced Tools (Week 10-12) ✅ COMPLETE

Goals: Implement advanced editing tools

Tasks:

1. Text Tool ✅ COMPLETE (Phase 11)

   • Text rendering on canvas (on-canvas editor with live preview)
   • Font family selection (16 system fonts)
   • Font size/style/weight (including Bold/Italic toggles)
   • Text color and opacity
   • Text alignment (Left/Center/Right buttons)
   • Line height control (slider 0.5-3.0)
   • Letter spacing control (slider -10px to 50px)
   • Text editing/repositioning (drag to move, click to re-edit)
   • Delete text functionality (Delete/Backspace on empty text)
   • Web font loading (Google Fonts integration) - TODO: Enhancement

2. Shape Tools ✅ COMPLETE (Phase 10)

   • Rectangle (fill/stroke)
   • Ellipse (fill/stroke)
   • Line
   • Arrow
   • Polygon
   • Star
   • Triangle

3. Advanced Tools ✅ COMPLETE

   • Clone Stamp Tool (Alt+Click to set source)
   • Healing Brush - TODO: Future enhancement
   • Blur/Sharpen Tool (brush-based) - TODO: Future enhancement
   • Smudge Tool (blending and smearing)
   • Dodge/Burn (Alt to toggle between lighten/darken)

4. Transform Tools ✅ COMPLETE (Phase 9)

   • Free Transform
   • Rotate
   • Scale
   • Skew
   • Perspective - TODO: Advanced feature
   • Move Tool

Deliverables:

• ✅ Text tool fully functional with comprehensive formatting
• ✅ Shape tools functional
• ✅ Transform operations smooth

---

Phase 9: Image Manipulation (Week 12-13) ✅ COMPLETE (Integrated with Phase 8-9)

Goals: Advanced image operations

Tasks:

1. Canvas Operations

   • Resize canvas
   • Crop canvas
   • Rotate canvas (90°, 180°, 270°)
   • Flip horizontal/vertical
   • Trim transparent pixels - TODO: Utility feature

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) ✅ MOSTLY COMPLETE

Goals: Refine user interface and experience

Tasks:

1. Responsive Design

   • Mobile-friendly layout (professional editor layout)
   • Touch support for tools - TODO: Mobile optimization
   • Collapsible panels (Resizable panels with state persistence)
   • Mobile menu

2. Accessibility ✅ COMPLETE

   • Keyboard navigation (Ctrl+Z, Ctrl+Shift+Z, 1-0 for tools, Arrow keys for layers, etc.)
   • ARIA labels (all interactive elements)
   • Focus management (focus indicators with :focus-visible)
   • Screen reader support (via ARIA labels and semantic HTML)

3. UI Components ✅ COMPLETE

   • Context menus (right-click on layers with viewport detection)
   • Tooltips (via Radix UI with keyboard shortcuts)
   • Notification system (toast notifications with 4 types)
   • Loading states (full-screen overlays with custom messages)
   • Error boundaries

4. Performance ✅ MOSTLY COMPLETE

   • Lazy load tools (dynamic imports with caching)
   • Code splitting (tool loader with preloading)
   • Web Workers for heavy filters (with smart routing)
   • Dirty rectangle infrastructure (ready for integration)
   • Image optimization - TODO: Further optimization
   • Bundle size analysis - TODO: Optimization

Additional Features Implemented:

• Dark/Light theme toggle with persistence
• UI state persistence (panel positions, tool selection)
• Professional image editor layout structure
• Tool options bar with context-sensitive controls
• Transparent canvas background support
• Custom scrollbar styling

Deliverables:

• ✅ Professional UI layout
• ✅ Accessibility improvements complete (ARIA, keyboard nav, focus)
• ✅ Performance optimizations (lazy loading, code splitting, Web Workers)
• ✅ Fast load times with Next.js 16

---

Phase 11: Advanced Features (Week 14-16) ✅ TEXT TOOL COMPLETE

Goals: Nice-to-have features

Priority Tasks for Next Implementation:

1. Text Tool ✅ COMPLETE

   • Text rendering on canvas (Photoshop-style on-canvas editor)
   • Font family selection (16 system fonts)
   • Font size/style/weight (with Bold/Italic toggles)
   • Text color and opacity
   • Text alignment (Left/Center/Right buttons)
   • Line height control (0.5-3.0 range)
   • Letter spacing control (-10px to 50px)
   • Text editing/repositioning (click to edit, drag to move)
   • Delete functionality (Delete/Backspace on empty text)
   • Web font loading (Google Fonts integration) - TODO: Enhancement

2. Advanced Brush Tools ✅ COMPLETE

   • Clone Stamp Tool (keyboard shortcut: 8)
   • Healing Brush - TODO: Future enhancement
   • Blur/Sharpen Tool (brush-based) - TODO: Future enhancement
   • Smudge Tool (keyboard shortcut: 9)
   • Dodge/Burn Tool (keyboard shortcut: 0, Alt to toggle)

3. Animation Support (Future)

   • Frame timeline
   • Frame duplication
   • Onion skinning
   • Export as GIF
   • Export as APNG/WEBP animation

4. Batch Operations (Future)

   • Apply effect to multiple layers
   • Batch export
   • Actions/macros recording

5. Plugins/Extensions (Future)

   • Plugin API design
   • Custom tool registration
   • Custom effect registration

Deliverables:

• ✅ Text tool complete with professional features
• ✅ Advanced brush tools complete (Clone Stamp, Smudge, Dodge/Burn)
• ⏸️ Animation/batch/plugin features (nice-to-have, future)

---

Phase 12: Testing & Documentation (Week 16-18) ⚠️ TODO

Goals: Ensure quality and maintainability

Tasks:

1. Testing

   • Unit tests (Vitest) - Core utilities and commands
   • Integration tests - Tool interactions
   • E2E tests (Playwright) - Complete workflows
   • Visual regression tests - UI consistency

2. Documentation

   • Implementation plan (this document)
   • User documentation - How to use each tool
   • API documentation - For developers
   • Architecture guide - System design
   • Contributing guide - For contributors

3. CI/CD

   • Docker configuration
   • GitHub Actions setup
   • Automated testing
   • Build optimization
   • Deployment pipeline

Deliverables:

• ⚠️ Testing framework TODO
• ⚠️ User documentation TODO
• ⚠️ Automated CI/CD TODO

---

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.