jason/pnger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update INSTRUCTIONS with Sprint 1 completed features

Browse Source
This commit is contained in:
jason
2026-03-08 21:38:49 -05:00
parent 98f03c9b22
commit a9da791766
1 changed files with 171 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
INSTRUCTIONS.md
View File

@@ -6,35 +6,41 @@ PNGer is a single-container web application for PNG editing and resizing, design
## Development Roadmap ## Development Roadmap
### Phase 1: MVP Foundation (Current) ### Phase 1: MVP Foundation (Completed ✅)
- [x] Repository setup - [x] Repository setup
- [ ] Project structure initialization - [x] Project structure initialization
- [ ] Backend API scaffold - [x] Backend API scaffold
- [ ] Frontend scaffold - [x] Frontend scaffold
- [ ] Basic upload/download flow - [x] Basic upload/download flow
- [ ] Dockerfile configuration - [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 ### Phase 2: Sprint 1 - Enhanced UX (Completed ✅)
- [ ] Image resize functionality - [x] Drag & drop file upload
- [ ] PNG compression - [x] Clipboard paste (Ctrl+V)
- [ ] Real-time preview - [x] Smart presets (8 configurations)
- [ ] Responsive UI design - [x] Keyboard shortcuts (Enter, Ctrl+Enter, ?, Esc)
- [ ] Error handling - [x] Enhanced visual feedback
- [x] Responsive UI improvements
- [x] Theme contrast fixes
### Phase 3: Polish & Deployment ### Phase 3: Advanced Features (Upcoming)
- [ ] Docker Compose for Unraid - [ ] Batch processing
- [ ] Environment configuration - [ ] Advanced crop tool with visual selector
- [ ] Documentation - [ ] Watermarking
- [ ] Testing - [ ] Image filters and effects
- [ ] Production build optimization - [ ] Undo/redo functionality
- [ ] History/recent files
## Technical Architecture ## Technical Architecture
### Backend (Express + Sharp) ### Backend (Express + Sharp)
**Endpoints:** **Endpoints:**
- `POST /api/upload` - Accept PNG file - `POST /api/transform` - Transform image (resize, crop, compress, convert)
- `POST /api/process` - Resize/compress image
- `GET /api/health` - Health check - `GET /api/health` - Health check
**Key Dependencies:** **Key Dependencies:**
@@ -46,11 +52,21 @@ PNGer is a single-container web application for PNG editing and resizing, design
### Frontend (Svelte + Vite) ### Frontend (Svelte + Vite)
**Components:** **Components:**
- `App.svelte` - Main container - `App.svelte` - Main container with all features
- `Uploader.svelte` - Drag & drop interface - `lib/api.ts` - API client
- `Editor.svelte` - Resize controls - `lib/preview.ts` - Live preview logic using Canvas API
- `Preview.svelte` - Real-time image preview - `lib/theme.ts` - Dark/light theme management
- `Download.svelte` - Download button - `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:** **Key Dependencies:**
- svelte: Reactive framework - 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 git clone https://git.alwisp.com/jason/pnger.git
cd pnger cd pnger
# Install root dependencies (if monorepo)
npm install
# Setup backend # Setup backend
cd backend cd backend
npm install npm install
@@ -110,7 +123,7 @@ npm run dev
``` ```
PORT=3000 PORT=3000
NODE_ENV=development NODE_ENV=development
MAX_FILE_SIZE=10 MAX_FILE_SIZE=10485760
CORS_ORIGIN=http://localhost:5173 CORS_ORIGIN=http://localhost:5173
``` ```
@@ -167,21 +180,65 @@ docker-compose up -d
## Code Standards ## Code Standards
### JavaScript/Svelte ### JavaScript/TypeScript
- Use ES6+ features - Use ES6+ features
- Async/await for asynchronous operations - Async/await for asynchronous operations
- Descriptive variable names - Descriptive variable names
- Comments for complex logic only - Comments for complex logic only
- Type safety with TypeScript
### File Organization ### File Organization
- One component per file - One component per file
- Group related utilities - Group related utilities
- Keep components under 200 lines - Keep components under 300 lines (split if larger)
- Organize by feature when possible
### Commit Messages ### Commit Messages
- Format: `type: description` - 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` - 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 ## Troubleshooting
@@ -202,27 +259,101 @@ npm rebuild sharp
- Verify Dockerfile syntax - Verify Dockerfile syntax
- Clear Docker cache: `docker builder prune` - 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 ## Performance Targets
- Upload handling: < 100ms (for 5MB file) - Upload handling: < 100ms (for 5MB file)
- Image processing: < 2s (for 10MP image) - Image processing: < 2s (for 10MP image)
- Download generation: < 500ms - Download generation: < 500ms
- UI response time: < 100ms - UI response time: < 100ms
- Preview generation: < 500ms (client-side)
- Docker image size: < 150MB - Docker image size: < 150MB
## Security Considerations ## Security Considerations
- File type validation (PNG only) - File type validation (image/* only)
- File size limits (10MB default) - File size limits (10MB default, configurable)
- No persistent storage of user files - No persistent storage of user files
- Memory cleanup after processing - Memory cleanup after processing
- CORS configuration - 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 ## Next Steps
1. Create backend folder structure 1. ✅ Create backend folder structure
2. Create frontend folder structure 2. ✅ Create frontend folder structure
3. Initialize package.json files 3. ✅ Initialize package.json files
4. Create Dockerfile 4. ✅ Create Dockerfile
5. Create docker-compose.yml 5. ✅ Create docker-compose.yml
6. Begin MVP development 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)