# SPDX-License-Identifier: Apache-2.0 """Terminal capability detection: what can this terminal draw? There are two questions. MeshTerm answers both out-of-band, because it cannot ask a terminal in-band. A glyph that the terminal does not have still occupies its cell, so the screen looks the same if the character arrived or not. **Powerline separators**, below, are a question about the font. MeshTerm reads the configured face of the terminal and matches it against fonts that are known to have the block. **Emoji** (:func:`emoji_support`) are a question about the host, and only on Windows. The classic console (``conhost``, which a program that the user double-clicks still gets) rasterizes through GDI with the console font and nothing behind it. Thus an emoji is a replacement box, in any font configuration. All the hosts that replaced it draw emoji correctly. So the verdict identifies the host, from its structure and not from the environment. (``WT_SESSION`` is inherited across process launches. A program that starts from Windows Terminal into a console of its own still says that it is in Windows Terminal.) A ``False`` sends each icon through the compact single-glyph table :func:`meshterm.ui.theme.glyph`, which MeshTerm already keeps for the PicoCalc. All of this vocabulary is in the BMP, so it draws wherever the plain status marks draw. Both verdicts are hints that pick a default. Each has an override for the user who knows better than the probe: ``MESHTERM_POWERLINE`` and ``MESHTERM_EMOJI``. The path-line widget (:mod:`~meshterm.ui.pathline`) can render a sequence of hops as interlocking powerline segments. Each hop is a chip with a colour fill. The solid triangle U+E0B0 joins the chips. Its foreground is the fill of the previous chip, and its background is the fill of the next chip (the oh-my-posh look). That triangle is in the Private Use Area, so it draws only when the configured font of the terminal (or the terminal itself) supplies the glyph. A font without the glyph shows tofu boxes. MeshTerm cannot ask in-band if the terminal has this glyph. A missing glyph still occupies its cell, so even a probe of the cursor position sees nothing. Thus this is a problem of out-of-band detection. MeshTerm identifies the terminal, reads its configuration, and matches the configured face against fonts that are known to have the powerline block. There are four sources of truth, in the order of confidence: * **An explicit override.** ``MESHTERM_POWERLINE`` (``1``/``full``, ``core``, ``0``/``off``) always wins. It is the same gate pattern as ``MESHTERM_FULL_WIDTH``. The user knows their own display better than any probe. * **The font of a handheld.** Where the platform names a glyph contract (:attr:`~meshterm.platforms.Platform.font`), the render boundary folds each frame down to that font, in any terminal that started the app. Thus the inventory is the answer, and a question to the terminal is a question to the wrong display. The panel of the Cardputer is Terminus, which has the core chevrons. The 512-glyph console font of the PicoCalc draws the two chevrons in two donor slots. Thus the paths are chips on both handhelds. MeshTerm does not probe: :data:`~meshterm.ui.fontset.FONTS` already says what each font can draw. * **The configured font**, found for each terminal. The terminals are Windows Terminal (``WT_SESSION`` + ``WT_PROFILE_ID`` → the ``font.face`` of the profile in ``settings.json``), the integrated terminal of VS Code (``TERM_PROGRAM=vscode`` → ``terminal.integrated.fontFamily``, the workspace before the user, with ``editor.fontFamily`` as the fallback), and classic conhost (``GetCurrentConsoleFontEx``, which MeshTerm trusts only when it detects no ConPTY host, because the hidden conhost under a ConPTY host reports a stub face and not what is on the screen). MeshTerm matches the face against :data:`RECOMMENDED_FONTS` (the list of fonts that MeshTerm recommends to users). The list has the alias spellings that Nerd Fonts use (``Hack Nerd Font Mono`` / ``Hack NFM``). A generic rule, "any Nerd Font", is also in the match, because each Nerd Font patch has the full powerline block. * **The renderer of the terminal.** Several terminals draw the core triangles in any font. Windows Terminal falls back to its bundled Cascadia Code NF for the symbol ranges (version 1.22 and later). The terminal of VS Code draws them as custom glyphs (``terminal.integrated.customGlyphs``, on by default). kitty, WezTerm, and Alacritty have built-in powerline glyphs. These terminals count as ``core`` support, also when the configured font matches nothing. There are two levels of coverage. ``full`` is a Nerd Font patch: the triangles and the extended block (rounded caps and slants). ``core`` is only U+E0B0–U+E0B3, which many stock coder fonts (Fira Code, JetBrains Mono, Source Code Pro) have natively. The path widget uses only the core triangle, so ``core`` is enough to switch it on. ``full`` is more than the widget needs, for more complex chrome. When MeshTerm cannot know the answer, for example in an ssh session (the font is on the machine of the far client) or in an unrecognized terminal, the verdict is ``unknown``. Then callers must keep the plain-arrow rendering. Each probe does its best. Unreadable settings, missing registry keys, or a failed Win32 call lower the verdict, and never raise an exception. The result is a hint that picks a default. It is not a gate that the user must fight. """ from __future__ import annotations import json import os import re import sys from collections.abc import Callable, Iterable, Mapping from dataclasses import dataclass from functools import lru_cache from pathlib import Path from ..core import win32dll from ..platforms import Platform, on_platform from .fontset import FONTS #: The levels of coverage that a verdict (or a recommended font) can have, the strongest first. FULL = "full" CORE = "core" NONE = "none" UNKNOWN = "unknown" @dataclass(frozen=True) class RecommendedFont: """One font that MeshTerm recommends for the rendering of powerline paths. Attributes: name: The canonical display name (what a screen of recommendations shows). aliases: The normalized name prefixes that identify the family. They are all the spellings that the config of a terminal can have, in lower case with collapsed spaces. Nerd Fonts have several spellings on purpose: ``hack nerd font mono`` and ``hack nfm`` are the same file. coverage: :data:`FULL` when the family has the whole powerline block (Nerd Font patches). :data:`CORE` when it has only the four triangles. """ name: str aliases: tuple[str, ...] coverage: str #: The fonts that MeshTerm recommends, with the full-coverage Nerd Fonts first. The order #: is important, because the first alias that matches wins. Thus ``JetBrainsMono Nerd #: Font`` must match its ``full`` entry before the plain ``JetBrains Mono`` prefix can #: claim it as ``core``. RECOMMENDED_FONTS: tuple[RecommendedFont, ...] = ( RecommendedFont( "MesloLGM Nerd Font", ( "meslolgm nerd font", "meslolgs nerd font", "meslolgl nerd font", "meslolgm nf", "meslolgs nf", "meslolgl nf", "meslo lgm nerd font", "meslo lgs nerd font", ), FULL, ), RecommendedFont( "Hack Nerd Font", ("hack nerd font", "hack nf", "hack nfm", "hack nfp"), FULL, ), RecommendedFont( "CaskaydiaCove Nerd Font", ( "caskaydiacove nerd font", "caskaydiacove nf", "caskaydiacove nfm", "caskaydiamono nerd font", "caskaydiamono nf", "caskaydia cove nerd font", ), FULL, ), RecommendedFont( "Cascadia Code NF", ("cascadia code nf", "cascadia mono nf"), FULL, ), RecommendedFont( "FiraCode Nerd Font", ("firacode nerd font", "firacode nf", "firacode nfm", "fira code nerd font"), FULL, ), RecommendedFont( "JetBrainsMono Nerd Font", ( "jetbrainsmono nerd font", "jetbrainsmono nf", "jetbrainsmono nfm", "jetbrains mono nerd font", ), FULL, ), RecommendedFont("Cascadia Code PL", ("cascadia code pl", "cascadia mono pl"), CORE), RecommendedFont("Fira Code", ("fira code",), CORE), RecommendedFont("JetBrains Mono", ("jetbrains mono",), CORE), RecommendedFont("Source Code Pro", ("source code pro", "source code variable"), CORE), RecommendedFont("Iosevka", ("iosevka",), CORE), ) #: The catch-all for a patched font that the explicit list does not name. Each family #: whose name has the Nerd Font branding has the full powerline block. The branding is the #: long ``… Nerd Font [Mono|Propo]`` or the short suffixes of version 3 #: (``NF``/``NFM``/``NFP``). NERD_FONT_GENERIC = RecommendedFont("Nerd Font (patched)", (), FULL) _NERD_RE = re.compile(r"\bnerd font\b|\bnf[mp]?\b") @dataclass(frozen=True) class FontDetection: """The configured terminal font, and the terminal that MeshTerm read it from. Attributes: face: The font family name as configured (not normalized). source: ``"windows-terminal"``, ``"vscode"``, or ``"conhost"``. """ face: str source: str @dataclass(frozen=True) class PowerlineSupport: """The verdict: how certain MeshTerm is that this terminal can draw powerline separators. Attributes: level: :data:`FULL`, :data:`CORE`, :data:`NONE`, or :data:`UNKNOWN`. source: What decided the verdict. ``"env"`` is the override. ``"platform:"`` is the font inventory of a handheld. ``"font:"`` is a configured face that matched, or that definitely did not match. ``"renderer:"`` is a terminal that draws the glyphs itself. ``"ssh"`` is a font on the far client, which MeshTerm cannot know. ``"unknown"`` is all other cases. face: The configured face, when MeshTerm found one. It is for information. matched: The entry of the recommended list that the face matched, if any. """ level: str source: str face: str | None = None matched: RecommendedFont | None = None @property def capable(self) -> bool: """Check if the core triangle (the only glyph that the path widget needs) will draw.""" return self.level in (FULL, CORE) # --- name matching --------------------------------------------------------------- def primary_family(value: str) -> str: """The first family of a font list in the CSS style, without quotes. VS Code stores ``"'Hack Nerd Font Mono', monospace"``. The renderer tries the first family first, so MeshTerm judges that family. Args: value: The value of a font-family setting (a single name or a comma list). Returns: The first family, with the quotes and the outer whitespace removed. """ first = value.split(",")[0] return first.strip().strip("'\"").strip() def normalize_face(face: str) -> str: """Fold a face name to its form for a match: lower case, single-spaced, without quotes. Args: face: A font family name as a config file spells it. Returns: The normalized name (it can be empty). """ return " ".join(face.strip().strip("'\"").lower().split()) def match_recommended(face: str | None) -> RecommendedFont | None: """Match a configured face against the recommended-font list. A face matches an entry when it is one of the aliases of the entry, or when it extends one alias as a longer family name (``hack nerd font mono`` extends ``hack nerd font``). The generic Nerd Font rule (:data:`NERD_FONT_GENERIC`) matches the patched families that the explicit list does not name. Args: face: The configured font family (a single name or a comma list). ``None`` does nothing and is not an error. Returns: The matched :class:`RecommendedFont`, or ``None`` when the face is not known. """ if not face: return None norm = normalize_face(primary_family(face)) if not norm: return None for spec in RECOMMENDED_FONTS: if any(norm == alias or norm.startswith(alias + " ") for alias in spec.aliases): return spec if _NERD_RE.search(norm): return NERD_FONT_GENERIC return None # --- config-file reading --------------------------------------------------------- def _strip_jsonc(text: str) -> str: """Remove the ``//`` and ``/* */`` comments from JSON with comments. Strings are safe.""" out: list[str] = [] i, n = 0, len(text) in_string = False while i < n: ch = text[i] if in_string: out.append(ch) if ch == "\\" and i + 1 < n: # keep the escaped character exactly out.append(text[i + 1]) i += 2 continue if ch == '"': in_string = False i += 1 continue if ch == '"': in_string = True out.append(ch) i += 1 continue if ch == "/" and i + 1 < n and text[i + 1] == "/": while i < n and text[i] != "\n": i += 1 continue if ch == "/" and i + 1 < n and text[i + 1] == "*": i += 2 while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"): i += 1 i += 2 continue out.append(ch) i += 1 return "".join(out) def _read_jsonc(path: Path) -> dict | None: """Parse a JSONC settings file (comments, trailing commas). Return ``None`` on any failure. Windows Terminal and VS Code both write JSON with comments. A strict parser fails at the first ``//``. After the removal of the comments, which does not change strings, a regex removes the trailing commas. The regex does its best. A string that contains ``", }"`` can in theory be cut, but no font config has such a string. """ try: text = path.read_text(encoding="utf-8-sig") data = json.loads(re.sub(r",\s*([}\]])", r"\1", _strip_jsonc(text))) return data if isinstance(data, dict) else None except Exception: return None def _profile_face(profile: object) -> str | None: """The configured font face of a Windows Terminal profile. The function reads the new ``font.face`` or the legacy ``fontFace``. It returns ``None`` when the profile leaves the choice to the chain of defaults. """ if not isinstance(profile, dict): return None font = profile.get("font") if isinstance(font, dict): face = font.get("face") if isinstance(face, list) and face: # defensive: for an array face, use its first item face = face[0] if isinstance(face, str) and face.strip(): return face legacy = profile.get("fontFace") if isinstance(legacy, str) and legacy.strip(): return legacy return None def _wt_settings_paths(environ: Mapping[str, str]) -> list[Path]: """The places where Windows Terminal can keep its ``settings.json``. These are the packaged, preview, and unpackaged locations. The list has only files that exist. """ local = environ.get("LOCALAPPDATA") if not local: return [] base = Path(local) candidates: list[Path] = [] try: packages = base / "Packages" if packages.is_dir(): candidates.extend( sorted(packages.glob("Microsoft.WindowsTerminal*/LocalState/settings.json")) ) except OSError: pass candidates.append(base / "Microsoft" / "Windows Terminal" / "settings.json") return [p for p in candidates if p.is_file()] def _windows_terminal_face(environ: Mapping[str, str]) -> str: """The face that Windows Terminal uses to render this session. The function finds the face in the same way as the terminal. First it uses the font of the ``WT_PROFILE_ID`` profile. If there is none, it uses ``profiles.defaults``. If there is none, it uses the built-in default ``Cascadia Mono``. An unreadable settings file also gives the built-in default, which is the same as a new installation. """ guid = (environ.get("WT_PROFILE_ID") or "").strip().lower() for path in _wt_settings_paths(environ): data = _read_jsonc(path) if data is None: continue profiles = data.get("profiles") plist: list = [] defaults: object = {} if isinstance(profiles, dict): plist = profiles.get("list") or [] defaults = profiles.get("defaults") or {} elif isinstance(profiles, list): # the old flat-list schema plist = profiles profile = ( next( ( p for p in plist if isinstance(p, dict) and str(p.get("guid", "")).strip().lower() == guid ), None, ) if guid else None ) face = _profile_face(profile) or _profile_face(defaults) if face: return face break # a settings file that parsed but has no face: use the built-in default return "Cascadia Mono" def _vscode_settings_paths(environ: Mapping[str, str], start: Path | None) -> list[Path]: """The settings files of VS Code, the nearest first. First is the closest workspace. Then come the user files (stable and Insiders, in their locations for each platform). The list has only files that exist. """ paths: list[Path] = [] try: here = (start or Path.cwd()).resolve() for folder in (here, *here.parents): candidate = folder / ".vscode" / "settings.json" if candidate.is_file(): paths.append(candidate) break except OSError: pass roots: list[Path] = [] appdata = environ.get("APPDATA") if appdata: roots.append(Path(appdata)) home = environ.get("HOME") or environ.get("USERPROFILE") if home: roots.append(Path(home) / ".config") roots.append(Path(home) / "Library" / "Application Support") for root in roots: for flavour in ("Code", "Code - Insiders"): candidate = root / flavour / "User" / "settings.json" if candidate.is_file(): paths.append(candidate) return paths def _vscode_default_face() -> str: """The first name of the default editor font family of VS Code on this platform.""" if sys.platform == "win32": return "Consolas" if sys.platform == "darwin": return "Menlo" return "Droid Sans Mono" def _vscode_face(environ: Mapping[str, str], start: Path | None = None) -> str: """The face that the integrated terminal of VS Code uses to render. ``terminal.integrated.fontFamily`` wins over ``editor.fontFamily`` (VS Code's own fallback). For each key, the workspace file wins over the user file. The stored value is a comma list in the CSS style, and MeshTerm judges the first family. """ paths = _vscode_settings_paths(environ, start) settings = [data for data in (_read_jsonc(p) for p in paths) if data is not None] for key in ("terminal.integrated.fontFamily", "editor.fontFamily"): for data in settings: value = data.get(key) if isinstance(value, str) and value.strip(): return primary_family(value) return _vscode_default_face() def _conhost_face() -> str | None: """The face of the classic console, from ``GetCurrentConsoleFontEx``, or ``None``. The result has a meaning only on a real conhost. The caller first makes sure that there are no ConPTY markers, because the hidden conhost under Windows Terminal or VS Code reports a stub face and not the glyphs on the screen. """ if sys.platform != "win32": return None try: import ctypes import ctypes.wintypes as wintypes kernel32 = win32dll.kernel32() if not kernel32.GetConsoleWindow(): return None class _COORD(ctypes.Structure): _fields_ = [("X", wintypes.SHORT), ("Y", wintypes.SHORT)] class _CONSOLE_FONT_INFOEX(ctypes.Structure): _fields_ = [ ("cbSize", wintypes.ULONG), ("nFont", wintypes.DWORD), ("dwFontSize", _COORD), ("FontFamily", wintypes.UINT), ("FontWeight", wintypes.UINT), ("FaceName", ctypes.c_wchar * 32), ] info = _CONSOLE_FONT_INFOEX() info.cbSize = ctypes.sizeof(_CONSOLE_FONT_INFOEX) handle = kernel32.GetStdHandle(-11) # STD_OUTPUT_HANDLE if not kernel32.GetCurrentConsoleFontEx(handle, False, ctypes.byref(info)): return None return info.FaceName or None except Exception: return None # --- the ladder ------------------------------------------------------------------- def detect_terminal_font( environ: Mapping[str, str] | None = None, *, cwd: Path | None = None, conhost_probe: Callable[[], str | None] = _conhost_face, ) -> FontDetection | None: """Identify the terminal and read the font that it is configured to render with. The ladder goes from the most certain to the least certain source: * Windows Terminal. ``WT_SESSION`` names the app and ``WT_PROFILE_ID`` names the exact profile. * VS Code (``TERM_PROGRAM=vscode``). * A real classic conhost, which the function asks directly through Win32. It has no ConPTY markers and no ``TERM``. A ``TERM`` that is set means that another emulator hosts the console. For all other cases the result is ``None``, for example an unrecognized terminal or an ssh session. MeshTerm cannot know the face from here. Args: environ: The environment to examine (the default is ``os.environ``). cwd: Where the search for the VS Code workspace starts (the default is the cwd of the process). conhost_probe: The function that reads the face of the classic console (a parameter, so that tests can replace it). Returns: The configured face and its source, or ``None`` when no source applies. """ env = os.environ if environ is None else environ if env.get("WT_SESSION"): return FontDetection(_windows_terminal_face(env), "windows-terminal") if (env.get("TERM_PROGRAM") or "").lower() == "vscode": return FontDetection(_vscode_face(env, cwd), "vscode") if not env.get("TERM") and not env.get("TERM_PROGRAM"): face = conhost_probe() if face: return FontDetection(face, "conhost") return None def _renderer_backed(environ: Mapping[str, str]) -> str | None: """The terminal id, when the terminal draws the core triangles itself. Windows Terminal falls back to its bundled Cascadia Code NF for the powerline symbol ranges (version 1.22 and later). The terminal of VS Code draws them as custom glyphs (``terminal.integrated.customGlyphs``, on by default). kitty, WezTerm, and Alacritty have built-in powerline glyphs. In these terminals, the separators render in any configured font. """ if environ.get("WT_SESSION"): return "windows-terminal" term_program = (environ.get("TERM_PROGRAM") or "").lower() if term_program == "vscode": return "vscode" if term_program == "wezterm" or environ.get("WEZTERM_EXECUTABLE"): return "wezterm" if environ.get("KITTY_WINDOW_ID") or environ.get("TERM") == "xterm-kitty": return "kitty" if ( environ.get("ALACRITTY_WINDOW_ID") or environ.get("ALACRITTY_SOCKET") or environ.get("TERM") == "alacritty" ): return "alacritty" return None #: The glyphs that the path widget draws at ``core``: the solid triangle that each seam #: is, and the thin triangle that joins two fills that the eye cannot tell apart #: (:mod:`~meshterm.ui.pathline`). _CORE_GLYPHS = (0xE0B0, 0xE0B1) #: What ``full`` adds that the widget uses: the rounded caps that replace the square ends #: of a path. _FULL_GLYPHS = (0xE0B4, 0xE0B6) def _inventory_coverage(inventory: frozenset[int]) -> str: """The level of coverage that a known glyph inventory has. The result is not a guess, because the inventory lists all the glyphs. """ if not all(code in inventory for code in _CORE_GLYPHS): return NONE return FULL if all(code in inventory for code in _FULL_GLYPHS) else CORE def _powerline_support( environ: Mapping[str, str] | None = None, *, cwd: Path | None = None, conhost_probe: Callable[[], str | None] = _conhost_face, handheld: tuple[str, frozenset[int]] | None = None, ) -> PowerlineSupport: """The verdict without the cache (refer to :func:`powerline_support` for the ladder). Args: environ: The environment to examine (the default is ``os.environ``). cwd: Where the search for the VS Code workspace starts (the default is the cwd of the process). conhost_probe: The function that reads the face of the classic console (a parameter, so that tests can replace it). handheld: The name and the glyph inventory of the platform, where the font of a handheld itself draws the screen. ``None`` on a terminal. """ env = os.environ if environ is None else environ override = (env.get("MESHTERM_POWERLINE") or "").strip().lower() if override in {"0", "off", "no", "none", "false"}: return PowerlineSupport(NONE, "env") if override in {"1", "on", "yes", "true", "full"}: return PowerlineSupport(FULL, "env") if override == "core": return PowerlineSupport(CORE, "env") if handheld is not None: name, inventory = handheld return PowerlineSupport(_inventory_coverage(inventory), f"platform:{name}") detected = detect_terminal_font(env, cwd=cwd, conhost_probe=conhost_probe) matched = match_recommended(detected.face) if detected else None if detected and matched: return PowerlineSupport(matched.coverage, f"font:{detected.source}", detected.face, matched) backed = _renderer_backed(env) if backed: return PowerlineSupport(CORE, f"renderer:{backed}", detected.face if detected else None) if detected: # MeshTerm read a face, it matches nothing, and the terminal has no fallback return PowerlineSupport(NONE, f"font:{detected.source}", detected.face) if env.get("SSH_CONNECTION") or env.get("SSH_TTY") or env.get("SSH_CLIENT"): return PowerlineSupport(UNKNOWN, "ssh") return PowerlineSupport(UNKNOWN, "unknown") @lru_cache(maxsize=1) def powerline_support() -> PowerlineSupport: """The powerline verdict of the session. MeshTerm decides it one time and caches it. The ladder has these steps, in this order: * The ``MESHTERM_POWERLINE`` override. * The own font inventory of a handheld platform. * The configured font, matched against :data:`RECOMMENDED_FONTS`. * A renderer that draws the glyphs itself. * ``none`` (MeshTerm read the face, but there is no match and no fallback) or ``unknown`` (an ssh session, or a terminal that MeshTerm cannot identify). The result is cached, because the environment and the settings files do not change during a session. A switch of platform clears the cache (:func:`_bind`). Tests call :func:`_powerline_support` directly. Returns: The :class:`PowerlineSupport` verdict. """ return _powerline_support(os.environ, handheld=_HANDHELD_FONT) def powerline_enabled() -> bool: """Check if path lines must use powerline separators by default (refer to ``.capable``).""" return powerline_support().capable def powerline_full() -> bool: """Check if the extended block is also present: the rounded caps at U+E0B4 and later. Only a Nerd Font patch has these glyphs. Thus this check is narrower than :func:`powerline_enabled`. A stock coder font (Fira Code, JetBrains Mono) draws the core triangles natively and no other glyph. A terminal that supplies the separators from its own renderer promises only those four glyphs. Callers use this check for chrome that must degrade. When it is true, :mod:`~meshterm.ui.pathline` rounds the two outer ends of a path. When it is false, the module squares them off. """ return powerline_support().level == FULL #: The name and the glyph inventory of the active handheld, or ``None`` where a terminal #: draws all that it receives. MeshTerm binds it when the platform switches (:func:`_bind`). _HANDHELD_FONT: tuple[str, frozenset[int]] | None = None @on_platform def _bind(platform: Platform) -> None: """Bind the handheld font that the verdict reads, and clear the verdict of the last font.""" global _HANDHELD_FONT inventory = FONTS.get(platform.font) _HANDHELD_FONT = (platform.name, inventory) if inventory is not None else None powerline_support.cache_clear() # --- installed-font scan ---------------------------------------------------------- def _installed_families() -> Iterable[str]: """All the installed font family names that this platform reports. It does its best.""" if sys.platform == "win32": try: import winreg for root in (winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER): try: key = winreg.OpenKey( root, r"SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts" ) except OSError: continue with key: for i in range(winreg.QueryInfoKey(key)[1]): try: name = winreg.EnumValue(key, i)[0] except OSError: break # "Hack Nerd Font Mono (TrueType)" → "Hack Nerd Font Mono" yield name.split(" (")[0] except Exception: return return try: import subprocess result = subprocess.run( ["fc-list", ":", "family"], capture_output=True, text=True, timeout=2 ) for line in result.stdout.splitlines(): for family in line.split(","): if family.strip(): yield family.strip() except Exception: return def installed_recommended() -> RecommendedFont | None: """The best recommended font that is installed on this machine, selected or not. This check is weaker, but it is always available. A future screen of recommendations can use it to choose between three messages: "not installed — here's the list", "installed but not selected in your terminal's profile", and "active". The function prefers :data:`FULL` coverage to :data:`CORE`. It returns ``None`` when no recommended font is installed, or when the platform has no way to ask. """ best: RecommendedFont | None = None for family in _installed_families(): matched = match_recommended(family) if matched is None: continue if matched.coverage == FULL: return matched best = best or matched return best # --- emoji support ---------------------------------------------------------------- @dataclass(frozen=True) class EmojiSupport: """The verdict if this terminal can show an emoji at all, and what decided it. Attributes: supported: ``True`` when an emoji icon reaches the screen as the emoji. source: ``"env"`` (the ``MESHTERM_EMOJI`` override), ``"platform"`` (not Windows, so the problem of the classic console does not apply), ``"console"`` (the host was identified, refer to :func:`_is_classic_console`), or ``"no-console"`` (there is nothing to identify: the output is redirected, or the call failed). """ supported: bool source: str def _is_classic_console() -> bool | None: """Check if this process draws into a real ``conhost`` window. This is the whole question. That host renders through GDI with the console font and has no emoji font behind it. All the hosts that replaced it draw emoji correctly. These are Windows Terminal, the terminal of VS Code, and anything over ssh. MeshTerm cannot ask in band. A missing glyph still occupies its cell, so the screen reads back the same as if the character had drawn. We measured this on Windows 10 22H2. A classic console stores ``📡`` correctly and advances two cells, but it shows a single replacement box. A ConPTY (which does draw the emoji) reads back as U+FFFD, because the buffer behind it is updated asynchronously. A probe that writes and reads back gives the wrong answer for both hosts. This docstring records this trap. MeshTerm also cannot trust the environment alone. Child processes inherit ``WT_SESSION``. A program that starts from Windows Terminal into a console of its own still has it, and the answer is for the wrong host. So MeshTerm identifies the host from its structure, with two independent facts. Both facts must agree before MeshTerm dims anything. The costly mistake is to remove the icons from a terminal that can draw them. * **The console font has a real pixel width.** The hidden conhost of a ConPTY reports a stub (face ``Consolas``, cell width ``0``), because it rasterizes nothing. * **The buffer is taller than its window.** A classic console owns its scrollback (9001 rows by default). Under a ConPTY the terminal owns the scrollback, so the buffer is the same as the window. Returns: ``True`` for a real classic console. ``False`` for all other hosts that draw to a console. ``None`` when there is no console on stdout (the output is redirected, the platform is not Windows, or the call failed). An unknown result is never a reason to degrade. """ if sys.platform != "win32": return None try: import ctypes from ctypes import wintypes class _COORD(ctypes.Structure): _fields_ = [("X", wintypes.SHORT), ("Y", wintypes.SHORT)] class _SMALL_RECT(ctypes.Structure): _fields_ = [ ("Left", wintypes.SHORT), ("Top", wintypes.SHORT), ("Right", wintypes.SHORT), ("Bottom", wintypes.SHORT), ] class _CSBI(ctypes.Structure): _fields_ = [ ("dwSize", _COORD), ("dwCursorPosition", _COORD), ("wAttributes", wintypes.WORD), ("srWindow", _SMALL_RECT), ("dwMaximumWindowSize", _COORD), ] class _CONSOLE_FONT_INFOEX(ctypes.Structure): _fields_ = [ ("cbSize", wintypes.ULONG), ("nFont", wintypes.DWORD), ("dwFontSize", _COORD), ("FontFamily", wintypes.UINT), ("FontWeight", wintypes.UINT), ("FaceName", ctypes.c_wchar * 32), ] # It is safe to declare these types, because this handle is only ours (refer to # meshterm.core.win32dll). The explicit restype is important. Without it, ctypes # assumes a 32-bit int and cuts the 64-bit HANDLE, and each later call fails # without a message. kernel32 = win32dll.kernel32() kernel32.GetStdHandle.argtypes = [wintypes.DWORD] kernel32.GetStdHandle.restype = wintypes.HANDLE kernel32.GetConsoleScreenBufferInfo.argtypes = [wintypes.HANDLE, ctypes.POINTER(_CSBI)] kernel32.GetConsoleScreenBufferInfo.restype = wintypes.BOOL kernel32.GetCurrentConsoleFontEx.argtypes = [ wintypes.HANDLE, wintypes.BOOL, ctypes.POINTER(_CONSOLE_FONT_INFOEX), ] kernel32.GetCurrentConsoleFontEx.restype = wintypes.BOOL handle = kernel32.GetStdHandle(wintypes.DWORD(-11).value) # STD_OUTPUT_HANDLE info = _CSBI() # This call fails when stdout is a pipe or a file. Then MeshTerm draws nothing and # there is no answer. This is the reason that redirected runs and CI runs do not # use the rest of this function. if not kernel32.GetConsoleScreenBufferInfo(handle, ctypes.byref(info)): return None font = _CONSOLE_FONT_INFOEX() font.cbSize = ctypes.sizeof(_CONSOLE_FONT_INFOEX) if not kernel32.GetCurrentConsoleFontEx(handle, False, ctypes.byref(font)): return None rasterised = font.dwFontSize.X > 0 owns_scrollback = info.dwSize.Y > (info.srWindow.Bottom - info.srWindow.Top + 1) return rasterised and owns_scrollback except Exception: # pragma: no cover - a probe that fails gives an unknown result, not a crash return None def _emoji_support( environ: Mapping[str, str] | None = None, *, console_probe: Callable[[], bool | None] = _is_classic_console, system: str | None = None, ) -> EmojiSupport: """The verdict without the cache (refer to :func:`emoji_support` for the ladder).""" env = os.environ if environ is None else environ override = (env.get("MESHTERM_EMOJI") or "").strip().lower() if override in {"0", "off", "no", "none", "false"}: return EmojiSupport(False, "env") if override in {"1", "on", "yes", "true"}: return EmojiSupport(True, "env") if (sys.platform if system is None else system) != "win32": return EmojiSupport(True, "platform") classic = console_probe() if classic is None: return EmojiSupport(True, "no-console") return EmojiSupport(not classic, "console") @lru_cache(maxsize=1) def classic_console() -> bool: """Check if this session draws into a real ``conhost`` window. This is the only host that has no font fallback of its own. Thus it is the only host where the glyphs of the configured font decide what the user sees. Refer to :func:`_is_classic_console` for how MeshTerm identifies it, and why it does not use the environment. """ return _is_classic_console() is True @lru_cache(maxsize=1) def emoji_support() -> EmojiSupport: """Check if emoji icons can be drawn here. MeshTerm decides one time and caches it. The ladder has these steps, in this order: the ``MESHTERM_EMOJI`` override, then all platforms that are not Windows (where a UTF-8 terminal draws emoji correctly), then :func:`_is_classic_console`. The result is cached, because a session does not change its host during the session. Returns: The :class:`EmojiSupport` verdict. """ return _emoji_support(os.environ) def emoji_enabled() -> bool: """Check if icons must render as emoji instead of through the compact table.""" return emoji_support().supported # --- chart glyphs ----------------------------------------------------------------- #: The families that we measured to have the Braille Patterns block (U+2800–U+28FF). #: :mod:`meshterm.ui.braillechart` draws each timeline from this block. #: #: The list is short on purpose. Each entry is a measurement, not a reputation. On #: 2026-09-07 we read the ``cmap`` of each font that is installed on a development #: machine. Almost no monospace font has the block. Hack Nerd Font, JetBrains Mono, Fira #: Code, Source Code Pro, Consolas, Lucida Console, and DejaVu Sans *Mono* (a surprise) #: all measure zero of 256. DejaVu *Sans* is proportional, and it has all 256. This is #: the source of the common advice "install DejaVu for braille". The advice works only #: because terminals fall back from the mono face to the proportional face for that #: block. #: #: This is the important point. On each host that falls back (Windows Terminal, the #: terminal of VS Code, macOS, Linux), the charts draw in any chosen font. Thus this list #: does not have to be correct there. It matters on the one host that has no fallback, the #: classic Windows console. There, a font that is not in this list gives boxes where the #: charts must be. CHART_FONTS: tuple[str, ...] = ( # The console font of Microsoft: 44/44, and the family that MeshTerm bundles (refer to # meshterm.core.consolefont). The prefix also matches the PL and NF builds. "cascadia mono", "cascadia code", # The Nerd Font patches of the same fonts. They keep what they patch. "caskaydiacove", "caskaydiamono", # Many reports say that it has the block. We did not measure it, because we have no # copy. "iosevka", ) def face_draws_charts(face: str | None) -> bool: """Check if ``face`` can draw the braille that the timelines use. Args: face: A configured font family, in any spelling, or ``None``. Returns: ``True`` if it is one of :data:`CHART_FONTS`. """ if not face: return False normal = normalize_face(face) return any(normal.startswith(known) for known in CHART_FONTS) def installed_chart_font() -> str | None: """The first installed family that can draw the charts, or ``None``. The result decides between two actions: "select the font that the user already has" (each Windows 11 machine, and each user who installed Windows Terminal) and "offer to install our font". Returns: The family name as installed, or ``None`` when no installed family can do it. """ for family in _installed_families(): if face_draws_charts(family): return family return None