diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md index 1c4edd9..06ac1b7 100644 --- a/INSTRUCTIONS.md +++ b/INSTRUCTIONS.md @@ -6,35 +6,41 @@ PNGer is a single-container web application for PNG editing and resizing, design ## Development Roadmap -### Phase 1: MVP Foundation (Current) +### Phase 1: MVP Foundation (Completed ✅) - [x] Repository setup -- [ ] Project structure initialization -- [ ] Backend API scaffold -- [ ] Frontend scaffold -- [ ] Basic upload/download flow -- [ ] Dockerfile configuration +- [x] Project structure initialization +- [x] Backend API scaffold +- [x] Frontend scaffold +- [x] Basic upload/download flow +- [x] Dockerfile configuration +- [x] Live preview implementation +- [x] Dark/light mode theming +- [x] Image resize and compression +- [x] Format conversion (PNG, WebP, JPEG) -### Phase 2: Core Features -- [ ] Image resize functionality -- [ ] PNG compression -- [ ] Real-time preview -- [ ] Responsive UI design -- [ ] Error handling +### Phase 2: Sprint 1 - Enhanced UX (Completed ✅) +- [x] Drag & drop file upload +- [x] Clipboard paste (Ctrl+V) +- [x] Smart presets (8 configurations) +- [x] Keyboard shortcuts (Enter, Ctrl+Enter, ?, Esc) +- [x] Enhanced visual feedback +- [x] Responsive UI improvements +- [x] Theme contrast fixes -### Phase 3: Polish & Deployment -- [ ] Docker Compose for Unraid -- [ ] Environment configuration -- [ ] Documentation -- [ ] Testing -- [ ] Production build optimization +### Phase 3: Advanced Features (Upcoming) +- [ ] Batch processing +- [ ] Advanced crop tool with visual selector +- [ ] Watermarking +- [ ] Image filters and effects +- [ ] Undo/redo functionality +- [ ] History/recent files ## Technical Architecture ### Backend (Express + Sharp) **Endpoints:** -- `POST /api/upload` - Accept PNG file -- `POST /api/process` - Resize/compress image +- `POST /api/transform` - Transform image (resize, crop, compress, convert) - `GET /api/health` - Health check **Key Dependencies:** @@ -46,11 +52,21 @@ PNGer is a single-container web application for PNG editing and resizing, design ### Frontend (Svelte + Vite) **Components:** -- `App.svelte` - Main container -- `Uploader.svelte` - Drag & drop interface -- `Editor.svelte` - Resize controls -- `Preview.svelte` - Real-time image preview -- `Download.svelte` - Download button +- `App.svelte` - Main container with all features +- `lib/api.ts` - API client +- `lib/preview.ts` - Live preview logic using Canvas API +- `lib/theme.ts` - Dark/light theme management +- `lib/presets.ts` - Smart presets configuration + +**Key Features:** +- Drag & drop upload +- Clipboard paste support +- Real-time preview (debounced 300ms) +- Side-by-side comparison +- File size analysis +- 8 smart presets +- Keyboard shortcuts +- Persistent theme preference **Key Dependencies:** - svelte: Reactive framework @@ -80,9 +96,6 @@ PNGer is a single-container web application for PNG editing and resizing, design git clone https://git.alwisp.com/jason/pnger.git cd pnger -# Install root dependencies (if monorepo) -npm install - # Setup backend cd backend npm install @@ -110,7 +123,7 @@ npm run dev ``` PORT=3000 NODE_ENV=development -MAX_FILE_SIZE=10 +MAX_FILE_SIZE=10485760 CORS_ORIGIN=http://localhost:5173 ``` @@ -167,21 +180,65 @@ docker-compose up -d ## Code Standards -### JavaScript/Svelte +### JavaScript/TypeScript - Use ES6+ features - Async/await for asynchronous operations - Descriptive variable names - Comments for complex logic only +- Type safety with TypeScript ### File Organization - One component per file - Group related utilities -- Keep components under 200 lines +- Keep components under 300 lines (split if larger) +- Organize by feature when possible ### Commit Messages - Format: `type: description` -- Types: feat, fix, docs, style, refactor, test +- Types: feat, fix, docs, style, refactor, test, chore - Example: `feat: add drag and drop upload` +- Be specific and descriptive + +## Feature Implementation Notes + +### Drag & Drop Upload +- Uses HTML5 Drag and Drop API +- Visual feedback on dragover/dragleave +- File type validation on drop +- Falls back to file input for browser support + +### Clipboard Paste +- Listens for paste events on document +- Extracts image from clipboard items +- Supports screenshots and copied images +- Works across all major browsers + +### Smart Presets +- 8 predefined configurations: + 1. Web Optimized (1920x1080, 80%, WebP) + 2. Social Media (1080x1080, 85%, JPEG) + 3. Profile Picture (400x400, 90%, PNG) + 4. Email Friendly (800x600, 75%, JPEG) + 5. Tiny Icon (64x64, 100%, PNG) + 6. Retina 2x (2x size, 90%) + 7. Icon Small (256x256, 95%, PNG) + 8. Icon Large (512x512, 95%, PNG) +- Applies all settings with one click +- Visual icons for easy identification + +### Keyboard Shortcuts +- Global document listeners +- Context-aware Enter key (checks focus) +- Help dialog with ? key +- Esc to close dialogs +- Cross-platform support (Ctrl/Cmd) + +### Live Preview +- Client-side Canvas API rendering +- Debounced updates (300ms) +- Reactive state management +- Automatic size estimation +- Side-by-side comparison ## Troubleshooting @@ -202,27 +259,101 @@ npm rebuild sharp - Verify Dockerfile syntax - Clear Docker cache: `docker builder prune` +**Preview not updating:** +- Check browser console for errors +- Verify Canvas API support +- Clear browser cache + +**Drag & drop not working:** +- Check file type validation +- Verify event handlers are attached +- Test with different browsers + ## Performance Targets - Upload handling: < 100ms (for 5MB file) - Image processing: < 2s (for 10MP image) - Download generation: < 500ms - UI response time: < 100ms +- Preview generation: < 500ms (client-side) - Docker image size: < 150MB ## Security Considerations -- File type validation (PNG only) -- File size limits (10MB default) +- File type validation (image/* only) +- File size limits (10MB default, configurable) - No persistent storage of user files - Memory cleanup after processing - CORS configuration +- Input sanitization +- Error message sanitization (no path disclosure) + +## Testing Checklist + +### Upload Methods +- [ ] File input (click to browse) +- [ ] Drag & drop +- [ ] Clipboard paste (Ctrl+V) +- [ ] File validation errors +- [ ] Size limit handling + +### Image Operations +- [ ] Resize with width only +- [ ] Resize with height only +- [ ] Resize with both dimensions +- [ ] Crop to fit (cover mode) +- [ ] All 9 crop positions +- [ ] Format conversion (PNG, WebP, JPEG) +- [ ] Quality adjustment + +### Presets +- [ ] All 8 presets apply correctly +- [ ] Preset values match specifications +- [ ] Visual feedback on selection + +### Keyboard Shortcuts +- [ ] Ctrl+V pastes image +- [ ] Enter downloads (not in input) +- [ ] Ctrl+Enter downloads (anywhere) +- [ ] ? shows help dialog +- [ ] Esc closes dialog + +### UI/UX +- [ ] Theme toggle works +- [ ] Theme persists on reload +- [ ] Live preview updates +- [ ] File size analysis accurate +- [ ] Error messages clear +- [ ] Loading states visible +- [ ] Responsive on mobile + +### Browser Compatibility +- [ ] Chrome/Edge +- [ ] Firefox +- [ ] Safari +- [ ] Mobile browsers ## Next Steps -1. Create backend folder structure -2. Create frontend folder structure -3. Initialize package.json files -4. Create Dockerfile -5. Create docker-compose.yml -6. Begin MVP development \ No newline at end of file +1. ✅ Create backend folder structure +2. ✅ Create frontend folder structure +3. ✅ Initialize package.json files +4. ✅ Create Dockerfile +5. ✅ Create docker-compose.yml +6. ✅ Implement MVP features +7. ✅ Add drag & drop upload +8. ✅ Add clipboard paste +9. ✅ Add smart presets +10. ✅ Add keyboard shortcuts +11. [ ] Implement batch processing +12. [ ] Add advanced crop tool +13. [ ] Add watermarking +14. [ ] Add filters/effects + +## Resources + +- [Sharp Documentation](https://sharp.pixelplumbing.com/) +- [Svelte Documentation](https://svelte.dev/docs) +- [Canvas API Reference](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) +- [Drag and Drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API) +- [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) \ No newline at end of file