2026-03-08 21:40:08 -05:00
2 changed files with 240 additions and 54 deletions
--- 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
+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)
--- 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
+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