zettcode-plugin-api 0.4.0__py3-none-any.whl

zettcode/plugin_api/pets.py

@@ -0,0 +1,224 @@
+"""What a pet is, and the catalog that finds one by name.
+
+A :class:`Pet` is only data: a palette and, for each mood, the pixel maps it is drawn from, in the encoding
+:func:`pixel_lines` defines (``.`` is transparent, any other character names its colour). It
+knows nothing of the terminal's size, of where it stands, or of the mouse; ``app/ui/widgets/pet.py`` places
+it, moves it, and picks the mood.
+
+Pets are offered the way palettes are: a :class:`PetSource` names one and builds it only when it is asked for,
+the built-in plugin offers the ones that ship, and any other plugin offers its own through
+``ctx.tui.register_pet``. :class:`PetCatalog` is what ``/pet`` and the start-up read.
+
+Every frame of a pet is the same size, and its height is an even number of pixel rows: two pixels fit in
+one terminal cell.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+from typing import NamedTuple
+
+from zettcode.tui.render.style import Span, Style, TextLine
+
+#: The moods a pet may have. ``idle`` is the only one it must have; a pet without the others stays as it is.
+#: A pet is asleep when it is idle, awake and busy while a request runs, and pleased when it is patted.
+IDLE = "idle"
+WORKING = "working"
+GLAD = "glad"
+
+#: What a pet may be called: one word, the way a palette's name is, because it is typed after ``/pet``.
+PET_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
+
+#: The pet a reader has without choosing one.
+DEFAULT_PET_NAME = "cat"
+
+
+def _brightness(colour: str) -> int:
+    """Return the mean of a ``#rrggbb`` colour's channels, 0 to 255."""
+    return sum(int(colour[index : index + 2], 16) for index in (1, 3, 5)) // 3
+
+
+def pixel_lines(pixels: tuple[str, ...], palette: dict[str, str]) -> tuple[TextLine, ...]:
+    """Encode each pixel pair with a full/half block and two independent colours.
+
+    Equal pixels use a full block. Different opaque pixels use an upper half
+    block with the lower pixel as its background. When either half is outside
+    the silhouette, its background stays unset to preserve the terminal's own
+    colour rather than drawing a rectangle around the mark.
+
+    Args:
+        pixels: Equal-length rows, an even number of them; ``.`` is transparent and any other
+            character names its colour in ``palette``.
+        palette: Colour of each pixel character.
+    """
+    lines: list[TextLine] = []
+    for index in range(0, len(pixels), 2):
+        spans: list[Span] = []
+        for upper, lower in zip(pixels[index], pixels[index + 1], strict=True):
+            if upper == lower:
+                span = Span(" " if upper == "." else "█", Style(foreground=palette.get(upper)))
+            elif upper == ".":
+                span = Span("▄", Style(foreground=palette[lower]))
+            else:
+                span = Span("▀", Style(foreground=palette[upper], background=palette.get(lower)))
+            if spans and spans[-1].style == span.style:
+                spans[-1] = Span(spans[-1].text + span.text, span.style)
+            else:
+                spans.append(span)
+        lines.append(TextLine(tuple(spans)))
+    return tuple(lines)
+
+
+class Pet:
+    """A sprite and the frames of each of its moods.
+
+    Args:
+        name: What the pet is called.
+        palette: The colour of each pixel character the frames use.
+        poses: For each mood, the frames it cycles through, each frame a tuple of equal-length pixel rows.
+
+    Raises:
+        ValueError: There is no ``idle`` pose, a frame differs in size from the first, or its height is odd.
+    """
+
+    def __init__(self, name: str, palette: Mapping[str, str], poses: Mapping[str, tuple[tuple[str, ...], ...]]) -> None:
+        """Check the frames agree, and draw each into cells once."""
+        if IDLE not in poses:
+            raise ValueError(f"pet {name!r} has no {IDLE!r} pose")
+        first = poses[IDLE][0]
+        size = (len(first[0]), len(first))
+        for pose, frames in poses.items():
+            if not frames:
+                raise ValueError(f"pet {name!r}: pose {pose!r} has no frames")
+            for frame in frames:
+                if (len(frame[0]), len(frame)) != size or any(len(row) != size[0] for row in frame):
+                    raise ValueError(f"pet {name!r}: a frame of {pose!r} is not {size[0]}x{size[1]}")
+        if size[1] % 2:
+            raise ValueError(f"pet {name!r}: {size[1]} pixel rows do not fill whole cells")
+        self.name = name
+        self.palette = dict(palette)
+        self.poses = dict(poses)
+        #: Columns and rows of cells the pet takes.
+        self.width = size[0]
+        self.height = size[1] // 2
+        self._cells: dict[str, tuple[tuple[TextLine, ...], ...]] = {
+            pose: tuple(pixel_lines(frame, self.palette) for frame in frames) for pose, frames in poses.items()
+        }
+
+    def swatch(self, count: int = 3) -> tuple[str, ...]:
+        """Return the colours this pet is mostly made of, most used first, for a chip that stands for it.
+
+        Read from its resting frame. The near-black of eyes and outlines is left out: it says nothing about the
+        pet and would disappear on a dark page.
+        """
+        used = Counter(char for row in self.poses[IDLE][0] for char in row if char != ".")
+        colours: list[str] = []
+        for char, _ in used.most_common():
+            colour = self.palette.get(char)
+            if colour and colour not in colours and _brightness(colour) >= 70:
+                colours.append(colour)
+        return tuple(colours[:count])
+
+    def frames(self, pose: str) -> int:
+        """Return how many frames the mood has; a mood the pet lacks has its idle frames."""
+        return len(self._cells.get(pose, self._cells[IDLE]))
+
+    def lines(self, pose: str, step: int = 0) -> tuple[TextLine, ...]:
+        """Return the cells of one frame of a mood, counting steps round the frames it has."""
+        frames = self._cells.get(pose, self._cells[IDLE])
+        return frames[step % len(frames)]
+
+
+def mirrored(halves: tuple[str, ...]) -> tuple[str, ...]:
+    """Return a frame drawn as its left half only, completed by its own reflection.
+
+    Most creatures are symmetric, and drawing one side keeps the two from drifting apart as the art is edited. A
+    mood that is not symmetric (an eye that looks aside, a tail) replaces whole rows with :func:`edited`.
+    """
+    return tuple(row + row[::-1] for row in halves)
+
+
+def edited(frame: tuple[str, ...], rows: Mapping[int, str]) -> tuple[str, ...]:
+    """Return a frame with some of its pixel rows replaced, which is how one mood is made from another.
+
+    Raises:
+        ValueError: A row index is outside the frame, or a new row is not as wide as the frame.
+    """
+    changed = list(frame)
+    for index, row in rows.items():
+        if not 0 <= index < len(frame) or len(row) != len(frame[0]):
+            raise ValueError(f"row {index} cannot be replaced by {row!r}")
+        changed[index] = row
+    return tuple(changed)
+
+
+class PetSource(NamedTuple):
+    """A pet that something offers by name: the program's own, or a plugin.
+
+    Attributes:
+        name: What ``/pet`` is typed with; one word.
+        load: Builds the pet. Called when it is asked for, never before, so a source costs nothing until picked.
+        description: The one-line note the menu shows beside the name, or a function that returns it (called only
+            when the menu is opened).
+    """
+
+    name: str
+    load: Callable[[], Pet]
+    description: str | Callable[[], str] = ""
+
+
+class PetCatalog:
+    """Every pet that can be asked for by name, in the order a menu lists them.
+
+    A source whose name is taken, or is not one word, is ignored: the first one wins, so the pets that ship are
+    never displaced by a plugin's and the menu never lists a name twice. Only names are listed up front; a pet is
+    built when it is asked for.
+
+    Args:
+        sources: What the program and the plugins offer, in load order.
+    """
+
+    def __init__(self, sources: Sequence[PetSource] = ()) -> None:
+        chosen: dict[str, PetSource] = {}
+        for source in sources:
+            if source.name not in chosen and PET_NAME.fullmatch(source.name):
+                chosen[source.name] = source
+        self._sources = chosen
+
+    def names(self) -> tuple[str, ...]:
+        """Return the names in the order a menu lists them. Nothing is built."""
+        return tuple(self._sources)
+
+    def load(self, name: str) -> Pet:
+        """Return the pet called ``name``.
+
+        Raises:
+            ValueError: There is no such pet, or it could not be built. The message names what is available, so
+                a typo is answered by the list.
+        """
+        source = self._sources.get(name)
+        if source is None:
+            available = ", ".join(self.names()) or "none"
+            raise ValueError(f"Unknown pet: {name!r}. Available: {available}")
+        try:
+            return source.load()
+        except Exception as error:  # noqa: BLE001 - a plugin's pet is its author's code
+            raise ValueError(f"Pet {name!r} could not be built: {error}") from error
+
+    def notes(self) -> dict[str, str]:
+        """Return the one-line note each pet carries, by name; a pet with none is left out.
+
+        Whatever cannot be read has no note, and is not an error here: it is the error of the person who picks it.
+        """
+        notes: dict[str, str] = {}
+        for name, source in self._sources.items():
+            try:
+                described = source.description
+                text = described() if callable(described) else described
+            except Exception:  # noqa: BLE001 - see above
+                continue
+            if isinstance(text, str) and text.strip():
+                notes[name] = text.strip()
+        return notes

zettcode/plugin_api/plugin.py

@@ -0,0 +1,76 @@
+"""The terminal's plugin base class and the bundle of what the loaded plugins produced for the terminal.
+
+:class:`TuiPlugin` is the engine's :class:`~zettcode.engine.plugins.plugin.Plugin` with the shell's row hooks, and
+it is activated with a :class:`~zettcode.engine.plugins.context.PluginContext`. :class:`TuiPlugins` is the
+engine's bundle plus what only a terminal reads: commands, palettes, pets, presenters and rows.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from zettcode.engine.plugins.context import PluginContext
+from zettcode.engine.plugins.plugin import Plugin, Plugins
+from zettcode.plugin_api.mixins import PluginUiMixin
+from zettcode.plugin_api.state import TurnSegment, UiRow
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, so the imports stay lazy
+    from zettcode.plugin_api.commands import Command
+    from zettcode.plugin_api.presenters import Presenter
+    from zettcode.tui import ThemeSource
+
+    from .pets import PetSource
+
+
+class TuiPlugin(Plugin[PluginContext], PluginUiMixin):
+    """A plugin that fills shell slots by overriding a method; ``PluginUiMixin`` holds the four.
+
+    It is the same :class:`~zettcode.engine.plugins.plugin.Plugin` with the row hooks mixed in. Nothing about it says
+    "terminal only": whether a plugin has a screen to draw on is ``ctx.tui is not None``, which is what its
+    ``activate`` should test before registering a command, a palette, a pet, a presenter or a row.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class TuiPlugins(Plugins):
+    """Everything the installed plugins contributed, for the terminal: the agent's side and the shell's.
+
+    Attributes:
+        commands: Commands the plugins registered, in load and registration
+            order, each typed ``"plugin"``.
+        builtin_commands: The first of ``commands`` that came from the plugins compiled into the program, in the same
+            order. The shell lists them ahead of its own and puts the rest after everything built in, so an installed
+            plugin can add a command but never shadow one of the program's.
+        themes: Palettes the plugins offered by name, in load and registration order; the built-in plugin's come
+            first. ``/theme`` lists, previews and switches to them, after ``dark`` and ``light``.
+        presenters: How plugins asked for entries to be drawn, in load and registration order; the built-in
+            presenters come first, at the lowest priority, so a plugin's claim on the same rows wins.
+        pets: Pets the plugins offered by name, in load and registration order; the built-in plugin's come first.
+            ``/pet`` lists, previews and switches to them.
+        rows: The header and status rows the plugins fill, each with its left
+            and right segments in paint order. The builtin rows are merged in
+            first, so an overridden segment keeps its place.
+        turn_segments: The items of the line a request ends on, in the order they stand; the built-in plugin's come
+            first, so a name a plugin reuses replaces that item in place.
+        focus_handlers: Told when the terminal window gains or loses focus, in load order.
+        turn_start_handlers: Told when a turn of the conversation starts, in load order.
+        turn_end_handlers: Told when a turn of the conversation ends, in load order.
+    """
+
+    commands: tuple[Command, ...] = ()
+    builtin_commands: tuple[Command, ...] = ()
+    themes: tuple[ThemeSource, ...] = ()
+    pets: tuple[PetSource, ...] = ()
+    presenters: tuple[Presenter, ...] = ()
+    rows: tuple[UiRow, ...] = ()
+    turn_segments: tuple[TurnSegment, ...] = ()
+    focus_handlers: tuple[Callable[[bool], None], ...] = ()
+    turn_start_handlers: tuple[Callable[[], None], ...] = ()
+    turn_end_handlers: tuple[Callable[[bool], None], ...] = ()
+
+    @property
+    def installed_commands(self) -> tuple[Command, ...]:
+        """Return the commands of the installed plugins: ``commands`` without the built-in ones."""
+        return self.commands[len(self.builtin_commands) :]

zettcode/plugin_api/presenters.py

@@ -0,0 +1,277 @@
+"""What a plugin implements to draw a row: the base class, and how a drawn block is cached.
+
+A presenter turns one kind of entry into lines. The built-in ones live in `zettcode.presenters`; a plugin registers its
+own through `ctx.tui.register_presenter`, and the row it draws is the same kind of object, so this — the base class and
+the rule for when a row is drawn again — is part of the plugin contract, not part of the terminal.
+
+The registry (`Presenters`) is here and not with the built-in rows because `Presenter.block` takes it as its `owner`:
+the base class names the registry in its own signature, so moving the registry out would make the base class import its
+implementation for a type.
+
+The two line sources here are how a block is cached: the entry keeps the last block it was drawn as, its key made of
+the width, the palette, the registry and what the row looks like, so a frame that changes nothing redraws nothing.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from dataclasses import fields as dataclass_fields
+from typing import Any, ClassVar, Generic, TypeVar
+
+from zettcode.tui import LineSource, Span, StaticLines, Style, TextLine, Theme
+from zettcode.tui.render import inset_line, layout_rich_lines, wrap_words
+
+from .entries import Entry, EntryKind
+
+#: Columns a row's content is inset by, past the gutter marker.
+CONTENT_INDENT = 2
+
+#: The entry a presenter accepts; each subclass pins it to one entry type.
+E = TypeVar("E", bound=Entry)
+
+
+#: The entry fields that are not part of how a row looks: its identity, and the
+#: slots the cache itself lives in.
+_NOT_LOOK = frozenset({"id", "block", "block_key"})
+
+
+_LOOK_FIELDS: dict[type, tuple[str, ...]] = {}
+
+
+def _look_fields(entry_type: type) -> tuple[str, ...]:
+    """Return the names of the fields a row of this type may look different for.
+
+    Worked out once per entry class and kept, because it is asked for every entry
+    every time the transcript view measures it.
+    """
+    names = _LOOK_FIELDS.get(entry_type)
+    if names is None:
+        names = tuple(field.name for field in dataclass_fields(entry_type) if field.name not in _NOT_LOOK)
+        _LOOK_FIELDS[entry_type] = names
+    return names
+
+
+class Presenter(Generic[E], ABC):
+    """Turns one kind of entry into rows.
+
+    The type parameter is the entry the presenter handles, and :attr:`kind` is the
+    kind that routes it there, so :meth:`lines` receives exactly that entry.
+
+    Attributes:
+        kind: The kind of entry this presenter presents; one presenter per kind.
+        entry_type: The entry class this presenter is for, when it is for one family of a kind
+            rather than the kind as a whole: the presenter of an edit row is the one for
+            ``EditEntry``, though an edit row is a ``tool`` row like any other. The registry looks
+            for the entry's own class first (and its parents') and the kind second.
+        gutter: Whether the rows open with a marker the presenter draws in the
+            gutter's own column — the user's arrow, the wait row's sparkle, a
+            tool's outcome. Every other row is inset past the gutter, so every
+            leading glyph sits in one column and every line of content in the next.
+        priority: How strongly this presenter claims the rows it draws, when more than one could draw
+            them. The higher number wins, and an equal number goes to whichever was registered later,
+            so the built-in presenters - priority 0, registered first - are what a transcript uses
+            until a plugin registers its own. A plugin that wants to replace only some families of a
+            kind, or to beat another plugin, raises this.
+    """
+
+    kind: ClassVar[EntryKind]
+    entry_type: ClassVar[type[Entry] | None] = None
+    gutter: ClassVar[bool] = False
+    priority: ClassVar[int] = 0
+
+    @abstractmethod
+    def lines(self, entry: E, width: int, theme: Theme, frame: int) -> list[TextLine]:
+        """Return the rows this entry paints at the available width."""
+
+    def look(self, entry: E, frame: int) -> object:
+        """Return what the entry's rows depend on, so unchanged ones are not drawn again.
+
+        The default is every field of the entry. That is the safe direction to be
+        wrong in: a field nobody told the cache about changes the key and costs one
+        more render, where a hand-written list that forgot it would keep showing
+        the row as it was. A presenter narrows it only to leave out something that
+        changes without changing the rows, and adds to it only what is not a field.
+        """
+        return tuple(getattr(entry, name) for name in _look_fields(type(entry)))
+
+    def block(self, entry: E, width: int, theme: Theme, frame: int, owner: Presenters) -> LineSource:
+        """Return the entry's cached rows, rendering them again only when the look changed.
+
+        Args:
+            entry: The entry to present; its cache slots hold the last result.
+            width: Columns available.
+            theme: Palette the rows are drawn in.
+            frame: Animation step, which only a presenter that animates reads.
+            owner: The registry this call came through, part of the key so a
+                transcript given other presenters never reuses these rows.
+        """
+        key: tuple[object, ...] = (width, theme, owner, self.look(entry, frame))
+        if entry.block is None or entry.block_key != key:
+            margin = min(CONTENT_INDENT, max(0, width - 1))
+            content_width = width if self.gutter else max(1, width - margin)
+            rendered = StaticLines(self.lines(entry, content_width, theme, frame))
+            entry.block = rendered if self.gutter else Indented(rendered)
+            entry.block_key = key
+        return entry.block
+
+    @staticmethod
+    def text_lines(text: str, width: int, style: Style, *, indent: int = 0, words: bool = False) -> list[TextLine]:
+        """Wrap text with the same layout used by RichText and Markdown.
+
+        Args:
+            text: What to wrap; each newline starts a new row.
+            width: Columns available.
+            style: The ink the text is drawn in.
+            indent: Columns left empty at the start of every row.
+            words: Break between words and not mid-word. For a sentence a reader is meant to read, such as an
+                error naming a command to try; left off, a row breaks at the column, as code and output must.
+        """
+        margin = min(indent, max(0, width - 1))
+        room = max(1, width - margin)
+        if words:
+            rows = [piece for line in text.split("\n") for piece in wrap_words(line, room)]
+            # A character wider than the whole row (a wide glyph in a column or two) cannot be placed in it;
+            # the layout that wraps by column cuts such a row to the budget, and so does this.
+            fitted = layout_rich_lines(tuple(TextLine((Span(row, style),)) for row in rows), room, wrap=False)
+            return [inset_line(row, margin) for row in fitted]
+        source = tuple(TextLine((Span(line, style),)) for line in text.split("\n"))
+        return [inset_line(row, margin) for row in layout_rich_lines(source, room)]
+
+
+class LeadingGap(LineSource):
+    """LineSource that renders one blank row before a nested source.
+
+    Streamed answers are served by ``Markdown`` so their parsing stays
+    incremental, which means the separating blank line cannot come from the
+    generic presenter.
+    """
+
+    def __init__(self, source: LineSource) -> None:
+        """Wrap the nested line source.
+
+        Args:
+            source: Line source whose rows shift down by one; it is a
+                ``LineSource`` itself, so the wrapper stays composable.
+        """
+        self.source = source
+
+    def count(self, width: int) -> int:
+        """Return the nested line count plus the leading blank row."""
+        return self.source.count(width) + 1
+
+    def line(self, index: int, width: int) -> TextLine:
+        """Shift the index past the blank row and delegate to the nested source."""
+        if index == 0:
+            return TextLine()
+        return self.source.line(index - 1, width)
+
+
+class Indented(LineSource):
+    """LineSource that shifts every row right by a fixed margin.
+
+    The margin is drawn with the row's own leading style, so a line that carries
+    a background keeps it across the gutter. The nested source wraps at the
+    remaining width, which keeps long lines inside the window instead of
+    wrapping past its right edge.
+    """
+
+    def __init__(self, source: LineSource, columns: int = CONTENT_INDENT) -> None:
+        """Wrap ``source`` with ``columns`` cells of leading space.
+
+        Args:
+            source: Line source to shift right.
+            columns: Margin in cells; the nested source wraps that much narrower.
+        """
+        self.source = source
+        self.columns = max(0, columns)
+
+    def count(self, width: int) -> int:
+        """Return the nested row count, which the margin does not change."""
+        return self.source.count(max(1, width - self._margin(width)))
+
+    def line(self, index: int, width: int) -> TextLine:
+        """Draw the margin, then the nested row at the reduced width."""
+        margin = self._margin(width)
+        row = self.source.line(index, max(1, width - margin))
+        return inset_line(row, margin)
+
+    def _margin(self, width: int) -> int:
+        """Keep at least one column available for content on narrow screens."""
+        return min(self.columns, max(0, width - 1))
+
+
+class Presenters:
+    """The presenters of one transcript: one for each kind of entry, and for the families inside a kind.
+
+    A presenter is found by the entry's class first, walking up its parents, and by its kind
+    second. Most kinds have one presenter and no family (a notice is a notice), and ``tool`` has
+    one for tools in general and one for each tool whose entry carries more than the rest.
+
+    When more than one presenter could draw the same rows, the one with the higher
+    :attr:`Presenter.priority` wins, and an equal priority goes to the later registration. That is
+    what makes a transcript's own presenters the default: they are registered first, at priority 0,
+    so anything a plugin registers for the same rows wins without having to outrank them.
+    :meth:`replacing` appends, which is the same thing for a caller holding a registry rather than a
+    plugin container.
+
+    A presenter for a whole kind is a claim on every row of that kind, so it beats the families
+    registered before it at its priority: a plugin that draws every tool row draws every tool row.
+    A family registered after it, or at a higher priority, is a refinement and keeps its own.
+    """
+
+    def __init__(self, presenters: Iterable[Presenter[Any]]) -> None:
+        """Register presenters in order; for one kind or class, the strongest claim wins."""
+        self._by_kind: dict[EntryKind, tuple[int, int, Presenter[Any]]] = {}
+        self._by_type: dict[type[Entry], tuple[int, int, Presenter[Any]]] = {}
+        for order, presenter in enumerate(presenters):
+            rank = (presenter.priority, order)
+            if presenter.entry_type is not None:
+                current = self._by_type.get(presenter.entry_type)
+                if current is None or rank >= current[:2]:
+                    self._by_type[presenter.entry_type] = (*rank, presenter)
+            else:
+                current = self._by_kind.get(presenter.kind)
+                if current is None or rank >= current[:2]:
+                    self._by_kind[presenter.kind] = (*rank, presenter)
+
+    @property
+    def presenters(self) -> tuple[Presenter[Any], ...]:
+        """Return the presenters that draw something: the kinds' first, then the families'.
+
+        A family a kind's presenter has outranked is left out: it would never be asked for a row.
+        """
+        live = [presenter for _, _, presenter in self._by_kind.values()]
+        live.extend(
+            presenter
+            for priority, order, presenter in self._by_type.values()
+            if self._by_kind.get(presenter.kind) is None or (priority, order) > self._by_kind[presenter.kind][:2]
+        )
+        return tuple(live)
+
+    def replacing(self, *presenters: Presenter[Any]) -> Presenters:
+        """Return a registry that draws the given kinds, and families, with the given presenters."""
+        return Presenters((*self.presenters, *presenters))
+
+    def for_entry(self, entry: Entry) -> Presenter[Any]:
+        """Return the presenter for an entry: the strongest claim on its class or kind, else say so."""
+        family: tuple[int, int, Presenter[Any]] | None = None
+        for cls in type(entry).__mro__:
+            found = self._by_type.get(cls)
+            if found is not None:
+                family = found
+                break
+        kind = self._by_kind.get(entry.kind)
+        if family is not None and (kind is None or family[:2] > kind[:2]):
+            return family[2]
+        if kind is None:
+            raise ValueError(f"No presenter for a {entry.kind.value} row")
+        return kind[2]
+
+    def lines(self, entry: Entry, width: int, theme: Theme, frame: int) -> list[TextLine]:
+        """Return the rows an entry paints, rendered now and not cached."""
+        return self.for_entry(entry).lines(entry, width, theme, frame)
+
+    def block(self, entry: Entry, width: int, theme: Theme, frame: int) -> LineSource:
+        """Return an entry's rows as a cached line source, in the gutter's layout."""
+        return self.for_entry(entry).block(entry, width, theme, frame, self)

zettcode/plugin_api/rows.py

@@ -0,0 +1,91 @@
+"""The line the header and the status line are drawn from, as a plugin's segment may hand it over.
+
+A segment hook returns a styled line, a string, or one of these; the shell joins the parts and drops the ones that
+are hidden. It sits in the contract because the type a hook may return is part of the hook.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import NamedTuple
+
+from zettcode.statusline_parts import Part
+from zettcode.tui.glyphs import SEPARATOR
+
+__all__ = ["GAP", "JOIN", "Piece", "Row"]
+
+JOIN = f" {SEPARATOR} "
+GAP = "  "
+
+
+class Piece(NamedTuple):
+    """A part that is shown, with the characters in front of it: the side's lead, a join, or a gap."""
+
+    glue: str
+    part: Part
+
+
+class Row:
+    """One side of the header or the status line, appended to part by part.
+
+    Shape::
+
+        row = Row(lead="  ").add("app", "The mark and name", "\\u25c8 zettcode").gap()
+        row.add("session", "The session's title", "Fix").add("workspace", "The directory", "~/api")
+        row.text()            # "  \\u25c8 zettcode  Fix \\u00b7 ~/api"
+
+    Parts of one run are joined by :data:`JOIN` and runs by :data:`GAP`. A part that is hidden or has no
+    text takes no room and no separator either, and a side with nothing left is empty rather than a pair of
+    padding spaces — a row too narrow for its right end loses that end, not a stray separator.
+    """
+
+    def __init__(self, *, lead: str = "", trail: str = "") -> None:
+        """Start an empty side.
+
+        Args:
+            lead: Characters before the first part, when there is one.
+            trail: Characters after the last part, when there is one.
+        """
+        self.lead = lead
+        self.trail = trail
+        #: The parts in the order they were added, with ``None`` standing for a break between two runs.
+        self._items: list[Part | None] = []
+
+    def add(self, name: str, summary: str, text: str = "") -> Row:
+        """Append one part, and return this row so the calls chain.
+
+        Args:
+            name: The part's name, which is the switch ``/statusline`` and ``[statusline]`` use.
+            summary: What the part shows, in one line, for the panel.
+            text: What it shows now; empty when it has nothing to say in this session.
+        """
+        self._items.append(Part(name, summary, text))
+        return self
+
+    def gap(self) -> Row:
+        """Begin a new run: the next part shown stands two spaces after the one before it."""
+        self._items.append(None)
+        return self
+
+    def parts(self) -> tuple[Part, ...]:
+        """Return every part that was added, in order, whether or not it has anything to say."""
+        return tuple(item for item in self._items if item is not None)
+
+    def shown(self, hidden: Collection[str] = ()) -> tuple[Piece, ...]:
+        """Return the parts that are neither hidden nor empty, each with what stands in front of it."""
+        pieces: list[Piece] = []
+        glue = self.lead
+        for item in self._items:
+            if item is None:
+                glue = GAP
+            elif item.text and item.name not in hidden:
+                pieces.append(Piece(glue, item))
+                glue = JOIN
+        return tuple(pieces)
+
+    def text(self, hidden: Collection[str] = ()) -> str:
+        """Return the side as the characters it shows, or ``""`` when nothing is left of it."""
+        pieces = self.shown(hidden)
+        if not pieces:
+            return ""
+        return "".join(piece.glue + piece.part.text for piece in pieces) + self.trail