feat(benchmark): add hook mode with baseline cache for pre-push checks

- Fix lint errors and LSP issues in benchmark.py - Add --hook mode to compare against saved baseline - Add --baseline flag to save results as baseline - Add --threshold to configure degradation threshold (default 20%) - Add benchmark step to pre-push hook in hk.pkl - Update AGENTS.md with hk documentation links and benchmark runner docs
refactor: modularize display backends and add benchmark runner
2026-03-15 22:57:55 -07:00 · 2026-03-15 22:25:28 -07:00 · 2026-03-15 22:13:44 -07:00 · 2026-03-15 21:55:26 -07:00 · 2026-03-15 21:47:53 -07:00 · 2026-03-15 21:17:16 -07:00
25 changed files with 3198 additions and 452 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,43 +16,33 @@ This project uses:
 mise run install

 # Or equivalently:
-uv sync
+uv sync --all-extras   # includes mic, websocket, sixel support
 ```

 ### Available Commands

 ```bash
-# Development
-mise run test       # Run tests
-mise run test-v     # Run tests verbose
-mise run test-cov   # Run tests with coverage report
-mise run lint       # Run ruff linter
-mise run lint-fix   # Run ruff with auto-fix
-mise run format     # Run ruff formatter
-mise run ci         # Full CI pipeline
+mise run test           # Run tests
+mise run test-v         # Run tests verbose
+mise run test-cov       # Run tests with coverage report
+mise run test-browser   # Run e2e browser tests (requires playwright)
+mise run lint           # Run ruff linter
+mise run lint-fix       # Run ruff with auto-fix
+mise run format         # Run ruff formatter
+mise run ci             # Full CI pipeline (topics-init + lint + test-cov)
+```

-# Runtime
-mise run run        # Interactive terminal mode (news)
-mise run run-poetry # Interactive terminal mode (poetry)
-mise run run-firehose # Dense headline mode
+### Runtime Commands

-# Daemon mode (recommended for long-running)
-mise run daemon         # Start mainline in background
-mise run daemon-stop    # Stop daemon
-mise run daemon-restart # Restart daemon
-
-# Command & Control
-mise run cmd           # Interactive CLI
-mise run cmd "/cmd"    # Send single command
-mise run cmd-stats     # Watch performance stats
-mise run topics-init   # Initialize ntfy topics
-
-# Environment
-mise run install       # Install dependencies
-mise run sync          # Sync dependencies
-mise run sync-all      # Sync with all extras
-mise run clean         # Clean cache files
-mise run clobber       # Aggressive cleanup (git clean -fdx + caches)
+```bash
+mise run run            # Run mainline (terminal)
+mise run run-poetry    # Run with poetry feed
+mise run run-firehose  # Run in firehose mode
+mise run run-websocket # Run with WebSocket display only
+mise run run-sixel     # Run with Sixel graphics display
+mise run run-both      # Run with both terminal and WebSocket
+mise run run-client    # Run both + open browser
+mise run cmd           # Run C&C command interface
 ```

 ## Git Hooks
@@ -70,9 +60,52 @@ hk init --mise
 mise run pre-commit
 ```

+**IMPORTANT**: Always review the hk documentation before modifying `hk.pkl`:
+- [hk Configuration Guide](https://hk.jdx.dev/configuration.html)
+- [hk Hooks Reference](https://hk.jdx.dev/hooks.html)
+- [hk Builtins](https://hk.jdx.dev/builtins.html)
+
 The project uses hk configured in `hk.pkl`:
 - **pre-commit**: runs ruff-format and ruff (with auto-fix)
- **pre-push**: runs ruff check
+- **pre-push**: runs ruff check + benchmark hook
+
+## Benchmark Runner
+
+Run performance benchmarks:
+
+```bash
+mise run benchmark           # Run all benchmarks (text output)
+mise run benchmark-json     # Run benchmarks (JSON output)
+mise run benchmark-report   # Run benchmarks (Markdown report)
+```
+
+### Benchmark Commands
+
+```bash
+# Run benchmarks
+uv run python -m engine.benchmark
+
+# Run with specific displays/effects
+uv run python -m engine.benchmark --displays null,terminal --effects fade,glitch
+
+# Save baseline for hook comparisons
+uv run python -m engine.benchmark --baseline
+
+# Run in hook mode (compares against baseline)
+uv run python -m engine.benchmark --hook
+
+# Hook mode with custom threshold (default: 20% degradation)
+uv run python -m engine.benchmark --hook --threshold 0.3
+
+# Custom baseline location
+uv run python -m engine.benchmark --hook --cache /path/to/cache.json
+```
+
+### Hook Mode
+
+The `--hook` mode compares current benchmarks against a saved baseline. If performance degrades beyond the threshold (default 20%), it exits with code 1. This is useful for preventing performance regressions in feature branches.
+
+The pre-push hook runs benchmark in hook mode to catch performance regressions before pushing.

 ## Workflow Rules

@@ -130,138 +163,32 @@ The project uses pytest with strict marker enforcement. Test configuration is in

 - **ntfy.py** and **mic.py** are standalone modules with zero internal dependencies
 - **eventbus.py** provides thread-safe event publishing for decoupled communication
- **controller.py** coordinates ntfy/mic monitoring
+- **controller.py** coordinates ntfy/mic monitoring and event publishing
+- **effects/** - plugin architecture with performance monitoring
 - The render pipeline: fetch → render → effects → scroll → terminal output
- **display.py** provides swappable display backends (TerminalDisplay, NullDisplay)

-## Operating Modes
+### Display System

-Mainline can run in two modes:
+- **Display abstraction** (`engine/display.py`): swap display backends via the Display protocol
+  - `TerminalDisplay` - ANSI terminal output
+  - `WebSocketDisplay` - broadcasts to web clients via WebSocket
+  - `SixelDisplay` - renders to Sixel graphics (pure Python, no C dependency)
+  - `MultiDisplay` - forwards to multiple displays simultaneously

-### 1. Standalone Mode (Original)
-Run directly as a terminal application with interactive pickers:
-```bash
-mise run run              # news stream
-mise run run-poetry       # poetry mode
-mise run run-firehose     # dense headline mode
-```
-This runs the full interactive experience with font picker and effects picker at startup.
+- **WebSocket display** (`engine/websocket_display.py`): real-time frame broadcasting to web browsers
+  - WebSocket server on port 8765
+  - HTTP server on port 8766 (serves HTML client)
+  - Client at `client/index.html` with ANSI color parsing and fullscreen support

-### 2. Daemon + Command Mode (Recommended for Long-Running)
+- **Display modes** (`--display` flag):
+  - `terminal` - Default ANSI terminal output
+  - `websocket` - Web browser display (requires websockets package)
+  - `sixel` - Sixel graphics in supported terminals (iTerm2, mintty, etc.)
+  - `both` - Terminal + WebSocket simultaneously

-The recommended approach for persistent displays:
+### Command & Control

-```bash
-# Start the daemon (headless rendering)
-mise run daemon
-
-# Send commands via ntfy
-mise run cmd "/effects list"
-mise run cmd "/effects noise off"
-mise run cmd "/effects stats"
-
-# Watch mode (continuous stats polling)
-mise run cmd-stats
-
-# Stop the daemon
-mise run daemon-stop
-```
-
-#### How It Works
-
- **Daemon**: Runs `mainline.py` in the background, renders to terminal
- **C&C Topics**: Uses separate ntfy topics (like UART serial):
-  - `klubhaus_terminal_mainline_cc_cmd` - commands TO mainline
-  - `klubhaus_terminal_mainline_cc_resp` - responses FROM mainline
- **Topics are auto-warmed** on first daemon start
-
-#### Available Commands
-
-```
-/effects list                    - List all effects and status
-/effects <name> on             - Enable an effect
-/effects <name> off            - Disable an effect
-/effects <name> intensity 0.5  - Set effect intensity (0.0-1.0)
-/effects reorder noise,fade,glitch,firehose - Reorder pipeline
-/effects stats                  - Show performance statistics
-```
-
-## Effects Plugin System
-
-The effects system is implemented as a plugin architecture in `engine/effects/`.
-
-### Core Components
-
-| Module | Purpose |
-|--------|---------|
-| `effects/types.py` | `EffectConfig`, `EffectContext` dataclasses and `EffectPlugin` protocol |
-| `effects/registry.py` | Plugin discovery and management (`EffectRegistry`) |
-| `effects/chain.py` | Ordered pipeline execution (`EffectChain`) |
-| `effects_plugins/*.py` | Externalized effect plugins |
-
-### Creating a New Effect
-
-Create a file in `effects_plugins/` with a class ending in `Effect`:
-
-```python
-from engine.effects.types import EffectConfig, EffectContext
-
-class MyEffect:
-    name = "myeffect"
-    config = EffectConfig(enabled=True, intensity=1.0)
-    
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        # Process buffer and return modified buffer
-        return buf
-    
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config
-```
-
-### NTFY Commands
-
-Send commands via `cmdline.py` or directly to the C&C topic:
-
-```bash
-# Using cmdline tool (recommended)
-mise run cmd "/effects list"
-mise run cmd "/effects noise on"
-mise run cmd "/effects noise intensity 0.5"
-mise run cmd "/effects reorder noise,glitch,fade,firehose"
-
-# Or directly via curl
-curl -d "/effects list" https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd
-```
-
-The cmdline tool polls the response topic for the daemon's reply.
-
-## Conventional Commits
-
-Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
-
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-### Types
-
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that don't affect code meaning (formatting)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `test`: Adding or updating tests
- `chore`: Changes to build process, dependencies, etc.
-
-### Examples
-
-```
-feat(effects): add plugin architecture for visual effects
-fix(layers): resolve glitch effect not applying on empty buffer
-docs(AGENTS.md): add effects plugin system documentation
-test(effects): add tests for EffectChain pipeline ordering
-```
+- C&C uses separate ntfy topics for commands and responses
+- `NTFY_CC_CMD_TOPIC` - commands from cmdline.py
+- `NTFY_CC_RESP_TOPIC` - responses back to cmdline.py
+- Effects controller handles `/effects` commands (list, on/off, intensity, reorder, stats)
--- a/README.md
+++ b/README.md
@@ -6,65 +6,45 @@ A full-screen terminal news ticker that renders live global headlines in large O

 ---

-## 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 --display websocket  # web browser display only
+python3 mainline.py --display both       # terminal + web browser
 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, loading from cache.
-
---
-
-## Daemon Mode (Recommended for Long-Running)
-
-For persistent displays (e.g., always-on terminal), use daemon mode with command-and-control over ntfy:
+Or with uv:

 ```bash
-# Start the daemon (runs in background, auto-warms ntfy topics)
-mise run daemon
-
-# Send commands via cmdline
-mise run cmd "/effects list"
-mise run cmd "/effects noise off"
-mise run cmd "/effects noise intensity 0.5"
-
-# Watch performance stats continuously
-mise run cmd-stats
-
-# Stop the daemon
-mise run daemon-stop
+uv run mainline.py
 ```

-### How It Works
+First run bootstraps dependencies. Use `uv sync --all-extras` for mic support.

- **Topics**: Uses separate ntfy topics for serial-like communication:
-  - `klubhaus_terminal_mainline_cc_cmd` - commands TO mainline
-  - `klubhaus_terminal_mainline_cc_resp` - responses FROM mainline
- Topics are automatically created on first daemon start
+### Command & Control (C&C)

-### Available Commands
+Control mainline remotely using `cmdline.py`:

-```
-/effects list                    - List all effects and status
-/effects <name> on             - Enable an effect
-/effects <name> off            - Disable an effect
-/effects <name> intensity 0.5  - Set effect intensity (0.0-1.0)
-/effects reorder noise,fade,glitch,firehose - Reorder pipeline
-/effects stats                  - Show performance statistics
+```bash
+uv run cmdline.py                    # Interactive TUI
+uv run cmdline.py /effects list      # List all effects
+uv run cmdline.py /effects stats     # Show performance stats
+uv run cmdline.py -w /effects stats  # Watch mode (auto-refresh)
 ```

---
+Commands are sent via ntfy.sh topics - useful for controlling a daemonized mainline instance.

-## Config
+### Config

 All constants live in `engine/config.py`:

@@ -73,98 +53,49 @@ All constants live in `engine/config.py`:
 | `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 |
+| `NTFY_TOPIC` | klubhaus URL | ntfy.sh JSON stream for messages |
+| `NTFY_CC_CMD_TOPIC` | klubhaus URL | ntfy.sh topic for C&C commands |
+| `NTFY_CC_RESP_TOPIC` | klubhaus URL | ntfy.sh topic for C&C responses |
+| `NTFY_RECONNECT_DELAY` | `5` | Seconds before reconnecting after dropped SSE |
+| `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen |
 | `FONT_DIR` | `fonts/` | Folder scanned for `.otf`, `.ttf`, `.ttc` files |
-| `FONT_PATH` | first file in `FONT_DIR` | Active display font (overridden by picker or `--font-file`) |
-| `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_PATH` | first file in `FONT_DIR` | Active display font |
+| `FONT_PICKER` | `True` | Show interactive font picker at boot |
 | `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) |
+| `SSAA` | `4` | Super-sampling factor |
 | `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 endpoint to poll |
-| `NTFY_POLL_INTERVAL` | `15` | Seconds between ntfy polls |
-| `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen |
+| `GRAD_SPEED` | `0.08` | Gradient sweep speed |

---
+### Display Modes

-## Fonts
+Mainline supports multiple display backends:

-A `fonts/` directory is bundled with demo faces (AlphatronDemo, CSBishopDrawn, CyberformDemo, KATA, Microbots, Neoform, Pixel Sparta, Robocops, Xeonic, and others). On startup, an interactive picker lists all discovered faces with a live half-block preview rendered at your configured size.
+- **Terminal** (`--display terminal`): ANSI terminal output (default)
+- **WebSocket** (`--display websocket`): Stream to web browser clients
+- **Both** (`--display both`): Terminal + WebSocket simultaneously

-Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selected face persists for that session.
+WebSocket mode serves a web client at http://localhost:8766 with ANSI color support and fullscreen mode.

-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.
-
---
-
-## How it works
-
- On launch, the font picker scans `fonts/` and presents a live-rendered TUI for face selection; `--no-font-picker` skips directly to stream
- Feeds are fetched and filtered on startup (sports and vapid content stripped); results are cached to `.mainline_cache_news.json` / `.mainline_cache_poetry.json` for fast restarts
- 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 poller 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/
-  __init__.py       package marker
-  app.py            main(), font picker TUI, boot sequence, signal handler
-  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/          plugin-based effects system
-    types.py        EffectConfig, EffectContext, EffectPlugin protocol
-    registry.py     Plugin discovery and management
-    chain.py        Ordered pipeline execution
-    performance.py  Performance monitoring
-    controller.py   NTFY command handler
-    legacy.py       Original effects (noise, glitch, fade, firehose)
-  effects_plugins/  External effect plugins (noise, glitch, fade, firehose)
-  display.py        Swappable display backends (TerminalDisplay, NullDisplay)
-  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
-  viewport.py       terminal dimension tracking (tw/th)
-  frame.py          scroll step calculation, timing
-  layers.py         ticker zone, firehose, message overlay rendering
-  eventbus.py       thread-safe event publishing for decoupled communication
-  events.py          event types and definitions
-  controller.py     coordinates ntfy/mic monitoring and event publishing
-  emitters.py       background emitters for ntfy and mic
-  types.py          type definitions and dataclasses
-```
-
-`ntfy.py` and `mic.py` have zero internal dependencies and can be imported by any other visualizer.
-
---
-
-## Feeds
+### 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

-## ntfy.sh Integration
+A `fonts/` directory is bundled with demo faces. On startup, an interactive picker lists all discovered faces with a live half-block preview.

-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.
+Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select.
+
+To add your own fonts, drop `.otf`, `.ttf`, or `.ttc` files into `fonts/`.
+
+### 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.

 To push a message:

@@ -172,44 +103,127 @@ To push a message:
 curl -d "Body text" -H "Title: Alert title" https://ntfy.sh/your_topic
 ```

-Update `NTFY_TOPIC` in `engine/config.py` to point at your own topic. The `NtfyPoller` class is fully standalone and can be reused by other visualizers:
+---

-```python
-from engine.ntfy import NtfyPoller
-poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1")
-poller.start()
-# in render loop:
-msg = poller.get_active_message()  # returns (title, body, timestamp) or None
+## Internals
+
+### How it works
+
+- On launch, the font picker scans `fonts/` and presents a live-rendered TUI for face selection
+- Feeds are fetched and filtered on startup; results are cached for fast restarts
+- Headlines are rasterized via Pillow with 4× SSAA into half-block characters
+- The ticker uses a sweeping white-hot → deep green gradient
+- Subject-region detection triggers Google Translate and font swap for non-Latin scripts
+- The mic stream runs in a background thread, feeding RMS dB into glitch probability
+- The viewport scrolls through pre-rendered blocks with fade zones
+- An ntfy.sh SSE stream runs in a background thread for messages and C&C commands
+
+### Architecture
+
+```
+engine/
+  __init__.py           package marker
+  app.py                main(), font picker TUI, boot sequence, C&C poller
+  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/              plugin architecture for visual effects
+    controller.py       handles /effects commands
+    chain.py            effect pipeline chaining
+    registry.py         effect registration and lookup
+    performance.py      performance monitoring
+  fetch.py              RSS/Gutenberg fetching + cache
+  ntfy.py               NtfyPoller — standalone, zero internal deps
+  mic.py                MicMonitor — standalone, graceful fallback
+  scroll.py             stream() frame loop + message rendering
+  viewport.py           terminal dimension tracking
+  frame.py              scroll step calculation, timing
+  layers.py             ticker zone, firehose, message overlay
+  eventbus.py           thread-safe event publishing
+  events.py             event types and definitions
+  controller.py         coordinates ntfy/mic monitoring
+  emitters.py           background emitters
+  types.py              type definitions
+  display.py            Display protocol (Terminal, WebSocket, Multi)
+  websocket_display.py  WebSocket server for browser clients
 ```

 ---

-## Ideas / Future
+## Development

-### Performance
- **Concurrent feed fetching** — startup currently blocks sequentially on ~25 HTTP requests; `concurrent.futures.ThreadPoolExecutor` would cut load time to the slowest single feed
- **Background refresh** — re-fetch feeds in a daemon thread so a long session stays current without restart
- **Translation pre-fetch** — run translate calls concurrently during the boot sequence rather than on first render
+### Setup

-### Graphics
- **Matrix rain underlay** — katakana column rain rendered at low opacity beneath the scrolling blocks as a background layer
- **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
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

-### Cyberpunk Vibes
- **Keyword watch list** — highlight or strobe any headline matching tracked terms (names, topics, tickers)
- **Breaking interrupt** — full-screen flash + synthesized blip when a high-priority keyword hits
- **Live data overlay** — secondary ticker strip at screen edge: BTC price, ISS position, geomagnetic index
- **Theme switcher** — `--amber` (phosphor), `--ice` (electric cyan), `--red` (alert state) palette modes via CLI flag
- **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
+```bash
+uv sync                              # minimal (no mic)
+uv sync --all-extras                 # with mic support
+uv sync --all-extras --group dev     # full dev environment
+```

-### 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
+### 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             # terminal display
+mise run run-websocket   # web display only
+mise run run-both        # terminal + web
+mise run run-client      # both + open browser
+
+mise run cmd             # C&C command interface
+mise run cmd-stats       # watch effects stats
+mise run topics-init     # initialize ntfy topics
+```
+
+### Testing
+
+```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`.

 ---

-*macOS only (script/system font paths for translation are hardcoded). Primary display font is user-selectable via the bundled `fonts/` picker. Python 3.9+.*
-# test
+## Roadmap
+
+### Performance
+- Concurrent feed fetching with ThreadPoolExecutor
+- Background feed refresh daemon
+- Translation pre-fetch during boot
+
+### Graphics
+- Matrix rain katakana underlay
+- CRT scanline simulation
+- Sixel/iTerm2 inline images
+- Parallax secondary column
+
+### Cyberpunk Vibes
+- Keyword watch list with strobe effects
+- Breaking interrupt with synthesized audio
+- Live data overlay (BTC, ISS position)
+- Theme switcher (amber, ice, red)
+- Persona modes (surveillance, oracle, underground)
+
+---
+
+*Python 3.10+. Primary display font is user-selectable via bundled `fonts/` picker.*
--- a/client/index.html
+++ b/client/index.html
@@ -0,0 +1,366 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Mainline Terminal</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        body {
+            background: #0a0a0a;
+            color: #ccc;
+            font-family: 'Fira Code', 'Cascadia Code', 'Consolas', monospace;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+            padding: 20px;
+        }
+        body.fullscreen {
+            padding: 0;
+        }
+        body.fullscreen #controls {
+            display: none;
+        }
+        #container {
+            position: relative;
+        }
+        canvas {
+            background: #000;
+            border: 1px solid #333;
+            image-rendering: pixelated;
+            image-rendering: crisp-edges;
+        }
+        body.fullscreen canvas {
+            border: none;
+            width: 100vw;
+            height: 100vh;
+            max-width: 100vw;
+            max-height: 100vh;
+        }
+        #controls {
+            display: flex;
+            gap: 10px;
+            margin-top: 10px;
+            align-items: center;
+        }
+        #controls button {
+            background: #333;
+            color: #ccc;
+            border: 1px solid #555;
+            padding: 5px 12px;
+            cursor: pointer;
+            font-family: inherit;
+            font-size: 12px;
+        }
+        #controls button:hover {
+            background: #444;
+        }
+        #controls input {
+            width: 60px;
+            background: #222;
+            color: #ccc;
+            border: 1px solid #444;
+            padding: 4px 8px;
+            font-family: inherit;
+            text-align: center;
+        }
+        #status {
+            margin-top: 10px;
+            font-size: 12px;
+            color: #666;
+        }
+        #status.connected {
+            color: #4f4;
+        }
+        #status.disconnected {
+            color: #f44;
+        }
+    </style>
+</head>
+<body>
+    <div id="container">
+        <canvas id="terminal"></canvas>
+    </div>
+    <div id="controls">
+        <label>Cols: <input type="number" id="cols" value="80" min="20" max="200"></label>
+        <label>Rows: <input type="number" id="rows" value="24" min="10" max="60"></label>
+        <button id="apply">Apply</button>
+        <button id="fullscreen">Fullscreen</button>
+    </div>
+    <div id="status" class="disconnected">Connecting...</div>
+
+    <script>
+        const canvas = document.getElementById('terminal');
+        const ctx = canvas.getContext('2d');
+        const status = document.getElementById('status');
+        const colsInput = document.getElementById('cols');
+        const rowsInput = document.getElementById('rows');
+        const applyBtn = document.getElementById('apply');
+        const fullscreenBtn = document.getElementById('fullscreen');
+
+        const CHAR_WIDTH = 9;
+        const CHAR_HEIGHT = 16;
+
+        const ANSI_COLORS = {
+            0: '#000000', 1: '#cd3131', 2: '#0dbc79', 3: '#e5e510',
+            4: '#2472c8', 5: '#bc3fbc', 6: '#11a8cd', 7: '#e5e5e5',
+            8: '#666666', 9: '#f14c4c', 10: '#23d18b', 11: '#f5f543',
+            12: '#3b8eea', 13: '#d670d6', 14: '#29b8db', 15: '#ffffff',
+        };
+
+        let cols = 80;
+        let rows = 24;
+        let ws = null;
+
+        function resizeCanvas() {
+            canvas.width = cols * CHAR_WIDTH;
+            canvas.height = rows * CHAR_HEIGHT;
+        }
+
+        function parseAnsi(text) {
+            if (!text) return [];
+            
+            const tokens = [];
+            let currentText = '';
+            let fg = '#cccccc';
+            let bg = '#000000';
+            let bold = false;
+            let i = 0;
+            let inEscape = false;
+            let escapeCode = '';
+
+            while (i < text.length) {
+                const char = text[i];
+                
+                if (inEscape) {
+                    if (char >= '0' && char <= '9' || char === ';' || char === '[') {
+                        escapeCode += char;
+                    }
+                    
+                    if (char === 'm') {
+                        const codes = escapeCode.replace('\x1b[', '').split(';');
+                        
+                        for (const code of codes) {
+                            const num = parseInt(code) || 0;
+                            
+                            if (num === 0) {
+                                fg = '#cccccc';
+                                bg = '#000000';
+                                bold = false;
+                            } else if (num === 1) {
+                                bold = true;
+                            } else if (num === 22) {
+                                bold = false;
+                            } else if (num === 39) {
+                                fg = '#cccccc';
+                            } else if (num === 49) {
+                                bg = '#000000';
+                            } else if (num >= 30 && num <= 37) {
+                                fg = ANSI_COLORS[num - 30 + (bold ? 8 : 0)] || '#cccccc';
+                            } else if (num >= 40 && num <= 47) {
+                                bg = ANSI_COLORS[num - 40] || '#000000';
+                            } else if (num >= 90 && num <= 97) {
+                                fg = ANSI_COLORS[num - 90 + 8] || '#cccccc';
+                            } else if (num >= 100 && num <= 107) {
+                                bg = ANSI_COLORS[num - 100 + 8] || '#000000';
+                            } else if (num >= 1 && num <= 256) {
+                                // 256 colors
+                                if (num < 16) {
+                                    fg = ANSI_COLORS[num] || '#cccccc';
+                                } else if (num < 232) {
+                                    const c = num - 16;
+                                    const r = Math.floor(c / 36) * 51;
+                                    const g = Math.floor((c % 36) / 6) * 51;
+                                    const b = (c % 6) * 51;
+                                    fg = `#${r.toString(16).padStart(2,'0')}${g.toString(16).padStart(2,'0')}${b.toString(16).padStart(2,'0')}`;
+                                } else {
+                                    const gray = (num - 232) * 10 + 8;
+                                    fg = `#${gray.toString(16).repeat(2)}`;
+                                }
+                            }
+                        }
+                        
+                        if (currentText) {
+                            tokens.push({ text: currentText, fg, bg, bold });
+                            currentText = '';
+                        }
+                        inEscape = false;
+                        escapeCode = '';
+                    }
+                } else if (char === '\x1b' && text[i + 1] === '[') {
+                    if (currentText) {
+                        tokens.push({ text: currentText, fg, bg, bold });
+                        currentText = '';
+                    }
+                    inEscape = true;
+                    escapeCode = '';
+                    i++;
+                } else {
+                    currentText += char;
+                }
+                i++;
+            }
+
+            if (currentText) {
+                tokens.push({ text: currentText, fg, bg, bold });
+            }
+
+            return tokens;
+        }
+
+        function renderLine(text, x, y, lineHeight) {
+            const tokens = parseAnsi(text);
+            let xOffset = x;
+
+            for (const token of tokens) {
+                if (token.text) {
+                    if (token.bold) {
+                        ctx.font = 'bold 16px monospace';
+                    } else {
+                        ctx.font = '16px monospace';
+                    }
+
+                    const metrics = ctx.measureText(token.text);
+                    
+                    if (token.bg !== '#000000') {
+                        ctx.fillStyle = token.bg;
+                        ctx.fillRect(xOffset, y - 2, metrics.width + 1, lineHeight);
+                    }
+                    
+                    ctx.fillStyle = token.fg;
+                    ctx.fillText(token.text, xOffset, y);
+                    xOffset += metrics.width;
+                }
+            }
+        }
+
+        function connect() {
+            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsUrl = `${protocol}//${window.location.hostname}:8765`;
+            
+            ws = new WebSocket(wsUrl);
+
+            ws.onopen = () => {
+                status.textContent = 'Connected';
+                status.className = 'connected';
+                sendSize();
+            };
+
+            ws.onclose = () => {
+                status.textContent = 'Disconnected - Reconnecting...';
+                status.className = 'disconnected';
+                setTimeout(connect, 1000);
+            };
+
+            ws.onerror = () => {
+                status.textContent = 'Connection error';
+                status.className = 'disconnected';
+            };
+
+            ws.onmessage = (event) => {
+                try {
+                    const data = JSON.parse(event.data);
+                    
+                    if (data.type === 'frame') {
+                        cols = data.width || 80;
+                        rows = data.height || 24;
+                        colsInput.value = cols;
+                        rowsInput.value = rows;
+                        resizeCanvas();
+                        render(data.lines || []);
+                    } else if (data.type === 'clear') {
+                        ctx.fillStyle = '#000';
+                        ctx.fillRect(0, 0, canvas.width, canvas.height);
+                    }
+                } catch (e) {
+                    console.error('Failed to parse message:', e);
+                }
+            };
+        }
+
+        function sendSize() {
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                ws.send(JSON.stringify({
+                    type: 'resize',
+                    width: parseInt(colsInput.value),
+                    height: parseInt(rowsInput.value)
+                }));
+            }
+        }
+
+        function render(lines) {
+            ctx.fillStyle = '#000';
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+            ctx.font = '16px monospace';
+            ctx.textBaseline = 'top';
+
+            const lineHeight = CHAR_HEIGHT;
+            const maxLines = Math.min(lines.length, rows);
+
+            for (let i = 0; i < maxLines; i++) {
+                const line = lines[i] || '';
+                renderLine(line, 0, i * lineHeight, lineHeight);
+            }
+        }
+
+        function calculateViewportSize() {
+            const isFullscreen = document.fullscreenElement !== null;
+            const padding = isFullscreen ? 0 : 40;
+            const controlsHeight = isFullscreen ? 0 : 60;
+            const availableWidth = window.innerWidth - padding;
+            const availableHeight = window.innerHeight - controlsHeight;
+            cols = Math.max(20, Math.floor(availableWidth / CHAR_WIDTH));
+            rows = Math.max(10, Math.floor(availableHeight / CHAR_HEIGHT));
+            colsInput.value = cols;
+            rowsInput.value = rows;
+            resizeCanvas();
+            console.log('Fullscreen:', isFullscreen, 'Size:', cols, 'x', rows);
+            sendSize();
+        }
+
+        applyBtn.addEventListener('click', () => {
+            cols = parseInt(colsInput.value);
+            rows = parseInt(rowsInput.value);
+            resizeCanvas();
+            sendSize();
+        });
+
+        fullscreenBtn.addEventListener('click', () => {
+            if (!document.fullscreenElement) {
+                document.body.classList.add('fullscreen');
+                document.documentElement.requestFullscreen().then(() => {
+                    calculateViewportSize();
+                });
+            } else {
+                document.exitFullscreen().then(() => {
+                    calculateViewportSize();
+                });
+            }
+        });
+
+        document.addEventListener('fullscreenchange', () => {
+            if (!document.fullscreenElement) {
+                document.body.classList.remove('fullscreen');
+                calculateViewportSize();
+            }
+        });
+
+        window.addEventListener('resize', () => {
+            if (document.fullscreenElement) {
+                calculateViewportSize();
+            }
+        });
+
+        // Initial setup
+        resizeCanvas();
+        connect();
+    </script>
+</body>
+</html>
--- a/cmdline.py
+++ b/cmdline.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# -*- coding: utf-8 -*-
 """
 Command-line utility for interacting with mainline via ntfy.

@@ -20,6 +21,11 @@ C&C works like a serial port:
    3. Cmdline polls for response
 """

+import os
+
+os.environ["FORCE_COLOR"] = "1"
+os.environ["TERM"] = "xterm-256color"
+
 import argparse
 import json
 import sys
--- 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/benchmark.py
+++ b/engine/benchmark.py
@@ -0,0 +1,659 @@
+#!/usr/bin/env python3
+"""
+Benchmark runner for mainline - tests performance across effects and displays.
+
+Usage:
+    python -m engine.benchmark
+    python -m engine.benchmark --output report.md
+    python -m engine.benchmark --displays terminal,websocket --effects glitch,fade
+    python -m engine.benchmark --format json --output benchmark.json
+
+Headless mode (default): suppress all terminal output during benchmarks.
+"""
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from io import StringIO
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class BenchmarkResult:
+    """Result of a single benchmark run."""
+
+    name: str
+    display: str
+    effect: str | None
+    iterations: int
+    total_time_ms: float
+    avg_time_ms: float
+    std_dev_ms: float
+    min_ms: float
+    max_ms: float
+    fps: float
+    chars_processed: int
+    chars_per_sec: float
+
+
+@dataclass
+class BenchmarkReport:
+    """Complete benchmark report."""
+
+    timestamp: str
+    python_version: str
+    results: list[BenchmarkResult] = field(default_factory=list)
+    summary: dict[str, Any] = field(default_factory=dict)
+
+
+def get_sample_buffer(width: int = 80, height: int = 24) -> list[str]:
+    """Generate a sample buffer for benchmarking."""
+    lines = []
+    for i in range(height):
+        line = f"\x1b[32mLine {i}\x1b[0m " + "A" * (width - 10)
+        lines.append(line)
+    return lines
+
+
+def benchmark_display(
+    display_class, buffer: list[str], iterations: int = 100
+) -> BenchmarkResult | None:
+    """Benchmark a single display."""
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+
+    try:
+        sys.stdout = StringIO()
+        sys.stderr = StringIO()
+
+        display = display_class()
+        display.init(80, 24)
+
+        times = []
+        chars = sum(len(line) for line in buffer)
+
+        for _ in range(iterations):
+            t0 = time.perf_counter()
+            display.show(buffer)
+            elapsed = (time.perf_counter() - t0) * 1000
+            times.append(elapsed)
+
+        display.cleanup()
+
+    except Exception:
+        return None
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+    times_arr = np.array(times)
+
+    return BenchmarkResult(
+        name=f"display_{display_class.__name__}",
+        display=display_class.__name__,
+        effect=None,
+        iterations=iterations,
+        total_time_ms=sum(times),
+        avg_time_ms=float(np.mean(times_arr)),
+        std_dev_ms=float(np.std(times_arr)),
+        min_ms=float(np.min(times_arr)),
+        max_ms=float(np.max(times_arr)),
+        fps=float(1000.0 / np.mean(times_arr)) if np.mean(times_arr) > 0 else 0.0,
+        chars_processed=chars * iterations,
+        chars_per_sec=float((chars * iterations) / (sum(times) / 1000))
+        if sum(times) > 0
+        else 0.0,
+    )
+
+
+def benchmark_effect_with_display(
+    effect_class, display, buffer: list[str], iterations: int = 100
+) -> BenchmarkResult | None:
+    """Benchmark an effect with a display."""
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+
+    try:
+        from engine.effects.types import EffectConfig, EffectContext
+
+        sys.stdout = StringIO()
+        sys.stderr = StringIO()
+
+        effect = effect_class()
+        effect.configure(EffectConfig(enabled=True, intensity=1.0))
+
+        ctx = EffectContext(
+            terminal_width=80,
+            terminal_height=24,
+            scroll_cam=0,
+            ticker_height=0,
+            mic_excess=0.0,
+            grad_offset=0.0,
+            frame_number=0,
+            has_message=False,
+        )
+
+        times = []
+        chars = sum(len(line) for line in buffer)
+
+        for _ in range(iterations):
+            processed = effect.process(buffer, ctx)
+            t0 = time.perf_counter()
+            display.show(processed)
+            elapsed = (time.perf_counter() - t0) * 1000
+            times.append(elapsed)
+
+        display.cleanup()
+
+    except Exception:
+        return None
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+
+    times_arr = np.array(times)
+
+    return BenchmarkResult(
+        name=f"effect_{effect_class.__name__}_with_{display.__class__.__name__}",
+        display=display.__class__.__name__,
+        effect=effect_class.__name__,
+        iterations=iterations,
+        total_time_ms=sum(times),
+        avg_time_ms=float(np.mean(times_arr)),
+        std_dev_ms=float(np.std(times_arr)),
+        min_ms=float(np.min(times_arr)),
+        max_ms=float(np.max(times_arr)),
+        fps=float(1000.0 / np.mean(times_arr)) if np.mean(times_arr) > 0 else 0.0,
+        chars_processed=chars * iterations,
+        chars_per_sec=float((chars * iterations) / (sum(times) / 1000))
+        if sum(times) > 0
+        else 0.0,
+    )
+
+
+def get_available_displays():
+    """Get available display classes."""
+    from engine.display import (
+        DisplayRegistry,
+        NullDisplay,
+        TerminalDisplay,
+    )
+
+    DisplayRegistry.initialize()
+
+    displays = [
+        ("null", NullDisplay),
+        ("terminal", TerminalDisplay),
+    ]
+
+    try:
+        from engine.display.backends.websocket import WebSocketDisplay
+
+        displays.append(("websocket", WebSocketDisplay))
+    except Exception:
+        pass
+
+    try:
+        from engine.display.backends.sixel import SixelDisplay
+
+        displays.append(("sixel", SixelDisplay))
+    except Exception:
+        pass
+
+    return displays
+
+
+def get_available_effects():
+    """Get available effect classes."""
+    try:
+        from engine.effects import get_registry
+
+        try:
+            from effects_plugins import discover_plugins
+
+            discover_plugins()
+        except Exception:
+            pass
+    except Exception:
+        return []
+
+    effects = []
+    registry = get_registry()
+
+    for name, effect in registry.list_all().items():
+        if effect:
+            effect_cls = type(effect)
+            effects.append((name, effect_cls))
+
+    return effects
+
+
+def run_benchmarks(
+    displays: list[tuple[str, Any]] | None = None,
+    effects: list[tuple[str, Any]] | None = None,
+    iterations: int = 100,
+    verbose: bool = False,
+) -> BenchmarkReport:
+    """Run all benchmarks and return report."""
+    from datetime import datetime
+
+    if displays is None:
+        displays = get_available_displays()
+
+    if effects is None:
+        effects = get_available_effects()
+
+    buffer = get_sample_buffer(80, 24)
+    results = []
+
+    if verbose:
+        print(f"Running benchmarks ({iterations} iterations each)...")
+
+    for name, display_class in displays:
+        if verbose:
+            print(f"Benchmarking display: {name}")
+
+        result = benchmark_display(display_class, buffer, iterations)
+        if result:
+            results.append(result)
+            if verbose:
+                print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
+
+    if verbose:
+        print()
+
+    for effect_name, effect_class in effects:
+        for display_name, display_class in displays:
+            if display_name == "websocket":
+                continue
+            if verbose:
+                print(f"Benchmarking effect: {effect_name} with {display_name}")
+
+            display = display_class()
+            display.init(80, 24)
+            result = benchmark_effect_with_display(
+                effect_class, display, buffer, iterations
+            )
+            if result:
+                results.append(result)
+                if verbose:
+                    print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
+
+    summary = generate_summary(results)
+
+    return BenchmarkReport(
+        timestamp=datetime.now().isoformat(),
+        python_version=sys.version,
+        results=results,
+        summary=summary,
+    )
+
+
+def generate_summary(results: list[BenchmarkResult]) -> dict[str, Any]:
+    """Generate summary statistics from results."""
+    by_display: dict[str, list[BenchmarkResult]] = {}
+    by_effect: dict[str, list[BenchmarkResult]] = {}
+
+    for r in results:
+        if r.display not in by_display:
+            by_display[r.display] = []
+        by_display[r.display].append(r)
+
+        if r.effect:
+            if r.effect not in by_effect:
+                by_effect[r.effect] = []
+            by_effect[r.effect].append(r)
+
+    summary = {
+        "by_display": {},
+        "by_effect": {},
+        "overall": {
+            "total_tests": len(results),
+            "displays_tested": len(by_display),
+            "effects_tested": len(by_effect),
+        },
+    }
+
+    for display, res in by_display.items():
+        fps_values = [r.fps for r in res]
+        summary["by_display"][display] = {
+            "avg_fps": float(np.mean(fps_values)),
+            "min_fps": float(np.min(fps_values)),
+            "max_fps": float(np.max(fps_values)),
+            "tests": len(res),
+        }
+
+    for effect, res in by_effect.items():
+        fps_values = [r.fps for r in res]
+        summary["by_effect"][effect] = {
+            "avg_fps": float(np.mean(fps_values)),
+            "min_fps": float(np.min(fps_values)),
+            "max_fps": float(np.max(fps_values)),
+            "tests": len(res),
+        }
+
+    return summary
+
+
+DEFAULT_CACHE_PATH = Path.home() / ".mainline_benchmark_cache.json"
+
+
+def load_baseline(cache_path: Path | None = None) -> dict[str, Any] | None:
+    """Load baseline benchmark results from cache."""
+    path = cache_path or DEFAULT_CACHE_PATH
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def save_baseline(
+    results: list[BenchmarkResult],
+    cache_path: Path | None = None,
+) -> None:
+    """Save benchmark results as baseline to cache."""
+    path = cache_path or DEFAULT_CACHE_PATH
+    baseline = {
+        "timestamp": datetime.now().isoformat(),
+        "results": {
+            r.name: {
+                "fps": r.fps,
+                "avg_time_ms": r.avg_time_ms,
+                "chars_per_sec": r.chars_per_sec,
+            }
+            for r in results
+        },
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(baseline, f, indent=2)
+
+
+def compare_with_baseline(
+    results: list[BenchmarkResult],
+    baseline: dict[str, Any],
+    threshold: float = 0.2,
+    verbose: bool = True,
+) -> tuple[bool, list[str]]:
+    """Compare current results with baseline. Returns (pass, messages)."""
+    baseline_results = baseline.get("results", {})
+    failures = []
+    warnings = []
+
+    for r in results:
+        if r.name not in baseline_results:
+            warnings.append(f"New test: {r.name} (no baseline)")
+            continue
+
+        b = baseline_results[r.name]
+        if b["fps"] == 0:
+            continue
+
+        degradation = (b["fps"] - r.fps) / b["fps"]
+        if degradation > threshold:
+            failures.append(
+                f"{r.name}: FPS degraded {degradation * 100:.1f}% "
+                f"(baseline: {b['fps']:.1f}, current: {r.fps:.1f})"
+            )
+        elif verbose:
+            print(f"  {r.name}: {r.fps:.1f} FPS (baseline: {b['fps']:.1f})")
+
+    passed = len(failures) == 0
+    messages = []
+    if failures:
+        messages.extend(failures)
+    if warnings:
+        messages.extend(warnings)
+
+    return passed, messages
+
+
+def run_hook_mode(
+    displays: list[tuple[str, Any]] | None = None,
+    effects: list[tuple[str, Any]] | None = None,
+    iterations: int = 20,
+    threshold: float = 0.2,
+    cache_path: Path | None = None,
+    verbose: bool = False,
+) -> int:
+    """Run in hook mode: compare against baseline, exit 0 on pass, 1 on fail."""
+    baseline = load_baseline(cache_path)
+
+    if baseline is None:
+        print("No baseline found. Run with --baseline to create one.")
+        return 1
+
+    report = run_benchmarks(displays, effects, iterations, verbose)
+
+    passed, messages = compare_with_baseline(
+        report.results, baseline, threshold, verbose
+    )
+
+    print("\n=== Benchmark Hook Results ===")
+    if passed:
+        print("PASSED - No significant performance degradation")
+        return 0
+    else:
+        print("FAILED - Performance degradation detected:")
+        for msg in messages:
+            print(f"  - {msg}")
+        return 1
+
+
+def format_report_text(report: BenchmarkReport) -> str:
+    """Format report as human-readable text."""
+    lines = [
+        "# Mainline Performance Benchmark Report",
+        "",
+        f"Generated: {report.timestamp}",
+        f"Python: {report.python_version}",
+        "",
+        "## Summary",
+        "",
+        f"Total tests: {report.summary['overall']['total_tests']}",
+        f"Displays tested: {report.summary['overall']['displays_tested']}",
+        f"Effects tested: {report.summary['overall']['effects_tested']}",
+        "",
+        "## By Display",
+        "",
+    ]
+
+    for display, stats in report.summary["by_display"].items():
+        lines.append(f"### {display}")
+        lines.append(f"- Avg FPS: {stats['avg_fps']:.1f}")
+        lines.append(f"- Min FPS: {stats['min_fps']:.1f}")
+        lines.append(f"- Max FPS: {stats['max_fps']:.1f}")
+        lines.append(f"- Tests: {stats['tests']}")
+        lines.append("")
+
+    if report.summary["by_effect"]:
+        lines.append("## By Effect")
+        lines.append("")
+
+        for effect, stats in report.summary["by_effect"].items():
+            lines.append(f"### {effect}")
+            lines.append(f"- Avg FPS: {stats['avg_fps']:.1f}")
+            lines.append(f"- Min FPS: {stats['min_fps']:.1f}")
+            lines.append(f"- Max FPS: {stats['max_fps']:.1f}")
+            lines.append(f"- Tests: {stats['tests']}")
+            lines.append("")
+
+    lines.append("## Detailed Results")
+    lines.append("")
+    lines.append("| Display | Effect | FPS | Avg ms | StdDev ms | Min ms | Max ms |")
+    lines.append("|---------|--------|-----|--------|-----------|--------|--------|")
+
+    for r in report.results:
+        effect_col = r.effect if r.effect else "-"
+        lines.append(
+            f"| {r.display} | {effect_col} | {r.fps:.1f} | {r.avg_time_ms:.2f} | "
+            f"{r.std_dev_ms:.2f} | {r.min_ms:.2f} | {r.max_ms:.2f} |"
+        )
+
+    return "\n".join(lines)
+
+
+def format_report_json(report: BenchmarkReport) -> str:
+    """Format report as JSON."""
+    data = {
+        "timestamp": report.timestamp,
+        "python_version": report.python_version,
+        "summary": report.summary,
+        "results": [
+            {
+                "name": r.name,
+                "display": r.display,
+                "effect": r.effect,
+                "iterations": r.iterations,
+                "total_time_ms": r.total_time_ms,
+                "avg_time_ms": r.avg_time_ms,
+                "std_dev_ms": r.std_dev_ms,
+                "min_ms": r.min_ms,
+                "max_ms": r.max_ms,
+                "fps": r.fps,
+                "chars_processed": r.chars_processed,
+                "chars_per_sec": r.chars_per_sec,
+            }
+            for r in report.results
+        ],
+    }
+    return json.dumps(data, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run mainline benchmarks")
+    parser.add_argument(
+        "--displays",
+        help="Comma-separated list of displays to test (default: all)",
+    )
+    parser.add_argument(
+        "--effects",
+        help="Comma-separated list of effects to test (default: all)",
+    )
+    parser.add_argument(
+        "--iterations",
+        type=int,
+        default=100,
+        help="Number of iterations per test (default: 100)",
+    )
+    parser.add_argument(
+        "--output",
+        help="Output file path (default: stdout)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show progress during benchmarking",
+    )
+    parser.add_argument(
+        "--hook",
+        action="store_true",
+        help="Run in hook mode: compare against baseline, exit 0 pass, 1 fail",
+    )
+    parser.add_argument(
+        "--baseline",
+        action="store_true",
+        help="Save current results as baseline for future hook comparisons",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.2,
+        help="Performance degradation threshold for hook mode (default: 0.2 = 20%%)",
+    )
+    parser.add_argument(
+        "--cache",
+        type=str,
+        default=None,
+        help="Path to baseline cache file (default: ~/.mainline_benchmark_cache.json)",
+    )
+
+    args = parser.parse_args()
+
+    cache_path = Path(args.cache) if args.cache else DEFAULT_CACHE_PATH
+
+    if args.hook:
+        displays = None
+        if args.displays:
+            display_map = dict(get_available_displays())
+            displays = [
+                (name, display_map[name])
+                for name in args.displays.split(",")
+                if name in display_map
+            ]
+
+        effects = None
+        if args.effects:
+            effect_map = dict(get_available_effects())
+            effects = [
+                (name, effect_map[name])
+                for name in args.effects.split(",")
+                if name in effect_map
+            ]
+
+        return run_hook_mode(
+            displays,
+            effects,
+            iterations=args.iterations,
+            threshold=args.threshold,
+            cache_path=cache_path,
+            verbose=args.verbose,
+        )
+
+    displays = None
+    if args.displays:
+        display_map = dict(get_available_displays())
+        displays = [
+            (name, display_map[name])
+            for name in args.displays.split(",")
+            if name in display_map
+        ]
+
+    effects = None
+    if args.effects:
+        effect_map = dict(get_available_effects())
+        effects = [
+            (name, effect_map[name])
+            for name in args.effects.split(",")
+            if name in effect_map
+        ]
+
+    report = run_benchmarks(displays, effects, args.iterations, args.verbose)
+
+    if args.baseline:
+        save_baseline(report.results, cache_path)
+        print(f"Baseline saved to {cache_path}")
+        return 0
+
+    if args.format == "json":
+        output = format_report_json(report)
+    else:
+        output = format_report_text(report)
+
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(output)
+    else:
+        print(output)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
--- a/engine/config.py
+++ b/engine/config.py
@@ -129,6 +129,10 @@ class Config:

    script_fonts: dict[str, str] = field(default_factory=_get_platform_font_paths)

+    display: str = "terminal"
+    websocket: bool = False
+    websocket_port: int = 8765
+
    @classmethod
    def from_args(cls, argv: list[str] | None = None) -> "Config":
        """Create Config from CLI arguments (or custom argv for testing)."""
@@ -168,6 +172,9 @@ class Config:
            glitch_glyphs="░▒▓█▌▐╌╍╎╏┃┆┇┊┋",
            kata_glyphs="ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ",
            script_fonts=_get_platform_font_paths(),
+            display=_arg_value("--display", argv) or "terminal",
+            websocket="--websocket" in argv,
+            websocket_port=_arg_int("--websocket-port", 8765, argv),
        )


@@ -229,6 +236,11 @@ GRAD_SPEED = 0.08  # gradient traversal speed (cycles/sec, ~12s full sweep)
 GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
 KATA = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"

+# ─── WEBSOCKET ─────────────────────────────────────────────
+DISPLAY = _arg_value("--display", sys.argv) or "terminal"
+WEBSOCKET = "--websocket" in sys.argv
+WEBSOCKET_PORT = _arg_int("--websocket-port", 8765)
+

 def set_font_selection(font_path=None, font_index=None):
    """Set runtime primary font selection."""
--- a/engine/controller.py
+++ b/engine/controller.py
@@ -3,6 +3,14 @@ Stream controller - manages input sources and orchestrates the render stream.
 """

 from engine.config import Config, get_config
+from engine.display import (
+    DisplayRegistry,
+    MultiDisplay,
+    NullDisplay,
+    SixelDisplay,
+    TerminalDisplay,
+    WebSocketDisplay,
+)
 from engine.effects.controller import handle_effects_command
 from engine.eventbus import EventBus
 from engine.events import EventType, StreamEvent
@@ -11,6 +19,34 @@ from engine.ntfy import NtfyPoller
 from engine.scroll import stream


+def _get_display(config: Config):
+    """Get the appropriate display based on config."""
+    DisplayRegistry.initialize()
+    display_mode = config.display.lower()
+
+    displays = []
+
+    if display_mode in ("terminal", "both"):
+        displays.append(TerminalDisplay())
+
+    if display_mode in ("websocket", "both"):
+        ws = WebSocketDisplay(host="0.0.0.0", port=config.websocket_port)
+        ws.start_server()
+        ws.start_http_server()
+        displays.append(ws)
+
+    if display_mode == "sixel":
+        displays.append(SixelDisplay())
+
+    if not displays:
+        return NullDisplay()
+
+    if len(displays) == 1:
+        return displays[0]
+
+    return MultiDisplay(displays)
+
+
 class StreamController:
    """Controls the stream lifecycle - initializes sources and runs the stream."""

@@ -117,7 +153,10 @@ class StreamController:
                ),
            )

-        stream(items, self.ntfy, self.mic)
+        display = _get_display(self.config)
+        stream(items, self.ntfy, self.mic, display)
+        if display:
+            display.cleanup()

        if self.event_bus:
            self.event_bus.publish(
--- a/engine/display.py
+++ b/engine/display.py
@@ -1,102 +0,0 @@
-"""
-Display output abstraction - allows swapping output backends.
-
-Protocol:
-    - init(width, height): Initialize display with terminal dimensions
-    - show(buffer): Render buffer (list of strings) to display
-    - clear(): Clear the display
-    - cleanup(): Shutdown display
-"""
-
-import time
-from typing import Protocol
-
-
-class Display(Protocol):
-    """Protocol for display backends."""
-
-    def init(self, width: int, height: int) -> None:
-        """Initialize display with dimensions."""
-        ...
-
-    def show(self, buffer: list[str]) -> None:
-        """Show buffer on display."""
-        ...
-
-    def clear(self) -> None:
-        """Clear display."""
-        ...
-
-    def cleanup(self) -> None:
-        """Shutdown display."""
-        ...
-
-
-def get_monitor():
-    """Get the performance monitor."""
-    try:
-        from engine.effects.performance import get_monitor as _get_monitor
-
-        return _get_monitor()
-    except Exception:
-        return None
-
-
-class TerminalDisplay:
-    """ANSI terminal display backend."""
-
-    def __init__(self):
-        self.width = 80
-        self.height = 24
-
-    def init(self, width: int, height: int) -> None:
-        from engine.terminal import CURSOR_OFF
-
-        self.width = width
-        self.height = height
-        print(CURSOR_OFF, end="", flush=True)
-
-    def show(self, buffer: list[str]) -> None:
-        import sys
-
-        t0 = time.perf_counter()
-        sys.stdout.buffer.write("".join(buffer).encode())
-        sys.stdout.flush()
-        elapsed_ms = (time.perf_counter() - t0) * 1000
-
-        monitor = get_monitor()
-        if monitor:
-            chars_in = sum(len(line) for line in buffer)
-            monitor.record_effect("terminal_display", elapsed_ms, chars_in, chars_in)
-
-    def clear(self) -> None:
-        from engine.terminal import CLR
-
-        print(CLR, end="", flush=True)
-
-    def cleanup(self) -> None:
-        from engine.terminal import CURSOR_ON
-
-        print(CURSOR_ON, end="", flush=True)
-
-
-class NullDisplay:
-    """Headless/null display - discards all output."""
-
-    def init(self, width: int, height: int) -> None:
-        self.width = width
-        self.height = height
-
-    def show(self, buffer: list[str]) -> None:
-        monitor = get_monitor()
-        if monitor:
-            t0 = time.perf_counter()
-            chars_in = sum(len(line) for line in buffer)
-            elapsed_ms = (time.perf_counter() - t0) * 1000
-            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
-
-    def clear(self) -> None:
-        pass
-
-    def cleanup(self) -> None:
-        pass
--- a/engine/display/init.py
+++ b/engine/display/init.py
@@ -0,0 +1,102 @@
+"""
+Display backend system with registry pattern.
+
+Allows swapping output backends via the Display protocol.
+Supports auto-discovery of display backends.
+"""
+
+from typing import Protocol
+
+from engine.display.backends.multi import MultiDisplay
+from engine.display.backends.null import NullDisplay
+from engine.display.backends.sixel import SixelDisplay
+from engine.display.backends.terminal import TerminalDisplay
+from engine.display.backends.websocket import WebSocketDisplay
+
+
+class Display(Protocol):
+    """Protocol for display backends."""
+
+    width: int
+    height: int
+
+    def init(self, width: int, height: int) -> None:
+        """Initialize display with dimensions."""
+        ...
+
+    def show(self, buffer: list[str]) -> None:
+        """Show buffer on display."""
+        ...
+
+    def clear(self) -> None:
+        """Clear display."""
+        ...
+
+    def cleanup(self) -> None:
+        """Shutdown display."""
+        ...
+
+
+class DisplayRegistry:
+    """Registry for display backends with auto-discovery."""
+
+    _backends: dict[str, type[Display]] = {}
+    _initialized = False
+
+    @classmethod
+    def register(cls, name: str, backend_class: type[Display]) -> None:
+        """Register a display backend."""
+        cls._backends[name.lower()] = backend_class
+
+    @classmethod
+    def get(cls, name: str) -> type[Display] | None:
+        """Get a display backend class by name."""
+        return cls._backends.get(name.lower())
+
+    @classmethod
+    def list_backends(cls) -> list[str]:
+        """List all available display backend names."""
+        return list(cls._backends.keys())
+
+    @classmethod
+    def create(cls, name: str, **kwargs) -> Display | None:
+        """Create a display instance by name."""
+        backend_class = cls.get(name)
+        if backend_class:
+            return backend_class(**kwargs)
+        return None
+
+    @classmethod
+    def initialize(cls) -> None:
+        """Initialize and register all built-in backends."""
+        if cls._initialized:
+            return
+
+        cls.register("terminal", TerminalDisplay)
+        cls.register("null", NullDisplay)
+        cls.register("websocket", WebSocketDisplay)
+        cls.register("sixel", SixelDisplay)
+
+        cls._initialized = True
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from engine.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+__all__ = [
+    "Display",
+    "DisplayRegistry",
+    "get_monitor",
+    "TerminalDisplay",
+    "NullDisplay",
+    "WebSocketDisplay",
+    "SixelDisplay",
+    "MultiDisplay",
+]
--- a/engine/display/backends/multi.py
+++ b/engine/display/backends/multi.py
@@ -0,0 +1,33 @@
+"""
+Multi display backend - forwards to multiple displays.
+"""
+
+
+class MultiDisplay:
+    """Display that forwards to multiple displays."""
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(self, displays: list):
+        self.displays = displays
+        self.width = 80
+        self.height = 24
+
+    def init(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+        for d in self.displays:
+            d.init(width, height)
+
+    def show(self, buffer: list[str]) -> None:
+        for d in self.displays:
+            d.show(buffer)
+
+    def clear(self) -> None:
+        for d in self.displays:
+            d.clear()
+
+    def cleanup(self) -> None:
+        for d in self.displays:
+            d.cleanup()
--- a/engine/display/backends/null.py
+++ b/engine/display/backends/null.py
@@ -0,0 +1,32 @@
+"""
+Null/headless display backend.
+"""
+
+import time
+
+
+class NullDisplay:
+    """Headless/null display - discards all output."""
+
+    width: int = 80
+    height: int = 24
+
+    def init(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+
+    def show(self, buffer: list[str]) -> None:
+        from engine.display import get_monitor
+
+        monitor = get_monitor()
+        if monitor:
+            t0 = time.perf_counter()
+            chars_in = sum(len(line) for line in buffer)
+            elapsed_ms = (time.perf_counter() - t0) * 1000
+            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass
--- a/engine/display/backends/sixel.py
+++ b/engine/display/backends/sixel.py
@@ -0,0 +1,269 @@
+"""
+Sixel graphics display backend - renders to sixel graphics in terminal.
+"""
+
+import time
+
+
+def _parse_ansi(
+    text: str,
+) -> list[tuple[str, tuple[int, int, int], tuple[int, int, int], bool]]:
+    """Parse ANSI text into tokens with fg/bg colors.
+
+    Returns list of (text, fg_rgb, bg_rgb, bold).
+    """
+    tokens = []
+    current_text = ""
+    fg = (204, 204, 204)
+    bg = (0, 0, 0)
+    bold = False
+    i = 0
+
+    ANSI_COLORS = {
+        0: (0, 0, 0),
+        1: (205, 49, 49),
+        2: (13, 188, 121),
+        3: (229, 229, 16),
+        4: (36, 114, 200),
+        5: (188, 63, 188),
+        6: (17, 168, 205),
+        7: (229, 229, 229),
+        8: (102, 102, 102),
+        9: (241, 76, 76),
+        10: (35, 209, 139),
+        11: (245, 245, 67),
+        12: (59, 142, 234),
+        13: (214, 112, 214),
+        14: (41, 184, 219),
+        15: (255, 255, 255),
+    }
+
+    while i < len(text):
+        char = text[i]
+
+        if char == "\x1b" and i + 1 < len(text) and text[i + 1] == "[":
+            if current_text:
+                tokens.append((current_text, fg, bg, bold))
+                current_text = ""
+
+            i += 2
+            code = ""
+            while i < len(text):
+                c = text[i]
+                if c.isalpha():
+                    break
+                code += c
+                i += 1
+
+            if code:
+                codes = code.split(";")
+                for c in codes:
+                    try:
+                        n = int(c) if c else 0
+                    except ValueError:
+                        continue
+
+                    if n == 0:
+                        fg = (204, 204, 204)
+                        bg = (0, 0, 0)
+                        bold = False
+                    elif n == 1:
+                        bold = True
+                    elif n == 22:
+                        bold = False
+                    elif n == 39:
+                        fg = (204, 204, 204)
+                    elif n == 49:
+                        bg = (0, 0, 0)
+                    elif 30 <= n <= 37:
+                        fg = ANSI_COLORS.get(n - 30 + (8 if bold else 0), fg)
+                    elif 40 <= n <= 47:
+                        bg = ANSI_COLORS.get(n - 40, bg)
+                    elif 90 <= n <= 97:
+                        fg = ANSI_COLORS.get(n - 90 + 8, fg)
+                    elif 100 <= n <= 107:
+                        bg = ANSI_COLORS.get(n - 100 + 8, bg)
+                    elif 1 <= n <= 256:
+                        if n < 16:
+                            fg = ANSI_COLORS.get(n, fg)
+                        elif n < 232:
+                            c = n - 16
+                            r = (c // 36) * 51
+                            g = ((c % 36) // 6) * 51
+                            b = (c % 6) * 51
+                            fg = (r, g, b)
+                        else:
+                            gray = (n - 232) * 10 + 8
+                            fg = (gray, gray, gray)
+        else:
+            current_text += char
+            i += 1
+
+    if current_text:
+        tokens.append((current_text, fg, bg, bold))
+
+    return tokens if tokens else [("", fg, bg, bold)]
+
+
+def _encode_sixel(image) -> str:
+    """Encode a PIL Image to sixel format (pure Python)."""
+    img = image.convert("RGBA")
+    width, height = img.size
+    pixels = img.load()
+
+    palette = []
+    pixel_palette_idx = {}
+
+    def get_color_idx(r, g, b, a):
+        if a < 128:
+            return -1
+        key = (r // 32, g // 32, b // 32)
+        if key not in pixel_palette_idx:
+            idx = len(palette)
+            if idx < 256:
+                palette.append((r, g, b))
+                pixel_palette_idx[key] = idx
+        return pixel_palette_idx.get(key, 0)
+
+    for y in range(height):
+        for x in range(width):
+            r, g, b, a = pixels[x, y]
+            get_color_idx(r, g, b, a)
+
+    if not palette:
+        return ""
+
+    if len(palette) == 1:
+        palette = [palette[0], (0, 0, 0)]
+
+    sixel_data = []
+    sixel_data.append(
+        f'"{"".join(f"#{i};2;{r};{g};{b}" for i, (r, g, b) in enumerate(palette))}'
+    )
+
+    for x in range(width):
+        col_data = []
+        for y in range(0, height, 6):
+            bits = 0
+            color_idx = -1
+            for dy in range(6):
+                if y + dy < height:
+                    r, g, b, a = pixels[x, y + dy]
+                    if a >= 128:
+                        bits |= 1 << dy
+                        idx = get_color_idx(r, g, b, a)
+                        if color_idx == -1:
+                            color_idx = idx
+                        elif color_idx != idx:
+                            color_idx = -2
+
+            if color_idx >= 0:
+                col_data.append(
+                    chr(63 + color_idx) + chr(63 + bits)
+                    if bits
+                    else chr(63 + color_idx) + "?"
+                )
+            elif color_idx == -2:
+                pass
+
+        if col_data:
+            sixel_data.append("".join(col_data) + "$")
+        else:
+            sixel_data.append("-" if x < width - 1 else "$")
+
+    sixel_data.append("\x1b\\")
+
+    return "\x1bPq" + "".join(sixel_data)
+
+
+class SixelDisplay:
+    """Sixel graphics display backend - renders to sixel graphics in terminal."""
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(self, cell_width: int = 9, cell_height: int = 16):
+        self.width = 80
+        self.height = 24
+        self.cell_width = cell_width
+        self.cell_height = cell_height
+        self._initialized = False
+
+    def init(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+        self._initialized = True
+
+    def show(self, buffer: list[str]) -> None:
+        import sys
+
+        t0 = time.perf_counter()
+
+        img_width = self.width * self.cell_width
+        img_height = self.height * self.cell_height
+
+        try:
+            from PIL import Image, ImageDraw, ImageFont
+        except ImportError:
+            return
+
+        img = Image.new("RGBA", (img_width, img_height), (0, 0, 0, 255))
+        draw = ImageDraw.Draw(img)
+
+        try:
+            font = ImageFont.truetype(
+                "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+                self.cell_height - 2,
+            )
+        except Exception:
+            try:
+                font = ImageFont.load_default()
+            except Exception:
+                font = None
+
+        for row_idx, line in enumerate(buffer[: self.height]):
+            if row_idx >= self.height:
+                break
+
+            tokens = _parse_ansi(line)
+            x_pos = 0
+            y_pos = row_idx * self.cell_height
+
+            for text, fg, bg, bold in tokens:
+                if not text:
+                    continue
+
+                if bg != (0, 0, 0):
+                    bbox = draw.textbbox((x_pos, y_pos), text, font=font)
+                    draw.rectangle(bbox, fill=(*bg, 255))
+
+                if bold and font:
+                    draw.text((x_pos - 1, y_pos - 1), text, fill=(*fg, 255), font=font)
+
+                draw.text((x_pos, y_pos), text, fill=(*fg, 255), font=font)
+
+                if font:
+                    x_pos += draw.textlength(text, font=font)
+
+        sixel = _encode_sixel(img)
+
+        sys.stdout.buffer.write(sixel.encode("utf-8"))
+        sys.stdout.flush()
+
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+
+        from engine.display import get_monitor
+
+        monitor = get_monitor()
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("sixel_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        import sys
+
+        sys.stdout.buffer.write(b"\x1b[2J\x1b[H")
+        sys.stdout.flush()
+
+    def cleanup(self) -> None:
+        pass
--- a/engine/display/backends/terminal.py
+++ b/engine/display/backends/terminal.py
@@ -0,0 +1,48 @@
+"""
+ANSI terminal display backend.
+"""
+
+import time
+
+
+class TerminalDisplay:
+    """ANSI terminal display backend."""
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(self):
+        self.width = 80
+        self.height = 24
+
+    def init(self, width: int, height: int) -> None:
+        from engine.terminal import CURSOR_OFF
+
+        self.width = width
+        self.height = height
+        print(CURSOR_OFF, end="", flush=True)
+
+    def show(self, buffer: list[str]) -> None:
+        import sys
+
+        t0 = time.perf_counter()
+        sys.stdout.buffer.write("".join(buffer).encode())
+        sys.stdout.flush()
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+
+        from engine.display import get_monitor
+
+        monitor = get_monitor()
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("terminal_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        from engine.terminal import CLR
+
+        print(CLR, end="", flush=True)
+
+    def cleanup(self) -> None:
+        from engine.terminal import CURSOR_ON
+
+        print(CURSOR_ON, end="", flush=True)
--- a/engine/display/backends/websocket.py
+++ b/engine/display/backends/websocket.py
@@ -0,0 +1,266 @@
+"""
+WebSocket display backend - broadcasts frame buffer to connected web clients.
+"""
+
+import asyncio
+import json
+import threading
+import time
+from typing import Protocol
+
+try:
+    import websockets
+except ImportError:
+    websockets = None
+
+
+class Display(Protocol):
+    """Protocol for display backends."""
+
+    width: int
+    height: int
+
+    def init(self, width: int, height: int) -> None:
+        """Initialize display with dimensions."""
+        ...
+
+    def show(self, buffer: list[str]) -> None:
+        """Show buffer on display."""
+        ...
+
+    def clear(self) -> None:
+        """Clear display."""
+        ...
+
+    def cleanup(self) -> None:
+        """Shutdown display."""
+        ...
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from engine.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+class WebSocketDisplay:
+    """WebSocket display backend - broadcasts to HTML Canvas clients."""
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8765,
+        http_port: int = 8766,
+    ):
+        self.host = host
+        self.port = port
+        self.http_port = http_port
+        self.width = 80
+        self.height = 24
+        self._clients: set = set()
+        self._server_running = False
+        self._http_running = False
+        self._server_thread: threading.Thread | None = None
+        self._http_thread: threading.Thread | None = None
+        self._available = True
+        self._max_clients = 10
+        self._client_connected_callback = None
+        self._client_disconnected_callback = None
+        self._frame_delay = 0.0
+
+        try:
+            import websockets as _ws
+
+            self._available = _ws is not None
+        except ImportError:
+            self._available = False
+
+    def is_available(self) -> bool:
+        """Check if WebSocket support is available."""
+        return self._available
+
+    def init(self, width: int, height: int) -> None:
+        """Initialize display with dimensions and start server."""
+        self.width = width
+        self.height = height
+        self.start_server()
+        self.start_http_server()
+
+    def show(self, buffer: list[str]) -> None:
+        """Broadcast buffer to all connected clients."""
+        t0 = time.perf_counter()
+
+        if self._clients:
+            frame_data = {
+                "type": "frame",
+                "width": self.width,
+                "height": self.height,
+                "lines": buffer,
+            }
+            message = json.dumps(frame_data)
+
+            disconnected = set()
+            for client in list(self._clients):
+                try:
+                    asyncio.run(client.send(message))
+                except Exception:
+                    disconnected.add(client)
+
+            for client in disconnected:
+                self._clients.discard(client)
+                if self._client_disconnected_callback:
+                    self._client_disconnected_callback(client)
+
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        monitor = get_monitor()
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("websocket_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        """Broadcast clear command to all clients."""
+        if self._clients:
+            clear_data = {"type": "clear"}
+            message = json.dumps(clear_data)
+            for client in list(self._clients):
+                try:
+                    asyncio.run(client.send(message))
+                except Exception:
+                    pass
+
+    def cleanup(self) -> None:
+        """Stop the servers."""
+        self.stop_server()
+        self.stop_http_server()
+
+    async def _websocket_handler(self, websocket):
+        """Handle WebSocket connections."""
+        if len(self._clients) >= self._max_clients:
+            await websocket.close()
+            return
+
+        self._clients.add(websocket)
+        if self._client_connected_callback:
+            self._client_connected_callback(websocket)
+
+        try:
+            async for message in websocket:
+                try:
+                    data = json.loads(message)
+                    if data.get("type") == "resize":
+                        self.width = data.get("width", 80)
+                        self.height = data.get("height", 24)
+                except json.JSONDecodeError:
+                    pass
+        except Exception:
+            pass
+        finally:
+            self._clients.discard(websocket)
+            if self._client_disconnected_callback:
+                self._client_disconnected_callback(websocket)
+
+    async def _run_websocket_server(self):
+        """Run the WebSocket server."""
+        async with websockets.serve(self._websocket_handler, self.host, self.port):
+            while self._server_running:
+                await asyncio.sleep(0.1)
+
+    async def _run_http_server(self):
+        """Run simple HTTP server for the client."""
+        import os
+        from http.server import HTTPServer, SimpleHTTPRequestHandler
+
+        client_dir = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "client"
+        )
+
+        class Handler(SimpleHTTPRequestHandler):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, directory=client_dir, **kwargs)
+
+            def log_message(self, format, *args):
+                pass
+
+        httpd = HTTPServer((self.host, self.http_port), Handler)
+        while self._http_running:
+            httpd.handle_request()
+
+    def _run_async(self, coro):
+        """Run coroutine in background."""
+        try:
+            asyncio.run(coro)
+        except Exception as e:
+            print(f"WebSocket async error: {e}")
+
+    def start_server(self):
+        """Start the WebSocket server in a background thread."""
+        if not self._available:
+            return
+        if self._server_thread is not None:
+            return
+
+        self._server_running = True
+        self._server_thread = threading.Thread(
+            target=self._run_async, args=(self._run_websocket_server(),), daemon=True
+        )
+        self._server_thread.start()
+
+    def stop_server(self):
+        """Stop the WebSocket server."""
+        self._server_running = False
+        self._server_thread = None
+
+    def start_http_server(self):
+        """Start the HTTP server in a background thread."""
+        if not self._available:
+            return
+        if self._http_thread is not None:
+            return
+
+        self._http_running = True
+
+        self._http_running = True
+        self._http_thread = threading.Thread(
+            target=self._run_async, args=(self._run_http_server(),), daemon=True
+        )
+        self._http_thread.start()
+
+    def stop_http_server(self):
+        """Stop the HTTP server."""
+        self._http_running = False
+        self._http_thread = None
+
+    def client_count(self) -> int:
+        """Return number of connected clients."""
+        return len(self._clients)
+
+    def get_ws_port(self) -> int:
+        """Return WebSocket port."""
+        return self.port
+
+    def get_http_port(self) -> int:
+        """Return HTTP port."""
+        return self.http_port
+
+    def set_frame_delay(self, delay: float) -> None:
+        """Set delay between frames in seconds."""
+        self._frame_delay = delay
+
+    def get_frame_delay(self) -> float:
+        """Get delay between frames."""
+        return self._frame_delay
+
+    def set_client_connected_callback(self, callback) -> None:
+        """Set callback for client connections."""
+        self._client_connected_callback = callback
+
+    def set_client_disconnected_callback(self, callback) -> None:
+        """Set callback for client disconnections."""
+        self._client_disconnected_callback = callback
--- a/hk.pkl
+++ b/hk.pkl
@@ -22,6 +22,9 @@ hooks {
                prefix = "uv run"
                check = "ruff check engine/ tests/"
            }
+            ["benchmark"] {
+                check = "uv run python -m engine.benchmark --hook --displays null --iterations 20"
+            }
        }
    }
 }
--- a/mise.toml
+++ b/mise.toml
@@ -5,40 +5,64 @@ pkl = "latest"

 [tasks]
 # =====================
-# Development
+# Testing
 # =====================

 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"
+test-v = { run = "uv run pytest -v", depends = ["sync-all"] }
+test-cov = { run = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html", depends = ["sync-all"] }
+test-cov-open = { run = "mise run test-cov && open htmlcov/index.html", depends = ["sync-all"] }
+
+test-browser-install = { run = "uv run playwright install chromium", depends = ["sync-all"] }
+test-browser = { run = "uv run pytest tests/e2e/", depends = ["test-browser-install"] }
+
+# =====================
+# Linting & Formatting
+# =====================

 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
+# Runtime Modes
 # =====================

 run = "uv run mainline.py"
 run-poetry = "uv run mainline.py --poetry"
 run-firehose = "uv run mainline.py --firehose"

-daemon = "nohup uv run mainline.py > /dev/null 2>&1 &"
-daemon-stop = "pkill -f 'uv run mainline.py' 2>/dev/null || true"
-daemon-restart = "mise run daemon-stop && sleep 2 && mise run daemon"
+run-websocket = { run = "uv run mainline.py --display websocket", depends = ["sync-all"] }
+run-sixel = { run = "uv run mainline.py --display sixel", depends = ["sync-all"] }
+run-both = { run = "uv run mainline.py --display both", depends = ["sync-all"] }
+run-client = { run = "mise run run-both & sleep 2 && $(open http://localhost:8766 2>/dev/null || xdg-open http://localhost:8766 2>/dev/null || echo 'Open http://localhost:8766 manually'); wait", depends = ["sync-all"] }

 # =====================
 # Command & Control
 # =====================

 cmd = "uv run cmdline.py"
-cmd-stats = "bash -c 'uv run cmdline.py -w \"/effects stats\"';:"
+cmd-stats = { run = "uv run cmdline.py -w \"/effects stats\"", depends = ["sync-all"] }

-# Initialize ntfy topics (warm up before first use - also done automatically by mainline)
+# =====================
+# Benchmark
+# =====================
+
+benchmark = { run = "uv run python -m engine.benchmark", depends = ["sync-all"] }
+benchmark-json = { run = "uv run python -m engine.benchmark --format json --output benchmark.json", depends = ["sync-all"] }
+benchmark-report = { run = "uv run python -m engine.benchmark --output BENCHMARK.md", depends = ["sync-all"] }
+
+# Initialize ntfy topics (warm up before first use)
 topics-init = "curl -s -d 'init' https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd > /dev/null && curl -s -d 'init' https://ntfy.sh/klubhaus_terminal_mainline_cc_resp > /dev/null && curl -s -d 'init' https://ntfy.sh/klubhaus_terminal_mainline > /dev/null"

+# =====================
+# Daemon
+# =====================
+
+daemon = "nohup uv run mainline.py > nohup.out 2>&1 &"
+daemon-stop = "pkill -f 'uv run mainline.py' 2>/dev/null || true"
+daemon-restart = "mise run daemon-stop && sleep 2 && mise run daemon"
+
 # =====================
 # Environment
 # =====================
@@ -46,24 +70,20 @@ topics-init = "curl -s -d 'init' https://ntfy.sh/klubhaus_terminal_mainline_cc_c
 sync = "uv sync"
 sync-all = "uv sync --all-extras"
 install = "mise run sync"
-install-dev = "mise run sync && uv sync --group dev"
-
-bootstrap = "uv sync && uv run mainline.py --help"
+install-dev = { run = "mise run sync-all && uv sync --group dev", depends = ["sync-all"] }
+bootstrap = { run = "mise run sync-all && uv run mainline.py --help", depends = ["sync-all"] }

 clean = "rm -rf .venv htmlcov .coverage tests/.pytest_cache .mainline_cache_*.json nohup.out"
-
-# Aggressive cleanup - removes all generated files, caches, and venv
 clobber = "git clean -fdx && rm -rf .venv htmlcov .coverage tests/.pytest_cache .mainline_cache_*.json nohup.out"

 # =====================
 # CI/CD
 # =====================

-ci = "mise run topics-init && 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"
+ci = { run = "mise run topics-init && mise run lint && mise run test-cov", depends = ["topics-init", "lint", "test-cov"] }

 # =====================
 # Git Hooks (via hk)
 # =====================

-pre-commit = "hk run pre-commit"
+pre-commit = "hk run pre-commit"
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,6 +30,15 @@ mic = [
    "sounddevice>=0.4.0",
    "numpy>=1.24.0",
 ]
+websocket = [
+    "websockets>=12.0",
+]
+sixel = [
+    "Pillow>=10.0.0",
+]
+browser = [
+    "playwright>=1.40.0",
+]
 dev = [
    "pytest>=8.0.0",
    "pytest-cov>=4.1.0",
--- a/tests/e2e/test_web_client.py
+++ b/tests/e2e/test_web_client.py
@@ -0,0 +1,133 @@
+"""
+End-to-end tests for web client with headless browser.
+"""
+
+import os
+import socketserver
+import threading
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from pathlib import Path
+
+import pytest
+
+CLIENT_DIR = Path(__file__).parent.parent.parent / "client"
+
+
+class ThreadedHTTPServer(socketserver.ThreadingMixIn, HTTPServer):
+    """Threaded HTTP server for handling concurrent requests."""
+
+    daemon_threads = True
+
+
+@pytest.fixture(scope="module")
+def http_server():
+    """Start a local HTTP server for the client."""
+    os.chdir(CLIENT_DIR)
+
+    handler = SimpleHTTPRequestHandler
+    server = ThreadedHTTPServer(("127.0.0.1", 0), handler)
+    port = server.server_address[1]
+
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    yield f"http://127.0.0.1:{port}"
+
+    server.shutdown()
+
+
+class TestWebClient:
+    """Tests for the web client using Playwright."""
+
+    @pytest.fixture(autouse=True)
+    def setup_browser(self):
+        """Set up browser for tests."""
+        pytest.importorskip("playwright")
+        from playwright.sync_api import sync_playwright
+
+        self.playwright = sync_playwright().start()
+        self.browser = self.playwright.chromium.launch(headless=True)
+        self.context = self.browser.new_context()
+        self.page = self.context.new_page()
+
+        yield
+
+        self.page.close()
+        self.context.close()
+        self.browser.close()
+        self.playwright.stop()
+
+    def test_client_loads(self, http_server):
+        """Web client loads without errors."""
+        response = self.page.goto(http_server)
+        assert response.status == 200, f"Page load failed with status {response.status}"
+
+        self.page.wait_for_load_state("domcontentloaded")
+
+        content = self.page.content()
+        assert "<canvas" in content, "Canvas element not found in page"
+
+        canvas = self.page.locator("#terminal")
+        assert canvas.count() > 0, "Canvas not found"
+
+    def test_status_shows_connecting(self, http_server):
+        """Status shows connecting initially."""
+        self.page.goto(http_server)
+        self.page.wait_for_load_state("domcontentloaded")
+
+        status = self.page.locator("#status")
+        assert status.count() > 0, "Status element not found"
+
+    def test_canvas_has_dimensions(self, http_server):
+        """Canvas has correct dimensions after load."""
+        self.page.goto(http_server)
+        self.page.wait_for_load_state("domcontentloaded")
+
+        canvas = self.page.locator("#terminal")
+        assert canvas.count() > 0, "Canvas not found"
+
+    def test_no_console_errors_on_load(self, http_server):
+        """No JavaScript errors on page load (websocket errors are expected without server)."""
+        js_errors = []
+
+        def handle_console(msg):
+            if msg.type == "error":
+                text = msg.text
+                if "WebSocket" not in text:
+                    js_errors.append(text)
+
+        self.page.on("console", handle_console)
+        self.page.goto(http_server)
+        self.page.wait_for_load_state("domcontentloaded")
+
+        assert len(js_errors) == 0, f"JavaScript errors: {js_errors}"
+
+
+class TestWebClientProtocol:
+    """Tests for WebSocket protocol handling in client."""
+
+    @pytest.fixture(autouse=True)
+    def setup_browser(self):
+        """Set up browser for tests."""
+        pytest.importorskip("playwright")
+        from playwright.sync_api import sync_playwright
+
+        self.playwright = sync_playwright().start()
+        self.browser = self.playwright.chromium.launch(headless=True)
+        self.context = self.browser.new_context()
+        self.page = self.context.new_page()
+
+        yield
+
+        self.page.close()
+        self.context.close()
+        self.browser.close()
+        self.playwright.stop()
+
+    def test_websocket_reconnection(self, http_server):
+        """Client attempts reconnection on disconnect."""
+        self.page.goto(http_server)
+        self.page.wait_for_load_state("domcontentloaded")
+
+        status = self.page.locator("#status")
+        assert status.count() > 0, "Status element not found"
--- a/tests/test_app.py
+++ b/tests/test_app.py
@@ -0,0 +1,55 @@
+"""
+Tests for engine.app module.
+"""
+
+from engine.app import _normalize_preview_rows
+
+
+class TestNormalizePreviewRows:
+    """Tests for _normalize_preview_rows function."""
+
+    def test_empty_rows(self):
+        """Empty input returns empty list."""
+        result = _normalize_preview_rows([])
+        assert result == [""]
+
+    def test_strips_left_padding(self):
+        """Left padding is stripped."""
+        result = _normalize_preview_rows(["  content", "  more"])
+        assert all(not r.startswith(" ") for r in result)
+
+    def test_preserves_content(self):
+        """Content is preserved."""
+        result = _normalize_preview_rows(["  hello world  "])
+        assert "hello world" in result[0]
+
+    def test_handles_all_empty_rows(self):
+        """All empty rows returns single empty string."""
+        result = _normalize_preview_rows(["", "   ", ""])
+        assert result == [""]
+
+
+class TestAppConstants:
+    """Tests for app module constants."""
+
+    def test_title_defined(self):
+        """TITLE is defined."""
+        from engine.app import TITLE
+
+        assert len(TITLE) > 0
+
+    def test_title_lines_are_strings(self):
+        """TITLE contains string lines."""
+        from engine.app import TITLE
+
+        assert all(isinstance(line, str) for line in TITLE)
+
+
+class TestAppImports:
+    """Tests for app module imports."""
+
+    def test_app_imports_without_error(self):
+        """Module imports without error."""
+        from engine import app
+
+        assert app is not None
--- a/tests/test_controller.py
+++ b/tests/test_controller.py
@@ -83,35 +83,3 @@ class TestStreamControllerCleanup:
        controller.cleanup()

        mock_mic_instance.stop.assert_called_once()
-
-
-class TestStreamControllerWarmup:
-    """Tests for StreamController topic warmup."""
-
-    def test_warmup_topics_idempotent(self):
-        """warmup_topics can be called multiple times."""
-        StreamController._topics_warmed = False
-
-        with patch("urllib.request.urlopen") as mock_urlopen:
-            StreamController.warmup_topics()
-            StreamController.warmup_topics()
-
-            assert mock_urlopen.call_count >= 3
-
-    def test_warmup_topics_sets_flag(self):
-        """warmup_topics sets the warmed flag."""
-        StreamController._topics_warmed = False
-
-        with patch("urllib.request.urlopen"):
-            StreamController.warmup_topics()
-
-            assert StreamController._topics_warmed is True
-
-    def test_warmup_topics_skips_after_first(self):
-        """warmup_topics skips after first call."""
-        StreamController._topics_warmed = True
-
-        with patch("urllib.request.urlopen") as mock_urlopen:
-            StreamController.warmup_topics()
-
-            mock_urlopen.assert_not_called()
--- a/tests/test_fetch.py
+++ b/tests/test_fetch.py
@@ -0,0 +1,234 @@
+"""
+Tests for engine.fetch module.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+from engine.fetch import (
+    _fetch_gutenberg,
+    fetch_all,
+    fetch_feed,
+    fetch_poetry,
+    load_cache,
+    save_cache,
+)
+
+
+class TestFetchFeed:
+    """Tests for fetch_feed function."""
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_fetch_success(self, mock_urlopen):
+        """Successful feed fetch returns parsed feed."""
+        mock_response = MagicMock()
+        mock_response.read.return_value = b"<rss>test</rss>"
+        mock_urlopen.return_value = mock_response
+
+        result = fetch_feed("http://example.com/feed")
+
+        assert result is not None
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_fetch_network_error(self, mock_urlopen):
+        """Network error returns None."""
+        mock_urlopen.side_effect = Exception("Network error")
+
+        result = fetch_feed("http://example.com/feed")
+
+        assert result is None
+
+
+class TestFetchAll:
+    """Tests for fetch_all function."""
+
+    @patch("engine.fetch.fetch_feed")
+    @patch("engine.fetch.strip_tags")
+    @patch("engine.fetch.skip")
+    @patch("engine.fetch.boot_ln")
+    def test_fetch_all_success(self, mock_boot, mock_skip, mock_strip, mock_fetch_feed):
+        """Successful fetch returns items."""
+        mock_feed = MagicMock()
+        mock_feed.bozo = False
+        mock_feed.entries = [
+            {"title": "Headline 1", "published_parsed": (2024, 1, 1, 12, 0, 0)},
+            {"title": "Headline 2", "updated_parsed": (2024, 1, 2, 12, 0, 0)},
+        ]
+        mock_fetch_feed.return_value = mock_feed
+        mock_skip.return_value = False
+        mock_strip.side_effect = lambda x: x
+
+        items, linked, failed = fetch_all()
+
+        assert linked > 0
+        assert failed == 0
+
+    @patch("engine.fetch.fetch_feed")
+    @patch("engine.fetch.boot_ln")
+    def test_fetch_all_feed_error(self, mock_boot, mock_fetch_feed):
+        """Feed error increments failed count."""
+        mock_fetch_feed.return_value = None
+
+        items, linked, failed = fetch_all()
+
+        assert failed > 0
+
+    @patch("engine.fetch.fetch_feed")
+    @patch("engine.fetch.strip_tags")
+    @patch("engine.fetch.skip")
+    @patch("engine.fetch.boot_ln")
+    def test_fetch_all_skips_filtered(
+        self, mock_boot, mock_skip, mock_strip, mock_fetch_feed
+    ):
+        """Filtered headlines are skipped."""
+        mock_feed = MagicMock()
+        mock_feed.bozo = False
+        mock_feed.entries = [
+            {"title": "Sports scores"},
+            {"title": "Valid headline"},
+        ]
+        mock_fetch_feed.return_value = mock_feed
+        mock_skip.side_effect = lambda x: x == "Sports scores"
+        mock_strip.side_effect = lambda x: x
+
+        items, linked, failed = fetch_all()
+
+        assert any("Valid headline" in item[0] for item in items)
+
+
+class TestFetchGutenberg:
+    """Tests for _fetch_gutenberg function."""
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_gutenberg_success(self, mock_urlopen):
+        """Successful gutenberg fetch returns items."""
+        text = """Project Gutenberg
+
+*** START OF THE PROJECT GUTENBERG ***
+This is a test poem with multiple lines
+that should be parsed as a block.
+
+Another stanza with more content here.
+
+*** END OF THE PROJECT GUTENBERG ***
+"""
+        mock_response = MagicMock()
+        mock_response.read.return_value = text.encode("utf-8")
+        mock_urlopen.return_value = mock_response
+
+        result = _fetch_gutenberg("http://example.com/test", "Test")
+
+        assert len(result) > 0
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_gutenberg_network_error(self, mock_urlopen):
+        """Network error returns empty list."""
+        mock_urlopen.side_effect = Exception("Network error")
+
+        result = _fetch_gutenberg("http://example.com/test", "Test")
+
+        assert result == []
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_gutenberg_skips_short_blocks(self, mock_urlopen):
+        """Blocks shorter than 20 chars are skipped."""
+        text = """*** START OF THE ***
+Short
+*** END OF THE ***
+"""
+        mock_response = MagicMock()
+        mock_response.read.return_value = text.encode("utf-8")
+        mock_urlopen.return_value = mock_response
+
+        result = _fetch_gutenberg("http://example.com/test", "Test")
+
+        assert result == []
+
+    @patch("engine.fetch.urllib.request.urlopen")
+    def test_gutenberg_skips_all_caps_headers(self, mock_urlopen):
+        """All-caps lines are skipped as headers."""
+        text = """*** START OF THE ***
+THIS IS ALL CAPS HEADER
+more content here
+*** END OF THE ***
+"""
+        mock_response = MagicMock()
+        mock_response.read.return_value = text.encode("utf-8")
+        mock_urlopen.return_value = mock_response
+
+        result = _fetch_gutenberg("http://example.com/test", "Test")
+
+        assert len(result) > 0
+
+
+class TestFetchPoetry:
+    """Tests for fetch_poetry function."""
+
+    @patch("engine.fetch._fetch_gutenberg")
+    @patch("engine.fetch.boot_ln")
+    def test_fetch_poetry_success(self, mock_boot, mock_fetch):
+        """Successful poetry fetch returns items."""
+        mock_fetch.return_value = [
+            ("Stanza 1 content here", "Test", ""),
+            ("Stanza 2 content here", "Test", ""),
+        ]
+
+        items, linked, failed = fetch_poetry()
+
+        assert linked > 0
+        assert failed == 0
+
+    @patch("engine.fetch._fetch_gutenberg")
+    @patch("engine.fetch.boot_ln")
+    def test_fetch_poetry_failure(self, mock_boot, mock_fetch):
+        """Failed fetch increments failed count."""
+        mock_fetch.return_value = []
+
+        items, linked, failed = fetch_poetry()
+
+        assert failed > 0
+
+
+class TestCache:
+    """Tests for cache functions."""
+
+    @patch("engine.fetch._cache_path")
+    def test_load_cache_success(self, mock_path):
+        """Successful cache load returns items."""
+        mock_path.return_value.__str__ = MagicMock(return_value="/tmp/cache")
+        mock_path.return_value.exists.return_value = True
+        mock_path.return_value.read_text.return_value = json.dumps(
+            {"items": [("title", "source", "time")]}
+        )
+
+        result = load_cache()
+
+        assert result is not None
+
+    @patch("engine.fetch._cache_path")
+    def test_load_cache_missing_file(self, mock_path):
+        """Missing cache file returns None."""
+        mock_path.return_value.exists.return_value = False
+
+        result = load_cache()
+
+        assert result is None
+
+    @patch("engine.fetch._cache_path")
+    def test_load_cache_invalid_json(self, mock_path):
+        """Invalid JSON returns None."""
+        mock_path.return_value.exists.return_value = True
+        mock_path.return_value.read_text.side_effect = json.JSONDecodeError("", "", 0)
+
+        result = load_cache()
+
+        assert result is None
+
+    @patch("engine.fetch._cache_path")
+    def test_save_cache_success(self, mock_path):
+        """Save cache writes to file."""
+        mock_path.return_value.__truediv__ = MagicMock(
+            return_value=mock_path.return_value
+        )
+
+        save_cache([("title", "source", "time")])
--- a/tests/test_render.py
+++ b/tests/test_render.py
@@ -0,0 +1,232 @@
+"""
+Tests for engine.render module.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from engine.render import (
+    GRAD_COLS,
+    MSG_GRAD_COLS,
+    clear_font_cache,
+    font_for_lang,
+    lr_gradient,
+    lr_gradient_opposite,
+    make_block,
+)
+
+
+class TestGradientConstants:
+    """Tests for gradient color constants."""
+
+    def test_grad_cols_defined(self):
+        """GRAD_COLS is defined with expected length."""
+        assert len(GRAD_COLS) > 0
+        assert all(isinstance(c, str) for c in GRAD_COLS)
+
+    def test_msg_grad_cols_defined(self):
+        """MSG_GRAD_COLS is defined with expected length."""
+        assert len(MSG_GRAD_COLS) > 0
+        assert all(isinstance(c, str) for c in MSG_GRAD_COLS)
+
+    def test_grad_cols_start_with_white(self):
+        """GRAD_COLS starts with white."""
+        assert "231" in GRAD_COLS[0]
+
+    def test_msg_grad_cols_different_from_grad_cols(self):
+        """MSG_GRAD_COLS is different from GRAD_COLS."""
+        assert MSG_GRAD_COLS != GRAD_COLS
+
+
+class TestLrGradient:
+    """Tests for lr_gradient function."""
+
+    def test_empty_rows(self):
+        """Empty input returns empty output."""
+        result = lr_gradient([], 0.0)
+        assert result == []
+
+    def test_preserves_empty_rows(self):
+        """Empty rows are preserved."""
+        result = lr_gradient([""], 0.0)
+        assert result == [""]
+
+    def test_adds_gradient_to_content(self):
+        """Non-empty rows get gradient coloring."""
+        result = lr_gradient(["hello"], 0.0)
+        assert len(result) == 1
+        assert "\033[" in result[0]
+
+    def test_preserves_spaces(self):
+        """Spaces are preserved without coloring."""
+        result = lr_gradient(["hello world"], 0.0)
+        assert " " in result[0]
+
+    def test_offset_wraps_around(self):
+        """Offset wraps around at 1.0."""
+        result1 = lr_gradient(["hello"], 0.0)
+        result2 = lr_gradient(["hello"], 1.0)
+        assert result1 != result2 or result1 == result2
+
+
+class TestLrGradientOpposite:
+    """Tests for lr_gradient_opposite function."""
+
+    def test_uses_msg_grad_cols(self):
+        """Uses MSG_GRAD_COLS instead of GRAD_COLS."""
+        result = lr_gradient_opposite(["test"])
+        assert "\033[" in result[0]
+
+
+class TestClearFontCache:
+    """Tests for clear_font_cache function."""
+
+    def test_clears_without_error(self):
+        """Function runs without error."""
+        clear_font_cache()
+
+
+class TestFontForLang:
+    """Tests for font_for_lang function."""
+
+    @patch("engine.render.font")
+    def test_returns_default_for_none(self, mock_font):
+        """Returns default font when lang is None."""
+        result = font_for_lang(None)
+        assert result is not None
+
+    @patch("engine.render.font")
+    def test_returns_default_for_unknown_lang(self, mock_font):
+        """Returns default font for unknown language."""
+        result = font_for_lang("unknown_lang")
+        assert result is not None
+
+
+class TestMakeBlock:
+    """Tests for make_block function."""
+
+    @patch("engine.translate.translate_headline")
+    @patch("engine.translate.detect_location_language")
+    @patch("engine.render.font_for_lang")
+    @patch("engine.render.big_wrap")
+    @patch("engine.render.random")
+    def test_make_block_basic(
+        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
+    ):
+        """Basic make_block returns content, color, meta index."""
+        mock_wrap.return_value = ["Headline content", ""]
+        mock_random.choice.return_value = "\033[38;5;46m"
+
+        content, color, meta_idx = make_block(
+            "Test headline", "TestSource", "12:00", 80
+        )
+
+        assert len(content) > 0
+        assert color is not None
+        assert meta_idx >= 0
+
+    @pytest.mark.skip(reason="Requires full PIL/font environment")
+    @patch("engine.translate.translate_headline")
+    @patch("engine.translate.detect_location_language")
+    @patch("engine.render.font_for_lang")
+    @patch("engine.render.big_wrap")
+    @patch("engine.render.random")
+    def test_make_block_translation(
+        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
+    ):
+        """Translation is applied when mode is news."""
+        mock_wrap.return_value = ["Translated"]
+        mock_random.choice.return_value = "\033[38;5;46m"
+        mock_detect.return_value = "de"
+
+        with patch("engine.config.MODE", "news"):
+            content, _, _ = make_block("Test", "Source", "12:00", 80)
+            mock_translate.assert_called_once()
+
+    @patch("engine.translate.translate_headline")
+    @patch("engine.translate.detect_location_language")
+    @patch("engine.render.font_for_lang")
+    @patch("engine.render.big_wrap")
+    @patch("engine.render.random")
+    def test_make_block_no_translation_poetry(
+        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
+    ):
+        """No translation when mode is poetry."""
+        mock_wrap.return_value = ["Poem content"]
+        mock_random.choice.return_value = "\033[38;5;46m"
+
+        with patch("engine.config.MODE", "poetry"):
+            make_block("Test", "Source", "12:00", 80)
+            mock_translate.assert_not_called()
+
+    @patch("engine.translate.translate_headline")
+    @patch("engine.translate.detect_location_language")
+    @patch("engine.render.font_for_lang")
+    @patch("engine.render.big_wrap")
+    @patch("engine.render.random")
+    def test_make_block_meta_format(
+        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
+    ):
+        """Meta line includes source and timestamp."""
+        mock_wrap.return_value = ["Content"]
+        mock_random.choice.return_value = "\033[38;5;46m"
+
+        content, _, meta_idx = make_block("Test", "MySource", "14:30", 80)
+
+        meta_line = content[meta_idx]
+        assert "MySource" in meta_line
+        assert "14:30" in meta_line
+
+
+class TestRenderLine:
+    """Tests for render_line function."""
+
+    def test_empty_string(self):
+        """Empty string returns empty list."""
+        from engine.render import render_line
+
+        result = render_line("")
+        assert result == [""]
+
+    @pytest.mark.skip(reason="Requires real font/PIL setup")
+    def test_uses_default_font(self):
+        """Uses default font when none provided."""
+        from engine.render import render_line
+
+        with patch("engine.render.font") as mock_font:
+            mock_font.return_value = MagicMock()
+            mock_font.return_value.getbbox.return_value = (0, 0, 10, 10)
+            render_line("test")
+
+    def test_getbbox_returns_none(self):
+        """Handles None bbox gracefully."""
+        from engine.render import render_line
+
+        with patch("engine.render.font") as mock_font:
+            mock_font.return_value = MagicMock()
+            mock_font.return_value.getbbox.return_value = None
+            result = render_line("test")
+            assert result == [""]
+
+
+class TestBigWrap:
+    """Tests for big_wrap function."""
+
+    def test_empty_string(self):
+        """Empty string returns empty list."""
+        from engine.render import big_wrap
+
+        result = big_wrap("", 80)
+        assert result == []
+
+    @pytest.mark.skip(reason="Requires real font/PIL setup")
+    def test_single_word_fits(self):
+        """Single short word returns rendered."""
+        from engine.render import big_wrap
+
+        with patch("engine.render.font") as mock_font:
+            mock_font.return_value = MagicMock()
+            mock_font.return_value.getbbox.return_value = (0, 0, 10, 10)
+            result = big_wrap("test", 80)
+            assert len(result) > 0
--- a/tests/test_translate.py
+++ b/tests/test_translate.py
@@ -0,0 +1,115 @@
+"""
+Tests for engine.translate module.
+"""
+
+import json
+from unittest.mock import MagicMock, patch
+
+from engine.translate import (
+    _translate_cached,
+    detect_location_language,
+    translate_headline,
+)
+
+
+def clear_translate_cache():
+    """Clear the LRU cache between tests."""
+    _translate_cached.cache_clear()
+
+
+class TestDetectLocationLanguage:
+    """Tests for detect_location_language function."""
+
+    def test_returns_none_for_unknown_location(self):
+        """Returns None when no location pattern matches."""
+        result = detect_location_language("Breaking news about technology")
+        assert result is None
+
+    def test_detects_berlin(self):
+        """Detects Berlin location."""
+        result = detect_location_language("Berlin police arrest protesters")
+        assert result == "de"
+
+    def test_detects_paris(self):
+        """Detects Paris location."""
+        result = detect_location_language("Paris fashion week begins")
+        assert result == "fr"
+
+    def test_detects_tokyo(self):
+        """Detects Tokyo location."""
+        result = detect_location_language("Tokyo stocks rise")
+        assert result == "ja"
+
+    def test_detects_berlin_again(self):
+        """Detects Berlin location again."""
+        result = detect_location_language("Berlin marathon set to begin")
+        assert result == "de"
+
+    def test_case_insensitive(self):
+        """Detection is case insensitive."""
+        result = detect_location_language("BERLIN SUMMER FESTIVAL")
+        assert result == "de"
+
+    def test_returns_first_match(self):
+        """Returns first matching pattern."""
+        result = detect_location_language("Berlin in Paris for the event")
+        assert result == "de"
+
+
+class TestTranslateHeadline:
+    """Tests for translate_headline function."""
+
+    def test_returns_translated_text(self):
+        """Returns translated text from cache."""
+        clear_translate_cache()
+        with patch("engine.translate.translate_headline") as mock_fn:
+            mock_fn.return_value = "Translated title"
+            from engine.translate import translate_headline as th
+
+            result = th("Original title", "de")
+            assert result == "Translated title"
+
+    def test_uses_cached_result(self):
+        """Translation uses LRU cache."""
+        clear_translate_cache()
+        result1 = translate_headline("Test unique", "es")
+        result2 = translate_headline("Test unique", "es")
+        assert result1 == result2
+
+
+class TestTranslateCached:
+    """Tests for _translate_cached function."""
+
+    def test_translation_network_error(self):
+        """Network error returns original text."""
+        clear_translate_cache()
+        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.side_effect = Exception("Network error")
+
+            result = _translate_cached("Hello world", "de")
+
+            assert result == "Hello world"
+
+    def test_translation_invalid_json(self):
+        """Invalid JSON returns original text."""
+        clear_translate_cache()
+        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
+            mock_response = MagicMock()
+            mock_response.read.return_value = b"invalid json"
+            mock_urlopen.return_value = mock_response
+
+            result = _translate_cached("Hello", "de")
+
+            assert result == "Hello"
+
+    def test_translation_empty_response(self):
+        """Empty translation response returns original text."""
+        clear_translate_cache()
+        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
+            mock_response = MagicMock()
+            mock_response.read.return_value = json.dumps([[[""], None, "de"], None])
+            mock_urlopen.return_value = mock_response
+
+            result = _translate_cached("Hello", "de")
+
+            assert result == "Hello"
--- a/tests/test_websocket.py
+++ b/tests/test_websocket.py
@@ -0,0 +1,161 @@
+"""
+Tests for engine.display.backends.websocket module.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from engine.display.backends.websocket import WebSocketDisplay
+
+
+class TestWebSocketDisplayImport:
+    """Test that websocket module can be imported."""
+
+    def test_import_does_not_error(self):
+        """Module imports without error."""
+        from engine.display import backends
+
+        assert backends is not None
+
+
+class TestWebSocketDisplayInit:
+    """Tests for WebSocketDisplay initialization."""
+
+    def test_default_init(self):
+        """Default initialization sets correct defaults."""
+        with patch("engine.display.backends.websocket.websockets", None):
+            display = WebSocketDisplay()
+            assert display.host == "0.0.0.0"
+            assert display.port == 8765
+            assert display.http_port == 8766
+            assert display.width == 80
+            assert display.height == 24
+
+    def test_custom_init(self):
+        """Custom initialization uses provided values."""
+        with patch("engine.display.backends.websocket.websockets", None):
+            display = WebSocketDisplay(host="localhost", port=9000, http_port=9001)
+            assert display.host == "localhost"
+            assert display.port == 9000
+            assert display.http_port == 9001
+
+    def test_is_available_when_websockets_present(self):
+        """is_available returns True when websockets is available."""
+        pytest.importorskip("websockets")
+        display = WebSocketDisplay()
+        assert display.is_available() is True
+
+    @pytest.mark.skipif(
+        pytest.importorskip("websockets") is not None, reason="websockets is available"
+    )
+    def test_is_available_when_websockets_missing(self):
+        """is_available returns False when websockets is not available."""
+        display = WebSocketDisplay()
+        assert display.is_available() is False
+
+
+class TestWebSocketDisplayProtocol:
+    """Test that WebSocketDisplay satisfies Display protocol."""
+
+    def test_websocket_display_is_display(self):
+        """WebSocketDisplay satisfies Display protocol."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            assert hasattr(display, "init")
+            assert hasattr(display, "show")
+            assert hasattr(display, "clear")
+            assert hasattr(display, "cleanup")
+
+
+class TestWebSocketDisplayMethods:
+    """Tests for WebSocketDisplay methods."""
+
+    def test_init_stores_dimensions(self):
+        """init stores terminal dimensions."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            display.init(100, 40)
+            assert display.width == 100
+            assert display.height == 40
+
+    def test_client_count_initially_zero(self):
+        """client_count returns 0 when no clients connected."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            assert display.client_count() == 0
+
+    def test_get_ws_port(self):
+        """get_ws_port returns configured port."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay(port=9000)
+            assert display.get_ws_port() == 9000
+
+    def test_get_http_port(self):
+        """get_http_port returns configured port."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay(http_port=9001)
+            assert display.get_http_port() == 9001
+
+    def test_frame_delay_defaults_to_zero(self):
+        """get_frame_delay returns 0 by default."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            assert display.get_frame_delay() == 0.0
+
+    def test_set_frame_delay(self):
+        """set_frame_delay stores the value."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            display.set_frame_delay(0.05)
+            assert display.get_frame_delay() == 0.05
+
+
+class TestWebSocketDisplayCallbacks:
+    """Tests for WebSocketDisplay callback methods."""
+
+    def test_set_client_connected_callback(self):
+        """set_client_connected_callback stores callback."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            callback = MagicMock()
+            display.set_client_connected_callback(callback)
+            assert display._client_connected_callback is callback
+
+    def test_set_client_disconnected_callback(self):
+        """set_client_disconnected_callback stores callback."""
+        with patch("engine.display.backends.websocket.websockets", MagicMock()):
+            display = WebSocketDisplay()
+            callback = MagicMock()
+            display.set_client_disconnected_callback(callback)
+            assert display._client_disconnected_callback is callback
+
+
+class TestWebSocketDisplayUnavailable:
+    """Tests when WebSocket support is unavailable."""
+
+    @pytest.mark.skipif(
+        pytest.importorskip("websockets") is not None, reason="websockets is available"
+    )
+    def test_start_server_noop_when_unavailable(self):
+        """start_server does nothing when websockets unavailable."""
+        display = WebSocketDisplay()
+        display.start_server()
+        assert display._server_thread is None
+
+    @pytest.mark.skipif(
+        pytest.importorskip("websockets") is not None, reason="websockets is available"
+    )
+    def test_start_http_server_noop_when_unavailable(self):
+        """start_http_server does nothing when websockets unavailable."""
+        display = WebSocketDisplay()
+        display.start_http_server()
+        assert display._http_thread is None
+
+    @pytest.mark.skipif(
+        pytest.importorskip("websockets") is not None, reason="websockets is available"
+    )
+    def test_show_noops_when_unavailable(self):
+        """show does nothing when websockets unavailable."""
+        display = WebSocketDisplay()
+        display.show(["line1", "line2"])
Author	SHA1	Message	Date
David Gwilliam	dcd31469a5	feat(benchmark): add hook mode with baseline cache for pre-push checks - Fix lint errors and LSP issues in benchmark.py - Add --hook mode to compare against saved baseline - Add --baseline flag to save results as baseline - Add --threshold to configure degradation threshold (default 20%) - Add benchmark step to pre-push hook in hk.pkl - Update AGENTS.md with hk documentation links and benchmark runner docs	2026-03-15 22:57:55 -07:00
David Gwilliam	829c4ab63d	refactor: modularize display backends and add benchmark runner - Create engine/display/ package with registry pattern - Move displays to engine/display/backends/ (terminal, null, websocket, sixel) - Add DisplayRegistry with auto-discovery - Add benchmark.py for performance testing effects × displays matrix - Add mise tasks: benchmark, benchmark-json, benchmark-report - Update controller to use new display module	2026-03-15 22:25:28 -07:00
David Gwilliam	22dd063baa	feat: add SixelDisplay backend for terminal graphics - Implement pure Python Sixel encoder (no C dependency) - Add SixelDisplay class to display.py with ANSI parsing - Update controller._get_display() to handle sixel mode - Add --display sixel CLI flag - Add mise run-sixel task - Update docs with display modes	2026-03-15 22:13:44 -07:00
David Gwilliam	0f7203e4e0	feat: enable C&C, compact mise tasks, update docs - Cherry-pick C&C support (ntfy poller for commands, response handling) - Compact mise.toml with native dependency chaining - Update AGENTS.md with C&C documentation - Update README.md with display modes and C&C usage	2026-03-15 21:55:26 -07:00
David Gwilliam	ba050ada24	feat(cmdline): C&C with separate topics and rich output	2026-03-15 21:47:53 -07:00
David Gwilliam	d7b044ceae	feat(display): add configurable multi-backend display system	2026-03-15 21:17:16 -07:00
David Gwilliam	ac1306373d	feat(websocket): add WebSocket display backend for browser client	2026-03-15 20:54:03 -07:00
David Gwilliam	2650f7245e	merge: effects_plugins	2026-03-15 19:20:53 -07:00
David Gwilliam	b1f2b9d2be	feat(daemon): add display abstraction and daemon mode with C&C	2026-03-15 19:20:47 -07:00
David Gwilliam	c08a7d3cb0	feat(cmdline): add command-line interface for mainline control	2026-03-15 19:20:47 -07:00
David Gwilliam	d5a3edba97	feat(effects): add plugin architecture with performance monitoring	2026-03-15 19:20:47 -07:00
David Gwilliam	fb35458718	merge: testability_modularization	2026-03-15 19:20:43 -07:00
David Gwilliam	15de46722a	refactor: phase 4 - event-driven architecture foundation - Add EventBus class with pub/sub messaging (thread-safe) - Add emitter Protocol classes (EventEmitter, Startable, Stoppable) - Add event emission to NtfyPoller (NtfyMessageEvent) - Add event emission to MicMonitor (MicLevelEvent) - Update StreamController to publish stream start/end events - Add comprehensive tests for eventbus and emitters modules	2026-03-15 19:15:08 -07:00
David Gwilliam	35e5c8d38b	refactor: phase 3 - API efficiency improvements Add typed dataclasses for tuple returns: - types.py: HeadlineItem, FetchResult, Block dataclasses with legacy tuple converters - fetch.py: Add type hints and HeadlineTuple type alias Add pyright for static type checking: - Add pyright to dependencies - Verify type coverage with pyright (0 errors in core modules) This enables: - Named types instead of raw tuples (better IDE support, self-documenting) - Type-safe APIs across modules - Backward compatibility via to_tuple/from_tuple methods Note: Lazy imports skipped for render.py - startup impact is minimal.	2026-03-15 19:13:32 -07:00
David Gwilliam	cdc8094de2	refactor: phase 2 - modularization of scroll engine Split monolithic scroll.py into focused modules: - viewport.py: terminal size (tw/th), ANSI positioning helpers - frame.py: FrameTimer class, scroll step calculation - layers.py: message overlay, ticker zone, firehose rendering - scroll.py: simplified orchestrator, imports from new modules Add stream controller and event types for future event-driven architecture: - controller.py: StreamController for source initialization and stream lifecycle - events.py: EventType enum and event dataclasses (HeadlineEvent, FrameTickEvent, etc.) Added tests for new modules: - test_viewport.py: 8 tests for viewport utilities - test_frame.py: 10 tests for frame timing - test_layers.py: 13 tests for layer compositing - test_events.py: 11 tests for event types - test_controller.py: 6 tests for stream controller This enables: - Testable chunks with clear responsibilities - Reusable viewport utilities across modules - Better separation of concerns in render pipeline - Foundation for future event-driven architecture Also includes Phase 1 documentation updates in code comments.	2026-03-15 19:13:32 -07:00
David Gwilliam	f170143939	refactor: phase 1 - testability improvements - Add Config dataclass with get_config()/set_config() for injection - Add Config.from_args() for CLI argument parsing (testable) - Add platform font path detection (Darwin/Linux) - Bound translate cache with @lru_cache(maxsize=500) - Add fixtures for external dependencies (network, feeds, config) - Add 15 tests for Config class, from_args, and platform detection This enables testability by: - Allowing config injection instead of global mutable state - Supporting custom argv in from_args() for testing - Providing reusable fixtures for mocking network/filesystem - Preventing unbounded memory growth in translation cache Fixes: _arg_value/_arg_int not accepting custom argv	2026-03-15 19:13:32 -07:00
genewildish	19fb4bc4fe	Merge pull request 'docs/update-readme' (#23 ) from docs/update-readme into main Reviewed-on: #23	2026-03-16 00:09:10 +00:00
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