Skip to content

feat(terminal): add configurable fallback font stacks - #8428

Open
mmarabel wants to merge 4 commits into
stablyai:mainfrom
mmarabel:gatsby74/feature-allow-custom-terminal-font-fallback-stac
Open

mmarabel wants to merge 4 commits into
stablyai:mainfrom
mmarabel:gatsby74/feature-allow-custom-terminal-font-fallback-stac

Conversation

@mmarabel

@mmarabel mmarabel commented Jul 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes #8367.

Adds an ordered Fallback Fonts setting under Settings → Terminal → Terminal Typography so multilingual terminal glyphs resolve predictably:

Primary font → user-defined fallbacks → Orca defaults

  • Add, edit, remove, and reorder fallback families using Orca's installed-font autocomplete.
  • Apply changes immediately to mounted terminal panes and the settings preview, and use them for newly created panes.
  • Preserve Orca's existing cross-platform and Nerd Font fallback chain when the custom list is empty or a configured font is unavailable.
  • Normalize persisted and IPC-provided stacks by trimming, dropping invalid/empty entries, case-insensitively deduplicating, and bounding the list to 32 families.
  • Import repeated Ghostty font-family entries as primary + ordered fallbacks.
  • Add localized Settings/search copy for English, Spanish, Japanese, Korean, and Chinese.

Screenshots

Settings UI changed. Screenshots are not attached from this CLI-only run; the new control is covered by focused component tests for add, edit, focus retention, reorder, remove, duplicate rejection, and the 32-font boundary.

Testing

  • pnpm lint — full-repo lint not rerun; changed-file oxlint, React Doctor lint from the pre-commit hook, localization gates, max-lines ratchet, and git diff --check passed
  • pnpm typecheck
  • pnpm test — focused suites passed: 510 tests across 9 files; the full suite was not completed under the local unsupported Node 26 runtime
  • pnpm build
  • Added or updated high-quality tests that would catch regressions, or explained why tests were not needed

Focused coverage includes:

  • font-stack order, CSS quoting, exact-family deduplication, and the trailing unquoted monospace fallback;
  • persistence-load and renderer IPC normalization;
  • mounted-pane live updates, preview wiring, and new-pane construction;
  • fallback-list add/edit/blur/Enter behavior, focus retention, reorder/remove, duplicate rejection, and max length;
  • repeated Ghostty font-family mapping.

AI Review Report

Implemented and reviewed with orchestrated AI agents, including a Claude Opus architecture review and an independent Codex diff/UX review.

The reviews explicitly checked:

  • macOS/Linux/Windows: the stack retains Orca's existing SF Mono/Menlo, Cascadia/Consolas, DejaVu/Liberation, Nerd Font, and generic fallback behavior. No shortcut, shortcut-label, path, shell, or Electron platform branch changed.
  • Local/SSH/remote: fallback selection is renderer presentation state applied to the same xterm options for local, WSL, SSH, and paired-runtime panes; it makes no host-font assumption beyond normal browser font availability.
  • Lifecycle coverage: existing panes, new panes, and the terminal preview all consume the same ordered setting.
  • Accessibility/UX: installed-font autocomplete is reused; controls have accessible names, keyboard-operable move/remove actions, stable focus while editing, explicit duplicate handling, and a visible maximum-state message.
  • Compatibility: old profiles backfill to [], preserving the previous effective font stack byte-for-byte when no custom fallbacks are configured.

The independent review flagged and we fixed:

  1. value-derived row keys and per-keystroke persistence could remount the autocomplete and drop focus;
  2. clearing an edit could accidentally remove the row;
  3. substring-based default dedup could suppress distinct families such as Menlo Extra;
  4. a quoted user monospace could suppress the required trailing CSS generic;
  5. the 32-entry cap needed visible UI feedback;
  6. repeated Ghostty font families and non-English locale values needed coverage.

No blocking findings remain.

Security Audit

  • No command execution, filesystem path handling, authentication, secrets, dependencies, or privilege changes.
  • No new IPC channel or RPC method. The existing settings channel accepts one additional bounded array field.
  • Renderer input and persisted state are normalized again in the main process: non-arrays become empty, non-string/empty entries are dropped, duplicates are removed, and stacks are capped at 32 entries.
  • Font family values are emitted through JSON.stringify before entering xterm's CSS font-family option, preventing malformed quote/comma construction from hand-built CSS strings.
  • Ghostty import reuses the same normalization authority.

No security follow-up is needed.

Notes

  • Unavailable fonts are skipped by the browser's normal CSS font fallback resolution.
  • User-provided monospace is intentionally omitted from the middle of the stack so Orca retains one final unquoted generic fallback.
  • The 32-family bound prevents pathological persisted/IPC arrays while remaining far above practical multilingual stacks.
  • Made with Orca 🐋

ELI5

Under Terminal Typography you can set an ordered list of fallback fonts for characters your primary font lacks. Multilingual glyphs resolve more predictably: primary font, then your fallbacks, then Orca defaults.

@coderabbitai

coderabbitai Bot commented Jul 12, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds an optional terminal font fallback stack with trimming, case-insensitive deduplication, invalid-value filtering, and a maximum of 32 entries. Ghostty mappings, IPC updates, and persisted settings now normalize fallback values. Terminal font-family construction and xterm updates include configured fallbacks. Settings UI controls support adding, editing, reordering, removing, and searching fallback fonts, with new localization strings and tests.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The PR includes unrelated formatting-only edits to updatePRBotAuthorOverride RPC/type files, which are outside the fallback-font feature scope. Remove the client-ui.ts and api-types.ts edits unless they are required for this feature, or explain them explicitly in the PR.
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR implements ordered user-configurable fallback stacks, preserves defaults when empty/unavailable, and imports Ghostty stacks as requested for #8367.
Title check ✅ Passed The title clearly and concisely describes the main change: configurable terminal fallback font stacks.
Description check ✅ Passed All required sections are present and the key implementation, testing, security, and notes details are covered, though screenshots are noted as unavailable.

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (1)
src/renderer/src/components/settings/TerminalFontFallbackSetting.tsx (1)

69-72: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use hash-based locale keys instead of named keys.

All translate calls in this file use named keys (e.g., TerminalFontFallbackSetting.list, .moveUp, .entryLabel) while the existing codebase convention — including SettingsFormControls.tsx in the same directory — uses 10-character hash-based keys (e.g., a4ff6143f8). The same pattern appears in TerminalAppearanceSection.tsx (line 241, 258) and terminal-typography-search.ts (lines 38, 42, 53). Based on learnings, settings components should use translate('auto.components.<Dir>.<ComponentFile>.<10-char-hash>', 'Default English text') and run pnpm bootstrap:locale-catalog to propagate translations.

Source: Learnings


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: cb3a88cf-030d-4287-b329-c5fdebacfdbc

📥 Commits

Reviewing files that changed from the base of the PR and between d509ee7 and 76dd51521dc3a7b4bc030b7c4082ef23d3d14327.

📒 Files selected for processing (26)
  • src/main/ghostty/mapper.test.ts
  • src/main/ghostty/mapper.ts
  • src/main/ipc/settings.test.ts
  • src/main/ipc/settings.ts
  • src/main/persistence.test.ts
  • src/main/persistence.ts
  • src/renderer/src/components/settings/SettingsFormControls.tsx
  • src/renderer/src/components/settings/TerminalAppearanceSection.tsx
  • src/renderer/src/components/settings/TerminalFontFallbackSetting.test.tsx
  • src/renderer/src/components/settings/TerminalFontFallbackSetting.tsx
  • src/renderer/src/components/settings/TerminalSettingsPreview.tsx
  • src/renderer/src/components/settings/terminal-typography-search.ts
  • src/renderer/src/components/terminal-pane/layout-serialization.test.ts
  • src/renderer/src/components/terminal-pane/layout-serialization.ts
  • src/renderer/src/components/terminal-pane/terminal-appearance.test.ts
  • src/renderer/src/components/terminal-pane/terminal-appearance.ts
  • src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json
  • src/shared/constants.ts
  • src/shared/terminal-font-fallbacks.test.ts
  • src/shared/terminal-font-fallbacks.ts
  • src/shared/types.ts

Comment thread src/main/ghostty/mapper.ts Resolved
Comment thread src/shared/terminal-font-fallbacks.ts Resolved
@AmethystLiang
AmethystLiang requested a review from Jinwoo-H July 13, 2026 16:48
@AmethystLiang AmethystLiang assigned OrcaWin and unassigned Jinwoo-H Jul 20, 2026
@AmethystLiang
AmethystLiang requested review from OrcaWin and removed request for Jinwoo-H July 20, 2026 18:39
@nwparker nwparker added the enhancement New feature or request label Jul 27, 2026
@mmarabel

Copy link
Copy Markdown
Contributor Author

Rebased onto current upstream/main (5b7f44278a).

The fallback-font setting now lives in the current persistence/settings shape:

  • terminalFontFallbacks is on GlobalSettings in src/shared/global-settings-types.ts (the old src/shared/types.ts / persistence.test.ts monoliths are gone).
  • Load/update go through the current Store sanitizers; IPC still normalizes and bounds the stack.
  • FontAutocomplete extras (onCommit, ariaLabel) are on the extracted FontAutocomplete.tsx.
  • Custom fallbacks still sit between the primary family and Orca defaults.

Force-pushed gatsby74/feature-allow-custom-terminal-font-fallback-stac.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants