Runtime capability contract
QuokkaPix browser compatibility matrix
QuokkaPix runs image, metadata, ZIP and PDF workflows locally in the browser. This matrix explains which capabilities are browser-dependent, which paths have local fallbacks and what agents should verify at runtime before starting heavy automation.
Compatibility matrix
The table is intentionally conservative. It does not pretend that every browser/device behaves the same; agents should read the live capability object from the current browser session.
| Feature | Desktop browsers | Mobile browsers | Runtime signal | Important limit |
|---|---|---|---|---|
| JPEG / JPG | Common browser decode and export; advanced MozJPEG encoder is preferred when loaded. | Common browser decode and export; memory still depends on file size. | Listed in getState().capabilities.supportedOutputFormats when export is available. | Visual edits re-export a new file. Metadata-only cleanup can use the lossless binary path. |
| PNG | Common browser decode and export; OxiPNG optimization is preferred when loaded. | Common browser decode and export; large transparent PNG files can be memory-heavy. | Runtime export support plus advanced encoder availability are exposed in capabilities. | Optimization can change byte structure and file size while keeping pixels intact. |
| WebP | Browser export is used when available; WASM WebP encoder can provide a stable advanced path. | Supported in modern mobile browsers, but agents should still inspect runtime capabilities. | Use supported output formats and advanced encoder state before choosing WebP automation. | Animated WebP is not a general animation editing workflow. |
| AVIF | Browser support varies; advanced AVIF encoder can be used when loaded. | Availability and speed vary by browser and device. | Agents should check capabilities before requesting AVIF output. | AVIF export is heavier than JPEG/WebP and can be slower in large batches. |
| HEIC / HEIF input | Decoded locally through the QuokkaPix browser path when the HEIC worker is available. | Useful for phone photos, but availability and memory headroom still matter. | HEIC worker availability is reported in capabilities. | HEIC is an input conversion path, not a universal browser-native export target. |
| JPEG XL output | Experimental advanced encoder path only. | Experimental and not a safe default for mobile publishing workflows. | No Canvas fallback. If the encoder cannot load, the run fails instead of producing a mislabeled file. | Many browsers cannot preview JXL directly; keep it for technical/pro workflows. |
| GIF input | Accepted by normal image tools where browser decoding is possible. | Accepted by normal image tools where browser decoding is possible. | GIF limitations are exposed through capabilities. | Background removal does not support GIF input, and animated editing is limited. |
| PDF tools | Merge, split and extract run locally for PDF files in PDF mode. | Works for practical documents, but large scanned PDFs can be heavy. | Use tool=pdf and pdf-tool=merge|split|extract through the app/agent surface. | PDF tools are document workflows. Normal image tools still require image files. |
| ZIP import | Batch image mode can unpack ZIP locally and add supported image files to the queue. | Useful, but large archives can exceed mobile memory limits. | Agents should use memory.recommendedBatchSize after files are selected. | RAR/7z are not accepted. PDF ZIP import is limited to PDF merge. |
| Workers / OffscreenCanvas | Used where supported for heavier browser work. | Used where supported; fallback paths remain available. | Worker support and the current worker decision are exposed in capabilities. | Not every browser API or third-party decoder can run fully off the main thread. |
| WebGPU / local background AI | Background runtime reports whether WebGPU or CPU is selected. | Often CPU-bound or limited by device/browser support. | backgroundModel reports selected quality/model and WebGPU/CPU status. | WebNN is not a required public dependency; agents should not assume it exists. |
| Agent automation | Stable data-agent selectors and window.QuokkaPixAgent expose the same runtime state. | Agents normally run desktop automation, but browser capability rules are the same. | Use getContract(), getState(), getResultManifest(), listRecipes() and listRuleProfiles(). | Files still enter through the browser file input; there is no public server image processing API. |
What agents should do
1
Open /#agent=1 and wait for window.QuokkaPixAgent to be available.
2
Call getState().capabilities before choosing output format, background quality, PDF workflow or batch size.
3
Use memory.recommendedBatchSize when a selected batch is large or a heavy mode is enabled.
4
Read getResultManifest() after completion instead of scraping visible text.
Public proof points
1
The benchmark page publishes repeated browser workflow measurements.
2
The agent test page checks selectors, status, formats and payment policy without uploading a file.
3
agent-manifest.json and llms.txt expose the same public contract for crawlers and local agents.
4
The editor does not expose a server-side image processing API; files remain local to the browser workflow.
FAQ
Why not hard-code one universal compatibility promise?
Because browser export, workers, WebGPU, mobile memory and advanced encoders differ by browser and device. QuokkaPix exposes live capabilities so people and agents can make a decision for the current session.
What happens when an advanced encoder is unavailable?
For normal browser-supported formats QuokkaPix can fall back to Canvas export. JPEG XL is different: it has no Canvas fallback, so a missing encoder causes a clear failure instead of a mislabeled file.
Does WebGPU change privacy?
No. WebGPU is only a local compute path for supported browsers. Source files are still supplied through the browser file input and processed locally.