fix(web): validate monospace fonts on pick instead of scanning the catalog

[eggfriedrice24]

What Changed

• The code and terminal font pickers no longer classify every installed family up front. They list the full catalog, like the interface picker already does, and probe only the family the user picks.
• A proportional pick does not commit: an error toast explains why and the current font is kept. The Default option commits unchecked.
• isMonospaceFamily verdicts (pass and fail) are cached per normalized family list, shared by the picker, the typed input fallback, and the terminal surface, so remounts (toggling Advanced typography, reopening Appearance) never re-probe.

Why

Opening Settings > Appearance in the desktop app silently grants local font access and enumerates every installed family; each monospace picker then ran up to 32 synchronous canvas measureText calls per family during render. That loop scales with the installed catalog: with 710 families the Electron renderer froze for over five minutes, and fontconfig catalogs in the thousands fare worse. Batching the scan (#5642) still froze Electron in its author's own testing, because the total work is unchanged. Validating only the picked family bounds every interaction to at most one probe, which #5656 lists as the smallest viable approach. Builds on the diagnosis by @alex73630 in #5642 and supersedes its batching approach.

Fixes #5656

Verification:

• vp test run --project unit src/appearanceFonts.test.ts: 18 passed, 3 new for the verdict cache; targeted typecheck, lint, and format checks.
• Web client smoke test with a 1,866 family catalog: Appearance opens instantly, the picker upgrades in under a second with a single 100 ms main thread task, a monospace pick (Cartograph CF) commits and updates --font-mono, a proportional pick (DejaVu Sans) is rejected with the toast and the previous font is kept.
• Not yet verified separately in the Electron desktop client.

UI Changes

The monospace pickers now list all installed families, and a rejected proportional pick shows an error toast ("X" isn't monospace / Code and terminal need a fixed-width font, so the current font was kept). Happy to add screenshots on request.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Model: Claude Fable 5. Harness: Claude Code in T3 Code.

🤖 Generated with Claude Code

---

Note

Low Risk
Performance and validation-timing change in appearance settings only; monospace enforcement remains on pick/commit with fail-open canvas behavior unchanged.

Overview
Fixes Appearance settings freezing when large font catalogs are installed by stopping upfront monospace classification of every enumerated family in code/terminal pickers. Those pickers now list the full installed catalog (like the interface picker) and run one cached canvas probe only when the user picks a family.

Adds createCachedFamilyProbe so isMonospaceFamily shares normalized family-list verdicts across the picker, typed-input validation, and terminal surfaces. Verdicts are stored only after every name in the stack resolves via familiesResolve, so late-loading faces can be re-probed instead of locking in a fallback measurement.

When requireMonospace is on, a proportional pick does not commit—an error toast explains the rejection and the current font is kept; Default still commits without probing.

^{Reviewed by Cursor Bugbot for commit 40b0c40. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Validate monospace fonts on pick in FontFamilyPicker instead of scanning catalog

• The picker no longer hides non-monospace families from the list. It now shows all installed families and validates on selection.
• Adds createCachedFamilyProbe and familiesResolve to appearanceFonts.ts to cache probe results by normalized family list, deferring the cache until all families resolve.
• Behavioral Change: Selecting a proportional face when requireMonospace is true shows an error toast and rejects the selection.

^{Macroscope summarized 40b0c40.}

Summary by CodeRabbit

• New Features

  • Font pickers now display all installed font families, including those that may not be monospace.
  • Monospace-required selections are validated when chosen, with an error message shown for unsupported fonts.

• Bug Fixes

  • Improved font detection for family lists, quoted names, whitespace variations, and fonts that resolve asynchronously.
  • Font availability checks now wait for all specified families before finalizing a result.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 4ecc93fe-981b-4788-b211-cf5a9b31fcb5

📥 Commits

Reviewing files that changed from the base of the PR and between 7a00e58 and 9113a4b.

📒 Files selected for processing (1)

• apps/web/src/components/settings/FontFamilyPicker.tsx

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The font utilities now cache resolved family probe results. FontFamilyPicker displays all installed families and validates monospace requirements only after selection. Invalid selections show an error toast and are not committed.

Changes

Font validation flow

Layer / File(s)	Summary
Family resolution and probe caching apps/web/src/appearanceFonts.ts, apps/web/src/appearanceFonts.test.ts	Family lists use shared resolution and cached probe verdicts. Unresolved lists are re-probed. Tests cover normalization, deferred caching, multi-family resolution, and empty input.
Selection-time monospace validation apps/web/src/components/settings/FontFamilyPicker.tsx	The picker retains the complete installed-font catalog and validates selected families when monospace enforcement is enabled. Invalid selections show an error toast and do not call onSelect.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant FontFamilyPicker
  participant isMonospaceFamily
  participant Canvas
  participant toastManager
  FontFamilyPicker->>isMonospaceFamily: validate selected family
  isMonospaceFamily->>Canvas: measure glyph advances
  Canvas-->>isMonospaceFamily: return measurements
  isMonospaceFamily-->>FontFamilyPicker: return verdict
  FontFamilyPicker->>toastManager: show error for proportional family

Loading

Suggested reviewers: alex73630

Merge Risk: ⚪ Minimal · up to 9113a

The picker now shows all installed font families while validating monospace compatibility only when selected, preserving the current font for invalid choices. No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	The implementation matches the main coding objectives in #5656. FontFamilyPicker lists the complete enumerated catalog and calls isMonospaceFamily only for a selected non-default value. Rejected v…	Provide repository evidence that existing focused tests cover the remaining #5656 behaviors, or add those tests if that coverage is absent.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: monospace validation occurs when a font is selected instead of during catalog scanning.
Description check	✅ Passed	The description includes the required What Changed, Why, UI Changes, and Checklist sections. It explains the performance problem, implementation, validation behavior, testing, and user-facing impact. …
Out of Scope Changes check	✅ Passed	The reviewed changes are limited to font-family resolution, monospace verdict caching, picker selection behavior, and related tests. These changes directly support #5656.

Full details: Linked Issues check

Explanation

The implementation matches the main coding objectives in #5656. FontFamilyPicker lists the complete enumerated catalog and calls isMonospaceFamily only for a selected non-default value. Rejected values do not call onSelect, and the default path commits without probing. createCachedFamilyProbe normalizes family lists, caches resolved verdicts, and leaves unresolved verdicts uncached. The added tests cover cache normalization, unresolved families, multi-family resolution, and empty input. The available PR evidence does not establish focused coverage for proportional-selection rejection, manual-input fallback, default non-probing, or the absence of probing during open, search, scroll, and highlight interactions.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes the existing code and terminal font-selection workflow: the full catalog is now shown, picks trigger synchronous validation and toast rejection, and cached verdicts are shared with typed input and terminal rechecks. Although the catalog-wide freeze is addressed and default font values remain unchanged, the cross-surface runtime and user-facing behavior warrants human review.

No code changes detected at 9113a4b. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

[macroscopeapp]

One finding: the new page-lifetime verdict cache in appearanceFonts.ts silently disables the post-load monospace re-validation that terminal/ghostty/surface.ts depends on. Details inline. The FontFamilyPicker changes themselves (full catalog + bounded probe on pick, stackedThreadToast for the rejection) match the existing toast and combobox conventions.

^{Posted via Macroscope — UI Consistency}

[eggfriedrice24]

Hi @juliusmarminge @maria-rcks, apologies for tagging you directly, I know you have a lot on your plates. Flagging this because it is actively disrupting our team: accidentally opening the Appearance settings freezes the app and forces a full close and reopen. This PR fixes that by validating monospace fonts on pick instead of scanning the whole catalog. Branch is freshly updated with main and checks are green. A review whenever you can spare a moment would mean a lot.

[eggfriedrice24]

Rebased on main after the conflict from #8738 (test import block only). Addressed the Macroscope finding on the verdict cache in b4b2fea. CI green, approved by @alex73630, ready to merge.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 8a57cd2. Configure here.}

Dismissing prior approval to re-evaluate 40b0c40