Cache RAW-to-TIFF conversions in OPFS so they survive a reload

[adulbrich]

Split out of #232 (Phase 4), which is otherwise complete.

What exists

convert_raw_img's replacement rides on the dcraw_emu WebAssembly build, and #242 made the resulting TIFF shared between the viewer's preview and the pipeline, so a RAW file is converted once per session rather than twice.

Per session. The cache lives in memory and dies with the tab. Reload the page, or come back tomorrow, and every RAW in the bracket is converted again from scratch.

Why it matters

RAW conversion is the most expensive single thing the app does on a CR2 set, and it is pure recomputation: the same input bytes always produce the same TIFF. The desktop build used to keep this on disk (src-tauri/src/image_cache/, keyed by compute_hash_for_file) and lost that when the pipeline moved to WebAssembly, so this is a regression for desktop users as well as a gap for browser ones.

Depends on the RAW conversion worker

FileSystemFileHandle.createSyncAccessHandle() -- the fast OPFS path -- is callable only from a dedicated Web Worker. Not the main thread, not an iframe, not a SharedWorker. It is excluded there deliberately, because synchronous I/O on the main thread blocks rendering.

So this needs a dedicated worker that holds the RAW bytes. Moving dcraw_emu off the main thread (src/lib/raw-worker.ts) is being done separately, for its own reason -- callMain is synchronous, so converting a 10-frame CR2 bracket for thumbnails froze the tab for ~20 s. That worker is where this belongs: it already receives the source bytes, so it can hash them without a second read, and the persistent tier never has to cross back to the page.

Scope

• Back the RAW-to-TIFF cache with OPFS, so a conversion survives a reload.
• Two tiers, two keys. The session cache stays keyed on path|size:mtime, which costs no file read at all when a frame is already resident. Only the OPFS tier is keyed by a content hash, and it is consulted just on a session-cache miss -- where the bytes have been read anyway. Hashing on every request instead would mean reading and digesting ~250 MB per session for a 10-frame bracket to avoid conversions the in-memory cache had already avoided.
• Key the OPFS tier by content hash rather than path, so a file that moved is still a hit and a file that changed is not.
• Bound it, and evict least-recently-used first. A 10-frame CR2 bracket is hundreds of megabytes of TIFF, so an unbounded cache is a way to fill someone's disk quietly.
• Keep an index. OPFS exposes no access time, so eviction needs sizes and last-used stamps recorded alongside the blobs -- a small record in OPFS or in IndexedDB. Naming the mechanism here because "evict oldest-first" is not implementable from OPFS metadata on its own.
• Serve the desktop build from the same code. There is one pipeline now, and a second caching implementation behind isTauri() would be the thing that drifts.

Open question

Whether OPFS behaves in all three Tauri v2 webviews: WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux. Sharing one implementation across desktop and browser is a design constraint above, not an observation, and it should be verified before it is relied on -- WebKitGTK especially, and given the OPFS write bugs that have shown up in Safari.

Notes

OPFS is available in every target browser including Safari. It needs no permission prompt, unlike the File System Access API, which Safari does not implement at all.

Worth considering later, not worth building first: memoising fingerprint -> content hash would let an unchanged file skip the read and the digest on a later session.

Not a blocker for the deployment: the app is correct without it, just slower on a second visit.

[adulbrich]

Implemented in #249, with one deliberate departure from this issue's design: the cache is backed by IndexedDB, not OPFS.

The open question, answered

This issue asks:

Whether OPFS behaves in all three Tauri v2 webviews: WKWebView on macOS, WebView2 on Windows, WebKitGTK on Linux.

It does not. e2e-web/tests/storage-probe.spec.ts was written and run first, before any cache code, and CI reports:

Host	Engine	opfsAvailable	IndexedDB 67 MB
Browser	WebKit	false (quota: null)	ok, 298 ms
Linux desktop	WebKitGTK 605.1.15	false	ok
Browser	Chromium	true	ok
Windows desktop	WebView2	true	ok

navigator.storage.getDirectory is not merely slow or quota-limited on those two — it does not exist. An OPFS-backed cache would have silently never worked for Safari users or Linux desktop users, which is the failure mode hardest to notice: the app would simply have kept reconverting, exactly as before.

IndexedDB round-tripped 67 MB on every engine tested, and already backs presets, settings and run history in production.

The scope points in this issue survive the substitution intact: two tiers with two keys, the OPFS tier's content-hash key, bounded LRU eviction, an index carrying sizes and last-used stamps, and one implementation serving desktop and browser. Only the storage primitive changed. Approach C (OPFS where available, IndexedDB elsewhere) was rejected for the reason this issue itself gives — "a second caching implementation behind isTauri() would be the thing that drifts".

Result

	first import	after reload
3 frames	9,208 ms	1,977 ms	4.7x
10 frames	25,715 ms	5,198 ms	4.9x
control, cache disabled	8,036 ms	7,944 ms	none

The control rebuilds raw-worker.ts from its pre-cache parent and shows the second import staying as slow, so the saving is causally the cache rather than warm-up.

One addition beyond this issue's scope, and why

The key is sha256(bytes) + "-" + toolTag, where the tag covers the dcraw_emu commit, the Emscripten version and the dcrawArgs flags. Content hash alone is not sufficient: rebuilding the WebAssembly artifacts — which #244 automates — would otherwise leave every cached TIFF valid-looking but produced by a different demosaic, breaking the byte-identical guarantee raw-preview.ts exists to hold.

The content hash is also a correctness requirement rather than the optimisation this issue frames it as. registerSessionFile mints /session/<n>/<name> from a counter that restarts each session, so a path-keyed cache would name different bytes with the same string across visits and serve the wrong image.

Left undone

• navigator.storage.persist() is now requested, and the budget clamps to a share of navigator.storage.estimate().quota — but the ceiling for large values in IndexedDB is still unmeasured above 67 MB. The probe measured one frame, not a full bracket.
• macOS/WKWebView remains unprobed: the desktop e2e matrix is [ubuntu-22.04, windows-latest], so it needs a local Tauri debug build. It no longer blocks anything, since WebKitGTK alone settled the backend.
• Memoising fingerprint → content hash, explicitly out of scope here and still is.