Files
MeshTerm/meshterm/ui/tui/screen.py
T
Jean-Pierre MartineauandClaude Opus 5 0a41303366 Lists: what stays overhead is the section you are in
Two things a grouped list has to keep in view while it scrolls, and neither one
was staying: the lane names that read every row, and the heading that says which
group a row belongs to.

The lanes come first. A column header means the same thing in every section, so
it is not a section landmark at all — it pins for the *whole* list, above any
heading, once it scrolls off (`Separator(pinned=True)`). It is drawn outside the
body slice, so it stays exactly one row: too wide for the terminal it ellipsizes
rather than wrapping and stealing a second reserved row from the content. And it
can now size itself — a Separator title may be a callable taking the render
width — so `column_header`/`Lane` lay each label over its own lane and hand back
the shorter form (DESCRIPTION → DESC) only for the lanes that actually overrun,
from the right, where the trailing lane is the only one with a cell to give.
`lane_header` is that header for `lane_row`'s lanes, shared by the two editors so
they head identical lanes identically.

The headings were the other half, and they were pinning the wrong row. Every
non-pinned separator was a candidate, and the rule takes the last one at or above
the scroll — so what pinned was whatever muted line sat lowest under the heading.
In the Trophy case that meant a discipline's *description* stuck to the top and
the heading itself never did; at the foot of any list, the blank spacer above
Back pinned a blank row. So heading-ness is explicit now (`Separator.heading`,
conferred by `section_heading`, which is why every hand-rolled `── … ──` in the
app — the main menu's categories, the chat picker's Channels/Direct, Trace path's
candidate and ranked lists — now goes through it, and why three lanes headers
that genuinely *are* their block's only landmark say so).

A landmark is also no longer one line but a block: a heading plus the separators
written immediately under it, before the section's first row. Prose written there
is the section's preamble — the Trophy case's "what this discipline scores" — and
it belongs overhead with the heading rather than scrolling away from the rows it
explains. The block hands its rows over one at a time as they leave, so the
heading pins while its description is still the top content row and the two pin
together once both are gone: what is overhead always continues seamlessly into
the body. It never takes more than half the viewport, giving rows up from the
end, so the row that says *which* section this is is the last one dropped.

The frame settles the scroll against however many rows come back rather than
assuming one, and re-asks after sliding the window at the bottom — a heading
among the dropped lines would otherwise vanish instead of pinning.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-29 04:13:14 -04:00

494 lines
22 KiB
Python

"""The screen abstraction: one layer in the TUI's window stack.
A :class:`Screen` knows how to render its body (as Rich, converted to ANSI lines by
:mod:`~meshterm.ui.tui.render`) and how to react to normalized key *actions* dispatched by
the :class:`~meshterm.ui.tui.session.TuiSession`. Screens never touch prompt_toolkit or the
terminal directly, so they stay small, uniform, and testable.
Interactive screens (select, text, confirm) resolve an :class:`asyncio.Future` when the user
commits or cancels; the session awaits that future and then pops the screen, giving the
push/await/pop model behind ``await session.select(...)`` and friends.
"""
from __future__ import annotations
import asyncio
from typing import Any, Optional, Sequence
from rich.console import RenderableType
from rich.text import Text
from .render import render_lines
from .spinner import Spinner
#: Sentinel a screen resolves with when the user presses Esc to cancel, distinct from a
#: legitimately selected ``None`` value.
CANCEL = object()
class Screen:
"""Base class for every TUI layer.
Attributes:
title: Heading shown at the top of the screen/dialog.
footer_hint: One-line key hint shown in the footer.
scroll: Current vertical scroll offset into the body's rendered lines.
future: Resolved with the screen's result (or :data:`CANCEL`) when it commits.
floating: Whether the session should draw this screen as a centered dialog over
the dimmed screen beneath it (deeper layers float; the base does not).
grow_only: Whether a floating dialog may only ever grow. Its box is sized to the
tallest body — and, for a natural-width dialog, the widest — it has shown, not
the current one, so a screen whose content swings as it changes (the packet
viewer paging between packets, the path composer's shifting suggestions) keeps
a steady, centred box — blank-padded when the current body is shorter — instead
of resizing on every change.
chrome: Whether, as the base screen, this layer is wrapped in the session's
persistent header/footer frame. A startup splash sets this ``False`` so the
session instead centers it under the :attr:`banner` with no status bars.
banner: Block-glyph art (one string per row) drawn, centered, above a chromeless
base screen. Ignored while ``chrome`` is ``True``.
footnote: A short line drawn muted and centered *below* a chromeless base screen's
box (e.g. a copyright notice). Ignored while ``chrome`` is ``True``.
"""
title: str = ""
footer_hint: str = "Esc back"
floating: bool = True
grow_only: bool = False
chrome: bool = True
banner: Optional[Sequence[str]] = None
footnote: Optional[str] = None
def __init__(self) -> None:
"""Initialize scroll state and the (later-assigned) result future."""
self.scroll = 0
self.future: Optional[asyncio.Future] = None
# (body-line index, rendered ANSI lines) for each section landmark eligible to be
# pinned to the top rows once it scrolls off. A block is usually one line — a section
# heading, a day divider — but may carry the rows that belong with it (a heading and
# the description under it), which pin together as they scroll off, in order. A screen
# that wants sticky headers rebuilds this list while rendering its body (see
# :meth:`sticky_block`); the default is no landmarks.
self._sticky_headers: list[tuple[int, list[str]]] = []
# The one header that pins for the *whole* list rather than for its section — a
# table's column header, which means nothing scrolled off (see :meth:`sticky_rows`).
# Recorded the same way, as (body-line index, rendered line); ``None`` for none.
self._pinned_header: Optional[tuple[int, str]] = None
# The last render's body height and viewport, recorded by the frame (:meth:`note_metrics`)
# so the shared scroll helpers can page by a screenful of the *current* terminal and
# clamp to the content without every caller threading the sizes through.
self._scroll_total = 1
self._scroll_viewport = 1
# A grow-only screen's high-water body height and natural width: the tallest and
# widest it has rendered into a dialog, so its box can be held at that size once
# reached (see :meth:`ratchet_viewport` / :meth:`ratchet_width`). Zero until the
# first paint; irrelevant while not :attr:`grow_only`.
self._viewport_floor = 0
self._width_floor = 0
# --- rendering -----------------------------------------------------------
def render_body(self, width: int) -> list[str]:
"""Return the body's ANSI lines at ``width`` columns (unclipped).
Args:
width: Inner content width in columns.
Returns:
One ANSI string per body line; the session slices these to the viewport.
"""
raise NotImplementedError
def ratchet_viewport(self, body_h: int) -> int:
"""The body height a :attr:`grow_only` dialog is sized to: its running maximum.
The frame calls this each paint with the current body's height. A grow-only
screen returns the tallest height it has yet shown — so its box never shrinks,
and the frame blank-pads a now-shorter body to fill it — while an ordinary
screen returns the height unchanged and is sized to each body as it comes.
"""
if not self.grow_only:
return body_h
self._viewport_floor = max(self._viewport_floor, body_h)
return self._viewport_floor
def ratchet_width(self, natural: int) -> int:
"""The natural width a :attr:`grow_only` dialog is sized to: its running maximum.
The width-side twin of :meth:`ratchet_viewport`, applied by the frame to a
dialog's requested ``dialog_width`` before the terminal cap — so a grow-only
box holds its widest extent as its content narrows, but a shrinking terminal
still clips it. Full-cap dialogs (no ``dialog_width``) never reach here.
"""
if not self.grow_only:
return natural
self._width_floor = max(self._width_floor, natural)
return self._width_floor
def cursor_line(self) -> Optional[int]:
"""Return a body line that must stay visible, or ``None`` for free scrolling.
Selection/text screens return the active row so the session can keep it in view;
plain scroll screens return ``None``.
"""
return None
def consume_edge_scrub(self) -> int:
"""Right-edge columns the session should force-repaint on the next paint (0 = none).
The default is 0 — no screen needs this. A screen whose body can emit glyphs the
terminal renders at an unexpected width (the map's braille) overrides this to have the
session redraw just the smeared edge cells, which prompt_toolkit's differential paint
would otherwise never rewrite (see :class:`~meshterm.ui.map_screen.MapScreen`).
"""
return 0
def sticky_block(self, scroll: int) -> list[str]:
"""The already-rendered body lines to pin as ``scroll`` moves past a section landmark.
Lets a grouped list keep its current section overhead after the section's own rows have
scrolled off — a select screen's ``Channels``/``Direct`` divider, the Trophy case's
discipline heading *and the description under it*, the chat transcript's
``── Wed Jul 8 ──`` day divider. ``scroll`` is the offset the body is about to be
sliced at; the returned lines are drawn as top rows, under any whole-list header pinned
over them (:meth:`sticky_rows` composes them for the frame).
The shared rule: among the blocks a screen recorded in :attr:`_sticky_headers` while
rendering, find the last one starting at or above ``scroll`` (the one *governing* the
top visible row) and pin exactly the rows of it that ``scroll`` has passed. So a block
hands its rows over one at a time as they leave — the heading pins while its
description is still the top content row, and the two pin together once both are gone —
and the pinned rows always continue seamlessly into the body below. A screen opts in
simply by populating :attr:`_sticky_headers`; the empty default means no pinning.
A block never takes more than half the viewport: the rows are given up from the *end*,
so the heading — the row that says which section this is — is the last thing dropped on
a short terminal.
"""
governing: Optional[tuple[int, list[str]]] = None
for entry in self._sticky_headers:
if entry[0] <= scroll:
governing = entry
else:
break # blocks are recorded in body order; nothing past here can govern
if governing is None:
return [] # no landmark above the top visible row
at, rows = governing
keep = max(1, self._scroll_viewport // 2)
return rows[: min(scroll - at, keep)]
def sticky_rows(self, scroll: int) -> list[str]:
"""Every already-rendered line to pin above the body sliced at ``scroll``.
What the frame actually draws, top-down: the whole-list header from
:attr:`_pinned_header` (a table's column header — the lane names, which mean the
same everywhere in the list) once it has scrolled off, then the governing section
block from :meth:`sticky_block`. A screen with only section headings pins one
line; a grouped table pins both, so a scrolled row can still be read off its lanes
*and* placed in its group.
Args:
scroll: The offset the body is about to be sliced at.
Returns:
The lines to pin, in draw order (empty for nothing to pin). Each one costs the
body a row, so the frame reserves exactly as many as come back.
"""
rows: list[str] = []
if self._pinned_header is not None and self._pinned_header[0] < scroll:
rows.append(self._pinned_header[1])
rows.extend(self.sticky_block(scroll))
return rows
# --- input ---------------------------------------------------------------
def handle(self, action: str, data: str = "") -> None:
"""React to a normalized key action from the session.
Args:
action: One of ``up``, ``down``, ``pageup``, ``pagedown``, ``home``, ``end``,
``ctrl_home``, ``ctrl_end``, ``ctrl_pageup``, ``ctrl_pagedown``, ``left``,
``right``, ``ctrl_left``, ``ctrl_right``, ``ctrl_up``, ``ctrl_down``,
``shift_up``, ``shift_down``,
``shift_left``, ``shift_right``, ``enter``, ``escape``, ``backspace``,
``delete``, ``space``, ``tab``, ``shift_tab``, or ``text`` (with ``data``
set to the character).
data: The typed character when ``action`` is ``text``.
"""
if action == "escape":
self.resolve(CANCEL)
def resolve(self, value: Any) -> None:
"""Resolve this screen's future, committing ``value`` (or :data:`CANCEL`).
Args:
value: The result to hand back to the awaiting caller.
"""
if self.future is not None and not self.future.done():
self.future.set_result(value)
# --- scrolling helpers (shared) ------------------------------------------
def note_metrics(self, total: int, viewport: int) -> None:
"""Record the last render's body height and viewport (the frame calls this each paint).
The shared scroll/section jumps below size themselves from these, so a PageDown moves
by a screenful of the current terminal rather than a fixed constant, and the top/bottom
clamps track the real content height without the caller passing the sizes in.
"""
self._scroll_total = max(1, total)
self._scroll_viewport = max(1, viewport)
def note_viewport(self, viewport: int) -> None:
"""Record just the viewport height (for callers that don't know the body total)."""
self._scroll_viewport = max(1, viewport)
@property
def _page_step(self) -> int:
"""Lines a PageUp/PageDown moves: a screenful, bar one row kept for continuity."""
return max(1, self._scroll_viewport - 1)
@property
def content_overflows(self) -> bool:
"""Whether the last-rendered body is taller than its viewport — i.e. it can scroll.
The reusable gate for the app-wide rule that a footer only advertises a key that
would do something: a screen whose body fits has nothing to scroll, so it drops its
``↑↓ PgUp/PgDn scroll`` atom (see :attr:`DashboardScreen.footer_hint`). Reads the
metrics the frame recorded on the *previous* paint (:meth:`note_metrics`), so it is
honest one frame after a resize — the frame repaints again immediately.
"""
return self._scroll_total > self._scroll_viewport
def scroll_by(self, delta: int, total: int, viewport: int) -> None:
"""Adjust :attr:`scroll` by ``delta`` lines, clamped to the given content bounds."""
self.scroll = _clamp_scroll(self.scroll + delta, total, viewport)
def scroll_lines(self, delta: int) -> None:
"""Scroll by ``delta`` lines, clamped to the last-recorded content bounds."""
self.scroll = _clamp_scroll(
self.scroll + delta, self._scroll_total, self._scroll_viewport
)
def scroll_pages(self, pages: int) -> None:
"""Scroll by ``pages`` screenfuls (negative scrolls up)."""
self.scroll_lines(pages * self._page_step)
def scroll_to_top(self) -> None:
"""Jump the view to the first line."""
self.scroll = 0
def scroll_to_bottom(self) -> None:
"""Jump the view to the last screenful."""
self.scroll = max(0, self._scroll_total - self._scroll_viewport)
def scroll_to_section_start(self) -> None:
"""Move to the top of the section holding the top visible line.
Sections are delimited by the recorded :attr:`_sticky_headers` (a select list's group
dividers, the chat transcript's day dividers). If that heading is already the top line,
move to the *previous* section instead — so repeated presses walk up section by section,
the way a text editor's paragraph jump does. Falls back to the very top with no sections.
"""
offsets = [idx for idx, _ in self._sticky_headers]
governing = max((o for o in offsets if o <= self.scroll), default=None)
if governing is None:
target = 0
elif governing < self.scroll:
target = governing # up to the top of the section we're inside
else:
target = max((o for o in offsets if o < self.scroll), default=0)
self.scroll = _clamp_scroll(target, self._scroll_total, self._scroll_viewport)
def scroll_to_next_section(self) -> None:
"""Move to the start of the next section below the top visible line (else the bottom)."""
offsets = [idx for idx, _ in self._sticky_headers]
nxt = min((o for o in offsets if o > self.scroll), default=None)
target = nxt if nxt is not None else self._scroll_total
self.scroll = _clamp_scroll(target, self._scroll_total, self._scroll_viewport)
class ListWindow:
"""Scroll state for a list that scrolls *inside* a fixed screen.
The app-wide windowed-list pattern (established by the mesh walk's link list): the
screen sizes its fixed chrome — headings, charts, action rows — to the frame's
viewport (see :meth:`Screen.note_viewport`; the frame records it before
``render_body`` runs) and hands the leftover rows here; only the list's rows
scroll within them. Faint ``↑ n more`` / ``↓ n more`` markers (see
:meth:`marker`) take the window's edge rows exactly when rows are hidden on
that side, and the settled content capacity is remembered as :attr:`page`, the
stride a PgUp/PgDn should move by.
Attributes:
top: First list row the window shows (clamped by :meth:`fit` each paint).
page: Rows the window carried on the last :meth:`fit` — the paging stride.
"""
def __init__(self) -> None:
"""Start at the top with a conservative pre-first-paint stride."""
self.top = 0
self.page = 6
def fit(self, n: int, win: int, index: Optional[int] = None) -> tuple[int, int]:
"""Settle the window over ``n`` rows into ``win`` lines: ``(top, count)``.
The edge markers eat the window's boundary rows exactly when rows hide
beyond them, so the content capacity shifts as the window slides; a few
passes settle top, capacity, and the highlight clamp together.
Args:
n: Total list rows.
win: Lines the window may spend — on content and markers alike.
index: A highlighted row that must stay visible, or ``None`` when the
window scrolls free (a cursor-less log; ``top`` is just clamped).
Returns:
The first visible row and how many rows to draw. Rows hidden above
number ``top``; below, ``n - top - count`` — each side non-zero exactly
when its marker row should be drawn.
"""
if n <= win:
self.top = 0
self.page = max(1, win)
return 0, n
top = max(0, min(self.top, n - 1))
count = 1
for _ in range(4):
above = 1 if top > 0 else 0
below = 1 if n - top > win - above else 0
count = max(1, win - above - below)
if index is not None:
if index < top:
top = index
elif index >= top + count:
top = index - count + 1
top = max(0, min(top, n - count))
self.top = top
self.page = count
return top, count
def to_end(self) -> None:
"""Slide the window to the list's tail on the next :meth:`fit`.
The overshoot is deliberate — the caller rarely knows the list length at
keypress time, and :meth:`fit` clamps to the last windowful either way.
"""
self.top = 10**9
@staticmethod
def marker(hidden: int, direction: str) -> Text:
"""The faint edge row counting rows hidden ``"above"`` or ``"below"``."""
arrow = "↑" if direction == "above" else "↓"
return Text(f" {arrow} {hidden} more", style="faint")
def _clamp_scroll(scroll: int, total: int, viewport: int) -> int:
"""Clamp a scroll offset to the valid range for the content and viewport.
Args:
scroll: Proposed offset.
total: Total line count.
viewport: Visible height in lines.
Returns:
The offset clamped to ``0 .. max(0, total - viewport)``.
"""
return max(0, min(scroll, max(0, total - viewport)))
class ScrollScreen(Screen):
"""A read-only screen that shows a Rich renderable in a scrollable viewport.
Used for tool result windows and any long list. Content taller than the viewport scrolls
with the arrows / PageUp / PageDown (a screenful) / Home / End (or Ctrl+Home / Ctrl+End);
Esc dismisses it. Result windows carry no sections, so Ctrl+PageUp/PageDown just reach the
top/bottom.
"""
def __init__(
self,
renderable: RenderableType,
*,
title: str = "",
footer_hint: str = "↑↓ PgUp/PgDn scroll · Esc close",
floating: bool = True,
) -> None:
"""Wrap a renderable in a dismissable, scrollable screen.
Args:
renderable: The Rich content to display.
title: Heading for the screen/dialog.
footer_hint: Footer key hint.
floating: Whether to draw as a centered dialog over the parent.
"""
super().__init__()
self._renderable = renderable
self.title = title
self.footer_hint = footer_hint
self.floating = floating
def render_body(self, width: int) -> list[str]:
"""Render the wrapped content to ANSI lines and remember the total count."""
lines = render_lines(self._renderable, width)
self._scroll_total = max(1, len(lines))
return lines
def handle(self, action: str, data: str = "") -> None:
"""Scroll the viewport (by line, page, or to an edge) or dismiss the screen."""
if action == "up":
self.scroll_lines(-1)
elif action == "down":
self.scroll_lines(1)
elif action == "pageup":
self.scroll_pages(-1)
elif action in ("pagedown", "space"):
self.scroll_pages(1)
elif action in ("home", "ctrl_home"):
self.scroll_to_top()
elif action in ("end", "ctrl_end"):
self.scroll_to_bottom()
elif action == "ctrl_pageup":
self.scroll_to_section_start()
elif action == "ctrl_pagedown":
self.scroll_to_next_section()
elif action in ("escape", "enter"):
self.resolve(None)
class BusyScreen(Screen):
"""A non-interactive splash body: an animated spinner beside a message.
Used to keep the startup splash on screen — its wordmark and box unchanged — while a
short async task runs (e.g. smoke-testing a chosen companion device). It set as a
chromeless base so it redraws the same centered-under-the-wordmark splash, only swapping
the box's contents. It resolves nothing and ignores every key; the session pops it when
the awaited task completes. The animation itself is the reusable
:class:`~meshterm.ui.tui.spinner.Spinner`.
"""
footer_hint = "working…"
floating = False
def __init__(self, message: str, *, title: str = "") -> None:
"""Start a busy splash showing ``message`` under an optional ``title``."""
super().__init__()
self.title = title
self._message = message
self._spinner = Spinner()
def tick(self) -> None:
"""Advance the spinner to its next frame (driven by the session's animation timer)."""
self._spinner.tick()
def render_body(self, width: int) -> list[str]:
"""Render the current spinner frame followed by the message."""
line = self._spinner.text()
line.append(" ")
line.append(self._message)
return render_lines(line, width)
def handle(self, action: str, data: str = "") -> None:
"""Swallow all keys: the splash dismisses itself when the task finishes."""
return