"""Terminal capability detection — what can this terminal actually draw? Two questions, both answered out-of-band because a terminal cannot be asked in-band: a glyph it does not have still occupies its cell, so the screen looks the same whether the character arrived or not. **Powerline separators**, below, are a *font* question — read the terminal's configured face and match it against fonts known to carry the block. **Emoji** (:func:`emoji_support`) are a *host* question, and only on Windows. The classic console — ``conhost``, which is what a double-clicked program still gets — rasterises through GDI with the console font and nothing behind it, so an emoji lands as a replacement box however the font is configured. Everything that replaced it draws them fine. So the verdict identifies the host, structurally rather than from the environment (``WT_SESSION`` is inherited across process launches, so a program started from Windows Terminal into a console of its own still claims to be in one), and a ``False`` routes every icon through the compact single-glyph table :func:`meshterm.ui.theme.glyph` already keeps for the PicoCalc — that whole vocabulary is BMP, so it draws wherever the plain status marks already do. Both verdicts are hints that pick a default, and both have an override for the reader who knows better than the probe: ``MESHTERM_POWERLINE`` and ``MESHTERM_EMOJI``. The path-line widget (:mod:`~meshterm.ui.pathline`) can render a hop sequence as interlocking powerline segments — each hop a colour-filled chip, joined by the solid triangle U+E0B0 whose foreground is the previous chip's fill and whose background is the next's, the oh-my-posh look. That triangle lives in the Private Use Area, so it only draws when the *terminal's configured font* (or the terminal itself) supplies the glyph; a font without it shows tofu boxes. Nothing in-band can ask "do you have this glyph?" — a missing glyph still occupies its cell, so even cursor-position probes see nothing — which makes this an *out-of-band* detection problem: identify the terminal, read its configuration, and match the configured face against fonts known to carry the powerline block. Three sources of truth, in confidence order: * **An explicit override** — ``MESHTERM_POWERLINE`` (``1``/``full``, ``core``, ``0``/``off``) always wins, the same gate pattern as ``MESHTERM_FULL_WIDTH``. The user knows their glass better than any probe. * **The configured font**, resolved per terminal: Windows Terminal (``WT_SESSION`` + ``WT_PROFILE_ID`` → the profile's ``font.face`` in ``settings.json``), VS Code's integrated terminal (``TERM_PROGRAM=vscode`` → ``terminal.integrated.fontFamily``, workspace over user, falling back to ``editor.fontFamily``), and classic conhost (``GetCurrentConsoleFontEx`` — trusted only when no ConPTY host is detected, because the hidden conhost under one reports a stub face, not what's on screen). The face is matched against :data:`RECOMMENDED_FONTS` — the list MeshTerm recommends to users — with the alias spellings Nerd Fonts ship under (``Hack Nerd Font Mono`` / ``Hack NFM``), plus a generic "any Nerd Font" rule, since every Nerd Font patch carries the full powerline block. * **The terminal's own renderer**: several terminals draw the core triangles regardless of font — Windows Terminal falls back to its bundled Cascadia Code NF for the symbol ranges (≥ 1.22), VS Code's terminal draws them as custom glyphs (``terminal.integrated.customGlyphs``, default on), and kitty / WezTerm / Alacritty ship built-in powerline glyphs. Those count as ``core`` support even when the configured font matches nothing. Coverage comes in two levels: ``full`` (a Nerd Font patch — triangles *and* the extended block: rounded caps, slants) and ``core`` (just U+E0B0–U+E0B3, which many stock coder fonts — Fira Code, JetBrains Mono, Source Code Pro — include natively). The path widget only uses the core triangle, so ``core`` is enough to switch it on; ``full`` is headroom for fancier chrome. When nothing can be known — an ssh session (the font lives on the far client's machine), an unrecognised terminal — the verdict is honestly ``unknown`` and callers should keep the plain-arrow rendering. Every probe is best-effort: unreadable settings, missing registry keys, or a failed Win32 call degrade the verdict, never raise. The result is a *hint that picks a default*, not a gate the user has to 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 #: Coverage levels a verdict (or a recommended font) can carry, strongest first. FULL = "full" CORE = "core" NONE = "none" UNKNOWN = "unknown" @dataclass(frozen=True) class RecommendedFont: """One font MeshTerm recommends for powerline path rendering. Attributes: name: The canonical display name (what a recommendation screen shows). aliases: Normalised name prefixes that identify the family — every spelling a terminal config might hold, lower-case with collapsed spaces (Nerd Fonts deliberately ship several: ``hack nerd font mono`` and ``hack nfm`` are the same file). coverage: :data:`FULL` when the family carries the whole powerline block (Nerd Font patches), :data:`CORE` when it ships just the four triangles. """ name: str aliases: tuple[str, ...] coverage: str #: The fonts MeshTerm recommends, full-coverage Nerd Fonts first — order matters, the #: first alias hit wins, so ``JetBrainsMono Nerd Font`` must match its ``full`` entry #: before the plain ``JetBrains Mono`` prefix could 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 the explicit list doesn't spell out: any family #: whose name carries the Nerd Font branding — the long ``… Nerd Font [Mono|Propo]`` #: or the v3 short suffixes ``NF``/``NFM``/``NFP`` — has the full powerline block. 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 which terminal it was read from. Attributes: face: The font family name as configured (unnormalised). source: ``"windows-terminal"``, ``"vscode"``, or ``"conhost"``. """ face: str source: str @dataclass(frozen=True) class PowerlineSupport: """The verdict: how confidently this terminal can draw powerline separators. Attributes: level: :data:`FULL`, :data:`CORE`, :data:`NONE`, or :data:`UNKNOWN`. source: What decided it — ``"env"`` (the override), ``"font:"`` (a configured face matched, or definitively didn't), ``"renderer:"`` (the terminal draws the glyphs itself), ``"ssh"`` (the font lives on the far client, unknowable), or ``"unknown"``. face: The configured face when one was found, for the curious. matched: The recommended-list entry the face matched, if any. """ level: str source: str face: str | None = None matched: RecommendedFont | None = None @property def capable(self) -> bool: """Whether the core triangle (all 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 CSS-style font list, unquoted. VS Code stores ``"'Hack Nerd Font Mono', monospace"``; the first family is the one the renderer tries first, so it is the one we judge. Args: value: A font-family setting value (single name or comma list). Returns: The first family with quotes and outer whitespace stripped. """ first = value.split(",")[0] return first.strip().strip("'\"").strip() def normalize_face(face: str) -> str: """Fold a face name to its matchable form: lower-case, single-spaced, unquoted. Args: face: A font family name as a config file spells it. Returns: The normalised name (may 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 entry's aliases or extends one as a longer family name (``hack nerd font mono`` extends ``hack nerd font``); the generic Nerd Font rule (:data:`NERD_FONT_GENERIC`) catches patched families the explicit list doesn't spell out. Args: face: The configured font family (single name or comma list); ``None`` is a polite no-op. Returns: The matched :class:`RecommendedFont`, or ``None`` when the face is unknown. """ 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: """Strip ``//`` and ``/* */`` comments from JSON-with-comments, string-safely.""" 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 char verbatim 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), ``None`` on any failure. Both Windows Terminal and VS Code write JSON-with-comments; a strict parser dies on the first ``//``. Trailing commas are swept with a best-effort regex after the string-aware comment strip (a *string* containing ``", }"`` could theoretically be clipped — no font config holds one). """ 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: """A Windows Terminal profile's configured font face. Reads the new ``font.face`` or the legacy ``fontFace``, and answers ``None`` when the profile leaves the choice to the defaults chain. """ 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: an array face takes its head 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]: """Where Windows Terminal might keep its ``settings.json``. The packaged, preview, and unpackaged locations — existing files only. """ 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 Windows Terminal is rendering this session with. Resolved the way the terminal itself does: the ``WT_PROFILE_ID`` profile's font, else ``profiles.defaults``, else the built-in default ``Cascadia Mono``. An unreadable settings file lands on the built-in default too — a pristine install is exactly that. """ 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 ancient 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 parsed settings file with no face set → the built-in default return "Cascadia Mono" def _vscode_settings_paths(environ: Mapping[str, str], start: Path | None) -> list[Path]: """VS Code's settings files, nearest first. The closest workspace, then the user's own (stable and Insiders, in their per-platform locations) — existing files only. """ 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: """VS Code's per-platform default editor font family's first name.""" 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 VS Code's integrated terminal is rendering with. ``terminal.integrated.fontFamily`` wins over ``editor.fontFamily`` (VS Code's own fallback), and within each key the workspace file wins over the user file. The stored value is a CSS-style comma list; the first family is judged. """ 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 classic-console face via ``GetCurrentConsoleFontEx``, or ``None``. Only meaningful on a *genuine* conhost — the caller gates on the absence of ConPTY markers first, because the hidden conhost under Windows Terminal / VS Code reports a stub face, not the glyphs on 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 it is configured to render with. The ladder, most to least certain: Windows Terminal (``WT_SESSION`` names the app, ``WT_PROFILE_ID`` the exact profile), VS Code (``TERM_PROGRAM=vscode``), then a genuine classic conhost (no ConPTY markers, no ``TERM`` — a set ``TERM`` means some other emulator is hosting the console) asked directly via Win32. Anything else — an unrecognised terminal, an ssh session — is ``None``: the face is unknowable from here. Args: environ: The environment to inspect (defaults to ``os.environ``). cwd: Where the VS Code workspace walk starts (defaults to the process cwd). conhost_probe: The classic-console face reader (injectable for tests). 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 (≥ 1.22), VS Code's terminal draws them as custom glyphs (``terminal.integrated.customGlyphs``, default on), and kitty / WezTerm / Alacritty ship built-in powerline glyphs — on those, the separators render whatever the configured font holds. """ 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 def _powerline_support( environ: Mapping[str, str] | None = None, *, cwd: Path | None = None, conhost_probe: Callable[[], str | None] = _conhost_face, ) -> PowerlineSupport: """The uncached verdict (see :func:`powerline_support` for the ladder).""" 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") 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: # a face we could read, matching nothing, on a terminal with 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 session's powerline verdict, decided once and cached. The ladder: the ``MESHTERM_POWERLINE`` override, then the configured font matched against :data:`RECOMMENDED_FONTS`, then a renderer that draws the glyphs itself, then an honest ``none`` (face read, no match, no fallback) or ``unknown`` (ssh, or a terminal we can't identify). Cached because the environment and settings files don't change mid-session; tests exercise :func:`_powerline_support` directly. Returns: The :class:`PowerlineSupport` verdict. """ return _powerline_support(os.environ) def powerline_enabled() -> bool: """Whether path lines should default to powerline separators (see ``.capable``).""" return powerline_support().capable def powerline_full() -> bool: """Whether the *extended* block is there too — the rounded caps at U+E0B4+. Only a Nerd Font patch carries them, so this is strictly narrower than :func:`powerline_enabled`: a stock coder font (Fira Code, JetBrains Mono) draws the core triangles natively and nothing beyond, and a terminal that supplies the separators from its own renderer is only promising those four. Callers use it for chrome that must degrade — :mod:`~meshterm.ui.pathline` rounds a path's two outer ends when it is true and squares them off when it isn't. """ return powerline_support().level == FULL # --- installed-font scan ---------------------------------------------------------- def _installed_families() -> Iterable[str]: """Every installed font family name this platform will admit to, best-effort.""" 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 *installed* on this machine, selected or not. The weaker, always-available check that a future recommendation screen splits its message on: "not installed — here's the list" versus "installed but not selected in your terminal's profile" versus "active". Prefers :data:`FULL` coverage over :data:`CORE`; returns ``None`` when nothing recommended is installed (or the platform offers 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: """Whether this terminal can show an emoji at all, and what decided that. Attributes: supported: ``True`` when an emoji icon reaches the screen as itself. source: ``"env"`` (the ``MESHTERM_EMOJI`` override), ``"platform"`` (not Windows, so not the classic console's problem), ``"console"`` (the host was identified — see :func:`_is_classic_console`), or ``"no-console"`` (nothing to identify: output is redirected, or the call failed). """ supported: bool source: str def _is_classic_console() -> bool | None: """Whether this process is drawing into a genuine ``conhost`` window. Which is the whole question, because that host renders through GDI with the console font and no emoji font behind it, while everything that replaced it — Windows Terminal, VS Code's terminal, anything over ssh — draws emoji as a matter of course. It cannot be asked in band. A missing glyph still occupies its cell, so the screen reads back exactly as it would have if the character had drawn: measured on Windows 10 22H2, a classic console stores ``📡`` intact and advances two cells while showing a single replacement box, and a ConPTY (which does draw it) reads back as U+FFFD because the buffer behind it is updated asynchronously. A write-and-read-back probe answers both hosts *backwards*, which is the trap this docstring exists to record. Nor can the environment be trusted alone: ``WT_SESSION`` is inherited by child processes, so a program launched from Windows Terminal into a console of its own still carries it and would answer for the wrong host. So the host is identified structurally, from two independent facts, and both must agree before anything is dimmed (the costly mistake is stripping icons from a terminal that could draw them): * **The console font has a real pixel width.** A ConPTY's hidden conhost reports a stub — face ``Consolas``, cell width ``0`` — because nothing is rasterised there. * **The buffer is taller than its window.** A classic console owns its scrollback (9001 rows by default); under a ConPTY the terminal owns it, so the buffer is exactly the window. Returns: ``True`` for a genuine classic console, ``False`` for anything else drawing to a console, and ``None`` when there is no console on stdout (redirected output, not Windows, or the call failed) — an unknown 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), ] # Safe to declare: this handle is ours alone (see meshterm.core.win32dll). The # explicit restype matters — ctypes would assume a 32-bit int and truncate the # 64-bit HANDLE, turning every later call into a silent failure. 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() # Fails when stdout is a pipe or a file — nothing is being drawn, so there is # nothing to answer, and this is what keeps redirected and CI runs out of it. 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 is an unknown, 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 uncached verdict (see :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: """Whether this session is drawing into a genuine ``conhost`` window. The one host with no font fallback of its own, so the only one where the configured font's own repertoire decides what the reader sees. See :func:`_is_classic_console` for how it is identified, and why not from the environment. """ return _is_classic_console() is True @lru_cache(maxsize=1) def emoji_support() -> EmojiSupport: """Whether emoji icons can be drawn here, decided once and cached. The ladder: the ``MESHTERM_EMOJI`` override, then everything that isn't Windows (where a UTF-8 terminal draws them as a matter of course), then :func:`_is_classic_console`. Cached because a session does not change host halfway through. Returns: The :class:`EmojiSupport` verdict. """ return _emoji_support(os.environ) def emoji_enabled() -> bool: """Whether icons should render as emoji rather than through the compact table.""" return emoji_support().supported # --- chart glyphs ----------------------------------------------------------------- #: Families measured to carry the Braille Patterns block (U+2800–U+28FF) that #: :mod:`meshterm.ui.braillechart` draws every timeline from. #: #: The list is short on purpose, and each entry is a measurement rather than a #: reputation: reading the ``cmap`` of every font installed on a development machine #: (2026-09-07) found that nearly no monospace font carries the block at all. Hack Nerd #: Font, JetBrains Mono, Fira Code, Source Code Pro, Consolas, Lucida Console and — the #: surprise — DejaVu Sans *Mono* all measure zero of 256. DejaVu *Sans*, which is #: proportional, carries all 256, which is where the widespread "install DejaVu for #: braille" advice comes from: it works only because terminals fall back from the mono #: face to the proportional one for that block. #: #: Which is the point. On every host that falls back — Windows Terminal, VS Code's #: terminal, macOS, Linux — the charts draw whatever the chosen font holds, so this list #: never has to be right. It matters on the one host with no fallback at all, the classic #: Windows console, where a font outside this list means boxes where the charts should be. CHART_FONTS: tuple[str, ...] = ( # Microsoft's console font: 44/44, and the family MeshTerm bundles (see # meshterm.core.consolefont). Covers the PL and NF builds by prefix. "cascadia mono", "cascadia code", # The Nerd Font patches of the same, which keep what they patch. "caskaydiacove", "caskaydiamono", # Widely reported to carry the block; not measured here, no copy to hand. "iosevka", ) def face_draws_charts(face: str | None) -> bool: """Whether ``face`` can draw the braille the timelines are made of. Args: face: A configured font family, in any spelling, or ``None``. Returns: Whether 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``. What separates "select the font they already have" — every Windows 11 machine, and anyone who has installed Windows Terminal — from "offer to install ours". Returns: The family name as installed, or ``None`` when nothing installed can do it. """ for family in _installed_families(): if face_draws_charts(family): return family return None