feat(daemon): add display abstraction and daemon mode with C&C

- 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

AGENTS.md

@@ -16,33 +16,43 @@ This project uses:
 mise run install
 
 # Or equivalently:
-uv sync --all-extras   # includes mic, websocket, sixel support
+uv sync
 ```
 
 ### Available Commands
 
 ```bash
-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)
-```
+# 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
 
-### Runtime Commands
+# Runtime
+mise run run        # Interactive terminal mode (news)
+mise run run-poetry # Interactive terminal mode (poetry)
+mise run run-firehose # Dense headline mode
 
-```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
+# 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)
 ```
 
 ## Git Hooks
@@ -60,30 +70,9 @@ 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 + benchmark hook
-
-## Benchmark Runner
-
-Benchmark tests are in `tests/test_benchmark.py` with `@pytest.mark.benchmark`.
-
-### Hook Mode (via pytest)
-
-Run benchmarks in hook mode to catch performance regressions:
-
-```bash
-mise run test-cov  # Run with coverage
-```
-
-The benchmark tests will fail if performance degrades beyond the threshold.
-
-The pre-push hook runs benchmark in hook mode to catch performance regressions before pushing.
+- **pre-push**: runs ruff check
 
 ## Workflow Rules
 
@@ -137,143 +126,142 @@ mise run test-cov
 
 The project uses pytest with strict marker enforcement. Test configuration is in `pyproject.toml` under `[tool.pytest.ini_options]`.
 
-### Test Coverage Strategy
-
-Current coverage: 56% (463 tests)
-
-Key areas with lower coverage (acceptable for now):
-- **app.py** (8%): Main entry point - integration heavy, requires terminal
-- **scroll.py** (10%): Terminal-dependent rendering logic (unused)
-
-Key areas with good coverage:
-- **display/backends/null.py** (95%): Easy to test headlessly
-- **display/backends/terminal.py** (96%): Uses mocking
-- **display/backends/multi.py** (100%): Simple forwarding logic
-- **effects/performance.py** (99%): Pure Python logic
-- **eventbus.py** (96%): Simple event system
-- **effects/controller.py** (95%): Effects command handling
-
-Areas needing more tests:
-- **websocket.py** (48%): Network I/O, hard to test in CI
-- **ntfy.py** (50%): Network I/O, hard to test in CI
-- **mic.py** (61%): Audio I/O, hard to test in CI
-
-Note: Terminal-dependent modules (scroll, layers render) are harder to test in CI.
-Performance regression tests are in `tests/test_benchmark.py` with `@pytest.mark.benchmark`.
-
 ## Architecture Notes
 
-- **ntfy.py** - standalone notification poller with zero internal dependencies
-- **sensors/** - Sensor framework (MicSensor, OscillatorSensor) for real-time input
+- **ntfy.py** and **mic.py** are standalone modules with zero internal dependencies
 - **eventbus.py** provides thread-safe event publishing for decoupled communication
-- **effects/** - plugin architecture with performance monitoring
-- The new pipeline architecture: source → render → effects → display
+- **controller.py** coordinates ntfy/mic monitoring
+- The render pipeline: fetch → render → effects → scroll → terminal output
+- **display.py** provides swappable display backends (TerminalDisplay, NullDisplay)
 
-#### Canvas & Camera
+## Operating Modes
 
-- **Canvas** (`engine/canvas.py`): 2D rendering surface with dirty region tracking
-- **Camera** (`engine/camera.py`): Viewport controller for scrolling content
+Mainline can run in two modes:
 
-The Canvas tracks dirty regions automatically when content is written (via `put_region`, `put_text`, `fill`), enabling partial buffer updates for optimized effect processing.
+### 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.
 
-### Pipeline Architecture
+### 2. Daemon + Command Mode (Recommended for Long-Running)
 
-The new Stage-based pipeline architecture provides capability-based dependency resolution:
+The recommended approach for persistent displays:
 
-- **Stage** (`engine/pipeline/core.py`): Base class for pipeline stages
-- **Pipeline** (`engine/pipeline/controller.py`): Executes stages with capability-based dependency resolution
-- **StageRegistry** (`engine/pipeline/registry.py`): Discovers and registers stages
-- **Stage Adapters** (`engine/pipeline/adapters.py`): Wraps existing components as stages
+```bash
+# Start the daemon (headless rendering)
+mise run daemon
 
-#### Capability-Based Dependencies
+# Send commands via ntfy
+mise run cmd "/effects list"
+mise run cmd "/effects noise off"
+mise run cmd "/effects stats"
 
-Stages declare capabilities (what they provide) and dependencies (what they need). The Pipeline resolves dependencies using prefix matching:
-- `"source"` matches `"source.headlines"`, `"source.poetry"`, etc.
-- This allows flexible composition without hardcoding specific stage names
+# Watch mode (continuous stats polling)
+mise run cmd-stats
 
-#### Sensor Framework
+# Stop the daemon
+mise run daemon-stop
+```
 
-- **Sensor** (`engine/sensors/__init__.py`): Base class for real-time input sensors
-- **SensorRegistry**: Discovers available sensors
-- **SensorStage**: Pipeline adapter that provides sensor values to effects
-- **MicSensor** (`engine/sensors/mic.py`): Self-contained microphone input
-- **OscillatorSensor** (`engine/sensors/oscillator.py`): Test sensor for development
-- **PipelineMetricsSensor** (`engine/sensors/pipeline_metrics.py`): Exposes pipeline metrics as sensor values
+#### How It Works
 
-Sensors support param bindings to drive effect parameters in real-time.
+- **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
 
-#### Pipeline Introspection
+#### Available Commands
 
-- **PipelineIntrospectionSource** (`engine/data_sources/pipeline_introspection.py`): Renders live ASCII visualization of pipeline DAG with metrics
-- **PipelineIntrospectionDemo** (`engine/pipeline/pipeline_introspection_demo.py`): 3-phase demo controller for effect animation
+```
+/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
+```
 
-Preset: `pipeline-inspect` - Live pipeline introspection with DAG and performance metrics
+## Effects Plugin System
 
-#### Partial Update Support
+The effects system is implemented as a plugin architecture in `engine/effects/`.
 
-Effect plugins can opt-in to partial buffer updates for performance optimization:
-- Set `supports_partial_updates = True` on the effect class
-- Implement `process_partial(buf, ctx, partial)` method
-- The `PartialUpdate` dataclass indicates which regions changed
+### Core Components
 
-### Preset System
+| 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 |
 
-Presets use TOML format (no external dependencies):
+### Creating a New Effect
 
-- Built-in: `engine/presets.toml`
-- User config: `~/.config/mainline/presets.toml`
-- Local override: `./presets.toml`
+Create a file in `effects_plugins/` with a class ending in `Effect`:
 
-- **Preset loader** (`engine/pipeline/preset_loader.py`): Loads and validates presets
-- **PipelinePreset** (`engine/pipeline/presets.py`): Dataclass for preset configuration
+```python
+from engine.effects.types import EffectConfig, EffectContext
 
-Functions:
-- `validate_preset()` - Validate preset structure
-- `validate_signal_path()` - Detect circular dependencies
-- `generate_preset_toml()` - Generate skeleton preset
+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
+```
 
-### Display System
+### NTFY Commands
 
-- **Display abstraction** (`engine/display/`): swap display backends via the Display protocol
-  - `display/backends/terminal.py` - ANSI terminal output
-  - `display/backends/websocket.py` - broadcasts to web clients via WebSocket
-  - `display/backends/sixel.py` - renders to Sixel graphics (pure Python, no C dependency)
-  - `display/backends/null.py` - headless display for testing
-  - `display/backends/multi.py` - forwards to multiple displays simultaneously
-  - `display/__init__.py` - DisplayRegistry for backend discovery
+Send commands via `cmdline.py` or directly to the C&C topic:
 
-- **WebSocket display** (`engine/display/backends/websocket.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
+```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"
 
-- **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
+# Or directly via curl
+curl -d "/effects list" https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd
+```
 
-### Effect Plugin System
+The cmdline tool polls the response topic for the daemon's reply.
 
-- **EffectPlugin ABC** (`engine/effects/types.py`): abstract base class for effects
-  - All effects must inherit from EffectPlugin and implement `process()` and `configure()`
-  - Runtime discovery via `effects_plugins/__init__.py` using `issubclass()` checks
-  
-- **EffectRegistry** (`engine/effects/registry.py`): manages registered effects
-- **EffectChain** (`engine/effects/chain.py`): chains effects in pipeline order
+## Conventional Commits
 
-### Command & Control
+Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
 
-- 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)
+```
+<type>(<scope>): <description>
 
-### Pipeline Documentation
+[optional body]
 
-The rendering pipeline is documented in `docs/PIPELINE.md` using Mermaid diagrams.
+[optional footer(s)]
+```
 
-**IMPORTANT**: When making significant architectural changes to the rendering pipeline (new layers, effects, display backends), update `docs/PIPELINE.md` to reflect the changes:
-1. Edit `docs/PIPELINE.md` with the new architecture
-2. If adding new SVG diagrams, render them manually using an external tool (e.g., Mermaid Live Editor)
-3. Commit both the markdown and any new diagram files
+### 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
+```

README.md

@@ -6,45 +6,65 @@ A full-screen terminal news ticker that renders live global headlines in large O
 
 ---
 
-## Using
-
-### Run
+## 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 --display websocket  # web browser display only
-python3 mainline.py --display both       # terminal + web browser
+python3 mainline.py --refresh            # force re-fetch (bypass cache)
 python3 mainline.py --no-font-picker     # skip interactive font picker
 python3 mainline.py --font-file path.otf # use a specific font file
 python3 mainline.py --font-dir ~/fonts   # scan a different font folder
 python3 mainline.py --font-index 1       # select face index within a collection
 ```
 
-Or with uv:
+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:
 
 ```bash
-uv run mainline.py
+# 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
 ```
 
-First run bootstraps dependencies. Use `uv sync --all-extras` for mic support.
+### How It Works
 
-### Command & Control (C&C)
+- **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
 
-Control mainline remotely using `cmdline.py`:
+### Available Commands
 
-```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)
+```
+/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
 ```
 
-Commands are sent via ntfy.sh topics - useful for controlling a daemonized mainline instance.
+---
 
-### Config
+## Config
 
 All constants live in `engine/config.py`:
 
@@ -53,50 +73,98 @@ 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 |
-| `FONT_PICKER` | `True` | Show interactive font picker at boot |
+| `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_SZ` | `60` | Font render size (affects block density) |
 | `RENDER_H` | `8` | Terminal rows per headline line |
-| `SSAA` | `4` | Super-sampling factor |
+| `SSAA` | `4` | Super-sampling factor (render at 4× then downsample) |
 | `SCROLL_DUR` | `5.625` | Seconds per headline |
 | `FRAME_DT` | `0.05` | Frame interval in seconds (20 FPS) |
+| `GRAD_SPEED` | `0.08` | Gradient sweep speed (cycles/sec, ~12s full sweep) |
 | `FIREHOSE_H` | `12` | Firehose zone height (terminal rows) |
-| `GRAD_SPEED` | `0.08` | Gradient sweep speed |
+| `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 |
 
-### Display Modes
+---
 
-Mainline supports multiple display backends:
+## Fonts
 
-- **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
+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.
 
-WebSocket mode serves a web client at http://localhost:8766 with ANSI color support and fullscreen mode.
+Navigation: `↑`/`↓` or `j`/`k` to move, `Enter` or `q` to select. The selected face persists for that session.
 
-### Feeds
+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
 
 ~25 sources across four categories: **Science & Technology**, **Economics & Business**, **World & Politics**, **Culture & Ideas**. Add or swap feeds in `engine/sources.py` → `FEEDS`.
 
 **Poetry mode** pulls from Project Gutenberg: Whitman, Dickinson, Thoreau, Emerson. Sources are in `engine/sources.py` → `POETRY_SOURCES`.
 
-### Fonts
+---
 
-A `fonts/` directory is bundled with demo faces. On startup, an interactive picker lists all discovered faces with a live half-block preview.
+## ntfy.sh Integration
 
-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.
+Mainline polls a configurable ntfy.sh topic in the background. When a message arrives, the scroll pauses and the message renders full-screen for `MESSAGE_DISPLAY_SECS` seconds, then the stream resumes.
 
 To push a message:
 
@@ -104,160 +172,44 @@ 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:
 
-## 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
-    types.py            EffectPlugin ABC, EffectConfig, EffectContext
-    registry.py         effect registration and lookup
-    chain.py            effect pipeline chaining
-    controller.py       handles /effects commands
-    performance.py      performance monitoring
-    legacy.py           legacy functional effects
-  effects_plugins/      effect plugin implementations
-    noise.py            noise effect
-    fade.py             fade effect
-    glitch.py           glitch effect
-    firehose.py         firehose effect
-  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
+```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
 ```
 
 ---
 
-## Development
-
-### Setup
-
-Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
-
-```bash
-uv sync                              # minimal (no mic)
-uv sync --all-extras                 # with mic support
-uv sync --all-extras --group dev     # full dev environment
-```
-
-### Tasks
-
-With [mise](https://mise.jdx.dev/):
-
-```bash
-mise run test            # run test suite
-mise run test-cov       # run with coverage report
-
-mise run lint           # ruff check
-mise run lint-fix       # ruff check --fix
-mise run format         # ruff format
-
-mise run run            # 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
-
-```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
-uv run ruff check engine/ mainline.py
-uv run ruff format engine/ mainline.py
-```
-
-Pre-commit hooks run lint automatically via `hk`.
-
----
-
-## Roadmap
+## Ideas / Future
 
 ### Performance
-- Concurrent feed fetching with ThreadPoolExecutor
-- Background feed refresh daemon
-- Translation pre-fetch during boot
+- **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
 
 ### Graphics
-- Matrix rain katakana underlay
-- CRT scanline simulation
-- Sixel/iTerm2 inline images
-- Parallax secondary column
+- **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
 
 ### 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)
+- **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
+
+### 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
 
 ---
 
-*Python 3.10+. Primary display font is user-selectable via bundled `fonts/` picker.*
+*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

client/index.html

@@ -1,366 +0,0 @@
-<!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>

cmdline.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 """
 Command-line utility for interacting with mainline via ntfy.
 
@@ -21,11 +20,6 @@ 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

docs/LEGACY_CLEANUP_CHECKLIST.md

@@ -1,239 +0,0 @@
-# Legacy Code Cleanup - Actionable Checklist
-
-## Phase 1: Safe Removals (0 Risk, Run Immediately)
-
-These modules have ZERO dependencies and can be removed without any testing:
-
-### Files to Delete
-
-```bash
-# Core modules (402 lines total)
-rm /home/dietpi/src/Mainline/engine/emitters.py (25 lines)
-rm /home/dietpi/src/Mainline/engine/beautiful_mermaid.py (4107 lines) 
-rm /home/dietpi/src/Mainline/engine/pipeline_viz.py (364 lines)
-
-# Test files (2145 bytes)
-rm /home/dietpi/src/Mainline/tests/test_emitters.py
-
-# Configuration/cleanup
-# Remove from pipeline.py: introspect_pipeline_viz() method calls
-# Remove from pipeline.py: introspect_animation() references to pipeline_viz
-```
-
-### Verification Commands
-
-```bash
-# Verify emitters.py has zero references
-grep -r "from engine.emitters\|import.*emitters" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv"
-# Expected: NO RESULTS
-
-# Verify beautiful_mermaid.py only used by pipeline_viz
-grep -r "beautiful_mermaid" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv"
-# Expected: Only one match in pipeline_viz.py
-
-# Verify pipeline_viz.py has zero real usage
-grep -r "pipeline_viz\|CameraLarge\|PipelineIntrospection" /home/dietpi/src/Mainline --include="*.py" | grep -v "__pycache__" | grep -v ".venv" | grep -v "engine/pipeline_viz.py"
-# Expected: Only references in pipeline.py's introspection method
-```
-
-### After Deletion - Cleanup Steps
-
-1. Remove these lines from `engine/pipeline.py`:
-
-```python
-# Remove method: introspect_pipeline_viz() (entire method)
-def introspect_pipeline_viz(self) -> None:
-    # ... remove this entire method ...
-    pass
-
-# Remove method call from introspect():
-self.introspect_pipeline_viz()
-
-# Remove import line:
-elif "pipeline_viz" in node.module or "CameraLarge" in node.name:
-```
-
-2. Update imports in `engine/pipeline/__init__.py` if pipeline_viz is exported
-
-3. Run test suite to verify:
-```bash
-mise run test
-```
-
----
-
-## Phase 2: Audit Required
-
-### Action Items
-
-#### 2.1 Pygame Backend Check
-
-```bash
-# Find all preset definitions
-grep -r "display.*=.*['\"]pygame" /home/dietpi/src/Mainline --include="*.py" --include="*.toml"
-
-# Search preset files
-grep -r "display.*pygame" /home/dietpi/src/Mainline/engine/presets.toml
-grep -r "pygame" /home/dietpi/src/Mainline/presets.toml
-
-# If NO results: Safe to remove
-rm /home/dietpi/src/Mainline/engine/display/backends/pygame.py
-# And remove from DisplayRegistry.__init__: cls.register("pygame", PygameDisplay)
-# And remove import: from engine.display.backends.pygame import PygameDisplay
-
-# If results exist: Keep the backend
-```
-
-#### 2.2 Kitty Backend Check
-
-```bash
-# Find all preset definitions
-grep -r "display.*=.*['\"]kitty" /home/dietpi/src/Mainline --include="*.py" --include="*.toml"
-
-# Search preset files  
-grep -r "display.*kitty" /home/dietpi/src/Mainline/engine/presets.toml
-grep -r "kitty" /home/dietpi/src/Mainline/presets.toml
-
-# If NO results: Safe to remove
-rm /home/dietpi/src/Mainline/engine/display/backends/kitty.py
-# And remove from DisplayRegistry.__init__: cls.register("kitty", KittyDisplay)
-# And remove import: from engine.display.backends.kitty import KittyDisplay
-
-# If results exist: Keep the backend
-```
-
-#### 2.3 Animation Module Check
-
-```bash
-# Search for actual usage of AnimationController, create_demo_preset, create_pipeline_preset
-grep -r "AnimationController\|create_demo_preset\|create_pipeline_preset" /home/dietpi/src/Mainline --include="*.py" | grep -v "animation.py" | grep -v "test_" | grep -v ".venv"
-
-# If NO results: Safe to remove
-rm /home/dietpi/src/Mainline/engine/animation.py
-
-# If results exist: Keep the module
-```
-
----
-
-## Phase 3: Known Future Removals (Don't Remove Yet)
-
-These modules are marked deprecated and still in use. Plan to remove after their clients are migrated:
-
-### Schedule for Removal
-
-#### After scroll.py clients migrated:
-```bash
-rm /home/dietpi/src/Mainline/engine/scroll.py
-```
-
-#### Consolidate legacy modules:
-```bash
-# After render.py functions are no longer called from adapters:
-# Move render.py to engine/legacy/render.py
-# Consolidate render.py with effects/legacy.py
-
-# After layers.py functions are no longer called:
-# Move layers.py to engine/legacy/layers.py
-# Move effects/legacy.py functions alongside
-```
-
-#### After legacy adapters are phased out:
-```bash
-rm /home/dietpi/src/Mainline/engine/pipeline/adapters.py (or move to legacy)
-```
-
----
-
-## How to Verify Changes
-
-After making changes, run:
-
-```bash
-# Run full test suite
-mise run test
-
-# Run with coverage
-mise run test-cov
-
-# Run linter
-mise run lint
-
-# Check for import errors
-python3 -c "import engine.app; print('OK')"
-```
-
----
-
-## Summary of File Changes
-
-### Phase 1 Deletions (Safe)
-
-| File | Lines | Purpose | Verify With |
-|------|-------|---------|------------|
-| engine/emitters.py | 25 | Unused protocols | `grep -r emitters` |
-| engine/beautiful_mermaid.py | 4107 | Unused diagram renderer | `grep -r beautiful_mermaid` |
-| engine/pipeline_viz.py | 364 | Unused visualization | `grep -r pipeline_viz` |
-| tests/test_emitters.py | 2145 bytes | Tests for emitters | Auto-removed with module |
-
-### Phase 2 Conditional
-
-| File | Size | Condition | Action |
-|------|------|-----------|--------|
-| engine/display/backends/pygame.py | 9185 | If not in presets | Delete or keep |
-| engine/display/backends/kitty.py | 5305 | If not in presets | Delete or keep |
-| engine/animation.py | 340 | If not used | Safe to delete |
-
-### Phase 3 Future
-
-| File | Lines | When | Action |
-|------|-------|------|--------|
-| engine/scroll.py | 156 | Deprecated | Plan removal |
-| engine/render.py | 274 | Still used | Consolidate later |
-| engine/layers.py | 272 | Still used | Consolidate later |
-
----
-
-## Testing After Cleanup
-
-1. **Unit Tests**: `mise run test`
-2. **Coverage Report**: `mise run test-cov`
-3. **Linting**: `mise run lint`
-4. **Manual Testing**: `mise run run` (run app in various presets)
-
-### Expected Test Results After Phase 1
-
-- No new test failures
-- test_emitters.py collection skipped (module removed)
-- All other tests pass
-- No import errors
-
----
-
-## Rollback Plan
-
-If issues arise after deletion:
-
-```bash
-# Check git status
-git status
-
-# Revert specific deletions
-git restore engine/emitters.py
-git restore engine/beautiful_mermaid.py
-# etc.
-
-# Or full rollback
-git checkout HEAD -- engine/
-git checkout HEAD -- tests/
-```
-
----
-
-## Notes
-
-- All Phase 1 deletions are verified to have ZERO usage
-- Phase 2 requires checking presets (can be done via grep)
-- Phase 3 items are actively used but marked for future removal
-- Keep test files synchronized with module deletions
-- Update AGENTS.md after Phase 1 completion

docs/LEGACY_CODE_ANALYSIS.md

@@ -1,286 +0,0 @@
-# Legacy & Dead Code Analysis - Mainline Codebase
-
-## Executive Summary
-
-The codebase contains **702 lines** of clearly marked legacy code spread across **4 main modules**, plus several candidate modules that may be unused. The legacy code primarily relates to the old rendering pipeline that has been superseded by the new Stage-based pipeline architecture.
-
----
-
-## 1. MARKED DEPRECATED MODULES (Should Remove/Refactor)
-
-### 1.1 `engine/scroll.py` (156 lines)
-- **Status**: DEPRECATED - Marked with deprecation notice
-- **Why**: Legacy rendering/orchestration code replaced by pipeline architecture
-- **Usage**: Used by legacy demo mode via scroll.stream()
-- **Dependencies**: 
-  - Imports: camera, display, layers, viewport, frame
-  - Used by: scroll.py is only imported in tests and demo mode
-- **Risk**: LOW - Clean deprecation boundary
-- **Recommendation**: **SAFE TO REMOVE**
-  - This is the main rendering loop orchestrator for the old system
-  - All new code uses the Pipeline architecture
-  - Demo mode is transitioning to pipeline presets
-  - Consider keeping test_layers.py for testing layer functions
-
-### 1.2 `engine/render.py` (274 lines)
-- **Status**: DEPRECATED - Marked with deprecation notice  
-- **Why**: Legacy rendering code for font loading, text rasterization, gradient coloring
-- **Contains**:
-  - `render_line()` - Renders text to terminal half-blocks using PIL
-  - `big_wrap()` - Word-wrap text fitting
-  - `lr_gradient()` - Left-to-right color gradients
-  - `make_block()` - Assembles headline blocks
-- **Usage**:
-  - layers.py imports: big_wrap, lr_gradient, lr_gradient_opposite
-  - scroll.py conditionally imports make_block
-  - adapters.py uses make_block
-  - test_render.py tests these functions
-- **Risk**: MEDIUM - Used by legacy adapters and layers
-- **Recommendation**: **KEEP FOR NOW**
-  - These functions are still used by adapters for legacy support
-  - Could be moved to legacy submodule if cleanup needed
-  - Consider marking functions individually as deprecated
-
-### 1.3 `engine/layers.py` (272 lines)
-- **Status**: DEPRECATED - Marked with deprecation notice
-- **Why**: Legacy rendering layer logic for effects, overlays, firehose
-- **Contains**:
-  - `render_ticker_zone()` - Renders ticker content
-  - `render_firehose()` - Renders firehose effect
-  - `render_message_overlay()` - Renders messages
-  - `apply_glitch()` - Applies glitch effect
-  - `process_effects()` - Legacy effect chain
-  - `get_effect_chain()` - Access to legacy effect chain
-- **Usage**:
-  - scroll.py imports multiple functions
-  - effects/controller.py imports get_effect_chain as fallback
-  - effects/__init__.py imports get_effect_chain as fallback
-  - adapters.py imports render_firehose, render_ticker_zone
-  - test_layers.py tests these functions
-- **Risk**: MEDIUM - Used as fallback in effects system
-- **Recommendation**: **KEEP FOR NOW**
-  - Legacy effects system relies on this as fallback
-  - Used by adapters for backwards compatibility
-  - Mark individual functions as deprecated
-
-### 1.4 `engine/animation.py` (340 lines)
-- **Status**: UNDEPRECATED but largely UNUSED
-- **Why**: Animation system with Clock, AnimationController, Preset classes
-- **Contains**:
-  - Clock - High-resolution timer
-  - AnimationController - Manages timed events and parameters
-  - Preset - Bundles pipeline config + animation
-  - Helper functions: create_demo_preset(), create_pipeline_preset()
-  - Easing functions: linear_ease, ease_in_out, ease_out_bounce
-- **Usage**:
-  - Documentation refers to it in pipeline.py docstrings
-  - introspect_animation() method exists but generates no actual content
-  - No actual imports of AnimationController found outside animation.py itself
-  - Demo presets in animation.py are never called
-  - PipelineParams dataclass is defined here but animation system never used
-- **Risk**: LOW - Isolated module with no real callers
-- **Recommendation**: **CONSIDER REMOVING**
-  - This appears to be abandoned experimental code
-  - The pipeline system doesn't actually use animation controllers
-  - If animation is needed in future, should be redesigned
-  - Safe to remove without affecting current functionality
-
----
-
-## 2. COMPLETELY UNUSED MODULES (Safe to Remove)
-
-### 2.1 `engine/emitters.py` (25 lines)
-- **Status**: UNUSED - Protocol definitions only
-- **Contains**: Three Protocol classes:
-  - EventEmitter - Define subscribe/unsubscribe interface
-  - Startable - Define start() interface
-  - Stoppable - Define stop() interface
-- **Usage**: ZERO references found in codebase
-- **Risk**: NONE - Dead code
-- **Recommendation**: **SAFE TO REMOVE**
-  - Protocol definitions are not used anywhere
-  - EventBus uses its own implementation, doesn't inherit from these
-
-### 2.2 `engine/beautiful_mermaid.py` (4107 lines!)
-- **Status**: UNUSED - Large ASCII renderer for Mermaid diagrams
-- **Why**: Pure Python Mermaid → ASCII renderer (ported from TypeScript)
-- **Usage**:
-  - Only imported in pipeline_viz.py
-  - pipeline_viz.py is not imported anywhere in codebase
-  - Never called in production code
-- **Risk**: NONE - Dead code
-- **Recommendation**: **SAFE TO REMOVE**
-  - Huge module (4000+ lines) with zero real usage
-  - Only used by experimental pipeline_viz which itself is unused
-  - Consider keeping as optional visualization tool if needed later
-
-### 2.3 `engine/pipeline_viz.py` (364 lines)
-- **Status**: UNUSED - Pipeline visualization module
-- **Contains**: CameraLarge camera mode for pipeline visualization
-- **Usage**: 
-  - Only referenced in pipeline.py's introspect_pipeline_viz() method
-  - This introspection method generates no actual output
-  - Never instantiated or called in real code
-- **Risk**: NONE - Experimental dead code
-- **Recommendation**: **SAFE TO REMOVE**
-  - Depends on beautiful_mermaid which is also unused
-  - Remove together with beautiful_mermaid
-
----
-
-## 3. UNUSED DISPLAY BACKENDS (Lower Priority)
-
-These backends are registered in DisplayRegistry but may not be actively used:
-
-### 3.1 `engine/display/backends/pygame.py` (9185 bytes)
-- **Status**: REGISTERED but potentially UNUSED
-- **Usage**: Registered in DisplayRegistry
-- **Last used in**: Demo mode (may have been replaced)
-- **Risk**: LOW - Backend system is pluggable
-- **Recommendation**: CHECK USAGE
-  - Verify if any presets use "pygame" display
-  - If not used, can remove
-  - Otherwise keep as optional backend
-
-### 3.2 `engine/display/backends/kitty.py` (5305 bytes)
-- **Status**: REGISTERED but potentially UNUSED
-- **Usage**: Registered in DisplayRegistry
-- **Last used in**: Kitty terminal graphics protocol
-- **Risk**: LOW - Backend system is pluggable
-- **Recommendation**: CHECK USAGE
-  - Verify if any presets use "kitty" display
-  - If not used, can remove
-  - Otherwise keep as optional backend
-
-### 3.3 `engine/display/backends/multi.py` (1137 bytes)
-- **Status**: REGISTERED and likely USED
-- **Usage**: MultiDisplay for simultaneous output
-- **Risk**: LOW - Simple wrapper
-- **Recommendation**: KEEP
-
----
-
-## 4. TEST FILES THAT MAY BE OBSOLETE
-
-### 4.1 `tests/test_emitters.py` (2145 bytes)
-- **Status**: ORPHANED
-- **Why**: Tests for unused emitters protocols
-- **Recommendation**: **SAFE TO REMOVE**
-  - Remove with engine/emitters.py
-
-### 4.2 `tests/test_render.py` (7628 bytes)
-- **Status**: POTENTIALLY USEFUL
-- **Why**: Tests for legacy render functions still used by adapters
-- **Recommendation**: **KEEP FOR NOW**
-  - Keep while render.py functions are used
-
-### 4.3 `tests/test_layers.py` (3717 bytes)
-- **Status**: POTENTIALLY USEFUL
-- **Why**: Tests for legacy layer functions
-- **Recommendation**: **KEEP FOR NOW**
-  - Keep while layers.py functions are used
-
----
-
-## 5. QUESTIONABLE PATTERNS & TECHNICAL DEBT
-
-### 5.1 Legacy Effect Chain Fallback
-**Location**: `effects/controller.py`, `effects/__init__.py`
-
-```python
-# Fallback to legacy effect chain if no new effects available
-try:
-    from engine.layers import get_effect_chain as _chain
-except ImportError:
-    _chain = None
-```
-
-**Issue**: Dual effect system with implicit fallback
-**Recommendation**: Document or remove fallback path if not actually used
-
-### 5.2 Deprecated ItemsStage Bootstrap
-**Location**: `pipeline/adapters.py` line 356-365
-
-```python
-@deprecated("ItemsStage is deprecated. Use DataSourceStage with a DataSource instead.")
-class ItemsStage(Stage):
-    """Deprecated bootstrap mechanism."""
-```
-
-**Issue**: Marked deprecated but still registered and potentially used
-**Recommendation**: Audit usage and remove if not needed
-
-### 5.3 Legacy Tuple Conversion Methods
-**Location**: `engine/types.py`
-
-```python
-def to_legacy_tuple(self) -> tuple[list[tuple], int, int]:
-    """Convert to legacy tuple format for backward compatibility."""
-```
-
-**Issue**: Backward compatibility layer that may not be needed
-**Recommendation**: Check if actually used by legacy code
-
-### 5.4 Frame Module (Minimal Usage)
-**Location**: `engine/frame.py`
-
-**Status**: Appears minimal and possibly legacy
-**Recommendation**: Check what's actually using it
-
----
-
-## SUMMARY TABLE
-
-| Module | LOC | Status | Risk | Action |
-|--------|-----|--------|------|--------|
-| scroll.py | 156 | **REMOVE** | LOW | Delete - fully deprecated |
-| emitters.py | 25 | **REMOVE** | NONE | Delete - zero usage |
-| beautiful_mermaid.py | 4107 | **REMOVE** | NONE | Delete - zero usage |
-| pipeline_viz.py | 364 | **REMOVE** | NONE | Delete - zero usage |
-| animation.py | 340 | CONSIDER | LOW | Remove if not planned |
-| render.py | 274 | KEEP | MEDIUM | Still used by adapters |
-| layers.py | 272 | KEEP | MEDIUM | Still used by adapters |
-| pygame backend | 9185 | AUDIT | LOW | Check if used |
-| kitty backend | 5305 | AUDIT | LOW | Check if used |
-| test_emitters.py | 2145 | **REMOVE** | NONE | Delete with emitters.py |
-
----
-
-## RECOMMENDED CLEANUP STRATEGY
-
-### Phase 1: Safe Removals (No Dependencies)
-1. Delete `engine/emitters.py`
-2. Delete `tests/test_emitters.py`
-3. Delete `engine/beautiful_mermaid.py`
-4. Delete `engine/pipeline_viz.py`
-5. Clean up related deprecation code in `pipeline.py`
-
-**Impact**: ~4500 lines of dead code removed
-**Risk**: NONE - verified zero usage
-
-### Phase 2: Conditional Removals (Audit Required)
-1. Verify pygame and kitty backends are not used in any preset
-2. If unused, remove from DisplayRegistry and delete files
-3. Consider removing `engine/animation.py` if animation features not planned
-
-### Phase 3: Legacy Module Migration (Future)
-1. Move render.py functions to legacy submodule if scroll.py is removed
-2. Consolidate layers.py with legacy effects
-3. Keep test files until legacy adapters are phased out
-4. Deprecate legacy adapters in favor of new pipeline stages
-
-### Phase 4: Documentation
-1. Update AGENTS.md to document removal of legacy modules
-2. Document which adapters are for backwards compatibility
-3. Add migration guide for teams using old scroll API
-
----
-
-## KEY METRICS
-
-- **Total Dead Code Lines**: ~9000+ lines
-- **Safe to Remove Immediately**: ~4500 lines
-- **Conditional Removals**: ~10000+ lines (if backends/animation unused)
-- **Legacy But Needed**: ~700 lines (render.py + layers.py)
-- **Test Files for Dead Code**: ~2100 lines
-

docs/LEGACY_CODE_INDEX.md

@@ -1,153 +0,0 @@
-# Legacy Code Analysis - Document Index
-
-This directory contains comprehensive analysis of legacy and dead code in the Mainline codebase.
-
-## Quick Start
-
-**Start here:** [LEGACY_CLEANUP_CHECKLIST.md](./LEGACY_CLEANUP_CHECKLIST.md)
-
-This document provides step-by-step instructions for removing dead code in three phases:
-- **Phase 1**: Safe removals (~4,500 lines, zero risk)
-- **Phase 2**: Audit required (~14,000 lines)
-- **Phase 3**: Future migration plan
-
-## Available Documents
-
-### 1. LEGACY_CLEANUP_CHECKLIST.md (Action-Oriented)
-**Purpose**: Step-by-step cleanup procedures with verification commands
-
-**Contains**:
-- Phase 1: Safe deletions with verification commands
-- Phase 2: Audit procedures for display backends
-- Phase 3: Future removal planning
-- Testing procedures after cleanup
-- Rollback procedures
-
-**Start reading if you want to**: Execute cleanup immediately
-
-### 2. LEGACY_CODE_ANALYSIS.md (Detailed Technical)
-**Purpose**: Comprehensive technical analysis with risk assessments
-
-**Contains**:
-- Executive summary
-- Marked deprecated modules (scroll.py, render.py, layers.py)
-- Completely unused modules (emitters.py, beautiful_mermaid.py, pipeline_viz.py)
-- Unused display backends
-- Test file analysis
-- Technical debt patterns
-- Cleanup strategy across 4 phases
-- Key metrics and statistics
-
-**Start reading if you want to**: Understand the technical details
-
-## Key Findings Summary
-
-### Dead Code Identified: ~9,000 lines
-
-#### Category 1: UNUSED (Safe to delete immediately)
-- **engine/emitters.py** (25 lines) - Unused Protocol definitions
-- **engine/beautiful_mermaid.py** (4,107 lines) - Unused Mermaid ASCII renderer
-- **engine/pipeline_viz.py** (364 lines) - Unused visualization module
-- **tests/test_emitters.py** - Orphaned test file
-
-**Total**: ~4,500 lines with ZERO risk
-
-#### Category 2: DEPRECATED BUT ACTIVE (Keep for now)
-- **engine/scroll.py** (156 lines) - Legacy rendering orchestration
-- **engine/render.py** (274 lines) - Legacy font/gradient rendering
-- **engine/layers.py** (272 lines) - Legacy layer/effect rendering
-
-**Total**: ~700 lines (still used for backwards compatibility)
-
-#### Category 3: QUESTIONABLE (Consider removing)
-- **engine/animation.py** (340 lines) - Unused animation system
-
-**Total**: ~340 lines (abandoned experimental code)
-
-#### Category 4: POTENTIALLY UNUSED (Requires audit)
-- **engine/display/backends/pygame.py** (9,185 bytes)
-- **engine/display/backends/kitty.py** (5,305 bytes)
-
-**Total**: ~14,000 bytes (check if presets use them)
-
-## File Paths
-
-### Recommended for Deletion (Phase 1)
-```
-/home/dietpi/src/Mainline/engine/emitters.py
-/home/dietpi/src/Mainline/engine/beautiful_mermaid.py
-/home/dietpi/src/Mainline/engine/pipeline_viz.py
-/home/dietpi/src/Mainline/tests/test_emitters.py
-```
-
-### Keep for Now (Legacy Backwards Compatibility)
-```
-/home/dietpi/src/Mainline/engine/scroll.py
-/home/dietpi/src/Mainline/engine/render.py
-/home/dietpi/src/Mainline/engine/layers.py
-```
-
-### Requires Audit (Phase 2)
-```
-/home/dietpi/src/Mainline/engine/display/backends/pygame.py
-/home/dietpi/src/Mainline/engine/display/backends/kitty.py
-```
-
-## Recommended Reading Order
-
-1. **First**: This file (overview)
-2. **Then**: LEGACY_CLEANUP_CHECKLIST.md (if you want to act immediately)
-3. **Or**: LEGACY_CODE_ANALYSIS.md (if you want to understand deeply)
-
-## Key Statistics
-
-| Metric | Value |
-|--------|-------|
-| Total Dead Code | ~9,000 lines |
-| Safe to Remove (Phase 1) | ~4,500 lines |
-| Conditional Removals (Phase 2) | ~3,800 lines |
-| Legacy But Active (Phase 3) | ~700 lines |
-| Risk Level (Phase 1) | NONE |
-| Risk Level (Phase 2) | LOW |
-| Risk Level (Phase 3) | MEDIUM |
-
-## Action Items
-
-### Immediate (Phase 1 - 0 Risk)
-- [ ] Delete engine/emitters.py
-- [ ] Delete tests/test_emitters.py
-- [ ] Delete engine/beautiful_mermaid.py
-- [ ] Delete engine/pipeline_viz.py
-- [ ] Clean up pipeline.py introspection methods
-
-### Short Term (Phase 2 - Low Risk)
-- [ ] Audit pygame backend usage
-- [ ] Audit kitty backend usage
-- [ ] Decide on animation.py
-
-### Future (Phase 3 - Medium Risk)
-- [ ] Plan scroll.py migration
-- [ ] Consolidate render.py/layers.py
-- [ ] Deprecate legacy adapters
-
-## How to Execute Cleanup
-
-See [LEGACY_CLEANUP_CHECKLIST.md](./LEGACY_CLEANUP_CHECKLIST.md) for:
-- Exact deletion commands
-- Verification procedures
-- Testing procedures
-- Rollback procedures
-
-## Questions?
-
-Refer to the detailed analysis documents:
-- For specific module details: LEGACY_CODE_ANALYSIS.md
-- For how to delete: LEGACY_CLEANUP_CHECKLIST.md
-- For verification commands: LEGACY_CLEANUP_CHECKLIST.md (Phase 1 section)
-
----
-
-**Analysis Date**: March 16, 2026
-**Codebase**: Mainline (Pipeline Architecture)
-**Legacy Code Found**: ~9,000 lines
-**Safe to Remove Now**: ~4,500 lines

docs/PIPELINE.md

@@ -1,199 +0,0 @@
-# Mainline Pipeline
-
-## Architecture Overview
-
-```
-Sources (static/dynamic) → Fetch → Prepare → Scroll → Effects → Render → Display
-                                     ↓
-                    NtfyPoller ← MicMonitor (async)
-```
-
-### Data Source Abstraction (sources_v2.py)
-
-- **Static sources**: Data fetched once and cached (HeadlinesDataSource, PoetryDataSource)
-- **Dynamic sources**: Idempotent fetch for runtime updates (PipelineDataSource)
-- **SourceRegistry**: Discovery and management of data sources
-
-### Camera Modes
-
-- **Vertical**: Scroll up (default)
-- **Horizontal**: Scroll left
-- **Omni**: Diagonal scroll
-- **Floating**: Sinusoidal bobbing
-- **Trace**: Follow network path node-by-node (for pipeline viz)
-
-## Content to Display Rendering Pipeline
-
-```mermaid
-flowchart TD
-    subgraph Sources["Data Sources (v2)"]
-        Headlines[HeadlinesDataSource]
-        Poetry[PoetryDataSource]
-        Pipeline[PipelineDataSource]
-        Registry[SourceRegistry]
-    end
-
-    subgraph SourcesLegacy["Data Sources (legacy)"]
-        RSS[("RSS Feeds")]
-        PoetryFeed[("Poetry Feed")]
-        Ntfy[("Ntfy Messages")]
-        Mic[("Microphone")]
-    end
-
-    subgraph Fetch["Fetch Layer"]
-        FC[fetch_all]
-        FP[fetch_poetry]
-        Cache[(Cache)]
-    end
-
-    subgraph Prepare["Prepare Layer"]
-        MB[make_block]
-        Strip[strip_tags]
-        Trans[translate]
-    end
-
-    subgraph Scroll["Scroll Engine"]
-        SC[StreamController]
-        CAM[Camera]
-        RTZ[render_ticker_zone]
-        Msg[render_message_overlay]
-        Grad[lr_gradient]
-        VT[vis_trunc / vis_offset]
-    end
-
-    subgraph Effects["Effect Pipeline"]
-        subgraph EffectsPlugins["Effect Plugins"]
-            Noise[NoiseEffect]
-            Fade[FadeEffect]
-            Glitch[GlitchEffect]
-            Firehose[FirehoseEffect]
-            Hud[HudEffect]
-        end
-        EC[EffectChain]
-        ER[EffectRegistry]
-    end
-
-    subgraph Render["Render Layer"]
-        BW[big_wrap]
-        RL[render_line]
-    end
-
-    subgraph Display["Display Backends"]
-        TD[TerminalDisplay]
-        PD[PygameDisplay]
-        SD[SixelDisplay]
-        KD[KittyDisplay]
-        WSD[WebSocketDisplay]
-        ND[NullDisplay]
-    end
-
-    subgraph Async["Async Sources"]
-        NTFY[NtfyPoller]
-        MIC[MicMonitor]
-    end
-
-    subgraph Animation["Animation System"]
-        AC[AnimationController]
-        PR[Preset]
-    end
-
-    Sources --> Fetch
-    RSS --> FC
-    PoetryFeed --> FP
-    FC --> Cache
-    FP --> Cache
-    Cache --> MB
-    Strip --> MB
-    Trans --> MB
-    MB --> SC
-    NTFY --> SC
-    SC --> RTZ
-    CAM --> RTZ
-    Grad --> RTZ
-    VT --> RTZ
-    RTZ --> EC
-    EC --> ER
-    ER --> EffectsPlugins
-    EffectsPlugins --> BW
-    BW --> RL
-    RL --> Display
-    Ntfy --> RL
-    Mic --> RL
-    MIC --> RL
-
-    style Sources fill:#f9f,stroke:#333
-    style Fetch fill:#bbf,stroke:#333
-    style Prepare fill:#bff,stroke:#333
-    style Scroll fill:#bfb,stroke:#333
-    style Effects fill:#fbf,stroke:#333
-    style Render fill:#ffb,stroke:#333
-    style Display fill:#bbf,stroke:#333
-    style Async fill:#fbb,stroke:#333
-    style Animation fill:#bfb,stroke:#333
-```
-
-## Animation & Presets
-
-```mermaid
-flowchart LR
-    subgraph Preset["Preset"]
-        PP[PipelineParams]
-        AC[AnimationController]
-    end
-    
-    subgraph AnimationController["AnimationController"]
-        Clock[Clock]
-        Events[Events]
-        Triggers[Triggers]
-    end
-    
-    subgraph Triggers["Trigger Types"]
-        TIME[TIME]
-        FRAME[FRAME]
-        CYCLE[CYCLE]
-        COND[CONDITION]
-        MANUAL[MANUAL]
-    end
-    
-    PP --> AC
-    Clock --> AC
-    Events --> AC
-    Triggers --> Events
-```
-
-## Camera Modes
-
-```mermaid
-stateDiagram-v2
-    [*] --> Vertical
-    Vertical --> Horizontal: mode change
-    Horizontal --> Omni: mode change
-    Omni --> Floating: mode change
-    Floating --> Trace: mode change
-    Trace --> Vertical: mode change
-
-    state Vertical {
-        [*] --> ScrollUp
-        ScrollUp --> ScrollUp: +y each frame
-    }
-
-    state Horizontal {
-        [*] --> ScrollLeft
-        ScrollLeft --> ScrollLeft: +x each frame
-    }
-
-    state Omni {
-        [*] --> Diagonal
-        Diagonal --> Diagonal: +x, +y each frame
-    }
-
-    state Floating {
-        [*] --> Bobbing
-        Bobbing --> Bobbing: sin(time) for x,y
-    }
-
-    state Trace {
-        [*] --> FollowPath
-        FollowPath --> FollowPath: node by node
-    }
-```

docs/SESSION_SUMMARY.md

@@ -1,501 +0,0 @@
-# Session Summary: Phase 2, 3 & 4 Complete
-
-**Date:** March 16, 2026  
-**Duration:** Full session  
-**Overall Achievement:** 126 new tests added, 5,296+ lines of legacy code cleaned up, RenderStage/ItemsStage removed, codebase modernized
-
----
-
-## Executive Summary
-
-This session accomplished four major phases of work:
-
-1. **Phase 2: Test Coverage Improvements** - Added 67 comprehensive tests
-2. **Phase 3 (Early): Legacy Code Removal** - Removed 4,840 lines of dead code (Phases 1-2)
-3. **Phase 3 (Full): Legacy Module Migration** - Reorganized remaining legacy code into dedicated subsystem
-4. **Phase 4: Remove Deprecated Adapters** - Deleted RenderStage and ItemsStage, replaced with modern patterns
-
-**Final Stats:**
-- Tests: 463 → 530 → 521 → 515 → 508 passing (508 core tests, 6 legacy failures pre-existing)
-- Core tests (non-legacy): 67 new tests added
-- Lines of code removed: 5,576 lines total (5,296 + 280 from Phase 4)
-- Legacy code properly organized in `engine/legacy/` and `tests/legacy/`
-- Deprecated adapters fully removed and replaced
-
----
-
-## Phase 4: Remove Deprecated Adapters (Complete Refactor)
-
-### Overview
-
-Phase 4 completed the removal of two deprecated pipeline adapter classes:
-- **RenderStage** (124 lines) - Legacy rendering layer
-- **ItemsStage** (32 lines) - Bootstrap mechanism for pre-fetched items
-- **create_items_stage()** function (3 lines)
-
-**Replacement Strategy:**
-- Created `ListDataSource` class (38 lines) to wrap arbitrary pre-fetched items
-- Updated app.py to use DataSourceStage + ListDataSource pattern
-- Removed 7 deprecated test methods
-
-**Net Result:** 280 lines removed, 0 regressions, 508 core tests passing
-
-### Phase 4.1: Add Deprecation Warnings (7c69086)
-**File:** `engine/pipeline/adapters.py`
-
-Added DeprecationWarning to RenderStage.__init__():
-- Notifies developers that RenderStage uses legacy rendering code
-- Points to modern replacement (SourceItemsToBufferStage)
-- Prepares codebase for full removal
-
-### Phase 4.2: Remove RenderStage Usage from app.py (3e73ea0)
-**File:** `engine/app.py`
-
-Replaced RenderStage with SourceItemsToBufferStage:
-- Removed special-case logic for non-special sources
-- Simplified render pipeline - all sources use same modern path
-- All 11 app integration tests pass
-- No behavior change, only architecture improvement
-
-### Phase 4.3: Delete Deprecated Classes (6fc3cbc)
-**Files:** `engine/pipeline/adapters.py`, `engine/data_sources/sources.py`, `tests/test_pipeline.py`
-
-**Deletions:**
-1. **RenderStage class** (124 lines)
-   - Used legacy engine.legacy.render and engine.legacy.layers
-   - Replaced with SourceItemsToBufferStage + DataSourceStage pattern
-   - Removed 4 test methods for RenderStage
-
-2. **ItemsStage class** (32 lines)
-   - Bootstrap mechanism for pre-fetched items
-   - Removed 3 test methods for ItemsStage
-
-3. **create_items_stage() function** (3 lines)
-   - Helper to create ItemsStage instances
-   - No longer needed
-
-**Additions:**
-1. **ListDataSource class** (38 lines)
-   - Wraps arbitrary pre-fetched items as DataSource
-   - Allows items to be used with modern DataSourceStage
-   - Simple implementation: stores items in constructor, returns in get_items()
-
-**Test Removals:**
-- `test_render_stage_capabilities` - RenderStage-specific
-- `test_render_stage_dependencies` - RenderStage-specific
-- `test_render_stage_process` - RenderStage-specific
-- `test_datasource_stage_capabilities_match_render_deps` - RenderStage comparison
-- `test_items_stage` - ItemsStage-specific
-- `test_pipeline_with_items_and_effect` - ItemsStage usage
-- `test_pipeline_with_items_stage` - ItemsStage usage
-
-**Impact:** 
-- 159 lines deleted from adapters.py
-- 3 lines deleted from app.py
-- 38 lines added as ListDataSource
-- 7 test methods removed (expected deprecation)
-- **508 core tests pass** - no regressions
-
-### Phase 4.4: Update Pipeline Introspection (d14f850)
-**File:** `engine/pipeline.py`
-
-Removed documentation entries:
-- ItemsStage documentation removed
-- RenderStage documentation removed
-- Introspection DAG now only shows active stages
-
-**Impact:**
-- Cleaner pipeline visualization
-- No confusion about deprecated adapters
-- 508 tests still passing
-
-### Architecture Changes
-
-**Before Phase 4:**
-```
-DataSourceStage
-    ↓
-(RenderStage - deprecated)
-    ↓
-SourceItemsToBufferStage
-    ↓
-DisplayStage
-
-Bootstrap:
-(ItemsStage - deprecated, only for pre-fetched items)
-    ↓
-SourceItemsToBufferStage
-```
-
-**After Phase 4:**
-```
-DataSourceStage (now wraps all sources, including ListDataSource)
-    ↓
-SourceItemsToBufferStage
-    ↓
-DisplayStage
-
-Unified Pattern:
-ListDataSource wraps pre-fetched items
-    ↓
-DataSourceStage
-    ↓
-SourceItemsToBufferStage
-```
-
-### Test Metrics
-
-**Before Phase 4:**
-- 515 core tests passing
-- RenderStage had 4 dedicated tests
-- ItemsStage had 3 dedicated tests
-- create_items_stage() had related tests
-
-**After Phase 4:**
-- 508 core tests passing
-- 7 deprecated tests removed (expected)
-- 19 tests skipped
-- 6 legacy tests failing (pre-existing, unrelated)
-- **Zero regressions** in modern code
-
-### Code Quality
-
-**Linting:** ✅ All checks pass
-- ruff format checks pass
-- ruff check passes
-- No style violations
-
-**Testing:** ✅ Full suite passes
-```
-508 passed, 19 skipped, 6 failed (pre-existing legacy)
-```
-
----
-
-## Phase 2: Test Coverage Improvements (67 new tests)
-
-### Commit 1: Data Source Tests (d9c7138)
-**File:** `tests/test_data_sources.py` (220 lines, 19 tests)
-
-Tests for:
-- `SourceItem` dataclass creation and metadata
-- `EmptyDataSource` - blank content generation
-- `HeadlinesDataSource` - RSS feed integration
-- `PoetryDataSource` - poetry source integration
-- `DataSource` base class interface
-
-**Coverage Impact:**
-- `engine/data_sources/sources.py`: 34% → 39%
-
-### Commit 2: Pipeline Adapter Tests (952b73c)
-**File:** `tests/test_adapters.py` (345 lines, 37 tests)
-
-Tests for:
-- `DataSourceStage` - data source integration
-- `DisplayStage` - display backend integration
-- `PassthroughStage` - pass-through rendering
-- `SourceItemsToBufferStage` - content to buffer conversion
-- `EffectPluginStage` - effect application
-
-**Coverage Impact:**
-- `engine/pipeline/adapters.py`: ~50% → 57%
-
-### Commit 3: Fix App Integration Tests (28203ba)
-**File:** `tests/test_app.py` (fixed 7 tests)
-
-Fixed issues:
-- Config mocking for PIPELINE_DIAGRAM flag
-- Proper display mock setup to prevent pygame window launch
-- Correct preset display backend expectations
-- All 11 app tests now passing
-
-**Coverage Impact:**
-- `engine/app.py`: 0-8% → 67%
-
----
-
-## Phase 3: Legacy Code Cleanup
-
-### Phase 3.1: Dead Code Removal
-
-**Commits:**
-- 5762d5e: Removed 4,500 lines of dead code
-- 0aa80f9: Removed 340 lines of unused animation.py
-
-**Deleted:**
-- `engine/emitters.py` (25 lines) - unused Protocol definitions
-- `engine/beautiful_mermaid.py` (4,107 lines) - unused Mermaid ASCII renderer
-- `engine/pipeline_viz.py` (364 lines) - unused visualization module
-- `tests/test_emitters.py` (69 lines) - orphaned test file
-- `engine/animation.py` (340 lines) - abandoned experimental animation system
-- Cleanup of `engine/pipeline.py` introspection methods (25 lines)
-
-**Created:**
-- `docs/LEGACY_CODE_INDEX.md` - Navigation guide
-- `docs/LEGACY_CODE_ANALYSIS.md` - Detailed technical analysis (286 lines)
-- `docs/LEGACY_CLEANUP_CHECKLIST.md` - Action-oriented procedures (239 lines)
-
-**Impact:** 0 risk, all tests pass, no regressions
-
-### Phase 3.2-3.4: Legacy Module Migration
-
-**Commits:**
-- 1d244cf: Delete scroll.py (156 lines)
-- dfe42b0: Create engine/legacy/ subsystem and move render.py + layers.py
-- 526e5ae: Update production imports to engine.legacy.*
-- cda1358: Move legacy tests to tests/legacy/ directory
-
-**Actions Taken:**
-
-1. **Delete scroll.py (156 lines)**
-   - Fully deprecated rendering orchestrator
-   - No production code imports
-   - Clean removal, 0 risk
-
-2. **Create engine/legacy/ subsystem**
-   - `engine/legacy/__init__.py` - Package documentation
-   - `engine/legacy/render.py` - Moved from root (274 lines)
-   - `engine/legacy/layers.py` - Moved from root (272 lines)
-
-3. **Update Production Imports**
-   - `engine/effects/__init__.py` - get_effect_chain() path
-   - `engine/effects/controller.py` - Fallback import path
-   - `engine/pipeline/adapters.py` - RenderStage & ItemsStage imports
-
-4. **Move Legacy Tests**
-   - `tests/legacy/test_render.py` - Moved from root
-   - `tests/legacy/test_layers.py` - Moved from root
-   - Updated all imports to use `engine.legacy.*`
-
-**Impact:** 
-- Core production code fully functional
-- Clear separation between legacy and modern code
-- All modern tests pass (67 new tests)
-- Ready for future removal of legacy modules
-
----
-
-## Architecture Changes
-
-### Before: Monolithic legacy code scattered throughout
-
-```
-engine/
-  ├── emitters.py (unused)
-  ├── beautiful_mermaid.py (unused)
-  ├── animation.py (unused)
-  ├── pipeline_viz.py (unused)
-  ├── scroll.py (deprecated)
-  ├── render.py (legacy)
-  ├── layers.py (legacy)
-  ├── effects/
-  │   └── controller.py (uses layers.py)
-  └── pipeline/
-      └── adapters.py (uses render.py + layers.py)
-
-tests/
-  ├── test_render.py (tests legacy)
-  ├── test_layers.py (tests legacy)
-  └── test_emitters.py (orphaned)
-```
-
-### After: Clean separation of legacy and modern
-
-```
-engine/
-  ├── legacy/
-  │   ├── __init__.py
-  │   ├── render.py (274 lines)
-  │   └── layers.py (272 lines)
-  ├── effects/
-  │   └── controller.py (imports engine.legacy.layers)
-  └── pipeline/
-      └── adapters.py (imports engine.legacy.*)
-
-tests/
-  ├── test_data_sources.py (NEW - 19 tests)
-  ├── test_adapters.py (NEW - 37 tests)
-  ├── test_app.py (FIXED - 11 tests)
-  └── legacy/
-      ├── test_render.py (moved, 24 passing tests)
-      └── test_layers.py (moved, 30 passing tests)
-```
-
----
-
-## Test Statistics
-
-### New Tests Added
-- `test_data_sources.py`: 19 tests (SourceItem, DataSources)
-- `test_adapters.py`: 37 tests (Pipeline stages)
-- `test_app.py`: 11 tests (fixed 7 failing tests)
-- **Total new:** 67 tests
-
-### Test Categories
-- Unit tests: 67 new tests in core modules
-- Integration tests: 11 app tests covering pipeline orchestration
-- Legacy tests: 54 tests moved to `tests/legacy/` (6 pre-existing failures)
-
-### Coverage Improvements
-| Module | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| engine/app.py | 0-8% | 67% | +67% |
-| engine/data_sources/sources.py | 34% | 39% | +5% |
-| engine/pipeline/adapters.py | ~50% | 57% | +7% |
-| Overall | 35% | ~35% | (code cleanup offsets new tests) |
-
----
-
-## Code Cleanup Statistics
-
-### Phase 1-2: Dead Code Removal
-- **emitters.py:** 25 lines (0 references)
-- **beautiful_mermaid.py:** 4,107 lines (0 production usage)
-- **pipeline_viz.py:** 364 lines (0 production usage)
-- **animation.py:** 340 lines (0 imports)
-- **test_emitters.py:** 69 lines (orphaned)
-- **pipeline.py cleanup:** 25 lines (introspection methods)
-- **Total:** 4,930 lines removed, 0 risk
-
-### Phase 3: Legacy Module Migration
-- **scroll.py:** 156 lines (deleted - fully deprecated)
-- **render.py:** 274 lines (moved to engine/legacy/)
-- **layers.py:** 272 lines (moved to engine/legacy/)
-- **Total moved:** 546 lines, properly organized
-
-### Grand Total: 5,296 lines of dead/legacy code handled
-
----
-
-## Git Commit History
-
-```
-d14f850 refactor(remove): Remove RenderStage and ItemsStage from pipeline.py introspection (Phase 4.4)
-6fc3cbc refactor(remove): Delete RenderStage and ItemsStage classes (Phase 4.3)
-3e73ea0 refactor(remove-renderstage): Remove RenderStage usage from app.py (Phase 4.2)
-7c69086 refactor(deprecate): Add deprecation warning to RenderStage (Phase 4.1)
-0980279 docs: Add comprehensive session summary - Phase 2 & 3 complete
-cda1358 refactor(legacy): Move legacy tests to tests/legacy/ (Phase 3.4)
-526e5ae refactor(legacy): Update production imports to engine.legacy (Phase 3.3)
-dfe42b0 refactor(legacy): Create engine/legacy/ subsystem (Phase 3.2)
-1d244cf refactor(legacy): Delete scroll.py (Phase 3.1)
-0aa80f9 refactor(cleanup): Remove 340 lines of unused animation.py
-5762d5e refactor(cleanup): Remove 4,500 lines of dead code (Phase 1)
-28203ba test: Fix app.py integration tests - prevent pygame launch
-952b73c test: Add comprehensive pipeline adapter tests (37 tests)
-d9c7138 test: Add comprehensive data source tests (19 tests)
-c976b99 test(app): add focused integration tests for run_pipeline_mode
-```
-
----
-
-## Quality Assurance
-
-### Testing
-- ✅ All 67 new tests pass
-- ✅ All 11 app integration tests pass
-- ✅ 515 core tests passing (non-legacy)
-- ✅ No regressions in existing code
-- ✅ Legacy tests moved without breaking modern code
-
-### Code Quality
-- ✅ All linting passes (ruff checks)
-- ✅ All syntax valid (Python 3.12 compatible)
-- ✅ Proper imports verified throughout codebase
-- ✅ Pre-commit hooks pass (format + lint)
-
-### Documentation
-- ✅ 3 comprehensive legacy code analysis documents created
-- ✅ 4 phase migration strategy documented
-- ✅ Clear separation between legacy and modern code
-- ✅ Deprecation notices added to legacy modules
-
----
-
-## Key Achievements
-
-### Code Quality
-1. **Eliminated 5,296 lines of dead/legacy code** - cleaner codebase
-2. **Organized remaining legacy code** - `engine/legacy/` and `tests/legacy/`
-3. **Clear migration path** - legacy modules marked deprecated with timeline
-
-### Testing Infrastructure
-1. **67 new comprehensive tests** - improved coverage of core modules
-2. **Fixed integration tests** - app.py tests now stable, prevent UI launch
-3. **Organized test structure** - legacy tests separated from modern tests
-
-### Maintainability
-1. **Modern code fully functional** - 515 core tests passing
-2. **Legacy code isolated** - doesn't affect new pipeline architecture
-3. **Clear deprecation strategy** - timeline for removal documented
-
----
-
-## Next Steps (Future Sessions)
-
-### Completed
-- ✅ Document legacy code inventory - DONE (Phase 3)
-- ✅ Delete dead code - DONE (Phase 1-2)
-- ✅ Migrate legacy modules - DONE (Phase 3)
-- ✅ Remove deprecated adapters - DONE (Phase 4)
-
-### Short Term (Phase 5)
-- Remove engine/legacy/ subsystem entirely
-- Delete tests/legacy/ directory  
-- Clean up any remaining legacy imports in production code
-
-### Long Term (Phase 6+)
-- Archive old rendering code to historical branch if needed
-- Final cleanup and code optimization
-- Performance profiling of modern pipeline
-
----
-
-## Conclusion
-
-This comprehensive 4-phase session successfully:
-
-### Phase 2: Testing (67 new tests)
-1. ✅ Added comprehensive tests for DataSources, adapters, and app integration
-2. ✅ Improved coverage of core modules from ~35% → modern patterns
-3. ✅ Fixed integration tests to prevent UI launch in CI
-
-### Phase 3: Legacy Organization (5,296 lines removed)
-1. ✅ Removed 4,930 lines of provably dead code
-2. ✅ Organized 546 lines of legacy code into dedicated subsystem
-3. ✅ Created clear separation: `engine/legacy/` and `tests/legacy/`
-
-### Phase 4: Adapter Removal (280 lines removed)
-1. ✅ Deprecated RenderStage and ItemsStage
-2. ✅ Created ListDataSource replacement pattern
-3. ✅ Removed deprecated adapters and associated tests
-4. ✅ Updated pipeline introspection documentation
-
-### Overall Results
-
-**Code Quality:**
-- 5,576 total lines of legacy/dead code removed
-- Clean architecture with no deprecated patterns in use
-- Modern pipeline fully functional and testable
-
-**Testing:**
-- 67 new tests added
-- 508 core tests passing (100% of modern code)
-- 19 tests skipped
-- 6 legacy test failures (pre-existing, unrelated to Phase 4)
-- Zero regressions in any phase
-
-**Technical Debt:**
-- Reduced by 5,576 lines
-- Remaining legacy code (546 lines) isolated and marked for removal
-- Clear path to Phase 5: Complete removal of engine/legacy/
-
-The codebase is now in excellent shape with:
-- ✅ No deprecated adapters in use
-- ✅ All modern code patterns adopted
-- ✅ Clear separation of concerns
-- ✅ Ready for next phase of cleanup
-
----
-
-**End of Session Summary**

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

@@ -1,145 +0,0 @@
-# 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

effects_plugins/__init__.py

@@ -5,7 +5,6 @@ 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 = {}
@@ -23,13 +22,11 @@ def discover_plugins():
                 attr = getattr(module, attr_name)
                 if (
                     isinstance(attr, type)
-                    and issubclass(attr, EffectPlugin)
-                    and attr is not EffectPlugin
+                    and hasattr(attr, "name")
+                    and hasattr(attr, "process")
                     and attr_name.endswith("Effect")
                 ):
                     plugin = attr()
-                    if not isinstance(plugin, EffectPlugin):
-                        continue
                     registry.register(plugin)
                     imported[plugin.name] = plugin
         except Exception:

effects_plugins/border.py

@@ -1,105 +0,0 @@
-from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
-
-
-class BorderEffect(EffectPlugin):
-    """Simple border effect for terminal display.
-
-    Draws a border around the buffer and optionally displays
-    performance metrics in the border corners.
-
-    Internally crops to display dimensions to ensure border fits.
-    """
-
-    name = "border"
-    config = EffectConfig(enabled=True, intensity=1.0)
-
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        if not buf:
-            return buf
-
-        # Get actual display dimensions from context
-        display_w = ctx.terminal_width
-        display_h = ctx.terminal_height
-
-        # If dimensions are reasonable, crop first - use slightly smaller to ensure fit
-        if display_w >= 10 and display_h >= 3:
-            # Subtract 2 for border characters (left and right)
-            crop_w = display_w - 2
-            crop_h = display_h - 2
-            buf = self._crop_to_size(buf, crop_w, crop_h)
-            w = display_w
-            h = display_h
-        else:
-            # Use buffer dimensions
-            h = len(buf)
-            w = max(len(line) for line in buf) if buf else 0
-
-        if w < 3 or h < 3:
-            return buf
-
-        inner_w = w - 2
-
-        # Get metrics from context
-        fps = 0.0
-        frame_time = 0.0
-        metrics = ctx.get_state("metrics")
-        if metrics:
-            avg_ms = metrics.get("avg_ms")
-            frame_count = metrics.get("frame_count", 0)
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Build borders
-        # Top border: ┌────────────────────┐ or with FPS
-        if fps > 0:
-            fps_str = f" FPS:{fps:.0f}"
-            if len(fps_str) < inner_w:
-                right_len = inner_w - len(fps_str)
-                top_border = "┌" + "─" * right_len + fps_str + "┐"
-            else:
-                top_border = "┌" + "─" * inner_w + "┐"
-        else:
-            top_border = "┌" + "─" * inner_w + "┐"
-
-        # Bottom border: └────────────────────┘ or with frame time
-        if frame_time > 0:
-            ft_str = f" {frame_time:.1f}ms"
-            if len(ft_str) < inner_w:
-                right_len = inner_w - len(ft_str)
-                bottom_border = "└" + "─" * right_len + ft_str + "┘"
-            else:
-                bottom_border = "└" + "─" * inner_w + "┘"
-        else:
-            bottom_border = "└" + "─" * inner_w + "┘"
-
-        # Build result with left/right borders
-        result = [top_border]
-        for line in buf[: h - 2]:
-            if len(line) >= inner_w:
-                result.append("│" + line[:inner_w] + "│")
-            else:
-                result.append("│" + line + " " * (inner_w - len(line)) + "│")
-
-        result.append(bottom_border)
-
-        return result
-
-    def _crop_to_size(self, buf: list[str], w: int, h: int) -> list[str]:
-        """Crop buffer to fit within w x h."""
-        result = []
-        for i in range(min(h, len(buf))):
-            line = buf[i]
-            if len(line) > w:
-                result.append(line[:w])
-            else:
-                result.append(line + " " * (w - len(line)))
-
-        # Pad with empty lines if needed (for border)
-        while len(result) < h:
-            result.append(" " * w)
-
-        return result
-
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config

effects_plugins/crop.py

@@ -1,42 +0,0 @@
-from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
-
-
-class CropEffect(EffectPlugin):
-    """Crop effect that crops the input buffer to fit the display.
-
-    This ensures the output buffer matches the actual display dimensions,
-    useful when the source produces a buffer larger than the viewport.
-    """
-
-    name = "crop"
-    config = EffectConfig(enabled=True, intensity=1.0)
-
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        if not buf:
-            return buf
-
-        # Get actual display dimensions from context
-        w = (
-            ctx.terminal_width
-            if ctx.terminal_width > 0
-            else max(len(line) for line in buf)
-        )
-        h = ctx.terminal_height if ctx.terminal_height > 0 else len(buf)
-
-        # Crop buffer to fit
-        result = []
-        for i in range(min(h, len(buf))):
-            line = buf[i]
-            if len(line) > w:
-                result.append(line[:w])
-            else:
-                result.append(line + " " * (w - len(line)))
-
-        # Pad with empty lines if needed
-        while len(result) < h:
-            result.append(" " * w)
-
-        return result
-
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config

effects_plugins/fade.py

@@ -3,7 +3,7 @@ import random
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 
 
-class FadeEffect(EffectPlugin):
+class FadeEffect:
     name = "fade"
     config = EffectConfig(enabled=True, intensity=1.0)
 
@@ -54,5 +54,5 @@ class FadeEffect(EffectPlugin):
                 i += 1
         return "".join(result)
 
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config
+    def configure(self, cfg: EffectConfig) -> None:
+        self.config = cfg

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(EffectPlugin):
+class FirehoseEffect:
     name = "firehose"
     config = EffectConfig(enabled=True, intensity=1.0)
 
@@ -68,5 +68,5 @@ class FirehoseEffect(EffectPlugin):
             color = random.choice([G_LO, C_DIM, W_GHOST])
             return f"{color}{text}{RST}"
 
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config
+    def configure(self, cfg: EffectConfig) -> None:
+        self.config = cfg

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(EffectPlugin):
+class GlitchEffect:
     name = "glitch"
     config = EffectConfig(enabled=True, intensity=1.0)
 
@@ -33,5 +33,5 @@ class GlitchEffect(EffectPlugin):
         o = random.randint(0, w - n)
         return " " * o + f"{G_LO}{DIM}" + c * n + RST
 
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config
+    def configure(self, cfg: EffectConfig) -> None:
+        self.config = cfg

effects_plugins/hud.py

@@ -1,105 +0,0 @@
-from engine.effects.types import (
-    EffectConfig,
-    EffectContext,
-    EffectPlugin,
-    PartialUpdate,
-)
-
-
-class HudEffect(EffectPlugin):
-    name = "hud"
-    config = EffectConfig(enabled=True, intensity=1.0)
-    supports_partial_updates = True  # Enable partial update optimization
-
-    # Cache last HUD content to detect changes
-    _last_hud_content: tuple | None = None
-
-    def process_partial(
-        self, buf: list[str], ctx: EffectContext, partial: PartialUpdate
-    ) -> list[str]:
-        # If full buffer requested, process normally
-        if partial.full_buffer:
-            return self.process(buf, ctx)
-
-        # If HUD rows (0, 1, 2) aren't dirty, skip processing
-        if partial.dirty:
-            hud_rows = {0, 1, 2}
-            dirty_hud_rows = partial.dirty & hud_rows
-            if not dirty_hud_rows:
-                return buf  # Nothing for HUD to do
-
-        # Proceed with full processing
-        return self.process(buf, ctx)
-
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        result = list(buf)
-
-        # Read metrics from pipeline context (first-class citizen)
-        # Falls back to global monitor for backwards compatibility
-        metrics = ctx.get_state("metrics")
-        if not metrics:
-            # Fallback to global monitor for backwards compatibility
-            from engine.effects.performance import get_monitor
-
-            monitor = get_monitor()
-            if monitor:
-                stats = monitor.get_stats()
-                if stats and "pipeline" in stats:
-                    metrics = stats
-
-        fps = 0.0
-        frame_time = 0.0
-        if metrics:
-            if "error" in metrics:
-                pass  # No metrics available yet
-            elif "pipeline" in metrics:
-                frame_time = metrics["pipeline"].get("avg_ms", 0.0)
-                frame_count = metrics.get("frame_count", 0)
-                if frame_count > 0 and frame_time > 0:
-                    fps = 1000.0 / frame_time
-            elif "avg_ms" in metrics:
-                # Direct metrics format
-                frame_time = metrics.get("avg_ms", 0.0)
-                frame_count = metrics.get("frame_count", 0)
-                if frame_count > 0 and frame_time > 0:
-                    fps = 1000.0 / frame_time
-
-        w = ctx.terminal_width
-        h = ctx.terminal_height
-
-        effect_name = self.config.params.get("display_effect", "none")
-        effect_intensity = self.config.params.get("display_intensity", 0.0)
-
-        hud_lines = []
-        hud_lines.append(
-            f"\033[1;1H\033[38;5;46mMAINLINE DEMO\033[0m \033[38;5;245m|\033[0m \033[38;5;39mFPS: {fps:.1f}\033[0m \033[38;5;245m|\033[0m \033[38;5;208m{frame_time:.1f}ms\033[0m"
-        )
-
-        bar_width = 20
-        filled = int(bar_width * effect_intensity)
-        bar = (
-            "\033[38;5;82m"
-            + "█" * filled
-            + "\033[38;5;240m"
-            + "░" * (bar_width - filled)
-            + "\033[0m"
-        )
-        hud_lines.append(
-            f"\033[2;1H\033[38;5;45mEFFECT:\033[0m \033[1;38;5;227m{effect_name:12s}\033[0m \033[38;5;245m|\033[0m {bar} \033[38;5;245m|\033[0m \033[38;5;219m{effect_intensity * 100:.0f}%\033[0m"
-        )
-
-        # Get pipeline order from context
-        pipeline_order = ctx.get_state("pipeline_order")
-        pipeline_str = ",".join(pipeline_order) if pipeline_order else "(none)"
-        hud_lines.append(f"\033[3;1H\033[38;5;44mPIPELINE:\033[0m {pipeline_str}")
-
-        for i, line in enumerate(hud_lines):
-            if i < len(result):
-                result[i] = line + result[i][len(line) :]
-            else:
-                result.append(line)
-
-        return result
-
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config

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(EffectPlugin):
+class NoiseEffect:
     name = "noise"
     config = EffectConfig(enabled=True, intensity=0.15)
 
@@ -32,5 +32,5 @@ class NoiseEffect(EffectPlugin):
             for _ in range(w)
         )
 
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config
+    def configure(self, cfg: EffectConfig) -> None:
+        self.config = cfg

effects_plugins/tint.py

@@ -1,99 +0,0 @@
-from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
-
-
-class TintEffect(EffectPlugin):
-    """Tint effect that applies an RGB color overlay to the buffer.
-
-    Uses ANSI escape codes to tint text with the specified RGB values.
-    Supports transparency (0-100%) for blending.
-
-    Inlets:
-    - r: Red component (0-255)
-    - g: Green component (0-255)
-    - b: Blue component (0-255)
-    - a: Alpha/transparency (0.0-1.0, where 0.0 = fully transparent)
-    """
-
-    name = "tint"
-    config = EffectConfig(enabled=True, intensity=1.0)
-
-    # Define inlet types for PureData-style typing
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        if not buf:
-            return buf
-
-        # Get tint values from effect params or sensors
-        r = self.config.params.get("r", 255)
-        g = self.config.params.get("g", 255)
-        b = self.config.params.get("b", 255)
-        a = self.config.params.get("a", 0.3)  # Default 30% tint
-
-        # Clamp values
-        r = max(0, min(255, int(r)))
-        g = max(0, min(255, int(g)))
-        b = max(0, min(255, int(b)))
-        a = max(0.0, min(1.0, float(a)))
-
-        if a <= 0:
-            return buf
-
-        # Convert RGB to ANSI 256 color
-        ansi_color = self._rgb_to_ansi256(r, g, b)
-
-        # Apply tint with transparency effect
-        result = []
-        for line in buf:
-            if not line.strip():
-                result.append(line)
-                continue
-
-            # Check if line already has ANSI codes
-            if "\033[" in line:
-                # For lines with existing colors, wrap the whole line
-                result.append(f"\033[38;5;{ansi_color}m{line}\033[0m")
-            else:
-                # Apply tint to plain text lines
-                result.append(f"\033[38;5;{ansi_color}m{line}\033[0m")
-
-        return result
-
-    def _rgb_to_ansi256(self, r: int, g: int, b: int) -> int:
-        """Convert RGB (0-255 each) to ANSI 256 color code."""
-        if r == g == b == 0:
-            return 16
-        if r == g == b == 255:
-            return 231
-
-        # Calculate grayscale
-        gray = int((0.299 * r + 0.587 * g + 0.114 * b) / 255 * 24) + 232
-
-        # Calculate color cube
-        ri = int(r / 51)
-        gi = int(g / 51)
-        bi = int(b / 51)
-        color = 16 + 36 * ri + 6 * gi + bi
-
-        # Use whichever is closer - gray or color
-        gray_dist = abs(r - gray)
-        color_dist = (
-            (r - ri * 51) ** 2 + (g - gi * 51) ** 2 + (b - bi * 51) ** 2
-        ) ** 0.5
-
-        if gray_dist < color_dist:
-            return gray
-        return color
-
-    def configure(self, config: EffectConfig) -> None:
-        self.config = config

engine/app.py

@@ -1,268 +1,452 @@
 """
-Application orchestrator — pipeline mode entry point.
+Application orchestrator — boot sequence, signal handling, main loop wiring.
 """
 
+import atexit
+import os
+import signal
 import sys
+import termios
 import time
+import tty
 
-import effects_plugins
-from engine import config
-from engine.display import DisplayRegistry
-from engine.effects import PerformanceMonitor, get_registry, set_monitor
-from engine.fetch import fetch_all, fetch_poetry, load_cache
-from engine.pipeline import (
-    Pipeline,
-    PipelineConfig,
-    get_preset,
-    list_presets,
-)
-from engine.pipeline.adapters import (
-    SourceItemsToBufferStage,
-    create_stage_from_display,
-    create_stage_from_effect,
+from engine import config, render
+from engine.controller import StreamController
+from engine.fetch import fetch_all, fetch_poetry, load_cache, save_cache
+from engine.terminal import (
+    CLR,
+    CURSOR_OFF,
+    CURSOR_ON,
+    G_DIM,
+    G_HI,
+    G_MID,
+    RST,
+    W_DIM,
+    W_GHOST,
+    boot_ln,
+    slow_print,
+    tw,
 )
 
+TITLE = [
+    "  ███╗   ███╗ █████╗ ██╗███╗   ██╗██╗     ██╗███╗   ██╗███████╗",
+    "  ████╗ ████║██╔══██╗██║████╗  ██║██║     ██║████╗  ██║██╔════╝",
+    "  ██╔████╔██║███████║██║██╔██╗ ██║██║     ██║██╔██╗ ██║█████╗  ",
+    "  ██║╚██╔╝██║██╔══██║██║██║╚██╗██║██║     ██║██║╚██╗██║██╔══╝  ",
+    "  ██║ ╚═╝ ██║██║  ██║██║██║ ╚████║███████╗██║██║ ╚████║███████╗",
+    "  ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚══════╝╚═╝╚═╝  ╚═══╝╚══════╝",
+]
 
-def main():
-    """Main entry point - all modes now use presets."""
-    if config.PIPELINE_DIAGRAM:
-        try:
-            from engine.pipeline import generate_pipeline_diagram
-        except ImportError:
-            print("Error: pipeline diagram not available")
-            return
-        print(generate_pipeline_diagram())
+
+def _read_picker_key():
+    ch = sys.stdin.read(1)
+    if ch == "\x03":
+        return "interrupt"
+    if ch in ("\r", "\n"):
+        return "enter"
+    if ch == "\x1b":
+        c1 = sys.stdin.read(1)
+        if c1 != "[":
+            return None
+        c2 = sys.stdin.read(1)
+        if c2 == "A":
+            return "up"
+        if c2 == "B":
+            return "down"
+        return None
+    if ch in ("k", "K"):
+        return "up"
+    if ch in ("j", "J"):
+        return "down"
+    if ch in ("q", "Q"):
+        return "enter"
+    return None
+
+
+def _normalize_preview_rows(rows):
+    """Trim shared left padding and trailing spaces for stable on-screen previews."""
+    non_empty = [r for r in rows if r.strip()]
+    if not non_empty:
+        return [""]
+    left_pad = min(len(r) - len(r.lstrip(" ")) for r in non_empty)
+    out = []
+    for row in rows:
+        if left_pad < len(row):
+            out.append(row[left_pad:].rstrip())
+        else:
+            out.append(row.rstrip())
+    return out
+
+
+def _draw_font_picker(faces, selected):
+    w = tw()
+    h = 24
+    try:
+        h = os.get_terminal_size().lines
+    except Exception:
+        pass
+
+    max_preview_w = max(24, w - 8)
+    header_h = 6
+    footer_h = 3
+    preview_h = max(4, min(config.RENDER_H + 2, max(4, h // 2)))
+    visible = max(1, h - header_h - preview_h - footer_h)
+    top = max(0, selected - (visible // 2))
+    bottom = min(len(faces), top + visible)
+    top = max(0, bottom - visible)
+
+    print(CLR, end="")
+    print(CURSOR_OFF, end="")
+    print()
+    print(f"  {G_HI}FONT PICKER{RST}")
+    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
+    print(f"  {W_DIM}{config.FONT_DIR[:max_preview_w]}{RST}")
+    print(f"  {W_GHOST}↑/↓ move · Enter select · q accept current{RST}")
+    print()
+
+    for pos in range(top, bottom):
+        face = faces[pos]
+        active = pos == selected
+        pointer = "▶" if active else " "
+        color = G_HI if active else W_DIM
+        print(
+            f"  {color}{pointer} {face['name']}{RST}{W_GHOST} · {face['file_name']}{RST}"
+        )
+
+    if top > 0:
+        print(f"  {W_GHOST}… {top} above{RST}")
+    if bottom < len(faces):
+        print(f"  {W_GHOST}… {len(faces) - bottom} below{RST}")
+
+    print()
+    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
+    print(
+        f"  {W_DIM}Preview: {faces[selected]['name']} · {faces[selected]['file_name']}{RST}"
+    )
+    preview_rows = faces[selected]["preview_rows"][:preview_h]
+    for row in preview_rows:
+        shown = row[:max_preview_w]
+        print(f"    {shown}")
+
+
+def pick_font_face():
+    """Interactive startup picker for selecting a face from repo OTF files."""
+    if not config.FONT_PICKER:
         return
 
-    preset_name = None
-
-    if config.PRESET:
-        preset_name = config.PRESET
-    elif config.PIPELINE_MODE:
-        preset_name = config.PIPELINE_PRESET
-    else:
-        preset_name = "demo"
-
-    available = list_presets()
-    if preset_name not in available:
-        print(f"Error: Unknown preset '{preset_name}'")
-        print(f"Available presets: {', '.join(available)}")
+    font_files = config.list_repo_font_files()
+    if not font_files:
+        print(CLR, end="")
+        print(CURSOR_OFF, end="")
+        print()
+        print(f"  {G_HI}FONT PICKER{RST}")
+        print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
+        print(f"  {G_DIM}> no .otf/.ttf/.ttc files found in: {config.FONT_DIR}{RST}")
+        print(f"  {W_GHOST}> add font files to the fonts folder, then rerun{RST}")
+        time.sleep(1.8)
         sys.exit(1)
 
-    run_pipeline_mode(preset_name)
+    prepared = []
+    for font_path in font_files:
+        try:
+            faces = render.list_font_faces(font_path, max_faces=64)
+        except Exception:
+            fallback = os.path.splitext(os.path.basename(font_path))[0]
+            faces = [{"index": 0, "name": fallback}]
+        for face in faces:
+            idx = face["index"]
+            name = face["name"]
+            file_name = os.path.basename(font_path)
+            try:
+                fnt = render.load_font_face(font_path, idx)
+                rows = _normalize_preview_rows(render.render_line(name, fnt))
+            except Exception:
+                rows = ["(preview unavailable)"]
+            prepared.append(
+                {
+                    "font_path": font_path,
+                    "font_index": idx,
+                    "name": name,
+                    "file_name": file_name,
+                    "preview_rows": rows,
+                }
+            )
+
+    if not prepared:
+        print(CLR, end="")
+        print(CURSOR_OFF, end="")
+        print()
+        print(f"  {G_HI}FONT PICKER{RST}")
+        print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
+        print(f"  {G_DIM}> no readable font faces found in: {config.FONT_DIR}{RST}")
+        time.sleep(1.8)
+        sys.exit(1)
+
+    def _same_path(a, b):
+        try:
+            return os.path.samefile(a, b)
+        except Exception:
+            return os.path.abspath(a) == os.path.abspath(b)
+
+    selected = next(
+        (
+            i
+            for i, f in enumerate(prepared)
+            if _same_path(f["font_path"], config.FONT_PATH)
+            and f["font_index"] == config.FONT_INDEX
+        ),
+        0,
+    )
+
+    if not sys.stdin.isatty():
+        selected_font = prepared[selected]
+        config.set_font_selection(
+            font_path=selected_font["font_path"],
+            font_index=selected_font["font_index"],
+        )
+        render.clear_font_cache()
+        print(
+            f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}"
+        )
+        time.sleep(0.8)
+        print(CLR, end="")
+        print(CURSOR_OFF, end="")
+        print()
+        return
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        while True:
+            _draw_font_picker(prepared, selected)
+            key = _read_picker_key()
+            if key == "up":
+                selected = max(0, selected - 1)
+            elif key == "down":
+                selected = min(len(prepared) - 1, selected + 1)
+            elif key == "enter":
+                break
+            elif key == "interrupt":
+                raise KeyboardInterrupt
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+    selected_font = prepared[selected]
+    config.set_font_selection(
+        font_path=selected_font["font_path"],
+        font_index=selected_font["font_index"],
+    )
+    render.clear_font_cache()
+    print(
+        f"  {G_DIM}> using {selected_font['name']} ({selected_font['file_name']}){RST}"
+    )
+    time.sleep(0.8)
+    print(CLR, end="")
+    print(CURSOR_OFF, end="")
+    print()
 
 
-def run_pipeline_mode(preset_name: str = "demo"):
-    """Run using the new unified pipeline architecture."""
-    print("  \033[1;38;5;46mPIPELINE MODE\033[0m")
-    print("  \033[38;5;245mUsing unified pipeline architecture\033[0m")
+def pick_effects_config():
+    """Interactive picker for configuring effects pipeline."""
+    import effects_plugins
+    from engine.effects import get_effect_chain, get_registry
 
     effects_plugins.discover_plugins()
 
-    monitor = PerformanceMonitor()
-    set_monitor(monitor)
+    registry = get_registry()
+    chain = get_effect_chain()
+    chain.set_order(["noise", "fade", "glitch", "firehose"])
 
-    preset = get_preset(preset_name)
-    if not preset:
-        print(f"  \033[38;5;196mUnknown preset: {preset_name}\033[0m")
-        sys.exit(1)
-
-    print(f"  \033[38;5;245mPreset: {preset.name} - {preset.description}\033[0m")
-
-    params = preset.to_params()
-    params.viewport_width = 80
-    params.viewport_height = 24
-
-    pipeline = Pipeline(
-        config=PipelineConfig(
-            source=preset.source,
-            display=preset.display,
-            camera=preset.camera,
-            effects=preset.effects,
-        )
-    )
-
-    print("  \033[38;5;245mFetching content...\033[0m")
-
-    # Handle special sources that don't need traditional fetching
-    introspection_source = None
-    if preset.source == "pipeline-inspect":
-        items = []
-        print("  \033[38;5;245mUsing pipeline introspection source\033[0m")
-    elif preset.source == "empty":
-        items = []
-        print("  \033[38;5;245mUsing empty source (no content)\033[0m")
-    else:
-        cached = load_cache()
-        if cached:
-            items = cached
-        elif preset.source == "poetry":
-            items, _, _ = fetch_poetry()
-        else:
-            items, _, _ = fetch_all()
-
-        if not items:
-            print("  \033[38;5;196mNo content available\033[0m")
-            sys.exit(1)
-
-        print(f"  \033[38;5;82mLoaded {len(items)} items\033[0m")
-
-    # CLI --display flag takes priority over preset
-    # Check if --display was explicitly provided
-    display_name = preset.display
-    if "--display" in sys.argv:
-        idx = sys.argv.index("--display")
-        if idx + 1 < len(sys.argv):
-            display_name = sys.argv[idx + 1]
-
-    display = DisplayRegistry.create(display_name)
-    if not display:
-        print(f"  \033[38;5;196mFailed to create display: {display_name}\033[0m")
-        sys.exit(1)
-
-    display.init(0, 0)
-
-    effect_registry = get_registry()
-
-    # Create source stage based on preset source type
-    if preset.source == "pipeline-inspect":
-        from engine.data_sources.pipeline_introspection import (
-            PipelineIntrospectionSource,
-        )
-        from engine.pipeline.adapters import DataSourceStage
-
-        introspection_source = PipelineIntrospectionSource(
-            pipeline=None,  # Will be set after pipeline.build()
-            viewport_width=80,
-            viewport_height=24,
-        )
-        pipeline.add_stage(
-            "source", DataSourceStage(introspection_source, name="pipeline-inspect")
-        )
-    elif preset.source == "empty":
-        from engine.data_sources.sources import EmptyDataSource
-        from engine.pipeline.adapters import DataSourceStage
-
-        empty_source = EmptyDataSource(width=80, height=24)
-        pipeline.add_stage("source", DataSourceStage(empty_source, name="empty"))
-    else:
-        from engine.data_sources.sources import ListDataSource
-        from engine.pipeline.adapters import DataSourceStage
-
-        list_source = ListDataSource(items, name=preset.source)
-        pipeline.add_stage("source", DataSourceStage(list_source, name=preset.source))
-
-    # Add FontStage for headlines/poetry (default for demo)
-    if preset.source in ["headlines", "poetry"]:
-        from engine.pipeline.adapters import FontStage, ViewportFilterStage
-
-        # Add viewport filter to prevent rendering all items
-        pipeline.add_stage(
-            "viewport_filter", ViewportFilterStage(name="viewport-filter")
-        )
-        pipeline.add_stage("font", FontStage(name="font"))
-    else:
-        # Fallback to simple conversion for other sources
-        pipeline.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
-
-    # Add camera stage if specified in preset
-    if preset.camera:
-        from engine.camera import Camera
-        from engine.pipeline.adapters import CameraStage
-
-        camera = None
-        speed = getattr(preset, "camera_speed", 1.0)
-        if preset.camera == "feed":
-            camera = Camera.feed(speed=speed)
-        elif preset.camera == "scroll":
-            camera = Camera.scroll(speed=speed)
-        elif preset.camera == "vertical":
-            camera = Camera.scroll(speed=speed)  # Backwards compat
-        elif preset.camera == "horizontal":
-            camera = Camera.horizontal(speed=speed)
-        elif preset.camera == "omni":
-            camera = Camera.omni(speed=speed)
-        elif preset.camera == "floating":
-            camera = Camera.floating(speed=speed)
-        elif preset.camera == "bounce":
-            camera = Camera.bounce(speed=speed)
-
-        if camera:
-            pipeline.add_stage("camera", CameraStage(camera, name=preset.camera))
-
-    for effect_name in preset.effects:
-        effect = effect_registry.get(effect_name)
-        if effect:
-            pipeline.add_stage(
-                f"effect_{effect_name}", create_stage_from_effect(effect, effect_name)
-            )
-
-    pipeline.add_stage("display", create_stage_from_display(display, display_name))
-
-    pipeline.build()
-
-    # For pipeline-inspect, set the pipeline after build to avoid circular dependency
-    if introspection_source is not None:
-        introspection_source.set_pipeline(pipeline)
-
-    if not pipeline.initialize():
-        print("  \033[38;5;196mFailed to initialize pipeline\033[0m")
-        sys.exit(1)
-
-    print("  \033[38;5;82mStarting pipeline...\033[0m")
-    print("  \033[38;5;245mPress Ctrl+C to exit\033[0m\n")
-
-    ctx = pipeline.context
-    ctx.params = params
-    ctx.set("display", display)
-    ctx.set("items", items)
-    ctx.set("pipeline", pipeline)
-    ctx.set("pipeline_order", pipeline.execution_order)
-    ctx.set("camera_y", 0)
-
-    current_width = 80
-    current_height = 24
-
-    if hasattr(display, "get_dimensions"):
-        current_width, current_height = display.get_dimensions()
-        params.viewport_width = current_width
-        params.viewport_height = current_height
-
-    try:
-        frame = 0
-        while True:
-            params.frame_number = frame
-            ctx.params = params
-
-            result = pipeline.execute(items)
-            if result.success:
-                display.show(result.data, border=params.border)
-
-            if hasattr(display, "is_quit_requested") and display.is_quit_requested():
-                if hasattr(display, "clear_quit_request"):
-                    display.clear_quit_request()
-                raise KeyboardInterrupt()
-
-            if hasattr(display, "get_dimensions"):
-                new_w, new_h = display.get_dimensions()
-                if new_w != current_width or new_h != current_height:
-                    current_width, current_height = new_w, new_h
-                    params.viewport_width = current_width
-                    params.viewport_height = current_height
-
-            time.sleep(1 / 60)
-            frame += 1
-
-    except KeyboardInterrupt:
-        pipeline.cleanup()
-        display.cleanup()
-        print("\n  \033[38;5;245mPipeline stopped\033[0m")
+    effects = list(registry.list_all().values())
+    if not effects:
         return
 
-    pipeline.cleanup()
-    display.cleanup()
-    print("\n  \033[38;5;245mPipeline stopped\033[0m")
+    selected = 0
+    editing_intensity = False
+    intensity_value = 1.0
+
+    def _draw_effects_picker():
+        w = tw()
+        print(CLR, end="")
+        print("\033[1;1H", end="")
+        print("  \033[1;38;5;231mEFFECTS CONFIG\033[0m")
+        print(f"  \033[2;38;5;37m{'─' * (w - 4)}\033[0m")
+        print()
+
+        for i, effect in enumerate(effects):
+            prefix = " > " if i == selected else "   "
+            marker = "[*]" if effect.config.enabled else "[ ]"
+            if editing_intensity and i == selected:
+                print(
+                    f"{prefix}{marker} \033[1;38;5;82m{effect.name}\033[0m: intensity={intensity_value:.2f} (use +/- to adjust, Enter to confirm)"
+                )
+            else:
+                print(
+                    f"{prefix}{marker} {effect.name}: intensity={effect.config.intensity:.2f}"
+                )
+
+        print()
+        print(f"  \033[2;38;5;37m{'─' * (w - 4)}\033[0m")
+        print(
+            "  \033[38;5;245mControls: space=toggle on/off | +/-=adjust intensity | arrows=move | Enter=next effect | q=done\033[0m"
+        )
+
+    def _read_effects_key():
+        ch = sys.stdin.read(1)
+        if ch == "\x03":
+            return "interrupt"
+        if ch in ("\r", "\n"):
+            return "enter"
+        if ch == " ":
+            return "toggle"
+        if ch == "q":
+            return "quit"
+        if ch == "+" or ch == "=":
+            return "up"
+        if ch == "-" or ch == "_":
+            return "down"
+        if ch == "\x1b":
+            c1 = sys.stdin.read(1)
+            if c1 != "[":
+                return None
+            c2 = sys.stdin.read(1)
+            if c2 == "A":
+                return "up"
+            if c2 == "B":
+                return "down"
+            return None
+        return None
+
+    if not sys.stdin.isatty():
+        return
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        while True:
+            _draw_effects_picker()
+            key = _read_effects_key()
+
+            if key == "quit" or key == "enter":
+                break
+            elif key == "up" and editing_intensity:
+                intensity_value = min(1.0, intensity_value + 0.1)
+                effects[selected].config.intensity = intensity_value
+            elif key == "down" and editing_intensity:
+                intensity_value = max(0.0, intensity_value - 0.1)
+                effects[selected].config.intensity = intensity_value
+            elif key == "up":
+                selected = max(0, selected - 1)
+                intensity_value = effects[selected].config.intensity
+            elif key == "down":
+                selected = min(len(effects) - 1, selected + 1)
+                intensity_value = effects[selected].config.intensity
+            elif key == "toggle":
+                effects[selected].config.enabled = not effects[selected].config.enabled
+            elif key == "interrupt":
+                raise KeyboardInterrupt
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
 
 
-if __name__ == "__main__":
-    main()
+def main():
+    atexit.register(lambda: print(CURSOR_ON, end="", flush=True))
+
+    def handle_sigint(*_):
+        print(f"\n\n  {G_DIM}> SIGNAL LOST{RST}")
+        print(f"  {W_GHOST}> connection terminated{RST}\n")
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    StreamController.warmup_topics()
+
+    w = tw()
+    print(CLR, end="")
+    print(CURSOR_OFF, end="")
+    pick_font_face()
+    pick_effects_config()
+    w = tw()
+    print()
+    time.sleep(0.4)
+
+    for ln in TITLE:
+        print(f"{G_HI}{ln}{RST}")
+        time.sleep(0.07)
+
+    print()
+    _subtitle = (
+        "literary consciousness stream"
+        if config.MODE == "poetry"
+        else "digital consciousness stream"
+    )
+    print(f"  {W_DIM}v0.1 · {_subtitle}{RST}")
+    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
+    print()
+    time.sleep(0.4)
+
+    cached = load_cache() if "--refresh" not in sys.argv else None
+    if cached:
+        items = cached
+        boot_ln("Cache", f"LOADED [{len(items)} SIGNALS]", True)
+    elif config.MODE == "poetry":
+        slow_print("  > INITIALIZING LITERARY CORPUS...\n")
+        time.sleep(0.2)
+        print()
+        items, linked, failed = fetch_poetry()
+        print()
+        print(
+            f"  {G_DIM}>{RST} {G_MID}{linked} TEXTS LOADED{RST} {W_GHOST}· {failed} DARK{RST}"
+        )
+        print(f"  {G_DIM}>{RST} {G_MID}{len(items)} STANZAS ACQUIRED{RST}")
+        save_cache(items)
+    else:
+        slow_print("  > INITIALIZING FEED ARRAY...\n")
+        time.sleep(0.2)
+        print()
+        items, linked, failed = fetch_all()
+        print()
+        print(
+            f"  {G_DIM}>{RST} {G_MID}{linked} SOURCES LINKED{RST} {W_GHOST}· {failed} DARK{RST}"
+        )
+        print(f"  {G_DIM}>{RST} {G_MID}{len(items)} SIGNALS ACQUIRED{RST}")
+        save_cache(items)
+
+    if not items:
+        print(f"\n  {W_DIM}> NO SIGNAL — check network{RST}")
+        sys.exit(1)
+
+    print()
+    controller = StreamController()
+    mic_ok, ntfy_ok = controller.initialize_sources()
+
+    if controller.mic and controller.mic.available:
+        boot_ln(
+            "Microphone",
+            "ACTIVE"
+            if mic_ok
+            else "OFFLINE · check System Settings → Privacy → Microphone",
+            bool(mic_ok),
+        )
+
+    boot_ln("ntfy", "LISTENING" if ntfy_ok else "OFFLINE", ntfy_ok)
+
+    if config.FIREHOSE:
+        boot_ln("Firehose", "ENGAGED", True)
+
+    time.sleep(0.4)
+    slow_print("  > STREAMING...\n")
+    time.sleep(0.2)
+    print(f"  {W_GHOST}{'─' * (w - 4)}{RST}")
+    print()
+    time.sleep(0.4)
+
+    controller.run(items)
+
+    print()
+    print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
+    print(f"  {G_DIM}> {config.HEADLINE_LIMIT} SIGNALS PROCESSED{RST}")
+    print(f"  {W_GHOST}> end of stream{RST}")
+    print()

engine/camera.py

@@ -1,354 +0,0 @@
-"""
-Camera system for viewport scrolling.
-
-Provides abstraction for camera motion in different modes:
-- Vertical: traditional upward scroll
-- Horizontal: left/right movement
-- Omni: combination of both
-- Floating: sinusoidal/bobbing motion
-
-The camera defines a visible viewport into a larger Canvas.
-"""
-
-import math
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from enum import Enum, auto
-
-
-class CameraMode(Enum):
-    FEED = auto()  # Single item view (static or rapid cycling)
-    SCROLL = auto()  # Smooth vertical scrolling (movie credits style)
-    HORIZONTAL = auto()
-    OMNI = auto()
-    FLOATING = auto()
-    BOUNCE = auto()
-
-
-@dataclass
-class CameraViewport:
-    """Represents the visible viewport."""
-
-    x: int
-    y: int
-    width: int
-    height: int
-
-
-@dataclass
-class Camera:
-    """Camera for viewport scrolling.
-
-    The camera defines a visible viewport into a Canvas.
-    It can be smaller than the canvas to allow scrolling,
-    and supports zoom to scale the view.
-
-    Attributes:
-        x: Current horizontal offset (positive = scroll left)
-        y: Current vertical offset (positive = scroll up)
-        mode: Current camera mode
-        speed: Base scroll speed
-        zoom: Zoom factor (1.0 = 100%, 2.0 = 200% zoom out)
-        canvas_width: Width of the canvas being viewed
-        canvas_height: Height of the canvas being viewed
-        custom_update: Optional custom update function
-    """
-
-    x: int = 0
-    y: int = 0
-    mode: CameraMode = CameraMode.FEED
-    speed: float = 1.0
-    zoom: float = 1.0
-    canvas_width: int = 200  # Larger than viewport for scrolling
-    canvas_height: int = 200
-    custom_update: Callable[["Camera", float], None] | None = None
-    _x_float: float = field(default=0.0, repr=False)
-    _y_float: float = field(default=0.0, repr=False)
-    _time: float = field(default=0.0, repr=False)
-
-    @property
-    def w(self) -> int:
-        """Shorthand for viewport_width."""
-        return self.viewport_width
-
-    @property
-    def h(self) -> int:
-        """Shorthand for viewport_height."""
-        return self.viewport_height
-
-    @property
-    def viewport_width(self) -> int:
-        """Get the visible viewport width.
-
-        This is the canvas width divided by zoom.
-        """
-        return max(1, int(self.canvas_width / self.zoom))
-
-    @property
-    def viewport_height(self) -> int:
-        """Get the visible viewport height.
-
-        This is the canvas height divided by zoom.
-        """
-        return max(1, int(self.canvas_height / self.zoom))
-
-    def get_viewport(self) -> CameraViewport:
-        """Get the current viewport bounds.
-
-        Returns:
-            CameraViewport with position and size (clamped to canvas bounds)
-        """
-        vw = self.viewport_width
-        vh = self.viewport_height
-
-        clamped_x = max(0, min(self.x, self.canvas_width - vw))
-        clamped_y = max(0, min(self.y, self.canvas_height - vh))
-
-        return CameraViewport(
-            x=clamped_x,
-            y=clamped_y,
-            width=vw,
-            height=vh,
-        )
-
-    def set_zoom(self, zoom: float) -> None:
-        """Set the zoom factor.
-
-        Args:
-            zoom: Zoom factor (1.0 = 100%, 2.0 = zoomed out 2x, 0.5 = zoomed in 2x)
-        """
-        self.zoom = max(0.1, min(10.0, zoom))
-
-    def update(self, dt: float) -> None:
-        """Update camera position based on mode.
-
-        Args:
-            dt: Delta time in seconds
-        """
-        self._time += dt
-
-        if self.custom_update:
-            self.custom_update(self, dt)
-            return
-
-        if self.mode == CameraMode.FEED:
-            self._update_feed(dt)
-        elif self.mode == CameraMode.SCROLL:
-            self._update_scroll(dt)
-        elif self.mode == CameraMode.HORIZONTAL:
-            self._update_horizontal(dt)
-        elif self.mode == CameraMode.OMNI:
-            self._update_omni(dt)
-        elif self.mode == CameraMode.FLOATING:
-            self._update_floating(dt)
-        elif self.mode == CameraMode.BOUNCE:
-            self._update_bounce(dt)
-
-        # Bounce mode handles its own bounds checking
-        if self.mode != CameraMode.BOUNCE:
-            self._clamp_to_bounds()
-
-    def _clamp_to_bounds(self) -> None:
-        """Clamp camera position to stay within canvas bounds.
-
-        Only clamps if the viewport is smaller than the canvas.
-        If viewport equals canvas (no scrolling needed), allows any position
-        for backwards compatibility with original behavior.
-        """
-        vw = self.viewport_width
-        vh = self.viewport_height
-
-        # Only clamp if there's room to scroll
-        if vw < self.canvas_width:
-            self.x = max(0, min(self.x, self.canvas_width - vw))
-        if vh < self.canvas_height:
-            self.y = max(0, min(self.y, self.canvas_height - vh))
-
-    def _update_feed(self, dt: float) -> None:
-        """Feed mode: rapid scrolling (1 row per frame at speed=1.0)."""
-        self.y += int(self.speed * dt * 60)
-
-    def _update_scroll(self, dt: float) -> None:
-        """Scroll mode: smooth vertical scrolling with float accumulation."""
-        self._y_float += self.speed * dt * 60
-        self.y = int(self._y_float)
-
-    def _update_horizontal(self, dt: float) -> None:
-        self.x += int(self.speed * dt * 60)
-
-    def _update_omni(self, dt: float) -> None:
-        speed = self.speed * dt * 60
-        self.y += int(speed)
-        self.x += int(speed * 0.5)
-
-    def _update_floating(self, dt: float) -> None:
-        base = self.speed * 30
-        self.y = int(math.sin(self._time * 2) * base)
-        self.x = int(math.cos(self._time * 1.5) * base * 0.5)
-
-    def _update_bounce(self, dt: float) -> None:
-        """Bouncing DVD-style camera that bounces off canvas edges."""
-        vw = self.viewport_width
-        vh = self.viewport_height
-
-        # Initialize direction if not set
-        if not hasattr(self, "_bounce_dx"):
-            self._bounce_dx = 1
-            self._bounce_dy = 1
-
-        # Calculate max positions
-        max_x = max(0, self.canvas_width - vw)
-        max_y = max(0, self.canvas_height - vh)
-
-        # Move
-        move_speed = self.speed * dt * 60
-
-        # Bounce off edges - reverse direction when hitting bounds
-        self.x += int(move_speed * self._bounce_dx)
-        self.y += int(move_speed * self._bounce_dy)
-
-        # Bounce horizontally
-        if self.x <= 0:
-            self.x = 0
-            self._bounce_dx = 1
-        elif self.x >= max_x:
-            self.x = max_x
-            self._bounce_dx = -1
-
-        # Bounce vertically
-        if self.y <= 0:
-            self.y = 0
-            self._bounce_dy = 1
-        elif self.y >= max_y:
-            self.y = max_y
-            self._bounce_dy = -1
-
-    def reset(self) -> None:
-        """Reset camera position."""
-        self.x = 0
-        self.y = 0
-        self._time = 0.0
-        self.zoom = 1.0
-
-    def set_canvas_size(self, width: int, height: int) -> None:
-        """Set the canvas size and clamp position if needed.
-
-        Args:
-            width: New canvas width
-            height: New canvas height
-        """
-        self.canvas_width = width
-        self.canvas_height = height
-        self._clamp_to_bounds()
-
-    def apply(
-        self, buffer: list[str], viewport_width: int, viewport_height: int | None = None
-    ) -> list[str]:
-        """Apply camera viewport to a text buffer.
-
-        Slices the buffer based on camera position (x, y) and viewport dimensions.
-        Handles ANSI escape codes correctly for colored/styled text.
-
-        Args:
-            buffer: List of strings representing lines of text
-            viewport_width: Width of the visible viewport in characters
-            viewport_height: Height of the visible viewport (overrides camera's viewport_height if provided)
-
-        Returns:
-            Sliced buffer containing only the visible lines and columns
-        """
-        from engine.effects.legacy import vis_offset, vis_trunc
-
-        if not buffer:
-            return buffer
-
-        # Get current viewport bounds (clamped to canvas size)
-        viewport = self.get_viewport()
-
-        # Use provided viewport_height if given, otherwise use camera's viewport
-        vh = viewport_height if viewport_height is not None else viewport.height
-
-        # Vertical slice: extract lines that fit in viewport height
-        start_y = viewport.y
-        end_y = min(viewport.y + vh, len(buffer))
-
-        if start_y >= len(buffer):
-            # Scrolled past end of buffer, return empty viewport
-            return [""] * vh
-
-        vertical_slice = buffer[start_y:end_y]
-
-        # Horizontal slice: apply horizontal offset and truncate to width
-        horizontal_slice = []
-        for line in vertical_slice:
-            # Apply horizontal offset (skip first x characters, handling ANSI)
-            offset_line = vis_offset(line, viewport.x)
-            # Truncate to viewport width (handling ANSI)
-            truncated_line = vis_trunc(offset_line, viewport_width)
-
-            # Pad line to full viewport width to prevent ghosting when panning
-            import re
-
-            visible_len = len(re.sub(r"\x1b\[[0-9;]*m", "", truncated_line))
-            if visible_len < viewport_width:
-                truncated_line += " " * (viewport_width - visible_len)
-
-            horizontal_slice.append(truncated_line)
-
-        # Pad with empty lines if needed to fill viewport height
-        while len(horizontal_slice) < vh:
-            horizontal_slice.append("")
-
-        return horizontal_slice
-
-    @classmethod
-    def feed(cls, speed: float = 1.0) -> "Camera":
-        """Create a feed camera (rapid single-item scrolling, 1 row/frame at speed=1.0)."""
-        return cls(mode=CameraMode.FEED, speed=speed, canvas_height=200)
-
-    @classmethod
-    def scroll(cls, speed: float = 0.5) -> "Camera":
-        """Create a smooth scrolling camera (movie credits style).
-
-        Uses float accumulation for sub-integer speeds.
-        Sets canvas_width=0 so it matches viewport_width for proper text wrapping.
-        """
-        return cls(
-            mode=CameraMode.SCROLL, speed=speed, canvas_width=0, canvas_height=200
-        )
-
-    @classmethod
-    def vertical(cls, speed: float = 1.0) -> "Camera":
-        """Deprecated: Use feed() or scroll() instead."""
-        return cls(mode=CameraMode.FEED, speed=speed, canvas_height=200)
-
-    @classmethod
-    def horizontal(cls, speed: float = 1.0) -> "Camera":
-        """Create a horizontal scrolling camera."""
-        return cls(mode=CameraMode.HORIZONTAL, speed=speed, canvas_width=200)
-
-    @classmethod
-    def omni(cls, speed: float = 1.0) -> "Camera":
-        """Create an omnidirectional scrolling camera."""
-        return cls(
-            mode=CameraMode.OMNI, speed=speed, canvas_width=200, canvas_height=200
-        )
-
-    @classmethod
-    def floating(cls, speed: float = 1.0) -> "Camera":
-        """Create a floating/bobbing camera."""
-        return cls(
-            mode=CameraMode.FLOATING, speed=speed, canvas_width=200, canvas_height=200
-        )
-
-    @classmethod
-    def bounce(cls, speed: float = 1.0) -> "Camera":
-        """Create a bouncing DVD-style camera that bounces off canvas edges."""
-        return cls(
-            mode=CameraMode.BOUNCE, speed=speed, canvas_width=200, canvas_height=200
-        )
-
-    @classmethod
-    def custom(cls, update_fn: Callable[["Camera", float], None]) -> "Camera":
-        """Create a camera with custom update function."""
-        return cls(custom_update=update_fn)

engine/canvas.py

@@ -1,186 +0,0 @@
-"""
-Canvas - 2D surface for rendering.
-
-The Canvas represents a full rendered surface that can be larger than the display.
-The Camera then defines the visible viewport into this canvas.
-"""
-
-from dataclasses import dataclass
-
-
-@dataclass
-class CanvasRegion:
-    """A rectangular region on the canvas."""
-
-    x: int
-    y: int
-    width: int
-    height: int
-
-    def is_valid(self) -> bool:
-        """Check if region has positive dimensions."""
-        return self.width > 0 and self.height > 0
-
-    def rows(self) -> set[int]:
-        """Return set of row indices in this region."""
-        return set(range(self.y, self.y + self.height))
-
-
-class Canvas:
-    """2D canvas for rendering content.
-
-    The canvas is a 2D grid of cells that can hold text content.
-    It can be larger than the visible viewport (display).
-
-    Attributes:
-        width: Total width in characters
-        height: Total height in characters
-    """
-
-    def __init__(self, width: int = 80, height: int = 24):
-        self.width = width
-        self.height = height
-        self._grid: list[list[str]] = [
-            [" " for _ in range(width)] for _ in range(height)
-        ]
-        self._dirty_regions: list[CanvasRegion] = []  # Track dirty regions
-
-    def clear(self) -> None:
-        """Clear the entire canvas."""
-        self._grid = [[" " for _ in range(self.width)] for _ in range(self.height)]
-        self._dirty_regions = [CanvasRegion(0, 0, self.width, self.height)]
-
-    def mark_dirty(self, x: int, y: int, width: int, height: int) -> None:
-        """Mark a region as dirty (caller declares what they changed)."""
-        self._dirty_regions.append(CanvasRegion(x, y, width, height))
-
-    def get_dirty_regions(self) -> list[CanvasRegion]:
-        """Get all dirty regions and clear the set."""
-        regions = self._dirty_regions
-        self._dirty_regions = []
-        return regions
-
-    def get_dirty_rows(self) -> set[int]:
-        """Get union of all dirty rows."""
-        rows: set[int] = set()
-        for region in self._dirty_regions:
-            rows.update(region.rows())
-        return rows
-
-    def is_dirty(self) -> bool:
-        """Check if any region is dirty."""
-        return len(self._dirty_regions) > 0
-
-    def get_region(self, x: int, y: int, width: int, height: int) -> list[list[str]]:
-        """Get a rectangular region from the canvas.
-
-        Args:
-            x: Left position
-            y: Top position
-            width: Region width
-            height: Region height
-
-        Returns:
-            2D list of characters (height rows, width columns)
-        """
-        region: list[list[str]] = []
-        for py in range(y, y + height):
-            row: list[str] = []
-            for px in range(x, x + width):
-                if 0 <= py < self.height and 0 <= px < self.width:
-                    row.append(self._grid[py][px])
-                else:
-                    row.append(" ")
-            region.append(row)
-        return region
-
-    def get_region_flat(self, x: int, y: int, width: int, height: int) -> list[str]:
-        """Get a rectangular region as flat list of lines.
-
-        Args:
-            x: Left position
-            y: Top position
-            width: Region width
-            height: Region height
-
-        Returns:
-            List of strings (one per row)
-        """
-        region = self.get_region(x, y, width, height)
-        return ["".join(row) for row in region]
-
-    def put_region(self, x: int, y: int, content: list[list[str]]) -> None:
-        """Put content into a rectangular region on the canvas.
-
-        Args:
-            x: Left position
-            y: Top position
-            content: 2D list of characters to place
-        """
-        height = len(content) if content else 0
-        width = len(content[0]) if height > 0 else 0
-
-        for py, row in enumerate(content):
-            for px, char in enumerate(row):
-                canvas_x = x + px
-                canvas_y = y + py
-                if 0 <= canvas_y < self.height and 0 <= canvas_x < self.width:
-                    self._grid[canvas_y][canvas_x] = char
-
-        if width > 0 and height > 0:
-            self.mark_dirty(x, y, width, height)
-
-    def put_text(self, x: int, y: int, text: str) -> None:
-        """Put a single line of text at position.
-
-        Args:
-            x: Left position
-            y: Row position
-            text: Text to place
-        """
-        text_len = len(text)
-        for i, char in enumerate(text):
-            canvas_x = x + i
-            if 0 <= canvas_x < self.width and 0 <= y < self.height:
-                self._grid[y][canvas_x] = char
-
-        if text_len > 0:
-            self.mark_dirty(x, y, text_len, 1)
-
-    def fill(self, x: int, y: int, width: int, height: int, char: str = " ") -> None:
-        """Fill a rectangular region with a character.
-
-        Args:
-            x: Left position
-            y: Top position
-            width: Region width
-            height: Region height
-            char: Character to fill with
-        """
-        for py in range(y, y + height):
-            for px in range(x, x + width):
-                if 0 <= py < self.height and 0 <= px < self.width:
-                    self._grid[py][px] = char
-
-        if width > 0 and height > 0:
-            self.mark_dirty(x, y, width, height)
-
-    def resize(self, width: int, height: int) -> None:
-        """Resize the canvas.
-
-        Args:
-            width: New width
-            height: New height
-        """
-        if width == self.width and height == self.height:
-            return
-
-        new_grid: list[list[str]] = [[" " for _ in range(width)] for _ in range(height)]
-
-        for py in range(min(self.height, height)):
-            for px in range(min(self.width, width)):
-                new_grid[py][px] = self._grid[py][px]
-
-        self.width = width
-        self.height = height
-        self._grid = new_grid

engine/config.py

@@ -129,10 +129,6 @@ class Config:
 
     script_fonts: dict[str, str] = field(default_factory=_get_platform_font_paths)
 
-    display: str = "pygame"
-    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)."""
@@ -172,9 +168,6 @@ 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),
         )
 
 
@@ -236,26 +229,6 @@ GRAD_SPEED = 0.08  # gradient traversal speed (cycles/sec, ~12s full sweep)
 GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
 KATA = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"
 
-# ─── WEBSOCKET ─────────────────────────────────────────────
-DISPLAY = _arg_value("--display", sys.argv) or "pygame"
-WEBSOCKET = "--websocket" in sys.argv
-WEBSOCKET_PORT = _arg_int("--websocket-port", 8765)
-
-# ─── DEMO MODE ────────────────────────────────────────────
-DEMO = "--demo" in sys.argv
-DEMO_EFFECT_DURATION = 5.0  # seconds per effect
-PIPELINE_DEMO = "--pipeline-demo" in sys.argv
-
-# ─── PIPELINE MODE (new unified architecture) ─────────────
-PIPELINE_MODE = "--pipeline" in sys.argv
-PIPELINE_PRESET = _arg_value("--pipeline-preset", sys.argv) or "demo"
-
-# ─── PRESET MODE ────────────────────────────────────────────
-PRESET = _arg_value("--preset", sys.argv)
-
-# ─── PIPELINE DIAGRAM ────────────────────────────────────
-PIPELINE_DIAGRAM = "--pipeline-diagram" in sys.argv
-
 
 def set_font_selection(font_path=None, font_index=None):
     """Set runtime primary font selection."""

engine/controller.py

@@ -0,0 +1,134 @@
+"""
+Stream controller - manages input sources and orchestrates the render stream.
+"""
+
+from engine.config import Config, get_config
+from engine.effects.controller import handle_effects_command
+from engine.eventbus import EventBus
+from engine.events import EventType, StreamEvent
+from engine.mic import MicMonitor
+from engine.ntfy import NtfyPoller
+from engine.scroll import stream
+
+
+class StreamController:
+    """Controls the stream lifecycle - initializes sources and runs the stream."""
+
+    _topics_warmed = False
+
+    def __init__(self, config: Config | None = None, event_bus: EventBus | None = None):
+        self.config = config or get_config()
+        self.event_bus = event_bus
+        self.mic: MicMonitor | None = None
+        self.ntfy: NtfyPoller | None = None
+        self.ntfy_cc: NtfyPoller | None = None
+
+    @classmethod
+    def warmup_topics(cls) -> None:
+        """Warm up ntfy topics lazily (creates them if they don't exist)."""
+        if cls._topics_warmed:
+            return
+
+        import urllib.request
+
+        topics = [
+            "https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd",
+            "https://ntfy.sh/klubhaus_terminal_mainline_cc_resp",
+            "https://ntfy.sh/klubhaus_terminal_mainline",
+        ]
+
+        for topic in topics:
+            try:
+                req = urllib.request.Request(
+                    topic,
+                    data=b"init",
+                    headers={
+                        "User-Agent": "mainline/0.1",
+                        "Content-Type": "text/plain",
+                    },
+                    method="POST",
+                )
+                urllib.request.urlopen(req, timeout=5)
+            except Exception:
+                pass
+
+        cls._topics_warmed = True
+
+    def initialize_sources(self) -> tuple[bool, bool]:
+        """Initialize microphone and ntfy sources.
+
+        Returns:
+            (mic_ok, ntfy_ok) - success status for each source
+        """
+        self.mic = MicMonitor(threshold_db=self.config.mic_threshold_db)
+        mic_ok = self.mic.start() if self.mic.available else False
+
+        self.ntfy = NtfyPoller(
+            self.config.ntfy_topic,
+            reconnect_delay=self.config.ntfy_reconnect_delay,
+            display_secs=self.config.message_display_secs,
+        )
+        ntfy_ok = self.ntfy.start()
+
+        self.ntfy_cc = NtfyPoller(
+            self.config.ntfy_cc_cmd_topic,
+            reconnect_delay=self.config.ntfy_reconnect_delay,
+            display_secs=5,
+        )
+        self.ntfy_cc.subscribe(self._handle_cc_message)
+        ntfy_cc_ok = self.ntfy_cc.start()
+
+        return bool(mic_ok), ntfy_ok and ntfy_cc_ok
+
+    def _handle_cc_message(self, event) -> None:
+        """Handle incoming C&C message - like a serial port control interface."""
+        import urllib.request
+
+        cmd = event.body.strip() if hasattr(event, "body") else str(event).strip()
+        if not cmd.startswith("/"):
+            return
+
+        response = handle_effects_command(cmd)
+
+        topic_url = self.config.ntfy_cc_resp_topic.replace("/json", "")
+        data = response.encode("utf-8")
+        req = urllib.request.Request(
+            topic_url,
+            data=data,
+            headers={"User-Agent": "mainline/0.1", "Content-Type": "text/plain"},
+            method="POST",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass
+
+    def run(self, items: list) -> None:
+        """Run the stream with initialized sources."""
+        if self.mic is None or self.ntfy is None:
+            self.initialize_sources()
+
+        if self.event_bus:
+            self.event_bus.publish(
+                EventType.STREAM_START,
+                StreamEvent(
+                    event_type=EventType.STREAM_START,
+                    headline_count=len(items),
+                ),
+            )
+
+        stream(items, self.ntfy, self.mic)
+
+        if self.event_bus:
+            self.event_bus.publish(
+                EventType.STREAM_END,
+                StreamEvent(
+                    event_type=EventType.STREAM_END,
+                    headline_count=len(items),
+                ),
+            )
+
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        if self.mic:
+            self.mic.stop()

engine/data_sources/__init__.py

@@ -1,12 +0,0 @@
-"""
-Data source implementations for the pipeline architecture.
-
-Import directly from submodules:
-    from engine.data_sources.sources import DataSource, SourceItem, HeadlinesDataSource
-    from engine.data_sources.pipeline_introspection import PipelineIntrospectionSource
-"""
-
-# Re-export for convenience
-from engine.data_sources.sources import ImageItem, SourceItem
-
-__all__ = ["ImageItem", "SourceItem"]

engine/data_sources/pipeline_introspection.py

@@ -1,312 +0,0 @@
-"""
-Pipeline introspection source - Renders live visualization of pipeline DAG and metrics.
-
-This DataSource introspects one or more Pipeline instances and renders
-an ASCII visualization showing:
-- Stage DAG with signal flow connections
-- Per-stage execution times
-- Sparkline of frame times
-- Stage breakdown bars
-
-Example:
-    source = PipelineIntrospectionSource(pipelines=[my_pipeline])
-    items = source.fetch()  # Returns ASCII visualization
-"""
-
-from typing import TYPE_CHECKING
-
-from engine.data_sources.sources import DataSource, SourceItem
-
-if TYPE_CHECKING:
-    from engine.pipeline.controller import Pipeline
-
-
-SPARKLINE_CHARS = " ▁▂▃▄▅▆▇█"
-BAR_CHARS = " ▁▂▃▄▅▆▇█"
-
-
-class PipelineIntrospectionSource(DataSource):
-    """Data source that renders live pipeline introspection visualization.
-
-    Renders:
-    - DAG of stages with signal flow
-    - Per-stage execution times
-    - Sparkline of frame history
-    - Stage breakdown bars
-    """
-
-    def __init__(
-        self,
-        pipeline: "Pipeline | None" = None,
-        viewport_width: int = 100,
-        viewport_height: int = 35,
-    ):
-        self._pipeline = pipeline  # May be None initially, set later via set_pipeline()
-        self.viewport_width = viewport_width
-        self.viewport_height = viewport_height
-        self.frame = 0
-        self._ready = False
-
-    def set_pipeline(self, pipeline: "Pipeline") -> None:
-        """Set the pipeline to introspect (call after pipeline is built)."""
-        self._pipeline = [pipeline]  # Wrap in list for iteration
-        self._ready = True
-
-    @property
-    def ready(self) -> bool:
-        """Check if source is ready to fetch."""
-        return self._ready
-
-    @property
-    def name(self) -> str:
-        return "pipeline-inspect"
-
-    @property
-    def is_dynamic(self) -> bool:
-        return True
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.NONE}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    def add_pipeline(self, pipeline: "Pipeline") -> None:
-        """Add a pipeline to visualize."""
-        if self._pipeline is None:
-            self._pipeline = [pipeline]
-        elif isinstance(self._pipeline, list):
-            self._pipeline.append(pipeline)
-        else:
-            self._pipeline = [self._pipeline, pipeline]
-        self._ready = True
-
-    def remove_pipeline(self, pipeline: "Pipeline") -> None:
-        """Remove a pipeline from visualization."""
-        if self._pipeline is None:
-            return
-        elif isinstance(self._pipeline, list):
-            self._pipeline = [p for p in self._pipeline if p is not pipeline]
-            if not self._pipeline:
-                self._pipeline = None
-                self._ready = False
-        elif self._pipeline is pipeline:
-            self._pipeline = None
-            self._ready = False
-
-    def fetch(self) -> list[SourceItem]:
-        """Fetch the introspection visualization."""
-        if not self._ready:
-            # Return a placeholder until ready
-            return [
-                SourceItem(
-                    content="Initializing...",
-                    source="pipeline-inspect",
-                    timestamp="init",
-                )
-            ]
-
-        lines = self._render()
-        self.frame += 1
-        content = "\n".join(lines)
-        return [
-            SourceItem(
-                content=content, source="pipeline-inspect", timestamp=f"f{self.frame}"
-            )
-        ]
-
-    def get_items(self) -> list[SourceItem]:
-        return self.fetch()
-
-    def _render(self) -> list[str]:
-        """Render the full visualization."""
-        lines: list[str] = []
-
-        # Header
-        lines.extend(self._render_header())
-
-        # Render pipeline(s) if ready
-        if self._ready and self._pipeline:
-            pipelines = (
-                self._pipeline if isinstance(self._pipeline, list) else [self._pipeline]
-            )
-            for pipeline in pipelines:
-                lines.extend(self._render_pipeline(pipeline))
-
-        # Footer with sparkline
-        lines.extend(self._render_footer())
-
-        return lines
-
-    @property
-    def _pipelines(self) -> list:
-        """Return pipelines as a list for iteration."""
-        if self._pipeline is None:
-            return []
-        elif isinstance(self._pipeline, list):
-            return self._pipeline
-        else:
-            return [self._pipeline]
-
-    def _render_header(self) -> list[str]:
-        """Render the header with frame info and metrics summary."""
-        lines: list[str] = []
-
-        if not self._pipeline:
-            return ["PIPELINE INTROSPECTION"]
-
-        # Get aggregate metrics
-        total_ms = 0.0
-        fps = 0.0
-        frame_count = 0
-
-        for pipeline in self._pipelines:
-            try:
-                metrics = pipeline.get_metrics_summary()
-                if metrics and "error" not in metrics:
-                    # Get avg_ms from pipeline metrics
-                    pipeline_avg = metrics.get("pipeline", {}).get("avg_ms", 0)
-                    total_ms = max(total_ms, pipeline_avg)
-                    # Calculate FPS from avg_ms
-                    if pipeline_avg > 0:
-                        fps = max(fps, 1000.0 / pipeline_avg)
-                    frame_count = max(frame_count, metrics.get("frame_count", 0))
-            except Exception:
-                pass
-
-        header = f"PIPELINE INTROSPECTION -- frame: {self.frame} -- avg: {total_ms:.1f}ms -- fps: {fps:.1f}"
-        lines.append(header)
-
-        return lines
-
-    def _render_pipeline(self, pipeline: "Pipeline") -> list[str]:
-        """Render a single pipeline's DAG."""
-        lines: list[str] = []
-
-        stages = pipeline.stages
-        execution_order = pipeline.execution_order
-
-        if not stages:
-            lines.append("    (no stages)")
-            return lines
-
-        # Build stage info
-        stage_infos: list[dict] = []
-        for name in execution_order:
-            stage = stages.get(name)
-            if not stage:
-                continue
-
-            try:
-                metrics = pipeline.get_metrics_summary()
-                stage_ms = metrics.get("stages", {}).get(name, {}).get("avg_ms", 0.0)
-            except Exception:
-                stage_ms = 0.0
-
-            stage_infos.append(
-                {
-                    "name": name,
-                    "category": stage.category,
-                    "ms": stage_ms,
-                }
-            )
-
-        # Calculate total time for percentages
-        total_time = sum(s["ms"] for s in stage_infos) or 1.0
-
-        # Render DAG - group by category
-        lines.append("")
-        lines.append("  Signal Flow:")
-
-        # Group stages by category for display
-        categories: dict[str, list[dict]] = {}
-        for info in stage_infos:
-            cat = info["category"]
-            if cat not in categories:
-                categories[cat] = []
-            categories[cat].append(info)
-
-        # Render categories in order
-        cat_order = ["source", "render", "effect", "overlay", "display", "system"]
-
-        for cat in cat_order:
-            if cat not in categories:
-                continue
-
-            cat_stages = categories[cat]
-            cat_names = [s["name"] for s in cat_stages]
-            lines.append(f"    {cat}: {' → '.join(cat_names)}")
-
-        # Render timing breakdown
-        lines.append("")
-        lines.append("  Stage Timings:")
-
-        for info in stage_infos:
-            name = info["name"]
-            ms = info["ms"]
-            pct = (ms / total_time) * 100
-            bar = self._render_bar(pct, 20)
-            lines.append(f"    {name:12s} {ms:6.2f}ms {bar} {pct:5.1f}%")
-
-        lines.append("")
-
-        return lines
-
-    def _render_footer(self) -> list[str]:
-        """Render the footer with sparkline."""
-        lines: list[str] = []
-
-        # Get frame history from first pipeline
-        pipelines = self._pipelines
-        if pipelines:
-            try:
-                frame_times = pipelines[0].get_frame_times()
-            except Exception:
-                frame_times = []
-        else:
-            frame_times = []
-
-        if frame_times:
-            sparkline = self._render_sparkline(frame_times[-60:], 50)
-            lines.append(f" Frame Time History (last {len(frame_times[-60:])} frames)")
-            lines.append(f" {sparkline}")
-        else:
-            lines.append(" Frame Time History")
-            lines.append(" (collecting data...)")
-
-        lines.append("")
-
-        return lines
-
-    def _render_bar(self, percentage: float, width: int) -> str:
-        """Render a horizontal bar for percentage."""
-        filled = int((percentage / 100.0) * width)
-        bar = "█" * filled + "░" * (width - filled)
-        return bar
-
-    def _render_sparkline(self, values: list[float], width: int) -> str:
-        """Render a sparkline from values."""
-        if not values:
-            return " " * width
-
-        min_val = min(values)
-        max_val = max(values)
-        range_val = max_val - min_val or 1.0
-
-        result = []
-        for v in values[-width:]:
-            normalized = (v - min_val) / range_val
-            idx = int(normalized * (len(SPARKLINE_CHARS) - 1))
-            idx = max(0, min(idx, len(SPARKLINE_CHARS) - 1))
-            result.append(SPARKLINE_CHARS[idx])
-
-        # Pad to width
-        while len(result) < width:
-            result.insert(0, " ")
-        return "".join(result[:width])

engine/data_sources/sources.py

@@ -1,490 +0,0 @@
-"""
-Data sources for the pipeline architecture.
-
-This module contains all DataSource implementations:
-- DataSource: Abstract base class
-- SourceItem, ImageItem: Data containers
-- HeadlinesDataSource, PoetryDataSource, ImageDataSource: Concrete sources
-- SourceRegistry: Registry for source discovery
-"""
-
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import Any
-
-
-@dataclass
-class SourceItem:
-    """A single item from a data source."""
-
-    content: str
-    source: str
-    timestamp: str
-    metadata: dict[str, Any] | None = None
-
-
-@dataclass
-class ImageItem:
-    """An image item from a data source - wraps a PIL Image."""
-
-    image: Any  # PIL Image
-    source: str
-    timestamp: str
-    path: str | None = None  # File path or URL if applicable
-    metadata: dict[str, Any] | None = None
-
-
-class DataSource(ABC):
-    """Abstract base class for data sources.
-
-    Static sources: Data fetched once and cached. Safe to call fetch() multiple times.
-    Dynamic sources: Data changes over time. fetch() should be idempotent.
-    """
-
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """Display name for this source."""
-        ...
-
-    @property
-    def is_dynamic(self) -> bool:
-        """Whether this source updates dynamically while the app runs. Default False."""
-        return False
-
-    @abstractmethod
-    def fetch(self) -> list[SourceItem]:
-        """Fetch fresh data from the source. Must be idempotent."""
-        ...
-
-    def get_items(self) -> list[SourceItem]:
-        """Get current items. Default implementation returns cached fetch results."""
-        if not hasattr(self, "_items") or self._items is None:
-            self._items = self.fetch()
-        return self._items
-
-    def refresh(self) -> list[SourceItem]:
-        """Force refresh - clear cache and fetch fresh data."""
-        self._items = self.fetch()
-        return self._items
-
-    def stream(self):
-        """Optional: Yield items continuously. Override for streaming sources."""
-        raise NotImplementedError
-
-    def __post_init__(self):
-        self._items: list[SourceItem] | None = None
-
-
-class HeadlinesDataSource(DataSource):
-    """Data source for RSS feed headlines."""
-
-    @property
-    def name(self) -> str:
-        return "headlines"
-
-    def fetch(self) -> list[SourceItem]:
-        from engine.fetch import fetch_all
-
-        items, _, _ = fetch_all()
-        return [SourceItem(content=t, source=s, timestamp=ts) for t, s, ts in items]
-
-
-class EmptyDataSource(DataSource):
-    """Empty data source that produces blank lines for testing.
-
-    Useful for testing display borders, effects, and other pipeline
-    components without needing actual content.
-    """
-
-    def __init__(self, width: int = 80, height: int = 24):
-        self.width = width
-        self.height = height
-
-    @property
-    def name(self) -> str:
-        return "empty"
-
-    @property
-    def is_dynamic(self) -> bool:
-        return False
-
-    def fetch(self) -> list[SourceItem]:
-        # Return empty lines as content
-        content = "\n".join([" " * self.width for _ in range(self.height)])
-        return [SourceItem(content=content, source="empty", timestamp="0")]
-
-
-class ListDataSource(DataSource):
-    """Data source that wraps a pre-fetched list of items.
-
-    Used for bootstrap loading when items are already available in memory.
-    This is a simple wrapper for already-fetched data.
-    """
-
-    def __init__(self, items, name: str = "list"):
-        self._raw_items = items  # Store raw items separately
-        self._items = None  # Cache for converted SourceItem objects
-        self._name = name
-
-    @property
-    def name(self) -> str:
-        return self._name
-
-    @property
-    def is_dynamic(self) -> bool:
-        return False
-
-    def fetch(self) -> list[SourceItem]:
-        # Convert tuple items to SourceItem if needed
-        result = []
-        for item in self._raw_items:
-            if isinstance(item, SourceItem):
-                result.append(item)
-            elif isinstance(item, tuple) and len(item) >= 3:
-                # Assume (content, source, timestamp) tuple format
-                result.append(
-                    SourceItem(content=item[0], source=item[1], timestamp=str(item[2]))
-                )
-            else:
-                # Fallback: treat as string content
-                result.append(
-                    SourceItem(content=str(item), source="list", timestamp="0")
-                )
-        return result
-
-
-class PoetryDataSource(DataSource):
-    """Data source for Poetry DB."""
-
-    @property
-    def name(self) -> str:
-        return "poetry"
-
-    def fetch(self) -> list[SourceItem]:
-        from engine.fetch import fetch_poetry
-
-        items, _, _ = fetch_poetry()
-        return [SourceItem(content=t, source=s, timestamp=ts) for t, s, ts in items]
-
-
-class ImageDataSource(DataSource):
-    """Data source that loads PNG images from file paths or URLs.
-
-    Supports:
-    - Local file paths (e.g., /path/to/image.png)
-    - URLs (e.g., https://example.com/image.png)
-
-    Yields ImageItem objects containing PIL Image objects that can be
-    converted to text buffers by an ImageToTextTransform stage.
-    """
-
-    def __init__(
-        self,
-        path: str | list[str] | None = None,
-        urls: str | list[str] | None = None,
-    ):
-        """
-        Args:
-            path: Single path or list of paths to PNG files
-            urls: Single URL or list of URLs to PNG images
-        """
-        self._paths = [path] if isinstance(path, str) else (path or [])
-        self._urls = [urls] if isinstance(urls, str) else (urls or [])
-        self._images: list[ImageItem] = []
-        self._load_images()
-
-    def _load_images(self) -> None:
-        """Load all images from paths and URLs."""
-        from datetime import datetime
-        from io import BytesIO
-        from urllib.request import urlopen
-
-        timestamp = datetime.now().isoformat()
-
-        for path in self._paths:
-            try:
-                from PIL import Image
-
-                img = Image.open(path)
-                if img.mode != "RGBA":
-                    img = img.convert("RGBA")
-                self._images.append(
-                    ImageItem(
-                        image=img,
-                        source=f"file:{path}",
-                        timestamp=timestamp,
-                        path=path,
-                    )
-                )
-            except Exception:
-                pass
-
-        for url in self._urls:
-            try:
-                from PIL import Image
-
-                with urlopen(url) as response:
-                    img = Image.open(BytesIO(response.read()))
-                if img.mode != "RGBA":
-                    img = img.convert("RGBA")
-                self._images.append(
-                    ImageItem(
-                        image=img,
-                        source=f"url:{url}",
-                        timestamp=timestamp,
-                        path=url,
-                    )
-                )
-            except Exception:
-                pass
-
-    @property
-    def name(self) -> str:
-        return "image"
-
-    @property
-    def is_dynamic(self) -> bool:
-        return False  # Static images, not updating
-
-    def fetch(self) -> list[ImageItem]:
-        """Return loaded images as ImageItem list."""
-        return self._images
-
-    def get_items(self) -> list[ImageItem]:
-        """Return current image items."""
-        return self._images
-
-
-class MetricsDataSource(DataSource):
-    """Data source that renders live pipeline metrics as ASCII art.
-
-    Wraps a Pipeline and displays active stages with their average execution
-    time and approximate FPS impact. Updates lazily when camera is about to
-    focus on a new node (frame % 15 == 12).
-    """
-
-    def __init__(
-        self,
-        pipeline: Any,
-        viewport_width: int = 80,
-        viewport_height: int = 24,
-    ):
-        self.pipeline = pipeline
-        self.viewport_width = viewport_width
-        self.viewport_height = viewport_height
-        self.frame = 0
-        self._cached_metrics: dict | None = None
-
-    @property
-    def name(self) -> str:
-        return "metrics"
-
-    @property
-    def is_dynamic(self) -> bool:
-        return True
-
-    def fetch(self) -> list[SourceItem]:
-        if self.frame % 15 == 12:
-            self._cached_metrics = None
-
-        if self._cached_metrics is None:
-            self._cached_metrics = self._fetch_metrics()
-
-        buffer = self._render_metrics(self._cached_metrics)
-        self.frame += 1
-        content = "\n".join(buffer)
-        return [
-            SourceItem(content=content, source="metrics", timestamp=f"f{self.frame}")
-        ]
-
-    def _fetch_metrics(self) -> dict:
-        if hasattr(self.pipeline, "get_metrics_summary"):
-            metrics = self.pipeline.get_metrics_summary()
-            if "error" not in metrics:
-                return metrics
-        return {"stages": {}, "pipeline": {"avg_ms": 0}}
-
-    def _render_metrics(self, metrics: dict) -> list[str]:
-        stages = metrics.get("stages", {})
-
-        if not stages:
-            return self._render_empty()
-
-        active_stages = {
-            name: stats for name, stats in stages.items() if stats.get("avg_ms", 0) > 0
-        }
-
-        if not active_stages:
-            return self._render_empty()
-
-        total_avg = sum(s["avg_ms"] for s in active_stages.values())
-        if total_avg == 0:
-            total_avg = 1
-
-        lines: list[str] = []
-        lines.append("═" * self.viewport_width)
-        lines.append(" PIPELINE METRICS ".center(self.viewport_width, "─"))
-        lines.append("─" * self.viewport_width)
-
-        header = f"{'STAGE':<20} {'AVG_MS':>8} {'FPS %':>8}"
-        lines.append(header)
-        lines.append("─" * self.viewport_width)
-
-        for name, stats in sorted(active_stages.items()):
-            avg_ms = stats.get("avg_ms", 0)
-            fps_impact = (avg_ms / 16.67) * 100 if avg_ms > 0 else 0
-
-            row = f"{name:<20} {avg_ms:>7.2f} {fps_impact:>7.1f}%"
-            lines.append(row[: self.viewport_width])
-
-        lines.append("─" * self.viewport_width)
-        total_row = (
-            f"{'TOTAL':<20} {total_avg:>7.2f} {(total_avg / 16.67) * 100:>7.1f}%"
-        )
-        lines.append(total_row[: self.viewport_width])
-        lines.append("─" * self.viewport_width)
-        lines.append(
-            f" Frame:{self.frame:04d}  Cache:{'HIT' if self._cached_metrics else 'MISS'}"
-        )
-
-        while len(lines) < self.viewport_height:
-            lines.append(" " * self.viewport_width)
-
-        return lines[: self.viewport_height]
-
-    def _render_empty(self) -> list[str]:
-        lines = [" " * self.viewport_width for _ in range(self.viewport_height)]
-        msg = "No metrics available"
-        y = self.viewport_height // 2
-        x = (self.viewport_width - len(msg)) // 2
-        lines[y] = " " * x + msg + " " * (self.viewport_width - x - len(msg))
-        return lines
-
-    def get_items(self) -> list[SourceItem]:
-        return self.fetch()
-
-
-class CachedDataSource(DataSource):
-    """Data source that wraps another source with caching."""
-
-    def __init__(self, source: DataSource, max_items: int = 100):
-        self.source = source
-        self.max_items = max_items
-
-    @property
-    def name(self) -> str:
-        return f"cached:{self.source.name}"
-
-    def fetch(self) -> list[SourceItem]:
-        items = self.source.fetch()
-        return items[: self.max_items]
-
-    def get_items(self) -> list[SourceItem]:
-        if not hasattr(self, "_items") or self._items is None:
-            self._items = self.fetch()
-        return self._items
-
-
-class TransformDataSource(DataSource):
-    """Data source that transforms items from another source.
-
-    Applies optional filter and map functions to each item.
-    This enables chaining: source → transform → transformed output.
-
-    Args:
-        source: The source to fetch items from
-        filter_fn: Optional function(item: SourceItem) -> bool
-        map_fn: Optional function(item: SourceItem) -> SourceItem
-    """
-
-    def __init__(
-        self,
-        source: DataSource,
-        filter_fn: Callable[[SourceItem], bool] | None = None,
-        map_fn: Callable[[SourceItem], SourceItem] | None = None,
-    ):
-        self.source = source
-        self.filter_fn = filter_fn
-        self.map_fn = map_fn
-
-    @property
-    def name(self) -> str:
-        return f"transform:{self.source.name}"
-
-    def fetch(self) -> list[SourceItem]:
-        items = self.source.fetch()
-
-        if self.filter_fn:
-            items = [item for item in items if self.filter_fn(item)]
-
-        if self.map_fn:
-            items = [self.map_fn(item) for item in items]
-
-        return items
-
-
-class CompositeDataSource(DataSource):
-    """Data source that combines multiple sources."""
-
-    def __init__(self, sources: list[DataSource]):
-        self.sources = sources
-
-    @property
-    def name(self) -> str:
-        return "composite"
-
-    def fetch(self) -> list[SourceItem]:
-        items = []
-        for source in self.sources:
-            items.extend(source.fetch())
-        return items
-
-
-class SourceRegistry:
-    """Registry for data sources."""
-
-    def __init__(self):
-        self._sources: dict[str, DataSource] = {}
-        self._default: str | None = None
-
-    def register(self, source: DataSource, default: bool = False) -> None:
-        self._sources[source.name] = source
-        if default or self._default is None:
-            self._default = source.name
-
-    def get(self, name: str) -> DataSource | None:
-        return self._sources.get(name)
-
-    def list_all(self) -> dict[str, DataSource]:
-        return dict(self._sources)
-
-    def default(self) -> DataSource | None:
-        if self._default:
-            return self._sources.get(self._default)
-        return None
-
-    def create_headlines(self) -> HeadlinesDataSource:
-        return HeadlinesDataSource()
-
-    def create_poetry(self) -> PoetryDataSource:
-        return PoetryDataSource()
-
-
-_global_registry: SourceRegistry | None = None
-
-
-def get_source_registry() -> SourceRegistry:
-    global _global_registry
-    if _global_registry is None:
-        _global_registry = SourceRegistry()
-    return _global_registry
-
-
-def init_default_sources() -> SourceRegistry:
-    """Initialize the default source registry with standard sources."""
-    registry = get_source_registry()
-    registry.register(HeadlinesDataSource(), default=True)
-    registry.register(PoetryDataSource())
-    return registry

engine/display.py

@@ -0,0 +1,102 @@
+"""
+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

engine/display/__init__.py

@@ -1,250 +0,0 @@
-"""
-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.kitty import KittyDisplay
-from engine.display.backends.multi import MultiDisplay
-from engine.display.backends.null import NullDisplay
-from engine.display.backends.pygame import PygameDisplay
-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.
-
-    All display backends must implement:
-    - width, height: Terminal dimensions
-    - init(width, height, reuse=False): Initialize the display
-    - show(buffer): Render buffer to display
-    - clear(): Clear the display
-    - cleanup(): Shutdown the display
-
-    Optional methods for keyboard input:
-    - is_quit_requested(): Returns True if user pressed Ctrl+C/Q or Escape
-    - clear_quit_request(): Clears the quit request flag
-
-    The reuse flag allows attaching to an existing display instance
-    rather than creating a new window/connection.
-
-    Keyboard input support by backend:
-    - terminal: No native input (relies on signal handler for Ctrl+C)
-    - pygame: Supports Ctrl+C, Ctrl+Q, Escape for graceful shutdown
-    - websocket: No native input (relies on signal handler for Ctrl+C)
-    - sixel: No native input (relies on signal handler for Ctrl+C)
-    - null: No native input
-    - kitty: Supports Ctrl+C, Ctrl+Q, Escape (via pygame-like handling)
-    """
-
-    width: int
-    height: int
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: If True, attach to existing display instead of creating new
-        """
-        ...
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        """Show buffer on display.
-
-        Args:
-            buffer: Buffer to display
-            border: If True, render border around buffer (default False)
-        """
-        ...
-
-    def clear(self) -> None:
-        """Clear display."""
-        ...
-
-    def cleanup(self) -> None:
-        """Shutdown display."""
-        ...
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current terminal dimensions.
-
-        Returns:
-            (width, height) in character cells
-
-        This method is called after show() to check if the display
-        was resized. The main loop should compare this to the current
-        viewport dimensions and update accordingly.
-        """
-        ...
-
-    def is_quit_requested(self) -> bool:
-        """Check if user requested quit (Ctrl+C, Ctrl+Q, or Escape).
-
-        Returns:
-            True if quit was requested, False otherwise
-
-        Optional method - only implemented by backends that support keyboard input.
-        """
-        ...
-
-    def clear_quit_request(self) -> None:
-        """Clear the quit request flag.
-
-        Optional method - only implemented by backends that support keyboard input.
-        """
-        ...
-
-
-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."""
-        cls.initialize()
-        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.register("kitty", KittyDisplay)
-        cls.register("pygame", PygameDisplay)
-
-        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
-
-
-def _strip_ansi(s: str) -> str:
-    """Strip ANSI escape sequences from string for length calculation."""
-    import re
-
-    return re.sub(r"\x1b\[[0-9;]*[a-zA-Z]", "", s)
-
-
-def render_border(
-    buf: list[str], width: int, height: int, fps: float = 0.0, frame_time: float = 0.0
-) -> list[str]:
-    """Render a border around the buffer.
-
-    Args:
-        buf: Input buffer (list of strings)
-        width: Display width in characters
-        height: Display height in rows
-        fps: Current FPS to display in top border (optional)
-        frame_time: Frame time in ms to display in bottom border (optional)
-
-    Returns:
-        Buffer with border applied
-    """
-    if not buf or width < 3 or height < 3:
-        return buf
-
-    inner_w = width - 2
-    inner_h = height - 2
-
-    # Crop buffer to fit inside border
-    cropped = []
-    for i in range(min(inner_h, len(buf))):
-        line = buf[i]
-        # Calculate visible width (excluding ANSI codes)
-        visible_len = len(_strip_ansi(line))
-        if visible_len > inner_w:
-            # Truncate carefully - this is approximate for ANSI text
-            cropped.append(line[:inner_w])
-        else:
-            cropped.append(line + " " * (inner_w - visible_len))
-
-    # Pad with empty lines if needed
-    while len(cropped) < inner_h:
-        cropped.append(" " * inner_w)
-
-    # Build borders
-    if fps > 0:
-        fps_str = f" FPS:{fps:.0f}"
-        if len(fps_str) < inner_w:
-            right_len = inner_w - len(fps_str)
-            top_border = "┌" + "─" * right_len + fps_str + "┐"
-        else:
-            top_border = "┌" + "─" * inner_w + "┐"
-    else:
-        top_border = "┌" + "─" * inner_w + "┐"
-
-    if frame_time > 0:
-        ft_str = f" {frame_time:.1f}ms"
-        if len(ft_str) < inner_w:
-            right_len = inner_w - len(ft_str)
-            bottom_border = "└" + "─" * right_len + ft_str + "┘"
-        else:
-            bottom_border = "└" + "─" * inner_w + "┘"
-    else:
-        bottom_border = "└" + "─" * inner_w + "┘"
-
-    # Build result with left/right borders
-    result = [top_border]
-    for line in cropped:
-        # Ensure exactly inner_w characters before adding right border
-        if len(line) < inner_w:
-            line = line + " " * (inner_w - len(line))
-        elif len(line) > inner_w:
-            line = line[:inner_w]
-        result.append("│" + line + "│")
-    result.append(bottom_border)
-
-    return result
-
-
-__all__ = [
-    "Display",
-    "DisplayRegistry",
-    "get_monitor",
-    "render_border",
-    "TerminalDisplay",
-    "NullDisplay",
-    "WebSocketDisplay",
-    "SixelDisplay",
-    "MultiDisplay",
-]

engine/display/backends/kitty.py

@@ -1,180 +0,0 @@
-"""
-Kitty graphics display backend - renders using kitty's native graphics protocol.
-"""
-
-import time
-
-from engine.display.renderer import get_default_font_path, parse_ansi
-
-
-def _encode_kitty_graphic(image_data: bytes, width: int, height: int) -> bytes:
-    """Encode image data using kitty's graphics protocol."""
-    import base64
-
-    encoded = base64.b64encode(image_data).decode("ascii")
-
-    chunks = []
-    for i in range(0, len(encoded), 4096):
-        chunk = encoded[i : i + 4096]
-        if i == 0:
-            chunks.append(f"\x1b_Gf=100,t=d,s={width},v={height},c=1,r=1;{chunk}\x1b\\")
-        else:
-            chunks.append(f"\x1b_Gm={height};{chunk}\x1b\\")
-
-    return "".join(chunks).encode("utf-8")
-
-
-class KittyDisplay:
-    """Kitty graphics display backend using kitty's native protocol."""
-
-    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
-        self._font_path = None
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: Ignored for KittyDisplay (protocol doesn't support reuse)
-        """
-        self.width = width
-        self.height = height
-        self._initialized = True
-
-    def _get_font_path(self) -> str | None:
-        """Get font path from env or detect common locations."""
-        import os
-
-        if self._font_path:
-            return self._font_path
-
-        env_font = os.environ.get("MAINLINE_KITTY_FONT")
-        if env_font and os.path.exists(env_font):
-            self._font_path = env_font
-            return env_font
-
-        font_path = get_default_font_path()
-        if font_path:
-            self._font_path = font_path
-
-        return self._font_path
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        import sys
-
-        t0 = time.perf_counter()
-
-        # Get metrics for border display
-        fps = 0.0
-        frame_time = 0.0
-        from engine.display import get_monitor
-
-        monitor = get_monitor()
-        if monitor:
-            stats = monitor.get_stats()
-            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
-            frame_count = stats.get("frame_count", 0) if stats else 0
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Apply border if requested
-        if border:
-            from engine.display import render_border
-
-            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
-
-        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)
-
-        font_path = self._get_font_path()
-        font = None
-        if font_path:
-            try:
-                font = ImageFont.truetype(font_path, self.cell_height - 2)
-            except Exception:
-                font = None
-
-        if font is None:
-            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)
-
-        from io import BytesIO
-
-        output = BytesIO()
-        img.save(output, format="PNG")
-        png_data = output.getvalue()
-
-        graphic = _encode_kitty_graphic(png_data, img_width, img_height)
-
-        sys.stdout.buffer.write(graphic)
-        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("kitty_display", elapsed_ms, chars_in, chars_in)
-
-    def clear(self) -> None:
-        import sys
-
-        sys.stdout.buffer.write(b"\x1b_Ga=d\x1b\\")
-        sys.stdout.flush()
-
-    def cleanup(self) -> None:
-        self.clear()
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current dimensions.
-
-        Returns:
-            (width, height) in character cells
-        """
-        return (self.width, self.height)

engine/display/backends/multi.py

@@ -1,50 +0,0 @@
-"""
-Multi display backend - forwards to multiple displays.
-"""
-
-
-class MultiDisplay:
-    """Display that forwards to multiple displays.
-
-    Supports reuse - passes reuse flag to all child 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, reuse: bool = False) -> None:
-        """Initialize all child displays with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: If True, use reuse mode for child displays
-        """
-        self.width = width
-        self.height = height
-        for d in self.displays:
-            d.init(width, height, reuse=reuse)
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        for d in self.displays:
-            d.show(buffer, border=border)
-
-    def clear(self) -> None:
-        for d in self.displays:
-            d.clear()
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get dimensions from the first child display that supports it."""
-        for d in self.displays:
-            if hasattr(d, "get_dimensions"):
-                return d.get_dimensions()
-        return (self.width, self.height)
-
-    def cleanup(self) -> None:
-        for d in self.displays:
-            d.cleanup()

engine/display/backends/null.py

@@ -1,51 +0,0 @@
-"""
-Null/headless display backend.
-"""
-
-import time
-
-
-class NullDisplay:
-    """Headless/null display - discards all output.
-
-    This display does nothing - useful for headless benchmarking
-    or when no display output is needed.
-    """
-
-    width: int = 80
-    height: int = 24
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: Ignored for NullDisplay (no resources to reuse)
-        """
-        self.width = width
-        self.height = height
-
-    def show(self, buffer: list[str], border: bool = False) -> 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
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current dimensions.
-
-        Returns:
-            (width, height) in character cells
-        """
-        return (self.width, self.height)

engine/display/backends/pygame.py

@@ -1,277 +0,0 @@
-"""
-Pygame display backend - renders to a native application window.
-"""
-
-import time
-
-from engine.display.renderer import parse_ansi
-
-
-class PygameDisplay:
-    """Pygame display backend - renders to native window.
-
-    Supports reuse mode - when reuse=True, skips SDL initialization
-    and reuses the existing pygame window from a previous instance.
-    """
-
-    width: int = 80
-    window_width: int = 800
-    window_height: int = 600
-
-    def __init__(
-        self,
-        cell_width: int = 10,
-        cell_height: int = 18,
-        window_width: int = 800,
-        window_height: int = 600,
-        target_fps: float = 30.0,
-    ):
-        self.width = 80
-        self.height = 24
-        self.cell_width = cell_width
-        self.cell_height = cell_height
-        self.window_width = window_width
-        self.window_height = window_height
-        self.target_fps = target_fps
-        self._initialized = False
-        self._pygame = None
-        self._screen = None
-        self._font = None
-        self._resized = False
-        self._quit_requested = False
-        self._last_frame_time = 0.0
-        self._frame_period = 1.0 / target_fps if target_fps > 0 else 0
-
-    def _get_font_path(self) -> str | None:
-        """Get font path for rendering."""
-        import os
-        import sys
-        from pathlib import Path
-
-        env_font = os.environ.get("MAINLINE_PYGAME_FONT")
-        if env_font and os.path.exists(env_font):
-            return env_font
-
-        def search_dir(base_path: str) -> str | None:
-            if not os.path.exists(base_path):
-                return None
-            if os.path.isfile(base_path):
-                return base_path
-            for font_file in Path(base_path).rglob("*"):
-                if font_file.suffix.lower() in (".ttf", ".otf", ".ttc"):
-                    name = font_file.stem.lower()
-                    if "geist" in name and ("nerd" in name or "mono" in name):
-                        return str(font_file)
-            return None
-
-        search_dirs = []
-        if sys.platform == "darwin":
-            search_dirs.append(os.path.expanduser("~/Library/Fonts/"))
-        elif sys.platform == "win32":
-            search_dirs.append(
-                os.path.expanduser("~\\AppData\\Local\\Microsoft\\Windows\\Fonts\\")
-            )
-        else:
-            search_dirs.extend(
-                [
-                    os.path.expanduser("~/.local/share/fonts/"),
-                    os.path.expanduser("~/.fonts/"),
-                    "/usr/share/fonts/",
-                ]
-            )
-
-        for search_dir_path in search_dirs:
-            found = search_dir(search_dir_path)
-            if found:
-                return found
-
-        return None
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: If True, attach to existing pygame window instead of creating new
-        """
-        self.width = width
-        self.height = height
-
-        import os
-
-        os.environ["SDL_VIDEODRIVER"] = "x11"
-
-        try:
-            import pygame
-        except ImportError:
-            return
-
-        if reuse and PygameDisplay._pygame_initialized:
-            self._pygame = pygame
-            self._initialized = True
-            return
-
-        pygame.init()
-        pygame.display.set_caption("Mainline")
-
-        self._screen = pygame.display.set_mode(
-            (self.window_width, self.window_height),
-            pygame.RESIZABLE,
-        )
-        self._pygame = pygame
-        PygameDisplay._pygame_initialized = True
-
-        # Calculate character dimensions from actual window size
-        self.width = max(1, self.window_width // self.cell_width)
-        self.height = max(1, self.window_height // self.cell_height)
-
-        font_path = self._get_font_path()
-        if font_path:
-            try:
-                self._font = pygame.font.Font(font_path, self.cell_height - 2)
-            except Exception:
-                self._font = pygame.font.SysFont("monospace", self.cell_height - 2)
-        else:
-            self._font = pygame.font.SysFont("monospace", self.cell_height - 2)
-
-        self._initialized = True
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        if not self._initialized or not self._pygame:
-            return
-
-        t0 = time.perf_counter()
-
-        for event in self._pygame.event.get():
-            if event.type == self._pygame.QUIT:
-                self._quit_requested = True
-            elif event.type == self._pygame.KEYDOWN:
-                if event.key in (self._pygame.K_ESCAPE, self._pygame.K_c):
-                    if event.key == self._pygame.K_c and not (
-                        event.mod & self._pygame.KMOD_LCTRL
-                        or event.mod & self._pygame.KMOD_RCTRL
-                    ):
-                        continue
-                    self._quit_requested = True
-            elif event.type == self._pygame.VIDEORESIZE:
-                self.window_width = event.w
-                self.window_height = event.h
-                self.width = max(1, self.window_width // self.cell_width)
-                self.height = max(1, self.window_height // self.cell_height)
-                self._resized = True
-
-        # FPS limiting - skip frame if we're going too fast
-        if self._frame_period > 0:
-            now = time.perf_counter()
-            elapsed = now - self._last_frame_time
-            if elapsed < self._frame_period:
-                return  # Skip this frame
-            self._last_frame_time = now
-
-        # Get metrics for border display
-        fps = 0.0
-        frame_time = 0.0
-        from engine.display import get_monitor
-
-        monitor = get_monitor()
-        if monitor:
-            stats = monitor.get_stats()
-            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
-            frame_count = stats.get("frame_count", 0) if stats else 0
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Apply border if requested
-        if border:
-            from engine.display import render_border
-
-            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
-
-        self._screen.fill((0, 0, 0))
-
-        for row_idx, line in enumerate(buffer[: self.height]):
-            if row_idx >= self.height:
-                break
-
-            tokens = parse_ansi(line)
-            x_pos = 0
-
-            for text, fg, bg, _bold in tokens:
-                if not text:
-                    continue
-
-                if bg != (0, 0, 0):
-                    bg_surface = self._font.render(text, True, fg, bg)
-                    self._screen.blit(bg_surface, (x_pos, row_idx * self.cell_height))
-                else:
-                    text_surface = self._font.render(text, True, fg)
-                    self._screen.blit(text_surface, (x_pos, row_idx * self.cell_height))
-
-                x_pos += self._font.size(text)[0]
-
-        self._pygame.display.flip()
-
-        elapsed_ms = (time.perf_counter() - t0) * 1000
-
-        if monitor:
-            chars_in = sum(len(line) for line in buffer)
-            monitor.record_effect("pygame_display", elapsed_ms, chars_in, chars_in)
-
-    def clear(self) -> None:
-        if self._screen and self._pygame:
-            self._screen.fill((0, 0, 0))
-            self._pygame.display.flip()
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current terminal dimensions based on window size.
-
-        Returns:
-            (width, height) in character cells
-        """
-        # Query actual window size and recalculate character cells
-        if self._screen and self._pygame:
-            try:
-                w, h = self._screen.get_size()
-                if w != self.window_width or h != self.window_height:
-                    self.window_width = w
-                    self.window_height = h
-                    self.width = max(1, w // self.cell_width)
-                    self.height = max(1, h // self.cell_height)
-            except Exception:
-                pass
-        return self.width, self.height
-
-    def cleanup(self, quit_pygame: bool = True) -> None:
-        """Cleanup display resources.
-
-        Args:
-            quit_pygame: If True, quit pygame entirely. Set to False when
-                        reusing the display to avoid closing shared window.
-        """
-        if quit_pygame and self._pygame:
-            self._pygame.quit()
-            PygameDisplay._pygame_initialized = False
-
-    @classmethod
-    def reset_state(cls) -> None:
-        """Reset pygame state - useful for testing."""
-        cls._pygame_initialized = False
-
-    def is_quit_requested(self) -> bool:
-        """Check if user requested quit (Ctrl+C, Ctrl+Q, or Escape).
-
-        Returns True if the user pressed Ctrl+C, Ctrl+Q, or Escape.
-        The main loop should check this and raise KeyboardInterrupt.
-        """
-        return self._quit_requested
-
-    def clear_quit_request(self) -> bool:
-        """Clear the quit request flag after handling.
-
-        Returns the previous quit request state.
-        """
-        was_requested = self._quit_requested
-        self._quit_requested = False
-        return was_requested

engine/display/backends/sixel.py

@@ -1,228 +0,0 @@
-"""
-Sixel graphics display backend - renders to sixel graphics in terminal.
-"""
-
-import time
-
-from engine.display.renderer import get_default_font_path, parse_ansi
-
-
-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
-        self._font_path = None
-
-    def _get_font_path(self) -> str | None:
-        """Get font path from env or detect common locations."""
-        import os
-
-        if self._font_path:
-            return self._font_path
-
-        env_font = os.environ.get("MAINLINE_SIXEL_FONT")
-        if env_font and os.path.exists(env_font):
-            self._font_path = env_font
-            return env_font
-
-        font_path = get_default_font_path()
-        if font_path:
-            self._font_path = font_path
-
-        return self._font_path
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: Ignored for SixelDisplay
-        """
-        self.width = width
-        self.height = height
-        self._initialized = True
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        import sys
-
-        t0 = time.perf_counter()
-
-        # Get metrics for border display
-        fps = 0.0
-        frame_time = 0.0
-        from engine.display import get_monitor
-
-        monitor = get_monitor()
-        if monitor:
-            stats = monitor.get_stats()
-            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
-            frame_count = stats.get("frame_count", 0) if stats else 0
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Apply border if requested
-        if border:
-            from engine.display import render_border
-
-            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
-
-        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)
-
-        font_path = self._get_font_path()
-        font = None
-        if font_path:
-            try:
-                font = ImageFont.truetype(font_path, self.cell_height - 2)
-            except Exception:
-                font = None
-
-        if font is None:
-            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
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current dimensions.
-
-        Returns:
-            (width, height) in character cells
-        """
-        return (self.width, self.height)

engine/display/backends/terminal.py

@@ -1,126 +0,0 @@
-"""
-ANSI terminal display backend.
-"""
-
-import os
-import time
-
-
-class TerminalDisplay:
-    """ANSI terminal display backend.
-
-    Renders buffer to stdout using ANSI escape codes.
-    Supports reuse - when reuse=True, skips re-initializing terminal state.
-    Auto-detects terminal dimensions on init.
-    """
-
-    width: int = 80
-    height: int = 24
-    _initialized: bool = False
-
-    def __init__(self, target_fps: float = 30.0):
-        self.target_fps = target_fps
-        self._frame_period = 1.0 / target_fps if target_fps > 0 else 0
-        self._last_frame_time = 0.0
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        """Initialize display with dimensions.
-
-        If width/height are not provided (0/None), auto-detects terminal size.
-        Otherwise uses provided dimensions or falls back to terminal size
-        if the provided dimensions exceed terminal capacity.
-
-        Args:
-            width: Desired terminal width (0 = auto-detect)
-            height: Desired terminal height (0 = auto-detect)
-            reuse: If True, skip terminal re-initialization
-        """
-        from engine.terminal import CURSOR_OFF
-
-        # Auto-detect terminal size (handle case where no terminal)
-        try:
-            term_size = os.get_terminal_size()
-            term_width = term_size.columns
-            term_height = term_size.lines
-        except OSError:
-            # No terminal available (e.g., in tests)
-            term_width = width if width > 0 else 80
-            term_height = height if height > 0 else 24
-
-        # Use provided dimensions if valid, otherwise use terminal size
-        if width > 0 and height > 0:
-            self.width = min(width, term_width)
-            self.height = min(height, term_height)
-        else:
-            self.width = term_width
-            self.height = term_height
-
-        if not reuse or not self._initialized:
-            print(CURSOR_OFF, end="", flush=True)
-            self._initialized = True
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current terminal dimensions.
-
-        Returns:
-            (width, height) in character cells
-        """
-        try:
-            term_size = os.get_terminal_size()
-            return (term_size.columns, term_size.lines)
-        except OSError:
-            return (self.width, self.height)
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        import sys
-
-        from engine.display import get_monitor, render_border
-
-        t0 = time.perf_counter()
-
-        # FPS limiting - skip frame if we're going too fast
-        if self._frame_period > 0:
-            now = time.perf_counter()
-            elapsed = now - self._last_frame_time
-            if elapsed < self._frame_period:
-                # Skip this frame - too soon
-                return
-            self._last_frame_time = now
-
-        # Get metrics for border display
-        fps = 0.0
-        frame_time = 0.0
-        monitor = get_monitor()
-        if monitor:
-            stats = monitor.get_stats()
-            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
-            frame_count = stats.get("frame_count", 0) if stats else 0
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Apply border if requested
-        if border:
-            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
-
-        # Clear screen and home cursor before each frame
-        from engine.terminal import CLR
-
-        output = CLR + "".join(buffer)
-        sys.stdout.buffer.write(output.encode())
-        sys.stdout.flush()
-        elapsed_ms = (time.perf_counter() - t0) * 1000
-
-        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)

engine/display/backends/websocket.py

@@ -1,300 +0,0 @@
-"""
-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], border: bool = False) -> 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, reuse: bool = False) -> None:
-        """Initialize display with dimensions and start server.
-
-        Args:
-            width: Terminal width in characters
-            height: Terminal height in rows
-            reuse: If True, skip starting servers (assume already running)
-        """
-        self.width = width
-        self.height = height
-
-        if not reuse or not self._server_running:
-            self.start_server()
-            self.start_http_server()
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        """Broadcast buffer to all connected clients."""
-        t0 = time.perf_counter()
-
-        # Get metrics for border display
-        fps = 0.0
-        frame_time = 0.0
-        monitor = get_monitor()
-        if monitor:
-            stats = monitor.get_stats()
-            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
-            frame_count = stats.get("frame_count", 0) if stats else 0
-            if avg_ms and frame_count > 0:
-                fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-        # Apply border if requested
-        if border:
-            from engine.display import render_border
-
-            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
-
-        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
-
-    def get_dimensions(self) -> tuple[int, int]:
-        """Get current dimensions.
-
-        Returns:
-            (width, height) in character cells
-        """
-        return (self.width, self.height)

engine/display/renderer.py

@@ -1,280 +0,0 @@
-"""
-Shared display rendering utilities.
-
-Provides common functionality for displays that render text to images
-(Pygame, Sixel, Kitty displays).
-"""
-
-from typing import Any
-
-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),
-}
-
-
-def parse_ansi(
-    text: str,
-) -> list[tuple[str, tuple[int, int, int], tuple[int, int, int], bool]]:
-    """Parse ANSI escape sequences into text tokens with colors.
-
-    Args:
-        text: Text containing ANSI escape sequences
-
-    Returns:
-        List of (text, fg_rgb, bg_rgb, bold) tuples
-    """
-    tokens = []
-    current_text = ""
-    fg = (204, 204, 204)
-    bg = (0, 0, 0)
-    bold = False
-    i = 0
-
-    ANSI_COLORS_4BIT = {
-        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:
-                    if c == "0":
-                        fg = (204, 204, 204)
-                        bg = (0, 0, 0)
-                        bold = False
-                    elif c == "1":
-                        bold = True
-                    elif c == "22":
-                        bold = False
-                    elif c == "39":
-                        fg = (204, 204, 204)
-                    elif c == "49":
-                        bg = (0, 0, 0)
-                    elif c.isdigit():
-                        color_idx = int(c)
-                        if color_idx in ANSI_COLORS_4BIT:
-                            fg = ANSI_COLORS_4BIT[color_idx]
-                        elif 30 <= color_idx <= 37:
-                            fg = ANSI_COLORS_4BIT.get(color_idx - 30, fg)
-                        elif 40 <= color_idx <= 47:
-                            bg = ANSI_COLORS_4BIT.get(color_idx - 40, bg)
-                        elif 90 <= color_idx <= 97:
-                            fg = ANSI_COLORS_4BIT.get(color_idx - 90 + 8, fg)
-                        elif 100 <= color_idx <= 107:
-                            bg = ANSI_COLORS_4BIT.get(color_idx - 100 + 8, bg)
-                    elif c.startswith("38;5;"):
-                        idx = int(c.split(";")[-1])
-                        if idx < 256:
-                            if idx < 16:
-                                fg = ANSI_COLORS_4BIT.get(idx, fg)
-                            elif idx < 232:
-                                c_idx = idx - 16
-                                fg = (
-                                    (c_idx >> 4) * 51,
-                                    ((c_idx >> 2) & 7) * 51,
-                                    (c_idx & 3) * 85,
-                                )
-                            else:
-                                gray = (idx - 232) * 10 + 8
-                                fg = (gray, gray, gray)
-                    elif c.startswith("48;5;"):
-                        idx = int(c.split(";")[-1])
-                        if idx < 256:
-                            if idx < 16:
-                                bg = ANSI_COLORS_4BIT.get(idx, bg)
-                            elif idx < 232:
-                                c_idx = idx - 16
-                                bg = (
-                                    (c_idx >> 4) * 51,
-                                    ((c_idx >> 2) & 7) * 51,
-                                    (c_idx & 3) * 85,
-                                )
-                            else:
-                                gray = (idx - 232) * 10 + 8
-                                bg = (gray, gray, gray)
-            i += 1
-        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 get_default_font_path() -> str | None:
-    """Get the path to a default monospace font."""
-    import os
-    import sys
-    from pathlib import Path
-
-    def search_dir(base_path: str) -> str | None:
-        if not os.path.exists(base_path):
-            return None
-        if os.path.isfile(base_path):
-            return base_path
-        for font_file in Path(base_path).rglob("*"):
-            if font_file.suffix.lower() in (".ttf", ".otf", ".ttc"):
-                name = font_file.stem.lower()
-                if "geist" in name and ("nerd" in name or "mono" in name):
-                    return str(font_file)
-                if "mono" in name or "courier" in name or "terminal" in name:
-                    return str(font_file)
-        return None
-
-    search_dirs = []
-    if sys.platform == "darwin":
-        search_dirs.extend(
-            [
-                os.path.expanduser("~/Library/Fonts/"),
-                "/System/Library/Fonts/",
-            ]
-        )
-    elif sys.platform == "win32":
-        search_dirs.extend(
-            [
-                os.path.expanduser("~\\AppData\\Local\\Microsoft\\Windows\\Fonts\\"),
-                "C:\\Windows\\Fonts\\",
-            ]
-        )
-    else:
-        search_dirs.extend(
-            [
-                os.path.expanduser("~/.local/share/fonts/"),
-                os.path.expanduser("~/.fonts/"),
-                "/usr/share/fonts/",
-            ]
-        )
-
-    for search_dir_path in search_dirs:
-        found = search_dir(search_dir_path)
-        if found:
-            return found
-
-    if sys.platform != "win32":
-        try:
-            import subprocess
-
-            for pattern in ["monospace", "DejaVuSansMono", "LiberationMono"]:
-                result = subprocess.run(
-                    ["fc-match", "-f", "%{file}", pattern],
-                    capture_output=True,
-                    text=True,
-                    timeout=5,
-                )
-                if result.returncode == 0 and result.stdout.strip():
-                    font_file = result.stdout.strip()
-                    if os.path.exists(font_file):
-                        return font_file
-        except Exception:
-            pass
-
-    return None
-
-
-def render_to_pil(
-    buffer: list[str],
-    width: int,
-    height: int,
-    cell_width: int = 10,
-    cell_height: int = 18,
-    font_path: str | None = None,
-) -> Any:
-    """Render buffer to a PIL Image.
-
-    Args:
-        buffer: List of text lines to render
-        width: Terminal width in characters
-        height: Terminal height in rows
-        cell_width: Width of each character cell in pixels
-        cell_height: Height of each character cell in pixels
-        font_path: Path to TTF/OTF font file (optional)
-
-    Returns:
-        PIL Image object
-    """
-    from PIL import Image, ImageDraw, ImageFont
-
-    img_width = width * cell_width
-    img_height = height * cell_height
-
-    img = Image.new("RGBA", (img_width, img_height), (0, 0, 0, 255))
-    draw = ImageDraw.Draw(img)
-
-    if font_path:
-        try:
-            font = ImageFont.truetype(font_path, cell_height - 2)
-        except Exception:
-            font = ImageFont.load_default()
-    else:
-        font = ImageFont.load_default()
-
-    for row_idx, line in enumerate(buffer[:height]):
-        if row_idx >= height:
-            break
-
-        tokens = parse_ansi(line)
-        x_pos = 0
-        y_pos = row_idx * 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))
-
-            draw.text((x_pos, y_pos), text, fill=(*fg, 255), font=font)
-
-            if font:
-                x_pos += draw.textlength(text, font=font)
-
-    return img

engine/effects/__init__.py

@@ -6,17 +6,18 @@ from engine.effects.legacy import (
     glitch_bar,
     next_headline,
     noise,
-    vis_offset,
     vis_trunc,
 )
 from engine.effects.performance import PerformanceMonitor, get_monitor, set_monitor
 from engine.effects.registry import EffectRegistry, get_registry, set_registry
-from engine.effects.types import (
-    EffectConfig,
-    EffectContext,
-    PipelineConfig,
-    create_effect_context,
-)
+from engine.effects.types import EffectConfig, EffectContext, PipelineConfig
+
+
+def get_effect_chain():
+    from engine.layers import get_effect_chain as _chain
+
+    return _chain()
+
 
 __all__ = [
     "EffectChain",
@@ -24,9 +25,9 @@ __all__ = [
     "EffectConfig",
     "EffectContext",
     "PipelineConfig",
-    "create_effect_context",
     "get_registry",
     "set_registry",
+    "get_effect_chain",
     "get_monitor",
     "set_monitor",
     "PerformanceMonitor",
@@ -38,5 +39,4 @@ __all__ = [
     "noise",
     "next_headline",
     "vis_trunc",
-    "vis_offset",
 ]

engine/effects/chain.py

@@ -2,7 +2,7 @@ import time
 
 from engine.effects.performance import PerformanceMonitor, get_monitor
 from engine.effects.registry import EffectRegistry
-from engine.effects.types import EffectContext, PartialUpdate
+from engine.effects.types import EffectContext
 
 
 class EffectChain:
@@ -51,18 +51,6 @@ class EffectChain:
         frame_number = ctx.frame_number
         monitor.start_frame(frame_number)
 
-        # Get dirty regions from canvas via context (set by CanvasStage)
-        dirty_rows = ctx.get_state("canvas.dirty_rows")
-
-        # Create PartialUpdate for effects that support it
-        full_buffer = dirty_rows is None or len(dirty_rows) == 0
-        partial = PartialUpdate(
-            rows=None,
-            cols=None,
-            dirty=dirty_rows,
-            full_buffer=full_buffer,
-        )
-
         frame_start = time.perf_counter()
         result = list(buf)
         for name in self._order:
@@ -71,11 +59,7 @@ class EffectChain:
                 chars_in = sum(len(line) for line in result)
                 effect_start = time.perf_counter()
                 try:
-                    # Use process_partial if supported, otherwise fall back to process
-                    if getattr(plugin, "supports_partial_updates", False):
-                        result = plugin.process_partial(result, ctx, partial)
-                    else:
-                        result = plugin.process(result, ctx)
+                    result = plugin.process(result, ctx)
                 except Exception:
                     plugin.config.enabled = False
                 elapsed = time.perf_counter() - effect_start

engine/effects/controller.py

@@ -6,7 +6,14 @@ _effect_chain_ref = None
 
 def _get_effect_chain():
     global _effect_chain_ref
-    return _effect_chain_ref
+    if _effect_chain_ref is not None:
+        return _effect_chain_ref
+    try:
+        from engine.layers import get_effect_chain as _chain
+
+        return _chain()
+    except Exception:
+        return None
 
 
 def set_effect_chain_ref(chain) -> None:

engine/effects/legacy.py

@@ -1,14 +1,6 @@
 """
 Visual effects: noise, glitch, fade, ANSI-aware truncation, firehose, headline pool.
 Depends on: config, terminal, sources.
-
-These are low-level functional implementations of visual effects. They are used
-internally by the EffectPlugin system (effects_plugins/*.py) and also directly
-by layers.py and scroll.py for rendering.
-
-The plugin system provides a higher-level OOP interface with configuration
-support, while these legacy functions provide direct functional access.
-Both systems coexist - there are no current plans to deprecate the legacy functions.
 """
 
 import random
@@ -82,37 +74,6 @@ def vis_trunc(s, w):
     return "".join(result)
 
 
-def vis_offset(s, offset):
-    """Offset string by skipping first offset visual characters, skipping ANSI escape codes."""
-    if offset <= 0:
-        return s
-    result = []
-    vw = 0
-    i = 0
-    skipping = True
-    while i < len(s):
-        if s[i] == "\033" and i + 1 < len(s) and s[i + 1] == "[":
-            j = i + 2
-            while j < len(s) and not s[j].isalpha():
-                j += 1
-            if skipping:
-                i = j + 1
-                continue
-            result.append(s[i : j + 1])
-            i = j + 1
-        else:
-            if skipping:
-                if vw >= offset:
-                    skipping = False
-                    result.append(s[i])
-                vw += 1
-                i += 1
-            else:
-                result.append(s[i])
-                i += 1
-    return "".join(result)
-
-
 def next_headline(pool, items, seen):
     """Pull the next unique headline from pool, refilling as needed."""
     while True:

engine/effects/types.py

@@ -1,79 +1,18 @@
-"""
-Visual effects type definitions and base classes.
-
-EffectPlugin Architecture:
-- Uses ABC (Abstract Base Class) for interface enforcement
-- Runtime discovery via directory scanning (effects_plugins/)
-- Configuration via EffectConfig dataclass
-- Context passed through EffectContext dataclass
-
-Plugin System Research (see AGENTS.md for references):
-- VST: Standardized audio interfaces, chaining, presets (FXP/FXB)
-- Python Entry Points: Namespace packages, importlib.metadata discovery
-- Shadertoy: Shader-based with uniforms as context
-
-Current gaps vs industry patterns:
-- No preset save/load system
-- No external plugin distribution via entry points
-- No plugin metadata (version, author, description)
-"""
-
-from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any
 
 
-@dataclass
-class PartialUpdate:
-    """Represents a partial buffer update for optimized rendering.
-
-    Instead of processing the full buffer every frame, effects that support
-    partial updates can process only changed regions.
-
-    Attributes:
-        rows: Row indices that changed (None = all rows)
-        cols: Column range that changed (None = full width)
-        dirty: Set of dirty row indices
-    """
-
-    rows: tuple[int, int] | None = None  # (start, end) inclusive
-    cols: tuple[int, int] | None = None  # (start, end) inclusive
-    dirty: set[int] | None = None  # Set of dirty row indices
-    full_buffer: bool = True  # If True, process entire buffer
-
-
 @dataclass
 class EffectContext:
     terminal_width: int
     terminal_height: int
     scroll_cam: int
     ticker_height: int
-    camera_x: int = 0
-    mic_excess: float = 0.0
-    grad_offset: float = 0.0
-    frame_number: int = 0
-    has_message: bool = False
+    mic_excess: float
+    grad_offset: float
+    frame_number: int
+    has_message: bool
     items: list = field(default_factory=list)
-    _state: dict[str, Any] = field(default_factory=dict, repr=False)
-
-    def get_sensor_value(self, sensor_name: str) -> float | None:
-        """Get a sensor value from context state.
-
-        Args:
-            sensor_name: Name of the sensor (e.g., "mic", "camera")
-
-        Returns:
-            Sensor value as float, or None if not available.
-        """
-        return self._state.get(f"sensor.{sensor_name}")
-
-    def set_state(self, key: str, value: Any) -> None:
-        """Set a state value in the context."""
-        self._state[key] = value
-
-    def get_state(self, key: str, default: Any = None) -> Any:
-        """Get a state value from the context."""
-        return self._state.get(key, default)
 
 
 @dataclass
@@ -83,168 +22,18 @@ class EffectConfig:
     params: dict[str, Any] = field(default_factory=dict)
 
 
-class EffectPlugin(ABC):
-    """Abstract base class for effect plugins.
-
-    Subclasses must define:
-    - name: str - unique identifier for the effect
-    - config: EffectConfig - current configuration
-
-    Optional class attribute:
-    - param_bindings: dict - Declarative sensor-to-param bindings
-        Example:
-            param_bindings = {
-                "intensity": {"sensor": "mic", "transform": "linear"},
-                "rate": {"sensor": "mic", "transform": "exponential"},
-            }
-
-    And implement:
-    - process(buf, ctx) -> list[str]
-    - configure(config) -> None
-
-    Effect Behavior with ticker_height=0:
-    - NoiseEffect: Returns buffer unchanged (no ticker to apply noise to)
-    - FadeEffect: Returns buffer unchanged (no ticker to fade)
-    - GlitchEffect: Processes normally (doesn't depend on ticker_height)
-    - FirehoseEffect: Returns buffer unchanged if no items in context
-
-    Effects should handle missing or zero context values gracefully by
-    returning the input buffer unchanged rather than raising errors.
-
-    The param_bindings system enables PureData-style signal routing:
-    - Sensors emit values that effects can bind to
-    - Transform functions map sensor values to param ranges
-    - Effects read bound values from context.state["sensor.{name}"]
-    """
-
+class EffectPlugin:
     name: str
     config: EffectConfig
-    param_bindings: dict[str, dict[str, str | float]] = {}
-    supports_partial_updates: bool = False  # Override in subclasses for optimization
 
-    @abstractmethod
     def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        """Process the buffer with this effect applied.
+        raise NotImplementedError
 
-        Args:
-            buf: List of lines to process
-            ctx: Effect context with terminal state
-
-        Returns:
-            Processed buffer (may be same object or new list)
-        """
-        ...
-
-    def process_partial(
-        self, buf: list[str], ctx: EffectContext, partial: PartialUpdate
-    ) -> list[str]:
-        """Process a partial buffer for optimized rendering.
-
-        Override this in subclasses that support partial updates for performance.
-        Default implementation falls back to full buffer processing.
-
-        Args:
-            buf: List of lines to process
-            ctx: Effect context with terminal state
-            partial: PartialUpdate indicating which regions changed
-
-        Returns:
-            Processed buffer (may be same object or new list)
-        """
-        # Default: fall back to full processing
-        return self.process(buf, ctx)
-
-    @abstractmethod
     def configure(self, config: EffectConfig) -> None:
-        """Configure the effect with new settings.
-
-        Args:
-            config: New configuration to apply
-        """
-        ...
-
-
-def create_effect_context(
-    terminal_width: int = 80,
-    terminal_height: int = 24,
-    scroll_cam: int = 0,
-    ticker_height: 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,
-        mic_excess=mic_excess,
-        grad_offset=grad_offset,
-        frame_number=frame_number,
-        has_message=has_message,
-        items=items or [],
-    )
+        raise NotImplementedError
 
 
 @dataclass
 class PipelineConfig:
     order: list[str] = field(default_factory=list)
     effects: dict[str, EffectConfig] = field(default_factory=dict)
-
-
-def apply_param_bindings(
-    effect: "EffectPlugin",
-    ctx: EffectContext,
-) -> EffectConfig:
-    """Apply sensor bindings to effect config.
-
-    This resolves param_bindings declarations by reading sensor values
-    from the context and applying transform functions.
-
-    Args:
-        effect: The effect with param_bindings to apply
-        ctx: EffectContext containing sensor values
-
-    Returns:
-        Modified EffectConfig with sensor-driven values applied.
-    """
-    import copy
-
-    if not effect.param_bindings:
-        return effect.config
-
-    config = copy.deepcopy(effect.config)
-
-    for param_name, binding in effect.param_bindings.items():
-        sensor_name: str = binding.get("sensor", "")
-        transform: str = binding.get("transform", "linear")
-
-        if not sensor_name:
-            continue
-
-        sensor_value = ctx.get_sensor_value(sensor_name)
-        if sensor_value is None:
-            continue
-
-        if transform == "linear":
-            applied_value: float = sensor_value
-        elif transform == "exponential":
-            applied_value = sensor_value**2
-        elif transform == "threshold":
-            threshold = float(binding.get("threshold", 0.5))
-            applied_value = 1.0 if sensor_value > threshold else 0.0
-        elif transform == "inverse":
-            applied_value = 1.0 - sensor_value
-        else:
-            applied_value = sensor_value
-
-        config.params[f"{param_name}_sensor"] = applied_value
-
-        if param_name == "intensity":
-            base_intensity = effect.config.intensity
-            config.intensity = base_intensity * (0.5 + applied_value * 0.5)
-
-    return config

engine/emitters.py

@@ -0,0 +1,25 @@
+"""
+Event emitter protocols - abstract interfaces for event-producing components.
+"""
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class EventEmitter(Protocol):
+    """Protocol for components that emit events."""
+
+    def subscribe(self, callback: Callable[[Any], None]) -> None: ...
+    def unsubscribe(self, callback: Callable[[Any], None]) -> None: ...
+
+
+class Startable(Protocol):
+    """Protocol for components that can be started."""
+
+    def start(self) -> Any: ...
+
+
+class Stoppable(Protocol):
+    """Protocol for components that can be stopped."""
+
+    def stop(self) -> None: ...

engine/layers.py

@@ -0,0 +1,260 @@
+"""
+Layer compositing — message overlay, ticker zone, firehose, noise.
+Depends on: config, render, effects.
+"""
+
+import random
+import re
+import time
+from datetime import datetime
+
+from engine import config
+from engine.effects import (
+    EffectChain,
+    EffectContext,
+    fade_line,
+    firehose_line,
+    glitch_bar,
+    noise,
+    vis_trunc,
+)
+from engine.render import big_wrap, lr_gradient, lr_gradient_opposite
+from engine.terminal import RST, W_COOL
+
+MSG_META = "\033[38;5;245m"
+MSG_BORDER = "\033[2;38;5;37m"
+
+
+def render_message_overlay(
+    msg: tuple[str, str, float] | None,
+    w: int,
+    h: int,
+    msg_cache: tuple,
+) -> tuple[list[str], tuple]:
+    """Render ntfy message overlay.
+
+    Args:
+        msg: (title, body, timestamp) or None
+        w: terminal width
+        h: terminal height
+        msg_cache: (cache_key, rendered_rows) for caching
+
+    Returns:
+        (list of ANSI strings, updated cache)
+    """
+    overlay = []
+    if msg is None:
+        return overlay, msg_cache
+
+    m_title, m_body, m_ts = msg
+    display_text = m_body or m_title or "(empty)"
+    display_text = re.sub(r"\s+", " ", display_text.upper())
+
+    cache_key = (display_text, w)
+    if msg_cache[0] != cache_key:
+        msg_rows = big_wrap(display_text, w - 4)
+        msg_cache = (cache_key, msg_rows)
+    else:
+        msg_rows = msg_cache[1]
+
+    msg_rows = lr_gradient_opposite(
+        msg_rows, (time.monotonic() * config.GRAD_SPEED) % 1.0
+    )
+
+    elapsed_s = int(time.monotonic() - m_ts)
+    remaining = max(0, config.MESSAGE_DISPLAY_SECS - elapsed_s)
+    ts_str = datetime.now().strftime("%H:%M:%S")
+    panel_h = len(msg_rows) + 2
+    panel_top = max(0, (h - panel_h) // 2)
+
+    row_idx = 0
+    for mr in msg_rows:
+        ln = vis_trunc(mr, w)
+        overlay.append(f"\033[{panel_top + row_idx + 1};1H  {ln}\033[0m\033[K")
+        row_idx += 1
+
+    meta_parts = []
+    if m_title and m_title != m_body:
+        meta_parts.append(m_title)
+    meta_parts.append(f"ntfy \u00b7 {ts_str} \u00b7 {remaining}s")
+    meta = (
+        "  " + " \u00b7 ".join(meta_parts)
+        if len(meta_parts) > 1
+        else "  " + meta_parts[0]
+    )
+    overlay.append(f"\033[{panel_top + row_idx + 1};1H{MSG_META}{meta}\033[0m\033[K")
+    row_idx += 1
+
+    bar = "\u2500" * (w - 4)
+    overlay.append(f"\033[{panel_top + row_idx + 1};1H  {MSG_BORDER}{bar}\033[0m\033[K")
+
+    return overlay, msg_cache
+
+
+def render_ticker_zone(
+    active: list,
+    scroll_cam: int,
+    ticker_h: int,
+    w: int,
+    noise_cache: dict,
+    grad_offset: float,
+) -> tuple[list[str], dict]:
+    """Render the ticker scroll zone.
+
+    Args:
+        active: list of (content_rows, color, canvas_y, meta_idx)
+        scroll_cam: camera position (viewport top)
+        ticker_h: height of ticker zone
+        w: terminal width
+        noise_cache: dict of cy -> noise string
+        grad_offset: gradient animation offset
+
+    Returns:
+        (list of ANSI strings, updated noise_cache)
+    """
+    buf = []
+    top_zone = max(1, int(ticker_h * 0.25))
+    bot_zone = max(1, int(ticker_h * 0.10))
+
+    def noise_at(cy):
+        if cy not in noise_cache:
+            noise_cache[cy] = noise(w) if random.random() < 0.15 else None
+        return noise_cache[cy]
+
+    for r in range(ticker_h):
+        scr_row = r + 1
+        cy = scroll_cam + r
+        top_f = min(1.0, r / top_zone) if top_zone > 0 else 1.0
+        bot_f = min(1.0, (ticker_h - 1 - r) / bot_zone) if bot_zone > 0 else 1.0
+        row_fade = min(top_f, bot_f)
+        drawn = False
+
+        for content, hc, by, midx in active:
+            cr = cy - by
+            if 0 <= cr < len(content):
+                raw = content[cr]
+                if cr != midx:
+                    colored = lr_gradient([raw], grad_offset)[0]
+                else:
+                    colored = raw
+                ln = vis_trunc(colored, w)
+                if row_fade < 1.0:
+                    ln = fade_line(ln, row_fade)
+
+                if cr == midx:
+                    buf.append(f"\033[{scr_row};1H{W_COOL}{ln}{RST}\033[K")
+                elif ln.strip():
+                    buf.append(f"\033[{scr_row};1H{ln}{RST}\033[K")
+                else:
+                    buf.append(f"\033[{scr_row};1H\033[K")
+                drawn = True
+                break
+
+        if not drawn:
+            n = noise_at(cy)
+            if row_fade < 1.0 and n:
+                n = fade_line(n, row_fade)
+            if n:
+                buf.append(f"\033[{scr_row};1H{n}")
+            else:
+                buf.append(f"\033[{scr_row};1H\033[K")
+
+    return buf, noise_cache
+
+
+def apply_glitch(
+    buf: list[str],
+    ticker_buf_start: int,
+    mic_excess: float,
+    w: int,
+) -> list[str]:
+    """Apply glitch effect to ticker buffer.
+
+    Args:
+        buf: current buffer
+        ticker_buf_start: index where ticker starts in buffer
+        mic_excess: mic level above threshold
+        w: terminal width
+
+    Returns:
+        Updated buffer with glitches applied
+    """
+    glitch_prob = 0.32 + min(0.9, mic_excess * 0.16)
+    n_hits = 4 + int(mic_excess / 2)
+    ticker_buf_len = len(buf) - ticker_buf_start
+
+    if random.random() < glitch_prob and ticker_buf_len > 0:
+        for _ in range(min(n_hits, ticker_buf_len)):
+            gi = random.randint(0, ticker_buf_len - 1)
+            scr_row = gi + 1
+            buf[ticker_buf_start + gi] = f"\033[{scr_row};1H{glitch_bar(w)}"
+
+    return buf
+
+
+def render_firehose(items: list, w: int, fh: int, h: int) -> list[str]:
+    """Render firehose strip at bottom of screen."""
+    buf = []
+    if fh > 0:
+        for fr in range(fh):
+            scr_row = h - fh + fr + 1
+            fline = firehose_line(items, w)
+            buf.append(f"\033[{scr_row};1H{fline}\033[K")
+    return buf
+
+
+_effect_chain = None
+
+
+def init_effects() -> None:
+    """Initialize effect plugins and chain."""
+    global _effect_chain
+    from engine.effects import EffectChain, get_registry
+
+    registry = get_registry()
+
+    import effects_plugins
+
+    effects_plugins.discover_plugins()
+
+    chain = EffectChain(registry)
+    chain.set_order(["noise", "fade", "glitch", "firehose"])
+    _effect_chain = chain
+
+
+def process_effects(
+    buf: list[str],
+    w: int,
+    h: int,
+    scroll_cam: int,
+    ticker_h: int,
+    mic_excess: float,
+    grad_offset: float,
+    frame_number: int,
+    has_message: bool,
+    items: list,
+) -> list[str]:
+    """Process buffer through effect chain."""
+    if _effect_chain is None:
+        init_effects()
+
+    ctx = EffectContext(
+        terminal_width=w,
+        terminal_height=h,
+        scroll_cam=scroll_cam,
+        ticker_height=ticker_h,
+        mic_excess=mic_excess,
+        grad_offset=grad_offset,
+        frame_number=frame_number,
+        has_message=has_message,
+        items=items,
+    )
+    return _effect_chain.process(buf, ctx)
+
+
+def get_effect_chain() -> EffectChain | None:
+    """Get the effect chain instance."""
+    global _effect_chain
+    if _effect_chain is None:
+        init_effects()
+    return _effect_chain

engine/mic.py

@@ -0,0 +1,96 @@
+"""
+Microphone input monitor — standalone, no internal dependencies.
+Gracefully degrades if sounddevice/numpy are unavailable.
+"""
+
+import atexit
+from collections.abc import Callable
+from datetime import datetime
+
+try:
+    import numpy as _np
+    import sounddevice as _sd
+
+    _HAS_MIC = True
+except Exception:
+    _HAS_MIC = False
+
+
+from engine.events import MicLevelEvent
+
+
+class MicMonitor:
+    """Background mic stream that exposes current RMS dB level."""
+
+    def __init__(self, threshold_db=50):
+        self.threshold_db = threshold_db
+        self._db = -99.0
+        self._stream = None
+        self._subscribers: list[Callable[[MicLevelEvent], None]] = []
+
+    @property
+    def available(self):
+        """True if sounddevice is importable."""
+        return _HAS_MIC
+
+    @property
+    def db(self):
+        """Current RMS dB level."""
+        return self._db
+
+    @property
+    def excess(self):
+        """dB above threshold (clamped to 0)."""
+        return max(0.0, self._db - self.threshold_db)
+
+    def subscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
+        """Register a callback to be called when mic level changes."""
+        self._subscribers.append(callback)
+
+    def unsubscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
+        """Remove a registered callback."""
+        if callback in self._subscribers:
+            self._subscribers.remove(callback)
+
+    def _emit(self, event: MicLevelEvent) -> None:
+        """Emit an event to all subscribers."""
+        for cb in self._subscribers:
+            try:
+                cb(event)
+            except Exception:
+                pass
+
+    def start(self):
+        """Start background mic stream. Returns True on success, False/None otherwise."""
+        if not _HAS_MIC:
+            return None
+
+        def _cb(indata, frames, t, status):
+            rms = float(_np.sqrt(_np.mean(indata**2)))
+            self._db = 20 * _np.log10(rms) if rms > 0 else -99.0
+            if self._subscribers:
+                event = MicLevelEvent(
+                    db_level=self._db,
+                    excess_above_threshold=max(0.0, self._db - self.threshold_db),
+                    timestamp=datetime.now(),
+                )
+                self._emit(event)
+
+        try:
+            self._stream = _sd.InputStream(
+                callback=_cb, channels=1, samplerate=44100, blocksize=2048
+            )
+            self._stream.start()
+            atexit.register(self.stop)
+            return True
+        except Exception:
+            return False
+
+    def stop(self):
+        """Stop the mic stream if running."""
+        if self._stream:
+            try:
+                self._stream.stop()
+            except Exception:
+                pass
+            self._stream = None

engine/pipeline/__init__.py

@@ -1,107 +0,0 @@
-"""
-Unified Pipeline Architecture.
-
-This module provides a clean, dependency-managed pipeline system:
-- Stage: Base class for all pipeline components
-- Pipeline: DAG-based execution orchestrator
-- PipelineParams: Runtime configuration for animation
-- PipelinePreset: Pre-configured pipeline configurations
-- StageRegistry: Unified registration for all stage types
-
-The pipeline architecture supports:
-- Sources: Data providers (headlines, poetry, pipeline viz)
-- Effects: Post-processors (noise, fade, glitch, hud)
-- Displays: Output backends (terminal, pygame, websocket)
-- Cameras: Viewport controllers (vertical, horizontal, omni)
-
-Example:
-    from engine.pipeline import Pipeline, PipelineConfig, StageRegistry
-
-    pipeline = Pipeline(PipelineConfig(source="headlines", display="terminal"))
-    pipeline.add_stage("source", StageRegistry.create("source", "headlines"))
-    pipeline.add_stage("display", StageRegistry.create("display", "terminal"))
-    pipeline.build().initialize()
-
-    result = pipeline.execute(initial_data)
-"""
-
-from engine.pipeline.controller import (
-    Pipeline,
-    PipelineConfig,
-    PipelineRunner,
-    create_default_pipeline,
-    create_pipeline_from_params,
-)
-from engine.pipeline.core import (
-    PipelineContext,
-    Stage,
-    StageConfig,
-    StageError,
-    StageResult,
-)
-from engine.pipeline.params import (
-    DEFAULT_HEADLINE_PARAMS,
-    DEFAULT_PIPELINE_PARAMS,
-    DEFAULT_PYGAME_PARAMS,
-    PipelineParams,
-)
-from engine.pipeline.presets import (
-    DEMO_PRESET,
-    FIREHOSE_PRESET,
-    PIPELINE_VIZ_PRESET,
-    POETRY_PRESET,
-    PRESETS,
-    SIXEL_PRESET,
-    WEBSOCKET_PRESET,
-    PipelinePreset,
-    create_preset_from_params,
-    get_preset,
-    list_presets,
-)
-from engine.pipeline.registry import (
-    StageRegistry,
-    discover_stages,
-    register_camera,
-    register_display,
-    register_effect,
-    register_source,
-)
-
-__all__ = [
-    # Core
-    "Stage",
-    "StageConfig",
-    "StageError",
-    "StageResult",
-    "PipelineContext",
-    # Controller
-    "Pipeline",
-    "PipelineConfig",
-    "PipelineRunner",
-    "create_default_pipeline",
-    "create_pipeline_from_params",
-    # Params
-    "PipelineParams",
-    "DEFAULT_HEADLINE_PARAMS",
-    "DEFAULT_PIPELINE_PARAMS",
-    "DEFAULT_PYGAME_PARAMS",
-    # Presets
-    "PipelinePreset",
-    "PRESETS",
-    "DEMO_PRESET",
-    "POETRY_PRESET",
-    "PIPELINE_VIZ_PRESET",
-    "WEBSOCKET_PRESET",
-    "SIXEL_PRESET",
-    "FIREHOSE_PRESET",
-    "get_preset",
-    "list_presets",
-    "create_preset_from_params",
-    # Registry
-    "StageRegistry",
-    "discover_stages",
-    "register_source",
-    "register_effect",
-    "register_display",
-    "register_camera",
-]

engine/pipeline/adapters.py

@@ -1,840 +0,0 @@
-"""
-Stage adapters - Bridge existing components to the Stage interface.
-
-This module provides adapters that wrap existing components
-(EffectPlugin, Display, DataSource, Camera) as Stage implementations.
-"""
-
-from typing import Any
-
-from engine.pipeline.core import PipelineContext, Stage
-
-
-class EffectPluginStage(Stage):
-    """Adapter wrapping EffectPlugin as a Stage."""
-
-    def __init__(self, effect_plugin, name: str = "effect"):
-        self._effect = effect_plugin
-        self.name = name
-        self.category = "effect"
-        self.optional = False
-
-    @property
-    def stage_type(self) -> str:
-        """Return stage_type based on effect name.
-
-        HUD effects are overlays.
-        """
-        if self.name == "hud":
-            return "overlay"
-        return self.category
-
-    @property
-    def render_order(self) -> int:
-        """Return render_order based on effect type.
-
-        HUD effects have high render_order to appear on top.
-        """
-        if self.name == "hud":
-            return 100  # High order for overlays
-        return 0
-
-    @property
-    def is_overlay(self) -> bool:
-        """Return True for HUD effects.
-
-        HUD is an overlay - it composes on top of the buffer
-        rather than transforming it for the next stage.
-        """
-        return self.name == "hud"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"effect.{self.name}"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return set()
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Process data through the effect."""
-        if data is None:
-            return None
-        from engine.effects.types import EffectContext, apply_param_bindings
-
-        w = ctx.params.viewport_width if ctx.params else 80
-        h = ctx.params.viewport_height if ctx.params else 24
-        frame = ctx.params.frame_number if ctx.params else 0
-
-        effect_ctx = EffectContext(
-            terminal_width=w,
-            terminal_height=h,
-            scroll_cam=0,
-            ticker_height=h,
-            camera_x=0,
-            mic_excess=0.0,
-            grad_offset=(frame * 0.01) % 1.0,
-            frame_number=frame,
-            has_message=False,
-            items=ctx.get("items", []),
-        )
-
-        # Copy sensor state from PipelineContext to EffectContext
-        for key, value in ctx.state.items():
-            if key.startswith("sensor."):
-                effect_ctx.set_state(key, value)
-
-        # Copy metrics from PipelineContext to EffectContext
-        if "metrics" in ctx.state:
-            effect_ctx.set_state("metrics", ctx.state["metrics"])
-
-        # Apply sensor param bindings if effect has them
-        if hasattr(self._effect, "param_bindings") and self._effect.param_bindings:
-            bound_config = apply_param_bindings(self._effect, effect_ctx)
-            self._effect.configure(bound_config)
-
-        return self._effect.process(data, effect_ctx)
-
-
-class DisplayStage(Stage):
-    """Adapter wrapping Display as a Stage."""
-
-    def __init__(self, display, name: str = "terminal"):
-        self._display = display
-        self.name = name
-        self.category = "display"
-        self.optional = False
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {"display.output"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"render.output"}  # Display needs rendered content
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}  # Display consumes rendered text
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.NONE}  # Display is a terminal stage (no output)
-
-    def init(self, ctx: PipelineContext) -> bool:
-        w = ctx.params.viewport_width if ctx.params else 80
-        h = ctx.params.viewport_height if ctx.params else 24
-        result = self._display.init(w, h, reuse=False)
-        return result is not False
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Output data to display."""
-        if data is not None:
-            self._display.show(data)
-        return data
-
-    def cleanup(self) -> None:
-        self._display.cleanup()
-
-
-class DataSourceStage(Stage):
-    """Adapter wrapping DataSource as a Stage."""
-
-    def __init__(self, data_source, name: str = "headlines"):
-        self._source = data_source
-        self.name = name
-        self.category = "source"
-        self.optional = False
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"source.{self.name}"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return set()
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.NONE}  # Sources don't take input
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Fetch data from source."""
-        if hasattr(self._source, "get_items"):
-            return self._source.get_items()
-        return data
-
-
-class PassthroughStage(Stage):
-    """Simple stage that passes data through unchanged.
-
-    Used for sources that already provide the data in the correct format
-    (e.g., pipeline introspection that outputs text directly).
-    """
-
-    def __init__(self, name: str = "passthrough"):
-        self.name = name
-        self.category = "render"
-        self.optional = True
-
-    @property
-    def stage_type(self) -> str:
-        return "render"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {"render.output"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"source"}
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Pass data through unchanged."""
-        return data
-
-
-class SourceItemsToBufferStage(Stage):
-    """Convert SourceItem objects to text buffer.
-
-    Takes a list of SourceItem objects and extracts their content,
-    splitting on newlines to create a proper text buffer for display.
-    """
-
-    def __init__(self, name: str = "items-to-buffer"):
-        self.name = name
-        self.category = "render"
-        self.optional = True
-
-    @property
-    def stage_type(self) -> str:
-        return "render"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {"render.output"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"source"}
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Convert SourceItem list to text buffer."""
-        if data is None:
-            return []
-
-        # If already a list of strings, return as-is
-        if isinstance(data, list) and data and isinstance(data[0], str):
-            return data
-
-        # If it's a list of SourceItem, extract content
-        from engine.data_sources import SourceItem
-
-        if isinstance(data, list):
-            result = []
-            for item in data:
-                if isinstance(item, SourceItem):
-                    # Split content by newline to get individual lines
-                    lines = item.content.split("\n")
-                    result.extend(lines)
-                elif hasattr(item, "content"):  # Has content attribute
-                    lines = str(item.content).split("\n")
-                    result.extend(lines)
-                else:
-                    result.append(str(item))
-            return result
-
-        # Single item
-        if isinstance(data, SourceItem):
-            return data.content.split("\n")
-
-        return [str(data)]
-
-
-class CameraStage(Stage):
-    """Adapter wrapping Camera as a Stage."""
-
-    def __init__(self, camera, name: str = "vertical"):
-        self._camera = camera
-        self.name = name
-        self.category = "camera"
-        self.optional = True
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {"camera"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"render.output"}  # Depend on rendered output from font or render stage
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}  # Camera works on rendered text
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Apply camera transformation to data."""
-        if data is None:
-            return None
-        if hasattr(self._camera, "apply"):
-            viewport_width = ctx.params.viewport_width if ctx.params else 80
-            viewport_height = ctx.params.viewport_height if ctx.params else 24
-            buffer_height = len(data) if isinstance(data, list) else 0
-
-            # Get global layout height for canvas (enables full scrolling range)
-            total_layout_height = ctx.get("total_layout_height", buffer_height)
-
-            # Preserve camera's configured canvas width, but ensure it's at least viewport_width
-            # This allows horizontal/omni/floating/bounce cameras to scroll properly
-            canvas_width = max(
-                viewport_width, getattr(self._camera, "canvas_width", viewport_width)
-            )
-
-            # Update camera's viewport dimensions so it knows its actual bounds
-            if hasattr(self._camera, "viewport_width"):
-                self._camera.viewport_width = viewport_width
-                self._camera.viewport_height = viewport_height
-
-            # Set canvas to full layout height so camera can scroll through all content
-            self._camera.set_canvas_size(width=canvas_width, height=total_layout_height)
-
-            # Update camera position (scroll) - uses global canvas for clamping
-            if hasattr(self._camera, "update"):
-                self._camera.update(1 / 60)
-
-            # Store camera_y in context for ViewportFilterStage (global y position)
-            ctx.set("camera_y", self._camera.y)
-
-            # Apply camera viewport slicing to the partial buffer
-            # The buffer starts at render_offset_y in global coordinates
-            render_offset_y = ctx.get("render_offset_y", 0)
-
-            # Temporarily shift camera to local buffer coordinates for apply()
-            real_y = self._camera.y
-            local_y = max(0, real_y - render_offset_y)
-
-            # Temporarily shrink canvas to local buffer size so apply() works correctly
-            self._camera.set_canvas_size(width=canvas_width, height=buffer_height)
-            self._camera.y = local_y
-
-            # Apply slicing
-            result = self._camera.apply(data, viewport_width, viewport_height)
-
-            # Restore global canvas and camera position for next frame
-            self._camera.set_canvas_size(width=canvas_width, height=total_layout_height)
-            self._camera.y = real_y
-
-            return result
-        return data
-
-    def cleanup(self) -> None:
-        if hasattr(self._camera, "reset"):
-            self._camera.reset()
-
-
-class ViewportFilterStage(Stage):
-    """Stage that limits items based on layout calculation.
-
-    Computes cumulative y-offsets for all items using cheap height estimation,
-    then returns only items that overlap the camera's viewport window.
-    This prevents FontStage from rendering thousands of items when only a few
-    are visible, while still allowing camera scrolling through all content.
-    """
-
-    def __init__(self, name: str = "viewport-filter"):
-        self.name = name
-        self.category = "filter"
-        self.optional = False
-        self._cached_count = 0
-        self._layout: list[tuple[int, int]] = []
-
-    @property
-    def stage_type(self) -> str:
-        return "filter"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"filter.{self.name}"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"source"}
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Filter items based on layout and camera position."""
-        if data is None or not isinstance(data, list):
-            return data
-
-        viewport_height = ctx.params.viewport_height if ctx.params else 24
-        viewport_width = ctx.params.viewport_width if ctx.params else 80
-        camera_y = ctx.get("camera_y", 0)
-
-        # Recompute layout only when item count changes
-        if len(data) != self._cached_count:
-            self._layout = []
-            y = 0
-            from engine.render.blocks import estimate_block_height
-
-            for item in data:
-                if hasattr(item, "content"):
-                    title = item.content
-                elif isinstance(item, tuple):
-                    title = str(item[0]) if item else ""
-                else:
-                    title = str(item)
-                h = estimate_block_height(title, viewport_width)
-                self._layout.append((y, h))
-                y += h
-            self._cached_count = len(data)
-
-        # Find items visible in [camera_y - buffer, camera_y + viewport_height + buffer]
-        buffer_zone = viewport_height
-        vis_start = max(0, camera_y - buffer_zone)
-        vis_end = camera_y + viewport_height + buffer_zone
-
-        visible_items = []
-        render_offset_y = 0
-        first_visible_found = False
-        for i, (start_y, height) in enumerate(self._layout):
-            item_end = start_y + height
-            if item_end > vis_start and start_y < vis_end:
-                if not first_visible_found:
-                    render_offset_y = start_y
-                    first_visible_found = True
-                visible_items.append(data[i])
-
-        # Compute total layout height for the canvas
-        total_layout_height = 0
-        if self._layout:
-            last_start, last_height = self._layout[-1]
-            total_layout_height = last_start + last_height
-
-        # Store metadata for CameraStage
-        ctx.set("render_offset_y", render_offset_y)
-        ctx.set("total_layout_height", total_layout_height)
-
-        # Always return at least one item to avoid empty buffer errors
-        return visible_items if visible_items else data[:1]
-
-
-class FontStage(Stage):
-    """Stage that applies font rendering to content.
-
-    FontStage is a Transform that takes raw content (text, headlines)
-    and renders it to an ANSI-formatted buffer using the configured font.
-
-    This decouples font rendering from data sources, allowing:
-    - Different fonts per source
-    - Runtime font swapping
-    - Font as a pipeline stage
-
-    Attributes:
-        font_path: Path to font file (None = use config default)
-        font_size: Font size in points (None = use config default)
-        font_ref: Reference name for registered font ("default", "cjk", etc.)
-    """
-
-    def __init__(
-        self,
-        font_path: str | None = None,
-        font_size: int | None = None,
-        font_ref: str | None = "default",
-        name: str = "font",
-    ):
-        self.name = name
-        self.category = "transform"
-        self.optional = False
-        self._font_path = font_path
-        self._font_size = font_size
-        self._font_ref = font_ref
-        self._font = None
-        self._render_cache: dict[tuple[str, str, int], list[str]] = {}
-
-    @property
-    def stage_type(self) -> str:
-        return "transform"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"transform.{self.name}", "render.output"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"source"}
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.SOURCE_ITEMS}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    def init(self, ctx: PipelineContext) -> bool:
-        """Initialize font from config or path."""
-        from engine import config
-
-        if self._font_path:
-            try:
-                from PIL import ImageFont
-
-                size = self._font_size or config.FONT_SZ
-                self._font = ImageFont.truetype(self._font_path, size)
-            except Exception:
-                return False
-        return True
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Render content with font to buffer."""
-        if data is None:
-            return None
-
-        from engine.render import make_block
-
-        w = ctx.params.viewport_width if ctx.params else 80
-
-        # If data is already a list of strings (buffer), return as-is
-        if isinstance(data, list) and data and isinstance(data[0], str):
-            return data
-
-        # If data is a list of items, render each with font
-        if isinstance(data, list):
-            result = []
-            for item in data:
-                # Handle SourceItem or tuple (title, source, timestamp)
-                if hasattr(item, "content"):
-                    title = item.content
-                    src = getattr(item, "source", "unknown")
-                    ts = getattr(item, "timestamp", "0")
-                elif isinstance(item, tuple):
-                    title = item[0] if len(item) > 0 else ""
-                    src = item[1] if len(item) > 1 else "unknown"
-                    ts = str(item[2]) if len(item) > 2 else "0"
-                else:
-                    title = str(item)
-                    src = "unknown"
-                    ts = "0"
-
-                # Check cache first
-                cache_key = (title, src, ts, w)
-                if cache_key in self._render_cache:
-                    result.extend(self._render_cache[cache_key])
-                    continue
-
-                try:
-                    block_lines, color_code, meta_idx = make_block(title, src, ts, w)
-                    self._render_cache[cache_key] = block_lines
-                    result.extend(block_lines)
-                except Exception:
-                    result.append(title)
-
-            return result
-
-        return data
-
-
-class ImageToTextStage(Stage):
-    """Transform that converts PIL Image to ASCII text buffer.
-
-    Takes an ImageItem or PIL Image and converts it to a text buffer
-    using ASCII character density mapping. The output can be displayed
-    directly or further processed by effects.
-
-    Attributes:
-        width: Output width in characters
-        height: Output height in characters
-        charset: Character set for density mapping (default: simple ASCII)
-    """
-
-    def __init__(
-        self,
-        width: int = 80,
-        height: int = 24,
-        charset: str = " .:-=+*#%@",
-        name: str = "image-to-text",
-    ):
-        self.name = name
-        self.category = "transform"
-        self.optional = False
-        self.width = width
-        self.height = height
-        self.charset = charset
-
-    @property
-    def stage_type(self) -> str:
-        return "transform"
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.PIL_IMAGE}  # Accepts PIL Image objects or ImageItem
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.TEXT_BUFFER}
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"transform.{self.name}", "render.output"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return {"source"}
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Convert PIL Image to text buffer."""
-        if data is None:
-            return None
-
-        from engine.data_sources.sources import ImageItem
-
-        # Extract PIL Image from various input types
-        pil_image = None
-
-        if isinstance(data, ImageItem) or hasattr(data, "image"):
-            pil_image = data.image
-        else:
-            # Assume it's already a PIL Image
-            pil_image = data
-
-        # Check if it's a PIL Image
-        if not hasattr(pil_image, "resize"):
-            # Not a PIL Image, return as-is
-            return data if isinstance(data, list) else [str(data)]
-
-        # Convert to grayscale and resize
-        try:
-            if pil_image.mode != "L":
-                pil_image = pil_image.convert("L")
-        except Exception:
-            return ["[image conversion error]"]
-
-        # Calculate cell aspect ratio correction (characters are taller than wide)
-        aspect_ratio = 0.5
-        target_w = self.width
-        target_h = int(self.height * aspect_ratio)
-
-        # Resize image to target dimensions
-        try:
-            resized = pil_image.resize((target_w, target_h))
-        except Exception:
-            return ["[image resize error]"]
-
-        # Map pixels to characters
-        result = []
-        pixels = list(resized.getdata())
-
-        for row in range(target_h):
-            line = ""
-            for col in range(target_w):
-                idx = row * target_w + col
-                if idx < len(pixels):
-                    brightness = pixels[idx]
-                    char_idx = int((brightness / 255) * (len(self.charset) - 1))
-                    line += self.charset[char_idx]
-                else:
-                    line += " "
-            result.append(line)
-
-        # Pad or trim to exact height
-        while len(result) < self.height:
-            result.append(" " * self.width)
-        result = result[: self.height]
-
-        # Pad lines to width
-        result = [line.ljust(self.width) for line in result]
-
-        return result
-
-
-def create_stage_from_display(display, name: str = "terminal") -> DisplayStage:
-    """Create a Stage from a Display instance."""
-    return DisplayStage(display, name)
-
-
-def create_stage_from_effect(effect_plugin, name: str) -> EffectPluginStage:
-    """Create a Stage from an EffectPlugin."""
-    return EffectPluginStage(effect_plugin, name)
-
-
-def create_stage_from_source(data_source, name: str = "headlines") -> DataSourceStage:
-    """Create a Stage from a DataSource."""
-    return DataSourceStage(data_source, name)
-
-
-def create_stage_from_camera(camera, name: str = "vertical") -> CameraStage:
-    """Create a Stage from a Camera."""
-    return CameraStage(camera, name)
-
-
-def create_stage_from_font(
-    font_path: str | None = None,
-    font_size: int | None = None,
-    font_ref: str | None = "default",
-    name: str = "font",
-) -> FontStage:
-    """Create a FontStage for rendering content with fonts."""
-    return FontStage(
-        font_path=font_path, font_size=font_size, font_ref=font_ref, name=name
-    )
-
-
-class CanvasStage(Stage):
-    """Stage that manages a Canvas for rendering.
-
-    CanvasStage creates and manages a 2D canvas that can hold rendered content.
-    Other stages can write to and read from the canvas via the pipeline context.
-
-    This enables:
-    - Pre-rendering content off-screen
-    - Multiple cameras viewing different regions
-    - Smooth scrolling (camera moves, content stays)
-    - Layer compositing
-
-    Usage:
-        - Add CanvasStage to pipeline
-        - Other stages access canvas via: ctx.get("canvas")
-    """
-
-    def __init__(
-        self,
-        width: int = 80,
-        height: int = 24,
-        name: str = "canvas",
-    ):
-        self.name = name
-        self.category = "system"
-        self.optional = True
-        self._width = width
-        self._height = height
-        self._canvas = None
-
-    @property
-    def stage_type(self) -> str:
-        return "system"
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {"canvas"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return set()
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.ANY}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.ANY}
-
-    def init(self, ctx: PipelineContext) -> bool:
-        from engine.canvas import Canvas
-
-        self._canvas = Canvas(width=self._width, height=self._height)
-        ctx.set("canvas", self._canvas)
-        return True
-
-    def process(self, data: Any, ctx: PipelineContext) -> Any:
-        """Pass through data but ensure canvas is in context."""
-        if self._canvas is None:
-            from engine.canvas import Canvas
-
-            self._canvas = Canvas(width=self._width, height=self._height)
-            ctx.set("canvas", self._canvas)
-
-        # Get dirty regions from canvas and expose via context
-        # Effects can access via ctx.get_state("canvas.dirty_rows")
-        if self._canvas.is_dirty():
-            dirty_rows = self._canvas.get_dirty_rows()
-            ctx.set_state("canvas.dirty_rows", dirty_rows)
-            ctx.set_state("canvas.dirty_regions", self._canvas.get_dirty_regions())
-
-        return data
-
-    def get_canvas(self):
-        """Get the canvas instance."""
-        return self._canvas
-
-    def cleanup(self) -> None:
-        self._canvas = None

engine/pipeline/controller.py

@@ -1,576 +0,0 @@
-"""
-Pipeline controller - DAG-based pipeline execution.
-
-The Pipeline class orchestrates stages in dependency order, handling
-the complete render cycle from source to display.
-"""
-
-import time
-from dataclasses import dataclass, field
-from typing import Any
-
-from engine.pipeline.core import PipelineContext, Stage, StageError, StageResult
-from engine.pipeline.params import PipelineParams
-from engine.pipeline.registry import StageRegistry
-
-
-@dataclass
-class PipelineConfig:
-    """Configuration for a pipeline instance."""
-
-    source: str = "headlines"
-    display: str = "terminal"
-    camera: str = "vertical"
-    effects: list[str] = field(default_factory=list)
-    enable_metrics: bool = True
-
-
-@dataclass
-class StageMetrics:
-    """Metrics for a single stage execution."""
-
-    name: str
-    duration_ms: float
-    chars_in: int = 0
-    chars_out: int = 0
-
-
-@dataclass
-class FrameMetrics:
-    """Metrics for a single frame through the pipeline."""
-
-    frame_number: int
-    total_ms: float
-    stages: list[StageMetrics] = field(default_factory=list)
-
-
-class Pipeline:
-    """Main pipeline orchestrator.
-
-    Manages the execution of all stages in dependency order,
-    handling initialization, processing, and cleanup.
-    """
-
-    def __init__(
-        self,
-        config: PipelineConfig | None = None,
-        context: PipelineContext | None = None,
-    ):
-        self.config = config or PipelineConfig()
-        self.context = context or PipelineContext()
-        self._stages: dict[str, Stage] = {}
-        self._execution_order: list[str] = []
-        self._initialized = False
-
-        self._metrics_enabled = self.config.enable_metrics
-        self._frame_metrics: list[FrameMetrics] = []
-        self._max_metrics_frames = 60
-        self._current_frame_number = 0
-
-    def add_stage(self, name: str, stage: Stage) -> "Pipeline":
-        """Add a stage to the pipeline."""
-        self._stages[name] = stage
-        return self
-
-    def remove_stage(self, name: str) -> None:
-        """Remove a stage from the pipeline."""
-        if name in self._stages:
-            del self._stages[name]
-
-    def get_stage(self, name: str) -> Stage | None:
-        """Get a stage by name."""
-        return self._stages.get(name)
-
-    def build(self) -> "Pipeline":
-        """Build execution order based on dependencies."""
-        self._capability_map = self._build_capability_map()
-        self._execution_order = self._resolve_dependencies()
-        self._validate_dependencies()
-        self._validate_types()
-        self._initialized = True
-        return self
-
-    def _build_capability_map(self) -> dict[str, list[str]]:
-        """Build a map of capabilities to stage names.
-
-        Returns:
-            Dict mapping capability -> list of stage names that provide it
-        """
-        capability_map: dict[str, list[str]] = {}
-        for name, stage in self._stages.items():
-            for cap in stage.capabilities:
-                if cap not in capability_map:
-                    capability_map[cap] = []
-                capability_map[cap].append(name)
-        return capability_map
-
-    def _find_stage_with_capability(self, capability: str) -> str | None:
-        """Find a stage that provides the given capability.
-
-        Supports wildcard matching:
-        - "source" matches "source.headlines" (prefix match)
-        - "source.*" matches "source.headlines"
-        - "source.headlines" matches exactly
-
-        Args:
-            capability: The capability to find
-
-        Returns:
-            Stage name that provides the capability, or None if not found
-        """
-        # Exact match
-        if capability in self._capability_map:
-            return self._capability_map[capability][0]
-
-        # Prefix match (e.g., "source" -> "source.headlines")
-        for cap, stages in self._capability_map.items():
-            if cap.startswith(capability + "."):
-                return stages[0]
-
-        # Wildcard match (e.g., "source.*" -> "source.headlines")
-        if ".*" in capability:
-            prefix = capability[:-2]  # Remove ".*"
-            for cap in self._capability_map:
-                if cap.startswith(prefix + "."):
-                    return self._capability_map[cap][0]
-
-        return None
-
-    def _resolve_dependencies(self) -> list[str]:
-        """Resolve stage execution order using topological sort with capability matching."""
-        ordered = []
-        visited = set()
-        temp_mark = set()
-
-        def visit(name: str) -> None:
-            if name in temp_mark:
-                raise StageError(name, "Circular dependency detected")
-            if name in visited:
-                return
-
-            temp_mark.add(name)
-            stage = self._stages.get(name)
-            if stage:
-                for dep in stage.dependencies:
-                    # Find a stage that provides this capability
-                    dep_stage_name = self._find_stage_with_capability(dep)
-                    if dep_stage_name:
-                        visit(dep_stage_name)
-
-            temp_mark.remove(name)
-            visited.add(name)
-            ordered.append(name)
-
-        for name in self._stages:
-            if name not in visited:
-                visit(name)
-
-        return ordered
-
-    def _validate_dependencies(self) -> None:
-        """Validate that all dependencies can be satisfied.
-
-        Raises StageError if any dependency cannot be resolved.
-        """
-        missing: list[tuple[str, str]] = []  # (stage_name, capability)
-
-        for name, stage in self._stages.items():
-            for dep in stage.dependencies:
-                if not self._find_stage_with_capability(dep):
-                    missing.append((name, dep))
-
-        if missing:
-            msgs = [f"  - {stage} needs {cap}" for stage, cap in missing]
-            raise StageError(
-                "validation",
-                "Missing capabilities:\n" + "\n".join(msgs),
-            )
-
-    def _validate_types(self) -> None:
-        """Validate inlet/outlet types between connected stages.
-
-        PureData-style type validation. Each stage declares its inlet_types
-        (what it accepts) and outlet_types (what it produces). This method
-        validates that connected stages have compatible types.
-
-        Raises StageError if type mismatch is detected.
-        """
-        from engine.pipeline.core import DataType
-
-        errors: list[str] = []
-
-        for i, name in enumerate(self._execution_order):
-            stage = self._stages.get(name)
-            if not stage:
-                continue
-
-            inlet_types = stage.inlet_types
-
-            # Check against previous stage's outlet types
-            if i > 0:
-                prev_name = self._execution_order[i - 1]
-                prev_stage = self._stages.get(prev_name)
-                if prev_stage:
-                    prev_outlets = prev_stage.outlet_types
-
-                    # Check if any outlet type is accepted by this inlet
-                    compatible = (
-                        DataType.ANY in inlet_types
-                        or DataType.ANY in prev_outlets
-                        or bool(prev_outlets & inlet_types)
-                    )
-
-                    if not compatible:
-                        errors.append(
-                            f"  - {name} (inlet: {inlet_types}) "
-                            f"← {prev_name} (outlet: {prev_outlets})"
-                        )
-
-            # Check display/sink stages (should accept TEXT_BUFFER)
-            if (
-                stage.category == "display"
-                and DataType.TEXT_BUFFER not in inlet_types
-                and DataType.ANY not in inlet_types
-            ):
-                errors.append(f"  - {name} is display but doesn't accept TEXT_BUFFER")
-
-        if errors:
-            raise StageError(
-                "type_validation",
-                "Type mismatch in pipeline connections:\n" + "\n".join(errors),
-            )
-
-    def initialize(self) -> bool:
-        """Initialize all stages in execution order."""
-        for name in self._execution_order:
-            stage = self._stages.get(name)
-            if stage and not stage.init(self.context) and not stage.optional:
-                return False
-        return True
-
-    def execute(self, data: Any | None = None) -> StageResult:
-        """Execute the pipeline with the given input data.
-
-        Pipeline execution:
-        1. Execute all non-overlay stages in dependency order
-        2. Apply overlay stages on top (sorted by render_order)
-        """
-        import os
-        import sys
-
-        debug = os.environ.get("MAINLINE_DEBUG_DATAFLOW") == "1"
-
-        if debug:
-            print(
-                f"[PIPELINE.execute] Starting with data type: {type(data).__name__ if data else 'None'}",
-                file=sys.stderr,
-                flush=True,
-            )
-
-        if not self._initialized:
-            self.build()
-
-        if not self._initialized:
-            return StageResult(
-                success=False,
-                data=None,
-                error="Pipeline not initialized",
-            )
-
-        current_data = data
-        frame_start = time.perf_counter() if self._metrics_enabled else 0
-        stage_timings: list[StageMetrics] = []
-
-        # Separate overlay stages from regular stages
-        overlay_stages: list[tuple[int, Stage]] = []
-        regular_stages: list[str] = []
-
-        for name in self._execution_order:
-            stage = self._stages.get(name)
-            if not stage or not stage.is_enabled():
-                continue
-
-            # Safely check is_overlay - handle MagicMock and other non-bool returns
-            try:
-                is_overlay = bool(getattr(stage, "is_overlay", False))
-            except Exception:
-                is_overlay = False
-
-            if is_overlay:
-                # Safely get render_order
-                try:
-                    render_order = int(getattr(stage, "render_order", 0))
-                except Exception:
-                    render_order = 0
-                overlay_stages.append((render_order, stage))
-            else:
-                regular_stages.append(name)
-
-        # Execute regular stages in dependency order
-        for name in regular_stages:
-            stage = self._stages.get(name)
-            if not stage or not stage.is_enabled():
-                continue
-
-            stage_start = time.perf_counter() if self._metrics_enabled else 0
-
-            try:
-                if debug:
-                    data_info = type(current_data).__name__
-                    if isinstance(current_data, list):
-                        data_info += f"[{len(current_data)}]"
-                    print(
-                        f"[STAGE.{name}] Starting with: {data_info}",
-                        file=sys.stderr,
-                        flush=True,
-                    )
-
-                current_data = stage.process(current_data, self.context)
-
-                if debug:
-                    data_info = type(current_data).__name__
-                    if isinstance(current_data, list):
-                        data_info += f"[{len(current_data)}]"
-                    print(
-                        f"[STAGE.{name}] Completed, output: {data_info}",
-                        file=sys.stderr,
-                        flush=True,
-                    )
-            except Exception as e:
-                if debug:
-                    print(f"[STAGE.{name}] ERROR: {e}", file=sys.stderr, flush=True)
-                if not stage.optional:
-                    return StageResult(
-                        success=False,
-                        data=current_data,
-                        error=str(e),
-                        stage_name=name,
-                    )
-                continue
-
-            if self._metrics_enabled:
-                stage_duration = (time.perf_counter() - stage_start) * 1000
-                chars_in = len(str(data)) if data else 0
-                chars_out = len(str(current_data)) if current_data else 0
-                stage_timings.append(
-                    StageMetrics(
-                        name=name,
-                        duration_ms=stage_duration,
-                        chars_in=chars_in,
-                        chars_out=chars_out,
-                    )
-                )
-
-        # Apply overlay stages (sorted by render_order)
-        overlay_stages.sort(key=lambda x: x[0])
-        for render_order, stage in overlay_stages:
-            stage_start = time.perf_counter() if self._metrics_enabled else 0
-            stage_name = f"[overlay]{stage.name}"
-
-            try:
-                # Overlays receive current_data but don't pass their output to next stage
-                # Instead, their output is composited on top
-                overlay_output = stage.process(current_data, self.context)
-                # For now, we just let the overlay output pass through
-                # In a more sophisticated implementation, we'd composite it
-                if overlay_output is not None:
-                    current_data = overlay_output
-            except Exception as e:
-                if not stage.optional:
-                    return StageResult(
-                        success=False,
-                        data=current_data,
-                        error=str(e),
-                        stage_name=stage_name,
-                    )
-
-            if self._metrics_enabled:
-                stage_duration = (time.perf_counter() - stage_start) * 1000
-                chars_in = len(str(data)) if data else 0
-                chars_out = len(str(current_data)) if current_data else 0
-                stage_timings.append(
-                    StageMetrics(
-                        name=stage_name,
-                        duration_ms=stage_duration,
-                        chars_in=chars_in,
-                        chars_out=chars_out,
-                    )
-                )
-
-        if self._metrics_enabled:
-            total_duration = (time.perf_counter() - frame_start) * 1000
-            self._frame_metrics.append(
-                FrameMetrics(
-                    frame_number=self._current_frame_number,
-                    total_ms=total_duration,
-                    stages=stage_timings,
-                )
-            )
-
-            # Store metrics in context for other stages (like HUD)
-            # This makes metrics a first-class pipeline citizen
-            if self.context:
-                self.context.state["metrics"] = self.get_metrics_summary()
-
-            if len(self._frame_metrics) > self._max_metrics_frames:
-                self._frame_metrics.pop(0)
-            self._current_frame_number += 1
-
-        return StageResult(success=True, data=current_data)
-
-    def cleanup(self) -> None:
-        """Clean up all stages in reverse order."""
-        for name in reversed(self._execution_order):
-            stage = self._stages.get(name)
-            if stage:
-                try:
-                    stage.cleanup()
-                except Exception:
-                    pass
-        self._stages.clear()
-        self._initialized = False
-
-    @property
-    def stages(self) -> dict[str, Stage]:
-        """Get all stages."""
-        return self._stages.copy()
-
-    @property
-    def execution_order(self) -> list[str]:
-        """Get execution order."""
-        return self._execution_order.copy()
-
-    def get_stage_names(self) -> list[str]:
-        """Get list of stage names."""
-        return list(self._stages.keys())
-
-    def get_overlay_stages(self) -> list[Stage]:
-        """Get all overlay stages sorted by render_order."""
-        overlays = [stage for stage in self._stages.values() if stage.is_overlay]
-        overlays.sort(key=lambda s: s.render_order)
-        return overlays
-
-    def get_stage_type(self, name: str) -> str:
-        """Get the stage_type for a stage."""
-        stage = self._stages.get(name)
-        return stage.stage_type if stage else ""
-
-    def get_render_order(self, name: str) -> int:
-        """Get the render_order for a stage."""
-        stage = self._stages.get(name)
-        return stage.render_order if stage else 0
-
-    def get_metrics_summary(self) -> dict:
-        """Get summary of collected metrics."""
-        if not self._frame_metrics:
-            return {"error": "No metrics collected"}
-
-        total_times = [f.total_ms for f in self._frame_metrics]
-        avg_total = sum(total_times) / len(total_times)
-        min_total = min(total_times)
-        max_total = max(total_times)
-
-        stage_stats: dict[str, dict] = {}
-        for frame in self._frame_metrics:
-            for stage in frame.stages:
-                if stage.name not in stage_stats:
-                    stage_stats[stage.name] = {"times": [], "total_chars": 0}
-                stage_stats[stage.name]["times"].append(stage.duration_ms)
-                stage_stats[stage.name]["total_chars"] += stage.chars_out
-
-        for name, stats in stage_stats.items():
-            times = stats["times"]
-            stats["avg_ms"] = sum(times) / len(times)
-            stats["min_ms"] = min(times)
-            stats["max_ms"] = max(times)
-            del stats["times"]
-
-        return {
-            "frame_count": len(self._frame_metrics),
-            "pipeline": {
-                "avg_ms": avg_total,
-                "min_ms": min_total,
-                "max_ms": max_total,
-            },
-            "stages": stage_stats,
-        }
-
-    def reset_metrics(self) -> None:
-        """Reset collected metrics."""
-        self._frame_metrics.clear()
-        self._current_frame_number = 0
-
-    def get_frame_times(self) -> list[float]:
-        """Get historical frame times for sparklines/charts."""
-        return [f.total_ms for f in self._frame_metrics]
-
-
-class PipelineRunner:
-    """High-level pipeline runner with animation support."""
-
-    def __init__(
-        self,
-        pipeline: Pipeline,
-        params: PipelineParams | None = None,
-    ):
-        self.pipeline = pipeline
-        self.params = params or PipelineParams()
-        self._running = False
-
-    def start(self) -> bool:
-        """Start the pipeline."""
-        self._running = True
-        return self.pipeline.initialize()
-
-    def step(self, input_data: Any | None = None) -> Any:
-        """Execute one pipeline step."""
-        self.params.frame_number += 1
-        self.pipeline.context.params = self.params
-        result = self.pipeline.execute(input_data)
-        return result.data if result.success else None
-
-    def stop(self) -> None:
-        """Stop and clean up the pipeline."""
-        self._running = False
-        self.pipeline.cleanup()
-
-    @property
-    def is_running(self) -> bool:
-        """Check if runner is active."""
-        return self._running
-
-
-def create_pipeline_from_params(params: PipelineParams) -> Pipeline:
-    """Create a pipeline from PipelineParams."""
-    config = PipelineConfig(
-        source=params.source,
-        display=params.display,
-        camera=params.camera_mode,
-        effects=params.effect_order,
-    )
-    return Pipeline(config=config)
-
-
-def create_default_pipeline() -> Pipeline:
-    """Create a default pipeline with all standard components."""
-    from engine.data_sources.sources import HeadlinesDataSource
-    from engine.pipeline.adapters import (
-        DataSourceStage,
-        SourceItemsToBufferStage,
-    )
-
-    pipeline = Pipeline()
-
-    # Add source stage (wrapped as Stage)
-    source = HeadlinesDataSource()
-    pipeline.add_stage("source", DataSourceStage(source, name="headlines"))
-
-    # Add render stage to convert items to text buffer
-    pipeline.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
-
-    # Add display stage
-    display = StageRegistry.create("display", "terminal")
-    if display:
-        pipeline.add_stage("display", display)
-
-    return pipeline.build()

engine/pipeline/core.py

@@ -1,306 +0,0 @@
-"""
-Pipeline core - Unified Stage abstraction and PipelineContext.
-
-This module provides the foundation for a clean, dependency-managed pipeline:
-- Stage: Base class for all pipeline components (sources, effects, displays, cameras)
-- PipelineContext: Dependency injection context for runtime data exchange
-- Capability system: Explicit capability declarations with duck-typing support
-- DataType: PureData-style inlet/outlet typing for validation
-"""
-
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from enum import Enum, auto
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from engine.pipeline.params import PipelineParams
-
-
-class DataType(Enum):
-    """PureData-style data types for inlet/outlet validation.
-
-    Each type represents a specific data format that flows through the pipeline.
-    This enables compile-time-like validation of connections.
-
-    Examples:
-        SOURCE_ITEMS: List[SourceItem] - raw items from sources
-        ITEM_TUPLES: List[tuple] - (title, source, timestamp) tuples
-        TEXT_BUFFER: List[str] - rendered ANSI buffer for display
-        RAW_TEXT: str - raw text strings
-        PIL_IMAGE: PIL Image object
-    """
-
-    SOURCE_ITEMS = auto()  # List[SourceItem] - from DataSource
-    ITEM_TUPLES = auto()  # List[tuple] - (title, source, ts)
-    TEXT_BUFFER = auto()  # List[str] - ANSI buffer
-    RAW_TEXT = auto()  # str - raw text
-    PIL_IMAGE = auto()  # PIL Image object
-    ANY = auto()  # Accepts any type
-    NONE = auto()  # No data (terminator)
-
-
-@dataclass
-class StageConfig:
-    """Configuration for a single stage."""
-
-    name: str
-    category: str
-    enabled: bool = True
-    optional: bool = False
-    params: dict[str, Any] = field(default_factory=dict)
-
-
-class Stage(ABC):
-    """Abstract base class for all pipeline stages.
-
-    A Stage is a single component in the rendering pipeline. Stages can be:
-    - Sources: Data providers (headlines, poetry, pipeline viz)
-    - Effects: Post-processors (noise, fade, glitch, hud)
-    - Displays: Output backends (terminal, pygame, websocket)
-    - Cameras: Viewport controllers (vertical, horizontal, omni)
-    - Overlays: UI elements that compose on top (HUD)
-
-    Stages declare:
-    - capabilities: What they provide to other stages
-    - dependencies: What they need from other stages
-    - stage_type: Category of stage (source, effect, overlay, display)
-    - render_order: Execution order within category
-    - is_overlay: If True, output is composited on top, not passed downstream
-
-    Duck-typing is supported: any class with the required methods can act as a Stage.
-    """
-
-    name: str
-    category: str  # "source", "effect", "overlay", "display", "camera"
-    optional: bool = False  # If True, pipeline continues even if stage fails
-
-    @property
-    def stage_type(self) -> str:
-        """Category of stage for ordering.
-
-        Valid values: "source", "effect", "overlay", "display", "camera"
-        Defaults to category for backwards compatibility.
-        """
-        return self.category
-
-    @property
-    def render_order(self) -> int:
-        """Execution order within stage_type group.
-
-        Higher values execute later. Useful for ordering overlays
-        or effects that need specific execution order.
-        """
-        return 0
-
-    @property
-    def is_overlay(self) -> bool:
-        """If True, this stage's output is composited on top of the buffer.
-
-        Overlay stages don't pass their output to the next stage.
-        Instead, their output is layered on top of the final buffer.
-        Use this for HUD, status displays, and similar UI elements.
-        """
-        return False
-
-    @property
-    def inlet_types(self) -> set[DataType]:
-        """Return set of data types this stage accepts.
-
-        PureData-style inlet typing. If the connected upstream stage's
-        outlet_type is not in this set, the pipeline will raise an error.
-
-        Examples:
-            - Source stages: {DataType.NONE} (no input needed)
-            - Transform stages: {DataType.ITEM_TUPLES, DataType.TEXT_BUFFER}
-            - Display stages: {DataType.TEXT_BUFFER}
-        """
-        return {DataType.ANY}
-
-    @property
-    def outlet_types(self) -> set[DataType]:
-        """Return set of data types this stage produces.
-
-        PureData-style outlet typing. Downstream stages must accept
-        this type in their inlet_types.
-
-        Examples:
-            - Source stages: {DataType.SOURCE_ITEMS}
-            - Transform stages: {DataType.TEXT_BUFFER}
-            - Display stages: {DataType.NONE} (consumes data)
-        """
-        return {DataType.ANY}
-
-    @property
-    def capabilities(self) -> set[str]:
-        """Return set of capabilities this stage provides.
-
-        Examples:
-            - "source.headlines"
-            - "effect.noise"
-            - "display.output"
-            - "camera"
-        """
-        return {f"{self.category}.{self.name}"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        """Return set of capability names this stage needs.
-
-        Examples:
-            - {"display.output"}
-            - {"source.headlines"}
-            - {"camera"}
-        """
-        return set()
-
-    def init(self, ctx: "PipelineContext") -> bool:
-        """Initialize stage with pipeline context.
-
-        Args:
-            ctx: PipelineContext for accessing services
-
-        Returns:
-            True if initialization succeeded, False otherwise
-        """
-        return True
-
-    @abstractmethod
-    def process(self, data: Any, ctx: "PipelineContext") -> Any:
-        """Process input data and return output.
-
-        Args:
-            data: Input data from previous stage (or initial data for first stage)
-            ctx: PipelineContext for accessing services and state
-
-        Returns:
-            Processed data for next stage
-        """
-        ...
-
-    def cleanup(self) -> None:  # noqa: B027
-        """Clean up resources when pipeline shuts down."""
-        pass
-
-    def get_config(self) -> StageConfig:
-        """Return current configuration of this stage."""
-        return StageConfig(
-            name=self.name,
-            category=self.category,
-            optional=self.optional,
-        )
-
-    def set_enabled(self, enabled: bool) -> None:
-        """Enable or disable this stage."""
-        self._enabled = enabled  # type: ignore[attr-defined]
-
-    def is_enabled(self) -> bool:
-        """Check if stage is enabled."""
-        return getattr(self, "_enabled", True)
-
-
-@dataclass
-class StageResult:
-    """Result of stage processing, including success/failure info."""
-
-    success: bool
-    data: Any
-    error: str | None = None
-    stage_name: str = ""
-
-
-class PipelineContext:
-    """Dependency injection context passed through the pipeline.
-
-    Provides:
-    - services: Named services (display, config, event_bus, etc.)
-    - state: Runtime state shared between stages
-    - params: PipelineParams for animation-driven config
-
-    Services can be injected at construction time or lazily resolved.
-    """
-
-    def __init__(
-        self,
-        services: dict[str, Any] | None = None,
-        initial_state: dict[str, Any] | None = None,
-    ):
-        self.services: dict[str, Any] = services or {}
-        self.state: dict[str, Any] = initial_state or {}
-        self._params: PipelineParams | None = None
-
-        # Lazy resolvers for common services
-        self._lazy_resolvers: dict[str, Callable[[], Any]] = {
-            "config": self._resolve_config,
-            "event_bus": self._resolve_event_bus,
-        }
-
-    def _resolve_config(self) -> Any:
-        from engine.config import get_config
-
-        return get_config()
-
-    def _resolve_event_bus(self) -> Any:
-        from engine.eventbus import get_event_bus
-
-        return get_event_bus()
-
-    def get(self, key: str, default: Any = None) -> Any:
-        """Get a service or state value by key.
-
-        First checks services, then state, then lazy resolution.
-        """
-        if key in self.services:
-            return self.services[key]
-        if key in self.state:
-            return self.state[key]
-        if key in self._lazy_resolvers:
-            try:
-                return self._lazy_resolvers[key]()
-            except Exception:
-                return default
-        return default
-
-    def set(self, key: str, value: Any) -> None:
-        """Set a service or state value."""
-        self.services[key] = value
-
-    def set_state(self, key: str, value: Any) -> None:
-        """Set a runtime state value."""
-        self.state[key] = value
-
-    def get_state(self, key: str, default: Any = None) -> Any:
-        """Get a runtime state value."""
-        return self.state.get(key, default)
-
-    @property
-    def params(self) -> "PipelineParams | None":
-        """Get current pipeline params (for animation)."""
-        return self._params
-
-    @params.setter
-    def params(self, value: "PipelineParams") -> None:
-        """Set pipeline params (from animation controller)."""
-        self._params = value
-
-    def has_capability(self, capability: str) -> bool:
-        """Check if a capability is available."""
-        return capability in self.services or capability in self._lazy_resolvers
-
-
-class StageError(Exception):
-    """Raised when a stage fails to process."""
-
-    def __init__(self, stage_name: str, message: str, is_optional: bool = False):
-        self.stage_name = stage_name
-        self.message = message
-        self.is_optional = is_optional
-        super().__init__(f"Stage '{stage_name}' failed: {message}")
-
-
-def create_stage_error(
-    stage_name: str, error: Exception, is_optional: bool = False
-) -> StageError:
-    """Helper to create a StageError from an exception."""
-    return StageError(stage_name, str(error), is_optional)

engine/pipeline/params.py

@@ -1,145 +0,0 @@
-"""
-Pipeline parameters - Runtime configuration layer for animation control.
-
-PipelineParams is the target for AnimationController - animation events
-modify these params, which the pipeline then applies to its stages.
-"""
-
-from dataclasses import dataclass, field
-from typing import Any
-
-
-@dataclass
-class PipelineParams:
-    """Runtime configuration for the pipeline.
-
-    This is the canonical config object that AnimationController modifies.
-    Stages read from these params to adjust their behavior.
-    """
-
-    # Source config
-    source: str = "headlines"
-    source_refresh_interval: float = 60.0
-
-    # Display config
-    display: str = "terminal"
-    border: bool = False
-
-    # Camera config
-    camera_mode: str = "vertical"
-    camera_speed: float = 1.0
-    camera_x: int = 0  # For horizontal scrolling
-
-    # Effect config
-    effect_order: list[str] = field(
-        default_factory=lambda: ["noise", "fade", "glitch", "firehose", "hud"]
-    )
-    effect_enabled: dict[str, bool] = field(default_factory=dict)
-    effect_intensity: dict[str, float] = field(default_factory=dict)
-
-    # Animation-driven state (set by AnimationController)
-    pulse: float = 0.0
-    current_effect: str | None = None
-    path_progress: float = 0.0
-
-    # Viewport
-    viewport_width: int = 80
-    viewport_height: int = 24
-
-    # Firehose
-    firehose_enabled: bool = False
-
-    # Runtime state
-    frame_number: int = 0
-    fps: float = 60.0
-
-    def get_effect_config(self, name: str) -> tuple[bool, float]:
-        """Get (enabled, intensity) for an effect."""
-        enabled = self.effect_enabled.get(name, True)
-        intensity = self.effect_intensity.get(name, 1.0)
-        return enabled, intensity
-
-    def set_effect_config(self, name: str, enabled: bool, intensity: float) -> None:
-        """Set effect configuration."""
-        self.effect_enabled[name] = enabled
-        self.effect_intensity[name] = intensity
-
-    def is_effect_enabled(self, name: str) -> bool:
-        """Check if an effect is enabled."""
-        if name not in self.effect_enabled:
-            return True  # Default to enabled
-        return self.effect_enabled.get(name, True)
-
-    def get_effect_intensity(self, name: str) -> float:
-        """Get effect intensity (0.0 to 1.0)."""
-        return self.effect_intensity.get(name, 1.0)
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for serialization."""
-        return {
-            "source": self.source,
-            "display": self.display,
-            "camera_mode": self.camera_mode,
-            "camera_speed": self.camera_speed,
-            "effect_order": self.effect_order,
-            "effect_enabled": self.effect_enabled.copy(),
-            "effect_intensity": self.effect_intensity.copy(),
-            "pulse": self.pulse,
-            "current_effect": self.current_effect,
-            "viewport_width": self.viewport_width,
-            "viewport_height": self.viewport_height,
-            "firehose_enabled": self.firehose_enabled,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "PipelineParams":
-        """Create from dictionary."""
-        params = cls()
-        for key, value in data.items():
-            if hasattr(params, key):
-                setattr(params, key, value)
-        return params
-
-    def copy(self) -> "PipelineParams":
-        """Create a copy of this params object."""
-        params = PipelineParams()
-        params.source = self.source
-        params.display = self.display
-        params.camera_mode = self.camera_mode
-        params.camera_speed = self.camera_speed
-        params.camera_x = self.camera_x
-        params.effect_order = self.effect_order.copy()
-        params.effect_enabled = self.effect_enabled.copy()
-        params.effect_intensity = self.effect_intensity.copy()
-        params.pulse = self.pulse
-        params.current_effect = self.current_effect
-        params.path_progress = self.path_progress
-        params.viewport_width = self.viewport_width
-        params.viewport_height = self.viewport_height
-        params.firehose_enabled = self.firehose_enabled
-        params.frame_number = self.frame_number
-        params.fps = self.fps
-        return params
-
-
-# Default params for different modes
-DEFAULT_HEADLINE_PARAMS = PipelineParams(
-    source="headlines",
-    display="terminal",
-    camera_mode="vertical",
-    effect_order=["noise", "fade", "glitch", "firehose", "hud"],
-)
-
-DEFAULT_PYGAME_PARAMS = PipelineParams(
-    source="headlines",
-    display="pygame",
-    camera_mode="vertical",
-    effect_order=["noise", "fade", "glitch", "firehose", "hud"],
-)
-
-DEFAULT_PIPELINE_PARAMS = PipelineParams(
-    source="pipeline",
-    display="pygame",
-    camera_mode="trace",
-    effect_order=["hud"],  # Just HUD for pipeline viz
-)

engine/pipeline/pipeline_introspection_demo.py

@@ -1,300 +0,0 @@
-"""
-Pipeline introspection demo controller - 3-phase animation system.
-
-Phase 1: Toggle each effect on/off one at a time (3s each, 1s gap)
-Phase 2: LFO drives intensity default → max → min → default for each effect
-Phase 3: All effects with shared LFO driving full waveform
-
-This controller manages the animation and updates the pipeline accordingly.
-"""
-
-import time
-from dataclasses import dataclass
-from enum import Enum, auto
-from typing import Any
-
-from engine.effects import get_registry
-from engine.sensors.oscillator import OscillatorSensor
-
-
-class DemoPhase(Enum):
-    """The three phases of the pipeline introspection demo."""
-
-    PHASE_1_TOGGLE = auto()  # Toggle each effect on/off
-    PHASE_2_LFO = auto()  # LFO drives intensity up/down
-    PHASE_3_SHARED_LFO = auto()  # All effects with shared LFO
-
-
-@dataclass
-class PhaseState:
-    """State for a single phase of the demo."""
-
-    phase: DemoPhase
-    start_time: float
-    current_effect_index: int = 0
-    effect_start_time: float = 0.0
-    lfo_phase: float = 0.0  # 0.0 to 1.0
-
-
-@dataclass
-class DemoConfig:
-    """Configuration for the demo animation."""
-
-    effect_cycle_duration: float = 3.0  # seconds per effect
-    gap_duration: float = 1.0  # seconds between effects
-    lfo_duration: float = (
-        4.0  # seconds for full LFO cycle (default → max → min → default)
-    )
-    phase_2_effect_duration: float = 4.0  # seconds per effect in phase 2
-    phase_3_lfo_duration: float = 6.0  # seconds for full waveform in phase 3
-
-
-class PipelineIntrospectionDemo:
-    """Controller for the 3-phase pipeline introspection demo.
-
-    Manages effect toggling and LFO modulation across the pipeline.
-    """
-
-    def __init__(
-        self,
-        pipeline: Any,
-        effect_names: list[str] | None = None,
-        config: DemoConfig | None = None,
-    ):
-        self._pipeline = pipeline
-        self._config = config or DemoConfig()
-        self._effect_names = effect_names or ["noise", "fade", "glitch", "firehose"]
-        self._phase = DemoPhase.PHASE_1_TOGGLE
-        self._phase_state = PhaseState(
-            phase=DemoPhase.PHASE_1_TOGGLE,
-            start_time=time.time(),
-        )
-        self._shared_oscillator: OscillatorSensor | None = None
-        self._frame = 0
-
-        # Register shared oscillator for phase 3
-        self._shared_oscillator = OscillatorSensor(
-            name="demo-lfo",
-            waveform="sine",
-            frequency=1.0 / self._config.phase_3_lfo_duration,
-        )
-
-    @property
-    def phase(self) -> DemoPhase:
-        return self._phase
-
-    @property
-    def phase_display(self) -> str:
-        """Get a human-readable phase description."""
-        phase_num = {
-            DemoPhase.PHASE_1_TOGGLE: 1,
-            DemoPhase.PHASE_2_LFO: 2,
-            DemoPhase.PHASE_3_SHARED_LFO: 3,
-        }
-        return f"Phase {phase_num[self._phase]}"
-
-    @property
-    def effect_names(self) -> list[str]:
-        return self._effect_names
-
-    @property
-    def shared_oscillator(self) -> OscillatorSensor | None:
-        return self._shared_oscillator
-
-    def update(self) -> dict[str, Any]:
-        """Update the demo state and return current parameters.
-
-        Returns:
-            dict with current effect settings for the pipeline
-        """
-        self._frame += 1
-        current_time = time.time()
-        elapsed = current_time - self._phase_state.start_time
-
-        # Phase transition logic
-        phase_duration = self._get_phase_duration()
-        if elapsed >= phase_duration:
-            self._advance_phase()
-
-        # Update based on current phase
-        if self._phase == DemoPhase.PHASE_1_TOGGLE:
-            return self._update_phase_1(current_time)
-        elif self._phase == DemoPhase.PHASE_2_LFO:
-            return self._update_phase_2(current_time)
-        else:
-            return self._update_phase_3(current_time)
-
-    def _get_phase_duration(self) -> float:
-        """Get duration of current phase in seconds."""
-        if self._phase == DemoPhase.PHASE_1_TOGGLE:
-            # Duration = (effect_time + gap) * num_effects + final_gap
-            return (
-                self._config.effect_cycle_duration + self._config.gap_duration
-            ) * len(self._effect_names) + self._config.gap_duration
-        elif self._phase == DemoPhase.PHASE_2_LFO:
-            return self._config.phase_2_effect_duration * len(self._effect_names)
-        else:
-            # Phase 3 runs indefinitely
-            return float("inf")
-
-    def _advance_phase(self) -> None:
-        """Advance to the next phase."""
-        if self._phase == DemoPhase.PHASE_1_TOGGLE:
-            self._phase = DemoPhase.PHASE_2_LFO
-        elif self._phase == DemoPhase.PHASE_2_LFO:
-            self._phase = DemoPhase.PHASE_3_SHARED_LFO
-            # Start the shared oscillator
-            if self._shared_oscillator:
-                self._shared_oscillator.start()
-        else:
-            # Phase 3 loops indefinitely - reset for demo replay after long time
-            self._phase = DemoPhase.PHASE_1_TOGGLE
-
-        self._phase_state = PhaseState(
-            phase=self._phase,
-            start_time=time.time(),
-        )
-
-    def _update_phase_1(self, current_time: float) -> dict[str, Any]:
-        """Phase 1: Toggle each effect on/off one at a time."""
-        effect_time = current_time - self._phase_state.effect_start_time
-
-        # Check if we should move to next effect
-        cycle_time = self._config.effect_cycle_duration + self._config.gap_duration
-        effect_index = int((current_time - self._phase_state.start_time) / cycle_time)
-
-        # Clamp to valid range
-        if effect_index >= len(self._effect_names):
-            effect_index = len(self._effect_names) - 1
-
-        # Calculate current effect state
-        in_gap = effect_time >= self._config.effect_cycle_duration
-
-        # Build effect states
-        effect_states: dict[str, dict[str, Any]] = {}
-        for i, name in enumerate(self._effect_names):
-            if i < effect_index:
-                # Past effects - leave at default
-                effect_states[name] = {"enabled": False, "intensity": 0.5}
-            elif i == effect_index:
-                # Current effect - toggle on/off
-                if in_gap:
-                    effect_states[name] = {"enabled": False, "intensity": 0.5}
-                else:
-                    effect_states[name] = {"enabled": True, "intensity": 1.0}
-            else:
-                # Future effects - off
-                effect_states[name] = {"enabled": False, "intensity": 0.5}
-
-        # Apply to effect registry
-        self._apply_effect_states(effect_states)
-
-        return {
-            "phase": "PHASE_1_TOGGLE",
-            "phase_display": self.phase_display,
-            "current_effect": self._effect_names[effect_index]
-            if effect_index < len(self._effect_names)
-            else None,
-            "effect_states": effect_states,
-            "frame": self._frame,
-        }
-
-    def _update_phase_2(self, current_time: float) -> dict[str, Any]:
-        """Phase 2: LFO drives intensity default → max → min → default."""
-        elapsed = current_time - self._phase_state.start_time
-        effect_index = int(elapsed / self._config.phase_2_effect_duration)
-        effect_index = min(effect_index, len(self._effect_names) - 1)
-
-        # Calculate LFO position (0 → 1 → 0)
-        effect_elapsed = elapsed % self._config.phase_2_effect_duration
-        lfo_position = effect_elapsed / self._config.phase_2_effect_duration
-
-        # LFO: 0 → 1 → 0 (triangle wave)
-        if lfo_position < 0.5:
-            lfo_value = lfo_position * 2  # 0 → 1
-        else:
-            lfo_value = 2 - lfo_position * 2  # 1 → 0
-
-        # Map to intensity: 0.3 (default) → 1.0 (max) → 0.0 (min) → 0.3 (default)
-        if lfo_position < 0.25:
-            # 0.3 → 1.0
-            intensity = 0.3 + (lfo_position / 0.25) * 0.7
-        elif lfo_position < 0.75:
-            # 1.0 → 0.0
-            intensity = 1.0 - ((lfo_position - 0.25) / 0.5) * 1.0
-        else:
-            # 0.0 → 0.3
-            intensity = ((lfo_position - 0.75) / 0.25) * 0.3
-
-        # Build effect states
-        effect_states: dict[str, dict[str, Any]] = {}
-        for i, name in enumerate(self._effect_names):
-            if i < effect_index:
-                # Past effects - default
-                effect_states[name] = {"enabled": True, "intensity": 0.5}
-            elif i == effect_index:
-                # Current effect - LFO modulated
-                effect_states[name] = {"enabled": True, "intensity": intensity}
-            else:
-                # Future effects - off
-                effect_states[name] = {"enabled": False, "intensity": 0.5}
-
-        # Apply to effect registry
-        self._apply_effect_states(effect_states)
-
-        return {
-            "phase": "PHASE_2_LFO",
-            "phase_display": self.phase_display,
-            "current_effect": self._effect_names[effect_index],
-            "lfo_value": lfo_value,
-            "intensity": intensity,
-            "effect_states": effect_states,
-            "frame": self._frame,
-        }
-
-    def _update_phase_3(self, current_time: float) -> dict[str, Any]:
-        """Phase 3: All effects with shared LFO driving full waveform."""
-        # Read shared oscillator
-        lfo_value = 0.5  # Default
-        if self._shared_oscillator:
-            sensor_val = self._shared_oscillator.read()
-            if sensor_val:
-                lfo_value = sensor_val.value
-
-        # All effects enabled with shared LFO
-        effect_states: dict[str, dict[str, Any]] = {}
-        for name in self._effect_names:
-            effect_states[name] = {"enabled": True, "intensity": lfo_value}
-
-        # Apply to effect registry
-        self._apply_effect_states(effect_states)
-
-        return {
-            "phase": "PHASE_3_SHARED_LFO",
-            "phase_display": self.phase_display,
-            "lfo_value": lfo_value,
-            "effect_states": effect_states,
-            "frame": self._frame,
-        }
-
-    def _apply_effect_states(self, effect_states: dict[str, dict[str, Any]]) -> None:
-        """Apply effect states to the effect registry."""
-        try:
-            registry = get_registry()
-            for name, state in effect_states.items():
-                effect = registry.get(name)
-                if effect:
-                    effect.config.enabled = state["enabled"]
-                    effect.config.intensity = state["intensity"]
-        except Exception:
-            pass  # Silently fail if registry not available
-
-    def cleanup(self) -> None:
-        """Clean up resources."""
-        if self._shared_oscillator:
-            self._shared_oscillator.stop()
-
-        # Reset all effects to default
-        self._apply_effect_states(
-            {name: {"enabled": False, "intensity": 0.5} for name in self._effect_names}
-        )

engine/pipeline/preset_loader.py

@@ -1,282 +0,0 @@
-"""
-Preset loader - Loads presets from TOML files.
-
-Supports:
-- Built-in presets.toml in the package
-- User overrides in ~/.config/mainline/presets.toml
-- Local override in ./presets.toml
-- Fallback DEFAULT_PRESET when loading fails
-"""
-
-import os
-from pathlib import Path
-from typing import Any
-
-import tomllib
-
-DEFAULT_PRESET: dict[str, Any] = {
-    "description": "Default fallback preset",
-    "source": "headlines",
-    "display": "terminal",
-    "camera": "vertical",
-    "effects": ["hud"],
-    "viewport": {"width": 80, "height": 24},
-    "camera_speed": 1.0,
-    "firehose_enabled": False,
-}
-
-
-def get_preset_paths() -> list[Path]:
-    """Get list of preset file paths in load order (later overrides earlier)."""
-    paths = []
-
-    builtin = Path(__file__).parent.parent / "presets.toml"
-    if builtin.exists():
-        paths.append(builtin)
-
-    user_config = Path(os.path.expanduser("~/.config/mainline/presets.toml"))
-    if user_config.exists():
-        paths.append(user_config)
-
-    local = Path("presets.toml")
-    if local.exists():
-        paths.append(local)
-
-    return paths
-
-
-def load_presets() -> dict[str, Any]:
-    """Load all presets, merging from multiple sources."""
-    merged: dict[str, Any] = {"presets": {}, "sensors": {}, "effect_configs": {}}
-
-    for path in get_preset_paths():
-        try:
-            with open(path, "rb") as f:
-                data = tomllib.load(f)
-
-            if "presets" in data:
-                merged["presets"].update(data["presets"])
-
-            if "sensors" in data:
-                merged["sensors"].update(data["sensors"])
-
-            if "effect_configs" in data:
-                merged["effect_configs"].update(data["effect_configs"])
-
-        except Exception as e:
-            print(f"Warning: Failed to load presets from {path}: {e}")
-
-    return merged
-
-
-def get_preset(name: str) -> dict[str, Any] | None:
-    """Get a preset by name."""
-    presets = load_presets()
-    return presets.get("presets", {}).get(name)
-
-
-def list_preset_names() -> list[str]:
-    """List all available preset names."""
-    presets = load_presets()
-    return list(presets.get("presets", {}).keys())
-
-
-def get_sensor_config(name: str) -> dict[str, Any] | None:
-    """Get sensor configuration by name."""
-    sensors = load_presets()
-    return sensors.get("sensors", {}).get(name)
-
-
-def get_effect_config(name: str) -> dict[str, Any] | None:
-    """Get effect configuration by name."""
-    configs = load_presets()
-    return configs.get("effect_configs", {}).get(name)
-
-
-def get_all_effect_configs() -> dict[str, Any]:
-    """Get all effect configurations."""
-    configs = load_presets()
-    return configs.get("effect_configs", {})
-
-
-def get_preset_or_default(name: str) -> dict[str, Any]:
-    """Get a preset by name, or return DEFAULT_PRESET if not found."""
-    preset = get_preset(name)
-    if preset is not None:
-        return preset
-    return DEFAULT_PRESET.copy()
-
-
-def ensure_preset_available(name: str | None) -> dict[str, Any]:
-    """Ensure a preset is available, falling back to DEFAULT_PRESET."""
-    if name is None:
-        return DEFAULT_PRESET.copy()
-    return get_preset_or_default(name)
-
-
-class PresetValidationError(Exception):
-    """Raised when preset validation fails."""
-
-    pass
-
-
-def validate_preset(preset: dict[str, Any]) -> list[str]:
-    """Validate a preset and return list of errors (empty if valid)."""
-    errors: list[str] = []
-
-    required_fields = ["source", "display", "effects"]
-    for field in required_fields:
-        if field not in preset:
-            errors.append(f"Missing required field: {field}")
-
-    if "effects" in preset:
-        if not isinstance(preset["effects"], list):
-            errors.append("'effects' must be a list")
-        else:
-            for effect in preset["effects"]:
-                if not isinstance(effect, str):
-                    errors.append(
-                        f"Effect must be string, got {type(effect)}: {effect}"
-                    )
-
-    if "viewport" in preset:
-        viewport = preset["viewport"]
-        if not isinstance(viewport, dict):
-            errors.append("'viewport' must be a dict")
-        else:
-            if "width" in viewport and not isinstance(viewport["width"], int):
-                errors.append("'viewport.width' must be an int")
-            if "height" in viewport and not isinstance(viewport["height"], int):
-                errors.append("'viewport.height' must be an int")
-
-    return errors
-
-
-def validate_signal_flow(stages: list[dict]) -> list[str]:
-    """Validate signal flow based on inlet/outlet types.
-
-    This validates that the preset's stage configuration produces valid
-    data flow using the PureData-style type system.
-
-    Args:
-        stages: List of stage configs with 'name', 'category', 'inlet_types', 'outlet_types'
-
-    Returns:
-        List of errors (empty if valid)
-    """
-    errors: list[str] = []
-
-    if not stages:
-        errors.append("Signal flow is empty")
-        return errors
-
-    # Define expected types for each category
-    type_map = {
-        "source": {"inlet": "NONE", "outlet": "SOURCE_ITEMS"},
-        "data": {"inlet": "ANY", "outlet": "SOURCE_ITEMS"},
-        "transform": {"inlet": "SOURCE_ITEMS", "outlet": "TEXT_BUFFER"},
-        "effect": {"inlet": "TEXT_BUFFER", "outlet": "TEXT_BUFFER"},
-        "overlay": {"inlet": "TEXT_BUFFER", "outlet": "TEXT_BUFFER"},
-        "camera": {"inlet": "TEXT_BUFFER", "outlet": "TEXT_BUFFER"},
-        "display": {"inlet": "TEXT_BUFFER", "outlet": "NONE"},
-        "render": {"inlet": "SOURCE_ITEMS", "outlet": "TEXT_BUFFER"},
-    }
-
-    # Check stage order and type compatibility
-    for i, stage in enumerate(stages):
-        category = stage.get("category", "unknown")
-        name = stage.get("name", f"stage_{i}")
-
-        if category not in type_map:
-            continue  # Skip unknown categories
-
-        expected = type_map[category]
-
-        # Check against previous stage
-        if i > 0:
-            prev = stages[i - 1]
-            prev_category = prev.get("category", "unknown")
-            if prev_category in type_map:
-                prev_outlet = type_map[prev_category]["outlet"]
-                inlet = expected["inlet"]
-
-                # Validate type compatibility
-                if inlet != "ANY" and prev_outlet != "ANY" and inlet != prev_outlet:
-                    errors.append(
-                        f"Type mismatch at '{name}': "
-                        f"expects {inlet} but previous stage outputs {prev_outlet}"
-                    )
-
-    return errors
-
-
-def validate_signal_path(stages: list[str]) -> list[str]:
-    """Validate signal path for circular dependencies and connectivity.
-
-    Args:
-        stages: List of stage names in execution order
-
-    Returns:
-        List of errors (empty if valid)
-    """
-    errors: list[str] = []
-
-    if not stages:
-        errors.append("Signal path is empty")
-        return errors
-
-    seen: set[str] = set()
-    for i, stage in enumerate(stages):
-        if stage in seen:
-            errors.append(
-                f"Circular dependency: '{stage}' appears multiple times at index {i}"
-            )
-        seen.add(stage)
-
-    return errors
-
-
-def generate_preset_toml(
-    name: str,
-    source: str = "headlines",
-    display: str = "terminal",
-    effects: list[str] | None = None,
-    viewport_width: int = 80,
-    viewport_height: int = 24,
-    camera: str = "vertical",
-    camera_speed: float = 1.0,
-    firehose_enabled: bool = False,
-) -> str:
-    """Generate a TOML preset skeleton with default values.
-
-    Args:
-        name: Preset name
-        source: Data source name
-        display: Display backend
-        effects: List of effect names
-        viewport_width: Viewport width in columns
-        viewport_height: Viewport height in rows
-        camera: Camera mode
-        camera_speed: Camera scroll speed
-        firehose_enabled: Enable firehose mode
-
-    Returns:
-        TOML string for the preset
-    """
-
-    if effects is None:
-        effects = ["fade", "hud"]
-
-    output = []
-    output.append(f"[presets.{name}]")
-    output.append(f'description = "Auto-generated preset: {name}"')
-    output.append(f'source = "{source}"')
-    output.append(f'display = "{display}"')
-    output.append(f'camera = "{camera}"')
-    output.append(f"effects = {effects}")
-    output.append(f"viewport_width = {viewport_width}")
-    output.append(f"viewport_height = {viewport_height}")
-    output.append(f"camera_speed = {camera_speed}")
-    output.append(f"firehose_enabled = {str(firehose_enabled).lower()}")
-
-    return "\n".join(output)

engine/pipeline/presets.py

@@ -1,182 +0,0 @@
-"""
-Pipeline presets - Pre-configured pipeline configurations.
-
-Provides PipelinePreset as a unified preset system.
-Presets can be loaded from TOML files (presets.toml) or defined in code.
-
-Loading order:
-1. Built-in presets.toml in the package
-2. User config ~/.config/mainline/presets.toml
-3. Local ./presets.toml (overrides earlier)
-"""
-
-from dataclasses import dataclass, field
-from typing import Any
-
-from engine.pipeline.params import PipelineParams
-
-
-def _load_toml_presets() -> dict[str, Any]:
-    """Load presets from TOML file."""
-    try:
-        from engine.pipeline.preset_loader import load_presets
-
-        return load_presets()
-    except Exception:
-        return {}
-
-
-# Pre-load TOML presets
-_YAML_PRESETS = _load_toml_presets()
-
-
-@dataclass
-class PipelinePreset:
-    """Pre-configured pipeline with stages and animation.
-
-    A PipelinePreset packages:
-    - Initial params: Starting configuration
-    - Stages: List of stage configurations to create
-
-    This is the new unified preset that works with the Pipeline class.
-    """
-
-    name: str
-    description: str = ""
-    source: str = "headlines"
-    display: str = "terminal"
-    camera: str = "scroll"
-    effects: list[str] = field(default_factory=list)
-    border: bool = False
-
-    def to_params(self) -> PipelineParams:
-        """Convert to PipelineParams."""
-        params = PipelineParams()
-        params.source = self.source
-        params.display = self.display
-        params.border = self.border
-        params.camera_mode = self.camera
-        params.effect_order = self.effects.copy()
-        return params
-
-    @classmethod
-    def from_yaml(cls, name: str, data: dict[str, Any]) -> "PipelinePreset":
-        """Create a PipelinePreset from YAML data."""
-        return cls(
-            name=name,
-            description=data.get("description", ""),
-            source=data.get("source", "headlines"),
-            display=data.get("display", "terminal"),
-            camera=data.get("camera", "vertical"),
-            effects=data.get("effects", []),
-            border=data.get("border", False),
-        )
-
-
-# Built-in presets
-DEMO_PRESET = PipelinePreset(
-    name="demo",
-    description="Demo mode with effect cycling and camera modes",
-    source="headlines",
-    display="pygame",
-    camera="scroll",
-    effects=["noise", "fade", "glitch", "firehose", "hud"],
-)
-
-POETRY_PRESET = PipelinePreset(
-    name="poetry",
-    description="Poetry feed with subtle effects",
-    source="poetry",
-    display="pygame",
-    camera="scroll",
-    effects=["fade", "hud"],
-)
-
-PIPELINE_VIZ_PRESET = PipelinePreset(
-    name="pipeline",
-    description="Pipeline visualization mode",
-    source="pipeline",
-    display="terminal",
-    camera="trace",
-    effects=["hud"],
-)
-
-WEBSOCKET_PRESET = PipelinePreset(
-    name="websocket",
-    description="WebSocket display mode",
-    source="headlines",
-    display="websocket",
-    camera="scroll",
-    effects=["noise", "fade", "glitch", "hud"],
-)
-
-SIXEL_PRESET = PipelinePreset(
-    name="sixel",
-    description="Sixel graphics display mode",
-    source="headlines",
-    display="sixel",
-    camera="scroll",
-    effects=["noise", "fade", "glitch", "hud"],
-)
-
-FIREHOSE_PRESET = PipelinePreset(
-    name="firehose",
-    description="High-speed firehose mode",
-    source="headlines",
-    display="pygame",
-    camera="scroll",
-    effects=["noise", "fade", "glitch", "firehose", "hud"],
-)
-
-
-# Build presets from YAML data
-def _build_presets() -> dict[str, PipelinePreset]:
-    """Build preset dictionary from all sources."""
-    result = {}
-
-    # Add YAML presets
-    yaml_presets = _YAML_PRESETS.get("presets", {})
-    for name, data in yaml_presets.items():
-        result[name] = PipelinePreset.from_yaml(name, data)
-
-    # Add built-in presets as fallback (if not in YAML)
-    builtins = {
-        "demo": DEMO_PRESET,
-        "poetry": POETRY_PRESET,
-        "pipeline": PIPELINE_VIZ_PRESET,
-        "websocket": WEBSOCKET_PRESET,
-        "sixel": SIXEL_PRESET,
-        "firehose": FIREHOSE_PRESET,
-    }
-
-    for name, preset in builtins.items():
-        if name not in result:
-            result[name] = preset
-
-    return result
-
-
-PRESETS: dict[str, PipelinePreset] = _build_presets()
-
-
-def get_preset(name: str) -> PipelinePreset | None:
-    """Get a preset by name."""
-    return PRESETS.get(name)
-
-
-def list_presets() -> list[str]:
-    """List all available preset names."""
-    return list(PRESETS.keys())
-
-
-def create_preset_from_params(
-    params: PipelineParams, name: str = "custom"
-) -> PipelinePreset:
-    """Create a preset from PipelineParams."""
-    return PipelinePreset(
-        name=name,
-        source=params.source,
-        display=params.display,
-        camera=params.camera_mode,
-        effects=params.effect_order.copy() if hasattr(params, "effect_order") else [],
-    )

engine/pipeline/registry.py

@@ -1,181 +0,0 @@
-"""
-Stage registry - Unified registration for all pipeline stages.
-
-Provides a single registry for sources, effects, displays, and cameras.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any, TypeVar
-
-from engine.pipeline.core import Stage
-
-if TYPE_CHECKING:
-    from engine.pipeline.core import Stage
-
-T = TypeVar("T")
-
-
-class StageRegistry:
-    """Unified registry for all pipeline stage types."""
-
-    _categories: dict[str, dict[str, type[Any]]] = {}
-    _discovered: bool = False
-    _instances: dict[str, Stage] = {}
-
-    @classmethod
-    def register(cls, category: str, stage_class: type[Any]) -> None:
-        """Register a stage class in a category.
-
-        Args:
-            category: Category name (source, effect, display, camera)
-            stage_class: Stage subclass to register
-        """
-        if category not in cls._categories:
-            cls._categories[category] = {}
-
-        key = getattr(stage_class, "__name__", stage_class.__class__.__name__)
-        cls._categories[category][key] = stage_class
-
-    @classmethod
-    def get(cls, category: str, name: str) -> type[Any] | None:
-        """Get a stage class by category and name."""
-        return cls._categories.get(category, {}).get(name)
-
-    @classmethod
-    def list(cls, category: str) -> list[str]:
-        """List all stage names in a category."""
-        return list(cls._categories.get(category, {}).keys())
-
-    @classmethod
-    def list_categories(cls) -> list[str]:
-        """List all registered categories."""
-        return list(cls._categories.keys())
-
-    @classmethod
-    def create(cls, category: str, name: str, **kwargs) -> Stage | None:
-        """Create a stage instance by category and name."""
-        stage_class = cls.get(category, name)
-        if stage_class:
-            return stage_class(**kwargs)
-        return None
-
-    @classmethod
-    def create_instance(cls, stage: Stage | type[Stage], **kwargs) -> Stage:
-        """Create an instance from a stage class or return as-is."""
-        if isinstance(stage, Stage):
-            return stage
-        if isinstance(stage, type) and issubclass(stage, Stage):
-            return stage(**kwargs)
-        raise TypeError(f"Expected Stage class or instance, got {type(stage)}")
-
-    @classmethod
-    def register_instance(cls, name: str, stage: Stage) -> None:
-        """Register a stage instance by name."""
-        cls._instances[name] = stage
-
-    @classmethod
-    def get_instance(cls, name: str) -> Stage | None:
-        """Get a registered stage instance by name."""
-        return cls._instances.get(name)
-
-
-def discover_stages() -> None:
-    """Auto-discover and register all stage implementations."""
-    if StageRegistry._discovered:
-        return
-
-    # Import and register all stage implementations
-    try:
-        from engine.data_sources.sources import (
-            HeadlinesDataSource,
-            PoetryDataSource,
-        )
-
-        StageRegistry.register("source", HeadlinesDataSource)
-        StageRegistry.register("source", PoetryDataSource)
-
-        StageRegistry._categories["source"]["headlines"] = HeadlinesDataSource
-        StageRegistry._categories["source"]["poetry"] = PoetryDataSource
-    except ImportError:
-        pass
-
-    # Register pipeline introspection source
-    try:
-        from engine.data_sources.pipeline_introspection import (
-            PipelineIntrospectionSource,
-        )
-
-        StageRegistry.register("source", PipelineIntrospectionSource)
-        StageRegistry._categories["source"]["pipeline-inspect"] = (
-            PipelineIntrospectionSource
-        )
-    except ImportError:
-        pass
-
-    try:
-        from engine.effects.types import EffectPlugin  # noqa: F401
-    except ImportError:
-        pass
-
-    # Register display stages
-    _register_display_stages()
-
-    StageRegistry._discovered = True
-
-
-def _register_display_stages() -> None:
-    """Register display backends as stages."""
-    try:
-        from engine.display import DisplayRegistry
-    except ImportError:
-        return
-
-    DisplayRegistry.initialize()
-
-    for backend_name in DisplayRegistry.list_backends():
-        factory = _DisplayStageFactory(backend_name)
-        StageRegistry._categories.setdefault("display", {})[backend_name] = factory
-
-
-class _DisplayStageFactory:
-    """Factory that creates DisplayStage instances for a specific backend."""
-
-    def __init__(self, backend_name: str):
-        self._backend_name = backend_name
-
-    def __call__(self):
-        from engine.display import DisplayRegistry
-        from engine.pipeline.adapters import DisplayStage
-
-        display = DisplayRegistry.create(self._backend_name)
-        if display is None:
-            raise RuntimeError(
-                f"Failed to create display backend: {self._backend_name}"
-            )
-        return DisplayStage(display, name=self._backend_name)
-
-    @property
-    def __name__(self) -> str:
-        return self._backend_name.capitalize() + "Stage"
-
-
-# Convenience functions
-def register_source(stage_class: type[Stage]) -> None:
-    """Register a source stage."""
-    StageRegistry.register("source", stage_class)
-
-
-def register_effect(stage_class: type[Stage]) -> None:
-    """Register an effect stage."""
-    StageRegistry.register("effect", stage_class)
-
-
-def register_display(stage_class: type[Stage]) -> None:
-    """Register a display stage."""
-    StageRegistry.register("display", stage_class)
-
-
-def register_camera(stage_class: type[Stage]) -> None:
-    """Register a camera stage."""
-    StageRegistry.register("camera", stage_class)

engine/render.py

@@ -1,6 +1,7 @@
-"""Block rendering core - Font loading, text rasterization, word-wrap, and headline assembly.
-
-Provides PIL font-based rendering to terminal half-block characters.
+"""
+OTF → terminal half-block rendering pipeline.
+Font loading, text rasterization, word-wrap, gradient coloring, headline block assembly.
+Depends on: config, terminal, sources, translate.
 """
 
 import random
@@ -11,51 +12,41 @@ from PIL import Image, ImageDraw, ImageFont
 
 from engine import config
 from engine.sources import NO_UPPER, SCRIPT_FONTS, SOURCE_LANGS
+from engine.terminal import RST
 from engine.translate import detect_location_language, translate_headline
 
+# ─── GRADIENT ─────────────────────────────────────────────
+# Left → right: white-hot leading edge fades to near-black
+GRAD_COLS = [
+    "\033[1;38;5;231m",  # white
+    "\033[1;38;5;195m",  # pale cyan-white
+    "\033[38;5;123m",  # bright cyan
+    "\033[38;5;118m",  # bright lime
+    "\033[38;5;82m",  # lime
+    "\033[38;5;46m",  # bright green
+    "\033[38;5;40m",  # green
+    "\033[38;5;34m",  # medium green
+    "\033[38;5;28m",  # dark green
+    "\033[38;5;22m",  # deep green
+    "\033[2;38;5;22m",  # dim deep green
+    "\033[2;38;5;235m",  # near black
+]
 
-def estimate_block_height(title: str, width: int, fnt=None) -> int:
-    """Estimate rendered block height without full PIL rendering.
-
-    Uses font bbox measurement to count wrapped lines, then computes:
-    height = num_lines * RENDER_H + (num_lines - 1) + 2
-
-    Args:
-        title: Headline text to measure
-        width: Terminal width in characters
-        fnt: Optional PIL font (uses default if None)
-
-    Returns:
-        Estimated height in terminal rows
-    """
-    if fnt is None:
-        fnt = font()
-    text = re.sub(r"\s+", " ", title.upper())
-    words = text.split()
-    lines = 0
-    cur = ""
-    for word in words:
-        test = f"{cur} {word}".strip() if cur else word
-        bbox = fnt.getbbox(test)
-        if bbox:
-            img_h = bbox[3] - bbox[1] + 8
-            pix_h = config.RENDER_H * 2
-            scale = pix_h / max(img_h, 1)
-            term_w = int((bbox[2] - bbox[0] + 8) * scale)
-        else:
-            term_w = 0
-        max_term_w = width - 4 - 4
-        if term_w > max_term_w and cur:
-            lines += 1
-            cur = word
-        else:
-            cur = test
-    if cur:
-        lines += 1
-    if lines == 0:
-        lines = 1
-    return lines * config.RENDER_H + max(0, lines - 1) + 2
-
+# Complementary sweep for queue messages (opposite hue family from ticker greens)
+MSG_GRAD_COLS = [
+    "\033[1;38;5;231m",  # white
+    "\033[1;38;5;225m",  # pale pink-white
+    "\033[38;5;219m",  # bright pink
+    "\033[38;5;213m",  # hot pink
+    "\033[38;5;207m",  # magenta
+    "\033[38;5;201m",  # bright magenta
+    "\033[38;5;165m",  # orchid-red
+    "\033[38;5;161m",  # ruby-magenta
+    "\033[38;5;125m",  # dark magenta
+    "\033[38;5;89m",  # deep maroon-magenta
+    "\033[2;38;5;89m",  # dim deep maroon-magenta
+    "\033[2;38;5;235m",  # near black
+]
 
 # ─── FONT LOADING ─────────────────────────────────────────
 _FONT_OBJ = None
@@ -198,22 +189,36 @@ def big_wrap(text, max_w, fnt=None):
     return out
 
 
+def lr_gradient(rows, offset=0.0, grad_cols=None):
+    """Color each non-space block character with a shifting left-to-right gradient."""
+    cols = grad_cols or GRAD_COLS
+    n = len(cols)
+    max_x = max((len(r.rstrip()) for r in rows if r.strip()), default=1)
+    out = []
+    for row in rows:
+        if not row.strip():
+            out.append(row)
+            continue
+        buf = []
+        for x, ch in enumerate(row):
+            if ch == " ":
+                buf.append(" ")
+            else:
+                shifted = (x / max(max_x - 1, 1) + offset) % 1.0
+                idx = min(round(shifted * (n - 1)), n - 1)
+                buf.append(f"{cols[idx]}{ch}{RST}")
+        out.append("".join(buf))
+    return out
+
+
+def lr_gradient_opposite(rows, offset=0.0):
+    """Complementary (opposite wheel) gradient used for queue message panels."""
+    return lr_gradient(rows, offset, MSG_GRAD_COLS)
+
+
 # ─── HEADLINE BLOCK ASSEMBLY ─────────────────────────────
 def make_block(title, src, ts, w):
-    """Render a headline into a content block with color.
-
-    Args:
-        title: Headline text to render
-        src: Source identifier (for metadata)
-        ts: Timestamp string (for metadata)
-        w: Width constraint in terminal characters
-
-    Returns:
-        tuple: (content_lines, color_code, meta_row_index)
-            - content_lines: List of rendered text lines
-            - color_code: ANSI color code for display
-            - meta_row_index: Row index of metadata line
-    """
+    """Render a headline into a content block with color."""
     target_lang = (
         (SOURCE_LANGS.get(src) or detect_location_language(title))
         if config.MODE == "news"

engine/render/__init__.py

@@ -1,37 +0,0 @@
-"""Modern block rendering system - OTF font to terminal half-block conversion.
-
-This module provides the core rendering capabilities for big block letters
-and styled text output using PIL fonts and ANSI terminal rendering.
-
-Exports:
-    - make_block: Render a headline into a content block with color
-    - big_wrap: Word-wrap text and render with OTF font
-    - render_line: Render a line of text as terminal rows using half-blocks
-    - font_for_lang: Get appropriate font for a language
-    - clear_font_cache: Reset cached font objects
-    - lr_gradient: Color block characters with left-to-right gradient
-    - lr_gradient_opposite: Complementary gradient coloring
-"""
-
-from engine.render.blocks import (
-    big_wrap,
-    clear_font_cache,
-    font_for_lang,
-    list_font_faces,
-    load_font_face,
-    make_block,
-    render_line,
-)
-from engine.render.gradient import lr_gradient, lr_gradient_opposite
-
-__all__ = [
-    "big_wrap",
-    "clear_font_cache",
-    "font_for_lang",
-    "list_font_faces",
-    "load_font_face",
-    "lr_gradient",
-    "lr_gradient_opposite",
-    "make_block",
-    "render_line",
-]

engine/render/gradient.py

@@ -1,82 +0,0 @@
-"""Gradient coloring for rendered block characters.
-
-Provides left-to-right and complementary gradient effects for terminal display.
-"""
-
-from engine.terminal import RST
-
-# Left → right: white-hot leading edge fades to near-black
-GRAD_COLS = [
-    "\033[1;38;5;231m",  # white
-    "\033[1;38;5;195m",  # pale cyan-white
-    "\033[38;5;123m",  # bright cyan
-    "\033[38;5;118m",  # bright lime
-    "\033[38;5;82m",  # lime
-    "\033[38;5;46m",  # bright green
-    "\033[38;5;40m",  # green
-    "\033[38;5;34m",  # medium green
-    "\033[38;5;28m",  # dark green
-    "\033[38;5;22m",  # deep green
-    "\033[2;38;5;22m",  # dim deep green
-    "\033[2;38;5;235m",  # near black
-]
-
-# Complementary sweep for queue messages (opposite hue family from ticker greens)
-MSG_GRAD_COLS = [
-    "\033[1;38;5;231m",  # white
-    "\033[1;38;5;225m",  # pale pink-white
-    "\033[38;5;219m",  # bright pink
-    "\033[38;5;213m",  # hot pink
-    "\033[38;5;207m",  # magenta
-    "\033[38;5;201m",  # bright magenta
-    "\033[38;5;165m",  # orchid-red
-    "\033[38;5;161m",  # ruby-magenta
-    "\033[38;5;125m",  # dark magenta
-    "\033[38;5;89m",  # deep maroon-magenta
-    "\033[2;38;5;89m",  # dim deep maroon-magenta
-    "\033[2;38;5;235m",  # near black
-]
-
-
-def lr_gradient(rows, offset=0.0, grad_cols=None):
-    """Color each non-space block character with a shifting left-to-right gradient.
-
-    Args:
-        rows: List of text lines with block characters
-        offset: Gradient offset (0.0-1.0) for animation
-        grad_cols: List of ANSI color codes (default: GRAD_COLS)
-
-    Returns:
-        List of lines with gradient coloring applied
-    """
-    cols = grad_cols or GRAD_COLS
-    n = len(cols)
-    max_x = max((len(r.rstrip()) for r in rows if r.strip()), default=1)
-    out = []
-    for row in rows:
-        if not row.strip():
-            out.append(row)
-            continue
-        buf = []
-        for x, ch in enumerate(row):
-            if ch == " ":
-                buf.append(" ")
-            else:
-                shifted = (x / max(max_x - 1, 1) + offset) % 1.0
-                idx = min(round(shifted * (n - 1)), n - 1)
-                buf.append(f"{cols[idx]}{ch}{RST}")
-        out.append("".join(buf))
-    return out
-
-
-def lr_gradient_opposite(rows, offset=0.0):
-    """Complementary (opposite wheel) gradient used for queue message panels.
-
-    Args:
-        rows: List of text lines with block characters
-        offset: Gradient offset (0.0-1.0) for animation
-
-    Returns:
-        List of lines with complementary gradient coloring applied
-    """
-    return lr_gradient(rows, offset, MSG_GRAD_COLS)

engine/scroll.py

@@ -0,0 +1,141 @@
+"""
+Render engine — ticker content, scroll motion, message panel, and firehose overlay.
+Orchestrates viewport, frame timing, and layers.
+"""
+
+import random
+import time
+
+from engine import config
+from engine.display import (
+    Display,
+    TerminalDisplay,
+)
+from engine.display import (
+    get_monitor as _get_display_monitor,
+)
+from engine.frame import calculate_scroll_step
+from engine.layers import (
+    apply_glitch,
+    process_effects,
+    render_firehose,
+    render_message_overlay,
+    render_ticker_zone,
+)
+from engine.viewport import th, tw
+
+USE_EFFECT_CHAIN = True
+
+
+def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
+    """Main render loop with four layers: message, ticker, scroll motion, firehose."""
+    if display is None:
+        display = TerminalDisplay()
+    random.shuffle(items)
+    pool = list(items)
+    seen = set()
+    queued = 0
+
+    time.sleep(0.5)
+    w, h = tw(), th()
+    display.init(w, h)
+    display.clear()
+    fh = config.FIREHOSE_H if config.FIREHOSE else 0
+    ticker_view_h = h - fh
+    GAP = 3
+    scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, ticker_view_h)
+
+    active = []
+    scroll_cam = 0
+    ticker_next_y = ticker_view_h
+    noise_cache = {}
+    scroll_motion_accum = 0.0
+    msg_cache = (None, None)
+    frame_number = 0
+
+    while True:
+        if queued >= config.HEADLINE_LIMIT and not active:
+            break
+
+        t0 = time.monotonic()
+        w, h = tw(), th()
+        fh = config.FIREHOSE_H if config.FIREHOSE else 0
+        ticker_view_h = h - fh
+        scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, ticker_view_h)
+
+        msg = ntfy_poller.get_active_message()
+        msg_overlay, msg_cache = render_message_overlay(msg, w, h, msg_cache)
+
+        buf = []
+        ticker_h = ticker_view_h
+
+        scroll_motion_accum += config.FRAME_DT
+        while scroll_motion_accum >= scroll_step_interval:
+            scroll_motion_accum -= scroll_step_interval
+            scroll_cam += 1
+
+            while (
+                ticker_next_y < scroll_cam + ticker_view_h + 10
+                and queued < config.HEADLINE_LIMIT
+            ):
+                from engine.effects import next_headline
+                from engine.render import make_block
+
+                t, src, ts = next_headline(pool, items, seen)
+                ticker_content, hc, midx = make_block(t, src, ts, w)
+                active.append((ticker_content, hc, ticker_next_y, midx))
+                ticker_next_y += len(ticker_content) + GAP
+                queued += 1
+
+            active = [
+                (c, hc, by, mi) for c, hc, by, mi in active if by + len(c) > scroll_cam
+            ]
+            for k in list(noise_cache):
+                if k < scroll_cam:
+                    del noise_cache[k]
+
+        grad_offset = (time.monotonic() * config.GRAD_SPEED) % 1.0
+        ticker_buf_start = len(buf)
+
+        ticker_buf, noise_cache = render_ticker_zone(
+            active, scroll_cam, ticker_h, w, noise_cache, grad_offset
+        )
+        buf.extend(ticker_buf)
+
+        mic_excess = mic_monitor.excess
+        render_start = time.perf_counter()
+
+        if USE_EFFECT_CHAIN:
+            buf = process_effects(
+                buf,
+                w,
+                h,
+                scroll_cam,
+                ticker_h,
+                mic_excess,
+                grad_offset,
+                frame_number,
+                msg is not None,
+                items,
+            )
+        else:
+            buf = apply_glitch(buf, ticker_buf_start, mic_excess, w)
+            firehose_buf = render_firehose(items, w, fh, h)
+            buf.extend(firehose_buf)
+
+        if msg_overlay:
+            buf.extend(msg_overlay)
+
+        render_elapsed = (time.perf_counter() - render_start) * 1000
+        monitor = _get_display_monitor()
+        if monitor:
+            chars = sum(len(line) for line in buf)
+            monitor.record_effect("render", render_elapsed, chars, chars)
+
+        display.show(buf)
+
+        elapsed = time.monotonic() - t0
+        time.sleep(max(0, config.FRAME_DT - elapsed))
+        frame_number += 1
+
+    display.cleanup()

engine/sensors/__init__.py

@@ -1,203 +0,0 @@
-"""
-Sensor framework - PureData-style real-time input system.
-
-Sensors are data sources that emit values over time, similar to how
-PureData objects emit signals. Effects can bind to sensors to modulate
-their parameters dynamically.
-
-Architecture:
-- Sensor: Base class for all sensors (mic, camera, ntfy, OSC, etc.)
-- SensorRegistry: Global registry for sensor discovery
-- SensorStage: Pipeline stage wrapper for sensors
-- Effect param_bindings: Declarative sensor-to-param routing
-
-Example:
-    class GlitchEffect(EffectPlugin):
-        param_bindings = {
-            "intensity": {"sensor": "mic", "transform": "linear"},
-        }
-
-This binds the mic sensor to the glitch intensity parameter.
-"""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from engine.pipeline.core import PipelineContext
-
-
-@dataclass
-class SensorValue:
-    """A sensor reading with metadata."""
-
-    sensor_name: str
-    value: float
-    timestamp: float
-    unit: str = ""
-
-
-class Sensor(ABC):
-    """Abstract base class for sensors.
-
-    Sensors are real-time data sources that emit values. They can be:
-    - Physical: mic, camera, joystick, MIDI, OSC
-    - Virtual: ntfy, timer, random, noise
-
-    Each sensor has a name and emits SensorValue objects.
-    """
-
-    name: str
-    unit: str = ""
-
-    @property
-    def available(self) -> bool:
-        """Whether the sensor is currently available."""
-        return True
-
-    @abstractmethod
-    def read(self) -> SensorValue | None:
-        """Read current sensor value.
-
-        Returns:
-            SensorValue if available, None if sensor is not ready.
-        """
-        ...
-
-    @abstractmethod
-    def start(self) -> bool:
-        """Start the sensor.
-
-        Returns:
-            True if started successfully.
-        """
-        ...
-
-    @abstractmethod
-    def stop(self) -> None:
-        """Stop the sensor and release resources."""
-        ...
-
-
-class SensorRegistry:
-    """Global registry for sensors.
-
-    Provides:
-    - Registration of sensor instances
-    - Lookup by name
-    - Global start/stop
-    """
-
-    _sensors: dict[str, Sensor] = {}
-    _started: bool = False
-
-    @classmethod
-    def register(cls, sensor: Sensor) -> None:
-        """Register a sensor instance."""
-        cls._sensors[sensor.name] = sensor
-
-    @classmethod
-    def get(cls, name: str) -> Sensor | None:
-        """Get a sensor by name."""
-        return cls._sensors.get(name)
-
-    @classmethod
-    def list_sensors(cls) -> list[str]:
-        """List all registered sensor names."""
-        return list(cls._sensors.keys())
-
-    @classmethod
-    def start_all(cls) -> bool:
-        """Start all sensors.
-
-        Returns:
-            True if all sensors started successfully.
-        """
-        if cls._started:
-            return True
-
-        all_started = True
-        for sensor in cls._sensors.values():
-            if sensor.available and not sensor.start():
-                all_started = False
-
-        cls._started = all_started
-        return all_started
-
-    @classmethod
-    def stop_all(cls) -> None:
-        """Stop all sensors."""
-        for sensor in cls._sensors.values():
-            sensor.stop()
-        cls._started = False
-
-    @classmethod
-    def read_all(cls) -> dict[str, float]:
-        """Read all sensor values.
-
-        Returns:
-            Dict mapping sensor name to current value.
-        """
-        result = {}
-        for name, sensor in cls._sensors.items():
-            value = sensor.read()
-            if value:
-                result[name] = value.value
-        return result
-
-
-class SensorStage:
-    """Pipeline stage wrapper for sensors.
-
-    Provides sensor data to the pipeline context.
-    Sensors don't transform data - they inject sensor values into context.
-    """
-
-    def __init__(self, sensor: Sensor, name: str | None = None):
-        self._sensor = sensor
-        self.name = name or sensor.name
-        self.category = "sensor"
-        self.optional = True
-
-    @property
-    def stage_type(self) -> str:
-        return "sensor"
-
-    @property
-    def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.ANY}
-
-    @property
-    def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
-
-        return {DataType.ANY}
-
-    @property
-    def capabilities(self) -> set[str]:
-        return {f"sensor.{self.name}"}
-
-    @property
-    def dependencies(self) -> set[str]:
-        return set()
-
-    def init(self, ctx: "PipelineContext") -> bool:
-        return self._sensor.start()
-
-    def process(self, data: Any, ctx: "PipelineContext") -> Any:
-        value = self._sensor.read()
-        if value:
-            ctx.set_state(f"sensor.{self.name}", value.value)
-            ctx.set_state(f"sensor.{self.name}.full", value)
-        return data
-
-    def cleanup(self) -> None:
-        self._sensor.stop()
-
-
-def create_sensor_stage(sensor: Sensor, name: str | None = None) -> SensorStage:
-    """Create a pipeline stage from a sensor."""
-    return SensorStage(sensor, name)

engine/sensors/mic.py

@@ -1,145 +0,0 @@
-"""
-Mic sensor - audio input as a pipeline sensor.
-
-Self-contained implementation that handles audio input directly,
-with graceful degradation if sounddevice is unavailable.
-"""
-
-import atexit
-import time
-from collections.abc import Callable
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Any
-
-try:
-    import numpy as np
-    import sounddevice as sd
-
-    _HAS_AUDIO = True
-except Exception:
-    np = None  # type: ignore
-    sd = None  # type: ignore
-    _HAS_AUDIO = False
-
-
-from engine.events import MicLevelEvent
-from engine.sensors import Sensor, SensorRegistry, SensorValue
-
-
-@dataclass
-class AudioConfig:
-    """Configuration for audio input."""
-
-    threshold_db: float = 50.0
-    sample_rate: float = 44100.0
-    block_size: int = 1024
-
-
-class MicSensor(Sensor):
-    """Microphone sensor for pipeline integration.
-
-    Self-contained implementation with graceful degradation.
-    No external dependencies required - works with or without sounddevice.
-    """
-
-    def __init__(self, threshold_db: float = 50.0, name: str = "mic"):
-        self.name = name
-        self.unit = "dB"
-        self._config = AudioConfig(threshold_db=threshold_db)
-        self._db: float = -99.0
-        self._stream: Any = None
-        self._subscribers: list[Callable[[MicLevelEvent], None]] = []
-
-    @property
-    def available(self) -> bool:
-        """Check if audio input is available."""
-        return _HAS_AUDIO and self._stream is not None
-
-    def start(self) -> bool:
-        """Start the microphone stream."""
-        if not _HAS_AUDIO or sd is None:
-            return False
-
-        try:
-            self._stream = sd.InputStream(
-                samplerate=self._config.sample_rate,
-                blocksize=self._config.block_size,
-                channels=1,
-                callback=self._audio_callback,
-            )
-            self._stream.start()
-            atexit.register(self.stop)
-            return True
-        except Exception:
-            return False
-
-    def stop(self) -> None:
-        """Stop the microphone stream."""
-        if self._stream:
-            try:
-                self._stream.stop()
-                self._stream.close()
-            except Exception:
-                pass
-            self._stream = None
-
-    def _audio_callback(self, indata, frames, time_info, status) -> None:
-        """Process audio data from sounddevice."""
-        if not _HAS_AUDIO or np is None:
-            return
-
-        rms = np.sqrt(np.mean(indata**2))
-        if rms > 0:
-            db = 20 * np.log10(rms)
-        else:
-            db = -99.0
-
-        self._db = db
-
-        excess = max(0.0, db - self._config.threshold_db)
-        event = MicLevelEvent(
-            db_level=db, excess_above_threshold=excess, timestamp=datetime.now()
-        )
-        self._emit(event)
-
-    def _emit(self, event: MicLevelEvent) -> None:
-        """Emit event to all subscribers."""
-        for callback in self._subscribers:
-            try:
-                callback(event)
-            except Exception:
-                pass
-
-    def subscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
-        """Subscribe to mic level events."""
-        if callback not in self._subscribers:
-            self._subscribers.append(callback)
-
-    def unsubscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
-        """Unsubscribe from mic level events."""
-        if callback in self._subscribers:
-            self._subscribers.remove(callback)
-
-    def read(self) -> SensorValue | None:
-        """Read current mic level as sensor value."""
-        if not self.available:
-            return None
-
-        excess = max(0.0, self._db - self._config.threshold_db)
-        return SensorValue(
-            sensor_name=self.name,
-            value=excess,
-            timestamp=time.time(),
-            unit=self.unit,
-        )
-
-
-def register_mic_sensor() -> None:
-    """Register the mic sensor with the global registry."""
-    sensor = MicSensor()
-    SensorRegistry.register(sensor)
-
-
-# Auto-register when imported
-register_mic_sensor()

engine/sensors/oscillator.py

@@ -1,161 +0,0 @@
-"""
-Oscillator sensor - Modular synth-style oscillator as a pipeline sensor.
-
-Provides various waveforms that can be:
-1. Self-driving (phase accumulates over time)
-2. Sensor-driven (phase modulated by external sensor)
-
-Built-in waveforms:
-- sine: Pure sine wave
-- square: Square wave (0 to 1)
-- sawtooth: Rising sawtooth (0 to 1, wraps)
-- triangle: Triangle wave (0 to 1 to 0)
-- noise: Random values (0 to 1)
-
-Example usage:
-    osc = OscillatorSensor(waveform="sine", frequency=0.5)
-    # Or driven by mic sensor:
-    osc = OscillatorSensor(waveform="sine", frequency=1.0, input_sensor="mic")
-"""
-
-import math
-import random
-import time
-from enum import Enum
-
-from engine.sensors import Sensor, SensorRegistry, SensorValue
-
-
-class Waveform(Enum):
-    """Built-in oscillator waveforms."""
-
-    SINE = "sine"
-    SQUARE = "square"
-    SAWTOOTH = "sawtooth"
-    TRIANGLE = "triangle"
-    NOISE = "noise"
-
-
-class OscillatorSensor(Sensor):
-    """Oscillator sensor that generates periodic or random values.
-
-    Can run in two modes:
-    - Self-driving: phase accumulates based on frequency
-    - Sensor-driven: phase modulated by external sensor value
-    """
-
-    WAVEFORMS = {
-        "sine": lambda p: (math.sin(2 * math.pi * p) + 1) / 2,
-        "square": lambda p: 1.0 if (p % 1.0) < 0.5 else 0.0,
-        "sawtooth": lambda p: p % 1.0,
-        "triangle": lambda p: 2 * abs(2 * (p % 1.0) - 1) - 1,
-        "noise": lambda _: random.random(),
-    }
-
-    def __init__(
-        self,
-        name: str = "osc",
-        waveform: str = "sine",
-        frequency: float = 1.0,
-        input_sensor: str | None = None,
-        input_scale: float = 1.0,
-    ):
-        """Initialize oscillator sensor.
-
-        Args:
-            name: Sensor name
-            waveform: Waveform type (sine, square, sawtooth, triangle, noise)
-            frequency: Frequency in Hz (self-driving mode)
-            input_sensor: Optional sensor name to drive phase
-            input_scale: Scale factor for input sensor
-        """
-        self.name = name
-        self.unit = ""
-        self._waveform = waveform
-        self._frequency = frequency
-        self._input_sensor = input_sensor
-        self._input_scale = input_scale
-        self._phase = 0.0
-        self._start_time = time.time()
-
-    @property
-    def available(self) -> bool:
-        return True
-
-    @property
-    def waveform(self) -> str:
-        return self._waveform
-
-    @waveform.setter
-    def waveform(self, value: str) -> None:
-        if value not in self.WAVEFORMS:
-            raise ValueError(f"Unknown waveform: {value}")
-        self._waveform = value
-
-    @property
-    def frequency(self) -> float:
-        return self._frequency
-
-    @frequency.setter
-    def frequency(self, value: float) -> None:
-        self._frequency = max(0.0, value)
-
-    def start(self) -> bool:
-        self._phase = 0.0
-        self._start_time = time.time()
-        return True
-
-    def stop(self) -> None:
-        pass
-
-    def _get_input_value(self) -> float:
-        """Get value from input sensor if configured."""
-        if self._input_sensor:
-            from engine.sensors import SensorRegistry
-
-            sensor = SensorRegistry.get(self._input_sensor)
-            if sensor:
-                reading = sensor.read()
-                if reading:
-                    return reading.value * self._input_scale
-        return 0.0
-
-    def read(self) -> SensorValue | None:
-        current_time = time.time()
-        elapsed = current_time - self._start_time
-
-        if self._input_sensor:
-            input_val = self._get_input_value()
-            phase_increment = (self._frequency * elapsed) + input_val
-        else:
-            phase_increment = self._frequency * elapsed
-
-        self._phase += phase_increment
-
-        waveform_fn = self.WAVEFORMS.get(self._waveform)
-        if waveform_fn is None:
-            return None
-
-        value = waveform_fn(self._phase)
-        value = max(0.0, min(1.0, value))
-
-        return SensorValue(
-            sensor_name=self.name,
-            value=value,
-            timestamp=current_time,
-            unit=self.unit,
-        )
-
-    def set_waveform(self, waveform: str) -> None:
-        """Change waveform at runtime."""
-        self.waveform = waveform
-
-    def set_frequency(self, frequency: float) -> None:
-        """Change frequency at runtime."""
-        self.frequency = frequency
-
-
-def register_oscillator_sensor(name: str = "osc", **kwargs) -> None:
-    """Register an oscillator sensor with the global registry."""
-    sensor = OscillatorSensor(name=name, **kwargs)
-    SensorRegistry.register(sensor)

engine/sensors/pipeline_metrics.py

@@ -1,114 +0,0 @@
-"""
-Pipeline metrics sensor - Exposes pipeline performance data as sensor values.
-
-This sensor reads metrics from a Pipeline instance and provides them
-as sensor values that can drive effect parameters.
-
-Example:
-    sensor = PipelineMetricsSensor(pipeline)
-    sensor.read()  # Returns SensorValue with total_ms, fps, etc.
-"""
-
-from typing import TYPE_CHECKING
-
-from engine.sensors import Sensor, SensorValue
-
-if TYPE_CHECKING:
-    from engine.pipeline.controller import Pipeline
-
-
-class PipelineMetricsSensor(Sensor):
-    """Sensor that reads metrics from a Pipeline instance.
-
-    Provides real-time performance data:
-    - total_ms: Total frame time in milliseconds
-    - fps: Calculated frames per second
-    - stage_timings: Dict of stage name -> duration_ms
-
-    Can be bound to effect parameters for reactive visuals.
-    """
-
-    def __init__(self, pipeline: "Pipeline | None" = None, name: str = "pipeline"):
-        self._pipeline = pipeline
-        self.name = name
-        self.unit = "ms"
-        self._last_values: dict[str, float] = {
-            "total_ms": 0.0,
-            "fps": 0.0,
-            "avg_ms": 0.0,
-            "min_ms": 0.0,
-            "max_ms": 0.0,
-        }
-
-    @property
-    def available(self) -> bool:
-        return self._pipeline is not None
-
-    def set_pipeline(self, pipeline: "Pipeline") -> None:
-        """Set or update the pipeline to read metrics from."""
-        self._pipeline = pipeline
-
-    def read(self) -> SensorValue | None:
-        """Read current metrics from the pipeline."""
-        if not self._pipeline:
-            return None
-
-        try:
-            metrics = self._pipeline.get_metrics_summary()
-        except Exception:
-            return None
-
-        if not metrics or "error" in metrics:
-            return None
-
-        self._last_values["total_ms"] = metrics.get("total_ms", 0.0)
-        self._last_values["fps"] = metrics.get("fps", 0.0)
-        self._last_values["avg_ms"] = metrics.get("avg_ms", 0.0)
-        self._last_values["min_ms"] = metrics.get("min_ms", 0.0)
-        self._last_values["max_ms"] = metrics.get("max_ms", 0.0)
-
-        # Provide total_ms as primary value (for LFO-style effects)
-        return SensorValue(
-            sensor_name=self.name,
-            value=self._last_values["total_ms"],
-            timestamp=0.0,
-            unit=self.unit,
-        )
-
-    def get_stage_timing(self, stage_name: str) -> float:
-        """Get timing for a specific stage."""
-        if not self._pipeline:
-            return 0.0
-        try:
-            metrics = self._pipeline.get_metrics_summary()
-            stages = metrics.get("stages", {})
-            return stages.get(stage_name, {}).get("avg_ms", 0.0)
-        except Exception:
-            return 0.0
-
-    def get_all_timings(self) -> dict[str, float]:
-        """Get all stage timings as a dict."""
-        if not self._pipeline:
-            return {}
-        try:
-            metrics = self._pipeline.get_metrics_summary()
-            return metrics.get("stages", {})
-        except Exception:
-            return {}
-
-    def get_frame_history(self) -> list[float]:
-        """Get historical frame times for sparklines."""
-        if not self._pipeline:
-            return []
-        try:
-            return self._pipeline.get_frame_times()
-        except Exception:
-            return []
-
-    def start(self) -> bool:
-        """Start the sensor (no-op for read-only metrics)."""
-        return True
-
-    def stop(self) -> None:
-        """Stop the sensor (no-op for read-only metrics)."""
-        pass

hk.pkl

@@ -22,9 +22,6 @@ hooks {
                 prefix = "uv run"
                 check = "ruff check engine/ tests/"
             }
-            ["benchmark"] {
-                check = "uv run python -m engine.benchmark --hook --displays null --iterations 20"
-            }
         }
     }
 }

kitty_test.py

@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-"""Test script for Kitty graphics display."""
-
-import sys
-
-
-def test_kitty_simple():
-    """Test simple Kitty graphics output with embedded PNG."""
-    import base64
-
-    # Minimal 1x1 red pixel PNG (pre-encoded)
-    # This is a tiny valid PNG with a red pixel
-    png_red_1x1 = (
-        b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00"
-        b"\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde"
-        b"\x00\x00\x00\x0cIDATx\x9cc\xf8\xcf\xc0\x00\x00\x00"
-        b"\x03\x00\x01\x00\x05\xfe\xd4\x00\x00\x00\x00IEND\xaeB`\x82"
-    )
-
-    encoded = base64.b64encode(png_red_1x1).decode("ascii")
-
-    graphic = f"\x1b_Gf=100,t=d,s=1,v=1,c=1,r=1;{encoded}\x1b\\"
-    sys.stdout.buffer.write(graphic.encode("utf-8"))
-    sys.stdout.flush()
-
-    print("\n[If you see a red dot above, Kitty graphics is working!]")
-    print("[If you see nothing or garbage, it's not working]")
-
-
-if __name__ == "__main__":
-    test_kitty_simple()

mise.toml

@@ -5,84 +5,40 @@ pkl = "latest"
 
 [tasks]
 # =====================
-# Testing
+# Development
 # =====================
 
 test = "uv run pytest"
-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
-# =====================
+test-v = "uv run pytest -v"
+test-cov = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html"
+test-cov-open = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html && open htmlcov/index.html"
 
 lint = "uv run ruff check engine/ mainline.py"
 lint-fix = "uv run ruff check --fix engine/ mainline.py"
 format = "uv run ruff format engine/ mainline.py"
 
 # =====================
-# Runtime Modes
+# Runtime
 # =====================
 
 run = "uv run mainline.py"
 run-poetry = "uv run mainline.py --poetry"
 run-firehose = "uv run mainline.py --firehose"
 
-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-kitty = { run = "uv run mainline.py --display kitty", depends = ["sync-all"] }
-run-pygame = { run = "uv run mainline.py --display pygame", 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"] }
-
-# =====================
-# Pipeline Architecture (unified Stage-based)
-# =====================
-
-run-pipeline = { run = "uv run mainline.py --pipeline --display pygame", depends = ["sync-all"] }
-run-pipeline-demo = { run = "uv run mainline.py --pipeline --pipeline-preset demo --display pygame", depends = ["sync-all"] }
-run-pipeline-poetry = { run = "uv run mainline.py --pipeline --pipeline-preset poetry --display pygame", depends = ["sync-all"] }
-run-pipeline-websocket = { run = "uv run mainline.py --pipeline --pipeline-preset websocket", depends = ["sync-all"] }
-run-pipeline-firehose = { run = "uv run mainline.py --pipeline --pipeline-preset firehose --display pygame", depends = ["sync-all"] }
-
-# =====================
-# Presets (Animation-controlled modes)
-# =====================
-
-run-preset-demo = { run = "uv run mainline.py --preset demo --display pygame", depends = ["sync-all"] }
-run-preset-border-test = { run = "uv run mainline.py --preset border-test --display terminal", depends = ["sync-all"] }
-run-preset-pipeline-inspect = { run = "uv run mainline.py --preset pipeline-inspect --display terminal", depends = ["sync-all"] }
+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"
 
 # =====================
 # Command & Control
 # =====================
 
 cmd = "uv run cmdline.py"
-cmd-stats = { run = "uv run cmdline.py -w \"/effects stats\"", depends = ["sync-all"] }
+cmd-stats = "bash -c 'uv run cmdline.py -w \"/effects stats\"';:"
 
-# =====================
-# 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)
+# Initialize ntfy topics (warm up before first use - also done automatically by mainline)
 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
 # =====================
@@ -90,20 +46,24 @@ daemon-restart = "mise run daemon-stop && sleep 2 && mise run daemon"
 sync = "uv sync"
 sync-all = "uv sync --all-extras"
 install = "mise run sync"
-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"] }
+install-dev = "mise run sync && uv sync --group dev"
+
+bootstrap = "uv sync && uv run mainline.py --help"
 
 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 = { run = "mise run topics-init && mise run lint && mise run test-cov", depends = ["topics-init", "lint", "test-cov"] }
+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"
 
 # =====================
 # Git Hooks (via hk)
 # =====================
 
-pre-commit = "hk run pre-commit"
+pre-commit = "hk run pre-commit"

presets.toml

@@ -1,117 +0,0 @@
-# Mainline Presets Configuration
-# Human- and machine-readable preset definitions
-#
-# Format: TOML
-# Usage: mainline --preset <name>
-#
-# Built-in presets can be overridden by user presets in:
-#   - ~/.config/mainline/presets.toml
-#   - ./presets.toml (local override)
-
-[presets.demo]
-description = "Demo mode with effect cycling and camera modes"
-source = "headlines"
-display = "pygame"
-camera = "scroll"
-effects = ["noise", "fade", "glitch", "firehose"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 1.0
-firehose_enabled = true
-
-[presets.poetry]
-description = "Poetry feed with subtle effects"
-source = "poetry"
-display = "pygame"
-camera = "scroll"
-effects = ["fade"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 0.5
-
-[presets.border-test]
-description = "Test border rendering with empty buffer"
-source = "empty"
-display = "terminal"
-camera = "scroll"
-effects = ["border"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 1.0
-firehose_enabled = false
-border = false
-
-[presets.websocket]
-description = "WebSocket display mode"
-source = "headlines"
-display = "websocket"
-camera = "scroll"
-effects = ["noise", "fade", "glitch"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 1.0
-firehose_enabled = false
-
-[presets.sixel]
-description = "Sixel graphics display mode"
-source = "headlines"
-display = "sixel"
-camera = "scroll"
-effects = ["noise", "fade", "glitch"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 1.0
-firehose_enabled = false
-
-[presets.firehose]
-description = "High-speed firehose mode"
-source = "headlines"
-display = "pygame"
-camera = "scroll"
-effects = ["noise", "fade", "glitch", "firehose"]
-viewport_width = 80
-viewport_height = 24
-camera_speed = 2.0
-firehose_enabled = true
-
-[presets.pipeline-inspect]
-description = "Live pipeline introspection with DAG and performance metrics"
-source = "pipeline-inspect"
-display = "pygame"
-camera = "scroll"
-effects = ["crop"]
-viewport_width = 100
-viewport_height = 35
-camera_speed = 0.3
-firehose_enabled = false
-
-# Sensor configuration (for future use with param bindings)
-[sensors.mic]
-enabled = false
-threshold_db = 50.0
-
-[sensors.oscillator]
-enabled = false
-waveform = "sine"
-frequency = 1.0
-
-# Effect configurations
-[effect_configs.noise]
-enabled = true
-intensity = 1.0
-
-[effect_configs.fade]
-enabled = true
-intensity = 1.0
-
-[effect_configs.glitch]
-enabled = true
-intensity = 0.5
-
-[effect_configs.firehose]
-enabled = true
-intensity = 1.0
-
-[effect_configs.hud]
-enabled = true
-intensity = 1.0

pyproject.toml

@@ -23,7 +23,6 @@ dependencies = [
     "feedparser>=6.0.0",
     "Pillow>=10.0.0",
     "pyright>=1.1.408",
-    "numpy>=1.24.0",
 ]
 
 [project.optional-dependencies]
@@ -31,21 +30,8 @@ mic = [
     "sounddevice>=0.4.0",
     "numpy>=1.24.0",
 ]
-websocket = [
-    "websockets>=12.0",
-]
-sixel = [
-    "Pillow>=10.0.0",
-]
-pygame = [
-    "pygame>=2.0.0",
-]
-browser = [
-    "playwright>=1.40.0",
-]
 dev = [
     "pytest>=8.0.0",
-    "pytest-benchmark>=4.0.0",
     "pytest-cov>=4.1.0",
     "pytest-mock>=3.12.0",
     "ruff>=0.1.0",
@@ -61,7 +47,6 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "pytest>=8.0.0",
-    "pytest-benchmark>=4.0.0",
     "pytest-cov>=4.1.0",
     "pytest-mock>=3.12.0",
     "ruff>=0.1.0",
@@ -76,12 +61,6 @@ addopts = [
     "--tb=short",
     "-v",
 ]
-markers = [
-    "benchmark: marks tests as performance benchmarks (may be slow)",
-    "e2e: marks tests as end-to-end tests (require network/display)",
-    "integration: marks tests as integration tests (require external services)",
-    "ntfy: marks tests that require ntfy service",
-]
 filterwarnings = [
     "ignore::DeprecationWarning",
 ]

tests/conftest.py

@@ -1,36 +0,0 @@
-"""
-Pytest configuration for mainline.
-"""
-
-import pytest
-
-
-def pytest_configure(config):
-    """Configure pytest to skip integration tests by default."""
-    config.addinivalue_line(
-        "markers",
-        "integration: marks tests as integration tests (require external services)",
-    )
-    config.addinivalue_line("markers", "ntfy: marks tests that require ntfy service")
-
-
-def pytest_collection_modifyitems(config, items):
-    """Skip integration/e2e tests unless explicitly requested with -m."""
-    # Get the current marker expression
-    marker_expr = config.getoption("-m", default="")
-
-    # If explicitly running integration or e2e, don't skip them
-    if marker_expr in ("integration", "e2e", "integration or e2e"):
-        return
-
-    # Skip integration tests
-    skip_integration = pytest.mark.skip(reason="need -m integration to run")
-    for item in items:
-        if "integration" in item.keywords:
-            item.add_marker(skip_integration)
-
-    # Skip e2e tests by default (they require browser/display)
-    skip_e2e = pytest.mark.skip(reason="need -m e2e to run")
-    for item in items:
-        if "e2e" in item.keywords and "integration" not in item.keywords:
-            item.add_marker(skip_e2e)

tests/e2e/test_web_client.py

@@ -1,133 +0,0 @@
-"""
-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"

tests/test_adapters.py

@@ -1,345 +0,0 @@
-"""
-Tests for engine/pipeline/adapters.py - Stage adapters for the pipeline.
-
-Tests Stage adapters that bridge existing components to the Stage interface:
-- DataSourceStage: Wraps DataSource objects
-- DisplayStage: Wraps Display backends
-- PassthroughStage: Simple pass-through stage for pre-rendered data
-- SourceItemsToBufferStage: Converts SourceItem objects to text buffers
-- EffectPluginStage: Wraps effect plugins
-"""
-
-from unittest.mock import MagicMock
-
-from engine.data_sources.sources import SourceItem
-from engine.pipeline.adapters import (
-    DataSourceStage,
-    DisplayStage,
-    EffectPluginStage,
-    PassthroughStage,
-    SourceItemsToBufferStage,
-)
-from engine.pipeline.core import PipelineContext
-
-
-class TestDataSourceStage:
-    """Test DataSourceStage adapter."""
-
-    def test_datasource_stage_name(self):
-        """DataSourceStage stores name correctly."""
-        mock_source = MagicMock()
-        stage = DataSourceStage(mock_source, name="headlines")
-        assert stage.name == "headlines"
-
-    def test_datasource_stage_category(self):
-        """DataSourceStage has 'source' category."""
-        mock_source = MagicMock()
-        stage = DataSourceStage(mock_source, name="headlines")
-        assert stage.category == "source"
-
-    def test_datasource_stage_capabilities(self):
-        """DataSourceStage advertises source capability."""
-        mock_source = MagicMock()
-        stage = DataSourceStage(mock_source, name="headlines")
-        assert "source.headlines" in stage.capabilities
-
-    def test_datasource_stage_dependencies(self):
-        """DataSourceStage has no dependencies."""
-        mock_source = MagicMock()
-        stage = DataSourceStage(mock_source, name="headlines")
-        assert stage.dependencies == set()
-
-    def test_datasource_stage_process_calls_get_items(self):
-        """DataSourceStage.process() calls source.get_items()."""
-        mock_items = [
-            SourceItem(content="Item 1", source="headlines", timestamp="12:00"),
-        ]
-        mock_source = MagicMock()
-        mock_source.get_items.return_value = mock_items
-
-        stage = DataSourceStage(mock_source, name="headlines")
-        ctx = PipelineContext()
-        result = stage.process(None, ctx)
-
-        assert result == mock_items
-        mock_source.get_items.assert_called_once()
-
-    def test_datasource_stage_process_fallback_returns_data(self):
-        """DataSourceStage.process() returns data if no get_items method."""
-        mock_source = MagicMock(spec=[])  # No get_items method
-        stage = DataSourceStage(mock_source, name="headlines")
-        ctx = PipelineContext()
-        test_data = [{"content": "test"}]
-
-        result = stage.process(test_data, ctx)
-        assert result == test_data
-
-
-class TestDisplayStage:
-    """Test DisplayStage adapter."""
-
-    def test_display_stage_name(self):
-        """DisplayStage stores name correctly."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-        assert stage.name == "terminal"
-
-    def test_display_stage_category(self):
-        """DisplayStage has 'display' category."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-        assert stage.category == "display"
-
-    def test_display_stage_capabilities(self):
-        """DisplayStage advertises display capability."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-        assert "display.output" in stage.capabilities
-
-    def test_display_stage_dependencies(self):
-        """DisplayStage depends on render.output."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-        assert "render.output" in stage.dependencies
-
-    def test_display_stage_init(self):
-        """DisplayStage.init() calls display.init() with dimensions."""
-        mock_display = MagicMock()
-        mock_display.init.return_value = True
-        stage = DisplayStage(mock_display, name="terminal")
-
-        ctx = PipelineContext()
-        ctx.params = MagicMock()
-        ctx.params.viewport_width = 100
-        ctx.params.viewport_height = 30
-
-        result = stage.init(ctx)
-
-        assert result is True
-        mock_display.init.assert_called_once_with(100, 30, reuse=False)
-
-    def test_display_stage_init_uses_defaults(self):
-        """DisplayStage.init() uses defaults when params missing."""
-        mock_display = MagicMock()
-        mock_display.init.return_value = True
-        stage = DisplayStage(mock_display, name="terminal")
-
-        ctx = PipelineContext()
-        ctx.params = None
-
-        result = stage.init(ctx)
-
-        assert result is True
-        mock_display.init.assert_called_once_with(80, 24, reuse=False)
-
-    def test_display_stage_process_calls_show(self):
-        """DisplayStage.process() calls display.show() with data."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-
-        test_buffer = [[["A", "red"] for _ in range(80)] for _ in range(24)]
-        ctx = PipelineContext()
-        result = stage.process(test_buffer, ctx)
-
-        assert result == test_buffer
-        mock_display.show.assert_called_once_with(test_buffer)
-
-    def test_display_stage_process_skips_none_data(self):
-        """DisplayStage.process() skips show() if data is None."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-
-        ctx = PipelineContext()
-        result = stage.process(None, ctx)
-
-        assert result is None
-        mock_display.show.assert_not_called()
-
-    def test_display_stage_cleanup(self):
-        """DisplayStage.cleanup() calls display.cleanup()."""
-        mock_display = MagicMock()
-        stage = DisplayStage(mock_display, name="terminal")
-
-        stage.cleanup()
-
-        mock_display.cleanup.assert_called_once()
-
-
-class TestPassthroughStage:
-    """Test PassthroughStage adapter."""
-
-    def test_passthrough_stage_name(self):
-        """PassthroughStage stores name correctly."""
-        stage = PassthroughStage(name="test")
-        assert stage.name == "test"
-
-    def test_passthrough_stage_category(self):
-        """PassthroughStage has 'render' category."""
-        stage = PassthroughStage()
-        assert stage.category == "render"
-
-    def test_passthrough_stage_is_optional(self):
-        """PassthroughStage is optional."""
-        stage = PassthroughStage()
-        assert stage.optional is True
-
-    def test_passthrough_stage_capabilities(self):
-        """PassthroughStage advertises render output capability."""
-        stage = PassthroughStage()
-        assert "render.output" in stage.capabilities
-
-    def test_passthrough_stage_dependencies(self):
-        """PassthroughStage depends on source."""
-        stage = PassthroughStage()
-        assert "source" in stage.dependencies
-
-    def test_passthrough_stage_process_returns_data_unchanged(self):
-        """PassthroughStage.process() returns data unchanged."""
-        stage = PassthroughStage()
-        ctx = PipelineContext()
-
-        test_data = [
-            SourceItem(content="Line 1", source="test", timestamp="12:00"),
-        ]
-        result = stage.process(test_data, ctx)
-
-        assert result == test_data
-        assert result is test_data
-
-
-class TestSourceItemsToBufferStage:
-    """Test SourceItemsToBufferStage adapter."""
-
-    def test_source_items_to_buffer_stage_name(self):
-        """SourceItemsToBufferStage stores name correctly."""
-        stage = SourceItemsToBufferStage(name="custom-name")
-        assert stage.name == "custom-name"
-
-    def test_source_items_to_buffer_stage_category(self):
-        """SourceItemsToBufferStage has 'render' category."""
-        stage = SourceItemsToBufferStage()
-        assert stage.category == "render"
-
-    def test_source_items_to_buffer_stage_is_optional(self):
-        """SourceItemsToBufferStage is optional."""
-        stage = SourceItemsToBufferStage()
-        assert stage.optional is True
-
-    def test_source_items_to_buffer_stage_capabilities(self):
-        """SourceItemsToBufferStage advertises render output capability."""
-        stage = SourceItemsToBufferStage()
-        assert "render.output" in stage.capabilities
-
-    def test_source_items_to_buffer_stage_dependencies(self):
-        """SourceItemsToBufferStage depends on source."""
-        stage = SourceItemsToBufferStage()
-        assert "source" in stage.dependencies
-
-    def test_source_items_to_buffer_stage_process_single_line_item(self):
-        """SourceItemsToBufferStage converts single-line SourceItem."""
-        stage = SourceItemsToBufferStage()
-        ctx = PipelineContext()
-
-        items = [
-            SourceItem(content="Single line content", source="test", timestamp="12:00"),
-        ]
-        result = stage.process(items, ctx)
-
-        assert isinstance(result, list)
-        assert len(result) >= 1
-        # Result should be lines of text
-        assert all(isinstance(line, str) for line in result)
-
-    def test_source_items_to_buffer_stage_process_multiline_item(self):
-        """SourceItemsToBufferStage splits multiline SourceItem content."""
-        stage = SourceItemsToBufferStage()
-        ctx = PipelineContext()
-
-        content = "Line 1\nLine 2\nLine 3"
-        items = [
-            SourceItem(content=content, source="test", timestamp="12:00"),
-        ]
-        result = stage.process(items, ctx)
-
-        # Should have at least 3 lines
-        assert len(result) >= 3
-        assert all(isinstance(line, str) for line in result)
-
-    def test_source_items_to_buffer_stage_process_multiple_items(self):
-        """SourceItemsToBufferStage handles multiple SourceItems."""
-        stage = SourceItemsToBufferStage()
-        ctx = PipelineContext()
-
-        items = [
-            SourceItem(content="Item 1", source="test", timestamp="12:00"),
-            SourceItem(content="Item 2", source="test", timestamp="12:01"),
-            SourceItem(content="Item 3", source="test", timestamp="12:02"),
-        ]
-        result = stage.process(items, ctx)
-
-        # Should have at least 3 lines (one per item, possibly more)
-        assert len(result) >= 3
-        assert all(isinstance(line, str) for line in result)
-
-
-class TestEffectPluginStage:
-    """Test EffectPluginStage adapter."""
-
-    def test_effect_plugin_stage_name(self):
-        """EffectPluginStage stores name correctly."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        assert stage.name == "blur"
-
-    def test_effect_plugin_stage_category(self):
-        """EffectPluginStage has 'effect' category."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        assert stage.category == "effect"
-
-    def test_effect_plugin_stage_is_not_optional(self):
-        """EffectPluginStage is required when configured."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        assert stage.optional is False
-
-    def test_effect_plugin_stage_capabilities(self):
-        """EffectPluginStage advertises effect capability with name."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        assert "effect.blur" in stage.capabilities
-
-    def test_effect_plugin_stage_dependencies(self):
-        """EffectPluginStage has no static dependencies."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        # EffectPluginStage has empty dependencies - they are resolved dynamically
-        assert stage.dependencies == set()
-
-    def test_effect_plugin_stage_stage_type(self):
-        """EffectPluginStage.stage_type returns effect for non-HUD."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="blur")
-        assert stage.stage_type == "effect"
-
-    def test_effect_plugin_stage_hud_special_handling(self):
-        """EffectPluginStage has special handling for HUD effect."""
-        mock_effect = MagicMock()
-        stage = EffectPluginStage(mock_effect, name="hud")
-        assert stage.stage_type == "overlay"
-        assert stage.is_overlay is True
-        assert stage.render_order == 100
-
-    def test_effect_plugin_stage_process(self):
-        """EffectPluginStage.process() calls effect.process()."""
-        mock_effect = MagicMock()
-        mock_effect.process.return_value = "processed_data"
-
-        stage = EffectPluginStage(mock_effect, name="blur")
-        ctx = PipelineContext()
-        test_buffer = "test_buffer"
-
-        result = stage.process(test_buffer, ctx)
-
-        assert result == "processed_data"
-        mock_effect.process.assert_called_once()

tests/test_app.py

@@ -1,205 +0,0 @@
-"""
-Integration tests for engine/app.py - pipeline orchestration.
-
-Tests the main entry point and pipeline mode initialization.
-"""
-
-import sys
-from unittest.mock import Mock, patch
-
-import pytest
-
-from engine.app import main, run_pipeline_mode
-from engine.pipeline import get_preset
-
-
-class TestMain:
-    """Test main() entry point."""
-
-    def test_main_calls_run_pipeline_mode_with_default_preset(self):
-        """main() runs default preset (demo) when no args provided."""
-        with patch("engine.app.run_pipeline_mode") as mock_run:
-            sys.argv = ["mainline.py"]
-            main()
-            mock_run.assert_called_once_with("demo")
-
-    def test_main_calls_run_pipeline_mode_with_config_preset(self):
-        """main() uses PRESET from config if set."""
-        with (
-            patch("engine.app.config") as mock_config,
-            patch("engine.app.run_pipeline_mode") as mock_run,
-        ):
-            mock_config.PIPELINE_DIAGRAM = False
-            mock_config.PRESET = "border-test"
-            mock_config.PIPELINE_MODE = False
-            sys.argv = ["mainline.py"]
-            main()
-            mock_run.assert_called_once_with("border-test")
-
-    def test_main_exits_on_unknown_preset(self):
-        """main() exits with error for unknown preset."""
-        with (
-            patch("engine.app.config") as mock_config,
-            patch("engine.app.list_presets", return_value=["demo", "poetry"]),
-        ):
-            mock_config.PIPELINE_DIAGRAM = False
-            mock_config.PRESET = "nonexistent"
-            mock_config.PIPELINE_MODE = False
-            sys.argv = ["mainline.py"]
-            with pytest.raises(SystemExit) as exc_info:
-                main()
-            assert exc_info.value.code == 1
-
-
-class TestRunPipelineMode:
-    """Test run_pipeline_mode() initialization."""
-
-    def test_run_pipeline_mode_loads_valid_preset(self):
-        """run_pipeline_mode() loads a valid preset."""
-        preset = get_preset("demo")
-        assert preset is not None
-        assert preset.name == "demo"
-        assert preset.source == "headlines"
-
-    def test_run_pipeline_mode_exits_on_invalid_preset(self):
-        """run_pipeline_mode() exits if preset not found."""
-        with pytest.raises(SystemExit) as exc_info:
-            run_pipeline_mode("invalid-preset-xyz")
-        assert exc_info.value.code == 1
-
-    def test_run_pipeline_mode_exits_when_no_content_available(self):
-        """run_pipeline_mode() exits if no content can be fetched."""
-        with (
-            patch("engine.app.load_cache", return_value=None),
-            patch("engine.app.fetch_all", return_value=([], None, None)),
-            patch("engine.app.effects_plugins"),
-            pytest.raises(SystemExit) as exc_info,
-        ):
-            run_pipeline_mode("demo")
-        assert exc_info.value.code == 1
-
-    def test_run_pipeline_mode_uses_cache_over_fetch(self):
-        """run_pipeline_mode() uses cached content if available."""
-        cached = ["cached_item"]
-        with (
-            patch("engine.app.load_cache", return_value=cached) as mock_load,
-            patch("engine.app.fetch_all") as mock_fetch,
-            patch("engine.app.DisplayRegistry.create") as mock_create,
-        ):
-            mock_display = Mock()
-            mock_display.init = Mock()
-            mock_display.get_dimensions = Mock(return_value=(80, 24))
-            mock_display.is_quit_requested = Mock(return_value=True)
-            mock_display.clear_quit_request = Mock()
-            mock_display.show = Mock()
-            mock_display.cleanup = Mock()
-            mock_create.return_value = mock_display
-
-            try:
-                run_pipeline_mode("demo")
-            except (KeyboardInterrupt, SystemExit):
-                pass
-
-            # Verify fetch_all was NOT called (cache was used)
-            mock_fetch.assert_not_called()
-            mock_load.assert_called_once()
-
-    def test_run_pipeline_mode_creates_display(self):
-        """run_pipeline_mode() creates a display backend."""
-        with (
-            patch("engine.app.load_cache", return_value=["item"]),
-            patch("engine.app.DisplayRegistry.create") as mock_create,
-        ):
-            mock_display = Mock()
-            mock_display.init = Mock()
-            mock_display.get_dimensions = Mock(return_value=(80, 24))
-            mock_display.is_quit_requested = Mock(return_value=True)
-            mock_display.clear_quit_request = Mock()
-            mock_display.show = Mock()
-            mock_display.cleanup = Mock()
-            mock_create.return_value = mock_display
-
-            try:
-                run_pipeline_mode("border-test")
-            except (KeyboardInterrupt, SystemExit):
-                pass
-
-            # Verify display was created with 'terminal' (preset display for border-test)
-            mock_create.assert_called_once_with("terminal")
-
-    def test_run_pipeline_mode_respects_display_cli_flag(self):
-        """run_pipeline_mode() uses --display CLI flag if provided."""
-        sys.argv = ["mainline.py", "--display", "websocket"]
-
-        with (
-            patch("engine.app.load_cache", return_value=["item"]),
-            patch("engine.app.DisplayRegistry.create") as mock_create,
-        ):
-            mock_display = Mock()
-            mock_display.init = Mock()
-            mock_display.get_dimensions = Mock(return_value=(80, 24))
-            mock_display.is_quit_requested = Mock(return_value=True)
-            mock_display.clear_quit_request = Mock()
-            mock_display.show = Mock()
-            mock_display.cleanup = Mock()
-            mock_create.return_value = mock_display
-
-            try:
-                run_pipeline_mode("demo")
-            except (KeyboardInterrupt, SystemExit):
-                pass
-
-            # Verify display was created with CLI override
-            mock_create.assert_called_once_with("websocket")
-
-    def test_run_pipeline_mode_fetches_poetry_for_poetry_source(self):
-        """run_pipeline_mode() fetches poetry for poetry preset."""
-        with (
-            patch("engine.app.load_cache", return_value=None),
-            patch(
-                "engine.app.fetch_poetry", return_value=(["poem"], None, None)
-            ) as mock_fetch_poetry,
-            patch("engine.app.fetch_all") as mock_fetch_all,
-            patch("engine.app.DisplayRegistry.create") as mock_create,
-        ):
-            mock_display = Mock()
-            mock_display.init = Mock()
-            mock_display.get_dimensions = Mock(return_value=(80, 24))
-            mock_display.is_quit_requested = Mock(return_value=True)
-            mock_display.clear_quit_request = Mock()
-            mock_display.show = Mock()
-            mock_display.cleanup = Mock()
-            mock_create.return_value = mock_display
-
-            try:
-                run_pipeline_mode("poetry")
-            except (KeyboardInterrupt, SystemExit):
-                pass
-
-            # Verify fetch_poetry was called, not fetch_all
-            mock_fetch_poetry.assert_called_once()
-            mock_fetch_all.assert_not_called()
-
-    def test_run_pipeline_mode_discovers_effect_plugins(self):
-        """run_pipeline_mode() discovers available effect plugins."""
-        with (
-            patch("engine.app.load_cache", return_value=["item"]),
-            patch("engine.app.effects_plugins") as mock_effects,
-            patch("engine.app.DisplayRegistry.create") as mock_create,
-        ):
-            mock_display = Mock()
-            mock_display.init = Mock()
-            mock_display.get_dimensions = Mock(return_value=(80, 24))
-            mock_display.is_quit_requested = Mock(return_value=True)
-            mock_display.clear_quit_request = Mock()
-            mock_display.show = Mock()
-            mock_display.cleanup = Mock()
-            mock_create.return_value = mock_display
-
-            try:
-                run_pipeline_mode("demo")
-            except (KeyboardInterrupt, SystemExit):
-                pass
-
-            # Verify effects_plugins.discover_plugins was called
-            mock_effects.discover_plugins.assert_called_once()

tests/test_benchmark.py

@@ -1,100 +0,0 @@
-"""
-Tests for engine.benchmark module - performance regression tests.
-"""
-
-from unittest.mock import patch
-
-import pytest
-
-from engine.display import NullDisplay
-
-
-class TestBenchmarkNullDisplay:
-    """Performance tests for NullDisplay - regression tests."""
-
-    @pytest.mark.benchmark
-    def test_null_display_minimum_fps(self):
-        """NullDisplay should meet minimum performance threshold."""
-        import time
-
-        display = NullDisplay()
-        display.init(80, 24)
-        buffer = ["x" * 80 for _ in range(24)]
-
-        iterations = 1000
-        start = time.perf_counter()
-        for _ in range(iterations):
-            display.show(buffer)
-        elapsed = time.perf_counter() - start
-
-        fps = iterations / elapsed
-        min_fps = 20000
-
-        assert fps >= min_fps, f"NullDisplay FPS {fps:.0f} below minimum {min_fps}"
-
-    @pytest.mark.benchmark
-    def test_effects_minimum_throughput(self):
-        """Effects should meet minimum processing throughput."""
-        import time
-
-        from effects_plugins import discover_plugins
-        from engine.effects import EffectContext, get_registry
-
-        discover_plugins()
-        registry = get_registry()
-        effect = registry.get("noise")
-        assert effect is not None, "Noise effect should be registered"
-
-        buffer = ["x" * 80 for _ in range(24)]
-        ctx = EffectContext(
-            terminal_width=80,
-            terminal_height=24,
-            scroll_cam=0,
-            ticker_height=20,
-            mic_excess=0.0,
-            grad_offset=0.0,
-            frame_number=0,
-            has_message=False,
-        )
-
-        iterations = 500
-        start = time.perf_counter()
-        for _ in range(iterations):
-            effect.process(buffer, ctx)
-        elapsed = time.perf_counter() - start
-
-        fps = iterations / elapsed
-        min_fps = 10000
-
-        assert fps >= min_fps, (
-            f"Effect processing FPS {fps:.0f} below minimum {min_fps}"
-        )
-
-
-class TestBenchmarkWebSocketDisplay:
-    """Performance tests for WebSocketDisplay."""
-
-    @pytest.mark.benchmark
-    def test_websocket_display_minimum_fps(self):
-        """WebSocketDisplay should meet minimum performance threshold."""
-        import time
-
-        with patch("engine.display.backends.websocket.websockets", None):
-            from engine.display import WebSocketDisplay
-
-            display = WebSocketDisplay()
-            display.init(80, 24)
-            buffer = ["x" * 80 for _ in range(24)]
-
-            iterations = 500
-            start = time.perf_counter()
-            for _ in range(iterations):
-                display.show(buffer)
-            elapsed = time.perf_counter() - start
-
-            fps = iterations / elapsed
-            min_fps = 10000
-
-            assert fps >= min_fps, (
-                f"WebSocketDisplay FPS {fps:.0f} below minimum {min_fps}"
-            )

tests/test_border_effect.py

@@ -1,112 +0,0 @@
-"""
-Tests for BorderEffect.
-"""
-
-
-from effects_plugins.border import BorderEffect
-from engine.effects.types import EffectContext
-
-
-def make_ctx(terminal_width: int = 80, terminal_height: int = 24) -> EffectContext:
-    """Create a mock EffectContext."""
-    return EffectContext(
-        terminal_width=terminal_width,
-        terminal_height=terminal_height,
-        scroll_cam=0,
-        ticker_height=terminal_height,
-    )
-
-
-class TestBorderEffect:
-    """Tests for BorderEffect."""
-
-    def test_basic_init(self):
-        """BorderEffect initializes with defaults."""
-        effect = BorderEffect()
-        assert effect.name == "border"
-        assert effect.config.enabled is True
-
-    def test_adds_border(self):
-        """BorderEffect adds border around content."""
-        effect = BorderEffect()
-        buf = [
-            "Hello World",
-            "Test Content",
-            "Third Line",
-        ]
-        ctx = make_ctx(terminal_width=20, terminal_height=10)
-
-        result = effect.process(buf, ctx)
-
-        # Should have top and bottom borders
-        assert len(result) >= 3
-        # First line should start with border character
-        assert result[0][0] in "┌┎┍"
-        # Last line should end with border character
-        assert result[-1][-1] in "┘┖┚"
-
-    def test_border_with_small_buffer(self):
-        """BorderEffect handles small buffer (too small for border)."""
-        effect = BorderEffect()
-        buf = ["ab"]  # Too small for proper border
-        ctx = make_ctx(terminal_width=10, terminal_height=5)
-
-        result = effect.process(buf, ctx)
-
-        # Should still try to add border but result may differ
-        # At minimum should have output
-        assert len(result) >= 1
-
-    def test_metrics_in_border(self):
-        """BorderEffect includes FPS and frame time in border."""
-        effect = BorderEffect()
-        buf = ["x" * 10] * 5
-        ctx = make_ctx(terminal_width=20, terminal_height=10)
-
-        # Add metrics to context
-        ctx.set_state(
-            "metrics",
-            {
-                "avg_ms": 16.5,
-                "frame_count": 100,
-                "fps": 60.0,
-            },
-        )
-
-        result = effect.process(buf, ctx)
-
-        # Check for FPS in top border
-        top_line = result[0]
-        assert "FPS" in top_line or "60" in top_line
-
-        # Check for frame time in bottom border
-        bottom_line = result[-1]
-        assert "ms" in bottom_line or "16" in bottom_line
-
-    def test_no_metrics(self):
-        """BorderEffect works without metrics."""
-        effect = BorderEffect()
-        buf = ["content"] * 5
-        ctx = make_ctx(terminal_width=20, terminal_height=10)
-        # No metrics set
-
-        result = effect.process(buf, ctx)
-
-        # Should still have border characters
-        assert len(result) >= 3
-        assert result[0][0] in "┌┎┍"
-
-    def test_crops_before_bordering(self):
-        """BorderEffect crops input before adding border."""
-        effect = BorderEffect()
-        buf = ["x" * 100] * 50  # Very large buffer
-        ctx = make_ctx(terminal_width=20, terminal_height=10)
-
-        result = effect.process(buf, ctx)
-
-        # Should be cropped to fit, then bordered
-        # Result should be <= terminal_height with border
-        assert len(result) <= ctx.terminal_height
-        # Each line should be <= terminal_width
-        for line in result:
-            assert len(line) <= ctx.terminal_width

tests/test_camera.py

@@ -1,68 +0,0 @@
-from engine.camera import Camera, CameraMode
-
-
-def test_camera_vertical_default():
-    """Test default vertical camera."""
-    cam = Camera()
-    assert cam.mode == CameraMode.FEED
-    assert cam.x == 0
-    assert cam.y == 0
-
-
-def test_camera_vertical_factory():
-    """Test vertical factory method."""
-    cam = Camera.feed(speed=2.0)
-    assert cam.mode == CameraMode.FEED
-    assert cam.speed == 2.0
-
-
-def test_camera_horizontal():
-    """Test horizontal camera."""
-    cam = Camera.horizontal(speed=1.5)
-    assert cam.mode == CameraMode.HORIZONTAL
-    cam.update(1.0)
-    assert cam.x > 0
-
-
-def test_camera_omni():
-    """Test omnidirectional camera."""
-    cam = Camera.omni(speed=1.0)
-    assert cam.mode == CameraMode.OMNI
-    cam.update(1.0)
-    assert cam.x > 0
-    assert cam.y > 0
-
-
-def test_camera_floating():
-    """Test floating camera with sinusoidal motion."""
-    cam = Camera.floating(speed=1.0)
-    assert cam.mode == CameraMode.FLOATING
-    y_before = cam.y
-    cam.update(0.5)
-    y_after = cam.y
-    assert y_before != y_after
-
-
-def test_camera_reset():
-    """Test camera reset."""
-    cam = Camera.vertical()
-    cam.update(1.0)
-    assert cam.y > 0
-    cam.reset()
-    assert cam.x == 0
-    assert cam.y == 0
-
-
-def test_camera_custom_update():
-    """Test custom update function."""
-    call_count = 0
-
-    def custom_update(camera, dt):
-        nonlocal call_count
-        call_count += 1
-        camera.x += int(10 * dt)
-
-    cam = Camera.custom(custom_update)
-    cam.update(1.0)
-    assert call_count == 1
-    assert cam.x == 10

tests/test_controller.py

@@ -0,0 +1,117 @@
+"""
+Tests for engine.controller module.
+"""
+
+from unittest.mock import MagicMock, patch
+
+from engine import config
+from engine.controller import StreamController
+
+
+class TestStreamController:
+    """Tests for StreamController class."""
+
+    def test_init_default_config(self):
+        """StreamController initializes with default config."""
+        controller = StreamController()
+        assert controller.config is not None
+        assert isinstance(controller.config, config.Config)
+
+    def test_init_custom_config(self):
+        """StreamController accepts custom config."""
+        custom_config = config.Config(headline_limit=500)
+        controller = StreamController(config=custom_config)
+        assert controller.config.headline_limit == 500
+
+    def test_init_sources_none_by_default(self):
+        """Sources are None until initialized."""
+        controller = StreamController()
+        assert controller.mic is None
+        assert controller.ntfy is None
+
+    @patch("engine.controller.MicMonitor")
+    @patch("engine.controller.NtfyPoller")
+    def test_initialize_sources(self, mock_ntfy, mock_mic):
+        """initialize_sources creates mic and ntfy instances."""
+        mock_mic_instance = MagicMock()
+        mock_mic_instance.available = True
+        mock_mic_instance.start.return_value = True
+        mock_mic.return_value = mock_mic_instance
+
+        mock_ntfy_instance = MagicMock()
+        mock_ntfy_instance.start.return_value = True
+        mock_ntfy.return_value = mock_ntfy_instance
+
+        controller = StreamController()
+        mic_ok, ntfy_ok = controller.initialize_sources()
+
+        assert mic_ok is True
+        assert ntfy_ok is True
+        assert controller.mic is not None
+        assert controller.ntfy is not None
+
+    @patch("engine.controller.MicMonitor")
+    @patch("engine.controller.NtfyPoller")
+    def test_initialize_sources_mic_unavailable(self, mock_ntfy, mock_mic):
+        """initialize_sources handles unavailable mic."""
+        mock_mic_instance = MagicMock()
+        mock_mic_instance.available = False
+        mock_mic.return_value = mock_mic_instance
+
+        mock_ntfy_instance = MagicMock()
+        mock_ntfy_instance.start.return_value = True
+        mock_ntfy.return_value = mock_ntfy_instance
+
+        controller = StreamController()
+        mic_ok, ntfy_ok = controller.initialize_sources()
+
+        assert mic_ok is False
+        assert ntfy_ok is True
+
+
+class TestStreamControllerCleanup:
+    """Tests for StreamController cleanup."""
+
+    @patch("engine.controller.MicMonitor")
+    def test_cleanup_stops_mic(self, mock_mic):
+        """cleanup stops the microphone if running."""
+        mock_mic_instance = MagicMock()
+        mock_mic.return_value = mock_mic_instance
+
+        controller = StreamController()
+        controller.mic = mock_mic_instance
+        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()

tests/test_crop_effect.py

@@ -1,100 +0,0 @@
-"""
-Tests for CropEffect.
-"""
-
-
-from effects_plugins.crop import CropEffect
-from engine.effects.types import EffectContext
-
-
-def make_ctx(terminal_width: int = 80, terminal_height: int = 24) -> EffectContext:
-    """Create a mock EffectContext."""
-    return EffectContext(
-        terminal_width=terminal_width,
-        terminal_height=terminal_height,
-        scroll_cam=0,
-        ticker_height=terminal_height,
-    )
-
-
-class TestCropEffect:
-    """Tests for CropEffect."""
-
-    def test_basic_init(self):
-        """CropEffect initializes with defaults."""
-        effect = CropEffect()
-        assert effect.name == "crop"
-        assert effect.config.enabled is True
-
-    def test_crop_wider_buffer(self):
-        """CropEffect crops wide buffer to terminal width."""
-        effect = CropEffect()
-        buf = [
-            "This is a very long line that exceeds the terminal width of eighty characters!",
-            "Another long line that should also be cropped to fit within the terminal bounds!",
-            "Short",
-        ]
-        ctx = make_ctx(terminal_width=40, terminal_height=10)
-
-        result = effect.process(buf, ctx)
-
-        # Lines should be cropped to 40 chars
-        assert len(result[0]) == 40
-        assert len(result[1]) == 40
-        assert result[2] == "Short" + " " * 35  # padded to width
-
-    def test_crop_taller_buffer(self):
-        """CropEffect crops tall buffer to terminal height."""
-        effect = CropEffect()
-        buf = ["line"] * 30  # 30 lines
-        ctx = make_ctx(terminal_width=80, terminal_height=10)
-
-        result = effect.process(buf, ctx)
-
-        # Should be cropped to 10 lines
-        assert len(result) == 10
-
-    def test_pad_shorter_lines(self):
-        """CropEffect pads lines shorter than width."""
-        effect = CropEffect()
-        buf = ["short", "medium length", ""]
-        ctx = make_ctx(terminal_width=20, terminal_height=5)
-
-        result = effect.process(buf, ctx)
-
-        assert len(result[0]) == 20  # padded
-        assert len(result[1]) == 20  # padded
-        assert len(result[2]) == 20  # padded (was empty)
-
-    def test_pad_to_height(self):
-        """CropEffect pads with empty lines if buffer is too short."""
-        effect = CropEffect()
-        buf = ["line1", "line2"]
-        ctx = make_ctx(terminal_width=20, terminal_height=10)
-
-        result = effect.process(buf, ctx)
-
-        # Should have 10 lines
-        assert len(result) == 10
-        # Last 8 should be empty padding
-        for i in range(2, 10):
-            assert result[i] == " " * 20
-
-    def test_empty_buffer(self):
-        """CropEffect handles empty buffer."""
-        effect = CropEffect()
-        ctx = make_ctx()
-
-        result = effect.process([], ctx)
-
-        assert result == []
-
-    def test_uses_context_dimensions(self):
-        """CropEffect uses context terminal_width/terminal_height."""
-        effect = CropEffect()
-        buf = ["x" * 100]
-        ctx = make_ctx(terminal_width=50, terminal_height=1)
-
-        result = effect.process(buf, ctx)
-
-        assert len(result[0]) == 50

tests/test_data_sources.py

@@ -1,220 +0,0 @@
-"""
-Tests for engine/data_sources/sources.py - data source implementations.
-
-Tests HeadlinesDataSource, PoetryDataSource, EmptyDataSource, and the
-base DataSource class functionality.
-"""
-
-from unittest.mock import patch
-
-import pytest
-
-from engine.data_sources.sources import (
-    EmptyDataSource,
-    HeadlinesDataSource,
-    PoetryDataSource,
-    SourceItem,
-)
-
-
-class TestSourceItem:
-    """Test SourceItem dataclass."""
-
-    def test_source_item_creation(self):
-        """SourceItem can be created with required fields."""
-        item = SourceItem(
-            content="Test headline",
-            source="test_source",
-            timestamp="2024-01-01",
-        )
-        assert item.content == "Test headline"
-        assert item.source == "test_source"
-        assert item.timestamp == "2024-01-01"
-        assert item.metadata is None
-
-    def test_source_item_with_metadata(self):
-        """SourceItem can include optional metadata."""
-        metadata = {"author": "John", "category": "tech"}
-        item = SourceItem(
-            content="Test",
-            source="test",
-            timestamp="2024-01-01",
-            metadata=metadata,
-        )
-        assert item.metadata == metadata
-
-
-class TestEmptyDataSource:
-    """Test EmptyDataSource."""
-
-    def test_empty_source_name(self):
-        """EmptyDataSource has correct name."""
-        source = EmptyDataSource()
-        assert source.name == "empty"
-
-    def test_empty_source_is_not_dynamic(self):
-        """EmptyDataSource is static, not dynamic."""
-        source = EmptyDataSource()
-        assert source.is_dynamic is False
-
-    def test_empty_source_fetch_returns_blank_content(self):
-        """EmptyDataSource.fetch() returns blank lines."""
-        source = EmptyDataSource(width=80, height=24)
-        items = source.fetch()
-
-        assert len(items) == 1
-        assert isinstance(items[0], SourceItem)
-        assert items[0].source == "empty"
-        # Content should be 24 lines of 80 spaces
-        lines = items[0].content.split("\n")
-        assert len(lines) == 24
-        assert all(len(line) == 80 for line in lines)
-
-    def test_empty_source_get_items_caches_result(self):
-        """EmptyDataSource.get_items() caches the result."""
-        source = EmptyDataSource()
-        items1 = source.get_items()
-        items2 = source.get_items()
-        # Should return same cached items (same object reference)
-        assert items1 is items2
-
-
-class TestHeadlinesDataSource:
-    """Test HeadlinesDataSource."""
-
-    def test_headlines_source_name(self):
-        """HeadlinesDataSource has correct name."""
-        source = HeadlinesDataSource()
-        assert source.name == "headlines"
-
-    def test_headlines_source_is_static(self):
-        """HeadlinesDataSource is static."""
-        source = HeadlinesDataSource()
-        assert source.is_dynamic is False
-
-    def test_headlines_fetch_returns_source_items(self):
-        """HeadlinesDataSource.fetch() returns SourceItem list."""
-        mock_items = [
-            ("Test Article 1", "source1", "10:30"),
-            ("Test Article 2", "source2", "11:45"),
-        ]
-        with patch("engine.fetch.fetch_all") as mock_fetch_all:
-            mock_fetch_all.return_value = (mock_items, 2, 0)
-
-            source = HeadlinesDataSource()
-            items = source.fetch()
-
-            assert len(items) == 2
-            assert all(isinstance(item, SourceItem) for item in items)
-            assert items[0].content == "Test Article 1"
-            assert items[0].source == "source1"
-            assert items[0].timestamp == "10:30"
-
-    def test_headlines_fetch_with_empty_feed(self):
-        """HeadlinesDataSource handles empty feeds gracefully."""
-        with patch("engine.fetch.fetch_all") as mock_fetch_all:
-            mock_fetch_all.return_value = ([], 0, 1)
-
-            source = HeadlinesDataSource()
-            items = source.fetch()
-
-            # Should return empty list
-            assert isinstance(items, list)
-            assert len(items) == 0
-
-    def test_headlines_get_items_caches_result(self):
-        """HeadlinesDataSource.get_items() caches the result."""
-        mock_items = [("Test Article", "source", "12:00")]
-        with patch("engine.fetch.fetch_all") as mock_fetch_all:
-            mock_fetch_all.return_value = (mock_items, 1, 0)
-
-            source = HeadlinesDataSource()
-            items1 = source.get_items()
-            items2 = source.get_items()
-
-            # Should only call fetch once (cached)
-            assert mock_fetch_all.call_count == 1
-            assert items1 is items2
-
-    def test_headlines_refresh_clears_cache(self):
-        """HeadlinesDataSource.refresh() clears cache and refetches."""
-        mock_items = [("Test Article", "source", "12:00")]
-        with patch("engine.fetch.fetch_all") as mock_fetch_all:
-            mock_fetch_all.return_value = (mock_items, 1, 0)
-
-            source = HeadlinesDataSource()
-            source.get_items()
-            source.refresh()
-            source.get_items()
-
-            # Should call fetch twice (once for initial, once for refresh)
-            assert mock_fetch_all.call_count == 2
-
-
-class TestPoetryDataSource:
-    """Test PoetryDataSource."""
-
-    def test_poetry_source_name(self):
-        """PoetryDataSource has correct name."""
-        source = PoetryDataSource()
-        assert source.name == "poetry"
-
-    def test_poetry_source_is_static(self):
-        """PoetryDataSource is static."""
-        source = PoetryDataSource()
-        assert source.is_dynamic is False
-
-    def test_poetry_fetch_returns_source_items(self):
-        """PoetryDataSource.fetch() returns SourceItem list."""
-        mock_items = [
-            ("Poetry line 1", "Poetry Source 1", ""),
-            ("Poetry line 2", "Poetry Source 2", ""),
-        ]
-        with patch("engine.fetch.fetch_poetry") as mock_fetch_poetry:
-            mock_fetch_poetry.return_value = (mock_items, 2, 0)
-
-            source = PoetryDataSource()
-            items = source.fetch()
-
-            assert len(items) == 2
-            assert all(isinstance(item, SourceItem) for item in items)
-            assert items[0].content == "Poetry line 1"
-            assert items[0].source == "Poetry Source 1"
-
-    def test_poetry_get_items_caches_result(self):
-        """PoetryDataSource.get_items() caches result."""
-        mock_items = [("Poetry line", "Poetry Source", "")]
-        with patch("engine.fetch.fetch_poetry") as mock_fetch_poetry:
-            mock_fetch_poetry.return_value = (mock_items, 1, 0)
-
-            source = PoetryDataSource()
-            items1 = source.get_items()
-            items2 = source.get_items()
-
-            # Should only fetch once (cached)
-            assert mock_fetch_poetry.call_count == 1
-            assert items1 is items2
-
-
-class TestDataSourceInterface:
-    """Test DataSource base class interface."""
-
-    def test_data_source_stream_not_implemented(self):
-        """DataSource.stream() raises NotImplementedError."""
-        source = EmptyDataSource()
-        with pytest.raises(NotImplementedError):
-            source.stream()
-
-    def test_data_source_is_dynamic_defaults_false(self):
-        """DataSource.is_dynamic defaults to False."""
-        source = EmptyDataSource()
-        assert source.is_dynamic is False
-
-    def test_data_source_refresh_updates_cache(self):
-        """DataSource.refresh() updates internal cache."""
-        source = EmptyDataSource()
-        source.get_items()
-        items_refreshed = source.refresh()
-
-        # refresh() should return new items
-        assert isinstance(items_refreshed, list)

tests/test_display.py

@@ -2,10 +2,7 @@
 Tests for engine.display module.
 """
 
-from unittest.mock import MagicMock
-
-from engine.display import DisplayRegistry, NullDisplay, TerminalDisplay
-from engine.display.backends.multi import MultiDisplay
+from engine.display import NullDisplay, TerminalDisplay
 
 
 class TestDisplayProtocol:
@@ -28,66 +25,6 @@ class TestDisplayProtocol:
         assert hasattr(display, "cleanup")
 
 
-class TestDisplayRegistry:
-    """Tests for DisplayRegistry class."""
-
-    def setup_method(self):
-        """Reset registry before each test."""
-        DisplayRegistry._backends = {}
-        DisplayRegistry._initialized = False
-
-    def test_register_adds_backend(self):
-        """register adds a backend to the registry."""
-        DisplayRegistry.register("test", TerminalDisplay)
-        assert DisplayRegistry.get("test") == TerminalDisplay
-
-    def test_register_case_insensitive(self):
-        """register is case insensitive."""
-        DisplayRegistry.register("TEST", TerminalDisplay)
-        assert DisplayRegistry.get("test") == TerminalDisplay
-
-    def test_get_returns_none_for_unknown(self):
-        """get returns None for unknown backend."""
-        assert DisplayRegistry.get("unknown") is None
-
-    def test_list_backends_returns_all(self):
-        """list_backends returns all registered backends."""
-        DisplayRegistry.register("a", TerminalDisplay)
-        DisplayRegistry.register("b", NullDisplay)
-        backends = DisplayRegistry.list_backends()
-        assert "a" in backends
-        assert "b" in backends
-
-    def test_create_returns_instance(self):
-        """create returns a display instance."""
-        DisplayRegistry.register("test", NullDisplay)
-        display = DisplayRegistry.create("test")
-        assert isinstance(display, NullDisplay)
-
-    def test_create_returns_none_for_unknown(self):
-        """create returns None for unknown backend."""
-        display = DisplayRegistry.create("unknown")
-        assert display is None
-
-    def test_initialize_registers_defaults(self):
-        """initialize registers default backends."""
-        DisplayRegistry.initialize()
-        assert DisplayRegistry.get("terminal") == TerminalDisplay
-        assert DisplayRegistry.get("null") == NullDisplay
-        from engine.display.backends.sixel import SixelDisplay
-        from engine.display.backends.websocket import WebSocketDisplay
-
-        assert DisplayRegistry.get("websocket") == WebSocketDisplay
-        assert DisplayRegistry.get("sixel") == SixelDisplay
-
-    def test_initialize_idempotent(self):
-        """initialize can be called multiple times safely."""
-        DisplayRegistry.initialize()
-        DisplayRegistry._backends["custom"] = TerminalDisplay
-        DisplayRegistry.initialize()
-        assert "custom" in DisplayRegistry.list_backends()
-
-
 class TestTerminalDisplay:
     """Tests for TerminalDisplay class."""
 
@@ -140,71 +77,3 @@ class TestNullDisplay:
         """cleanup does nothing."""
         display = NullDisplay()
         display.cleanup()
-
-
-class TestMultiDisplay:
-    """Tests for MultiDisplay class."""
-
-    def test_init_stores_dimensions(self):
-        """init stores dimensions and forwards to displays."""
-        mock_display1 = MagicMock()
-        mock_display2 = MagicMock()
-        multi = MultiDisplay([mock_display1, mock_display2])
-
-        multi.init(120, 40)
-
-        assert multi.width == 120
-        assert multi.height == 40
-        mock_display1.init.assert_called_once_with(120, 40, reuse=False)
-        mock_display2.init.assert_called_once_with(120, 40, reuse=False)
-
-    def test_show_forwards_to_all_displays(self):
-        """show forwards buffer to all displays."""
-        mock_display1 = MagicMock()
-        mock_display2 = MagicMock()
-        multi = MultiDisplay([mock_display1, mock_display2])
-
-        buffer = ["line1", "line2"]
-        multi.show(buffer, border=False)
-
-        mock_display1.show.assert_called_once_with(buffer, border=False)
-        mock_display2.show.assert_called_once_with(buffer, border=False)
-
-    def test_clear_forwards_to_all_displays(self):
-        """clear forwards to all displays."""
-        mock_display1 = MagicMock()
-        mock_display2 = MagicMock()
-        multi = MultiDisplay([mock_display1, mock_display2])
-
-        multi.clear()
-
-        mock_display1.clear.assert_called_once()
-        mock_display2.clear.assert_called_once()
-
-    def test_cleanup_forwards_to_all_displays(self):
-        """cleanup forwards to all displays."""
-        mock_display1 = MagicMock()
-        mock_display2 = MagicMock()
-        multi = MultiDisplay([mock_display1, mock_display2])
-
-        multi.cleanup()
-
-        mock_display1.cleanup.assert_called_once()
-        mock_display2.cleanup.assert_called_once()
-
-    def test_empty_displays_list(self):
-        """handles empty displays list gracefully."""
-        multi = MultiDisplay([])
-        multi.init(80, 24)
-        multi.show(["test"])
-        multi.clear()
-        multi.cleanup()
-
-    def test_init_with_reuse(self):
-        """init passes reuse flag to child displays."""
-        mock_display = MagicMock()
-        multi = MultiDisplay([mock_display])
-
-        multi.init(80, 24, reuse=True)
-
-        mock_display.init.assert_called_once_with(80, 24, reuse=True)

tests/test_effects_controller.py

@@ -5,10 +5,8 @@ Tests for engine.effects.controller module.
 from unittest.mock import MagicMock, patch
 
 from engine.effects.controller import (
-    _format_stats,
     handle_effects_command,
     set_effect_chain_ref,
-    show_effects_menu,
 )
 
 
@@ -94,29 +92,6 @@ class TestHandleEffectsCommand:
                 assert "Reordered pipeline" in result
                 mock_chain_instance.reorder.assert_called_once_with(["noise", "fade"])
 
-    def test_reorder_failure(self):
-        """reorder returns error on failure."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_registry.return_value.list_all.return_value = {}
-
-            with patch("engine.effects.controller._get_effect_chain") as mock_chain:
-                mock_chain_instance = MagicMock()
-                mock_chain_instance.reorder.return_value = False
-                mock_chain.return_value = mock_chain_instance
-
-                result = handle_effects_command("/effects reorder bad")
-
-                assert "Failed to reorder" in result
-
-    def test_unknown_effect(self):
-        """unknown effect returns error."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_registry.return_value.list_all.return_value = {}
-
-            result = handle_effects_command("/effects unknown on")
-
-            assert "Unknown effect" in result
-
     def test_unknown_command(self):
         """unknown command returns error."""
         result = handle_effects_command("/unknown")
@@ -127,105 +102,6 @@ class TestHandleEffectsCommand:
         result = handle_effects_command("not a command")
         assert "Unknown command" in result
 
-    def test_invalid_intensity_value(self):
-        """invalid intensity value returns error."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_plugin = MagicMock()
-            mock_registry.return_value.get.return_value = mock_plugin
-            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
-
-            result = handle_effects_command("/effects noise intensity bad")
-
-            assert "Invalid intensity" in result
-
-    def test_missing_action(self):
-        """missing action returns usage."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_plugin = MagicMock()
-            mock_registry.return_value.get.return_value = mock_plugin
-            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
-
-            result = handle_effects_command("/effects noise")
-
-            assert "Usage" in result
-
-    def test_stats_command(self):
-        """stats command returns formatted stats."""
-        with patch("engine.effects.controller.get_monitor") as mock_monitor:
-            mock_monitor.return_value.get_stats.return_value = {
-                "frame_count": 100,
-                "pipeline": {"avg_ms": 1.5, "min_ms": 1.0, "max_ms": 2.0},
-                "effects": {},
-            }
-
-            result = handle_effects_command("/effects stats")
-
-            assert "Performance Stats" in result
-
-    def test_list_only_effects(self):
-        """list command works with just /effects."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_plugin = MagicMock()
-            mock_plugin.config.enabled = False
-            mock_plugin.config.intensity = 0.5
-            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
-
-            with patch("engine.effects.controller._get_effect_chain") as mock_chain:
-                mock_chain.return_value = None
-
-                result = handle_effects_command("/effects")
-
-                assert "noise: OFF" in result
-
-
-class TestShowEffectsMenu:
-    """Tests for show_effects_menu function."""
-
-    def test_returns_formatted_menu(self):
-        """returns formatted effects menu."""
-        with patch("engine.effects.controller.get_registry") as mock_registry:
-            mock_plugin = MagicMock()
-            mock_plugin.config.enabled = True
-            mock_plugin.config.intensity = 0.75
-            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
-
-            with patch("engine.effects.controller._get_effect_chain") as mock_chain:
-                mock_chain_instance = MagicMock()
-                mock_chain_instance.get_order.return_value = ["noise"]
-                mock_chain.return_value = mock_chain_instance
-
-                result = show_effects_menu()
-
-                assert "EFFECTS MENU" in result
-                assert "noise" in result
-
-
-class TestFormatStats:
-    """Tests for _format_stats function."""
-
-    def test_returns_error_when_no_monitor(self):
-        """returns error when monitor unavailable."""
-        with patch("engine.effects.controller.get_monitor") as mock_monitor:
-            mock_monitor.return_value.get_stats.return_value = {"error": "No data"}
-
-            result = _format_stats()
-
-            assert "No data" in result
-
-    def test_formats_pipeline_stats(self):
-        """formats pipeline stats correctly."""
-        with patch("engine.effects.controller.get_monitor") as mock_monitor:
-            mock_monitor.return_value.get_stats.return_value = {
-                "frame_count": 50,
-                "pipeline": {"avg_ms": 2.5, "min_ms": 2.0, "max_ms": 3.0},
-                "effects": {"noise": {"avg_ms": 0.5, "min_ms": 0.4, "max_ms": 0.6}},
-            }
-
-            result = _format_stats()
-
-            assert "Pipeline" in result
-            assert "noise" in result
-
 
 class TestSetEffectChainRef:
     """Tests for set_effect_chain_ref function."""

tests/test_emitters.py

@@ -0,0 +1,69 @@
+"""
+Tests for engine.emitters module.
+"""
+
+from engine.emitters import EventEmitter, Startable, Stoppable
+
+
+class TestEventEmitterProtocol:
+    """Tests for EventEmitter protocol."""
+
+    def test_protocol_exists(self):
+        """EventEmitter protocol is defined."""
+        assert EventEmitter is not None
+
+    def test_protocol_has_subscribe_method(self):
+        """EventEmitter has subscribe method in protocol."""
+        assert hasattr(EventEmitter, "subscribe")
+
+    def test_protocol_has_unsubscribe_method(self):
+        """EventEmitter has unsubscribe method in protocol."""
+        assert hasattr(EventEmitter, "unsubscribe")
+
+
+class TestStartableProtocol:
+    """Tests for Startable protocol."""
+
+    def test_protocol_exists(self):
+        """Startable protocol is defined."""
+        assert Startable is not None
+
+    def test_protocol_has_start_method(self):
+        """Startable has start method in protocol."""
+        assert hasattr(Startable, "start")
+
+
+class TestStoppableProtocol:
+    """Tests for Stoppable protocol."""
+
+    def test_protocol_exists(self):
+        """Stoppable protocol is defined."""
+        assert Stoppable is not None
+
+    def test_protocol_has_stop_method(self):
+        """Stoppable has stop method in protocol."""
+        assert hasattr(Stoppable, "stop")
+
+
+class TestProtocolCompliance:
+    """Tests that existing classes comply with protocols."""
+
+    def test_ntfy_poller_complies_with_protocol(self):
+        """NtfyPoller implements EventEmitter protocol."""
+        from engine.ntfy import NtfyPoller
+
+        poller = NtfyPoller("http://example.com/topic")
+        assert hasattr(poller, "subscribe")
+        assert hasattr(poller, "unsubscribe")
+        assert callable(poller.subscribe)
+        assert callable(poller.unsubscribe)
+
+    def test_mic_monitor_complies_with_protocol(self):
+        """MicMonitor implements EventEmitter and Startable protocols."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert hasattr(monitor, "subscribe")
+        assert hasattr(monitor, "unsubscribe")
+        assert hasattr(monitor, "start")
+        assert hasattr(monitor, "stop")

tests/test_fetch.py

@@ -1,234 +0,0 @@
-"""
-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")])

tests/test_hud.py

@@ -1,107 +0,0 @@
-
-from engine.effects.performance import PerformanceMonitor, set_monitor
-from engine.effects.types import EffectContext
-
-
-def test_hud_effect_adds_hud_lines():
-    """Test that HUD effect adds HUD lines to the buffer."""
-    from effects_plugins.hud import HudEffect
-
-    set_monitor(PerformanceMonitor())
-
-    hud = HudEffect()
-    hud.config.params["display_effect"] = "noise"
-    hud.config.params["display_intensity"] = 0.5
-
-    ctx = EffectContext(
-        terminal_width=80,
-        terminal_height=24,
-        scroll_cam=0,
-        ticker_height=24,
-        mic_excess=0.0,
-        grad_offset=0.0,
-        frame_number=0,
-        has_message=False,
-        items=[],
-    )
-
-    buf = [
-        "A" * 80,
-        "B" * 80,
-        "C" * 80,
-    ]
-
-    result = hud.process(buf, ctx)
-
-    assert len(result) >= 3, f"Expected at least 3 lines, got {len(result)}"
-
-    first_line = result[0]
-    assert "MAINLINE DEMO" in first_line, (
-        f"HUD not found in first line: {first_line[:50]}"
-    )
-
-    second_line = result[1]
-    assert "EFFECT:" in second_line, f"Effect line not found: {second_line[:50]}"
-
-    print("First line:", result[0])
-    print("Second line:", result[1])
-    if len(result) > 2:
-        print("Third line:", result[2])
-
-
-def test_hud_effect_shows_current_effect():
-    """Test that HUD displays the correct effect name."""
-    from effects_plugins.hud import HudEffect
-
-    set_monitor(PerformanceMonitor())
-
-    hud = HudEffect()
-    hud.config.params["display_effect"] = "fade"
-    hud.config.params["display_intensity"] = 0.75
-
-    ctx = EffectContext(
-        terminal_width=80,
-        terminal_height=24,
-        scroll_cam=0,
-        ticker_height=24,
-        mic_excess=0.0,
-        grad_offset=0.0,
-        frame_number=0,
-        has_message=False,
-        items=[],
-    )
-
-    buf = ["X" * 80]
-    result = hud.process(buf, ctx)
-
-    second_line = result[1]
-    assert "fade" in second_line, f"Effect name 'fade' not found in: {second_line}"
-
-
-def test_hud_effect_shows_intensity():
-    """Test that HUD displays intensity percentage."""
-    from effects_plugins.hud import HudEffect
-
-    set_monitor(PerformanceMonitor())
-
-    hud = HudEffect()
-    hud.config.params["display_effect"] = "glitch"
-    hud.config.params["display_intensity"] = 0.8
-
-    ctx = EffectContext(
-        terminal_width=80,
-        terminal_height=24,
-        scroll_cam=0,
-        ticker_height=24,
-        mic_excess=0.0,
-        grad_offset=0.0,
-        frame_number=0,
-        has_message=False,
-        items=[],
-    )
-
-    buf = ["Y" * 80]
-    result = hud.process(buf, ctx)
-
-    second_line = result[1]
-    assert "80%" in second_line, f"Intensity 80% not found in: {second_line}"

tests/test_layers.py

@@ -0,0 +1,96 @@
+"""
+Tests for engine.layers module.
+"""
+
+import time
+
+from engine import layers
+
+
+class TestRenderMessageOverlay:
+    """Tests for render_message_overlay function."""
+
+    def test_no_message_returns_empty(self):
+        """Returns empty list when msg is None."""
+        result, cache = layers.render_message_overlay(None, 80, 24, (None, None))
+        assert result == []
+        assert cache[0] is None
+
+    def test_message_returns_overlay_lines(self):
+        """Returns non-empty list when message is present."""
+        msg = ("Test Title", "Test Body", time.monotonic())
+        result, cache = layers.render_message_overlay(msg, 80, 24, (None, None))
+        assert len(result) > 0
+        assert cache[0] is not None
+
+    def test_cache_key_changes_with_text(self):
+        """Cache key changes when message text changes."""
+        msg1 = ("Title1", "Body1", time.monotonic())
+        msg2 = ("Title2", "Body2", time.monotonic())
+
+        _, cache1 = layers.render_message_overlay(msg1, 80, 24, (None, None))
+        _, cache2 = layers.render_message_overlay(msg2, 80, 24, cache1)
+
+        assert cache1[0] != cache2[0]
+
+    def test_cache_reuse_avoids_recomputation(self):
+        """Cache is returned when same message is passed (interface test)."""
+        msg = ("Same Title", "Same Body", time.monotonic())
+
+        result1, cache1 = layers.render_message_overlay(msg, 80, 24, (None, None))
+        result2, cache2 = layers.render_message_overlay(msg, 80, 24, cache1)
+
+        assert len(result1) > 0
+        assert len(result2) > 0
+        assert cache1[0] == cache2[0]
+
+
+class TestRenderFirehose:
+    """Tests for render_firehose function."""
+
+    def test_no_firehose_returns_empty(self):
+        """Returns empty list when firehose height is 0."""
+        items = [("Headline", "Source", "12:00")]
+        result = layers.render_firehose(items, 80, 0, 24)
+        assert result == []
+
+    def test_firehose_returns_lines(self):
+        """Returns lines when firehose height > 0."""
+        items = [("Headline", "Source", "12:00")]
+        result = layers.render_firehose(items, 80, 4, 24)
+        assert len(result) == 4
+
+    def test_firehose_includes_ansi_escapes(self):
+        """Returns lines containing ANSI escape sequences."""
+        items = [("Headline", "Source", "12:00")]
+        result = layers.render_firehose(items, 80, 1, 24)
+        assert "\033[" in result[0]
+
+
+class TestApplyGlitch:
+    """Tests for apply_glitch function."""
+
+    def test_empty_buffer_unchanged(self):
+        """Empty buffer is returned unchanged."""
+        result = layers.apply_glitch([], 0, 0.0, 80)
+        assert result == []
+
+    def test_buffer_length_preserved(self):
+        """Buffer length is preserved after glitch application."""
+        buf = [f"\033[{i + 1};1Htest\033[K" for i in range(10)]
+        result = layers.apply_glitch(buf, 0, 0.5, 80)
+        assert len(result) == len(buf)
+
+
+class TestRenderTickerZone:
+    """Tests for render_ticker_zone function - focusing on interface."""
+
+    def test_returns_list(self):
+        """Returns a list of strings."""
+        result, cache = layers.render_ticker_zone([], 0, 10, 80, {}, 0.0)
+        assert isinstance(result, list)
+
+    def test_returns_dict_for_cache(self):
+        """Returns a dict for the noise cache."""
+        result, cache = layers.render_ticker_zone([], 0, 10, 80, {}, 0.0)
+        assert isinstance(cache, dict)

tests/test_mic.py

@@ -0,0 +1,149 @@
+"""
+Tests for engine.mic module.
+"""
+
+from datetime import datetime
+from unittest.mock import patch
+
+from engine.events import MicLevelEvent
+
+
+class TestMicMonitorImport:
+    """Tests for module import behavior."""
+
+    def test_mic_monitor_imports_without_error(self):
+        """MicMonitor can be imported even without sounddevice."""
+        from engine.mic import MicMonitor
+
+        assert MicMonitor is not None
+
+
+class TestMicMonitorInit:
+    """Tests for MicMonitor initialization."""
+
+    def test_init_sets_threshold(self):
+        """Threshold is set correctly."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=60)
+        assert monitor.threshold_db == 60
+
+    def test_init_defaults(self):
+        """Default values are set correctly."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert monitor.threshold_db == 50
+
+    def test_init_db_starts_at_negative(self):
+        """_db starts at negative value."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert monitor.db == -99.0
+
+
+class TestMicMonitorProperties:
+    """Tests for MicMonitor properties."""
+
+    def test_excess_returns_positive_when_above_threshold(self):
+        """excess returns positive value when above threshold."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=50)
+        with patch.object(monitor, "_db", 60.0):
+            assert monitor.excess == 10.0
+
+    def test_excess_returns_zero_when_below_threshold(self):
+        """excess returns zero when below threshold."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor(threshold_db=50)
+        with patch.object(monitor, "_db", 40.0):
+            assert monitor.excess == 0.0
+
+
+class TestMicMonitorAvailable:
+    """Tests for MicMonitor.available property."""
+
+    def test_available_is_bool(self):
+        """available returns a boolean."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        assert isinstance(monitor.available, bool)
+
+
+class TestMicMonitorStop:
+    """Tests for MicMonitor.stop method."""
+
+    def test_stop_does_nothing_when_no_stream(self):
+        """stop() does nothing if no stream exists."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        monitor.stop()
+        assert monitor._stream is None
+
+
+class TestMicMonitorEventEmission:
+    """Tests for MicMonitor event emission."""
+
+    def test_subscribe_adds_callback(self):
+        """subscribe() adds a callback."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        def callback(e):
+            return None
+
+        monitor.subscribe(callback)
+
+        assert callback in monitor._subscribers
+
+    def test_unsubscribe_removes_callback(self):
+        """unsubscribe() removes a callback."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        def callback(e):
+            return None
+        monitor.subscribe(callback)
+
+        monitor.unsubscribe(callback)
+
+        assert callback not in monitor._subscribers
+
+    def test_emit_calls_subscribers(self):
+        """_emit() calls all subscribers."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+        received = []
+
+        def callback(event):
+            received.append(event)
+
+        monitor.subscribe(callback)
+        event = MicLevelEvent(
+            db_level=60.0, excess_above_threshold=10.0, timestamp=datetime.now()
+        )
+        monitor._emit(event)
+
+        assert len(received) == 1
+        assert received[0].db_level == 60.0
+
+    def test_emit_handles_subscriber_exception(self):
+        """_emit() handles exceptions in subscribers gracefully."""
+        from engine.mic import MicMonitor
+
+        monitor = MicMonitor()
+
+        def bad_callback(event):
+            raise RuntimeError("test")
+
+        monitor.subscribe(bad_callback)
+        event = MicLevelEvent(
+            db_level=60.0, excess_above_threshold=10.0, timestamp=datetime.now()
+        )
+        monitor._emit(event)

tests/test_ntfy_integration.py

@@ -6,11 +6,7 @@ import json
 import time
 import urllib.request
 
-import pytest
 
-
-@pytest.mark.integration
-@pytest.mark.ntfy
 class TestNtfyTopics:
     def test_cc_cmd_topic_exists_and_writable(self):
         """Verify C&C CMD topic exists and accepts messages."""

tests/test_performance_regression.py

@@ -1,192 +0,0 @@
-"""Performance regression tests for pipeline stages with realistic data volumes.
-
-These tests verify that the pipeline maintains performance with large datasets
-by ensuring ViewportFilterStage prevents FontStage from rendering excessive items.
-
-Uses pytest-benchmark for statistical benchmarking with automatic regression detection.
-"""
-
-import pytest
-
-from engine.data_sources.sources import SourceItem
-from engine.pipeline.adapters import FontStage, ViewportFilterStage
-from engine.pipeline.core import PipelineContext
-
-
-class MockParams:
-    """Mock parameters object for testing."""
-
-    def __init__(self, viewport_width: int = 80, viewport_height: int = 24):
-        self.viewport_width = viewport_width
-        self.viewport_height = viewport_height
-
-
-class TestViewportFilterPerformance:
-    """Test ViewportFilterStage performance with realistic data volumes."""
-
-    @pytest.mark.benchmark
-    def test_filter_2000_items_to_viewport(self, benchmark):
-        """Benchmark: Filter 2000 items to viewport size.
-
-        Performance threshold: Must complete in < 1ms per iteration
-        This tests the filtering overhead is negligible.
-        """
-        # Create 2000 test items (more than real headline sources)
-        test_items = [
-            SourceItem(f"Headline {i}", f"source-{i % 10}", str(i)) for i in range(2000)
-        ]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_height=24)
-
-        result = benchmark(stage.process, test_items, ctx)
-
-        # Verify result is correct
-        assert len(result) <= 5
-        assert len(result) > 0
-
-    @pytest.mark.benchmark
-    def test_font_stage_with_filtered_items(self, benchmark):
-        """Benchmark: FontStage rendering filtered (5) items.
-
-        Performance threshold: Must complete in < 50ms per iteration
-        This tests that filtering saves significant time by reducing FontStage work.
-        """
-        # Create filtered items (what ViewportFilterStage outputs)
-        filtered_items = [
-            SourceItem(f"Headline {i}", "source", str(i))
-            for i in range(5)  # Filtered count
-        ]
-
-        font_stage = FontStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        result = benchmark(font_stage.process, filtered_items, ctx)
-
-        # Should render successfully
-        assert result is not None
-        assert isinstance(result, list)
-        assert len(result) > 0
-
-    def test_filter_reduces_work_by_288x(self):
-        """Verify ViewportFilterStage achieves expected performance improvement.
-
-        With 1438 items and 24-line viewport:
-        - Without filter: FontStage renders all 1438 items
-        - With filter: FontStage renders ~3 items (layout-based)
-        - Expected improvement: 1438 / 3 ≈ 479x
-        """
-        test_items = [
-            SourceItem(f"Headline {i}", "source", str(i)) for i in range(1438)
-        ]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_height=24)
-
-        filtered = stage.process(test_items, ctx)
-        improvement_factor = len(test_items) / len(filtered)
-
-        # Verify we get expected ~479x improvement (better than old ~288x)
-        assert 400 < improvement_factor < 600
-        # Verify filtered count is reasonable (layout-based is more precise)
-        assert 2 <= len(filtered) <= 5
-
-
-class TestPipelinePerformanceWithRealData:
-    """Integration tests for full pipeline performance with large datasets."""
-
-    def test_pipeline_handles_large_item_count(self):
-        """Test that pipeline doesn't hang with 2000+ items due to filtering."""
-        # Create large dataset
-        large_items = [
-            SourceItem(f"Headline {i}", f"source-{i % 5}", str(i)) for i in range(2000)
-        ]
-
-        filter_stage = ViewportFilterStage()
-        font_stage = FontStage()
-
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_height=24)
-
-        # Filter should reduce items quickly
-        filtered = filter_stage.process(large_items, ctx)
-        assert len(filtered) < len(large_items)
-
-        # FontStage should process filtered items quickly
-        rendered = font_stage.process(filtered, ctx)
-        assert rendered is not None
-
-    def test_multiple_viewports_filter_correctly(self):
-        """Test that filter respects different viewport configurations."""
-        large_items = [
-            SourceItem(f"Headline {i}", "source", str(i)) for i in range(1000)
-        ]
-
-        stage = ViewportFilterStage()
-
-        # Test different viewport heights
-        test_cases = [
-            (12, 3),  # 12px height -> ~3 items
-            (24, 5),  # 24px height -> ~5 items
-            (48, 9),  # 48px height -> ~9 items
-        ]
-
-        for viewport_height, expected_max_items in test_cases:
-            ctx = PipelineContext()
-            ctx.params = MockParams(viewport_height=viewport_height)
-
-            filtered = stage.process(large_items, ctx)
-
-            # Verify filtering is proportional to viewport
-            assert len(filtered) <= expected_max_items + 1
-            assert len(filtered) > 0
-
-
-class TestPerformanceRegressions:
-    """Tests that catch common performance regressions."""
-
-    def test_filter_doesnt_render_all_items(self):
-        """Regression test: Ensure filter doesn't accidentally render all items.
-
-        This would indicate that ViewportFilterStage is broken or bypassed.
-        """
-        large_items = [
-            SourceItem(f"Headline {i}", "source", str(i)) for i in range(1438)
-        ]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        filtered = stage.process(large_items, ctx)
-
-        # Should NOT have all items (regression detection)
-        assert len(filtered) != len(large_items)
-        # Should have drastically fewer items
-        assert len(filtered) < 10
-
-    def test_font_stage_doesnt_hang_with_filter(self):
-        """Regression test: FontStage shouldn't hang when receiving filtered data.
-
-        Previously, FontStage would render all items, causing 10+ second hangs.
-        Now it should receive only ~5 items and complete quickly.
-        """
-        # Simulate what happens after ViewportFilterStage
-        filtered_items = [
-            SourceItem(f"Headline {i}", "source", str(i))
-            for i in range(5)  # What filter outputs
-        ]
-
-        font_stage = FontStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        # Should complete instantly (not hang)
-        result = font_stage.process(filtered_items, ctx)
-
-        # Verify it actually worked
-        assert result is not None
-        assert isinstance(result, list)

tests/test_pipeline_e2e.py

@@ -1,526 +0,0 @@
-"""
-End-to-end pipeline integration tests.
-
-Verifies that data actually flows through every pipeline stage
-(source -> render -> effects -> display) using a queue-backed
-stub display to capture output frames.
-
-These tests catch dead-code paths and wiring bugs that unit tests miss.
-"""
-
-import queue
-from unittest.mock import patch
-
-from engine.data_sources.sources import ListDataSource, SourceItem
-from engine.effects import EffectContext
-from engine.effects.types import EffectPlugin
-from engine.pipeline import Pipeline, PipelineConfig
-from engine.pipeline.adapters import (
-    DataSourceStage,
-    DisplayStage,
-    EffectPluginStage,
-    FontStage,
-    SourceItemsToBufferStage,
-)
-from engine.pipeline.core import PipelineContext
-from engine.pipeline.params import PipelineParams
-
-# ─── FIXTURES ────────────────────────────────────────────
-
-
-class QueueDisplay:
-    """Stub display that captures every frame into a queue.
-
-    Acts as a FIFO sink so tests can inspect exactly what
-    the pipeline produced without any terminal or network I/O.
-    """
-
-    def __init__(self):
-        self.frames: queue.Queue[list[str]] = queue.Queue()
-        self.width = 80
-        self.height = 24
-        self._init_called = False
-
-    def init(self, width: int, height: int, reuse: bool = False) -> None:
-        self.width = width
-        self.height = height
-        self._init_called = True
-
-    def show(self, buffer: list[str], border: bool = False) -> None:
-        # Deep copy to prevent later mutations
-        self.frames.put(list(buffer))
-
-    def clear(self) -> None:
-        pass
-
-    def cleanup(self) -> None:
-        pass
-
-    def get_dimensions(self) -> tuple[int, int]:
-        return (self.width, self.height)
-
-
-class MarkerEffect(EffectPlugin):
-    """Effect that prepends a marker line to prove it ran.
-
-    Each MarkerEffect adds a unique tag so tests can verify
-    which effects executed and in what order.
-    """
-
-    def __init__(self, tag: str = "MARKER"):
-        self._tag = tag
-        self.call_count = 0
-        super().__init__()
-
-    @property
-    def name(self) -> str:
-        return f"marker-{self._tag}"
-
-    def configure(self, config: dict) -> None:
-        pass
-
-    def process(self, buffer: list[str], ctx: EffectContext) -> list[str]:
-        self.call_count += 1
-        if buffer is None:
-            return [f"[{self._tag}:EMPTY]"]
-        return [f"[{self._tag}]"] + list(buffer)
-
-
-# ─── HELPERS ─────────────────────────────────────────────
-
-
-def _build_pipeline(
-    items: list,
-    effects: list[tuple[str, EffectPlugin]] | None = None,
-    use_font_stage: bool = False,
-    width: int = 80,
-    height: int = 24,
-) -> tuple[Pipeline, QueueDisplay, PipelineContext]:
-    """Build a fully-wired pipeline with a QueueDisplay sink.
-
-    Args:
-        items: Content items to feed into the source.
-        effects: Optional list of (name, EffectPlugin) to add.
-        use_font_stage: Use FontStage instead of SourceItemsToBufferStage.
-        width: Viewport width.
-        height: Viewport height.
-
-    Returns:
-        (pipeline, queue_display, context) tuple.
-    """
-    display = QueueDisplay()
-
-    ctx = PipelineContext()
-    params = PipelineParams()
-    params.viewport_width = width
-    params.viewport_height = height
-    params.frame_number = 0
-    ctx.params = params
-    ctx.set("items", items)
-
-    pipeline = Pipeline(
-        config=PipelineConfig(enable_metrics=True),
-        context=ctx,
-    )
-
-    # Source stage
-    source = ListDataSource(items, name="test-source")
-    pipeline.add_stage("source", DataSourceStage(source, name="test-source"))
-
-    # Render stage
-    if use_font_stage:
-        pipeline.add_stage("render", FontStage(name="font"))
-    else:
-        pipeline.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
-
-    # Effect stages
-    if effects:
-        for effect_name, effect_plugin in effects:
-            pipeline.add_stage(
-                f"effect_{effect_name}",
-                EffectPluginStage(effect_plugin, name=effect_name),
-            )
-
-    # Display stage
-    pipeline.add_stage("display", DisplayStage(display, name="queue"))
-
-    pipeline.build()
-    pipeline.initialize()
-
-    return pipeline, display, ctx
-
-
-# ─── TESTS: HAPPY PATH ──────────────────────────────────
-
-
-class TestPipelineE2EHappyPath:
-    """End-to-end: data flows source -> render -> display."""
-
-    def test_items_reach_display(self):
-        """Content items fed to source must appear in the display output."""
-        items = [
-            SourceItem(content="Hello World", source="test", timestamp="now"),
-            SourceItem(content="Second Item", source="test", timestamp="now"),
-        ]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        result = pipeline.execute(items)
-
-        assert result.success, f"Pipeline failed: {result.error}"
-        frame = display.frames.get(timeout=1)
-        text = "\n".join(frame)
-        assert "Hello World" in text
-        assert "Second Item" in text
-
-    def test_pipeline_output_is_list_of_strings(self):
-        """Display must receive list[str], not raw SourceItems."""
-        items = [SourceItem(content="Line one", source="s", timestamp="t")]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        assert isinstance(frame, list)
-        for line in frame:
-            assert isinstance(line, str), f"Expected str, got {type(line)}: {line!r}"
-
-    def test_multiline_items_are_split(self):
-        """Items with newlines should be split into individual buffer lines."""
-        items = [
-            SourceItem(content="Line A\nLine B\nLine C", source="s", timestamp="t")
-        ]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        assert "Line A" in frame
-        assert "Line B" in frame
-        assert "Line C" in frame
-
-    def test_empty_source_produces_empty_buffer(self):
-        """An empty source should produce an empty (or blank) frame."""
-        items = []
-        pipeline, display, ctx = _build_pipeline(items)
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        assert isinstance(frame, list)
-
-    def test_multiple_frames_are_independent(self):
-        """Each execute() call should produce a distinct frame."""
-        items = [SourceItem(content="frame-content", source="s", timestamp="t")]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        pipeline.execute(items)
-        pipeline.execute(items)
-
-        f1 = display.frames.get(timeout=1)
-        f2 = display.frames.get(timeout=1)
-        assert f1 == f2  # Same input => same output
-        assert display.frames.empty()  # Exactly 2 frames
-
-
-# ─── TESTS: EFFECTS IN THE PIPELINE ─────────────────────
-
-
-class TestPipelineE2EEffects:
-    """End-to-end: effects process the buffer between render and display."""
-
-    def test_single_effect_modifies_output(self):
-        """A single effect should visibly modify the output frame."""
-        items = [SourceItem(content="Original", source="s", timestamp="t")]
-        marker = MarkerEffect("FX1")
-        pipeline, display, ctx = _build_pipeline(items, effects=[("marker", marker)])
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        assert "[FX1]" in frame, f"Marker not found in frame: {frame}"
-        assert "Original" in "\n".join(frame)
-
-    def test_effect_chain_ordering(self):
-        """Multiple effects execute in the order they were added."""
-        items = [SourceItem(content="data", source="s", timestamp="t")]
-        fx_a = MarkerEffect("A")
-        fx_b = MarkerEffect("B")
-        pipeline, display, ctx = _build_pipeline(
-            items, effects=[("alpha", fx_a), ("beta", fx_b)]
-        )
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        text = "\n".join(frame)
-        # B runs after A, so B's marker is prepended last => appears first
-        idx_a = text.index("[A]")
-        idx_b = text.index("[B]")
-        assert idx_b < idx_a, f"Expected [B] before [A], got: {frame}"
-
-    def test_effect_receives_list_of_strings(self):
-        """Effects must receive list[str] from the render stage."""
-        items = [SourceItem(content="check-type", source="s", timestamp="t")]
-        received_types = []
-
-        class TypeCheckEffect(EffectPlugin):
-            @property
-            def name(self):
-                return "typecheck"
-
-            def configure(self, config):
-                pass
-
-            def process(self, buffer, ctx):
-                received_types.append(type(buffer).__name__)
-                if isinstance(buffer, list):
-                    for item in buffer:
-                        received_types.append(type(item).__name__)
-                return buffer
-
-        pipeline, display, ctx = _build_pipeline(
-            items, effects=[("typecheck", TypeCheckEffect())]
-        )
-
-        pipeline.execute(items)
-
-        assert received_types[0] == "list", f"Buffer type: {received_types[0]}"
-        # All elements should be strings
-        for t in received_types[1:]:
-            assert t == "str", f"Buffer element type: {t}"
-
-    def test_disabled_effect_is_skipped(self):
-        """A disabled effect should not process data."""
-        items = [SourceItem(content="data", source="s", timestamp="t")]
-        marker = MarkerEffect("DISABLED")
-        pipeline, display, ctx = _build_pipeline(
-            items, effects=[("disabled-fx", marker)]
-        )
-
-        # Disable the effect stage
-        stage = pipeline.get_stage("effect_disabled-fx")
-        stage.set_enabled(False)
-
-        result = pipeline.execute(items)
-
-        assert result.success
-        frame = display.frames.get(timeout=1)
-        assert "[DISABLED]" not in frame, "Disabled effect should not run"
-        assert marker.call_count == 0
-
-
-# ─── TESTS: STAGE EXECUTION ORDER & METRICS ─────────────
-
-
-class TestPipelineE2EStageOrder:
-    """Verify all stages execute and metrics are collected."""
-
-    def test_all_stages_appear_in_execution_order(self):
-        """Pipeline build must include source, render, and display."""
-        items = [SourceItem(content="x", source="s", timestamp="t")]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        order = pipeline.execution_order
-        assert "source" in order
-        assert "render" in order
-        assert "display" in order
-
-    def test_execution_order_is_source_render_display(self):
-        """Source must come before render, render before display."""
-        items = [SourceItem(content="x", source="s", timestamp="t")]
-        pipeline, display, ctx = _build_pipeline(items)
-
-        order = pipeline.execution_order
-        assert order.index("source") < order.index("render")
-        assert order.index("render") < order.index("display")
-
-    def test_effects_between_render_and_display(self):
-        """Effects must execute after render and before display."""
-        items = [SourceItem(content="x", source="s", timestamp="t")]
-        marker = MarkerEffect("MID")
-        pipeline, display, ctx = _build_pipeline(items, effects=[("mid", marker)])
-
-        order = pipeline.execution_order
-        render_idx = order.index("render")
-        display_idx = order.index("display")
-        effect_idx = order.index("effect_mid")
-        assert render_idx < effect_idx < display_idx
-
-    def test_metrics_collected_for_all_stages(self):
-        """After execution, metrics should exist for every active stage."""
-        items = [SourceItem(content="x", source="s", timestamp="t")]
-        marker = MarkerEffect("M")
-        pipeline, display, ctx = _build_pipeline(items, effects=[("m", marker)])
-
-        pipeline.execute(items)
-
-        summary = pipeline.get_metrics_summary()
-        assert "stages" in summary
-        stage_names = set(summary["stages"].keys())
-        # All regular (non-overlay) stages should have metrics
-        assert "source" in stage_names
-        assert "render" in stage_names
-        assert "display" in stage_names
-        assert "effect_m" in stage_names
-
-
-# ─── TESTS: FONT STAGE DATAFLOW ─────────────────────────
-
-
-class TestFontStageDataflow:
-    """Verify FontStage correctly renders content through make_block.
-
-    These tests expose the tuple-unpacking bug in FontStage.process()
-    where make_block returns (lines, color, meta_idx) but the code
-    does result.extend(block) instead of result.extend(block[0]).
-    """
-
-    def test_font_stage_unpacks_make_block_correctly(self):
-        """FontStage must produce list[str] output, not mixed types."""
-        items = [
-            SourceItem(content="Test Headline", source="test-src", timestamp="12345")
-        ]
-
-        # Mock make_block to return its documented signature
-        mock_lines = ["  RENDERED LINE 1", "  RENDERED LINE 2", "", "  meta info"]
-        mock_return = (mock_lines, "\033[38;5;46m", 3)
-
-        with patch("engine.render.make_block", return_value=mock_return):
-            pipeline, display, ctx = _build_pipeline(items, use_font_stage=True)
-
-            result = pipeline.execute(items)
-
-            assert result.success, f"Pipeline failed: {result.error}"
-            frame = display.frames.get(timeout=1)
-
-            # Every element in the frame must be a string
-            for i, line in enumerate(frame):
-                assert isinstance(line, str), (
-                    f"Frame line {i} is {type(line).__name__}: {line!r} "
-                    f"(FontStage likely extended with raw tuple)"
-                )
-
-    def test_font_stage_output_contains_rendered_content(self):
-        """FontStage output should contain the rendered lines, not color codes."""
-        items = [SourceItem(content="My Headline", source="src", timestamp="0")]
-
-        mock_lines = ["  BIG BLOCK TEXT", "  MORE TEXT", "", "  ░ src · 0"]
-        mock_return = (mock_lines, "\033[38;5;46m", 3)
-
-        with patch("engine.render.make_block", return_value=mock_return):
-            pipeline, display, ctx = _build_pipeline(items, use_font_stage=True)
-
-            result = pipeline.execute(items)
-
-            assert result.success
-            frame = display.frames.get(timeout=1)
-            text = "\n".join(frame)
-            assert "BIG BLOCK TEXT" in text
-            assert "MORE TEXT" in text
-
-    def test_font_stage_does_not_leak_color_codes_as_lines(self):
-        """The ANSI color code from make_block must NOT appear as a frame line."""
-        items = [SourceItem(content="Headline", source="s", timestamp="0")]
-
-        color_code = "\033[38;5;46m"
-        mock_return = (["  rendered"], color_code, 0)
-
-        with patch("engine.render.make_block", return_value=mock_return):
-            pipeline, display, ctx = _build_pipeline(items, use_font_stage=True)
-
-            result = pipeline.execute(items)
-
-            assert result.success
-            frame = display.frames.get(timeout=1)
-            # The color code itself should not be a standalone line
-            assert color_code not in frame, (
-                f"Color code leaked as a frame line: {frame}"
-            )
-            # The meta_row_index (int) should not be a line either
-            for line in frame:
-                assert not isinstance(line, int), f"Integer leaked into frame: {line}"
-
-    def test_font_stage_handles_multiple_items(self):
-        """FontStage should render each item through make_block."""
-        items = [
-            SourceItem(content="First", source="a", timestamp="1"),
-            SourceItem(content="Second", source="b", timestamp="2"),
-        ]
-
-        call_count = 0
-
-        def mock_make_block(title, src, ts, w):
-            nonlocal call_count
-            call_count += 1
-            return ([f"  [{title}]"], "\033[0m", 0)
-
-        with patch("engine.render.make_block", side_effect=mock_make_block):
-            pipeline, display, ctx = _build_pipeline(items, use_font_stage=True)
-
-            result = pipeline.execute(items)
-
-            assert result.success
-            assert call_count == 2, f"make_block called {call_count} times, expected 2"
-            frame = display.frames.get(timeout=1)
-            text = "\n".join(frame)
-            assert "[First]" in text
-            assert "[Second]" in text
-
-
-# ─── TESTS: MIRROR OF app.py ASSEMBLY ───────────────────
-
-
-class TestAppPipelineAssembly:
-    """Verify the pipeline as assembled by app.py works end-to-end.
-
-    This mirrors how run_pipeline_mode() builds the pipeline but
-    without any network or terminal dependencies.
-    """
-
-    def test_demo_preset_pipeline_produces_output(self):
-        """Simulates the 'demo' preset pipeline with stub data."""
-        # Simulate what app.py does for the demo preset
-        items = [
-            ("Breaking: Test passes", "UnitTest", "1234567890"),
-            ("Update: Coverage improves", "CI", "1234567891"),
-        ]
-
-        display = QueueDisplay()
-        ctx = PipelineContext()
-        params = PipelineParams()
-        params.viewport_width = 80
-        params.viewport_height = 24
-        params.frame_number = 0
-        ctx.params = params
-        ctx.set("items", items)
-
-        pipeline = Pipeline(
-            config=PipelineConfig(enable_metrics=True),
-            context=ctx,
-        )
-
-        # Mirror app.py: ListDataSource -> SourceItemsToBufferStage -> display
-        source = ListDataSource(items, name="headlines")
-        pipeline.add_stage("source", DataSourceStage(source, name="headlines"))
-        pipeline.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
-        pipeline.add_stage("display", DisplayStage(display, name="queue"))
-
-        pipeline.build()
-        pipeline.initialize()
-
-        result = pipeline.execute(items)
-
-        assert result.success, f"Pipeline failed: {result.error}"
-        assert not display.frames.empty(), "Display received no frames"
-
-        frame = display.frames.get(timeout=1)
-        assert isinstance(frame, list)
-        assert len(frame) > 0
-        # All lines must be strings
-        for line in frame:
-            assert isinstance(line, str)

tests/test_pipeline_introspection.py

@@ -1,171 +0,0 @@
-"""
-Tests for PipelineIntrospectionSource.
-"""
-
-from engine.data_sources.pipeline_introspection import PipelineIntrospectionSource
-
-
-class TestPipelineIntrospectionSource:
-    """Tests for PipelineIntrospectionSource."""
-
-    def test_basic_init(self):
-        """Source initializes with defaults."""
-        source = PipelineIntrospectionSource()
-        assert source.name == "pipeline-inspect"
-        assert source.is_dynamic is True
-        assert source.frame == 0
-        assert source.ready is False
-
-    def test_init_with_params(self):
-        """Source initializes with custom params."""
-        source = PipelineIntrospectionSource(viewport_width=100, viewport_height=40)
-        assert source.viewport_width == 100
-        assert source.viewport_height == 40
-
-    def test_inlet_outlet_types(self):
-        """Source has correct inlet/outlet types."""
-        source = PipelineIntrospectionSource()
-        from engine.pipeline.core import DataType
-
-        assert DataType.NONE in source.inlet_types
-        assert DataType.SOURCE_ITEMS in source.outlet_types
-
-    def test_fetch_returns_items(self):
-        """fetch() returns SourceItem list."""
-        source = PipelineIntrospectionSource()
-        items = source.fetch()
-        assert len(items) == 1
-        assert items[0].source == "pipeline-inspect"
-
-    def test_fetch_increments_frame(self):
-        """fetch() increments frame counter when ready."""
-        source = PipelineIntrospectionSource()
-        assert source.frame == 0
-
-        # Set pipeline first to make source ready
-        class MockPipeline:
-            stages = {}
-            execution_order = []
-
-            def get_metrics_summary(self):
-                return {"avg_ms": 10.0, "fps": 60, "stages": {}}
-
-            def get_frame_times(self):
-                return [10.0, 12.0, 11.0]
-
-        source.set_pipeline(MockPipeline())
-        assert source.ready is True
-
-        source.fetch()
-        assert source.frame == 1
-        source.fetch()
-        assert source.frame == 2
-
-    def test_get_items(self):
-        """get_items() returns list of SourceItems."""
-        source = PipelineIntrospectionSource()
-        items = source.get_items()
-        assert isinstance(items, list)
-        assert len(items) > 0
-        assert items[0].source == "pipeline-inspect"
-
-    def test_set_pipeline(self):
-        """set_pipeline() marks source as ready."""
-        source = PipelineIntrospectionSource()
-        assert source.ready is False
-
-        class MockPipeline:
-            stages = {}
-            execution_order = []
-
-            def get_metrics_summary(self):
-                return {"avg_ms": 10.0, "fps": 60, "stages": {}}
-
-            def get_frame_times(self):
-                return [10.0, 12.0, 11.0]
-
-        source.set_pipeline(MockPipeline())
-        assert source.ready is True
-
-
-class TestPipelineIntrospectionRender:
-    """Tests for rendering methods."""
-
-    def test_render_header_no_pipeline(self):
-        """_render_header returns default when no pipeline."""
-        source = PipelineIntrospectionSource()
-        lines = source._render_header()
-        assert len(lines) == 1
-        assert "PIPELINE INTROSPECTION" in lines[0]
-
-    def test_render_bar(self):
-        """_render_bar creates correct bar."""
-        source = PipelineIntrospectionSource()
-        bar = source._render_bar(50, 10)
-        assert len(bar) == 10
-        assert bar.count("█") == 5
-        assert bar.count("░") == 5
-
-    def test_render_bar_zero(self):
-        """_render_bar handles zero percentage."""
-        source = PipelineIntrospectionSource()
-        bar = source._render_bar(0, 10)
-        assert bar == "░" * 10
-
-    def test_render_bar_full(self):
-        """_render_bar handles 100%."""
-        source = PipelineIntrospectionSource()
-        bar = source._render_bar(100, 10)
-        assert bar == "█" * 10
-
-    def test_render_sparkline(self):
-        """_render_sparkline creates sparkline."""
-        source = PipelineIntrospectionSource()
-        values = [1.0, 2.0, 3.0, 4.0, 5.0]
-        sparkline = source._render_sparkline(values, 10)
-        assert len(sparkline) == 10
-
-    def test_render_sparkline_empty(self):
-        """_render_sparkline handles empty values."""
-        source = PipelineIntrospectionSource()
-        sparkline = source._render_sparkline([], 10)
-        assert sparkline == " " * 10
-
-    def test_render_footer_no_pipeline(self):
-        """_render_footer shows collecting data when no pipeline."""
-        source = PipelineIntrospectionSource()
-        lines = source._render_footer()
-        assert len(lines) >= 2
-
-
-class TestPipelineIntrospectionFull:
-    """Integration tests."""
-
-    def test_render_empty(self):
-        """_render works when not ready."""
-        source = PipelineIntrospectionSource()
-        lines = source._render()
-        assert len(lines) > 0
-        assert "PIPELINE INTROSPECTION" in lines[0]
-
-    def test_render_with_mock_pipeline(self):
-        """_render works with mock pipeline."""
-        source = PipelineIntrospectionSource()
-
-        class MockStage:
-            category = "source"
-            name = "test"
-
-        class MockPipeline:
-            stages = {"test": MockStage()}
-            execution_order = ["test"]
-
-            def get_metrics_summary(self):
-                return {"stages": {"test": {"avg_ms": 1.5}}, "avg_ms": 2.0, "fps": 60}
-
-            def get_frame_times(self):
-                return [1.0, 2.0, 3.0]
-
-        source.set_pipeline(MockPipeline())
-        lines = source._render()
-        assert len(lines) > 0

tests/test_pipeline_introspection_demo.py

@@ -1,167 +0,0 @@
-"""
-Tests for PipelineIntrospectionDemo.
-"""
-
-from engine.pipeline.pipeline_introspection_demo import (
-    DemoConfig,
-    DemoPhase,
-    PhaseState,
-    PipelineIntrospectionDemo,
-)
-
-
-class MockPipeline:
-    """Mock pipeline for testing."""
-
-    pass
-
-
-class MockEffectConfig:
-    """Mock effect config."""
-
-    def __init__(self):
-        self.enabled = False
-        self.intensity = 0.5
-
-
-class MockEffect:
-    """Mock effect for testing."""
-
-    def __init__(self, name):
-        self.name = name
-        self.config = MockEffectConfig()
-
-
-class MockRegistry:
-    """Mock effect registry."""
-
-    def __init__(self, effects):
-        self._effects = {e.name: e for e in effects}
-
-    def get(self, name):
-        return self._effects.get(name)
-
-
-class TestDemoPhase:
-    """Tests for DemoPhase enum."""
-
-    def test_phases_exist(self):
-        """All three phases exist."""
-        assert DemoPhase.PHASE_1_TOGGLE is not None
-        assert DemoPhase.PHASE_2_LFO is not None
-        assert DemoPhase.PHASE_3_SHARED_LFO is not None
-
-
-class TestDemoConfig:
-    """Tests for DemoConfig."""
-
-    def test_defaults(self):
-        """Default config has sensible values."""
-        config = DemoConfig()
-        assert config.effect_cycle_duration == 3.0
-        assert config.gap_duration == 1.0
-        assert config.lfo_duration == 4.0
-        assert config.phase_2_effect_duration == 4.0
-        assert config.phase_3_lfo_duration == 6.0
-
-
-class TestPhaseState:
-    """Tests for PhaseState."""
-
-    def test_defaults(self):
-        """PhaseState initializes correctly."""
-        state = PhaseState(phase=DemoPhase.PHASE_1_TOGGLE, start_time=0.0)
-        assert state.phase == DemoPhase.PHASE_1_TOGGLE
-        assert state.start_time == 0.0
-        assert state.current_effect_index == 0
-
-
-class TestPipelineIntrospectionDemo:
-    """Tests for PipelineIntrospectionDemo."""
-
-    def test_basic_init(self):
-        """Demo initializes with defaults."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        assert demo.phase == DemoPhase.PHASE_1_TOGGLE
-        assert demo.effect_names == ["noise", "fade", "glitch", "firehose"]
-
-    def test_init_with_custom_effects(self):
-        """Demo initializes with custom effects."""
-        demo = PipelineIntrospectionDemo(pipeline=None, effect_names=["noise", "fade"])
-        assert demo.effect_names == ["noise", "fade"]
-
-    def test_phase_display(self):
-        """phase_display returns correct string."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        assert "Phase 1" in demo.phase_display
-
-    def test_shared_oscillator_created(self):
-        """Shared oscillator is created."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        assert demo.shared_oscillator is not None
-        assert demo.shared_oscillator.name == "demo-lfo"
-
-
-class TestPipelineIntrospectionDemoUpdate:
-    """Tests for update method."""
-
-    def test_update_returns_dict(self):
-        """update() returns a dict with expected keys."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        result = demo.update()
-        assert "phase" in result
-        assert "phase_display" in result
-        assert "effect_states" in result
-
-    def test_update_phase_1_structure(self):
-        """Phase 1 has correct structure."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        result = demo.update()
-        assert result["phase"] == "PHASE_1_TOGGLE"
-        assert "current_effect" in result
-
-    def test_effect_states_structure(self):
-        """effect_states has correct structure."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        result = demo.update()
-        states = result["effect_states"]
-        for name in demo.effect_names:
-            assert name in states
-            assert "enabled" in states[name]
-            assert "intensity" in states[name]
-
-
-class TestPipelineIntrospectionDemoPhases:
-    """Tests for phase transitions."""
-
-    def test_phase_1_initial(self):
-        """Starts in phase 1."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        assert demo.phase == DemoPhase.PHASE_1_TOGGLE
-
-    def test_shared_oscillator_not_started_initially(self):
-        """Shared oscillator not started in phase 1."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        assert demo.shared_oscillator is not None
-        # The oscillator.start() is called when transitioning to phase 3
-
-
-class TestPipelineIntrospectionDemoCleanup:
-    """Tests for cleanup method."""
-
-    def test_cleanup_no_error(self):
-        """cleanup() runs without error."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        demo.cleanup()  # Should not raise
-
-    def test_cleanup_resets_effects(self):
-        """cleanup() resets effects."""
-        demo = PipelineIntrospectionDemo(pipeline=None)
-        demo._apply_effect_states(
-            {
-                "noise": {"enabled": True, "intensity": 1.0},
-                "fade": {"enabled": True, "intensity": 1.0},
-            }
-        )
-        demo.cleanup()
-        # If we had a mock registry, we could verify effects were reset

tests/test_pipeline_metrics_sensor.py

@@ -1,113 +0,0 @@
-"""
-Tests for PipelineMetricsSensor.
-"""
-
-from engine.sensors.pipeline_metrics import PipelineMetricsSensor
-
-
-class MockPipeline:
-    """Mock pipeline for testing."""
-
-    def __init__(self, metrics=None):
-        self._metrics = metrics or {}
-
-    def get_metrics_summary(self):
-        return self._metrics
-
-
-class TestPipelineMetricsSensor:
-    """Tests for PipelineMetricsSensor."""
-
-    def test_basic_init(self):
-        """Sensor initializes with defaults."""
-        sensor = PipelineMetricsSensor()
-        assert sensor.name == "pipeline"
-        assert sensor.available is False
-
-    def test_init_with_pipeline(self):
-        """Sensor initializes with pipeline."""
-        mock = MockPipeline()
-        sensor = PipelineMetricsSensor(mock)
-        assert sensor.available is True
-
-    def test_set_pipeline(self):
-        """set_pipeline() updates pipeline."""
-        sensor = PipelineMetricsSensor()
-        assert sensor.available is False
-        sensor.set_pipeline(MockPipeline())
-        assert sensor.available is True
-
-    def test_read_no_pipeline(self):
-        """read() returns None when no pipeline."""
-        sensor = PipelineMetricsSensor()
-        assert sensor.read() is None
-
-    def test_read_with_metrics(self):
-        """read() returns sensor value with metrics."""
-        mock = MockPipeline(
-            {
-                "total_ms": 18.5,
-                "fps": 54.0,
-                "avg_ms": 18.5,
-                "min_ms": 15.0,
-                "max_ms": 22.0,
-                "stages": {"render": {"avg_ms": 12.0}, "noise": {"avg_ms": 3.0}},
-            }
-        )
-        sensor = PipelineMetricsSensor(mock)
-        val = sensor.read()
-        assert val is not None
-        assert val.sensor_name == "pipeline"
-        assert val.value == 18.5
-
-    def test_read_with_error(self):
-        """read() returns None when metrics have error."""
-        mock = MockPipeline({"error": "No metrics collected"})
-        sensor = PipelineMetricsSensor(mock)
-        assert sensor.read() is None
-
-    def test_get_stage_timing(self):
-        """get_stage_timing() returns stage timing."""
-        mock = MockPipeline(
-            {
-                "stages": {"render": {"avg_ms": 12.0}, "noise": {"avg_ms": 3.0}},
-            }
-        )
-        sensor = PipelineMetricsSensor(mock)
-        assert sensor.get_stage_timing("render") == 12.0
-        assert sensor.get_stage_timing("noise") == 3.0
-        assert sensor.get_stage_timing("nonexistent") == 0.0
-
-    def test_get_stage_timing_no_pipeline(self):
-        """get_stage_timing() returns 0 when no pipeline."""
-        sensor = PipelineMetricsSensor()
-        assert sensor.get_stage_timing("test") == 0.0
-
-    def test_get_all_timings(self):
-        """get_all_timings() returns all stage timings."""
-        mock = MockPipeline(
-            {
-                "stages": {"render": {"avg_ms": 12.0}, "noise": {"avg_ms": 3.0}},
-            }
-        )
-        sensor = PipelineMetricsSensor(mock)
-        timings = sensor.get_all_timings()
-        assert timings == {"render": {"avg_ms": 12.0}, "noise": {"avg_ms": 3.0}}
-
-    def test_get_frame_history(self):
-        """get_frame_history() returns frame times."""
-        MockPipeline()
-
-        class MockPipelineWithFrames:
-            def get_frame_times(self):
-                return [1.0, 2.0, 3.0]
-
-        sensor = PipelineMetricsSensor(MockPipelineWithFrames())
-        history = sensor.get_frame_history()
-        assert history == [1.0, 2.0, 3.0]
-
-    def test_start_stop(self):
-        """start() and stop() work."""
-        sensor = PipelineMetricsSensor()
-        assert sensor.start() is True
-        sensor.stop()  # Should not raise

tests/test_sensors.py

@@ -1,473 +0,0 @@
-"""
-Tests for the sensor framework.
-"""
-
-import time
-
-from engine.sensors import Sensor, SensorRegistry, SensorStage, SensorValue
-
-
-class TestSensorValue:
-    """Tests for SensorValue dataclass."""
-
-    def test_create_sensor_value(self):
-        """SensorValue stores sensor data correctly."""
-        value = SensorValue(
-            sensor_name="mic",
-            value=42.5,
-            timestamp=1234567890.0,
-            unit="dB",
-        )
-
-        assert value.sensor_name == "mic"
-        assert value.value == 42.5
-        assert value.timestamp == 1234567890.0
-        assert value.unit == "dB"
-
-
-class DummySensor(Sensor):
-    """Dummy sensor for testing."""
-
-    def __init__(self, name: str = "dummy", value: float = 1.0):
-        self.name = name
-        self.unit = "units"
-        self._value = value
-
-    def start(self) -> bool:
-        return True
-
-    def stop(self) -> None:
-        pass
-
-    def read(self) -> SensorValue | None:
-        return SensorValue(
-            sensor_name=self.name,
-            value=self._value,
-            timestamp=time.time(),
-            unit=self.unit,
-        )
-
-
-class TestSensorRegistry:
-    """Tests for SensorRegistry."""
-
-    def setup_method(self):
-        """Clear registry before each test."""
-        SensorRegistry._sensors.clear()
-        SensorRegistry._started = False
-
-    def test_register_sensor(self):
-        """SensorRegistry registers sensors."""
-        sensor = DummySensor()
-        SensorRegistry.register(sensor)
-
-        assert SensorRegistry.get("dummy") is sensor
-
-    def test_list_sensors(self):
-        """SensorRegistry lists registered sensors."""
-        SensorRegistry.register(DummySensor("a"))
-        SensorRegistry.register(DummySensor("b"))
-
-        sensors = SensorRegistry.list_sensors()
-        assert "a" in sensors
-        assert "b" in sensors
-
-    def test_read_all(self):
-        """SensorRegistry reads all sensor values."""
-        SensorRegistry.register(DummySensor("a", 1.0))
-        SensorRegistry.register(DummySensor("b", 2.0))
-
-        values = SensorRegistry.read_all()
-        assert values["a"] == 1.0
-        assert values["b"] == 2.0
-
-
-class TestSensorStage:
-    """Tests for SensorStage pipeline adapter."""
-
-    def setup_method(self):
-        SensorRegistry._sensors.clear()
-        SensorRegistry._started = False
-
-    def test_sensor_stage_capabilities(self):
-        """SensorStage declares correct capabilities."""
-        sensor = DummySensor("mic")
-        stage = SensorStage(sensor)
-
-        assert "sensor.mic" in stage.capabilities
-
-    def test_sensor_stage_process(self):
-        """SensorStage reads sensor and stores in context."""
-        from engine.pipeline.core import PipelineContext
-
-        sensor = DummySensor("test", 42.0)
-        stage = SensorStage(sensor, "test")
-
-        ctx = PipelineContext()
-        result = stage.process(None, ctx)
-
-        assert ctx.get_state("sensor.test") == 42.0
-        assert result is None
-
-
-class TestApplyParamBindings:
-    """Tests for sensor param bindings."""
-
-    def test_no_bindings_returns_original(self):
-        """Effect without bindings returns original config."""
-        from engine.effects.types import (
-            EffectConfig,
-            EffectPlugin,
-            apply_param_bindings,
-        )
-
-        class TestEffect(EffectPlugin):
-            name = "test"
-            config = EffectConfig()
-
-            def process(self, buf, ctx):
-                return buf
-
-            def configure(self, config):
-                pass
-
-        effect = TestEffect()
-        ctx = object()
-
-        result = apply_param_bindings(effect, ctx)
-        assert result is effect.config
-
-    def test_bindings_read_sensor_values(self):
-        """Param bindings read sensor values from context."""
-        from engine.effects.types import (
-            EffectConfig,
-            EffectPlugin,
-            apply_param_bindings,
-        )
-
-        class TestEffect(EffectPlugin):
-            name = "test"
-            config = EffectConfig(intensity=1.0)
-            param_bindings = {
-                "intensity": {"sensor": "mic", "transform": "linear"},
-            }
-
-            def process(self, buf, ctx):
-                return buf
-
-            def configure(self, config):
-                pass
-
-        from engine.effects.types import EffectContext
-
-        effect = TestEffect()
-        ctx = EffectContext(
-            terminal_width=80,
-            terminal_height=24,
-            scroll_cam=0,
-            ticker_height=20,
-        )
-        ctx.set_state("sensor.mic", 0.8)
-
-        result = apply_param_bindings(effect, ctx)
-        assert "intensity_sensor" in result.params
-
-
-class TestSensorLifecycle:
-    """Tests for sensor start/stop lifecycle."""
-
-    def setup_method(self):
-        SensorRegistry._sensors.clear()
-        SensorRegistry._started = False
-
-    def test_start_all(self):
-        """SensorRegistry starts all sensors."""
-        started = []
-
-        class StatefulSensor(Sensor):
-            name = "stateful"
-
-            def start(self) -> bool:
-                started.append("start")
-                return True
-
-            def stop(self) -> None:
-                started.append("stop")
-
-            def read(self) -> SensorValue | None:
-                return SensorValue("stateful", 1.0, 0.0)
-
-        SensorRegistry.register(StatefulSensor())
-        SensorRegistry.start_all()
-
-        assert "start" in started
-        assert SensorRegistry._started is True
-
-    def test_stop_all(self):
-        """SensorRegistry stops all sensors."""
-        stopped = []
-
-        class StatefulSensor(Sensor):
-            name = "stateful"
-
-            def start(self) -> bool:
-                return True
-
-            def stop(self) -> None:
-                stopped.append("stop")
-
-            def read(self) -> SensorValue | None:
-                return SensorValue("stateful", 1.0, 0.0)
-
-        SensorRegistry.register(StatefulSensor())
-        SensorRegistry.start_all()
-        SensorRegistry.stop_all()
-
-        assert "stop" in stopped
-        assert SensorRegistry._started is False
-
-    def test_unavailable_sensor(self):
-        """Unavailable sensor returns None from read."""
-
-        class UnavailableSensor(Sensor):
-            name = "unavailable"
-
-            @property
-            def available(self) -> bool:
-                return False
-
-            def start(self) -> bool:
-                return False
-
-            def stop(self) -> None:
-                pass
-
-            def read(self) -> SensorValue | None:
-                return None
-
-        sensor = UnavailableSensor()
-        assert sensor.available is False
-        assert sensor.read() is None
-
-
-class TestTransforms:
-    """Tests for sensor value transforms."""
-
-    def test_exponential_transform(self):
-        """Exponential transform squares the value."""
-        from engine.effects.types import (
-            EffectConfig,
-            EffectPlugin,
-            apply_param_bindings,
-        )
-
-        class TestEffect(EffectPlugin):
-            name = "test"
-            config = EffectConfig(intensity=1.0)
-            param_bindings = {
-                "intensity": {"sensor": "mic", "transform": "exponential"},
-            }
-
-            def process(self, buf, ctx):
-                return buf
-
-            def configure(self, config):
-                pass
-
-        from engine.effects.types import EffectContext
-
-        effect = TestEffect()
-        ctx = EffectContext(80, 24, 0, 20)
-        ctx.set_state("sensor.mic", 0.5)
-
-        result = apply_param_bindings(effect, ctx)
-        # 0.5^2 = 0.25, then scaled: 0.5 + 0.25*0.5 = 0.625
-        assert result.intensity != effect.config.intensity
-
-    def test_inverse_transform(self):
-        """Inverse transform inverts the value."""
-        from engine.effects.types import (
-            EffectConfig,
-            EffectPlugin,
-            apply_param_bindings,
-        )
-
-        class TestEffect(EffectPlugin):
-            name = "test"
-            config = EffectConfig(intensity=1.0)
-            param_bindings = {
-                "intensity": {"sensor": "mic", "transform": "inverse"},
-            }
-
-            def process(self, buf, ctx):
-                return buf
-
-            def configure(self, config):
-                pass
-
-        from engine.effects.types import EffectContext
-
-        effect = TestEffect()
-        ctx = EffectContext(80, 24, 0, 20)
-        ctx.set_state("sensor.mic", 0.8)
-
-        result = apply_param_bindings(effect, ctx)
-        # 1.0 - 0.8 = 0.2
-        assert abs(result.params["intensity_sensor"] - 0.2) < 0.001
-
-    def test_threshold_transform(self):
-        """Threshold transform applies binary threshold."""
-        from engine.effects.types import (
-            EffectConfig,
-            EffectPlugin,
-            apply_param_bindings,
-        )
-
-        class TestEffect(EffectPlugin):
-            name = "test"
-            config = EffectConfig(intensity=1.0)
-            param_bindings = {
-                "intensity": {
-                    "sensor": "mic",
-                    "transform": "threshold",
-                    "threshold": 0.5,
-                },
-            }
-
-            def process(self, buf, ctx):
-                return buf
-
-            def configure(self, config):
-                pass
-
-        from engine.effects.types import EffectContext
-
-        effect = TestEffect()
-        ctx = EffectContext(80, 24, 0, 20)
-
-        # Above threshold
-        ctx.set_state("sensor.mic", 0.8)
-        result = apply_param_bindings(effect, ctx)
-        assert result.params["intensity_sensor"] == 1.0
-
-        # Below threshold
-        ctx.set_state("sensor.mic", 0.3)
-        result = apply_param_bindings(effect, ctx)
-        assert result.params["intensity_sensor"] == 0.0
-
-
-class TestOscillatorSensor:
-    """Tests for OscillatorSensor."""
-
-    def setup_method(self):
-        SensorRegistry._sensors.clear()
-        SensorRegistry._started = False
-
-    def test_sine_waveform(self):
-        """Oscillator generates sine wave."""
-        from engine.sensors.oscillator import OscillatorSensor
-
-        osc = OscillatorSensor(name="test", waveform="sine", frequency=1.0)
-        osc.start()
-
-        values = [osc.read().value for _ in range(10)]
-        assert all(0 <= v <= 1 for v in values)
-
-    def test_square_waveform(self):
-        """Oscillator generates square wave."""
-        from engine.sensors.oscillator import OscillatorSensor
-
-        osc = OscillatorSensor(name="test", waveform="square", frequency=10.0)
-        osc.start()
-
-        values = [osc.read().value for _ in range(10)]
-        assert all(v in (0.0, 1.0) for v in values)
-
-    def test_waveform_types(self):
-        """All waveform types work."""
-        from engine.sensors.oscillator import OscillatorSensor
-
-        for wf in ["sine", "square", "sawtooth", "triangle", "noise"]:
-            osc = OscillatorSensor(name=wf, waveform=wf, frequency=1.0)
-            osc.start()
-            val = osc.read()
-            assert val is not None
-            assert 0 <= val.value <= 1
-
-    def test_invalid_waveform_raises(self):
-        """Invalid waveform returns None."""
-        from engine.sensors.oscillator import OscillatorSensor
-
-        osc = OscillatorSensor(waveform="invalid")
-        osc.start()
-        val = osc.read()
-        assert val is None
-
-    def test_sensor_driven_oscillator(self):
-        """Oscillator can be driven by another sensor."""
-        from engine.sensors.oscillator import OscillatorSensor
-
-        class ModSensor(Sensor):
-            name = "mod"
-
-            def start(self) -> bool:
-                return True
-
-            def stop(self) -> None:
-                pass
-
-            def read(self) -> SensorValue | None:
-                return SensorValue("mod", 0.5, 0.0)
-
-        SensorRegistry.register(ModSensor())
-
-        osc = OscillatorSensor(
-            name="lfo", waveform="sine", frequency=0.1, input_sensor="mod"
-        )
-        osc.start()
-
-        val = osc.read()
-        assert val is not None
-        assert 0 <= val.value <= 1
-
-
-class TestMicSensor:
-    """Tests for MicSensor."""
-
-    def setup_method(self):
-        SensorRegistry._sensors.clear()
-        SensorRegistry._started = False
-
-    def test_mic_sensor_creation(self):
-        """MicSensor can be created."""
-        from engine.sensors.mic import MicSensor
-
-        sensor = MicSensor()
-        assert sensor.name == "mic"
-        assert sensor.unit == "dB"
-
-    def test_mic_sensor_custom_name(self):
-        """MicSensor can have custom name."""
-        from engine.sensors.mic import MicSensor
-
-        sensor = MicSensor(name="my_mic")
-        assert sensor.name == "my_mic"
-
-    def test_mic_sensor_start(self):
-        """MicSensor.start returns bool."""
-        from engine.sensors.mic import MicSensor
-
-        sensor = MicSensor()
-        result = sensor.start()
-        assert isinstance(result, bool)
-
-    def test_mic_sensor_read_returns_value_or_none(self):
-        """MicSensor.read returns SensorValue or None."""
-        from engine.sensors.mic import MicSensor
-
-        sensor = MicSensor()
-        sensor.start()
-        # May be None if no mic available
-        result = sensor.read()
-        # Just check it doesn't raise - result depends on system
-        assert result is None or isinstance(result, SensorValue)

tests/test_sixel.py

@@ -1,128 +0,0 @@
-"""
-Tests for engine.display.backends.sixel module.
-"""
-
-from unittest.mock import MagicMock, patch
-
-
-class TestSixelDisplay:
-    """Tests for SixelDisplay class."""
-
-    def test_init_stores_dimensions(self):
-        """init stores dimensions."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay()
-        display.init(80, 24)
-        assert display.width == 80
-        assert display.height == 24
-
-    def test_init_custom_cell_size(self):
-        """init accepts custom cell size."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay(cell_width=12, cell_height=18)
-        assert display.cell_width == 12
-        assert display.cell_height == 18
-
-    def test_show_handles_empty_buffer(self):
-        """show handles empty buffer gracefully."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay()
-        display.init(80, 24)
-
-        with patch("engine.display.backends.sixel._encode_sixel") as mock_encode:
-            mock_encode.return_value = ""
-            display.show([])
-
-    def test_show_handles_pil_import_error(self):
-        """show gracefully handles missing PIL."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay()
-        display.init(80, 24)
-
-        with patch.dict("sys.modules", {"PIL": None}):
-            display.show(["test line"])
-
-    def test_clear_sends_escape_sequence(self):
-        """clear sends clear screen escape sequence."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay()
-
-        with patch("sys.stdout") as mock_stdout:
-            display.clear()
-            mock_stdout.buffer.write.assert_called()
-
-    def test_cleanup_does_nothing(self):
-        """cleanup does nothing."""
-        from engine.display.backends.sixel import SixelDisplay
-
-        display = SixelDisplay()
-        display.cleanup()
-
-
-class TestSixelAnsiParsing:
-    """Tests for ANSI parsing in SixelDisplay."""
-
-    def test_parse_empty_string(self):
-        """handles empty string."""
-        from engine.display.renderer import parse_ansi
-
-        result = parse_ansi("")
-        assert len(result) > 0
-
-    def test_parse_plain_text(self):
-        """parses plain text without ANSI codes."""
-        from engine.display.renderer import parse_ansi
-
-        result = parse_ansi("hello world")
-        assert len(result) == 1
-        text, fg, bg, bold = result[0]
-        assert text == "hello world"
-
-    def test_parse_with_color_codes(self):
-        """parses ANSI color codes."""
-        from engine.display.renderer import parse_ansi
-
-        result = parse_ansi("\033[31mred\033[0m")
-        assert len(result) == 1
-        assert result[0][0] == "red"
-        assert result[0][1] == (205, 49, 49)
-
-    def test_parse_with_bold(self):
-        """parses bold codes."""
-        from engine.display.renderer import parse_ansi
-
-        result = parse_ansi("\033[1mbold\033[0m")
-        assert len(result) == 1
-        assert result[0][0] == "bold"
-        assert result[0][3] is True
-
-    def test_parse_256_color(self):
-        """parses 256 color codes."""
-        from engine.display.renderer import parse_ansi
-
-        result = parse_ansi("\033[38;5;196mred\033[0m")
-        assert len(result) == 1
-        assert result[0][0] == "red"
-
-
-class TestSixelEncoding:
-    """Tests for Sixel encoding."""
-
-    def test_encode_empty_image(self):
-        """handles empty image."""
-        from engine.display.backends.sixel import _encode_sixel
-
-        with patch("PIL.Image.Image") as mock_image:
-            mock_img_instance = MagicMock()
-            mock_img_instance.convert.return_value = mock_img_instance
-            mock_img_instance.size = (0, 0)
-            mock_img_instance.load.return_value = {}
-            mock_image.return_value = mock_img_instance
-
-            result = _encode_sixel(mock_img_instance)
-            assert result == ""

tests/test_tint_effect.py

@@ -1,125 +0,0 @@
-import pytest
-
-from effects_plugins.tint import TintEffect
-from engine.effects.types import EffectConfig
-
-
-@pytest.fixture
-def effect():
-    return TintEffect()
-
-
-@pytest.fixture
-def effect_with_params(r=255, g=128, b=64, a=0.5):
-    e = TintEffect()
-    config = EffectConfig(
-        enabled=True,
-        intensity=1.0,
-        params={"r": r, "g": g, "b": b, "a": a},
-    )
-    e.configure(config)
-    return e
-
-
-@pytest.fixture
-def mock_context():
-    class MockContext:
-        terminal_width = 80
-        terminal_height = 24
-
-        def get_state(self, key):
-            return None
-
-    return MockContext()
-
-
-class TestTintEffect:
-    def test_name(self, effect):
-        assert effect.name == "tint"
-
-    def test_enabled_by_default(self, effect):
-        assert effect.config.enabled is True
-
-    def test_returns_input_when_empty(self, effect, mock_context):
-        result = effect.process([], mock_context)
-        assert result == []
-
-    def test_returns_input_when_transparency_zero(
-        self, effect_with_params, mock_context
-    ):
-        effect_with_params.config.params["a"] = 0.0
-        buf = ["hello world"]
-        result = effect_with_params.process(buf, mock_context)
-        assert result == buf
-
-    def test_applies_tint_to_plain_text(self, effect_with_params, mock_context):
-        buf = ["hello world"]
-        result = effect_with_params.process(buf, mock_context)
-        assert len(result) == 1
-        assert "\033[" in result[0]  # Has ANSI codes
-        assert "hello world" in result[0]
-
-    def test_tint_preserves_content(self, effect_with_params, mock_context):
-        buf = ["hello world", "test line"]
-        result = effect_with_params.process(buf, mock_context)
-        assert "hello world" in result[0]
-        assert "test line" in result[1]
-
-    def test_rgb_to_ansi256_black(self, effect):
-        assert effect._rgb_to_ansi256(0, 0, 0) == 16
-
-    def test_rgb_to_ansi256_white(self, effect):
-        assert effect._rgb_to_ansi256(255, 255, 255) == 231
-
-    def test_rgb_to_ansi256_red(self, effect):
-        color = effect._rgb_to_ansi256(255, 0, 0)
-        assert 196 <= color <= 197  # Red in 256 color
-
-    def test_rgb_to_ansi256_green(self, effect):
-        color = effect._rgb_to_ansi256(0, 255, 0)
-        assert 34 <= color <= 46
-
-    def test_rgb_to_ansi256_blue(self, effect):
-        color = effect._rgb_to_ansi256(0, 0, 255)
-        assert 20 <= color <= 33
-
-    def test_configure_updates_params(self, effect):
-        config = EffectConfig(
-            enabled=True,
-            intensity=1.0,
-            params={"r": 100, "g": 150, "b": 200, "a": 0.8},
-        )
-        effect.configure(config)
-        assert effect.config.params["r"] == 100
-        assert effect.config.params["g"] == 150
-        assert effect.config.params["b"] == 200
-        assert effect.config.params["a"] == 0.8
-
-    def test_clamp_rgb_values(self, effect_with_params, mock_context):
-        effect_with_params.config.params["r"] = 300
-        effect_with_params.config.params["g"] = -10
-        effect_with_params.config.params["b"] = 1.5
-        buf = ["test"]
-        result = effect_with_params.process(buf, mock_context)
-        assert "\033[" in result[0]
-
-    def test_clamp_alpha_above_one(self, effect_with_params, mock_context):
-        effect_with_params.config.params["a"] = 1.5
-        buf = ["test"]
-        result = effect_with_params.process(buf, mock_context)
-        assert "\033[" in result[0]
-
-    def test_preserves_empty_lines(self, effect_with_params, mock_context):
-        buf = ["hello", "", "world"]
-        result = effect_with_params.process(buf, mock_context)
-        assert result[1] == ""
-
-    def test_inlet_types_includes_text_buffer(self, effect):
-        from engine.pipeline.core import DataType
-
-        assert DataType.TEXT_BUFFER in effect.inlet_types
-
-    def test_outlet_types_includes_text_buffer(self, effect):
-        from engine.pipeline.core import DataType
-
-        assert DataType.TEXT_BUFFER in effect.outlet_types

tests/test_translate.py

@@ -1,115 +0,0 @@
-"""
-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"

tests/test_viewport_filter_performance.py

@@ -1,160 +0,0 @@
-"""Integration tests for ViewportFilterStage with realistic data volumes.
-
-These tests verify that the ViewportFilterStage effectively reduces the number
-of items processed by FontStage, preventing the 10+ second hangs observed with
-large headline sources.
-"""
-
-from engine.data_sources.sources import SourceItem
-from engine.pipeline.adapters import ViewportFilterStage
-from engine.pipeline.core import PipelineContext
-
-
-class MockParams:
-    """Mock parameters object for testing."""
-
-    def __init__(self, viewport_width: int = 80, viewport_height: int = 24):
-        self.viewport_width = viewport_width
-        self.viewport_height = viewport_height
-
-
-class TestViewportFilterStage:
-    """Test ViewportFilterStage filtering behavior."""
-
-    def test_filter_stage_exists(self):
-        """Verify ViewportFilterStage can be instantiated."""
-        stage = ViewportFilterStage()
-        assert stage is not None
-        assert stage.name == "viewport-filter"
-
-    def test_filter_stage_properties(self):
-        """Verify ViewportFilterStage has correct type properties."""
-        stage = ViewportFilterStage()
-        from engine.pipeline.core import DataType
-
-        assert DataType.SOURCE_ITEMS in stage.inlet_types
-        assert DataType.SOURCE_ITEMS in stage.outlet_types
-
-    def test_filter_large_item_count_to_viewport(self):
-        """Test filtering 1438 items (like real headlines) to viewport size."""
-        # Create 1438 test items (matching real headline source)
-        test_items = [
-            SourceItem(f"Headline {i}", f"source-{i % 5}", str(i)) for i in range(1438)
-        ]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_width=80, viewport_height=24)
-
-        # Filter items
-        filtered = stage.process(test_items, ctx)
-
-        # Verify filtering reduced item count significantly
-        assert len(filtered) < len(test_items)
-        assert len(filtered) <= 5  # 24 height / 6 lines per item + 1
-        assert len(filtered) > 0  # Must return at least 1 item
-
-    def test_filter_respects_viewport_height(self):
-        """Test that filter respects different viewport heights."""
-        test_items = [SourceItem(f"Headline {i}", "source", str(i)) for i in range(100)]
-
-        stage = ViewportFilterStage()
-
-        # Test with different viewport heights
-        for height in [12, 24, 48]:
-            ctx = PipelineContext()
-            ctx.params = MockParams(viewport_height=height)
-
-            filtered = stage.process(test_items, ctx)
-            expected_max = max(1, height // 6 + 1)
-
-            assert len(filtered) <= expected_max
-            assert len(filtered) > 0
-
-    def test_filter_handles_empty_list(self):
-        """Test filter handles empty input gracefully."""
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        result = stage.process([], ctx)
-
-        assert result == []
-
-    def test_filter_handles_none(self):
-        """Test filter handles None input gracefully."""
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        result = stage.process(None, ctx)
-
-        assert result is None
-
-    def test_filter_performance_improvement(self):
-        """Verify significant performance improvement (288x reduction)."""
-        # With 1438 items and 24-line viewport:
-        # - Without filter: FontStage renders all 1438 items
-        # - With filter: FontStage renders only ~5 items
-        # - Improvement: 1438 / 3 = ~479x fewer items to render
-        #   (layout-based filtering is more precise than old estimate)
-
-        test_items = [
-            SourceItem(f"Headline {i}", "source", str(i)) for i in range(1438)
-        ]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_height=24)
-
-        filtered = stage.process(test_items, ctx)
-        improvement_factor = len(test_items) / len(filtered)
-
-        # Verify we get at least 400x improvement (better than old ~288x)
-        assert improvement_factor > 400
-        # Verify we get the expected ~479x improvement
-        assert 400 < improvement_factor < 600
-
-
-class TestViewportFilterIntegration:
-    """Test ViewportFilterStage in pipeline context."""
-
-    def test_filter_output_is_source_items(self):
-        """Verify filter output can be consumed by FontStage."""
-        from engine.pipeline.adapters import FontStage
-
-        test_items = [
-            SourceItem("Test Headline", "test-source", "123") for _ in range(10)
-        ]
-
-        filter_stage = ViewportFilterStage()
-        font_stage = FontStage()
-
-        ctx = PipelineContext()
-        ctx.params = MockParams()
-
-        # Filter items
-        filtered = filter_stage.process(test_items, ctx)
-
-        # Verify filtered output is compatible with FontStage
-        assert isinstance(filtered, list)
-        assert all(isinstance(item, SourceItem) for item in filtered)
-
-        # FontStage should accept the filtered items
-        # (This would throw if types were incompatible)
-        result = font_stage.process(filtered, ctx)
-        assert result is not None
-
-    def test_filter_preserves_item_order(self):
-        """Verify filter preserves order of first N items."""
-        test_items = [SourceItem(f"Headline {i}", "source", str(i)) for i in range(20)]
-
-        stage = ViewportFilterStage()
-        ctx = PipelineContext()
-        ctx.params = MockParams(viewport_height=24)
-
-        filtered = stage.process(test_items, ctx)
-
-        # Verify we kept the first N items in order
-        for i, item in enumerate(filtered):
-            assert item.content == f"Headline {i}"

tests/test_vis_offset.py

@@ -1,32 +0,0 @@
-
-from engine.effects.legacy import vis_offset, vis_trunc
-
-
-def test_vis_offset_no_change():
-    """vis_offset with offset 0 returns original."""
-    result = vis_offset("hello", 0)
-    assert result == "hello"
-
-
-def test_vis_offset_trims_start():
-    """vis_offset skips first N characters."""
-    result = vis_offset("hello world", 6)
-    assert result == "world"
-
-
-def test_vis_offset_handles_ansi():
-    """vis_offset handles ANSI codes correctly."""
-    result = vis_offset("\033[31mhello\033[0m", 3)
-    assert result == "lo\x1b[0m" or "lo" in result
-
-
-def test_vis_offset_greater_than_length():
-    """vis_offset with offset > length returns empty-ish."""
-    result = vis_offset("hi", 10)
-    assert result == ""
-
-
-def test_vis_trunc_still_works():
-    """Ensure vis_trunc still works after changes."""
-    result = vis_trunc("hello world", 5)
-    assert result == "hello"

tests/test_websocket.py

@@ -1,161 +0,0 @@
-"""
-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"])

tests/test_websocket_e2e.py

@@ -1,78 +0,0 @@
-"""
-End-to-end tests for WebSocket display using Playwright.
-"""
-
-import time
-
-import pytest
-
-
-class TestWebSocketE2E:
-    """End-to-end tests for WebSocket display with browser."""
-
-    @pytest.mark.e2e
-    def test_websocket_server_starts(self):
-        """Test that WebSocket server starts and serves HTTP."""
-        import threading
-
-        from engine.display.backends.websocket import WebSocketDisplay
-
-        display = WebSocketDisplay(host="127.0.0.1", port=18765)
-
-        server_thread = threading.Thread(target=display.start_http_server)
-        server_thread.daemon = True
-        server_thread.start()
-
-        time.sleep(1)
-
-        try:
-            import urllib.request
-
-            response = urllib.request.urlopen("http://127.0.0.1:18765", timeout=5)
-            assert response.status == 200
-            content = response.read().decode("utf-8")
-            assert len(content) > 0
-        finally:
-            display.cleanup()
-            time.sleep(0.5)
-
-    @pytest.mark.e2e
-    @pytest.mark.skipif(
-        not pytest.importorskip("playwright", reason="playwright not installed"),
-        reason="playwright not installed",
-    )
-    def test_websocket_browser_connection(self):
-        """Test WebSocket connection with actual browser."""
-        import threading
-
-        from playwright.sync_api import sync_playwright
-
-        from engine.display.backends.websocket import WebSocketDisplay
-
-        display = WebSocketDisplay(host="127.0.0.1", port=18767)
-
-        server_thread = threading.Thread(target=display.start_server)
-        server_thread.daemon = True
-        server_thread.start()
-
-        http_thread = threading.Thread(target=display.start_http_server)
-        http_thread.daemon = True
-        http_thread.start()
-
-        time.sleep(1)
-
-        try:
-            with sync_playwright() as p:
-                browser = p.chromium.launch(headless=True)
-                page = browser.new_page()
-
-                page.goto("http://127.0.0.1:18767")
-                time.sleep(0.5)
-
-                title = page.title()
-                assert len(title) >= 0
-
-                browser.close()
-        finally:
-            display.cleanup()
-            time.sleep(0.5)