scrollkit 0.8.3__py3-none-any.whl

scrollkit/dev/validation.py

@@ -0,0 +1,245 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Pre-flight validation for a ScrollKit app — structured issues with fixes.
+
+``validate(app)`` runs the app headless once and combines *static* checks on its
+content (colors, text width, on-panel positions) with *dynamic* findings from the
+run (did it render anything, plus the hardware feasibility warnings — stutter,
+RAM). It returns a ``ValidationReport`` of ``Issue``s, each carrying a severity, a
+stable code, a human message, and a concrete fix — so an AI agent gets actionable
+feedback instead of a stack trace, and can decide whether the app is ready.
+
+Design note: this reports the *real* behavior of the imperative content classes.
+A color name string, for example, is flagged as an error (it would crash
+``draw_text``, which expects an int) rather than being quietly "fixed". Honest
+root-cause feedback over papering over the problem.
+
+Desktop-only (imported via ``scrollkit.dev``).
+"""
+
+PANEL_WIDTH = 64
+PANEL_HEIGHT = 32
+CHAR_WIDTH_PX = 6  # ScrollingText's own width estimate; good enough for a heuristic
+
+
+class Issue:
+    """One validation finding: severity + stable code + message + concrete fix."""
+
+    __slots__ = ("severity", "code", "message", "fix")
+
+    def __init__(self, severity, code, message, fix):
+        self.severity = severity   # "error" | "warning" | "info"
+        self.code = code
+        self.message = message
+        self.fix = fix
+
+    def as_dict(self):
+        return {"severity": self.severity, "code": self.code,
+                "message": self.message, "fix": self.fix}
+
+    def __repr__(self):
+        return "Issue(%s, %s)" % (self.severity, self.code)
+
+
+class ValidationReport:
+    """Aggregate of validation issues, plus the underlying RunResult (if any)."""
+
+    def __init__(self, issues, run=None):
+        self.issues = issues
+        self.run = run  # the RunResult from the headless render, or None
+
+    @property
+    def errors(self):
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self):
+        return [i for i in self.issues if i.severity == "warning"]
+
+    @property
+    def infos(self):
+        return [i for i in self.issues if i.severity == "info"]
+
+    @property
+    def ok(self):
+        """True when there are no errors (warnings are allowed)."""
+        return not self.errors
+
+    def as_dict(self):
+        return {
+            "ok": self.ok,
+            "counts": {"error": len(self.errors), "warning": len(self.warnings),
+                       "info": len(self.infos)},
+            "issues": [i.as_dict() for i in self.issues],
+        }
+
+    def as_text(self):
+        lines = ["=== validate: %s ===" % ("OK" if self.ok else "ISSUES FOUND")]
+        if not self.issues:
+            lines.append("  No issues.")
+        for i in self.issues:
+            lines.append("  [%s] %s: %s" % (i.severity.upper(), i.code, i.message))
+            if i.fix:
+                lines.append("        fix: %s" % i.fix)
+        return "\n".join(lines)
+
+    def __repr__(self):
+        return "ValidationReport(ok=%s, errors=%d, warnings=%d)" % (
+            self.ok, len(self.errors), len(self.warnings))
+
+
+# --- checks -------------------------------------------------------------------
+
+def _check_color(color, label):
+    if isinstance(color, bool):  # bool is an int subclass — almost certainly a bug
+        return [Issue("error", "color_type",
+                      "%s: color is a bool (%r)." % (label, color),
+                      "Use an int 0xRRGGBB or an (r, g, b) tuple.")]
+    if isinstance(color, int):
+        if color < 0 or color > 0xFFFFFF:
+            return [Issue("warning", "color_out_of_range",
+                          "%s: color 0x%X is outside 0x000000..0xFFFFFF."
+                          % (label, color),
+                          "Use a 24-bit value, e.g. 0xFF8800.")]
+        return []
+    if isinstance(color, (tuple, list)):
+        ok = (len(color) == 3 and all(
+            isinstance(c, int) and not isinstance(c, bool) and 0 <= c <= 255
+            for c in color))
+        if not ok:
+            return [Issue("warning", "color_out_of_range",
+                          "%s: RGB %r must be three ints in 0..255." % (label, color),
+                          "e.g. (255, 136, 0).")]
+        return []
+    if isinstance(color, str):
+        return [Issue("error", "color_string",
+                      "%s: color is the string %r — pass an int 0xRRGGBB, a tuple "
+                      "(r, g, b), or a settings key defined via "
+                      "self.settings.define(key, default, type='color')." % (label, color),
+                      "Use 0xRRGGBB or (r, g, b). For a named setting: "
+                      "self.settings.define('highlight', 0xFF8800, type='color').")]
+    return [Issue("error", "color_type",
+                  "%s: color has unsupported type %s." % (label, type(color).__name__),
+                  "Use an int 0xRRGGBB or an (r, g, b) tuple.")]
+
+
+def _static_checks(items, panel_width, panel_height, app=None):
+    issues = []
+    if not items:
+        issues.append(Issue(
+            "info", "empty_queue",
+            "content_queue is empty.",
+            "If you render via a prepare_display_content() override this is fine; "
+            "otherwise add content in setup(), e.g. "
+            "self.content_queue.add(ScrollingText('HELLO'))."))
+        return issues
+
+    # Build the set of defined settings keys so we can validate color references.
+    defined_keys = set()
+    if app is not None:
+        try:
+            schema = getattr(getattr(app, "settings", None), "_schema", [])
+            defined_keys = {e["key"] for e in schema}
+        except Exception:
+            pass
+
+    for idx, item in enumerate(items):
+        label = "%s#%d" % (type(item).__name__, idx)
+
+        color_setting = getattr(item, "_color_setting", None)
+        if color_setting is not None:
+            # color was None or a string key — validate the key is defined
+            if color_setting not in defined_keys:
+                issues.extend(_check_color(color_setting, label))
+        else:
+            color = getattr(item, "color", None)
+            if color is not None:
+                issues.extend(_check_color(color, label))
+
+        text = getattr(item, "text", None)
+        scrolling = hasattr(item, "speed")  # ScrollingText has speed; StaticText doesn't
+        if isinstance(text, str) and not scrolling:
+            width = len(text) * CHAR_WIDTH_PX
+            if width > panel_width:
+                issues.append(Issue(
+                    "warning", "text_clipped",
+                    "%s: text ~%dpx wide exceeds the %dpx panel and will be clipped."
+                    % (label, width, panel_width),
+                    "Use ScrollingText so it scrolls, or shorten the text."))
+
+        y = getattr(item, "y", None)
+        if isinstance(y, int) and (y < 0 or y >= panel_height):
+            issues.append(Issue(
+                "warning", "offscreen_y",
+                "%s: y=%d is outside the 0..%d panel." % (label, y, panel_height - 1),
+                "y is the top-down baseline (origin top-left, y grows down); "
+                "pick a y within the panel. y=12 vertically centers an 8px font; "
+                "low y like 0 clips glyphs off the top."))
+
+    return issues
+
+
+def _dynamic_checks(result):
+    issues = []
+    for e in result.errors:
+        issues.append(Issue(
+            "error", "runtime_error", e,
+            "Fix the exception; scrollkit.dev.run_headless(app) shows full detail."))
+    if result.is_blank and not result.errors:
+        if result.frames == 0:
+            msg = ("Nothing rendered (0 frames shown) — no content reached the "
+                   "display.")
+        else:
+            msg = "Ran %d frames but nothing was lit." % result.frames
+        issues.append(Issue(
+            "error", "blank_render", msg,
+            "Check content was added to the queue (or drawn), colors aren't "
+            "black, and positions are on-panel."))
+    # Hardware estimates from a crashed or empty run are meaningless, so skip
+    # them then. The feasibility warnings already carry their own fix guidance,
+    # so no separate fix line is needed.
+    if result.hardware and not result.errors and result.frames > 0:
+        for w in result.hardware.get("warnings", []):
+            issues.append(Issue("warning", "hardware", w, None))
+    return issues
+
+
+def validate(app, panel_width=PANEL_WIDTH, panel_height=PANEL_HEIGHT,
+             run=True, frames=60):
+    """Validate ``app`` and return a :class:`ValidationReport`.
+
+    Args:
+        app: a ``ScrollKitApp`` instance (its ``setup()`` populates content).
+        panel_width/panel_height: target panel size (MatrixPortal S3 = 64x32).
+        run: render the app headless to add dynamic checks + hardware warnings
+            (default True). With ``run=False`` only static checks run.
+        frames: frames to render when ``run`` is True.
+
+    The app's ``setup()`` runs as part of this call (via the headless render, or
+    directly when ``run=False``), so pass a fresh, un-run app instance.
+    """
+    issues = []
+    result = None
+
+    if run:
+        from .harness import run_headless
+        result = run_headless(app, frames=frames, hardware=True)
+    else:
+        import asyncio
+        try:
+            asyncio.run(app.setup())
+        except Exception as e:
+            issues.append(Issue(
+                "warning", "setup_failed",
+                "Could not run setup() for static checks: %r" % (e,),
+                "Ensure setup() runs without a live display, or use run=True."))
+
+    try:
+        items = list(app.content_queue)
+    except Exception:
+        items = []
+    issues.extend(_static_checks(items, panel_width, panel_height, app=app))
+
+    if result is not None:
+        issues.extend(_dynamic_checks(result))
+
+    return ValidationReport(issues, result)

scrollkit/display/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""ScrollKit Display module.
+
+Kept lean on purpose: importing this package pulls in only the core content
+model (``DisplayContent``/``ContentQueue``/text classes) and ``UnifiedDisplay``,
+so a basic display app stays small on the RAM-constrained device. Heavier,
+optional pieces (effects, the dev/simulator toolkits) are imported directly
+from their own modules when needed.
+"""
+
+from .content import ContentQueue, DisplayContent, ScrollingText, StaticText
+from .unified import UnifiedDisplay
+
+__all__ = ['ContentQueue', 'DisplayContent', 'ScrollingText', 'StaticText', 'UnifiedDisplay']

scrollkit/display/_graphics.py

@@ -0,0 +1,299 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Shared display-graphics primitives (mixed into Simulator + Unified displays).
+
+One code path, both platforms. Provides:
+- ``GraphicsContext`` (``display.gfx``): the platform-resolved Bitmap / Palette /
+  TileGrid / Group / bitmaptools, built once and cached.
+- The content/layer group split (D11): ``_content_group`` (Labels + fill, emptied
+  per frame) sits BELOW ``_layer_group`` (overlay-mask / bitmap-text / paint
+  canvas, persistent across frames), so an effect layer can never be hidden by
+  per-frame label churn.
+- Bounded span/rect painters (``fill_rect`` / ``fill_span`` / ``clear_rect``) that
+  write a persistent full-screen paint canvas through ``bitmaptools.fill_region``
+  (a C bulk op) — never a full-2048 Python loop — and account the cost.
+- The shared per-frame surface: ``clear()`` (label-slot reset + paint wipe),
+  ``set_pixel()`` (a 1x1 ``fill_rect`` into the paint canvas, so pixels survive
+  the displayio re-render on BOTH platforms — this is what the particle system
+  renders through) and ``fill()`` (a cached full-screen background TileGrid at
+  the bottom of the content group). One implementation, hardware == simulator.
+- ``measure_text`` via real font glyph advances (not ``len(text) * 6``).
+
+CircuitPython-safe: no runtime ``typing``, no desktop-only imports here.
+"""
+
+
+class GraphicsContext:
+    """Platform-resolved graphics primitives, held by reference (no allocation).
+
+    Built once per display in ``initialize()`` and returned by ``display.gfx`` so
+    effects build bitmaps/palettes/tilegrids and run C bulk ops through ONE code
+    path. On CircuitPython these are the real built-ins; on desktop they are the
+    ``scrollkit.simulator`` equivalents (including the ``bitmaptools`` shim).
+    """
+
+    __slots__ = ("Bitmap", "Palette", "TileGrid", "Group", "bitmaptools")
+
+    def __init__(self, Bitmap, Palette, TileGrid, Group, bitmaptools):
+        self.Bitmap = Bitmap
+        self.Palette = Palette
+        self.TileGrid = TileGrid
+        self.Group = Group
+        self.bitmaptools = bitmaptools
+
+
+def _glyph_advance(glyph):
+    """Pull the horizontal advance from a glyph (dict or object), or None."""
+    if glyph is None:
+        return None
+    if isinstance(glyph, dict):
+        for key in ("dx", "shift_x", "width"):
+            if key in glyph and glyph[key] is not None:
+                return glyph[key]
+        return None
+    for key in ("dx", "shift_x", "width"):
+        val = getattr(glyph, key, None)
+        if val is not None:
+            return val
+    return None
+
+
+class GraphicsMixin:
+    """Mixed into the display implementations. Expects the subclass to provide
+    ``self._width``, ``self._height``, ``self.font``, ``self._perf`` and to call
+    ``_init_graphics()`` from ``initialize()`` once ``self.main_group`` exists."""
+
+    PAINT_VALUE_COUNT = 256
+
+    # --- setup ----------------------------------------------------------------
+    def _init_graphics(self, displayio_mod, bitmaptools_mod):
+        """Create the content/layer sub-groups inside main_group and cache gfx.
+
+        Call from ``initialize()`` after ``self.main_group`` is created and set as
+        the display's root group.
+        """
+        self._content_group = displayio_mod.Group()
+        self._layer_group = displayio_mod.Group()
+        self.main_group.append(self._content_group)   # below
+        self.main_group.append(self._layer_group)     # above
+        self._gfx = GraphicsContext(
+            displayio_mod.Bitmap, displayio_mod.Palette, displayio_mod.TileGrid,
+            displayio_mod.Group, bitmaptools_mod)
+        # The full-screen paint canvas is created lazily on the first painter call
+        # so apps that never paint pay nothing.
+        self._paint_bitmap = None
+        self._paint_palette = None
+        self._paint_tile = None
+        self._paint_colors = None
+        # Full-screen background for fill(), also lazy (one Bitmap/Palette/
+        # TileGrid ever — the palette color is mutated per call, never realloc'd).
+        self._bg_bitmap = None
+        self._bg_palette = None
+        self._bg_tile = None
+
+    # --- gfx ------------------------------------------------------------------
+    @property
+    def gfx(self):
+        """The cached :class:`GraphicsContext` (identity-stable; no per-access alloc)."""
+        gfx = getattr(self, "_gfx", None)
+        if gfx is None:
+            raise RuntimeError("display.gfx is unavailable until initialize() runs")
+        return gfx
+
+    # --- layers (D11) ---------------------------------------------------------
+    def add_layer(self, tilegrid):
+        """Composite ``tilegrid`` above all content (idempotent)."""
+        lg = getattr(self, "_layer_group", None)
+        if lg is None:
+            return
+        for i in range(len(lg)):
+            if lg[i] is tilegrid:
+                return
+        lg.append(tilegrid)
+
+    def remove_layer(self, tilegrid):
+        """Remove a layer added via :meth:`add_layer` (idempotent)."""
+        lg = getattr(self, "_layer_group", None)
+        if lg is None:
+            return
+        for i in range(len(lg)):
+            if lg[i] is tilegrid:
+                lg.pop(i)
+                return
+
+    # --- bounded painters -----------------------------------------------------
+    def _ensure_paint(self):
+        if self._paint_bitmap is not None:
+            return
+        gfx = self.gfx
+        bm = gfx.Bitmap(self._width, self._height, self.PAINT_VALUE_COUNT)
+        pal = gfx.Palette(self.PAINT_VALUE_COUNT)
+        if hasattr(pal, "make_transparent"):
+            pal.make_transparent(0)          # unpainted shows underlying content
+        tile = gfx.TileGrid(bm, pixel_shader=pal)
+        self._paint_bitmap = bm
+        self._paint_palette = pal
+        self._paint_tile = tile
+        self._paint_colors = {}              # 0xRRGGBB -> palette index (0 reserved)
+        self.add_layer(tile)
+
+    def _paint_index(self, color):
+        idx = self._paint_colors.get(color)
+        if idx is not None:
+            return idx
+        idx = len(self._paint_colors) + 1
+        if idx >= self.PAINT_VALUE_COUNT:
+            # Palette saturated: reuse the last slot for this color WITHOUT caching
+            # it, so the most recently painted color is always the correct one
+            # (caching here would alias several colors to one mutable slot).
+            idx = self.PAINT_VALUE_COUNT - 1
+            self._paint_palette[idx] = color
+            return idx
+        self._paint_palette[idx] = color
+        self._paint_colors[color] = idx
+        return idx
+
+    def _clip_rect(self, x, y, w, h):
+        x0 = x if x > 0 else 0
+        y0 = y if y > 0 else 0
+        x1 = x + w
+        y1 = y + h
+        if x1 > self._width:
+            x1 = self._width
+        if y1 > self._height:
+            y1 = self._height
+        if x1 < x0:
+            x1 = x0
+        if y1 < y0:
+            y1 = y0
+        return x0, y0, x1, y1
+
+    def _account_bulk(self, x0, y0, x1, y1):
+        pm = getattr(self, "_perf", None)
+        if pm is not None:
+            pm.account_bulk_op("fill_region", (x1 - x0) * (y1 - y0))
+
+    async def fill_rect(self, x, y, w, h, color):
+        """Fill the clipped rectangle with ``color`` via a C bulk op."""
+        self._ensure_paint()
+        idx = self._paint_index(color)
+        x0, y0, x1, y1 = self._clip_rect(x, y, w, h)
+        if x1 > x0 and y1 > y0:
+            self.gfx.bitmaptools.fill_region(self._paint_bitmap, x0, y0, x1, y1, idx)
+            self._account_bulk(x0, y0, x1, y1)
+
+    async def fill_span(self, y, x0, x1, color):
+        """Fill the single-row span ``[x0, x1)`` with ``color``."""
+        await self.fill_rect(x0, y, x1 - x0, 1, color)
+
+    async def clear_rect(self, x, y, w, h):
+        """Clear the clipped rectangle back to transparent via a C bulk op."""
+        self._ensure_paint()
+        x0, y0, x1, y1 = self._clip_rect(x, y, w, h)
+        if x1 > x0 and y1 > y0:
+            self.gfx.bitmaptools.fill_region(self._paint_bitmap, x0, y0, x1, y1, 0)
+            self._account_bulk(x0, y0, x1, y1)
+
+    # --- the shared per-frame surface (one code path, both platforms) ---------
+    def _hide_unused_labels(self):
+        """Hide pooled Labels that weren't drawn this frame (frame drew fewer)."""
+        pool = getattr(self, "_label_pool", None) or ()
+        for i in range(getattr(self, "_label_idx", 0), len(pool)):
+            lbl = pool[i]
+            if hasattr(lbl, "hidden"):
+                lbl.hidden = True
+        pool = getattr(self, "_scaled_pool", None) or ()
+        for i in range(getattr(self, "_scaled_idx", 0), len(pool)):
+            lbl = pool[i]
+            if hasattr(lbl, "hidden"):
+                lbl.hidden = True
+
+    async def clear(self):
+        """Clear the display (start a new frame).
+
+        Resets the per-frame Label slot indices so draw_text() reuses pooled
+        Labels instead of allocating (labels not redrawn this frame are hidden
+        in show()), wipes the bounded-painter canvas so fill_rect()/set_pixel()
+        drawings don't ghost across frames (immediate-mode, one C bulk fill),
+        and hides the fill() background. Persistent effect layers live in
+        _layer_group and are deliberately NOT touched. No per-pixel loops, no
+        raw-matrix writes: the displayio refresh in show() re-renders the whole
+        group each frame on both platforms.
+        """
+        self._label_idx = 0
+        self._scaled_idx = 0
+        if getattr(self, "_paint_bitmap", None) is not None:
+            self._paint_bitmap.fill(0)
+        if getattr(self, "_bg_tile", None) is not None:
+            self._bg_tile.hidden = True
+
+    async def set_pixel(self, x, y, color):
+        """Set a single foreground pixel (drawn on top of other content).
+
+        A 1x1 fill_rect into the persistent paint-canvas LAYER, so the pixel is
+        part of the displayio tree and survives show()'s re-render on hardware
+        AND desktop (a raw matrix write would be wiped by refresh, and the
+        hardware matrix has no pixel API at all). This is the primitive the
+        particle system renders through; each write is a bounded C bulk op that
+        the hardware feasibility model accounts for.
+        """
+        if getattr(self, "_gfx", None) is None:
+            return   # not initialized yet — mirror the old silent no-op
+        if 0 <= x < self._width and 0 <= y < self._height:
+            await self.fill_rect(x, y, 1, 1, color)
+
+    def _ensure_bg(self):
+        gfx = self.gfx
+        if self._bg_bitmap is None:
+            self._bg_bitmap = gfx.Bitmap(self._width, self._height, 1)
+            self._bg_palette = gfx.Palette(1)
+            self._bg_tile = gfx.TileGrid(self._bg_bitmap,
+                                         pixel_shader=self._bg_palette)
+            # Bottom of the CONTENT group: behind every label, below the
+            # persistent effect layers. Inserted once; fill()/clear() toggle
+            # .hidden and mutate the palette — never another allocation.
+            self._content_group.insert(0, self._bg_tile)
+
+    async def fill(self, color):
+        """Fill the display background with a solid color (behind labels).
+
+        Immediate-mode like draw_text(): lasts until the next clear(). Backed
+        by one cached full-screen TileGrid whose 1-entry palette is mutated per
+        call — no per-frame allocation, works identically on hardware and
+        desktop (the old paths wrote to the raw matrix, which the hardware
+        wrapper doesn't expose and the desktop refresh wiped).
+        """
+        if getattr(self, "_gfx", None) is None or self._content_group is None:
+            return
+        self._ensure_bg()
+        self._bg_palette[0] = color
+        self._bg_tile.hidden = False
+
+    # --- measurement ----------------------------------------------------------
+    def measure_text(self, text, font=None):
+        """Rendered pixel width from summed font glyph advances (not ``len*6``).
+
+        Empty string is 0; a missing/advance-less glyph contributes the font's
+        space advance (else a documented 6). A font with no ``get_glyph`` API
+        falls back to a coarse ``len*6`` estimate (last resort).
+        """
+        if not text:
+            return 0
+        if font is None:
+            font = getattr(self, "font", None)
+        get = getattr(font, "get_glyph", None) if font is not None else None
+        if get is None:
+            return len(text) * 6
+        try:
+            repl = _glyph_advance(get(" "))
+        except Exception:
+            repl = None
+        if repl is None:
+            repl = 6
+        total = 0
+        for ch in text:
+            try:
+                adv = _glyph_advance(get(ch))
+            except Exception:
+                adv = None
+            total += adv if adv is not None else repl
+        return total