# IDEA.md – bygg en egen snabb PDF-läsare Den här filen ä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 Pdfer, en PDF-läsare för Windows och macOS skriven i Rust, men du behöver inte ha sett den koden. --- ## 1. Vad som ska byggas **Syftet:** en PDF-läsare för skrivbordet som ersätter Adobe Acrobat Reader för den som vill ha något snabbt och lätt, utan påtvingade tilläggsprogram, och med de funktioner som saknas i Readers gratisversion: texttolkning (OCR) av skannade dokument och rättning av text. **Huvudkravet är upplevd hastighet.** Kallstart, filöppning och sidbyte ska kännas omedelbara, även i dokument på tusentals sidor. Varje designbeslut nedan ska vägas mot det. **Ska kunna:** - Visa PDF:er med bläddring (piltangenter, PgUp/PgDn, Home/End, mushjul – ett hjulsteg är en sida), zoom kring muspekaren (Ctrl+hjul, Ctrl +/−/0), passningslägen (hel sida, sidbredd, faktisk storlek) och rotation av vyn. - Visa aktuell sida och antal sidor ("12 / 348"), med en dragbar scrollbar som når hela dokumentet och visar sidnummer medan man drar. - Ha flera dokument öppna i flikar i ett och samma fönster. Dubbelklickar man på en PDF när programmet redan kör ska filen bli en ny flik, inte ett nytt program. - Markera och kopiera text (dra, dubbelklick = ord, trippelklick = textobjekt), med textmarkör när pekaren står över markerbar text. - Söka i dokumentet medan man skriver, och söka genom alla PDF:er i en mapp med undermappar, utan att något dokument behöver vara öppet. - Miniatyrer och innehållsförteckning (bokmärken) i en sidopanel. - Texttolka skannade sidor och skriva in texten som ett osynligt textlager, så att den sparade filen blir sökbar i alla PDF-läsare. - Rätta befintlig text, ett textobjekt i taget, med ångra/gör om och sparning. - Skriva ut med sidintervall (`1-5, 8, 11-`), kopior, skalning och dubbelsidigt. - Komma ihåg läsposition per fil. **Ingår uttryckligen inte:** - Kommentarer, formulärifyllning och signering. - Textredigering med ombrytning. PDF har inget textflöde: ett stycke är ett antal objekt med absoluta positioner. Låtsas inte vara en ordbehandlare. - Markering över sidgränser (PDFium numrerar tecken per sida). - Molntjänster, konton, telemetri. --- ## 2. Stack och arkitektur **Språk: Rust.** Ingen GC, ingen runtime-start, kostnadsfri FFI mot C-bibliotek. Uppstarten mäts i tiotals millisekunder. Bortvalt: Electron/Tauri (en webbvy kostar hundratals ms vid start), C++/Qt (tyngre bygge, licensfrågor), .NET (sämre plattformsoberoende GUI). **PDF-motor: PDFium**, förbyggd från `bblanchon/pdfium-binaries` (välj varianten utan V8 och XFA), laddad vid körning med `libloading`. Samma motor som Chrome – den mest beprövade koden mot trasiga PDF:er som finns. BSD-3-licens. Den täcker även redigering (page objects, `FPDFText_SetText`, `FPDFPage_GenerateContent`, sparning). **OCR: Tesseract 5.5** med språkdata `swe` och `eng`, också laddad vid körning. Programmet ska fungera utan OCR-biblioteken – då gråas menyvalet ut. **Gränssnitt: egui via eframe, renderat med wgpu.** Egenritat och identiskt på alla plattformar, GPU-accelererat. Sidor ritas som texturer, så sidbyte kostar nästan ingen CPU. Ritas bara om när något händer: 0 % CPU i vila. **Struktur:** en Cargo-workspace med två crates. `core` är helt UI-fritt (motor, layout, sessioner, text, sökning, utskriftslogik, OCR) så att det kan testas och mätas utan fönster. `app` är fönstret och inmatningen. **Utbytbart:** egui mot annat GUI, Tesseract mot annan OCR-motor (men mät först, se fallgroparna). Lägg motorn bakom ett trait så att t.ex. MuPDF kan provas. **Inte utbytbart utan att tänka om:** att all PDFium-användning sker på en tråd. **Beroenden:** håll dem få. Inget async-runtime (tokio) – vanliga trådar och kanaler (`crossbeam-channel`) räcker och kostar inget vid start. Release-profil: `lto = "fat"`, `codegen-units = 1`, `panic = "abort"`, `strip = true`. --- ## 3. Beslut som visade sig avgörande **3.1 En enda renderingstråd äger PDFium.** PDFium har globalt tillstånd och är inte trådsäkert. Fler trådar ger ingen parallellitet och ett misstag ger SIGABRT, inte ett felmeddelande. All PDFium-användning – rendering, text, sökning, utskrift, OCR-inskrivning, sparning – sker därför på *en* tråd som äger en motor per öppet dokument. UI-tråden skickar kommandon och får tillbaka händelser över kanaler. **3.2 Arbetsloopen är en prioritetsstege.** Varje varv tar renderingstråden *en* arbetsenhet från det högst prioriterade steget som har något att göra, och läser kommandokön mellan varven. Ordning ungefär: synliga sidor → text för synliga sidor → sökning i dokumentet → mätning av sidstorlekar → innehållsförteckning → katalogsökning. Det är den här mekanismen som gör Avbryt möjligt utan egen trådsynkronisering, och som gör att en långsam katalogsökning aldrig märks när man scrollar. Nya jobb läggs till som ett steg i stegen, aldrig som en ny tråd. **3.3 Rendering ska kunna avbrytas mitt i en sida.** Använd `FPDF_RenderPageBitmap_Start` / `FPDF_RenderPage_Continue` med en `IFSDK_PAUSE`-callback. En tung vektorsida (CAD, karta) kan ta sekunder; utan detta blockerar den tråden långt efter att användaren bläddrat vidare. UI:t skickar om hela önskelistan när vyn ändras, tjänsten ersätter den gamla, och varje jobb har ett löpnummer så att ett sent avbrott aldrig träffar nästa sida. **3.4 Skriv egna FFI-bindningar.** Färdiga Rust-bindningar (`pdfium-render`) döljer `FPDF_PAGE`- och `FPDF_BITMAP`-handtagen, vilket omöjliggör både avbrytbar och kopiefri rendering. Deklarera själv de funktioner du behöver. **Läs signaturerna ur headerfilerna** för exakt den biblioteksversion du använder – en felaktig signatur ger tyst minneskorruption, inte ett kompileringsfel. Byt aldrig biblioteksversion utan att läsa om dem. **3.5 Öppna fönstret först, gör allt annat parallellt.** Uppstarten domineras av fönster- och GPU-initiering, inte av PDF-arbetet (motorn är klar efter ~30 ms). Beräkna aldrig alla sidstorlekar vid start: anta att alla sidor är lika stora som sida 1 och korrigera layouten inkrementellt i bakgrunden. Använd `FPDF_GetPageSizeByIndexF`, som inte laddar sidan. **3.6 Virtuell layout.** Sidhöjderna i en prefixsumma ger O(log n) mappning mellan scrollposition och sida oavsett dokumentstorlek. Behåll ett scrollankare så att sidan under läsaren står still när en uppskattad storlek ersätts av den riktiga. **3.7 Kopiefri rendering och textur-cache i UI-lagret.** Låt PDFium skriva rakt in i en buffert som sedan laddas upp till GPU:n. Be om `FPDF_REVERSE_BYTE_ORDER` så slipper du konvertera BGRA→RGBA. Cacha GPU-texturer (inte pixelbuffertar) med minnesbudget, nycklade på (dokument, sida, zoomsteg, rotation); kvantisera zoom i steg så att småjusteringar återanvänder texturer. Cacha ~8 öppna sidhandtag – `FPDF_LoadPage` kostar lika mycket som att rendera en textsida. **3.8 Rutor vid hög zoom.** Över ~4 megapixel (≈300 % för A4) delas sidan i rutor om 1024×1024 och bara de synliga renderas. Utan detta är en A4 vid 800 % 128 MB och 40–51 ms för en enda sida. **3.9 Text extraheras en gång per sida, till rena data.** En lista tecken och en ruta per tecken. Markering, kopiering, träffmarkering och textmarkör blir då ren lokal aritmetik i UI-tråden, utan trådväxling per musrörelse. **3.10 Ett gemensamt koordinatsystem för text: den visade sidan.** PDFium rapporterar sidans mått *efter* sidans egen `/Rotate`, men placerar tecken i *oroterade* användarkoordinater med boxens (CropBox/MediaBox) hörn som origo. Räkna om varje teckenruta, sökträff och objektgräns till den visade sidans system vid utläsningen (läs `FPDFPage_GetRotation` och `FPDF_GetPageBoundingBox`), och räkna åt andra hållet när du skriver in text (OCR-lagret). Vyns egen rotation läggs ovanpå det. **3.11 OCR skriver ett osynligt textlager.** Rendera sidan i 200 dpi, tolka, skriv ett textobjekt per ord med renderingsläge 3 (osynligt) och en matris som täcker ordets ruta. Den sparade filen blir sökbar överallt. Jobbet är modalt (hela dokumentet i ett svep, med förlopp och Avbryt), vilket låter det bli ett steg i arbetsloopen i stället för en egen tråd med cache. Kör aldrig OCR på sidor som redan har text. **3.12 En instans per användare.** Den första instansen lyssnar på en lokal socket (namnet innehåller användarnamnet); senare starter skickar sina sökvägar dit och avslutar. Mät: överlämningen ska ta några millisekunder. **3.13 Utskrift är vektorer, inte skärmbilder.** På macOS/Linux skickas originalfilen orörd till CUPS (`lp`). På Windows ritar PDFium direkt på skrivarens enhetskontext med `FPDF_RenderPage`. All urvalslogik (sidintervall, aktuell sida, dokumentets egna utskriftsönskemål i `/ViewerPreferences`) ligger i gemensam, testad kod; plattformslagret får ett färdigt jobb. **3.14 Sparning skriver aldrig över originalet direkt.** Skriv till en tempfil och byt in den. Över originalet: stäng dokumentet, byt filen, öppna igen. --- ## 4. Fallgropar – gör så här, inte så - **Öppna aldrig en egen PDFium-instans utanför renderingstråden**, inte ens för "bara utskrift". Det gav SIGABRT i Windows-utskriften. Och testramverket kör tester parallellt: alla tester som rör PDFium måste ta ett gemensamt mutex. - **Lita inte på färdiga bindningar för avbrytbar rendering.** `pdfium-render` kunde inte avbryta en tung sida (tråden blockerades i 5,3 s). Egna bindningar avbryter på ~40 ms. - **Mät FFI-overhead, anta den inte.** Första egna versionen var långsammare än kraden (3,6 ms/sida) – bara 1,45 ms var rendering. Kopian och omladdning av sidan var resten. Fasmät innan du optimerar. - **Glöm inte sidans egen rotation.** Utan omräkningen i 3.10 hamnar markeringen ett kvarts varv fel på varje liggande sida som egentligen är en stående med `/Rotate 90` – mycket vanligt. Uppmätt: bara 59 % av teckenrutorna låg över text före rättelsen, över 95 % efter. - **Vrid liggande sidor vid utskrift.** Placeras en liggande sida oroterad på stående papper krymps den till knappt halva arket. Vrid den 90° moturs (samma riktning som Windows egen liggande orientering) när sidans och papperets orientering skiljer sig, i både "anpassa" och "faktisk storlek". Lägg placeringsberäkningen i plattformsoberoende kod så att den kan testas. - **Ett minimerat fönster kör ingen UI-kod i eframe.** egui räknar det som osynligt och hoppar över hela UI-passet, så `ViewportCommand::Minimized(false)` skickat därifrån når aldrig fram. Häv minimeringen direkt mot operativsystemet (Windows: `ShowWindowAsync(hwnd, SW_RESTORE)` om `IsIconic`) från tråden som tar emot den överlämnade filen; ge sedan fokus från UI:t. - **Välj OCR-motor med mätning, inte känsla.** En ren Rust-motor (ocrs) gav 8,7 % teckenfel på svensk text mot 0,00 % för Tesseract – dess modell saknar å, ä och ö helt. Ha en facittext bredvid varje testskanning. - **Rendera för OCR i 200 dpi.** 120 dpi gav 1,8 % teckenfel, 100 dpi 22 %. 200 dpi håller en A4 under 4 megapixel, så sidan inte delas i rutor. - **Läs tillbaka texten efter varje redigering.** PDFium byter tyst ut tecken som saknas i typsnittets delmängd (uppmätt: `ẞ` blev `ÿ`). Jämför med det som begärdes och säg till användaren – annars är det dataförlust ingen ser. - **Bygg Tesseract själv om du länkar C-runtimen statiskt.** Färdiga paket drar in libcurl, libarchive och sex bildkodekar. Med valfria beroenden avstängda går kedjan från elva bibliotek till två. Patcha uppströms portabilitetsfel i byggskriptet och låt skriptet avbryta om mönstret inte finns, så att en versionshöjning stannar bygget i stället för att tyst bygga något annat. - **macOS: dubbelklick i Finder levereras som Apple Event**, inte som argument, och eframe/winit exponerar den inte. Räkna med det, eller planera en egen `NSApplicationDelegate`. - **Låt inte tester hoppa över tyst** när ett bibliotek saknas: avbryt med ett förklarande meddelande och ha en uttrycklig miljövariabel för att hoppa över. "20 passed" på noll sekunder ser ut som ett godkänt bygge. --- ## 5. Krav och mått Riktmärken från Pdfer (Linux/WSL med mjukvarurendering – motorsiffrorna är representativa, fönstersiffrorna mäts om på riktig hårdvara): - *Mål, inte uppmätt på riktig hårdvara:* fönster < 80 ms; första sidan synlig < 150 ms varm, < 300 ms kall. (Uppmätt i WSL: första bildrutan efter 77–250 ms.) - Öppna ett dokument på 500 sidor: 1,8–3,5 ms. Öppningstiden får inte bero på sidantalet. - Rendera en A4 vid 108 dpi: 1,4–3,2 ms (p95 3,8 ms). En tråd räcker med god marginal (300–700 sidor/s). - Avbryta en pågående tung sida: ~40 ms. - Sidstorlek för ett 1-sidigt dokument: 0,3 ms; alla 500 sidstorlekar: ~150 ms (görs i bakgrunden, aldrig vid start). - Överlämning mellan instanser: 2–4 ms. - 0 % CPU i vila. - Minnet ska plana ut vid zoom 100–800 % (rutor + budget). - OCR på en normal kontorsskanning i 300 dpi: 0,00 % teckenfel; en sida på ~0,8 s. - Binär ~11 MB; installationspaket med PDF-motor och OCR ~16 MB. - Windows: statiskt länkad C-runtime, inget VC++-paket krävs. --- ## 6. Så verifieras det - **Testkorpus, genererad av ett beroendefritt skript och incheckad:** 1 sida, 500 sidor, blandade sidstorlekar (bryter antagandet att alla är som sida 1), sidor med `/Rotate` 0/90/180/270 och en CropBox som inte börjar i noll, rena färgfält (avslöjar förväxlade röd/blå-kanaler), en tung vektorsida, en fil med trasig xref, samt skannade sidor i olika kvalitet med facittext – inklusive en fil där vissa sidor redan har text. - **Enhetstester** för layout, sidintervallstolkning, koordinatomräkning (alla rotationer, rundgång åt båda hållen), utskriftsplacering, ord-/objektmarkering. - **Integrationstester mot den riktiga motorn** för det enhetstester inte ser: att markeringsrutorna ligger över mörka pixlar i den renderade sidan (det är det enda som bevisar att markeringen hamnar där texten syns), att en ruta vid hög zoom är pixel för pixel lika motsvarande del av helsidan, att en tung sida kan avbrytas, att ett OCR-lager överlever sparning och blir sökbart. - **OCR-kvalitet mäts** som teckenfel mot facit, inte bedöms med ögat. - **UI-ändringar granskas med skärmbild.** Bygg in utvecklarhjälp: miljövariabler för fönsterstorlek, ett startläge (öppen meny, sökning, zoom) och "spara en skärmbild och avsluta", så att agenten kan granska gränssnittet utan att någon sitter vid skärmen. - **Verifieringskedja innan något är klart:** clippy utan varningar (även för Windows-målet), alla tester i release-läge, `cargo check` för varje målplattform. - **Klart betyder provkört.** Det som kräver Windows, en Mac eller en skrivare är inte klart förrän en människa kört det. --- ## 7. Arbetssätt - **Plan först.** Börja med en plan: teknikval med skäl, arkitektur, milstolpar (skelett och mätning → visning → läsfunktioner → sökning → utskrift → paketering → redigering). Mät i första milstolpen innan designen låses. - **Fråga om verkliga beslut, inte om sådant som går att avgöra själv.** När en premiss skaver – en motor som saknar tecknen språket kräver, en förenkling som tar bort halva arkitekturbehovet – säg det innan något byggs. - **Ärenden på en bräda.** Buggar och önskemål läggs som kort. Agenten läser brädan vid sessionsstart, kommenterar sin tolkning på otydliga kort, bygger, och skriver in vad som *mättes* på kortet. Ett kort stängs först när det är verifierat. - **Provkör i en riktig miljö.** Utvecklingsmiljön (t.ex. Linux/WSL) kan inte visa allt: minimerade fönster, skrivare, Windows förgrundsregler. Bygg ett installerbart paket för varje omgång och låt en människa prova. - **Kommentarer och dokumentation förklarar varför**, med de uppmätta siffrorna, så att nästa person inte gör om samma misstag. --- ## 8. Prompten ``` Bygg en snabb PDF-läsare för skrivbordet enligt IDEA.md, som ligger bifogad. Plattformar: [Windows och macOS]. Utvecklingsmiljö: [t.ex. Linux/WSL med korskompilering till Windows via cargo-xwin; macOS byggs på en Mac]. Gränssnittsspråk: [engelska]. Kommentarer och dokumentation: [svenska]. Versionshantering: [git/SVN]; checka inte in åt mig. Börja med att läsa IDEA.md i sin helhet. Skriv sedan en plan (docs/PLAN.md) med teknikval, arkitektur och milstolpar, och stäm av den med mig innan du bygger. Första milstolpen är ett skelett och ett fönsterlöst mätverktyg: mät biblioteksladdning, öppning av ett 500-sidigt dokument och rendering av en A4-sida innan något annat byggs. Regler som gäller hela vägen: - All PDFium-användning sker på en enda renderingstråd. Inga undantag. - FFI-signaturer läses ur headerfilerna för exakt den biblioteksversion som används. - Varje funktion verifieras med tester mot den riktiga motorn, och varje gränssnittsändring med en skärmbild. - Siffror i dokumentation och kommentarer ska vara uppmätta. - Fråga mig om verkliga beslut. Det som kräver hårdvara eller ett annat operativsystem än ditt markerar du som obevisat och bygger ett paket som jag kan provköra. [Lägg till eller ta bort funktioner här, t.ex. "OCR behövs inte" eller "lägg till sidoperationer: rotera, radera, flytta, slå ihop".] ```