refactor: Restructure README, add uv and mise commands, and detail component extension and development workflows.

docs: add README update design spec
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-15 17:08:32 -07:00 · 2026-03-15 16:56:58 -07:00 · 2026-03-15 23:21:35 +00:00 · 2026-03-15 15:16:37 -07:00 · 2026-03-15 15:16:37 -07:00 · 2026-03-15 15:16:37 -07:00
57 changed files with 3046 additions and 1125 deletions
--- a/.DS_Store
+++ b/.DS_Store
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,11 @@
 __pycache__/
 *.pyc
 .mainline_venv/
 .venv/
 uv.lock
 .mainline_cache_*.json
 .DS_Store
 htmlcov/
 .coverage
 .pytest_cache/
 *.egg-info/
--- a/.python-version
+++ b/.python-version
@@ -0,0 +1 @@
 3.12
--- a/ESP32.md
+++ b/ESP32.md
@@ -3,29 +3,29 @@
 mainline\.py does heavy work unsuitable for ESP32: 25\+ HTTPS/TLS RSS feeds, OTF font rasterization via Pillow, Google Translate API calls, and complex text layout\. Simultaneously, messages arriving on `ntfy.sh/klubhaus_terminal_mainline` need to interrupt the news ticker on the same device\.
 ## Architecture: Server \+ Thin Client
 Split the system into two halves that are designed together\.
-**Server \(mainline\.py `--serve` mode, runs on any always\-on machine\)**
+**Server (mainline\.py `--serve` mode, runs on any always\-on machine)**
 * Reuses existing feed fetching, caching, content filtering, translation, and Pillow font rendering pipeline — no duplication\.
-* Pre\-renders each headline into a 1\-bit bitmap strip \(the OTF→half\-block pipeline already produces this as an intermediate step in `_render_line()`\)\.
+* Pre\-renders each headline into a 1\-bit bitmap strip (the OTF→half\-block pipeline already produces this as an intermediate step in `_render_line()`)\.
 * Exposes a lightweight HTTP API the ESP32 polls\.
-**ESP32 thin client \(Arduino sketch\)**
+**ESP32 thin client (Arduino sketch)**
-* Polls the mainline server for pre\-rendered headline bitmaps over plain HTTP \(no TLS needed if on the same LAN\)\.
+* Polls the mainline server for pre\-rendered headline bitmaps over plain HTTP (no TLS needed if on the same LAN)\.
-* Polls `ntfy.sh/klubhaus_terminal_mainline` directly for messages, reusing the proven `NetManager::httpGet()` \+ JSON parsing pattern from DoorbellLogic \(`DoorbellLogic.cpp:155-192`\)\.
+* Polls `ntfy.sh/klubhaus_terminal_mainline` directly for messages, reusing the proven `NetManager::httpGet()` \+ JSON parsing pattern from DoorbellLogic (`DoorbellLogic.cpp:155-192`)\.
-* Manages scrolling, gradient coloring, and glitch effects locally \(cheap per\-frame GPU work\)\.
+* Manages scrolling, gradient coloring, and glitch effects locally (cheap per\-frame GPU work)\.
 * When an ntfy message arrives, the scroll is paused and the message takes over the display — same interrupt pattern as the doorbell's ALERT→DASHBOARD flow\.
-## Server API \(mainline repo\)
+## Server API (mainline repo)
-New file: `serve.py` \(or `--serve` mode in mainline\.py\)\.
+New file: `serve.py` (or `--serve` mode in mainline\.py)\.
 Endpoints:
 * `GET /api/headlines` — returns JSON array of headline metadata: `[{"id": 0, "src": "Nature", "ts": "14:30", "width": 280, "height": 16, "bitmap": "<base64 1-bit packed>"}]`\. Bitmaps are 1\-bit\-per\-pixel, row\-major, packed 8px/byte\. The ESP32 applies gradient color locally\.
 * `GET /api/config` — returns `{"count": 120, "version": "...", "mode": "news"}` so the ESP32 knows what it's getting\.
 * `GET /api/health` — `{"ok": true, "last_fetch": "...", "headline_count": 120}`
-The server renders at a configurable target width \(e\.g\. 800px for Board 3, 320px for Boards 1/2\) via a `--width` flag or query parameter\. Height is fixed per headline by the font size\.
+The server renders at a configurable target width (e\.g\. 800px for Board 3, 320px for Boards 1/2) via a `--width` flag or query parameter\. Height is fixed per headline by the font size\.
-The server refreshes feeds on a timer \(reusing `_SCROLL_DUR` cadence or a longer interval\), re\-renders, and serves the latest set\. The ESP32 polls `/api/headlines` periodically \(e\.g\. every 60s\) and swaps in the new set\.
+The server refreshes feeds on a timer (reusing `_SCROLL_DUR` cadence or a longer interval), re\-renders, and serves the latest set\. The ESP32 polls `/api/headlines` periodically (e\.g\. every 60s) and swaps in the new set\.
-## Render pipeline \(server side\)
+## Render pipeline (server side)
 The existing `_render_line()` in mainline\.py already does:
 1. `ImageFont.truetype()` → `ImageDraw.text()` → grayscale `Image`
 2. Resize to target height
-3. Threshold to 1\-bit \(the `thr = 80` step\)
+3. Threshold to 1\-bit (the `thr = 80` step)
-For the server, we stop at step 3 and pack the 1\-bit data into bytes instead of converting to half\-block Unicode\. This is the exact same pipeline, just with a different output format\. The `_big_wrap()` and `_lr_gradient()` logic stays on the server for layout; gradient *coloring* moves to the ESP32 \(it's just an index lookup per pixel column\)\.
+For the server, we stop at step 3 and pack the 1\-bit data into bytes instead of converting to half\-block Unicode\. This is the exact same pipeline, just with a different output format\. The `_big_wrap()` and `_lr_gradient()` logic stays on the server for layout; gradient *coloring* moves to the ESP32 (it's just an index lookup per pixel column)\.
 ## ESP32 client
 ### State machine
 ```warp-runnable-command
@@ -35,19 +35,19 @@ BOOT → SCROLL ⇄ MESSAGE
 * **BOOT** — WiFi connect, initial headline fetch from server\.
 * **SCROLL** — Vertical scroll through pre\-rendered headlines with local gradient \+ glitch\. Polls server for new headlines periodically\. Polls ntfy every 15s\.
 * **MESSAGE** — ntfy message arrived\. Scroll paused, message displayed\. Auto\-dismiss after timeout or touch\-dismiss\. Returns to SCROLL\.
-* **OFF** — Backlight off after inactivity \(polling continues in background\)\.
+* **OFF** — Backlight off after inactivity (polling continues in background)\.
 ### ntfy integration
 The ESP32 polls `https://ntfy.sh/klubhaus_terminal_mainline/json?since=20s&poll=1` on the same 15s interval as the doorbell polls its topics\. When a message event arrives:
 1. Parse JSON: `{"event": "message", "title": "...", "message": "..."}`
 2. Save current scroll position\.
 3. Transition to MESSAGE state\.
-4. Render message text using the display library's built\-in fonts \(messages are short, no custom font needed\)\.
+4. Render message text using the display library's built\-in fonts (messages are short, no custom font needed)\.
-5. After `MESSAGE_TIMEOUT_MS` \(e\.g\. 30s\) or touch, restore scroll position and resume\.
+5. After `MESSAGE_TIMEOUT_MS` (e\.g\. 30s) or touch, restore scroll position and resume\.
-This is architecturally identical to `DoorbellLogic::onAlert()` → `dismissAlert()`, just with different content\. The ntfy polling runs independently of the server connection, so messages work even if the mainline server is offline \(the device just shows the last cached headlines\)\.
+This is architecturally identical to `DoorbellLogic::onAlert()` → `dismissAlert()`, just with different content\. The ntfy polling runs independently of the server connection, so messages work even if the mainline server is offline (the device just shows the last cached headlines)\.
 ### Headline storage
-* Board 3 \(8 MB PSRAM\): store all ~120 headline bitmaps in PSRAM\. At 800px × 16px × 1 bit = 1\.6 KB each → ~192 KB total\. Trivial\.
+* Board 3 (8 MB PSRAM): store all ~120 headline bitmaps in PSRAM\. At 800px × 16px × 1 bit = 1\.6 KB each → ~192 KB total\. Trivial\.
-* Boards 1/2 \(PSRAM TBD\): at 320px × 16px = 640 bytes each → ~77 KB for 120 headlines\. Fits if PSRAM is present\. Without PSRAM, keep ~20 headlines in a ring buffer \(~13 KB\)\.
+* Boards 1/2 (PSRAM TBD): at 320px × 16px = 640 bytes each → ~77 KB for 120 headlines\. Fits if PSRAM is present\. Without PSRAM, keep ~20 headlines in a ring buffer (~13 KB)\.
-### Gradient coloring \(local\)
+### Gradient coloring (local)
 The 12\-step ANSI gradient in mainline\.py maps to 12 RGB565 values:
 ```warp-runnable-command
 const uint16_t GRADIENT[] = {
@@ -68,8 +68,8 @@ mainline.py          (existing, unchanged)
 serve.py             (new — HTTP server, imports mainline rendering functions)
 klubhaus-doorbell-hardware.md  (existing)
 ```
-`serve.py` imports the rendering functions from mainline\.py \(after refactoring them into importable form — they're currently top\-level but not wrapped in `if __name__`\)\.
+`serve.py` imports the rendering functions from mainline\.py (after refactoring them into importable form — they're currently top\-level but not wrapped in `if __name__`)\.
-### klubhaus\-doorbell repo \(or mainline repo under firmware/\)
+### klubhaus\-doorbell repo (or mainline repo under firmware/)
 ```warp-runnable-command
 boards/esp32-mainline/
 ├── esp32-mainline.ino    Main sketch
@@ -79,31 +79,31 @@ boards/esp32-mainline/
 ├── HeadlineStore.h/.cpp  Bitmap ring buffer in PSRAM
 └── NtfyPoller.h/.cpp     ntfy.sh polling (extracted from DoorbellLogic pattern)
 ```
-The display driver is reused from the target board \(e\.g\. `DisplayDriverGFX` for Board 3\)\. `MainlineLogic` replaces `DoorbellLogic` as the state machine but follows the same patterns\.
+The display driver is reused from the target board (e\.g\. `DisplayDriverGFX` for Board 3)\. `MainlineLogic` replaces `DoorbellLogic` as the state machine but follows the same patterns\.
 ## Branch strategy recommendation
 The work spans two repos and has clear dependency ordering\.
-### Phase 1 — Finish current branch \(mainline repo\)
+### Phase 1 — Finish current branch (mainline repo)
-**Branch:** `feat/arduino` \(current\)
+**Branch:** `feat/arduino` (current)
 **Content:** Hardware spec doc\. Already done\.
 **Action:** Merge to main when ready\.
-### Phase 2 — Server renderer \(mainline repo\)
+### Phase 2 — Server renderer (mainline repo)
-**Branch:** `feat/renderer` \(branch from main after Phase 1 merges\)
+**Branch:** `feat/renderer` (branch from main after Phase 1 merges)
 **Content:**
-* Refactor mainline\.py rendering functions to be importable \(extract from `__main__` guard\)
+* Refactor mainline\.py rendering functions to be importable (extract from `__main__` guard)
 * `serve.py` — HTTP server with `/api/headlines`, `/api/config`, `/api/health`
-* Bitmap packing utility \(1\-bit row\-major\)
+* Bitmap packing utility (1\-bit row\-major)
-**Why a separate branch:** This changes mainline\.py's structure \(refactoring for imports\) and adds a new entry point\. It's a self\-contained, testable unit — you can verify the API with `curl` before touching any Arduino code\.
+**Why a separate branch:** This changes mainline\.py's structure (refactoring for imports) and adds a new entry point\. It's a self\-contained, testable unit — you can verify the API with `curl` before touching any Arduino code\.
-### Phase 3 — ESP32 client \(klubhaus\-doorbell repo, or mainline repo\)
+### Phase 3 — ESP32 client (klubhaus\-doorbell repo, or mainline repo)
 **Branch:** `feat/mainline-client` in whichever repo hosts it
 **Content:**
 * `MainlineLogic` state machine
 * `HeadlineStore` bitmap buffer
 * `NtfyPoller` for `klubhaus_terminal_mainline`
 * Board\-specific sketch for the target board
-**Depends on:** Phase 2 \(needs a running server to test against\)
+**Depends on:** Phase 2 (needs a running server to test against)
 **Repo decision:** If you have push access to klubhaus\-doorbell, it fits naturally as a new board target alongside the existing doorbell sketches — it reuses `NetManager`, `IDisplayDriver`, and the vendored display libraries\. If not, put it under `mainline/firmware/` and vendor the shared KlubhausCore library\.
 ### Merge order
-1. `feat/arduino` → main \(hardware spec\)
+1. `feat/arduino` → main (hardware spec)
-2. `feat/renderer` → main \(server\)
+2. `feat/renderer` → main (server)
-3. `feat/mainline-client` → main in whichever repo \(ESP32 client\)
+3. `feat/mainline-client` → main in whichever repo (ESP32 client)
 Each phase is independently testable and doesn't block the other until Phase 3 needs a running server\.
--- a/README.md
+++ b/README.md
@@ -2,58 +2,233 @@
 > *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.
+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).
 ---
-## Run
+## Using
 ### Run
 ```bash
 python3 mainline.py                      # news stream
 python3 mainline.py --poetry             # literary consciousness mode
 python3 mainline.py -p                   # same
 python3 mainline.py --firehose           # dense rapid-fire headline mode
 python3 mainline.py --refresh            # force re-fetch (bypass cache)
 python3 mainline.py --no-font-picker     # skip interactive font picker
 python3 mainline.py --font-file path.otf # use a specific font file
 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.
+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.
-At the top of `mainline.py`:
+### Config
 All constants live in `engine/config.py`:
 | Constant | Default | What it does |
 |---|---|---|
 | `HEADLINE_LIMIT` | `1000` | Total headlines per session |
 | `FEED_TIMEOUT` | `10` | Per-feed HTTP timeout (seconds) |
 | `MIC_THRESHOLD_DB` | `50` | dB floor above which glitches spike |
-| `_FONT_PATH` | hardcoded path | Path to your OTF/TTF display font |
+| `FONT_DIR` | `fonts/` | Folder scanned for `.otf`, `.ttf`, `.ttc` files |
-| `_FONT_SZ` | `60` | Font render size (affects block density) |
+| `FONT_PATH` | first file in `FONT_DIR` | Active display font (overridden by picker or `--font-file`) |
-| `_RENDER_H` | `8` | Terminal rows per headline line |
+| `FONT_INDEX` | `0` | Face index within a font collection file |
 | `FONT_PICKER` | `True` | Show interactive font picker at boot (`--no-font-picker` to skip) |
 | `FONT_SZ` | `60` | Font render size (affects block density) |
 | `RENDER_H` | `8` | Terminal rows per headline line |
 | `SSAA` | `4` | Super-sampling factor (render at 4× then downsample) |
 | `SCROLL_DUR` | `5.625` | Seconds per headline |
 | `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 stream endpoint |
 | `NTFY_RECONNECT_DELAY` | `5` | Seconds before reconnecting after a dropped SSE stream |
 | `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen |
-**Font:** `_FONT_PATH` is hardcoded to a local path. Update it to point to whatever display font you want — anything with strong contrast and wide letterforms works well.
+### Feeds
 ~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap feeds in `engine/sources.py` → `FEEDS`.
 **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.
 ### 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
- Feeds are fetched and filtered on startup (sports and vapid content stripped)
+### How it works
- Headlines are rasterized via Pillow into half-block characters (`▀▄█ `) at the configured font size
+
- A left-to-right ANSI gradient colors each character: white-hot leading edge trails off to near-black
+- 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
 - Headlines are rasterized via Pillow with 4× SSAA into half-block characters (`▀▄█ `) at the configured font size
 - The ticker uses a sweeping white-hot → deep green gradient; ntfy messages use a complementary white-hot → magenta/maroon gradient to distinguish them visually
 - 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 SSE stream runs in a background thread; incoming messages interrupt the scroll and render full-screen until dismissed or expired
 ### Architecture
 `mainline.py` is a thin entrypoint (venv bootstrap → `engine.app.main()`). All logic lives in the `engine/` package:
 ```
 engine/
  config.py       constants, CLI flags, glyph tables
  sources.py      FEEDS, POETRY_SOURCES, language/script maps
  terminal.py     ANSI codes, tw/th, type_out, boot_ln
  filter.py       HTML stripping, content filter
  translate.py    Google Translate wrapper + region detection
  render.py       OTF → half-block pipeline (SSAA, gradient)
  effects.py      noise, glitch_bar, fade, firehose
  fetch.py        RSS/Gutenberg fetching + cache load/save
  ntfy.py         NtfyPoller — standalone, zero internal deps
  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 in `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.
+### NtfyPoller
 ```python
 from engine.ntfy import NtfyPoller
 poller = NtfyPoller("https://ntfy.sh/my_topic/json")
 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
 ```
 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
@@ -62,7 +237,6 @@ At the top of `mainline.py`:
 ### Graphics
 - **Matrix rain underlay** — katakana column rain rendered at low opacity beneath the scrolling blocks as a background layer
 - **Animated gradient** — shift the white-hot leading edge left/right each frame for a pulse/comet effect
 - **CRT simulation** — subtle dim scanlines every N rows, occasional brightness ripple across the full screen
 - **Sixel / iTerm2 inline images** — bypass half-blocks entirely and stream actual bitmap frames for true resolution; would require a capable terminal
 - **Parallax secondary column** — a second, dimmer, faster-scrolling stream of ambient text at reduced opacity on one side
@@ -75,6 +249,10 @@ At the top of `mainline.py`:
 - **Persona modes** — `--surveillance`, `--oracle`, `--underground` as feed presets with matching color themes and boot copy
 - **Synthesized audio** — short static bursts tied to glitch events, independent of mic input
 ### Extensibility
 - **serve.py** — HTTP server that imports `engine.render` and `engine.fetch` directly to stream 1-bit bitmaps to an ESP32 display
 - **Rust port** — `ntfy.py` and `render.py` are the natural first targets; clear module boundaries make incremental porting viable
 ---
-*macOS only (system font paths hardcoded). 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+.*
--- a/mainline.md
+++ b/mainline.md
@@ -0,0 +1,178 @@
 # Refactor mainline\.py into modular package
 ## Problem
 `mainline.py` is a single 1085\-line file with ~10 interleaved concerns\. This prevents:
 * Reusing the ntfy doorbell interrupt in other visualizers
 * Importing the render pipeline from `serve.py` \(future ESP32 HTTP server\)
 * Testing any concern in isolation
 * Porting individual layers to Rust independently
 ## Target structure
 ```warp-runnable-command
 mainline.py              # thin entrypoint: venv bootstrap → engine.app.main()
 engine/
  __init__.py
  config.py              # constants, CLI flags, glyph tables
  sources.py             # FEEDS, POETRY_SOURCES, SOURCE_LANGS, _LOCATION_LANGS
  terminal.py            # ANSI codes, tw/th, type_out, slow_print, boot_ln
  filter.py              # HTML stripping, content filter (_SKIP_RE)
  translate.py           # Google Translate wrapper + location→language detection
  render.py              # OTF font loading, _render_line, _big_wrap, _lr_gradient, _make_block
  effects.py             # noise, glitch_bar, _fade_line, _vis_trunc, _firehose_line, _next_headline
  fetch.py               # RSS/Gutenberg fetching, cache load/save
  ntfy.py                # NtfyPoller class — standalone, zero internal deps
  mic.py                 # MicMonitor class — standalone
  scroll.py              # stream() frame loop + message rendering
  app.py                 # main(), TITLE art, boot sequence, signal handler
 ```
 The package is named `engine/` to avoid a naming conflict with the `mainline.py` entrypoint\.
 ## Module dependency graph
 ```warp-runnable-command
 config      ← (nothing)
 sources     ← (nothing)
 terminal    ← (nothing)
 filter      ← (nothing)
 translate   ← sources
 render      ← config, terminal, sources
 effects     ← config, terminal, sources
 fetch       ← config, sources, filter, terminal
 ntfy        ← (nothing — stdlib only, fully standalone)
 mic         ← (nothing — sounddevice only)
 scroll      ← config, terminal, render, effects, ntfy, mic
 app         ← everything above
 ```
 Critical property: **ntfy\.py and mic\.py have zero internal dependencies**, making ntfy reusable by any visualizer\.
 ## Module details
 ### mainline\.py \(entrypoint — slimmed down\)
 Keeps only the venv bootstrap \(lines 10\-38\) which must run before any third\-party imports\. After bootstrap, delegates to `engine.app.main()`\.
 ### engine/config\.py
 From current mainline\.py:
 * `HEADLINE_LIMIT`, `FEED_TIMEOUT`, `MIC_THRESHOLD_DB` \(lines 55\-57\)
 * `MODE`, `FIREHOSE` CLI flag parsing \(lines 58\-59\)
 * `NTFY_TOPIC`, `NTFY_POLL_INTERVAL`, `MESSAGE_DISPLAY_SECS` \(lines 62\-64\)
 * `_FONT_PATH`, `_FONT_SZ`, `_RENDER_H` \(lines 147\-150\)
 * `_SCROLL_DUR`, `_FRAME_DT`, `FIREHOSE_H` \(lines 505\-507\)
 * `GLITCH`, `KATA` glyph tables \(lines 143\-144\)
 ### engine/sources\.py
 Pure data, no logic:
 * `FEEDS` dict \(lines 102\-140\)
 * `POETRY_SOURCES` dict \(lines 67\-80\)
 * `SOURCE_LANGS` dict \(lines 258\-266\)
 * `_LOCATION_LANGS` dict \(lines 269\-289\)
 * `_SCRIPT_FONTS` dict \(lines 153\-165\)
 * `_NO_UPPER` set \(line 167\)
 ### engine/terminal\.py
 ANSI primitives and terminal I/O:
 * All ANSI constants: `RST`, `BOLD`, `DIM`, `G_HI`, `G_MID`, `G_LO`, `G_DIM`, `W_COOL`, `W_DIM`, `W_GHOST`, `C_DIM`, `CLR`, `CURSOR_OFF`, `CURSOR_ON` \(lines 83\-99\)
 * `tw()`, `th()` \(lines 223\-234\)
 * `type_out()`, `slow_print()`, `boot_ln()` \(lines 355\-386\)
 ### engine/filter\.py
 * `_Strip` HTML parser class \(lines 205\-214\)
 * `strip_tags()` \(lines 217\-220\)
 * `_SKIP_RE` compiled regex \(lines 322\-346\)
 * `_skip()` predicate \(lines 349\-351\)
 ### engine/translate\.py
 * `_TRANSLATE_CACHE` \(line 291\)
 * `_detect_location_language()` \(lines 294\-300\) — imports `_LOCATION_LANGS` from sources
 * `_translate_headline()` \(lines 303\-319\)
 ### engine/render\.py
 The OTF→terminal pipeline\. This is exactly what `serve.py` will import to produce 1\-bit bitmaps for the ESP32\.
 * `_GRAD_COLS` gradient table \(lines 169\-182\)
 * `_font()`, `_font_for_lang()` with lazy\-load \+ cache \(lines 185\-202\)
 * `_render_line()` — OTF text → half\-block terminal rows \(lines 567\-605\)
 * `_big_wrap()` — word\-wrap \+ render \(lines 608\-636\)
 * `_lr_gradient()` — apply left→right color gradient \(lines 639\-656\)
 * `_make_block()` — composite: translate → render → colorize a headline \(lines 718\-756\)\. Imports from translate, sources\.
 ### engine/effects\.py
 Visual effects applied during the frame loop:
 * `noise()` \(lines 237\-245\)
 * `glitch_bar()` \(lines 248\-252\)
 * `_fade_line()` — probabilistic character dissolve \(lines 659\-680\)
 * `_vis_trunc()` — ANSI\-aware width truncation \(lines 683\-701\)
 * `_firehose_line()` \(lines 759\-801\) — imports config\.MODE, sources\.FEEDS/POETRY\_SOURCES
 * `_next_headline()` — pool management \(lines 704\-715\)
 ### engine/fetch\.py
 * `fetch_feed()` \(lines 390\-396\)
 * `fetch_all()` \(lines 399\-426\) — imports filter\.\_skip, filter\.strip\_tags, terminal\.boot\_ln
 * `_fetch_gutenberg()` \(lines 429\-456\)
 * `fetch_poetry()` \(lines 459\-472\)
 * `_cache_path()`, `_load_cache()`, `_save_cache()` \(lines 476\-501\)
 ### engine/ntfy\.py — standalone, reusable
 Refactored from the current globals \+ thread \(lines 531\-564\) and the message rendering section of `stream()` \(lines 845\-909\) into a class:
 ```python
 class NtfyPoller:
    def __init__(self, topic_url, poll_interval=15, display_secs=30):
        ...
    def start(self):
        """Start background polling thread."""
    def get_active_message(self):
        """Return (title, body, timestamp) if a message is active and not expired, else None."""
    def dismiss(self):
        """Manually dismiss current message."""
 ```
 Dependencies: `urllib.request`, `json`, `threading`, `time` — all stdlib\. No internal imports\.
 Other visualizers use it like:
 ```python
 from engine.ntfy import NtfyPoller
 poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1")
 poller.start()
 # in render loop:
 msg = poller.get_active_message()
 if msg:
    title, body, ts = msg
    render_my_message(title, body)  # visualizer-specific
 ```
 ### engine/mic\.py — standalone
 Refactored from the current globals \(lines 508\-528\) into a class:
 ```python
 class MicMonitor:
    def __init__(self, threshold_db=50):
        ...
    def start(self) -> bool:
        """Start background mic stream. Returns False if unavailable."""
    def stop(self):
        ...
    @property
    def db(self) -> float:
        """Current RMS dB level."""
    @property
    def excess(self) -> float:
        """dB above threshold (clamped to 0)."""
 ```
 Dependencies: `sounddevice`, `numpy` \(both optional — graceful fallback\)\.
 ### engine/scroll\.py
 The `stream()` function \(lines 804\-990\)\. Receives its dependencies via arguments or imports:
 * `stream(items, ntfy_poller, mic_monitor, config)` or similar
 * Message rendering \(lines 855\-909\) stays here since it's terminal\-display\-specific — a different visualizer would render messages differently
 ### engine/app\.py
 The orchestrator:
 * `TITLE` ASCII art \(lines 994\-1001\)
 * `main()` \(lines 1004\-1084\): CLI handling, signal setup, boot animation, fetch, wire up ntfy/mic/scroll
 ## Execution order
 ### Step 1: Create engine/ package skeleton
 Create `engine/__init__.py` and all empty module files\.
 ### Step 2: Extract pure data modules \(zero\-dep\)
 Move constants and data dicts into `config.py`, `sources.py`\. These have no logic dependencies\.
 ### Step 3: Extract terminal\.py
 Move ANSI codes and terminal I/O helpers\. No internal deps\.
 ### Step 4: Extract filter\.py and translate\.py
 Both are small, self\-contained\. translate imports from sources\.
 ### Step 5: Extract render\.py
 Font loading \+ the OTF→half\-block pipeline\. Imports from config, terminal, sources\. This is the module `serve.py` will later import\.
 ### Step 6: Extract effects\.py
 Visual effects\. Imports from config, terminal, sources\.
 ### Step 7: Extract fetch\.py
 Feed/Gutenberg fetching \+ caching\. Imports from config, sources, filter, terminal\.
 ### Step 8: Extract ntfy\.py and mic\.py
 Refactor globals\+threads into classes\. Zero internal deps\.
 ### Step 9: Extract scroll\.py
 The frame loop\. Last to extract because it depends on everything above\.
 ### Step 10: Extract app\.py
 The `main()` function, boot sequence, signal handler\. Wire up all modules\.
 ### Step 11: Slim down mainline\.py
 Keep only venv bootstrap \+ `from engine.app import main; main()`\.
 ### Step 12: Verify
 Run `python3 mainline.py`, `python3 mainline.py --poetry`, and `python3 mainline.py --firehose` to confirm identical behavior\. No behavioral changes in this refactor\.
 ## What this enables
 * **serve\.py** \(future\): `from engine.render import _render_line, _big_wrap` \+ `from engine.fetch import fetch_all` — imports the pipeline directly
 * **Other visualizers**: `from engine.ntfy import NtfyPoller` — doorbell feature with no coupling to mainline's scroll engine
 * **Rust port**: Clear boundaries for what to port first \(ntfy client, render pipeline\) vs what stays in Python \(fetching, caching — the server side\)
 * **Testing**: Each module can be unit\-tested in isolation
--- a/docs/superpowers/specs/2026-03-15-readme-update-design.md
+++ b/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
--- a/engine/init.py
+++ b/engine/init.py
@@ -0,0 +1 @@
 # engine — modular internals for mainline
--- a/engine/app.py
+++ b/engine/app.py
@@ -0,0 +1,352 @@
 """
 Application orchestrator — boot sequence, signal handling, main loop wiring.
 """
 import atexit
 import os
 import signal
 import sys
 import termios
 import time
 import tty
 from engine import config, render
 from engine.fetch import fetch_all, fetch_poetry, load_cache, save_cache
 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 = [
    "  ███╗   ███╗ █████╗ ██╗███╗   ██╗██╗     ██╗███╗   ██╗███████╗",
    "  ████╗ ████║██╔══██╗██║████╗  ██║██║     ██║████╗  ██║██╔════╝",
    "  ██╔████╔██║███████║██║██╔██╗ ██║██║     ██║██╔██╗ ██║█████╗  ",
    "  ██║╚██╔╝██║██╔══██║██║██║╚██╗██║██║     ██║██║╚██╗██║██╔══╝  ",
    "  ██║ ╚═╝ ██║██║  ██║██║██║ ╚████║███████╗██║██║ ╚████║███████╗",
    "  ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝",
 ]
 def _read_picker_key():
    ch = sys.stdin.read(1)
    if ch == "\x03":
        return "interrupt"
    if ch in ("\r", "\n"):
        return "enter"
    if ch == "\x1b":
        c1 = sys.stdin.read(1)
        if c1 != "[":
            return None
        c2 = sys.stdin.read(1)
        if c2 == "A":
            return "up"
        if c2 == "B":
            return "down"
        return None
    if ch in ("k", "K"):
        return "up"
    if ch in ("j", "J"):
        return "down"
    if ch in ("q", "Q"):
        return "enter"
    return None
 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()]
    if not non_empty:
        return [""]
    left_pad = min(len(r) - len(r.lstrip(" ")) for r in non_empty)
    out = []
    for row in rows:
        if left_pad < len(row):
            out.append(row[left_pad:].rstrip())
        else:
            out.append(row.rstrip())
    return out
 def _draw_font_picker(faces, selected):
    w = tw()
    h = 24
    try:
        h = os.get_terminal_size().lines
    except Exception:
        pass
    max_preview_w = max(24, w - 8)
    header_h = 6
    footer_h = 3
    preview_h = max(4, min(config.RENDER_H + 2, max(4, h // 2)))
    visible = max(1, h - header_h - preview_h - footer_h)
    top = max(0, selected - (visible // 2))
    bottom = min(len(faces), top + visible)
    top = max(0, bottom - visible)
    print(CLR, end="")
    print(CURSOR_OFF, end="")
    print()
    print(f"  {G_HI}FONT PICKER{RST}")
    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
    print(f"  {W_DIM}{config.FONT_DIR[:max_preview_w]}{RST}")
    print(f"  {W_GHOST}↑/↓ move · Enter select · q accept current{RST}")
    print()
    for pos in range(top, bottom):
        face = faces[pos]
        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}"
        )
    if top > 0:
        print(f"  {W_GHOST}… {top} above{RST}")
    if bottom < len(faces):
        print(f"  {W_GHOST}… {len(faces) - bottom} below{RST}")
    print()
    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
    print(
        f"  {W_DIM}Preview: {faces[selected]['name']} · {faces[selected]['file_name']}{RST}"
    )
    preview_rows = faces[selected]["preview_rows"][:preview_h]
    for row in preview_rows:
        shown = row[:max_preview_w]
        print(f"    {shown}")
 def pick_font_face():
    """Interactive startup picker for selecting a face from repo OTF files."""
    if not config.FONT_PICKER:
        return
    font_files = config.list_repo_font_files()
    if not font_files:
        print(CLR, end="")
        print(CURSOR_OFF, end="")
        print()
        print(f"  {G_HI}FONT PICKER{RST}")
        print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
        print(f"  {G_DIM}> no .otf/.ttf/.ttc files found in: {config.FONT_DIR}{RST}")
        print(f"  {W_GHOST}> add font files to the fonts folder, then rerun{RST}")
        time.sleep(1.8)
        sys.exit(1)
    prepared = []
    for font_path in font_files:
        try:
            faces = render.list_font_faces(font_path, max_faces=64)
        except Exception:
            fallback = os.path.splitext(os.path.basename(font_path))[0]
            faces = [{"index": 0, "name": fallback}]
        for face in faces:
            idx = face["index"]
            name = face["name"]
            file_name = os.path.basename(font_path)
            try:
                fnt = render.load_font_face(font_path, idx)
                rows = _normalize_preview_rows(render.render_line(name, fnt))
            except Exception:
                rows = ["(preview unavailable)"]
            prepared.append(
                {
                    "font_path": font_path,
                    "font_index": idx,
                    "name": name,
                    "file_name": file_name,
                    "preview_rows": rows,
                }
            )
    if not prepared:
        print(CLR, end="")
        print(CURSOR_OFF, end="")
        print()
        print(f"  {G_HI}FONT PICKER{RST}")
        print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
        print(f"  {G_DIM}> no readable font faces found in: {config.FONT_DIR}{RST}")
        time.sleep(1.8)
        sys.exit(1)
    def _same_path(a, b):
        try:
            return os.path.samefile(a, b)
        except Exception:
            return os.path.abspath(a) == os.path.abspath(b)
    selected = next(
        (
            i
            for i, f in enumerate(prepared)
            if _same_path(f["font_path"], config.FONT_PATH)
            and f["font_index"] == config.FONT_INDEX
        ),
        0,
    )
    if not sys.stdin.isatty():
        selected_font = prepared[selected]
        config.set_font_selection(
            font_path=selected_font["font_path"],
            font_index=selected_font["font_index"],
        )
        render.clear_font_cache()
        print(
            f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}"
        )
        time.sleep(0.8)
        print(CLR, end="")
        print(CURSOR_OFF, end="")
        print()
        return
    fd = sys.stdin.fileno()
    old_settings = termios.tcgetattr(fd)
    try:
        tty.setcbreak(fd)
        while True:
            _draw_font_picker(prepared, selected)
            key = _read_picker_key()
            if key == "up":
                selected = max(0, selected - 1)
            elif key == "down":
                selected = min(len(prepared) - 1, selected + 1)
            elif key == "enter":
                break
            elif key == "interrupt":
                raise KeyboardInterrupt
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
    selected_font = prepared[selected]
    config.set_font_selection(
        font_path=selected_font["font_path"],
        font_index=selected_font["font_index"],
    )
    render.clear_font_cache()
    print(
        f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}"
    )
    time.sleep(0.8)
    print(CLR, end="")
    print(CURSOR_OFF, end="")
    print()
 def main():
    atexit.register(lambda: print(CURSOR_ON, end="", flush=True))
    def handle_sigint(*_):
        print(f"\n\n  {G_DIM}> SIGNAL LOST{RST}")
        print(f"  {W_GHOST}> connection terminated{RST}\n")
        sys.exit(0)
    signal.signal(signal.SIGINT, handle_sigint)
    w = tw()
    print(CLR, end="")
    print(CURSOR_OFF, end="")
    pick_font_face()
    w = tw()
    print()
    time.sleep(0.4)
    for ln in TITLE:
        print(f"{G_HI}{ln}{RST}")
        time.sleep(0.07)
    print()
    _subtitle = (
        "literary consciousness stream"
        if config.MODE == "poetry"
        else "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
    if cached:
        items = cached
        boot_ln("Cache", f"LOADED [{len(items)} SIGNALS]", True)
    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}{len(items)} STANZAS ACQUIRED{RST}")
        save_cache(items)
    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}{len(items)} SIGNALS ACQUIRED{RST}")
        save_cache(items)
    if not items:
        print(f"\n  {W_DIM}> NO SIGNAL — check network{RST}")
        sys.exit(1)
    print()
    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),
        )
    ntfy = NtfyPoller(
        config.NTFY_TOPIC,
        reconnect_delay=config.NTFY_RECONNECT_DELAY,
        display_secs=config.MESSAGE_DISPLAY_SECS,
    )
    ntfy_ok = ntfy.start()
    boot_ln("ntfy", "LISTENING" if ntfy_ok else "OFFLINE", ntfy_ok)
    if config.FIREHOSE:
        boot_ln("Firehose", "ENGAGED", True)
    time.sleep(0.4)
    slow_print("  > STREAMING...\n")
    time.sleep(0.2)
    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
    print()
    time.sleep(0.4)
    stream(items, ntfy, mic)
    print()
    print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
    print(f"  {G_DIM}> {config.HEADLINE_LIMIT} SIGNALS PROCESSED{RST}")
    print(f"  {W_GHOST}> end of stream{RST}")
    print()
--- a/engine/config.py
+++ b/engine/config.py
@@ -0,0 +1,102 @@
 """
 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"}
 def _arg_value(flag):
    """Get value following a CLI flag, if present."""
    if flag not in sys.argv:
        return None
    i = sys.argv.index(flag)
    return sys.argv[i + 1] if i + 1 < len(sys.argv) else None
 def _arg_int(flag, default):
    """Get int CLI argument with safe fallback."""
    raw = _arg_value(flag)
    if raw is None:
        return default
    try:
        return int(raw)
    except ValueError:
        return default
 def _resolve_font_path(raw_path):
    """Resolve font path; relative paths are anchored to repo root."""
    p = Path(raw_path).expanduser()
    if p.is_absolute():
        return str(p)
    return str((_REPO_ROOT / p).resolve())
 def _list_font_files(font_dir):
    """List supported font files within a font directory."""
    font_root = Path(font_dir)
    if not font_root.exists() or not font_root.is_dir():
        return []
    return [
        str(path.resolve())
        for path in sorted(font_root.iterdir())
        if path.is_file() and path.suffix.lower() in _FONT_EXTENSIONS
    ]
 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
 MODE = "poetry" if "--poetry" in sys.argv or "-p" 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
 # ─── FONT RENDERING ──────────────────────────────────────
 FONT_DIR = _resolve_font_path(_arg_value("--font-dir") or "fonts")
 _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_PICKER = "--no-font-picker" not in sys.argv
 FONT_SZ = 60
 RENDER_H = 8  # terminal rows per rendered text line
 # ─── FONT RENDERING (ADVANCED) ────────────────────────────
 SSAA = 4  # super-sampling factor: render at SSAA× then downsample
 # ─── SCROLL / FRAME ──────────────────────────────────────
 SCROLL_DUR = 5.625  # seconds per headline (2/3 original speed)
 FRAME_DT = 0.05  # 50ms base frame rate (20 FPS)
 FIREHOSE_H = 12  # firehose zone height (terminal rows)
 GRAD_SPEED = 0.08  # gradient traversal speed (cycles/sec, ~12s full sweep)
 # ─── GLYPHS ───────────────────────────────────────────────
 GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
 KATA = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"
 def set_font_selection(font_path=None, font_index=None):
    """Set runtime primary font selection."""
    global FONT_PATH, FONT_INDEX
    if font_path is not None:
        FONT_PATH = _resolve_font_path(font_path)
    if font_index is not None:
        FONT_INDEX = max(0, int(font_index))
--- a/engine/effects.py
+++ b/engine/effects.py
@@ -0,0 +1,134 @@
 """
 Visual effects: noise, glitch, fade, ANSI-aware truncation, firehose, headline pool.
 Depends on: config, terminal, sources.
 """
 import random
 from datetime import datetime
 from engine import config
 from engine.sources import FEEDS, POETRY_SOURCES
 from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST, W_GHOST
 def noise(w):
    d = random.choice([0.15, 0.25, 0.35, 0.12])
    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 " "
        for _ in range(w)
    )
 def glitch_bar(w):
    c = random.choice(["░", "▒", "─", "╌"])
    n = random.randint(3, w // 2)
    o = random.randint(0, w - n)
    return " " * o + f"{G_LO}{DIM}" + c * n + RST
 def fade_line(s, fade):
    """Dissolve a rendered line by probabilistically dropping characters."""
    if fade >= 1.0:
        return s
    if fade <= 0.0:
        return ""
    result = []
    i = 0
    while i < len(s):
        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])
            i = j + 1
        elif s[i] == " ":
            result.append(" ")
            i += 1
        else:
            result.append(s[i] if random.random() < fade else " ")
            i += 1
    return "".join(result)
 def vis_trunc(s, w):
    """Truncate string to visual width w, skipping ANSI escape codes."""
    result = []
    vw = 0
    i = 0
    while i < len(s):
        if vw >= w:
            break
        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])
            i = j + 1
        else:
            result.append(s[i])
            vw += 1
            i += 1
    return "".join(result)
 def next_headline(pool, items, seen):
    """Pull the next unique headline from pool, refilling as needed."""
    while True:
        if not pool:
            pool.extend(items)
            random.shuffle(pool)
            seen.clear()
        title, src, ts = pool.pop()
        sig = title.lower().strip()
        if sig not in seen:
            seen.add(sig)
            return title, src, ts
 def firehose_line(items, w):
    """Generate one line of rapidly cycling firehose content."""
    r = random.random()
    if r < 0.35:
        # Raw headline text
        title, src, ts = random.choice(items)
        text = title[: w - 1]
        color = random.choice([G_LO, G_DIM, W_GHOST, C_DIM])
        return f"{color}{text}{RST}"
    elif r < 0.55:
        # Dense glitch noise
        d = random.choice([0.45, 0.55, 0.65, 0.75])
        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 " "
            for _ in range(w)
        )
    elif r < 0.78:
        # Status / program output
        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]}",
            f"  ░░ FEED ACTIVE :: {src}",
            f"  >> DECODE 0x{random.randint(0x1000, 0xFFFF):04X} :: {src[:24]}",
            f"  ▒▒ ACQUIRE :: {random.choice(['TCP', 'UDP', 'RSS', 'ATOM', 'XML'])} :: {src}",
            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]
        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)]
        pad = random.randint(0, max(0, w - len(frag) - 8))
        gp = "".join(random.choice(config.GLITCH) for _ in range(random.randint(1, 3)))
        text = (" " * pad + gp + " " + frag)[: w - 1]
        color = random.choice([G_LO, C_DIM, W_GHOST])
        return f"{color}{text}{RST}"
--- a/engine/fetch.py
+++ b/engine/fetch.py
@@ -0,0 +1,139 @@
 """
 RSS feed fetching, Project Gutenberg parsing, and headline caching.
 Depends on: config, sources, filter, terminal.
 """
 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.terminal import boot_ln
 # ─── SINGLE FEED ──────────────────────────────────────────
 def fetch_feed(url):
    try:
        req = urllib.request.Request(url, headers={"User-Agent": "mainline/0.1"})
        resp = urllib.request.urlopen(req, timeout=config.FEED_TIMEOUT)
        return feedparser.parse(resp.read())
    except Exception:
        return None
 # ─── ALL RSS FEEDS ────────────────────────────────────────
 def fetch_all():
    items = []
    linked = failed = 0
    for src, url in FEEDS.items():
        feed = fetch_feed(url)
        if feed is None or (feed.bozo and not feed.entries):
            boot_ln(src, "DARK", False)
            failed += 1
            continue
        n = 0
        for e in feed.entries:
            t = strip_tags(e.get("title", ""))
            if not t or skip(t):
                continue
            pub = e.get("published_parsed") or e.get("updated_parsed")
            try:
                ts = datetime(*pub[:6]).strftime("%H:%M") if pub else "——:——"
            except Exception:
                ts = "——:——"
            items.append((t, src, ts))
            n += 1
        if n:
            boot_ln(src, f"LINKED [{n}]", True)
            linked += 1
        else:
            boot_ln(src, "EMPTY", False)
            failed += 1
    return items, linked, failed
 # ─── PROJECT GUTENBERG ────────────────────────────────────
 def _fetch_gutenberg(url, label):
    """Download and parse stanzas/passages from a Project Gutenberg text."""
    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")
        )
        # Strip PG boilerplate
        m = re.search(r"\*\*\*\s*START OF[^\n]*\n", text)
        if m:
            text = text[m.end() :]
        m = re.search(r"\*\*\*\s*END OF", text)
        if m:
            text = text[: m.start()]
        # Split on blank lines into stanzas/passages
        blocks = re.split(r"\n{2,}", text.strip())
        items = []
        for blk in blocks:
            blk = " ".join(blk.split())  # flatten to one line
            if len(blk) < 20 or len(blk) > 280:
                continue
            if blk.isupper():  # skip all-caps headers
                continue
            if re.match(r"^[IVXLCDM]+\.?\s*$", blk):  # roman numerals
                continue
            items.append((blk, label, ""))
        return items
    except Exception:
        return []
 def fetch_poetry():
    """Fetch all poetry/literature sources."""
    items = []
    linked = failed = 0
    for label, url in POETRY_SOURCES.items():
        stanzas = _fetch_gutenberg(url, label)
        if stanzas:
            boot_ln(label, f"LOADED [{len(stanzas)}]", True)
            items.extend(stanzas)
            linked += 1
        else:
            boot_ln(label, "DARK", False)
            failed += 1
    return items, linked, failed
 # ─── CACHE ────────────────────────────────────────────────
 _CACHE_DIR = pathlib.Path(__file__).resolve().parent.parent
 def _cache_path():
    return _CACHE_DIR / f".mainline_cache_{config.MODE}.json"
 def load_cache():
    """Load cached items from disk if available."""
    p = _cache_path()
    if not p.exists():
        return None
    try:
        data = json.loads(p.read_text())
        items = [tuple(i) for i in data["items"]]
        return items if items else None
    except Exception:
        return None
 def save_cache(items):
    """Save fetched items to disk for fast subsequent runs."""
    try:
        _cache_path().write_text(json.dumps({"items": items}))
    except Exception:
        pass
--- a/engine/filter.py
+++ b/engine/filter.py
@@ -0,0 +1,60 @@
 """
 HTML stripping and content filter (sports, vapid, insipid).
 No internal dependencies.
 """
 import re
 from html import unescape
 from html.parser import HTMLParser
 # ─── HTML STRIPPING ───────────────────────────────────────
 class _Strip(HTMLParser):
    def __init__(self):
        super().__init__()
        self._t = []
    def handle_data(self, d):
        self._t.append(d)
    def text(self):
        return "".join(self._t).strip()
 def strip_tags(html):
    s = _Strip()
    s.feed(unescape(html or ""))
    return s.text()
 # ─── CONTENT FILTER ───────────────────────────────────────
 _SKIP_RE = re.compile(
    r"\b(?:"
    # ── sports ──
    r"football|soccer|basketball|baseball|softball|tennis|golf|cricket|rugby|"
    r"hockey|lacrosse|volleyball|badminton|"
    r"nba|nfl|nhl|mlb|mls|fifa|uefa|"
    r"premier league|champions league|la liga|serie a|bundesliga|"
    r"world cup|super bowl|world series|stanley cup|"
    r"playoff|playoffs|touchdown|goalkeeper|striker|quarterback|"
    r"slam dunk|home run|grand slam|offside|halftime|"
    r"batting|wicket|innings|"
    r"formula 1|nascar|motogp|"
    r"boxing|ufc|mma|"
    r"marathon|tour de france|"
    r"transfer window|draft pick|relegation|"
    # ── vapid / insipid ──
    r"kardashian|jenner|reality tv|reality show|"
    r"influencer|viral video|tiktok|instagram|"
    r"best dressed|worst dressed|red carpet|"
    r"horoscope|zodiac|gossip|bikini|selfie|"
    r"you won.t believe|what happened next|"
    r"celebrity couple|celebrity feud|baby bump"
    r")\b",
    re.IGNORECASE,
 )
 def skip(title):
    """Return True if headline is sports, vapid, or insipid."""
    return bool(_SKIP_RE.search(title))
--- a/engine/mic.py
+++ b/engine/mic.py
@@ -0,0 +1,66 @@
 """
 Microphone input monitor — standalone, no internal dependencies.
 Gracefully degrades if sounddevice/numpy are unavailable.
 """
 import atexit
 try:
    import numpy as _np
    import sounddevice as _sd
    _HAS_MIC = True
 except Exception:
    _HAS_MIC = False
 class MicMonitor:
    """Background mic stream that exposes current RMS dB level."""
    def __init__(self, threshold_db=50):
        self.threshold_db = threshold_db
        self._db = -99.0
        self._stream = None
    @property
    def available(self):
        """True if sounddevice is importable."""
        return _HAS_MIC
    @property
    def db(self):
        """Current RMS dB level."""
        return self._db
    @property
    def excess(self):
        """dB above threshold (clamped to 0)."""
        return max(0.0, self._db - self.threshold_db)
    def start(self):
        """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)))
            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
            )
            self._stream.start()
            atexit.register(self.stop)
            return True
        except Exception:
            return False
    def stop(self):
        """Stop the mic stream if running."""
        if self._stream:
            try:
                self._stream.stop()
            except Exception:
                pass
            self._stream = None
--- a/engine/ntfy.py
+++ b/engine/ntfy.py
@@ -0,0 +1,93 @@
 """
 ntfy.sh SSE stream listener — standalone, zero internal dependencies.
 Reusable by any visualizer:
    from engine.ntfy import NtfyPoller
    poller = NtfyPoller("https://ntfy.sh/my_topic/json")
    poller.start()
    # in render loop:
    msg = poller.get_active_message()
    if msg:
        title, body, ts = msg
        render_my_message(title, body)
 """
 import json
 import threading
 import time
 import urllib.request
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 class NtfyPoller:
    """SSE stream listener for ntfy.sh topics. Messages arrive in ~1s (network RTT)."""
    def __init__(self, topic_url, reconnect_delay=5, display_secs=30):
        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._lock = threading.Lock()
    def start(self):
        """Start background stream thread. Returns True."""
        t = threading.Thread(target=self._stream_loop, daemon=True)
        t.start()
        return True
    def get_active_message(self):
        """Return (title, body, timestamp) if a message is active and not expired, else None."""
        with self._lock:
            if self._message is None:
                return None
            title, body, ts = self._message
            if time.monotonic() - ts < self.display_secs:
                return self._message
            self._message = None
            return None
    def dismiss(self):
        """Manually dismiss the current message."""
        with self._lock:
            self._message = None
    def _build_url(self, last_id=None):
        """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"]
        new_query = urlencode({k: v[0] for k, v in params.items()})
        return urlunparse(parsed._replace(query=new_query))
    def _stream_loop(self):
        last_id = None
        while True:
            try:
                url = self._build_url(last_id)
                req = urllib.request.Request(
                    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:
                    line = resp.readline()
                    if not line:
                        break  # server closed connection — reconnect
                    try:
                        data = json.loads(line.decode("utf-8", errors="replace"))
                    except json.JSONDecodeError:
                        continue
                    # Advance cursor on every event (message + keepalive) to
                    # avoid replaying already-seen events after a reconnect.
                    if "id" in data:
                        last_id = data["id"]
                    if data.get("event") == "message":
                        with self._lock:
                            self._message = (
                                data.get("title", ""),
                                data.get("message", ""),
                                time.monotonic(),
                            )
            except Exception:
                pass
            time.sleep(self.reconnect_delay)
--- a/engine/render.py
+++ b/engine/render.py
@@ -0,0 +1,269 @@
 """
 OTF → terminal half-block rendering pipeline.
 Font loading, text rasterization, word-wrap, gradient coloring, headline block assembly.
 Depends on: config, terminal, sources, translate.
 """
 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.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)
 MSG_GRAD_COLS = [
    "\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
 _FONT_OBJ_KEY = None
 _FONT_CACHE = {}
 def font():
    """Lazy-load the primary OTF font (path + face index aware)."""
    global _FONT_OBJ, _FONT_OBJ_KEY
    if not config.FONT_PATH:
        raise FileNotFoundError(
            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 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
    _FONT_OBJ = None
    _FONT_OBJ_KEY = None
 def load_font_face(font_path, font_index=0, size=None):
    """Load a specific face from a font file or collection."""
    font_size = size or config.FONT_SZ
    return ImageFont.truetype(font_path, font_size, index=font_index)
 def list_font_faces(font_path, max_faces=64):
    """Return discoverable face indexes + display names from a font file."""
    faces = []
    for idx in range(max_faces):
        try:
            fnt = load_font_face(font_path, idx)
        except Exception:
            if idx == 0:
                raise
            break
        family, style = fnt.getname()
        display = f"{family} {style}".strip()
        if not display:
            display = f"{Path(font_path).stem} [{idx}]"
        faces.append({"index": idx, "name": display})
    return faces
 def font_for_lang(lang=None):
    """Get appropriate font for a language."""
    if lang is None or lang not in SCRIPT_FONTS:
        return font()
    if lang not in _FONT_CACHE:
        try:
            _FONT_CACHE[lang] = ImageFont.truetype(SCRIPT_FONTS[lang], config.FONT_SZ)
        except Exception:
            _FONT_CACHE[lang] = font()
    return _FONT_CACHE[lang]
 # ─── RASTERIZATION ────────────────────────────────────────
 def render_line(text, fnt=None):
    """Render a line of text as terminal rows using OTF font + half-blocks."""
    if fnt is None:
        fnt = font()
    bbox = fnt.getbbox(text)
    if not bbox or bbox[2] <= bbox[0]:
        return [""]
    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)
    draw = ImageDraw.Draw(img)
    draw.text((-bbox[0] + pad, -bbox[1] + pad), text, fill=255, font=fnt)
    pix_h = config.RENDER_H * 2
    hi_h = pix_h * config.SSAA
    scale = hi_h / max(img_h, 1)
    new_w_hi = max(1, int(img_w * scale))
    img = img.resize((new_w_hi, hi_h), Image.Resampling.LANCZOS)
    new_w = max(1, int(new_w_hi / config.SSAA))
    img = img.resize((new_w, pix_h), Image.Resampling.LANCZOS)
    data = img.tobytes()
    thr = 80
    rows = []
    for y in range(0, pix_h, 2):
        row = []
        for x in range(new_w):
            top = data[y * new_w + x] > thr
            bot = data[(y + 1) * new_w + x] > thr if y + 1 < pix_h else False
            if top and bot:
                row.append("█")
            elif top:
                row.append("▀")
            elif bot:
                row.append("▄")
            else:
                row.append(" ")
        rows.append("".join(row))
    while rows and not rows[-1].strip():
        rows.pop()
    while rows and not rows[0].strip():
        rows.pop(0)
    return rows if rows else [""]
 def big_wrap(text, max_w, fnt=None):
    """Word-wrap text and render with OTF font."""
    if fnt is None:
        fnt = font()
    words = text.split()
    lines, cur = [], ""
    for word in words:
        test = f"{cur} {word}".strip() if cur else word
        bbox = fnt.getbbox(test)
        if bbox:
            img_h = bbox[3] - bbox[1] + 8
            pix_h = config.RENDER_H * 2
            scale = pix_h / max(img_h, 1)
            term_w = int((bbox[2] - bbox[0] + 8) * scale)
        else:
            term_w = 0
        if term_w > max_w - 4 and cur:
            lines.append(cur)
            cur = word
        else:
            cur = test
    if cur:
        lines.append(cur)
    out = []
    for i, ln in enumerate(lines):
        out.extend(render_line(ln, fnt))
        if i < len(lines) - 1:
            out.append("")
    return out
 def lr_gradient(rows, offset=0.0, grad_cols=None):
    """Color each non-space block character with a shifting left-to-right gradient."""
    cols = grad_cols or GRAD_COLS
    n = len(cols)
    max_x = max((len(r.rstrip()) for r in rows if r.strip()), default=1)
    out = []
    for row in rows:
        if not row.strip():
            out.append(row)
            continue
        buf = []
        for x, ch in enumerate(row):
            if ch == " ":
                buf.append(" ")
            else:
                shifted = (x / max(max_x - 1, 1) + offset) % 1.0
                idx = min(round(shifted * (n - 1)), n - 1)
                buf.append(f"{cols[idx]}{ch}{RST}")
        out.append("".join(buf))
    return out
 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)
 # ─── 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
    )
    lang_font = font_for_lang(target_lang)
    if target_lang:
        title = translate_headline(title, target_lang)
    # Don't uppercase scripts that have no case (CJK, Arabic, etc.)
    if target_lang and target_lang in NO_UPPER:
        title_up = re.sub(r"\s+", " ", title)
    else:
        title_up = re.sub(r"\s+", " ", title.upper())
    for old, new in [
        ("\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(
        [
            "\033[38;5;46m",  # matrix green
            "\033[38;5;34m",  # dark green
            "\033[38;5;82m",  # lime
            "\033[38;5;48m",  # sea green
            "\033[38;5;37m",  # teal
            "\033[38;5;44m",  # cyan
            "\033[38;5;87m",  # sky
            "\033[38;5;117m",  # ice blue
            "\033[38;5;250m",  # cool white
            "\033[38;5;156m",  # pale green
            "\033[38;5;120m",  # mint
            "\033[38;5;80m",  # dark cyan
            "\033[38;5;108m",  # grey-green
            "\033[38;5;115m",  # sage
            "\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}"
    content.append(" " * max(2, w - len(meta) - 2) + meta)
    return content, hc, len(content) - 1  # (rows, color, meta_row_index)
--- a/engine/scroll.py
+++ b/engine/scroll.py
@@ -0,0 +1,220 @@
 """
 Render engine — ticker content, scroll motion, message panel, and firehose overlay.
 Depends on: config, terminal, render, effects, ntfy, mic.
 """
 import random
 import re
 import sys
 import time
 from datetime import datetime
 from engine import config
 from engine.effects import (
    fade_line,
    firehose_line,
    glitch_bar,
    next_headline,
    noise,
    vis_trunc,
 )
 from engine.render import big_wrap, lr_gradient, lr_gradient_opposite, make_block
 from engine.terminal import CLR, RST, W_COOL, th, tw
 def stream(items, ntfy_poller, mic_monitor):
    """Main render loop with four layers: message, ticker, scroll motion, firehose."""
    random.shuffle(items)
    pool = list(items)
    seen = set()
    queued = 0
    time.sleep(0.5)
    sys.stdout.write(CLR)
    sys.stdout.flush()
    w, h = tw(), th()
    fh = config.FIREHOSE_H if config.FIREHOSE else 0
    ticker_view_h = h - fh  # reserve fixed firehose strip at bottom
    GAP = 3  # blank rows between headlines
    scroll_step_interval = config.SCROLL_DUR / (ticker_view_h + 15) * 2
    # Taxonomy:
    # - message: centered ntfy overlay panel
    # - ticker: large headline text content
    # - scroll: upward camera motion applied to ticker content
    # - 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
    ticker_next_y = (
        ticker_view_h  # canvas-y where next block starts (off-screen bottom)
    )
    noise_cache = {}
    scroll_motion_accum = 0.0
    def _noise_at(cy):
        if cy not in noise_cache:
            noise_cache[cy] = noise(w) if random.random() < 0.15 else None
        return noise_cache[cy]
    # Message color: bright cyan/white — distinct from headline greens
    MSG_META = "\033[38;5;245m"  # cool grey
    MSG_BORDER = "\033[2;38;5;37m"  # dim teal
    _msg_cache = (None, None)  # (cache_key, rendered_rows)
    while queued < config.HEADLINE_LIMIT or active:
        t0 = time.monotonic()
        w, h = tw(), th()
        fh = config.FIREHOSE_H if config.FIREHOSE else 0
        ticker_view_h = h - fh
        # ── Check for ntfy message ────────────────────────
        msg_h = 0
        msg_overlay = []
        msg = ntfy_poller.get_active_message()
        buf = []
        if msg is not None:
            m_title, m_body, m_ts = msg
            # ── Message overlay: centered in the viewport ──
            display_text = m_body or m_title or "(empty)"
            display_text = re.sub(r"\s+", " ", display_text.upper())
            cache_key = (display_text, w)
            if _msg_cache[0] != cache_key:
                msg_rows = big_wrap(display_text, w - 4)
                _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
            )
            # Layout: rendered text + meta + border
            elapsed_s = int(time.monotonic() - m_ts)
            remaining = max(0, config.MESSAGE_DISPLAY_SECS - elapsed_s)
            ts_str = datetime.now().strftime("%H:%M:%S")
            panel_h = len(msg_rows) + 2  # meta + border
            panel_top = max(0, (h - panel_h) // 2)
            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"
                )
                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]
            )
            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"
            )
        # Ticker draws above the fixed firehose strip; message is a centered overlay.
        ticker_h = ticker_view_h - msg_h
        # ── Ticker content + scroll motion (always runs) ──
        scroll_motion_accum += config.FRAME_DT
        while scroll_motion_accum >= scroll_step_interval:
            scroll_motion_accum -= scroll_step_interval
            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
            ):
                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))
                ticker_next_y += len(ticker_content) + GAP
                queued += 1
            # Prune off-screen blocks and stale noise
            active = [
                (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]
        # Draw ticker zone (above fixed firehose strip)
        top_zone = max(1, int(ticker_h * 0.25))
        bot_zone = max(1, int(ticker_h * 0.10))
        grad_offset = (time.monotonic() * config.GRAD_SPEED) % 1.0
        ticker_buf_start = len(buf)  # track where ticker rows start in buf
        for r in range(ticker_h):
            scr_row = r + 1  # 1-indexed ANSI screen row
            cy = scroll_cam + r
            top_f = min(1.0, r / top_zone) if top_zone > 0 else 1.0
            bot_f = min(1.0, (ticker_h - 1 - r) / bot_zone) if bot_zone > 0 else 1.0
            row_fade = min(top_f, bot_f)
            drawn = False
            for content, hc, by, midx in active:
                cr = cy - by
                if 0 <= cr < len(content):
                    raw = content[cr]
                    if cr != midx:
                        colored = lr_gradient([raw], grad_offset)[0]
                    else:
                        colored = raw
                    ln = vis_trunc(colored, w)
                    if row_fade < 1.0:
                        ln = fade_line(ln, row_fade)
                    if cr == midx:
                        buf.append(f"\033[{scr_row};1H{W_COOL}{ln}{RST}\033[K")
                    elif ln.strip():
                        buf.append(f"\033[{scr_row};1H{ln}{RST}\033[K")
                    else:
                        buf.append(f"\033[{scr_row};1H\033[K")
                    drawn = True
                    break
            if not drawn:
                n = _noise_at(cy)
                if row_fade < 1.0 and n:
                    n = fade_line(n, row_fade)
                if n:
                    buf.append(f"\033[{scr_row};1H{n}")
                else:
                    buf.append(f"\033[{scr_row};1H\033[K")
        # Glitch — base rate + mic-reactive spikes (ticker zone only)
        mic_excess = mic_monitor.excess
        glitch_prob = 0.32 + min(0.9, mic_excess * 0.16)
        n_hits = 4 + int(mic_excess / 2)
        ticker_buf_len = len(buf) - ticker_buf_start
        if random.random() < glitch_prob and ticker_buf_len > 0:
            for _ in range(min(n_hits, ticker_buf_len)):
                gi = random.randint(0, ticker_buf_len - 1)
                scr_row = gi + 1
                buf[ticker_buf_start + gi] = f"\033[{scr_row};1H{glitch_bar(w)}"
        if config.FIREHOSE and fh > 0:
            for fr in range(fh):
                scr_row = h - fh + fr + 1
                fline = firehose_line(items, w)
                buf.append(f"\033[{scr_row};1H{fline}\033[K")
        if msg_overlay:
            buf.extend(msg_overlay)
        sys.stdout.buffer.write("".join(buf).encode())
        sys.stdout.flush()
        # Precise frame timing
        elapsed = time.monotonic() - t0
        time.sleep(max(0, config.FRAME_DT - elapsed))
    sys.stdout.write(CLR)
    sys.stdout.flush()
--- a/engine/sources.py
+++ b/engine/sources.py
@@ -0,0 +1,115 @@
 """
 Data sources: feed URLs, poetry sources, language mappings, script fonts.
 Pure data — no logic, no dependencies.
 """
 # ─── RSS FEEDS ────────────────────────────────────────────
 FEEDS = {
    # Science & Technology
    "Nature": "https://www.nature.com/nature.rss",
    "Science Daily": "https://www.sciencedaily.com/rss/all.xml",
    "Phys.org": "https://phys.org/rss-feed/",
    "NASA": "https://www.nasa.gov/news-release/feed/",
    "Ars Technica": "https://feeds.arstechnica.com/arstechnica/index",
    "New Scientist": "https://www.newscientist.com/section/news/feed/",
    "Quanta": "https://api.quantamagazine.org/feed/",
    "BBC Science": "http://feeds.bbci.co.uk/news/science_and_environment/rss.xml",
    "MIT Tech Review": "https://www.technologyreview.com/feed/",
    # Economics & Business
    "BBC Business": "http://feeds.bbci.co.uk/news/business/rss.xml",
    "MarketWatch": "https://feeds.marketwatch.com/marketwatch/topstories/",
    "Economist": "https://www.economist.com/finance-and-economics/rss.xml",
    # World & Politics
    "BBC World": "http://feeds.bbci.co.uk/news/world/rss.xml",
    "NPR": "https://feeds.npr.org/1001/rss.xml",
    "Al Jazeera": "https://www.aljazeera.com/xml/rss/all.xml",
    "Guardian World": "https://www.theguardian.com/world/rss",
    "DW": "https://rss.dw.com/rdf/rss-en-all",
    "France24": "https://www.france24.com/en/rss",
    "ABC Australia": "https://www.abc.net.au/news/feed/2942460/rss.xml",
    "Japan Times": "https://www.japantimes.co.jp/feed/",
    "The Hindu": "https://www.thehindu.com/news/national/feeder/default.rss",
    "SCMP": "https://www.scmp.com/rss/91/feed",
    "Der Spiegel": "https://www.spiegel.de/international/index.rss",
    # Culture & Ideas
    "Guardian Culture": "https://www.theguardian.com/culture/rss",
    "Aeon": "https://aeon.co/feed.rss",
    "Smithsonian": "https://www.smithsonianmag.com/rss/latest_articles/",
    "The Marginalian": "https://www.themarginalian.org/feed/",
    "Nautilus": "https://nautil.us/feed/",
    "Wired": "https://www.wired.com/feed/rss",
    "The Conversation": "https://theconversation.com/us/articles.atom",
    "Longreads": "https://longreads.com/feed/",
    "Literary Hub": "https://lithub.com/feed/",
    "Atlas Obscura": "https://www.atlasobscura.com/feeds/latest",
 }
 # ─── POETRY / LITERATURE ─────────────────────────────────
 # Public domain via Project Gutenberg
 POETRY_SOURCES = {
    "Whitman": "https://www.gutenberg.org/cache/epub/1322/pg1322.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",
    "Pound": "https://www.gutenberg.org/cache/epub/41162/pg41162.txt",
    "Pound II": "https://www.gutenberg.org/cache/epub/51992/pg51992.txt",
    "Eliot": "https://www.gutenberg.org/cache/epub/1567/pg1567.txt",
    "Yeats": "https://www.gutenberg.org/cache/epub/38877/pg38877.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",
    "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",
    "DW": "de",
    "France24": "fr",
    "Japan Times": "ja",
    "The Hindu": "hi",
    "SCMP": "zh-cn",
    "Al Jazeera": "ar",
 }
 # ─── LOCATION → LANGUAGE ─────────────────────────────────
 LOCATION_LANGS = {
    r"\b(?:china|chinese|beijing|shanghai|hong kong|xi jinping)\b": "zh-cn",
    r"\b(?:japan|japanese|tokyo|osaka|kishida)\b": "ja",
    r"\b(?:korea|korean|seoul|pyongyang)\b": "ko",
    r"\b(?:russia|russian|moscow|kremlin|putin)\b": "ru",
    r"\b(?:saudi|dubai|qatar|egypt|cairo|arabic)\b": "ar",
    r"\b(?:india|indian|delhi|mumbai|modi)\b": "hi",
    r"\b(?:germany|german|berlin|munich|scholz)\b": "de",
    r"\b(?:france|french|paris|lyon|macron)\b": "fr",
    r"\b(?:spain|spanish|madrid)\b": "es",
    r"\b(?:italy|italian|rome|milan|meloni)\b": "it",
    r"\b(?:portugal|portuguese|lisbon)\b": "pt",
    r"\b(?:brazil|brazilian|são paulo|lula)\b": "pt",
    r"\b(?:greece|greek|athens)\b": "el",
    r"\b(?:turkey|turkish|istanbul|ankara|erdogan)\b": "tr",
    r"\b(?:iran|iranian|tehran)\b": "fa",
    r"\b(?:thailand|thai|bangkok)\b": "th",
    r"\b(?:vietnam|vietnamese|hanoi)\b": "vi",
    r"\b(?:ukraine|ukrainian|kyiv|kiev|zelensky)\b": "uk",
    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",
    "ja": "/System/Library/Fonts/ヒラギノ角ゴシック W9.ttc",
    "ko": "/System/Library/Fonts/AppleSDGothicNeo.ttc",
    "ru": "/System/Library/Fonts/Supplemental/Arial.ttf",
    "uk": "/System/Library/Fonts/Supplemental/Arial.ttf",
    "el": "/System/Library/Fonts/Supplemental/Arial.ttf",
    "he": "/System/Library/Fonts/Supplemental/Arial.ttf",
    "ar": "/System/Library/Fonts/GeezaPro.ttc",
    "fa": "/System/Library/Fonts/GeezaPro.ttc",
    "hi": "/System/Library/Fonts/Kohinoor.ttc",
    "th": "/System/Library/Fonts/ThonburiUI.ttc",
 }
 # Scripts that have no uppercase
 NO_UPPER = {"zh-cn", "ja", "ko", "ar", "fa", "hi", "th", "he"}
--- a/engine/terminal.py
+++ b/engine/terminal.py
@@ -0,0 +1,78 @@
 """
 ANSI escape codes, terminal size helpers, and text output primitives.
 No internal dependencies.
 """
 import os
 import random
 import sys
 import time
 # ─── ANSI ─────────────────────────────────────────────────
 RST = "\033[0m"
 BOLD = "\033[1m"
 DIM = "\033[2m"
 # Matrix greens
 G_HI = "\033[38;5;46m"
 G_MID = "\033[38;5;34m"
 G_LO = "\033[38;5;22m"
 G_DIM = "\033[2;38;5;34m"
 # THX-1138 sterile tones
 W_COOL = "\033[38;5;250m"
 W_DIM = "\033[2;38;5;245m"
 W_GHOST = "\033[2;38;5;238m"
 C_DIM = "\033[2;38;5;37m"
 # Terminal control
 CLR = "\033[2J\033[H"
 CURSOR_OFF = "\033[?25l"
 CURSOR_ON = "\033[?25h"
 # ─── TERMINAL SIZE ────────────────────────────────────────
 def tw():
    try:
        return os.get_terminal_size().columns
    except Exception:
        return 80
 def th():
    try:
        return os.get_terminal_size().lines
    except Exception:
        return 24
 # ─── TEXT OUTPUT ──────────────────────────────────────────
 def type_out(text, color=G_HI):
    i = 0
    while i < len(text):
        if random.random() < 0.3:
            b = random.randint(2, 5)
            sys.stdout.write(f"{color}{text[i : i + b]}{RST}")
            i += b
        else:
            sys.stdout.write(f"{color}{text[i]}{RST}")
            i += 1
        sys.stdout.flush()
        time.sleep(random.uniform(0.004, 0.018))
 def slow_print(text, color=G_DIM, delay=0.015):
    for ch in text:
        sys.stdout.write(f"{color}{ch}{RST}")
        sys.stdout.flush()
        time.sleep(delay)
 def boot_ln(label, status, ok=True):
    dots = max(3, min(30, tw() - len(label) - len(status) - 8))
    sys.stdout.write(f"  {G_DIM}>{RST} {W_DIM}{label} ")
    sys.stdout.flush()
    for _ in range(dots):
        sys.stdout.write(f"{G_LO}.")
        sys.stdout.flush()
        time.sleep(random.uniform(0.006, 0.025))
    c = G_MID if ok else "\033[2;38;5;196m"
    print(f" {c}{status}{RST}")
    time.sleep(random.uniform(0.02, 0.1))
--- a/engine/translate.py
+++ b/engine/translate.py
@@ -0,0 +1,43 @@
 """
 Google Translate wrapper and location→language detection.
 Depends on: sources (for LOCATION_LANGS).
 """
 import json
 import re
 import urllib.parse
 import urllib.request
 from engine.sources import LOCATION_LANGS
 _TRANSLATE_CACHE = {}
 def detect_location_language(title):
    """Detect if headline mentions a location, return target language."""
    title_lower = title.lower()
    for pattern, lang in LOCATION_LANGS.items():
        if re.search(pattern, title_lower):
            return lang
    return None
 def translate_headline(title, target_lang):
    """Translate headline via Google Translate API (zero dependencies)."""
    key = (title, target_lang)
    if key in _TRANSLATE_CACHE:
        return _TRANSLATE_CACHE[key]
    try:
        q = urllib.parse.quote(title)
        url = (
            "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())
        result = "".join(p[0] for p in data[0] if p[0]) or title
    except Exception:
        result = title
    _TRANSLATE_CACHE[key] = result
    return result
--- a/fonts/AgorTechnoDemo-Regular.otf
+++ b/fonts/AgorTechnoDemo-Regular.otf
--- a/fonts/AlphatronDemo-Display.otf
+++ b/fonts/AlphatronDemo-Display.otf
--- a/fonts/CSBishopDrawn-Italic.otf
+++ b/fonts/CSBishopDrawn-Italic.otf
--- a/fonts/CSBishopDrawn-Italic.ttf
+++ b/fonts/CSBishopDrawn-Italic.ttf
--- a/fonts/CSBishopDrawn-Regular.otf
+++ b/fonts/CSBishopDrawn-Regular.otf
--- a/fonts/CSBishopDrawn-Regular.ttf
+++ b/fonts/CSBishopDrawn-Regular.ttf
--- a/fonts/Corptic
+++ b/fonts/Corptic
--- a/fonts/CubaTechnologyDemo-Regular.otf
+++ b/fonts/CubaTechnologyDemo-Regular.otf
--- a/fonts/CyberformDemo-Oblique.otf
+++ b/fonts/CyberformDemo-Oblique.otf
--- a/fonts/CyberformDemo.otf
+++ b/fonts/CyberformDemo.otf
--- a/fonts/Eyekons.otf
+++ b/fonts/Eyekons.otf
--- a/fonts/KATA
+++ b/fonts/KATA
--- a/fonts/KATA
+++ b/fonts/KATA
--- a/fonts/KATA.otf
+++ b/fonts/KATA.otf
--- a/fonts/KATA.ttf
+++ b/fonts/KATA.ttf
--- a/fonts/Microbots
+++ b/fonts/Microbots
--- a/fonts/ModernSpaceDemo-Regular.otf
+++ b/fonts/ModernSpaceDemo-Regular.otf
--- a/fonts/Neoform-Demo.otf
+++ b/fonts/Neoform-Demo.otf
--- a/fonts/Pixel
+++ b/fonts/Pixel
--- a/fonts/RaceHugoDemo-Regular.otf
+++ b/fonts/RaceHugoDemo-Regular.otf
--- a/fonts/Resond-Regular.otf
+++ b/fonts/Resond-Regular.otf
--- a/fonts/Robocops-Demo.otf
+++ b/fonts/Robocops-Demo.otf
--- a/fonts/Synthetix.otf
+++ b/fonts/Synthetix.otf
--- a/fonts/Xeonic.ttf
+++ b/fonts/Xeonic.ttf
--- a/hk.pkl
+++ b/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/"
            }
        }
    }
 }
--- a/mainline.py
+++ b/mainline.py
--- a/mise.toml
+++ b/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"
--- a/pyproject.toml
+++ b/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"]
--- a/requirements-dev.txt
+++ b/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
--- a/requirements.txt
+++ b/requirements.txt
@@ -0,0 +1,4 @@
 feedparser>=6.0.0
 Pillow>=10.0.0
 sounddevice>=0.4.0
 numpy>=1.24.0
--- a/tests/init.py
+++ b/tests/init.py
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -0,0 +1,162 @@
 """
 Tests for engine.config module.
 """
 import sys
 import tempfile
 from pathlib import Path
 from unittest.mock import patch
 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
--- a/tests/test_filter.py
+++ b/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
--- a/tests/test_mic.py
+++ b/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
--- a/tests/test_ntfy.py
+++ b/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
--- a/tests/test_sources.py
+++ b/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
--- a/tests/test_terminal.py
+++ b/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
Author	SHA1	Message	Date
Gene Johnson	ae10fd78ca	refactor: Restructure README, add `uv` and `mise` commands, and detail component extension and development workflows.	2026-03-15 17:08:32 -07:00
Gene Johnson	4afab642f7	docs: add README update design spec Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-03-15 16:56:58 -07:00
genewildish	f6f177590b	Merge pull request 'Modernize project with uv, pytest, ruff, and git hooks' (#21 ) from enhance_portability into main Reviewed-on: #21	2026-03-15 23:21:35 +00:00
David Gwilliam	9ae4dc2b07	fix: update ntfy tests for SSE API (reconnect_delay)	2026-03-15 15:16:37 -07:00
David Gwilliam	1ac2dec3b0	fix: use native hk staging in pre-commit hook fix: add explicit check command to pre-push hook	2026-03-15 15:16:37 -07:00
David Gwilliam	757c854584	fix: apply ruff auto-fixes and add hk git hooks - Fix pre-existing lint errors in engine/ modules using ruff --unsafe-fixes - Add hk.pkl with pre-commit and pre-push hooks using ruff builtin - Configure hooks to use 'uv run' prefix for tool execution - Update mise.toml to include hk and pkl tools - All 73 tests pass fix: apply ruff auto-fixes and add hk git hooks - Fix pre-existing lint errors in engine/ modules using ruff --unsafe-fixes - Add hk.pkl with pre-commit and pre-push hooks using ruff builtin - Configure hooks to use 'uv run' prefix for tool execution - Update mise.toml to include hk and pkl tools - Use 'hk install --mise' for proper mise integration - All 73 tests pass	2026-03-15 15:16:37 -07:00
David Gwilliam	4844a64203	style: apply ruff auto-fixes across codebase - Fix import sorting (isort) across all engine modules - Fix SIM105 try-except-pass patterns (contextlib.suppress) - Fix nested with statements in tests - Fix unused loop variables Run 'uv run pytest' to verify tests still pass.	2026-03-15 15:16:37 -07:00
David Gwilliam	9201117096	feat: modernize project with uv, add pytest test suite - Add pyproject.toml with modern Python packaging (PEP 517/518) - Add uv-based dependency management replacing inline venv bootstrap - Add requirements.txt and requirements-dev.txt for compatibility - Add mise.toml with dev tasks (test, lint, run, sync, ci) - Add .python-version pinned to Python 3.12 - Add comprehensive pytest test suite (73 tests) for: - engine/config, filter, terminal, sources, mic, ntfy modules - Configure pytest with coverage reporting (16% total, 100% on tested modules) - Configure ruff for linting with Python 3.10+ target - Remove redundant venv bootstrap code from mainline.py - Update .gitignore for uv/venv artifacts Run 'uv sync' to install dependencies, 'uv run pytest' to test.	2026-03-15 15:16:37 -07:00
genewildish	d758541156	Merge pull request 'feat: migrate Ntfy message retrieval from polling to SSE streaming, replacing `poll_interval` with `reconnect_delay` for continuous updates.' (#20 ) from feat/ntfy-sse into main Reviewed-on: #20	2026-03-15 20:50:08 +00:00
genewildish	b979621dd4	Merge branch 'main' into feat/ntfy-sse	2026-03-15 20:50:02 +00:00
genewildish	f91cc9844e	Merge pull request 'feat: add new font files to the fonts directory' (#19 ) from feat/display into main Reviewed-on: #19	2026-03-15 20:47:16 +00:00
genewildish	bddbd69371	Merge branch 'main' into feat/display	2026-03-15 20:45:54 +00:00
Gene Johnson	6e39a2dad2	feat: migrate Ntfy message retrieval from polling to SSE streaming, replacing `poll_interval` with `reconnect_delay` for continuous updates.	2026-03-15 13:44:26 -07:00
Gene Johnson	1ba3848bed	feat: add new font files to the fonts directory	2026-03-15 13:30:08 -07:00
genewildish	a986df344a	Merge pull request 'doc: Document new font selection command-line arguments, environment variables, and a dedicated font management section.' (#18 ) from docs/update-readme into main Reviewed-on: #18	2026-03-15 11:08:25 +00:00
Gene Johnson	c84bd5c05a	doc: Document new font selection command-line arguments, environment variables, and a dedicated font management section.	2026-03-15 04:07:24 -07:00
genewildish	7b0f886e53	Merge pull request 'feat: add new font assets including CSBishopDrawn, CyberformDemo, and KATA.' (#17 ) from feat/font-picker into main Reviewed-on: #17	2026-03-15 11:01:39 +00:00
genewildish	9eeb817dca	Merge branch 'main' into feat/font-picker	2026-03-15 11:01:31 +00:00
Gene Johnson	ac80ab23cc	feat: add new font assets including CSBishopDrawn, CyberformDemo, and KATA.	2026-03-15 04:01:06 -07:00
genewildish	516123345e	Merge pull request 'feat/font-picker' (#16 ) from feat/font-picker into main Reviewed-on: #16	2026-03-15 10:53:16 +00:00
Gene Johnson	11226872a1	feat: Implement interactive font selection by scanning the `fonts/` directory for `.otf`, `.ttf`, and `.ttc` files, adding new fonts and updating documentation.	2026-03-15 03:52:10 -07:00
Gene Johnson	e6826c884c	feat: Implement an interactive font face picker at startup, allowing selection of specific font faces from a font file.	2026-03-15 03:38:14 -07:00
genewildish	0740e34293	Merge pull request 'style: Replace escaped parentheses with standard parentheses in the Mainline Renderer documentation.' (#15 ) from feat/scalability into main Reviewed-on: #15	2026-03-15 10:03:42 +00:00
genewildish	1e99d70387	Merge branch 'main' into feat/scalability	2026-03-15 10:03:34 +00:00
genewildish	7098b2f5aa	Merge pull request 'feat: Introduce a complementary color gradient for queue messages.' (#14 ) from feat/display into main Reviewed-on: #14	2026-03-15 10:01:57 +00:00
Gene Johnson	e7de09be50	style: Replace escaped parentheses with standard parentheses in the Mainline Renderer documentation.	2026-03-15 02:58:38 -07:00
Gene Johnson	9140bfd32b	feat: Introduce a complementary color gradient for queue messages.	2026-03-15 02:44:38 -07:00
genewildish	c49c0aab33	Merge pull request 'refactor: Change firehose from a drifting overlay to a fixed bottom strip and message display from a top-pinned section to a centered overlay.' (#13 ) from drift into main Reviewed-on: #13	2026-03-15 09:27:16 +00:00
Gene Johnson	66c13b5829	refactor: Change firehose from a drifting overlay to a fixed bottom strip and message display from a top-pinned section to a centered overlay.	2026-03-15 02:26:44 -07:00
genewildish	089c8ed66a	Merge pull request 'drift' (#12 ) from drift into main Reviewed-on: #12	2026-03-15 08:33:48 +00:00
Gene Johnson	086214f05e	style: remove firehose opaque row backdrop and background color	2026-03-15 01:31:44 -07:00
Gene Johnson	0f762475b5	feat: Apply a distinct background color to firehose lines.	2026-03-15 01:08:17 -07:00
Gene Johnson	b00b612da0	refactor: rename rendering components and variables for clarity, distinguishing between message, ticker, and scroll motion layers.	2026-03-15 00:58:36 -07:00
Gene Johnson	39dab4b22b	feat: Implement a drifting firehose overlay that scrolls independently over the main ticker content.	2026-03-15 00:49:58 -07:00
genewildish	47f17e12ef	Merge pull request 'docs: Add ntfy.sh integration details, new CLI options, expanded configuration, and architecture overview to README.' (#11 ) from docs/update-readme into main Reviewed-on: #11	2026-03-15 07:19:14 +00:00
Gene Johnson	851c4a77b4	docs: Add ntfy.sh integration details, new CLI options, expanded configuration, and architecture overview to README.	2026-03-15 00:17:05 -07:00
genewildish	cdbb6dfd1c	Merge pull request 'feat/scalability' (#10 ) from feat/scalability into main Reviewed-on: #10	2026-03-15 06:50:11 +00:00
genewildish	45a202e955	Merge branch 'main' into feat/scalability	2026-03-15 06:50:02 +00:00
Gene Johnson	339510dd60	Please provide the diff for `/Users/genejohnson/Dev/mainline/mainline.py` to generate an accurate commit message.	2026-03-14 23:46:31 -07:00
Gene Johnson	9bd8115c55	feat: introduce the scroll engine with a main rendering loop for headlines, messages, and visual effects.	2026-03-14 23:36:56 -07:00
Gene Johnson	2c777729f5	feat: Introduce ntfy.sh message polling, content fetching with caching, and microphone input monitoring.	2026-03-14 23:34:23 -07:00
genewildish	0e500d1b71	Merge pull request 'feat/display' (#9 ) from feat/display into main Reviewed-on: #9	2026-03-15 06:25:57 +00:00
genewildish	3571e2780b	Merge branch 'main' into feat/display	2026-03-15 06:25:49 +00:00
Gene Johnson	dfd902fb90	feat: add module for fetching RSS feeds, parsing Project Gutenberg texts, and caching headlines	2026-03-14 22:51:50 -07:00
Gene Johnson	2e6b2c48bd	feat: Introduce visual effects module, enhance text rendering with SSAA, and add shifting gradient support.	2026-03-14 22:15:48 -07:00
Gene Johnson	1ff2e54586	Merge remote-tracking branch 'origin/feat/display' into feat/scalability	2026-03-14 22:06:35 -07:00
Gene Johnson	424332e065	feat: Implement a top-pinned ntfy message banner that reduces scrollable area instead of freezing the display.	2026-03-14 22:02:28 -07:00
Gene Johnson	f6ad89769f	feat: Implement OTF to terminal half-block rendering pipeline including font loading, text rasterization, word-wrap, and gradient coloring.	2026-03-14 21:53:47 -07:00
Gene Johnson	d3c403848c	feat: Introduce `translate` module for Google Translate integration and location-based language detection, and add a new `filter` module.	2026-03-14 21:00:24 -07:00
Gene Johnson	119ed193c0	feat: Add terminal module.	2026-03-14 20:57:53 -07:00
Gene Johnson	dcc3718012	refactor: Create `engine` package, extracting data sources to `sources.py`, and add refactoring documentation.	2026-03-14 20:56:24 -07:00
genewildish	2e69cad984	Merge pull request 'feat/display' (#8 ) from feat/display into main Reviewed-on: #8	2026-03-15 02:42:50 +00:00
Gene Johnson	7274f57bbb	feat: Implement super-sampling for text rendering and adjust `_RENDER_H` from 16 to 8.	2026-03-14 19:21:24 -07:00
Gene Johnson	c857d7bd81	feat: implement dynamic shifting gradients for messages and scrolling content, and adjust rendering parameters	2026-03-14 19:15:55 -07:00
genewildish	6a5a73fd88	Merge pull request 'feat/mod_poetry' (#7 ) from feat/mod_poetry into main Reviewed-on: #7	2026-03-15 02:06:55 +00:00
Gene Johnson	5474c58ce0	Remove Thoreau and Emerson from poetry sources.	2026-03-14 19:05:25 -07:00
Gene Johnson	571da4fa47	feat: Add several new authors and their text sources to the `TEXTS` dictionary.	2026-03-14 19:03:38 -07:00
genewildish	6d7ab770cd	Merge pull request 'feat/ntfy-local' (#6 ) from feat/ntfy-local into main Reviewed-on: #6	2026-03-15 01:42:14 +00:00
		`@@ -0,0 +1 @@`
							`# engine — modular internals for mainline`