From 98f03c9b221e9e5b08d88fa7fd5b844f6f134e2b Mon Sep 17 00:00:00 2001 From: jason Date: Sun, 8 Mar 2026 21:38:01 -0500 Subject: [PATCH 1/2] docs: update README with Sprint 1 features (drag/drop, presets, shortcuts) --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 69 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 226cf38..af54e93 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PNGer - Modern PNG Editor & Resizer -A sleek, modern PNG editor and resizer with **live preview**, **dark/light mode theming**, and direct upload/download features. Built with TypeScript and deployed as a single Docker container on Unraid. +A sleek, modern PNG editor and resizer with **live preview**, **drag & drop**, **smart presets**, **keyboard shortcuts**, and **dark/light mode theming**. Built with TypeScript and deployed as a single Docker container on Unraid. ## ✨ Features @@ -26,12 +26,31 @@ A sleek, modern PNG editor and resizer with **live preview**, **dark/light mode - **Fit Modes**: Inside (resize only) or Cover (crop to fill) ### 🚀 Performance & Usability +- **Drag & Drop**: Drag images directly into the app or use file browser +- **Clipboard Paste**: Paste images with Ctrl+V (Cmd+V on Mac) +- **Smart Presets**: Quick access to common configurations: + - 📷 Web Optimized (1920x1080, 80% quality, WebP) + - 📱 Social Media (1080x1080, 85% quality, JPEG) + - 👤 Profile Picture (400x400, 90% quality, PNG) + - 📧 Email Friendly (800x600, 75% quality, JPEG) + - ⭐ Tiny Icon (64x64, 100% quality, PNG) + - 🔍 Retina 2x (2x dimensions, 90% quality) + - 💎 Icon Small (256x256, 95% quality, PNG) + - 🔶 Icon Large (512x512, 95% quality, PNG) +- **Keyboard Shortcuts**: Fast workflow with keyboard controls (see below) - **Direct Download**: No server-side storage, immediate download - **Modern UI**: Sleek, responsive TypeScript/Svelte design - **File Analysis**: Original size, transformed size, savings percentage - **Debounced Updates**: Smooth preview generation (300ms delay) - **Visual Feedback**: Loading states, error messages, success indicators +### ⌨️ Keyboard Shortcuts +- **Ctrl+V** (Cmd+V): Paste image from clipboard +- **Enter**: Transform & Download (works when input not focused) +- **Ctrl+Enter** (Cmd+Enter): Transform & Download (works anywhere) +- **?**: Show/hide keyboard shortcuts help +- **Esc**: Close shortcuts dialog + ## Tech Stack - **Frontend**: Svelte 4 + Vite + TypeScript @@ -162,7 +181,7 @@ docker run -d \ ``` pnger/ -├── frontend/ # Svelte + TypeScript application +├── frontend/ # Svelte + TypeScript application │ ├── src/ │ │ ├── App.svelte # Main UI component (with live preview) │ │ ├── main.ts # Entry point @@ -170,11 +189,12 @@ pnger/ │ │ └── lib/ │ │ ├── api.ts # API client │ │ ├── preview.ts # Live preview logic -│ │ └── theme.ts # Theme management store +│ │ ├── theme.ts # Theme management store +│ │ └── presets.ts # Smart presets configuration │ ├── package.json │ ├── tsconfig.json │ └── vite.config.ts -├── backend/ # Express + TypeScript API server +├── backend/ # Express + TypeScript API server │ ├── src/ │ │ ├── index.ts # Express server │ │ ├── routes/ @@ -183,20 +203,21 @@ pnger/ │ │ └── image.ts # TypeScript types │ ├── package.json │ └── tsconfig.json -├── Dockerfile # Multi-stage build (frontend + backend) -├── docker-compose.yml # Unraid deployment config +├── Dockerfile # Multi-stage build (frontend + backend) +├── docker-compose.yml # Unraid deployment config ├── ROADMAP.md # Feature roadmap -└── UI_UPGRADE_NOTES.md # UI upgrade documentation +├── SPRINT1_CHANGES.md # Sprint 1 implementation details +└── UI_UPGRADE_NOTES.md # UI upgrade documentation ``` ## How It Works -1. User uploads an image via the web interface +1. User uploads an image via drag & drop, file browser, or clipboard paste 2. **Live preview** generates instantly using Canvas API -3. User adjusts parameters (width, height, quality, format, etc.) +3. User adjusts parameters (width, height, quality, format, etc.) or selects a preset 4. Preview updates in real-time (debounced 300ms) 5. User sees file size comparison and savings -6. When satisfied, user clicks "Transform & Download" +6. When satisfied, user clicks "Transform & Download" or presses Enter 7. Frontend sends image + parameters to backend API 8. Backend processes using Sharp (resize, crop, compress, convert) 9. Processed image returned directly to browser @@ -250,20 +271,48 @@ All configuration is handled via environment variables passed through Docker/Unr - **Instant Updates**: Debounced at 300ms for smooth performance - **Canvas-Based**: No server load, runs in browser +### Drag & Drop Upload +- **Drop Zone**: Large, responsive drop target with visual feedback +- **Multiple Methods**: Drag & drop, click to browse, or paste from clipboard +- **File Validation**: Instant validation with clear error messages +- **Visual States**: Hover and dragging states for better UX + +### Smart Presets +- **8 Pre-configured Options**: Common use cases ready to go +- **One-Click Apply**: Instantly sets all parameters +- **Visual Icons**: Easy identification of each preset +- **Responsive Grid**: Adapts to screen size + +### Keyboard Shortcuts +- **Productivity Focused**: Common operations accessible via keyboard +- **Help Dialog**: Press ? to see all shortcuts +- **Context Aware**: Enter works differently based on focus +- **Cross-Platform**: Supports both Ctrl and Cmd modifiers + ### Image Analysis - Original file size displayed - Preview size estimation - Savings/increase percentage - Visual feedback with color coding +## Recent Updates (Sprint 1) + +✅ **Drag & Drop Upload** - Drag images directly into the app +✅ **Clipboard Paste** - Paste images with Ctrl+V +✅ **Smart Presets** - 8 quick-access presets for common scenarios +✅ **Keyboard Shortcuts** - Fast workflow with keyboard controls +✅ **Enhanced UX** - Better visual feedback and error handling +✅ **Theme Contrast Fixes** - Improved text visibility in both themes + +See [SPRINT1_CHANGES.md](./SPRINT1_CHANGES.md) for detailed implementation notes. + ## Roadmap See [ROADMAP.md](./ROADMAP.md) for planned features including: -- Drag & drop upload - Batch processing -- Smart presets +- Advanced crop tool with visual selector - Watermarking -- Advanced crop tool +- Image filters and effects - And more! ## License @@ -283,4 +332,10 @@ Clean white interface with dark gold accents, perfect for inspecting dark images Sleek black interface with light gold accents, ideal for viewing light/transparent PNGs ### Live Preview -Side-by-side comparison showing original and transformed image with file size analysis \ No newline at end of file +Side-by-side comparison showing original and transformed image with file size analysis + +### Smart Presets +Quick-access buttons for common image optimization scenarios + +### Keyboard Shortcuts +Built-in help dialog showing all available shortcuts \ No newline at end of file From a9da79176602221c8c5e92cc166ec42991e9fb5d Mon Sep 17 00:00:00 2001 From: jason Date: Sun, 8 Mar 2026 21:38:49 -0500 Subject: [PATCH 2/2] docs: update INSTRUCTIONS with Sprint 1 completed features --- INSTRUCTIONS.md | 211 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 171 insertions(+), 40 deletions(-) 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