iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/features/buddy/model.py

@@ -0,0 +1,265 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""What a buddy is: the record that is saved, and the living view derived from it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+from chrys.app.features.buddy.progression import FINAL_LEVEL, Progress, earned_xp, progress
+from chrys.foundation.i18n import MessageDef, MessageRef, msg
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+TRAIT_MIN = 1
+TRAIT_MAX = 100
+NAME_MAX_LENGTH = 24
+
+
+class Rarity(StrEnum):
+    """Rarity tiers, lowest first. A buddy evolves upwards through them."""
+
+    N = "N"
+    R = "R"
+    SR = "SR"
+    SSR = "SSR"
+
+    @property
+    def rank(self) -> int:
+        """Position among the tiers, starting at 0."""
+        return _RARITIES.index(self)
+
+
+_RARITIES = tuple(Rarity)
+
+
+class Species(StrEnum):
+    """Every species with pixel artwork, in alphabetical order."""
+
+    ALIEN = "alien"
+    AXOLOTL = "axolotl"
+    BAT = "bat"
+    BEE = "bee"
+    CACTUS = "cactus"
+    CAPYBARA = "capybara"
+    CAT = "cat"
+    CRAB = "crab"
+    DRAGON = "dragon"
+    DUCK = "duck"
+    FOX = "fox"
+    FROG = "frog"
+    GHOST = "ghost"
+    GOOSE = "goose"
+    JELLY = "jelly"
+    LLAMA = "llama"
+    MUSHROOM = "mushroom"
+    OCTOPUS = "octopus"
+    OWL = "owl"
+    PANDA = "panda"
+    PENGUIN = "penguin"
+    RABBIT = "rabbit"
+    ROBOT = "robot"
+    SHARK = "shark"
+    SNAIL = "snail"
+    SNAKE = "snake"
+    TABBY = "tabby"
+    TURTLE = "turtle"
+
+
+class Trait(StrEnum):
+    """What a buddy is like. The strongest trait decides its persona."""
+
+    FOCUS = "focus"
+    CURIOSITY = "curiosity"
+    GRIT = "grit"
+    CHARM = "charm"
+
+
+_PERSONA_FOCUS = msg(
+    "tui.buddy.persona.focus",
+    fallback="Watches every keystroke in silence and hates being interrupted.",
+)
+_PERSONA_CURIOSITY = msg(
+    "tui.buddy.persona.curiosity",
+    fallback="Wants to know what every file does and why it is named that way.",
+)
+_PERSONA_GRIT = msg("tui.buddy.persona.grit", fallback="Never gives up on a failing test, however late it gets.")
+_PERSONA_CHARM = msg("tui.buddy.persona.charm", fallback="Cheers for every green build as if it were the first.")
+# The info card and the sidebar show the persona in the user's language; the model is told it in English.
+_PERSONAS: dict[Trait, MessageDef] = {
+    Trait.FOCUS: _PERSONA_FOCUS,
+    Trait.CURIOSITY: _PERSONA_CURIOSITY,
+    Trait.GRIT: _PERSONA_GRIT,
+    Trait.CHARM: _PERSONA_CHARM,
+}
+
+
+@dataclass(frozen=True)
+class Appearance:
+    """Everything a portrait needs to know."""
+
+    species: Species
+    rarity: Rarity
+    shiny: bool = False
+
+
+@dataclass(frozen=True)
+class BuddyRecord:
+    """The saved buddy: what was drawn when it hatched, and what has happened to it since."""
+
+    species: Species
+    rarity: Rarity
+    shiny: bool
+    traits: Mapping[Trait, int] = field(hash=False)
+    name: str
+    hatched_at: datetime
+    turns: int = 0
+    pets: int = 0
+    muted: bool = False
+
+    def __post_init__(self) -> None:
+        # Frozen all the way down: the caller's mapping is copied and the copy is read-only.
+        object.__setattr__(self, "traits", MappingProxyType(dict(self.traits)))
+
+    def to_json(self) -> dict[str, object]:
+        """The JSON document this record is saved as."""
+        return {
+            "species": self.species.value,
+            "rarity": self.rarity.value,
+            "shiny": self.shiny,
+            "traits": {trait.value: value for trait, value in self.traits.items()},
+            "name": self.name,
+            "hatched_at": self.hatched_at.isoformat(),
+            "turns": self.turns,
+            "pets": self.pets,
+            "muted": self.muted,
+        }
+
+    @classmethod
+    def from_json(cls, document: object) -> BuddyRecord | None:
+        """Read a saved document back, or None unless it is exactly what :meth:`to_json` writes.
+
+        Nothing is coerced: JSON's ``true`` is not a count, ``"7"`` is not a number,
+        and a name that would be cleaned up differently was not written here.
+        """
+        if not isinstance(document, dict) or document.keys() != _DOCUMENT_KEYS:
+            return None
+        try:
+            saved_traits = _exactly(dict, document["traits"])
+            if saved_traits.keys() != _TRAIT_KEYS:
+                return None
+            record = cls(
+                species=Species(_exactly(str, document["species"])),
+                rarity=Rarity(_exactly(str, document["rarity"])),
+                shiny=_exactly(bool, document["shiny"]),
+                traits={trait: _exactly(int, saved_traits[trait.value]) for trait in Trait},
+                name=_exactly(str, document["name"]),
+                hatched_at=datetime.fromisoformat(_exactly(str, document["hatched_at"])),
+                turns=_exactly(int, document["turns"]),
+                pets=_exactly(int, document["pets"]),
+                muted=_exactly(bool, document["muted"]),
+            )
+        except TypeError, ValueError:
+            return None
+        sound = (
+            all(TRAIT_MIN <= value <= TRAIT_MAX for value in record.traits.values())
+            and record.name
+            and record.name == clean_name(record.name)
+            and record.hatched_at.tzinfo is not None
+            and record.turns >= 0
+            and record.pets >= 0
+        )
+        return record if sound else None
+
+
+_DOCUMENT_KEYS = frozenset({"species", "rarity", "shiny", "traits", "name", "hatched_at", "turns", "pets", "muted"})
+_TRAIT_KEYS = frozenset(trait.value for trait in Trait)
+
+
+def _exactly[T](kind: type[T], value: object) -> T:
+    """*value*, which has to be a *kind* and nothing that merely passes for one (``True`` is not an ``int``)."""
+    if not isinstance(value, kind) or type(value) is not kind:
+        raise TypeError(f"expected {kind.__name__}, got {type(value).__name__}")
+    return value
+
+
+def clean_name(name: str) -> str:
+    """One visible line of bounded length: a name is shown in toasts, a nameplate and a prompt.
+
+    Control, formatting and other invisible characters are dropped, so a name cannot
+    be empty to the eye, carry an escape sequence, or reorder the text around it.
+    """
+    words = ("".join(filter(str.isprintable, word)) for word in name.split())
+    return " ".join(word for word in words if word)[:NAME_MAX_LENGTH].rstrip()
+
+
+@dataclass(frozen=True)
+class Buddy:
+    """A record together with how far it has come."""
+
+    record: BuddyRecord
+    progress: Progress
+
+    @classmethod
+    def of(cls, record: BuddyRecord) -> Buddy:
+        """Work out how far *record* has come."""
+        final_stage = len(_RARITIES) - 1 - record.rarity.rank
+        return cls(record, progress(earned_xp(record.turns, record.pets), final_stage))
+
+    @property
+    def name(self) -> str:
+        return self.record.name
+
+    @property
+    def display_name(self) -> str:
+        """The name, marked once the buddy has evolved."""
+        if not self.evolved:
+            return self.name
+        return f"{'🌟' if self.rarity is _RARITIES[-1] else '✨'} {self.name}"
+
+    @property
+    def species(self) -> Species:
+        return self.record.species
+
+    @property
+    def rarity(self) -> Rarity:
+        """The tier the buddy has evolved to."""
+        return _RARITIES[self.record.rarity.rank + self.progress.stage]
+
+    @property
+    def evolved(self) -> bool:
+        return self.progress.stage > 0
+
+    @property
+    def level(self) -> int:
+        return self.progress.level
+
+    @property
+    def shiny(self) -> bool:
+        """Hatched shiny, or earned: evolving into the top tier or finishing it."""
+        earned = self.rarity is _RARITIES[-1] and (self.evolved or self.level == FINAL_LEVEL)
+        return self.record.shiny or earned
+
+    @property
+    def traits(self) -> dict[Trait, int]:
+        """Traits grow a point every ten levels and ten points every evolution."""
+        growth = 10 * self.progress.stage + self.level // 10
+        return {trait: min(TRAIT_MAX, value + growth) for trait, value in self.record.traits.items()}
+
+    @property
+    def persona(self) -> MessageRef:
+        """One sentence of character, set by the trait the buddy hatched strongest in."""
+        return _PERSONAS[max(Trait, key=lambda trait: self.record.traits[trait])].bind()
+
+    @property
+    def muted(self) -> bool:
+        return self.record.muted
+
+    @property
+    def appearance(self) -> Appearance:
+        return Appearance(self.species, self.rarity, self.shiny)

chrys/app/features/buddy/pixel_renderer.py

@@ -0,0 +1,113 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Pixel rendering engine for buddies using Unicode half-blocks."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from PIL import Image
+from rich.color import Color
+from rich.style import Style
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+_HALF_BLOCK = "\u2580"
+DEFAULT_BG_RGB: tuple[int, int, int] = (15, 18, 24)
+
+
+def image_to_half_block_lines(
+    image: Image.Image,
+    *,
+    bg_rgb: tuple[int, int, int] | None = DEFAULT_BG_RGB,
+) -> list[Text]:
+    """Convert a PIL RGBA image into TrueColor Rich Text lines using half-block characters.
+
+    Each terminal character cell represents 2 vertical pixels (1:1 square pixel aspect ratio).
+    Top pixel -> foreground color, Bottom pixel -> background color.
+
+    Args:
+        image: The PIL Image (RGBA or RGB) to render.
+        bg_rgb: Background RGB color to composite transparent pixels against.
+            None preserves the terminal background with binary transparency
+            (alpha below 128 is transparent), since its RGB value is unknown.
+
+    Returns:
+        List of Rich Text instances representing terminal character rows.
+    """
+    image = image.convert("RGBA")
+    # Ensure height is even for half-block pairing
+    if image.height % 2 != 0:
+        padded = Image.new("RGBA", (image.width, image.height + 1), (0, 0, 0, 0))
+        padded.paste(image, (0, 0))
+        image = padded
+
+    if bg_rgb is not None:
+        background = Image.new("RGBA", image.size, (*bg_rgb, 255))
+        background.alpha_composite(image)
+        image = background
+
+    pixels = image.load()
+    if pixels is None:
+        return []
+
+    lines: list[Text] = []
+    width = image.width
+    height = image.height
+
+    for y in range(0, height, 2):
+        line = Text()
+        for x in range(width):
+            upper = cast(tuple[int, int, int, int], pixels[x, y])
+            lower = cast(tuple[int, int, int, int], pixels[x, y + 1])
+            upper_color = Color.from_rgb(*upper[:3]) if upper[3] >= 128 else None
+            lower_color = Color.from_rgb(*lower[:3]) if lower[3] >= 128 else None
+            if upper_color is not None:
+                line.append(_HALF_BLOCK, style=Style(color=upper_color, bgcolor=lower_color))
+            elif lower_color is not None:
+                # Invert the glyph, not the colors: its upper half must inherit
+                # the terminal background rather than painting a guessed RGB.
+                line.append("▄", style=Style(color=lower_color))
+            else:
+                line.append(" ")
+        lines.append(line)
+
+    return lines
+
+
+def matrix_to_image(
+    rows: Sequence[str | Sequence[int]],
+    palette: Mapping[int, tuple[int, int, int, int]],
+) -> Image.Image:
+    """Construct a PIL RGBA Image from a 2D palette index matrix and color map.
+
+    Args:
+        rows: Sequence of rows containing palette indices (as numeric values or digits '0'-'9').
+        palette: Mapping of index -> RGBA tuple.
+
+    Returns:
+        Constructed PIL RGBA Image.
+    """
+    height = len(rows)
+    width = max((len(row) for row in rows), default=0) if height > 0 else 0
+
+    img = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    pixels = img.load()
+    if pixels is None:
+        return img
+
+    for y, row in enumerate(rows):
+        for x, char_or_val in enumerate(row):
+            if isinstance(char_or_val, str):
+                try:
+                    idx = int(char_or_val)
+                except ValueError:
+                    idx = 0
+            else:
+                idx = int(char_or_val)
+
+            pixels[x, y] = palette.get(idx, (0, 0, 0, 0))
+
+    return img

chrys/app/features/buddy/pixel_sprites.py

@@ -0,0 +1,279 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Pixel artwork, blinking, and asset loading for buddies.
+
+Each species' palette and poses are data, kept one file per species in
+``sprites/<species>.toml`` beside this module; this module loads them, applies
+user PNG overrides and builds the frames the portrait renders.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from functools import cache, lru_cache
+from importlib import resources
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from PIL import Image
+
+from chrys.app.features.buddy.animation import IDLE_FRAME_COUNT
+from chrys.app.features.buddy.model import Species
+from chrys.app.features.buddy.pixel_renderer import DEFAULT_BG_RGB, image_to_half_block_lines, matrix_to_image
+from chrys.foundation.platform import get_platform
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+
+    from rich.text import Text
+
+# Resolution: 20 pixels wide x 16 pixels high (maps to 20 columns x 8 rows of terminal character cells)
+PIXEL_WIDTH = 20
+PIXEL_HEIGHT = 16
+
+type Rgba = tuple[int, int, int, int]
+
+# -----------------------------------------------------------------------------
+# Palette roles
+# -----------------------------------------------------------------------------
+
+_SHADOW_PALETTE_KEY = 3  # palette index used for the species' own shadow
+_EYE_PALETTE_KEY = 4  # palette index used for the primary eye colour
+
+# -----------------------------------------------------------------------------
+# Built-in artwork
+# -----------------------------------------------------------------------------
+
+_SPRITES_PACKAGE = "chrys.app.features.buddy"
+_SPRITES_DIR = "sprites"
+
+
+@dataclass(frozen=True, slots=True)
+class SpeciesSprite:
+    """One species' built-in artwork."""
+
+    palette: Mapping[int, Rgba]
+    """Palette index to RGBA color; ``3`` is the body shadow and ``4`` the pupils."""
+    frames: tuple[tuple[str, ...], ...]
+    """Idle poses, each ``PIXEL_HEIGHT`` rows of ``PIXEL_WIDTH`` palette-index digits."""
+
+
+@cache
+def species_sprite(species: Species) -> SpeciesSprite:
+    """Load the packaged artwork for *species*, once per process."""
+    name = f"{species.value}.toml"
+    resource = resources.files(_SPRITES_PACKAGE) / _SPRITES_DIR / name
+    try:
+        data = tomllib.loads(resource.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"{name}: {exc}") from exc
+    return _parse_sprite(name, data)
+
+
+def _parse_sprite(name: str, data: dict[str, Any]) -> SpeciesSprite:
+    """Check the shape the frame builder relies on, so a bad file fails by name."""
+    palette_table = data.get("palette")
+    if not isinstance(palette_table, dict):
+        raise ValueError(f"{name}: no [palette] table")
+    palette = {_parse_index(name, key): _parse_rgba(name, key, value) for key, value in palette_table.items()}
+    missing_roles = {_SHADOW_PALETTE_KEY, _EYE_PALETTE_KEY} - palette.keys()
+    if missing_roles:
+        raise ValueError(f"{name}: the palette has no index {min(missing_roles)}")
+    frame_tables = data.get("frames")
+    if not isinstance(frame_tables, list) or not frame_tables:
+        raise ValueError(f"{name}: no frames")
+    indices = {str(key) for key in palette}
+    frames: list[tuple[str, ...]] = []
+    for frame_idx, frame in enumerate(frame_tables):
+        rows = frame.get("rows") if isinstance(frame, dict) else None
+        if (
+            not isinstance(rows, list)
+            or len(rows) != PIXEL_HEIGHT
+            or any(not isinstance(row, str) or len(row) != PIXEL_WIDTH for row in rows)
+        ):
+            raise ValueError(f"{name}: frame {frame_idx} is not {PIXEL_WIDTH}x{PIXEL_HEIGHT}")
+        unknown = set("".join(rows)) - indices
+        if unknown:
+            raise ValueError(f"{name}: frame {frame_idx} uses indices missing from the palette: {sorted(unknown)}")
+        frames.append(tuple(rows))
+    return SpeciesSprite(palette=MappingProxyType(palette), frames=tuple(frames))
+
+
+def _parse_index(name: str, key: str) -> int:
+    # Each pixel of a frame row is one palette-index digit.
+    if len(key) != 1 or key not in "0123456789":
+        raise ValueError(f"{name}: palette key {key!r} is not a digit 0-9")
+    return int(key)
+
+
+def _parse_rgba(name: str, key: str, value: object) -> Rgba:
+    if (
+        not isinstance(value, list)
+        or len(value) != 4
+        or not all(
+            isinstance(channel, int) and not isinstance(channel, bool) and 0 <= channel <= 255 for channel in value
+        )
+    ):
+        raise ValueError(f"{name}: palette index {key} is not four 0-255 RGBA channels")
+    red, green, blue, alpha = value
+    return (red, green, blue, alpha)
+
+
+def _get_assets_dir() -> Path:
+    """Get path to custom buddy pixel assets directory."""
+    return get_platform().config_dir / "extras" / "buddy" / "assets"
+
+
+@lru_cache(maxsize=128)
+def _load_external_asset(target_path: Path, _revision: tuple[int, int, int]) -> Image.Image:
+    """Keep only resized artwork in a bounded cache, invalidated by file changes."""
+    # Custom artwork is PNG by contract; no other decoder reads the file.
+    with Image.open(target_path, formats=("PNG",)) as opened:
+        img = opened.convert("RGBA")
+        if img.size != (PIXEL_WIDTH, PIXEL_HEIGHT):
+            img = img.resize((PIXEL_WIDTH, PIXEL_HEIGHT), Image.Resampling.NEAREST)
+        # Source metadata may dwarf the thumbnail; the renderer needs pixels only.
+        img.info.clear()
+        return img
+
+
+def load_external_pixel_frame(species: Species, frame_idx: int) -> Image.Image | None:
+    """Load custom artwork from ~/.chrys/extras/buddy/assets/<species>_<frame_idx>.png.
+
+    Checking the revision keeps edits and removals live without decoding the
+    same PNG on every badge repaint. Callers receive their own mutable image.
+    """
+    target_path = _get_assets_dir() / f"{species.value}_{frame_idx}.png"
+    try:
+        stat = target_path.stat()
+        image = _load_external_asset(target_path, (stat.st_mtime_ns, stat.st_ctime_ns, stat.st_size))
+    except Exception:
+        # Failed reads must remain retryable: a Windows sharing violation can
+        # clear without changing the file revision. The LRU caches successes.
+        return None
+    return image.copy()
+
+
+# -----------------------------------------------------------------------------
+# Frame Builder — private helpers
+# -----------------------------------------------------------------------------
+
+
+def _build_petting_frame(frames: Sequence[Sequence[str]], frame_idx: int) -> list[str]:
+    """Animate intact species poses at the caller's faster petting cadence."""
+    pet_phase = frame_idx % IDLE_FRAME_COUNT
+    raw = list(frames[pet_phase % len(frames)])
+    if pet_phase == 0 and all(index == "0" for index in raw[0]):
+        # Hop only when the top row is empty; tall ears, horns, and antennae
+        # already touching the canvas edge must not be clipped off.
+        return [*raw[1:], "0" * PIXEL_WIDTH]
+    return raw
+
+
+def _apply_blink(
+    pixels: Any,
+    raw_frame: list[str],
+    palette: Mapping[int, Rgba],
+) -> None:
+    """Close the upper eye pixels while retaining a native-colored lower lid."""
+    for y, row in enumerate(raw_frame[:-1]):
+        for x, index in enumerate(row):
+            if int(index) == _EYE_PALETTE_KEY and int(raw_frame[y + 1][x]) == _EYE_PALETTE_KEY:
+                # Single-pixel eyes stay intact; taller eyes become a thin
+                # line instead of disappearing into the face's shadow color.
+                pixels[x, y] = palette[_SHADOW_PALETTE_KEY]
+
+
+# -----------------------------------------------------------------------------
+# Frame Builder
+# -----------------------------------------------------------------------------
+
+
+def build_pixel_frame(
+    species: Species,
+    frame_idx: int = 0,
+    blink: bool = False,
+    *,
+    width: int = PIXEL_WIDTH,
+) -> Image.Image:
+    """Construct 20x16 RGBA artwork, fitting it to narrower panels if requested."""
+    # 1. Prefer user-supplied external PNG asset
+    external_img = load_external_pixel_frame(species, frame_idx)
+    if external_img is not None:
+        return _fit_pixel_frame(external_img, width)
+
+    # 2. Keep species colours intact; portrait chrome owns rarity and shiny.
+    sprite = species_sprite(species)
+    palette = sprite.palette
+
+    # 3. Resolve the raw pixel-matrix frame (idle or dynamic petting)
+    frames = sprite.frames
+    raw_frame = (
+        _build_petting_frame(frames, frame_idx)
+        if frame_idx >= IDLE_FRAME_COUNT
+        else list(frames[frame_idx % len(frames)])
+    )
+
+    # 4. Preserve the authored pupil colors; only blinking changes their shape.
+    img = matrix_to_image(raw_frame, palette)
+    pixels = img.load()
+    if pixels is None:
+        raise RuntimeError("The buddy sprite has no pixel buffer.")
+
+    if blink:
+        _apply_blink(pixels, raw_frame, palette)
+
+    if width < PIXEL_WIDTH:
+        # Nearest-neighbor sampling alone can skip a one-column pupil. Keep
+        # its visible pixels at their scaled positions, including closed lids.
+        pupils = [
+            (x, y)
+            for y, row in enumerate(raw_frame)
+            for x, key in enumerate(row)
+            if key == "4" and pixels[x, y] == palette[_EYE_PALETTE_KEY]
+        ]
+        return _fit_pixel_frame(img, width, pupils=pupils)
+    return img
+
+
+def _fit_pixel_frame(image: Image.Image, width: int, *, pupils: list[tuple[int, int]] | None = None) -> Image.Image:
+    """Fit the whole canvas, preserving pupil contrast and a fixed row count."""
+    width = max(1, min(width, PIXEL_WIDTH))
+    if width == PIXEL_WIDTH:
+        return image
+    height = max(1, round(PIXEL_HEIGHT * width / PIXEL_WIDTH))
+    fitted = image.resize((width, height), Image.Resampling.NEAREST)
+    for x, y in pupils or ():
+        target = (int((x + 0.5) * width / PIXEL_WIDTH), int((y + 0.5) * height / PIXEL_HEIGHT))
+        color = image.getpixel((x, y))
+        if color is None:
+            raise RuntimeError("The buddy pupil has no pixel value.")
+        fitted.putpixel(target, color)
+    canvas = Image.new("RGBA", (width, PIXEL_HEIGHT))
+    canvas.paste(fitted, (0, (PIXEL_HEIGHT - height) // 2))
+    return canvas
+
+
+# -----------------------------------------------------------------------------
+# Main Render Function
+# -----------------------------------------------------------------------------
+
+
+def render_pixel_sprite(
+    species: Species,
+    frame: int = 0,
+    blink: bool = False,
+    *,
+    bg_rgb: tuple[int, int, int] | None = DEFAULT_BG_RGB,
+    width: int = PIXEL_WIDTH,
+) -> list[Text]:
+    """Fit pixel artwork to the available columns, retaining eight terminal rows."""
+    img = build_pixel_frame(
+        species,
+        frame_idx=frame,
+        blink=blink,
+        width=width,
+    )
+    return image_to_half_block_lines(img, bg_rgb=bg_rgb)