From c9df06e11b06fecb32d9007b6fc2fbcd02b31937 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Kr=C3=BCger?= Date: Thu, 20 Nov 2025 21:06:55 +0100 Subject: [PATCH] chore: initialize paint-ui project with comprehensive implementation plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .gitignore | 49 +++ IMPLEMENTATION_PLAN.md | 712 +++++++++++++++++++++++++++++++++++++++++ README.md | 69 ++++ 3 files changed, 830 insertions(+) create mode 100644 .gitignore create mode 100644 IMPLEMENTATION_PLAN.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d42c79f --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..76400f3 --- /dev/null +++ b/IMPLEMENTATION_PLAN.md @@ -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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..43ed011 --- /dev/null +++ b/README.md @@ -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