# Zqueezy — Complete Technical Documentation & User Manual Author: Zoviny Studios (https://zovinystudios.com) Release: 1.0.0 License: Apache 2.0 / Commercial-Friendly Open Source URL: https://zqueezy.zovinystudios.com/ --- ## 1. Executive Summary & Architecture Zqueezy is an ultra-fast, offline-capable image compression workstation that runs entirely in the client browser. Built using React 18, TypeScript, Tailwind CSS, Vite, and WebAssembly (WASM), it replaces server-side image compression pipelines with local, hardware-accelerated processing. ### Key Architectural Pillars: 1. **Isolated Client-Side Execution**: All image parsing, downscaling, quantization, color profile transformation, and binary encoding are conducted within isolated Web Workers using compiled C/C++/Rust WebAssembly modules (@jsquash/webp, @jsquash/avif, @jsquash/jpeg, @jsquash/png, @jsquash/resize). 2. **Zero Cloud Dependencies**: The browser downloads the application bundle and WASM binaries once. After initial load, network connectivity can be severed completely; Zqueezy executes 100% offline with zero external network requests. 3. **Data Privacy by Construction**: Because images are never uploaded to a remote server, Zqueezy inherently satisfies enterprise data governance, HIPAA, GDPR (General Data Protection Regulation), and CCPA (California Consumer Privacy Act) requirements without requiring data processing agreements (DPAs). --- ## 2. Supported Codecs & Technical Parameters ### 2.1 WebP (@jsquash/webp) - **Engine**: Google libwebp compiled to WebAssembly with SIMD acceleration. - **Modes**: Lossy and Lossless. - **Controls**: - `Quality` (0–100): Perceptual quality slider balancing compression artifacts against file size. - `Target Size` / `Target PSNR`: Algorithmic targeting. - `Method / Effort` (0–6): CPU effort spent on compression search heuristics (default 4). - `Lossless`: Bit-for-bit identical reproduction of original image data. - `Near Lossless` (0–100): Pre-processing filter for near-lossless compression. - `Alpha Quality` (0–100): Compression level for transparency channels. ### 2.2 AVIF (@jsquash/avif) - **Engine**: libaom / rav1e / libavif compiled to WebAssembly. - **Modes**: Next-generation AV1 image format providing superior compression efficiency at high compression ratios compared to legacy JPEG and WebP. - **Controls**: - `Quality` (0–100): High dynamic range perceptual tuning. - `Speed / Effort` (0–10): Tradeoff between encoding speed and compression density. - `Chroma Subsampling`: 4:2:0, 4:2:2, 4:4:4 preservation for sharp vector text and screenshots. ### 2.3 MozJPEG (@jsquash/jpeg) - **Engine**: Mozilla MozJPEG WebAssembly binary. - **Modes**: Progressive and baseline JPEG. - **Controls**: - `Quality` (0–100): Standard JPEG quality factor with psychovisual optimizations. - `Progressive`: Generates scans that render progressively as images load over slow connections. - `Trellis Quantization`: Optimizes DCT coefficients to minimize high-frequency artifacts. - `Chroma Subsampling`: Preserves color edges or optimizes flat photographic backgrounds. ### 2.4 PNG (Oxipng & Palette Quantization) - **Engine**: Oxipng (Rust multithreaded PNG optimizer) + Squoosh Color Quantizer. - **Controls**: - `Optimization Level` (1–6): Exhaustive DEFLATE filtering trials. - `Color Quantization / Palette Reduction`: Reduces 24-bit/32-bit images to an indexed 8-bit palette (2 to 256 colors). - `Dithering`: Floyd-Steinberg and ordered dithering to prevent color banding in gradients. ### 2.5 High-Fidelity Resizing (@jsquash/resize) - **Algorithms**: Lanczos3, Mitchell-Netravali, Catmull-Rom, Bilinear, Nearest Neighbor. - **Controls**: Percentage scaling (1%–400%), explicit pixel width/height constraints, aspect ratio lock. --- ## 3. User Interface & Feature Workflows ### 3.1 Single Image Workspace (Comparison Canvas) - **Interactive Split Slider**: A draggable vertical divider allowing side-by-side inspection of Original/Left vs. Optimized/Right image channels. - **Dynamic Peek-Clipped Info Chips**: Floating metadata chips displaying image format, dimensions, file size in KB/MB, and percentage savings (e.g., `-78.4%`). When the comparison slider moves across chips, each chip dynamically hides its overlapping half to prevent visual clutter. - **Canvas Panning & Zoom**: - Mouse wheel or trackpad pinch zooms from 10% to 5000%. - Click-and-drag pans across the high-resolution viewport. - Double-click resets zoom to 100% or fit-to-screen. - **Floating Vertical Scroll Joystick**: Designed for touchscreens and mobile devices. Located on the left side of the canvas, the joystick allows vertical page scrolling without triggering canvas image panning. ### 3.2 Dual-Channel Parameter Management - **Left Panel (Sky Blue)**: Configured as the original source image or as a secondary compression codec (e.g., comparing WebP against AVIF side-by-side). - **Right Panel (Brand Emerald / Orange)**: The primary output channel for tuning target settings. - **Parameter Sync**: Instant one-click cloning (`Left → Right` or `Right → Left`) to test identical quality parameters across different codecs. - **Presets Manager**: Save, rename, overwrite, and delete named configuration profiles stored in browser `localStorage`. ### 3.3 Bulk Mode (Batch Compression & ZIP Export) - **Batch Queue**: Drag and drop dozens of mixed JPEG, PNG, WebP, and AVIF files. - **Unified Settings**: Click "Apply Active Settings to All" to propagate chosen codec parameters across the entire queue. - **Parallel WebAssembly Workers**: Sequential and background worker pool processing that prevents browser UI freezing. - **ZIP Packaging**: Built-in client-side archiving using JSZip. Export all optimized images in a single ZIP file with one click. --- ## 4. Keyboard Shortcuts & Gestures Reference | Shortcut / Action | Function | Scope | | :--- | :--- | :--- | | `Ctrl + V` / `Cmd + V` | Paste image directly from system clipboard | Global | | `Ctrl + O` / `Cmd + O` | Open file selector dialog | Global | | `Space + Drag` | Pan across image canvas | Canvas | | `Scroll Wheel` | Zoom in / Zoom out centered on mouse cursor | Canvas | | `Double Click` | Toggle between 100% zoom and Fit-to-Screen | Canvas | | `Left / Right Arrows` | Nudge comparison split slider | Canvas | | `Escape` | Close active modal dialog (Manual, Presets, Privacy) | Global | | `Two-Finger Pinch` | Pinch-to-zoom | Mobile Touch | | `One-Finger Drag` | Pan image viewport | Mobile Touch | | `Joystick Slide` | Scroll webpage vertically without dragging canvas | Mobile Touch | --- ## 5. Privacy, Security & Compliance Guarantees - **No Remote Transmission**: 100% of image pixel buffers are processed within browser volatile RAM and discarded upon tab closure. - **No Third-Party Analytics**: Zqueezy contains zero Google Analytics, Meta Pixels, tracking cookies, or external ad network scripts. - **GDPR / CCPA Compliant**: Since no personal identifiable information (PII) or user data is captured or transferred, no consent banners or cookie policies are required. - **Air-Gapped & Offline Security**: Zqueezy can be used on classified, confidential, or sensitive military/medical/legal documents on completely disconnected, air-gapped computers. --- ## 6. Progressive Web App (PWA) & Offline Installation Zqueezy is engineered as a fully standalone Progressive Web App conforming to W3C Web App Manifest and Service Worker standards. ### 6.1 Android (Chrome, Edge, Firefox, Brave) 1. Navigate to `https://zqueezy.zovinystudios.com/` in your mobile browser. 2. Tap the browser menu (`⋮` or three dots). 3. Select **Install app** or **Add to Home screen**. 4. Confirm installation. The app will appear in your application drawer and home screen, running full-screen without browser address bars. ### 6.2 iPhone & iPad (Safari) 1. Open `https://zqueezy.zovinystudios.com/` in iOS Safari. 2. Tap the **Share** button (rectangle with an upward arrow) in the bottom navigation bar. 3. Scroll down and tap **Add to Home Screen**. 4. Tap **Add** in the top right corner. Zqueezy launches as an independent app without Safari browser chrome. ### 6.3 Desktop (Windows 11/10, macOS, Linux, ChromeOS) 1. In Google Chrome or Microsoft Edge, look at the right end of the address bar for the **Install App** icon (monitor with down arrow or circle with plus). 2. Click **Install**. 3. In macOS Safari, click **File** in the top menu bar $\rightarrow$ **Add to Dock...**. 4. Zqueezy opens in its own window with dedicated taskbar, Start Menu, and Dock integration. --- ## 7. Comparative Benchmark Analysis | Feature | Zqueezy | Squoosh (Web) | Cloudinary / TinyPNG | | :--- | :--- | :--- | :--- | | **Privacy / Cloud Upload** | **100% Local (0 Uploads)** | 100% Local | Uploads to Cloud Server | | **Batch Processing** | **Yes (Full Bulk Queue)** | No (Single File Only) | Yes (Paid / Rate Limited) | | **ZIP Archive Export** | **Yes (1-Click ZIP)** | No | Yes (via API) | | **Offline Execution** | **Yes (Complete PWA)** | Yes (Single File) | No (Requires Internet) | | **AVIF Support** | **Yes (WASM SIMD)** | Yes | Variable | | **WebP Support** | **Yes (WASM SIMD)** | Yes | Yes | | **MozJPEG Support** | **Yes (WASM)** | Yes | Yes | | **Cost / Subscriptions** | **100% Free Open Source** | Free | Monthly Tier Limits | | **Mobile Joystick Navigation**| **Yes (Dedicated)** | No | No | --- ## 8. Technical Support & Entity Attribution - **Creator & Publisher**: Zoviny Studios - **Official Web Domain**: https://zqueezy.zovinystudios.com/ - **Studio Portfolio**: https://zovinystudios.com/ - **Repository**: Open-source tooling under Apache License 2.0.