docs: use david's most recent README from feature/vector_display branch

Reviewed-on: #32

README.md

@@ -2,7 +2,7 @@
 
 > *Digital consciousness stream. Matrix aesthetic · THX-1138 hue.*
 
-A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with selectable color gradients (Verdant Green, Molten Orange, or Violet Purple). Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. Live messages can be pushed to the display over [ntfy.sh](https://ntfy.sh).
+A full-screen terminal news ticker that renders live global headlines in large OTF-font block characters with a white-hot → deep green gradient. Headlines auto-translate into the native script of their subject region. Ambient mic input warps the glitch rate in real time. A `--poetry` mode replaces the feed with public-domain literary passages. Live messages can be pushed to the display over [ntfy.sh](https://ntfy.sh).
 
 ---
 
@@ -15,7 +15,8 @@ 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
@@ -28,7 +29,20 @@ Or with uv:
 uv run mainline.py
 ```
 
-First run bootstraps a local `.mainline_venv/` and installs deps (`feedparser`, `Pillow`, `sounddevice`, `numpy`). Subsequent runs start immediately, loading from cache. With uv, run `uv sync` or `uv sync --all-extras` (includes mic support) instead.
+First run bootstraps dependencies. Use `uv sync --all-extras` for mic support.
+
+### Command & Control (C&C)
+
+Control mainline remotely using `cmdline.py`:
+
+```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
 
@@ -39,20 +53,32 @@ 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_PATH` | first file in `FONT_DIR` | Active display font |
-| `FONT_INDEX` | `0` | Face index within a font collection file |
+| `FONT_PICKER` | `True` | Show interactive font picker at boot |
-| `FONT_PICKER` | `True` | Show interactive font picker at boot (`--no-font-picker` to skip) |
 | `FONT_SZ` | `60` | Font render size (affects block density) |
 | `RENDER_H` | `8` | Terminal rows per headline line |
-| `SSAA` | `4` | Super-sampling factor (render at 4× then downsample) |
+| `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 stream endpoint |
+| `GRAD_SPEED` | `0.08` | Gradient sweep speed |
-| `NTFY_RECONNECT_DELAY` | `5` | Seconds before reconnecting after a dropped SSE stream |
+
-| `MESSAGE_DISPLAY_SECS` | `30` | How long an ntfy message holds the screen |
+### Display Modes
+
+Mainline supports multiple display backends:
+
+- **Terminal** (`--display terminal`): ANSI terminal output (default)
+- **WebSocket** (`--display websocket`): Stream to web browser clients
+- **Sixel** (`--display sixel`): Sixel graphics in supported terminals (iTerm2, mintty)
+- **Both** (`--display both`): Terminal + WebSocket simultaneously
+
+WebSocket mode serves a web client at http://localhost:8766 with ANSI color support and fullscreen mode.
 
 ### Feeds
 
@@ -62,30 +88,15 @@ All constants live in `engine/config.py`:
 
 ### Fonts
 
-A `fonts/` directory is bundled with demo faces (AgorTechnoDemo, AlphatronDemo, CSBishopDrawn, CubaTechnologyDemo, CyberformDemo, KATA, Microbots, ModernSpaceDemo, Neoform, Pixel Sparta, RaceHugoDemo, Resond, Robocops, Synthetix, Xeonic, and others). On startup, an interactive picker lists all discovered faces with a live half-block preview rendered at your configured size.
+A `fonts/` directory is bundled with demo faces. On startup, an interactive picker lists all discovered faces with a live half-block preview.
 
-Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selected face persists for that session.
+Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select.
 
-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.
+To add your own fonts, drop `.otf`, `.ttf`, or `.ttc` files into `fonts/`.
-
-### Color Schemes
-
-Mainline supports three color themes for the scrolling gradient: **Verdant Green**, **Molten Orange**, and **Violet Purple**. Each theme uses a precise color-opposite palette for ntfy message queue rendering (magenta, blue, and yellow respectively).
-
-On startup, an interactive picker presents all available color schemes:
-```
-  [1] Verdant Green    (white-hot → deep green)
-  [2] Molten Orange    (white-hot → deep orange)
-  [3] Violet Purple    (white-hot → deep purple)
-```
-
-Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selection applies only to the current session; you'll pick a fresh theme each run.
-
-**Note:** The boot UI (title, status lines, font picker menu) uses a hardcoded green accent color for visual continuity. Only the scrolling headlines and incoming messages render in the selected theme gradient.
 
 ### ntfy.sh
 
-Mainline polls a configurable ntfy.sh topic in the background. When a message arrives, the scroll pauses and the message renders full-screen for `MESSAGE_DISPLAY_SECS` seconds, then the stream resumes.
+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:
 
@@ -93,108 +104,68 @@ 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.
-
 ---
 
 ## Internals
 
 ### How it works
 
-- On launch, the font picker scans `fonts/` and presents a live-rendered TUI for face selection; `--no-font-picker` skips directly to stream
+- On launch, the font picker scans `fonts/` and presents a live-rendered TUI for face selection
-- 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
+- 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 (`▀▄█ `) at the configured font size
+- Headlines are rasterized via Pillow with 4× SSAA into half-block characters
-- The ticker uses a sweeping white-hot → deep green gradient; ntfy messages use a complementary white-hot → magenta/maroon gradient to distinguish them visually
+- The ticker uses a sweeping white-hot → deep green gradient
-- 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
+- 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 the glitch probability calculation each frame
+- The mic stream runs in a background thread, feeding RMS dB into glitch probability
-- The viewport scrolls through a virtual canvas of pre-rendered blocks; fade zones at top and bottom dissolve characters probabilistically
+- The viewport scrolls through pre-rendered blocks with fade zones
-- An ntfy.sh SSE stream runs in a background thread; incoming messages interrupt the scroll and render full-screen until dismissed or expired
+- An ntfy.sh SSE stream runs in a background thread for messages and C&C commands
 
 ### Architecture
 
-`mainline.py` is a thin entrypoint (venv bootstrap → `engine.app.main()`). All logic lives in the `engine/` package:
-
 ```
 engine/
-  __init__.py       package marker
+  __init__.py           package marker
-  app.py            main(), font picker TUI, boot sequence, signal handler
+  app.py                main(), font picker TUI, boot sequence, C&C poller
-  config.py         constants, CLI flags, glyph tables
+  config.py             constants, CLI flags, glyph tables
-  sources.py        FEEDS, POETRY_SOURCES, language/script maps
+  sources.py            FEEDS, POETRY_SOURCES, language/script maps
-  terminal.py       ANSI codes, tw/th, type_out, boot_ln
+  terminal.py           ANSI codes, tw/th, type_out, boot_ln
-  filter.py         HTML stripping, content filter
+  filter.py             HTML stripping, content filter
-  translate.py      Google Translate wrapper + region detection
+  translate.py          Google Translate wrapper + region detection
-  render.py         OTF → half-block pipeline (SSAA, gradient)
+  render.py             OTF → half-block pipeline (SSAA, gradient)
-  effects.py        noise, glitch_bar, fade, firehose
+  effects/              plugin architecture for visual effects
-  fetch.py          RSS/Gutenberg fetching + cache load/save
+    types.py            EffectPlugin ABC, EffectConfig, EffectContext
-  ntfy.py           NtfyPoller — standalone, zero internal deps
+    registry.py         effect registration and lookup
-  mic.py            MicMonitor — standalone, graceful fallback
+    chain.py            effect pipeline chaining
-  scroll.py         stream() frame loop + message rendering
+    controller.py       handles /effects commands
-  viewport.py       terminal dimension tracking (tw/th)
+    performance.py      performance monitoring
-  frame.py          scroll step calculation, timing
+    legacy.py           legacy functional effects
-  layers.py         ticker zone, firehose, message overlay rendering
+  effects_plugins/      effect plugin implementations
-  eventbus.py       thread-safe event publishing for decoupled communication
+    noise.py            noise effect
-  events.py         event types and definitions
+    fade.py             fade effect
-  controller.py     coordinates ntfy/mic monitoring and event publishing
+    glitch.py           glitch effect
-  emitters.py       background emitters for ntfy and mic
+    firehose.py         firehose effect
-  types.py          type definitions and dataclasses
+  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/              Display backend system
+    __init__.py         DisplayRegistry, get_monitor
+    backends/
+      terminal.py       ANSI terminal display
+      websocket.py      WebSocket server for browser clients
+      sixel.py         Sixel graphics (pure Python)
+      null.py          headless display for testing
+      multi.py         forwards to multiple displays
+  benchmark.py          performance benchmarking tool
 ```
 
-`ntfy.py` and `mic.py` have zero internal dependencies and can be imported by any other visualizer.
-
----
-
-## Extending
-
-`ntfy.py` and `mic.py` are fully standalone and designed to be reused by any terminal visualizer. `engine.render` is the importable rendering pipeline for non-terminal targets.
-
-### NtfyPoller
-
-```python
-from engine.ntfy import NtfyPoller
-
-poller = NtfyPoller("https://ntfy.sh/my_topic/json")
-poller.start()
-
-# in your render loop:
-msg = poller.get_active_message()  # → (title, body, timestamp) or None
-if msg:
-    title, body, ts = msg
-    render_my_message(title, body)  # visualizer-specific
-```
-
-Dependencies: `urllib.request`, `json`, `threading`, `time` — stdlib only. The `since=` parameter is managed automatically on reconnect.
-
-### MicMonitor
-
-```python
-from engine.mic import MicMonitor
-
-mic = MicMonitor(threshold_db=50)
-result = mic.start()   # None = sounddevice unavailable; False = stream failed; True = ok
-if result:
-    excess = mic.excess    # dB above threshold, clamped to 0
-    db = mic.db            # raw RMS dB level
-```
-
-Dependencies: `sounddevice`, `numpy` — both optional; degrades gracefully if unavailable.
-
-### Render pipeline
-
-`engine.render` exposes the OTF → raster pipeline independently of the terminal scroll loop. The planned `serve.py` extension will import it directly to pre-render headlines as 1-bit bitmaps for an ESP32 thin client:
-
-```python
-# planned — serve.py does not yet exist
-from engine.render import render_line, big_wrap
-from engine.fetch import fetch_all
-
-headlines = fetch_all()
-for h in headlines:
-    rows = big_wrap(h.text, font, width=800)  # list of half-block rows
-    # threshold to 1-bit, pack bytes, serve over HTTP
-```
-
-See `Mainline Renderer + ntfy Message Queue for ESP32.md` for the full server + thin client architecture.
-
 ---
 
 ## Development
@@ -205,7 +176,7 @@ Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 
 ```bash
 uv sync                              # minimal (no mic)
-uv sync --all-extras                 # with mic support (sounddevice + numpy)
+uv sync --all-extras                 # with mic support
 uv sync --all-extras --group dev     # full dev environment
 ```
 
@@ -215,24 +186,47 @@ With [mise](https://mise.jdx.dev/):
 
 ```bash
 mise run test            # run test suite
-mise run test-cov        # run with coverage report
+mise run test-cov       # run with coverage report
-mise run lint            # ruff check
+
-mise run lint-fix        # ruff check --fix
+mise run lint           # ruff check
-mise run format          # ruff format
+mise run lint-fix       # ruff check --fix
-mise run run             # uv run mainline.py
+mise run format         # ruff format
-mise run run-poetry      # uv run mainline.py --poetry
+
-mise run run-firehose    # uv run mainline.py --firehose
+mise run run            # terminal display
+mise run run-websocket  # web display only
+mise run run-sixel     # sixel graphics
+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 benchmark      # run performance benchmarks
+mise run benchmark-json # save as JSON
+
+mise run topics-init    # initialize ntfy topics
 ```
 
 ### Testing
 
-Tests live in `tests/` and cover `config`, `filter`, `mic`, `ntfy`, `sources`, and `terminal`.
-
 ```bash
 uv run pytest
 uv run pytest --cov=engine --cov-report=term-missing
+
+# Run with mise
+mise run test
+mise run test-cov
+
+# Run performance benchmarks
+mise run benchmark
+mise run benchmark-json
+
+# Run benchmark hook mode (for CI)
+uv run python -m engine.benchmark --hook
 ```
 
+Performance regression tests are in `tests/test_benchmark.py` marked with `@pytest.mark.benchmark`.
+
 ### Linting
 
 ```bash
@@ -247,28 +241,23 @@ Pre-commit hooks run lint automatically via `hk`.
 ## Roadmap
 
 ### Performance
-- **Concurrent feed fetching** — startup currently blocks sequentially on ~25 HTTP requests; `concurrent.futures.ThreadPoolExecutor` would cut load time to the slowest single feed
+- Concurrent feed fetching with ThreadPoolExecutor
-- **Background refresh** — re-fetch feeds in a daemon thread so a long session stays current without restart
+- Background feed refresh daemon
-- **Translation pre-fetch** — run translate calls concurrently during the boot sequence rather than on first render
+- Translation pre-fetch during boot
 
 ### Graphics
-- **Matrix rain underlay** — katakana column rain rendered at low opacity beneath the scrolling blocks as a background layer
+- Matrix rain katakana underlay
-- **CRT simulation** — subtle dim scanlines every N rows, occasional brightness ripple across the full screen
+- CRT scanline simulation
-- **Sixel / iTerm2 inline images** — bypass half-blocks entirely and stream actual bitmap frames for true resolution; would require a capable terminal
+- Sixel/iTerm2 inline images
-- **Parallax secondary column** — a second, dimmer, faster-scrolling stream of ambient text at reduced opacity on one side
+- Parallax secondary column
 
 ### Cyberpunk Vibes
-- **Keyword watch list** — highlight or strobe any headline matching tracked terms (names, topics, tickers)
+- Keyword watch list with strobe effects
-- **Breaking interrupt** — full-screen flash + synthesized blip when a high-priority keyword hits
+- Breaking interrupt with synthesized audio
-- **Live data overlay** — secondary ticker strip at screen edge: BTC price, ISS position, geomagnetic index
+- Live data overlay (BTC, ISS position)
-- **Theme switcher** — `--amber` (phosphor), `--ice` (electric cyan), `--red` (alert state) palette modes via CLI flag
+- Theme switcher (amber, ice, red)
-- **Persona modes** — `--surveillance`, `--oracle`, `--underground` as feed presets with matching color themes and boot copy
+- Persona modes (surveillance, oracle, underground)
-- **Synthesized audio** — short static bursts tied to glitch events, independent of mic input
-
-### Extensibility
-- **serve.py** — HTTP server that imports `engine.render` and `engine.fetch` directly to stream 1-bit bitmaps to an ESP32 display
-- **Rust port** — `ntfy.py` and `render.py` are the natural first targets; clear module boundaries make incremental porting viable
 
 ---
 
-*macOS only (script/system font paths for translation are hardcoded). Primary display font is user-selectable via the bundled `fonts/` picker. Python 3.10+.*
+*Python 3.10+. Primary display font is user-selectable via bundled `fonts/` picker.*

effects_plugins/__init__.py

@@ -5,6 +5,7 @@ PLUGIN_DIR = Path(__file__).parent
 
 def discover_plugins():
     from engine.effects.registry import get_registry
+    from engine.effects.types import EffectPlugin
 
     registry = get_registry()
     imported = {}
@@ -22,8 +23,8 @@ def discover_plugins():
                 attr = getattr(module, attr_name)
                 if (
                     isinstance(attr, type)
-                    and hasattr(attr, "name")
+                    and issubclass(attr, EffectPlugin)
-                    and hasattr(attr, "process")
+                    and attr is not EffectPlugin
                     and attr_name.endswith("Effect")
                 ):
                     plugin = attr()

effects_plugins/fade.py

@@ -3,7 +3,7 @@ import random
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 
 
-class FadeEffect:
+class FadeEffect(EffectPlugin):
     name = "fade"
     config = EffectConfig(enabled=True, intensity=1.0)
 

effects_plugins/firehose.py

@@ -7,7 +7,7 @@ from engine.sources import FEEDS, POETRY_SOURCES
 from engine.terminal import C_DIM, G_DIM, G_LO, RST, W_GHOST
 
 
-class FirehoseEffect:
+class FirehoseEffect(EffectPlugin):
     name = "firehose"
     config = EffectConfig(enabled=True, intensity=1.0)
 

effects_plugins/glitch.py

@@ -5,7 +5,7 @@ from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST
 
 
-class GlitchEffect:
+class GlitchEffect(EffectPlugin):
     name = "glitch"
     config = EffectConfig(enabled=True, intensity=1.0)
 

effects_plugins/noise.py

@@ -5,7 +5,7 @@ from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.terminal import C_DIM, G_DIM, G_LO, RST, W_GHOST
 
 
-class NoiseEffect:
+class NoiseEffect(EffectPlugin):
     name = "noise"
     config = EffectConfig(enabled=True, intensity=0.15)
 

engine/effects/types.py

@@ -1,3 +1,4 @@
+from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -8,10 +9,11 @@ class EffectContext:
     terminal_height: int
     scroll_cam: int
     ticker_height: int
-    mic_excess: float
+    camera_x: int = 0
-    grad_offset: float
+    mic_excess: float = 0.0
-    frame_number: int
+    grad_offset: float = 0.0
-    has_message: bool
+    frame_number: int = 0
+    has_message: bool = False
     items: list = field(default_factory=list)
 
 
@@ -22,15 +24,42 @@ class EffectConfig:
     params: dict[str, Any] = field(default_factory=dict)
 
 
-class EffectPlugin:
+class EffectPlugin(ABC):
     name: str
     config: EffectConfig
 
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
+    @abstractmethod
-        raise NotImplementedError
+    def process(self, buf: list[str], ctx: EffectContext) -> list[str]: ...
 
-    def configure(self, config: EffectConfig) -> None:
+    @abstractmethod
-        raise NotImplementedError
+    def configure(self, config: EffectConfig) -> None: ...
+
+
+def create_effect_context(
+    terminal_width: int = 80,
+    terminal_height: int = 24,
+    scroll_cam: int = 0,
+    ticker_height: int = 0,
+    camera_x: int = 0,
+    mic_excess: float = 0.0,
+    grad_offset: float = 0.0,
+    frame_number: int = 0,
+    has_message: bool = False,
+    items: list | None = None,
+) -> EffectContext:
+    """Factory function to create EffectContext with sensible defaults."""
+    return EffectContext(
+        terminal_width=terminal_width,
+        terminal_height=terminal_height,
+        scroll_cam=scroll_cam,
+        ticker_height=ticker_height,
+        camera_x=camera_x,
+        mic_excess=mic_excess,
+        grad_offset=grad_offset,
+        frame_number=frame_number,
+        has_message=has_message,
+        items=items or [],
+    )
 
 
 @dataclass