refactor: Fix import ordering and code formatting with ruff

Organize imports in render.py and scroll.py to meet ruff style requirements.
Add blank lines for code formatting compliance.

.gitignore

@@ -1,4 +1,11 @@
 __pycache__/
 *.pyc
 .mainline_venv/
+.venv/
+uv.lock
 .mainline_cache_*.json
+.DS_Store
+htmlcov/
+.coverage
+.pytest_cache/
+*.egg-info/

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -2,11 +2,13 @@
 
 > *Digital consciousness stream. Matrix aesthetic · THX-1138 hue.*
 
-A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with a white-hot → deep green gradient. Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. Live messages can be pushed to the display over [ntfy.sh](https://ntfy.sh).
+A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with selectable color gradients (Verdant Green, Molten Orange, or Violet Purple). Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. Live messages can be pushed to the display over [ntfy.sh](https://ntfy.sh).
 
 ---
 
-## Run
+## Using
+
+### Run
 
 ```bash
 python3 mainline.py                      # news stream
@@ -20,11 +22,15 @@ python3 mainline.py --font-dir ~/fonts   # scan a different font folder
 python3 mainline.py --font-index 1       # select face index within a collection
 ```
 
-First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately, loading from cache.
+Or with uv:
 
----
+```bash
+uv run mainline.py
+```
 
-## Config
+First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately, loading from cache. With uv, run `uv sync` or `uv sync --all-extras` (includes mic support) instead.
+
+### Config
 
 All constants live in `engine/config.py`:
 
@@ -44,23 +50,56 @@ All constants live in `engine/config.py`:
 | `FRAME_DT` | `0.05` | Frame interval in seconds (20 FPS) |
 | `GRAD_SPEED` | `0.08` | Gradient sweep speed (cycles/sec, ~12s full sweep) |
 | `FIREHOSE_H` | `12` | Firehose zone height (terminal rows) |
-| `NTFY_TOPIC` | klubhaus URL | ntfy.sh JSON endpoint to poll |
+| `NTFY_TOPIC` | klubhaus URL | ntfy.sh JSON stream endpoint |
-| `NTFY_POLL_INTERVAL` | `15` | Seconds between ntfy polls |
+| `NTFY_RECONNECT_DELAY` | `5` | Seconds before reconnecting after a dropped SSE stream |
 | `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen |
 
----
+### Feeds
 
-## Fonts
+~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap feeds in `engine/sources.py` → `FEEDS`.
 
-A `fonts/` directory is bundled with demo faces (AlphatronDemo, CSBishopDrawn, CyberformDemo, KATA, Microbots, Neoform, Pixel Sparta, Robocops, Xeonic, and others). On startup, an interactive picker lists all discovered faces with a live half-block preview rendered at your configured size.
+**Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson. Sources are in `engine/sources.py` → `POETRY_SOURCES`.
+
+### Fonts
+
+A `fonts/` directory is bundled with demo faces (AgorTechnoDemo, AlphatronDemo, CSBishopDrawn, CubaTechnologyDemo, CyberformDemo, KATA, Microbots, ModernSpaceDemo, Neoform, Pixel Sparta, RaceHugoDemo, Resond, Robocops, Synthetix, Xeonic, and others). On startup, an interactive picker lists all discovered faces with a live half-block preview rendered at your configured size.
 
 Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selected face persists for that session.
 
 To add your own fonts, drop `.otf`, `.ttf`, or `.ttc` files into `fonts/` (or point `--font-dir` at any other folder). Font collections (`.ttc`, multi-face `.otf`) are enumerated face-by-face.
 
+### Color Schemes
+
+Mainline supports three color themes for the scrolling gradient: **Verdant Green**, **Molten Orange**, and **Violet Purple**. Each theme uses a precise color-opposite palette for ntfy message queue rendering (magenta, blue, and yellow respectively).
+
+On startup, an interactive picker presents all available color schemes:
+```
+  [1] Verdant Green    (white-hot → deep green)
+  [2] Molten Orange    (white-hot → deep orange)
+  [3] Violet Purple    (white-hot → deep purple)
+```
+
+Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selection applies only to the current session; you'll pick a fresh theme each run.
+
+**Note:** The boot UI (title, status lines, font picker menu) uses a hardcoded green accent color for visual continuity. Only the scrolling headlines and incoming messages render in the selected theme gradient.
+
+### ntfy.sh
+
+Mainline polls a configurable ntfy.sh topic in the background. When a message arrives, the scroll pauses and the message renders full-screen for `MESSAGE_DISPLAY_SECS` seconds, then the stream resumes.
+
+To push a message:
+
+```bash
+curl -d "Body text" -H "Title: Alert title" https://ntfy.sh/your_topic
+```
+
+Update `NTFY_TOPIC` in `engine/config.py` to point at your own topic.
+
 ---
 
-## How it works
+## Internals
+
+### How it works
 
 - On launch, the font picker scans `fonts/` and presents a live-rendered TUI for face selection; `--no-font-picker` skips directly to stream
 - Feeds are fetched and filtered on startup (sports and vapid content stripped); results are cached to `.mainline_cache_news.json` / `.mainline_cache_poetry.json` for fast restarts
@@ -69,11 +108,9 @@ To add your own fonts, drop `.otf`, `.ttf`, or `.ttc` files into `fonts/` (or po
 - Subject-region detection runs a regex pass on each headline; matches trigger a Google Translate call and font swap to the appropriate script (CJK, Arabic, Devanagari, etc.) using macOS system fonts
 - The mic stream runs in a background thread, feeding RMS dB into the glitch probability calculation each frame
 - The viewport scrolls through a virtual canvas of pre-rendered blocks; fade zones at top and bottom dissolve characters probabilistically
-- An ntfy.sh poller runs in a background thread; incoming messages interrupt the scroll and render full-screen until dismissed or expired
+- An ntfy.sh SSE stream runs in a background thread; incoming messages interrupt the scroll and render full-screen until dismissed or expired
 
----
+### Architecture
-
-## Architecture
 
 `mainline.py` is a thin entrypoint (venv bootstrap → `engine.app.main()`). All logic lives in the `engine/` package:
 
@@ -91,43 +128,122 @@ engine/
   mic.py          MicMonitor — standalone, graceful fallback
   scroll.py       stream() frame loop + message rendering
   app.py          main(), font picker TUI, boot sequence, signal handler
+
+tests/
+  test_config.py
+  test_filter.py
+  test_mic.py
+  test_ntfy.py
+  test_sources.py
+  test_terminal.py
 ```
 
 `ntfy.py` and `mic.py` have zero internal dependencies and can be imported by any other visualizer.
 
 ---
 
-## Feeds
+## Extending
 
-~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap feeds in `engine/sources.py` → `FEEDS`.
+`ntfy.py` and `mic.py` are fully standalone and designed to be reused by any terminal visualizer. `engine.render` is the importable rendering pipeline for non-terminal targets.
 
-**Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson. Sources are in `engine/sources.py` → `POETRY_SOURCES`.
+### NtfyPoller
-
----
-
-## ntfy.sh Integration
-
-Mainline polls a configurable ntfy.sh topic in the background. When a message arrives, the scroll pauses and the message renders full-screen for `MESSAGE_DISPLAY_SECS` seconds, then the stream resumes.
-
-To push a message:
-
-```bash
-curl -d "Body text" -H "Title: Alert title" https://ntfy.sh/your_topic
-```
-
-Update `NTFY_TOPIC` in `engine/config.py` to point at your own topic. The `NtfyPoller` class is fully standalone and can be reused by other visualizers:
 
 ```python
 from engine.ntfy import NtfyPoller
-poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1")
+
+poller = NtfyPoller("https://ntfy.sh/my_topic/json")
 poller.start()
-# in render loop:
+
-msg = poller.get_active_message()  # returns (title, body, timestamp) or None
+# in your render loop:
+msg = poller.get_active_message()  # → (title, body, timestamp) or None
+if msg:
+    title, body, ts = msg
+    render_my_message(title, body)  # visualizer-specific
 ```
 
+Dependencies: `urllib.request`, `json`, `threading`, `time` — stdlib only. The `since=` parameter is managed automatically on reconnect.
+
+### MicMonitor
+
+```python
+from engine.mic import MicMonitor
+
+mic = MicMonitor(threshold_db=50)
+result = mic.start()   # None = sounddevice unavailable; False = stream failed; True = ok
+if result:
+    excess = mic.excess    # dB above threshold, clamped to 0
+    db = mic.db            # raw RMS dB level
+```
+
+Dependencies: `sounddevice`, `numpy` — both optional; degrades gracefully if unavailable.
+
+### Render pipeline
+
+`engine.render` exposes the OTF → raster pipeline independently of the terminal scroll loop. The planned `serve.py` extension will import it directly to pre-render headlines as 1-bit bitmaps for an ESP32 thin client:
+
+```python
+# planned — serve.py does not yet exist
+from engine.render import render_line, big_wrap
+from engine.fetch import fetch_all
+
+headlines = fetch_all()
+for h in headlines:
+    rows = big_wrap(h.text, font, width=800)  # list of half-block rows
+    # threshold to 1-bit, pack bytes, serve over HTTP
+```
+
+See `Mainline Renderer + ntfy Message Queue for ESP32.md` for the full server + thin client architecture.
+
 ---
 
-## Ideas / Future
+## Development
+
+### Setup
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                              # minimal (no mic)
+uv sync --all-extras                 # with mic support (sounddevice + numpy)
+uv sync --all-extras --group dev     # full dev environment
+```
+
+### Tasks
+
+With [mise](https://mise.jdx.dev/):
+
+```bash
+mise run test            # run test suite
+mise run test-cov        # run with coverage report
+mise run lint            # ruff check
+mise run lint-fix        # ruff check --fix
+mise run format          # ruff format
+mise run run             # uv run mainline.py
+mise run run-poetry      # uv run mainline.py --poetry
+mise run run-firehose    # uv run mainline.py --firehose
+```
+
+### Testing
+
+Tests live in `tests/` and cover `config`, `filter`, `mic`, `ntfy`, `sources`, and `terminal`.
+
+```bash
+uv run pytest
+uv run pytest --cov=engine --cov-report=term-missing
+```
+
+### Linting
+
+```bash
+uv run ruff check engine/ mainline.py
+uv run ruff format engine/ mainline.py
+```
+
+Pre-commit hooks run lint automatically via `hk`.
+
+---
+
+## Roadmap
 
 ### Performance
 - **Concurrent feed fetching** — startup currently blocks sequentially on ~25 HTTP requests; `concurrent.futures.ThreadPoolExecutor` would cut load time to the slowest single feed
@@ -154,4 +270,4 @@ msg = poller.get_active_message()  # returns (title, body, timestamp) or None
 
 ---
 
-*macOS only (script/system font paths for translation are hardcoded). Primary display font is user-selectable via the bundled `fonts/` picker. Python 3.9+.*
+*macOS only (script/system font paths for translation are hardcoded). Primary display font is user-selectable via the bundled `fonts/` picker. Python 3.10+.*

docs/superpowers/plans/2026-03-16-color-scheme-implementation.md

@@ -0,0 +1,894 @@
+# Color Scheme Switcher Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement interactive color theme picker at startup that lets users choose between green, orange, or purple gradients with complementary message queue colors.
+
+**Architecture:** New `themes.py` data module defines Theme class and THEME_REGISTRY. Config adds `ACTIVE_THEME` global set by picker. Render functions read from active theme instead of hardcoded constants. App adds picker UI that mirrors font picker pattern.
+
+**Tech Stack:** Python 3.10+, ANSI 256-color codes, existing terminal I/O utilities
+
+---
+
+## File Structure
+
+| File | Purpose | Change Type |
+|------|---------|------------|
+| `engine/themes.py` | Theme class, THEME_REGISTRY, color codes | Create |
+| `engine/config.py` | ACTIVE_THEME global, set_active_theme() | Modify |
+| `engine/render.py` | Replace GRAD_COLS/MSG_GRAD_COLS with config lookup | Modify |
+| `engine/scroll.py` | Update message gradient call | Modify |
+| `engine/app.py` | pick_color_theme(), call in main() | Modify |
+| `tests/test_themes.py` | Theme class and registry unit tests | Create |
+
+---
+
+## Chunk 1: Theme Data Module
+
+### Task 1: Create themes.py with Theme class and registry
+
+**Files:**
+- Create: `engine/themes.py`
+- Test: `tests/test_themes.py`
+
+- [ ] **Step 1: Write failing test for Theme class**
+
+Create `tests/test_themes.py`:
+
+```python
+"""Test color themes and registry."""
+from engine.themes import Theme, THEME_REGISTRY, get_theme
+
+
+def test_theme_construction():
+    """Theme stores name and gradient lists."""
+    main = ["\033[1;38;5;231m"] * 12
+    msg = ["\033[1;38;5;225m"] * 12
+    theme = Theme(name="Test Green", main_gradient=main, message_gradient=msg)
+
+    assert theme.name == "Test Green"
+    assert theme.main_gradient == main
+    assert theme.message_gradient == msg
+
+
+def test_gradient_length():
+    """Each gradient must have exactly 12 ANSI codes."""
+    for theme_id, theme in THEME_REGISTRY.items():
+        assert len(theme.main_gradient) == 12, f"{theme_id} main gradient wrong length"
+        assert len(theme.message_gradient) == 12, f"{theme_id} message gradient wrong length"
+
+
+def test_theme_registry_has_three_themes():
+    """Registry contains green, orange, purple."""
+    assert len(THEME_REGISTRY) == 3
+    assert "green" in THEME_REGISTRY
+    assert "orange" in THEME_REGISTRY
+    assert "purple" in THEME_REGISTRY
+
+
+def test_get_theme_valid():
+    """get_theme returns Theme object for valid ID."""
+    theme = get_theme("green")
+    assert isinstance(theme, Theme)
+    assert theme.name == "Verdant Green"
+
+
+def test_get_theme_invalid():
+    """get_theme raises KeyError for invalid ID."""
+    with pytest.raises(KeyError):
+        get_theme("invalid_theme")
+
+
+def test_green_theme_unchanged():
+    """Green theme uses original green → magenta colors."""
+    green_theme = get_theme("green")
+    # First color should be white (bold)
+    assert green_theme.main_gradient[0] == "\033[1;38;5;231m"
+    # Last deep green
+    assert green_theme.main_gradient[9] == "\033[38;5;22m"
+    # Message gradient is magenta
+    assert green_theme.message_gradient[9] == "\033[38;5;89m"
+```
+
+Run: `pytest tests/test_themes.py -v`
+Expected: FAIL (module doesn't exist)
+
+- [ ] **Step 2: Create themes.py with Theme class and finalized gradients**
+
+Create `engine/themes.py`:
+
+```python
+"""Color theme definitions and registry."""
+from typing import Optional
+
+
+class Theme:
+    """Encapsulates a color scheme: name, main gradient, message gradient."""
+
+    def __init__(self, name: str, main_gradient: list[str], message_gradient: list[str]):
+        """Initialize theme with display name and gradient lists.
+
+        Args:
+            name: Display name (e.g., "Verdant Green")
+            main_gradient: List of 12 ANSI 256-color codes (white → primary color)
+            message_gradient: List of 12 ANSI codes (white → complementary color)
+        """
+        self.name = name
+        self.main_gradient = main_gradient
+        self.message_gradient = message_gradient
+
+
+# ─── FINALIZED GRADIENTS ──────────────────────────────────────────────────
+# Each gradient: white → primary/complementary, 12 steps total
+# Format: "\033[<brightness>;<color>m" where color is 38;5;<colorcode>
+
+_GREEN_MAIN = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;195m",  # pale white-tint
+    "\033[38;5;123m",    # bright cyan
+    "\033[38;5;118m",    # bright lime
+    "\033[38;5;82m",     # lime
+    "\033[38;5;46m",     # bright green
+    "\033[38;5;40m",     # green
+    "\033[38;5;34m",     # medium green
+    "\033[38;5;28m",     # dark green
+    "\033[38;5;22m",     # deep green
+    "\033[2;38;5;22m",   # dim deep green
+    "\033[2;38;5;235m",  # near black
+]
+
+_GREEN_MESSAGE = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;225m",  # pale pink-white
+    "\033[38;5;219m",    # bright pink
+    "\033[38;5;213m",    # hot pink
+    "\033[38;5;207m",    # magenta
+    "\033[38;5;201m",    # bright magenta
+    "\033[38;5;165m",    # orchid-red
+    "\033[38;5;161m",    # ruby-magenta
+    "\033[38;5;125m",    # dark magenta
+    "\033[38;5;89m",     # deep maroon-magenta
+    "\033[2;38;5;89m",   # dim deep maroon-magenta
+    "\033[2;38;5;235m",  # near black
+]
+
+_ORANGE_MAIN = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;215m",  # pale orange-white
+    "\033[38;5;209m",    # bright orange
+    "\033[38;5;208m",    # vibrant orange
+    "\033[38;5;202m",    # orange
+    "\033[38;5;166m",    # dark orange
+    "\033[38;5;130m",    # burnt orange
+    "\033[38;5;94m",     # rust
+    "\033[38;5;58m",     # dark rust
+    "\033[38;5;94m",     # rust (hold)
+    "\033[2;38;5;94m",   # dim rust
+    "\033[2;38;5;235m",  # near black
+]
+
+_ORANGE_MESSAGE = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;195m",  # pale cyan-white
+    "\033[38;5;33m",     # bright blue
+    "\033[38;5;27m",     # blue
+    "\033[38;5;21m",     # deep blue
+    "\033[38;5;21m",     # deep blue (hold)
+    "\033[38;5;21m",     # deep blue (hold)
+    "\033[38;5;18m",     # navy
+    "\033[38;5;18m",     # navy (hold)
+    "\033[38;5;18m",     # navy (hold)
+    "\033[2;38;5;18m",   # dim navy
+    "\033[2;38;5;235m",  # near black
+]
+
+_PURPLE_MAIN = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;225m",  # pale purple-white
+    "\033[38;5;177m",    # bright purple
+    "\033[38;5;171m",    # vibrant purple
+    "\033[38;5;165m",    # purple
+    "\033[38;5;135m",    # medium purple
+    "\033[38;5;129m",    # purple
+    "\033[38;5;93m",     # dark purple
+    "\033[38;5;57m",     # deep purple
+    "\033[38;5;57m",     # deep purple (hold)
+    "\033[2;38;5;57m",   # dim deep purple
+    "\033[2;38;5;235m",  # near black
+]
+
+_PURPLE_MESSAGE = [
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;226m",  # pale yellow-white
+    "\033[38;5;226m",    # bright yellow
+    "\033[38;5;220m",    # yellow
+    "\033[38;5;220m",    # yellow (hold)
+    "\033[38;5;184m",    # dark yellow
+    "\033[38;5;184m",    # dark yellow (hold)
+    "\033[38;5;178m",    # olive-yellow
+    "\033[38;5;178m",    # olive-yellow (hold)
+    "\033[38;5;172m",    # golden
+    "\033[2;38;5;172m",  # dim golden
+    "\033[2;38;5;235m",  # near black
+]
+
+# ─── THEME REGISTRY ───────────────────────────────────────────────────────
+
+THEME_REGISTRY = {
+    "green": Theme(
+        name="Verdant Green",
+        main_gradient=_GREEN_MAIN,
+        message_gradient=_GREEN_MESSAGE,
+    ),
+    "orange": Theme(
+        name="Molten Orange",
+        main_gradient=_ORANGE_MAIN,
+        message_gradient=_ORANGE_MESSAGE,
+    ),
+    "purple": Theme(
+        name="Violet Purple",
+        main_gradient=_PURPLE_MAIN,
+        message_gradient=_PURPLE_MESSAGE,
+    ),
+}
+
+
+def get_theme(theme_id: str) -> Theme:
+    """Retrieve a theme by ID.
+
+    Args:
+        theme_id: One of "green", "orange", "purple"
+
+    Returns:
+        Theme object
+
+    Raises:
+        KeyError: If theme_id not found in registry
+    """
+    if theme_id not in THEME_REGISTRY:
+        raise KeyError(f"Unknown theme: {theme_id}. Available: {list(THEME_REGISTRY.keys())}")
+    return THEME_REGISTRY[theme_id]
+```
+
+- [ ] **Step 3: Run tests to verify they pass**
+
+Run: `pytest tests/test_themes.py -v`
+Expected: PASS (all 6 tests)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add engine/themes.py tests/test_themes.py
+git commit -m "feat: create Theme class and registry with finalized color gradients
+
+- Define Theme class to encapsulate name and main/message gradients
+- Create THEME_REGISTRY with green, orange, purple themes
+- Each gradient has 12 ANSI 256-color codes finalized
+- Complementary color pairs: green/magenta, orange/blue, purple/yellow
+- Add get_theme() lookup with error handling
+- Add comprehensive unit tests"
+```
+
+---
+
+## Chunk 2: Config Integration
+
+### Task 2: Add ACTIVE_THEME global and set_active_theme() to config.py
+
+**Files:**
+- Modify: `engine/config.py:1-30`
+- Test: `tests/test_config.py` (expand existing)
+
+- [ ] **Step 1: Write failing tests for config changes**
+
+Add to `tests/test_config.py`:
+
+```python
+def test_active_theme_initially_none():
+    """ACTIVE_THEME is None before initialization."""
+    # This test may fail if config is already initialized
+    # We'll set it to None first for testing
+    import engine.config
+    engine.config.ACTIVE_THEME = None
+    assert engine.config.ACTIVE_THEME is None
+
+
+def test_set_active_theme_green():
+    """set_active_theme('green') sets ACTIVE_THEME to green theme."""
+    from engine.config import set_active_theme
+    from engine.themes import get_theme
+
+    set_active_theme("green")
+
+    assert config.ACTIVE_THEME is not None
+    assert config.ACTIVE_THEME.name == "Verdant Green"
+    assert config.ACTIVE_THEME == get_theme("green")
+
+
+def test_set_active_theme_default():
+    """set_active_theme() with no args defaults to green."""
+    from engine.config import set_active_theme
+
+    set_active_theme()
+
+    assert config.ACTIVE_THEME.name == "Verdant Green"
+
+
+def test_set_active_theme_invalid():
+    """set_active_theme() with invalid ID raises KeyError."""
+    from engine.config import set_active_theme
+
+    with pytest.raises(KeyError):
+        set_active_theme("invalid")
+```
+
+Run: `pytest tests/test_config.py -v`
+Expected: FAIL (functions don't exist yet)
+
+- [ ] **Step 2: Add ACTIVE_THEME global and set_active_theme() to config.py**
+
+Edit `engine/config.py`, add after line 30 (after `_resolve_font_path` function):
+
+```python
+# ─── COLOR THEME ──────────────────────────────────────────────────────────
+ACTIVE_THEME = None  # set by set_active_theme() after picker
+
+
+def set_active_theme(theme_id: str = "green"):
+    """Set the active color theme. Defaults to 'green' if not specified.
+
+    Args:
+        theme_id: One of "green", "orange", "purple"
+
+    Raises:
+        KeyError: If theme_id is invalid
+    """
+    global ACTIVE_THEME
+    from engine import themes
+    ACTIVE_THEME = themes.get_theme(theme_id)
+```
+
+- [ ] **Step 3: Remove hardcoded GRAD_COLS and MSG_GRAD_COLS from render.py**
+
+Edit `engine/render.py`, find and delete lines 20-49 (the hardcoded gradient arrays):
+
+```python
+# DELETED:
+# GRAD_COLS = [...]
+# MSG_GRAD_COLS = [...]
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_config.py::test_active_theme_initially_none -v`
+Run: `pytest tests/test_config.py::test_set_active_theme_green -v`
+Run: `pytest tests/test_config.py::test_set_active_theme_default -v`
+Run: `pytest tests/test_config.py::test_set_active_theme_invalid -v`
+
+Expected: PASS (all 4 new tests)
+
+- [ ] **Step 5: Verify existing config tests still pass**
+
+Run: `pytest tests/test_config.py -v`
+
+Expected: PASS (all existing + new tests)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add engine/config.py tests/test_config.py
+git commit -m "feat: add ACTIVE_THEME global and set_active_theme() to config
+
+- Add ACTIVE_THEME global (initialized to None)
+- Add set_active_theme(theme_id) function with green default
+- Remove hardcoded GRAD_COLS and MSG_GRAD_COLS (move to themes.py)
+- Add comprehensive tests for theme setting"
+```
+
+---
+
+## Chunk 3: Render Pipeline Integration
+
+### Task 3: Update render.py to use config.ACTIVE_THEME
+
+**Files:**
+- Modify: `engine/render.py:15-220`
+- Test: `tests/test_render.py` (expand existing)
+
+- [ ] **Step 1: Write failing test for lr_gradient with theme**
+
+Add to `tests/test_render.py`:
+
+```python
+def test_lr_gradient_uses_active_theme(monkeypatch):
+    """lr_gradient uses config.ACTIVE_THEME when cols=None."""
+    from engine import config, render
+    from engine.themes import get_theme
+
+    # Set orange theme
+    config.set_active_theme("orange")
+
+    # Create simple rows
+    rows = ["test row"]
+    result = render.lr_gradient(rows, offset=0, cols=None)
+
+    # Result should start with first color from orange main gradient
+    assert result[0].startswith("\033[1;38;5;231m")  # white (same for all)
+
+
+def test_lr_gradient_fallback_when_no_theme(monkeypatch):
+    """lr_gradient uses fallback when ACTIVE_THEME is None."""
+    from engine import config, render
+
+    # Clear active theme
+    config.ACTIVE_THEME = None
+
+    rows = ["test row"]
+    result = render.lr_gradient(rows, offset=0, cols=None)
+
+    # Should not crash and should return something
+    assert result is not None
+    assert len(result) > 0
+
+
+def test_default_green_gradient_length():
+    """_default_green_gradient returns 12 colors."""
+    from engine import render
+
+    colors = render._default_green_gradient()
+    assert len(colors) == 12
+```
+
+Run: `pytest tests/test_render.py::test_lr_gradient_uses_active_theme -v`
+Expected: FAIL (function signature doesn't match)
+
+- [ ] **Step 2: Update lr_gradient() to use config.ACTIVE_THEME**
+
+Edit `engine/render.py`, find the `lr_gradient()` function (around line 194) and update it:
+
+```python
+def lr_gradient(rows, offset, cols=None):
+    """
+    Render rows through a left-to-right color sweep.
+
+    Args:
+        rows: List of text rows to colorize
+        offset: Gradient position offset (for animation)
+        cols: Optional list of color codes. If None, uses active theme.
+
+    Returns:
+        List of colorized rows
+    """
+    if cols is None:
+        from engine import config
+        cols = (
+            config.ACTIVE_THEME.main_gradient
+            if config.ACTIVE_THEME
+            else _default_green_gradient()
+        )
+
+    # ... rest of function unchanged ...
+```
+
+- [ ] **Step 3: Add _default_green_gradient() fallback function**
+
+Add to `engine/render.py` before `lr_gradient()`:
+
+```python
+def _default_green_gradient():
+    """Fallback green gradient (original colors) for initialization."""
+    return [
+        "\033[1;38;5;231m",  # white (bold)
+        "\033[1;38;5;195m",  # pale white-tint
+        "\033[38;5;123m",    # bright cyan
+        "\033[38;5;118m",    # bright lime
+        "\033[38;5;82m",     # lime
+        "\033[38;5;46m",     # bright green
+        "\033[38;5;40m",     # green
+        "\033[38;5;34m",     # medium green
+        "\033[38;5;28m",     # dark green
+        "\033[38;5;22m",     # deep green
+        "\033[2;38;5;22m",   # dim deep green
+        "\033[2;38;5;235m",  # near black
+    ]
+
+
+def _default_magenta_gradient():
+    """Fallback magenta gradient (original message colors) for initialization."""
+    return [
+        "\033[1;38;5;231m",  # white (bold)
+        "\033[1;38;5;225m",  # pale pink-white
+        "\033[38;5;219m",    # bright pink
+        "\033[38;5;213m",    # hot pink
+        "\033[38;5;207m",    # magenta
+        "\033[38;5;201m",    # bright magenta
+        "\033[38;5;165m",    # orchid-red
+        "\033[38;5;161m",    # ruby-magenta
+        "\033[38;5;125m",    # dark magenta
+        "\033[38;5;89m",     # deep maroon-magenta
+        "\033[2;38;5;89m",   # dim deep maroon-magenta
+        "\033[2;38;5;235m",  # near black
+    ]
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_render.py::test_lr_gradient_uses_active_theme -v`
+Run: `pytest tests/test_render.py::test_lr_gradient_fallback_when_no_theme -v`
+Run: `pytest tests/test_render.py::test_default_green_gradient_length -v`
+
+Expected: PASS (all 3 new tests)
+
+- [ ] **Step 5: Run full render test suite**
+
+Run: `pytest tests/test_render.py -v`
+
+Expected: PASS (existing tests may need adjustment for mocking)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add engine/render.py tests/test_render.py
+git commit -m "feat: update lr_gradient to use config.ACTIVE_THEME
+
+- Update lr_gradient(cols=None) to check config.ACTIVE_THEME
+- Add _default_green_gradient() and _default_magenta_gradient() fallbacks
+- Fallback used when ACTIVE_THEME is None (non-interactive init)
+- Add tests for theme-aware and fallback gradient rendering"
+```
+
+---
+
+## Chunk 4: Message Gradient Integration
+
+### Task 4: Update scroll.py to use message gradient from config
+
+**Files:**
+- Modify: `engine/scroll.py:85-95`
+- Test: existing `tests/test_scroll.py`
+
+- [ ] **Step 1: Locate message gradient calls in scroll.py**
+
+Run: `grep -n "MSG_GRAD_COLS\|lr_gradient_opposite" /Users/genejohnson/Dev/mainline/engine/scroll.py`
+
+Expected: Should find line(s) where `MSG_GRAD_COLS` or similar is used
+
+- [ ] **Step 2: Update scroll.py to use theme message gradient**
+
+Edit `engine/scroll.py`, find the line that uses message gradients (around line 89 based on spec) and update:
+
+Old code:
+```python
+# Some variation of:
+rows = lr_gradient(rows, offset, MSG_GRAD_COLS)
+```
+
+New code:
+```python
+from engine import config
+msg_cols = (
+    config.ACTIVE_THEME.message_gradient
+    if config.ACTIVE_THEME
+    else render._default_magenta_gradient()
+)
+rows = lr_gradient(rows, offset, msg_cols)
+```
+
+Or use the helper approach (create `msg_gradient()` in render.py):
+
+```python
+def msg_gradient(rows, offset):
+    """Apply message (ntfy) gradient using theme complementary colors."""
+    from engine import config
+    cols = (
+        config.ACTIVE_THEME.message_gradient
+        if config.ACTIVE_THEME
+        else _default_magenta_gradient()
+    )
+    return lr_gradient(rows, offset, cols)
+```
+
+Then in scroll.py:
+```python
+rows = render.msg_gradient(rows, offset)
+```
+
+- [ ] **Step 3: Run existing scroll tests**
+
+Run: `pytest tests/test_scroll.py -v`
+
+Expected: PASS (existing functionality unchanged)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add engine/scroll.py engine/render.py
+git commit -m "feat: update scroll.py to use theme message gradient
+
+- Replace MSG_GRAD_COLS reference with config.ACTIVE_THEME.message_gradient
+- Use fallback magenta gradient when theme not initialized
+- Ensure ntfy messages render in complementary color from selected theme"
+```
+
+---
+
+## Chunk 5: Color Picker UI
+
+### Task 5: Create pick_color_theme() function in app.py
+
+**Files:**
+- Modify: `engine/app.py:1-300`
+- Test: manual/integration (interactive)
+
+- [ ] **Step 1: Write helper functions for color picker UI**
+
+Edit `engine/app.py`, add before `pick_font_face()` function:
+
+```python
+def _draw_color_picker(themes_list, selected):
+    """Draw the color theme picker menu."""
+    import sys
+    from engine.terminal import CLR, W_GHOST, G_HI, G_DIM, tw
+
+    print(CLR, end="")
+    print()
+    print(f"  {G_HI}▼ COLOR THEME{W_GHOST} ─ ↑/↓ or j/k to move, Enter/q to select{G_DIM}")
+    print(f"  {W_GHOST}{'─' * (tw() - 4)}\n")
+
+    for i, (theme_id, theme) in enumerate(themes_list):
+        prefix = "  ▶ " if i == selected else "    "
+        color = G_HI if i == selected else ""
+        reset = "" if i == selected else W_GHOST
+        print(f"{prefix}{color}{theme.name}{reset}")
+
+    print()
+```
+
+- [ ] **Step 2: Create pick_color_theme() function**
+
+Edit `engine/app.py`, add after helper function:
+
+```python
+def pick_color_theme():
+    """Interactive color theme picker. Defaults to 'green' if not TTY."""
+    import sys
+    import termios
+    import tty
+    from engine import config, themes
+
+    # Non-interactive fallback: use green
+    if not sys.stdin.isatty():
+        config.set_active_theme("green")
+        return
+
+    themes_list = list(themes.THEME_REGISTRY.items())
+    selected = 0
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        while True:
+            _draw_color_picker(themes_list, selected)
+            key = _read_picker_key()
+            if key == "up":
+                selected = max(0, selected - 1)
+            elif key == "down":
+                selected = min(len(themes_list) - 1, selected + 1)
+            elif key == "enter":
+                break
+            elif key == "interrupt":
+                raise KeyboardInterrupt
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+    selected_theme_id = themes_list[selected][0]
+    config.set_active_theme(selected_theme_id)
+
+    theme_name = themes_list[selected][1].name
+    print(f"  {G_DIM}> using {theme_name}{RST}")
+    time.sleep(0.8)
+    print(CLR, end="")
+    print(CURSOR_OFF, end="")
+    print()
+```
+
+- [ ] **Step 3: Update main() to call pick_color_theme() before pick_font_face()**
+
+Edit `engine/app.py`, find the `main()` function and locate where `pick_font_face()` is called (around line 265). Add before it:
+
+```python
+def main():
+    # ... existing signal handler setup ...
+
+    pick_color_theme()  # NEW LINE - before font picker
+    pick_font_face()
+
+    # ... rest of main unchanged ...
+```
+
+- [ ] **Step 4: Manual test - run in interactive terminal**
+
+Run: `python3 mainline.py`
+
+Expected:
+- See color theme picker menu before font picker
+- Can navigate with ↑/↓ or j/k
+- Can select with Enter or q
+- Selected theme applies to scrolling headlines
+- Can select different themes and see colors change
+
+- [ ] **Step 5: Manual test - run in non-interactive environment**
+
+Run: `echo "" | python3 mainline.py`
+
+Expected:
+- No color picker menu shown
+- Defaults to green theme
+- App runs without error
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add engine/app.py
+git commit -m "feat: add pick_color_theme() UI and integration
+
+- Create _draw_color_picker() to render menu
+- Create pick_color_theme() function mirroring font picker pattern
+- Integrate into main() before font picker
+- Fallback to green theme in non-interactive environments
+- Support arrow keys and j/k navigation"
+```
+
+---
+
+## Chunk 6: Integration & Validation
+
+### Task 6: End-to-end testing and cleanup
+
+**Files:**
+- Test: All modified files
+- Verify: App functionality
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `pytest tests/ -v`
+
+Expected: PASS (all tests, including new ones)
+
+- [ ] **Step 2: Run linter**
+
+Run: `ruff check engine/ mainline.py`
+
+Expected: No errors (fix any style issues)
+
+- [ ] **Step 3: Manual integration test - green theme**
+
+Run: `python3 mainline.py`
+
+Then select "Verdant Green" from picker.
+
+Expected:
+- Headlines render in green → deep green
+- ntfy messages render in magenta gradient
+- Both work correctly during streaming
+
+- [ ] **Step 4: Manual integration test - orange theme**
+
+Run: `python3 mainline.py`
+
+Then select "Molten Orange" from picker.
+
+Expected:
+- Headlines render in orange → deep orange
+- ntfy messages render in blue gradient
+- Colors are visually distinct from green
+
+- [ ] **Step 5: Manual integration test - purple theme**
+
+Run: `python3 mainline.py`
+
+Then select "Violet Purple" from picker.
+
+Expected:
+- Headlines render in purple → deep purple
+- ntfy messages render in yellow gradient
+- Colors are visually distinct from green and orange
+
+- [ ] **Step 6: Test poetry mode with color picker**
+
+Run: `python3 mainline.py --poetry`
+
+Then select "orange" from picker.
+
+Expected:
+- Poetry mode works with color picker
+- Colors apply to poetry rendering
+
+- [ ] **Step 7: Test code mode with color picker**
+
+Run: `python3 mainline.py --code`
+
+Then select "purple" from picker.
+
+Expected:
+- Code mode works with color picker
+- Colors apply to code rendering
+
+- [ ] **Step 8: Verify acceptance criteria**
+
+✓ Color picker displays 3 theme options at startup
+✓ Selection applies to all headline and message gradients
+✓ Boot UI (title, status) uses hardcoded green (not theme)
+✓ Scrolling headlines and ntfy messages use theme gradients
+✓ No persistence between runs (each run picks fresh)
+✓ Non-TTY environments default to green without error
+✓ Architecture supports future random/animation modes
+✓ All gradient color codes finalized with no TBD values
+
+- [ ] **Step 9: Final commit**
+
+```bash
+git add -A
+git commit -m "feat: color scheme switcher implementation complete
+
+Closes color-pick feature with:
+- Three selectable color themes (green, orange, purple)
+- Interactive menu at startup (mirrors font picker UI)
+- Complementary colors for ntfy message queue
+- Fallback to green in non-interactive environments
+- All tests passing, manual validation complete"
+```
+
+- [ ] **Step 10: Create feature branch PR summary**
+
+```
+## Color Scheme Switcher
+
+Implements interactive color theme selection for Mainline news ticker.
+
+### What's New
+- 3 color themes: Verdant Green, Molten Orange, Violet Purple
+- Interactive picker at startup (↑/↓ or j/k, Enter to select)
+- Complementary gradients for ntfy messages (magenta, blue, yellow)
+- Fresh theme selection each run (no persistence)
+
+### Files Changed
+- `engine/themes.py` (new)
+- `engine/config.py` (ACTIVE_THEME, set_active_theme)
+- `engine/render.py` (theme-aware gradients)
+- `engine/scroll.py` (message gradient integration)
+- `engine/app.py` (pick_color_theme UI)
+- `tests/test_themes.py` (new theme tests)
+- `README.md` (documentation)
+
+### Acceptance Criteria
+All met. App fully tested and ready for merge.
+```
+
+---
+
+## Testing Checklist
+
+- [ ] Unit tests: `pytest tests/test_themes.py -v`
+- [ ] Unit tests: `pytest tests/test_config.py -v`
+- [ ] Unit tests: `pytest tests/test_render.py -v`
+- [ ] Full suite: `pytest tests/ -v`
+- [ ] Linting: `ruff check engine/ mainline.py`
+- [ ] Manual: Green theme selection
+- [ ] Manual: Orange theme selection
+- [ ] Manual: Purple theme selection
+- [ ] Manual: Poetry mode with colors
+- [ ] Manual: Code mode with colors
+- [ ] Manual: Non-TTY fallback
+
+---
+
+## Notes
+
+- `themes.py` is data-only; never import config or render to prevent cycles
+- `ACTIVE_THEME` initialized to None; guaranteed non-None before stream() via pick_color_theme()
+- Font picker UI remains hardcoded green; title/subtitle use G_HI/G_DIM constants (not theme)
+- Message gradients use complementary colors; lookup in scroll.py
+- Each gradient has 12 colors; verify length in tests
+- No persistence; fresh picker each run

docs/superpowers/specs/2026-03-15-readme-update-design.md

@@ -0,0 +1,145 @@
+# README Update Design — 2026-03-15
+
+## Goal
+
+Restructure and expand `README.md` to:
+1. Align with the current codebase (Python 3.10+, uv/mise/pytest/ruff toolchain, 6 new fonts)
+2. Add extensibility-focused content (`Extending` section)
+3. Add developer workflow coverage (`Development` section)
+4. Improve navigability via top-level grouping (Approach C)
+
+---
+
+## Proposed Structure
+
+```
+# MAINLINE
+> tagline + description
+
+## Using
+  ### Run
+  ### Config
+  ### Feeds
+  ### Fonts
+  ### ntfy.sh
+
+## Internals
+  ### How it works
+  ### Architecture
+
+## Extending
+  ### NtfyPoller
+  ### MicMonitor
+  ### Render pipeline
+
+## Development
+  ### Setup
+  ### Tasks
+  ### Testing
+  ### Linting
+
+## Roadmap
+
+---
+*footer*
+```
+
+---
+
+## Section-by-section design
+
+### Using
+
+All existing content preserved verbatim. Two changes:
+- **Run**: add `uv run mainline.py` as an alternative invocation; expand bootstrap note to mention `uv sync` / `uv sync --all-extras`
+- **ntfy.sh**: remove `NtfyPoller` reuse code example (moves to Extending); keep push instructions and topic config
+
+Subsections moved into Using (currently standalone):
+- `Feeds` — it's configuration, not a concept
+- `ntfy.sh` (usage half)
+
+### Internals
+
+All existing content preserved verbatim. One change:
+- **Architecture**: append `tests/` directory listing to the module tree
+
+### Extending
+
+Entirely new section. Three subsections:
+
+**NtfyPoller**
+- Minimal working import + usage example
+- Note: stdlib only dependencies
+
+```python
+from engine.ntfy import NtfyPoller
+
+poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1")
+poller.start()
+
+# in your render loop:
+msg = poller.get_active_message()  # → (title, body, timestamp) or None
+if msg:
+    title, body, ts = msg
+    render_my_message(title, body)  # visualizer-specific
+```
+
+**MicMonitor**
+- Minimal working import + usage example
+- Note: sounddevice/numpy optional, degrades gracefully
+
+```python
+from engine.mic import MicMonitor
+
+mic = MicMonitor(threshold_db=50)
+if mic.start():                # returns False if sounddevice unavailable
+    excess = mic.excess        # dB above threshold, clamped to 0
+    db = mic.db                # raw RMS dB level
+```
+
+**Render pipeline**
+- Brief prose about `engine.render` as importable pipeline
+- Minimal sketch of serve.py / ESP32 usage pattern
+- Reference to `Mainline Renderer + ntfy Message Queue for ESP32.md`
+
+### Development
+
+Entirely new section. Four subsections:
+
+**Setup**
+- Hard requirements: Python 3.10+, uv
+- `uv sync` / `uv sync --all-extras` / `uv sync --group dev`
+
+**Tasks** (via mise)
+- `mise run test`, `test-cov`, `lint`, `lint-fix`, `format`, `run`, `run-poetry`, `run-firehose`
+
+**Testing**
+- Tests in `tests/` covering config, filter, mic, ntfy, sources, terminal
+- `uv run pytest` and `uv run pytest --cov=engine --cov-report=term-missing`
+
+**Linting**
+- `uv run ruff check` and `uv run ruff format`
+- Note: pre-commit hooks run lint via `hk`
+
+### Roadmap
+
+Existing `## Ideas / Future` content preserved verbatim. Only change: rename heading to `## Roadmap`.
+
+### Footer
+
+Update `Python 3.9+` → `Python 3.10+`.
+
+---
+
+## Files changed
+
+- `README.md` — restructured and expanded as above
+- No other files
+
+---
+
+## What is not changing
+
+- All existing prose, examples, and config table values — preserved verbatim where retained
+- The Ideas/Future content — kept intact under the new Roadmap heading
+- The cyberpunk voice and terse style of the existing README

docs/superpowers/specs/2026-03-16-code-scroll-design.md

@@ -0,0 +1,154 @@
+# Code Scroll Mode — Design Spec
+
+**Date:** 2026-03-16
+**Branch:** feat/code-scroll
+**Status:** Approved
+
+---
+
+## Overview
+
+Add a `--code` CLI flag that puts MAINLINE into "source consciousness" mode. Instead of RSS headlines or poetry stanzas, the program's own source code scrolls upward as large OTF half-block characters with the standard white-hot → deep green gradient. Each scroll item is one non-blank, non-comment line from `engine/*.py`, attributed to its enclosing function/class scope and dotted module path.
+
+---
+
+## Goals
+
+- Mirror the existing `--poetry` mode pattern as closely as possible
+- Zero new runtime dependencies (stdlib `ast` and `pathlib` only)
+- No changes to `scroll.py` or the render pipeline
+- The item tuple shape `(text, src, ts)` is unchanged
+
+---
+
+## New Files
+
+### `engine/fetch_code.py`
+
+Single public function `fetch_code()` that returns `(items, line_count, 0)`.
+
+**Algorithm:**
+
+1. Glob `engine/*.py` in sorted order
+2. For each file:
+   a. Read source text
+   b. `ast.parse(source)` → build a `{line_number: scope_label}` map by walking all `FunctionDef`, `AsyncFunctionDef`, and `ClassDef` nodes. Each node covers its full line range. Inner scopes override outer ones.
+   c. Iterate source lines (1-indexed). Skip if:
+      - The stripped line is empty
+      - The stripped line starts with `#`
+   d. For each kept line emit:
+      - `text` = `line.rstrip()` (preserve indentation for readability in the big render)
+      - `src` = scope label from the AST map, e.g. `stream()` for functions, `MicMonitor` for classes, `<module>` for top-level lines
+      - `ts` = dotted module path derived from filename, e.g. `engine/scroll.py` → `engine.scroll`
+3. Return `(items, len(items), 0)`
+
+**Scope label rules:**
+- `FunctionDef` / `AsyncFunctionDef` → `name()`
+- `ClassDef` → `name` (no parens)
+- No enclosing node → `<module>`
+
+**Dependencies:** `ast`, `pathlib` — stdlib only.
+
+---
+
+## Modified Files
+
+### `engine/config.py`
+
+Extend `MODE` detection to recognise `--code`:
+
+```python
+MODE = (
+    "poetry" if "--poetry" in sys.argv or "-p" in sys.argv
+    else "code" if "--code" in sys.argv
+    else "news"
+)
+```
+
+### `engine/app.py`
+
+**Subtitle line** — extend the subtitle dict:
+
+```python
+_subtitle = {
+    "poetry": "literary consciousness stream",
+    "code":   "source consciousness stream",
+}.get(config.MODE, "digital consciousness stream")
+```
+
+**Boot sequence** — add `elif config.MODE == "code":` branch after the poetry branch:
+
+```python
+elif config.MODE == "code":
+    from engine.fetch_code import fetch_code
+    slow_print("  > INITIALIZING SOURCE ARRAY...\n")
+    time.sleep(0.2)
+    print()
+    items, line_count, _ = fetch_code()
+    print()
+    print(f"  {G_DIM}>{RST} {G_MID}{line_count} LINES ACQUIRED{RST}")
+```
+
+No cache save/load — local source files are read instantly and change only on disk writes.
+
+---
+
+## Data Flow
+
+```
+engine/*.py (sorted)
+    │
+    ▼
+fetch_code()
+    │  ast.parse → scope map
+    │  filter blank + comment lines
+    │  emit (line, scope(), engine.module)
+    ▼
+items: List[Tuple[str, str, str]]
+    │
+    ▼
+stream(items, ntfy, mic)   ← unchanged
+    │
+    ▼
+next_headline() shuffles + recycles automatically
+```
+
+---
+
+## Error Handling
+
+- If a file fails to `ast.parse` (malformed source), fall back to `<module>` scope for all lines in that file — do not crash.
+- If `engine/` contains no `.py` files (shouldn't happen in practice), `fetch_code()` returns an empty list; `app.py`'s existing `if not items:` guard handles this.
+
+---
+
+## Testing
+
+New file: `tests/test_fetch_code.py`
+
+| Test | Assertion |
+|------|-----------|
+| `test_items_are_tuples` | Every item from `fetch_code()` is a 3-tuple of strings |
+| `test_blank_and_comment_lines_excluded` | No item text is empty; no item text (stripped) starts with `#` |
+| `test_module_path_format` | Every `ts` field matches pattern `engine\.\w+` |
+
+No mocking — tests read the real engine source files, keeping them honest against actual content.
+
+---
+
+## CLI
+
+```bash
+python3 mainline.py --code        # source consciousness mode
+uv run mainline.py --code
+```
+
+Compatible with all existing flags (`--no-font-picker`, `--font-file`, `--firehose`, etc.).
+
+---
+
+## Out of Scope
+
+- Syntax highlighting / token-aware coloring (can be added later)
+- `--code-dir` flag for pointing at arbitrary directories (YAGNI)
+- Caching code items to disk

docs/superpowers/specs/2026-03-16-color-scheme-design.md

@@ -0,0 +1,299 @@
+# Color Scheme Switcher Design
+
+**Date:** 2026-03-16
+**Status:** Revised after review
+**Scope:** Interactive color theme selection for Mainline news ticker
+
+---
+
+## Overview
+
+Mainline currently renders news headlines with a fixed white-hot → deep green gradient. This feature adds an interactive theme picker at startup that lets users choose between three precise color schemes (green, orange, purple), each with complementary message queue colors.
+
+The implementation uses a dedicated `Theme` class to encapsulate gradients and metadata, enabling future extensions like random rotation, animation, or additional themes without architectural changes.
+
+---
+
+## Requirements
+
+**Functional:**
+1. User selects a color theme from an interactive menu at startup (green, orange, or purple)
+2. Main headline gradient uses the selected primary color (white → color)
+3. Message queue (ntfy) gradient uses the precise complementary color (white → opposite)
+4. Selection is fresh each run (no persistence)
+5. Design supports future "random rotation" mode without refactoring
+
+**Complementary colors (precise opposites):**
+- Green (38;5;22) → Magenta (38;5;89) *(current, unchanged)*
+- Orange (38;5;208) → Blue (38;5;21)
+- Purple (38;5;129) → Yellow (38;5;226)
+
+**Non-functional:**
+- Reuse the existing font picker pattern for UI consistency
+- Zero runtime overhead during streaming (theme lookup happens once at startup)
+- **Boot UI (title, subtitle, status lines) use hardcoded green color constants (G_HI, G_DIM, G_MID); only scrolling headlines and ntfy messages use theme gradients**
+- Font picker UI remains hardcoded green for visual continuity
+
+---
+
+## Architecture
+
+### New Module: `engine/themes.py`
+
+**Data-only module:** Contains Theme class, THEME_REGISTRY, and get_theme() function. **Imports only typing; does NOT import config or render** to prevent circular dependencies.
+
+```python
+class Theme:
+    """Encapsulates a color scheme: name, main gradient, message gradient."""
+
+    def __init__(self, name: str, main_gradient: list[str], message_gradient: list[str]):
+        self.name = name
+        self.main_gradient = main_gradient      # white → primary color
+        self.message_gradient = message_gradient  # white → complementary
+```
+
+**Theme Registry:**
+Three instances registered by ID: `"green"`, `"orange"`, `"purple"` (IDs match menu labels for clarity).
+
+Each gradient is a list of 12 ANSI 256-color codes matching the current green gradient:
+```
+[
+    "\033[1;38;5;231m",  # white (bold)
+    "\033[1;38;5;195m",  # pale white-tint
+    "\033[38;5;123m",    # bright cyan
+    "\033[38;5;118m",    # bright lime
+    "\033[38;5;82m",     # lime
+    "\033[38;5;46m",     # bright color
+    "\033[38;5;40m",     # color
+    "\033[38;5;34m",     # medium color
+    "\033[38;5;28m",     # dark color
+    "\033[38;5;22m",     # deep color
+    "\033[2;38;5;22m",   # dim deep color
+    "\033[2;38;5;235m",  # near black
+]
+```
+
+**Finalized color codes:**
+
+**Green (primary: 22, complementary: 89)** — unchanged from current
+- Main: `[231, 195, 123, 118, 82, 46, 40, 34, 28, 22, 22(dim), 235]`
+- Messages: `[231, 225, 219, 213, 207, 201, 165, 161, 125, 89, 89(dim), 235]`
+
+**Orange (primary: 208, complementary: 21)**
+- Main: `[231, 215, 209, 208, 202, 166, 130, 94, 58, 94, 94(dim), 235]`
+- Messages: `[231, 195, 33, 27, 21, 21, 21, 18, 18, 18, 18(dim), 235]`
+
+**Purple (primary: 129, complementary: 226)**
+- Main: `[231, 225, 177, 171, 165, 135, 129, 93, 57, 57, 57(dim), 235]`
+- Messages: `[231, 226, 226, 220, 220, 184, 184, 178, 178, 172, 172(dim), 235]`
+
+**Public API:**
+- `get_theme(theme_id: str) -> Theme` — lookup by ID, raises KeyError if not found
+- `THEME_REGISTRY` — dict of all available themes (for picker)
+
+---
+
+### Modified: `engine/config.py`
+
+**New globals:**
+```python
+ACTIVE_THEME = None  # set by set_active_theme() after picker; guaranteed non-None during stream()
+```
+
+**New function:**
+```python
+def set_active_theme(theme_id: str = "green"):
+    """Set the active theme. Defaults to 'green' if not specified."""
+    global ACTIVE_THEME
+    from engine import themes
+    ACTIVE_THEME = themes.get_theme(theme_id)
+```
+
+**Behavior:**
+- Called by `app.pick_color_theme()` with user selection
+- Has default fallback to "green" for non-interactive environments (CI, testing, piped stdin)
+- Guarantees `ACTIVE_THEME` is set before any render functions are called
+
+**Removal:**
+- Delete hardcoded `GRAD_COLS` and `MSG_GRAD_COLS` constants
+
+---
+
+### Modified: `engine/render.py`
+
+**Updated gradient access in existing functions:**
+
+Current pattern (will be removed):
+```python
+GRAD_COLS = [...]  # hardcoded green
+MSG_GRAD_COLS = [...] # hardcoded magenta
+```
+
+New pattern — update `lr_gradient()` function:
+```python
+def lr_gradient(rows, offset, cols=None):
+    if cols is None:
+        from engine import config
+        cols = (config.ACTIVE_THEME.main_gradient
+                if config.ACTIVE_THEME
+                else _default_green_gradient())
+    # ... rest of function unchanged
+```
+
+**Define fallback:**
+```python
+def _default_green_gradient():
+    """Fallback green gradient (current colors)."""
+    return [
+        "\033[1;38;5;231m", "\033[1;38;5;195m", "\033[38;5;123m",
+        "\033[38;5;118m", "\033[38;5;82m", "\033[38;5;46m",
+        "\033[38;5;40m", "\033[38;5;34m", "\033[38;5;28m",
+        "\033[38;5;22m", "\033[2;38;5;22m", "\033[2;38;5;235m",
+    ]
+```
+
+**Message gradient handling:**
+
+The existing code (scroll.py line 89) calls `lr_gradient()` with `MSG_GRAD_COLS`. Change this call to:
+```python
+# Instead of: lr_gradient(rows, offset, MSG_GRAD_COLS)
+# Use:
+from engine import config
+cols = (config.ACTIVE_THEME.message_gradient
+        if config.ACTIVE_THEME
+        else _default_magenta_gradient())
+lr_gradient(rows, offset, cols)
+```
+
+or define a helper:
+```python
+def msg_gradient(rows, offset):
+    """Apply message (ntfy) gradient using theme complementary colors."""
+    from engine import config
+    cols = (config.ACTIVE_THEME.message_gradient
+            if config.ACTIVE_THEME
+            else _default_magenta_gradient())
+    return lr_gradient(rows, offset, cols)
+```
+
+---
+
+### Modified: `engine/app.py`
+
+**New function: `pick_color_theme()`**
+
+Mirrors `pick_font_face()` pattern:
+
+```python
+def pick_color_theme():
+    """Interactive color theme picker. Defaults to 'green' if not TTY."""
+    import sys
+    from engine import config, themes
+
+    # Non-interactive fallback: use default
+    if not sys.stdin.isatty():
+        config.set_active_theme("green")
+        return
+
+    # Interactive picker (similar to font picker)
+    themes_list = list(themes.THEME_REGISTRY.items())
+    selected = 0
+
+    # ... render menu, handle arrow keys j/k, ↑/↓ ...
+    # ... on Enter, call config.set_active_theme(themes_list[selected][0]) ...
+```
+
+**Placement in `main()`:**
+```python
+def main():
+    # ... signal handler setup ...
+    pick_color_theme()  # NEW — before title/subtitle
+    pick_font_face()
+    # ... rest of boot sequence, title/subtitle use hardcoded G_HI/G_DIM ...
+```
+
+**Important:** The title and subtitle render with hardcoded `G_HI`/`G_DIM` constants, not theme gradients. This is intentional for visual consistency with the font picker menu.
+
+---
+
+## Data Flow
+
+```
+User starts: mainline.py
+    ↓
+main() called
+    ↓
+pick_color_theme()
+    → If TTY: display menu, read input, call config.set_active_theme(user_choice)
+    → If not TTY: silently call config.set_active_theme("green")
+    ↓
+pick_font_face() — renders in hardcoded green UI colors
+    ↓
+Boot messages (title, status) — all use hardcoded G_HI/G_DIM (not theme gradients)
+    ↓
+stream() — headlines + ntfy messages use config.ACTIVE_THEME gradients
+    ↓
+On exit: no persistence
+```
+
+---
+
+## Implementation Notes
+
+### Initialization Guarantee
+`config.ACTIVE_THEME` is guaranteed to be non-None before `stream()` is called because:
+1. `pick_color_theme()` always sets it (either interactively or via fallback)
+2. It's called before any rendering happens
+3. Default fallback ensures non-TTY environments don't crash
+
+### Module Independence
+`themes.py` is a pure data module with no imports of `config` or `render`. This prevents circular dependencies and allows it to be imported by multiple consumers without side effects.
+
+### Color Code Finalization
+All three gradient sequences (green, orange, purple main + complementary) are now finalized with specific ANSI codes. No TBD placeholders remain.
+
+### Theme ID Naming
+IDs are `"green"`, `"orange"`, `"purple"` — matching the menu labels exactly for clarity.
+
+### Terminal Resize Handling
+The `pick_color_theme()` function mirrors `pick_font_face()`, which does not handle terminal resizing during the picker display. If the terminal is resized while the picker menu is shown, the menu redraw may be incomplete; pressing any key (arrow, j/k, q) continues normally. This is acceptable because:
+1. The picker completes quickly (< 5 seconds typical interaction)
+2. Once a theme is selected, the menu closes and rendering begins
+3. The streaming phase (`stream()`) is resilient to terminal resizing and auto-reflows to new dimensions
+
+No special resize handling is needed for the color picker beyond what exists for the font picker.
+
+### Testing Strategy
+1. **Unit tests** (`tests/test_themes.py`):
+   - Verify Theme class construction
+   - Test THEME_REGISTRY lookup (valid and invalid IDs)
+   - Confirm gradient lists have correct length (12)
+
+2. **Integration tests** (`tests/test_render.py`):
+   - Mock `config.ACTIVE_THEME` to each theme
+   - Verify `lr_gradient()` uses correct colors
+   - Verify fallback works when `ACTIVE_THEME` is None
+
+3. **Existing tests:**
+   - Render tests that check gradient output will need to mock `config.ACTIVE_THEME`
+   - Use pytest fixtures to set theme per test case
+
+---
+
+## Files Changed
+- `engine/themes.py` (new)
+- `engine/config.py` (add `ACTIVE_THEME`, `set_active_theme()`)
+- `engine/render.py` (replace GRAD_COLS/MSG_GRAD_COLS references with config lookups)
+- `engine/app.py` (add `pick_color_theme()`, call in main)
+- `tests/test_themes.py` (new unit tests)
+- `tests/test_render.py` (update mocking strategy)
+
+## Acceptance Criteria
+1. ✓ Color picker displays 3 theme options at startup
+2. ✓ Selection applies to all headline and message gradients
+3. ✓ Boot UI (title, status) uses hardcoded green (not theme)
+4. ✓ Scrolling headlines and ntfy messages use theme gradients
+5. ✓ No persistence between runs
+6. ✓ Non-TTY environments default to green without error
+7. ✓ Architecture supports future random/animation modes
+8. ✓ All gradient color codes finalized with no TBD values

engine/app.py

@@ -2,23 +2,33 @@
 Application orchestrator — boot sequence, signal handling, main loop wiring.
 """
 
-import sys
-import os
-import time
-import signal
 import atexit
+import os
+import signal
+import sys
 import termios
+import time
 import tty
 
-from engine import config, render
+from engine import config, render, themes
-from engine.terminal import (
-    RST, G_HI, G_MID, G_DIM, W_DIM, W_GHOST, CLR, CURSOR_OFF, CURSOR_ON, tw,
-    slow_print, boot_ln,
-)
 from engine.fetch import fetch_all, fetch_poetry, load_cache, save_cache
-from engine.ntfy import NtfyPoller
 from engine.mic import MicMonitor
+from engine.ntfy import NtfyPoller
 from engine.scroll import stream
+from engine.terminal import (
+    CLR,
+    CURSOR_OFF,
+    CURSOR_ON,
+    G_DIM,
+    G_HI,
+    G_MID,
+    RST,
+    W_DIM,
+    W_GHOST,
+    boot_ln,
+    slow_print,
+    tw,
+)
 
 TITLE = [
     "  ███╗   ███╗ █████╗ ██╗███╗   ██╗██╗     ██╗███╗   ██╗███████╗",
@@ -29,6 +39,7 @@ TITLE = [
     "  ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝",
 ]
 
+
 def _read_picker_key():
     ch = sys.stdin.read(1)
     if ch == "\x03":
@@ -53,6 +64,31 @@ def _read_picker_key():
         return "enter"
     return None
 
+
+def _draw_color_picker(themes_list, selected):
+    """Draw the color theme picker menu.
+
+    Args:
+        themes_list: List of (theme_id, Theme) tuples from THEME_REGISTRY.items()
+        selected: Index of currently selected theme (0-2)
+    """
+    print(CLR, end="")
+    print()
+
+    print(
+        f"  {G_HI}▼ COLOR THEME{RST} {W_GHOST}─ ↑/↓ or j/k to move, Enter/q to select{RST}"
+    )
+    print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}\n")
+
+    for i, (theme_id, theme) in enumerate(themes_list):
+        prefix = "  ▶ " if i == selected else "    "
+        color = G_HI if i == selected else ""
+        reset = "" if i == selected else W_GHOST
+        print(f"{prefix}{color}{theme.name}{reset}")
+
+    print()
+
+
 def _normalize_preview_rows(rows):
     """Trim shared left padding and trailing spaces for stable on-screen previews."""
     non_empty = [r for r in rows if r.strip()]
@@ -99,7 +135,9 @@ def _draw_font_picker(faces, selected):
         active = pos == selected
         pointer = "▶" if active else " "
         color = G_HI if active else W_DIM
-        print(f"  {color}{pointer} {face['name']}{RST}{W_GHOST} · {face['file_name']}{RST}")
+        print(
+            f"  {color}{pointer} {face['name']}{RST}{W_GHOST} · {face['file_name']}{RST}"
+        )
 
     if top > 0:
         print(f"  {W_GHOST}… {top} above{RST}")
@@ -116,6 +154,51 @@ def _draw_font_picker(faces, selected):
         shown = row[:max_preview_w]
         print(f"    {shown}")
 
+
+def pick_color_theme():
+    """Interactive color theme picker. Defaults to 'green' if not TTY.
+
+    Displays a menu of available themes and lets user select with arrow keys.
+    Non-interactive environments (piped stdin, CI) silently default to green.
+    """
+    # Non-interactive fallback
+    if not sys.stdin.isatty():
+        config.set_active_theme("green")
+        return
+
+    # Interactive picker
+    themes_list = list(themes.THEME_REGISTRY.items())
+    selected = 0
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        while True:
+            _draw_color_picker(themes_list, selected)
+            key = _read_picker_key()
+            if key == "up":
+                selected = max(0, selected - 1)
+            elif key == "down":
+                selected = min(len(themes_list) - 1, selected + 1)
+            elif key == "enter":
+                break
+            elif key == "interrupt":
+                raise KeyboardInterrupt
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+    selected_theme_id = themes_list[selected][0]
+    config.set_active_theme(selected_theme_id)
+
+    theme_name = themes_list[selected][1].name
+    print(f"  {G_DIM}> using {theme_name}{RST}")
+    time.sleep(0.8)
+    print(CLR, end="")
+    print(CURSOR_OFF, end="")
+    print()
+
+
 def pick_font_face():
     """Interactive startup picker for selecting a face from repo OTF files."""
     if not config.FONT_PICKER:
@@ -225,7 +308,9 @@ def pick_font_face():
         font_index=selected_font["font_index"],
     )
     render.clear_font_cache()
-    print(f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}")
+    print(
+        f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}"
+    )
     time.sleep(0.8)
     print(CLR, end="")
     print(CURSOR_OFF, end="")
@@ -245,6 +330,7 @@ def main():
     w = tw()
     print(CLR, end="")
     print(CURSOR_OFF, end="")
+    pick_color_theme()
     pick_font_face()
     w = tw()
     print()
@@ -255,32 +341,48 @@ def main():
         time.sleep(0.07)
 
     print()
-    _subtitle = "literary consciousness stream" if config.MODE == 'poetry' else "digital consciousness stream"
+    _subtitle = {
+        "poetry": "literary consciousness stream",
+        "code": "source consciousness stream",
+    }.get(config.MODE, "digital consciousness stream")
     print(f"  {W_DIM}v0.1 · {_subtitle}{RST}")
     print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
     print()
     time.sleep(0.4)
 
-    cached = load_cache() if '--refresh' not in sys.argv else None
+    cached = load_cache() if "--refresh" not in sys.argv else None
     if cached:
         items = cached
         boot_ln("Cache", f"LOADED [{len(items)} SIGNALS]", True)
-    elif config.MODE == 'poetry':
+    elif config.MODE == "poetry":
         slow_print("  > INITIALIZING LITERARY CORPUS...\n")
         time.sleep(0.2)
         print()
         items, linked, failed = fetch_poetry()
         print()
-        print(f"  {G_DIM}>{RST} {G_MID}{linked} TEXTS LOADED{RST} {W_GHOST}· {failed} DARK{RST}")
+        print(
+            f"  {G_DIM}>{RST} {G_MID}{linked} TEXTS LOADED{RST} {W_GHOST}· {failed} DARK{RST}"
+        )
         print(f"  {G_DIM}>{RST} {G_MID}{len(items)} STANZAS ACQUIRED{RST}")
         save_cache(items)
+    elif config.MODE == "code":
+        from engine.fetch_code import fetch_code
+
+        slow_print("  > INITIALIZING SOURCE ARRAY...\n")
+        time.sleep(0.2)
+        print()
+        items, line_count, _ = fetch_code()
+        print()
+        print(f"  {G_DIM}>{RST} {G_MID}{line_count} LINES ACQUIRED{RST}")
     else:
         slow_print("  > INITIALIZING FEED ARRAY...\n")
         time.sleep(0.2)
         print()
         items, linked, failed = fetch_all()
         print()
-        print(f"  {G_DIM}>{RST} {G_MID}{linked} SOURCES LINKED{RST} {W_GHOST}· {failed} DARK{RST}")
+        print(
+            f"  {G_DIM}>{RST} {G_MID}{linked} SOURCES LINKED{RST} {W_GHOST}· {failed} DARK{RST}"
+        )
         print(f"  {G_DIM}>{RST} {G_MID}{len(items)} SIGNALS ACQUIRED{RST}")
         save_cache(items)
 
@@ -292,7 +394,13 @@ def main():
     mic = MicMonitor(threshold_db=config.MIC_THRESHOLD_DB)
     mic_ok = mic.start()
     if mic.available:
-        boot_ln("Microphone", "ACTIVE" if mic_ok else "OFFLINE · check System Settings → Privacy → Microphone", bool(mic_ok))
+        boot_ln(
+            "Microphone",
+            "ACTIVE"
+            if mic_ok
+            else "OFFLINE · check System Settings → Privacy → Microphone",
+            bool(mic_ok),
+        )
 
     ntfy = NtfyPoller(
         config.NTFY_TOPIC,

engine/config.py

@@ -3,8 +3,8 @@ Configuration constants, CLI flags, and glyph tables.
 """
 
 import sys
-
 from pathlib import Path
+
 _REPO_ROOT = Path(__file__).resolve().parent.parent
 _FONT_EXTENSIONS = {".otf", ".ttf", ".ttc"}
 
@@ -51,40 +51,48 @@ def _list_font_files(font_dir):
 def list_repo_font_files():
     """Public helper for discovering repository font files."""
     return _list_font_files(FONT_DIR)
+
+
 # ─── RUNTIME ──────────────────────────────────────────────
 HEADLINE_LIMIT = 1000
 FEED_TIMEOUT = 10
-MIC_THRESHOLD_DB = 50   # dB above which glitches intensify
+MIC_THRESHOLD_DB = 50  # dB above which glitches intensify
-MODE = 'poetry' if '--poetry' in sys.argv or '-p' in sys.argv else 'news'
+MODE = (
-FIREHOSE = '--firehose' in sys.argv
+    "poetry"
+    if "--poetry" in sys.argv or "-p" in sys.argv
+    else "code"
+    if "--code" in sys.argv
+    else "news"
+)
+FIREHOSE = "--firehose" in sys.argv
 
 # ─── NTFY MESSAGE QUEUE ──────────────────────────────────
 NTFY_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline/json"
 NTFY_RECONNECT_DELAY = 5  # seconds before reconnecting after a dropped stream
-MESSAGE_DISPLAY_SECS = 30 # how long a message holds the screen
+MESSAGE_DISPLAY_SECS = 30  # how long a message holds the screen
 
 # ─── FONT RENDERING ──────────────────────────────────────
-FONT_DIR = _resolve_font_path(_arg_value('--font-dir') or "fonts")
+FONT_DIR = _resolve_font_path(_arg_value("--font-dir") or "fonts")
-_FONT_FILE_ARG = _arg_value('--font-file')
+_FONT_FILE_ARG = _arg_value("--font-file")
 _FONT_FILES = _list_font_files(FONT_DIR)
 FONT_PATH = (
     _resolve_font_path(_FONT_FILE_ARG)
     if _FONT_FILE_ARG
     else (_FONT_FILES[0] if _FONT_FILES else "")
 )
-FONT_INDEX = max(0, _arg_int('--font-index', 0))
+FONT_INDEX = max(0, _arg_int("--font-index", 0))
-FONT_PICKER = '--no-font-picker' not in sys.argv
+FONT_PICKER = "--no-font-picker" not in sys.argv
 FONT_SZ = 60
-RENDER_H = 8              # terminal rows per rendered text line
+RENDER_H = 8  # terminal rows per rendered text line
 
 # ─── FONT RENDERING (ADVANCED) ────────────────────────────
-SSAA = 4                  # super-sampling factor: render at SSAA× then downsample
+SSAA = 4  # super-sampling factor: render at SSAA× then downsample
 
 # ─── SCROLL / FRAME ──────────────────────────────────────
-SCROLL_DUR = 5.625        # seconds per headline (2/3 original speed)
+SCROLL_DUR = 5.625  # seconds per headline (2/3 original speed)
-FRAME_DT = 0.05           # 50ms base frame rate (20 FPS)
+FRAME_DT = 0.05  # 50ms base frame rate (20 FPS)
-FIREHOSE_H = 12           # firehose zone height (terminal rows)
+FIREHOSE_H = 12  # firehose zone height (terminal rows)
-GRAD_SPEED = 0.08         # gradient traversal speed (cycles/sec, ~12s full sweep)
+GRAD_SPEED = 0.08  # gradient traversal speed (cycles/sec, ~12s full sweep)
 
 # ─── GLYPHS ───────────────────────────────────────────────
 GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
@@ -98,3 +106,26 @@ def set_font_selection(font_path=None, font_index=None):
         FONT_PATH = _resolve_font_path(font_path)
     if font_index is not None:
         FONT_INDEX = max(0, int(font_index))
+
+
+# ─── THEME MANAGEMENT ─────────────────────────────────────────
+ACTIVE_THEME = None
+
+
+def set_active_theme(theme_id: str = "green"):
+    """Set the active theme by ID.
+
+    Args:
+        theme_id: Theme identifier ("green", "orange", or "purple")
+                  Defaults to "green"
+
+    Raises:
+        KeyError: If theme_id is not in the theme registry
+
+    Side Effects:
+        Sets the ACTIVE_THEME global variable
+    """
+    global ACTIVE_THEME
+    from engine import themes
+
+    ACTIVE_THEME = themes.get_theme(theme_id)

engine/effects.py

@@ -7,8 +7,8 @@ import random
 from datetime import datetime
 
 from engine import config
-from engine.terminal import RST, DIM, G_LO, G_DIM, W_GHOST, C_DIM
 from engine.sources import FEEDS, POETRY_SOURCES
+from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST, W_GHOST
 
 
 def noise(w):
@@ -34,23 +34,23 @@ def fade_line(s, fade):
     if fade >= 1.0:
         return s
     if fade <= 0.0:
-        return ''
+        return ""
     result = []
     i = 0
     while i < len(s):
-        if s[i] == '\033' and i + 1 < len(s) and s[i + 1] == '[':
+        if s[i] == "\033" and i + 1 < len(s) and s[i + 1] == "[":
             j = i + 2
             while j < len(s) and not s[j].isalpha():
                 j += 1
-            result.append(s[i:j + 1])
+            result.append(s[i : j + 1])
             i = j + 1
-        elif s[i] == ' ':
+        elif s[i] == " ":
-            result.append(' ')
+            result.append(" ")
             i += 1
         else:
-            result.append(s[i] if random.random() < fade else ' ')
+            result.append(s[i] if random.random() < fade else " ")
             i += 1
-    return ''.join(result)
+    return "".join(result)
 
 
 def vis_trunc(s, w):
@@ -61,17 +61,17 @@ def vis_trunc(s, w):
     while i < len(s):
         if vw >= w:
             break
-        if s[i] == '\033' and i + 1 < len(s) and s[i + 1] == '[':
+        if s[i] == "\033" and i + 1 < len(s) and s[i + 1] == "[":
             j = i + 2
             while j < len(s) and not s[j].isalpha():
                 j += 1
-            result.append(s[i:j + 1])
+            result.append(s[i : j + 1])
             i = j + 1
         else:
             result.append(s[i])
             vw += 1
             i += 1
-    return ''.join(result)
+    return "".join(result)
 
 
 def next_headline(pool, items, seen):
@@ -94,7 +94,7 @@ def firehose_line(items, w):
     if r < 0.35:
         # Raw headline text
         title, src, ts = random.choice(items)
-        text = title[:w - 1]
+        text = title[: w - 1]
         color = random.choice([G_LO, G_DIM, W_GHOST, C_DIM])
         return f"{color}{text}{RST}"
     elif r < 0.55:
@@ -103,12 +103,13 @@ def firehose_line(items, w):
         return "".join(
             f"{random.choice([G_LO, G_DIM, C_DIM, W_GHOST])}"
             f"{random.choice(config.GLITCH + config.KATA)}{RST}"
-            if random.random() < d else " "
+            if random.random() < d
+            else " "
             for _ in range(w)
         )
     elif r < 0.78:
         # Status / program output
-        sources = FEEDS if config.MODE == 'news' else POETRY_SOURCES
+        sources = FEEDS if config.MODE == "news" else POETRY_SOURCES
         src = random.choice(list(sources.keys()))
         msgs = [
             f"  SIGNAL :: {src} :: {datetime.now().strftime('%H:%M:%S.%f')[:-3]}",
@@ -118,16 +119,16 @@ def firehose_line(items, w):
             f"  {''.join(random.choice(config.KATA) for _ in range(3))} STRM "
             f"{random.randint(0, 255):02X}:{random.randint(0, 255):02X}",
         ]
-        text = random.choice(msgs)[:w - 1]
+        text = random.choice(msgs)[: w - 1]
         color = random.choice([G_LO, G_DIM, W_GHOST])
         return f"{color}{text}{RST}"
     else:
         # Headline fragment with glitch prefix
         title, _, _ = random.choice(items)
         start = random.randint(0, max(0, len(title) - 20))
-        frag = title[start:start + random.randint(10, 35)]
+        frag = title[start : start + random.randint(10, 35)]
         pad = random.randint(0, max(0, w - len(frag) - 8))
-        gp = ''.join(random.choice(config.GLITCH) for _ in range(random.randint(1, 3)))
+        gp = "".join(random.choice(config.GLITCH) for _ in range(random.randint(1, 3)))
-        text = (' ' * pad + gp + ' ' + frag)[:w - 1]
+        text = (" " * pad + gp + " " + frag)[: w - 1]
         color = random.choice([G_LO, C_DIM, W_GHOST])
         return f"{color}{text}{RST}"

engine/fetch.py

@@ -3,19 +3,20 @@ RSS feed fetching, Project Gutenberg parsing, and headline caching.
 Depends on: config, sources, filter, terminal.
 """
 
-import re
 import json
 import pathlib
+import re
 import urllib.request
 from datetime import datetime
 
 import feedparser
 
 from engine import config
+from engine.filter import skip, strip_tags
 from engine.sources import FEEDS, POETRY_SOURCES
-from engine.filter import strip_tags, skip
 from engine.terminal import boot_ln
 
+
 # ─── SINGLE FEED ──────────────────────────────────────────
 def fetch_feed(url):
     try:
@@ -63,26 +64,31 @@ def _fetch_gutenberg(url, label):
     try:
         req = urllib.request.Request(url, headers={"User-Agent": "mainline/0.1"})
         resp = urllib.request.urlopen(req, timeout=15)
-        text = resp.read().decode('utf-8', errors='replace').replace('\r\n', '\n').replace('\r', '\n')
+        text = (
+            resp.read()
+            .decode("utf-8", errors="replace")
+            .replace("\r\n", "\n")
+            .replace("\r", "\n")
+        )
         # Strip PG boilerplate
-        m = re.search(r'\*\*\*\s*START OF[^\n]*\n', text)
+        m = re.search(r"\*\*\*\s*START OF[^\n]*\n", text)
         if m:
-            text = text[m.end():]
+            text = text[m.end() :]
-        m = re.search(r'\*\*\*\s*END OF', text)
+        m = re.search(r"\*\*\*\s*END OF", text)
         if m:
-            text = text[:m.start()]
+            text = text[: m.start()]
         # Split on blank lines into stanzas/passages
-        blocks = re.split(r'\n{2,}', text.strip())
+        blocks = re.split(r"\n{2,}", text.strip())
         items = []
         for blk in blocks:
-            blk = ' '.join(blk.split())   # flatten to one line
+            blk = " ".join(blk.split())  # flatten to one line
             if len(blk) < 20 or len(blk) > 280:
                 continue
-            if blk.isupper():             # skip all-caps headers
+            if blk.isupper():  # skip all-caps headers
                 continue
-            if re.match(r'^[IVXLCDM]+\.?\s*$', blk):  # roman numerals
+            if re.match(r"^[IVXLCDM]+\.?\s*$", blk):  # roman numerals
                 continue
-            items.append((blk, label, ''))
+            items.append((blk, label, ""))
         return items
     except Exception:
         return []

engine/fetch_code.py

@@ -0,0 +1,67 @@
+"""
+Source code feed — reads engine/*.py and emits non-blank, non-comment lines
+as scroll items. Used by --code mode.
+Depends on: nothing (stdlib only).
+"""
+
+import ast
+from pathlib import Path
+
+_ENGINE_DIR = Path(__file__).resolve().parent
+
+
+def _scope_map(source: str) -> dict[int, str]:
+    """Return {line_number: scope_label} for every line in source.
+
+    Nodes are sorted by range size descending so inner scopes overwrite
+    outer ones, guaranteeing the narrowest enclosing scope wins.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+
+    nodes = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            end = getattr(node, "end_lineno", node.lineno)
+            span = end - node.lineno
+            nodes.append((span, node))
+
+    # Largest range first → inner scopes overwrite on second pass
+    nodes.sort(key=lambda x: x[0], reverse=True)
+
+    scope = {}
+    for _, node in nodes:
+        end = getattr(node, "end_lineno", node.lineno)
+        if isinstance(node, ast.ClassDef):
+            label = node.name
+        else:
+            label = f"{node.name}()"
+        for ln in range(node.lineno, end + 1):
+            scope[ln] = label
+
+    return scope
+
+
+def fetch_code():
+    """Read engine/*.py and return (items, line_count, 0).
+
+    Each item is (text, src, ts) where:
+      text  = the code line (rstripped, indentation preserved)
+      src   = enclosing function/class name, e.g. 'stream()' or '<module>'
+      ts    = dotted module path, e.g. 'engine.scroll'
+    """
+    items = []
+    for path in sorted(_ENGINE_DIR.glob("*.py")):
+        module = f"engine.{path.stem}"
+        source = path.read_text(encoding="utf-8")
+        scope = _scope_map(source)
+        for lineno, raw in enumerate(source.splitlines(), start=1):
+            stripped = raw.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            label = scope.get(lineno, "<module>")
+            items.append((raw.rstrip(), label, module))
+
+    return items, len(items), 0

engine/filter.py

@@ -29,29 +29,29 @@ def strip_tags(html):
 
 # ─── CONTENT FILTER ───────────────────────────────────────
 _SKIP_RE = re.compile(
-    r'\b(?:'
+    r"\b(?:"
     # ── sports ──
-    r'football|soccer|basketball|baseball|softball|tennis|golf|cricket|rugby|'
+    r"football|soccer|basketball|baseball|softball|tennis|golf|cricket|rugby|"
-    r'hockey|lacrosse|volleyball|badminton|'
+    r"hockey|lacrosse|volleyball|badminton|"
-    r'nba|nfl|nhl|mlb|mls|fifa|uefa|'
+    r"nba|nfl|nhl|mlb|mls|fifa|uefa|"
-    r'premier league|champions league|la liga|serie a|bundesliga|'
+    r"premier league|champions league|la liga|serie a|bundesliga|"
-    r'world cup|super bowl|world series|stanley cup|'
+    r"world cup|super bowl|world series|stanley cup|"
-    r'playoff|playoffs|touchdown|goalkeeper|striker|quarterback|'
+    r"playoff|playoffs|touchdown|goalkeeper|striker|quarterback|"
-    r'slam dunk|home run|grand slam|offside|halftime|'
+    r"slam dunk|home run|grand slam|offside|halftime|"
-    r'batting|wicket|innings|'
+    r"batting|wicket|innings|"
-    r'formula 1|nascar|motogp|'
+    r"formula 1|nascar|motogp|"
-    r'boxing|ufc|mma|'
+    r"boxing|ufc|mma|"
-    r'marathon|tour de france|'
+    r"marathon|tour de france|"
-    r'transfer window|draft pick|relegation|'
+    r"transfer window|draft pick|relegation|"
     # ── vapid / insipid ──
-    r'kardashian|jenner|reality tv|reality show|'
+    r"kardashian|jenner|reality tv|reality show|"
-    r'influencer|viral video|tiktok|instagram|'
+    r"influencer|viral video|tiktok|instagram|"
-    r'best dressed|worst dressed|red carpet|'
+    r"best dressed|worst dressed|red carpet|"
-    r'horoscope|zodiac|gossip|bikini|selfie|'
+    r"horoscope|zodiac|gossip|bikini|selfie|"
-    r'you won.t believe|what happened next|'
+    r"you won.t believe|what happened next|"
-    r'celebrity couple|celebrity feud|baby bump'
+    r"celebrity couple|celebrity feud|baby bump"
-    r')\b',
+    r")\b",
-    re.IGNORECASE
+    re.IGNORECASE,
 )
 
 

engine/mic.py

@@ -6,8 +6,9 @@ Gracefully degrades if sounddevice/numpy are unavailable.
 import atexit
 
 try:
-    import sounddevice as _sd
     import numpy as _np
+    import sounddevice as _sd
+
     _HAS_MIC = True
 except Exception:
     _HAS_MIC = False
@@ -40,12 +41,15 @@ class MicMonitor:
         """Start background mic stream. Returns True on success, False/None otherwise."""
         if not _HAS_MIC:
             return None
+
         def _cb(indata, frames, t, status):
-            rms = float(_np.sqrt(_np.mean(indata ** 2)))
+            rms = float(_np.sqrt(_np.mean(indata**2)))
             self._db = 20 * _np.log10(rms) if rms > 0 else -99.0
+
         try:
             self._stream = _sd.InputStream(
-                callback=_cb, channels=1, samplerate=44100, blocksize=2048)
+                callback=_cb, channels=1, samplerate=44100, blocksize=2048
+            )
             self._stream.start()
             atexit.register(self.stop)
             return True

engine/ntfy.py

@@ -13,10 +13,10 @@ Reusable by any visualizer:
 """
 
 import json
-import time
 import threading
+import time
 import urllib.request
-from urllib.parse import urlparse, parse_qs, urlencode, urlunparse
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
 
 class NtfyPoller:
@@ -26,7 +26,7 @@ class NtfyPoller:
         self.topic_url = topic_url
         self.reconnect_delay = reconnect_delay
         self.display_secs = display_secs
-        self._message = None   # (title, body, monotonic_timestamp) or None
+        self._message = None  # (title, body, monotonic_timestamp) or None
         self._lock = threading.Lock()
 
     def start(self):
@@ -55,7 +55,7 @@ class NtfyPoller:
         """Build the stream URL, substituting since= to avoid message replays on reconnect."""
         parsed = urlparse(self.topic_url)
         params = parse_qs(parsed.query, keep_blank_values=True)
-        params['since'] = [last_id if last_id else '20s']
+        params["since"] = [last_id if last_id else "20s"]
         new_query = urlencode({k: v[0] for k, v in params.items()})
         return urlunparse(parsed._replace(query=new_query))
 
@@ -65,7 +65,8 @@ class NtfyPoller:
             try:
                 url = self._build_url(last_id)
                 req = urllib.request.Request(
-                    url, headers={"User-Agent": "mainline/0.1"})
+                    url, headers={"User-Agent": "mainline/0.1"}
+                )
                 # timeout=90 keeps the socket alive through ntfy.sh keepalive heartbeats
                 resp = urllib.request.urlopen(req, timeout=90)
                 while True:
@@ -73,7 +74,7 @@ class NtfyPoller:
                     if not line:
                         break  # server closed connection — reconnect
                     try:
-                        data = json.loads(line.decode('utf-8', errors='replace'))
+                        data = json.loads(line.decode("utf-8", errors="replace"))
                     except json.JSONDecodeError:
                         continue
                     # Advance cursor on every event (message + keepalive) to

engine/render.py

@@ -4,49 +4,83 @@ Font loading, text rasterization, word-wrap, gradient coloring, headline block a
 Depends on: config, terminal, sources, translate.
 """
 
-import re
 import random
+import re
 from pathlib import Path
 
 from PIL import Image, ImageDraw, ImageFont
 
 from engine import config
+from engine.sources import NO_UPPER, SCRIPT_FONTS, SOURCE_LANGS
 from engine.terminal import RST
-from engine.sources import SCRIPT_FONTS, SOURCE_LANGS, NO_UPPER
 from engine.translate import detect_location_language, translate_headline
 
-# ─── GRADIENT ─────────────────────────────────────────────
-# Left → right: white-hot leading edge fades to near-black
-GRAD_COLS = [
-    "\033[1;38;5;231m",  # white
-    "\033[1;38;5;195m",  # pale cyan-white
-    "\033[38;5;123m",    # bright cyan
-    "\033[38;5;118m",    # bright lime
-    "\033[38;5;82m",     # lime
-    "\033[38;5;46m",     # bright green
-    "\033[38;5;40m",     # green
-    "\033[38;5;34m",     # medium green
-    "\033[38;5;28m",     # dark green
-    "\033[38;5;22m",     # deep green
-    "\033[2;38;5;22m",   # dim deep green
-    "\033[2;38;5;235m",  # near black
-]
 
-# Complementary sweep for queue messages (opposite hue family from ticker greens)
+# ─── GRADIENT ─────────────────────────────────────────────
-MSG_GRAD_COLS = [
+def _color_codes_to_ansi(color_codes):
-    "\033[1;38;5;231m",  # white
+    """Convert a list of 256-color codes to ANSI escape code strings.
-    "\033[1;38;5;225m",  # pale pink-white
+
-    "\033[38;5;219m",    # bright pink
+    Pattern: first 2 are bold, middle 8 are normal, last 2 are dim.
-    "\033[38;5;213m",    # hot pink
+
-    "\033[38;5;207m",    # magenta
+    Args:
-    "\033[38;5;201m",    # bright magenta
+        color_codes: List of 12 integers (256-color palette codes)
-    "\033[38;5;165m",    # orchid-red
+
-    "\033[38;5;161m",    # ruby-magenta
+    Returns:
-    "\033[38;5;125m",    # dark magenta
+        List of ANSI escape code strings
-    "\033[38;5;89m",     # deep maroon-magenta
+    """
-    "\033[2;38;5;89m",   # dim deep maroon-magenta
+    if not color_codes or len(color_codes) != 12:
-    "\033[2;38;5;235m",  # near black
+        # Fallback to default green if invalid
-]
+        return _default_green_gradient()
+
+    result = []
+    for i, code in enumerate(color_codes):
+        if i < 2:
+            # Bold for first 2 (bright leading edge)
+            result.append(f"\033[1;38;5;{code}m")
+        elif i < 10:
+            # Normal for middle 8
+            result.append(f"\033[38;5;{code}m")
+        else:
+            # Dim for last 2 (dark trailing edge)
+            result.append(f"\033[2;38;5;{code}m")
+    return result
+
+
+def _default_green_gradient():
+    """Return the default 12-color green gradient for fallback when no theme is active."""
+    return [
+        "\033[1;38;5;231m",  # white
+        "\033[1;38;5;195m",  # pale cyan-white
+        "\033[38;5;123m",  # bright cyan
+        "\033[38;5;118m",  # bright lime
+        "\033[38;5;82m",  # lime
+        "\033[38;5;46m",  # bright green
+        "\033[38;5;40m",  # green
+        "\033[38;5;34m",  # medium green
+        "\033[38;5;28m",  # dark green
+        "\033[38;5;22m",  # deep green
+        "\033[2;38;5;22m",  # dim deep green
+        "\033[2;38;5;235m",  # near black
+    ]
+
+
+def _default_magenta_gradient():
+    """Return the default 12-color magenta gradient for fallback when no theme is active."""
+    return [
+        "\033[1;38;5;231m",  # white
+        "\033[1;38;5;225m",  # pale pink-white
+        "\033[38;5;219m",  # bright pink
+        "\033[38;5;213m",  # hot pink
+        "\033[38;5;207m",  # magenta
+        "\033[38;5;201m",  # bright magenta
+        "\033[38;5;165m",  # orchid-red
+        "\033[38;5;161m",  # ruby-magenta
+        "\033[38;5;125m",  # dark magenta
+        "\033[38;5;89m",  # deep maroon-magenta
+        "\033[2;38;5;89m",  # dim deep maroon-magenta
+        "\033[2;38;5;235m",  # near black
+    ]
+
 
 # ─── FONT LOADING ─────────────────────────────────────────
 _FONT_OBJ = None
@@ -62,13 +96,14 @@ def font():
             f"No primary font selected. Add .otf/.ttf/.ttc files to {config.FONT_DIR}."
         )
     key = (config.FONT_PATH, config.FONT_INDEX, config.FONT_SZ)
-    if _FONT_OBJ is None or _FONT_OBJ_KEY != key:
+    if _FONT_OBJ is None or key != _FONT_OBJ_KEY:
         _FONT_OBJ = ImageFont.truetype(
             config.FONT_PATH, config.FONT_SZ, index=config.FONT_INDEX
         )
         _FONT_OBJ_KEY = key
     return _FONT_OBJ
 
+
 def clear_font_cache():
     """Reset cached font objects after changing primary font selection."""
     global _FONT_OBJ, _FONT_OBJ_KEY
@@ -123,7 +158,7 @@ def render_line(text, fnt=None):
     pad = 4
     img_w = bbox[2] - bbox[0] + pad * 2
     img_h = bbox[3] - bbox[1] + pad * 2
-    img = Image.new('L', (img_w, img_h), 0)
+    img = Image.new("L", (img_w, img_h), 0)
     draw = ImageDraw.Draw(img)
     draw.text((-bbox[0] + pad, -bbox[1] + pad), text, fill=255, font=fnt)
     pix_h = config.RENDER_H * 2
@@ -188,9 +223,15 @@ def big_wrap(text, max_w, fnt=None):
     return out
 
 
-def lr_gradient(rows, offset=0.0, grad_cols=None):
+def lr_gradient(rows, offset=0.0, cols=None):
     """Color each non-space block character with a shifting left-to-right gradient."""
-    cols = grad_cols or GRAD_COLS
+    if cols is None:
+        from engine import config
+
+        if config.ACTIVE_THEME:
+            cols = _color_codes_to_ansi(config.ACTIVE_THEME.main_gradient)
+        else:
+            cols = _default_green_gradient()
     n = len(cols)
     max_x = max((len(r.rstrip()) for r in rows if r.strip()), default=1)
     out = []
@@ -200,8 +241,8 @@ def lr_gradient(rows, offset=0.0, grad_cols=None):
             continue
         buf = []
         for x, ch in enumerate(row):
-            if ch == ' ':
+            if ch == " ":
-                buf.append(' ')
+                buf.append(" ")
             else:
                 shifted = (x / max(max_x - 1, 1) + offset) % 1.0
                 idx = min(round(shifted * (n - 1)), n - 1)
@@ -212,13 +253,40 @@ def lr_gradient(rows, offset=0.0, grad_cols=None):
 
 def lr_gradient_opposite(rows, offset=0.0):
     """Complementary (opposite wheel) gradient used for queue message panels."""
-    return lr_gradient(rows, offset, MSG_GRAD_COLS)
+    return lr_gradient(rows, offset, _default_magenta_gradient())
+
+
+def msg_gradient(rows, offset):
+    """Apply message (ntfy) gradient using theme complementary colors.
+
+    Returns colored rows using ACTIVE_THEME.message_gradient if available,
+    falling back to default magenta if no theme is set.
+
+    Args:
+        rows: List of text strings to colorize
+        offset: Gradient offset (0.0-1.0) for animation
+
+    Returns:
+        List of rows with ANSI color codes applied
+    """
+    from engine import config
+
+    cols = (
+        _color_codes_to_ansi(config.ACTIVE_THEME.message_gradient)
+        if config.ACTIVE_THEME
+        else _default_magenta_gradient()
+    )
+    return lr_gradient(rows, offset, cols)
 
 
 # ─── HEADLINE BLOCK ASSEMBLY ─────────────────────────────
 def make_block(title, src, ts, w):
     """Render a headline into a content block with color."""
-    target_lang = (SOURCE_LANGS.get(src) or detect_location_language(title)) if config.MODE == 'news' else None
+    target_lang = (
+        (SOURCE_LANGS.get(src) or detect_location_language(title))
+        if config.MODE == "news"
+        else None
+    )
     lang_font = font_for_lang(target_lang)
     if target_lang:
         title = translate_headline(title, target_lang)
@@ -227,28 +295,36 @@ def make_block(title, src, ts, w):
         title_up = re.sub(r"\s+", " ", title)
     else:
         title_up = re.sub(r"\s+", " ", title.upper())
-    for old, new in [("\u2019","'"), ("\u2018","'"), ("\u201c",'"'),
+    for old, new in [
-                     ("\u201d",'"'), ("\u2013","-"), ("\u2014","-")]:
+        ("\u2019", "'"),
+        ("\u2018", "'"),
+        ("\u201c", '"'),
+        ("\u201d", '"'),
+        ("\u2013", "-"),
+        ("\u2014", "-"),
+    ]:
         title_up = title_up.replace(old, new)
     big_rows = big_wrap(title_up, w - 4, lang_font)
-    hc = random.choice([
+    hc = random.choice(
-        "\033[38;5;46m",    # matrix green
+        [
-        "\033[38;5;34m",    # dark green
+            "\033[38;5;46m",  # matrix green
-        "\033[38;5;82m",    # lime
+            "\033[38;5;34m",  # dark green
-        "\033[38;5;48m",    # sea green
+            "\033[38;5;82m",  # lime
-        "\033[38;5;37m",    # teal
+            "\033[38;5;48m",  # sea green
-        "\033[38;5;44m",    # cyan
+            "\033[38;5;37m",  # teal
-        "\033[38;5;87m",    # sky
+            "\033[38;5;44m",  # cyan
-        "\033[38;5;117m",   # ice blue
+            "\033[38;5;87m",  # sky
-        "\033[38;5;250m",   # cool white
+            "\033[38;5;117m",  # ice blue
-        "\033[38;5;156m",   # pale green
+            "\033[38;5;250m",  # cool white
-        "\033[38;5;120m",   # mint
+            "\033[38;5;156m",  # pale green
-        "\033[38;5;80m",    # dark cyan
+            "\033[38;5;120m",  # mint
-        "\033[38;5;108m",   # grey-green
+            "\033[38;5;80m",  # dark cyan
-        "\033[38;5;115m",   # sage
+            "\033[38;5;108m",  # grey-green
-        "\033[1;38;5;46m",  # bold green
+            "\033[38;5;115m",  # sage
-        "\033[1;38;5;250m", # bold white
+            "\033[1;38;5;46m",  # bold green
-    ])
+            "\033[1;38;5;250m",  # bold white
+        ]
+    )
     content = ["  " + r for r in big_rows]
     content.append("")
     meta = f"\u2591 {src} \u00b7 {ts}"

engine/scroll.py

@@ -3,16 +3,23 @@ Render engine — ticker content, scroll motion, message panel, and firehose ove
 Depends on: config, terminal, render, effects, ntfy, mic.
 """
 
+import random
 import re
 import sys
 import time
-import random
 from datetime import datetime
 
 from engine import config
-from engine.terminal import RST, W_COOL, CLR, tw, th
+from engine.effects import (
-from engine.render import big_wrap, lr_gradient, lr_gradient_opposite, make_block
+    fade_line,
-from engine.effects import noise, glitch_bar, fade_line, vis_trunc, next_headline, firehose_line
+    firehose_line,
+    glitch_bar,
+    next_headline,
+    noise,
+    vis_trunc,
+)
+from engine.render import big_wrap, lr_gradient, make_block, msg_gradient
+from engine.terminal import CLR, RST, W_COOL, th, tw
 
 
 def stream(items, ntfy_poller, mic_monitor):
@@ -28,8 +35,8 @@ def stream(items, ntfy_poller, mic_monitor):
 
     w, h = tw(), th()
     fh = config.FIREHOSE_H if config.FIREHOSE else 0
-    ticker_view_h = h - fh         # reserve fixed firehose strip at bottom
+    ticker_view_h = h - fh  # reserve fixed firehose strip at bottom
-    GAP = 3            # blank rows between headlines
+    GAP = 3  # blank rows between headlines
     scroll_step_interval = config.SCROLL_DUR / (ticker_view_h + 15) * 2
 
     # Taxonomy:
@@ -39,8 +46,10 @@ def stream(items, ntfy_poller, mic_monitor):
     # - firehose: fixed carriage-return style strip pinned at bottom
     # Active ticker blocks: (content_rows, color, canvas_y, meta_idx)
     active = []
-    scroll_cam = 0     # viewport top in virtual canvas coords
+    scroll_cam = 0  # viewport top in virtual canvas coords
-    ticker_next_y = ticker_view_h  # canvas-y where next block starts (off-screen bottom)
+    ticker_next_y = (
+        ticker_view_h  # canvas-y where next block starts (off-screen bottom)
+    )
     noise_cache = {}
     scroll_motion_accum = 0.0
 
@@ -50,9 +59,9 @@ def stream(items, ntfy_poller, mic_monitor):
         return noise_cache[cy]
 
     # Message color: bright cyan/white — distinct from headline greens
-    MSG_META  = "\033[38;5;245m"     # cool grey
+    MSG_META = "\033[38;5;245m"  # cool grey
-    MSG_BORDER = "\033[2;38;5;37m"   # dim teal
+    MSG_BORDER = "\033[2;38;5;37m"  # dim teal
-    _msg_cache = (None, None)        # (cache_key, rendered_rows)
+    _msg_cache = (None, None)  # (cache_key, rendered_rows)
 
     while queued < config.HEADLINE_LIMIT or active:
         t0 = time.monotonic()
@@ -77,7 +86,9 @@ def stream(items, ntfy_poller, mic_monitor):
                 _msg_cache = (cache_key, msg_rows)
             else:
                 msg_rows = _msg_cache[1]
-            msg_rows = lr_gradient_opposite(msg_rows, (time.monotonic() * config.GRAD_SPEED) % 1.0)
+            msg_rows = msg_gradient(
+                msg_rows, (time.monotonic() * config.GRAD_SPEED) % 1.0
+            )
             # Layout: rendered text + meta + border
             elapsed_s = int(time.monotonic() - m_ts)
             remaining = max(0, config.MESSAGE_DISPLAY_SECS - elapsed_s)
@@ -87,19 +98,29 @@ def stream(items, ntfy_poller, mic_monitor):
             row_idx = 0
             for mr in msg_rows:
                 ln = vis_trunc(mr, w)
-                msg_overlay.append(f"\033[{panel_top + row_idx + 1};1H  {ln}{RST}\033[K")
+                msg_overlay.append(
+                    f"\033[{panel_top + row_idx + 1};1H  {ln}{RST}\033[K"
+                )
                 row_idx += 1
             # Meta line: title (if distinct) + source + countdown
             meta_parts = []
             if m_title and m_title != m_body:
                 meta_parts.append(m_title)
             meta_parts.append(f"ntfy \u00b7 {ts_str} \u00b7 {remaining}s")
-            meta = "  " + " \u00b7 ".join(meta_parts) if len(meta_parts) > 1 else "  " + meta_parts[0]
+            meta = (
-            msg_overlay.append(f"\033[{panel_top + row_idx + 1};1H{MSG_META}{meta}{RST}\033[K")
+                "  " + " \u00b7 ".join(meta_parts)
+                if len(meta_parts) > 1
+                else "  " + meta_parts[0]
+            )
+            msg_overlay.append(
+                f"\033[{panel_top + row_idx + 1};1H{MSG_META}{meta}{RST}\033[K"
+            )
             row_idx += 1
             # Border — constant boundary under message panel
             bar = "\u2500" * (w - 4)
-            msg_overlay.append(f"\033[{panel_top + row_idx + 1};1H  {MSG_BORDER}{bar}{RST}\033[K")
+            msg_overlay.append(
+                f"\033[{panel_top + row_idx + 1};1H  {MSG_BORDER}{bar}{RST}\033[K"
+            )
 
         # Ticker draws above the fixed firehose strip; message is a centered overlay.
         ticker_h = ticker_view_h - msg_h
@@ -111,7 +132,10 @@ def stream(items, ntfy_poller, mic_monitor):
             scroll_cam += 1
 
             # Enqueue new headlines when room at the bottom
-            while ticker_next_y < scroll_cam + ticker_view_h + 10 and queued < config.HEADLINE_LIMIT:
+            while (
+                ticker_next_y < scroll_cam + ticker_view_h + 10
+                and queued < config.HEADLINE_LIMIT
+            ):
                 t, src, ts = next_headline(pool, items, seen)
                 ticker_content, hc, midx = make_block(t, src, ts, w)
                 active.append((ticker_content, hc, ticker_next_y, midx))
@@ -119,8 +143,9 @@ def stream(items, ntfy_poller, mic_monitor):
                 queued += 1
 
             # Prune off-screen blocks and stale noise
-            active = [(c, hc, by, mi) for c, hc, by, mi in active
+            active = [
-                      if by + len(c) > scroll_cam]
+                (c, hc, by, mi) for c, hc, by, mi in active if by + len(c) > scroll_cam
+            ]
             for k in list(noise_cache):
                 if k < scroll_cam:
                     del noise_cache[k]

engine/sources.py

@@ -47,69 +47,69 @@ FEEDS = {
 # ─── POETRY / LITERATURE ─────────────────────────────────
 # Public domain via Project Gutenberg
 POETRY_SOURCES = {
-    "Whitman":    "https://www.gutenberg.org/cache/epub/1322/pg1322.txt",
+    "Whitman": "https://www.gutenberg.org/cache/epub/1322/pg1322.txt",
-    "Dickinson":  "https://www.gutenberg.org/cache/epub/12242/pg12242.txt",
+    "Dickinson": "https://www.gutenberg.org/cache/epub/12242/pg12242.txt",
     "Whitman II": "https://www.gutenberg.org/cache/epub/8388/pg8388.txt",
-    "Rilke":      "https://www.gutenberg.org/cache/epub/38594/pg38594.txt",
+    "Rilke": "https://www.gutenberg.org/cache/epub/38594/pg38594.txt",
-    "Pound":      "https://www.gutenberg.org/cache/epub/41162/pg41162.txt",
+    "Pound": "https://www.gutenberg.org/cache/epub/41162/pg41162.txt",
-    "Pound II":   "https://www.gutenberg.org/cache/epub/51992/pg51992.txt",
+    "Pound II": "https://www.gutenberg.org/cache/epub/51992/pg51992.txt",
-    "Eliot":      "https://www.gutenberg.org/cache/epub/1567/pg1567.txt",
+    "Eliot": "https://www.gutenberg.org/cache/epub/1567/pg1567.txt",
-    "Yeats":      "https://www.gutenberg.org/cache/epub/38877/pg38877.txt",
+    "Yeats": "https://www.gutenberg.org/cache/epub/38877/pg38877.txt",
-    "Masters":    "https://www.gutenberg.org/cache/epub/1280/pg1280.txt",
+    "Masters": "https://www.gutenberg.org/cache/epub/1280/pg1280.txt",
     "Baudelaire": "https://www.gutenberg.org/cache/epub/36098/pg36098.txt",
-    "Crane":      "https://www.gutenberg.org/cache/epub/40786/pg40786.txt",
+    "Crane": "https://www.gutenberg.org/cache/epub/40786/pg40786.txt",
-    "Poe":        "https://www.gutenberg.org/cache/epub/10031/pg10031.txt",
+    "Poe": "https://www.gutenberg.org/cache/epub/10031/pg10031.txt",
 }
 
 # ─── SOURCE → LANGUAGE MAPPING ───────────────────────────
 # Headlines from these outlets render in their cultural home language
 SOURCE_LANGS = {
-    "Der Spiegel":  "de",
+    "Der Spiegel": "de",
-    "DW":           "de",
+    "DW": "de",
-    "France24":     "fr",
+    "France24": "fr",
-    "Japan Times":  "ja",
+    "Japan Times": "ja",
-    "The Hindu":    "hi",
+    "The Hindu": "hi",
-    "SCMP":         "zh-cn",
+    "SCMP": "zh-cn",
-    "Al Jazeera":   "ar",
+    "Al Jazeera": "ar",
 }
 
 # ─── LOCATION → LANGUAGE ─────────────────────────────────
 LOCATION_LANGS = {
-    r'\b(?:china|chinese|beijing|shanghai|hong kong|xi jinping)\b': 'zh-cn',
+    r"\b(?:china|chinese|beijing|shanghai|hong kong|xi jinping)\b": "zh-cn",
-    r'\b(?:japan|japanese|tokyo|osaka|kishida)\b': 'ja',
+    r"\b(?:japan|japanese|tokyo|osaka|kishida)\b": "ja",
-    r'\b(?:korea|korean|seoul|pyongyang)\b': 'ko',
+    r"\b(?:korea|korean|seoul|pyongyang)\b": "ko",
-    r'\b(?:russia|russian|moscow|kremlin|putin)\b': 'ru',
+    r"\b(?:russia|russian|moscow|kremlin|putin)\b": "ru",
-    r'\b(?:saudi|dubai|qatar|egypt|cairo|arabic)\b': 'ar',
+    r"\b(?:saudi|dubai|qatar|egypt|cairo|arabic)\b": "ar",
-    r'\b(?:india|indian|delhi|mumbai|modi)\b': 'hi',
+    r"\b(?:india|indian|delhi|mumbai|modi)\b": "hi",
-    r'\b(?:germany|german|berlin|munich|scholz)\b': 'de',
+    r"\b(?:germany|german|berlin|munich|scholz)\b": "de",
-    r'\b(?:france|french|paris|lyon|macron)\b': 'fr',
+    r"\b(?:france|french|paris|lyon|macron)\b": "fr",
-    r'\b(?:spain|spanish|madrid)\b': 'es',
+    r"\b(?:spain|spanish|madrid)\b": "es",
-    r'\b(?:italy|italian|rome|milan|meloni)\b': 'it',
+    r"\b(?:italy|italian|rome|milan|meloni)\b": "it",
-    r'\b(?:portugal|portuguese|lisbon)\b': 'pt',
+    r"\b(?:portugal|portuguese|lisbon)\b": "pt",
-    r'\b(?:brazil|brazilian|são paulo|lula)\b': 'pt',
+    r"\b(?:brazil|brazilian|são paulo|lula)\b": "pt",
-    r'\b(?:greece|greek|athens)\b': 'el',
+    r"\b(?:greece|greek|athens)\b": "el",
-    r'\b(?:turkey|turkish|istanbul|ankara|erdogan)\b': 'tr',
+    r"\b(?:turkey|turkish|istanbul|ankara|erdogan)\b": "tr",
-    r'\b(?:iran|iranian|tehran)\b': 'fa',
+    r"\b(?:iran|iranian|tehran)\b": "fa",
-    r'\b(?:thailand|thai|bangkok)\b': 'th',
+    r"\b(?:thailand|thai|bangkok)\b": "th",
-    r'\b(?:vietnam|vietnamese|hanoi)\b': 'vi',
+    r"\b(?:vietnam|vietnamese|hanoi)\b": "vi",
-    r'\b(?:ukraine|ukrainian|kyiv|kiev|zelensky)\b': 'uk',
+    r"\b(?:ukraine|ukrainian|kyiv|kiev|zelensky)\b": "uk",
-    r'\b(?:israel|israeli|jerusalem|tel aviv|netanyahu)\b': 'he',
+    r"\b(?:israel|israeli|jerusalem|tel aviv|netanyahu)\b": "he",
 }
 
 # ─── NON-LATIN SCRIPT FONTS (macOS) ──────────────────────
 SCRIPT_FONTS = {
-    'zh-cn': '/System/Library/Fonts/STHeiti Medium.ttc',
+    "zh-cn": "/System/Library/Fonts/STHeiti Medium.ttc",
-    'ja':    '/System/Library/Fonts/ヒラギノ角ゴシック W9.ttc',
+    "ja": "/System/Library/Fonts/ヒラギノ角ゴシック W9.ttc",
-    'ko':    '/System/Library/Fonts/AppleSDGothicNeo.ttc',
+    "ko": "/System/Library/Fonts/AppleSDGothicNeo.ttc",
-    'ru':    '/System/Library/Fonts/Supplemental/Arial.ttf',
+    "ru": "/System/Library/Fonts/Supplemental/Arial.ttf",
-    'uk':    '/System/Library/Fonts/Supplemental/Arial.ttf',
+    "uk": "/System/Library/Fonts/Supplemental/Arial.ttf",
-    'el':    '/System/Library/Fonts/Supplemental/Arial.ttf',
+    "el": "/System/Library/Fonts/Supplemental/Arial.ttf",
-    'he':    '/System/Library/Fonts/Supplemental/Arial.ttf',
+    "he": "/System/Library/Fonts/Supplemental/Arial.ttf",
-    'ar':    '/System/Library/Fonts/GeezaPro.ttc',
+    "ar": "/System/Library/Fonts/GeezaPro.ttc",
-    'fa':    '/System/Library/Fonts/GeezaPro.ttc',
+    "fa": "/System/Library/Fonts/GeezaPro.ttc",
-    'hi':    '/System/Library/Fonts/Kohinoor.ttc',
+    "hi": "/System/Library/Fonts/Kohinoor.ttc",
-    'th':    '/System/Library/Fonts/ThonburiUI.ttc',
+    "th": "/System/Library/Fonts/ThonburiUI.ttc",
 }
 
 # Scripts that have no uppercase
-NO_UPPER = {'zh-cn', 'ja', 'ko', 'ar', 'fa', 'hi', 'th', 'he'}
+NO_UPPER = {"zh-cn", "ja", "ko", "ar", "fa", "hi", "th", "he"}

engine/terminal.py

@@ -4,8 +4,8 @@ No internal dependencies.
 """
 
 import os
-import sys
 import random
+import sys
 import time
 
 # ─── ANSI ─────────────────────────────────────────────────
@@ -49,7 +49,7 @@ def type_out(text, color=G_HI):
     while i < len(text):
         if random.random() < 0.3:
             b = random.randint(2, 5)
-            sys.stdout.write(f"{color}{text[i:i+b]}{RST}")
+            sys.stdout.write(f"{color}{text[i : i + b]}{RST}")
             i += b
         else:
             sys.stdout.write(f"{color}{text[i]}{RST}")

engine/themes.py

@@ -0,0 +1,60 @@
+"""
+Theme definitions with color gradients for terminal rendering.
+
+This module is data-only and does not import config or render
+to prevent circular dependencies.
+"""
+
+
+class Theme:
+    """Represents a color theme with two gradients."""
+
+    def __init__(self, name, main_gradient, message_gradient):
+        """Initialize a theme with name and color gradients.
+
+        Args:
+            name: Theme identifier string
+            main_gradient: List of 12 ANSI 256-color codes for main gradient
+            message_gradient: List of 12 ANSI 256-color codes for message gradient
+        """
+        self.name = name
+        self.main_gradient = main_gradient
+        self.message_gradient = message_gradient
+
+
+# ─── GRADIENT DEFINITIONS ─────────────────────────────────────────────────
+# Each gradient is 12 ANSI 256-color codes in sequence
+# Format: [light...] → [medium...] → [dark...] → [black]
+
+_GREEN_MAIN = [231, 195, 123, 118, 82, 46, 40, 34, 28, 22, 22, 235]
+_GREEN_MSG = [231, 225, 219, 213, 207, 201, 165, 161, 125, 89, 89, 235]
+
+_ORANGE_MAIN = [231, 215, 209, 208, 202, 166, 130, 94, 58, 94, 94, 235]
+_ORANGE_MSG = [231, 195, 33, 27, 21, 21, 21, 18, 18, 18, 18, 235]
+
+_PURPLE_MAIN = [231, 225, 177, 171, 165, 135, 129, 93, 57, 57, 57, 235]
+_PURPLE_MSG = [231, 226, 226, 220, 220, 184, 184, 178, 178, 172, 172, 235]
+
+
+# ─── THEME REGISTRY ───────────────────────────────────────────────────────
+
+THEME_REGISTRY = {
+    "green": Theme("green", _GREEN_MAIN, _GREEN_MSG),
+    "orange": Theme("orange", _ORANGE_MAIN, _ORANGE_MSG),
+    "purple": Theme("purple", _PURPLE_MAIN, _PURPLE_MSG),
+}
+
+
+def get_theme(theme_id):
+    """Retrieve a theme by ID.
+
+    Args:
+        theme_id: Theme identifier string
+
+    Returns:
+        Theme object matching the ID
+
+    Raises:
+        KeyError: If theme_id is not in registry
+    """
+    return THEME_REGISTRY[theme_id]

engine/translate.py

@@ -3,10 +3,10 @@ Google Translate wrapper and location→language detection.
 Depends on: sources (for LOCATION_LANGS).
 """
 
-import re
 import json
-import urllib.request
+import re
 import urllib.parse
+import urllib.request
 
 from engine.sources import LOCATION_LANGS
 
@@ -29,8 +29,10 @@ def translate_headline(title, target_lang):
         return _TRANSLATE_CACHE[key]
     try:
         q = urllib.parse.quote(title)
-        url = ("https://translate.googleapis.com/translate_a/single"
+        url = (
-               f"?client=gtx&sl=en&tl={target_lang}&dt=t&q={q}")
+            "https://translate.googleapis.com/translate_a/single"
+            f"?client=gtx&sl=en&tl={target_lang}&dt=t&q={q}"
+        )
         req = urllib.request.Request(url, headers={"User-Agent": "mainline/0.1"})
         resp = urllib.request.urlopen(req, timeout=5)
         data = json.loads(resp.read())

hk.pkl

@@ -0,0 +1,27 @@
+amends "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.38.0/hk@1.38.0#/Builtins.pkl"
+
+hooks {
+    ["pre-commit"] {
+        fix = true
+        stash = "git"
+        steps {
+            ["ruff-format"] = (Builtins.ruff_format) {
+                prefix = "uv run"
+            }
+            ["ruff"] = (Builtins.ruff) {
+                prefix = "uv run"
+                check = "ruff check engine/ tests/"
+                fix = "ruff check --fix --unsafe-fixes engine/ tests/"
+            }
+        }
+    }
+    ["pre-push"] {
+        steps {
+            ["ruff"] = (Builtins.ruff) {
+                prefix = "uv run"
+                check = "ruff check engine/ tests/"
+            }
+        }
+    }
+}

mainline.py

@@ -5,40 +5,7 @@ Digital news consciousness stream.
 Matrix aesthetic · THX-1138 hue.
 """
 
-import subprocess, sys, pathlib
+from engine.app import main
-
-# ─── BOOTSTRAP VENV ───────────────────────────────────────
-_VENV = pathlib.Path(__file__).resolve().parent / ".mainline_venv"
-_MARKER = _VENV / ".installed_v3"
-
-def _ensure_venv():
-    """Create a local venv and install deps if needed."""
-    if _MARKER.exists():
-        return
-    import venv
-    print("\033[2;38;5;34m  > first run — creating environment...\033[0m")
-    venv.create(str(_VENV), with_pip=True, clear=True)
-    pip = str(_VENV / "bin" / "pip")
-    subprocess.check_call(
-        [pip, "install", "feedparser", "Pillow", "-q"],
-        stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
-    )
-    _MARKER.touch()
-
-_ensure_venv()
-
-# Install sounddevice on first run after v3
-_MARKER_SD = _VENV / ".installed_sd"
-if not _MARKER_SD.exists():
-    _pip = str(_VENV / "bin" / "pip")
-    subprocess.check_call([_pip, "install", "sounddevice", "numpy", "-q"],
-                          stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-    _MARKER_SD.touch()
-
-sys.path.insert(0, str(next((_VENV / "lib").glob("python*/site-packages"))))
-
-# ─── DELEGATE TO ENGINE ───────────────────────────────────
-from engine.app import main  # noqa: E402
 
 if __name__ == "__main__":
     main()

mise.toml

@@ -0,0 +1,52 @@
+[tools]
+python = "3.12"
+hk = "latest"
+pkl = "latest"
+
+[tasks]
+# =====================
+# Development
+# =====================
+
+test = "uv run pytest"
+test-v = "uv run pytest -v"
+test-cov = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html"
+test-cov-open = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html && open htmlcov/index.html"
+
+lint = "uv run ruff check engine/ mainline.py"
+lint-fix = "uv run ruff check --fix engine/ mainline.py"
+format = "uv run ruff format engine/ mainline.py"
+
+# =====================
+# Runtime
+# =====================
+
+run = "uv run mainline.py"
+run-poetry = "uv run mainline.py --poetry"
+run-firehose = "uv run mainline.py --firehose"
+
+# =====================
+# Environment
+# =====================
+
+sync = "uv sync"
+sync-all = "uv sync --all-extras"
+install = "uv sync"
+install-dev = "uv sync --group dev"
+
+bootstrap = "uv sync && uv run mainline.py --help"
+
+clean = "rm -rf .venv htmlcov .coverage tests/.pytest_cache"
+
+# =====================
+# CI/CD
+# =====================
+
+ci = "uv sync --group dev && uv run pytest --cov=engine --cov-report=term-missing --cov-report=xml"
+ci-lint = "uv run ruff check engine/ mainline.py"
+
+# =====================
+# Git Hooks (via hk)
+# =====================
+
+pre-commit = "hk run pre-commit"

pyproject.toml

@@ -0,0 +1,88 @@
+[project]
+name = "mainline"
+version = "0.1.0"
+description = "Terminal news ticker with Matrix aesthetic"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Mainline", email = "mainline@example.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Terminals",
+]
+
+dependencies = [
+    "feedparser>=6.0.0",
+    "Pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+mic = [
+    "sounddevice>=0.4.0",
+    "numpy>=1.24.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.12.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+mainline = "engine.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.12.0",
+    "ruff>=0.1.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+    "-v",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["engine"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]
+ignore = ["E501", "SIM105", "N806", "B007", "SIM108"]

requirements-dev.txt

@@ -0,0 +1,4 @@
+pytest>=8.0.0
+pytest-cov>=4.1.0
+pytest-mock>=3.12.0
+ruff>=0.1.0

requirements.txt

@@ -0,0 +1,4 @@
+feedparser>=6.0.0
+Pillow>=10.0.0
+sounddevice>=0.4.0
+numpy>=1.24.0

tests/test_config.py

@@ -0,0 +1,216 @@
+"""
+Tests for engine.config module.
+"""
+
+import sys
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from engine import config
+
+
+class TestArgValue:
+    """Tests for _arg_value helper."""
+
+    def test_returns_value_when_flag_present(self):
+        """Returns the value following the flag."""
+        with patch.object(sys, "argv", ["prog", "--font-file", "test.otf"]):
+            result = config._arg_value("--font-file")
+            assert result == "test.otf"
+
+    def test_returns_none_when_flag_missing(self):
+        """Returns None when flag is not present."""
+        with patch.object(sys, "argv", ["prog"]):
+            result = config._arg_value("--font-file")
+            assert result is None
+
+    def test_returns_none_when_no_value(self):
+        """Returns None when flag is last."""
+        with patch.object(sys, "argv", ["prog", "--font-file"]):
+            result = config._arg_value("--font-file")
+            assert result is None
+
+
+class TestArgInt:
+    """Tests for _arg_int helper."""
+
+    def test_parses_valid_int(self):
+        """Parses valid integer."""
+        with patch.object(sys, "argv", ["prog", "--font-index", "5"]):
+            result = config._arg_int("--font-index", 0)
+            assert result == 5
+
+    def test_returns_default_on_invalid(self):
+        """Returns default on invalid input."""
+        with patch.object(sys, "argv", ["prog", "--font-index", "abc"]):
+            result = config._arg_int("--font-index", 0)
+            assert result == 0
+
+    def test_returns_default_when_missing(self):
+        """Returns default when flag missing."""
+        with patch.object(sys, "argv", ["prog"]):
+            result = config._arg_int("--font-index", 10)
+            assert result == 10
+
+
+class TestResolveFontPath:
+    """Tests for _resolve_font_path helper."""
+
+    def test_returns_absolute_paths(self):
+        """Absolute paths are returned as-is."""
+        result = config._resolve_font_path("/absolute/path.otf")
+        assert result == "/absolute/path.otf"
+
+    def test_resolves_relative_paths(self):
+        """Relative paths are resolved to repo root."""
+        result = config._resolve_font_path("fonts/test.otf")
+        assert str(config._REPO_ROOT) in result
+
+    def test_expands_user_home(self):
+        """Tilde paths are expanded."""
+        with patch("pathlib.Path.expanduser", return_value=Path("/home/user/fonts")):
+            result = config._resolve_font_path("~/fonts/test.otf")
+            assert isinstance(result, str)
+
+
+class TestListFontFiles:
+    """Tests for _list_font_files helper."""
+
+    def test_returns_empty_for_missing_dir(self):
+        """Returns empty list for missing directory."""
+        result = config._list_font_files("/nonexistent/directory")
+        assert result == []
+
+    def test_filters_by_extension(self):
+        """Only returns valid font extensions."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "valid.otf").touch()
+            Path(tmpdir, "valid.ttf").touch()
+            Path(tmpdir, "invalid.txt").touch()
+            Path(tmpdir, "image.png").touch()
+
+            result = config._list_font_files(tmpdir)
+            assert len(result) == 2
+            assert all(f.endswith((".otf", ".ttf")) for f in result)
+
+    def test_sorts_alphabetically(self):
+        """Results are sorted alphabetically."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            Path(tmpdir, "zfont.otf").touch()
+            Path(tmpdir, "afont.otf").touch()
+
+            result = config._list_font_files(tmpdir)
+            filenames = [Path(f).name for f in result]
+            assert filenames == ["afont.otf", "zfont.otf"]
+
+
+class TestDefaults:
+    """Tests for default configuration values."""
+
+    def test_headline_limit(self):
+        """HEADLINE_LIMIT has sensible default."""
+        assert config.HEADLINE_LIMIT > 0
+
+    def test_feed_timeout(self):
+        """FEED_TIMEOUT has sensible default."""
+        assert config.FEED_TIMEOUT > 0
+
+    def test_font_extensions(self):
+        """Font extensions are defined."""
+        assert ".otf" in config._FONT_EXTENSIONS
+        assert ".ttf" in config._FONT_EXTENSIONS
+        assert ".ttc" in config._FONT_EXTENSIONS
+
+
+class TestGlyphs:
+    """Tests for glyph constants."""
+
+    def test_glitch_glyphs_defined(self):
+        """GLITCH glyphs are defined."""
+        assert len(config.GLITCH) > 0
+
+    def test_kata_glyphs_defined(self):
+        """KATA glyphs are defined."""
+        assert len(config.KATA) > 0
+
+
+class TestSetFontSelection:
+    """Tests for set_font_selection function."""
+
+    def test_updates_font_path(self):
+        """Updates FONT_PATH globally."""
+        original = config.FONT_PATH
+        config.set_font_selection(font_path="/new/path.otf")
+        assert config.FONT_PATH == "/new/path.otf"
+        config.FONT_PATH = original
+
+    def test_updates_font_index(self):
+        """Updates FONT_INDEX globally."""
+        original = config.FONT_INDEX
+        config.set_font_selection(font_index=5)
+        assert config.FONT_INDEX == 5
+        config.FONT_INDEX = original
+
+    def test_handles_none_values(self):
+        """Handles None values gracefully."""
+        original_path = config.FONT_PATH
+        original_index = config.FONT_INDEX
+
+        config.set_font_selection(font_path=None, font_index=None)
+        assert original_path == config.FONT_PATH
+        assert original_index == config.FONT_INDEX
+
+
+class TestActiveTheme:
+    """Tests for ACTIVE_THEME global and set_active_theme function."""
+
+    def test_active_theme_initially_none(self):
+        """ACTIVE_THEME should be None at module start."""
+        # Reset to None to test initial state
+        original = config.ACTIVE_THEME
+        config.ACTIVE_THEME = None
+        try:
+            assert config.ACTIVE_THEME is None
+        finally:
+            config.ACTIVE_THEME = original
+
+    def test_set_active_theme_green(self):
+        """Setting green theme works correctly."""
+        config.set_active_theme("green")
+        assert config.ACTIVE_THEME is not None
+        assert config.ACTIVE_THEME.name == "green"
+        assert len(config.ACTIVE_THEME.main_gradient) == 12
+        assert len(config.ACTIVE_THEME.message_gradient) == 12
+
+    def test_set_active_theme_default(self):
+        """Default theme is green when not specified."""
+        config.set_active_theme()
+        assert config.ACTIVE_THEME is not None
+        assert config.ACTIVE_THEME.name == "green"
+
+    def test_set_active_theme_invalid(self):
+        """Invalid theme_id raises KeyError."""
+        with pytest.raises(KeyError):
+            config.set_active_theme("nonexistent")
+
+    def test_set_active_theme_all_themes(self):
+        """Verify orange and purple themes work."""
+        # Test orange
+        config.set_active_theme("orange")
+        assert config.ACTIVE_THEME.name == "orange"
+
+        # Test purple
+        config.set_active_theme("purple")
+        assert config.ACTIVE_THEME.name == "purple"
+
+    def test_set_active_theme_idempotent(self):
+        """Calling set_active_theme multiple times works."""
+        config.set_active_theme("green")
+        first_theme = config.ACTIVE_THEME
+        config.set_active_theme("green")
+        second_theme = config.ACTIVE_THEME
+        assert first_theme.name == second_theme.name
+        assert first_theme.name == "green"

tests/test_fetch_code.py

@@ -0,0 +1,35 @@
+import re
+
+from engine.fetch_code import fetch_code
+
+
+def test_return_shape():
+    items, line_count, ignored = fetch_code()
+    assert isinstance(items, list)
+    assert line_count == len(items)
+    assert ignored == 0
+
+
+def test_items_are_tuples():
+    items, _, _ = fetch_code()
+    assert items, "expected at least one code line"
+    for item in items:
+        assert isinstance(item, tuple) and len(item) == 3
+        text, src, ts = item
+        assert isinstance(text, str)
+        assert isinstance(src, str)
+        assert isinstance(ts, str)
+
+
+def test_blank_and_comment_lines_excluded():
+    items, _, _ = fetch_code()
+    for text, _, _ in items:
+        assert text.strip(), "blank line should have been filtered"
+        assert not text.strip().startswith("#"), "comment line should have been filtered"
+
+
+def test_module_path_format():
+    items, _, _ = fetch_code()
+    pattern = re.compile(r"^engine\.\w+$")
+    for _, _, ts in items:
+        assert pattern.match(ts), f"unexpected module path: {ts!r}"

tests/test_filter.py

@@ -0,0 +1,93 @@
+"""
+Tests for engine.filter module.
+"""
+
+from engine.filter import skip, strip_tags
+
+
+class TestStripTags:
+    """Tests for strip_tags function."""
+
+    def test_strips_simple_html(self):
+        """Basic HTML tags are removed."""
+        assert strip_tags("<p>Hello</p>") == "Hello"
+        assert strip_tags("<b>Bold</b>") == "Bold"
+        assert strip_tags("<em>Italic</em>") == "Italic"
+
+    def test_strips_nested_html(self):
+        """Nested HTML tags are handled."""
+        assert strip_tags("<div><p>Nested</p></div>") == "Nested"
+        assert strip_tags("<span><strong>Deep</strong></span>") == "Deep"
+
+    def test_strips_html_with_attributes(self):
+        """HTML with attributes is handled."""
+        assert strip_tags('<a href="http://example.com">Link</a>') == "Link"
+        assert strip_tags('<img src="test.jpg" alt="test">') == ""
+
+    def test_handles_empty_string(self):
+        """Empty string returns empty string."""
+        assert strip_tags("") == ""
+        assert strip_tags(None) == ""
+
+    def test_handles_plain_text(self):
+        """Plain text without tags passes through."""
+        assert strip_tags("Plain text") == "Plain text"
+
+    def test_unescapes_html_entities(self):
+        """HTML entities are decoded and tags are stripped."""
+        assert strip_tags("&nbsp;test") == "test"
+        assert strip_tags("Hello &amp; World") == "Hello & World"
+
+    def test_handles_malformed_html(self):
+        """Malformed HTML is handled gracefully."""
+        assert strip_tags("<p>Unclosed") == "Unclosed"
+        assert strip_tags("</p>No start") == "No start"
+
+
+class TestSkip:
+    """Tests for skip function - content filtering."""
+
+    def test_skips_sports_content(self):
+        """Sports-related headlines are skipped."""
+        assert skip("Football: Team wins championship") is True
+        assert skip("NBA Finals Game 7 results") is True
+        assert skip("Soccer match ends in draw") is True
+        assert skip("Premier League transfer news") is True
+        assert skip("Super Bowl halftime show") is True
+
+    def test_skips_vapid_content(self):
+        """Vapid/celebrity content is skipped."""
+        assert skip("Kim Kardashian's new look") is True
+        assert skip("Influencer goes viral") is True
+        assert skip("Red carpet best dressed") is True
+        assert skip("Celebrity couple splits") is True
+
+    def test_allows_real_news(self):
+        """Legitimate news headlines are allowed."""
+        assert skip("Scientists discover new planet") is False
+        assert skip("Economy grows by 3%") is False
+        assert skip("World leaders meet for summit") is False
+        assert skip("New technology breakthrough") is False
+
+    def test_case_insensitive(self):
+        """Filter is case insensitive."""
+        assert skip("FOOTBALL scores") is True
+        assert skip("Football SCORES") is True
+        assert skip("Kardashian") is True
+
+    def test_word_boundary_matching(self):
+        """Word boundary matching works correctly."""
+        assert skip("The football stadium") is True
+        assert skip("Footballer scores") is False
+        assert skip("Footballs on sale") is False
+
+
+class TestIntegration:
+    """Integration tests combining filter functions."""
+
+    def test_full_pipeline(self):
+        """Test strip_tags followed by skip."""
+        html = '<p><a href="#">Breaking: Football championship final</a></p>'
+        text = strip_tags(html)
+        assert text == "Breaking: Football championship final"
+        assert skip(text) is True

tests/test_mic.py

@@ -0,0 +1,83 @@
+"""
+Tests for engine.mic module.
+"""
+
+from unittest.mock import patch
+
+
+class TestMicMonitorImport:
+    """Tests for module import behavior."""
+
+    def test_mic_monitor_imports_without_error(self):
+        """MicMonitor can be imported even without sounddevice."""
+        from engine.mic import MicMonitor
+
+        assert MicMonitor is not None
+
+
+class TestMicMonitorInit:
+    """Tests for MicMonitor initialization."""
+
+    def test_init_sets_threshold(self):
+        """Threshold is set correctly."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=60)
+        assert monitor.threshold_db == 60
+
+    def test_init_defaults(self):
+        """Default values are set correctly."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert monitor.threshold_db == 50
+
+    def test_init_db_starts_at_negative(self):
+        """_db starts at negative value."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert monitor.db == -99.0
+
+
+class TestMicMonitorProperties:
+    """Tests for MicMonitor properties."""
+
+    def test_excess_returns_positive_when_above_threshold(self):
+        """excess returns positive value when above threshold."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=50)
+        with patch.object(monitor, "_db", 60.0):
+            assert monitor.excess == 10.0
+
+    def test_excess_returns_zero_when_below_threshold(self):
+        """excess returns zero when below threshold."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=50)
+        with patch.object(monitor, "_db", 40.0):
+            assert monitor.excess == 0.0
+
+
+class TestMicMonitorAvailable:
+    """Tests for MicMonitor.available property."""
+
+    def test_available_is_bool(self):
+        """available returns a boolean."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert isinstance(monitor.available, bool)
+
+
+class TestMicMonitorStop:
+    """Tests for MicMonitor.stop method."""
+
+    def test_stop_does_nothing_when_no_stream(self):
+        """stop() does nothing if no stream exists."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        monitor.stop()
+        assert monitor._stream is None

tests/test_ntfy.py

@@ -0,0 +1,70 @@
+"""
+Tests for engine.ntfy module.
+"""
+
+import time
+from unittest.mock import MagicMock, patch
+
+from engine.ntfy import NtfyPoller
+
+
+class TestNtfyPollerInit:
+    """Tests for NtfyPoller initialization."""
+
+    def test_init_sets_defaults(self):
+        """Default values are set correctly."""
+        poller = NtfyPoller("http://example.com/topic")
+        assert poller.topic_url == "http://example.com/topic"
+        assert poller.reconnect_delay == 5
+        assert poller.display_secs == 30
+
+    def test_init_custom_values(self):
+        """Custom values are set correctly."""
+        poller = NtfyPoller(
+            "http://example.com/topic", reconnect_delay=10, display_secs=60
+        )
+        assert poller.reconnect_delay == 10
+        assert poller.display_secs == 60
+
+
+class TestNtfyPollerStart:
+    """Tests for NtfyPoller.start method."""
+
+    @patch("engine.ntfy.threading.Thread")
+    def test_start_creates_daemon_thread(self, mock_thread):
+        """start() creates and starts a daemon thread."""
+        mock_thread_instance = MagicMock()
+        mock_thread.return_value = mock_thread_instance
+
+        poller = NtfyPoller("http://example.com/topic")
+        result = poller.start()
+
+        assert result is True
+        mock_thread.assert_called_once()
+        args, kwargs = mock_thread.call_args
+        assert kwargs.get("daemon") is True
+        mock_thread_instance.start.assert_called_once()
+
+
+class TestNtfyPollerGetActiveMessage:
+    """Tests for NtfyPoller.get_active_message method."""
+
+    def test_returns_none_when_no_message(self):
+        """Returns None when no message has been received."""
+        poller = NtfyPoller("http://example.com/topic")
+        result = poller.get_active_message()
+        assert result is None
+
+
+class TestNtfyPollerDismiss:
+    """Tests for NtfyPoller.dismiss method."""
+
+    def test_dismiss_clears_message(self):
+        """dismiss() clears the current message."""
+        poller = NtfyPoller("http://example.com/topic")
+
+        with patch.object(poller, "_lock"):
+            poller._message = ("Title", "Body", time.monotonic())
+            poller.dismiss()
+
+            assert poller._message is None

tests/test_render.py

@@ -0,0 +1,301 @@
+"""
+Tests for engine.render module.
+"""
+
+import pytest
+
+from engine import config, render
+
+
+class TestDefaultGradients:
+    """Tests for default gradient fallback functions."""
+
+    def test_default_green_gradient_length(self):
+        """_default_green_gradient returns 12 colors."""
+        gradient = render._default_green_gradient()
+        assert len(gradient) == 12
+
+    def test_default_green_gradient_is_list(self):
+        """_default_green_gradient returns a list."""
+        gradient = render._default_green_gradient()
+        assert isinstance(gradient, list)
+
+    def test_default_green_gradient_all_strings(self):
+        """_default_green_gradient returns list of ANSI code strings."""
+        gradient = render._default_green_gradient()
+        assert all(isinstance(code, str) for code in gradient)
+
+    def test_default_magenta_gradient_length(self):
+        """_default_magenta_gradient returns 12 colors."""
+        gradient = render._default_magenta_gradient()
+        assert len(gradient) == 12
+
+    def test_default_magenta_gradient_is_list(self):
+        """_default_magenta_gradient returns a list."""
+        gradient = render._default_magenta_gradient()
+        assert isinstance(gradient, list)
+
+    def test_default_magenta_gradient_all_strings(self):
+        """_default_magenta_gradient returns list of ANSI code strings."""
+        gradient = render._default_magenta_gradient()
+        assert all(isinstance(code, str) for code in gradient)
+
+
+class TestLrGradientUsesActiveTheme:
+    """Tests for lr_gradient using active theme."""
+
+    def test_lr_gradient_uses_active_theme_when_cols_none(self):
+        """lr_gradient uses ACTIVE_THEME.main_gradient when cols=None."""
+        # Save original state
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            # Set a theme
+            config.set_active_theme("green")
+
+            # Create simple test data
+            rows = ["text"]
+
+            # Call without cols parameter (cols=None)
+            result = render.lr_gradient(rows, offset=0.0)
+
+            # Should not raise and should return colored output
+            assert isinstance(result, list)
+            assert len(result) == 1
+            # Should have ANSI codes (no plain "text")
+            assert result[0] != "text"
+        finally:
+            # Restore original state
+            config.ACTIVE_THEME = original_theme
+
+    def test_lr_gradient_fallback_when_no_theme(self):
+        """lr_gradient uses fallback green when ACTIVE_THEME is None."""
+        # Save original state
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            # Clear the theme
+            config.ACTIVE_THEME = None
+
+            # Create simple test data
+            rows = ["text"]
+
+            # Call without cols parameter (should use fallback)
+            result = render.lr_gradient(rows, offset=0.0)
+
+            # Should not raise and should return colored output
+            assert isinstance(result, list)
+            assert len(result) == 1
+            # Should have ANSI codes (no plain "text")
+            assert result[0] != "text"
+        finally:
+            # Restore original state
+            config.ACTIVE_THEME = original_theme
+
+    def test_lr_gradient_explicit_cols_parameter_still_works(self):
+        """lr_gradient with explicit cols parameter overrides theme."""
+        # Custom gradient
+        custom_cols = ["\033[38;5;1m", "\033[38;5;2m"] * 6
+
+        rows = ["xy"]
+        result = render.lr_gradient(rows, offset=0.0, cols=custom_cols)
+
+        # Should use the provided cols
+        assert isinstance(result, list)
+        assert len(result) == 1
+
+    def test_lr_gradient_respects_cols_parameter_name(self):
+        """lr_gradient accepts cols as keyword argument."""
+        custom_cols = ["\033[38;5;1m", "\033[38;5;2m"] * 6
+
+        rows = ["xy"]
+        # Call with cols as keyword
+        result = render.lr_gradient(rows, offset=0.0, cols=custom_cols)
+
+        assert isinstance(result, list)
+
+
+class TestLrGradientBasicFunctionality:
+    """Tests to ensure lr_gradient basic functionality still works."""
+
+    def test_lr_gradient_colors_non_space_chars(self):
+        """lr_gradient colors non-space characters."""
+        rows = ["hello"]
+
+        # Set a theme for the test
+        original_theme = config.ACTIVE_THEME
+        try:
+            config.set_active_theme("green")
+            result = render.lr_gradient(rows, offset=0.0)
+
+            # Result should have ANSI codes
+            assert any("\033[" in r for r in result), "Expected ANSI codes in result"
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_lr_gradient_preserves_spaces(self):
+        """lr_gradient preserves spaces in output."""
+        rows = ["a b c"]
+
+        original_theme = config.ACTIVE_THEME
+        try:
+            config.set_active_theme("green")
+            result = render.lr_gradient(rows, offset=0.0)
+
+            # Spaces should be preserved (not colored)
+            assert " " in result[0]
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_lr_gradient_empty_rows(self):
+        """lr_gradient handles empty rows correctly."""
+        rows = [""]
+
+        original_theme = config.ACTIVE_THEME
+        try:
+            config.set_active_theme("green")
+            result = render.lr_gradient(rows, offset=0.0)
+
+            assert result == [""]
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_lr_gradient_multiple_rows(self):
+        """lr_gradient handles multiple rows."""
+        rows = ["row1", "row2", "row3"]
+
+        original_theme = config.ACTIVE_THEME
+        try:
+            config.set_active_theme("green")
+            result = render.lr_gradient(rows, offset=0.0)
+
+            assert len(result) == 3
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+
+class TestMsgGradient:
+    """Tests for msg_gradient function (message/ntfy overlay coloring)."""
+
+    def test_msg_gradient_uses_active_theme(self):
+        """msg_gradient uses ACTIVE_THEME.message_gradient when theme is set."""
+        # Save original state
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            # Set a theme
+            config.set_active_theme("green")
+
+            # Create simple test data
+            rows = ["MESSAGE"]
+
+            # Call msg_gradient
+            result = render.msg_gradient(rows, offset=0.0)
+
+            # Should return colored output using theme's message_gradient
+            assert isinstance(result, list)
+            assert len(result) == 1
+            # Should have ANSI codes from the message gradient
+            assert result[0] != "MESSAGE"
+            assert "\033[" in result[0]
+        finally:
+            # Restore original state
+            config.ACTIVE_THEME = original_theme
+
+    def test_msg_gradient_fallback_when_no_theme(self):
+        """msg_gradient uses fallback magenta when ACTIVE_THEME is None."""
+        # Save original state
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            # Clear the theme
+            config.ACTIVE_THEME = None
+
+            # Create simple test data
+            rows = ["MESSAGE"]
+
+            # Call msg_gradient
+            result = render.msg_gradient(rows, offset=0.0)
+
+            # Should return colored output using default magenta
+            assert isinstance(result, list)
+            assert len(result) == 1
+            # Should have ANSI codes
+            assert result[0] != "MESSAGE"
+            assert "\033[" in result[0]
+        finally:
+            # Restore original state
+            config.ACTIVE_THEME = original_theme
+
+    def test_msg_gradient_returns_colored_rows(self):
+        """msg_gradient returns properly colored rows with animation offset."""
+        # Save original state
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            # Set a theme
+            config.set_active_theme("orange")
+
+            rows = ["NTFY", "ALERT"]
+
+            # Call with offset
+            result = render.msg_gradient(rows, offset=0.5)
+
+            # Should return same number of rows
+            assert len(result) == 2
+            # Both should be colored
+            assert all("\033[" in r for r in result)
+            # Should not be the original text
+            assert result != rows
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_msg_gradient_different_themes_produce_different_results(self):
+        """msg_gradient produces different colors for different themes."""
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            rows = ["TEST"]
+
+            # Get result with green theme
+            config.set_active_theme("green")
+            result_green = render.msg_gradient(rows, offset=0.0)
+
+            # Get result with orange theme
+            config.set_active_theme("orange")
+            result_orange = render.msg_gradient(rows, offset=0.0)
+
+            # Results should be different (different message gradients)
+            assert result_green != result_orange
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_msg_gradient_preserves_spacing(self):
+        """msg_gradient preserves spaces in rows."""
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            config.set_active_theme("purple")
+            rows = ["M E S S A G E"]
+
+            result = render.msg_gradient(rows, offset=0.0)
+
+            # Spaces should be preserved
+            assert " " in result[0]
+        finally:
+            config.ACTIVE_THEME = original_theme
+
+    def test_msg_gradient_empty_rows(self):
+        """msg_gradient handles empty rows correctly."""
+        original_theme = config.ACTIVE_THEME
+
+        try:
+            config.set_active_theme("green")
+            rows = [""]
+
+            result = render.msg_gradient(rows, offset=0.0)
+
+            # Empty row should stay empty
+            assert result == [""]
+        finally:
+            config.ACTIVE_THEME = original_theme

tests/test_sources.py

@@ -0,0 +1,93 @@
+"""
+Tests for engine.sources module - data validation.
+"""
+
+from engine import sources
+
+
+class TestFeeds:
+    """Tests for FEEDS data."""
+
+    def test_feeds_is_dict(self):
+        """FEEDS is a dictionary."""
+        assert isinstance(sources.FEEDS, dict)
+
+    def test_feeds_has_entries(self):
+        """FEEDS has feed entries."""
+        assert len(sources.FEEDS) > 0
+
+    def test_feeds_have_valid_urls(self):
+        """All feeds have valid URL format."""
+        for name, url in sources.FEEDS.items():
+            assert name
+            assert url.startswith("http://") or url.startswith("https://")
+
+
+class TestPoetrySources:
+    """Tests for POETRY_SOURCES data."""
+
+    def test_poetry_is_dict(self):
+        """POETRY_SOURCES is a dictionary."""
+        assert isinstance(sources.POETRY_SOURCES, dict)
+
+    def test_poetry_has_entries(self):
+        """POETRY_SOURCES has entries."""
+        assert len(sources.POETRY_SOURCES) > 0
+
+    def test_poetry_have_gutenberg_urls(self):
+        """All poetry sources are from Gutenberg."""
+        for _name, url in sources.POETRY_SOURCES.items():
+            assert "gutenberg.org" in url
+
+
+class TestSourceLangs:
+    """Tests for SOURCE_LANGS mapping."""
+
+    def test_source_langs_is_dict(self):
+        """SOURCE_LANGS is a dictionary."""
+        assert isinstance(sources.SOURCE_LANGS, dict)
+
+    def test_source_langs_valid_language_codes(self):
+        """Language codes are valid ISO codes."""
+        valid_codes = {"de", "fr", "ja", "zh-cn", "ar", "hi"}
+        for code in sources.SOURCE_LANGS.values():
+            assert code in valid_codes
+
+
+class TestLocationLangs:
+    """Tests for LOCATION_LANGS mapping."""
+
+    def test_location_langs_is_dict(self):
+        """LOCATION_LANGS is a dictionary."""
+        assert isinstance(sources.LOCATION_LANGS, dict)
+
+    def test_location_langs_has_patterns(self):
+        """LOCATION_LANGS has regex patterns."""
+        assert len(sources.LOCATION_LANGS) > 0
+
+
+class TestScriptFonts:
+    """Tests for SCRIPT_FONTS mapping."""
+
+    def test_script_fonts_is_dict(self):
+        """SCRIPT_FONTS is a dictionary."""
+        assert isinstance(sources.SCRIPT_FONTS, dict)
+
+    def test_script_fonts_has_paths(self):
+        """All script fonts have paths."""
+        for _lang, path in sources.SCRIPT_FONTS.items():
+            assert path
+
+
+class TestNoUpper:
+    """Tests for NO_UPPER set."""
+
+    def test_no_upper_is_set(self):
+        """NO_UPPER is a set."""
+        assert isinstance(sources.NO_UPPER, set)
+
+    def test_no_upper_contains_scripts(self):
+        """NO_UPPER contains non-Latin scripts."""
+        assert "zh-cn" in sources.NO_UPPER
+        assert "ja" in sources.NO_UPPER
+        assert "ar" in sources.NO_UPPER

tests/test_terminal.py

@@ -0,0 +1,130 @@
+"""
+Tests for engine.terminal module.
+"""
+
+import io
+import sys
+from unittest.mock import patch
+
+from engine import terminal
+
+
+class TestTerminalDimensions:
+    """Tests for terminal width/height functions."""
+
+    def test_tw_returns_columns(self):
+        """tw() returns terminal width."""
+        with (
+            patch.object(sys.stdout, "isatty", return_value=True),
+            patch("os.get_terminal_size") as mock_size,
+        ):
+            mock_size.return_value = io.StringIO("columns=120")
+            mock_size.columns = 120
+            result = terminal.tw()
+            assert isinstance(result, int)
+
+    def test_th_returns_lines(self):
+        """th() returns terminal height."""
+        with (
+            patch.object(sys.stdout, "isatty", return_value=True),
+            patch("os.get_terminal_size") as mock_size,
+        ):
+            mock_size.return_value = io.StringIO("lines=30")
+            mock_size.lines = 30
+            result = terminal.th()
+            assert isinstance(result, int)
+
+    def test_tw_fallback_on_error(self):
+        """tw() falls back to 80 on error."""
+        with patch("os.get_terminal_size", side_effect=OSError):
+            result = terminal.tw()
+            assert result == 80
+
+    def test_th_fallback_on_error(self):
+        """th() falls back to 24 on error."""
+        with patch("os.get_terminal_size", side_effect=OSError):
+            result = terminal.th()
+            assert result == 24
+
+
+class TestANSICodes:
+    """Tests for ANSI escape code constants."""
+
+    def test_ansi_constants_exist(self):
+        """All ANSI constants are defined."""
+        assert terminal.RST == "\033[0m"
+        assert terminal.BOLD == "\033[1m"
+        assert terminal.DIM == "\033[2m"
+
+    def test_green_shades_defined(self):
+        """Green gradient colors are defined."""
+        assert terminal.G_HI == "\033[38;5;46m"
+        assert terminal.G_MID == "\033[38;5;34m"
+        assert terminal.G_LO == "\033[38;5;22m"
+
+    def test_white_shades_defined(self):
+        """White/gray tones are defined."""
+        assert terminal.W_COOL == "\033[38;5;250m"
+        assert terminal.W_DIM == "\033[2;38;5;245m"
+
+    def test_cursor_controls_defined(self):
+        """Cursor control codes are defined."""
+        assert "?" in terminal.CURSOR_OFF
+        assert "?" in terminal.CURSOR_ON
+
+
+class TestTypeOut:
+    """Tests for type_out function."""
+
+    @patch("sys.stdout", new_callable=io.StringIO)
+    @patch("time.sleep")
+    def test_type_out_writes_text(self, mock_sleep, mock_stdout):
+        """type_out writes text to stdout."""
+        with patch("random.random", return_value=0.5):
+            terminal.type_out("Hi", color=terminal.G_HI)
+            output = mock_stdout.getvalue()
+            assert len(output) > 0
+
+    @patch("time.sleep")
+    def test_type_out_uses_color(self, mock_sleep):
+        """type_out applies color codes."""
+        with (
+            patch("sys.stdout", new_callable=io.StringIO),
+            patch("random.random", return_value=0.5),
+        ):
+            terminal.type_out("Test", color=terminal.G_HI)
+
+
+class TestSlowPrint:
+    """Tests for slow_print function."""
+
+    @patch("sys.stdout", new_callable=io.StringIO)
+    @patch("time.sleep")
+    def test_slow_print_writes_text(self, mock_sleep, mock_stdout):
+        """slow_print writes text to stdout."""
+        terminal.slow_print("Hi", color=terminal.G_DIM, delay=0)
+        output = mock_stdout.getvalue()
+        assert len(output) > 0
+
+
+class TestBootLn:
+    """Tests for boot_ln function."""
+
+    @patch("sys.stdout", new_callable=io.StringIO)
+    @patch("time.sleep")
+    def test_boot_ln_writes_label_and_status(self, mock_sleep, mock_stdout):
+        """boot_ln shows label and status."""
+        with patch("random.uniform", return_value=0):
+            terminal.boot_ln("Loading", "OK", ok=True)
+            output = mock_stdout.getvalue()
+            assert "Loading" in output
+            assert "OK" in output
+
+    @patch("sys.stdout", new_callable=io.StringIO)
+    @patch("time.sleep")
+    def test_boot_ln_error_status(self, mock_sleep, mock_stdout):
+        """boot_ln shows red for error status."""
+        with patch("random.uniform", return_value=0):
+            terminal.boot_ln("Loading", "FAIL", ok=False)
+            output = mock_stdout.getvalue()
+            assert "FAIL" in output

tests/test_themes.py

@@ -0,0 +1,169 @@
+"""
+Tests for engine.themes module.
+"""
+
+import pytest
+
+from engine import themes
+
+
+class TestThemeConstruction:
+    """Tests for Theme class initialization."""
+
+    def test_theme_construction(self):
+        """Theme stores name and gradients correctly."""
+        main_grad = ["color1", "color2", "color3"]
+        msg_grad = ["msg1", "msg2", "msg3"]
+        theme = themes.Theme("test_theme", main_grad, msg_grad)
+
+        assert theme.name == "test_theme"
+        assert theme.main_gradient == main_grad
+        assert theme.message_gradient == msg_grad
+
+
+class TestGradientLength:
+    """Tests for gradient length validation."""
+
+    def test_gradient_length_green(self):
+        """Green theme has exactly 12 colors in each gradient."""
+        green = themes.THEME_REGISTRY["green"]
+        assert len(green.main_gradient) == 12
+        assert len(green.message_gradient) == 12
+
+    def test_gradient_length_orange(self):
+        """Orange theme has exactly 12 colors in each gradient."""
+        orange = themes.THEME_REGISTRY["orange"]
+        assert len(orange.main_gradient) == 12
+        assert len(orange.message_gradient) == 12
+
+    def test_gradient_length_purple(self):
+        """Purple theme has exactly 12 colors in each gradient."""
+        purple = themes.THEME_REGISTRY["purple"]
+        assert len(purple.main_gradient) == 12
+        assert len(purple.message_gradient) == 12
+
+
+class TestThemeRegistry:
+    """Tests for THEME_REGISTRY dictionary."""
+
+    def test_theme_registry_has_three_themes(self):
+        """Registry contains exactly three themes: green, orange, purple."""
+        assert len(themes.THEME_REGISTRY) == 3
+        assert set(themes.THEME_REGISTRY.keys()) == {"green", "orange", "purple"}
+
+    def test_registry_values_are_themes(self):
+        """All registry values are Theme instances."""
+        for theme_id, theme in themes.THEME_REGISTRY.items():
+            assert isinstance(theme, themes.Theme)
+            assert theme.name == theme_id
+
+
+class TestGetTheme:
+    """Tests for get_theme function."""
+
+    def test_get_theme_valid_green(self):
+        """get_theme('green') returns correct green Theme."""
+        green = themes.get_theme("green")
+        assert isinstance(green, themes.Theme)
+        assert green.name == "green"
+
+    def test_get_theme_valid_orange(self):
+        """get_theme('orange') returns correct orange Theme."""
+        orange = themes.get_theme("orange")
+        assert isinstance(orange, themes.Theme)
+        assert orange.name == "orange"
+
+    def test_get_theme_valid_purple(self):
+        """get_theme('purple') returns correct purple Theme."""
+        purple = themes.get_theme("purple")
+        assert isinstance(purple, themes.Theme)
+        assert purple.name == "purple"
+
+    def test_get_theme_invalid(self):
+        """get_theme with invalid ID raises KeyError."""
+        with pytest.raises(KeyError):
+            themes.get_theme("invalid_theme")
+
+    def test_get_theme_invalid_none(self):
+        """get_theme with None raises KeyError."""
+        with pytest.raises(KeyError):
+            themes.get_theme(None)
+
+
+class TestGreenTheme:
+    """Tests for green theme specific values."""
+
+    def test_green_theme_unchanged(self):
+        """Green theme maintains original color sequence."""
+        green = themes.get_theme("green")
+
+        # Expected main gradient: 231→195→123→118→82→46→40→34→28→22→22(dim)→235
+        expected_main = [231, 195, 123, 118, 82, 46, 40, 34, 28, 22, 22, 235]
+        # Expected msg gradient: 231→225→219→213→207→201→165→161→125→89→89(dim)→235
+        expected_msg = [231, 225, 219, 213, 207, 201, 165, 161, 125, 89, 89, 235]
+
+        assert green.main_gradient == expected_main
+        assert green.message_gradient == expected_msg
+
+    def test_green_theme_name(self):
+        """Green theme has correct name."""
+        green = themes.get_theme("green")
+        assert green.name == "green"
+
+
+class TestOrangeTheme:
+    """Tests for orange theme specific values."""
+
+    def test_orange_theme_unchanged(self):
+        """Orange theme maintains original color sequence."""
+        orange = themes.get_theme("orange")
+
+        # Expected main gradient: 231→215→209→208→202→166→130→94→58→94→94(dim)→235
+        expected_main = [231, 215, 209, 208, 202, 166, 130, 94, 58, 94, 94, 235]
+        # Expected msg gradient: 231→195→33→27→21→21→21→18→18→18→18(dim)→235
+        expected_msg = [231, 195, 33, 27, 21, 21, 21, 18, 18, 18, 18, 235]
+
+        assert orange.main_gradient == expected_main
+        assert orange.message_gradient == expected_msg
+
+    def test_orange_theme_name(self):
+        """Orange theme has correct name."""
+        orange = themes.get_theme("orange")
+        assert orange.name == "orange"
+
+
+class TestPurpleTheme:
+    """Tests for purple theme specific values."""
+
+    def test_purple_theme_unchanged(self):
+        """Purple theme maintains original color sequence."""
+        purple = themes.get_theme("purple")
+
+        # Expected main gradient: 231→225→177→171→165→135→129→93→57→57→57(dim)→235
+        expected_main = [231, 225, 177, 171, 165, 135, 129, 93, 57, 57, 57, 235]
+        # Expected msg gradient: 231→226→226→220→220→184→184→178→178→172→172(dim)→235
+        expected_msg = [231, 226, 226, 220, 220, 184, 184, 178, 178, 172, 172, 235]
+
+        assert purple.main_gradient == expected_main
+        assert purple.message_gradient == expected_msg
+
+    def test_purple_theme_name(self):
+        """Purple theme has correct name."""
+        purple = themes.get_theme("purple")
+        assert purple.name == "purple"
+
+
+class TestThemeDataOnly:
+    """Tests to ensure themes module has no problematic imports."""
+
+    def test_themes_module_imports(self):
+        """themes module should be data-only without config/render imports."""
+        import inspect
+        source = inspect.getsource(themes)
+        # Verify no imports of config or render (look for actual import statements)
+        lines = source.split('\n')
+        import_lines = [line for line in lines if line.strip().startswith('import ') or line.strip().startswith('from ')]
+        # Filter out empty and comment lines
+        import_lines = [line for line in import_lines if line.strip() and not line.strip().startswith('#')]
+        # Should have no import lines
+        assert len(import_lines) == 0, f"Found unexpected imports: {import_lines}"