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

cleanup

Browse Source
This commit is contained in:
jason
2026-03-12 10:59:06 -05:00
parent c65355a43b
commit faa206d44b
7 changed files with 148 additions and 2173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
INSTRUCTIONS.md
View File

@@ -1,86 +1,76 @@
# PNGer Development Instructions
# PNGer Development & Technical Instructions
## Project Overview
PNGer is a single-container web application for PNG editing and resizing, designed for deployment on Unraid with Gitea version control.
## Development Roadmap
### Phase 1: MVP Foundation (Completed ✅)
- [x] Repository setup
- [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: 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: Advanced Features (Upcoming)
- [ ] Batch processing
- [ ] Advanced crop tool with visual selector
- [ ] Watermarking
- [ ] Image filters and effects
- [ ] Undo/redo functionality
- [ ] History/recent files
PNGer is a single-container web application for PNG editing and resizing, designed for deployment on Unraid with Gitea version control. It features a modern Svelte frontend and a high-performance Node.js/Sharp backend.
## Technical Architecture
### Architecture Overview
PNGer uses a multi-layered architecture designed for responsiveness and efficiency:
```mermaid
graph TD
A[User Browser] --> B[Svelte Frontend]
B --> C[Canvas API (Live Preview)]
B --> D[Express API (Backend)]
D --> E[Sharp Image Library]
D --> F[Runtime Environment (Docker)]
```
### Backend (Express + Sharp)
**Endpoints:**
The backend is built with Node.js and TypeScript, using Express for the API and Sharp for high-performance image processing.
**Key Endpoints:**
- `POST /api/transform` - Transform image (resize, crop, compress, convert)
- `GET /api/health` - Health check
**Key Dependencies:**
- express: Web framework
- multer: File upload handling
- sharp: Image processing
- cors: Cross-origin support
- `sharp`: High-performance image processing (handles resizing, cropping, and format conversion).
- `multer`: Middleware for handling `multipart/form-data`, used for file uploads.
- `express`: Web framework for the API.
### Frontend (Svelte + Vite)
**Components:**
- `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
The frontend is a reactive Svelte application that prioritizes real-time feedback and UX.
**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
**Core Components & Modules:**
- `App.svelte`: Main application container managing state and UI.
- `lib/api.ts`: API client for backend communication.
- `lib/preview.ts`: Client-side preview logic using the Canvas API for instant feedback.
- `lib/theme.ts`: Dark/light theme management with persistent storage.
- `lib/presets.ts`: Configuration for smart image presets.
**Key Dependencies:**
- svelte: Reactive framework
- vite: Build tool
- axios: HTTP client
### Design System (Dark/Light Modes)
### Docker Strategy
The UI uses a modern design system with CSS custom properties for theming:
- **Light Mode**: Clean white background with dark gold (`#b8860b`) accents.
- **Dark Mode**: Deep black (`#0a0a0a`) background with light gold (`#daa520`) accents.
- **Transparencies**: Dark/Light toggling allows users to inspect PNG transparency against different backgrounds.
**Multi-stage Build:**
1. Stage 1: Build frontend (Vite build)
2. Stage 2: Copy frontend + setup backend
3. Final image: Alpine-based Node.js
## Implementation Details
**Image Size Target:** < 150MB
### Live Preview System
Live preview is implemented using a client-side Canvas-based approach to provide instant feedback (< 100ms) without server round-trips.
**How it works:**
1. User uploads an image.
2. The browser loads the image into an HTML5 Canvas.
3. On any parameter change (width, quality, etc.), a debounced (300ms) update applies transformations to the canvas.
4. The canvas content is displayed side-by-side with the original for comparison.
5. File sizes are estimated from the Canvas data URL to provide immediate feedback on optimization savings.
### Docker Strategy & Fixes
PNGer uses a multi-stage Docker build to minimize image size and maximize security.
**Optimization Fixes applied:**
- **Dependency Installation**: Uses `npm install` instead of `npm ci` to handle missing lockfiles gracefully while maintaining stability via caret ranges in `package.json`.
- **Security**: Runs as a non-root `node` user in the final Alpine-based image.
- **Multer Upgrade**: Upgraded to `v2.1.0` for improved security and performance.
## Local Development Setup
@@ -89,7 +79,7 @@ PNGer is a single-container web application for PNG editing and resizing, design
- npm or pnpm
- Docker (optional)
### Initial Setup
### Setup Steps
```bash
# Clone repository
@@ -101,259 +91,44 @@ cd backend
npm install
npm run dev
# Setup frontend (new terminal)
# Setup frontend (separate terminal)
cd frontend
npm install
npm run dev
```
### Development Workflow
1. **Feature Branch**: Create from `main`
2. **Develop**: Make changes with hot-reload
3. **Test**: Manual testing + health checks
4. **Commit**: Descriptive commit messages
5. **Push**: Push to Gitea
6. **Review**: Self-review changes
7. **Merge**: Merge to `main`
### Environment Variables
**Backend (.env):**
```
PORT=3000
NODE_ENV=development
MAX_FILE_SIZE=10485760
CORS_ORIGIN=http://localhost:5173
```
- `PORT`: 3000 (internal)
- `MAX_FILE_SIZE`: 10485760 (10MB default)
- `CORS_ORIGIN`: http://localhost:5173
**Frontend (.env):**
```
VITE_API_URL=http://localhost:3000/api
```
- `VITE_API_URL`: http://localhost:3000/api
## Docker Build & Test
## Development Workflow & Standards
```bash
# Build image
docker build -t pnger:test .
### Workflow
1. **Feature Branch**: Create from `main`.
2. **Develop**: Use hot-reload (`npm run dev`).
3. **Test**: Perform manual testing of image operations and presets.
4. **Commit**: Use `type: description` format (e.g., `feat: add rotation`).
5. **Merge**: Merge into `main` after review.
# Run container
docker run -p 8080:3000 --name pnger-test pnger:test
# Test endpoints
curl http://localhost:8080/api/health
# View logs
docker logs pnger-test
# Stop and remove
docker stop pnger-test && docker rm pnger-test
```
## Unraid Deployment
### Setup Steps
1. **SSH into Unraid**
2. **Navigate to docker configs**: `/mnt/user/appdata/pnger`
3. **Clone repository**:
```bash
git clone https://git.alwisp.com/jason/pnger.git
cd pnger
```
4. **Build and run**:
```bash
docker-compose up -d
```
5. **Access**: http://[unraid-ip]:8080
### Update Process
```bash
cd /mnt/user/appdata/pnger
git pull origin main
docker-compose down
docker-compose build
docker-compose up -d
```
## Code Standards
### 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 300 lines (split if larger)
- Organize by feature when possible
### Commit Messages
- Format: `type: description`
- 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
### Code Standards
- **TypeScript**: Use strict types where possible.
- **Svelte**: Keep components modular and under 300 lines.
- **Async/Await**: Use for all asynchronous operations.
- **Semantic HTML**: Ensure accessibility and proper structure.
## Troubleshooting
### Common Issues
- **Port in use**: `lsof -ti:3000 | xargs kill -9`
- **Sharp issues**: `npm rebuild sharp`
- **Docker Cache**: `docker builder prune` if builds fail unexpectedly.
- **Preview Glitches**: Check browser console for Canvas API errors.
**Port already in use:**
```bash
lsof -ti:3000 | xargs kill -9
```
---
**Sharp installation issues:**
```bash
npm rebuild sharp
```
**Docker build fails:**
- Check Docker daemon is running
- 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 (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. ✅ 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)
**Last Updated**: March 12, 2026