valknar/paint-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: initialize paint-ui project with comprehensive implementation plan

Browse Source 
- Add detailed 18-week implementation roadmap
- Define architecture and tech stack (Next.js 16, Tailwind CSS 4)
- Plan 12 development phases from foundation to deployment
- Include directory structure and component organization
- Set performance targets and success metrics
- Document browser compatibility and API requirements

Inspired by miniPaint, reimagined for modern web development.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Sebastian Krüger
2025-11-20 21:06:55 +01:00
commit c9df06e11b
3 changed files with 830 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
.gitignore vendored Normal file
View File

@@ -0,0 +1,49 @@
# Dependencies
node_modules/
.pnp
.pnp.js
.yarn/
# Testing
coverage/
.nyc_output/
# Next.js
.next/
out/
build/
dist/
# Production
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# Environment
.env
.env*.local
.env.production
# Vercel
.vercel
# TypeScript
*.tsbuildinfo
next-env.d.ts
# OS
.DS_Store
Thumbs.db
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# Misc
.cache/
.turbo/

712
IMPLEMENTATION_PLAN.md Normal file
View File

@@ -0,0 +1,712 @@
# 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.

69
README.md Normal file
View File

@@ -0,0 +1,69 @@
# Paint UI
A modern, browser-based image editor built with Next.js 16 and Tailwind CSS 4. Inspired by miniPaint, reimagined for the modern web.
## Features (Planned)
- 🎨 **Multi-layer Canvas** - Professional layer system with blend modes
- 🖌️ **Drawing Tools** - Pencil, brush, eraser, fill, and selection tools
- ✨ **Image Effects** - 50+ filters and effects (blur, sharpen, color adjustments)
- 📝 **Text Tool** - Add text with web fonts
- 🔄 **Undo/Redo** - Full history system
- 💾 **File Support** - Open/save PNG, JPG, WEBP, GIF, and project files
- 🎭 **Dark Mode** - Beautiful dark and light themes
- ⌨️ **Keyboard Shortcuts** - Power user friendly
- 📱 **Responsive** - Works on desktop, tablet, and mobile
## Tech Stack
- **Framework**: Next.js 16 (App Router)
- **UI**: React 19 + TypeScript
- **Styling**: Tailwind CSS 4
- **Components**: Radix UI / Shadcn
- **State**: Zustand
- **Canvas**: HTML5 Canvas API + Web Workers
## Getting Started
### Prerequisites
- Node.js 20+
- pnpm 9+
### Installation
```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](http://localhost:3000) in your browser.
## Documentation
- [Implementation Plan](./IMPLEMENTATION_PLAN.md) - Detailed roadmap and architecture
- [Contributing Guide](./docs/contributing.md) - How to contribute (coming soon)
- [API Documentation](./docs/api.md) - Plugin API reference (coming soon)
## Inspiration
This project is inspired by [miniPaint](https://github.com/viliusle/miniPaint), an excellent open-source image editor. While paint-ui is a complete rewrite with modern technologies, we aim to preserve the powerful capabilities that make miniPaint great.
## License
MIT
## Author
valknar
## Repository
https://dev.pivoine.art/valknar/paint-ui