Known limitations and caveats

Current behavior worth knowing. These are not bugs to fix urgently; they are the edges of the chosen approach.

Color adjustments on older Safari

Brightness/contrast/saturation/effects are applied with the canvas filter property in the worker (and CSS filter in the live preview). Canvas filter support landed in Safari 16.4, and OffscreenCanvas filter support is newer still. On older Safari the export may ignore the adjustments (no crash; the file is still produced). The live preview uses CSS filter on an , which Safari supports earlier, so preview and export can diverge there.

Fix path: implement these as explicit pixel math (vips or a shader) - see docs/deferred/enhancements.md.

Clipboard "Copy"

The result card's Copy uses navigator.clipboard.write with a ClipboardItem. Image clipboard write is reliable for PNG in Chromium; JPEG/WebP/AVIF are often rejected by the browser. On failure the button shows "Unavailable". Save (download) always works.

AVIF export

AVIF is encoded by the jSquash AVIF codec. If that codec fails to load, the fallback is OffscreenCanvas.convertToBlob, which most browsers do not support for AVIF - so the export would surface an error rather than silently produce a wrong file. In practice the jSquash AVIF encoder works (verified in Chromium). AVIF encoding is also the slowest and largest codec; it loads lazily only when chosen.

wasm-vips requires cross-origin isolation

The high-quality vips resampler uses threads (SharedArrayBuffer), which needs the page to be cross-origin isolated (COOP same-origin + COEP require-corp). The dev and preview servers send these headers. If a production host does not, vips will not initialize and the app falls back to the canvas resampler automatically (correct output, slightly different resampling quality). The result card shows which engine ran.

require-corp blocks cross-origin subresources

Because of require-corp, any cross-origin resource (CDN scripts, remote model files) needs a CORP header or it is blocked. This directly affects adding ML-based features that fetch models from a CDN; self-host such assets. See docs/deferred/background-removal.md.

Crop is aspect-based, not free-form

react-easy-crop has no resizable crop box. The app offers aspect presets plus an "Original" (source-ratio) mode, not arbitrary corner-drag cropping. See docs/deferred/free-form-crop.md.

Memory on very large images

The pipeline decodes to a bitmap and works on OffscreenCanvas ImageData; the vips path copies pixels in and out of WASM memory. For very large images (24 MP and up) this is heavy though it runs off the main thread. No tiling/streaming is implemented.

No persistence

Reloading the page clears the loaded image and resets settings (format/quality/ template are not persisted). See docs/deferred/enhancements.md.

Passport support is framing-only and US-only

The US passport template sets the correct size (600x600, 2x2 inch at 300 DPI) and shows a manual head/eye-line guide. It does not auto-detect the face, enforce a background color, or cover other countries. See docs/deferred/face-aware-passport.md and background-removal.md.

Verified in Chromium only

End-to-end runtime verification used headless Chromium. Firefox/Safari were not runtime-tested; the Safari canvas-filter caveat above is the main known divergence.