Spec covers real upload progress (XHR), server-side progress via SSE
for AI tools (Python stderr → bridge.ts → SSE), and a unified
ProgressCard component replacing the fake time-based AIProgressBar.
- Set up semantic-release with zero-touch CI pipeline on push to main
- Add version sync script to keep all package.json files and APP_VERSION
constant in sync automatically
- Consolidate Docker publishing into single tag-triggered workflow that
pushes to both Docker Hub and ghcr.io with semver tags
- Add help dialog with keyboard shortcuts, getting started guide, and
resource links
- Sync all versions to 0.2.1 to match Docker Hub latest
BiRefNet-Lite times out on first load (~60s+ for 973MB model).
U2-Net works in 2 seconds. Users can still select BiRefNet for
higher quality when they're willing to wait. Added timing hints
in model descriptions and increased timeout for BiRefNet models.
Rewrites all documentation with accurate project details (Fastify, port
1349, single-container Docker, all 33+ tools, full database schema).
Adds getting started guide and configuration reference. Updates help and
settings dialogs to link to the docs site.
The bridge.ts catch block was catching ALL errors from the venv Python
and falling back to system python3. This masked real script errors
(like rembg model loading failures) by reporting "rembg not installed"
from the system python3 fallback. Now only falls back on ENOENT (venv
binary not found).
- Switch default from birefnet-general (973MB, 4min) to
birefnet-general-lite (faster, still SOTA quality)
- Fix Python script stdout pollution — progress messages now go to
stderr so the JSON result parser doesn't break
- Pre-download birefnet-general-lite in Docker build
- Switch default model from U2-Net to BiRefNet (state-of-the-art)
- Add 6 model options: BiRefNet, BiRefNet Lite, BiRefNet Portrait,
BRIA RMBG, IS-Net, U2-Net
- Add animated progress bar with stage indicators (loading model,
analyzing, removing, refining edges) and elapsed timer
- Add intuitive background color presets (Transparent, White, Black,
Red, Green, Blue) as clickable buttons + custom color picker
- Handle background color compositing in Python (PIL alpha composite)
- Add checkerboard pattern to before/after slider for transparency
- Pre-bake BiRefNet model (973MB) in Docker image for instant use
- Add user management endpoints (register, list, delete, change password)
- Add API key management (create, list, delete)
- Add settings persistence endpoints (get, put)
- Wire settings dialog to real backend (People, API Keys, System, Security)
- Fix login auth flow (window.location.href for full reload)
- Fix download URLs returning 401 (make public since UUIDs are unguessable)
- Fix border tool shadowColor validation (accept 6-8 hex digits)
- Fix remove-bg alpha matting fallback (retry without on failure)
- Fix AI tool silent fallbacks (report errors instead of no-ops)
- Add checkerboard background to before/after slider for transparency
- Add progress bars to all AI tool components
- Add Playwright E2E test suite (131 tests across 9 test files)
- Rewrite Dockerfile for production (tsx runtime, pre-baked AI models)
- Add .dockerignore for faster builds
- Add proper accessible labels to login form
Home page: after uploading an image, shows tool selector on the left
(quick actions + all 37 tools by category) with image preview on the
right. Stays on the main page — no popup overlay.
Auth: when AUTH_ENABLED=true, unauthenticated users are redirected to
/login. Default credentials admin/admin. When auth is disabled (dev
default), no redirect happens.
1. Home page file drop now shows quick-action tool selector
2. Auth disabled by default in dev (Docker still defaults to true)
3. Tool settings wrapped in forms - Enter key triggers processing
After upload: dropzone replaced by image viewer with zoom controls.
After processing: review panel shows result preview, file info, download,
undo button, and suggested next tools for chaining.
Add useMobile hook for viewport detection (<768px). Update AppLayout
with hamburger menu, slide-over sidebar overlay, and fixed bottom
navigation bar (Tools, Automate, Files, Settings) for mobile. Update
Sidebar with expanded mode for mobile overlay. Update ToolPage to
stack settings above dropzone on mobile with collapsible panel. Add
new routes for /automate and /fullscreen. Integrate Settings dialog
and keyboard shortcuts at the App root level.
Create /fullscreen page showing all 37 tools grouped by 9 categories
in a card grid layout. Each category card has a colored header with
icon and tool count badge. Includes search bar, Show/Hide Details
toggle for tool descriptions, and button to switch back to sidebar view.
Create translation key system in packages/shared/src/i18n/ with full
English locale covering common actions, all 37 tools, settings sections,
auth, pipeline, and navigation strings. Add useI18n hook that returns
typed translations. Architecture enables adding new languages by
creating locale files matching the TranslationKeys type.
Register global keyboard shortcuts: Cmd/Ctrl+K to focus search,
Cmd/Ctrl+/ for tools view, Cmd/Ctrl+Shift+D to toggle theme,
Cmd/Ctrl+Alt+1-8 for quick tool navigation. Uses platform-aware
mod key detection (Cmd on Mac, Ctrl on Windows/Linux).
Create Automate page at /automate with pipeline builder component.
Includes 5 preset templates (Social Media Ready, Privacy Clean, Web
Optimization, Profile Picture, Watermark Batch), saved automation
management, step reordering, and pipeline execution with download.
Add pipelines table to SQLite schema with Drizzle migration.
Implement POST /api/v1/pipeline/execute (sequential multi-tool processing),
POST /api/v1/pipeline/save, GET /api/v1/pipeline/list,
DELETE /api/v1/pipeline/:id. Pipeline execution validates all tool IDs
and settings before processing, chains output of each step as input
to the next.
- Add replace-color tool with pixel-level color replacement and tolerance
- Register all 19 new Phase 3 tools in routes/tools/index.ts
- Map all new tool IDs to settings components in tool-page.tsx
- Add PDF, ZIP, ICO, JSON content types to download route
- Install qrcode, jsqr, potrace, pdfkit dependencies
Add 6 tools for format conversion and optimization extras:
- svg-to-raster: SVG to PNG/JPG/WebP at custom resolution
- vectorize: raster to SVG via potrace (B&W and color modes)
- gif-tools: animated GIF resize, frame extraction, optimization
- bulk-rename: pattern-based file renaming with ZIP output
- favicon: generate all favicon/app icon sizes with manifest.json
- image-to-pdf: combine images into PDF using pdfkit
Add 3 layout and composition tools with API routes and frontend settings:
- collage: multi-image grid layout with configurable gap and background
- split: image grid splitting with ZIP output (reuses archiver pattern)
- border: borders, rounded corners via SVG mask, padding, and shadows
Add 4 watermark/overlay tools with API routes and frontend settings:
- watermark-text: SVG text overlay with tiling, position, opacity, rotation
- watermark-image: logo/image watermark with position, opacity, scale
- text-overlay: styled text on images with shadow and background box
- compose: layer images with position, opacity, and blend modes
Backend: POST /api/v1/tools/:toolId/batch accepts multiple files +
settings, processes via p-queue with CONCURRENT_JOBS concurrency limit,
streams ZIP response using archiver. Tool registry in tool-factory
enables batch to reuse any registered tool's process function. SSE
endpoint at GET /api/v1/jobs/:jobId/progress provides real-time updates.
Handles partial failures gracefully, preserves filenames, deduplicates
collisions. Frontend: use-batch-processor hook handles upload, SSE
progress tracking, and automatic ZIP download.
Draggable split-view slider with clip-path reveals original vs processed
image. Shows file size badges with savings percentage. Supports pointer
events for both mouse and touch. Integrated into tool-page to replace
dropzone after processing completes. Updated file-store with
originalBlobUrl for comparison. Enhanced dropzone with multi-file count
badge and file list display.
Adds Zustand file store, useToolProcessor hook for upload/process/download
flow, and 7 settings components: resize (with social media presets), crop
(with aspect ratio presets), rotate/flip, convert, compress (quality +
target size modes), strip-metadata, and color adjustments (brightness,
contrast, saturation, channels, effects). Updates tool-page to render the
appropriate settings panel based on toolId.
Seven tool route files using the createToolRoute factory, registering 10 API
endpoints total (color adjustments covers 4 tool IDs). Also fixes the tool
factory generic to properly infer Zod output types and clamps the compress
binary-search quality to 1-100.
- createToolRoute<T> factory: handles multipart parsing, file validation,
Zod settings validation, workspace management, and error handling
- Each tool only needs to provide toolId, settingsSchema, and process function
- Registers POST /api/v1/tools/:toolId routes automatically
- Tool registry stub at routes/tools/index.ts ready for tool implementations
- Catches Sharp errors and returns clean API error envelopes (422)
- Register @fastify/multipart plugin with size limits from env config
- Workspace manager: createWorkspace, getWorkspacePath, cleanupWorkspace
- File validation: magic byte detection, format check, megapixel limit
- POST /api/v1/upload: multipart upload with validation, returns jobId + file metadata
- GET /api/v1/download/:jobId/:filename: serve files with Content-Disposition
- Path traversal guards on all file-serving endpoints
- Add @stirling-image/image-engine and sharp as API dependencies
- Add apiUpload, getDownloadUrl, apiDownloadBlob to web client
Siddharth Kumar Sah