Files
MeshTerm/meshterm/ui/tui/overlay.py
T
Jean-Pierre MartineauandClaude Opus 4.8 b508f2fe27 Busy overlay: skeleton card with a Knight-Rider braille scanner
Replace the between-screens ring spinner with a titled skeleton card: a
heading, the one-cell working chip beside a "reading from <device>…"
caption, and a two-row braille LED bar in place of the old ring.

The bar is a Knight-Rider scanner — a red head sweeps left↔right and
bounces off both ends over a dark-gray track, dragging a persistence-of-
vision comet trail (per-tick decay) with a white-hot core. It rides the
same tick that spins the chip and fades in from black with the card, so
the wait reads as work rather than a frozen bar.

Thread an optional title/caption through busy_overlay so each gap names
the screen being fetched and the companion it's reading from. Give the
CLI progress dialog the same liveness: a spinning chip on every row and a
slim braille meter, with no dead track on indeterminate tasks. Drop the
now-unused RingSpinner.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-13 03:43:15 -04:00

283 lines
12 KiB
Python

"""The busy skeleton: a titled placeholder card floated between screens while a load runs.
A :class:`BusyOverlay` is the model behind :meth:`~meshterm.ui.tui.session.TuiSession.
busy_overlay` — a small *skeleton card* standing in for a screen the device is still
fetching: a title, the one-cell working :class:`~meshterm.ui.tui.spinner.Spinner` beside a
caption, and a Knight-Rider scanning-light bar standing in for the content still loading. Unlike a
:class:`~meshterm.ui.tui.screen.Screen` it is *not* part of the screen stack: the session
draws it as the top-most float, so it hovers over the gap between screens that a slow device
operation (Bluetooth most of all) opens — the caller shows it while the fetch runs and drops
it when that fetch returns.
Rather than pop in, it stays fully black for a short *hold* and then *fades in from black*
over its next fraction of a second (see :attr:`brightness`): an operation that finishes within
the hold shows nothing at all, and a longer one eases up out of the black rather than appearing
suddenly — so the card never flashes and never pops in.
Once up, it does not sit still. Beside the spinning chip a Knight-Rider scanning light sweeps
a two-row braille LED bar left→right and back, advanced on each :meth:`BusyOverlay.tick`: a red
head with a persistence-of-vision trail comet-tailing behind it over a dark-gray track. That
travelling light is what reads the card as *working* rather than as a frozen, broken bar.
"""
from __future__ import annotations
import time
from rich.cells import cell_len
from rich.text import Text
from .render import render_to_ansi
from .spinner import Spinner
#: The title line's colour (the theme's ``title.accent``, as hex so the fade can dim it).
_TITLE_COLOR = "bold #a5b4fc"
#: The working chip's colour (the theme's ``accent`` — the same beloved one-cell spinner).
_CHIP_COLOR = "bold #818cf8"
#: The caption colour (the theme's ``muted``, as a hex so it can be dimmed for the fade).
_CAPTION_COLOR = "#94a3b8"
#: The scanner's unlit-LED colour (the theme's ``track`` — a step below ``faint``, a dark
#: slate gray). Every lamp of the bar rests here; the moving light lifts lamps off it toward
#: red and they fade back as the trail decays, so an idle lamp reads as an unlit LED, not data.
_SCAN_TRACK = "#334155"
#: The lit-LED colours the moving light drives lamps toward: a vivid red (the theme's
#: ``hint.err``) for the body of the head, and a pale "highlighted" red at its very hottest
#: heart, so the core reads as white-hot the way a real LED bar's brightest lamp does.
_SCAN_RED = "#ef4444"
_SCAN_HOT = "#fca5a5"
#: The braille cell drawn for every lamp — dots 2,3,5,6, i.e. *two rows* of dots centred in the
#: cell, so the sweep reads as a slim two-row LED strip rather than a solid block.
_SCAN_GLYPH = "⠶"
#: How many lamps (terminal cells) wide the scanning bar is.
_SCAN_CELLS = 18
#: The per-tick persistence-of-vision fade: on each tick every lamp dims to this fraction of
#: its last brightness, so the head drags a comet trail that lags a few lamps behind it.
_SCAN_DECAY = 0.68
#: How many lamps the head advances per tick (its sweep speed) and the head's half-width in
#: lamps (the bright core lit around it before the trail takes over). Tuned so one pass across
#: the bar takes roughly a second at the session's ~0.06 s tick.
_SCAN_SPEED = 0.85
_SCAN_CORE = 1.2
class BusyOverlay:
"""A skeleton card (title, working chip + caption, placeholder rows) drawn as the top float.
Attributes:
spinner: The animated one-cell :class:`~meshterm.ui.tui.spinner.Spinner` — the same
working chip used inline elsewhere — sitting beside the caption.
title: An optional heading for the screen being fetched (empty for a bare card).
message: An optional caption drawn beside the chip (e.g. "reading from …").
started_at: The monotonic time the card was created, from which the hold + fade run.
hold: Seconds the card stays fully black before the fade begins.
fade: The fade-in duration in seconds, after the hold.
"""
def __init__(
self,
message: str = "",
*,
title: str = "",
hold: float = 0.2,
fade: float = 0.4,
) -> None:
"""Create a busy skeleton card.
Args:
message: A short caption drawn beside the working chip (empty for a bare card).
title: An optional heading naming the screen being fetched.
hold: Seconds to stay fully black before fading in, so an operation that finishes
this fast shows nothing at all.
fade: Seconds over which the card then brightens from black to full colour.
"""
self.spinner = Spinner()
self.title = title
self.message = message
self.started_at = time.monotonic()
self.hold = max(0.0, hold)
self.fade = max(0.0, fade)
#: The scanning-light state driving the Knight-Rider bar: the head's fractional lamp
#: position, its travel direction (``+1`` right / ``-1`` left, bouncing off each end),
#: and the per-lamp brightness buffer whose slow decay on each :meth:`tick` is the
#: persistence-of-vision trail. Seeded with the head already stamped so the first
#: painted frame shows the light rather than a bare track.
self._pos = 0.0
self._dir = 1
self._glow = [0.0] * _SCAN_CELLS
self._stamp_core()
@property
def brightness(self) -> float:
"""The current fade level in ``[0, 1]``: 0 through the :attr:`hold`, then easing to 1.
Stays exactly 0 for the first :attr:`hold` seconds (nothing paints), then a smoothstep
easing over :attr:`fade` gives a gentle glow up out of the black rather than a linear
ramp.
"""
elapsed = time.monotonic() - self.started_at - self.hold
if elapsed <= 0:
return 0.0
if self.fade <= 0:
return 1.0
t = min(1.0, elapsed / self.fade)
return t * t * (3 - 2 * t) # smoothstep
def tick(self) -> None:
"""Advance the working chip one frame and step the scanning light along its sweep."""
self.spinner.tick()
self._advance()
def _advance(self) -> None:
"""Fade the whole trail one notch, move the head, and re-light the core around it.
The decay is the persistence-of-vision effect: every lamp dims toward the track, so the
lamps the head has already passed glow on for a few frames as a comet tail. The head then
steps :data:`_SCAN_SPEED` lamps along, reversing when it reaches either end (the
Knight-Rider bounce), and a fresh bright core is stamped at its new position.
"""
self._glow = [g * _SCAN_DECAY for g in self._glow]
self._pos += self._dir * _SCAN_SPEED
if self._pos >= _SCAN_CELLS - 1:
self._pos = float(_SCAN_CELLS - 1)
self._dir = -1
elif self._pos <= 0:
self._pos = 0.0
self._dir = 1
self._stamp_core()
def _stamp_core(self) -> None:
"""Light the lamps around the head to full, tapering off over :data:`_SCAN_CORE` lamps.
Combined with ``max`` so a freshly-lit core never dims a lamp the decaying trail has
left brighter — the head is always at least as bright as its own tail.
"""
for i in range(_SCAN_CELLS):
core = 1.0 - abs(i - self._pos) / _SCAN_CORE
if core > self._glow[i]:
self._glow[i] = core
def restart(self) -> None:
"""Restart the intro from scratch: rewind the fade ramp and the chip to their starts.
Called each time the card is (re)exposed — its first appearance and every time it comes
back after a prompt covered it — so the black hold and fade-in play fresh every display
rather than the card snapping back at full brightness mid-way through an operation.
"""
self.started_at = time.monotonic()
self.spinner.reset()
self._pos = 0.0
self._dir = 1
self._glow = [0.0] * _SCAN_CELLS
self._stamp_core()
def render(self) -> str:
"""Render the skeleton card as a centred ANSI block, at the current fade level.
The title, the chip + caption line, a spacer, and the placeholder rows are each padded
to a common width and joined into one multi-line :class:`~rich.text.Text`, so the
session's content-sized float centres a clean rectangle over the gap between screens.
Returns:
An ANSI string of the card's rows.
"""
level = self.brightness
lines: list[Text] = []
if self.title:
lines.append(Text(self.title, style=dim_color(_TITLE_COLOR, level)))
status = self.spinner.text(dim_color(_CHIP_COLOR, level))
if self.message:
status.append(" ")
status.append(self.message, style=dim_color(_CAPTION_COLOR, level))
lines.append(status)
lines.append(Text("")) # a blank row between the caption and the scanning bar
lines.append(self._scanner_row(level))
width = max((cell_len(line.plain) for line in lines), default=0)
block = Text("\n").join(_center_text(line, width) for line in lines)
return render_to_ansi(block, width)
def _scanner_row(self, level: float) -> Text:
"""The scanning-light bar: one braille lamp per cell, coloured by its glow, then dimmed.
Every lamp is the same two-row braille glyph; only its colour moves. A lamp interpolates
from the unlit ``track`` gray up through vivid red to a pale hot core by its brightness
in :attr:`_glow` (the moving head plus its persistence-of-vision trail), and the whole
row is finally dimmed by ``level`` so the light eases in with the card's fade-from-black.
"""
row = Text()
for glow in self._glow:
row.append(_SCAN_GLYPH, style=dim_color(_scan_color(glow), level))
return row
def _center_text(text: Text, width: int) -> Text:
"""Return ``text`` padded with spaces so it is centred within ``width`` cells."""
pad = max(0, width - cell_len(text.plain))
left = pad // 2
out = Text(" " * left)
out.append_text(text)
out.append(" " * (pad - left))
return out
def _scan_color(glow: float) -> str:
"""Map a lamp's ``[0, 1]`` brightness to its colour: track gray → vivid red → hot core.
Two stops so the head reads as white-hot: the bottom three-quarters of the range walks the
unlit ``track`` up to full red, and the last quarter pushes red on toward the pale
``_SCAN_HOT`` so only the brightest heart of the head lightens past red.
"""
if glow <= 0.0:
return _SCAN_TRACK
if glow >= 1.0:
return _SCAN_HOT
if glow < 0.75:
return _lerp_hex(_SCAN_TRACK, _SCAN_RED, glow / 0.75)
return _lerp_hex(_SCAN_RED, _SCAN_HOT, (glow - 0.75) / 0.25)
def _lerp_hex(start: str, end: str, t: float) -> str:
"""Blend two ``#rrggbb`` colours: ``t=0`` returns ``start``, ``t=1`` returns ``end``."""
t = max(0.0, min(1.0, t))
channels = []
for lo, hi in ((1, 3), (3, 5), (5, 7)):
a = int(start[lo:hi], 16)
b = int(end[lo:hi], 16)
channels.append(round(a + (b - a) * t))
return "#{:02x}{:02x}{:02x}".format(*channels)
def dim_color(style: str, factor: float) -> str:
"""Scale a Rich hex-colour style toward black by ``factor`` (0 = black, 1 = unchanged).
Only the ``#rrggbb`` token is scaled; any attribute words (e.g. ``bold``) are preserved.
A style without a hex colour is returned untouched, as is any ``factor >= 1``.
Args:
style: A Rich style such as ``"#38bdf8"`` or ``"bold #ecfeff"``.
factor: The brightness multiplier, clamped to ``[0, 1]``.
Returns:
The style with its colour dimmed toward black.
"""
if factor >= 1.0:
return style
factor = max(0.0, factor)
parts = []
for token in style.split():
if token.startswith("#") and len(token) == 7:
r = round(int(token[1:3], 16) * factor)
g = round(int(token[3:5], 16) * factor)
b = round(int(token[5:7], 16) * factor)
parts.append(f"#{r:02x}{g:02x}{b:02x}")
else:
parts.append(token)
return " ".join(parts)