scrollkit 0.8.3__py3-none-any.whl

scrollkit/display/_recording.py

@@ -0,0 +1,165 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Desktop-only frame capture + encoding for the display recording API.
+
+The user-facing methods (``start_recording`` / ``save_gif`` / ``save_video`` /
+``screenshot``) live on ``UnifiedDisplay`` (and are therefore inherited by
+``SimulatorDisplay``); the heavy pygame/Pillow/ffmpeg work lives here so the
+RAM-constrained device never loads a byte of it — this module is only ever
+imported lazily from inside those methods, on desktop.
+"""
+
+from __future__ import annotations
+
+
+def capture_frame(matrix):
+    """Return the matrix's current LED-panel surface as an (H, W, 3) uint8 array,
+    or None when pygame/the surface isn't available."""
+    try:
+        import pygame
+    except ImportError:
+        return None
+    surface = (matrix.get_surface()
+               if matrix is not None and hasattr(matrix, "get_surface")
+               else None)
+    if surface is None:
+        return None
+    # array3d gives (W, H, 3); transpose to image orientation (H, W, 3).
+    return pygame.surfarray.array3d(surface).transpose(1, 0, 2).copy()
+
+
+def save_surface_png(matrix, path):
+    """Save the current LED-panel surface (or the window surface) to ``path``.
+
+    Returns the path on success or None when pygame/no surface is available.
+    """
+    try:
+        import pygame
+    except ImportError:
+        return None
+    surface = None
+    if matrix is not None and hasattr(matrix, "get_surface"):
+        surface = matrix.get_surface()
+    if surface is None and pygame.get_init():
+        surface = pygame.display.get_surface()
+    if surface is None:
+        return None
+    try:
+        pygame.image.save(surface, path)
+        return path
+    except (pygame.error, OSError) as e:
+        print(f"screenshot failed: {e}")
+        return None
+
+
+def encode_gif(frames, path, *, fps=20, target_width=360, max_colors=48,
+               loop=0, frame_step=1, disposal=1):
+    """Encode recorded frames to an animated GIF (see ``save_gif`` docstring)."""
+    if not frames:
+        return None
+    try:
+        from PIL import Image
+    except ImportError:
+        print("save_gif failed: Pillow not installed (pip install Pillow)")
+        return None
+
+    kept = frames[::max(1, int(frame_step))]
+    rgb = []
+    for arr in kept:
+        img = Image.fromarray(arr, "RGB")
+        if target_width and img.width != target_width:
+            h = max(1, round(img.height * target_width / img.width))
+            img = img.resize((target_width, h), Image.LANCZOS)
+        rgb.append(img)
+
+    # One shared palette from a handful of evenly-sampled frames: stable
+    # colors across the loop (no per-frame flicker) and a much smaller file.
+    sample = rgb[::max(1, len(rgb) // 16)]
+    montage = Image.new("RGB", (rgb[0].width, rgb[0].height * len(sample)))
+    for i, frame_img in enumerate(sample):
+        montage.paste(frame_img, (0, i * rgb[0].height))
+    palette = montage.quantize(colors=max_colors, method=Image.MEDIANCUT)
+    paletted = [im.quantize(palette=palette) for im in rgb]
+
+    duration = int(round(1000.0 / fps)) * max(1, int(frame_step))
+    try:
+        # disposal=1 ("do not dispose") leaves the prior frame in place so
+        # Pillow can crop each frame to just its changed region — the static
+        # LED-panel background is written once, shrinking the file several-fold
+        # versus disposal=2 (which restores to background and forces full frames).
+        paletted[0].save(path, save_all=True, append_images=paletted[1:],
+                         duration=duration, loop=loop, optimize=True,
+                         disposal=disposal)
+        return path
+    except (OSError, ValueError) as e:
+        print(f"save_gif failed: {e}")
+        return None
+
+
+def encode_video(frames, path, *, fps=24, target_width=None, crf=20,
+                 preset="medium", border=0, border_color=(10, 10, 13)):
+    """Encode recorded frames to MP4/H.264 via ffmpeg (see ``save_video``)."""
+    import shutil
+    import subprocess
+
+    if not frames:
+        return None
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        print("save_video failed: ffmpeg not found (e.g. `brew install ffmpeg`)")
+        return None
+
+    h0, w0 = int(frames[0].shape[0]), int(frames[0].shape[1])
+    if target_width and int(target_width) != w0:
+        out_w = int(target_width)
+        out_h = max(1, round(h0 * out_w / w0))
+    else:
+        out_w, out_h = w0, h0
+    out_w -= out_w % 2          # yuv420p needs even dimensions
+    out_h -= out_h % 2
+    if out_w < 2 or out_h < 2:
+        return None
+    resize = (out_w, out_h) != (w0, h0)
+    if resize:
+        try:
+            from PIL import Image
+        except ImportError:
+            print("save_video failed: Pillow needed to resize (pip install Pillow)")
+            return None
+
+    vf = []
+    if border and int(border) > 0:
+        b = int(border) - int(border) % 2   # keep padded dims even for yuv420p
+        if b > 0:
+            bc = border_color
+            vf = ["-vf", "pad=iw+%d:ih+%d:%d:%d:color=0x%02X%02X%02X"
+                  % (2 * b, 2 * b, b, b, int(bc[0]), int(bc[1]), int(bc[2]))]
+
+    cmd = ([ffmpeg, "-y", "-loglevel", "error",
+            "-f", "rawvideo", "-pix_fmt", "rgb24",
+            "-s", "%dx%d" % (out_w, out_h), "-r", str(int(fps)), "-i", "-",
+            "-an"] + vf
+           + ["-c:v", "libx264", "-pix_fmt", "yuv420p",
+              "-crf", str(int(crf)), "-preset", str(preset),
+              "-movflags", "+faststart", path])
+    try:
+        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE)
+    except OSError as e:
+        print("save_video failed: could not launch ffmpeg (%r)" % (e,))
+        return None
+    try:
+        for arr in frames:
+            if resize:
+                arr_bytes = Image.fromarray(arr, "RGB").resize(
+                    (out_w, out_h), Image.LANCZOS).tobytes()
+            else:
+                arr_bytes = arr.tobytes()
+            proc.stdin.write(arr_bytes)
+        proc.stdin.close()
+        rc = proc.wait()
+    except (OSError, ValueError) as e:
+        print("save_video failed: %r" % (e,))
+        return None
+    if rc != 0:
+        print("save_video failed: ffmpeg exited %s" % rc)
+        return None
+    return path

scrollkit/display/_sim_backend.py

@@ -0,0 +1,99 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Shared desktop-simulator backend setup for the two display classes.
+
+``UnifiedDisplay`` (the production entry point, which auto-selects hardware vs
+simulator) and ``SimulatorDisplay`` (the desktop recording/verification display)
+both stand up an identical simulator device: build a ``MatrixPortalS3``, wire the
+optional hardware-timing model onto it *before* ``initialize()`` (the LEDMatrix
+reads ``device.performance_manager`` there), initialize it, and prepare the
+render surface. That setup lived duplicated in both classes; it lives here now so
+one edit updates both.
+
+Desktop-only by design: every simulator import is inside a function, so importing
+this module costs nothing and it is never reached on the CircuitPython path (the
+hardware branch of ``UnifiedDisplay`` doesn't call it, and ``SimulatorDisplay``
+itself raises ``ImportError`` on CircuitPython).
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def create_sim_device(width, height, board_id, *, pitch=None,
+                      hardware_timing=False, throttle=False, strict=False):
+    """Build and initialize a simulator ``MatrixPortalS3``.
+
+    Wires an optional ``PerformanceManager`` (hardware-timing model) onto the
+    device before ``initialize()`` when timing is requested — via the
+    ``hardware_timing``/``throttle``/``strict`` flags or the
+    ``SCROLLKIT_HW_SIM`` / ``SCROLLKIT_HW_THROTTLE`` / ``SCROLLKIT_HW_STRICT``
+    env vars. ``strict`` (and throttle) imply timing: you can't gate/crawl a
+    model you aren't running.
+
+    Args:
+        width, height: Panel geometry in pixels.
+        board_id: Which board's timing profile to model.
+        pitch: LED pitch (mm) -> on-screen size; ``None`` uses the device default
+            (``UnifiedDisplay`` doesn't set it; ``SimulatorDisplay`` does, for
+            higher-resolution recordings).
+        hardware_timing, throttle, strict: Constructor-level opt-ins for the
+            timing model (env vars are honored regardless).
+
+    Returns:
+        ``(device, matrix, display, perf)`` where ``perf`` is the
+        ``PerformanceManager`` (or ``None`` when hardware timing is off).
+    """
+    from scrollkit.simulator.devices.matrixportal_s3 import MatrixPortalS3
+
+    env_sim = os.environ.get("SCROLLKIT_HW_SIM") == "1"
+    env_throttle = os.environ.get("SCROLLKIT_HW_THROTTLE") == "1"
+    env_strict = os.environ.get("SCROLLKIT_HW_STRICT") == "1"
+    want_throttle = throttle or env_throttle
+    want_strict = strict or env_strict
+    # strict implies hardware timing — you can't gate a model you aren't running.
+    want_timing = hardware_timing or env_sim or want_throttle or want_strict
+
+    if pitch is None:
+        device = MatrixPortalS3(width=width, height=height)
+    else:
+        device = MatrixPortalS3(width=width, height=height, pitch=pitch)
+
+    perf = None
+    if want_timing:
+        try:
+            from scrollkit.simulator.core.hardware_profile import profile_for
+            from scrollkit.simulator.core.performance_manager import (
+                PerformanceManager, set_active)
+        except ImportError:
+            perf = None
+        else:
+            perf = PerformanceManager(profile_for(board_id), enabled=True,
+                                      throttle=want_throttle, strict=want_strict)
+            # Wired BEFORE initialize() (LEDMatrix reads it there); set_active
+            # feeds the Label glyph-rebuild hook.
+            device.performance_manager = perf
+            set_active(perf)
+
+    device.initialize()
+
+    matrix = device.matrix
+    display = device.display
+    if hasattr(matrix, "initialize_surface"):
+        matrix.initialize_surface()
+
+    return device, matrix, display, perf
+
+
+def disabled_feasibility_report(hint):
+    """The shared "hardware timing is off" stub report.
+
+    ``hint`` is the caller-specific way to turn timing on (the env var alone for
+    ``UnifiedDisplay``; the constructor flag for ``SimulatorDisplay``).
+    """
+    from scrollkit.simulator.core.feasibility import FeasibilityReport
+    return FeasibilityReport(
+        "hardware timing disabled", "DISABLED",
+        hint,
+        False, None, 0.0, 0.0, {}, 0, 0,
+        ["Hardware timing is off — no feasibility data. " + hint])

scrollkit/display/bitmap_text.py

@@ -0,0 +1,408 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Palette-animated bitmap text (Class 3 — the proving spike for the foundation).
+
+A ScrollKit-native fixed-cell 5x7 font is rendered ONCE into an indexed Bitmap
+whose lit pixels carry palette *indices* (a colour-ramp position). The text scrolls
+by moving a TileGrid; the animation comes from rewriting a few palette entries each
+frame — near-zero per-frame pixel work and NO glyph rebuild. Runs unchanged on
+device and simulator via ``display.gfx``.
+
+This ships ``BitmapText`` plus the full palette-animation set (rainbow chase, neon
+tube crawl, chrome sheen, hazard stripes) and the complete printable-ASCII 5x7 font.
+"""
+
+from .content import DisplayContent, LOOP_FPS
+from .colors import scale as _scale, spectrum, gradient
+
+# Full printable-ASCII 5x7 font (table-driven; no BDF). Each glyph is 7 rows of a
+# 5-char mask ('#' = lit). Missing chars render blank. Lookup folds to upper-case.
+FONT_5x7 = {
+    " ": ["     ", "     ", "     ", "     ", "     ", "     ", "     "],
+    "A": [" ### ", "#   #", "#   #", "#####", "#   #", "#   #", "#   #"],
+    "B": ["#### ", "#   #", "#   #", "#### ", "#   #", "#   #", "#### "],
+    "C": [" ### ", "#   #", "#    ", "#    ", "#    ", "#   #", " ### "],
+    "D": ["#### ", "#   #", "#   #", "#   #", "#   #", "#   #", "#### "],
+    "E": ["#####", "#    ", "#    ", "#### ", "#    ", "#    ", "#####"],
+    "F": ["#####", "#    ", "#    ", "#### ", "#    ", "#    ", "#    "],
+    "G": [" ### ", "#   #", "#    ", "# ###", "#   #", "#   #", " ### "],
+    "H": ["#   #", "#   #", "#   #", "#####", "#   #", "#   #", "#   #"],
+    "I": ["#####", "  #  ", "  #  ", "  #  ", "  #  ", "  #  ", "#####"],
+    "J": ["  ###", "   # ", "   # ", "   # ", "#  # ", "#  # ", " ##  "],
+    "K": ["#   #", "#  # ", "# #  ", "##   ", "# #  ", "#  # ", "#   #"],
+    "L": ["#    ", "#    ", "#    ", "#    ", "#    ", "#    ", "#####"],
+    "M": ["#   #", "## ##", "# # #", "#   #", "#   #", "#   #", "#   #"],
+    "N": ["#   #", "##  #", "# # #", "#  ##", "#   #", "#   #", "#   #"],
+    "O": [" ### ", "#   #", "#   #", "#   #", "#   #", "#   #", " ### "],
+    "P": ["#### ", "#   #", "#   #", "#### ", "#    ", "#    ", "#    "],
+    "Q": [" ### ", "#   #", "#   #", "#   #", "# # #", "#  # ", " ## #"],
+    "R": ["#### ", "#   #", "#   #", "#### ", "# #  ", "#  # ", "#   #"],
+    "S": [" ####", "#    ", "#    ", " ### ", "    #", "    #", "#### "],
+    "T": ["#####", "  #  ", "  #  ", "  #  ", "  #  ", "  #  ", "  #  "],
+    "U": ["#   #", "#   #", "#   #", "#   #", "#   #", "#   #", " ### "],
+    "V": ["#   #", "#   #", "#   #", "#   #", "#   #", " # # ", "  #  "],
+    "W": ["#   #", "#   #", "#   #", "# # #", "# # #", "## ##", "#   #"],
+    "X": ["#   #", "#   #", " # # ", "  #  ", " # # ", "#   #", "#   #"],
+    "Y": ["#   #", "#   #", " # # ", "  #  ", "  #  ", "  #  ", "  #  "],
+    "Z": ["#####", "    #", "   # ", "  #  ", " #   ", "#    ", "#####"],
+    "0": [" ### ", "#   #", "#  ##", "# # #", "##  #", "#   #", " ### "],
+    "1": ["  #  ", " ##  ", "  #  ", "  #  ", "  #  ", "  #  ", "#####"],
+    "2": [" ### ", "#   #", "    #", "   # ", "  #  ", " #   ", "#####"],
+    "3": ["#####", "   # ", "  #  ", "   # ", "    #", "#   #", " ### "],
+    "4": ["   # ", "  ## ", " # # ", "#  # ", "#####", "   # ", "   # "],
+    "5": ["#####", "#    ", "#### ", "    #", "    #", "#   #", " ### "],
+    "6": [" ### ", "#    ", "#    ", "#### ", "#   #", "#   #", " ### "],
+    "7": ["#####", "    #", "   # ", "  #  ", " #   ", " #   ", " #   "],
+    "8": [" ### ", "#   #", "#   #", " ### ", "#   #", "#   #", " ### "],
+    "9": [" ### ", "#   #", "#   #", " ####", "    #", "    #", " ### "],
+    "!": ["  #  ", "  #  ", "  #  ", "  #  ", "  #  ", "     ", "  #  "],
+    "?": [" ### ", "#   #", "    #", "   # ", "  #  ", "     ", "  #  "],
+    ".": ["     ", "     ", "     ", "     ", "     ", " ##  ", " ##  "],
+    ",": ["     ", "     ", "     ", "     ", "     ", "  #  ", " #   "],
+    ":": ["     ", "  #  ", "  #  ", "     ", "  #  ", "  #  ", "     "],
+    ";": ["     ", "  #  ", "  #  ", "     ", "  #  ", "  #  ", " #   "],
+    "'": ["  #  ", "  #  ", "     ", "     ", "     ", "     ", "     "],
+    '"': [" # # ", " # # ", "     ", "     ", "     ", "     ", "     "],
+    "-": ["     ", "     ", "     ", "#####", "     ", "     ", "     "],
+    "+": ["     ", "  #  ", "  #  ", "#####", "  #  ", "  #  ", "     "],
+    "=": ["     ", "     ", "#####", "     ", "#####", "     ", "     "],
+    "_": ["     ", "     ", "     ", "     ", "     ", "     ", "#####"],
+    "/": ["    #", "    #", "   # ", "  #  ", " #   ", "#    ", "#    "],
+    "\\": ["#    ", "#    ", " #   ", "  #  ", "   # ", "    #", "    #"],
+    "*": ["     ", " # # ", "  #  ", "#####", "  #  ", " # # ", "     "],
+    "#": [" # # ", " # # ", "#####", " # # ", "#####", " # # ", " # # "],
+    "%": ["##  #", "##  #", "   # ", "  #  ", " #   ", "#  ##", "#  ##"],
+    "&": [" ##  ", "#  # ", "#  # ", " ##  ", "# # #", "#  # ", " ## #"],
+    "@": [" ### ", "#   #", "# ###", "# # #", "# ###", "#    ", " ### "],
+    "$": ["  #  ", " ####", "# #  ", " ### ", "  # #", "#### ", "  #  "],
+    "(": ["  #  ", " #   ", "#    ", "#    ", "#    ", " #   ", "  #  "],
+    ")": ["  #  ", "   # ", "    #", "    #", "    #", "   # ", "  #  "],
+    "<": ["   # ", "  #  ", " #   ", "#    ", " #   ", "  #  ", "   # "],
+    ">": [" #   ", "  #  ", "   # ", "    #", "   # ", "  #  ", " #   "],
+}
+
+# Backwards-compatible alias for the table.
+_GLYPHS = FONT_5x7
+
+GLYPH_W = 5
+GLYPH_H = 7
+CELL_W = GLYPH_W + 1     # one column of spacing between glyphs
+
+# Colour resolution of the palette effects. RAMP is how many palette slots BitmapText
+# animates, so it sets how smoothly a gradient spreads across the letters — wider ==
+# smoother (still pure palette rewrites: no per-frame allocation and zero PIXEL writes,
+# so feasibility is unchanged). 16 is a smooth spread that stays well inside the panel's
+# 4-bit-per-channel (4096-colour) reality. (Index 0 is the transparent background.)
+RAMP = 16
+# A smooth full-spectrum hue wheel of RAMP stops, built ONCE at import (zero per-frame
+# cost). Replaces the old six fixed primaries, so rainbow text sweeps the whole spectrum
+# instead of stepping through six blocks.
+_RAINBOW = spectrum(RAMP)
+
+# Public ramp + a tiny chase helper, so content can use the SAME flowing rainbow as
+# the palette effects without the legacy EffectsEngine.get_rainbow_color().
+RAINBOW = _RAINBOW
+
+
+__all__ = ['BitmapText', 'RainbowChase', 'NeonTubeCrawl', 'ChromeSheen', 'HazardStripes', 'MonoChase', 'palette_effects_for', 'rainbow_color', 'FONT_5x7']
+
+def rainbow_color(step):
+    """A flowing rainbow colour for integer ``step`` (wraps around the ramp)."""
+    return _RAINBOW[step % RAMP]
+
+
+def _glyph(ch):
+    return FONT_5x7.get(ch.upper())
+
+
+# Brightness curves for the single-hue palette effects, GENERATED at RAMP length so
+# they scale with the palette resolution (no hard-coded 6-tuples to fall out of sync
+# when RAMP changes). Built once when the effect is constructed.
+def _ramp_profile(n):
+    """A dark -> full brightness curve of length ``n`` (sheen: dim base to highlight)."""
+    if n <= 1:
+        return (1.0,)
+    lo = 0.12
+    return tuple(lo + (1.0 - lo) * i / (n - 1) for i in range(n))
+
+
+def _peak_profile(n):
+    """A dim -> bright -> dim brightness curve of length ``n`` (mono-chase highlight)."""
+    if n <= 1:
+        return (1.0,)
+    lo = 0.12
+    return tuple(lo + (1.0 - lo) * (1.0 - abs(2.0 * i / (n - 1) - 1.0))
+                 for i in range(n))
+
+
+class RainbowChase:
+    """Palette effect: rotate the colour ramp so a rainbow travels through the
+    letters. Pure palette rewrites — no glyph rebuild. ``period`` advances the
+    phase every N frames (>1 = a calmer, slower chase)."""
+
+    def __init__(self, step=1, period=1):
+        self.step = step
+        self.period = period if period > 1 else 1
+        self._phase = 0
+        self._tick = 0
+
+    def apply(self, palette):
+        for i in range(RAMP):
+            palette[1 + i] = _RAINBOW[(i + self._phase) % RAMP]
+        self._tick += 1
+        if self._tick >= self.period:
+            self._tick = 0
+            self._phase = (self._phase + self.step) % RAMP
+
+
+class NeonTubeCrawl:
+    """A bright pulse crawls along an otherwise-dim neon tube of one colour: one ramp
+    slot glows at full ``color`` while the rest hold a dimmed version of it. Pass
+    ``glow``/``base`` to set the two shades directly instead. Pure palette rewrites —
+    no glyph rebuild. ``period`` advances the pulse every N frames."""
+
+    def __init__(self, color=0x66FFCC, glow=None, base=None, period=2):
+        self.glow = glow if glow is not None else color
+        self.base = base if base is not None else _scale(color, 0.18)
+        self.period = period if period > 1 else 1
+        self._phase = 0
+        self._tick = 0
+
+    def apply(self, palette):
+        for i in range(RAMP):
+            palette[1 + i] = self.glow if i == self._phase else self.base
+        self._tick += 1
+        if self._tick >= self.period:
+            self._tick = 0
+            self._phase = (self._phase + 1) % RAMP
+
+
+class ChromeSheen:
+    """A metallic sheen: a dark→bright ramp of ``color`` (default silver/white) with a
+    highlight band that sweeps across the letters as the ramp rotates. Pass
+    ``highlight`` to make the sheen a smooth TWO-colour gradient (dim ``color`` → full
+    ``highlight``, e.g. steel-blue → white) instead of a single-hue brightness ramp.
+    Pure palette rewrites — no glyph rebuild."""
+
+    # brightness profile, dark -> full; the highlight sits at the bright end. Generated
+    # at RAMP length so the gradient stays smooth as the palette resolution widens.
+    _PROFILE = _ramp_profile(RAMP)
+
+    def __init__(self, color=0xFFFFFF, highlight=None, period=1):
+        self.color = color
+        self.highlight = highlight
+        self.period = period if period > 1 else 1
+        if highlight is None:
+            self._ramp = tuple(_scale(color, f) for f in self._PROFILE)
+        else:
+            # dim base of `color` -> full `highlight`: a smooth two-colour sheen ramp.
+            self._ramp = gradient(_scale(color, self._PROFILE[0]), highlight, RAMP)
+        self._phase = 0
+        self._tick = 0
+
+    def apply(self, palette):
+        for i in range(RAMP):
+            palette[1 + i] = self._ramp[(i + self._phase) % RAMP]
+        self._tick += 1
+        if self._tick >= self.period:
+            self._tick = 0
+            self._phase = (self._phase + 1) % RAMP
+
+
+class HazardStripes:
+    """Marching hazard stripes: an accent ``color`` alternating with a ``dark`` ground,
+    shifting one slot each step. Pass ``a``/``b`` to set the two colours directly.
+    Pure palette rewrites — no glyph rebuild."""
+
+    def __init__(self, color=0xFFCC00, dark=0x101010, a=None, b=None, period=2):
+        self.a = a if a is not None else color
+        self.b = b if b is not None else dark
+        self.period = period if period > 1 else 1
+        self._phase = 0
+        self._tick = 0
+
+    def apply(self, palette):
+        for i in range(RAMP):
+            palette[1 + i] = self.a if ((i + self._phase) % 2 == 0) else self.b
+        self._tick += 1
+        if self._tick >= self.period:
+            self._tick = 0
+            self._phase = (self._phase + 1) % 2
+
+
+class MonoChase:
+    """A single bright band of one ``color`` chases through the letters — RainbowChase,
+    but monochrome (one hue at varying brightness). Pure palette rewrites — no glyph
+    rebuild. ``period`` advances the chase every N frames."""
+
+    # a brightness peak (dim -> bright -> dim) that sweeps around the ramp. Generated at
+    # RAMP length so the sweep stays smooth as the palette resolution widens.
+    _PROFILE = _peak_profile(RAMP)
+
+    def __init__(self, color=0xFFFFFF, period=1):
+        self.color = color
+        self.period = period if period > 1 else 1
+        self._ramp = tuple(_scale(color, f) for f in self._PROFILE)
+        self._phase = 0
+        self._tick = 0
+
+    def apply(self, palette):
+        for i in range(RAMP):
+            palette[1 + i] = self._ramp[(i + self._phase) % RAMP]
+        self._tick += 1
+        if self._tick >= self.period:
+            self._tick = 0
+            self._phase = (self._phase + 1) % RAMP
+
+
+# Content pairing: palette effects animate the colours of bitmap text, so they read
+# well whether the text is held static or scrolling (surfaced in capabilities()/docs).
+RainbowChase.PAIRS_WITH = ("static", "scrolling")
+NeonTubeCrawl.PAIRS_WITH = ("static", "scrolling")
+ChromeSheen.PAIRS_WITH = ("static", "scrolling")
+HazardStripes.PAIRS_WITH = ("static", "scrolling")
+MonoChase.PAIRS_WITH = ("static", "scrolling")
+
+_PALETTE_EFFECTS = (RainbowChase, NeonTubeCrawl, ChromeSheen, HazardStripes, MonoChase)
+
+
+def palette_effects_for(presentation):
+    """The palette-effect CLASSES suited to `presentation` ('static' | 'scrolling').
+
+    Each returned class is used as ``BitmapText(text, palette_effect=cls())``. These
+    animate colour over bitmap text and read well static or scrolling. Reads the live
+    PAIRS_WITH tags, so it stays current as palette effects are added or retagged.
+
+        cls = random.choice(palette_effects_for("scrolling"))
+        app.content_queue.add(BitmapText("OPEN", palette_effect=cls()))
+    """
+    return tuple(cls for cls in _PALETTE_EFFECTS
+                 if presentation in getattr(cls, "PAIRS_WITH", ()))
+
+
+class BitmapText(DisplayContent):
+    """A message rendered once into an indexed bitmap, scrolled via a TileGrid,
+    with an optional per-frame palette effect."""
+
+    def __init__(self, text, y=0, palette_effect=None, scroll_speed=30,
+                 max_width_px=192, priority=2, complete_after_passes=None):
+        """Args (beyond the obvious):
+
+            complete_after_passes: if set (e.g. 1), ``is_complete`` becomes True
+                after the text has fully scrolled across that many times, so the
+                banner can advance a ContentQueue instead of looping forever.
+                Default None keeps the persistent-banner behaviour (never
+                completes on its own). Completion is keyed on SCROLL POSITION, not
+                wall-clock, so a heavy concurrent effect that drops the frame rate
+                can't end a pass early (cutting the text off mid-scroll).
+        """
+        super().__init__(duration=None, priority=priority)
+        self.text = text
+        self.y = y
+        self.palette_effect = palette_effect if palette_effect is not None else RainbowChase()
+        self.scroll_speed = scroll_speed
+        self.max_width_px = max_width_px
+        self.complete_after_passes = complete_after_passes
+        self._passes = 0         # full scroll passes completed (frame-based)
+        self._built = False
+        self._display = None
+        self._bitmap = None
+        self._palette = None
+        self._tile = None
+        self._pos_q = 0          # 1/16-px scroll accumulator
+        self._width = 0
+
+    def _delta_q(self):
+        return int(round(self.scroll_speed * 16 / LOOP_FPS))
+
+    def _build(self, display):
+        gfx = display.gfx
+        width = min(self.max_width_px, max(1, len(self.text) * CELL_W))
+        self._width = width
+        bitmap = gfx.Bitmap(width, GLYPH_H, RAMP + 1)
+        palette = gfx.Palette(RAMP + 1)
+        palette.make_transparent(0)              # background transparent
+        for i in range(RAMP):
+            palette[1 + i] = _RAINBOW[i]
+        # Render every glyph ONCE; each lit pixel's palette index is its column
+        # position in the ramp, so rotating the palette makes the colour chase.
+        cx = 0
+        for ch in self.text:
+            rows = _glyph(ch)
+            if rows is not None:
+                for ry in range(GLYPH_H):
+                    row = rows[ry]
+                    for rx in range(GLYPH_W):
+                        ax = cx + rx
+                        if ax < width and row[rx] != " ":
+                            bitmap[ax, ry] = (ax % RAMP) + 1
+            cx += CELL_W
+            if cx >= width:
+                break
+        tile = gfx.TileGrid(bitmap, pixel_shader=palette)
+        tile.x = display.width                   # start off the right edge
+        tile.y = self.y
+        display.add_layer(tile)
+        self._bitmap = bitmap
+        self._palette = palette
+        self._tile = tile
+        self._pos_q = display.width << 4
+        self._built = True
+
+    async def start(self):
+        """Reset so the layer is rebuilt and pass-completion replays when this
+        content cycles back through a ContentQueue.
+
+        The library's previous BitmapText never reset ``_built``, so a banner that
+        was ``stop()``-ed (which detaches its TileGrid) would not re-add the layer
+        when shown again — it went invisible on the second cycle. Rebuilding on
+        each start() makes it queue-safe.
+        """
+        await super().start()
+        self._built = False
+        self._passes = 0
+
+    async def render(self, display):
+        self._display = display                  # remembered so stop() can detach
+        was_built = self._built
+        if not self._built:
+            self._build(display)                 # one-time (frame 0)
+        # Animate by rewriting palette entries — NO glyph rebuild, ~zero pixel work.
+        if self.palette_effect is not None:
+            self.palette_effect.apply(self._palette)
+        # Scroll by moving the TileGrid.
+        self._pos_q -= self._delta_q()
+        self._tile.x = self._pos_q >> 4
+        if (self._pos_q >> 4) < -self._width:
+            self._pos_q = display.width << 4     # loop the scroll
+            # The wrap (position jumping back to the right edge) marks one full
+            # pass. Counted from scroll POSITION (frame-based), not wall-clock, so
+            # a low frame rate never ends a pass early. Skip the build frame.
+            if was_built:
+                self._passes += 1
+
+    @property
+    def is_complete(self):
+        if self._is_complete:
+            return True
+        if self.complete_after_passes is not None:
+            return self._passes >= self.complete_after_passes
+        return False
+
+    async def stop(self):
+        """Remove the bitmap-text layer when the content is taken off the queue."""
+        await super().stop()
+        if getattr(self, "_display", None) is not None:
+            self.detach(self._display)
+            self._display = None
+
+    def detach(self, display):
+        if self._tile is not None:
+            display.remove_layer(self._tile)
+
+
+# --- advertised feasibility metadata (US7 / FR-026) -------------------------
+# The glyph bitmap is rendered ONCE; animation is pure palette rewrites (<= RAMP
+# entries) and scrolling moves the TileGrid.x — so per-frame PIXEL writes are zero
+# and there is no per-frame allocation. Strict-feasible at 20 fps.
+BitmapText.FEASIBILITY = {"hardware_safe": True, "allocates_per_frame": False,
+                          "max_pixel_writes_per_frame": 0, "modeled_frame_ms": 5.0}