MeshTerm/meshterm/ui/tui/render.py

"""The single Rich-to-prompt_toolkit bridge.

The TUI keeps rendering in Rich (all existing tables, panels, and text widgets are reused
verbatim) and lets prompt_toolkit own the terminal, input, and resize events. This module
is the seam between the two: it renders any Rich renderable to an ANSI string at a chosen
width, which prompt_toolkit then draws via :class:`prompt_toolkit.formatted_text.ANSI`.

Because rendering is redone at the *current* width on every repaint, content reflows
automatically when the terminal is resized.
"""

from __future__ import annotations

from collections import OrderedDict
from io import StringIO

from rich.cells import cell_len
from rich.console import Console, RenderableType
from rich.text import Span, Text

from ...platforms import Platform, on_platform
from ..pathline import PATH_INK
from ..theme import active_theme, fold_text, is_identity_style

#: Cache one headless render console per width. Consoles are cheap but repaint happens on
#: every keystroke and on the live-monitor timer, so caching avoids needless churn. Keyed
#: by width because a console's width is fixed at construction; emptied whenever the
#: platform switches, since the theme and colour system are baked in at construction.
_CONSOLES: dict[int, Console] = {}

#: The colour depth the rasterizer emits at — bound per platform. ``"standard"`` on the
#: 16-slot console: the theme's ``color(N)`` styles pass through as exact slot indices,
#: and any stray truecolor (a node hue, a map feature) is downsampled by Rich to the
#: nearest conventional slot — which the palette deliberately keeps hue-aligned (see
#: ``theme._VT_SLOTS``), so even strays land in their own colour family.
_COLOR_SYSTEM = "truecolor"


#: Memoized ANSI per (content, width) for the *describable* renderables — a ``str`` or a
#: :class:`Text`, whose rendering is a pure function of their plain text, spans, and flags.
#: The TUI recomposes the whole frame on every keystroke and on the idle tick, and the
#: list-family screens rasterize row by row through :func:`render_to_ansi`; between two
#: paints almost every row is byte-identical, so this cache turns the per-row console
#: render (~0.15 ms each) into a dict hit. Tables, panels and groups have no cheap content
#: key and skip the cache (their callers memoize at their own level where it matters).
_ANSI_CACHE: OrderedDict[tuple, str] = OrderedDict()

#: Entries the ANSI cache holds before evicting least-recently-used ones. Sized for a few
#: screenfuls of distinct rows (a busy list, its filtered variants, a dialog over it) at
#: well under ~2 MB; small enough that even the PicoCalc carries it without noticing.
_ANSI_CACHE_MAX = 4096

#: Generation stamp folded into every cache key. A platform switch swaps the theme and
#: colour system baked into the render consoles, so it bumps the generation instead of
#: trusting eviction — a stale entry can then never be *read*, even mid-eviction.
_CACHE_GEN = 0


@on_platform
def _bind(platform: Platform) -> None:
    """Re-bind the rasterizer's colour depth and drop stale consoles on a switch."""
    global _COLOR_SYSTEM, _CACHE_GEN
    _COLOR_SYSTEM = "truecolor" if platform.truecolor else "standard"
    _CONSOLES.clear()
    _ANSI_CACHE.clear()
    _CACHE_GEN += 1


def _cache_key(renderable: RenderableType, width: int, no_wrap: bool) -> tuple | None:
    """A content key for a cacheable renderable, or ``None`` when it has no cheap one.

    A ``str`` *is* its own content (markup included). A :class:`Text` renders as a pure
    function of its plain text, span list, base style, and wrap flags — everything the
    key captures (span styles via ``str``, which :class:`~rich.style.Style` memoizes).
    Anything else — a table, a group, a panel — would need a deep walk to describe, so it
    reports ``None`` and renders uncached.
    """
    if isinstance(renderable, str):
        return ("s", renderable, width, no_wrap, _CACHE_GEN)
    if isinstance(renderable, Text):
        return (
            "t",
            renderable.plain,
            tuple((s.start, s.end, str(s.style)) for s in renderable.spans),
            str(renderable.style),
            renderable.no_wrap,
            renderable.overflow,
            renderable.justify,
            renderable.tab_size,
            width,
            no_wrap,
            _CACHE_GEN,
        )
    return None


def _console(width: int) -> Console:
    """Return a themed, headless console that emits ANSI at the given width.

    Args:
        width: Target render width in columns.

    Returns:
        A cached :class:`rich.console.Console` writing to an internal buffer.
    """
    console = _CONSOLES.get(width)
    if console is None:
        console = Console(
            theme=active_theme(),
            width=width,
            file=StringIO(),
            force_terminal=True,
            color_system=_COLOR_SYSTEM,
            # This console is a rasterizer, not terminal output: its ANSI is re-parsed
            # by prompt_toolkit, and the TUI's hues are semantics (node identity,
            # recency heat), not decoration. So a NO_COLOR environment must not strip
            # them here — the scripted CLI's real console (theme.build_console) is the
            # one that honours NO_COLOR.
            no_color=False,
            highlight=False,
            soft_wrap=False,
        )
        _CONSOLES[width] = console
    return console


def _whiten_identities(renderable: RenderableType) -> RenderableType:
    """On the cursor row, a node's name is drawn in the highlight's white, not its hue.

    A node's name is always coloured by its key, so a column of them reads as a column of
    identities — but the row the ``❯`` points at is answering a different question, and a
    keyed hue on it competes with the very highlight that says "this one". So the row that
    declares itself the cursor (its *base* style is ``cursor``, which is how every list and
    every screen drawing its own rows marks it) has its identity spans folded to that same
    white, and the row reads as one thing.

    Only :func:`~meshterm.ui.theme.is_identity_style` hues fold. Everything else on the row
    is untouched — the heard-age heat, an SNR reading, a red badge, a path line's chip
    fills, the grey of a node no key could place — because none of those are the identity
    the highlight is standing in for.

    **A path line is spared**, wherever it sits on the row. There the hue is not decoration
    on a name: it is what tells one hop from the next, and what a route graph drawn above
    the row is cross-referenced by — its labels are a marker and one byte of hash, and the
    colour is what says *which node*. So a picked route kept its hops' colours in chip form
    (the fills were never in this vocabulary) and lost them in arrow form, which is every
    path line on the PicoCalc and on any terminal without the powerline glyphs (JP,
    2026-08-30). The widget stamps its own extent with
    :data:`~meshterm.ui.pathline.PATH_INK` and the stamp arrives here as a span over the
    hops (``Text.append_text`` keeps a child's base style as one), so the route is spared
    by name rather than by each screen remembering to ask.

    Done here because this is where a row *is* a row: one boundary every screen's rows
    already leave through, rather than a rule each of them has to remember. Callers hand us
    read-only :class:`Text` (the ANSI cache keys on their content), so the rewrite is on a
    copy.

    Args:
        renderable: Whatever is about to be rendered.

    Returns:
        The renderable, or a cursor row's copy with its name hues turned white.
    """
    if not isinstance(renderable, Text) or str(renderable.style) != "cursor":
        return renderable
    spans = renderable.spans
    if not any(is_identity_style(str(span.style)) for span in spans):
        return renderable
    routes = [(span.start, span.end) for span in spans if str(span.style) == PATH_INK]
    out = renderable.copy()
    out.spans = [
        Span(span.start, span.end, "cursor")
        if is_identity_style(str(span.style)) and not _within(span, routes)
        else span
        for span in spans
    ]
    return out


def _within(span: Span, runs: list[tuple[int, int]]) -> bool:
    """Does ``span`` lie inside one of ``runs`` — a hop inside a marked path line?"""
    return any(start <= span.start and span.end <= end for start, end in runs)


def render_to_ansi(renderable: RenderableType, width: int, *, no_wrap: bool = False) -> str:
    """Render a Rich renderable to an ANSI string at ``width`` columns.

    Args:
        renderable: Any Rich renderable (table, panel, text, group, markup string).
        width: Target width in columns; content wraps/pads to it.
        no_wrap: When ``True``, keep the content on a single line — show what fits and
            crop the overflow (with an ellipsis) instead of wrapping onto more rows.

    Returns:
        The rendered output as an ANSI-escaped string, without a trailing newline.
    """
    width = max(1, width)
    key = _cache_key(renderable, width, no_wrap)
    if key is not None:
        cached = _ANSI_CACHE.get(key)
        if cached is not None:
            _ANSI_CACHE.move_to_end(key)
            return cached
    renderable = _whiten_identities(renderable)
    console = _console(width)
    with console.capture() as capture:
        if no_wrap:
            console.print(renderable, end="", no_wrap=True, overflow="ellipsis", crop=True)
        else:
            console.print(renderable, end="")
    # THE render boundary: every visible string in the TUI leaves through here, so this
    # one call is what makes the PicoCalc glyph contract hold app-wide (identity on the
    # regular platform). Widths were measured on the pre-fold text; the fold preserves
    # cell counts (wide emoji become glyph + pad), so the layout above survives it.
    out = fold_text(capture.get())
    if key is not None:
        _ANSI_CACHE[key] = out
        if len(_ANSI_CACHE) > _ANSI_CACHE_MAX:
            _ANSI_CACHE.popitem(last=False)
    return out


def render_lines(renderable: RenderableType, width: int, *, no_wrap: bool = False) -> list[str]:
    """Render a Rich renderable to a list of ANSI lines at ``width`` columns.

    Each returned line is an independently styled ANSI string, so the caller can slice a
    vertical viewport (for scrolling) without splitting escape sequences.

    Args:
        renderable: Any Rich renderable.
        width: Target width in columns.
        no_wrap: When ``True``, keep the content to a single cropped line (see
            :func:`render_to_ansi`).

    Returns:
        The rendered lines, newline-free. A trailing empty line (from the final newline)
        is dropped so line counts match visible rows.
    """
    ansi = render_to_ansi(renderable, width, no_wrap=no_wrap)
    lines = ansi.split("\n")
    if lines and lines[-1] == "":
        lines.pop()
    return lines


def query_line(query: str, width: int) -> str:
    """The live find/filter query echoed as one body line: ``/hub``, warn-styled.

    THE way a find-as-you-type screen shows what has been typed. Every such screen draws
    this same line above whatever the query narrows — the select list above its rows, the
    path composer above its suggestions, the map above its canvas, the walk above its link
    list — so the text you are typing is always in the same shape, in the same place, in
    the one colour nothing else in a body uses.

    The map and the walk *also* echo the query in their footer hint, with its editing keys
    beside it. That line is not drawn on a platform whose footer is the F-key lane (see
    :attr:`~meshterm.platforms.Platform.footer_fkeys`), which is exactly why those two
    call this: without it, the query would be invisible on the device while you typed it.
    They gate the call on that flag rather than drawing the line twice on the desktop.

    Args:
        query: The current query (callers only call this when it is non-empty).
        width: Inner content width in columns.

    Returns:
        One rendered ANSI line.
    """
    return render_to_ansi(Text(f"/{query}", style="warn"), width, no_wrap=True)


def right_aligned_tail(body: Text, tail: Text, width: int) -> Text:
    """Lay ``body`` out with ``tail`` pinned to the right edge of its last line.

    ``body`` wraps at ``width`` as usual; ``tail`` — a short status such as the chat
    compose bar's byte counter — is right-aligned on ``body``'s final wrapped line when
    it still fits there (after at least one blank cell), otherwise on a new line of its
    own, also right-aligned. So the tail reads as a steady gauge in the corner rather
    than trailing the cursor and wrapping along with the text.

    Args:
        body: The wrappable leading content (e.g. the input line, cursor block included).
        tail: The short run to pin to the right edge.
        width: Total render width in columns.

    Returns:
        A single :class:`Text` with embedded newlines, ready for :func:`render_lines`.
    """
    width = max(1, width)
    console = _console(width)
    lines = list(body.wrap(console, width)) or [Text("")]
    combined = Text()
    for line in lines[:-1]:
        combined.append_text(line)
        combined.append("\n")
    last = lines[-1]
    gap = width - last.cell_len - tail.cell_len
    if gap >= 1:
        combined.append_text(last)
        combined.append(" " * gap)
    else:
        combined.append_text(last)
        combined.append("\n")
        combined.append(" " * max(0, width - tail.cell_len))
    combined.append_text(tail)
    return combined


def crop_cells(text: Text, start: int, width: int) -> Text:
    """Cut a single-line styled Text to the cell window ``[start, start + width)``.

    The horizontal-scroll primitive: a row wider than its lane is shown ``width``
    cells at a time, shifted ``start`` cells in, styling preserved. Boundaries are
    measured in display cells, so a double-width glyph straddling either edge is
    dropped (replaced by a pad space on the left) rather than half-shown.

    Args:
        text: The styled line to crop (treated as a single line).
        start: Cells to skip from the left (clamped at 0).
        width: Cells the window spans.

    Returns:
        A new :class:`Text` at most ``width`` cells wide, ``no_wrap`` set so the
        caller can drop it straight into a row.
    """
    start = max(0, start)
    plain = text.plain
    index, pad = len(plain), 0
    if start == 0:
        index = 0
    else:
        acc = 0
        for i, ch in enumerate(plain):
            w = cell_len(ch)
            if acc + w > start:
                # This character crosses the cut: keep it when it starts exactly at
                # the boundary, else drop it and pad for its protruding half.
                index, pad = (i, 0) if acc == start else (i + 1, acc + w - start)
                break
            acc += w
    out = Text(" " * pad, no_wrap=True)
    out.append_text(text[index:])
    out.truncate(max(0, width))
    return out


def render_hanging(prefix: Text, body: Text, width: int, *, indent: int) -> list[str]:
    """Render ``prefix + body`` at ``width``, wrapping the body with a hanging indent.

    The first visual line carries ``prefix`` followed by the body; every wrapped
    continuation line is padded by ``indent`` columns so it aligns under the body rather
    than falling back to column zero. Used by the chat transcript so a wrapped message
    lines up with its own first line instead of with the timestamp gutter.

    Args:
        prefix: The leading run (e.g. a pointer + timestamp) shown once, on the first line.
        body: The wrappable message text; styling (mentions, glyphs) is preserved.
        width: Total render width in columns.
        indent: Columns to indent continuation lines by (typically ``prefix.cell_len``).

    Returns:
        The rendered lines, newline-free.
    """
    width = max(1, width)
    console = _console(width)
    avail = max(1, width - indent)
    wrapped = list(body.wrap(console, avail)) or [Text("")]
    pad = " " * indent
    combined = Text()
    for i, line in enumerate(wrapped):
        if i:
            combined.append("\n")
        combined.append_text(prefix if i == 0 else Text(pad))
        combined.append_text(line)
    return render_lines(combined, width)