# IDEA.md – en snabb bildvisare för Windows och macOS Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på erfarenheterna från Imager, en bildvisare för Windows och macOS byggd i Rust med Claude Code. ## 1. Vad som ska byggas En bildvisare där **två tal går före allt annat**: tiden från dubbelklick till synlig bild, och tiden från högerpil till nästa bild. Samma program, med samma beteende, på Windows och macOS. Problemet: bra bildvisare som IrfanView finns bara för ett operativsystem, och de som finns för flera är ofta tunga och tröga att starta och bläddra i. Programmet ska kunna: - öppna en bild från filhanteraren eller en fildialog, och bläddra i mappen med piltangenter, Home/End och mushjul - zooma (Ctrl+mushjul förankrat vid pekaren, +/−, anpassa till fönstret, 100 %), panorera med musen, rotera 90° - spela upp animerad GIF och WebP, med paus - kopiera bilden till urklipp, flytta filen till papperskorgen, spara en vriden bild över originalet eller som ny fil - visa en informationsrad som tonar bort (filnamn, plats i mappen, mått, zoom) och en menyrad med alla kommandon - fullskärm - **formatstöd via tillägg** som laddas först när de behövs Format: inbyggt JPEG, PNG/APNG, WebP, GIF, TIFF, BMP. Som tillägg: PSD/PSB, HEIC/HEIF, kamerarå (CR2, RAF), EPS, SVG, ICO/CUR. Ingår **inte**: redigering utöver rotation, batchkonvertering, bibliotek eller katalogisering, progressiv visning av inbäddade miniatyrer (förbered arkitekturen för det, men bygg det inte först). ## 2. Stack och arkitektur Det som är **viktigt** är markerat; resten går att byta. - **Viktigt: Rust + `winit` + `wgpu`**, med `egui` bara som ett tunt lager för meny och informationsrad. Ingen runtime, ingen skräpsamlare, statiskt länkad binär. wgpu ger D3D12 på Windows och Metal på macOS med samma kod. - **En workspace med fem crates**: binären (uppstart, händelseloop, indata, avkodningspool), renderaren (wgpu: textur, tiling, mipmaps, vymatematik, informationsrad), avkodningen (register, inbyggda avkodare, cache, förhandsladdning), tilläggsgränssnittet (stabilt C-ABI som delas av värd och tillägg) och IPC (named pipe på Windows, unix-socket på macOS/Linux). - **Viktigt: huvudtråden får aldrig blockera.** All I/O och avkodning sker på arbetstrådar som rapporterar via kanaler och en `EventLoopProxy`. - **Avkodare i ren Rust**: `zune-jpeg`, `zune-png`, `image-webp`, `gif`, `tiff`, `image` (BMP). Tillägg: `ag-psd`, `heif-oxide`, `rawler`, `stet`, `resvg`, `image`. **Inga C-beroenden** – korskompilering till Windows med `cargo xwin` har ingen fungerande väg att bygga libheif, libraw eller Ghostscript. - **Tilläggens C-ABI** – fem funktioner: ```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); ``` C-ABI snarare än Rusts eget gör att ett tillägg kan skrivas i vilket språk som helst och överlever att värden kompileras om. **Laddningen är lat**: `plugins/` bredvid programfilen skannas först när en filändelse dyker upp som ingen inbyggd avkodare känner igen. Den som bara tittar på JPEG betalar ingenting. En miljövariabel pekar ut katalogen för portabla installationer. - Paketering: Windows korskompilerat med `cargo xwin` (länkning med `rust-lld`, ingen Visual Studio behövs), NSIS-installerare per användare och portabel zip; macOS `.app` och dmg. Filtyperna för filassociationer och `Info.plist` hämtas ur binären själv (`--list-formats`), så de kan aldrig glida isär från vad programmet kan öppna. Ett versionsblock och ett programmanifest i Windows-binären, byggda utan `rc.exe`. ## 3. Beslut som visade sig avgörande **Avkoda före fönstret.** Köa avkodningsjobbet innan fönstret och wgpu-kontexten skapas, så att de överlappar. På Windows är bilden avkodad efter ~12 ms medan grafikkortet blir klart efter ~300 ms. GPU-initieringen (`request_device`) är ~95 % av uppstarten; allt annat är under 20 ms. **En instans tar över.** Andra gången en bild öppnas skickas sökvägen till den redan körande processen via named pipe eller unix-socket: 0,2 ms i stället för en hel uppstart. En flagga (`--new-instance`) stänger av det. **Visa fönstret först när det finns något att visa** – men senast efter 250 ms, så att en trasig fil ändå ger återkoppling. **Viktigt hur:** besluta att visa fönstret *utan* att rita, visa det, och begär omritning först därefter. Att vänta på en ritad bildruta fungerar på Wayland men aldrig på Win32 (ett dolt fönster får inget `WM_PAINT`); att rita direkt fungerar på Win32 men är ett protokollfel på Wayland. **Förhandsladda grannbilderna.** När bild *i* visas ska *i±1* och *i±2* ligga avkodade i en LRU-cache, riktningsviktat efter hur användaren bläddrar. Jobb som blir inaktuella avbryts via en delad flagga. Högerpil kostar då bara en texturuppladdning. **Uppgradera ett jobb som redan är igång.** Förhandsladdningsjobb har generation 0 och meddelar ingen när de blir klara. Bläddrar användaren fram till en bild som redan ligger i kön som förhandsladdning måste begäran *höja jobbets generation*, så att arbetaren vet att någon väntar. Ett avbrutet jobb ersätts i stället för att återanvändas – det svarar aldrig. Utan det fastnar bläddringen på "Läser in". **Zoom, panorering och rotation rör aldrig pixeldata.** Bilden ligger som GPU-textur; vyn är en uniform på 48 byte. Rotationen bakas in först när användaren sparar. **Tiling och mipmaps.** Bilder större än GPU:ns största textur delas i rutor med en pixels utfyllnad (så att skarvarna inte syns), och bara rutor som skär vyporten ritas. Utzoomat används en nedskalad översikt med mipmaps. **Filtrera i gammarum, inte linjärt.** Märk *texturen* `Rgba8Unorm` (inte `…Srgb`), konvertera sRGB→linjärt i shadern efter samplingen, och låt den sRGB-märkta ytan koda tillbaka. Filtrering i linjärt rum är fysikaliskt riktig men gör nedskalade bilder blekare än i alla andra bildvisare. Vid 1:1 ska resultatet vara bitidentiskt med källan. **Formatval på magic bytes, inte filändelse.** En `.jpg` som egentligen är PNG ska visas rätt. **Kamerarå ser ut som TIFF.** Låt TIFF-avkodaren avstå från (a) filer med en känd råsignatur efter huvudet (CR2 har `CR`) och (b) filer vars första IFD säger att bilden är nedskalad – råformat lägger en miniatyr där och sensordatan i en SubIFD. Annars visar den inbyggda TIFF-läsaren råfilens miniatyr på 128×96. **Råbiblioteket väljs på komprimerad X-Trans.** `rawloader` klarar inte Fujifilms komprimerade X-Trans; `rawler` gör det. Lägg CR2 och RAF i samma tillägg, eftersom de delar hela kodvägen. **Flytta sällan använda format till tillägg.** SVG via `resvg` drar med sig en typsnittsdatabas och en textmotor. Som tillägg blev kärnbinären 1,8 MB (12 %) mindre; priset är ~14 ms extra första gången en SVG öppnas. En inbyggd avkodare får alltid första tjing, så ett format måste tas *bort* ur kärnan för att ett tillägg ska nås. **Rullhjul bläddrar, Ctrl+rullhjul zoomar.** Styrplattor skickar kontinuerlig rullning; samla deltan tills det blivit ett helt steg – tröskel 160 px för bläddring och 50 px för zoom – annars hoppar en svepning ett tiotal bilder. **Informationsraden utanför första bildrutan.** egui:s initiering bygger en teckenatlas och kostar tiotals millisekunder. Den första rutan visar bara bilden; raden kommer i rutan efter. **En källa för genvägar.** Tangentgenvägarna definieras på ett ställe; menyns genvägstext och `--help` formateras ur samma konstanter, och menyn ger samma `Action` som tangentbordet. Alternativ som inte går att välja gråas (Spara tills bilden vridits, Pausa för en stillbild). **Att spara.** Spara är gråat tills bilden vridits – en omkodning som inte ändrar bilden kan bara förlora kvalitet. Ett format som bara kan läsas (råfil) leder till Spara som. Formatet väljs ur filändelsen; JPEG och BMP saknar alfa, så genomskinlighet plattas mot vitt. Efter sparning läses bilden om från disk. **Gränser mot uppblåsta huvuden**: 1024 megapixel totalt, och för JPEG 65 535 pixlar per sida. "Image too large" är ett eget fel, skilt från "damaged image file". Animationer som skulle bli större än 256 MB avkodade visas som stillbild. **Utvecklarhjälp från dag ett**, i appen själv – inte utifrån: - `_WINDOW=1600x800@X,Y` – storlek och läge, före det sparade fönsterläget, och som aldrig sparas - `_SCREENSHOT=fil.png` – läs tillbaka den ritade bildrutan (kopiera ytans textur till en buffert före `present()`, packa om BGRA→RGBA), spara och avsluta. Startar alltid en egen process. - `_SCREENSHOT_DELAY=N` – bildrutor att vänta när bilden visats, räknade först när gränssnittet animerat klart - `_DEBUG_STATE=fit,hud` – steg genom samma `apply` som menyn: `fit`, `actual`, `zoom=2.5`, `hud`, `rotate`, `rotate=ccw`, `next`, `prev`, `first`, `last` - `_DEBUG_MENU=File` – fäll upp en meny - `--bench-startup` – etapptider för uppstartsvägen ## 4. Fallgropar - **Fotografera inte fönstret utifrån.** `PrintWindow` kan ge en svart bild för en wgpu-yta, och skärmfångst tar med det som råkar ligga överst – andra program med privat innehåll. Bygg skärmbilden i appen. - **Fönstrets titel bevisar inte att en bild ritats** – den uppdateras redan vid navigering. Räkna loggens "showing"-rader (på stderr). - **Ett test som använder svart och vitt bevisar ingenting om färgrum.** 0 och 255 är fixpunkter för gammakurvan, så medelvärdet blir 128 i båda rummen. Använd 64 och 192, och kontrollera att testet faller när felet återinförs. - **Ett förhandsladdningsjobb meddelar ingen** – uppgradera det när någon väntar (se avsnitt 3). - **Lita inte på att rita-vid-visning beter sig lika på alla plattformar** (se avsnitt 3). Prova på Windows *och* på den andra plattformen. - **WSLg kraschar för bilder över ~90 MB avkodat** med "Broken pipe" mot Wayland-kompositören. Det är mjukvarurenderingens gräns, inte ett fel i koden; samma filer fungerar på Windows. - **Bygg inte versionsnumret i `build.rs`** – cargo bestämmer själv när det körs om, så numret skulle hoppa och öka även vid `cargo test`. Räkna upp det i byggskripten. - **En osignerad Windows-binär varnas av SmartScreen varje gång**, oavsett kvalitet. Signera både binären och alla tilläggs-DLL:er, med tidsstämpel. Avinstalleraren som NSIS skapar går inte att signera utan ett extra byggpass. - **Generera testkorpuset, checka inte in det** – och se till att testerna säger tydligt att det saknas. ## 5. Krav och mått Riktmärken från Imager: | Vad | Värde | |---|---| | Uppstart på Windows x64 (D3D12), 1600×1200 JPEG: första bildrutan | ~370 ms (286–370 ms beroende på drivrutinens tillstånd) | | Varav: bild avkodad / wgpu-instans / fönster + wgpu klara | 11,6 ms / 18,5 ms / ~310 ms | | Single-instance: överlämning till en körande process | 0,2 ms | | Avkodning 1600×1200 JPEG / 6000×4000 JPEG / 20000×1200 JPEG / 800×600 PNG med alfa | 3,8 / 64,2 / 49,0 / 4,2 ms | | Kärnbinären mindre när SVG och ICO blev tillägg | 1,8 MB, 12 % | | Första SVG-öppningen (laddar tillägget) | ~14 ms extra | | Tilläggens storlek: PSD / HEIC / RAW / EPS / SVG / ICO | 0,7 / 0,6 / 5,7 / 9,0 / 3,1 / 0,3 MB | Målet var 120 ms till första bildruta. Det nås inte utan att GPU-enheten skapas på en egen tråd parallellt med fönstret – prova det tidigt. ## 6. Så verifieras det - `cargo test --workspace --release` och `cargo clippy --workspace --all-targets` utan varningar. - **Ett genererat testkorpus** med avsiktligt trasiga filer, alla åtta EXIF-orienteringar, en felnamngiven PNG, animationer med delrutor och transparens, och ett panorama bredare än GPU:ns största textur. - **Renderingen verifieras på riktigt**: rita bildrutor till en minnesbuffert genom samma pipeline som fönstret och kontrollera pixlarna – det enda sättet att upptäcka speglade bilder, felplacerade rutor eller synliga skarvar. - **Tester för förhandsladdningen**: att bläddring förbi pågående jobb aldrig fastnar. - **Provfiler för tilläggen** (råbilder och HEIC, tiotals MB) hämtas med ett skript och körs genom alla tillägg mot förväntade mått. Använd fritt licensierade filer, till exempel CC0-filer från raw.pixls.us. - **Mät i den körande appen** på Windows: `--bench-startup`, loggen och skärmbilder via utvecklarhjälpen. - macOS provas på riktig hårdvara. ## 7. Arbetssätt - **Plan först**: varför stacken, workspace-strukturen, trådmodellen, snabbhetsknepen och vad som medvetet väntar. Bekräfta de verkliga valen med användaren: stack, hur formatstödet byggs ut, hur minimalt gränssnittet ska vara, vilka snabbhetsknep som ska med i första versionen. - **Mät, gissa inte.** Varje snabbhetsknep ska visa sin effekt i etapptider; en siffra som varierar mellan mättillfällen ska förklaras (A/B-test) innan den tillskrivs en kodändring. - **Ett ärende i taget**, med mätningen i avslutskommentaren. - **Prova på varje plattform.** Två av de svåraste felen syntes bara på en av dem. ## 8. Prompten > Bygg en bildvisare för [Windows och macOS] i [Rust med winit, wgpu och egui] där tiden från dubbelklick till synlig bild och från högerpil till nästa bild går före allt annat. Den ska fungera likadant på båda plattformarna, ha ett minimalt gränssnitt (bara bilden, en menyrad och en informationsrad som tonar bort) och få stöd för fler format genom tillägg med ett stabilt C-ABI som laddas först när de behövs. > > Läs hela IDEA.md nedan först. Den beskriver arkitekturen, snabbhetsknepen, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Skriv en plan: stack, workspace, trådmodell, snabbhetsknep, vad som väntar. Fråga mig om de verkliga valen. > 2. Bygg avkodning och rendering med tester mot ett genererat korpus, och verifiera renderingen genom att rita till en minnesbuffert. > 3. Bygg utvecklarhjälpen (fönsterstorlek, skärmbild ur appen själv, debugsteg) tidigt. > 4. Mät uppstarten i etapper och redovisa siffrorna på [plattform]. > 5. Prova på båda plattformarna innan något kallas klart. > > Format jag behöver utöver de inbyggda: [lista, t.ex. HEIC, kamerarå från [märke], PSD]. > > [klistra in IDEA.md här]