# IDEA.md – en egen fonthanterare för ett stort fontarkiv 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 Fontor, ett skrivbordsprogram för Windows och macOS byggt i Rust med Claude Code. ## 1. Vad som ska byggas Ett skrivbordsprogram som ger **överblick över ett stort fontarkiv** – några hundra till flera tusen filer i flera mappar – och de fonter som är installerade, och som låter användaren dela in fonterna på sitt eget sätt. Problemet: man vet inte vilka fonter som finns tillgängliga, vilka som är installerade, eller vilka som faktiskt kan skriva det man behöver. Färdiga fonthanterare låser kategorisering, taggar och vilken information som visas. Programmet ska kunna: - **Visa alla fonter i en lista** – arkivets och de installerade – med en valfri **provmening** i vald storlek (8–288 px), sök på namn eller familj, gruppering per familj och markering av flera. - **Visa status** för varje font: *Installed* (samma fil installerad), *Other version installed* (samma PostScript-namn, annan version eller fil), *Not installed* (bara i arkivet), *Installed only* (installerad men inte i arkivet). - **Markera saknade tecken** på provraden: "Missing 2: äö". - **Installera och avinstallera** från listan, per användare och utan administratörsrättigheter. Avinstallation flyttar filen till papperskorgen. Systemfonter rörs aldrig. - **Favoriter, grupper och projekt** i en sidopanel, med färg och egen ordning (dra för att flytta). Projekt exporteras och importeras som fil, och kan installeras i ett svep. - **Smarta grupper** som räknas fram vid skanningen ur vad fonten faktiskt kan skriva: Swedish (åäö), Caps Only, Monospace, Symbols, Cyrillic, Greek, Variable. De går inte att redigera, och tomma grupper visas inte. - **Taggar på varje rad**: fontens grupper, projekt och smarta grupper. Det som inte får plats blir "+N", och smarta grupper viker först. - **Arkivmappar** i sidopanelen med antal, och en vy per mapp (undermappar inräknade). - **En detaljpanel** med fyra flikar: familjens stilar, ett provark i fallande storlek, alla tecken fonten kan rita (klick kopierar) och fontfilens metadata. Format: `.ttf .otf .ttc .otc`; varje ansikte i en samling blir en egen rad. Ingår **inte**: WOFF/WOFF2 (går inte att installera på skrivbordet), reglage för variabla axlar, aktivering utan installation, systemvid installation, delade bibliotek. **Under utveckling, valfritt**: automatisk stilklassning (Basic, Display, Script, Icons, Techno, Fancy) ur fonternas former – se avsnitt 3. ## 2. Stack och arkitektur Det som är **viktigt** är markerat; resten går att byta. - **Rust** (edition 2024), en Cargo-workspace med en UI-fri kärna och ett fönsterprogram. - **Viktigt: `swash`** för att läsa metadata, forma text (kerning, ligaturer) och rastrera till alfamask – i en crate, utan C-beroenden, så korskompilering till Windows fungerar. - **Viktigt: egen rastrering till texturer.** Lägg *inte* in arkivets fonter i GUI-ramverkets fontsystem (i egui `FontDefinitions`): varje tillagd font bygger om hela teckenatlasen. Rita i stället provraderna på en arbetstråd till alfamasker, ladda upp dem som texturer och cacha dem i en LRU med nyckeln (font-id, storlek, texthash, skalfaktor). - **En arbetstråd med prioritetskö**: synliga rader går först, och jobb för rader man scrollat förbi avbryts. - **eframe/egui** (0.36) med wgpu för fönstret, en virtualiserad lista. Går att byta. - **Lagring**: `serde` + `toml` för biblioteket (favoriter, grupper, projekt) och inställningarna, en indexcache (JSON) för skanningen. Filerna skrivs atomiskt (temporär fil + rename). Ingen databas behövs. - **Fonter refereras med PostScript-namn + sha256**, så att en referens överlever att filen flyttas i arkivet. - **Windows-API** (`windows`-crate): registret, `AddFontResourceW`, `WM_FONTCHANGE`, papperskorgen. - **Menyn som data**, egui i fönstret på Windows och systemets menyrad på macOS, med tangentgenvägar från en enda källa. - Paketering: Windows korskompilerat med `cargo xwin` från WSL, NSIS-installerare och portabel zip; macOS `aarch64-apple-darwin`, `.app` och dmg. Kärnans moduler: skanning, ansiktsmetadata, installerade fonter per plattform, statusmatchning, bibliotek, installation, rastrering, teckentäckning, tabellkatalogens reparation och felfångst. ## 3. Beslut som visade sig avgörande **Skanna inkrementellt.** Gå rekursivt igenom arkivmapparna och de installerade katalogerna. Filer med oförändrad storlek och ändringstid återanvänds ur indexcachen; bara nya och ändrade filer läses. Skanningen körs på en egen tråd och rapporterar framsteg. **Installerade fonter per plattform**: - Windows: `%WINDIR%\Fonts`, `%LOCALAPPDATA%\Microsoft\Windows\Fonts` och värdena under `HKLM` och `HKCU\Software\Microsoft\Windows NT\CurrentVersion\Fonts`, som kan peka ut filer på andra ställen. - macOS: `/System/Library/Fonts` (och `Supplemental`), `/Library/Fonts`, `~/Library/Fonts`. Dölj systemfonter vars familjenamn börjar med punkt. **Statusmatchning**: samma sha256 = Installed; samma PostScript-namn men annan fil = Other version installed; bara i arkivet = Not installed; bara installerad = Installed only. En font som finns i flera arkivmappar är en rad – men raden ska komma ihåg *alla* kopiorna och räknas till varje mapp där någon ligger. **Installation per användare**: - Windows: kopiera filen till `%LOCALAPPDATA%\Microsoft\Windows\Fonts`, skriv `HKCU`-värdet `" (TrueType|OpenType)"`, anropa `AddFontResourceW` och skicka `WM_FONTCHANGE` med `SendMessageTimeoutW(HWND_BROADCAST …)`. Avinstallation i omvänd ordning, filen till papperskorgen. En låst fil rapporteras som fel och lämnas kvar. - macOS: kopiera till `~/Library/Fonts`, ta bort vid avinstallation. - Bara fonter som installerats per användare kan avinstalleras. En fil utanför användarens fontkatalog avregistreras men tas aldrig bort – den kan vara den enda kopian. Installera inte en annan version bredvid en installerad font med samma namn: då väljer programmen på måfå. **Teckentäckning ur former, inte ur metadata.** Stilklassen i fontfilen (OS/2 `sFamilyClass`, PANOSE) är tom eller fel i nästan alla fonter i ett verkligt arkiv. Räkna i stället ut vad fonten kan skriva ur teckentabellen *och* konturerna: ett tecken räknas som saknat om teckentabellen saknar det **eller** om dess glyf saknar kontur (och tecknet inte är ett blanksteg). Glyfer som bara finns som bitmapp räknas inte som tomma. Använd **samma regel** för markeringen på provraden och för de smarta grupperna, så att de aldrig säger olika saker. Symbolkodade teckentabeller med vanliga bokstäver (äldre Fontographer-fonter) måste också hanteras. **En trasig font får aldrig fälla programmet.** Fånga panik per fil, per glyf och per provrad, och bygg inte med `panic = "abort"`. En font som inte går att läsa blir en rad med ett fel. **Reparera osorterade tabellkataloger.** Fontläsare binärsöker tabellkatalogen. En osorterad katalog gör att tabeller som `maxp` inte hittas – fonten får noll glyfer, alla glyfer ritas ovanpå varandra och namnet försvinner. Sortera katalogen i en kopia innan filen läses. **Detaljpanelens data på en egen tråd.** Tecken och metadata läses ur filen när panelen byter font; de största CJK-fonterna (cirka 30 000 tecken) tar över 100 ms. **Automatisk stilklassning (under utveckling).** En undersökning av 462 fonter med 15 formmått på glyfer rastrerade i 96 px – igenkänning mot ett referensalfabet, likhet med samma bokstav, x-höjd, raka kanter, fyllnad, lutning, bredd, delar per glyf, kontrast – gav mot en handklassning 62 % rätt med sex klasser och 87 % med tre (Basic, Icons, övrigt). Basic (96 % täckning, 85 % precision) kan bli en smart grupp; resten bör vara förslag som användaren bekräftar, så att varje bekräftelse blir ett nytt exempel. Kontrast, vikt och grovhet skiljer nästan inte alls. **Utvecklarhjälp från dag ett**: - `_DATA_DIR=dir` – bibliotek och inställningar åt sidan - `_CATALOG=mapp` – en arkivmapp för utveckling, som skannas men inte sparas - `_WINDOW=1100x700@X,Y`, `_SCREENSHOT=fil.ppm`, `_SCREENSHOT_DELAY=N` - `_DEBUG_STATE=…` – `size=`, `sample=`, `search=`, `jump=Familj`, `collapse=`, `tab=styles|text|characters|meta`, `nosidebar`, `flat`, och steg som körs genom samma `apply` som menyn: `select=Prefix`, `do=favorite|newgroup|newproject|copy|selectall|install|uninstall|details`, `view=favorites|installed|catalog|notinstalled|group|project|folder|smart:swedish` - `_DEBUG_MENU=Font` ## 4. Fallgropar - **Lita inte på fontfilens stilklass eller teckentabell ensam.** Se avsnitt 3: räkna konturer, annars ritar provraden hål utan varning. - **Bygg inte med `panic = "abort"`.** En enda trasig fil i ett arkiv på tusentals stängde hela programmet direkt efter "Loading fonts". - **Anta inte att tabellkatalogen är sorterad.** 46 av 6 677 filer i ett verkligt arkiv hade osorterad katalog, och 27 av dem fick läsaren att krascha. - **Kom ihåg alla kopior av en fil.** När samma fil finns i flera mappar och raden bara minns den första, visar en mapp med 699 fonter 0. - **Lägg inga fristående installationsprogram i exemplen.** Windows Defender stoppade ett litet program som bara skrev fontregistret och anropade `AddFontResourceW` redan vid kopieringen. Hela appen med samma kod gick igenom. Prova installationen genom appen. (En osignerad binär kan få samma behandling hos användare – ett skäl att signera.) - **Mät installationen med GDI (`EnumFontFamiliesExW`), inte med .NET:s `InstalledFontCollection`.** GDI+ har en egen fontcache som fortsätter visa en avinstallerad font. - **Lägg inte fonterna i GUI-ramverkets fontatlas** (se avsnitt 2). - **Dölj macOS dolda systemfonter** (familjenamn som börjar med punkt), annars hamnar de överst i listan. - **Formatera genvägar för plattformen**: på macOS ska menyn visa ⌘D, inte "Cmd+D". - **`cargo fmt` formaterar om hela crate:n**, inte bara de filer du rört. ## 5. Krav och mått Riktmärken från Fontor: | Vad | Värde | |---|---| | Skanning, testarkiv + `C:\Windows\Fonts` (687 filer) på Windows, kallt | 61 ms, med teckentäckning 66–68 ms | | Samma med indexcache | 5,7 ms | | Skanning av ett verkligt arkiv (6 973 filer) på Windows | 259 ms kallt, 43 ms med cache | | Rastrering av en provrad i appen på Windows | 0,6–0,9 ms i snitt, max 5 ms | | Hela testarkivet (391 fonter) rastrerat | 0,17 s, 0,43 ms per font | | Första bildrutan / listan fylld på Windows | ~470 ms / ~520 ms | | Detaljpanelens tecken och metadata | 6,4 ms per ansikte; 115–120 ms för de största CJK-fonterna | | Programfilen / installerare / portabel zip | 10,4 MB / 5,5 MB / 5,2 MB | | Testarkivets fonter som saknar å, ä eller ö | 253 av 391 enligt teckentabellen, 281 när tomma glyfer räknas | ## 6. Så verifieras det - `cargo clippy --workspace --all-targets` utan varningar, `cargo test --workspace --release`, `cargo check --target` för den andra plattformen. Kärnans tester ska också gå att köra på Windows. - **Tester i kärnan** mot ett incheckat testarkiv med fria fonter (även en `.ttc` och en variabel font) och en mapp med trasiga filer: skanning, metadata, samlingar, statusmatchning, kopior i flera mappar, bibliotek fram och tillbaka, rastrering, tomma glyfer räknas som saknade, osorterad tabellkatalog. - **Mät skanning och rastrering utan fönster** med exempelprogram, och logga tid till första bildrutan och ifylld lista. - **Installationen på Windows**: läs `HKCU\…\Fonts` före och efter, kontrollera filen i användarens fontkatalog och statusen efter omskanning, avinstallera och kontrollera att allt är borta – genom appen, mätt med GDI. - **Gränssnittet granskas med skärmbilder** från den riktiga binären, med en egen datakatalog och testarkivet, så att användarens riktiga mappar inte syns. - macOS provas på riktig hårdvara, med en checklista. ## 7. Arbetssätt - **Plan först**: teknikval, katalogstruktur, kärnans moduler, gränssnittet och milstolpar (skelett, index, provlista, bibliotek, installation, paketering). Fråga om de verkliga besluten: per användare eller systemvid installation, lokalt eller delat bibliotek, hur stort arkivet är. - **Undersök innan du bygger det osäkra**: stilklassningen skrevs först som en undersökning med mätningar och en handklassad delmängd; först sedan beslutas vad som ska byggas. - **Ett ärende i taget**, med mätningen i avslutskommentaren. - **Prova mot användarens riktiga arkiv** (en kopia av inställningarna, datakatalogen åt sidan) – testarkivet räckte inte för att hitta de trasiga filerna. ## 8. Prompten > Bygg ett skrivbordsprogram för [Windows och macOS] i [Rust med eframe/egui och swash] som visar alla fonter i mitt fontarkiv och alla installerade fonter i en lista med en valfri provmening i vald storlek, visar status (installerad, annan version, inte installerad, bara installerad), markerar saknade tecken, installerar och avinstallerar per användare, och låter mig ordna fonterna i favoriter, grupper, projekt och smarta grupper som räknas fram ur vad fonterna kan skriva. > > Mitt arkiv ligger i [mappar] och har ungefär [antal] filer. > > Läs hela IDEA.md nedan först. Den beskriver funktionerna, arkitekturen, de beslut som visade sig avgörande och fallgroparna att undvika. > > Arbeta så här: > 1. Skriv en plan med milstolpar och fråga mig om de verkliga besluten. > 2. Bygg kärnan utan gränssnitt först – skanning, status, teckentäckning, rastrering – med tester mot ett testarkiv med fria fonter och några trasiga filer. > 3. Rita provraderna själv till texturer på en arbetstråd; lägg inte fonterna i ramverkets fontatlas. > 4. En trasig font får aldrig fälla programmet. > 5. Bygg utvecklarhjälpen tidigt och granska varje gränssnittsändring med en skärmbild från den riktiga binären. Mät skanning och rastrering och redovisa siffrorna. > 6. Prova mot mitt riktiga arkiv innan något kallas klart. > > Smarta grupper jag vill ha: [Swedish (åäö), Caps Only, Monospace, Symbols, …]. > > [klistra in IDEA.md här]