Files
pipelines/app/notes/interface-font-choice.md
alan 081ae0957d Add font: own web file chooser, so a picked font is never dropped silently
file_picker's web picker treated the window regaining focus as a cancel when
the files arrived more than 500 ms later, so a real dialog could return an
empty pick and Add font did nothing. The web now uses its own file input that
completes only on change or cancel; mobile browsers get no accept filter.
Picker, check and save failures are shown in a dialog, and the row is busy
only after files were chosen.
2026-11-04 20:47:43 +00:00

7.9 KiB
Raw Permalink Blame History

Interface font choice (per device)

Settings > Font offers System default (the default everywhere: Roboto on Android and the web, SF in the iOS app), Inter, IBM Plex Sans, Source Sans 3 and Atkinson Hyperlegible Next. Each option is named in its own face.

  • lib/ui/theme/app_font.dart: the options, stable stored ids and assets.
  • lib/ui/theme/app_font_store.dart: shared_preferences key pipelines.next.font.v1, so the choice belongs to this device or browser and is never sent to the server.
  • lib/ui/theme/app_font_controller.dart: AppFontController.instance loads the chosen family with a FontLoader and only then switches the theme (one switch, no reflow loop). Startup waits up to 1.5 s for a stored font beside the session load, then draws in the system font and applies the font when it lands. A failed load keeps the current face and says so.
  • lib/ui/theme/app_theme.dart: appLightTheme/appDarkTheme({fontFamily}) and appCupertinoThemeWith({fontFamily}) replace only the family in every text role; sizes, weights and text scaling are unchanged. Explicit appMonospaceFamily (RobotoMono) styles are untouched.
  • MyApp and the onboarding host rebuild from the controller, so a choice applies immediately on Material and Cupertino hosts.
  • lib/ui/theme/app_font_licenses.dart: each fonts/<family>/OFL.txt is registered with LicenseRegistry. The app has no licence page of its own yet, so nothing shows them in the UI.

Web download cost

The families are plain assets:, not pubspec fonts: (the web engine fetches every fonts: family at boot). Browser resource log on the fixture build: startup fetches no optional font; opening Settings fetches each family's Regular weight for the previews (65–431 KB each); choosing one fetches its other three weights. A stored choice fetches only its four files at startup.

Build size (release web): main.dart.js 4,214,247 -> 4,232,251 bytes (+18 KB, +5 KB gzip); build/web 43.6 -> 48.0 MB because the four families' 16 TTFs (4.45 MB, 2.09 MB gzip) ship as on-demand assets. The APK grows by about the same compressed amount (not measured).

Known gaps

  • Chat markdown code blocks were already in the proportional UI face, not RobotoMono; they now follow the chosen font too.
  • On the web Cupertino fixture, "System default" names an unregistered CupertinoSystemText family, which the browser engine substitutes.

Fonts the user adds

Settings > Font ends with Add font…. It opens the host picker, then: natively file_picker (.ttf/.otf filter on Apple and desktop hosts, every file on Android, whose document picker filters by MIME type); on the web its own <input type=file> (custom_fonts/font_file_picker_web.dart), filtered to .ttf/.otf in desktop browsers and unfiltered in Android/iOS browsers, where font MIME mapping is inconsistent. Every failure after the pick (unreadable file, wrong type, picker, load or storage error) is said in a dialog; the row is busy only once files were chosen.

  1. CustomFontDraft.inspect refuses other extensions, files over 10 MB, more than 16 files at once, two files of the same weight and style, and a total over 40 MB of added fonts. Each file is read by custom_fonts/font_file_info.dart, a bounded pure-Dart sfnt reader: it rejects TTC collections, WOFF, damaged table directories and fonts without cmap/head/outlines, reads the family from the name table (ID 16, else ID 1; Windows English first) and the weight from OS/2.usWeightClass (400 when absent) plus the italic bit.
  2. A name dialog is prefilled from the font's family (else the file name) and lists each file's style; the user can rename it there or later.
  3. AppFontController.addCustom registers the bytes with a FontLoader under the new family first; only if that succeeds are the bytes and the index stored, and the font is chosen. A failure stores nothing. (The engine ignores undecodable bytes rather than throwing, so the structural check in step 1 is the real gate; the loader catches the rest.)

Rows for added fonts sit below the bundled ones, named in their own face, with their styles ("Regular, Bold") and an options button (Rename, Remove) beside the row, outside the tile's merged semantics. Remove asks first and deletes the files; if the font was chosen, the device returns to System default. The engine keeps a removed family registered until the next start, but nothing uses it.

The choice key is unchanged (pipelines.next.font.v1 now holds either a bundled id or custom-<id>). A stored added font loads at startup within the same bounded wait; missing bytes keep the system face and the picker says "Could not load this font."

Storage

  • Index: shared_preferences key pipelines.next.custom-fonts.v1, JSON of names, weights and byte keys (a few hundred bytes per font).
  • Native bytes: one file per face under the app support directory (custom-fonts/<key>), written to a .partial file and renamed. Support, not Documents: it is private (not in the iOS Files app) and leaves with the app.
  • Web bytes: IndexedDB database pipelines-custom-fonts via package:web. localStorage (which shared_preferences uses on the web) was rejected: browsers cap it at about 5 MB of UTF-16 text per origin, shared with every other preference, and base64 inflates a four-weight family to 1–2 MB, so a 15 MB cap could never be honoured and an overflow would break other settings. Cache Storage needs a secure context, which a plain http:// LAN address is not. IndexedDB stores binary values directly with a disk-sized quota; each write asks navigator.storage.persist() so the browser keeps the fonts under disk pressure (best effort).
  • Bytes are written before the index names them, and the index forgets a font before its bytes are deleted, so the index never names a partial font.

Evidence

Tests: test/ui/theme/custom_fonts/ (parser on the bundled fonts and damaged/hostile inputs; draft limits; library round trip with an in-memory byte store; native directory store on a temp dir; controller add, reject, rename, remove, restore, missing bytes, real FontLoader) and test/features/settings/settings_custom_font_test.dart (Material and Cupertino add/rename/remove, invalid file, cancel). The IndexedDB store has no VM test (it needs a browser); the browser run below covers it.

Browser (tool/capture/, new files= step answering the file chooser): the fixture app at 880x1400, Material and Cupertino, adding the bundled Atkinson Hyperlegible Next Regular and Bold as a user font named "My Atkinson". Shots: the name dialog prefilled "Atkinson Hyperlegible Next" with both styles; the added row chosen and the app redrawn in it; the same after a page reload (restored from IndexedDB); run 7 in the added face; the options menu and action sheet; rename to "Body face"; the remove confirmation; the fallback to System default; and a fake .ttf refused with "“fake.ttf” cannot be used: The file is too short." Android and iOS were not run on a device.

Fix: “Add font… does nothing” in the browser

file_picker's web picker (cancelUploadOnWindowBlur, on by default) treats the window regaining focus as a cancel unless the chosen files arrive within 500 ms. A real dialog returns focus before the browser delivers the files, so a slow delivery became an empty pick and the action returned silently. The capture kit's files= step answers the chooser without any focus change, which hid it. Reproduced on the release build (the installed web app and the fixture) in Chrome with a canvas mouse click (semantics off), Page.setInterceptFileChooserDialog + DOM.setFileInputFiles, and a window focus 700 ms before the files: the old build dropped the font; the new one shows the name dialog and adds it. Also checked: two files added and chosen, OFL.txt refused with a message, and a 560x1600 Android-UA touch run (no accept filter, name dialog shown). Safari/iOS and the Android app were not run on a device.