feat(pipeline): improve new pipeline architecture

- Add TransformDataSource for filtering/mapping source items
- Add MetricsDataSource for rendering live pipeline metrics as ASCII art
- Fix display stage registration in StageRegistry
- Register sources with both class name and simple name aliases
- Fix DisplayStage.init() to pass reuse parameter
- Simplify create_default_pipeline to use DataSourceStage wrapper
- Set pygame as default display
- Remove old pipeline tasks from mise.toml
- Add tests for new pipeline architecture

AGENTS.md

@@ -16,7 +16,7 @@ This project uses:
 mise run install
 
 # Or equivalently:
-uv sync --all-extras   # includes mic support
+uv sync --all-extras   # includes mic, websocket, sixel support
 ```
 
 ### Available Commands
@@ -60,9 +60,52 @@ hk init --mise
 mise run pre-commit
 ```
 
+**IMPORTANT**: Always review the hk documentation before modifying `hk.pkl`:
+- [hk Configuration Guide](https://hk.jdx.dev/configuration.html)
+- [hk Hooks Reference](https://hk.jdx.dev/hooks.html)
+- [hk Builtins](https://hk.jdx.dev/builtins.html)
+
 The project uses hk configured in `hk.pkl`:
 - **pre-commit**: runs ruff-format and ruff (with auto-fix)
-- **pre-push**: runs ruff check
+- **pre-push**: runs ruff check + benchmark hook
+
+## Benchmark Runner
+
+Run performance benchmarks:
+
+```bash
+mise run benchmark           # Run all benchmarks (text output)
+mise run benchmark-json     # Run benchmarks (JSON output)
+mise run benchmark-report   # Run benchmarks (Markdown report)
+```
+
+### Benchmark Commands
+
+```bash
+# Run benchmarks
+uv run python -m engine.benchmark
+
+# Run with specific displays/effects
+uv run python -m engine.benchmark --displays null,terminal --effects fade,glitch
+
+# Save baseline for hook comparisons
+uv run python -m engine.benchmark --baseline
+
+# Run in hook mode (compares against baseline)
+uv run python -m engine.benchmark --hook
+
+# Hook mode with custom threshold (default: 20% degradation)
+uv run python -m engine.benchmark --hook --threshold 0.3
+
+# Custom baseline location
+uv run python -m engine.benchmark --hook --cache /path/to/cache.json
+```
+
+### Hook Mode
+
+The `--hook` mode compares current benchmarks against a saved baseline. If performance degrades beyond the threshold (default 20%), it exits with code 1. This is useful for preventing performance regressions in feature branches.
+
+The pre-push hook runs benchmark in hook mode to catch performance regressions before pushing.
 
 ## Workflow Rules
 
@@ -116,6 +159,31 @@ 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% (336 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
+- **benchmark.py** (0%): Standalone benchmark tool, runs separately
+
+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** and **mic.py** are standalone modules with zero internal dependencies
@@ -126,13 +194,15 @@ The project uses pytest with strict marker enforcement. Test configuration is in
 
 ### Display System
 
-- **Display abstraction** (`engine/display.py`): swap display backends via the Display protocol
-  - `TerminalDisplay` - ANSI terminal output
-  - `WebSocketDisplay` - broadcasts to web clients via WebSocket
-  - `SixelDisplay` - renders to Sixel graphics (pure Python, no C dependency)
-  - `MultiDisplay` - forwards to multiple displays simultaneously
+- **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
 
-- **WebSocket display** (`engine/websocket_display.py`): real-time frame broadcasting to web browsers
+- **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
@@ -143,9 +213,27 @@ The project uses pytest with strict marker enforcement. Test configuration is in
   - `sixel` - Sixel graphics in supported terminals (iTerm2, mintty, etc.)
   - `both` - Terminal + WebSocket simultaneously
 
+### Effect Plugin System
+
+- **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
+
 ### Command & Control
 
 - 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)
+- Effects controller handles `/effects` commands (list, on/off, intensity, reorder, stats)
+
+### Pipeline Documentation
+
+The rendering pipeline is documented in `docs/PIPELINE.md` using Mermaid diagrams.
+
+**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

README.md

@@ -75,6 +75,7 @@ Mainline supports multiple display backends:
 
 - **Terminal** (`--display terminal`): ANSI terminal output (default)
 - **WebSocket** (`--display websocket`): Stream to web browser clients
+- **Sixel** (`--display sixel`): Sixel graphics in supported terminals (iTerm2, mintty)
 - **Both** (`--display both`): Terminal + WebSocket simultaneously
 
 WebSocket mode serves a web client at http://localhost:8766 with ANSI color support and fullscreen mode.
@@ -131,10 +132,17 @@ engine/
   translate.py          Google Translate wrapper + region detection
   render.py             OTF → half-block pipeline (SSAA, gradient)
   effects/              plugin architecture for visual effects
-    controller.py       handles /effects commands
-    chain.py            effect pipeline chaining
+    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
@@ -147,8 +155,15 @@ engine/
   controller.py         coordinates ntfy/mic monitoring
   emitters.py           background emitters
   types.py              type definitions
-  display.py            Display protocol (Terminal, WebSocket, Multi)
-  websocket_display.py  WebSocket server for browser clients
+  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
 ```
 
 ---
@@ -171,19 +186,25 @@ 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 test-cov       # run with coverage report
 
-mise run run             # terminal display
-mise run run-websocket   # web display only
-mise run run-both        # terminal + web
-mise run run-client      # both + open browser
+mise run lint           # ruff check
+mise run lint-fix       # ruff check --fix
+mise run format         # ruff format
 
-mise run cmd             # C&C command interface
-mise run cmd-stats       # watch effects stats
-mise run topics-init     # initialize ntfy topics
+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
@@ -191,8 +212,21 @@ mise run topics-init     # initialize ntfy topics
 ```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

docs/PIPELINE.md

@@ -0,0 +1,199 @@
+# 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
+    }
+```

effects_plugins/__init__.py

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

effects_plugins/fade.py

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

effects_plugins/firehose.py

@@ -7,7 +7,7 @@ from engine.sources import FEEDS, POETRY_SOURCES
 from engine.terminal import C_DIM, G_DIM, G_LO, RST, W_GHOST
 
 
-class FirehoseEffect:
+class FirehoseEffect(EffectPlugin):
     name = "firehose"
     config = EffectConfig(enabled=True, intensity=1.0)
 
@@ -68,5 +68,5 @@ class FirehoseEffect:
             color = random.choice([G_LO, C_DIM, W_GHOST])
             return f"{color}{text}{RST}"
 
-    def configure(self, cfg: EffectConfig) -> None:
-        self.config = cfg
+    def configure(self, config: EffectConfig) -> None:
+        self.config = config

effects_plugins/glitch.py

@@ -5,7 +5,7 @@ from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST
 
 
-class GlitchEffect:
+class GlitchEffect(EffectPlugin):
     name = "glitch"
     config = EffectConfig(enabled=True, intensity=1.0)
 
@@ -33,5 +33,5 @@ class GlitchEffect:
         o = random.randint(0, w - n)
         return " " * o + f"{G_LO}{DIM}" + c * n + RST
 
-    def configure(self, cfg: EffectConfig) -> None:
-        self.config = cfg
+    def configure(self, config: EffectConfig) -> None:
+        self.config = config

effects_plugins/hud.py

@@ -0,0 +1,63 @@
+from engine.effects.performance import get_monitor
+from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
+
+
+class HudEffect(EffectPlugin):
+    name = "hud"
+    config = EffectConfig(enabled=True, intensity=1.0)
+
+    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
+        result = list(buf)
+        monitor = get_monitor()
+
+        fps = 0.0
+        frame_time = 0.0
+        if monitor:
+            stats = monitor.get_stats()
+            if stats and "pipeline" in stats:
+                frame_time = stats["pipeline"].get("avg_ms", 0.0)
+                frame_count = stats.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"
+        )
+
+        from engine.effects import get_effect_chain
+
+        chain = get_effect_chain()
+        order = chain.get_order()
+        pipeline_str = ",".join(order) if 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:
+class NoiseEffect(EffectPlugin):
     name = "noise"
     config = EffectConfig(enabled=True, intensity=0.15)
 
@@ -32,5 +32,5 @@ class NoiseEffect:
             for _ in range(w)
         )
 
-    def configure(self, cfg: EffectConfig) -> None:
-        self.config = cfg
+    def configure(self, config: EffectConfig) -> None:
+        self.config = config

engine/animation.py

@@ -0,0 +1,340 @@
+"""
+Animation system - Clock, events, triggers, durations, and animation controller.
+"""
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Any
+
+
+class Clock:
+    """High-resolution clock for animation timing."""
+
+    def __init__(self):
+        self._start_time = time.perf_counter()
+        self._paused = False
+        self._pause_offset = 0.0
+        self._pause_start = 0.0
+
+    def reset(self) -> None:
+        self._start_time = time.perf_counter()
+        self._paused = False
+        self._pause_offset = 0.0
+        self._pause_start = 0.0
+
+    def elapsed(self) -> float:
+        if self._paused:
+            return self._pause_start - self._start_time - self._pause_offset
+        return time.perf_counter() - self._start_time - self._pause_offset
+
+    def elapsed_ms(self) -> float:
+        return self.elapsed() * 1000
+
+    def elapsed_frames(self, fps: float = 60.0) -> int:
+        return int(self.elapsed() * fps)
+
+    def pause(self) -> None:
+        if not self._paused:
+            self._paused = True
+            self._pause_start = time.perf_counter()
+
+    def resume(self) -> None:
+        if self._paused:
+            self._pause_offset += time.perf_counter() - self._pause_start
+            self._paused = False
+
+
+class TriggerType(Enum):
+    TIME = auto()  # Trigger after elapsed time
+    FRAME = auto()  # Trigger after N frames
+    CYCLE = auto()  # Trigger on cycle repeat
+    CONDITION = auto()  # Trigger when condition is met
+    MANUAL = auto()  # Trigger manually
+
+
+@dataclass
+class Trigger:
+    """Event trigger configuration."""
+
+    type: TriggerType
+    value: float | int = 0
+    condition: Callable[["AnimationController"], bool] | None = None
+    repeat: bool = False
+    repeat_interval: float = 0.0
+
+
+@dataclass
+class Event:
+    """An event with trigger, duration, and action."""
+
+    name: str
+    trigger: Trigger
+    action: Callable[["AnimationController", float], None]
+    duration: float = 0.0
+    ease: Callable[[float], float] | None = None
+
+    def __post_init__(self):
+        if self.ease is None:
+            self.ease = linear_ease
+
+
+def linear_ease(t: float) -> float:
+    return t
+
+
+def ease_in_out(t: float) -> float:
+    return t * t * (3 - 2 * t)
+
+
+def ease_out_bounce(t: float) -> float:
+    if t < 1 / 2.75:
+        return 7.5625 * t * t
+    elif t < 2 / 2.75:
+        t -= 1.5 / 2.75
+        return 7.5625 * t * t + 0.75
+    elif t < 2.5 / 2.75:
+        t -= 2.25 / 2.75
+        return 7.5625 * t * t + 0.9375
+    else:
+        t -= 2.625 / 2.75
+        return 7.5625 * t * t + 0.984375
+
+
+class AnimationController:
+    """Controls animation parameters with clock and events."""
+
+    def __init__(self, fps: float = 60.0):
+        self.clock = Clock()
+        self.fps = fps
+        self.frame = 0
+        self._events: list[Event] = []
+        self._active_events: dict[str, float] = {}
+        self._params: dict[str, Any] = {}
+        self._cycled = 0
+
+    def add_event(self, event: Event) -> "AnimationController":
+        self._events.append(event)
+        return self
+
+    def set_param(self, key: str, value: Any) -> None:
+        self._params[key] = value
+
+    def get_param(self, key: str, default: Any = None) -> Any:
+        return self._params.get(key, default)
+
+    def update(self) -> dict[str, Any]:
+        """Update animation state, return current params."""
+        elapsed = self.clock.elapsed()
+
+        for event in self._events:
+            triggered = False
+
+            if event.trigger.type == TriggerType.TIME:
+                if self.clock.elapsed() >= event.trigger.value:
+                    triggered = True
+            elif event.trigger.type == TriggerType.FRAME:
+                if self.frame >= event.trigger.value:
+                    triggered = True
+            elif event.trigger.type == TriggerType.CYCLE:
+                cycle_duration = event.trigger.value
+                if cycle_duration > 0:
+                    current_cycle = int(elapsed / cycle_duration)
+                    if current_cycle > self._cycled:
+                        self._cycled = current_cycle
+                        triggered = True
+            elif event.trigger.type == TriggerType.CONDITION:
+                if event.trigger.condition and event.trigger.condition(self):
+                    triggered = True
+            elif event.trigger.type == TriggerType.MANUAL:
+                pass
+
+            if triggered:
+                if event.name not in self._active_events:
+                    self._active_events[event.name] = 0.0
+
+                progress = 0.0
+                if event.duration > 0:
+                    self._active_events[event.name] += 1 / self.fps
+                    progress = min(
+                        1.0, self._active_events[event.name] / event.duration
+                    )
+                    eased_progress = event.ease(progress)
+                    event.action(self, eased_progress)
+
+                    if progress >= 1.0:
+                        if event.trigger.repeat:
+                            self._active_events[event.name] = 0.0
+                        else:
+                            del self._active_events[event.name]
+                else:
+                    event.action(self, 1.0)
+                    if not event.trigger.repeat:
+                        del self._active_events[event.name]
+                    else:
+                        self._active_events[event.name] = 0.0
+
+        self.frame += 1
+        return dict(self._params)
+
+
+@dataclass
+class PipelineParams:
+    """Snapshot of pipeline parameters for animation."""
+
+    effect_enabled: dict[str, bool] = field(default_factory=dict)
+    effect_intensity: dict[str, float] = field(default_factory=dict)
+    camera_mode: str = "vertical"
+    camera_speed: float = 1.0
+    camera_x: int = 0
+    camera_y: int = 0
+    display_backend: str = "terminal"
+    scroll_speed: float = 1.0
+
+
+class Preset:
+    """Packages a starting pipeline config + Animation controller."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str = "",
+        initial_params: PipelineParams | None = None,
+        animation: AnimationController | None = None,
+    ):
+        self.name = name
+        self.description = description
+        self.initial_params = initial_params or PipelineParams()
+        self.animation = animation or AnimationController()
+
+    def create_controller(self) -> AnimationController:
+        controller = AnimationController()
+        for key, value in self.initial_params.__dict__.items():
+            controller.set_param(key, value)
+        for event in self.animation._events:
+            controller.add_event(event)
+        return controller
+
+
+def create_demo_preset() -> Preset:
+    """Create the demo preset with effect cycling and camera modes."""
+    animation = AnimationController(fps=60)
+
+    effects = ["noise", "fade", "glitch", "firehose"]
+    camera_modes = ["vertical", "horizontal", "omni", "floating", "trace"]
+
+    def make_effect_action(eff):
+        def action(ctrl, t):
+            ctrl.set_param("current_effect", eff)
+            ctrl.set_param("effect_intensity", t)
+
+        return action
+
+    def make_camera_action(cam_mode):
+        def action(ctrl, t):
+            ctrl.set_param("camera_mode", cam_mode)
+
+        return action
+
+    for i, effect in enumerate(effects):
+        effect_duration = 5.0
+
+        animation.add_event(
+            Event(
+                name=f"effect_{effect}",
+                trigger=Trigger(
+                    type=TriggerType.TIME,
+                    value=i * effect_duration,
+                    repeat=True,
+                    repeat_interval=len(effects) * effect_duration,
+                ),
+                duration=effect_duration,
+                action=make_effect_action(effect),
+                ease=ease_in_out,
+            )
+        )
+
+    for i, mode in enumerate(camera_modes):
+        camera_duration = 10.0
+        animation.add_event(
+            Event(
+                name=f"camera_{mode}",
+                trigger=Trigger(
+                    type=TriggerType.TIME,
+                    value=i * camera_duration,
+                    repeat=True,
+                    repeat_interval=len(camera_modes) * camera_duration,
+                ),
+                duration=0.5,
+                action=make_camera_action(mode),
+            )
+        )
+
+    animation.add_event(
+        Event(
+            name="pulse",
+            trigger=Trigger(type=TriggerType.CYCLE, value=2.0, repeat=True),
+            duration=1.0,
+            action=lambda ctrl, t: ctrl.set_param("pulse", t),
+            ease=ease_out_bounce,
+        )
+    )
+
+    return Preset(
+        name="demo",
+        description="Demo mode with effect cycling and camera modes",
+        initial_params=PipelineParams(
+            effect_enabled={
+                "noise": False,
+                "fade": False,
+                "glitch": False,
+                "firehose": False,
+                "hud": True,
+            },
+            effect_intensity={
+                "noise": 0.0,
+                "fade": 0.0,
+                "glitch": 0.0,
+                "firehose": 0.0,
+            },
+            camera_mode="vertical",
+            camera_speed=1.0,
+            display_backend="pygame",
+        ),
+        animation=animation,
+    )
+
+
+def create_pipeline_preset() -> Preset:
+    """Create preset for pipeline visualization."""
+    animation = AnimationController(fps=60)
+
+    animation.add_event(
+        Event(
+            name="camera_trace",
+            trigger=Trigger(type=TriggerType.CYCLE, value=8.0, repeat=True),
+            duration=8.0,
+            action=lambda ctrl, t: ctrl.set_param("camera_mode", "trace"),
+        )
+    )
+
+    animation.add_event(
+        Event(
+            name="highlight_path",
+            trigger=Trigger(type=TriggerType.CYCLE, value=4.0, repeat=True),
+            duration=4.0,
+            action=lambda ctrl, t: ctrl.set_param("path_progress", t),
+        )
+    )
+
+    return Preset(
+        name="pipeline",
+        description="Pipeline visualization with trace camera",
+        initial_params=PipelineParams(
+            camera_mode="trace",
+            camera_speed=1.0,
+            display_backend="pygame",
+        ),
+        animation=animation,
+    )

engine/app.py

@@ -351,7 +351,517 @@ def pick_effects_config():
         termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
 
 
+def run_demo_mode():
+    """Run demo mode - showcases effects and camera modes with real content."""
+    import random
+
+    from engine import config
+    from engine.camera import Camera, CameraMode
+    from engine.display import DisplayRegistry
+    from engine.effects import (
+        EffectContext,
+        PerformanceMonitor,
+        get_effect_chain,
+        get_registry,
+        set_monitor,
+    )
+    from engine.fetch import fetch_all, fetch_poetry, load_cache
+    from engine.scroll import calculate_scroll_step
+
+    print("  \033[1;38;5;46mMAINLINE DEMO MODE\033[0m")
+    print("  \033[38;5;245mInitializing...\033[0m")
+
+    import effects_plugins
+
+    effects_plugins.discover_plugins()
+
+    registry = get_registry()
+    chain = get_effect_chain()
+    chain.set_order(["noise", "fade", "glitch", "firehose", "hud"])
+
+    monitor = PerformanceMonitor()
+    set_monitor(monitor)
+    chain._monitor = monitor
+
+    display = DisplayRegistry.create("pygame")
+    if not display:
+        print("  \033[38;5;196mFailed to create pygame display\033[0m")
+        sys.exit(1)
+
+    w, h = 80, 24
+    display.init(w, h)
+    display.clear()
+
+    print("  \033[38;5;245mFetching content...\033[0m")
+
+    cached = load_cache()
+    if cached:
+        items = cached
+    elif config.MODE == "poetry":
+        items, _, _ = fetch_poetry()
+    else:
+        items, _, _ = fetch_all()
+
+    if not items:
+        print("  \033[38;5;196mNo content available\033[0m")
+        sys.exit(1)
+
+    random.shuffle(items)
+    pool = list(items)
+    seen = set()
+    active = []
+    ticker_next_y = 0
+    noise_cache = {}
+    scroll_motion_accum = 0.0
+    frame_number = 0
+
+    GAP = 3
+    scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, h)
+
+    camera = Camera.vertical(speed=1.0)
+
+    effects_to_demo = ["noise", "fade", "glitch", "firehose"]
+    effect_idx = 0
+    effect_name = effects_to_demo[effect_idx]
+    effect_start_time = time.time()
+    current_intensity = 0.0
+    ramping_up = True
+
+    camera_modes = [
+        (CameraMode.VERTICAL, "vertical"),
+        (CameraMode.HORIZONTAL, "horizontal"),
+        (CameraMode.OMNI, "omni"),
+        (CameraMode.FLOATING, "floating"),
+    ]
+    camera_mode_idx = 0
+    camera_start_time = time.time()
+
+    print("  \033[38;5;82mStarting effect & camera demo...\033[0m")
+    print("  \033[38;5;245mPress Ctrl+C to exit\033[0m\n")
+
+    try:
+        while True:
+            elapsed = time.time() - effect_start_time
+            camera_elapsed = time.time() - camera_start_time
+            duration = config.DEMO_EFFECT_DURATION
+
+            if elapsed >= duration:
+                effect_idx = (effect_idx + 1) % len(effects_to_demo)
+                effect_name = effects_to_demo[effect_idx]
+                effect_start_time = time.time()
+                elapsed = 0
+                current_intensity = 0.0
+                ramping_up = True
+
+            if camera_elapsed >= duration * 2:
+                camera_mode_idx = (camera_mode_idx + 1) % len(camera_modes)
+                mode, mode_name = camera_modes[camera_mode_idx]
+                camera = Camera(mode=mode, speed=1.0)
+                camera_start_time = time.time()
+                camera_elapsed = 0
+
+            progress = elapsed / duration
+            if ramping_up:
+                current_intensity = progress
+                if progress >= 1.0:
+                    ramping_up = False
+            else:
+                current_intensity = 1.0 - progress
+
+            for effect in registry.list_all().values():
+                if effect.name == effect_name:
+                    effect.config.enabled = True
+                    effect.config.intensity = current_intensity
+                elif effect.name not in ("hud",):
+                    effect.config.enabled = False
+
+            hud_effect = registry.get("hud")
+            if hud_effect:
+                mode_name = camera_modes[camera_mode_idx][1]
+                hud_effect.config.params["display_effect"] = (
+                    f"{effect_name} / {mode_name}"
+                )
+                hud_effect.config.params["display_intensity"] = current_intensity
+
+            scroll_motion_accum += config.FRAME_DT
+            while scroll_motion_accum >= scroll_step_interval:
+                scroll_motion_accum -= scroll_step_interval
+                camera.update(config.FRAME_DT)
+
+                while ticker_next_y < camera.y + h + 10 and len(active) < 50:
+                    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
+
+                active = [
+                    (c, hc, by, mi)
+                    for c, hc, by, mi in active
+                    if by + len(c) > camera.y
+                ]
+                for k in list(noise_cache):
+                    if k < camera.y:
+                        del noise_cache[k]
+
+            grad_offset = (time.time() * config.GRAD_SPEED) % 1.0
+
+            from engine.layers import render_ticker_zone
+
+            buf, noise_cache = render_ticker_zone(
+                active,
+                scroll_cam=camera.y,
+                camera_x=camera.x,
+                ticker_h=h,
+                w=w,
+                noise_cache=noise_cache,
+                grad_offset=grad_offset,
+            )
+
+            from engine.layers import render_firehose
+
+            firehose_buf = render_firehose(items, w, 0, h)
+            buf.extend(firehose_buf)
+
+            ctx = EffectContext(
+                terminal_width=w,
+                terminal_height=h,
+                scroll_cam=camera.y,
+                ticker_height=h,
+                camera_x=camera.x,
+                mic_excess=0.0,
+                grad_offset=grad_offset,
+                frame_number=frame_number,
+                has_message=False,
+                items=items,
+            )
+
+            result = chain.process(buf, ctx)
+            display.show(result)
+
+            new_w, new_h = display.get_dimensions()
+            if new_w != w or new_h != h:
+                w, h = new_w, new_h
+                scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, h)
+                active = []
+                noise_cache = {}
+
+            frame_number += 1
+            time.sleep(1 / 60)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        display.cleanup()
+        print("\n  \033[38;5;245mDemo ended\033[0m")
+
+
+def run_pipeline_demo():
+    """Run pipeline visualization demo mode - shows ASCII pipeline animation."""
+    import time
+
+    from engine import config
+    from engine.camera import Camera, CameraMode
+    from engine.display import DisplayRegistry
+    from engine.effects import (
+        EffectContext,
+        PerformanceMonitor,
+        get_effect_chain,
+        get_registry,
+        set_monitor,
+    )
+    from engine.pipeline_viz import generate_large_network_viewport
+
+    print("  \033[1;38;5;46mMAINLINE PIPELINE DEMO\033[0m")
+    print("  \033[38;5;245mInitializing...\033[0m")
+
+    import effects_plugins
+
+    effects_plugins.discover_plugins()
+
+    registry = get_registry()
+    chain = get_effect_chain()
+    chain.set_order(["noise", "fade", "glitch", "firehose", "hud"])
+
+    monitor = PerformanceMonitor()
+    set_monitor(monitor)
+    chain._monitor = monitor
+
+    display = DisplayRegistry.create("pygame")
+    if not display:
+        print("  \033[38;5;196mFailed to create pygame display\033[0m")
+        sys.exit(1)
+
+    w, h = 80, 24
+    display.init(w, h)
+    display.clear()
+
+    camera = Camera.vertical(speed=1.0)
+
+    effects_to_demo = ["noise", "fade", "glitch", "firehose"]
+    effect_idx = 0
+    effect_name = effects_to_demo[effect_idx]
+    effect_start_time = time.time()
+    current_intensity = 0.0
+    ramping_up = True
+
+    camera_modes = [
+        (CameraMode.VERTICAL, "vertical"),
+        (CameraMode.HORIZONTAL, "horizontal"),
+        (CameraMode.OMNI, "omni"),
+        (CameraMode.FLOATING, "floating"),
+    ]
+    camera_mode_idx = 0
+    camera_start_time = time.time()
+
+    frame_number = 0
+
+    print("  \033[38;5;82mStarting pipeline visualization...\033[0m")
+    print("  \033[38;5;245mPress Ctrl+C to exit\033[0m\n")
+
+    try:
+        while True:
+            elapsed = time.time() - effect_start_time
+            camera_elapsed = time.time() - camera_start_time
+            duration = config.DEMO_EFFECT_DURATION
+
+            if elapsed >= duration:
+                effect_idx = (effect_idx + 1) % len(effects_to_demo)
+                effect_name = effects_to_demo[effect_idx]
+                effect_start_time = time.time()
+                elapsed = 0
+                current_intensity = 0.0
+                ramping_up = True
+
+            if camera_elapsed >= duration * 2:
+                camera_mode_idx = (camera_mode_idx + 1) % len(camera_modes)
+                mode, mode_name = camera_modes[camera_mode_idx]
+                camera = Camera(mode=mode, speed=1.0)
+                camera_start_time = time.time()
+                camera_elapsed = 0
+
+            progress = elapsed / duration
+            if ramping_up:
+                current_intensity = progress
+                if progress >= 1.0:
+                    ramping_up = False
+            else:
+                current_intensity = 1.0 - progress
+
+            for effect in registry.list_all().values():
+                if effect.name == effect_name:
+                    effect.config.enabled = True
+                    effect.config.intensity = current_intensity
+                elif effect.name not in ("hud",):
+                    effect.config.enabled = False
+
+            hud_effect = registry.get("hud")
+            if hud_effect:
+                mode_name = camera_modes[camera_mode_idx][1]
+                hud_effect.config.params["display_effect"] = (
+                    f"{effect_name} / {mode_name}"
+                )
+                hud_effect.config.params["display_intensity"] = current_intensity
+
+            camera.update(config.FRAME_DT)
+
+            buf = generate_large_network_viewport(w, h, frame_number)
+
+            ctx = EffectContext(
+                terminal_width=w,
+                terminal_height=h,
+                scroll_cam=camera.y,
+                ticker_height=h,
+                camera_x=camera.x,
+                mic_excess=0.0,
+                grad_offset=0.0,
+                frame_number=frame_number,
+                has_message=False,
+                items=[],
+            )
+
+            result = chain.process(buf, ctx)
+            display.show(result)
+
+            new_w, new_h = display.get_dimensions()
+            if new_w != w or new_h != h:
+                w, h = new_w, new_h
+
+            frame_number += 1
+            time.sleep(1 / 60)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        display.cleanup()
+        print("\n  \033[38;5;245mPipeline demo ended\033[0m")
+
+
+def run_preset_mode(preset_name: str):
+    """Run mode using animation presets."""
+    from engine import config
+    from engine.animation import (
+        create_demo_preset,
+        create_pipeline_preset,
+    )
+    from engine.camera import Camera
+    from engine.display import DisplayRegistry
+    from engine.effects import (
+        EffectContext,
+        PerformanceMonitor,
+        get_effect_chain,
+        get_registry,
+        set_monitor,
+    )
+    from engine.sources_v2 import (
+        PipelineDataSource,
+        get_source_registry,
+        init_default_sources,
+    )
+
+    w, h = 80, 24
+
+    if preset_name == "demo":
+        preset = create_demo_preset()
+        init_default_sources()
+        source = get_source_registry().default()
+    elif preset_name == "pipeline":
+        preset = create_pipeline_preset()
+        source = PipelineDataSource(w, h)
+    else:
+        print(f"  \033[38;5;196mUnknown preset: {preset_name}\033[0m")
+        print("  Available: demo, pipeline")
+        sys.exit(1)
+
+    print(f"  \033[1;38;5;46mMAINLINE PRESET: {preset.name}\033[0m")
+    print(f"  \033[38;5;245m{preset.description}\033[0m")
+    print("  \033[38;5;245mInitializing...\033[0m")
+
+    import effects_plugins
+
+    effects_plugins.discover_plugins()
+
+    registry = get_registry()
+    chain = get_effect_chain()
+    chain.set_order(["noise", "fade", "glitch", "firehose", "hud"])
+
+    monitor = PerformanceMonitor()
+    set_monitor(monitor)
+    chain._monitor = monitor
+
+    display = DisplayRegistry.create(preset.initial_params.display_backend)
+    if not display:
+        print(
+            f"  \033[38;5;196mFailed to create {preset.initial_params.display_backend} display\033[0m"
+        )
+        sys.exit(1)
+
+    display.init(w, h)
+    display.clear()
+
+    camera = Camera.vertical()
+
+    print("  \033[38;5;82mStarting preset animation...\033[0m")
+    print("  \033[38;5;245mPress Ctrl+C to exit\033[0m\n")
+
+    controller = preset.create_controller()
+    frame_number = 0
+
+    try:
+        while True:
+            params = controller.update()
+
+            effect_name = params.get("current_effect", "none")
+            intensity = params.get("effect_intensity", 0.0)
+            camera_mode = params.get("camera_mode", "vertical")
+
+            if camera_mode == "vertical":
+                camera = Camera.vertical(speed=params.get("camera_speed", 1.0))
+            elif camera_mode == "horizontal":
+                camera = Camera.horizontal(speed=params.get("camera_speed", 1.0))
+            elif camera_mode == "omni":
+                camera = Camera.omni(speed=params.get("camera_speed", 1.0))
+            elif camera_mode == "floating":
+                camera = Camera.floating(speed=params.get("camera_speed", 1.0))
+
+            camera.update(config.FRAME_DT)
+
+            for eff in registry.list_all().values():
+                if eff.name == effect_name:
+                    eff.config.enabled = True
+                    eff.config.intensity = intensity
+                elif eff.name not in ("hud",):
+                    eff.config.enabled = False
+
+            hud_effect = registry.get("hud")
+            if hud_effect:
+                hud_effect.config.params["display_effect"] = (
+                    f"{effect_name} / {camera_mode}"
+                )
+                hud_effect.config.params["display_intensity"] = intensity
+
+            source.viewport_width = w
+            source.viewport_height = h
+            items = source.get_items()
+            buffer = items[0].content.split("\n") if items else [""] * h
+
+            ctx = EffectContext(
+                terminal_width=w,
+                terminal_height=h,
+                scroll_cam=camera.y,
+                ticker_height=h,
+                camera_x=camera.x,
+                mic_excess=0.0,
+                grad_offset=0.0,
+                frame_number=frame_number,
+                has_message=False,
+                items=[],
+            )
+
+            result = chain.process(buffer, ctx)
+            display.show(result)
+
+            new_w, new_h = display.get_dimensions()
+            if new_w != w or new_h != h:
+                w, h = new_w, new_h
+
+            frame_number += 1
+            time.sleep(1 / 60)
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        display.cleanup()
+        print("\n  \033[38;5;245mPreset ended\033[0m")
+
+
 def main():
+    from engine import config
+
+    if config.PIPELINE_DIAGRAM:
+        from engine.pipeline import generate_pipeline_diagram
+
+        print(generate_pipeline_diagram())
+        return
+
+    if config.PIPELINE_MODE:
+        run_pipeline_mode(config.PIPELINE_PRESET)
+        return
+
+    if config.PIPELINE_DEMO:
+        run_pipeline_demo()
+        return
+
+    if config.PRESET:
+        run_preset_mode(config.PRESET)
+        return
+
+    if config.DEMO:
+        run_demo_mode()
+        return
+
     atexit.register(lambda: print(CURSOR_ON, end="", flush=True))
 
     def handle_sigint(*_):
@@ -450,3 +960,128 @@ def main():
     print(f"  {G_DIM}> {config.HEADLINE_LIMIT} SIGNALS PROCESSED{RST}")
     print(f"  {W_GHOST}> end of stream{RST}")
     print()
+
+
+def run_pipeline_mode(preset_name: str = "demo"):
+    """Run using the new unified pipeline architecture."""
+    import effects_plugins
+    from engine.display import DisplayRegistry
+    from engine.effects import get_registry
+    from engine.fetch import fetch_all, fetch_poetry, load_cache
+    from engine.pipeline import (
+        Pipeline,
+        PipelineConfig,
+        get_preset,
+    )
+    from engine.pipeline.adapters import (
+        RenderStage,
+        create_items_stage,
+        create_stage_from_display,
+        create_stage_from_effect,
+    )
+
+    print("  \033[1;38;5;46mPIPELINE MODE\033[0m")
+    print("  \033[38;5;245mUsing unified pipeline architecture\033[0m")
+
+    effects_plugins.discover_plugins()
+
+    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")
+    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")
+
+    display = DisplayRegistry.create(preset.display)
+    if not display:
+        print(f"  \033[38;5;196mFailed to create display: {preset.display}\033[0m")
+        sys.exit(1)
+
+    display.init(80, 24)
+
+    effect_registry = get_registry()
+
+    pipeline.add_stage("source", create_items_stage(items, preset.source))
+    pipeline.add_stage(
+        "render",
+        RenderStage(
+            items,
+            width=80,
+            height=24,
+            camera_speed=params.camera_speed,
+            camera_mode=preset.camera,
+            firehose_enabled=params.firehose_enabled,
+        ),
+    )
+
+    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, preset.display))
+
+    pipeline.build()
+
+    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)
+
+    try:
+        frame = 0
+        while True:
+            params.frame_number = frame
+            ctx.params = params
+
+            result = pipeline.execute(items)
+            if result.success:
+                display.show(result.data)
+
+            time.sleep(1 / 60)
+            frame += 1
+
+    except KeyboardInterrupt:
+        pass
+    finally:
+        pipeline.cleanup()
+        display.cleanup()
+        print("\n  \033[38;5;245mPipeline stopped\033[0m")

engine/benchmark.py

@@ -6,6 +6,9 @@ Usage:
     python -m engine.benchmark
     python -m engine.benchmark --output report.md
     python -m engine.benchmark --displays terminal,websocket --effects glitch,fade
+    python -m engine.benchmark --format json --output benchmark.json
+
+Headless mode (default): suppress all terminal output during benchmarks.
 """
 
 import argparse
@@ -13,6 +16,9 @@ import json
 import sys
 import time
 from dataclasses import dataclass, field
+from datetime import datetime
+from io import StringIO
+from pathlib import Path
 from typing import Any
 
 import numpy as np
@@ -56,22 +62,52 @@ def get_sample_buffer(width: int = 80, height: int = 24) -> list[str]:
 
 
 def benchmark_display(
-    display_class, buffer: list[str], iterations: int = 100
-) -> BenchmarkResult:
-    """Benchmark a single display."""
-    display = display_class()
-    display.init(80, 24)
+    display_class,
+    buffer: list[str],
+    iterations: int = 100,
+    display=None,
+    reuse: bool = False,
+) -> BenchmarkResult | None:
+    """Benchmark a single display.
 
-    times = []
-    chars = sum(len(line) for line in buffer)
+    Args:
+        display_class: Display class to instantiate
+        buffer: Buffer to display
+        iterations: Number of iterations
+        display: Optional existing display instance to reuse
+        reuse: If True and display provided, use reuse mode
+    """
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
 
-    for _ in range(iterations):
-        t0 = time.perf_counter()
-        display.show(buffer)
-        elapsed = (time.perf_counter() - t0) * 1000
-        times.append(elapsed)
+    try:
+        sys.stdout = StringIO()
+        sys.stderr = StringIO()
 
-    display.cleanup()
+        if display is None:
+            display = display_class()
+            display.init(80, 24, reuse=False)
+            should_cleanup = True
+        else:
+            should_cleanup = False
+
+        times = []
+        chars = sum(len(line) for line in buffer)
+
+        for _ in range(iterations):
+            t0 = time.perf_counter()
+            display.show(buffer)
+            elapsed = (time.perf_counter() - t0) * 1000
+            times.append(elapsed)
+
+        if should_cleanup and hasattr(display, "cleanup"):
+            display.cleanup(quit_pygame=False)
+
+    except Exception:
+        return None
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
 
     times_arr = np.array(times)
 
@@ -81,36 +117,71 @@ def benchmark_display(
         effect=None,
         iterations=iterations,
         total_time_ms=sum(times),
-        avg_time_ms=np.mean(times_arr),
-        std_dev_ms=np.std(times_arr),
-        min_ms=np.min(times_arr),
-        max_ms=np.max(times_arr),
-        fps=1000.0 / np.mean(times_arr) if np.mean(times_arr) > 0 else 0,
+        avg_time_ms=float(np.mean(times_arr)),
+        std_dev_ms=float(np.std(times_arr)),
+        min_ms=float(np.min(times_arr)),
+        max_ms=float(np.max(times_arr)),
+        fps=float(1000.0 / np.mean(times_arr)) if np.mean(times_arr) > 0 else 0.0,
         chars_processed=chars * iterations,
-        chars_per_sec=(chars * iterations) / (sum(times) / 1000)
+        chars_per_sec=float((chars * iterations) / (sum(times) / 1000))
         if sum(times) > 0
-        else 0,
+        else 0.0,
     )
 
 
 def benchmark_effect_with_display(
-    effect_class, display, buffer: list[str], iterations: int = 100
-) -> BenchmarkResult:
-    """Benchmark an effect with a display."""
-    effect = effect_class()
-    effect.configure(enabled=True, intensity=1.0)
+    effect_class, display, buffer: list[str], iterations: int = 100, reuse: bool = False
+) -> BenchmarkResult | None:
+    """Benchmark an effect with a display.
 
-    times = []
-    chars = sum(len(line) for line in buffer)
+    Args:
+        effect_class: Effect class to instantiate
+        display: Display instance to use
+        buffer: Buffer to process and display
+        iterations: Number of iterations
+        reuse: If True, use reuse mode for display
+    """
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
 
-    for _ in range(iterations):
-        processed = effect.process(buffer)
-        t0 = time.perf_counter()
-        display.show(processed)
-        elapsed = (time.perf_counter() - t0) * 1000
-        times.append(elapsed)
+    try:
+        from engine.effects.types import EffectConfig, EffectContext
 
-    display.cleanup()
+        sys.stdout = StringIO()
+        sys.stderr = StringIO()
+
+        effect = effect_class()
+        effect.configure(EffectConfig(enabled=True, intensity=1.0))
+
+        ctx = EffectContext(
+            terminal_width=80,
+            terminal_height=24,
+            scroll_cam=0,
+            ticker_height=0,
+            mic_excess=0.0,
+            grad_offset=0.0,
+            frame_number=0,
+            has_message=False,
+        )
+
+        times = []
+        chars = sum(len(line) for line in buffer)
+
+        for _ in range(iterations):
+            processed = effect.process(buffer, ctx)
+            t0 = time.perf_counter()
+            display.show(processed)
+            elapsed = (time.perf_counter() - t0) * 1000
+            times.append(elapsed)
+
+        if not reuse and hasattr(display, "cleanup"):
+            display.cleanup(quit_pygame=False)
+
+    except Exception:
+        return None
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
 
     times_arr = np.array(times)
 
@@ -120,15 +191,15 @@ def benchmark_effect_with_display(
         effect=effect_class.__name__,
         iterations=iterations,
         total_time_ms=sum(times),
-        avg_time_ms=np.mean(times_arr),
-        std_dev_ms=np.std(times_arr),
-        min_ms=np.min(times_arr),
-        max_ms=np.max(times_arr),
-        fps=1000.0 / np.mean(times_arr) if np.mean(times_arr) > 0 else 0,
+        avg_time_ms=float(np.mean(times_arr)),
+        std_dev_ms=float(np.std(times_arr)),
+        min_ms=float(np.min(times_arr)),
+        max_ms=float(np.max(times_arr)),
+        fps=float(1000.0 / np.mean(times_arr)) if np.mean(times_arr) > 0 else 0.0,
         chars_processed=chars * iterations,
-        chars_per_sec=(chars * iterations) / (sum(times) / 1000)
+        chars_per_sec=float((chars * iterations) / (sum(times) / 1000))
         if sum(times) > 0
-        else 0,
+        else 0.0,
     )
 
 
@@ -139,7 +210,6 @@ def get_available_displays():
         NullDisplay,
         TerminalDisplay,
     )
-    from engine.display.backends.sixel import SixelDisplay
 
     DisplayRegistry.initialize()
 
@@ -156,27 +226,43 @@ def get_available_displays():
         pass
 
     try:
+        from engine.display.backends.sixel import SixelDisplay
+
         displays.append(("sixel", SixelDisplay))
     except Exception:
         pass
 
+    try:
+        from engine.display.backends.pygame import PygameDisplay
+
+        displays.append(("pygame", PygameDisplay))
+    except Exception:
+        pass
+
     return displays
 
 
 def get_available_effects():
     """Get available effect classes."""
     try:
-        from engine.effects.registry import get_effect_registry
+        from engine.effects import get_registry
+
+        try:
+            from effects_plugins import discover_plugins
+
+            discover_plugins()
+        except Exception:
+            pass
     except Exception:
         return []
 
     effects = []
-    registry = get_effect_registry()
+    registry = get_registry()
 
-    for name in registry.list_effects():
-        effect = registry.get(name)
+    for name, effect in registry.list_all().items():
         if effect:
-            effects.append((name, effect))
+            effect_cls = type(effect)
+            effects.append((name, effect_cls))
 
     return effects
 
@@ -185,7 +271,7 @@ def run_benchmarks(
     displays: list[tuple[str, Any]] | None = None,
     effects: list[tuple[str, Any]] | None = None,
     iterations: int = 100,
-    output_format: str = "text",
+    verbose: bool = False,
 ) -> BenchmarkReport:
     """Run all benchmarks and return report."""
     from datetime import datetime
@@ -199,35 +285,76 @@ def run_benchmarks(
     buffer = get_sample_buffer(80, 24)
     results = []
 
-    print(f"Running benchmarks ({iterations} iterations each)...")
-    print()
+    if verbose:
+        print(f"Running benchmarks ({iterations} iterations each)...")
 
+    pygame_display = None
     for name, display_class in displays:
-        print(f"Benchmarking display: {name}")
-        try:
-            result = benchmark_display(display_class, buffer, iterations)
-            results.append(result)
-            print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
-        except Exception as e:
-            print(f"  Error: {e}")
+        if verbose:
+            print(f"Benchmarking display: {name}")
 
-    print()
+        result = benchmark_display(display_class, buffer, iterations)
+        if result:
+            results.append(result)
+            if verbose:
+                print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
+
+        if name == "pygame":
+            pygame_display = result
+
+    if verbose:
+        print()
+
+    pygame_instance = None
+    if pygame_display:
+        try:
+            from engine.display.backends.pygame import PygameDisplay
+
+            PygameDisplay.reset_state()
+            pygame_instance = PygameDisplay()
+            pygame_instance.init(80, 24, reuse=False)
+        except Exception:
+            pygame_instance = None
 
     for effect_name, effect_class in effects:
         for display_name, display_class in displays:
             if display_name == "websocket":
                 continue
-            print(f"Benchmarking effect: {effect_name} with {display_name}")
-            try:
-                display = display_class()
-                display.init(80, 24)
-                result = benchmark_effect_with_display(
-                    effect_class, display, buffer, iterations
-                )
+
+            if display_name == "pygame":
+                if verbose:
+                    print(f"Benchmarking effect: {effect_name} with {display_name}")
+
+                if pygame_instance:
+                    result = benchmark_effect_with_display(
+                        effect_class, pygame_instance, buffer, iterations, reuse=True
+                    )
+                    if result:
+                        results.append(result)
+                        if verbose:
+                            print(
+                                f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg"
+                            )
+                continue
+
+            if verbose:
+                print(f"Benchmarking effect: {effect_name} with {display_name}")
+
+            display = display_class()
+            display.init(80, 24)
+            result = benchmark_effect_with_display(
+                effect_class, display, buffer, iterations
+            )
+            if result:
                 results.append(result)
-                print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
-            except Exception as e:
-                print(f"  Error: {e}")
+                if verbose:
+                    print(f"  {result.fps:.1f} FPS, {result.avg_time_ms:.2f}ms avg")
+
+    if pygame_instance:
+        try:
+            pygame_instance.cleanup(quit_pygame=True)
+        except Exception:
+            pass
 
     summary = generate_summary(results)
 
@@ -267,24 +394,132 @@ def generate_summary(results: list[BenchmarkResult]) -> dict[str, Any]:
     for display, res in by_display.items():
         fps_values = [r.fps for r in res]
         summary["by_display"][display] = {
-            "avg_fps": np.mean(fps_values),
-            "min_fps": np.min(fps_values),
-            "max_fps": np.max(fps_values),
+            "avg_fps": float(np.mean(fps_values)),
+            "min_fps": float(np.min(fps_values)),
+            "max_fps": float(np.max(fps_values)),
             "tests": len(res),
         }
 
     for effect, res in by_effect.items():
         fps_values = [r.fps for r in res]
         summary["by_effect"][effect] = {
-            "avg_fps": np.mean(fps_values),
-            "min_fps": np.min(fps_values),
-            "max_fps": np.max(fps_values),
+            "avg_fps": float(np.mean(fps_values)),
+            "min_fps": float(np.min(fps_values)),
+            "max_fps": float(np.max(fps_values)),
             "tests": len(res),
         }
 
     return summary
 
 
+DEFAULT_CACHE_PATH = Path.home() / ".mainline_benchmark_cache.json"
+
+
+def load_baseline(cache_path: Path | None = None) -> dict[str, Any] | None:
+    """Load baseline benchmark results from cache."""
+    path = cache_path or DEFAULT_CACHE_PATH
+    if not path.exists():
+        return None
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def save_baseline(
+    results: list[BenchmarkResult],
+    cache_path: Path | None = None,
+) -> None:
+    """Save benchmark results as baseline to cache."""
+    path = cache_path or DEFAULT_CACHE_PATH
+    baseline = {
+        "timestamp": datetime.now().isoformat(),
+        "results": {
+            r.name: {
+                "fps": r.fps,
+                "avg_time_ms": r.avg_time_ms,
+                "chars_per_sec": r.chars_per_sec,
+            }
+            for r in results
+        },
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        json.dump(baseline, f, indent=2)
+
+
+def compare_with_baseline(
+    results: list[BenchmarkResult],
+    baseline: dict[str, Any],
+    threshold: float = 0.2,
+    verbose: bool = True,
+) -> tuple[bool, list[str]]:
+    """Compare current results with baseline. Returns (pass, messages)."""
+    baseline_results = baseline.get("results", {})
+    failures = []
+    warnings = []
+
+    for r in results:
+        if r.name not in baseline_results:
+            warnings.append(f"New test: {r.name} (no baseline)")
+            continue
+
+        b = baseline_results[r.name]
+        if b["fps"] == 0:
+            continue
+
+        degradation = (b["fps"] - r.fps) / b["fps"]
+        if degradation > threshold:
+            failures.append(
+                f"{r.name}: FPS degraded {degradation * 100:.1f}% "
+                f"(baseline: {b['fps']:.1f}, current: {r.fps:.1f})"
+            )
+        elif verbose:
+            print(f"  {r.name}: {r.fps:.1f} FPS (baseline: {b['fps']:.1f})")
+
+    passed = len(failures) == 0
+    messages = []
+    if failures:
+        messages.extend(failures)
+    if warnings:
+        messages.extend(warnings)
+
+    return passed, messages
+
+
+def run_hook_mode(
+    displays: list[tuple[str, Any]] | None = None,
+    effects: list[tuple[str, Any]] | None = None,
+    iterations: int = 20,
+    threshold: float = 0.2,
+    cache_path: Path | None = None,
+    verbose: bool = False,
+) -> int:
+    """Run in hook mode: compare against baseline, exit 0 on pass, 1 on fail."""
+    baseline = load_baseline(cache_path)
+
+    if baseline is None:
+        print("No baseline found. Run with --baseline to create one.")
+        return 1
+
+    report = run_benchmarks(displays, effects, iterations, verbose)
+
+    passed, messages = compare_with_baseline(
+        report.results, baseline, threshold, verbose
+    )
+
+    print("\n=== Benchmark Hook Results ===")
+    if passed:
+        print("PASSED - No significant performance degradation")
+        return 0
+    else:
+        print("FAILED - Performance degradation detected:")
+        for msg in messages:
+            print(f"  - {msg}")
+        return 1
+
+
 def format_report_text(report: BenchmarkReport) -> str:
     """Format report as human-readable text."""
     lines = [
@@ -391,9 +626,67 @@ def main():
         default="text",
         help="Output format (default: text)",
     )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show progress during benchmarking",
+    )
+    parser.add_argument(
+        "--hook",
+        action="store_true",
+        help="Run in hook mode: compare against baseline, exit 0 pass, 1 fail",
+    )
+    parser.add_argument(
+        "--baseline",
+        action="store_true",
+        help="Save current results as baseline for future hook comparisons",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.2,
+        help="Performance degradation threshold for hook mode (default: 0.2 = 20%%)",
+    )
+    parser.add_argument(
+        "--cache",
+        type=str,
+        default=None,
+        help="Path to baseline cache file (default: ~/.mainline_benchmark_cache.json)",
+    )
 
     args = parser.parse_args()
 
+    cache_path = Path(args.cache) if args.cache else DEFAULT_CACHE_PATH
+
+    if args.hook:
+        displays = None
+        if args.displays:
+            display_map = dict(get_available_displays())
+            displays = [
+                (name, display_map[name])
+                for name in args.displays.split(",")
+                if name in display_map
+            ]
+
+        effects = None
+        if args.effects:
+            effect_map = dict(get_available_effects())
+            effects = [
+                (name, effect_map[name])
+                for name in args.effects.split(",")
+                if name in effect_map
+            ]
+
+        return run_hook_mode(
+            displays,
+            effects,
+            iterations=args.iterations,
+            threshold=args.threshold,
+            cache_path=cache_path,
+            verbose=args.verbose,
+        )
+
     displays = None
     if args.displays:
         display_map = dict(get_available_displays())
@@ -412,7 +705,12 @@ def main():
             if name in effect_map
         ]
 
-    report = run_benchmarks(displays, effects, args.iterations, args.format)
+    report = run_benchmarks(displays, effects, args.iterations, args.verbose)
+
+    if args.baseline:
+        save_baseline(report.results, cache_path)
+        print(f"Baseline saved to {cache_path}")
+        return 0
 
     if args.format == "json":
         output = format_report_json(report)
@@ -422,10 +720,11 @@ def main():
     if args.output:
         with open(args.output, "w") as f:
             f.write(output)
-        print(f"Report written to {args.output}")
     else:
         print(output)
 
+    return 0
+
 
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

engine/camera.py

@@ -0,0 +1,109 @@
+"""
+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
+"""
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class CameraMode(Enum):
+    VERTICAL = auto()
+    HORIZONTAL = auto()
+    OMNI = auto()
+    FLOATING = auto()
+
+
+@dataclass
+class Camera:
+    """Camera for viewport scrolling.
+
+    Attributes:
+        x: Current horizontal offset (positive = scroll left)
+        y: Current vertical offset (positive = scroll up)
+        mode: Current camera mode
+        speed: Base scroll speed
+        custom_update: Optional custom update function
+    """
+
+    x: int = 0
+    y: int = 0
+    mode: CameraMode = CameraMode.VERTICAL
+    speed: float = 1.0
+    custom_update: Callable[["Camera", float], None] | None = None
+    _time: float = field(default=0.0, repr=False)
+
+    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.VERTICAL:
+            self._update_vertical(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)
+
+    def _update_vertical(self, dt: float) -> None:
+        self.y += int(self.speed * dt * 60)
+
+    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 reset(self) -> None:
+        """Reset camera position."""
+        self.x = 0
+        self.y = 0
+        self._time = 0.0
+
+    @classmethod
+    def vertical(cls, speed: float = 1.0) -> "Camera":
+        """Create a vertical scrolling camera."""
+        return cls(mode=CameraMode.VERTICAL, speed=speed)
+
+    @classmethod
+    def horizontal(cls, speed: float = 1.0) -> "Camera":
+        """Create a horizontal scrolling camera."""
+        return cls(mode=CameraMode.HORIZONTAL, speed=speed)
+
+    @classmethod
+    def omni(cls, speed: float = 1.0) -> "Camera":
+        """Create an omnidirectional scrolling camera."""
+        return cls(mode=CameraMode.OMNI, speed=speed)
+
+    @classmethod
+    def floating(cls, speed: float = 1.0) -> "Camera":
+        """Create a floating/bobbing camera."""
+        return cls(mode=CameraMode.FLOATING, speed=speed)
+
+    @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/config.py

@@ -129,7 +129,7 @@ class Config:
 
     script_fonts: dict[str, str] = field(default_factory=_get_platform_font_paths)
 
-    display: str = "terminal"
+    display: str = "pygame"
     websocket: bool = False
     websocket_port: int = 8765
 
@@ -237,10 +237,25 @@ GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
 KATA = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"
 
 # ─── WEBSOCKET ─────────────────────────────────────────────
-DISPLAY = _arg_value("--display", sys.argv) or "terminal"
+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

@@ -5,8 +5,10 @@ Stream controller - manages input sources and orchestrates the render stream.
 from engine.config import Config, get_config
 from engine.display import (
     DisplayRegistry,
+    KittyDisplay,
     MultiDisplay,
     NullDisplay,
+    PygameDisplay,
     SixelDisplay,
     TerminalDisplay,
     WebSocketDisplay,
@@ -38,6 +40,12 @@ def _get_display(config: Config):
     if display_mode == "sixel":
         displays.append(SixelDisplay())
 
+    if display_mode == "kitty":
+        displays.append(KittyDisplay())
+
+    if display_mode == "pygame":
+        displays.append(PygameDisplay())
+
     if not displays:
         return NullDisplay()
 

engine/display/__init__.py

@@ -7,21 +7,40 @@ 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."""
+    """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
+
+    The reuse flag allows attaching to an existing display instance
+    rather than creating a new window/connection.
+    """
 
     width: int
     height: int
 
-    def init(self, width: int, height: int) -> None:
-        """Initialize display with dimensions."""
+    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]) -> None:
@@ -61,6 +80,7 @@ class DisplayRegistry:
     @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)
@@ -76,6 +96,8 @@ class DisplayRegistry:
         cls.register("null", NullDisplay)
         cls.register("websocket", WebSocketDisplay)
         cls.register("sixel", SixelDisplay)
+        cls.register("kitty", KittyDisplay)
+        cls.register("pygame", PygameDisplay)
 
         cls._initialized = True
 

engine/display/backends/kitty.py

@@ -0,0 +1,152 @@
+"""
+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]) -> None:
+        import sys
+
+        t0 = time.perf_counter()
+
+        img_width = self.width * self.cell_width
+        img_height = self.height * self.cell_height
+
+        try:
+            from PIL import Image, ImageDraw, ImageFont
+        except ImportError:
+            return
+
+        img = Image.new("RGBA", (img_width, img_height), (0, 0, 0, 255))
+        draw = ImageDraw.Draw(img)
+
+        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()

engine/display/backends/multi.py

@@ -4,7 +4,10 @@ Multi display backend - forwards to multiple displays.
 
 
 class MultiDisplay:
-    """Display that forwards to multiple displays."""
+    """Display that forwards to multiple displays.
+
+    Supports reuse - passes reuse flag to all child displays.
+    """
 
     width: int = 80
     height: int = 24
@@ -14,11 +17,18 @@ class MultiDisplay:
         self.width = 80
         self.height = 24
 
-    def init(self, width: int, height: int) -> None:
+    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)
+            d.init(width, height, reuse=reuse)
 
     def show(self, buffer: list[str]) -> None:
         for d in self.displays:

engine/display/backends/null.py

@@ -6,12 +6,23 @@ import time
 
 
 class NullDisplay:
-    """Headless/null display - discards all output."""
+    """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) -> 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 NullDisplay (no resources to reuse)
+        """
         self.width = width
         self.height = height
 

engine/display/backends/pygame.py

@@ -0,0 +1,212 @@
+"""
+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
+    _pygame_initialized: bool = False
+
+    def __init__(
+        self,
+        cell_width: int = 10,
+        cell_height: int = 18,
+        window_width: int = 800,
+        window_height: int = 600,
+    ):
+        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._initialized = False
+        self._pygame = None
+        self._screen = None
+        self._font = None
+        self._resized = False
+
+    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
+
+        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]) -> None:
+        import sys
+
+        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:
+                sys.exit(0)
+            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
+
+        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
+
+        from engine.display import get_monitor
+
+        monitor = get_monitor()
+        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
+        """
+        if self._resized:
+            self._resized = False
+        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

engine/display/backends/sixel.py

@@ -4,105 +4,7 @@ Sixel graphics display backend - renders to sixel graphics in terminal.
 
 import time
 
-
-def _parse_ansi(
-    text: str,
-) -> list[tuple[str, tuple[int, int, int], tuple[int, int, int], bool]]:
-    """Parse ANSI text into tokens with fg/bg colors.
-
-    Returns list of (text, fg_rgb, bg_rgb, bold).
-    """
-    tokens = []
-    current_text = ""
-    fg = (204, 204, 204)
-    bg = (0, 0, 0)
-    bold = False
-    i = 0
-
-    ANSI_COLORS = {
-        0: (0, 0, 0),
-        1: (205, 49, 49),
-        2: (13, 188, 121),
-        3: (229, 229, 16),
-        4: (36, 114, 200),
-        5: (188, 63, 188),
-        6: (17, 168, 205),
-        7: (229, 229, 229),
-        8: (102, 102, 102),
-        9: (241, 76, 76),
-        10: (35, 209, 139),
-        11: (245, 245, 67),
-        12: (59, 142, 234),
-        13: (214, 112, 214),
-        14: (41, 184, 219),
-        15: (255, 255, 255),
-    }
-
-    while i < len(text):
-        char = text[i]
-
-        if char == "\x1b" and i + 1 < len(text) and text[i + 1] == "[":
-            if current_text:
-                tokens.append((current_text, fg, bg, bold))
-                current_text = ""
-
-            i += 2
-            code = ""
-            while i < len(text):
-                c = text[i]
-                if c.isalpha():
-                    break
-                code += c
-                i += 1
-
-            if code:
-                codes = code.split(";")
-                for c in codes:
-                    try:
-                        n = int(c) if c else 0
-                    except ValueError:
-                        continue
-
-                    if n == 0:
-                        fg = (204, 204, 204)
-                        bg = (0, 0, 0)
-                        bold = False
-                    elif n == 1:
-                        bold = True
-                    elif n == 22:
-                        bold = False
-                    elif n == 39:
-                        fg = (204, 204, 204)
-                    elif n == 49:
-                        bg = (0, 0, 0)
-                    elif 30 <= n <= 37:
-                        fg = ANSI_COLORS.get(n - 30 + (8 if bold else 0), fg)
-                    elif 40 <= n <= 47:
-                        bg = ANSI_COLORS.get(n - 40, bg)
-                    elif 90 <= n <= 97:
-                        fg = ANSI_COLORS.get(n - 90 + 8, fg)
-                    elif 100 <= n <= 107:
-                        bg = ANSI_COLORS.get(n - 100 + 8, bg)
-                    elif 1 <= n <= 256:
-                        if n < 16:
-                            fg = ANSI_COLORS.get(n, fg)
-                        elif n < 232:
-                            c = n - 16
-                            r = (c // 36) * 51
-                            g = ((c % 36) // 6) * 51
-                            b = (c % 6) * 51
-                            fg = (r, g, b)
-                        else:
-                            gray = (n - 232) * 10 + 8
-                            fg = (gray, gray, gray)
-        else:
-            current_text += char
-            i += 1
-
-    if current_text:
-        tokens.append((current_text, fg, bg, bold))
-
-    return tokens if tokens else [("", fg, bg, bold)]
+from engine.display.renderer import get_default_font_path, parse_ansi
 
 
 def _encode_sixel(image) -> str:
@@ -188,8 +90,34 @@ class SixelDisplay:
         self.cell_width = cell_width
         self.cell_height = cell_height
         self._initialized = False
+        self._font_path = None
 
-    def init(self, width: int, height: int) -> 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
@@ -210,12 +138,15 @@ class SixelDisplay:
         img = Image.new("RGBA", (img_width, img_height), (0, 0, 0, 255))
         draw = ImageDraw.Draw(img)
 
-        try:
-            font = ImageFont.truetype(
-                "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
-                self.cell_height - 2,
-            )
-        except Exception:
+        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:
@@ -225,7 +156,7 @@ class SixelDisplay:
             if row_idx >= self.height:
                 break
 
-            tokens = _parse_ansi(line)
+            tokens = parse_ansi(line)
             x_pos = 0
             y_pos = row_idx * self.cell_height
 

engine/display/backends/terminal.py

@@ -6,21 +6,32 @@ import time
 
 
 class TerminalDisplay:
-    """ANSI terminal display backend."""
+    """ANSI terminal display backend.
+
+    Renders buffer to stdout using ANSI escape codes.
+    Supports reuse - when reuse=True, skips re-initializing terminal state.
+    """
 
     width: int = 80
     height: int = 24
+    _initialized: bool = False
 
-    def __init__(self):
-        self.width = 80
-        self.height = 24
+    def init(self, width: int, height: int, reuse: bool = False) -> None:
+        """Initialize display with dimensions.
 
-    def init(self, width: int, height: int) -> None:
+        Args:
+            width: Terminal width in characters
+            height: Terminal height in rows
+            reuse: If True, skip terminal re-initialization
+        """
         from engine.terminal import CURSOR_OFF
 
         self.width = width
         self.height = height
-        print(CURSOR_OFF, end="", flush=True)
+
+        if not reuse or not self._initialized:
+            print(CURSOR_OFF, end="", flush=True)
+            self._initialized = True
 
     def show(self, buffer: list[str]) -> None:
         import sys

engine/display/backends/websocket.py

@@ -86,12 +86,20 @@ class WebSocketDisplay:
         """Check if WebSocket support is available."""
         return self._available
 
-    def init(self, width: int, height: int) -> None:
-        """Initialize display with dimensions and start server."""
+    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
-        self.start_server()
-        self.start_http_server()
+
+        if not reuse or not self._server_running:
+            self.start_server()
+            self.start_http_server()
 
     def show(self, buffer: list[str]) -> None:
         """Broadcast buffer to all connected clients."""

engine/display/renderer.py

@@ -0,0 +1,280 @@
+"""
+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,11 +6,17 @@ 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
+from engine.effects.types import (
+    EffectConfig,
+    EffectContext,
+    PipelineConfig,
+    create_effect_context,
+)
 
 
 def get_effect_chain():
@@ -25,6 +31,7 @@ __all__ = [
     "EffectConfig",
     "EffectContext",
     "PipelineConfig",
+    "create_effect_context",
     "get_registry",
     "set_registry",
     "get_effect_chain",
@@ -39,4 +46,5 @@ __all__ = [
     "noise",
     "next_headline",
     "vis_trunc",
+    "vis_offset",
 ]

engine/effects/legacy.py

@@ -1,6 +1,14 @@
 """
 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
@@ -74,6 +82,37 @@ 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,3 +1,24 @@
+"""
+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
 
@@ -8,10 +29,11 @@ class EffectContext:
     terminal_height: int
     scroll_cam: int
     ticker_height: int
-    mic_excess: float
-    grad_offset: float
-    frame_number: int
-    has_message: bool
+    camera_x: int = 0
+    mic_excess: float = 0.0
+    grad_offset: float = 0.0
+    frame_number: int = 0
+    has_message: bool = False
     items: list = field(default_factory=list)
 
 
@@ -22,15 +44,76 @@ class EffectConfig:
     params: dict[str, Any] = field(default_factory=dict)
 
 
-class EffectPlugin:
+class EffectPlugin(ABC):
+    """Abstract base class for effect plugins.
+
+    Subclasses must define:
+    - name: str - unique identifier for the effect
+    - config: EffectConfig - current configuration
+
+    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.
+    """
+
     name: str
     config: EffectConfig
 
+    @abstractmethod
     def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        raise NotImplementedError
+        """Process the buffer with this effect applied.
 
+        Args:
+            buf: List of lines to process
+            ctx: Effect context with terminal state
+
+        Returns:
+            Processed buffer (may be same object or new list)
+        """
+        ...
+
+    @abstractmethod
     def configure(self, config: EffectConfig) -> None:
-        raise NotImplementedError
+        """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 [],
+    )
 
 
 @dataclass

engine/layers.py

@@ -16,6 +16,7 @@ from engine.effects import (
     firehose_line,
     glitch_bar,
     noise,
+    vis_offset,
     vis_trunc,
 )
 from engine.render import big_wrap, lr_gradient, lr_gradient_opposite
@@ -94,16 +95,18 @@ def render_message_overlay(
 def render_ticker_zone(
     active: list,
     scroll_cam: int,
-    ticker_h: int,
-    w: int,
-    noise_cache: dict,
-    grad_offset: float,
+    camera_x: int = 0,
+    ticker_h: int = 0,
+    w: int = 80,
+    noise_cache: dict | None = None,
+    grad_offset: float = 0.0,
 ) -> 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)
+        camera_x: horizontal camera offset
         ticker_h: height of ticker zone
         w: terminal width
         noise_cache: dict of cy -> noise string
@@ -112,6 +115,8 @@ def render_ticker_zone(
     Returns:
         (list of ANSI strings, updated noise_cache)
     """
+    if noise_cache is None:
+        noise_cache = {}
     buf = []
     top_zone = max(1, int(ticker_h * 0.25))
     bot_zone = max(1, int(ticker_h * 0.10))
@@ -137,7 +142,7 @@ def render_ticker_zone(
                     colored = lr_gradient([raw], grad_offset)[0]
                 else:
                     colored = raw
-                ln = vis_trunc(colored, w)
+                ln = vis_trunc(vis_offset(colored, camera_x), w)
                 if row_fade < 1.0:
                     ln = fade_line(ln, row_fade)
 
@@ -228,11 +233,12 @@ def process_effects(
     h: int,
     scroll_cam: int,
     ticker_h: int,
-    mic_excess: float,
-    grad_offset: float,
-    frame_number: int,
-    has_message: bool,
-    items: list,
+    camera_x: int = 0,
+    mic_excess: float = 0.0,
+    grad_offset: float = 0.0,
+    frame_number: int = 0,
+    has_message: bool = False,
+    items: list | None = None,
 ) -> list[str]:
     """Process buffer through effect chain."""
     if _effect_chain is None:
@@ -242,12 +248,13 @@ def process_effects(
         terminal_width=w,
         terminal_height=h,
         scroll_cam=scroll_cam,
+        camera_x=camera_x,
         ticker_height=ticker_h,
         mic_excess=mic_excess,
         grad_offset=grad_offset,
         frame_number=frame_number,
         has_message=has_message,
-        items=items,
+        items=items or [],
     )
     return _effect_chain.process(buf, ctx)
 

engine/pipeline.py

@@ -0,0 +1,611 @@
+"""
+Pipeline introspection - generates self-documenting diagrams of the render pipeline.
+
+Pipeline Architecture:
+- Sources: Data providers (RSS, Poetry, Ntfy, Mic) - static or dynamic
+- Fetch: Retrieve data from sources
+- Prepare: Transform raw data (make_block, strip_tags, translate)
+- Scroll: Camera-based viewport rendering (ticker zone, message overlay)
+- Effects: Post-processing chain (noise, fade, glitch, firehose, hud)
+- Render: Final line rendering and layout
+- Display: Output backends (terminal, pygame, websocket, sixel, kitty)
+
+Key abstractions:
+- DataSource: Sources can be static (cached) or dynamic (idempotent fetch)
+- Camera: Viewport controller (vertical, horizontal, omni, floating, trace)
+- EffectChain: Ordered effect processing pipeline
+- Display: Pluggable output backends
+- SourceRegistry: Source discovery and management
+- AnimationController: Time-based parameter animation
+- Preset: Package of initial params + animation for demo modes
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PipelineNode:
+    """Represents a node in the pipeline."""
+
+    name: str
+    module: str
+    class_name: str | None = None
+    func_name: str | None = None
+    description: str = ""
+    inputs: list[str] | None = None
+    outputs: list[str] | None = None
+    metrics: dict | None = None  # Performance metrics (avg_ms, min_ms, max_ms)
+
+
+class PipelineIntrospector:
+    """Introspects the render pipeline and generates documentation."""
+
+    def __init__(self):
+        self.nodes: list[PipelineNode] = []
+
+    def add_node(self, node: PipelineNode) -> None:
+        self.nodes.append(node)
+
+    def generate_mermaid_flowchart(self) -> str:
+        """Generate a Mermaid flowchart of the pipeline."""
+        lines = ["```mermaid", "flowchart TD"]
+
+        subgraph_groups = {
+            "Sources": [],
+            "Fetch": [],
+            "Prepare": [],
+            "Scroll": [],
+            "Effects": [],
+            "Display": [],
+            "Async": [],
+            "Animation": [],
+            "Viz": [],
+        }
+
+        other_nodes = []
+
+        for node in self.nodes:
+            node_id = node.name.replace("-", "_").replace(" ", "_").replace(":", "_")
+            label = node.name
+            if node.class_name:
+                label = f"{node.name}\\n({node.class_name})"
+            elif node.func_name:
+                label = f"{node.name}\\n({node.func_name})"
+
+            if node.description:
+                label += f"\\n{node.description}"
+
+            if node.metrics:
+                avg = node.metrics.get("avg_ms", 0)
+                if avg > 0:
+                    label += f"\\n⏱ {avg:.1f}ms"
+                    impact = node.metrics.get("impact_pct", 0)
+                    if impact > 0:
+                        label += f" ({impact:.0f}%)"
+
+            node_entry = f'    {node_id}["{label}"]'
+
+            if "DataSource" in node.name or "SourceRegistry" in node.name:
+                subgraph_groups["Sources"].append(node_entry)
+            elif "fetch" in node.name.lower():
+                subgraph_groups["Fetch"].append(node_entry)
+            elif (
+                "make_block" in node.name
+                or "strip_tags" in node.name
+                or "translate" in node.name
+            ):
+                subgraph_groups["Prepare"].append(node_entry)
+            elif (
+                "StreamController" in node.name
+                or "render_ticker" in node.name
+                or "render_message" in node.name
+                or "Camera" in node.name
+            ):
+                subgraph_groups["Scroll"].append(node_entry)
+            elif "Effect" in node.name or "effect" in node.module:
+                subgraph_groups["Effects"].append(node_entry)
+            elif "Display:" in node.name:
+                subgraph_groups["Display"].append(node_entry)
+            elif "Ntfy" in node.name or "Mic" in node.name:
+                subgraph_groups["Async"].append(node_entry)
+            elif "Animation" in node.name or "Preset" in node.name:
+                subgraph_groups["Animation"].append(node_entry)
+            elif "pipeline_viz" in node.module or "CameraLarge" in node.name:
+                subgraph_groups["Viz"].append(node_entry)
+            else:
+                other_nodes.append(node_entry)
+
+        for group_name, nodes in subgraph_groups.items():
+            if nodes:
+                lines.append(f"    subgraph {group_name}")
+                for node in nodes:
+                    lines.append(node)
+                lines.append("    end")
+
+        for node in other_nodes:
+            lines.append(node)
+
+        lines.append("")
+
+        for node in self.nodes:
+            node_id = node.name.replace("-", "_").replace(" ", "_").replace(":", "_")
+            if node.inputs:
+                for inp in node.inputs:
+                    inp_id = inp.replace("-", "_").replace(" ", "_").replace(":", "_")
+                    lines.append(f"    {inp_id} --> {node_id}")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def generate_mermaid_sequence(self) -> str:
+        """Generate a Mermaid sequence diagram of message flow."""
+        lines = ["```mermaid", "sequenceDiagram"]
+
+        lines.append("    participant Sources")
+        lines.append("    participant Fetch")
+        lines.append("    participant Scroll")
+        lines.append("    participant Effects")
+        lines.append("    participant Display")
+
+        lines.append("    Sources->>Fetch: headlines")
+        lines.append("    Fetch->>Scroll: content blocks")
+        lines.append("    Scroll->>Effects: buffer")
+        lines.append("    Effects->>Effects: process chain")
+        lines.append("    Effects->>Display: rendered buffer")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def generate_mermaid_state(self) -> str:
+        """Generate a Mermaid state diagram of camera modes."""
+        lines = ["```mermaid", "stateDiagram-v2"]
+
+        lines.append("    [*] --> Vertical")
+        lines.append("    Vertical --> Horizontal: set_mode()")
+        lines.append("    Horizontal --> Omni: set_mode()")
+        lines.append("    Omni --> Floating: set_mode()")
+        lines.append("    Floating --> Trace: set_mode()")
+        lines.append("    Trace --> Vertical: set_mode()")
+
+        lines.append("    state Vertical {")
+        lines.append("        [*] --> ScrollUp")
+        lines.append("        ScrollUp --> ScrollUp: +y each frame")
+        lines.append("    }")
+
+        lines.append("    state Horizontal {")
+        lines.append("        [*] --> ScrollLeft")
+        lines.append("        ScrollLeft --> ScrollLeft: +x each frame")
+        lines.append("    }")
+
+        lines.append("    state Omni {")
+        lines.append("        [*] --> Diagonal")
+        lines.append("        Diagonal --> Diagonal: +x, +y")
+        lines.append("    }")
+
+        lines.append("    state Floating {")
+        lines.append("        [*] --> Bobbing")
+        lines.append("        Bobbing --> Bobbing: sin(time)")
+        lines.append("    }")
+
+        lines.append("    state Trace {")
+        lines.append("        [*] --> FollowPath")
+        lines.append("        FollowPath --> FollowPath: node by node")
+        lines.append("    }")
+
+        lines.append("```")
+        return "\n".join(lines)
+
+    def generate_full_diagram(self) -> str:
+        """Generate full pipeline documentation."""
+        lines = [
+            "# Render Pipeline",
+            "",
+            "## Data Flow",
+            "",
+            self.generate_mermaid_flowchart(),
+            "",
+            "## Message Sequence",
+            "",
+            self.generate_mermaid_sequence(),
+            "",
+            "## Camera States",
+            "",
+            self.generate_mermaid_state(),
+        ]
+        return "\n".join(lines)
+
+    def introspect_sources(self) -> None:
+        """Introspect data sources."""
+        from engine import sources
+
+        for name in dir(sources):
+            obj = getattr(sources, name)
+            if isinstance(obj, dict):
+                self.add_node(
+                    PipelineNode(
+                        name=f"Data Source: {name}",
+                        module="engine.sources",
+                        description=f"{len(obj)} feeds configured",
+                    )
+                )
+
+    def introspect_sources_v2(self) -> None:
+        """Introspect data sources v2 (new abstraction)."""
+        from engine.sources_v2 import SourceRegistry, init_default_sources
+
+        init_default_sources()
+        SourceRegistry()
+
+        self.add_node(
+            PipelineNode(
+                name="SourceRegistry",
+                module="engine.sources_v2",
+                class_name="SourceRegistry",
+                description="Source discovery and management",
+            )
+        )
+
+        for name, desc in [
+            ("HeadlinesDataSource", "RSS feed headlines"),
+            ("PoetryDataSource", "Poetry DB"),
+            ("PipelineDataSource", "Pipeline viz (dynamic)"),
+        ]:
+            self.add_node(
+                PipelineNode(
+                    name=f"DataSource: {name}",
+                    module="engine.sources_v2",
+                    class_name=name,
+                    description=f"{desc}",
+                )
+            )
+
+    def introspect_prepare(self) -> None:
+        """Introspect prepare layer (transformation)."""
+        self.add_node(
+            PipelineNode(
+                name="make_block",
+                module="engine.render",
+                func_name="make_block",
+                description="Transform headline into display block",
+                inputs=["title", "source", "timestamp", "width"],
+                outputs=["block"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="strip_tags",
+                module="engine.filter",
+                func_name="strip_tags",
+                description="Remove HTML tags from content",
+                inputs=["html"],
+                outputs=["plain_text"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="translate_headline",
+                module="engine.translate",
+                func_name="translate_headline",
+                description="Translate headline to target language",
+                inputs=["title", "target_lang"],
+                outputs=["translated_title"],
+            )
+        )
+
+    def introspect_fetch(self) -> None:
+        """Introspect fetch layer."""
+        self.add_node(
+            PipelineNode(
+                name="fetch_all",
+                module="engine.fetch",
+                func_name="fetch_all",
+                description="Fetch RSS feeds",
+                outputs=["items"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="fetch_poetry",
+                module="engine.fetch",
+                func_name="fetch_poetry",
+                description="Fetch Poetry DB",
+                outputs=["items"],
+            )
+        )
+
+    def introspect_scroll(self) -> None:
+        """Introspect scroll engine."""
+        self.add_node(
+            PipelineNode(
+                name="StreamController",
+                module="engine.controller",
+                class_name="StreamController",
+                description="Main render loop orchestrator",
+                inputs=["items", "ntfy_poller", "mic_monitor", "display"],
+                outputs=["buffer"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="render_ticker_zone",
+                module="engine.layers",
+                func_name="render_ticker_zone",
+                description="Render scrolling ticker content",
+                inputs=["active", "camera"],
+                outputs=["buffer"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="render_message_overlay",
+                module="engine.layers",
+                func_name="render_message_overlay",
+                description="Render ntfy message overlay",
+                inputs=["msg", "width", "height"],
+                outputs=["overlay", "cache"],
+            )
+        )
+
+    def introspect_render(self) -> None:
+        """Introspect render layer."""
+        self.add_node(
+            PipelineNode(
+                name="big_wrap",
+                module="engine.render",
+                func_name="big_wrap",
+                description="Word-wrap text to width",
+                inputs=["text", "width"],
+                outputs=["lines"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="lr_gradient",
+                module="engine.render",
+                func_name="lr_gradient",
+                description="Apply left-right gradient to lines",
+                inputs=["lines", "position"],
+                outputs=["styled_lines"],
+            )
+        )
+
+    def introspect_async_sources(self) -> None:
+        """Introspect async data sources (ntfy, mic)."""
+        self.add_node(
+            PipelineNode(
+                name="NtfyPoller",
+                module="engine.ntfy",
+                class_name="NtfyPoller",
+                description="Poll ntfy for messages (async)",
+                inputs=["topic"],
+                outputs=["message"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="MicMonitor",
+                module="engine.mic",
+                class_name="MicMonitor",
+                description="Monitor microphone input (async)",
+                outputs=["audio_level"],
+            )
+        )
+
+    def introspect_eventbus(self) -> None:
+        """Introspect event bus for decoupled communication."""
+        self.add_node(
+            PipelineNode(
+                name="EventBus",
+                module="engine.eventbus",
+                class_name="EventBus",
+                description="Thread-safe event publishing",
+                inputs=["event"],
+                outputs=["subscribers"],
+            )
+        )
+
+    def introspect_animation(self) -> None:
+        """Introspect animation system."""
+        self.add_node(
+            PipelineNode(
+                name="AnimationController",
+                module="engine.animation",
+                class_name="AnimationController",
+                description="Time-based parameter animation",
+                inputs=["dt"],
+                outputs=["params"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="Preset",
+                module="engine.animation",
+                class_name="Preset",
+                description="Package of initial params + animation",
+            )
+        )
+
+    def introspect_pipeline_viz(self) -> None:
+        """Introspect pipeline visualization."""
+        self.add_node(
+            PipelineNode(
+                name="generate_large_network_viewport",
+                module="engine.pipeline_viz",
+                func_name="generate_large_network_viewport",
+                description="Large animated network visualization",
+                inputs=["viewport_w", "viewport_h", "frame"],
+                outputs=["buffer"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="CameraLarge",
+                module="engine.pipeline_viz",
+                class_name="CameraLarge",
+                description="Large grid camera (trace mode)",
+            )
+        )
+
+    def introspect_camera(self) -> None:
+        """Introspect camera system."""
+        self.add_node(
+            PipelineNode(
+                name="Camera",
+                module="engine.camera",
+                class_name="Camera",
+                description="Viewport position controller",
+                inputs=["dt"],
+                outputs=["x", "y"],
+            )
+        )
+
+    def introspect_effects(self) -> None:
+        """Introspect effect system."""
+        self.add_node(
+            PipelineNode(
+                name="EffectChain",
+                module="engine.effects",
+                class_name="EffectChain",
+                description="Process effects in sequence",
+                inputs=["buffer", "context"],
+                outputs=["buffer"],
+            )
+        )
+
+        self.add_node(
+            PipelineNode(
+                name="EffectRegistry",
+                module="engine.effects",
+                class_name="EffectRegistry",
+                description="Manage effect plugins",
+            )
+        )
+
+    def introspect_display(self) -> None:
+        """Introspect display backends."""
+        from engine.display import DisplayRegistry
+
+        DisplayRegistry.initialize()
+        backends = DisplayRegistry.list_backends()
+
+        for backend in backends:
+            self.add_node(
+                PipelineNode(
+                    name=f"Display: {backend}",
+                    module="engine.display.backends",
+                    class_name=f"{backend.title()}Display",
+                    description=f"Render to {backend}",
+                    inputs=["buffer"],
+                )
+            )
+
+    def introspect_new_pipeline(self, pipeline=None) -> None:
+        """Introspect new unified pipeline stages with metrics.
+
+        Args:
+            pipeline: Optional Pipeline instance to collect metrics from
+        """
+
+        stages_info = [
+            (
+                "ItemsSource",
+                "engine.pipeline.adapters",
+                "ItemsStage",
+                "Provides pre-fetched items",
+            ),
+            (
+                "Render",
+                "engine.pipeline.adapters",
+                "RenderStage",
+                "Renders items to buffer",
+            ),
+            (
+                "Effect",
+                "engine.pipeline.adapters",
+                "EffectPluginStage",
+                "Applies effect",
+            ),
+            (
+                "Display",
+                "engine.pipeline.adapters",
+                "DisplayStage",
+                "Outputs to display",
+            ),
+        ]
+
+        metrics = None
+        if pipeline and hasattr(pipeline, "get_metrics_summary"):
+            metrics = pipeline.get_metrics_summary()
+            if "error" in metrics:
+                metrics = None
+
+        total_avg = metrics.get("pipeline", {}).get("avg_ms", 0) if metrics else 0
+
+        for stage_name, module, class_name, desc in stages_info:
+            node_metrics = None
+            if metrics and "stages" in metrics:
+                for name, stats in metrics["stages"].items():
+                    if stage_name.lower() in name.lower():
+                        impact_pct = (
+                            (stats.get("avg_ms", 0) / total_avg * 100)
+                            if total_avg > 0
+                            else 0
+                        )
+                        node_metrics = {
+                            "avg_ms": stats.get("avg_ms", 0),
+                            "min_ms": stats.get("min_ms", 0),
+                            "max_ms": stats.get("max_ms", 0),
+                            "impact_pct": impact_pct,
+                        }
+                        break
+
+            self.add_node(
+                PipelineNode(
+                    name=f"Pipeline: {stage_name}",
+                    module=module,
+                    class_name=class_name,
+                    description=desc,
+                    inputs=["data"],
+                    outputs=["data"],
+                    metrics=node_metrics,
+                )
+            )
+
+    def run(self) -> str:
+        """Run full introspection."""
+        self.introspect_sources()
+        self.introspect_sources_v2()
+        self.introspect_fetch()
+        self.introspect_prepare()
+        self.introspect_scroll()
+        self.introspect_render()
+        self.introspect_camera()
+        self.introspect_effects()
+        self.introspect_display()
+        self.introspect_async_sources()
+        self.introspect_eventbus()
+        self.introspect_animation()
+        self.introspect_pipeline_viz()
+
+        return self.generate_full_diagram()
+
+
+def generate_pipeline_diagram() -> str:
+    """Generate a self-documenting pipeline diagram."""
+    introspector = PipelineIntrospector()
+    return introspector.run()
+
+
+if __name__ == "__main__":
+    print(generate_pipeline_diagram())

engine/pipeline/__init__.py

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

@@ -0,0 +1,299 @@
+"""
+Stage adapters - Bridge existing components to the Stage interface.
+
+This module provides adapters that wrap existing components
+(EffectPlugin, Display, DataSource, Camera) as Stage implementations.
+"""
+
+import random
+from typing import Any
+
+from engine.pipeline.core import PipelineContext, Stage
+
+
+class RenderStage(Stage):
+    """Stage that renders items to a text buffer for display.
+
+    This mimics the old demo's render pipeline:
+    - Selects headlines and renders them to blocks
+    - Applies camera scroll position
+    - Adds firehose layer if enabled
+    """
+
+    def __init__(
+        self,
+        items: list,
+        width: int = 80,
+        height: int = 24,
+        camera_speed: float = 1.0,
+        camera_mode: str = "vertical",
+        firehose_enabled: bool = False,
+        name: str = "render",
+    ):
+        self.name = name
+        self.category = "render"
+        self.optional = False
+        self._items = items
+        self._width = width
+        self._height = height
+        self._camera_speed = camera_speed
+        self._camera_mode = camera_mode
+        self._firehose_enabled = firehose_enabled
+
+        self._camera_y = 0.0
+        self._camera_x = 0
+        self._scroll_accum = 0.0
+        self._ticker_next_y = 0
+        self._active: list = []
+        self._seen: set = set()
+        self._pool: list = list(items)
+        self._noise_cache: dict = {}
+        self._frame_count = 0
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"source.items"}
+
+    def init(self, ctx: PipelineContext) -> bool:
+        random.shuffle(self._pool)
+        return True
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Render items to a text buffer."""
+        from engine.effects import next_headline
+        from engine.layers import render_firehose, render_ticker_zone
+        from engine.render import make_block
+
+        items = data or self._items
+        w = ctx.params.viewport_width if ctx.params else self._width
+        h = ctx.params.viewport_height if ctx.params else self._height
+        camera_speed = ctx.params.camera_speed if ctx.params else self._camera_speed
+        firehose = ctx.params.firehose_enabled if ctx.params else self._firehose_enabled
+
+        scroll_step = 0.5 / (camera_speed * 10)
+        self._scroll_accum += scroll_step
+
+        GAP = 3
+
+        while self._scroll_accum >= scroll_step:
+            self._scroll_accum -= scroll_step
+            self._camera_y += 1.0
+
+            while (
+                self._ticker_next_y < int(self._camera_y) + h + 10
+                and len(self._active) < 50
+            ):
+                t, src, ts = next_headline(self._pool, items, self._seen)
+                ticker_content, hc, midx = make_block(t, src, ts, w)
+                self._active.append((ticker_content, hc, self._ticker_next_y, midx))
+                self._ticker_next_y += len(ticker_content) + GAP
+
+        self._active = [
+            (c, hc, by, mi)
+            for c, hc, by, mi in self._active
+            if by + len(c) > int(self._camera_y)
+        ]
+        for k in list(self._noise_cache):
+            if k < int(self._camera_y):
+                del self._noise_cache[k]
+
+        grad_offset = (self._frame_count * 0.01) % 1.0
+
+        buf, self._noise_cache = render_ticker_zone(
+            self._active,
+            scroll_cam=int(self._camera_y),
+            camera_x=self._camera_x,
+            ticker_h=h,
+            w=w,
+            noise_cache=self._noise_cache,
+            grad_offset=grad_offset,
+        )
+
+        if firehose:
+            firehose_buf = render_firehose(items, w, 0, h)
+            buf.extend(firehose_buf)
+
+        self._frame_count += 1
+        return buf
+
+
+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 capabilities(self) -> set[str]:
+        return {f"effect.{self.name}"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return set()
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Process data through the effect."""
+        if data is None:
+            return None
+        from engine.effects import EffectContext
+
+        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", []),
+        )
+        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 set()
+
+    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()
+
+    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 ItemsStage(Stage):
+    """Stage that holds pre-fetched items and provides them to the pipeline."""
+
+    def __init__(self, items, name: str = "headlines"):
+        self._items = items
+        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()
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Return the pre-fetched items."""
+        return self._items
+
+
+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 {"source.items"}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Apply camera transformation to data."""
+        if data is None:
+            return None
+        if hasattr(self._camera, "apply"):
+            return self._camera.apply(
+                data, ctx.params.viewport_width if ctx.params else 80
+            )
+        return data
+
+    def cleanup(self) -> None:
+        if hasattr(self._camera, "reset"):
+            self._camera.reset()
+
+
+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_items_stage(items, name: str = "headlines") -> ItemsStage:
+    """Create a Stage that holds pre-fetched items."""
+    return ItemsStage(items, name)

engine/pipeline/controller.py

@@ -0,0 +1,320 @@
+"""
+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._execution_order = self._resolve_dependencies()
+        self._initialized = True
+        return self
+
+    def _resolve_dependencies(self) -> list[str]:
+        """Resolve stage execution order using topological sort."""
+        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:
+                    dep_stage = self._stages.get(dep)
+                    if dep_stage:
+                        visit(dep)
+
+            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 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."""
+        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] = []
+
+        for name in self._execution_order:
+            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:
+                current_data = stage.process(current_data, self.context)
+            except Exception as e:
+                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,
+                    )
+                )
+
+        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,
+                )
+            )
+            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_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
+
+
+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.pipeline.adapters import DataSourceStage
+    from engine.sources_v2 import HeadlinesDataSource
+
+    pipeline = Pipeline()
+
+    # Add source stage (wrapped as Stage)
+    source = HeadlinesDataSource()
+    pipeline.add_stage("source", DataSourceStage(source, name="headlines"))
+
+    # Add display stage
+    display = StageRegistry.create("display", "terminal")
+    if display:
+        pipeline.add_stage("display", display)
+
+    return pipeline.build()

engine/pipeline/core.py

@@ -0,0 +1,221 @@
+"""
+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
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from engine.pipeline.params import PipelineParams
+
+
+@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)
+
+    Stages declare:
+    - capabilities: What they provide to other stages
+    - dependencies: What they need from other stages
+
+    Duck-typing is supported: any class with the required methods can act as a Stage.
+    """
+
+    name: str
+    category: str  # "source", "effect", "display", "camera"
+    optional: bool = False  # If True, pipeline continues even if stage fails
+
+    @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

@@ -0,0 +1,144 @@
+"""
+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"
+
+    # 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/presets.py

@@ -0,0 +1,155 @@
+"""
+Pipeline presets - Pre-configured pipeline configurations.
+
+Provides PipelinePreset as a unified preset system that wraps
+the existing Preset class from animation.py for backwards compatibility.
+"""
+
+from dataclasses import dataclass, field
+
+from engine.animation import Preset as AnimationPreset
+from engine.pipeline.params import PipelineParams
+
+
+@dataclass
+class PipelinePreset:
+    """Pre-configured pipeline with stages and animation.
+
+    A PipelinePreset packages:
+    - Initial params: Starting configuration
+    - Stages: List of stage configurations to create
+    - Animation: Optional animation controller
+
+    This is the new unified preset that works with the Pipeline class.
+    """
+
+    name: str
+    description: str = ""
+    source: str = "headlines"
+    display: str = "terminal"
+    camera: str = "vertical"
+    effects: list[str] = field(default_factory=list)
+    initial_params: PipelineParams | None = None
+    animation_preset: AnimationPreset | None = None
+
+    def to_params(self) -> PipelineParams:
+        """Convert to PipelineParams."""
+        if self.initial_params:
+            return self.initial_params.copy()
+        params = PipelineParams()
+        params.source = self.source
+        params.display = self.display
+        params.camera_mode = self.camera
+        params.effect_order = self.effects.copy()
+        return params
+
+    @classmethod
+    def from_animation_preset(cls, preset: AnimationPreset) -> "PipelinePreset":
+        """Create a PipelinePreset from an existing animation Preset."""
+        params = preset.initial_params
+        return cls(
+            name=preset.name,
+            description=preset.description,
+            source=params.source,
+            display=params.display,
+            camera=params.camera_mode,
+            effects=params.effect_order.copy(),
+            initial_params=params,
+            animation_preset=preset,
+        )
+
+    def create_animation_controller(self):
+        """Create an AnimationController from this preset."""
+        if self.animation_preset:
+            return self.animation_preset.create_controller()
+        return None
+
+
+# Built-in presets
+DEMO_PRESET = PipelinePreset(
+    name="demo",
+    description="Demo mode with effect cycling and camera modes",
+    source="headlines",
+    display="terminal",
+    camera="vertical",
+    effects=["noise", "fade", "glitch", "firehose", "hud"],
+)
+
+POETRY_PRESET = PipelinePreset(
+    name="poetry",
+    description="Poetry feed with subtle effects",
+    source="poetry",
+    display="terminal",
+    camera="vertical",
+    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="vertical",
+    effects=["noise", "fade", "glitch", "hud"],
+)
+
+SIXEL_PRESET = PipelinePreset(
+    name="sixel",
+    description="Sixel graphics display mode",
+    source="headlines",
+    display="sixel",
+    camera="vertical",
+    effects=["noise", "fade", "glitch", "hud"],
+)
+
+FIREHOSE_PRESET = PipelinePreset(
+    name="firehose",
+    description="High-speed firehose mode",
+    source="headlines",
+    display="terminal",
+    camera="vertical",
+    effects=["noise", "fade", "glitch", "firehose", "hud"],
+)
+
+
+PRESETS: dict[str, PipelinePreset] = {
+    "demo": DEMO_PRESET,
+    "poetry": POETRY_PRESET,
+    "pipeline": PIPELINE_VIZ_PRESET,
+    "websocket": WEBSOCKET_PRESET,
+    "sixel": SIXEL_PRESET,
+    "firehose": FIREHOSE_PRESET,
+}
+
+
+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(),
+        initial_params=params,
+    )

engine/pipeline/registry.py

@@ -0,0 +1,165 @@
+"""
+Stage registry - Unified registration for all pipeline stages.
+
+Provides a single registry for sources, effects, displays, and cameras.
+"""
+
+from __future__ import annotations
+
+from engine.pipeline.core import Stage
+
+
+class StageRegistry:
+    """Unified registry for all pipeline stage types."""
+
+    _categories: dict[str, dict[str, type[Stage]]] = {}
+    _discovered: bool = False
+    _instances: dict[str, Stage] = {}
+
+    @classmethod
+    def register(cls, category: str, stage_class: type[Stage]) -> 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] = {}
+
+        # Use class name as key
+        key = getattr(stage_class, "__name__", stage_class.__class__.__name__)
+        cls._categories[category][key] = stage_class
+
+    @classmethod
+    def get(cls, category: str, name: str) -> type[Stage] | 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.sources_v2 import (
+            HeadlinesDataSource,
+            PipelineDataSource,
+            PoetryDataSource,
+        )
+
+        StageRegistry.register("source", HeadlinesDataSource)
+        StageRegistry.register("source", PoetryDataSource)
+        StageRegistry.register("source", PipelineDataSource)
+
+        StageRegistry._categories["source"]["headlines"] = HeadlinesDataSource
+        StageRegistry._categories["source"]["poetry"] = PoetryDataSource
+        StageRegistry._categories["source"]["pipeline"] = PipelineDataSource
+    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/pipeline_viz.py

@@ -0,0 +1,364 @@
+"""
+Pipeline visualization - Large animated network visualization with camera modes.
+"""
+
+import math
+
+NODE_NETWORK = {
+    "sources": [
+        {"id": "RSS", "label": "RSS FEEDS", "x": 20, "y": 20},
+        {"id": "POETRY", "label": "POETRY DB", "x": 100, "y": 20},
+        {"id": "NTFY", "label": "NTFY MSG", "x": 180, "y": 20},
+        {"id": "MIC", "label": "MICROPHONE", "x": 260, "y": 20},
+    ],
+    "fetch": [
+        {"id": "FETCH", "label": "FETCH LAYER", "x": 140, "y": 100},
+        {"id": "CACHE", "label": "CACHE", "x": 220, "y": 100},
+    ],
+    "scroll": [
+        {"id": "STREAM", "label": "STREAM CTRL", "x": 60, "y": 180},
+        {"id": "CAMERA", "label": "CAMERA", "x": 140, "y": 180},
+        {"id": "RENDER", "label": "RENDER", "x": 220, "y": 180},
+    ],
+    "effects": [
+        {"id": "NOISE", "label": "NOISE", "x": 20, "y": 260},
+        {"id": "FADE", "label": "FADE", "x": 80, "y": 260},
+        {"id": "GLITCH", "label": "GLITCH", "x": 140, "y": 260},
+        {"id": "FIRE", "label": "FIREHOSE", "x": 200, "y": 260},
+        {"id": "HUD", "label": "HUD", "x": 260, "y": 260},
+    ],
+    "display": [
+        {"id": "TERM", "label": "TERMINAL", "x": 20, "y": 340},
+        {"id": "WEB", "label": "WEBSOCKET", "x": 80, "y": 340},
+        {"id": "PYGAME", "label": "PYGAME", "x": 140, "y": 340},
+        {"id": "SIXEL", "label": "SIXEL", "x": 200, "y": 340},
+        {"id": "KITTY", "label": "KITTY", "x": 260, "y": 340},
+    ],
+}
+
+ALL_NODES = []
+for group_nodes in NODE_NETWORK.values():
+    ALL_NODES.extend(group_nodes)
+
+NETWORK_PATHS = [
+    ["RSS", "FETCH", "CACHE", "STREAM", "CAMERA", "RENDER", "NOISE", "TERM"],
+    ["POETRY", "FETCH", "CACHE", "STREAM", "CAMERA", "RENDER", "FADE", "WEB"],
+    ["NTFY", "FETCH", "CACHE", "STREAM", "CAMERA", "RENDER", "GLITCH", "PYGAME"],
+    ["MIC", "FETCH", "CACHE", "STREAM", "CAMERA", "RENDER", "FIRE", "SIXEL"],
+    ["RSS", "FETCH", "CACHE", "STREAM", "CAMERA", "RENDER", "HUD", "KITTY"],
+]
+
+GRID_WIDTH = 300
+GRID_HEIGHT = 400
+
+
+def get_node_by_id(node_id: str):
+    for node in ALL_NODES:
+        if node["id"] == node_id:
+            return node
+    return None
+
+
+def draw_network_to_grid(frame: int = 0) -> list[list[str]]:
+    grid = [[" " for _ in range(GRID_WIDTH)] for _ in range(GRID_HEIGHT)]
+
+    active_path_idx = (frame // 60) % len(NETWORK_PATHS)
+    active_path = NETWORK_PATHS[active_path_idx]
+
+    for node in ALL_NODES:
+        x, y = node["x"], node["y"]
+        label = node["label"]
+        is_active = node["id"] in active_path
+        is_highlight = node["id"] == active_path[(frame // 15) % len(active_path)]
+
+        node_w, node_h = 20, 7
+
+        for dy in range(node_h):
+            for dx in range(node_w):
+                gx, gy = x + dx, y + dy
+                if 0 <= gx < GRID_WIDTH and 0 <= gy < GRID_HEIGHT:
+                    if dy == 0:
+                        char = "┌" if dx == 0 else ("┐" if dx == node_w - 1 else "─")
+                    elif dy == node_h - 1:
+                        char = "└" if dx == 0 else ("┘" if dx == node_w - 1 else "─")
+                    elif dy == node_h // 2:
+                        if dx == 0 or dx == node_w - 1:
+                            char = "│"
+                        else:
+                            pad = (node_w - 2 - len(label)) // 2
+                            if dx - 1 == pad and len(label) <= node_w - 2:
+                                char = (
+                                    label[dx - 1 - pad]
+                                    if dx - 1 - pad < len(label)
+                                    else " "
+                                )
+                            else:
+                                char = " "
+                    else:
+                        char = "│" if dx == 0 or dx == node_w - 1 else " "
+
+                    if char.strip():
+                        if is_highlight:
+                            grid[gy][gx] = "\033[1;38;5;46m" + char + "\033[0m"
+                        elif is_active:
+                            grid[gy][gx] = "\033[1;38;5;220m" + char + "\033[0m"
+                        else:
+                            grid[gy][gx] = "\033[38;5;240m" + char + "\033[0m"
+
+    for i, node_id in enumerate(active_path[:-1]):
+        curr = get_node_by_id(node_id)
+        next_id = active_path[i + 1]
+        next_node = get_node_by_id(next_id)
+        if curr and next_node:
+            x1, y1 = curr["x"] + 7, curr["y"] + 2
+            x2, y2 = next_node["x"] + 7, next_node["y"] + 2
+
+            step = 1 if x2 >= x1 else -1
+            for x in range(x1, x2 + step, step):
+                if 0 <= x < GRID_WIDTH and 0 <= y1 < GRID_HEIGHT:
+                    grid[y1][x] = "\033[38;5;45m─\033[0m"
+
+            step = 1 if y2 >= y1 else -1
+            for y in range(y1, y2 + step, step):
+                if 0 <= x2 < GRID_WIDTH and 0 <= y < GRID_HEIGHT:
+                    grid[y][x2] = "\033[38;5;45m│\033[0m"
+
+    return grid
+
+
+class TraceCamera:
+    def __init__(self):
+        self.x = 0
+        self.y = 0
+        self.target_x = 0
+        self.target_y = 0
+        self.current_node_idx = 0
+        self.path = []
+        self.frame = 0
+
+    def update(self, dt: float, frame: int = 0) -> None:
+        self.frame = frame
+        active_path = NETWORK_PATHS[(frame // 60) % len(NETWORK_PATHS)]
+
+        if self.path != active_path:
+            self.path = active_path
+            self.current_node_idx = 0
+
+        if self.current_node_idx < len(self.path):
+            node_id = self.path[self.current_node_idx]
+            node = get_node_by_id(node_id)
+            if node:
+                self.target_x = max(0, node["x"] - 40)
+                self.target_y = max(0, node["y"] - 10)
+
+            self.current_node_idx += 1
+
+        self.x += int((self.target_x - self.x) * 0.1)
+        self.y += int((self.target_y - self.y) * 0.1)
+
+
+class CameraLarge:
+    def __init__(self, viewport_w: int, viewport_h: int, frame: int):
+        self.viewport_w = viewport_w
+        self.viewport_h = viewport_h
+        self.frame = frame
+        self.x = 0
+        self.y = 0
+        self.mode = "trace"
+        self.trace_camera = TraceCamera()
+
+    def set_vertical_mode(self):
+        self.mode = "vertical"
+
+    def set_horizontal_mode(self):
+        self.mode = "horizontal"
+
+    def set_omni_mode(self):
+        self.mode = "omni"
+
+    def set_floating_mode(self):
+        self.mode = "floating"
+
+    def set_trace_mode(self):
+        self.mode = "trace"
+
+    def update(self, dt: float):
+        self.frame += 1
+
+        if self.mode == "vertical":
+            self.y = int((self.frame * 0.5) % (GRID_HEIGHT - self.viewport_h))
+        elif self.mode == "horizontal":
+            self.x = int((self.frame * 0.5) % (GRID_WIDTH - self.viewport_w))
+        elif self.mode == "omni":
+            self.x = int((self.frame * 0.3) % (GRID_WIDTH - self.viewport_w))
+            self.y = int((self.frame * 0.5) % (GRID_HEIGHT - self.viewport_h))
+        elif self.mode == "floating":
+            self.x = int(50 + math.sin(self.frame * 0.02) * 30)
+            self.y = int(50 + math.cos(self.frame * 0.015) * 30)
+        elif self.mode == "trace":
+            self.trace_camera.update(dt, self.frame)
+            self.x = self.trace_camera.x
+            self.y = self.trace_camera.y
+
+
+def generate_mermaid_graph(frame: int = 0) -> str:
+    effects = ["NOISE", "FADE", "GLITCH", "FIREHOSE"]
+    active_effect = effects[(frame // 30) % 4]
+
+    cam_modes = ["VERTICAL", "HORIZONTAL", "OMNI", "FLOATING", "TRACE"]
+    active_cam = cam_modes[(frame // 100) % 5]
+
+    return f"""graph LR
+    subgraph SOURCES
+        RSS[RSS Feeds]
+        Poetry[Poetry DB]
+        Ntfy[Ntfy Msg]
+        Mic[Microphone]
+    end
+
+    subgraph FETCH
+        Fetch(fetch_all)
+        Cache[(Cache)]
+    end
+
+    subgraph SCROLL
+        Scroll(StreamController)
+        Camera({active_cam})
+    end
+
+    subgraph EFFECTS
+        Noise[NOISE]
+        Fade[FADE]
+        Glitch[GLITCH]
+        Fire[FIREHOSE]
+        Hud[HUD]
+    end
+
+    subgraph DISPLAY
+        Term[Terminal]
+        Web[WebSocket]
+        Pygame[PyGame]
+        Sixel[Sixel]
+    end
+
+    RSS --> Fetch
+    Poetry --> Fetch
+    Ntfy --> Fetch
+    Fetch --> Cache
+    Cache --> Scroll
+    Scroll --> Noise
+    Scroll --> Fade
+    Scroll --> Glitch
+    Scroll --> Fire
+    Scroll --> Hud
+
+    Noise --> Term
+    Fade --> Web
+    Glitch --> Pygame
+    Fire --> Sixel
+
+    style {active_effect} fill:#90EE90
+    style Camera fill:#87CEEB
+"""
+
+
+def generate_network_pipeline(
+    width: int = 80, height: int = 24, frame: int = 0
+) -> list[str]:
+    try:
+        from engine.beautiful_mermaid import render_mermaid_ascii
+
+        mermaid_graph = generate_mermaid_graph(frame)
+        ascii_output = render_mermaid_ascii(mermaid_graph, padding_x=2, padding_y=1)
+
+        lines = ascii_output.split("\n")
+
+        result = []
+        for y in range(height):
+            if y < len(lines):
+                line = lines[y]
+                if len(line) < width:
+                    line = line + " " * (width - len(line))
+                elif len(line) > width:
+                    line = line[:width]
+                result.append(line)
+            else:
+                result.append(" " * width)
+
+        status_y = height - 2
+        if status_y < height:
+            fps = 60 - (frame % 15)
+
+            cam_modes = ["VERTICAL", "HORIZONTAL", "OMNI", "FLOATING", "TRACE"]
+            cam = cam_modes[(frame // 100) % 5]
+            effects = ["NOISE", "FADE", "GLITCH", "FIREHOSE"]
+            eff = effects[(frame // 30) % 4]
+
+            anim = "▓▒░ "[frame % 4]
+            status = f" FPS:{fps:3.0f} │ {anim} {eff} │ Cam:{cam}"
+            status = status[: width - 4].ljust(width - 4)
+            result[status_y] = "║ " + status + " ║"
+
+        if height > 0:
+            result[0] = "═" * width
+            result[height - 1] = "═" * width
+
+        return result
+
+    except Exception as e:
+        return [
+            f"Error: {e}" + " " * (width - len(f"Error: {e}")) for _ in range(height)
+        ]
+
+
+def generate_large_network_viewport(
+    viewport_w: int = 80, viewport_h: int = 24, frame: int = 0
+) -> list[str]:
+    cam_modes = ["VERTICAL", "HORIZONTAL", "OMNI", "FLOATING", "TRACE"]
+    camera_mode = cam_modes[(frame // 100) % 5]
+
+    camera = CameraLarge(viewport_w, viewport_h, frame)
+
+    if camera_mode == "TRACE":
+        camera.set_trace_mode()
+    elif camera_mode == "VERTICAL":
+        camera.set_vertical_mode()
+    elif camera_mode == "HORIZONTAL":
+        camera.set_horizontal_mode()
+    elif camera_mode == "OMNI":
+        camera.set_omni_mode()
+    elif camera_mode == "FLOATING":
+        camera.set_floating_mode()
+
+    camera.update(1 / 60)
+
+    grid = draw_network_to_grid(frame)
+
+    result = []
+    for vy in range(viewport_h):
+        line = ""
+        for vx in range(viewport_w):
+            gx = camera.x + vx
+            gy = camera.y + vy
+            if 0 <= gx < GRID_WIDTH and 0 <= gy < GRID_HEIGHT:
+                line += grid[gy][gx]
+            else:
+                line += " "
+        result.append(line)
+
+    fps = 60 - (frame % 15)
+
+    active_path = NETWORK_PATHS[(frame // 60) % len(NETWORK_PATHS)]
+    active_node = active_path[(frame // 15) % len(active_path)]
+
+    anim = "▓▒░ "[frame % 4]
+    status = f" FPS:{fps:3.0f} │ {anim} {camera_mode:9s} │ Node:{active_node}"
+    status = status[: viewport_w - 4].ljust(viewport_w - 4)
+    if viewport_h > 2:
+        result[viewport_h - 2] = "║ " + status + " ║"
+
+    if viewport_h > 0:
+        result[0] = "═" * viewport_w
+        result[viewport_h - 1] = "═" * viewport_w
+
+    return result

engine/scroll.py

@@ -7,6 +7,7 @@ import random
 import time
 
 from engine import config
+from engine.camera import Camera
 from engine.display import (
     Display,
     TerminalDisplay,
@@ -27,10 +28,19 @@ from engine.viewport import th, tw
 USE_EFFECT_CHAIN = True
 
 
-def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
+def stream(
+    items,
+    ntfy_poller,
+    mic_monitor,
+    display: Display | None = None,
+    camera: Camera | None = None,
+):
     """Main render loop with four layers: message, ticker, scroll motion, firehose."""
     if display is None:
         display = TerminalDisplay()
+    if camera is None:
+        camera = Camera.vertical()
+
     random.shuffle(items)
     pool = list(items)
     seen = set()
@@ -46,7 +56,6 @@ def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
     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
@@ -72,10 +81,10 @@ def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
         scroll_motion_accum += config.FRAME_DT
         while scroll_motion_accum >= scroll_step_interval:
             scroll_motion_accum -= scroll_step_interval
-            scroll_cam += 1
+            camera.update(config.FRAME_DT)
 
             while (
-                ticker_next_y < scroll_cam + ticker_view_h + 10
+                ticker_next_y < camera.y + ticker_view_h + 10
                 and queued < config.HEADLINE_LIMIT
             ):
                 from engine.effects import next_headline
@@ -88,17 +97,17 @@ def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
                 queued += 1
 
             active = [
-                (c, hc, by, mi) for c, hc, by, mi in active if by + len(c) > scroll_cam
+                (c, hc, by, mi) for c, hc, by, mi in active if by + len(c) > camera.y
             ]
             for k in list(noise_cache):
-                if k < scroll_cam:
+                if k < camera.y:
                     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
+            active, camera.y, camera.x, ticker_h, w, noise_cache, grad_offset
         )
         buf.extend(ticker_buf)
 
@@ -110,8 +119,9 @@ def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
                 buf,
                 w,
                 h,
-                scroll_cam,
+                camera.y,
                 ticker_h,
+                camera.x,
                 mic_excess,
                 grad_offset,
                 frame_number,

engine/sources_v2.py

@@ -0,0 +1,362 @@
+"""
+Data source abstraction - Treat data sources as first-class citizens in the pipeline.
+
+Each data source implements a common interface:
+- name: Display name for the source
+- fetch(): Fetch fresh data
+- stream(): Stream data continuously (optional)
+- get_items(): Get current items
+"""
+
+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
+
+
+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 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 PipelineDataSource(DataSource):
+    """Data source for pipeline visualization (demo mode). Dynamic - updates every frame."""
+
+    def __init__(self, viewport_width: int = 80, viewport_height: int = 24):
+        self.viewport_width = viewport_width
+        self.viewport_height = viewport_height
+        self.frame = 0
+
+    @property
+    def name(self) -> str:
+        return "pipeline"
+
+    @property
+    def is_dynamic(self) -> bool:
+        return True
+
+    def fetch(self) -> list[SourceItem]:
+        from engine.pipeline_viz import generate_large_network_viewport
+
+        buffer = generate_large_network_viewport(
+            self.viewport_width, self.viewport_height, self.frame
+        )
+        self.frame += 1
+        content = "\n".join(buffer)
+        return [
+            SourceItem(content=content, source="pipeline", timestamp=f"f{self.frame}")
+        ]
+
+    def get_items(self) -> list[SourceItem]:
+        return self.fetch()
+
+
+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()
+
+    def create_pipeline(self, width: int = 80, height: int = 24) -> PipelineDataSource:
+        return PipelineDataSource(width, height)
+
+
+_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

hk.pkl

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

kitty_test.py

@@ -0,0 +1,31 @@
+#!/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

@@ -34,9 +34,28 @@ 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-pipeline = { run = "uv run mainline.py --preset pipeline --display pygame", depends = ["sync-all"] }
+
 # =====================
 # Command & Control
 # =====================

pyproject.toml

@@ -34,7 +34,10 @@ websocket = [
     "websockets>=12.0",
 ]
 sixel = [
-    "pysixel>=0.1.0",
+    "Pillow>=10.0.0",
+]
+pygame = [
+    "pygame>=2.0.0",
 ]
 browser = [
     "playwright>=1.40.0",
@@ -70,6 +73,12 @@ 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

@@ -0,0 +1,36 @@
+"""
+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/test_benchmark.py

@@ -0,0 +1,100 @@
+"""
+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_camera.py

@@ -0,0 +1,69 @@
+
+from engine.camera import Camera, CameraMode
+
+
+def test_camera_vertical_default():
+    """Test default vertical camera."""
+    cam = Camera()
+    assert cam.mode == CameraMode.VERTICAL
+    assert cam.x == 0
+    assert cam.y == 0
+
+
+def test_camera_vertical_factory():
+    """Test vertical factory method."""
+    cam = Camera.vertical(speed=2.0)
+    assert cam.mode == CameraMode.VERTICAL
+    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

@@ -5,7 +5,75 @@ Tests for engine.controller module.
 from unittest.mock import MagicMock, patch
 
 from engine import config
-from engine.controller import StreamController
+from engine.controller import StreamController, _get_display
+
+
+class TestGetDisplay:
+    """Tests for _get_display function."""
+
+    @patch("engine.controller.WebSocketDisplay")
+    @patch("engine.controller.TerminalDisplay")
+    def test_get_display_terminal(self, mock_terminal, mock_ws):
+        """returns TerminalDisplay for display=terminal."""
+        mock_terminal.return_value = MagicMock()
+        mock_ws.return_value = MagicMock()
+
+        cfg = config.Config(display="terminal")
+        display = _get_display(cfg)
+
+        mock_terminal.assert_called()
+        assert isinstance(display, MagicMock)
+
+    @patch("engine.controller.WebSocketDisplay")
+    @patch("engine.controller.TerminalDisplay")
+    def test_get_display_websocket(self, mock_terminal, mock_ws):
+        """returns WebSocketDisplay for display=websocket."""
+        mock_ws_instance = MagicMock()
+        mock_ws.return_value = mock_ws_instance
+        mock_terminal.return_value = MagicMock()
+
+        cfg = config.Config(display="websocket")
+        _get_display(cfg)
+
+        mock_ws.assert_called()
+        mock_ws_instance.start_server.assert_called()
+        mock_ws_instance.start_http_server.assert_called()
+
+    @patch("engine.controller.SixelDisplay")
+    def test_get_display_sixel(self, mock_sixel):
+        """returns SixelDisplay for display=sixel."""
+        mock_sixel.return_value = MagicMock()
+        cfg = config.Config(display="sixel")
+        _get_display(cfg)
+
+        mock_sixel.assert_called()
+
+    def test_get_display_unknown_returns_null(self):
+        """returns NullDisplay for unknown display mode."""
+        cfg = config.Config(display="unknown")
+        display = _get_display(cfg)
+
+        from engine.display import NullDisplay
+
+        assert isinstance(display, NullDisplay)
+
+    @patch("engine.controller.WebSocketDisplay")
+    @patch("engine.controller.TerminalDisplay")
+    @patch("engine.controller.MultiDisplay")
+    def test_get_display_both(self, mock_multi, mock_terminal, mock_ws):
+        """returns MultiDisplay for display=both."""
+        mock_terminal_instance = MagicMock()
+        mock_ws_instance = MagicMock()
+        mock_terminal.return_value = mock_terminal_instance
+        mock_ws.return_value = mock_ws_instance
+
+        cfg = config.Config(display="both")
+        _get_display(cfg)
+
+        mock_multi.assert_called()
+        call_args = mock_multi.call_args[0][0]
+        assert mock_terminal_instance in call_args
+        assert mock_ws_instance in call_args
 
 
 class TestStreamController:
@@ -68,6 +136,24 @@ class TestStreamController:
         assert mic_ok is False
         assert ntfy_ok is True
 
+    @patch("engine.controller.MicMonitor")
+    def test_initialize_sources_cc_subscribed(self, mock_mic):
+        """initialize_sources subscribes C&C handler."""
+        mock_mic_instance = MagicMock()
+        mock_mic_instance.available = False
+        mock_mic_instance.start.return_value = False
+        mock_mic.return_value = mock_mic_instance
+
+        with patch("engine.controller.NtfyPoller") as mock_ntfy:
+            mock_ntfy_instance = MagicMock()
+            mock_ntfy_instance.start.return_value = True
+            mock_ntfy.return_value = mock_ntfy_instance
+
+            controller = StreamController()
+            controller.initialize_sources()
+
+            mock_ntfy_instance.subscribe.assert_called()
+
 
 class TestStreamControllerCleanup:
     """Tests for StreamController cleanup."""

tests/test_display.py

@@ -2,7 +2,10 @@
 Tests for engine.display module.
 """
 
-from engine.display import NullDisplay, TerminalDisplay
+from unittest.mock import MagicMock
+
+from engine.display import DisplayRegistry, NullDisplay, TerminalDisplay
+from engine.display.backends.multi import MultiDisplay
 
 
 class TestDisplayProtocol:
@@ -25,6 +28,66 @@ 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."""
 
@@ -77,3 +140,71 @@ 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)
+
+        mock_display1.show.assert_called_once_with(buffer)
+        mock_display2.show.assert_called_once_with(buffer)
+
+    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,8 +5,10 @@ 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,
 )
 
 
@@ -92,6 +94,29 @@ 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")
@@ -102,6 +127,105 @@ 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_hud.py

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

@@ -87,10 +87,26 @@ class TestRenderTickerZone:
 
     def test_returns_list(self):
         """Returns a list of strings."""
-        result, cache = layers.render_ticker_zone([], 0, 10, 80, {}, 0.0)
+        result, cache = layers.render_ticker_zone(
+            [],
+            scroll_cam=0,
+            camera_x=0,
+            ticker_h=10,
+            w=80,
+            noise_cache={},
+            grad_offset=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)
+        result, cache = layers.render_ticker_zone(
+            [],
+            scroll_cam=0,
+            camera_x=0,
+            ticker_h=10,
+            w=80,
+            noise_cache={},
+            grad_offset=0.0,
+        )
         assert isinstance(cache, dict)

tests/test_ntfy_integration.py

@@ -6,7 +6,11 @@ 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_pipeline.py

@@ -0,0 +1,281 @@
+"""
+Tests for the new unified pipeline architecture.
+"""
+
+from unittest.mock import MagicMock
+
+from engine.pipeline import (
+    Pipeline,
+    PipelineConfig,
+    PipelineContext,
+    Stage,
+    StageRegistry,
+    create_default_pipeline,
+    discover_stages,
+)
+
+
+class TestStageRegistry:
+    """Tests for StageRegistry."""
+
+    def setup_method(self):
+        """Reset registry before each test."""
+        StageRegistry._discovered = False
+        StageRegistry._categories.clear()
+        StageRegistry._instances.clear()
+
+    def test_discover_stages_registers_sources(self):
+        """discover_stages registers source stages."""
+        discover_stages()
+
+        sources = StageRegistry.list("source")
+        assert "HeadlinesDataSource" in sources
+        assert "PoetryDataSource" in sources
+        assert "PipelineDataSource" in sources
+
+    def test_discover_stages_registers_displays(self):
+        """discover_stages registers display stages."""
+        discover_stages()
+
+        displays = StageRegistry.list("display")
+        assert "terminal" in displays
+        assert "pygame" in displays
+        assert "websocket" in displays
+        assert "null" in displays
+        assert "sixel" in displays
+
+    def test_create_source_stage(self):
+        """StageRegistry.create creates source stages."""
+        discover_stages()
+
+        source = StageRegistry.create("source", "HeadlinesDataSource")
+        assert source is not None
+        assert source.name == "headlines"
+
+    def test_create_display_stage(self):
+        """StageRegistry.create creates display stages."""
+        discover_stages()
+
+        display = StageRegistry.create("display", "terminal")
+        assert display is not None
+        assert hasattr(display, "_display")
+
+    def test_create_display_stage_pygame(self):
+        """StageRegistry.create creates pygame display stage."""
+        discover_stages()
+
+        display = StageRegistry.create("display", "pygame")
+        assert display is not None
+
+
+class TestPipeline:
+    """Tests for Pipeline class."""
+
+    def setup_method(self):
+        """Reset registry before each test."""
+        StageRegistry._discovered = False
+        StageRegistry._categories.clear()
+        StageRegistry._instances.clear()
+        discover_stages()
+
+    def test_create_pipeline(self):
+        """Pipeline can be created with config."""
+        config = PipelineConfig(source="headlines", display="terminal")
+        pipeline = Pipeline(config=config)
+
+        assert pipeline.config is not None
+        assert pipeline.config.source == "headlines"
+        assert pipeline.config.display == "terminal"
+
+    def test_add_stage(self):
+        """Pipeline.add_stage adds a stage."""
+        pipeline = Pipeline()
+        mock_stage = MagicMock(spec=Stage)
+        mock_stage.name = "test_stage"
+        mock_stage.category = "test"
+
+        pipeline.add_stage("test", mock_stage)
+
+        assert "test" in pipeline.stages
+
+    def test_build_resolves_dependencies(self):
+        """Pipeline.build resolves execution order."""
+        pipeline = Pipeline()
+        mock_source = MagicMock(spec=Stage)
+        mock_source.name = "source"
+        mock_source.category = "source"
+        mock_source.dependencies = set()
+
+        mock_display = MagicMock(spec=Stage)
+        mock_display.name = "display"
+        mock_display.category = "display"
+        mock_display.dependencies = {"source"}
+
+        pipeline.add_stage("source", mock_source)
+        pipeline.add_stage("display", mock_display)
+        pipeline.build()
+
+        assert pipeline._initialized is True
+        assert "source" in pipeline.execution_order
+        assert "display" in pipeline.execution_order
+
+    def test_execute_runs_stages(self):
+        """Pipeline.execute runs all stages in order."""
+        pipeline = Pipeline()
+
+        call_order = []
+
+        mock_source = MagicMock(spec=Stage)
+        mock_source.name = "source"
+        mock_source.category = "source"
+        mock_source.dependencies = set()
+        mock_source.process = lambda data, ctx: call_order.append("source") or "data"
+
+        mock_effect = MagicMock(spec=Stage)
+        mock_effect.name = "effect"
+        mock_effect.category = "effect"
+        mock_effect.dependencies = {"source"}
+        mock_effect.process = lambda data, ctx: call_order.append("effect") or data
+
+        mock_display = MagicMock(spec=Stage)
+        mock_display.name = "display"
+        mock_display.category = "display"
+        mock_display.dependencies = {"effect"}
+        mock_display.process = lambda data, ctx: call_order.append("display") or data
+
+        pipeline.add_stage("source", mock_source)
+        pipeline.add_stage("effect", mock_effect)
+        pipeline.add_stage("display", mock_display)
+        pipeline.build()
+
+        result = pipeline.execute(None)
+
+        assert result.success is True
+        assert call_order == ["source", "effect", "display"]
+
+    def test_execute_handles_stage_failure(self):
+        """Pipeline.execute handles stage failures."""
+        pipeline = Pipeline()
+
+        mock_source = MagicMock(spec=Stage)
+        mock_source.name = "source"
+        mock_source.category = "source"
+        mock_source.dependencies = set()
+        mock_source.process = lambda data, ctx: "data"
+
+        mock_failing = MagicMock(spec=Stage)
+        mock_failing.name = "failing"
+        mock_failing.category = "effect"
+        mock_failing.dependencies = {"source"}
+        mock_failing.optional = False
+        mock_failing.process = lambda data, ctx: (_ for _ in ()).throw(
+            Exception("fail")
+        )
+
+        pipeline.add_stage("source", mock_source)
+        pipeline.add_stage("failing", mock_failing)
+        pipeline.build()
+
+        result = pipeline.execute(None)
+
+        assert result.success is False
+        assert result.error is not None
+
+    def test_optional_stage_failure_continues(self):
+        """Pipeline.execute continues on optional stage failure."""
+        pipeline = Pipeline()
+
+        mock_source = MagicMock(spec=Stage)
+        mock_source.name = "source"
+        mock_source.category = "source"
+        mock_source.dependencies = set()
+        mock_source.process = lambda data, ctx: "data"
+
+        mock_optional = MagicMock(spec=Stage)
+        mock_optional.name = "optional"
+        mock_optional.category = "effect"
+        mock_optional.dependencies = {"source"}
+        mock_optional.optional = True
+        mock_optional.process = lambda data, ctx: (_ for _ in ()).throw(
+            Exception("fail")
+        )
+
+        pipeline.add_stage("source", mock_source)
+        pipeline.add_stage("optional", mock_optional)
+        pipeline.build()
+
+        result = pipeline.execute(None)
+
+        assert result.success is True
+
+
+class TestPipelineContext:
+    """Tests for PipelineContext."""
+
+    def test_init_empty(self):
+        """PipelineContext initializes with empty services and state."""
+        ctx = PipelineContext()
+
+        assert ctx.services == {}
+        assert ctx.state == {}
+
+    def test_init_with_services(self):
+        """PipelineContext accepts initial services."""
+        ctx = PipelineContext(services={"display": MagicMock()})
+
+        assert "display" in ctx.services
+
+    def test_init_with_state(self):
+        """PipelineContext accepts initial state."""
+        ctx = PipelineContext(initial_state={"count": 42})
+
+        assert ctx.get_state("count") == 42
+
+    def test_get_set_services(self):
+        """PipelineContext can get/set services."""
+        ctx = PipelineContext()
+        mock_service = MagicMock()
+
+        ctx.set("test_service", mock_service)
+
+        assert ctx.get("test_service") == mock_service
+
+    def test_get_set_state(self):
+        """PipelineContext can get/set state."""
+        ctx = PipelineContext()
+
+        ctx.set_state("counter", 100)
+
+        assert ctx.get_state("counter") == 100
+
+    def test_lazy_resolver(self):
+        """PipelineContext resolves lazy services."""
+        ctx = PipelineContext()
+
+        config = ctx.get("config")
+        assert config is not None
+
+    def test_has_capability(self):
+        """PipelineContext.has_capability checks for services."""
+        ctx = PipelineContext(services={"display.output": MagicMock()})
+
+        assert ctx.has_capability("display.output") is True
+        assert ctx.has_capability("missing") is False
+
+
+class TestCreateDefaultPipeline:
+    """Tests for create_default_pipeline function."""
+
+    def setup_method(self):
+        """Reset registry before each test."""
+        StageRegistry._discovered = False
+        StageRegistry._categories.clear()
+        StageRegistry._instances.clear()
+        discover_stages()
+
+    def test_create_default_pipeline(self):
+        """create_default_pipeline creates a working pipeline."""
+        pipeline = create_default_pipeline()
+
+        assert pipeline is not None
+        assert "display" in pipeline.stages

tests/test_sixel.py

@@ -0,0 +1,128 @@
+"""
+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_vis_offset.py

@@ -0,0 +1,32 @@
+
+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_e2e.py

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