Merge pull request #6 from askac/fix/windows-font-fallback

Improve terminal symbol font fallbacks

Author: askac

README.md

@@ -514,15 +514,16 @@ without a CDN:
 - `@xterm/xterm` 6.0.0: `static/js/xterm.js`, `static/css/xterm.css`
 - `@xterm/addon-fit` 0.11.0: `static/js/xterm-addon-fit.js`
 - `@xterm/addon-web-links` 0.12.0: `static/js/xterm-addon-web-links.js`
+- Powerline Symbols: `static/fonts/PowerlineSymbols.otf` (optional prompt-symbol fallback)
 
 The browser bundles are copied from official npm release packages. A matching
 source checkout is kept at `/mnt/d/workspace/github/xterm.js`, tag `6.0.0` /
 commit `f447274f430fd22513f6adbf9862d19524471c04`, for auditing and future
 upgrades.
 
-xterm.js and these addons are MIT licensed. Keep `THIRD-PARTY-NOTICES.md`,
-`static/licenses/xtermjs-MIT-LICENSE.txt`, and `static/js/README.md` when
-publishing releases that include the vendored files.
+xterm.js, these addons, and Powerline Symbols are MIT licensed. Keep
+`THIRD-PARTY-NOTICES.md`, the matching files under `static/licenses/`, and the
+asset README files when publishing releases that include the vendored files.
 
 ## Security Notes
 

THIRD-PARTY-NOTICES.md

@@ -15,6 +15,14 @@ This project incorporates components from the following projects:
 - **Copyright**: (c) 2014-2023 Guillermo Rauch
 - **Project**: https://github.com/socketio/socket.io
 
+## Powerline Symbols
+- **License**: MIT
+- **Copyright**: Copyright 2013 Kim Silkebækken and other contributors
+- **Project**: https://github.com/powerline/powerline
+- **Vendored file**: `static/fonts/PowerlineSymbols.otf`
+- **Upstream commit**: `11808cbe5c16e4621edcaefa916b5add81eab799`
+- **License text**: `static/licenses/powerline-MIT-LICENSE.txt`
+
 ## Microsoft Windows Terminal (Color Schemes)
 - **License**: MIT
 - **Copyright**: (c) Microsoft Corporation

static/fonts/PowerlineSymbols.otf

@@ -0,0 +1,16 @@
+# Vendored Fonts
+
+`PowerlineSymbols.otf` is copied from the official Powerline repository at
+commit `11808cbe5c16e4621edcaefa916b5add81eab799`:
+
+https://github.com/powerline/powerline/blob/11808cbe5c16e4621edcaefa916b5add81eab799/font/PowerlineSymbols.otf
+
+The file is 2,264 bytes and has this SHA-256 digest:
+
+```text
+4a2496a009b1649878ce067a7ec2aed9f79656c90136971e1dba00766515f7a1
+```
+
+It is used only when the optional Powerline symbol fallback preference is
+enabled. The browser font face is limited to `U+E0A0-E0A2` and
+`U+E0B0-E0B3`.

static/fonts/README.md

@@ -0,0 +1,21 @@
+Copyright 2013 Kim Silkebækken and other contributors
+https://github.com/powerline/powerline
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

static/licenses/powerline-MIT-LICENSE.txt

@@ -5,6 +5,14 @@
     <!-- Local Fallback Assets -->
     <link rel="stylesheet" href="/static/css/xterm.css" />
     <style>
+        @font-face {
+            font-family: "StandTerm Powerline Symbols";
+            src: url("/static/fonts/PowerlineSymbols.otf") format("opentype");
+            font-display: block;
+            font-style: normal;
+            font-weight: 400;
+            unicode-range: U+E0A0-E0A2, U+E0B0-E0B3;
+        }
         :root { --status-bar-height: 26px; --tab-bar-height: 34px; }
         body { margin: 0; background: #000; overflow: hidden; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
         #terminal-tabs { position: absolute; top: 0; left: 0; right: 0; height: var(--tab-bar-height); box-sizing: border-box; background: #151515; border-bottom: 1px solid #2a2a2a; display: none; align-items: center; gap: 4px; padding: 4px 8px; z-index: 40; overflow: hidden; }
@@ -610,6 +618,7 @@ <h3>Settings</h3>
                                 </select>
                             </div>
                             <div class="settings-row"><label for="pref-fontFace">Font face</label><input type="text" id="pref-fontFace"></div>
+                            <div class="settings-row"><label for="pref-powerlineSymbols" title="Use the bundled Powerline symbols font as a fallback for prompt glyphs such as the branch symbol.">Enable Powerline symbol fallback</label><input type="checkbox" id="pref-powerlineSymbols"></div>
                             <div class="settings-row"><label for="pref-fontSize">Font size</label><input type="number" id="pref-fontSize" min="8" max="32"></div>
                             <div class="settings-row"><label for="pref-fontWeight" title="Heavier weights can improve perceived brightness of thin glyphs, especially with macOS grayscale antialiasing.">Font weight</label>
                                 <select id="pref-fontWeight"><option value="normal">Normal (400)</option><option value="500">Medium (500)</option><option value="600">Semibold (600)</option><option value="bold">Bold (700)</option></select>
@@ -930,14 +939,15 @@ <h3>Session expired</h3>
         // --- Preferences ---
         const PREF_KEY = 'terminal.pref.v1';
         const LEGACY_DEFAULT_FONT_FACE = 'Consolas, "Courier New", monospace';
+        const WINDOWS_TERMINAL_FONT_FACE = 'Consolas, "Cascadia Mono", "Courier New", monospace';
         const LEGACY_MAC_DEFAULT_FONT_FACE = 'Menlo, Monaco, "Noto Sans Mono CJK TC", "PingFang TC", "Apple LiGothic", monospace';
         const MAC_TERMINAL_FONT_FACE = 'Menlo, Monaco, "SF Mono", "Noto Sans Mono CJK TC", "Sarasa Mono TC", "Biaodian Pro Sans CNS", monospace';
         function isApplePlatform() {
             return /Mac|iPhone|iPad|iPod/i.test(`${navigator.platform || ''} ${navigator.userAgent || ''}`);
         }
         function getDefaultTerminalFontFace() {
             if (isApplePlatform()) return MAC_TERMINAL_FONT_FACE;
-            return LEGACY_DEFAULT_FONT_FACE;
+            return WINDOWS_TERMINAL_FONT_FACE;
         }
         const PREF_DEFAULTS = {
             useCustomMenu: true,
@@ -946,6 +956,7 @@ <h3>Session expired</h3>
             detectUrls: true,
             urlClickAction: 'overlay',
             fontFace: getDefaultTerminalFontFace(),
+            powerlineSymbols: false,
             fontSize: 14,
             // macOS grayscale antialiasing renders thin bright glyphs dimmer
             // than Windows ClearType, so default to a slightly heavier weight
@@ -975,6 +986,10 @@ <h3>Session expired</h3>
             }
         }
         function savePrefs(p) { localStorage.setItem(PREF_KEY, JSON.stringify(p)); }
+        function getTerminalFontFace() {
+            if (!prefs.powerlineSymbols) return prefs.fontFace;
+            return '"StandTerm Powerline Symbols", ' + prefs.fontFace;
+        }
         function normalizeFontSize(value, fallback = PREF_DEFAULTS.fontSize) {
             const text = String(value).trim();
             if (!/^\d+$/.test(text)) return fallback;
@@ -2292,7 +2307,7 @@ <h3>Session expired</h3>
                     cursorBlink: false,
                     disableStdin: true,
                     cursorStyle: prefs.cursorStyle,
-                    fontFamily: prefs.fontFace,
+                    fontFamily: getTerminalFontFace(),
                     fontSize: prefs.fontSize,
                     fontWeight: prefs.fontWeight,
                     scrollback: 1000,
@@ -3448,7 +3463,7 @@ <h3>Session expired</h3>
                     allowProposedApi: true,
                     cursorBlink: true,
                     cursorStyle: prefs.cursorStyle,
-                    fontFamily: prefs.fontFace,
+                    fontFamily: getTerminalFontFace(),
                     fontSize: prefs.fontSize,
                     fontWeight: prefs.fontWeight,
                     theme: SCHEMES[prefs.colorScheme] || SCHEMES.vintage
@@ -3716,6 +3731,9 @@ <h3>Session expired</h3>
                             colorScheme: prefs.colorScheme,
                             mirrorCursorStyle: state.agentTerminalMirror
                                 ? state.agentTerminalMirror.options.cursorStyle
+                                : null,
+                            mirrorFontFamily: state.agentTerminalMirror
+                                ? state.agentTerminalMirror.options.fontFamily
                                 : null
                         });
                     },
@@ -5401,6 +5419,7 @@ <h3>Session expired</h3>
                 document.getElementById('pref-urlClickAction').value = prefs.urlClickAction;
                 document.getElementById('pref-colorScheme').value = prefs.colorScheme;
                 document.getElementById('pref-fontFace').value = prefs.fontFace;
+                document.getElementById('pref-powerlineSymbols').checked = prefs.powerlineSymbols;
                 document.getElementById('pref-fontSize').value = prefs.fontSize;
                 document.getElementById('pref-fontWeight').value = prefs.fontWeight;
                 document.getElementById('pref-cursorStyle').value = prefs.cursorStyle;
@@ -5486,20 +5505,21 @@ <h3>Session expired</h3>
                 prefs.urlClickAction = document.getElementById('pref-urlClickAction').value;
                 prefs.colorScheme = document.getElementById('pref-colorScheme').value;
                 prefs.fontFace = document.getElementById('pref-fontFace').value;
+                prefs.powerlineSymbols = document.getElementById('pref-powerlineSymbols').checked;
                 prefs.fontSize = normalizeFontSize(document.getElementById('pref-fontSize').value, prefs.fontSize);
                 prefs.fontWeight = normalizeFontWeight(document.getElementById('pref-fontWeight').value, prefs.fontWeight);
                 prefs.cursorStyle = normalizeCursorStyle(document.getElementById('pref-cursorStyle').value, prefs.cursorStyle);
                 savePrefs(prefs);
                 terminals.forEach(state => {
                     state.term.options.cursorStyle = prefs.cursorStyle;
-                    state.term.options.fontFamily = prefs.fontFace;
+                    state.term.options.fontFamily = getTerminalFontFace();
                     state.term.options.fontSize = prefs.fontSize;
                     state.term.options.fontWeight = prefs.fontWeight;
                     state.term.options.theme = SCHEMES[prefs.colorScheme] || SCHEMES.vintage;
                     applyCjkWidthPreference(state.term);
                     if (state.agentTerminalMirror) {
                         state.agentTerminalMirror.options.cursorStyle = prefs.cursorStyle;
-                        state.agentTerminalMirror.options.fontFamily = prefs.fontFace;
+                        state.agentTerminalMirror.options.fontFamily = getTerminalFontFace();
                         state.agentTerminalMirror.options.fontSize = prefs.fontSize;
                         state.agentTerminalMirror.options.fontWeight = prefs.fontWeight;
                         state.agentTerminalMirror.options.theme = SCHEMES[prefs.colorScheme] || SCHEMES.vintage;

templates/index.html

@@ -910,6 +910,131 @@ def test_cjk_width_compatibility_defaults_off(browser, access_url):
         close_context(context)
 
 
+def test_windows_font_fallback_defaults_and_migrates_legacy(browser, access_url):
+    expected = 'Consolas, "Cascadia Mono", "Courier New", monospace'
+    legacy = 'Consolas, "Courier New", monospace'
+    custom = 'Custom Mono, monospace'
+    context, page = new_page(browser, access_url)
+    try:
+        initial = page.evaluate("() => window.terminalTest.getActiveTerminalOptions().fontFamily")
+        check(initial == expected, 'terminal font fallback did not default to Cascadia Mono')
+
+        page.evaluate(
+            "fontFace => localStorage.setItem('terminal.pref.v1', JSON.stringify({ fontFace }))",
+            legacy,
+        )
+        page.reload(wait_until='domcontentloaded')
+        page.wait_for_function('() => !!window.terminalTest', timeout=10000)
+        page.wait_for_function(
+            "() => window.terminalTest.getSocketState().connected === true",
+            timeout=10000,
+        )
+        page.wait_for_function(
+            '() => window.terminalTest.getActiveTerminalOptions() !== null',
+            timeout=10000,
+        )
+        migrated = page.evaluate("() => window.terminalTest.getActiveTerminalOptions().fontFamily")
+        check(migrated == expected, 'legacy terminal font fallback was not migrated')
+
+        page.evaluate(
+            "fontFace => localStorage.setItem('terminal.pref.v1', JSON.stringify({ fontFace }))",
+            custom,
+        )
+        page.reload(wait_until='domcontentloaded')
+        page.wait_for_function('() => !!window.terminalTest', timeout=10000)
+        page.wait_for_function(
+            '() => window.terminalTest.getActiveTerminalOptions() !== null',
+            timeout=10000,
+        )
+        preserved = page.evaluate("() => window.terminalTest.getActiveTerminalOptions().fontFamily")
+        check(preserved == custom, 'custom terminal font face was overwritten by default migration')
+    finally:
+        close_context(context)
+
+
+def test_powerline_symbol_fallback_is_optional_and_applies_immediately(browser, access_url):
+    context, page = new_page(browser, access_url)
+    try:
+        initial = page.evaluate("() => window.terminalTest.getActiveTerminalOptions()")
+        check(
+            not initial['fontFamily'].startswith('"StandTerm Powerline Symbols"'),
+            'Powerline symbol fallback defaulted on',
+        )
+
+        page.click('#quick-settings')
+        page.wait_for_selector('#settings-modal.open', timeout=5000)
+        page.click('.settings-nav-item[data-tab="appearance"]')
+        check(
+            page.locator('#pref-powerlineSymbols').is_checked() is False,
+            'Powerline symbol fallback checkbox defaulted on',
+        )
+        page.check('#pref-powerlineSymbols')
+        page.click('#settings-save')
+        page.wait_for_function(
+            "() => window.terminalTest.getActiveTerminalOptions().fontFamily.startsWith('\\\"StandTerm Powerline Symbols\\\"')",
+            timeout=5000,
+        )
+        enabled = page.evaluate(
+            """() => ({
+                options: window.terminalTest.getActiveTerminalOptions(),
+                stored: JSON.parse(localStorage.getItem('terminal.pref.v1')).powerlineSymbols
+            })"""
+        )
+        check(enabled['stored'] is True, 'Powerline symbol fallback preference was not saved')
+        check(
+            enabled['options']['mirrorFontFamily'] == enabled['options']['fontFamily'],
+            'Powerline symbol fallback did not update the agent mirror',
+        )
+        loaded = page.evaluate(
+            """async () => {
+                const fonts = await document.fonts.load(
+                    '14px "StandTerm Powerline Symbols"',
+                    '\ue0a0'
+                );
+                return fonts.length;
+            }"""
+        )
+        check(loaded > 0, 'bundled Powerline symbols font did not load')
+
+        page.click('#new-tab-btn')
+        page.wait_for_function(
+            "() => window.terminalTest.getTerminalTabsState().tabs.length === 2",
+            timeout=5000,
+        )
+        new_tab = page.evaluate("() => window.terminalTest.getActiveTerminalOptions()")
+        check(
+            new_tab['fontFamily'] == enabled['options']['fontFamily'],
+            'new terminal did not use the Powerline symbol fallback',
+        )
+        check(
+            new_tab['mirrorFontFamily'] == enabled['options']['fontFamily'],
+            'new agent mirror did not use the Powerline symbol fallback',
+        )
+
+        page.click('#quick-settings')
+        page.wait_for_selector('#settings-modal.open', timeout=5000)
+        page.click('.settings-nav-item[data-tab="appearance"]')
+        page.uncheck('#pref-powerlineSymbols')
+        page.click('#settings-save')
+        page.wait_for_function(
+            "() => !window.terminalTest.getActiveTerminalOptions().fontFamily.startsWith('\\\"StandTerm Powerline Symbols\\\"')",
+            timeout=5000,
+        )
+        disabled = page.evaluate(
+            """() => ({
+                options: window.terminalTest.getActiveTerminalOptions(),
+                stored: JSON.parse(localStorage.getItem('terminal.pref.v1')).powerlineSymbols
+            })"""
+        )
+        check(disabled['stored'] is False, 'Powerline symbol fallback disable was not saved')
+        check(
+            disabled['options']['mirrorFontFamily'] == disabled['options']['fontFamily'],
+            'disabling Powerline symbol fallback did not update the agent mirror',
+        )
+    finally:
+        close_context(context)
+
+
 def test_cursor_type_setting_updates_existing_and_new_terminals(browser, access_url):
     context, page = new_page(browser, access_url)
     try:
@@ -1381,6 +1506,8 @@ def main():
         test_paste_review_approve_and_cancel,
         test_approval_payload_and_stale_rejections,
         test_cjk_width_compatibility_defaults_off,
+        test_windows_font_fallback_defaults_and_migrates_legacy,
+        test_powerline_symbol_fallback_is_optional_and_applies_immediately,
         test_cursor_type_setting_updates_existing_and_new_terminals,
         test_settings_server_tab_loads_readonly_snapshot,
         test_connection_diagnostics_are_session_scoped_and_redacted,