docs: rewrite README to FLEET layout (docs index, what it does, shape, known rough edges)

docs: update Unraid guide for registry image, inert MAX_FILE_SIZE, stateless volumes
docs: correct technical notes (no /api/health, unused env vars, dead server.js, preview caveats)
2026-07-31 21:19:16 -05:00 · 2026-07-31 21:19:15 -05:00 · 2026-07-31 21:19:14 -05:00 · 2026-07-31 21:19:13 -05:00 · 2026-07-31 21:19:12 -05:00 · 2026-07-31 21:19:11 -05:00
17 changed files with 1117 additions and 1780 deletions
@@ -0,0 +1,47 @@
 name: Build and Push Docker Image
 on:
  push:
    branches: [main]
  workflow_dispatch:
 jobs:
  build:
    # Runs on the forgerunner host: bundled Docker CLI + mounted /var/run/docker.sock.
    runs-on: host
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # Full history so `git rev-list --count HEAD` yields the true commit count
          # driving both the app version (v1.NNN) and the org.alwisp.version label.
          fetch-depth: 0
      - name: Log in to Gitea Container Registry
        uses: docker/login-action@v3
        with:
          registry: registry.alwisp.com
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_TOKEN }}
      - name: Build and Push
        run: |
          IMAGE="registry.alwisp.com/${{ gitea.repository }}"
          GIT_SHA="$(git rev-parse --short HEAD)"
          BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
          COMMIT_COUNT="$(git rev-list --count HEAD)"
          docker build \
            --build-arg GIT_SHA="${GIT_SHA}" \
            --build-arg BUILD_TIME="${BUILD_TIME}" \
            --build-arg COMMIT_COUNT="${COMMIT_COUNT}" \
            --label org.alwisp.git-sha="${{ gitea.sha }}" \
            --label org.alwisp.version="v1.$((COMMIT_COUNT-1))" \
            --label org.alwisp.repo="${{ gitea.repository }}" \
            -t "${IMAGE}:latest" .
          docker push "${IMAGE}:latest"
      # Dangling-only prune: removes untagged leftovers from previous builds. Never
      # removes the tagged :latest or any image referenced by a running container.
      - name: Prune dangling images on host
        if: always()
        run: docker image prune -f 2>/dev/null || true
@@ -1,167 +0,0 @@
 # Docker Build Fix - Simplified Dependency Installation
 ## Issue
 Docker build was failing with:
 ```
 npm error The `npm ci` command can only install with an existing package-lock.json
 ```
 ## Root Cause
 The original Dockerfile used `npm ci` which requires fully resolved `package-lock.json` files. These lockfiles were missing and stub lockfiles don't work because `npm ci` requires the complete dependency tree.
 ## Solution Applied
 ### Simplified Approach
 The Dockerfile now uses **`npm install`** instead of `npm ci`. This is simpler and more reliable:
 ```dockerfile
 RUN npm install
 ```
 **Why this works:**
 - ✅ No lockfile required
 - ✅ Automatically resolves and installs all dependencies
 - ✅ Works consistently across all environments
 - ✅ No manual lockfile maintenance needed
 - ✅ Simpler Dockerfile = easier to maintain
 ### Trade-offs
 | Approach | Speed | Lockfile Required | Deterministic | Maintenance |
 |----------|-------|-------------------|---------------|-------------|
 | `npm ci` | Fastest | ✅ Yes | ✅ Yes | High |
 | **`npm install`** | Fast | ❌ No | ⚠️ By version ranges | **Low** |
 **Note:** While `npm install` resolves versions at build time (not 100% deterministic), your `package.json` uses caret ranges (e.g., `^4.19.0`) which only allow minor/patch updates, providing reasonable stability.
 ### Files Modified
 1. **Dockerfile** - Simplified to use `npm install` in all three stages
 2. **.dockerignore** - Optimizes build context
 3. **backend/package.json** - Updated multer to v2.1.0 (v1.4.5 no longer exists)
 ### Dependency Updates
 - **multer**: `^1.4.5` → `^2.1.0` (security fixes, v1.x removed from npm)
 - **@types/multer**: `^1.4.7` → `^2.1.0` (matching types)
 ## How It Works
 ### Build Flow
 1. **Copy package.json** into build stage
 2. **Run npm install** - automatically resolves and installs all dependencies
 3. **Build the application**
 No lockfile generation or validation needed!
 ## Usage
 ### Build Docker Image
 ```bash
 docker build -t pnger:latest .
 ```
 The build will:
 - Install dependencies from npm registry
 - Build frontend and backend
 - Create production image with only runtime dependencies
 - Complete successfully every time
 ### Run Container
 ```bash
 docker run -d \
  -p 3000:3000 \
  -e MAX_FILE_SIZE=10485760 \
  --name pnger \
  pnger:latest
 ```
 ### Unraid Deployment
 The Docker image builds cleanly in Unraid without any configuration needed.
 ## Optional: Add Lockfiles for Deterministic Builds
 If you want 100% deterministic builds with locked dependency versions:
 ```bash
 # Generate lockfiles locally
 cd frontend && npm install && cd ..
 cd backend && npm install && cd ..
 # Commit them
 git add frontend/package-lock.json backend/package-lock.json
 git commit -m "Add lockfiles for deterministic builds"
 # Update Dockerfile to use npm ci instead of npm install
 ```
 **Benefits of lockfiles:**
 - Guaranteed exact dependency versions
 - Slightly faster builds
 - Better for production environments
 **Drawbacks:**
 - Must update lockfiles when changing dependencies
 - More complex maintenance
 ## Build Optimization
 The `.dockerignore` file excludes:
 - `node_modules/` (prevents copying local dependencies)
 - Development files (`.env`, `.vscode/`, etc.)
 - Build artifacts
 - Documentation and test files
 This keeps build context small and fast.
 ## Verification
 Test the complete build:
 ```bash
 # Build image
 docker build -t pnger:test .
 # Run container
 docker run -d -p 3000:3000 --name pnger-test pnger:test
 # Check health
 curl http://localhost:3000
 # View logs
 docker logs pnger-test
 # Cleanup
 docker stop pnger-test && docker rm pnger-test
 ```
 ## Technical Details
 ### Multi-Stage Build
 1. **frontend-builder**: Builds Svelte/Vite frontend with all dev dependencies
 2. **backend-builder**: Compiles TypeScript backend with all dev dependencies
 3. **production**: Combines compiled outputs with production dependencies only (`--omit=dev`)
 ### Security Features
 - Runs as non-root user (`node`)
 - Health check endpoint configured
 - Minimal production dependencies
 - Alpine Linux base (smaller attack surface)
 - No unnecessary dev tools in production image
 ### Multer v2.1.0 Upgrade
 Upgraded from v1.4.5 (no longer available) to v2.1.0:
 - ✅ Security fixes (CVE-2026-2359 and others)
 - ✅ Backward compatible API
 - ✅ Better performance
 - ✅ Active maintenance
 ---
 **Created**: 2026-03-08  
 **Branch**: `fix/add-package-lockfiles`  
 **Status**: Ready to merge  
 **Issue**: Docker build failing ✅ RESOLVED
@@ -32,6 +32,11 @@ RUN npm run build
 # Stage 3: Production Runtime
 FROM node:20-alpine
 # Upgrade existing packages to fix base image vulnerabilities, 
 # then install su-exec and shadow (for usermod/groupmod)
 RUN apk upgrade --no-cache && \
    apk add --no-cache su-exec shadow
 WORKDIR /app
 # Copy backend package files
@@ -48,17 +53,20 @@ COPY --from=backend-builder /app/backend/dist ./dist
 COPY --from=frontend-builder /app/frontend/dist ./dist/public
 # Create temp upload directory
-RUN mkdir -p /app/temp && \
+RUN mkdir -p /app/temp
    chown -R node:node /app
-# Switch to non-root user
+# Copy entrypoint script
-USER node
+COPY docker-entrypoint.sh /usr/local/bin/
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-# Environment variables (can be overridden via Unraid UI)
+# Environment variables (Unraid defaults and App defaults)
-ENV NODE_ENV=production
+ENV PUID=99 \
-ENV PORT=3000
+    PGID=100 \
-ENV MAX_FILE_SIZE=10485760
+    TZ=UTC \
-ENV TEMP_DIR=/app/temp
+    NODE_ENV=production \
    PORT=3000 \
    MAX_FILE_SIZE=10485760 \
    TEMP_DIR=/app/temp
 # Expose port
 EXPOSE 3000
@@ -67,5 +75,7 @@ EXPOSE 3000
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
 ENTRYPOINT ["docker-entrypoint.sh"]
 # Start server
 CMD ["node", "dist/index.js"]
@@ -1,228 +0,0 @@
 # PNGer Development 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 (Current)
 - [x] Repository setup
 - [ ] Project structure initialization
 - [ ] Backend API scaffold
 - [ ] Frontend scaffold
 - [ ] Basic upload/download flow
 - [ ] Dockerfile configuration
 ### Phase 2: Core Features
 - [ ] Image resize functionality
 - [ ] PNG compression
 - [ ] Real-time preview
 - [ ] Responsive UI design
 - [ ] Error handling
 ### Phase 3: Polish & Deployment
 - [ ] Docker Compose for Unraid
 - [ ] Environment configuration
 - [ ] Documentation
 - [ ] Testing
 - [ ] Production build optimization
 ## Technical Architecture
 ### Backend (Express + Sharp)
 **Endpoints:**
 - `POST /api/upload` - Accept PNG file
 - `POST /api/process` - Resize/compress image
 - `GET /api/health` - Health check
 **Key Dependencies:**
 - express: Web framework
 - multer: File upload handling
 - sharp: Image processing
 - cors: Cross-origin support
 ### 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
 **Key Dependencies:**
 - svelte: Reactive framework
 - vite: Build tool
 - axios: HTTP client
 ### Docker Strategy
 **Multi-stage Build:**
 1. Stage 1: Build frontend (Vite build)
 2. Stage 2: Copy frontend + setup backend
 3. Final image: Alpine-based Node.js
 **Image Size Target:** < 150MB
 ## Local Development Setup
 ### Prerequisites
 - Node.js 20+
 - npm or pnpm
 - Docker (optional)
 ### Initial Setup
 ```bash
 # Clone repository
 git clone https://git.alwisp.com/jason/pnger.git
 cd pnger
 # Install root dependencies (if monorepo)
 npm install
 # Setup backend
 cd backend
 npm install
 npm run dev
 # Setup frontend (new 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=10
 CORS_ORIGIN=http://localhost:5173
 ```
 **Frontend (.env):**
 ```
 VITE_API_URL=http://localhost:3000/api
 ```
 ## Docker Build & Test
 ```bash
 # Build image
 docker build -t pnger:test .
 # 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/Svelte
 - Use ES6+ features
 - Async/await for asynchronous operations
 - Descriptive variable names
 - Comments for complex logic only
 ### File Organization
 - One component per file
 - Group related utilities
 - Keep components under 200 lines
 ### Commit Messages
 - Format: `type: description`
 - Types: feat, fix, docs, style, refactor, test
 - Example: `feat: add drag and drop upload`
 ## Troubleshooting
 ### Common Issues
 **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`
 ## Performance Targets
 - Upload handling: < 100ms (for 5MB file)
 - Image processing: < 2s (for 10MP image)
 - Download generation: < 500ms
 - UI response time: < 100ms
 - Docker image size: < 150MB
 ## Security Considerations
 - File type validation (PNG only)
 - File size limits (10MB default)
 - No persistent storage of user files
 - Memory cleanup after processing
 - CORS configuration
 ## 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,286 +1,80 @@
-# PNGer - Modern PNG Editor & Resizer
+# 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, self-hosted image resizer with **live preview**, **drag & drop**, **smart presets**, **keyboard shortcuts**, and **dark/light theming**. Drop an image in, watch the before/after and the file-size delta update as you drag the sliders, hit Enter, get the file. Nothing is stored on the server — uploads are processed in memory and streamed straight back as a download.
-## ✨ Features
+Svelte + Vite on the front, Express + [Sharp](https://sharp.pixelplumbing.com/) on the back, shipped as one Docker container that serves both. Built for Unraid.
-### 🎨 Modern UI with Dark/Light Mode
+Despite the name it is not PNG-only: it reads anything Sharp can decode and writes **PNG, WebP or JPEG**.
 - **Dark Mode**: Black background (#0a0a0a) with light gold (#daa520) accents
 - **Light Mode**: White background with dark gold (#b8860b) accents
 - Perfect for inspecting PNG transparency on different backgrounds
 - Persistent theme preference
 - Smooth color transitions
-### ⚡ Live Preview
+## Docs
 - **Real-time preview** of transformations before download
 - **Side-by-side comparison** (original vs transformed)
 - **File size analysis** showing savings or increase
 - **Instant feedback** using client-side Canvas API (< 500ms)
 - No server round-trip needed for preview
-### 🖼️ Image Operations
+- **[Installation & configuration guide](docs/INSTALL.md)** — start here. Local dev, Docker, `docker compose`, the full env-var table, CI, health checks, upgrades.
- **Resize Operations**: Width, height, and aspect ratio controls
+- **[Unraid install](docs/UNRAID.md)** — step-by-step Docker GUI walkthrough (template fields, PUID/PGID/TZ, ports).
- **Crop to Fit**: Smart cropping with position control (9 positions)
+- **[Development & technical notes](docs/INSTRUCTIONS.md)** — architecture, the live-preview design, code standards, troubleshooting.
- **Format Conversion**: PNG, WebP, and JPEG output
+- **[Roadmap](docs/ROADMAP.md)** — what shipped in Sprints 0–1 and what is queued for Sprints 2–4.
 - **Quality Control**: Adjustable compression settings (10-100%)
 - **Fit Modes**: Inside (resize only) or Cover (crop to fill)
-### 🚀 Performance & Usability
+## What it does
 - **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
-## Tech Stack
+- **Resizes and crops** — set a width, a height, or both. *Resize only* (`fit: inside`) preserves aspect ratio; *Crop to fit box* (`fit: cover`) fills the box and crops the overflow from one of **nine anchor positions** (center, the four edges, the four corners).
 - **Converts and compresses** — output as PNG (compression level 9), WebP or JPEG, with a 1–100 quality control.
 - **Previews client-side before it touches the server** — the browser re-renders the image on a `<canvas>` 300 ms after you stop typing, so you get a side-by-side original/result comparison plus an estimated file-size delta ("↓ 412.3 KB saved (68.1%)") with no round-trip. Only the final download hits the API.
 - **Eight smart presets** — Web Thumbnail (300×300 WebP), Social Media / Open Graph (1200×630), Profile Picture (400×400), Email Friendly (600 wide JPEG q70), HD Quality (1920 wide), Retina @2x (doubles whatever you have typed), Icon Small (64×64) and Icon Large (256×256). One click sets width, height, quality, format and fit.
 - **Gets images in three ways** — drag & drop onto the drop zone, click to browse, or paste from the clipboard with `Ctrl+V` / `Cmd+V`.
 - **Themes light or dark** — gold-accented design system driven by CSS custom properties, remembered in `localStorage`, defaulting to your OS `prefers-color-scheme`. The point is practical: toggle the background to check PNG transparency against black and white.
 - **Stores nothing** — `multer` keeps the upload in memory, Sharp transforms it, Express sends the buffer back with `Content-Disposition: attachment`. No database, no disk writes, no cleanup job.
- **Frontend**: Svelte 4 + Vite + TypeScript
+## Keyboard shortcuts
 - **Backend**: Node.js + Express + TypeScript
 - **Image Processing**: Sharp (high-performance image library)
 - **Preview**: Canvas API (client-side)
 - **Container**: Docker (Alpine-based, multi-stage build)
 - **Deployment**: Unraid via Docker Compose
-## Quick Start
+| Key | Action |
 | --- | --- |
 | `Ctrl+V` / `Cmd+V` | Paste an image from the clipboard |
 | `Enter` | Transform & download (when no input is focused) |
 | `Ctrl+Enter` / `Cmd+Enter` | Transform & download (works from anywhere) |
 | `?` | Toggle the shortcuts dialog |
 | `Esc` | Close the shortcuts dialog |
-### Unraid Deployment (Recommended)
+## Shape
-1. **Clone or pull this repository to your Unraid server:**
+- **Stack** — frontend: Svelte 4 + Vite 5 + TypeScript, no UI framework, no router, one `App.svelte` plus four `lib/` modules (`api`, `preview`, `presets`, `theme`). Backend: Node 20 + Express 4 + TypeScript, `sharp` for the pixels, `multer` (memory storage) for the upload, `cors`.
-   ```bash
+- **API** — one endpoint. `POST /api/transform`, `multipart/form-data`, field `file`, with optional `width`, `height`, `quality` (default 80), `format` (`png` | `webp` | `jpeg`, default `png`), `fit` (default `inside`) and `position` (default `center`). Responds with the image bytes as an attachment, or `400` if no file / `500` if Sharp throws. Resizes use `withoutEnlargement: true`, so output is never larger than the source.
-   cd /mnt/user/appdata
+- **Data** — none. Stateless; no volumes required.
-   git clone https://git.alwisp.com/jason/pnger.git
+- **Serving** — in production the compiled frontend is copied to `dist/public` and served by the same Express process that answers `/api`, with an `app.get("*")` fallback to `index.html` for SPA routing. One port, one origin, no CORS in play.
-   cd pnger
+- **Hosting** — three-stage Docker build (frontend build → backend `tsc` → `node:20-alpine` runtime with `apk upgrade`, `su-exec` + `shadow`). `docker-entrypoint.sh` remaps the `node` user to `PUID`/`PGID` (Unraid defaults 99/100), chowns `/app`, then drops privileges. Listens on `3000`, `HEALTHCHECK` every 30 s, `EXPOSE 3000`. CI builds on every push to `main` and pushes `registry.alwisp.com/jason/pnger:latest`.
   ```
-2. **Build the Docker image:**
+## Quick start
   ```bash
   docker build -t pnger:latest .
   ```
-3. **Run via docker-compose:**
+**Docker (single container):**
   ```bash
   docker compose up -d
   ```
 4. **Access the application:**
   - Navigate to `http://[unraid-ip]:8080`
 ### Unraid Environment Variables (Configurable via UI)
 When setting up in Unraid Docker UI, you can configure:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `HOST_PORT` | `8080` | External port to access the app |
 | `MAX_FILE_SIZE` | `10485760` | Max upload size in bytes (10MB default) |
 | `MEM_LIMIT` | `512m` | Memory limit for container |
 | `CPU_LIMIT` | `1.0` | CPU limit (1.0 = 1 full core) |
 | `NODE_ENV` | `production` | Node environment |
 ### Unraid Docker Template Example
 ```xml
 <?xml version="1.0"?>
 <Container version="2">
  <Name>pnger</Name>
  <Repository>pnger:latest</Repository>
  <Network>bridge</Network>
  <Privileged>false</Privileged>
  <WebUI>http://[IP]:[PORT:8080]</WebUI>
  <Config Name="WebUI Port" Target="3000" Default="8080" Mode="tcp" Description="Port for web interface" Type="Port" Display="always" Required="true" Mask="false">8080</Config>
  <Config Name="Max File Size" Target="MAX_FILE_SIZE" Default="10485760" Mode="" Description="Maximum upload file size in bytes" Type="Variable" Display="advanced" Required="false" Mask="false">10485760</Config>
  <Config Name="Memory Limit" Target="" Default="512m" Mode="" Description="Container memory limit" Type="Variable" Display="advanced" Required="false" Mask="false">512m</Config>
 </Container>
 ```
 ## Local Development
 ### Prerequisites
 - Node.js 20+
 - npm or yarn
 ### Setup
 1. **Install backend dependencies:**
   ```bash
   cd backend
   npm install
   ```
 2. **Install frontend dependencies:**
   ```bash
   cd frontend
   npm install
   ```
 3. **Run development servers:**
   Terminal 1 (Backend):
   ```bash
   cd backend
   npm run dev
   ```
   Terminal 2 (Frontend):
   ```bash
   cd frontend
   npm run dev
   ```
 4. **Access dev server:**
   - Frontend: `http://localhost:5173`
   - Backend API: `http://localhost:3000/api`
 ### Building for Production
 ```bash
-# Backend TypeScript compilation
+git clone https://git.alwisp.com/jason/pnger.git
-cd backend
+cd pnger
-npm run build
+docker compose up -d --build
 # Frontend build
 cd frontend
 npm run build
 ```
-## Docker Deployment (Manual)
+Then open <http://localhost:8080> (host port is `HOST_PORT`, default `8080` → container `3000`).
 **Local development** — two terminals, Node 20+:
 ```bash
-# Build the image (all dependencies and builds are handled internally)
+cd backend  && npm install && npm run dev    # tsc watch on :3000
-docker build -t pnger:latest .
+cd frontend && npm install && npm run dev    # Vite on :5173
 # Run the container
 docker run -d \
  --name pnger \
  -p 8080:3000 \
  -e MAX_FILE_SIZE=10485760 \
  --restart unless-stopped \
  pnger:latest
 ```
-## Project Structure
+Open <http://localhost:5173>. In dev the frontend calls `http://localhost:3000/api` directly (`import.meta.env.DEV` branch in `lib/api.ts`); in a production build it calls the same-origin `/api`.
-```
+Full details, env vars and the Unraid path: **[docs/INSTALL.md](docs/INSTALL.md)**.
 pnger/
 ├── frontend/                # Svelte + TypeScript application
 │   ├── src/
 │   │   ├── App.svelte      # Main UI component (with live preview)
 │   │   ├── main.ts         # Entry point
 │   │   ├── app.css         # Design system (dark/light modes)
 │   │   └── lib/
 │   │       ├── api.ts      # API client
 │   │       ├── preview.ts  # Live preview logic
 │   │       └── theme.ts    # Theme management store
 │   ├── package.json
 │   ├── tsconfig.json
 │   └── vite.config.ts
 ├── backend/                 # Express + TypeScript API server
 │   ├── src/
 │   │   ├── index.ts        # Express server
 │   │   ├── routes/
 │   │   │   └── image.ts    # Image transform endpoint
 │   │   └── types/
 │   │       └── image.ts    # TypeScript types
 │   ├── package.json
 │   └── tsconfig.json
 ├── Dockerfile               # Multi-stage build (frontend + backend)
 ├── docker-compose.yml       # Unraid deployment config
 ├── ROADMAP.md              # Feature roadmap
 └── UI_UPGRADE_NOTES.md     # UI upgrade documentation
 ```
-## How It Works
+## Known rough edges
-1. User uploads an image via the web interface
+Documented rather than hidden — see [docs/INSTRUCTIONS.md](docs/INSTRUCTIONS.md) for the detail:
 2. **Live preview** generates instantly using Canvas API
 3. User adjusts parameters (width, height, quality, format, etc.)
 4. Preview updates in real-time (debounced 300ms)
 5. User sees file size comparison and savings
 6. When satisfied, user clicks "Transform & Download"
 7. Frontend sends image + parameters to backend API
 8. Backend processes using Sharp (resize, crop, compress, convert)
 9. Processed image returned directly to browser
 10. Browser triggers automatic download
 11. No files stored on server (stateless operation)
-## API Endpoints
+- **The preview is an approximation.** It is a Canvas re-encode, not Sharp. Sizes are estimated from the data URL, PNG quality has no effect in Canvas (it is always lossless there) but does affect the real output, and the preview will happily upscale where the server will not.
 - **`MAX_FILE_SIZE` is not enforced.** It is set in the `Dockerfile`, compose file and Unraid docs, but the live upload middleware has no `limits`, so the value currently does nothing.
 - **`backend/src/server.js` is not the server.** It is an older standalone implementation (`/api/health`, `/api/process`, `/api/metadata`, helmet, PNG-only filter, size limits) that nothing compiles or runs. The live entrypoint is `backend/src/index.ts`.
-### POST /api/transform
+---
-Transform an image with resize, crop, and format conversion.
+**License**: MIT · **Repository**: <https://git.alwisp.com/jason/pnger>
-**Request:**
+---
- Method: `POST`
+*MPM — Born to Innovate. Built to Last.*
 - Content-Type: `multipart/form-data`
 - Body:
  - `file`: Image file (PNG/JPEG/WebP)
  - `width`: Target width (optional)
  - `height`: Target height (optional)
  - `quality`: Quality 10-100 (optional, default: 80)
  - `format`: Output format `png|webp|jpeg` (optional, default: `png`)
  - `fit`: Resize mode `inside|cover` (optional, default: `inside`)
  - `position`: Crop position when `fit=cover` (optional, default: `center`)
 **Response:**
 - Content-Type: `image/[format]`
 - Body: Transformed image binary
 ## Configuration
 All configuration is handled via environment variables passed through Docker/Unraid:
 - `PORT`: Server port (default: `3000`, internal)
 - `MAX_FILE_SIZE`: Maximum upload size in bytes (default: `10485760` = 10MB)
 - `TEMP_DIR`: Temporary directory for uploads (default: `/app/temp`)
 - `NODE_ENV`: Node environment (default: `production`)
 ## UI Features in Detail
 ### Dark/Light Mode
 - **Toggle Button**: Sun (☀️) / Moon (🌙) icon in header
 - **Persistent**: Saved to localStorage
 - **System Detection**: Uses OS preference on first visit
 - **Smooth Transitions**: Colors fade smoothly (250ms)
 - **Use Case**: Compare PNG transparency on black vs white backgrounds
 ### Live Preview
 - **Side-by-Side**: Original image on left, preview on right
 - **File Size**: Shows before and after sizes
 - **Savings Indicator**: Green for reduction, yellow for increase
 - **Instant Updates**: Debounced at 300ms for smooth performance
 - **Canvas-Based**: No server load, runs in browser
 ### Image Analysis
 - Original file size displayed
 - Preview size estimation
 - Savings/increase percentage
 - Visual feedback with color coding
 ## Roadmap
 See [ROADMAP.md](./ROADMAP.md) for planned features including:
 - Drag & drop upload
 - Batch processing
 - Smart presets
 - Watermarking
 - Advanced crop tool
 - And more!
 ## License
 MIT License - See LICENSE file for details
 ## Repository
 https://git.alwisp.com/jason/pnger
 ## Screenshots
 ### Light Mode
 Clean white interface with dark gold accents, perfect for inspecting dark images
 ### Dark Mode
 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
@@ -1,301 +0,0 @@
 # PNGer Feature Roadmap
 ## Current Features ✅
 - Basic image upload (file picker)
 - Width/height resizing
 - Aspect ratio control (inside/cover)
 - Crop positioning (9 positions)
 - Format conversion (PNG, WebP, JPEG)
 - Quality adjustment (10-100)
 - Direct download (no server storage)
 - Docker deployment
 ---
 ## Phase 1: Enhanced User Experience (Priority: HIGH)
 ### 1.1 Live Preview 🎯 **TOP PRIORITY**
 **Why**: Immediate visual feedback dramatically improves UX
 **Effort**: Medium | **Impact**: High
 - [ ] Real-time preview of transformations before download
 - [ ] Side-by-side comparison (original vs transformed)
 - [ ] Show file size reduction/increase
 - [ ] Display actual dimensions of output
 - [ ] Preview updates on parameter change (debounced)
 **Technical approach:**
 - Client-side preview using Canvas API for instant feedback
 - Optional: Server preview endpoint for accurate Sharp rendering
 - Show estimated vs actual file size
 ### 1.2 Drag & Drop Interface
 **Why**: More intuitive than file picker
 **Effort**: Low | **Impact**: Medium
 - [ ] Drag & drop zone for image upload
 - [ ] Visual feedback on drag over
 - [ ] Support multiple files (batch processing)
 - [ ] Show thumbnail of uploaded image
 ### 1.3 Batch Processing
 **Why**: Process multiple images at once
 **Effort**: Medium | **Impact**: High
 - [ ] Upload multiple images
 - [ ] Apply same transformations to all
 - [ ] Download as ZIP file
 - [ ] Progress indicator for batch operations
 - [ ] Individual vs global settings per image
 ---
 ## Phase 2: Advanced Image Operations (Priority: MEDIUM-HIGH)
 ### 2.1 Smart Presets
 **Why**: Common use cases made easy
 **Effort**: Low | **Impact**: High
 - [ ] **Web Thumbnail** (300x300, WebP, 75% quality)
 - [ ] **Social Media** (1200x630 for OG images)
 - [ ] **Profile Picture** (square crop, various sizes)
 - [ ] **Email Friendly** (max 1MB, optimized)
 - [ ] **Retina Display** (@2x, @3x multipliers)
 - [ ] **Icon Set** (16, 32, 64, 128, 256px)
 - [ ] Custom preset saving
 ### 2.2 Image Optimization
 **Why**: Reduce file size without quality loss
 **Effort**: Low | **Impact**: High
 - [ ] **Auto-optimize** button (best compression/quality ratio)
 - [ ] Lossless PNG optimization
 - [ ] Strip EXIF metadata (privacy + size)
 - [ ] Progressive JPEG encoding
 - [ ] Show compression statistics
 ### 2.3 Additional Transformations
 **Why**: More creative control
 **Effort**: Medium | **Impact**: Medium
 - [ ] Rotation (90°, 180°, 270°, custom)
 - [ ] Flip (horizontal/vertical)
 - [ ] Grayscale conversion
 - [ ] Blur effect (with intensity)
 - [ ] Sharpen filter
 - [ ] Brightness/contrast adjustment
 - [ ] Border/padding addition
 ---
 ## Phase 3: Utilitarian Power Features (Priority: MEDIUM)
 ### 3.1 Image Analysis
 **Why**: Understand your images
 **Effort**: Low | **Impact**: Medium
 - [ ] Display image metadata (dimensions, format, color space)
 - [ ] File size analysis (before/after)
 - [ ] Color palette extraction
 - [ ] Dominant color detection
 - [ ] Transparency detection
 - [ ] Aspect ratio calculator
 ### 3.2 Custom Crop Tool
 **Why**: Precise control over cropping
 **Effort**: High | **Impact**: Medium
 - [ ] Visual crop selector (drag handles)
 - [ ] Aspect ratio lock
 - [ ] Freeform cropping
 - [ ] Rule of thirds grid overlay
 - [ ] Zoom for precision
 ### 3.3 Watermarking
 **Why**: Brand/protect images
 **Effort**: Medium | **Impact**: Medium
 - [ ] Text watermark with custom font
 - [ ] Image watermark overlay
 - [ ] Position control (9 positions + custom)
 - [ ] Opacity adjustment
 - [ ] Repeat pattern option
 ### 3.4 Image Comparison Tool
 **Why**: A/B test different settings
 **Effort**: Medium | **Impact**: Low-Medium
 - [ ] Compare 2-4 versions side-by-side
 - [ ] Slider to reveal differences
 - [ ] Quality vs file size comparison
 - [ ] Export comparison settings
 ---
 ## Phase 4: Workflow & Automation (Priority: LOW-MEDIUM)
 ### 4.1 API Access
 **Why**: Integrate with other tools
 **Effort**: Low | **Impact**: Medium
 - [ ] Generate API keys in UI
 - [ ] Rate limiting per key
 - [ ] Usage statistics dashboard
 - [ ] Webhook support for async processing
 - [ ] OpenAPI/Swagger documentation
 ### 4.2 Templates & Workflows
 **Why**: Reusable transformation pipelines
 **Effort**: Medium | **Impact**: Medium
 - [ ] Save transformation pipelines
 - [ ] Chain multiple operations
 - [ ] Share templates via URL
 - [ ] Import/export templates (JSON)
 - [ ] Community template gallery
 ### 4.3 History & Favorites
 **Why**: Quick access to common tasks
 **Effort**: Low | **Impact**: Low
 - [ ] Recent transformations (local storage)
 - [ ] Favorite presets
 - [ ] Quick re-apply last settings
 - [ ] Clear history button
 ---
 ## Phase 5: Extended Format Support (Priority: LOW)
 ### 5.1 More Input Formats
 **Effort**: Low-Medium | **Impact**: Medium
 - [ ] AVIF support (next-gen format)
 - [ ] TIFF support
 - [ ] SVG to raster conversion
 - [ ] ICO (favicon) generation
 - [ ] PDF to image (first page)
 - [ ] GIF frame extraction
 ### 5.2 Advanced Output Options
 **Effort**: Medium | **Impact**: Low
 - [ ] Multi-size export (responsive images)
 - [ ] Generate `<picture>` tag HTML
 - [ ] Create image sprites
 - [ ] Generate CSS for backgrounds
 ---
 ## Phase 6: Enterprise Features (Priority: LOW)
 ### 6.1 User Accounts (Optional)
 **Why**: For managed deployments
 **Effort**: High | **Impact**: Situational
 - [ ] User authentication
 - [ ] Per-user quotas
 - [ ] Saved presets sync
 - [ ] Usage analytics
 - [ ] Team collaboration
 ### 6.2 Cloud Storage Integration
 **Why**: Direct save to storage
 **Effort**: High | **Impact**: Low-Medium
 - [ ] S3/MinIO upload
 - [ ] Cloudflare Images integration
 - [ ] Google Drive export
 - [ ] Dropbox integration
 ---
 ## Quick Wins (Low Effort, High Impact)
 ### Immediate Improvements
 1. ✅ **Live Preview** - Phase 1.1 (start here!)
 2. ✅ **Smart Presets** - Phase 2.1
 3. ✅ **Drag & Drop** - Phase 1.2
 4. ✅ **Auto-optimize** - Phase 2.2
 5. ✅ **Image Analysis** - Phase 3.1
 ### UI/UX Polish
 - [ ] Dark mode support
 - [ ] Keyboard shortcuts (Ctrl+V paste, Enter to process)
 - [ ] Copy image to clipboard
 - [ ] Undo/redo support
 - [ ] Mobile-responsive design improvements
 - [ ] Loading skeletons instead of spinners
 - [ ] Toast notifications for actions
 - [ ] Image format auto-detection suggestions
 ---
 ## Technical Debt & Infrastructure
 ### Code Quality
 - [ ] Add unit tests (backend)
 - [ ] Add E2E tests (Playwright)
 - [ ] TypeScript strict mode
 - [ ] ESLint + Prettier configuration
 - [ ] CI/CD pipeline (GitHub Actions or Gitea Actions)
 - [ ] Code coverage reporting
 ### Performance
 - [ ] Image processing queue (for heavy operations)
 - [ ] Redis caching for repeated transforms
 - [ ] CDN integration
 - [ ] WebP/AVIF auto-detection based on browser support
 - [ ] Lazy loading for UI components
 - [ ] Service worker for offline support
 ### Security
 - [ ] Rate limiting (prevent abuse)
 - [ ] File type validation (magic bytes check)
 - [ ] Max file size enforcement (configurable)
 - [ ] CORS configuration
 - [ ] CSP headers
 - [ ] Input sanitization audit
 ### Monitoring
 - [ ] Prometheus metrics endpoint
 - [ ] Error tracking (Sentry integration)
 - [ ] Performance monitoring
 - [ ] Usage analytics (privacy-focused)
 ---
 ## Suggested Implementation Order
 **Sprint 1 (Week 1-2): MVP Enhancements**
 1. Live Preview (Phase 1.1) ⭐
 2. Drag & Drop (Phase 1.2)
 3. Image Analysis (Phase 3.1)
 4. Smart Presets (Phase 2.1)
 **Sprint 2 (Week 3-4): Power User Features**
 5. Batch Processing (Phase 1.3)
 6. Image Optimization (Phase 2.2)
 7. Additional Transformations (Phase 2.3)
 8. Keyboard shortcuts
 **Sprint 3 (Week 5-6): Polish & Advanced**
 9. Custom Crop Tool (Phase 3.2)
 10. Watermarking (Phase 3.3)
 11. API Access (Phase 4.1)
 12. Testing & bug fixes
 ---
 ## Community Ideas
 Have suggestions? Open an issue on the repository:
 - Feature requests
 - Bug reports
 - Use case discussions
 - Performance improvements
 **Maintainer**: jason  
 **Repository**: https://git.alwisp.com/jason/pnger  
 **Last Updated**: 2026-03-08
@@ -1,413 +0,0 @@
 # UI Upgrade - Dark Mode & Live Preview
 ## Overview
 This branch introduces a complete UI overhaul with modern design, dark/light mode theming, and real-time live preview functionality.
 ## What's New
 ### 🎨 Modern Design System
 **Color Themes:**
 - **Light Mode**: Clean white background with dark gold (#b8860b) accents
 - **Dark Mode**: Deep black (#0a0a0a) background with light gold (#daa520) accents
 - Smooth transitions between themes
 - System preference detection on first load
 **Design Tokens:**
 - CSS custom properties for consistent spacing, colors, shadows
 - Responsive typography scale
 - Smooth animations and transitions
 - Modern card-based layout
 - Professional shadows and borders
 ### 🌙 Dark/Light Mode Toggle
 - One-click theme switching
 - Persistent preference (localStorage)
 - Smooth color transitions
 - Icon indicators (☀️/🌙)
 - Perfect for comparing PNG transparency on different backgrounds
 ### ⚡ Live Preview
 **Instant Visual Feedback:**
 - Real-time preview updates as you adjust settings
 - Side-by-side comparison (original vs transformed)
 - No server round-trip required (client-side Canvas API)
 - Debounced updates (300ms) for performance
 **Preview Features:**
 - Shows exact transformations before download
 - File size comparison
 - Savings/increase indicator with percentage
 - Color-coded feedback (green = savings, yellow = increase)
 - Maintains aspect ratio and crop preview
 ### 📊 Enhanced Information Display
 - Original file name and size shown
 - Preview file size estimation
 - Savings calculation with visual indicators
 - Quality slider with percentage display
 - Clear visual separation of controls and preview
 ### 💅 Visual Improvements
 **Layout:**
 - Two-column grid layout (controls | preview)
 - Card-based design with subtle shadows
 - Proper spacing and visual hierarchy
 - Responsive design (mobile-friendly)
 **Interactions:**
 - Smooth hover effects on buttons
 - Focus states with accent color
 - Loading spinners for processing states
 - Fade-in animations
 - Button transforms on hover
 **Typography:**
 - System font stack (native look & feel)
 - Proper heading hierarchy
 - Readable line heights
 - Color-coded text (primary, secondary, accent)
 ## Files Modified
 ### New Files
 1. **`frontend/src/lib/preview.ts`**
   - Client-side preview generation using Canvas API
   - Image transformation calculations
   - File size estimation
   - Utility functions (debounce, format bytes, calculate savings)
 2. **`frontend/src/lib/theme.ts`**
   - Svelte store for theme management
   - localStorage persistence
   - System preference detection
   - Theme toggle functionality
 ### Updated Files
 3. **`frontend/src/app.css`**
   - Complete design system rewrite
   - CSS custom properties for theming
   - Dark mode support via `[data-theme="dark"]`
   - Modern component styles (buttons, inputs, cards)
   - Utility classes for layout
   - Responsive breakpoints
   - Custom scrollbar styling
   - Animation keyframes
 4. **`frontend/src/App.svelte`**
   - Complete UI restructuring
   - Two-column layout with grid
   - Live preview integration
   - Theme toggle button
   - Enhanced file upload UI
   - Clear file button
   - Improved error handling display
   - Loading states with spinners
   - Side-by-side image comparison
   - Savings indicator card
 ## Technical Details
 ### Preview Implementation
 **How it works:**
 1. User uploads image
 2. Canvas API loads image into memory
 3. Transformations applied client-side:
   - Resize calculations (aspect ratio aware)
   - Crop positioning (9 positions supported)
   - Quality adjustment via canvas.toDataURL()
 4. Preview updates on parameter change (debounced)
 5. File size estimated from base64 data URL
 **Performance:**
 - Debounced at 300ms to avoid excessive redraws
 - Canvas operations run on main thread (future: Web Worker)
 - Preview max size limited by browser memory
 - No server load for preview generation
 ### Theme System
 **Storage:**
 ```typescript
 localStorage.setItem('theme', 'dark' | 'light')
 ```
 **Application:**
 ```html
 <html data-theme="dark">
  <!-- CSS custom properties change based on data-theme -->
 </html>
 ```
 **CSS Variables:**
 ```css
 :root { --color-accent: #b8860b; } /* Light mode */
 [data-theme="dark"] { --color-accent: #daa520; } /* Dark mode */
 ```
 ### Design Tokens
 **Spacing Scale:**
 - xs: 0.25rem (4px)
 - sm: 0.5rem (8px)
 - md: 1rem (16px)
 - lg: 1.5rem (24px)
 - xl: 2rem (32px)
 - 2xl: 3rem (48px)
 **Color Palette:**
 | Light Mode | Dark Mode | Purpose |
 |------------|-----------|----------|
 | #ffffff | #0a0a0a | Primary BG |
 | #f8f9fa | #1a1a1a | Secondary BG |
 | #e9ecef | #2a2a2a | Tertiary BG |
 | #b8860b | #daa520 | Accent (Gold) |
 | #1a1a1a | #e9ecef | Text Primary |
 | #6c757d | #adb5bd | Text Secondary |
 **Shadows:**
 - sm: Subtle card elevation
 - md: Button hover states
 - lg: Modal/dropdown shadows
 - xl: Maximum elevation
 ## User Experience Improvements
 ### Before vs After
 **Before:**
 - Static form with no feedback
 - Download to see results
 - Trial and error workflow
 - Basic styling
 - No theme options
 **After:**
 - ✅ Real-time preview
 - ✅ See before download
 - ✅ Immediate feedback loop
 - ✅ Modern, professional design
 - ✅ Dark/light mode for different PNGs
 - ✅ File size visibility
 - ✅ Savings indicator
 ### Use Cases Enhanced
 1. **Comparing Transparency**
   - Toggle dark/light mode to see PNG transparency
   - Useful for logos, icons with transparency
 2. **Optimizing File Size**
   - See file size impact immediately
   - Adjust quality until size is acceptable
   - Green indicator shows successful optimization
 3. **Precise Cropping**
   - See crop position in real-time
   - Try all 9 positions visually
   - No guesswork needed
 4. **Format Comparison**
   - Compare PNG vs WebP vs JPEG quality
   - See size differences instantly
   - Make informed format choice
 ## Browser Compatibility
 **Tested On:**
 - Chrome 90+
 - Firefox 88+
 - Safari 14+
 - Edge 90+
 **Requirements:**
 - Canvas API support
 - CSS Custom Properties
 - localStorage
 - ES6 modules
 ## Performance Metrics
 **Preview Generation:**
 - Small images (< 1MB): ~50-100ms
 - Medium images (1-5MB): ~200-400ms
 - Large images (5-10MB): ~500ms-1s
 **Memory Usage:**
 - Canvas limited by browser (typically 512MB max)
 - Preview auto-cleanup on file change
 - No memory leaks detected
 ## Future Enhancements
 ### Planned (Not in This Branch)
 - [ ] Slider comparison (drag to reveal differences)
 - [ ] Zoom on preview for detail inspection
 - [ ] Web Worker for preview generation
 - [ ] Server-side preview option (Sharp accuracy)
 - [ ] Multiple preview sizes simultaneously
 - [ ] Drag & drop file upload
 - [ ] Batch preview mode
 ## Testing Checklist
 ### Manual Testing
 - [x] Upload PNG image
 - [x] Upload JPEG image
 - [x] Upload WebP image
 - [x] Adjust width only
 - [x] Adjust height only
 - [x] Adjust both dimensions
 - [x] Change quality slider
 - [x] Switch between formats
 - [x] Toggle fit mode (inside/cover)
 - [x] Test all 9 crop positions
 - [x] Toggle dark/light mode
 - [x] Verify theme persistence (refresh page)
 - [x] Clear file and re-upload
 - [x] Download transformed image
 - [x] Compare downloaded vs preview
 - [x] Test on mobile (responsive)
 ### Edge Cases
 - [ ] Very large image (> 10MB)
 - [ ] Very small image (< 10KB)
 - [ ] Square images
 - [ ] Panoramic images (extreme aspect ratios)
 - [ ] Images with transparency
 - [ ] Animated GIFs (should show first frame)
 ### Performance
 - [ ] Preview updates < 500ms
 - [ ] No UI blocking during preview
 - [ ] Smooth theme transitions
 - [ ] No console errors
 - [ ] Memory cleanup verified
 ## Deployment Notes
 ### Build Requirements
 - No new dependencies added
 - Uses existing Svelte + Vite setup
 - Compatible with current Docker build
 ### Breaking Changes
 - None - fully backward compatible
 - API unchanged
 - Old URL parameters still work
 ### Environment Variables
 - No new env vars required
 - Theme stored client-side only
 ## Usage Guide
 ### For End Users
 1. **Upload Image**: Click "Select Image" or use file picker
 2. **Adjust Settings**: Use controls on the left
 3. **Watch Preview**: See changes in real-time on the right
 4. **Toggle Theme**: Click sun/moon button for dark/light mode
 5. **Check Savings**: Green box shows file size reduction
 6. **Download**: Click "Transform & Download" when satisfied
 ### For Developers
 **Adding a New Control:**
 ```svelte
 <script>
  let newParam = defaultValue;
  $: if (file) updatePreview(); // Auto-trigger on change
 </script>
 <div>
  <label>New Parameter</label>
  <input bind:value={newParam} />
 </div>
 ```
 **Extending Theme:**
 ```css
 /* In app.css */
 :root {
  --color-new-token: #value;
 }
 [data-theme="dark"] {
  --color-new-token: #dark-value;
 }
 ```
 ## Screenshots (Conceptual)
 ### Light Mode
 ```
 ┌───────────────────────────────────────┐
 │ PNGer                    🌙 Dark │
 │ Modern PNG Editor & Resizer         │
 ├──────────────────┬────────────────────┤
 │ Upload & Transform │ Live Preview       │
 │                    │                    │
 │ [File picker]      │ [Original] [Prev]  │
 │ Width: [    ]      │                    │
 │ Height: [   ]      │ ↓ 450KB saved     │
 │ Quality: 80%       │                    │
 │ Format: PNG        │                    │
 │ [Download Button]  │                    │
 └──────────────────┴────────────────────┘
 ```
 ### Dark Mode
 ```
 ┌───────────────────────────────────────┐
 │ ✨PNGer✨                   ☀️ Light │
 │ Modern PNG Editor & Resizer         │
 ├──────────────────┬────────────────────┤
 │ 💻Upload & Transform│ 🖼️Live Preview      │
 │ (Black BG)         │ (Black BG)         │
 │ Gold accents       │ Gold borders       │
 └──────────────────┴────────────────────┘
 ```
 ## Merge Checklist
 - [x] All new files created
 - [x] All existing files updated
 - [x] No console errors
 - [x] Dark mode works
 - [x] Light mode works
 - [x] Theme persists across refreshes
 - [x] Preview generates correctly
 - [x] File size calculations accurate
 - [x] Responsive design tested
 - [ ] Ready to merge to main
 ---
 **Branch**: `feature/ui-upgrade-dark-mode-preview`  
 **Created**: 2026-03-08  
 **Status**: ✅ Ready for Testing  
 **Merge Target**: `main`  
 **Next Steps**:  
 1. Build and test locally
 2. Deploy to staging
 3. User acceptance testing
 4. Merge to main
 5. Deploy to production
@@ -10,10 +10,11 @@ services:
    ports:
      - "${HOST_PORT:-8080}:3000"
    environment:
      - PUID=${PUID:-99}
      - PGID=${PGID:-100}
      - TZ=${TZ:-UTC}
      - NODE_ENV=${NODE_ENV:-production}
      - PORT=3000
      - MAX_FILE_SIZE=${MAX_FILE_SIZE:-10485760}
      - TEMP_DIR=/app/temp
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
@@ -0,0 +1,23 @@
 #!/bin/sh
 set -e
 # Default to PUID 99 and PGID 100 if not specified
 PUID=${PUID:-99}
 PGID=${PGID:-100}
 echo "Starting with UID: $PUID, GID: $PGID"
 # Modify the 'node' user and group to match the provided PUID/PGID
 if [ "$(id -u node)" -ne "$PUID" ]; then
    usermod -o -u "$PUID" node
 fi
 if [ "$(id -g node)" -ne "$PGID" ]; then
    groupmod -o -g "$PGID" node
 fi
 # Ensure appropriate permissions on the application directory and temp dir
 chown -R node:node /app
 # Drop privileges to 'node' user and execute the command passed to the container
 exec su-exec node "$@"
@@ -0,0 +1,164 @@
 # Installation & configuration
 PNGer is a single stateless container: Express serves both the API and the compiled Svelte frontend on one port. There is no database, no persistent volume, and nothing to migrate.
 | Path | Use when | Where |
 | --- | --- | --- |
 | **Unraid Docker GUI** | Production on Unraid. | [UNRAID.md](UNRAID.md) — click-by-click. |
 | **`docker compose`** | Any Docker host. | §2 below. |
 | **Plain `docker run`** | Ad hoc. | §3 below. |
 | **Local Node** | Development. | §4 below. |
 ---
 ## 1. Prerequisites
 - **Docker** for the container paths. Nothing else — no runtime deps on the host.
 - **Node 20+ and npm** for local development. Sharp ships prebuilt binaries for common platforms; if `npm install` builds it from source you also need a C++ toolchain.
 - **A free host port.** The container listens on `3000`; the compose file publishes it on `8080` by default.
 No volume is required. No reverse proxy is required either, though you will want one if you expose it beyond the LAN — PNGer has **no authentication of any kind**.
 ---
 ## 2. `docker compose`
 ```bash
 git clone https://git.alwisp.com/jason/pnger.git
 cd pnger
 docker compose up -d --build
 ```
 Open <http://localhost:8080>.
 `docker-compose.yml` builds locally, tags `pnger:latest`, publishes `${HOST_PORT:-8080}:3000`, sets `restart: unless-stopped`, caps the container at `512m` / `1.0` CPU (`MEM_LIMIT` / `CPU_LIMIT`), rotates JSON logs at 10 MB × 3, and runs the same healthcheck as the image. Override anything through a `.env` file next to the compose file or through the shell environment:
 ```bash
 HOST_PORT=9000 TZ=America/Chicago docker compose up -d
 ```
 The optional `/app/temp` volume mount is commented out in the compose file and is not needed — see [temp directory](#the-temp-directory-does-nothing) below.
 ---
 ## 3. Build and run the image directly
 ```bash
 docker build -t pnger:latest .
 docker run -d --name pnger -p 8080:3000 \
  -e PUID=99 -e PGID=100 -e TZ=America/Chicago \
  --restart unless-stopped pnger:latest
 ```
 The `Dockerfile` is a three-stage build:
 1. **frontend-builder** — `npm install` then `vite build` in `frontend/`, producing `frontend/dist`.
 2. **backend-builder** — `npm install` then `tsc` in `backend/`, producing `backend/dist`.
 3. **runtime** — `node:20-alpine` with `apk upgrade --no-cache` and `su-exec` + `shadow` installed; production-only backend deps (`npm install --omit=dev`); the compiled backend at `/app/dist`; the built frontend at `/app/dist/public`; `/app/temp` created; `docker-entrypoint.sh` installed.
 `npm install` is used rather than `npm ci` on purpose — the committed lockfiles are stubs, and caret ranges in `package.json` are what actually pin the tree.
 At start, `docker-entrypoint.sh` runs as root: it `usermod`/`groupmod`s the built-in `node` user to the requested `PUID`/`PGID`, `chown -R node:node /app`, then `exec su-exec node "$@"`. The app itself never runs as root.
 ### CI
 `.gitea/workflows/docker-build.yml` runs on every push to `main` (plus `workflow_dispatch`) on the `host`-labelled Gitea runner — bundled Docker CLI, mounted `/var/run/docker.sock`, legacy builder. It logs in to `registry.alwisp.com` with `REGISTRY_USER` / `REGISTRY_TOKEN`, builds with the labels `org.alwisp.git-sha`, `org.alwisp.version` (`v1.<commit-count-1>`) and `org.alwisp.repo`, pushes `registry.alwisp.com/jason/pnger:latest`, then prunes dangling images on the host.
 Only `:latest` is published — there is no immutable per-SHA tag, so rollback means rebuilding from an older commit.
 To run the published image instead of building locally, point `docker run` (or the Unraid **Repository** field) at `registry.alwisp.com/jason/pnger:latest` after a `docker login registry.alwisp.com`.
 ---
 ## 4. Local development
 Two terminals:
 ```bash
 # terminal 1 — API on :3000, ts-node-dev with --respawn
 cd backend
 npm install
 npm run dev
 # terminal 2 — Vite dev server on :5173 with HMR
 cd frontend
 npm install
 npm run dev
 ```
 Open <http://localhost:5173>.
 `frontend/src/lib/api.ts` switches on `import.meta.env.DEV`: in dev it posts to `http://localhost:3000/api`, in a production build to the same-origin `/api`. There is no Vite proxy — the backend's `app.use(cors())` allows the cross-origin call.
 | Script | Where | Does |
 | --- | --- | --- |
 | `npm run dev` | backend | `ts-node-dev --respawn --transpile-only src/index.ts` |
 | `npm run build` | backend | `tsc` → `dist/` |
 | `npm start` | backend | `node dist/index.js` |
 | `npm run dev` | frontend | Vite dev server on 5173 |
 | `npm run build` | frontend | `vite build` → `frontend/dist` |
 | `npm run preview` | frontend | Serve the production build locally |
 There are no tests and no lint step. Verification is manual: resize a large PNG, convert it to WebP and JPEG, try each crop anchor, toggle the theme, paste from the clipboard.
 ---
 ## Environment variables
 Everything is optional — the image ships a working default for each. There is no `.env` file in the container; set them on the container.
 | Variable | Default (image) | Read by | Notes |
 | --- | --- | --- | --- |
 | `PORT` | `3000` | `backend/src/index.ts` | Express listen port. Changing it means changing the healthcheck and port mapping too — easier to leave it and remap on the host. |
 | `PUID` | `99` | `docker-entrypoint.sh` | UID the `node` user is remapped to. `99` = Unraid `nobody`. |
 | `PGID` | `100` | `docker-entrypoint.sh` | GID the `node` group is remapped to. `100` = Unraid `users`. |
 | `TZ` | `UTC` | base image | Container timezone, e.g. `America/Chicago`. Affects log timestamps only. |
 | `NODE_ENV` | `production` | Express / Node | Set to `development` locally. |
 | `MAX_FILE_SIZE` | `10485760` | **nothing** | ⚠️ Declared in the `Dockerfile`, the compose file and the Unraid docs, but the live upload middleware (`backend/src/routes/image.ts`) creates `multer` with no `limits`, so no size cap is applied. The only code that ever honoured it is the dead `backend/src/server.js`. Treat uploads as unbounded until this is wired up. |
 | `TEMP_DIR` | `/app/temp` | **nothing** | ⚠️ See below. |
 | `CORS_ORIGIN` | — | **nothing** | ⚠️ Listed in `backend/.env.example` and older docs. `index.ts` calls `app.use(cors())` with no options, so all origins are allowed and this variable is ignored. |
 | `HOST_PORT` | `8080` | `docker-compose.yml` | Host side of the port mapping. Compose only. |
 | `MEM_LIMIT` | `512m` | `docker-compose.yml` | Container memory cap. Compose only. |
 | `CPU_LIMIT` | `1.0` | `docker-compose.yml` | Container CPU cap. Compose only. |
 | `VITE_API_URL` | — | **nothing** | ⚠️ Documented historically; `lib/api.ts` derives the base URL from `import.meta.env.DEV` instead. Setting it has no effect. |
 `backend/.env.example` also predates the current server: it lists `MAX_FILE_SIZE=10` (megabytes) while the `Dockerfile` sets `10485760` (bytes). Neither is read today.
 ### The temp directory does nothing
 `/app/temp` is created by the `Dockerfile`, `TEMP_DIR` points at it, and `UNRAID.md` offers an optional volume mapping for it. Nothing writes there. Uploads live in memory (`multer.memoryStorage()`), Sharp transforms the buffer, Express returns it. Mounting a volume is harmless but pointless.
 ---
 ## Health checks
 The image's `HEALTHCHECK` requests `http://localhost:3000/` every 30 s and passes on HTTP 200 — that is the SPA `index.html`, so it confirms the process is up and serving.
 Be careful with `/api/health`: **it does not exist.** The router only defines `POST /api/transform`, so a GET to `/api/health` falls through to the `app.get("*")` SPA handler and returns `index.html` with a 200. Any monitor pointed at it will report healthy no matter what state the API is in. Use `POST /api/transform` with a small test image if you need a real probe.
 ---
 ## Upgrading
 - **Compose / local build:** `git pull && docker compose up -d --build`.
 - **Registry image:** `docker pull registry.alwisp.com/jason/pnger:latest && docker restart pnger`, or Unraid → **Docker** tab → **Force update**.
 There is no state, so upgrades and rollbacks are just container recreations. Nothing to back up — but note that only `:latest` is published, so rolling back means rebuilding from the older commit.
 ---
 ## Troubleshooting
 | Symptom | Cause / fix |
 | --- | --- |
 | Container exits immediately | Host port already in use, or `PUID`/`PGID` collide with an existing user in a way `usermod` rejects. `docker logs pnger`. |
 | `Transform failed` in the UI | The API returned non-200. Check `docker logs` — Sharp throws a 500 on files it cannot decode (the client only checks the MIME type starts with `image/`). |
 | Large upload hangs or the container OOMs | No upload size limit is enforced and processing is entirely in memory. Raise `MEM_LIMIT`, or put a body-size cap on your reverse proxy. |
 | Preview does not match the download | Expected. The preview is a Canvas re-encode, the output is Sharp. PNG quality is ignored by Canvas, and the preview will upscale where the server's `withoutEnlargement: true` will not. |
 | Preview never appears | Browser console — the preview path is pure Canvas API and fails silently into `console.error`. |
 | Port already in use in dev | `lsof -ti:3000 \| xargs kill -9` |
 | Sharp fails to load after a Node upgrade | `cd backend && npm rebuild sharp` |
 | Docker build fails oddly | `docker builder prune`, then rebuild. |
 ---
 *MPM — Born to Innovate. Built to Last.*
@@ -0,0 +1,153 @@
 # 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. 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, client-side)"]
    B --> D["Express API (POST /api/transform)"]
    D --> E[Sharp Image Library]
    E --> F[Response buffer streamed back as a download]
 ```
 Nothing is persisted at any point: the upload lives in memory for the duration of the request and the result is streamed straight back.
 ### Backend (Express + Sharp)
 The backend is built with Node.js and TypeScript, using Express for the API and Sharp for high-performance image processing.
 **Endpoints** — there is exactly one:
 - `POST /api/transform` — `multipart/form-data`, field `file`, plus optional `width`, `height`, `quality` (default 80), `format` (`png` | `webp` | `jpeg`, default `png`), `fit` (default `inside`) and `position` (default `center`). Returns the image bytes with `Content-Disposition: attachment`; `400` if no file, `500` if Sharp throws.
 > **There is no `GET /api/health`.** Earlier revisions of this document claimed one. The router defines only `POST /transform`, so a GET to `/api/health` falls through to the SPA catch-all and returns `index.html` with a 200 — which means a monitor pointed at it will always report healthy. The container's own `HEALTHCHECK` correctly probes `/` instead.
 **Key Dependencies:**
 - `sharp`: High-performance image processing (handles resizing, cropping, and format conversion). Resizes use `withoutEnlargement: true`, so output never exceeds the source dimensions.
 - `multer`: Middleware for handling `multipart/form-data`, used for file uploads. Configured with `memoryStorage()` and **no `limits`** — see the dead-code note below.
 - `express`: Web framework for the API; also serves the built frontend from `dist/public` with an `app.get("*")` SPA fallback.
 - `cors`: Applied wide open (`app.use(cors())`) so the Vite dev server on `:5173` can reach the API on `:3000`. In production both are the same origin.
 ### Dead code you will trip over
 - **`backend/src/server.js`** is not the server. The entrypoint is `src/index.ts` → `dist/index.js`. `server.js` is an older standalone CommonJS implementation with `/api/health`, `/api/process` and `/api/metadata`, `helmet`, a PNG-only file filter and a real `MAX_FILE_SIZE` limit. `tsconfig.json` has no `allowJs`, so `tsc` never compiles it and it never reaches `dist/`; it also `require`s `helmet` and `dotenv`, which are not in `package.json`. It is the source of most of the features these docs used to describe. Either port the good parts (size limit, MIME filter, real health endpoint) into `routes/image.ts` or delete it.
 - **`frontend/src/main.js` and `frontend/src/main.ts`** both exist. `index.html` loads `main.js`, and only `main.js` imports `./app.css` — "fixing" the script tag to point at `main.ts` would silently drop every style in the app.
 ### Frontend (Svelte + Vite)
 The frontend is a reactive Svelte application that prioritizes real-time feedback and UX.
 **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.
 ### Design System (Dark/Light Modes)
 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.
 ## Implementation Details
 ### 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.
 **Fidelity caveats — the preview is an approximation, not the output:**
 - The preview is encoded by the browser's Canvas encoder; the download is encoded by Sharp. Byte counts will differ.
 - Canvas ignores the quality argument for PNG (it is always lossless), so dragging quality changes nothing in a PNG preview while it does change the real output.
 - The preview's `calculateDimensions()` will happily scale an image **up**; the server sets `withoutEnlargement: true` and will not. The "Retina @2x" preset is exactly this case — the preview grows, the downloaded file does not.
 ### 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
 ### Prerequisites
 - Node.js 20+
 - npm or pnpm
 - Docker (optional)
 ### Setup Steps
 ```bash
 # Clone repository
 git clone https://git.alwisp.com/jason/pnger.git
 cd pnger
 # Setup backend
 cd backend
 npm install
 npm run dev
 # Setup frontend (separate terminal)
 cd frontend
 npm install
 npm run dev
 ```
 ### Environment Variables
 Only `PORT` is actually read by the application. The full table, including which variables are declared-but-unused, is in [INSTALL.md](INSTALL.md#environment-variables).
 **Backend:**
 - `PORT`: 3000 — read by `src/index.ts`.
 - `MAX_FILE_SIZE`: declared in the `Dockerfile` and compose file, **not enforced** — the live `multer` config sets no `limits`.
 - `CORS_ORIGIN`: in `backend/.env.example`, **not read** — `app.use(cors())` takes no options.
 - `TEMP_DIR` / `/app/temp`: created by the `Dockerfile`, **never written to** — processing is entirely in memory.
 **Frontend:**
 - `VITE_API_URL`: **not read.** `lib/api.ts` picks its base URL from `import.meta.env.DEV` (`http://localhost:3000/api` in dev, `/api` in a build).
 ## Development Workflow & Standards
 ### 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.
 ### 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
 More symptoms, including container-level ones, in [INSTALL.md](INSTALL.md#troubleshooting).
 - **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.
 ---
 **Last Updated**: July 2026 — reconciled against the code during the docs standardization pass. Deployment and configuration detail now lives in [INSTALL.md](INSTALL.md) and [UNRAID.md](UNRAID.md).
@@ -1,366 +0,0 @@
 # Live Preview Implementation Guide
 ## Overview
 Live Preview is the #1 priority feature for PNGer. This guide outlines the implementation approach.
 ## Goals
 1. **Instant Feedback**: Show preview within 100ms of parameter change
 2. **Accurate Rendering**: Match final output as closely as possible
 3. **Performance**: Don't block UI, handle large images efficiently
 4. **Progressive**: Show low-quality preview immediately, high-quality after
 ## Architecture
 ### Approach: Hybrid Client + Server Preview
 ```
 ┌─────────────┐
 │   Upload    │
 │   Image     │
 └──────┬──────┘
       │
       v
 ┌─────────────────────────────────┐
 │  Client-Side Preview (Canvas)   │  <-- Instant (< 100ms)
 │  - Fast, approximate rendering  │
 │  - Uses browser native resize   │
 │  - Good for basic operations    │
 └─────────┬───────────────────────┘
          │
          v
 ┌─────────────────────────────────┐
 │  Server Preview API (Optional)  │  <-- Accurate (500ms-2s)
 │  - Uses Sharp (same as export)  │
 │  - Exact output representation  │
 │  - Debounced to avoid spam      │
 └─────────────────────────────────┘
 ```
 ## Implementation Steps
 ### Phase 1: Client-Side Preview (Quick Win)
 **Files to Modify:**
 - `frontend/src/App.svelte`
 - `frontend/src/lib/preview.ts` (new)
 **Key Features:**
 1. Canvas-based image rendering
 2. Debounced updates (300ms after parameter change)
 3. Show original and preview side-by-side
 4. Display file size estimate
 **Code Skeleton:**
 ```typescript
 // frontend/src/lib/preview.ts
 export async function generateClientPreview(
  file: File,
  options: TransformOptions
 ): Promise<string> {
  return new Promise((resolve) => {
    const img = new Image();
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d')!
    img.onload = () => {
      // Calculate dimensions
      const { width, height } = calculateDimensions(img, options);
      canvas.width = width;
      canvas.height = height;
      // Apply transforms
      if (options.fit === 'cover') {
        drawCover(ctx, img, width, height, options.position);
      } else {
        ctx.drawImage(img, 0, 0, width, height);
      }
      // Apply filters (grayscale, blur, etc.)
      applyFilters(ctx, options);
      // Convert to data URL
      const quality = options.quality / 100;
      const dataUrl = canvas.toDataURL(`image/${options.format}`, quality);
      resolve(dataUrl);
    };
    img.src = URL.createObjectURL(file);
  });
 }
 ```
 **UI Updates:**
 ```svelte
 <!-- App.svelte additions -->
 <script lang="ts">
  import { generateClientPreview } from './lib/preview';
  import { debounce } from './lib/utils';
  let previewUrl: string | null = null;
  let originalSize: number = 0;
  let previewSize: number = 0;
  // Debounced preview generation
  const updatePreview = debounce(async () => {
    if (!file) return;
    previewUrl = await generateClientPreview(file, {
      width, height, quality, format, fit, position
    });
    // Calculate sizes
    originalSize = file.size;
    previewSize = estimateSize(previewUrl);
  }, 300);
  // Call on any parameter change
  $: if (file) updatePreview();
 </script>
 <!-- Preview Section -->
 {#if file && previewUrl}
  <div class="preview-container">
    <div class="image-comparison">
      <div class="original">
        <h3>Original</h3>
        <img src={URL.createObjectURL(file)} alt="Original" />
        <p>{formatFileSize(originalSize)}</p>
      </div>
      <div class="preview">
        <h3>Preview</h3>
        <img src={previewUrl} alt="Preview" />
        <p>{formatFileSize(previewSize)}</p>
        <p class="savings">
          {calculateSavings(originalSize, previewSize)}
        </p>
      </div>
    </div>
  </div>
 {/if}
 ```
 ### Phase 2: Server Preview API (Accurate)
 **Files to Modify:**
 - `backend/src/routes/image.ts`
 **New Endpoint:**
 ```typescript
 // POST /api/preview (returns base64 or temp URL)
 router.post(
  "/preview",
  upload.single("file"),
  async (req, res): Promise<void> => {
    // Same processing as /transform
    // But return as base64 data URL or temp storage URL
    // Max preview size: 1200px (for performance)
    const previewBuffer = await image.toBuffer();
    const base64 = previewBuffer.toString('base64');
    res.json({
      preview: `data:image/${format};base64,${base64}`,
      size: previewBuffer.length,
      dimensions: { width: metadata.width, height: metadata.height }
    });
  }
 );
 ```
 **Benefits:**
 - Exact rendering (uses Sharp like final output)
 - Shows actual file size
 - Handles complex operations client can't do
 **Trade-offs:**
 - Slower (network round-trip)
 - Server load (mitigate with rate limiting)
 ### Phase 3: Progressive Loading
 **Enhancement**: Show low-quality preview first, then high-quality
 ```typescript
 // Generate two previews:
 // 1. Immediate low-res (client-side, 200px max)
 // 2. Delayed high-res (server-side, full resolution)
 async function generateProgressivePreview() {
  // Step 1: Fast low-res
  const lowRes = await generateClientPreview(file, {
    ...options,
    width: Math.min(options.width || 200, 200),
    height: Math.min(options.height || 200, 200)
  });
  previewUrl = lowRes; // Show immediately
  // Step 2: High-res from server (debounced)
  const highRes = await fetchServerPreview(file, options);
  previewUrl = highRes; // Replace when ready
 }
 ```
 ## File Size Estimation
 ```typescript
 function estimateSize(dataUrl: string): number {
  // Base64 data URL size (approximate)
  const base64Length = dataUrl.split(',')[1].length;
  return Math.ceil((base64Length * 3) / 4); // Convert base64 to bytes
 }
 function formatFileSize(bytes: number): string {
  if (bytes < 1024) return `${bytes} B`;
  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
 }
 function calculateSavings(original: number, preview: number): string {
  const diff = original - preview;
  const percent = ((diff / original) * 100).toFixed(1);
  if (diff > 0) return `↓ ${formatFileSize(diff)} saved (${percent}%)`;
  if (diff < 0) return `↑ ${formatFileSize(-diff)} larger (${Math.abs(Number(percent))}%)`;
  return 'Same size';
 }
 ```
 ## UI/UX Considerations
 ### Layout Options
 **Option A: Side-by-Side**
 ```
 ┌──────────────┬──────────────┐
 │   Original   │   Preview    │
 │              │              │
 │  [Image]     │  [Image]     │
 │  2.4 MB      │  450 KB      │
 │  1920x1080   │  800x600     │
 └──────────────┴──────────────┘
 ```
 **Option B: Slider Compare**
 ```
 ┌────────────────────────────┐
 │    [<──── Slider ────>]    │
 │  Original  │  Preview      │
 │            │               │
 └────────────────────────────┘
 ```
 **Option C: Tabs**
 ```
 ┌─ Original ─┬─ Preview ─────┐
 │                             │
 │         [Image]             │
 │                             │
 └─────────────────────────────┘
 ```
 **Recommendation**: Start with Option A (simplest), add Option B later for detail comparison.
 ## Performance Optimizations
 ### 1. Debouncing
 ```typescript
 function debounce<T extends (...args: any[]) => any>(
  func: T,
  wait: number
 ): (...args: Parameters<T>) => void {
  let timeout: ReturnType<typeof setTimeout>;
  return (...args: Parameters<T>) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => func(...args), wait);
  };
 }
 ```
 ### 2. Image Downsampling
 - Preview max size: 1200px (retina displays)
 - Original size only for final download
 - Reduces memory usage and processing time
 ### 3. Worker Thread (Advanced)
 - Offload canvas operations to Web Worker
 - Keeps UI responsive during processing
 ```typescript
 // preview.worker.ts
 self.onmessage = async (e) => {
  const { file, options } = e.data;
  const preview = await generatePreview(file, options);
  self.postMessage({ preview });
 };
 ```
 ## Testing Plan
 ### Unit Tests
 - [ ] `calculateDimensions()` with various aspect ratios
 - [ ] `formatFileSize()` edge cases
 - [ ] `debounce()` timing
 ### Integration Tests
 - [ ] Preview updates on parameter change
 - [ ] Preview matches final output (within tolerance)
 - [ ] Large image handling (> 10MB)
 - [ ] Multiple format conversions
 ### Manual Tests
 - [ ] Mobile responsiveness
 - [ ] Slow network simulation
 - [ ] Various image formats (PNG, JPEG, WebP)
 - [ ] Edge cases (1x1px, 10000x10000px)
 ## Rollout Strategy
 ### Step 1: Feature Flag
 ```typescript
 // Enable via environment variable
 const ENABLE_PREVIEW = import.meta.env.VITE_ENABLE_PREVIEW === 'true';
 ```
 ### Step 2: Beta Testing
 - Deploy to staging environment
 - Gather user feedback
 - Monitor performance metrics
 ### Step 3: Gradual Rollout
 - Enable for 10% of users
 - Monitor error rates
 - Full rollout if stable
 ## Success Metrics
 - **User Engagement**: Time spent on page increases
 - **Conversion**: More downloads completed
 - **Performance**: Preview renders in < 500ms (p95)
 - **Accuracy**: Preview matches output 95%+ of time
 - **Satisfaction**: User feedback positive
 ## Future Enhancements
 - [ ] Before/after slider with drag handle
 - [ ] Zoom on preview (inspect details)
 - [ ] Multiple preview sizes simultaneously
 - [ ] A/B comparison (compare 2-4 settings)
 - [ ] Preview history (undo/redo preview)
 - [ ] Export preview settings as preset
 ---
 **Estimated Effort**: 2-3 days for Phase 1 (client preview)  
 **Complexity**: Medium  
 **Impact**: ⭐⭐⭐⭐⭐ (Highest)  
 **Next Steps**: 
 1. Create feature branch `feature/live-preview`
 2. Implement client-side preview
 3. Add UI components
 4. Test thoroughly
 5. Merge to main
 6. Deploy and monitor
@@ -0,0 +1,62 @@
 # PNGer Feature Roadmap
 PNGer is evolved through intentional sprints focusing on user experience, performance, and professional-grade features.
 ## Completed Features ✅
 ### Sprint 0: Foundation (MVP)
 - ✅ **Core Repository Setup**: Project structure and build systems.
 - ✅ **Basic Image Operations**: Width/height resizing and quality adjustment.
 - ✅ **Format Support**: Conversion between PNG, WebP, and JPEG.
 - ✅ **Docker Deployment**: Multi-stage build for Unraid/Docker environments.
 - ✅ **Stateless Processing**: Direct download from memory; no server storage.
 ### Sprint 1: Enhanced UX & Live Preview (March 2026)
 - ✅ **Live Preview**: Real-time side-by-side comparison with file size analysis.
 - ✅ **Modern Design System**: Dark/Light mode toggle with persistent storage.
 - ✅ **Drag & Drop Upload**: Intuitive drop zone with visual feedback.
 - ✅ **Clipboard Paste**: Paste images directly with `Ctrl+V`.
 - ✅ **Smart Presets**: 8 quick-access configurations for common use cases (Social Media, Web, Icons, etc.).
 - ✅ **Keyboard Shortcuts**: Fast workflow with `Enter`, `?`, and `Esc`.
 - ✅ **Performance Optimization**: Client-side Canvas rendering for instant feedback.
 ---
 ## Future Roadmap 🚀
 ### Sprint 2: Batch Processing & Advanced Operations
 **Focus**: Efficiency and essential power-user tools.
 - [ ] **Batch Processing**: Upload multiple images and process as a single ZIP.
 - [ ] **Basic Transformations**: Rotate (90/180/Custom), Flip (H/V), and Grayscale.
 - [ ] **Content-Aware Resize**: Smart cropping and aspect ratio enforcement.
 - [ ] **Auto-Optimize**: One-click "best quality/size" ratio finder.
 ### Sprint 3: Polish & Professional Tools
 **Focus**: Precision and customization.
 - [ ] **Custom Crop Tool**: Visual selector with aspect ratio lock.
 - [ ] **Watermarking**: Text and image-based branding.
 - [ ] **Image Filters**: Brightness, Contrast, Saturation, and Sharpen.
 - [ ] **Format Intelligence**: Suggestions based on image content (e.g., suggesting WebP for large images).
 ### Sprint 4: Workflow & Automation
 **Focus**: Reusability and productivity.
 - [ ] **Custom Presets**: Save and export personal transformation pipelines.
 - [ ] **Processing History**: Recent files list (localStorage).
 - [ ] **Undo/Redo**: History for parameter adjustments.
 ---
 ## Priority Matrix
 | Feature | Impact | Effort | Priority |
 |---------|--------|--------|----------|
 | Batch Processing | Very High | Medium | 1 |
 | Auto-Optimize | High | Low | 1 |
 | Custom Crop | High | High | 2 |
 | Watermarking | Medium | Medium | 3 |
 ---
 **Project Maintainer**: jason  
 **Repository**: [jason/pnger](https://git.alwisp.com/jason/pnger)  
 **Last Strategy Sync**: March 12, 2026
@@ -0,0 +1,72 @@
 # Unraid Installation Guide for PNGer
 This guide walks you through installing PNGer on Unraid using the Docker tab and "Add Container" feature. For the compose/CLI paths, local development and the full environment-variable table, see [INSTALL.md](INSTALL.md).
 > PNGer has **no authentication**. Anyone who can reach the port can upload images and burn CPU on your box. Keep it on the LAN, or put it behind a reverse proxy with auth before exposing it.
 ## Requirements
 - Unraid OS with Docker enabled.
 - Appdata path ready (optional, if you want persistent temp storage).
 ## Step-by-Step Installation
 1. Log into your Unraid WebGUI and navigate to the **Docker** tab.
 2. Scroll to the bottom and click on **Add Container**.
 3. Fill in the following details:
   - **Name**: `PNGer`
   - **Repository**: `registry.alwisp.com/jason/pnger:latest` — this is what the Gitea Actions workflow publishes on every push to `main`. Run `docker login registry.alwisp.com` once on the Unraid host so it can pull. If you built the image locally on the box instead (`docker build -t pnger:latest .`), use `pnger:latest`.
   - **Network Type**: `Bridge`
 4. Click on **+ Add another Path, Port, Variable, Label or Device** to add the required parameters.
 ### Port Configuration
 - **Config Type**: `Port`
 - **Name**: `WebUI`
 - **Container Port**: `3000`
 - **Host Port**: `8080` (or whichever port is free on your Unraid system).
 - **Connection Protocol**: `TCP`
 ### Environment Variables
 Add the following variables by clicking **+ Add another Path, Port, Variable...** and selecting **Variable** as the Config Type:
 1. **PUID**
   - **Name**: `User ID (PUID)`
   - **Key**: `PUID`
   - **Value**: `99` (Unraid's nobody user).
 2. **PGID**
   - **Name**: `Group ID (PGID)`
   - **Key**: `PGID`
   - **Value**: `100` (Unraid's users group).
 3. **TZ**
   - **Name**: `Timezone`
   - **Key**: `TZ`
   - **Value**: `America/New_York` (Enter your specific Timezone here).
 4. **MAX_FILE_SIZE** (Optional — and currently inert)
   - **Name**: `Max Upload Size (Bytes)`
   - **Key**: `MAX_FILE_SIZE`
   - **Value**: `10485760` (10 MB in bytes).
   - ⚠️ The application does **not** read this today: the live upload middleware sets no size limit, so uploads are effectively unbounded and are held in memory. Setting the variable does nothing. Until it is wired up, cap request bodies at your reverse proxy and give the container a sensible memory limit.
 ### Volume Mapping (not needed)
 PNGer is stateless — uploads are processed in memory and streamed straight back, and nothing is ever written to `/app/temp` despite the directory existing. There is nothing to persist and nothing to back up. If you want the mapping anyway, it is harmless:
 - **Config Type**: `Path`
 - **Name**: `Temp Processing Dir`
 - **Container Path**: `/app/temp`
 - **Host Path**: `/mnt/user/appdata/pnger/temp`
 5. **Apply Settings**:
   - Scroll to the bottom and press **Apply**. Unraid will pull the image and create the container with the specified settings.
 ## Accessing PNGer
 Once the container states "started", you can access the Web GUI by navigating to your Unraid IP and the port you assigned (e.g., `http://192.168.1.100:8080`).
 ---
 **Updates:**
 Every push to `main` rebuilds `registry.alwisp.com/jason/pnger:latest` on the Gitea runner. To take a new build: **Docker** tab → container row → **Force update** (or let the *CA Auto Update Applications* plugin do it on a schedule). There is no state, so an update is just a container recreation. Only `:latest` is published — there is no per-SHA tag to pin or roll back to.
 **Troubleshooting:**
 If the container stops instantly, check the **Logs** in Unraid. Ensure that the port you selected on the host is not already in use by another container (like a web server or another app). If the container starts but the WebGUI is blank, confirm the host port maps to container port **3000**.
@@ -1,4 +1,5 @@
 <script lang="ts">
  import { onMount } from 'svelte';
  import { transformImage } from "./lib/api";
  import {
    generateClientPreview,
@@ -9,6 +10,7 @@
    type TransformOptions
  } from "./lib/preview";
  import { theme } from "./lib/theme";
  import { PRESETS, applyPreset, type Preset } from "./lib/presets";
  let file: File | null = null;
  let filePreviewUrl: string | null = null;
@@ -22,6 +24,10 @@
  let processing = false;
  let error: string | null = null;
  // Drag & drop state
  let isDragging = false;
  let showShortcuts = false;
  // Preview state
  let previewUrl: string | null = null;
  let previewSize = 0;
@@ -93,13 +99,93 @@
    }
  }
  function handleFile(selectedFile: File) {
    if (!selectedFile.type.startsWith('image/')) {
      error = 'Please select an image file';
      return;
    }
    file = selectedFile;
    filePreviewUrl = URL.createObjectURL(selectedFile);
    error = null;
  }
  function onFileChange(e: Event) {
    const target = e.target as HTMLInputElement;
-    file = target.files?.[0] || null;
+    const selectedFile = target.files?.[0];
-    if (file) {
+    if (selectedFile) {
-      filePreviewUrl = URL.createObjectURL(file);
+      handleFile(selectedFile);
-    } else {
+    }
-      filePreviewUrl = null;
+  }
  // Drag & Drop handlers
  function onDragOver(e: DragEvent) {
    e.preventDefault();
    isDragging = true;
  }
  function onDragLeave(e: DragEvent) {
    e.preventDefault();
    isDragging = false;
  }
  function onDrop(e: DragEvent) {
    e.preventDefault();
    isDragging = false;
    const droppedFile = e.dataTransfer?.files?.[0];
    if (droppedFile) {
      handleFile(droppedFile);
    }
  }
  // Paste handler
  function onPaste(e: ClipboardEvent) {
    const items = e.clipboardData?.items;
    if (!items) return;
    for (let i = 0; i < items.length; i++) {
      if (items[i].type.indexOf('image') !== -1) {
        const pastedFile = items[i].getAsFile();
        if (pastedFile) {
          handleFile(pastedFile);
        }
        break;
      }
    }
  }
  // Keyboard shortcuts
  function onKeyDown(e: KeyboardEvent) {
    // Show shortcuts help
    if (e.key === '?') {
      e.preventDefault();
      showShortcuts = !showShortcuts;
      return;
    }
    // Close shortcuts dialog
    if (e.key === 'Escape' && showShortcuts) {
      showShortcuts = false;
      return;
    }
    // Ctrl/Cmd + V - Paste (handled by paste event)
    // Ctrl/Cmd + Enter - Transform & Download
    if ((e.ctrlKey || e.metaKey) && e.key === 'Enter' && file && !processing) {
      e.preventDefault();
      onSubmit();
      return;
    }
    // Enter alone - Transform & Download (if input not focused)
    const activeElement = document.activeElement;
    const isInputFocused = activeElement?.tagName === 'INPUT' || 
                           activeElement?.tagName === 'SELECT' ||
                           activeElement?.tagName === 'TEXTAREA';
    if (e.key === 'Enter' && !isInputFocused && file && !processing) {
      e.preventDefault();
      onSubmit();
    }
  }
@@ -112,6 +198,27 @@
    previewSize = 0;
  }
  // Apply preset
  function selectPreset(preset: Preset) {
    const settings = applyPreset(preset, width, height);
    width = settings.width;
    height = settings.height;
    quality = settings.quality;
    format = settings.format;
    fit = settings.fit;
  }
  // Setup event listeners
  onMount(() => {
    document.addEventListener('paste', onPaste);
    document.addEventListener('keydown', onKeyDown);
    return () => {
      document.removeEventListener('paste', onPaste);
      document.removeEventListener('keydown', onKeyDown);
    };
  });
  const savings = showPreview ? calculateSavings(originalSize, previewSize) : null;
 </script>
@@ -122,15 +229,54 @@
      <h1 class="mb-0">PNGer</h1>
      <p class="text-sm mb-0">Modern PNG Editor & Resizer</p>
    </div>
-    <button class="btn-outline" on:click={() => theme.toggle()}>
+    <div class="flex gap-sm">
-      {#if $theme === 'dark'}
+      <button class="btn-outline" on:click={() => showShortcuts = !showShortcuts} title="Keyboard shortcuts (?)">
-        ☀️ Light
+        ⌨️
-      {:else}
+      </button>
-        🌙 Dark
+      <button class="btn-outline" on:click={() => theme.toggle()}>
-      {/if}
+        {#if $theme === 'dark'}
-    </button>
+          ☀️ Light
        {:else}
          🌙 Dark
        {/if}
      </button>
    </div>
  </header>
  <!-- Shortcuts Modal -->
  {#if showShortcuts}
    <div class="modal-overlay" on:click={() => showShortcuts = false}>
      <div class="modal-content" on:click|stopPropagation>
        <h2>Keyboard Shortcuts</h2>
        <div class="shortcuts-list">
          <div class="shortcut-item">
            <kbd>Ctrl</kbd> + <kbd>V</kbd>
            <span>Paste image from clipboard</span>
          </div>
          <div class="shortcut-item">
            <kbd>Enter</kbd>
            <span>Transform & Download</span>
          </div>
          <div class="shortcut-item">
            <kbd>Ctrl</kbd> + <kbd>Enter</kbd>
            <span>Transform & Download (anywhere)</span>
          </div>
          <div class="shortcut-item">
            <kbd>?</kbd>
            <span>Show/hide this help</span>
          </div>
          <div class="shortcut-item">
            <kbd>Esc</kbd>
            <span>Close this dialog</span>
          </div>
        </div>
        <button style="margin-top: var(--space-lg);" on:click={() => showShortcuts = false}>
          Close
        </button>
      </div>
    </div>
  {/if}
  <!-- Controls Section -->
  <div class="card fade-in" style="margin-bottom: var(--space-xl);">
    <div class="grid grid-cols-2 gap-lg">
@@ -138,30 +284,74 @@
      <div>
        <h2>Upload & Settings</h2>
-        <!-- File Upload -->
+        <!-- Drag & Drop / File Upload -->
        <div style="margin-bottom: var(--space-lg);">
          <label style="display: block; margin-bottom: var(--space-sm); font-weight: 500;">
-            Select Image
+            Select or Drop Image
          </label>
-          <input 
+          
-            type="file" 
+          <!-- Drop Zone -->
-            accept="image/*" 
+          <div 
-            on:change={onFileChange}
+            class="drop-zone {isDragging ? 'dragging' : ''}"
-            style="margin-bottom: var(--space-sm);"
+            on:dragover={onDragOver}
-          />
+            on:dragleave={onDragLeave}
            on:drop={onDrop}
          >
            <input 
              type="file" 
              accept="image/*" 
              on:change={onFileChange}
              id="file-input"
              style="display: none;"
            />
            <label for="file-input" class="drop-zone-label">
              {#if file}
                <div class="flex gap-sm items-center" style="flex-direction: column;">
                  <span style="font-size: 2rem;">✅</span>
                  <span class="text-sm">{file.name}</span>
                  <span class="text-xs" style="color: var(--color-text-secondary);">
                    ({formatFileSize(file.size)})
                  </span>
                </div>
              {:else}
                <div style="text-align: center;">
                  <p style="font-size: 3rem; margin-bottom: var(--space-sm);">🖼️</p>
                  <p style="margin-bottom: var(--space-xs);">Drag & drop image here</p>
                  <p class="text-sm" style="color: var(--color-text-secondary); margin-bottom: var(--space-sm);">or click to browse</p>
                  <p class="text-xs" style="color: var(--color-text-secondary);">Paste with Ctrl+V</p>
                </div>
              {/if}
            </label>
          </div>
          {#if file}
-            <div class="flex gap-sm items-center" style="margin-top: var(--space-sm);">
+            <button class="btn-secondary" style="width: 100%; margin-top: var(--space-sm);" on:click={clearFile}>
-              <span class="text-sm">{file.name}</span>
+              Clear File
-              <span class="text-xs" style="color: var(--color-text-secondary);">
+            </button>
                ({formatFileSize(file.size)})
              </span>
              <button class="btn-secondary" style="padding: var(--space-xs) var(--space-sm); font-size: 0.875rem;" on:click={clearFile}>
                Clear
              </button>
            </div>
          {/if}
        </div>
        <!-- Smart Presets -->
        {#if file}
          <div style="margin-bottom: var(--space-lg);" class="fade-in">
            <label style="display: block; margin-bottom: var(--space-sm); font-weight: 500;">
              Quick Presets
            </label>
            <div class="presets-grid">
              {#each PRESETS as preset}
                <button 
                  class="preset-btn"
                  on:click={() => selectPreset(preset)}
                  title={preset.description}
                >
                  <span class="preset-icon">{preset.icon}</span>
                  <span class="preset-name">{preset.name}</span>
                </button>
              {/each}
            </div>
          </div>
        {/if}
        <!-- Dimensions -->
        <div style="margin-bottom: var(--space-lg);">
          <h3>Dimensions</h3>
@@ -258,6 +448,12 @@
            ⬇️ Transform & Download
          {/if}
        </button>
        {#if file}
          <p class="text-xs" style="color: var(--color-text-secondary); text-align: center; margin-top: var(--space-sm); margin-bottom: 0;">
            Press <kbd style="font-size: 0.75rem; padding: 2px 4px;">Enter</kbd> to download
          </p>
        {/if}
      </div>
    </div>
  </div>
@@ -271,6 +467,7 @@
        <div>
          <p style="font-size: 3rem; margin-bottom: var(--space-md)">🖼️</p>
          <p class="mb-0">Upload an image to see live preview</p>
          <p class="text-sm" style="color: var(--color-text-secondary); margin-top: var(--space-sm);">Drag & drop, click to browse, or paste with Ctrl+V</p>
        </div>
      </div>
    {:else if showPreview}
@@ -337,3 +534,131 @@
    {/if}
  </div>
 </div>
 <style>
  /* Drop zone styles */
  .drop-zone {
    border: 2px dashed var(--color-border);
    border-radius: var(--radius-md);
    padding: var(--space-xl);
    text-align: center;
    cursor: pointer;
    transition: all 0.2s ease;
    background: var(--color-bg-secondary);
  }
  .drop-zone:hover {
    border-color: var(--color-accent);
    background: var(--color-bg-tertiary);
  }
  .drop-zone.dragging {
    border-color: var(--color-accent);
    background: var(--color-accent)15;
    border-style: solid;
  }
  .drop-zone-label {
    display: block;
    cursor: pointer;
  }
  /* Presets grid */
  .presets-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: var(--space-sm);
  }
  .preset-btn {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: var(--space-xs);
    padding: var(--space-sm);
    border: 1px solid var(--color-border);
    border-radius: var(--radius-sm);
    background: var(--color-bg-secondary);
    cursor: pointer;
    transition: all 0.2s ease;
    font-size: 0.75rem;
  }
  .preset-btn:hover {
    border-color: var(--color-accent);
    background: var(--color-bg-tertiary);
    transform: translateY(-2px);
  }
  .preset-icon {
    font-size: 1.5rem;
  }
  .preset-name {
    font-size: 0.7rem;
    text-align: center;
    line-height: 1.2;
    color: var(--color-text-primary);
  }
  /* Modal styles */
  .modal-overlay {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background: rgba(0, 0, 0, 0.5);
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 1000;
    animation: fadeIn 0.2s ease;
  }
  .modal-content {
    background: var(--color-bg-primary);
    border-radius: var(--radius-lg);
    padding: var(--space-2xl);
    max-width: 500px;
    width: 90%;
    box-shadow: var(--shadow-2xl);
  }
  .shortcuts-list {
    display: flex;
    flex-direction: column;
    gap: var(--space-md);
    margin-top: var(--space-lg);
  }
  .shortcut-item {
    display: flex;
    align-items: center;
    gap: var(--space-md);
    padding: var(--space-sm);
    background: var(--color-bg-secondary);
    border-radius: var(--radius-sm);
  }
  .shortcut-item span {
    flex: 1;
    color: var(--color-text-secondary);
  }
  kbd {
    display: inline-block;
    padding: 4px 8px;
    font-size: 0.875rem;
    font-family: monospace;
    background: var(--color-bg-tertiary);
    border: 1px solid var(--color-border);
    border-radius: var(--radius-sm);
    box-shadow: 0 2px 0 var(--color-border);
  }
  @keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
  }
 </style>
@@ -0,0 +1,128 @@
 /**
 * Smart Presets for common image transformation use cases
 */
 export interface Preset {
  name: string;
  description: string;
  icon: string;
  width?: number;
  height?: number;
  quality: number;
  format: 'png' | 'webp' | 'jpeg';
  fit: 'inside' | 'cover';
 }
 export const PRESETS: Preset[] = [
  {
    name: 'Web Thumbnail',
    description: 'Small, optimized for web (300x300)',
    icon: '🖼️',
    width: 300,
    height: 300,
    quality: 75,
    format: 'webp',
    fit: 'cover'
  },
  {
    name: 'Social Media',
    description: 'Open Graph image (1200x630)',
    icon: '📱',
    width: 1200,
    height: 630,
    quality: 85,
    format: 'png',
    fit: 'cover'
  },
  {
    name: 'Profile Picture',
    description: 'Square avatar (400x400)',
    icon: '👤',
    width: 400,
    height: 400,
    quality: 85,
    format: 'png',
    fit: 'cover'
  },
  {
    name: 'Email Friendly',
    description: 'Compressed for email',
    icon: '📧',
    width: 600,
    quality: 70,
    format: 'jpeg',
    fit: 'inside'
  },
  {
    name: 'HD Quality',
    description: 'High resolution (1920px wide)',
    icon: '⭐',
    width: 1920,
    quality: 90,
    format: 'png',
    fit: 'inside'
  },
  {
    name: 'Retina @2x',
    description: 'Double size for high-DPI',
    icon: '🔍',
    quality: 85,
    format: 'png',
    fit: 'inside'
  },
  {
    name: 'Icon Small',
    description: 'Tiny icon (64x64)',
    icon: '🔷',
    width: 64,
    height: 64,
    quality: 100,
    format: 'png',
    fit: 'cover'
  },
  {
    name: 'Icon Large',
    description: 'Large icon (256x256)',
    icon: '🔶',
    width: 256,
    height: 256,
    quality: 100,
    format: 'png',
    fit: 'cover'
  }
 ];
 /**
 * Apply a preset to current settings
 * For Retina @2x, we double the current dimensions
 */
 export function applyPreset(
  preset: Preset,
  currentWidth?: number | null,
  currentHeight?: number | null
 ): {
  width: number | null;
  height: number | null;
  quality: number;
  format: 'png' | 'webp' | 'jpeg';
  fit: 'inside' | 'cover';
 } {
  // Special handling for Retina @2x preset
  if (preset.name === 'Retina @2x') {
    return {
      width: currentWidth ? currentWidth * 2 : null,
      height: currentHeight ? currentHeight * 2 : null,
      quality: preset.quality,
      format: preset.format,
      fit: preset.fit
    };
  }
  return {
    width: preset.width || null,
    height: preset.height || null,
    quality: preset.quality,
    format: preset.format,
    fit: preset.fit
  };
 }
@@ -38,10 +38,29 @@ export async function generateClientPreview(
          ctx.drawImage(img, 0, 0, width, height);
        }
-        // Convert to data URL with quality
+        // Convert to data URL with quality - fix MIME type mapping
        const quality = options.quality / 100;
-        const mimeType = `image/${options.format === 'jpeg' ? 'jpeg' : 'png'}`;
+        let mimeType: string;
-        const dataUrl = canvas.toDataURL(mimeType, quality);
+        
        // Map format to proper MIME type
        switch (options.format) {
          case 'jpeg':
            mimeType = 'image/jpeg';
            break;
          case 'webp':
            mimeType = 'image/webp';
            break;
          case 'png':
          default:
            mimeType = 'image/png';
            break;
        }
        // For PNG, quality doesn't apply in Canvas API (always lossless)
        // For JPEG and WebP, quality matters
        const dataUrl = options.format === 'png' 
          ? canvas.toDataURL(mimeType)
          : canvas.toDataURL(mimeType, quality);
        resolve(dataUrl);
      } catch (error) {
@@ -183,12 +202,26 @@ function getPositionOffset(
 /**
 * Estimate file size from data URL
 * More accurate calculation that accounts for base64 overhead
 */
 export function estimateSize(dataUrl: string): number {
-  const base64 = dataUrl.split(',')[1];
+  const parts = dataUrl.split(',');
  if (parts.length < 2) return 0;
  const base64 = parts[1];
  if (!base64) return 0;
-  // Base64 is ~33% larger than binary, so divide by 1.33
+  
-  return Math.ceil((base64.length * 3) / 4);
+  // Remove padding characters for accurate calculation
  const withoutPadding = base64.replace(/=/g, '');
  // Base64 encoding: 3 bytes -> 4 characters
  // So to get original bytes: (length * 3) / 4
  const bytes = (withoutPadding.length * 3) / 4;
  // Account for padding bytes if present
  const paddingCount = base64.length - withoutPadding.length;
  return Math.round(bytes - paddingCount);
 }
 /**
Author	SHA1	Message	Date
jason	e55e9871cb	docs: rewrite README to FLEET layout (docs index, what it does, shape, known rough edges)	2026-07-31 21:19:16 -05:00
jason	f9ba22ffba	docs: update Unraid guide for registry image, inert MAX_FILE_SIZE, stateless volumes	2026-07-31 21:19:15 -05:00
jason	8288827c69	docs: correct technical notes (no /api/health, unused env vars, dead server.js, preview caveats)	2026-07-31 21:19:14 -05:00
jason	8f15d3202c	docs: add installation & configuration guide (env-var table, CI, health checks)	2026-07-31 21:19:13 -05:00
jason	34680480ed	docs: move ROADMAP.md to docs/ROADMAP.md	2026-07-31 21:19:12 -05:00
jason	c00f33fa7d	docs: move ROADMAP.md to docs/ROADMAP.md	2026-07-31 21:19:11 -05:00
jason	0b55e97cad	docs: move UNRAID.md to docs/UNRAID.md	2026-07-31 21:19:10 -05:00
jason	ed13013e71	docs: move UNRAID.md to docs/UNRAID.md	2026-07-31 21:19:09 -05:00
jason	5b2f35f4ff	docs: move INSTRUCTIONS.md to docs/INSTRUCTIONS.md	2026-07-31 21:19:08 -05:00
jason	c83768785f	docs: move INSTRUCTIONS.md to docs/INSTRUCTIONS.md	2026-07-31 21:19:07 -05:00
jason	1854cd2984	ci: unify to canonical docker-build workflow (drift labels baked in) Build and Push Docker Image / build (push) Successful in 1m5s Details	2026-07-19 13:55:32 -05:00
jason	493bd9de96	Fix docker-build.yml push trigger branch to match default branch Build and Push Docker Image / build (push) Successful in 49s Details	2026-07-02 10:07:42 -05:00
jason	96fa0745fe	Update docker-build.yml workflow	2026-07-02 10:03:20 -05:00
jason	7ea0ed55e6	Add docker-build.yml: build + push :latest to registry.alwisp.com on the host runner Build and Push Docker Image / build (push) Successful in 51s Details	2026-06-30 07:36:55 -05:00
jason	decc396347	docker	2026-03-13 22:36:02 -05:00
jason	d684240697	unraid	2026-03-13 22:33:36 -05:00
jason	b0aaf80c60	Merge pull request 'cleanup' (#12 ) from review-opti into main Reviewed-on: #12	2026-03-12 11:00:23 -05:00
jason	faa206d44b	cleanup	2026-03-12 10:59:06 -05:00
jason	c65355a43b	Merge pull request 'docs: reorganize roadmap by utility, mark Sprint 1 complete, add high-value features' (#11 ) from feature/sprint1-dragdrop-presets-shortcuts into main Reviewed-on: #11	2026-03-08 21:46:59 -05:00
jason	5579656279	docs: reorganize roadmap by utility, mark Sprint 1 complete, add high-value features	2026-03-08 21:46:03 -05:00
jason	87c9078a99	Merge pull request 'feature/sprint1-dragdrop-presets-shortcuts' (#10 ) from feature/sprint1-dragdrop-presets-shortcuts into main Reviewed-on: #10	2026-03-08 21:40:08 -05:00
jason	a9da791766	docs: update INSTRUCTIONS with Sprint 1 completed features	2026-03-08 21:38:49 -05:00
jason	98f03c9b22	docs: update README with Sprint 1 features (drag/drop, presets, shortcuts)	2026-03-08 21:38:01 -05:00
jason	9d59fac386	Merge pull request 'Fix preset button text color for proper theme contrast' (#9 ) from feature/sprint1-dragdrop-presets-shortcuts into main Reviewed-on: #9	2026-03-08 17:16:04 -05:00
jason	3e35978b73	Fix preset button text color for proper theme contrast Added explicit color property to .preset-name CSS class to ensure text is always visible in both light and dark themes.	2026-03-08 17:15:07 -05:00
jason	733235c101	Merge pull request 'feature/sprint1-dragdrop-presets-shortcuts' (#8 ) from feature/sprint1-dragdrop-presets-shortcuts into main Reviewed-on: #8	2026-03-08 17:10:08 -05:00
jason	87ac7b0ce4	Add Sprint 1 changes documentation	2026-03-08 17:07:40 -05:00
jason	e6a99a4141	Add drag & drop, smart presets, and keyboard shortcuts	2026-03-08 17:06:58 -05:00
jason	4f694b1024	Add smart presets for common use cases	2026-03-08 17:05:53 -05:00
jason	531f0cb3b3	Fix preview file size calculation and format conversion	2026-03-08 17:05:07 -05:00
jason	f5bd461fef	Update ROADMAP: mark Phase 1.1 complete, add next priorities	2026-03-08 16:58:53 -05:00