# IDEA.md – a fast image viewer for Windows and macOS This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on what was learned building Imager, an image viewer for Windows and macOS written in Rust with Claude Code. ## 1. What to build An image viewer where **two numbers come before everything else**: the time from double-click to a visible image, and the time from the right arrow to the next image. The same program, behaving the same way, on Windows and macOS. The problem: good image viewers like IrfanView exist for only one operating system, and those that exist for several are often heavy and slow to start and to browse in. The program must be able to: - open an image from the file manager or a file dialog, and browse the folder with the arrow keys, Home/End and the mouse wheel - zoom (Ctrl+wheel anchored at the pointer, +/−, fit to window, 100 %), pan with the mouse, rotate by 90° - play animated GIF and WebP, with pause - copy the image to the clipboard, move the file to the recycle bin, save a rotated image over the original or as a new file - show an info bar that fades out (file name, position in the folder, size, zoom) and a menu bar with every command - full screen - **format support via plugins** that load only when needed Formats: built in JPEG, PNG/APNG, WebP, GIF, TIFF, BMP. As plugins: PSD/PSB, HEIC/HEIF, camera raw (CR2, RAF), EPS, SVG, ICO/CUR. **Not** included: editing beyond rotation, batch conversion, libraries or cataloguing, progressive display of embedded thumbnails (prepare the architecture for it, but don't build it first). ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Important: Rust + `winit` + `wgpu`**, with `egui` only as a thin layer for the menu and info bar. No runtime, no garbage collector, a statically linked binary. wgpu gives D3D12 on Windows and Metal on macOS with the same code. - **A workspace with five crates**: the binary (startup, event loop, input, decoding pool), the renderer (wgpu: texture, tiling, mipmaps, view maths, info bar), decoding (registry, built-in decoders, cache, prefetch), the plugin interface (a stable C ABI shared by host and plugins) and IPC (named pipe on Windows, unix socket on macOS/Linux). - **Important: the main thread must never block.** All I/O and decoding happen on worker threads that report back through channels and an `EventLoopProxy`. - **Pure-Rust decoders**: `zune-jpeg`, `zune-png`, `image-webp`, `gif`, `tiff`, `image` (BMP). Plugins: `ag-psd`, `heif-oxide`, `rawler`, `stet`, `resvg`, `image`. **No C dependencies** – cross-compiling to Windows with `cargo xwin` has no working way to build libheif, libraw or Ghostscript. - **The plugins' C ABI** – five functions: ```c uint32_t imager_abi_version(void); const char* imager_extensions(void); /* "psd,psb" */ int imager_probe(const uint8_t* head, size_t len); int imager_decode(const uint8_t* data, size_t len, ImagerImage* out); void imager_free(ImagerImage* img); ``` A C ABI rather than Rust's own means a plugin can be written in any language and survives the host being recompiled. **Loading is lazy**: `plugins/` next to the executable is scanned only when a file extension appears that no built-in decoder recognizes. Someone who only looks at JPEGs pays nothing. An environment variable points to the directory for portable installs. - Packaging: Windows cross-compiled with `cargo xwin` (linked with `rust-lld`, no Visual Studio needed), a per-user NSIS installer and a portable zip; macOS `.app` and dmg. The file types for file associations and `Info.plist` come from the binary itself (`--list-formats`), so they can never drift from what the program can open. A version block and an application manifest in the Windows binary, built without `rc.exe`. ## 3. Decisions that turned out to matter **Decode before the window.** Queue the decoding job before the window and the wgpu context are created, so they overlap. On Windows the image is decoded after ~12 ms while the GPU is ready after ~300 ms. GPU initialization (`request_device`) is ~95 % of startup; everything else is under 20 ms. **One instance takes over.** The second time an image is opened, the path is sent to the already running process through a named pipe or unix socket: 0.2 ms instead of a whole startup. A flag (`--new-instance`) turns it off. **Show the window only when there's something to show** – but after 250 ms at the latest, so a broken file still gives feedback. **Important how:** decide to show the window *without* drawing, show it, and only then request a redraw. Waiting for a drawn frame works on Wayland but never on Win32 (a hidden window gets no `WM_PAINT`); drawing straight away works on Win32 but is a protocol error on Wayland. **Prefetch the neighbours.** When image *i* is shown, *i±1* and *i±2* should be decoded in an LRU cache, weighted by the direction the user browses. Jobs that become stale are cancelled through a shared flag. The right arrow then costs only a texture upload. **Upgrade a job that's already running.** Prefetch jobs have generation 0 and notify no one when they finish. If the user browses to an image already in the queue as a prefetch, the request must *raise the job's generation*, so the worker knows someone is waiting. A cancelled job is replaced rather than reused – it never answers. Without this, browsing gets stuck on "Loading". **Zoom, pan and rotation never touch pixel data.** The image sits as a GPU texture; the view is a 48-byte uniform. Rotation is baked in only when the user saves. **Tiling and mipmaps.** Images larger than the GPU's largest texture are split into tiles with one pixel of padding (so seams don't show), and only tiles intersecting the viewport are drawn. Zoomed out, a downscaled overview with mipmaps is used. **Filter in gamma space, not linear.** Mark the *texture* `Rgba8Unorm` (not `…Srgb`), convert sRGB→linear in the shader after sampling, and let the sRGB-marked surface encode back. Filtering in linear space is physically correct but makes downscaled images paler than in every other image viewer. At 1:1 the result must be bit-identical to the source. **Choose the format by magic bytes, not the file extension.** A `.jpg` that's really a PNG must display correctly. **Camera raw looks like TIFF.** Have the TIFF decoder decline (a) files with a known raw signature after the header (CR2 has `CR`) and (b) files whose first IFD says its image is downscaled – raw formats put a thumbnail there and the sensor data in a SubIFD. Otherwise the built-in TIFF reader shows the raw file's 128×96 thumbnail. **Pick the raw library on compressed X-Trans.** `rawloader` can't handle Fujifilm's compressed X-Trans; `rawler` can. Put CR2 and RAF in the same plugin, since they share the whole code path. **Move rarely used formats to plugins.** SVG via `resvg` drags in a font database and a text layout engine. As a plugin, the core binary became 1.8 MB (12 %) smaller; the price is ~14 ms extra the first time an SVG is opened. A built-in decoder always gets first pick, so a format must be *removed* from the core for a plugin to be reached. **The wheel browses, Ctrl+wheel zooms.** Trackpads send continuous scrolling; accumulate the delta until it's a whole step – threshold 160 px for browsing and 50 px for zoom – or one swipe jumps a dozen images. **The info bar outside the first frame.** egui's initialization builds a glyph atlas and costs tens of milliseconds. The first frame shows only the image; the bar comes in the next. **One source for shortcuts.** Keyboard shortcuts are defined in one place; the menu's shortcut text and `--help` are formatted from the same constants, and the menu produces the same `Action` as the keyboard. Unavailable items are greyed out (Save until the image is rotated, Pause for a still image). **Saving.** Save is greyed out until the image has been rotated – re-encoding that doesn't change the image can only lose quality. A read-only format (raw) leads to Save As. The format comes from the file extension; JPEG and BMP have no alpha, so transparency is flattened against white. After saving, the image is re-read from disk. **Limits against inflated headers**: 1024 megapixels in total, and for JPEG 65,535 pixels per side. "Image too large" is its own error, separate from "damaged image file". Animations that would exceed 256 MB decoded are shown as a still image. **Developer hooks from day one**, in the app itself – not from outside: - `_WINDOW=1600x800@X,Y` – size and position, ahead of the saved window state, and never saved - `_SCREENSHOT=file.png` – read back the drawn frame (copy the surface texture to a buffer before `present()`, repack BGRA→RGBA), save and exit. Always starts its own process. - `_SCREENSHOT_DELAY=N` – frames to wait after the image is shown, counted only once the interface has finished animating - `_DEBUG_STATE=fit,hud` – steps through the same `apply` as the menu: `fit`, `actual`, `zoom=2.5`, `hud`, `rotate`, `rotate=ccw`, `next`, `prev`, `first`, `last` - `_DEBUG_MENU=File` – open a menu - `--bench-startup` – stage timings for the startup path ## 4. Pitfalls - **Don't photograph the window from outside.** `PrintWindow` can return a black image for a wgpu surface, and a screen grab includes whatever happens to be on top – other programs with private content. Build the screenshot into the app. - **The window title doesn't prove an image was drawn** – it updates already on navigation. Count the log's "showing" lines (on stderr). - **A test using black and white proves nothing about colour spaces.** 0 and 255 are fixed points of the gamma curve, so the average is 128 in both spaces. Use 64 and 192, and check that the test fails when the bug is reintroduced. - **A prefetch job notifies no one** – upgrade it when someone is waiting (see section 3). - **Don't trust draw-on-show to behave the same on every platform** (see section 3). Try it on Windows *and* the other platform. - **WSLg crashes for images over ~90 MB decoded** with "Broken pipe" against the Wayland compositor. That's the software renderer's limit, not a bug in the code; the same files work on Windows. - **Don't bump the version number in `build.rs`** – cargo decides when it reruns, so the number would jump and increase even on `cargo test`. Bump it in the build scripts. - **An unsigned Windows binary is warned about by SmartScreen every time**, regardless of quality. Sign both the binary and every plugin DLL, with a timestamp. The uninstaller NSIS generates can't be signed without an extra build pass. - **Generate the test corpus, don't check it in** – and make the tests say clearly when it's missing. ## 5. Requirements and measurements Benchmarks from Imager: | What | Value | |---|---| | Startup on Windows x64 (D3D12), 1600×1200 JPEG: first frame | ~370 ms (286–370 ms depending on driver state) | | Of which: image decoded / wgpu instance / window + wgpu ready | 11.6 ms / 18.5 ms / ~310 ms | | Single instance: handover to a running process | 0.2 ms | | Decoding 1600×1200 JPEG / 6000×4000 JPEG / 20000×1200 JPEG / 800×600 PNG with alpha | 3.8 / 64.2 / 49.0 / 4.2 ms | | Core binary smaller when SVG and ICO became plugins | 1.8 MB, 12 % | | First SVG open (loads the plugin) | ~14 ms extra | | Plugin sizes: PSD / HEIC / RAW / EPS / SVG / ICO | 0.7 / 0.6 / 5.7 / 9.0 / 3.1 / 0.3 MB | The target was 120 ms to the first frame. It isn't reached without creating the GPU device on its own thread in parallel with the window – try that early. ## 6. How it's verified - `cargo test --workspace --release` and `cargo clippy --workspace --all-targets` with no warnings. - **A generated test corpus** with deliberately broken files, all eight EXIF orientations, a misnamed PNG, animations with sub-frames and transparency, and a panorama wider than the GPU's largest texture. - **Rendering is verified for real**: draw frames to an in-memory buffer through the same pipeline as the window and check the pixels – the only way to catch mirrored images, misplaced tiles or visible seams. - **Tests for prefetching**: browsing past running jobs must never get stuck. - **Sample files for the plugins** (raw and HEIC, tens of MB) are fetched by a script and run through every plugin against expected dimensions. Use freely licensed files, for example CC0 files from raw.pixls.us. - **Measure in the running app** on Windows: `--bench-startup`, the log and screenshots via the developer hooks. - macOS is tried on real hardware. ## 7. Way of working - **Plan first**: why the stack, the workspace structure, the thread model, the speed tricks and what deliberately waits. Confirm the real choices with the user: the stack, how format support is extended, how minimal the interface should be, which speed tricks go into the first version. - **Measure, don't guess.** Every speed trick should show its effect in stage timings; a number that varies between runs should be explained (A/B test) before it's attributed to a code change. - **One task at a time**, with the measurement in the closing comment. - **Try it on every platform.** Two of the hardest bugs only showed on one of them. ## 8. The prompt > Build an image viewer for [Windows and macOS] in [Rust with winit, wgpu and egui] where the time from double-click to a visible image and from the right arrow to the next image come before everything else. It should behave the same on both platforms, have a minimal interface (just the image, a menu bar and an info bar that fades out) and get support for more formats through plugins with a stable C ABI that load only when needed. > > Read all of IDEA.md below first. It describes the architecture, the speed tricks, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Write a plan: stack, workspace, thread model, speed tricks, what waits. Ask me about the real choices. > 2. Build decoding and rendering with tests against a generated corpus, and verify rendering by drawing to an in-memory buffer. > 3. Build the developer hooks (window size, a screenshot from the app itself, debug steps) early. > 4. Measure startup in stages and report the numbers on [platform]. > 5. Try it on both platforms before calling anything done. > > Formats I need beyond the built-in ones: [list, e.g. HEIC, camera raw from [brand], PSD]. > > [paste IDEA.md here]