ADR 0008: Options-based SVG cache invalidation

Decision: Cache each file’s SVG keyed on (filePath, JSON.stringify(options)), stored in the renderer Zustand store. Why: Eliminates redundant 100–500 ms conversions on file switch; keeping the cache renderer-side avoids an IPC round-trip on every switch.

Context

Converting a PNG with Sharp + Potrace is CPU-bound and takes 100–500 ms per file depending on size and complexity. When a user switches between files in a batch, re-running the full conversion even when nothing changed was wasteful and made the UI feel slow.

Options considered

Decision

Cache each file’s SVG alongside the exact ConversionOptions used to generate it. On file switch, compare the cached options against the current options using JSON.stringify equality. Only trigger re-conversion when the cache is empty (null) or the options have changed.

// useAppStore.ts
svgCache: Record<string, { options: ConversionOptions; svg: string }>;

// on file switch:
const cached = svgCache[file.path];
const optsMatch = cached && JSON.stringify(cached.options) === JSON.stringify(fileOptions);
const currentSvg = optsMatch ? cached.svg : null;

// useApp.ts, only convert if currentSvg is null:
if (currentFile && currentSvg === null) triggerConversion();

Rationale

JSON.stringify comparison is simple and deterministic for flat option objects constructed from the same shape. More sophisticated strategies (structural diffing, hashing) would add complexity for no practical benefit at this scale. The cache is intentionally not persisted, it is rebuilt as needed within a session.

Cache lives in the renderer Zustand store, not in main

This is a deliberate architectural placement. The cache is tied to UI concerns, which file is currently selected, which options the UI is showing, when to skip re-conversion before issuing an IPC call. Moving the cache into the main process would mean every file switch still pays one round-trip across the IPC boundary just to ask “do you have this cached?”, a question the renderer can answer locally for free. Keeping the cache in the renderer means the UX-critical fast path (instant switch between two previously-tuned files) never crosses process boundaries.

Main is intentionally stateless about UI: it converts on request, returns SVG, doesn’t remember. That separation falls out of the security boundary in ADR 0002, main is the privileged process and gets less mutable state by design, not more. The cache is renderer-scoped session state, in the same store family as fileOptionsByPath and currentFile (ADR 0007).

Consequences

Positive

Negative

Follow-up

Code: src/renderer/store/useAppStore.ts · src/renderer/hooks/useApp.ts