# IDEA.md – a font manager of your own for a large font archive 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 Fontor, a desktop program for Windows and macOS written in Rust with Claude Code. ## 1. What to build A desktop program that gives **an overview of a large font archive** – a few hundred to several thousand files across several folders – and of the installed fonts, and lets the user organize the fonts their own way. The problem: you don't know which fonts are available, which are installed, or which can actually write what you need. Ready-made font managers lock down categorization, tagging and what information is shown. The program must be able to: - **Show every font in a list** – the archive's and the installed ones – with a custom **sample sentence** at a chosen size (8–288 px), search by name or family, grouping by family and multi-select. - **Show a status** for every font: *Installed* (the same file installed), *Other version installed* (same PostScript name, different version or file), *Not installed* (archive only), *Installed only* (installed but not in the archive). - **Flag missing characters** on the sample row: "Missing 2: äö". - **Install and uninstall** from the list, per user and without administrator rights. Uninstalling moves the file to the recycle bin. System fonts are never touched. - **Favorites, groups and projects** in a sidebar, with colors and their own order (drag to move). Projects are exported and imported as a file and can be installed in one go. - **Smart groups** computed during the scan from what the font can actually write: Swedish (åäö), Caps Only, Monospace, Symbols, Cyrillic, Greek, Variable. They can't be edited, and empty groups aren't shown. - **Tags on every row**: the font's groups, projects and smart groups. What doesn't fit becomes "+N", and smart groups give way first. - **Archive folders** in the sidebar with counts, and a view per folder (subfolders included). - **A details panel** with four tabs: the family's styles, a sample sheet in decreasing sizes, every character the font can draw (click to copy) and the font file's metadata. Formats: `.ttf .otf .ttc .otc`; each face in a collection becomes its own row. **Not** included: WOFF/WOFF2 (can't be installed on the desktop), sliders for variable axes, activation without installing, system-wide installation, shared libraries. **In development, optional**: automatic style classification (Basic, Display, Script, Icons, Techno, Fancy) from the fonts' shapes – see section 3. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **Rust** (edition 2024), a Cargo workspace with a UI-free core and a window program. - **Important: `swash`** to read metadata, shape text (kerning, ligatures) and rasterize to alpha masks – in one crate, with no C dependencies, so cross-compiling to Windows works. - **Important: rasterize to textures yourself.** Do *not* add the archive's fonts to the GUI framework's font system (in egui, `FontDefinitions`): every added font rebuilds the whole glyph atlas. Instead, draw the sample rows on a worker thread into alpha masks, upload them as textures and cache them in an LRU keyed on (font id, size, text hash, scale factor). - **A worker thread with a priority queue**: visible rows go first, and jobs for rows scrolled past are cancelled. - **eframe/egui** (0.36) with wgpu for the window, a virtualized list. Can be swapped. - **Storage**: `serde` + `toml` for the library (favorites, groups, projects) and settings, an index cache (JSON) for the scan. Files are written atomically (temporary file + rename). No database needed. - **Fonts are referenced by PostScript name + sha256**, so a reference survives the file moving within the archive. - **Windows APIs** (`windows` crate): the registry, `AddFontResourceW`, `WM_FONTCHANGE`, the recycle bin. - **The menu as data**, egui in the window on Windows and the system menu bar on macOS, with keyboard shortcuts from a single source. - Packaging: Windows cross-compiled with `cargo xwin` from WSL, an NSIS installer and a portable zip; macOS `aarch64-apple-darwin`, `.app` and dmg. The core's modules: scanning, face metadata, installed fonts per platform, status matching, library, installation, rasterization, character coverage, table-directory repair and panic guarding. ## 3. Decisions that turned out to matter **Scan incrementally.** Walk the archive folders and the installed directories recursively. Files with unchanged size and modification time are reused from the index cache; only new and changed files are read. The scan runs on its own thread and reports progress. **Installed fonts per platform**: - Windows: `%WINDIR%\Fonts`, `%LOCALAPPDATA%\Microsoft\Windows\Fonts` and the values under `HKLM` and `HKCU\Software\Microsoft\Windows NT\CurrentVersion\Fonts`, which can point to files elsewhere. - macOS: `/System/Library/Fonts` (and `Supplemental`), `/Library/Fonts`, `~/Library/Fonts`. Hide system fonts whose family name starts with a dot. **Status matching**: same sha256 = Installed; same PostScript name but a different file = Other version installed; archive only = Not installed; installed only = Installed only. A font that exists in several archive folders is one row – but the row must remember *all* its copies and count towards every folder where one lives. **Per-user installation**: - Windows: copy the file to `%LOCALAPPDATA%\Microsoft\Windows\Fonts`, write the `HKCU` value `" (TrueType|OpenType)"`, call `AddFontResourceW` and send `WM_FONTCHANGE` with `SendMessageTimeoutW(HWND_BROADCAST …)`. Uninstall in reverse, the file to the recycle bin. A locked file is reported as an error and left in place. - macOS: copy to `~/Library/Fonts`, remove on uninstall. - Only fonts installed per user can be uninstalled. A file outside the user's font directory is unregistered but never deleted – it may be the only copy. Don't install a different version next to an installed font with the same name: programs then pick one at random. **Character coverage from shapes, not metadata.** The style class in the font file (OS/2 `sFamilyClass`, PANOSE) is empty or wrong in almost every font in a real archive. Instead, work out what the font can write from the character map *and* the outlines: a character counts as missing if the character map lacks it **or** its glyph has no outline (and the character isn't whitespace). Bitmap-only glyphs don't count as empty. Use **the same rule** for the flag on the sample row and for the smart groups, so they never disagree. Symbol-encoded character maps with ordinary letters (older Fontographer fonts) must also be handled. **A broken font must never bring the program down.** Catch panics per file, per glyph and per sample row, and don't build with `panic = "abort"`. A font that can't be read becomes a row with an error. **Repair unsorted table directories.** Font readers binary-search the table directory. An unsorted directory means tables like `maxp` aren't found – the font gets zero glyphs, all glyphs are drawn on top of each other and the name disappears. Sort the directory in a copy before reading the file. **The details panel's data on its own thread.** Characters and metadata are read from the file when the panel switches font; the largest CJK fonts (around 30,000 characters) take over 100 ms. **Automatic style classification (in development).** A study of 462 fonts with 15 shape measures on glyphs rasterized at 96 px – recognition against a reference alphabet, similarity to the same letter, x-height, straight edges, fill, slant, width, parts per glyph, contrast – gave, against a hand classification, 62 % correct with six classes and 87 % with three (Basic, Icons, other). Basic (96 % coverage, 85 % precision) can become a smart group; the rest should be suggestions the user confirms, so every confirmation becomes a new example. Contrast, weight and roughness hardly separate the classes at all. **Developer hooks from day one**: - `_DATA_DIR=dir` – library and settings out of the way - `_CATALOG=folder` – an archive folder for development, scanned but not saved - `_WINDOW=1100x700@X,Y`, `_SCREENSHOT=file.ppm`, `_SCREENSHOT_DELAY=N` - `_DEBUG_STATE=…` – `size=`, `sample=`, `search=`, `jump=Family`, `collapse=`, `tab=styles|text|characters|meta`, `nosidebar`, `flat`, and steps that run through the same `apply` as the menu: `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. Pitfalls - **Don't trust the font file's style class or character map alone.** See section 3: count outlines, or the sample row shows holes without a warning. - **Don't build with `panic = "abort"`.** A single broken file in an archive of thousands closed the whole program right after "Loading fonts". - **Don't assume the table directory is sorted.** 46 of 6,677 files in a real archive had an unsorted directory, and 27 of them made the reader crash. - **Remember every copy of a file.** When the same file exists in several folders and the row only remembers the first, a folder with 699 fonts shows 0. - **Don't put stand-alone installer programs in the examples.** Windows Defender stopped a small program that only wrote the font registry and called `AddFontResourceW` as soon as it was copied. The whole app with the same code got through. Test installation through the app. (An unsigned binary may get the same treatment on users' machines – a reason to sign.) - **Measure installation with GDI (`EnumFontFamiliesExW`), not .NET's `InstalledFontCollection`.** GDI+ has its own font cache that keeps showing an uninstalled font. - **Don't put the fonts in the GUI framework's font atlas** (see section 2). - **Hide macOS's hidden system fonts** (family names starting with a dot), or they end up at the top of the list. - **Format shortcuts for the platform**: on macOS the menu should show ⌘D, not "Cmd+D". - **`cargo fmt` reformats the whole crate**, not just the files you touched. ## 5. Requirements and measurements Benchmarks from Fontor: | What | Value | |---|---| | Scan, test archive + `C:\Windows\Fonts` (687 files) on Windows, cold | 61 ms, with character coverage 66–68 ms | | Same with the index cache | 5.7 ms | | Scan of a real archive (6,973 files) on Windows | 259 ms cold, 43 ms with the cache | | Rasterizing a sample row in the app on Windows | 0.6–0.9 ms on average, 5 ms max | | The whole test archive (391 fonts) rasterized | 0.17 s, 0.43 ms per font | | First frame / list filled on Windows | ~470 ms / ~520 ms | | Details panel characters and metadata | 6.4 ms per face; 115–120 ms for the largest CJK fonts | | Executable / installer / portable zip | 10.4 MB / 5.5 MB / 5.2 MB | | Test-archive fonts missing å, ä or ö | 253 of 391 by the character map, 281 when empty glyphs count | ## 6. How it's verified - `cargo clippy --workspace --all-targets` with no warnings, `cargo test --workspace --release`, `cargo check --target` for the other platform. The core's tests must also run on Windows. - **Tests in the core** against a checked-in test archive of free fonts (including a `.ttc` and a variable font) and a folder of broken files: scanning, metadata, collections, status matching, copies in several folders, the library round-tripped, rasterization, empty glyphs counted as missing, an unsorted table directory. - **Measure scanning and rasterization without a window** with example programs, and log the time to the first frame and to a filled list. - **Installation on Windows**: read `HKCU\…\Fonts` before and after, check the file in the user's font directory and the status after a rescan, uninstall and check everything is gone – through the app, measured with GDI. - **The interface is reviewed with screenshots** from the real binary, with a separate data directory and the test archive, so the user's real folders don't show. - macOS is tried on real hardware, with a checklist. ## 7. Way of working - **Plan first**: technology choices, directory structure, the core's modules, the interface and milestones (skeleton, index, sample list, library, installation, packaging). Ask about the real decisions: per-user or system-wide installation, local or shared library, how big the archive is. - **Investigate before building the uncertain parts**: the style classification was first written up as a study with measurements and a hand-classified subset; only then is it decided what to build. - **One task at a time**, with the measurement in the closing comment. - **Try it against the user's real archive** (a copy of the settings, the data directory out of the way) – the test archive wasn't enough to find the broken files. ## 8. The prompt > Build a desktop program for [Windows and macOS] in [Rust with eframe/egui and swash] that shows every font in my font archive and every installed font in a list with a custom sample sentence at a chosen size, shows a status (installed, other version, not installed, installed only), flags missing characters, installs and uninstalls per user, and lets me organize the fonts into favorites, groups, projects and smart groups computed from what the fonts can write. > > My archive is in [folders] and has about [number] files. > > Read all of IDEA.md below first. It describes the features, the architecture, the decisions that turned out to matter and the pitfalls to avoid. > > Work like this: > 1. Write a plan with milestones and ask me about the real decisions. > 2. Build the core without an interface first – scanning, status, character coverage, rasterization – with tests against a test archive of free fonts and a few broken files. > 3. Draw the sample rows yourself into textures on a worker thread; don't put the fonts in the framework's font atlas. > 4. A broken font must never bring the program down. > 5. Build the developer hooks early and review every interface change with a screenshot from the real binary. Measure scanning and rasterization and report the numbers. > 6. Try it against my real archive before calling anything done. > > Smart groups I want: [Swedish (åäö), Caps Only, Monospace, Symbols, …]. > > [paste IDEA.md here]