fix(terminal): register configured font as a local() @font-face for the WebGL renderer (#898)

[yagop]

Closes #898

Register the configured terminal font as a local() @font-face so the macOS WKWebView WebGL glyph-atlas rasterizer can resolve it, then rebuild the atlas. Fixes the "two fonts at once" mismatch where a subset of glyphs fell back to bundled JetBrains Mono under the WebGL renderer while the DOM renderer was fine (same mechanism as #820).

• T1 Add registerLocalFont() to src/lib/fonts.ts — inject a local() @font-face for the configured family and load it into the FontFaceSet, no-op on blank/comma-stack input
• T2 Wire it into the WebGL renderer (rendererPool.ts): add a clearWebglAtlas() helper and register the font + rebuild the atlas on attachWebgl
• T3 Register + rebuild atlases in applyFontFamily so live font-family changes re-resolve under WebGL
• T4 Add registerLocalFont unit tests to src/lib/fonts.test.ts (guards, @font-face injection, dedup)
• T5 Address review (fix(terminal): register configured font as a local() @font-face for the WebGL renderer (#898) #918): simplify clearWebglAtlas to call slot.term.clearTextureAtlas(), dropping the webglAddon cast

Summary by CodeRabbit

• New Features

  • Added the ability to register user-provided local font families (including quoted names) for more reliable terminal text rendering.
  • When fonts change, the terminal now refreshes WebGL glyph rendering so updated fonts take effect promptly.

• Bug Fixes

  • Prevented duplicate local font registration and redundant style injection.
  • Improved input handling by ignoring empty values and font-stack inputs, avoiding unnecessary font loading.
  • Ensured font loads are applied correctly by waiting for local font faces to be registered before rendering.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds registerLocalFont to register user-selected local fonts through @font-face and preload them, with tests in a stubbed document environment. The terminal renderer now registers the configured font before WebGL atlas rebuilds and clears existing atlases after font changes.

Changes

Local font registration

Layer / File(s)	Summary
registerLocalFont implementation and tests src/lib/fonts.ts, src/lib/fonts.test.ts	Adds a cached-family registry and registerLocalFont(userInput) that trims, sanitizes, and ignores empty or comma-separated inputs, injects @font-face { src: local(...) } rules for weights 400 and 700, and loads them through document.fonts.load; the test suite stubs document in Node to cover registration, no-op paths, and deduplication.
WebGL renderer pool integration src/modules/terminal/lib/rendererPool.ts	Imports registerLocalFont, registers the active terminal font during WebGL attachment, adds clearWebglAtlas(slot) to reset the glyph atlas and refresh the terminal, and clears atlases for all slots after applyFontFamily(family) completes registration.

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

Related issues: #898

Suggested labels: bug, terminal, webgl, fonts

Suggested reviewers: crynta

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The changes implement the linked WebGL font-resolution fix by registering local fonts and rebuilding the atlas.
Out of Scope Changes check	✅ Passed	No unrelated code changes are evident beyond the font registration, WebGL atlas refresh, and supporting tests.
Title check	✅ Passed	The title follows Conventional Commits and accurately summarizes the font registration and WebGL renderer change.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[yagop]

😺 Michi — ready for review 🐾

Implemented in 4 commits on issue-898 (from fork yagop:issue-898):

• T1 228c1ae — registerLocalFont() in src/lib/fonts.ts: injects a local() @font-face (weights 400/700) for the configured family and loads it into the FontFaceSet; no-op on blank/comma-stack input, deduped.
• T2 9a6e3f1 — wire into the WebGL renderer (rendererPool.ts): new clearWebglAtlas() helper; on attachWebgl, register the configured font then rebuild the atlas so glyphs re-rasterize in the correct font (fixes the initial-render "two fonts" bug).
• T3 7be1e36 — applyFontFamily: re-register + rebuild atlases so live font-family changes also re-resolve under WebGL.
• T4 93d0ae9 — unit tests for registerLocalFont (guards, @font-face injection, dedup).

CI status. This is a cross-fork PR, so GitHub Actions won't run until a maintainer approves the workflow — no checks are queued yet. The change is frontend-only (no src-tauri/ changes), and I ran the full frontend CI job locally against the same commands, all green:

• pnpm lint → exit 0
• pnpm check-types → clean
• pnpm test → 242 passed (29 files), including 4 new registerLocalFont tests
• pnpm build → ✓
• pnpm size → within budget (startup 334.1 kB / 540 kB; total 1.41 MB / 1.5 MB)

Please approve the workflow run so CI can confirm on GitHub. The @font-face { src: local(...) } preflight noted in the issue still wants a real WKWebView check (document.fonts.check(...) before/after) — worth a manual smoke test on macOS with a system Nerd Font.

Not merged, not closing the issue — that's yours.

[coderabbitai]

🧹 Nitpick comments (1)

src/modules/terminal/lib/rendererPool.ts (1)

820-832: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Call slot.term.clearTextureAtlas() directly. @xterm/xterm 6.0.0 already exposes this on Terminal, so the cast through webglAddon is unnecessary. Keep the refresh afterward so the atlas rebuild still picks up the registered font.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/modules/terminal/lib/rendererPool.ts` around lines 820 - 832, The
clearWebglAtlas helper is still reaching through slot.webglAddon with an
unnecessary cast even though Terminal already exposes clearTextureAtlas. Update
clearWebglAtlas to call slot.term.clearTextureAtlas() directly, keep the
existing refresh afterward in slot.term.refresh, and remove the webglAddon shim
so the method reference stays aligned with `@xterm/xterm` Terminal.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/modules/terminal/lib/rendererPool.ts`:
- Around line 820-832: The clearWebglAtlas helper is still reaching through
slot.webglAddon with an unnecessary cast even though Terminal already exposes
clearTextureAtlas. Update clearWebglAtlas to call slot.term.clearTextureAtlas()
directly, keep the existing refresh afterward in slot.term.refresh, and remove
the webglAddon shim so the method reference stays aligned with `@xterm/xterm`
Terminal.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a2e2aaad-e0be-4c9e-abe9-330e14724918

📥 Commits

Reviewing files that changed from the base of the PR and between 3f4d680 and 93d0ae9.

📒 Files selected for processing (3)

• src/lib/fonts.test.ts
• src/lib/fonts.ts
• src/modules/terminal/lib/rendererPool.ts

[yagop]

😺 Michi — addressed the review 🐾

@coderabbitai thanks for the review — both points handled:

• clearWebglAtlas cast ✅ Verified @xterm/xterm@6.0.0 declares clearTextureAtlas(): void on Terminal (typings/xterm.d.ts), so I dropped the as unknown as webglAddon shim and call slot.term.clearTextureAtlas() directly, keeping the refresh afterward — commit e27a02a. pnpm check-types/lint/test (242) still green.
• Title check ✅ Retitled to Conventional Commits: fix(terminal): register configured font as a local() @font-face for the WebGL renderer (#898).

Leaving the thread for you to resolve.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh pr view 918 --repo crynta/terax-ai --json title,commits -q '.title, (.commits[-3:] | .[].messages)' 2>/dev/null
echo "---diff---"
gh pr diff 918 --repo crynta/terax-ai | sed -n '1,200p'

Length of output: 7874

---

🏁 Script executed:

#!/bin/bash
gh pr diff 918 --repo crynta/terax-ai | grep -n "clearTextureAtlas\|clearWebglAtlas\|webglAddon as" -A3 -B3

Length of output: 1388

---

Confirmed — both changes look right:

• clearWebglAtlas() now calls slot.term.clearTextureAtlas() directly (no cast), matching xterm 6.0.0's declared Terminal.clearTextureAtlas(): void, with refresh() afterward and defensive try/catch blocks — clean.
• PR title is now fix(terminal): register configured font as a local() @font-face for the WebGL renderer (Terminal: WebGL renderer falls back to JetBrains Mono for some glyphs when a system-installed Nerd Font is set (macOS/WKWebView) #898), properly conventional.

Nice work, @yagop. Nothing further from me here — this is ready pending the real WKWebView smoke test you flagged.

(๑˃̵ᴗ˂̵)و