PyPI - scrollkit - Versions diffs - 0.8.3__py3-none-any.whl - Mend

scrollkit 0.8.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (111) hide show

scrollkit/__init__.py +16 -0
scrollkit/app/__init__.py +6 -0
scrollkit/app/base.py +918 -0
scrollkit/app/memory.py +70 -0
scrollkit/config/__init__.py +1 -0
scrollkit/config/settings_manager.py +215 -0
scrollkit/config/transition_names.py +31 -0
scrollkit/dev/__init__.py +41 -0
scrollkit/dev/capabilities.py +374 -0
scrollkit/dev/harness.py +383 -0
scrollkit/dev/metrics.py +91 -0
scrollkit/dev/performance.py +174 -0
scrollkit/dev/validation.py +245 -0
scrollkit/display/__init__.py +14 -0
scrollkit/display/_graphics.py +299 -0
scrollkit/display/_recording.py +165 -0
scrollkit/display/_sim_backend.py +99 -0
scrollkit/display/bitmap_text.py +408 -0
scrollkit/display/boards.py +186 -0
scrollkit/display/colors.py +176 -0
scrollkit/display/content.py +604 -0
scrollkit/display/gradient_text.py +167 -0
scrollkit/display/interface.py +126 -0
scrollkit/display/simulator.py +80 -0
scrollkit/display/text_fill.py +59 -0
scrollkit/display/text_pixels.py +250 -0
scrollkit/display/unified.py +595 -0
scrollkit/effects/__init__.py +28 -0
scrollkit/effects/drip_splash.py +253 -0
scrollkit/effects/easing.py +131 -0
scrollkit/effects/overlay.py +92 -0
scrollkit/effects/particles.py +355 -0
scrollkit/effects/reveal_splash.py +132 -0
scrollkit/effects/scrolling.py +363 -0
scrollkit/effects/swarm_reveal.py +512 -0
scrollkit/effects/text_render.py +25 -0
scrollkit/effects/transitions.py +873 -0
scrollkit/exceptions.py +55 -0
scrollkit/network/__init__.py +1 -0
scrollkit/network/http_client.py +505 -0
scrollkit/network/mdns.py +44 -0
scrollkit/network/wifi_manager.py +382 -0
scrollkit/ota/__init__.py +13 -0
scrollkit/ota/client.py +528 -0
scrollkit/ota/display_progress.py +125 -0
scrollkit/ota/manifest.py +206 -0
scrollkit/ota/publish.py +379 -0
scrollkit/simulator/ATTRIBUTION.md +20 -0
scrollkit/simulator/CIRCUITPYTHON_COMPATIBILITY.md +364 -0
scrollkit/simulator/LICENSE +176 -0
scrollkit/simulator/README.md +87 -0
scrollkit/simulator/__init__.py +11 -0
scrollkit/simulator/adafruit_bitmap_font/__init__.py +5 -0
scrollkit/simulator/adafruit_bitmap_font/bitmap_font.py +273 -0
scrollkit/simulator/adafruit_bitmap_font/glyph_cache.py +70 -0
scrollkit/simulator/adafruit_display_text/__init__.py +5 -0
scrollkit/simulator/adafruit_display_text/label.py +336 -0
scrollkit/simulator/bitmaptools.py +50 -0
scrollkit/simulator/core/__init__.py +8 -0
scrollkit/simulator/core/color_utils.py +62 -0
scrollkit/simulator/core/device_benchmarks.json +254 -0
scrollkit/simulator/core/feasibility.py +160 -0
scrollkit/simulator/core/hardware_profile.py +191 -0
scrollkit/simulator/core/led_matrix.py +307 -0
scrollkit/simulator/core/matrixportal_s3_baseline.json +12 -0
scrollkit/simulator/core/performance_manager.py +253 -0
scrollkit/simulator/core/pixel_buffer.py +188 -0
scrollkit/simulator/devices/__init__.py +7 -0
scrollkit/simulator/devices/base_device.py +79 -0
scrollkit/simulator/devices/matrixportal_s3.py +87 -0
scrollkit/simulator/displayio/__init__.py +12 -0
scrollkit/simulator/displayio/bitmap.py +158 -0
scrollkit/simulator/displayio/display.py +195 -0
scrollkit/simulator/displayio/fourwire.py +54 -0
scrollkit/simulator/displayio/group.py +125 -0
scrollkit/simulator/displayio/ondiskbitmap.py +109 -0
scrollkit/simulator/displayio/palette.py +115 -0
scrollkit/simulator/displayio/tilegrid.py +155 -0
scrollkit/simulator/fonts/3x5.bdf +2474 -0
scrollkit/simulator/fonts/Arial_16.bdf +7366 -0
scrollkit/simulator/fonts/Arial_16.bdf.license +3 -0
scrollkit/simulator/fonts/Arial_Bold_12.bdf +6131 -0
scrollkit/simulator/fonts/Arial_Bold_12.bdf.license +2 -0
scrollkit/simulator/fonts/Arial_Bold_18.bdf +32653 -0
scrollkit/simulator/fonts/Arial_Bold_18.bdf.license +2 -0
scrollkit/simulator/fonts/Junction_regular_24.bdf +8676 -0
scrollkit/simulator/fonts/Junction_regular_24.bdf.license +3 -0
scrollkit/simulator/fonts/LeagueSpartan-Bold-16.bdf +12458 -0
scrollkit/simulator/fonts/LeagueSpartan-Bold-16.bdf.license +1921 -0
scrollkit/simulator/fonts/LeagueSpartan_Bold_16.bdf +12458 -0
scrollkit/simulator/fonts/LeagueSpartan_Bold_16.bdf.license +4 -0
scrollkit/simulator/fonts/LibreBodoniv2002-Bold-27.bdf +16818 -0
scrollkit/simulator/fonts/LibreBodoniv2002-Bold-27.bdf.license +1921 -0
scrollkit/simulator/fonts/tom-thumb.bdf +2353 -0
scrollkit/simulator/fonts/viii-bold.bdf +2673 -0
scrollkit/simulator/fonts/viii.bdf +2659 -0
scrollkit/simulator/terminalio/__init__.py +20 -0
scrollkit/utils/__init__.py +1 -0
scrollkit/utils/color_utils.py +54 -0
scrollkit/utils/diagnostics.py +227 -0
scrollkit/utils/error_handler.py +347 -0
scrollkit/utils/system_utils.py +245 -0
scrollkit/utils/url_utils.py +46 -0
scrollkit/web/__init__.py +6 -0
scrollkit/web/settings_server.py +328 -0
scrollkit/web/wifi_setup.py +331 -0
scrollkit-0.8.3.dist-info/METADATA +248 -0
scrollkit-0.8.3.dist-info/RECORD +111 -0
scrollkit-0.8.3.dist-info/WHEEL +5 -0
scrollkit-0.8.3.dist-info/licenses/LICENSE +31 -0
scrollkit-0.8.3.dist-info/top_level.txt +1 -0

scrollkit/web/wifi_setup.py ADDED Viewed

@@ -0,0 +1,331 @@
+"""WiFi onboarding portal — configure Wi-Fi from a phone, no file editing.
+This is the restored no-``secrets.py`` setup flow (see the original in git at
+``149ed9c:src/wifimgr.py`` — this is a redesign against the current
+architecture, not a revert). The flow:
+1. The device can't join Wi-Fi (no/wrong credentials), so the app calls
+   ``WiFiManager.run_setup_portal(display=...)`` — usually right after a
+   failed ``connect()``.
+2. The device starts its own access point (``WifiManager_XXXX``) and shows
+   join instructions on the LED panel.
+3. The user's phone joins that AP and opens ``http://192.168.4.1``: a page
+   with the scanned nearby networks (signal bars), a manual-SSID field, and
+   a password field.
+4. Submitting saves ``wifi_ssid``/``wifi_password`` through the
+   ``SettingsManager`` (settings.json — never a code file), then the device
+   reboots and ``WiFiManager`` connects with the saved credentials.
+Contract notes (same discipline as ``settings_server``):
+- The portal only ever WRITES SETTINGS. It never touches the content queue.
+  It runs as a blocking boot-phase flow that owns the screen exclusively —
+  before the app's display loop starts — like ``OTAProgressDisplay.
+  install_pending()``.
+- ``adafruit_httpserver``/``socketpool``/``wifi`` are imported lazily inside
+  methods, so importing this module costs nothing and the device only pays
+  for the portal on an unconfigured boot.
+- Desktop CPython works too (stdlib ``socket`` as the pool, localhost) so
+  the flow is testable off-device.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+from __future__ import annotations
+import asyncio
+import time
+from ..utils.url_utils import url_decode as _url_decode
+_SEE_OTHER = (303, "See Other")
+_POLL_INTERVAL = 0.05    # seconds between poll() calls (matches settings_server)
+# Keep serving briefly after a save so the browser finishes receiving the
+# confirmation page before the server (and on hardware, the AP) goes away.
+_LINGER_S = 2.0
+__all__ = ['WiFiSetupPortal']
+def _esc(text):
+    return (str(text).replace("&", "&amp;").replace("<", "&lt;")
+            .replace(">", "&gt;").replace('"', "&quot;"))
+def _bars(rssi):
+    """Rough signal-strength bars from RSSI (dBm)."""
+    try:
+        rssi = int(rssi)
+    except (ValueError, TypeError):
+        return 1
+    if rssi >= -55:
+        return 4
+    if rssi >= -65:
+        return 3
+    if rssi >= -75:
+        return 2
+    return 1
+_PAGE_HEADER = """<!DOCTYPE html>
+<html><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Wi-Fi Setup</title>
+<style>
+body{font-family:sans-serif;max-width:480px;margin:40px auto;padding:0 16px;background:#f5f5f5}
+h1{font-size:1.2em;margin-bottom:8px;color:#222}
+p.hint{font-size:.85em;color:#555;margin-top:0}
+.field{margin-bottom:16px}
+label{display:block;font-size:.85em;color:#555;margin-bottom:4px}
+input[type=text],input[type=password],select{
+  width:100%;padding:8px;border:1px solid #ccc;border-radius:4px;
+  box-sizing:border-box;font-size:1em;background:#fff}
+button{background:#333;color:#fff;border:none;padding:10px 28px;
+  border-radius:4px;font-size:1em;cursor:pointer;margin-top:8px}
+button:hover{background:#555}
+</style></head>
+<body><h1>Wi-Fi Setup</h1>
+<p class="hint">Pick your network (or type its name), enter the password,
+and the display will restart and connect.</p>
+<form method="POST" action="/save">
+"""
+_PAGE_FOOTER = """<button type="submit">Connect</button>
+</form></body></html>
+"""
+_SAVED_PAGE = """<!DOCTYPE html>
+<html><head><meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Wi-Fi Saved</title></head>
+<body style="font-family:sans-serif;max-width:480px;margin:40px auto;padding:0 16px">
+<h1>Saved</h1>
+<p>The display is restarting and will join <b>%s</b>.</p>
+<p>You can now reconnect this phone to your normal Wi-Fi.</p>
+</body></html>
+"""
+class WiFiSetupPortal:
+    """Access-point onboarding portal over a ``WiFiManager``.
+    Usually not constructed directly — call
+    ``WiFiManager.run_setup_portal(display=...)`` instead.
+    """
+    def __init__(self, wifi_manager, display=None, port=80):
+        self._wm = wifi_manager
+        self._display = display
+        self._port = port
+        self._server = None
+        self._server_url = ""
+        self._networks = []
+        self.saved = False
+        self.saved_ssid = None
+        self.error = None
+    # ------------------------------------------------------------------ #
+    # Form rendering
+    # ------------------------------------------------------------------ #
+    def _render_form(self):
+        parts = [_PAGE_HEADER]
+        if self._networks:
+            opts = ['<option value="" disabled selected>Choose a network...'
+                    '</option>']
+            for net in self._networks:
+                ssid = net.get("ssid", "")
+                if not ssid:
+                    continue
+                rssi = net.get("rssi", -99)
+                opts.append('<option value="%s">%s (%s bars, %s dBm)</option>'
+                            % (_esc(ssid), _esc(ssid), _bars(rssi), rssi))
+            parts.append(
+                '<div class="field"><label>Nearby networks</label>'
+                '<select name="ssid">%s</select></div>' % "".join(opts)
+            )
+        parts.append(
+            '<div class="field"><label>Or type a network name</label>'
+            '<input type="text" name="ssid_manual" value=""></div>'
+        )
+        parts.append(
+            '<div class="field"><label>Password</label>'
+            '<input type="password" name="password" value=""></div>'
+        )
+        if self.error:
+            parts.append('<p style="color:#a00">%s</p>' % _esc(self.error))
+        parts.append(_PAGE_FOOTER)
+        return "".join(parts)
+    # ------------------------------------------------------------------ #
+    # POST /save
+    # ------------------------------------------------------------------ #
+    def _apply(self, request):
+        """Read the submitted form; save credentials through the settings
+        manager. Returns True when credentials were saved. Only ever writes
+        settings — never display/queue state."""
+        fd = getattr(request, "form_data", None)
+        def _get(key):
+            if fd is None:
+                return ""
+            try:
+                v = fd.get(key)
+            except Exception:
+                return ""
+            if v is None:
+                return ""
+            if isinstance(v, bytes):
+                v = v.decode("utf-8", "replace")
+            if isinstance(v, str):
+                v = _url_decode(v)
+            return v.strip()
+        # A typed name beats the dropdown (covers hidden networks and an
+        # empty scan); the dropdown is the common path.
+        ssid = _get("ssid_manual") or _get("ssid")
+        password = _get("password")
+        if not ssid:
+            self.error = "Please choose or type a network name."
+            return False
+        self._wm.ssid = ssid
+        self._wm.password = password
+        self._wm.save_credentials()          # -> settings.json, never a code file
+        self.saved = True
+        self.saved_ssid = ssid
+        self.error = None
+        return True
+    # ------------------------------------------------------------------ #
+    # Server plumbing (lazy adafruit_httpserver import)
+    # ------------------------------------------------------------------ #
+    def _build_server(self):
+        import sys
+        import socket as _stdlib_socket
+        from adafruit_httpserver import Server, Response, Redirect, GET, POST
+        is_cp = (hasattr(sys, "implementation")
+                 and sys.implementation.name == "circuitpython")
+        if is_cp:
+            import socketpool
+            import wifi
+            pool = socketpool.SocketPool(wifi.radio)
+            host = self._wm.ap_ip_address()
+        else:
+            pool = _stdlib_socket
+            host = "localhost"
+        self._server = Server(pool, root_path=None, debug=False)
+        self._server_url = "http://{}:{}/".format(host, self._port)
+        self._host = host
+        _self = self
+        @self._server.route("/", [GET])
+        def _index(request):
+            return Response(request, _self._render_form(),
+                            content_type="text/html")
+        @self._server.route("/save", [POST])
+        def _save(request):
+            if _self._apply(request):
+                return Response(request, _SAVED_PAGE % _esc(_self.saved_ssid),
+                                content_type="text/html")
+            return Redirect(request, "/", status=_SEE_OTHER)
+    # ------------------------------------------------------------------ #
+    # Panel instructions
+    # ------------------------------------------------------------------ #
+    def _instructions(self):
+        wm = self._wm
+        return ("WiFi setup: join \"%s\" (password: %s) then open http://%s"
+                % (wm.AP_SSID, wm.AP_PASSWORD, wm.ap_ip_address()))
+    def _make_status_content(self):
+        """A ScrollingText with the join instructions, or None if the display
+        stack isn't usable (the portal must never die because of the panel)."""
+        if self._display is None:
+            return None
+        try:
+            from ..display.content import ScrollingText
+            return ScrollingText(self._instructions(), y=20, color=0x00A0FF)
+        except Exception as e:
+            print("wifi portal: status content unavailable:", e)
+            return None
+    # ------------------------------------------------------------------ #
+    # The blocking onboarding loop
+    # ------------------------------------------------------------------ #
+    async def run(self, timeout_s=None):
+        """Scan, start the AP, and serve the portal until credentials are
+        saved (returns True), the timeout passes, or the simulator window is
+        closed (returns False). Stops the server and the AP either way."""
+        wm = self._wm
+        # Scan BEFORE AP mode: some radio builds can't scan while running an
+        # access point, and the list only needs to be fresh-ish.
+        try:
+            self._networks = wm.scan_networks() or []
+        except Exception as e:
+            print("wifi portal: scan failed:", e)
+            self._networks = []
+        wm.start_access_point()
+        try:
+            self._build_server()
+            self._server.start(getattr(self, "_host", "localhost"), self._port)
+            print("WiFi setup portal on %s (AP %r)"
+                  % (self._server_url, wm.AP_SSID))
+            status = self._make_status_content()
+            if status is not None:
+                try:
+                    await status.start()
+                except Exception:
+                    status = None
+            start = time.monotonic()
+            linger_until = None
+            while True:
+                try:
+                    self._server.poll()
+                except OSError as e:
+                    print("wifi portal poll error:", e)
+                # Serve a little longer after the save so the confirmation
+                # page reaches the phone, then exit.
+                if self.saved and linger_until is None:
+                    linger_until = time.monotonic() + _LINGER_S
+                if linger_until is not None and time.monotonic() >= linger_until:
+                    break
+                if (timeout_s is not None
+                        and time.monotonic() - start >= timeout_s):
+                    break
+                if status is not None:
+                    try:
+                        await self._display.clear()
+                        await status.render(self._display)
+                        if await self._display.show() is False:
+                            break   # simulator window closed
+                    except Exception as e:
+                        print("wifi portal display error:", e)
+                        status = None
+                await asyncio.sleep(_POLL_INTERVAL)
+        finally:
+            try:
+                if self._server is not None:
+                    self._server.stop()
+            except Exception:
+                pass
+            wm.stop_access_point()
+        return self.saved

scrollkit-0.8.3.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: scrollkit
+Version: 0.8.3
+Summary: LED Matrix Display Framework for CircuitPython and Desktop
+Author-email: Michael Winslow Czeiszperger <michael@czei.org>
+License: MIT
+Project-URL: Homepage, https://github.com/czei/scrollkit
+Project-URL: Repository, https://github.com/czei/scrollkit
+Keywords: circuitpython,led-matrix,display,matrixportal,simulator
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: simulator
+Requires-Dist: pygame>=2.0; extra == "simulator"
+Requires-Dist: Pillow>=9.0; extra == "simulator"
+Requires-Dist: numpy>=1.21; extra == "simulator"
+Provides-Extra: web
+Requires-Dist: aiohttp>=3.8; extra == "web"
+Provides-Extra: dev
+Requires-Dist: scrollkit[simulator]; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: requests>=2.28; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+# ScrollKit
+Most LED-matrix libraries get you a scrolling "Hello, World" and stop. I built ScrollKit for what comes next: over-the-air updates to boards in the field, fault-tolerant data refresh, real transitions and effects, and a built-in web server users control from a browser. The hard part isn't any single feature. It's running all of them at once on a microcontroller without the display stuttering. It also runs on a desktop simulator I wrote that exports its own GIFs and videos, like the one below.
+*Built by [Michael Czeiszperger](http://czei.org)*
+📖 **Full documentation: [scrollkit.dev](https://scrollkit.dev)**
+<p align="center">
+  <!-- Absolute URL so the image also renders on the PyPI project page -->
+  <img src="https://raw.githubusercontent.com/czei/scrollkit/master/docs/assets/video/scrollkit-hero.gif" alt="ScrollKit hero: a swarm assembles the ScrollKit logo, sheen sweeps over it, then it colorizes to electric-blue/magenta/gold, all rendered on a 64×32 LED panel" width="640">
+</p>
+## Installation
+```bash
+# Desktop development with simulator
+pip install "scrollkit[simulator]"
+# To modify ScrollKit itself (or run the demos): clone and install editable
+git clone https://github.com/czei/scrollkit.git
+cd scrollkit && pip install -e ".[simulator]"
+# CircuitPython — copy scrollkit/ to your device's lib/ alongside your source
+```
+## Quick Start
+```python
+import asyncio
+from scrollkit.app.base import ScrollKitApp
+from scrollkit.display.content import ScrollingText
+class HelloWorldApp(ScrollKitApp):
+    async def setup(self):
+        self.content_queue.add(
+            ScrollingText("Hello, LED Matrix!", y=12, color=0x00AAFF))
+asyncio.run(HelloWorldApp().run())   # auto-detects MatrixPortal hardware vs desktop simulator
+```
+> The top-level `scrollkit` package deliberately performs **no** imports (every
+> import costs RAM on CircuitPython), so you always import from submodules, e.g.
+> `from scrollkit.app.base import ScrollKitApp`. See the
+> [getting-started guide](https://scrollkit.dev/getting-started/)
+> for the full `ScrollKitApp` / `UnifiedDisplay` API.
+## Architecture
+ScrollKit runs unchanged on the MatrixPortal S3 (CircuitPython) and a desktop
+pygame simulator. Your app subclasses `ScrollKitApp` and talks to one display
+abstraction; the library picks a backend at import time and brokers every external
+system the sign touches:
+```mermaid
+flowchart TB
+    app["Your app<br/>(subclasses ScrollKitApp)"] --> core["ScrollKitApp · UnifiedDisplay<br/>ContentQueue · effects · config"]
+    core -->|CircuitPython| hw["MatrixPortal S3<br/>displayio → RGBMatrix panel"]
+    core -->|desktop| sim["pygame simulator"]
+    core <-->|HttpClient — synchronous| api(["HTTP data API"])
+    core <-->|SettingsWebServer| browser(["Browser config UI"])
+    core -->|raw.githubusercontent.com| gh(["GitHub OTA"])
+```
+Subsystem dependencies (dashed = lazy import; `dev` and `simulator` are
+desktop-only, raising `ImportError` on the device):
+```mermaid
+flowchart LR
+    app["app"] --> display["display"]
+    app --> config["config"]
+    app -.->|lazy| utils["utils"]
+    app -.->|lazy| effects["effects"]
+    app -.->|lazy| web["web"]
+    effects --> display
+    display -.->|desktop| simulator["simulator"]
+    config -.->|lazy| utils
+    network["network"] --> config
+    network --> utils
+    ota["ota"] --> exceptions["exceptions"]
+    dev["dev"] --> display
+    dev --> effects
+    dev --> simulator
+    classDef desktop stroke-dasharray:6 4;
+    class dev,simulator desktop;
+```
+See the [Architecture guide](docs/guide/architecture.md) for the full write-up,
+including the invariants this graph enforces.
+## Package Structure
+```
+scrollkit/
+├── app/               # ScrollKitApp base class, async run loop, memory helpers
+├── display/           # UnifiedDisplay (auto-detects hardware vs simulator), content
+│   ├── unified.py                # Production display (device + desktop)
+│   ├── content.py                # DisplayContent / StaticText / ScrollingText / ContentQueue / Priority
+│   ├── bitmap_text.py            # Animated bitmap-font text + palette effects
+│   ├── gradient_text.py          # Gradient/multi-color text fill (GradientTextLayer)
+│   └── colors.py                 # Continuous 24-bit color generators
+├── effects/           # Transition contract (transitions.py) + standalone splash/particle helpers
+├── network/           # Networking utilities
+│   ├── http_client.py            # Dual-implementation HTTP client (raises NetworkError)
+│   ├── wifi_manager.py           # WiFi connection lifecycle
+│   └── mdns.py                   # <hostname>.local advertising (CircuitPython; no-op on desktop)
+├── config/            # Configuration management
+│   └── settings_manager.py       # JSON-based persistent settings
+├── ota/               # Over-the-air updates
+│   ├── client.py                 # GitHub-release-based OTA client
+│   ├── manifest.py               # Update manifest model
+│   ├── display_progress.py       # Display-progress adapter over OTAClient
+│   └── publish.py                # Host-side release publishing (desktop/CI only)
+└── utils/             # Utilities
+    ├── error_handler.py          # Logging and error handling
+    ├── diagnostics.py            # NVM boot/crash record + reboot-loop safe-mode breaker
+    ├── color_utils.py            # Named colors + settings-UI hex-string color table (no conversion helpers; int-based conversions live in display/colors.py)
+    ├── system_utils.py           # NTP / HTTP-Date system clock sync
+    └── url_utils.py              # URL decoding and credential loading
+```
+## Core API
+### Display
+```python
+from scrollkit.display.unified import UnifiedDisplay
+from scrollkit.display.content import ContentQueue, ScrollingText
+# Create display (auto-detects CircuitPython vs desktop)
+display = UnifiedDisplay(width=64, height=32)
+display.initialize()
+# ScrollKitApp drives this queue's render loop for you (see Quick Start above);
+# add() is all a subclass's setup() typically needs to call.
+queue = ContentQueue()
+queue.add(ScrollingText("Scrolling text", y=12, color=0x00AAFF))
+```
+### HTTP Client
+```python
+from scrollkit.network.http_client import HttpClient
+from scrollkit.exceptions import NetworkError
+client = HttpClient()
+try:
+    response = await client.get("https://api.example.com/data")
+    data = response.json()
+except NetworkError as e:
+    print("fetch failed:", e)
+```
+### Settings
+```python
+from scrollkit.config.settings_manager import SettingsManager
+settings = SettingsManager("app_settings.json",
+    defaults={"hostname": "mydevice", "brightness": "0.5"},
+    bool_keys=["dark_mode"])
+settings.set("hostname", "new-name")
+settings.save_settings()
+```
+### Utilities
+```python
+from scrollkit.utils.error_handler import ErrorHandler
+from scrollkit.display.colors import scale
+from scrollkit.network.wifi_manager import is_dev_mode
+logger = ErrorHandler("app.log")
+logger.info("Application started")
+color = scale(0xff0000, 0.5)  # Dim red to 50%
+if is_dev_mode():
+    print("running on desktop, not CircuitPython")
+```
+## Platform Support
+| Platform | Backend | Status |
+|---|---|---|
+| Adafruit MatrixPortal S3 | CircuitPython + displayio | ✅ Calibrated from device |
+| Pimoroni Interstate 75 W (RP2350) | CircuitPython + rgbmatrix | ✅ Supported (perf profile uncalibrated) |
+| Desktop (macOS/Linux/Windows) | SLDK Simulator | ✅ |
+| Custom CircuitPython boards | displayio / rgbmatrix | 🔌 Extensible (see [Adding New Hardware](https://scrollkit.dev/guide/hardware/)) |
+## How this was built
+I wrote the first two shipping versions by hand in 2024, when all of this was
+still one application. Splitting it into a library and a separate app layer, then
+documenting the result, is the kind of project that dies quietly in a spare-time
+backlog. So I used Claude Code and spec-driven development to handle the
+refactoring and the first drafts, then went back through all of it in my own
+voice, with my own screenshots. Yes, AI has touched a lot of this code. It was
+also directed by an engineer who has shipped production software for a living,
+including time on one of Sun Microsystems' API teams. Both are true.
+## License
+MIT