Files
pipelines/app/notes/interface-font-choice.md
T
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

142 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.