scrollkit 0.8.3__py3-none-any.whl

scrollkit/display/gradient_text.py

@@ -0,0 +1,167 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Static directional gradient / palette text fill (indexed-bitmap renderer).
+
+When ``StaticText`` / ``ScrollingText`` are given a ``palette``, their glyphs are
+rasterised ONCE — through the shared :func:`~scrollkit.display.text_pixels.\
+pixels_from_font_text` helper, so the *real* display font (terminalio by default)
+is preserved — into an indexed ``Bitmap`` whose every lit pixel carries a palette
+*index* equal to its position along the chosen axis. The text then shows / scrolls
+by moving a ``TileGrid``: no glyph rebuild and **zero per-frame pixel writes**,
+exactly like ``BitmapText``. The difference is that the palette here is a FIXED
+ramp (a static gradient), not a per-frame animation — animated colour stays the
+distinct concern of ``BitmapText`` + ``palette_effect``.
+
+A displayio ``Label`` is physically one colour (a 2-entry indexed bitmap), so this
+indexed-bitmap path is the only way to colour the normal font per-pixel. Runs
+unchanged on the simulator and on CircuitPython via ``display.gfx`` (integer-only;
+no per-frame allocation).
+"""
+
+from .colors import gradient, multi_gradient
+from .text_fill import clamp_palette_steps, normalize_direction
+from .text_pixels import font_text_ascent, font_text_width, pixels_from_font_text
+
+__all__ = ["GradientTextLayer"]
+
+# The Label path positions a line's baseline at screen row ``y + 4`` (the
+# simulator's adafruit_display_text.Label applies a device-compat offset so the
+# sim matches hardware). pixels_from_font_text rasterises with the run's baseline
+# `ascent` rows below the top, so placing tile.y = y + 4 - ascent puts that
+# baseline on the Label's baseline. The `ascent` term then cancels: every glyph
+# pixel lands at `y + 4 - height - y_offset + gy`, identical to the flat Label
+# path per glyph (descenders included). Pinned by test_gradient_text.py.
+_BASELINE_DROP = 4
+
+
+def _build_ramp(palette, steps):
+    """A ``steps``-long tuple of ``0xRRGGBB`` from the user's palette stops.
+
+    Two stops -> a straight :func:`gradient`; three or more -> a
+    :func:`multi_gradient` across them; one (or none) -> a flat fill.
+    """
+    stops = tuple(palette) if palette else ()
+    if len(stops) <= 1:
+        c = stops[0] if stops else 0xFFFFFF
+        return tuple(c for _ in range(max(1, steps)))
+    if len(stops) == 2:
+        return gradient(stops[0], stops[1], steps)
+    return multi_gradient(stops, steps)
+
+
+class GradientTextLayer:
+    """Owns the indexed bitmap, palette and TileGrid for one gradient string.
+
+    Build once (rasterise + positional index map, paid on the first frame), then
+    reposition by setting :attr:`x`; :meth:`detach` removes the layer.
+    ``StaticText`` / ``ScrollingText`` drive it via their ``palette=`` argument for
+    the common case; use this class directly for custom positioning/animation.
+
+    Args:
+        text: The string to rasterise.
+        y: Baseline row (screen coordinates; matches ``StaticText``/``ScrollingText``).
+        palette: A tuple of ``0xRRGGBB`` gradient stops (1 = flat fill, 2 = a
+            straight gradient, 3+ = a multi-stop gradient across the run).
+        direction: ``"vertical"`` (default), ``"horizontal"``, or ``"diagonal"``.
+        palette_steps: Ramp resolution (2..``MAX_PALETTE_STEPS``); ignored for a
+            single-colour palette.
+    """
+
+    def __init__(self, text, y, palette, direction="vertical", palette_steps=8):
+        self.text = text
+        self.y = y
+        self.palette = tuple(palette) if palette else ()
+        self.direction = normalize_direction(direction)
+        # A single-colour palette is a degenerate (flat) gradient: ramp length 1.
+        # Otherwise clamp to 2..MAX_PALETTE_STEPS so steps + transparent(0) <= 16
+        # keeps the bitmap at 4 bits/pixel.
+        self.steps = 1 if len(self.palette) <= 1 else clamp_palette_steps(palette_steps)
+        self.width = 0
+        self._bitmap = None
+        self._palette = None
+        self._tile = None
+
+    def build(self, display):
+        """Rasterise the text into an indexed bitmap and add it as a layer."""
+        gfx = display.gfx
+        font = getattr(display, "font", None)
+        # Top-origin rasterisation; the layer is positioned vertically via tile.y.
+        pixels = pixels_from_font_text(font, self.text, x=0, y=0)
+        advance = font_text_width(font, self.text)
+        ascent = font_text_ascent(font, self.text)   # baseline row within the raster
+        if pixels:
+            max_x = max(p[0] for p in pixels)
+            ys = [p[1] for p in pixels]
+            min_y, max_y = min(ys), max(ys)
+        else:
+            max_x = min_y = max_y = 0
+        # Full advance width (includes trailing spaces) so a horizontal ramp is
+        # stable across the whole phrase; widen if any glyph overhangs its advance.
+        width = max(1, advance, max_x + 1)
+        height = max_y + 1
+
+        ramp = _build_ramp(self.palette, self.steps)
+        n = len(ramp)
+        bitmap = gfx.Bitmap(width, height, n + 1)
+        palette = gfx.Palette(n + 1)
+        palette.make_transparent(0)                 # index 0 = transparent ground
+        for i in range(n):
+            palette[1 + i] = ramp[i]
+
+        # Each lit pixel's palette index is its position along the axis (NO modulo,
+        # so the ramp spans the whole word end-to-end rather than tiling). One O(1)
+        # lookup per lit pixel, paid once at build.
+        span_x = width - 1
+        span_y = max_y - min_y
+        last = n - 1
+        for (px, py) in pixels:
+            bitmap[px, py] = self._ramp_index(px, py, min_y, span_x, span_y, last) + 1
+
+        tile = gfx.TileGrid(bitmap, pixel_shader=palette)
+        tile.x = display.width                       # start off the right edge
+        tile.y = self.y + _BASELINE_DROP - ascent    # baseline-align to the Label
+        display.add_layer(tile)
+
+        self._bitmap = bitmap
+        self._palette = palette
+        self._tile = tile
+        self.width = width
+
+    def _ramp_index(self, x, y, min_y, span_x, span_y, last):
+        """Position -> ramp index 0..last for the configured direction."""
+        if last <= 0:
+            return 0
+        d = self.direction
+        if d == "horizontal":
+            num, den = x, span_x
+        elif d == "diagonal":
+            num, den = x + (y - min_y), span_x + span_y
+        else:                                        # vertical (default)
+            num, den = (y - min_y), span_y
+        if den <= 0:
+            return 0
+        ramp_i = num * last // den
+        if ramp_i < 0:
+            return 0
+        if ramp_i > last:
+            return last
+        return ramp_i
+
+    @property
+    def x(self):
+        return self._tile.x if self._tile is not None else 0
+
+    @x.setter
+    def x(self, value):
+        if self._tile is not None:
+            self._tile.x = value
+
+    def detach(self, display):
+        """Remove the layer (idempotent — remove_layer ignores an absent tile)."""
+        if self._tile is not None:
+            display.remove_layer(self._tile)
+            self._tile = None
+
+
+# 0.8.x compatibility alias: themeparkwaits (and any other pre-0.8.2 caller)
+# imports the old private name directly. Kept until a future 0.9.0.
+_GradientTextLayer = GradientTextLayer

scrollkit/display/interface.py

@@ -0,0 +1,126 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Display interface for SLDK.
+
+This provides the abstract interface that all display implementations must follow.
+Compatible with both CircuitPython and desktop Python.
+"""
+
+from __future__ import annotations
+
+try:
+    from typing import Any, Optional
+except ImportError:  # CircuitPython has no 'typing' module
+    pass
+
+
+__all__ = ['DisplayInterface']
+
+class DisplayInterface:
+    """Base interface for all display implementations."""
+
+    @property
+    def width(self) -> int:
+        """Display width in pixels."""
+        raise NotImplementedError("Subclass must implement width property")
+
+    @property
+    def height(self) -> int:
+        """Display height in pixels."""
+        raise NotImplementedError("Subclass must implement height property")
+
+    async def initialize(self) -> None:
+        """Initialize the display hardware or simulator."""
+        raise NotImplementedError("Subclass must implement initialize()")
+
+    async def clear(self) -> None:
+        """Clear the display."""
+        raise NotImplementedError("Subclass must implement clear()")
+
+    async def show(self) -> bool:
+        """Update the physical display.
+
+        Returns False when the user closed the simulator window (so the app loop
+        can shut down); True otherwise.
+        """
+        raise NotImplementedError("Subclass must implement show()")
+
+    async def set_pixel(self, x: int, y: int, color: int) -> None:
+        """Set a single pixel color.
+        
+        Args:
+            x: X coordinate
+            y: Y coordinate  
+            color: Color as 24-bit RGB integer (0xRRGGBB)
+        """
+        raise NotImplementedError("Subclass must implement set_pixel()")
+    
+    async def fill(self, color: int) -> None:
+        """Fill entire display with color.
+        
+        Args:
+            color: Color as 24-bit RGB integer (0xRRGGBB)
+        """
+        # Default implementation using set_pixel
+        for y in range(self.height):
+            for x in range(self.width):
+                await self.set_pixel(x, y, color)
+    
+    async def set_brightness(self, brightness: float) -> None:
+        """Set display brightness.
+        
+        Args:
+            brightness: Float between 0.0 and 1.0
+        """
+        raise NotImplementedError("Subclass must implement set_brightness()")
+    
+    # Higher-level convenience methods with default implementations
+    
+    async def draw_text(self, text: str, x: int = 0, y: int = 0, color: int = 0xFFFFFF, font: Any = None) -> None:
+        """Draw text on display.
+
+        Args:
+            text: Text to display
+            x: Starting X coordinate
+            y: Starting Y coordinate
+            color: Text color as 24-bit RGB
+            font: Font to use (implementation specific)
+        """
+        # Not a silent no-op: a DisplayInterface that can't draw text is a bug,
+        # and the concrete displays (Unified/Simulator via GraphicsMixin) all
+        # override this.
+        raise NotImplementedError("Subclass must implement draw_text()")
+
+    # --- bounded painters + graphics bridge (see display/_graphics.py) --------
+    # Real displays mix in GraphicsMixin, which provides concrete implementations
+    # backed by C bulk ops (bitmaptools). These stubs document the contract for
+    # any other DisplayInterface.
+
+    async def fill_rect(self, x: int, y: int, w: int, h: int, color: int) -> None:
+        """Fill a bounded rectangle with ``color`` via a C bulk op (no full loop)."""
+        raise NotImplementedError("Subclass must implement fill_rect()")
+
+    async def fill_span(self, y: int, x0: int, x1: int, color: int) -> None:
+        """Fill the single-row span ``[x0, x1)`` with ``color``."""
+        raise NotImplementedError("Subclass must implement fill_span()")
+
+    async def clear_rect(self, x: int, y: int, w: int, h: int) -> None:
+        """Clear a bounded rectangle back to the background."""
+        raise NotImplementedError("Subclass must implement clear_rect()")
+
+    def measure_text(self, text: str, font: Any = None) -> int:
+        """Rendered pixel width of ``text`` (summed glyph advances; not len*6)."""
+        return len(text) * 6   # coarse fallback; real displays override
+
+    @property
+    def gfx(self) -> Any:
+        """Platform-resolved graphics namespace (Bitmap/Palette/TileGrid/Group/
+        bitmaptools), cached per display."""
+        raise NotImplementedError("Subclass must implement gfx")
+
+    def add_layer(self, tilegrid: Any) -> None:
+        """Composite a TileGrid above content (persistent across frames)."""
+        raise NotImplementedError("Subclass must implement add_layer()")
+
+    def remove_layer(self, tilegrid: Any) -> None:
+        """Remove a layer added via add_layer()."""
+        raise NotImplementedError("Subclass must implement remove_layer()")

scrollkit/display/simulator.py

@@ -0,0 +1,80 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Simulator display for SLDK — the interactive desktop entry point.
+
+``SimulatorDisplay`` IS ``UnifiedDisplay`` (one per-frame pipeline: the same
+clear/draw_text/set_pixel/fill/show code that runs on hardware, over the
+emulated ``displayio`` backend). What this subclass adds is purely the desktop
+developer ergonomics:
+
+- opens the pygame window automatically on the first ``show()``
+- constructor knobs for the window (``scale``) and recording quality (``pitch``)
+- the hardware-timing flags as first-class constructor args (they exist on
+  ``UnifiedDisplay`` too)
+
+Everything else — recording (``start_recording`` / ``save_gif`` /
+``save_video``), ``screenshot``, the painters, the label pools, feasibility —
+is inherited. If simulator output ever disagrees with hardware, fix the
+simulator backend (``scrollkit.simulator``), never this class: there is no
+per-class render logic left to diverge.
+"""
+
+from __future__ import annotations
+
+import sys
+
+# Verify we're NOT on CircuitPython
+if hasattr(sys, 'implementation') and sys.implementation.name == 'circuitpython':
+    raise ImportError("Simulator display cannot be used on CircuitPython")
+
+from .unified import UnifiedDisplay, LED_SIMULATOR_AVAILABLE
+
+if not LED_SIMULATOR_AVAILABLE:
+    raise ImportError(
+        "SLDK simulator not available. "
+        "Ensure all SLDK components are properly installed."
+    )
+
+
+__all__ = ['SimulatorDisplay']
+
+
+class SimulatorDisplay(UnifiedDisplay):
+    """Interactive desktop display: UnifiedDisplay + an auto-created window."""
+
+    _WINDOW_TITLE = "SLDK Simulator"
+    _AUTO_WINDOW = True
+
+    def __init__(self, width: int = 64, height: int = 32, scale: int = 10,
+                 *, hardware_timing: bool = False, throttle: bool = False,
+                 strict: bool = False, board=None, pitch: float = 3.0):
+        """Initialize the simulator display.
+
+        Args:
+            width: Display width in pixels
+            height: Display height in pixels
+            scale: Window scale factor (fallback when the LED renderer doesn't
+                publish its own surface size)
+            hardware_timing: Model how slow the real CircuitPython device would
+                run (read the estimate via feasibility_report()). Off by default;
+                also enabled by the env var SCROLLKIT_HW_SIM=1.
+            throttle: When hardware_timing is on, also sleep so the window crawls
+                at the modeled hardware speed (off by default; tests never use it).
+            strict: Enforce the feasibility gate — a sustained over-budget run (or
+                a catastrophic single frame, or a RAM breach) raises
+                FeasibilityError instead of just warning. Implies hardware_timing.
+                Also enabled by SCROLLKIT_HW_STRICT=1. Off by default.
+            board: Which board's performance profile to model for hardware
+                timing/feasibility (e.g. ``"pimoroni_interstate75_w"``). ``None``
+                honors ``SCROLLKIT_HW_BOARD`` and defaults to the MatrixPortal S3.
+            pitch: LED pitch (mm) -> on-screen LED size. Raise it (e.g. 6.0) to
+                render the panel at a higher resolution for crisp recordings and
+                screenshots; changes only the visual scale, not the pixel grid.
+        """
+        super().__init__(width=width, height=height, board=board,
+                         hardware_timing=hardware_timing, throttle=throttle,
+                         strict=strict, pitch=pitch)
+        self._scale: int = scale
+
+    async def initialize(self) -> None:
+        await super().initialize()
+        print("Simulator display initialized")

scrollkit/display/text_fill.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Shared vocabulary for gradient text fills (the live source of truth).
+
+Kept deliberately tiny and dependency-free (pure constants + functions, no
+displayio, no colour math) so the RAM-constrained device pays almost nothing to
+import it, and so three callers can share ONE definition instead of hardcoding
+the strings in each place:
+
+* ``display.content`` — validates the ``direction`` argument at construction;
+* ``display.gradient_text`` — maps a pixel's position to a ramp index per axis;
+* ``dev.capabilities`` — advertises the directions to the AI-authoring catalog by
+  calling :func:`gradient_directions` (never a copy-pasted tuple), the same
+  live-introspection discipline ``transition_names`` / ``palette_effects_for``
+  already use.
+"""
+
+# The three gradient axes, matching ``SwarmReveal``'s colour-axis vocabulary so a
+# user learns one set of names. "vertical" is the default because a top-light →
+# bottom-dark shade reads as depth (the common "subtle" case). Reverse any axis by
+# reversing the palette tuple — there is intentionally no ``*_reverse`` name.
+GRADIENT_DIRECTIONS = ("vertical", "horizontal", "diagonal")
+
+# Default number of palette ramp steps generated from the stops. Small on purpose:
+# the panel is RGB444 (4 bits/channel) at the default bit_depth=4, so more steps
+# rarely survive as distinct colours.
+DEFAULT_PALETTE_STEPS = 8
+
+# Hard cap. ``steps`` colours plus the transparent background (palette index 0)
+# must fit in 16 values to keep the indexed bitmap at 4 bits/pixel (RAM + speed).
+MAX_PALETTE_STEPS = 15
+
+
+__all__ = ['gradient_directions', 'normalize_direction', 'clamp_palette_steps', 'GRADIENT_DIRECTIONS', 'DEFAULT_PALETTE_STEPS', 'MAX_PALETTE_STEPS']
+
+def gradient_directions():
+    """The supported gradient ``direction`` values, as a tuple of strings."""
+    return GRADIENT_DIRECTIONS
+
+
+def normalize_direction(direction):
+    """Return ``direction`` if valid, else fall back to ``"vertical"``.
+
+    Mirrors ``SwarmReveal``'s lenient handling: an unknown axis name degrades to
+    the sensible default rather than raising on the device.
+    """
+    return direction if direction in GRADIENT_DIRECTIONS else "vertical"
+
+
+def clamp_palette_steps(steps):
+    """Clamp a requested ramp length into the 2..``MAX_PALETTE_STEPS`` range."""
+    try:
+        steps = int(steps)
+    except (TypeError, ValueError):
+        return DEFAULT_PALETTE_STEPS
+    if steps < 2:
+        return 2
+    if steps > MAX_PALETTE_STEPS:
+        return MAX_PALETTE_STEPS
+    return steps

scrollkit/display/text_pixels.py

@@ -0,0 +1,250 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Font/scale-aware text → lit-pixel composition (single source of truth).
+
+``pixels_from_font_text`` renders a string with *any* loaded font at an integer
+scale and returns the list of lit ``(x, y)`` pixels — the same ``[(x, y), ...]``
+format the splash effects and the gradient text-fill renderer consume.  Because
+the drip animation, the live on-screen image, *and* gradient text are all built
+from this one function, the pixels are identical **by construction** — there is
+nothing to "match" and no chance of desktop/device drift.
+
+It is a pure function over the font's glyph bitmaps (no displayio Bitmap is
+allocated, no ``gfx`` needed), so it runs unchanged on the simulator and on
+CircuitPython.  The one real platform difference it papers over is the glyph
+object shape:
+
+* simulator ``font.get_glyph`` returns a **dict** (``'dx'`` is the advance,
+  ``'x_offset'`` the left bearing, ``'y_offset'`` the baseline-relative vertical
+  offset, ``'bitmap'`` the glyph bitmap);
+* CircuitPython ``adafruit_bitmap_font`` returns an **object** (``.shift_x`` is
+  the advance, ``.dx`` the left bearing, ``.dy`` the vertical offset, ``.bitmap``
+  the glyph bitmap).
+
+Glyphs are laid out left-to-right by advance and **baseline-aligned** (each glyph
+sits at ``baseline - height - y_offset``, so descenders drop below the line and
+short glyphs rest on it), matching ``adafruit_display_text.Label`` — so mixed-case
+prose with descenders renders correctly, not just digits and ALL-CAPS runs. The
+shared baseline sits ``font_text_ascent`` pixels below ``y`` (``y`` is the top of
+the tallest glyph in the run).
+
+This module lives in ``display/`` (not ``effects/``) on purpose: it is depended
+on by both ``display.gradient_text`` and the ``effects`` splash animations, and
+``effects`` already imports from ``display``.  Homing it here keeps the
+``display → effects`` direction from ever forming a cycle and stops the
+RAM-heavy ``effects`` package (particles/splashes) from loading just to render
+text.  ``effects/text_render.py`` re-exports these names for backwards
+compatibility.
+"""
+
+# Advance used when a glyph is missing entirely (keeps spacing sane).
+_MISSING_ADVANCE = 4
+
+
+__all__ = ['pixels_from_font_text', 'font_text_width', 'font_text_ascent']
+
+def _glyph_fields(glyph):
+    """Normalise a glyph (dict on simulator, object on device) to a tuple.
+
+    Returns ``(bitmap, width, height, x_bearing, y_offset, advance, sheet_x,
+    sheet_y)`` or ``None`` when the glyph is absent.  ``bitmap`` may be ``None``
+    (e.g. a space) — the caller still advances by ``advance``.
+
+    ``y_offset`` is the BDF ``BBX`` vertical offset: the bitmap's bottom edge sits
+    that many pixels above the baseline (so it is **negative for descenders**).
+    The top of the glyph relative to the baseline is therefore
+    ``baseline - height - y_offset`` — exactly what ``adafruit_display_text.Label``
+    uses, so callers can baseline-align mixed-height text instead of top-aligning
+    it.  On the simulator the glyph dict carries it as ``'y_offset'``; on
+    CircuitPython the ``adafruit_bitmap_font`` glyph object carries it as ``.dy``
+    (same sign convention — verify on hardware if in doubt).
+
+    ``sheet_x/sheet_y`` are the glyph's pixel origin *within* ``bitmap``: 0,0 for
+    per-glyph bitmaps (most BDF loads + the simulator), but non-zero for
+    built-in/packed fonts whose glyphs all share one sprite-sheet bitmap addressed
+    by ``tile_index`` (e.g. the device's ``terminalio`` font, where ``bitmap`` is
+    the whole 570x12 sheet).
+    """
+    if glyph is None:
+        return None
+    if isinstance(glyph, dict):
+        bmp = glyph.get("bitmap")
+        gw = glyph.get("width", 0) or 0
+        gh = glyph.get("height", 0) or 0
+        xoff = glyph.get("x_offset", 0) or 0
+        yoff = glyph.get("y_offset", 0) or 0  # simulator: BDF y-offset (baseline-rel)
+        adv = glyph.get("dx")                 # simulator: 'dx' is the advance
+        if adv is None:
+            adv = glyph.get("shift_x", gw)
+        return (bmp, gw, gh, xoff, yoff, adv if adv is not None else gw, 0, 0)
+    bmp = getattr(glyph, "bitmap", None)
+    gw = getattr(glyph, "width", 0) or 0
+    gh = getattr(glyph, "height", 0) or 0
+    xoff = getattr(glyph, "dx", 0) or 0       # device: '.dx' is the left bearing
+    yoff = getattr(glyph, "dy", 0) or 0       # device: '.dy' is the BDF y-offset
+    adv = getattr(glyph, "shift_x", None)     # device: '.shift_x' is the advance
+    if adv is None:
+        adv = gw
+    # Packed sprite-sheet fonts (terminalio built-in): every glyph's '.bitmap' is
+    # the same wide sheet; the glyph lives at tile '.tile_index'. Detect by the
+    # sheet being wider than one glyph and resolve the tile's top-left origin.
+    sheet_x = sheet_y = 0
+    if bmp is not None and gw:
+        try:
+            bw = bmp.width
+        except (AttributeError, TypeError):
+            bw = gw
+        if bw > gw:
+            tile_index = getattr(glyph, "tile_index", 0) or 0
+            tiles_per_row = bw // gw if gw else 1
+            if tiles_per_row < 1:
+                tiles_per_row = 1
+            sheet_x = (tile_index % tiles_per_row) * gw
+            sheet_y = (tile_index // tiles_per_row) * gh
+    return (bmp, gw, gh, xoff, yoff, adv, sheet_x, sheet_y)
+
+
+def _run_ascent(fields_list):
+    """Rows above the baseline for the TALLEST glyph in a resolved run (unscaled).
+
+    ``height + y_offset`` is a glyph's extent above the baseline; the run's ascent
+    is the max of that. It is the baseline's row offset from the top of the run,
+    and the smallest value that keeps every glyph (placed at
+    ``ascent - height - y_offset``) at a non-negative row.
+    """
+    run = 0
+    for fields in fields_list:
+        if fields is not None:
+            _b, _gw, gh, _x, yoff, _a, _sx, _sy = fields
+            if gh and (gh + yoff) > run:
+                run = gh + yoff
+    return run
+
+
+def pixels_from_font_text(font, text, x=0, y=0, scale=1):
+    """Return ``[(x, y), ...]`` lit pixels for ``text`` in ``font`` at ``scale``.
+
+    Glyphs are **baseline-aligned**: the run's shared baseline sits
+    ``font_text_ascent(font, text, scale)`` pixels below ``y``, and each glyph is
+    placed at ``baseline - height - y_offset`` (descenders drop below the line),
+    matching ``adafruit_display_text.Label``. For an equal-height run (digits, an
+    ALL-CAPS word) this is identical to plain top-alignment; for mixed-case prose
+    with descenders it renders correctly instead of floating the short letters up.
+
+    Args:
+        font:  A loaded font exposing ``get_glyph(codepoint)`` (the display's
+               ``self.font`` — terminalio by default).
+        text:  String to render.
+        x:     Left edge of the first glyph, in display pixels.
+        y:     Top edge of the text (the top of the tallest glyph), in display px.
+        scale: Integer magnification (>=1); each lit cell becomes a
+               ``scale`` x ``scale`` block, matching ``draw_text_scaled``.
+
+    Returns:
+        List of ``(x, y)`` integer tuples for every lit pixel.
+
+    Example — a 2x wait-time number, centred on a 64-wide display::
+
+        from scrollkit.display.text_pixels import pixels_from_font_text
+        # width is len*advance*scale; centre it, then drip these pixels in.
+        px = pixels_from_font_text(display.font, "45", x=20, y=8, scale=2)
+    """
+    if scale is None or scale < 1:
+        scale = 1
+    scale = int(scale)
+
+    # Resolve every glyph once, then find the run's baseline (tallest glyph above
+    # it) so shorter glyphs and descenders can be placed relative to it.
+    resolved = [_glyph_fields(font.get_glyph(ord(ch)) if font is not None else None)
+                for ch in text]
+    ascent = _run_ascent(resolved)
+
+    pixels = []
+    pen_x = x
+    for fields in resolved:
+        if fields is None:
+            pen_x += _MISSING_ADVANCE * scale
+            continue
+        bmp, gw, gh, xoff, yoff, adv, sheet_x, sheet_y = fields
+        if bmp is not None and gw and gh:
+            base_x = pen_x + xoff * scale
+            # Top of this glyph on a baseline shared by the whole run.
+            glyph_top = y + (ascent - gh - yoff) * scale
+            for gx in range(gw):
+                for gy in range(gh):
+                    if bmp[sheet_x + gx, sheet_y + gy]:
+                        px0 = base_x + gx * scale
+                        py0 = glyph_top + gy * scale
+                        for sx in range(scale):
+                            for sy in range(scale):
+                                pixels.append((px0 + sx, py0 + sy))
+        pen_x += (adv if adv else gw) * scale
+    return pixels
+
+
+def font_text_ascent(font, text, scale=1):
+    """Baseline row offset (px below ``y``) for ``text`` — how far below the top of
+    the rendered run its shared baseline sits, so a caller positioning the pixels
+    itself (the gradient text layer) can baseline-align to the ``Label`` path.
+
+    Derived from the glyphs' real **ink bottoms** (the most common bottom row is the
+    baseline), NOT from the reported glyph heights. That distinction is the whole
+    fix for the device: its built-in ``terminalio`` font is a FULL-CELL font — every
+    glyph is a 6x12 tile with ``height=12, dy=0`` and the true baseline buried inside
+    the cell — so ``max(height + y_offset)`` returns the cell bottom (12), which
+    pushes the text up and clips the cap tops on mixed-case names. Ink-bottoms give
+    the real baseline (~10) on that font and reduce to ``run_ascent`` on the
+    simulator's trimmed BDF font, so one rule serves both. Falls back to the metric
+    ascent when no ink is found (all spaces / empty).
+    """
+    if scale is None or scale < 1:
+        scale = 1
+    scale = int(scale)
+    resolved = [_glyph_fields(font.get_glyph(ord(ch)) if font is not None else None)
+                for ch in text]
+    # Same placement reference pixels_from_font_text uses, so ink rows land in the
+    # same coordinate space as the rasterised pixels.
+    ascent = _run_ascent(resolved)
+    counts = {}
+    for fields in resolved:
+        if fields is None:
+            continue
+        bmp, gw, gh, _xoff, yoff, _adv, sheet_x, sheet_y = fields
+        if bmp is None or not gw or not gh:
+            continue
+        glyph_top = ascent - gh - yoff
+        for ry in range(gh - 1, -1, -1):           # this glyph's lowest ink row
+            if any(bmp[sheet_x + rx, sheet_y + ry] for rx in range(gw)):
+                row = glyph_top + ry
+                counts[row] = counts.get(row, 0) + 1
+                break
+    if not counts:
+        return ascent * scale                       # no ink -> metric fallback
+    # baseline-1 == the most common ink bottom. Ties resolve to the HIGHER row
+    # (smaller value) — the body baseline rather than a descender's bottom — which
+    # is also the smaller ascent, so the text shifts DOWN, never up into a top clip.
+    best_row, best_n = None, -1
+    for row, n in counts.items():
+        if n > best_n or (n == best_n and row < best_row):
+            best_row, best_n = row, n
+    return (best_row + 1) * scale
+
+
+def font_text_width(font, text, scale=1):
+    """Total advance width (px) of ``text`` in ``font`` at ``scale``.
+
+    Mirrors the layout ``pixels_from_font_text`` uses, so callers can centre the
+    text (``x = (display.width - font_text_width(...)) // 2``) and get pixels
+    that line up with a later ``draw_text_scaled`` of the same string.
+    """
+    if scale is None or scale < 1:
+        scale = 1
+    scale = int(scale)
+    total = 0
+    for ch in text:
+        fields = _glyph_fields(font.get_glyph(ord(ch)) if font is not None else None)
+        if fields is None:
+            total += _MISSING_ADVANCE
+            continue
+        _bmp, gw, _gh, _xoff, _yoff, adv, _sx, _sy = fields
+        total += adv if adv else gw
+    return total * scale