style: Fix linting errors and organize imports

The old engine/pipeline/core.py file was removed as part of the Sideline/Mainline split.
All imports that referenced engine.pipeline.core have been updated to use engine.pipeline
which re-exports from sideline.pipeline.core.

This ensures consistency and avoids duplicate DataType enum instances.

REPL_USAGE.md

@@ -1,116 +0,0 @@
-# REPL Usage Guide
-
-The REPL (Read-Eval-Print Loop) effect provides an interactive command-line interface for controlling Mainline's pipeline in real-time.
-
-## How to Access the REPL
-
-### Method 1: Using CLI Arguments (Recommended)
-
-Run Mainline with the `repl` effect added to the effects list:
-
-```bash
-# With empty source (for testing)
-python mainline.py --pipeline-source empty --pipeline-effects repl
-
-# With headlines source (requires network)
-python mainline.py --pipeline-source headlines --pipeline-effects repl
-
-# With poetry source
-python mainline.py --pipeline-source poetry --pipeline-effects repl
-```
-
-### Method 2: Using a Preset
-
-Add a preset to your `~/.config/mainline/presets.toml` or `./presets.toml`:
-
-```toml
-[presets.repl]
-description = "Interactive REPL control"
-source = "headlines"
-display = "terminal"
-effects = ["repl"]
-viewport_width = 80
-viewport_height = 24
-```
-
-Then run:
-```bash
-python mainline.py --preset repl
-```
-
-### Method 3: Using Graph Config
-
-Create a TOML file (e.g., `repl_config.toml`):
-
-```toml
-source = "empty"
-display = "terminal"
-effects = ["repl"]
-```
-
-Then run:
-```bash
-python mainline.py --graph-config repl_config.toml
-```
-
-## REPL Commands
-
-Once the REPL is active, you can type commands:
-
-- **help** - Show available commands
-- **status** - Show pipeline status and metrics
-- **effects** - List all effects in the pipeline
-- **effect \<name\> \<on|off\>** - Toggle an effect
-- **param \<effect\> \<param\> \<value\>** - Set effect parameter
-- **pipeline** - Show current pipeline order
-- **clear** - Clear output buffer
-- **quit/exit** - Show exit message (use Ctrl+C to actually exit)
-
-## Keyboard Controls
-
-- **Enter** - Execute command
-- **Up/Down arrows** - Navigate command history
-- **Backspace** - Delete last character
-- **Ctrl+C** - Exit Mainline
-
-## Visual Features
-
-The REPL displays:
-- **HUD header** (top 3 lines): Shows FPS, frame time, command count, and output buffer size
-- **Content area**: Main content from the data source
-- **Separator line**: Visual divider
-- **REPL area**: Output buffer and input prompt
-
-## Example Session
-
-```
-MAINLINE REPL | FPS: 60.0 | 12.5ms
-COMMANDS: 3 | [2/3]
-OUTPUT: 5 lines
-────────────────────────────────────────
-Content from source appears here...
-More content...
-────────────────────────────────────────
-> help
-Available commands:
-  help - Show this help
-  status - Show pipeline status
-  effects - List all effects
-  effect <name> <on|off> - Toggle effect
-  param <effect> <param> <value> - Set parameter
-  pipeline - Show current pipeline order
-  clear - Clear output buffer
-  quit - Show exit message
-> effects
-Pipeline effects:
-  1. repl
-> effect repl off
-Effect 'repl' set to off
-```
-
-## Notes
-
-- The REPL effect needs a content source to overlay on (e.g., headlines, poetry, empty)
-- The REPL uses terminal display with raw input mode
-- Command history is preserved across sessions (up to 50 commands)
-- Pipeline mutations (enabling/disabling effects) are handled automatically

docs/GRAPH_SYSTEM_SUMMARY.md

@@ -1,178 +0,0 @@
-# Graph-Based Pipeline System - Implementation Summary
-
-## Overview
-
-Implemented a graph-based scripting language to replace the verbose `XYZStage` naming convention in Mainline's pipeline architecture. The new system represents pipelines as nodes and connections, providing a more intuitive way to define, configure, and orchestrate pipelines.
-
-## Files Created
-
-### Core Graph System
-- `engine/pipeline/graph.py` - Core graph abstraction (Node, Connection, Graph classes)
-- `engine/pipeline/graph_adapter.py` - Adapter to convert Graph to Pipeline with existing Stage classes
-- `engine/pipeline/graph_toml.py` - TOML-based graph configuration loader
-
-### Tests
-- `tests/test_graph_pipeline.py` - Comprehensive test suite (17 tests, all passing)
-- `examples/graph_dsl_demo.py` - Demo script showing the new DSL
-- `examples/test_graph_integration.py` - Integration test verifying pipeline execution
-- `examples/pipeline_graph.toml` - Example TOML configuration file
-
-### Documentation
-- `docs/graph-dsl.md` - Complete DSL documentation with examples
-- `docs/GRAPH_SYSTEM_SUMMARY.md` - This summary document
-
-## Key Features
-
-### 1. Graph Abstraction
-- **Node Types**: `source`, `camera`, `effect`, `position`, `display`, `render`, `overlay`
-- **Connections**: Directed edges between nodes with automatic dependency resolution
-- **Validation**: Cycle detection and disconnected node warnings
-
-### 2. DSL Syntax Options
-
-#### TOML Configuration
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.5
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> noise -> display"]
-```
-
-#### Python API
-```python
-from engine.pipeline.graph import Graph, NodeType
-from engine.pipeline.graph_adapter import graph_to_pipeline
-
-graph = Graph()
-graph.node("source", NodeType.SOURCE, source="headlines")
-graph.node("camera", NodeType.CAMERA, mode="scroll")
-graph.node("noise", NodeType.EFFECT, effect="noise", intensity=0.5)
-graph.node("display", NodeType.DISPLAY, backend="terminal")
-graph.chain("source", "camera", "noise", "display")
-
-pipeline = graph_to_pipeline(graph)
-```
-
-#### Dictionary/JSON Input
-```python
-from engine.pipeline.graph_adapter import dict_to_pipeline
-
-data = {
-    "nodes": {
-        "source": "headlines",
-        "noise": {"type": "effect", "effect": "noise", "intensity": 0.5},
-        "display": {"type": "display", "backend": "terminal"}
-    },
-    "connections": ["source -> noise -> display"]
-}
-
-pipeline = dict_to_pipeline(data)
-```
-
-### 3. Pipeline Integration
-
-The graph system integrates with the existing pipeline architecture:
-
-- **Auto-injection**: Pipeline automatically injects required stages (camera_update, render, etc.)
-- **Capability Resolution**: Uses existing capability-based dependency system
-- **Type Safety**: Validates data flow between stages (TEXT_BUFFER, SOURCE_ITEMS, etc.)
-- **Backward Compatible**: Works alongside existing preset system
-
-### 4. Node Configuration
-
-| Node Type | Config Options | Example |
-|-----------|----------------|---------|
-| `source` | `source`: "headlines", "poetry", "empty" | `{"type": "source", "source": "headlines"}` |
-| `camera` | `mode`: "scroll", "feed", "horizontal", etc.<br>`speed`: float | `{"type": "camera", "mode": "scroll", "speed": 1.0}` |
-| `effect` | `effect`: effect name<br>`intensity`: 0.0-1.0 | `{"type": "effect", "effect": "noise", "intensity": 0.5}` |
-| `position` | `mode`: "absolute", "relative", "mixed" | `{"type": "position", "mode": "mixed"}` |
-| `display` | `backend`: "terminal", "null", "websocket" | `{"type": "display", "backend": "terminal"}` |
-
-## Implementation Details
-
-### Graph Adapter Logic
-
-1. **Node Mapping**: Converts graph nodes to appropriate Stage classes
-2. **Effect Intensity**: Sets effect intensity globally (consistent with existing architecture)
-3. **Camera Creation**: Maps mode strings to Camera factory methods
-4. **Dependencies**: Effects automatically depend on `render.output`
-5. **Type Flow**: Ensures TEXT_BUFFER flow between render and effects
-
-### Validation
-
-- **Disconnected Nodes**: Warns about nodes without connections
-- **Cycle Detection**: Detects circular dependencies using DFS
-- **Type Validation**: Pipeline validates inlet/outlet type compatibility
-
-## Files Modified
-
-### Core Pipeline
-- `engine/pipeline/controller.py` - Pipeline class (no changes needed, uses existing architecture)
-- `engine/pipeline/graph_adapter.py` - Added effect intensity setting, fixed PositionStage creation
-- `engine/app/pipeline_runner.py` - Added graph config support
-
-### Documentation
-- `AGENTS.md` - Updated with task tracking
-
-## Test Results
-
-```
-17 tests passed in 0.23s
-- Graph creation and manipulation
-- Connection handling and validation
-- TOML loading and parsing
-- Pipeline conversion and execution
-- Effect intensity configuration
-- Camera mode mapping
-- Positioning mode support
-```
-
-## Usage Examples
-
-### Running with Graph Config
-```bash
-python -c "
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.graph_toml import load_pipeline_from_toml
-
-discover_plugins()
-pipeline = load_pipeline_from_toml('examples/pipeline_graph.toml')
-"
-```
-
-### Integration with Pipeline Runner
-```bash
-# The pipeline runner now supports graph configs
-# (Implementation in progress)
-```
-
-## Benefits
-
-1. **Simplified Configuration**: No need to manually create Stage instances
-2. **Visual Representation**: Graph structure is easier to understand than class hierarchy
-3. **Automatic Dependency Resolution**: Pipeline handles stage ordering automatically
-4. **Flexible Composition**: Easy to add/remove/modify pipeline stages
-5. **Backward Compatible**: Existing presets and stages continue to work
-
-## Future Enhancements
-
-1. **CLI Integration**: Add `--graph-config` flag to mainline command
-2. **Visual Builder**: Web-based drag-and-drop pipeline editor
-3. **Script Execution**: Support for loops, conditionals, and timing in graph scripts
-4. **Parameter Binding**: Real-time sensor-to-parameter bindings in graph config
-5. **Pipeline Inspection**: Visual DAG representation with metrics

docs/SUMMARY.md

@@ -1,30 +0,0 @@
-# Mainline Documentation Summary
-
-## Core Architecture
-- [Pipeline Architecture](PIPELINE.md) - Pipeline stages, capability resolution, DAG execution
-- [Graph-Based DSL](graph-dsl.md) - New graph abstraction for pipeline configuration
-
-## Pipeline Configuration
-- [Hybrid Config](hybrid-config.md) - **Recommended**: Preset simplicity + graph flexibility
-- [Graph DSL](graph-dsl.md) - Verbose node-based graph definition
-- [Presets Usage](presets-usage.md) - Creating and using pipeline presets
-
-## Feature Documentation
-- [Positioning Analysis](positioning-analysis.md) - Positioning modes and tradeoffs
-- [Pipeline Introspection](pipeline_introspection.md) - Live pipeline visualization
-
-## Implementation Details
-- [Graph System Summary](GRAPH_SYSTEM_SUMMARY.md) - Complete implementation overview
-
-## Quick Start
-
-**Recommended: Hybrid Configuration**
-```toml
-[pipeline]
-source = "headlines"
-camera = { mode = "scroll" }
-effects = [{ name = "noise", intensity = 0.3 }]
-display = { backend = "terminal" }
-```
-
-See `docs/hybrid-config.md` for details.

docs/analysis_graph_dsl_duplicative.md

@@ -1,236 +0,0 @@
-# Analysis: Graph DSL Duplicative Issue
-
-## Executive Summary
-
-The current Graph DSL implementation in Mainline is **duplicative** because:
-
-1. **Node definitions are repeated**: Every node requires a full `[nodes.name]` block with `type` and specific config, even when the type can often be inferred
-2. **Connections are separate**: The `[connections]` list must manually reference node names that were just defined
-3. **Type specification is redundant**: The `type = "effect"` is always the same as the key name prefix
-4. **No implicit connections**: Even linear pipelines require explicit connection strings
-
-This creates significant verbosity compared to the preset system.
-
----
-
-## What Makes the Script Feel "Duplicative"
-
-### 1. Type Specification Redundancy
-
-```toml
-[nodes.noise]
-type = "effect"        # ← Redundant: already know it's an effect from context
-effect = "noise"
-intensity = 0.3
-```
-
-**Why it's redundant:**
-- The `[nodes.noise]` section name suggests it's a custom node
-- The `effect = "noise"` key implies it's an effect type
-- The parser could infer the type from the presence of `effect` key
-
-### 2. Connection String Redundancy
-
-```toml
-[connections]
-list = ["source -> camera -> noise -> fade -> glitch -> firehose -> display"]
-```
-
-**Why it's redundant:**
-- All node names were already defined in individual blocks above
-- For linear pipelines, the natural flow is obvious
-- The connection order matches the definition order
-
-### 3. Verbosity Comparison
-
-**Preset System (10 lines):**
-```toml
-[presets.upstream-default]
-source = "headlines"
-display = "terminal"
-camera = "scroll"
-effects = ["noise", "fade", "glitch", "firehose"]
-camera_speed = 1.0
-viewport_width = 80
-viewport_height = 24
-```
-
-**Graph DSL (39 lines):**
-- 3.9x more lines for the same pipeline
-- Each effect requires 4 lines instead of 1 line in preset system
-- Connection string repeats all node names
-
----
-
-## Syntactic Sugar Options
-
-### Option 1: Type Inference (Immediate)
-
-**Current:**
-```toml
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-```
-
-**Proposed:**
-```toml
-[nodes.noise]
-effect = "noise"        # Type inferred from 'effect' key
-intensity = 0.3
-```
-
-**Implementation:** Modify `graph_toml.py` to infer node type from keys:
-- `effect` key → type = "effect"
-- `backend` key → type = "display"
-- `source` key → type = "source"
-- `mode` key → type = "camera"
-
-### Option 2: Implicit Linear Connections
-
-**Current:**
-```toml
-[connections]
-list = ["source -> camera -> noise -> fade -> display"]
-```
-
-**Proposed:**
-```toml
-[connections]
-implicit = true  # Auto-connect all nodes in definition order
-```
-
-**Implementation:** If `implicit = true`, automatically create connections between consecutive nodes.
-
-### Option 3: Inline Node Definitions
-
-**Current:**
-```toml
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.fade]
-type = "effect"
-effect = "fade"
-intensity = 0.5
-```
-
-**Proposed:**
-```toml
-[graph]
-nodes = [
-    { name = "source", source = "headlines" },
-    { name = "noise", effect = "noise", intensity = 0.3 },
-    { name = "fade", effect = "fade", intensity = 0.5 },
-    { name = "display", backend = "terminal" }
-]
-connections = ["source -> noise -> fade -> display"]
-```
-
-### Option 4: Hybrid Preset-Graph System
-
-```toml
-[presets.custom]
-source = "headlines"
-display = "terminal"
-camera = "scroll"
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5 }
-]
-```
-
----
-
-## Comparative Analysis: Other Systems
-
-### GitHub Actions
-```yaml
-steps:
-  - uses: actions/checkout@v2
-  - uses: actions/setup-node@v2
-  - run: npm install
-```
-- Steps in order, no explicit connection syntax
-- Type inference from `uses` or `run`
-
-### Apache Airflow
-```python
-task1 = PythonOperator(...)
-task2 = PythonOperator(...)
-task1 >> task2  # Minimal connection syntax
-```
-
-### Jenkins Pipeline
-```groovy
-stages {
-    stage('Build') { steps { sh 'make' } }
-    stage('Test') { steps { sh 'make test' } }
-}
-```
-- Implicit sequential execution
-
----
-
-## Recommended Improvements
-
-### Immediate (Backward Compatible)
-
-1. **Type Inference** - Make `type` field optional
-2. **Implicit Connections** - Add `implicit = true` option
-3. **Array Format** - Support `nodes = ["a", "b", "c"]` format
-
-### Example: Improved Configuration
-
-**Current (39 lines):**
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-speed = 1.0
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> noise -> display"]
-```
-
-**Improved (13 lines, 67% reduction):**
-```toml
-[graph]
-nodes = [
-    { name = "source", source = "headlines" },
-    { name = "camera", mode = "scroll", speed = 1.0 },
-    { name = "noise", effect = "noise", intensity = 0.3 },
-    { name = "display", backend = "terminal" }
-]
-
-[connections]
-implicit = true  # Auto-connects: source -> camera -> noise -> display
-```
-
----
-
-## Conclusion
-
-The Graph DSL's duplicative nature stems from:
-1. **Explicit type specification** when it could be inferred
-2. **Separate connection definitions** that repeat node names
-3. **Verbose node definitions** for simple cases
-4. **Lack of implicit defaults** for linear pipelines
-
-The recommended improvements focus on **type inference** and **implicit connections** as immediate wins that reduce verbosity by 50%+ while maintaining full flexibility for complex pipelines.

docs/graph-dsl.md

@@ -1,210 +0,0 @@
-# Graph-Based Pipeline DSL
-
-This document describes the new graph-based DSL for defining pipelines in Mainline.
-
-## Overview
-
-The graph DSL represents pipelines as nodes and connections, replacing the verbose `XYZStage` naming convention with a more intuitive graph abstraction.
-
-## TOML Syntax
-
-### Basic Pipeline
-
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> display"]
-```
-
-### With Effects
-
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.5
-
-[nodes.fade]
-type = "effect"
-effect = "fade"
-intensity = 0.8
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> noise -> fade -> display"]
-```
-
-### With Positioning
-
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.position]
-type = "position"
-mode = "mixed"
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> position -> display"]
-```
-
-## Python API
-
-### Basic Construction
-
-```python
-from engine.pipeline.graph import Graph, NodeType
-
-graph = Graph()
-graph.node("source", NodeType.SOURCE, source="headlines")
-graph.node("camera", NodeType.CAMERA, mode="scroll")
-graph.node("display", NodeType.DISPLAY, backend="terminal")
-graph.chain("source", "camera", "display")
-
-pipeline = graph_to_pipeline(graph)
-```
-
-### With Effects
-
-```python
-from engine.pipeline.graph import Graph, NodeType
-
-graph = Graph()
-graph.node("source", NodeType.SOURCE, source="headlines")
-graph.node("noise", NodeType.EFFECT, effect="noise", intensity=0.5)
-graph.node("fade", NodeType.EFFECT, effect="fade", intensity=0.8)
-graph.node("display", NodeType.DISPLAY, backend="terminal")
-graph.chain("source", "noise", "fade", "display")
-
-pipeline = graph_to_pipeline(graph)
-```
-
-### Dictionary/JSON Input
-
-```python
-from engine.pipeline.graph_adapter import dict_to_pipeline
-
-data = {
-    "nodes": {
-        "source": "headlines",
-        "noise": {"type": "effect", "effect": "noise", "intensity": 0.5},
-        "display": {"type": "display", "backend": "terminal"}
-    },
-    "connections": ["source -> noise -> display"]
-}
-
-pipeline = dict_to_pipeline(data)
-```
-
-## CLI Usage
-
-### Using Graph Config File
-
-```bash
-mainline --graph-config pipeline.toml
-```
-
-### Inline Graph Definition
-
-```bash
-mainline --graph 'source:headlines -> noise:noise:0.5 -> display:terminal'
-```
-
-### With Preset Override
-
-```bash
-mainline --preset demo --graph-modify 'add:noise:0.5 after:source'
-```
-
-## Node Types
-
-| Type | Description | Config Options |
-|------|-------------|----------------|
-| `source` | Data source | `source`: "headlines", "poetry", "empty", etc. |
-| `camera` | Viewport camera | `mode`: "scroll", "feed", "horizontal", etc. `speed`: float |
-| `effect` | Visual effect | `effect`: effect name, `intensity`: 0.0-1.0 |
-| `position` | Positioning mode | `mode`: "absolute", "relative", "mixed" |
-| `display` | Output backend | `backend`: "terminal", "null", "websocket", etc. |
-| `render` | Text rendering | (auto-injected) |
-| `overlay` | Message overlay | (auto-injected) |
-
-## Advanced Features
-
-### Conditional Connections
-
-```toml
-[connections]
-list = ["source -> camera -> display"]
-# Effects can be conditionally enabled/disabled
-```
-
-### Parameter Binding
-
-```toml
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 1.0
-# intensity can be bound to sensor values at runtime
-```
-
-### Pipeline Inspection
-
-```toml
-[nodes.inspect]
-type = "pipeline-inspect"
-# Renders live pipeline visualization
-```
-
-## Comparison with Stage-Based Approach
-
-### Old (Stage-Based)
-
-```python
-pipeline = Pipeline()
-pipeline.add_stage("source", DataSourceStage(HeadlinesDataSource()))
-pipeline.add_stage("camera", CameraStage(Camera.scroll()))
-pipeline.add_stage("render", FontStage())
-pipeline.add_stage("noise", EffectPluginStage(noise_effect))
-pipeline.add_stage("display", DisplayStage(terminal_display))
-```
-
-### New (Graph-Based)
-
-```python
-graph = Graph()
-graph.node("source", NodeType.SOURCE, source="headlines")
-graph.node("camera", NodeType.CAMERA, mode="scroll")
-graph.node("noise", NodeType.EFFECT, effect="noise")
-graph.node("display", NodeType.DISPLAY, backend="terminal")
-graph.chain("source", "camera", "noise", "display")
-pipeline = graph_to_pipeline(graph)
-```
-
-The graph system automatically:
-- Inserts the render stage between camera and effects
-- Handles capability-based dependency resolution
-- Auto-injects required stages (camera_update, render, etc.)

docs/hybrid-config.md

@@ -1,267 +0,0 @@
-# Hybrid Preset-Graph Configuration
-
-The hybrid configuration format combines the simplicity of presets with the flexibility of graphs, providing a concise way to define pipelines.
-
-## Overview
-
-The hybrid format uses **70% less space** than the verbose node-based DSL while providing the same functionality.
-
-### Comparison
-
-**Verbose Node DSL (39 lines):**
-```toml
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-speed = 1.0
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> noise -> display"]
-```
-
-**Hybrid Config (20 lines):**
-```toml
-[pipeline]
-source = "headlines"
-
-camera = { mode = "scroll", speed = 1.0 }
-
-effects = [
-    { name = "noise", intensity = 0.3 }
-]
-
-display = { backend = "terminal" }
-```
-
-## Syntax
-
-### Basic Structure
-
-```toml
-[pipeline]
-source = "headlines"
-camera = { mode = "scroll", speed = 1.0 }
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5 }
-]
-display = { backend = "terminal", positioning = "mixed" }
-```
-
-### Configuration Options
-
-#### Source
-```toml
-source = "headlines"  # Built-in source: headlines, poetry, empty, etc.
-```
-
-#### Camera
-```toml
-# Inline object notation
-camera = { mode = "scroll", speed = 1.0 }
-
-# Or shorthand (uses defaults)
-camera = "scroll"
-```
-
-Available modes: `scroll`, `feed`, `horizontal`, `omni`, `floating`, `bounce`, `radial`
-
-#### Effects
-```toml
-# Array of effect configurations
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5, enabled = true }
-]
-
-# Or shorthand (uses defaults)
-effects = ["noise", "fade"]
-```
-
-Available effects: `noise`, `fade`, `glitch`, `firehose`, `tint`, `hud`, etc.
-
-#### Display
-```toml
-# Inline object notation
-display = { backend = "terminal", positioning = "mixed" }
-
-# Or shorthand
-display = "terminal"
-```
-
-Available backends: `terminal`, `null`, `websocket`, `pygame`
-
-### Viewport Settings
-```toml
-[pipeline]
-viewport_width = 80
-viewport_height = 24
-```
-
-## Usage Examples
-
-### Minimal Configuration
-```toml
-[pipeline]
-source = "headlines"
-display = "terminal"
-```
-
-### With Camera and Effects
-```toml
-[pipeline]
-source = "headlines"
-camera = { mode = "scroll", speed = 1.0 }
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5 }
-]
-display = { backend = "terminal", positioning = "mixed" }
-```
-
-### Full Configuration
-```toml
-[pipeline]
-source = "poetry"
-camera = { mode = "scroll", speed = 1.5 }
-effects = [
-    { name = "noise", intensity = 0.2 },
-    { name = "fade", intensity = 0.4 },
-    { name = "glitch", intensity = 0.3 },
-    { name = "firehose", intensity = 0.5 }
-]
-display = { backend = "terminal", positioning = "mixed" }
-viewport_width = 100
-viewport_height = 30
-```
-
-## Python API
-
-### Loading from TOML File
-```python
-from engine.pipeline.hybrid_config import load_hybrid_config
-
-config = load_hybrid_config("examples/hybrid_config.toml")
-pipeline = config.to_pipeline()
-```
-
-### Creating Config Programmatically
-```python
-from engine.pipeline.hybrid_config import (
-    PipelineConfig,
-    CameraConfig,
-    EffectConfig,
-    DisplayConfig,
-)
-
-config = PipelineConfig(
-    source="headlines",
-    camera=CameraConfig(mode="scroll", speed=1.0),
-    effects=[
-        EffectConfig(name="noise", intensity=0.3),
-        EffectConfig(name="fade", intensity=0.5),
-    ],
-    display=DisplayConfig(backend="terminal", positioning="mixed"),
-)
-
-pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-```
-
-### Converting to Graph
-```python
-from engine.pipeline.hybrid_config import PipelineConfig
-
-config = PipelineConfig(source="headlines", display={"backend": "terminal"})
-graph = config.to_graph()  # Returns Graph object for further manipulation
-```
-
-## How It Works
-
-The hybrid config system:
-
-1. **Parses TOML** into a `PipelineConfig` dataclass
-2. **Converts to Graph** internally using automatic linear connections
-3. **Reuses existing adapter** to convert graph to pipeline stages
-4. **Maintains backward compatibility** with verbose node DSL
-
-### Automatic Connection Logic
-
-The system automatically creates linear connections:
-```
-source -> camera -> effects[0] -> effects[1] -> ... -> display
-```
-
-This covers 90% of use cases. For complex DAGs, use the verbose node DSL.
-
-## Migration Guide
-
-### From Presets
-The hybrid format is very similar to presets:
-
-**Preset:**
-```toml
-[presets.custom]
-source = "headlines"
-effects = ["noise", "fade"]
-display = "terminal"
-```
-
-**Hybrid:**
-```toml
-[pipeline]
-source = "headlines"
-effects = ["noise", "fade"]
-display = "terminal"
-```
-
-The main difference is using `[pipeline]` instead of `[presets.custom]`.
-
-### From Verbose Node DSL
-**Old (39 lines):**
-```toml
-[nodes.source] type = "source" source = "headlines"
-[nodes.camera] type = "camera" mode = "scroll"
-[nodes.noise] type = "effect" effect = "noise" intensity = 0.3
-[nodes.display] type = "display" backend = "terminal"
-[connections] list = ["source -> camera -> noise -> display"]
-```
-
-**New (14 lines):**
-```toml
-[pipeline]
-source = "headlines"
-camera = { mode = "scroll" }
-effects = [{ name = "noise", intensity = 0.3 }]
-display = { backend = "terminal" }
-```
-
-## When to Use Each Format
-
-| Format | Use When | Lines (example) |
-|--------|----------|-----------------|
-| **Preset** | Simple configurations, no effect intensity tuning | 10 |
-| **Hybrid** | Most common use cases, need intensity tuning | 20 |
-| **Verbose Node DSL** | Complex DAGs, branching, custom connections | 39 |
-| **Python API** | Dynamic configuration, programmatic generation | N/A |
-
-## Examples
-
-See `examples/hybrid_config.toml` for a complete working example.
-
-Run the demo:
-```bash
-python examples/hybrid_visualization.py
-```

docs/presets-usage.md

@@ -1,219 +0,0 @@
-# Presets Usage Guide
-
-## Overview
-
-The sideline branch introduces a new preset system that allows you to easily configure different pipeline behaviors. This guide explains the available presets and how to use them.
-
-## Available Presets
-
-### 1. upstream-default
-
-**Purpose:** Matches the default upstream Mainline operation for comparison.
-
-**Configuration:**
-- **Display:** Terminal (not pygame)
-- **Camera:** Scroll mode
-- **Effects:** noise, fade, glitch, firehose (classic four effects)
-- **Positioning:** Mixed mode
-- **Message Overlay:** Disabled (matches upstream)
-
-**Usage:**
-```bash
-python -m mainline --preset upstream-default --display terminal
-```
-
-**Best for:**
-- Comparing sideline vs upstream behavior
-- Legacy terminal-based operation
-- Baseline performance testing
-
-### 2. demo
-
-**Purpose:** Showcases sideline features including hotswappable effects and sensors.
-
-**Configuration:**
-- **Display:** Pygame (graphical display)
-- **Camera:** Scroll mode
-- **Effects:** noise, fade, glitch, firehose, hud (with visual feedback)
-- **Positioning:** Mixed mode
-- **Message Overlay:** Enabled (with ntfy integration)
-
-**Features:**
-- **Hotswappable Effects:** Effects can be toggled and modified at runtime
-- **LFO Sensor Modulation:** Oscillator sensor provides smooth intensity modulation
-- **Visual Feedback:** HUD effect shows current effect state and pipeline info
-- **Mixed Positioning:** Optimal balance of performance and control
-
-**Usage:**
-```bash
-python -m mainline --preset demo --display pygame
-```
-
-**Best for:**
-- Exploring sideline capabilities
-- Testing effect hotswapping
-- Demonstrating sensor integration
-
-### 3. demo-base / demo-pygame
-
-**Purpose:** Base presets for custom effect hotswapping experiments.
-
-**Configuration:**
-- **Display:** Terminal (base) or Pygame (pygame variant)
-- **Camera:** Feed mode
-- **Effects:** Empty (add your own)
-- **Positioning:** Mixed mode
-
-**Usage:**
-```bash
-python -m mainline --preset demo-pygame --display pygame
-```
-
-### 4. Other Presets
-
-- `poetry`: Poetry feed with subtle effects
-- `firehose`: High-speed firehose mode
-- `ui`: Interactive UI mode with control panel
-- `fixture`: Uses cached headline fixtures
-- `websocket`: WebSocket display mode
-
-## Positioning Modes
-
-The `--positioning` flag controls how text is positioned in the terminal:
-
-```bash
-# Relative positioning (newlines, good for scrolling)
-python -m mainline --positioning relative --preset demo
-
-# Absolute positioning (cursor codes, good for overlays)
-python -m mainline --positioning absolute --preset demo
-
-# Mixed positioning (default, optimal balance)
-python -m mainline --positioning mixed --preset demo
-```
-
-## Pipeline Stages
-
-### Upstream-Default Pipeline
-
-1. **Source Stage:** Headlines data source
-2. **Viewport Filter:** Filters items to viewport height
-3. **Font Stage:** Renders headlines as block characters
-4. **Camera Stages:** Scrolling animation
-5. **Effect Stages:** noise, fade, glitch, firehose
-6. **Display Stage:** Terminal output
-
-### Demo Pipeline
-
-1. **Source Stage:** Headlines data source
-2. **Viewport Filter:** Filters items to viewport height
-3. **Font Stage:** Renders headlines as block characters
-4. **Camera Stages:** Scrolling animation
-5. **Effect Stages:** noise, fade, glitch, firehose, hud
-6. **Message Overlay:** Ntfy message integration
-7. **Display Stage:** Pygame output
-
-## Command-Line Examples
-
-### Basic Usage
-
-```bash
-# Run upstream-default preset
-python -m mainline --preset upstream-default --display terminal
-
-# Run demo preset
-python -m mainline --preset demo --display pygame
-
-# Run with custom positioning
-python -m mainline --preset demo --display pygame --positioning absolute
-```
-
-### Comparison Testing
-
-```bash
-# Capture upstream output
-python -m mainline --preset upstream-default --display null --viewport 80x24
-
-# Capture sideline output
-python -m mainline --preset demo --display null --viewport 80x24
-```
-
-### Hotswapping Effects
-
-The demo preset supports hotswapping effects at runtime:
-- Use the WebSocket display to send commands
-- Toggle effects on/off
-- Adjust intensity values in real-time
-
-## Configuration Files
-
-### Built-in Presets
-
-Location: `engine/pipeline/presets.py` (Python code)
-
-### User Presets
-
-Location: `~/.config/mainline/presets.toml` or `./presets.toml`
-
-Example user preset:
-```toml
-[presets.my-custom-preset]
-description = "My custom configuration"
-source = "headlines"
-display = "terminal"
-camera = "scroll"
-effects = ["noise", "fade"]
-positioning = "mixed"
-viewport_width = 100
-viewport_height = 30
-```
-
-## Sensor Configuration
-
-### Oscillator Sensor (LFO)
-
-The oscillator sensor provides Low Frequency Oscillator modulation:
-
-```toml
-[sensors.oscillator]
-enabled = true
-waveform = "sine"  # sine, square, triangle, sawtooth
-frequency = 0.05   # 20 second cycle (gentle)
-amplitude = 0.5    # 50% modulation
-```
-
-### Effect Configuration
-
-Effect intensities can be configured with initial values:
-
-```toml
-[effect_configs.noise]
-enabled = true
-intensity = 1.0
-
-[effect_configs.fade]
-enabled = true
-intensity = 1.0
-
-[effect_configs.glitch]
-enabled = true
-intensity = 0.5
-```
-
-## Troubleshooting
-
-### No Display Output
-
-- Check if display backend is available (pygame, terminal, etc.)
-- Use `--display null` for headless testing
-
-### Effects Not Modulating
-
-- Ensure sensor is enabled in presets.toml
-- Check effect intensity values in configuration
-
-### Performance Issues
-
-- Use `--positioning relative` for large buffers
-- Reduce viewport height for better performance
-- Use null display for testing without rendering

engine/app/main.py

@@ -9,22 +9,28 @@ from engine import config
 from engine.display import BorderMode, DisplayRegistry
 from engine.effects import get_registry
 from engine.fetch import fetch_all, fetch_all_fast, fetch_poetry, load_cache, save_cache
-from engine.pipeline import (
+
+# Import from engine (Mainline-specific)
+from engine.pipeline import list_presets
+
+# Import from engine (Mainline-specific)
+from engine.pipeline.ui import UIConfig, UIPanel
+from engine.pipeline.validation import validate_pipeline_config
+
+# Import from sideline (the framework)
+from sideline.pipeline import (
     Pipeline,
     PipelineConfig,
     PipelineContext,
-    list_presets,
 )
-from engine.pipeline.adapters import (
+from sideline.pipeline.adapters import (
     CameraStage,
     DataSourceStage,
     EffectPluginStage,
     create_stage_from_display,
     create_stage_from_effect,
 )
-from engine.pipeline.params import PipelineParams
-from engine.pipeline.ui import UIConfig, UIPanel
-from engine.pipeline.validation import validate_pipeline_config
+from sideline.pipeline.params import PipelineParams
 
 try:
     from engine.display.backends.websocket import WebSocketDisplay
@@ -34,87 +40,39 @@ except ImportError:
 from .pipeline_runner import run_pipeline_mode
 
 
-def _handle_pipeline_mutation(pipeline: Pipeline, command: dict) -> bool:
-    """Handle pipeline mutation commands from REPL or other external control.
+def _register_mainline_stages():
+    """Register Mainline-specific stage components with Sideline.
 
-    Args:
-        pipeline: The pipeline to mutate
-        command: Command dictionary with 'action' and other parameters
-
-    Returns:
-        True if command was successfully handled, False otherwise
+    This should be called early in application startup to ensure
+    all Mainline stages are available for pipeline construction.
     """
-    action = command.get("action")
+    try:
+        from sideline.pipeline import StageRegistry
 
-    if action == "add_stage":
-        print(f"  [Pipeline] add_stage command received: {command}")
-        return True
+        # Method 1: Explicit registration via engine.plugins
+        try:
+            from engine.plugins import register_stages
 
-    elif action == "remove_stage":
-        stage_name = command.get("stage")
-        if stage_name:
-            result = pipeline.remove_stage(stage_name)
-            print(f"  [Pipeline] Removed stage '{stage_name}': {result is not None}")
-            return result is not None
+            register_stages(StageRegistry)
+        except ImportError as e:
+            print(f"Warning: Failed to register Mainline stages: {e}")
 
-    elif action == "replace_stage":
-        stage_name = command.get("stage")
-        print(f"  [Pipeline] replace_stage command received: {command}")
-        return True
+        # Method 2: Register via plugin module (for entry point discovery)
+        StageRegistry.register_plugin_module("engine.plugins")
 
-    elif action == "swap_stages":
-        stage1 = command.get("stage1")
-        stage2 = command.get("stage2")
-        if stage1 and stage2:
-            result = pipeline.swap_stages(stage1, stage2)
-            print(f"  [Pipeline] Swapped stages '{stage1}' and '{stage2}': {result}")
-            return result
-
-    elif action == "move_stage":
-        stage_name = command.get("stage")
-        after = command.get("after")
-        before = command.get("before")
-        if stage_name:
-            result = pipeline.move_stage(stage_name, after, before)
-            print(f"  [Pipeline] Moved stage '{stage_name}': {result}")
-            return result
-
-    elif action == "enable_stage":
-        stage_name = command.get("stage")
-        if stage_name:
-            result = pipeline.enable_stage(stage_name)
-            print(f"  [Pipeline] Enabled stage '{stage_name}': {result}")
-            return result
-
-    elif action == "disable_stage":
-        stage_name = command.get("stage")
-        if stage_name:
-            result = pipeline.disable_stage(stage_name)
-            print(f"  [Pipeline] Disabled stage '{stage_name}': {result}")
-            return result
-
-    elif action == "cleanup_stage":
-        stage_name = command.get("stage")
-        if stage_name:
-            pipeline.cleanup_stage(stage_name)
-            print(f"  [Pipeline] Cleaned up stage '{stage_name}'")
-            return True
-
-    elif action == "can_hot_swap":
-        stage_name = command.get("stage")
-        if stage_name:
-            can_swap = pipeline.can_hot_swap(stage_name)
-            print(f"  [Pipeline] Can hot-swap '{stage_name}': {can_swap}")
-            return True
-
-    return False
+        print("Mainline stage components registered successfully")
+    except Exception as e:
+        print(f"Warning: Stage registration failed: {e}")
 
 
 def main():
     """Main entry point - all modes now use presets or CLI construction."""
+    # Register Mainline stages with Sideline
+    _register_mainline_stages()
+
     if config.PIPELINE_DIAGRAM:
         try:
-            from engine.pipeline import generate_pipeline_diagram
+            from sideline.pipeline import generate_pipeline_diagram
         except ImportError:
             print("Error: pipeline diagram not available")
             return
@@ -467,21 +425,6 @@ def run_pipeline_mode_direct():
                     except Exception:
                         pass
 
-    # Check for REPL effect in pipeline
-    repl_effect = None
-    for stage in pipeline.stages.values():
-        if isinstance(stage, EffectPluginStage) and stage._effect.name == "repl":
-            repl_effect = stage._effect
-            print(
-                "  \033[38;5;46mREPL effect detected - Interactive mode enabled\033[0m"
-            )
-            break
-
-    # Enable raw mode for REPL if present and not already enabled
-    # Also enable for UI border mode (already handled above)
-    if repl_effect and ui_panel is None and hasattr(display, "set_raw_mode"):
-        display.set_raw_mode(True)
-
     # Run pipeline loop
     from engine.display import render_ui_panel
 
@@ -544,37 +487,6 @@ def run_pipeline_mode_direct():
                     except Exception:
                         pass
 
-            # --- REPL Input Handling ---
-            if repl_effect and hasattr(display, "get_input_keys"):
-                # Get keyboard input (non-blocking)
-                keys = display.get_input_keys(timeout=0.0)
-
-                for key in keys:
-                    if key == "ctrl_c":
-                        # Request quit when Ctrl+C is pressed
-                        if hasattr(display, "request_quit"):
-                            display.request_quit()
-                        else:
-                            raise KeyboardInterrupt()
-                    elif key == "return":
-                        # Get command string before processing
-                        cmd_str = repl_effect.state.current_command
-                        if cmd_str:
-                            repl_effect.process_command(cmd_str, ctx)
-                            # Check for pending pipeline mutations
-                            pending = repl_effect.get_pending_command()
-                            if pending:
-                                _handle_pipeline_mutation(pipeline, pending)
-                    elif key == "up":
-                        repl_effect.navigate_history(-1)
-                    elif key == "down":
-                        repl_effect.navigate_history(1)
-                    elif key == "backspace":
-                        repl_effect.backspace()
-                    elif len(key) == 1:
-                        repl_effect.append_to_command(key)
-            # --- End REPL Input Handling ---
-
             # Check for quit request
             if hasattr(display, "is_quit_requested") and display.is_quit_requested():
                 if hasattr(display, "clear_quit_request"):

engine/app/pipeline_runner.py

@@ -104,13 +104,8 @@ def _handle_pipeline_mutation(pipeline: Pipeline, command: dict) -> bool:
     return False
 
 
-def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None):
-    """Run using the new unified pipeline architecture.
-
-    Args:
-        preset_name: Name of the preset to use
-        graph_config: Path to a TOML graph configuration file (optional)
-    """
+def run_pipeline_mode(preset_name: str = "demo"):
+    """Run using the new unified pipeline architecture."""
     import engine.effects.plugins as effects_plugins
     from engine.effects import PerformanceMonitor, set_monitor
 
@@ -122,64 +117,17 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
     monitor = PerformanceMonitor()
     set_monitor(monitor)
 
-    # Check if graph config is provided
-    using_graph_config = graph_config is not None
+    preset = get_preset(preset_name)
+    if not preset:
+        print(f"  \033[38;5;196mUnknown preset: {preset_name}\033[0m")
+        sys.exit(1)
 
-    if using_graph_config:
-        from engine.pipeline.graph_toml import load_pipeline_from_toml
+    print(f"  \033[38;5;245mPreset: {preset.name} - {preset.description}\033[0m")
 
-        print(f"  \033[38;5;245mLoading graph from: {graph_config}\033[0m")
-
-        # Determine viewport size
-        viewport_width = 80
-        viewport_height = 24
-        if "--viewport" in sys.argv:
-            idx = sys.argv.index("--viewport")
-            if idx + 1 < len(sys.argv):
-                vp = sys.argv[idx + 1]
-                try:
-                    viewport_width, viewport_height = map(int, vp.split("x"))
-                except ValueError:
-                    print("Error: Invalid viewport format. Use WxH (e.g., 40x15)")
-                    sys.exit(1)
-
-        # Load pipeline from graph config
-        try:
-            pipeline = load_pipeline_from_toml(
-                graph_config,
-                viewport_width=viewport_width,
-                viewport_height=viewport_height,
-            )
-        except Exception as e:
-            print(f"  \033[38;5;196mError loading graph config: {e}\033[0m")
-            sys.exit(1)
-
-        # Set params for display
-        from engine.pipeline.params import PipelineParams
-
-        params = PipelineParams(
-            viewport_width=viewport_width, viewport_height=viewport_height
-        )
-
-        # Set display name from graph or CLI
-        display_name = "terminal"  # Default for graph mode
-        if "--display" in sys.argv:
-            idx = sys.argv.index("--display")
-            if idx + 1 < len(sys.argv):
-                display_name = sys.argv[idx + 1]
-    else:
-        # Use preset-based pipeline
-        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()
-        # Use preset viewport if available, else default to 80x24
-        params.viewport_width = getattr(preset, "viewport_width", 80)
-        params.viewport_height = getattr(preset, "viewport_height", 24)
+    params = preset.to_params()
+    # Use preset viewport if available, else default to 80x24
+    params.viewport_width = getattr(preset, "viewport_width", 80)
+    params.viewport_height = getattr(preset, "viewport_height", 24)
 
     if "--viewport" in sys.argv:
         idx = sys.argv.index("--viewport")
@@ -248,28 +196,22 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
 
         print(f"  \033[38;5;82mLoaded {len(items)} items\033[0m")
 
-    # CLI --display flag takes priority
+    # CLI --display flag takes priority over preset
     # Check if --display was explicitly provided
+    display_name = preset.display
     display_explicitly_specified = "--display" in sys.argv
-    if not using_graph_config:
-        # Preset mode: use preset display as default
-        display_name = preset.display
-        if display_explicitly_specified:
-            idx = sys.argv.index("--display")
-            if idx + 1 < len(sys.argv):
-                display_name = sys.argv[idx + 1]
-        else:
-            # Warn user that display is falling back to preset default
-            print(
-                f"  \033[38;5;226mWarning: No --display specified, using preset default: {display_name}\033[0m"
-            )
-            print(
-                "  \033[38;5;245mTip: Use --display null for headless mode (useful for testing/capture)\033[0m"
-            )
+    if display_explicitly_specified:
+        idx = sys.argv.index("--display")
+        if idx + 1 < len(sys.argv):
+            display_name = sys.argv[idx + 1]
     else:
-        # Graph mode: display_name already set above
-        if not display_explicitly_specified:
-            print(f"  \033[38;5;245mUsing default display: {display_name}\033[0m")
+        # Warn user that display is falling back to preset default
+        print(
+            f"  \033[38;5;226mWarning: No --display specified, using preset default: {display_name}\033[0m"
+        )
+        print(
+            "  \033[38;5;245mTip: Use --display null for headless mode (useful for testing/capture)\033[0m"
+        )
 
     display = DisplayRegistry.create(display_name)
     if not display and not display_name.startswith("multi"):
@@ -303,123 +245,113 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
 
     effect_registry = get_registry()
 
-    # Only build stages from preset if not using graph config
-    # (graph config already has all stages defined)
-    if not using_graph_config:
-        # Create source stage based on preset source type
-        if preset.source == "pipeline-inspect":
-            from engine.data_sources.pipeline_introspection import (
-                PipelineIntrospectionSource,
-            )
-            from engine.pipeline.adapters import DataSourceStage
+    # Create source stage based on preset source type
+    if preset.source == "pipeline-inspect":
+        from engine.data_sources.pipeline_introspection import (
+            PipelineIntrospectionSource,
+        )
+        from engine.pipeline.adapters import DataSourceStage
 
-            introspection_source = PipelineIntrospectionSource(
-                pipeline=None,  # Will be set after pipeline.build()
-                viewport_width=80,
-                viewport_height=24,
-            )
-            pipeline.add_stage(
-                "source", DataSourceStage(introspection_source, name="pipeline-inspect")
-            )
-        elif preset.source == "empty":
-            from engine.data_sources.sources import EmptyDataSource
-            from engine.pipeline.adapters import DataSourceStage
+        introspection_source = PipelineIntrospectionSource(
+            pipeline=None,  # Will be set after pipeline.build()
+            viewport_width=80,
+            viewport_height=24,
+        )
+        pipeline.add_stage(
+            "source", DataSourceStage(introspection_source, name="pipeline-inspect")
+        )
+    elif preset.source == "empty":
+        from engine.data_sources.sources import EmptyDataSource
+        from engine.pipeline.adapters import DataSourceStage
 
-            empty_source = EmptyDataSource(width=80, height=24)
-            pipeline.add_stage("source", DataSourceStage(empty_source, name="empty"))
-        else:
-            from engine.data_sources.sources import ListDataSource
-            from engine.pipeline.adapters import DataSourceStage
+        empty_source = EmptyDataSource(width=80, height=24)
+        pipeline.add_stage("source", DataSourceStage(empty_source, name="empty"))
+    else:
+        from engine.data_sources.sources import ListDataSource
+        from engine.pipeline.adapters import DataSourceStage
 
-            list_source = ListDataSource(items, name=preset.source)
-            pipeline.add_stage(
-                "source", DataSourceStage(list_source, name=preset.source)
-            )
+        list_source = ListDataSource(items, name=preset.source)
+        pipeline.add_stage("source", DataSourceStage(list_source, name=preset.source))
 
-        # Add camera state update stage if specified in preset (must run before viewport filter)
-        camera = None
-        if preset.camera:
-            from engine.camera import Camera
-            from engine.pipeline.adapters import CameraClockStage, CameraStage
+    # Add camera state update stage if specified in preset (must run before viewport filter)
+    camera = None
+    if preset.camera:
+        from engine.camera import Camera
+        from engine.pipeline.adapters import CameraClockStage, CameraStage
 
-            speed = getattr(preset, "camera_speed", 1.0)
-            if preset.camera == "feed":
-                camera = Camera.feed(speed=speed)
-            elif preset.camera == "scroll":
-                camera = Camera.scroll(speed=speed)
-            elif preset.camera == "vertical":
-                camera = Camera.scroll(speed=speed)  # Backwards compat
-            elif preset.camera == "horizontal":
-                camera = Camera.horizontal(speed=speed)
-            elif preset.camera == "omni":
-                camera = Camera.omni(speed=speed)
-            elif preset.camera == "floating":
-                camera = Camera.floating(speed=speed)
-            elif preset.camera == "bounce":
-                camera = Camera.bounce(speed=speed)
-            elif preset.camera == "radial":
-                camera = Camera.radial(speed=speed)
-            elif preset.camera == "static" or preset.camera == "":
-                # Static camera: no movement, but provides camera_y=0 for viewport filter
-                camera = Camera.scroll(speed=0.0)  # Speed 0 = no movement
-                camera.set_canvas_size(200, 200)
+        speed = getattr(preset, "camera_speed", 1.0)
+        if preset.camera == "feed":
+            camera = Camera.feed(speed=speed)
+        elif preset.camera == "scroll":
+            camera = Camera.scroll(speed=speed)
+        elif preset.camera == "vertical":
+            camera = Camera.scroll(speed=speed)  # Backwards compat
+        elif preset.camera == "horizontal":
+            camera = Camera.horizontal(speed=speed)
+        elif preset.camera == "omni":
+            camera = Camera.omni(speed=speed)
+        elif preset.camera == "floating":
+            camera = Camera.floating(speed=speed)
+        elif preset.camera == "bounce":
+            camera = Camera.bounce(speed=speed)
+        elif preset.camera == "radial":
+            camera = Camera.radial(speed=speed)
+        elif preset.camera == "static" or preset.camera == "":
+            # Static camera: no movement, but provides camera_y=0 for viewport filter
+            camera = Camera.scroll(speed=0.0)  # Speed 0 = no movement
+            camera.set_canvas_size(200, 200)
 
-            if camera:
-                # Add camera update stage to ensure camera_y is available for viewport filter
-                pipeline.add_stage(
-                    "camera_update", CameraClockStage(camera, name="camera-clock")
-                )
-
-    # Only build stages from preset if not using graph config
-    if not using_graph_config:
-        # Add FontStage for headlines/poetry (default for demo)
-        if preset.source in ["headlines", "poetry"]:
-            from engine.pipeline.adapters import FontStage, ViewportFilterStage
-
-            # Add viewport filter to prevent rendering all items
-            pipeline.add_stage(
-                "viewport_filter", ViewportFilterStage(name="viewport-filter")
-            )
-            pipeline.add_stage("font", FontStage(name="font"))
-        else:
-            # Fallback to simple conversion for other sources
-            pipeline.add_stage(
-                "render", SourceItemsToBufferStage(name="items-to-buffer")
-            )
-
-        # Add camera stage if specified in preset (after font/render stage)
         if camera:
-            pipeline.add_stage("camera", CameraStage(camera, name=preset.camera))
-
-        for effect_name in preset.effects:
-            effect = effect_registry.get(effect_name)
-            if effect:
-                pipeline.add_stage(
-                    f"effect_{effect_name}",
-                    create_stage_from_effect(effect, effect_name),
-                )
-
-        # Add message overlay stage if enabled
-        if getattr(preset, "enable_message_overlay", False):
-            from engine import config as engine_config
-            from engine.pipeline.adapters import MessageOverlayConfig
-
-            overlay_config = MessageOverlayConfig(
-                enabled=True,
-                display_secs=engine_config.MESSAGE_DISPLAY_SECS
-                if hasattr(engine_config, "MESSAGE_DISPLAY_SECS")
-                else 30,
-                topic_url=engine_config.NTFY_TOPIC
-                if hasattr(engine_config, "NTFY_TOPIC")
-                else None,
-            )
+            # Add camera update stage to ensure camera_y is available for viewport filter
             pipeline.add_stage(
-                "message_overlay", MessageOverlayStage(config=overlay_config)
+                "camera_update", CameraClockStage(camera, name="camera-clock")
             )
 
-        pipeline.add_stage("display", create_stage_from_display(display, display_name))
+    # Add FontStage for headlines/poetry (default for demo)
+    if preset.source in ["headlines", "poetry"]:
+        from engine.pipeline.adapters import FontStage, ViewportFilterStage
 
-        pipeline.build()
+        # Add viewport filter to prevent rendering all items
+        pipeline.add_stage(
+            "viewport_filter", ViewportFilterStage(name="viewport-filter")
+        )
+        pipeline.add_stage("font", FontStage(name="font"))
+    else:
+        # Fallback to simple conversion for other sources
+        pipeline.add_stage("render", SourceItemsToBufferStage(name="items-to-buffer"))
+
+    # Add camera stage if specified in preset (after font/render stage)
+    if camera:
+        pipeline.add_stage("camera", CameraStage(camera, name=preset.camera))
+
+    for effect_name in preset.effects:
+        effect = effect_registry.get(effect_name)
+        if effect:
+            pipeline.add_stage(
+                f"effect_{effect_name}", create_stage_from_effect(effect, effect_name)
+            )
+
+    # Add message overlay stage if enabled
+    if getattr(preset, "enable_message_overlay", False):
+        from engine import config as engine_config
+        from engine.pipeline.adapters import MessageOverlayConfig
+
+        overlay_config = MessageOverlayConfig(
+            enabled=True,
+            display_secs=engine_config.MESSAGE_DISPLAY_SECS
+            if hasattr(engine_config, "MESSAGE_DISPLAY_SECS")
+            else 30,
+            topic_url=engine_config.NTFY_TOPIC
+            if hasattr(engine_config, "NTFY_TOPIC")
+            else None,
+        )
+        pipeline.add_stage(
+            "message_overlay", MessageOverlayStage(config=overlay_config)
+        )
+
+    pipeline.add_stage("display", create_stage_from_display(display, display_name))
+
+    pipeline.build()
 
     # For pipeline-inspect, set the pipeline after build to avoid circular dependency
     if introspection_source is not None:
@@ -433,16 +365,6 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
     ui_panel = None
     render_ui_panel_in_terminal = False
 
-    # Check for REPL effect in pipeline
-    repl_effect = None
-    for stage in pipeline.stages.values():
-        if isinstance(stage, EffectPluginStage) and stage._effect.name == "repl":
-            repl_effect = stage._effect
-            print(
-                "  \033[38;5;46mREPL effect detected - Interactive mode enabled\033[0m"
-            )
-            break
-
     if need_ui_controller:
         from engine.display import render_ui_panel
 
@@ -458,10 +380,6 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
         if hasattr(display, "set_raw_mode"):
             display.set_raw_mode(True)
 
-    # Enable raw mode for REPL if present and not already enabled
-    elif repl_effect and hasattr(display, "set_raw_mode"):
-        display.set_raw_mode(True)
-
         # Register effect plugin stages from pipeline for UI control
         for stage in pipeline.stages.values():
             if isinstance(stage, EffectPluginStage):
@@ -913,13 +831,7 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
     ctx = pipeline.context
     ctx.params = params
     ctx.set("display", display)
-    # For graph mode, items might not be defined - use empty list if needed
-    if not using_graph_config:
-        ctx.set("items", items)
-    else:
-        # Graph-based pipelines typically use their own data sources
-        # But we can set an empty list for compatibility
-        ctx.set("items", [])
+    ctx.set("items", items)
     ctx.set("pipeline", pipeline)
     ctx.set("pipeline_order", pipeline.execution_order)
     ctx.set("camera_y", 0)
@@ -980,44 +892,6 @@ def run_pipeline_mode(preset_name: str = "demo", graph_config: str | None = None
                     else:
                         display.show(result.data, border=show_border)
 
-            # --- REPL Input Handling ---
-            if repl_effect and hasattr(display, "get_input_keys"):
-                # Get keyboard input (non-blocking)
-                keys = display.get_input_keys(timeout=0.0)
-
-                for key in keys:
-                    if key == "ctrl_c":
-                        # Request quit when Ctrl+C is pressed
-                        if hasattr(display, "request_quit"):
-                            display.request_quit()
-                        else:
-                            raise KeyboardInterrupt()
-                    elif key == "return":
-                        # Get command string before processing
-                        cmd_str = repl_effect.state.current_command
-                        if cmd_str:
-                            repl_effect.process_command(cmd_str, ctx)
-                            # Check for pending pipeline mutations
-                            pending = repl_effect.get_pending_command()
-                            if pending:
-                                _handle_pipeline_mutation(pipeline, pending)
-                                # Broadcast state update if WebSocket is active
-                                if web_control_active and isinstance(
-                                    display, WebSocketDisplay
-                                ):
-                                    state = display._get_state_snapshot()
-                                    if state:
-                                        display.broadcast_state(state)
-                    elif key == "up":
-                        repl_effect.navigate_history(-1)
-                    elif key == "down":
-                        repl_effect.navigate_history(1)
-                    elif key == "backspace":
-                        repl_effect.backspace()
-                    elif len(key) == 1:
-                        repl_effect.append_to_command(key)
-            # --- End REPL Input Handling ---
-
             if hasattr(display, "is_quit_requested") and display.is_quit_requested():
                 if hasattr(display, "clear_quit_request"):
                     display.clear_quit_request()

engine/data_sources/pipeline_introspection.py

@@ -67,13 +67,13 @@ class PipelineIntrospectionSource(DataSource):
 
     @property
     def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.NONE}
 
     @property
     def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.SOURCE_ITEMS}
 

engine/display/backends/terminal.py

@@ -3,10 +3,6 @@ ANSI terminal display backend.
 """
 
 import os
-import select
-import sys
-import termios
-import tty
 
 
 class TerminalDisplay:
@@ -26,9 +22,6 @@ class TerminalDisplay:
         self._frame_period = 1.0 / target_fps if target_fps > 0 else 0
         self._last_frame_time = 0.0
         self._cached_dimensions: tuple[int, int] | None = None
-        self._raw_mode_enabled: bool = False
-        self._original_termios: list = []
-        self._quit_requested: bool = False
 
     def init(self, width: int, height: int, reuse: bool = False) -> None:
         """Initialize display with dimensions.
@@ -157,106 +150,12 @@ class TerminalDisplay:
     def cleanup(self) -> None:
         from engine.terminal import CURSOR_ON
 
-        # Restore normal terminal mode if raw mode was enabled
-        self.set_raw_mode(False)
-
         print(CURSOR_ON, end="", flush=True)
 
     def is_quit_requested(self) -> bool:
         """Check if quit was requested (optional protocol method)."""
-        return self._quit_requested
+        return False
 
     def clear_quit_request(self) -> None:
         """Clear quit request (optional protocol method)."""
-        self._quit_requested = False
-
-    def request_quit(self) -> None:
-        """Request quit (e.g., when Ctrl+C is pressed)."""
-        self._quit_requested = True
-
-    def set_raw_mode(self, enable: bool = True) -> None:
-        """Enable/disable raw terminal mode for input capture.
-
-        When raw mode is enabled:
-        - Keystrokes are read immediately without echo
-        - Special keys (arrows, Ctrl+C, etc.) are captured
-        - Terminal is not in cooked/canonical mode
-
-        Args:
-            enable: True to enable raw mode, False to restore normal mode
-        """
-        try:
-            if enable and not self._raw_mode_enabled:
-                # Save original terminal settings
-                self._original_termios = termios.tcgetattr(sys.stdin)
-                # Set raw mode
-                tty.setraw(sys.stdin.fileno())
-                self._raw_mode_enabled = True
-            elif not enable and self._raw_mode_enabled:
-                # Restore original terminal settings
-                if self._original_termios:
-                    termios.tcsetattr(
-                        sys.stdin, termios.TCSADRAIN, self._original_termios
-                    )
-                self._raw_mode_enabled = False
-        except (termios.error, OSError):
-            # Terminal might not support raw mode (e.g., in tests)
-            pass
-
-    def get_input_keys(self, timeout: float = 0.0) -> list[str]:
-        """Get available keyboard input.
-
-        Reads available keystrokes from stdin. Should be called
-        with raw mode enabled for best results.
-
-        Args:
-            timeout: Maximum time to wait for input (seconds)
-
-        Returns:
-            List of key symbols as strings
-        """
-        keys = []
-
-        try:
-            # Check if input is available
-            if select.select([sys.stdin], [], [], timeout)[0]:
-                char = sys.stdin.read(1)
-
-                if char == "\x1b":  # Escape sequence
-                    # Read next character to determine key
-                    seq = sys.stdin.read(2)
-                    if seq == "[A":
-                        keys.append("up")
-                    elif seq == "[B":
-                        keys.append("down")
-                    elif seq == "[C":
-                        keys.append("right")
-                    elif seq == "[D":
-                        keys.append("left")
-                    else:
-                        # Unknown escape sequence
-                        keys.append("escape")
-                elif char == "\n" or char == "\r":
-                    keys.append("return")
-                elif char == "\t":
-                    keys.append("tab")
-                elif char == " ":
-                    keys.append(" ")
-                elif char == "\x7f" or char == "\x08":  # Backspace or Ctrl+H
-                    keys.append("backspace")
-                elif char == "\x03":  # Ctrl+C
-                    keys.append("ctrl_c")
-                elif char == "\x04":  # Ctrl+D
-                    keys.append("ctrl_d")
-                elif char == "\x1b":  # Escape
-                    keys.append("escape")
-                elif char.isprintable():
-                    keys.append(char)
-        except OSError:
-            pass
-
-        return keys
-
-    def is_raw_mode_enabled(self) -> bool:
-        """Check if raw mode is currently enabled."""
-        return self._raw_mode_enabled
+        pass

engine/effects/plugins/repl.py

@@ -1,410 +0,0 @@
-"""REPL Effect Plugin
-
-A HUD-style command-line interface for interactive pipeline control.
-
-This effect provides a Read-Eval-Print Loop (REPL) that allows users to:
-- View pipeline status and metrics
-- Toggle effects on/off
-- Adjust effect parameters in real-time
-- Inspect pipeline configuration
-- Execute commands for pipeline manipulation
-
-Usage:
-    Add 'repl' to the effects list in your configuration.
-
-Commands:
-    help - Show available commands
-    status - Show pipeline status
-    effects - List all effects
-    effect <name> <on|off> - Toggle an effect
-    param <effect> <param> <value> - Set effect parameter
-    pipeline - Show current pipeline order
-    clear - Clear output buffer
-    quit - Exit REPL
-
-Keyboard:
-    Enter - Execute command
-    Up/Down - Navigate command history
-    Tab - Auto-complete (if implemented)
-    Ctrl+C - Clear current input
-"""
-
-from dataclasses import dataclass, field
-
-from engine.effects.types import (
-    EffectConfig,
-    EffectContext,
-    EffectPlugin,
-    PartialUpdate,
-)
-
-
-@dataclass
-class REPLState:
-    """State of the REPL interface."""
-
-    command_history: list[str] = field(default_factory=list)
-    current_command: str = ""
-    history_index: int = -1
-    output_buffer: list[str] = field(default_factory=list)
-    max_history: int = 50
-    max_output_lines: int = 20
-
-
-class ReplEffect(EffectPlugin):
-    """REPL effect with HUD-style overlay for interactive pipeline control."""
-
-    name = "repl"
-    config = EffectConfig(
-        enabled=True,
-        intensity=1.0,
-        params={
-            "display_height": 8,  # Height of REPL area in lines
-            "show_hud": True,  # Show HUD header lines
-        },
-    )
-    supports_partial_updates = True
-
-    def __init__(self):
-        super().__init__()
-        self.state = REPLState()
-        self._last_metrics: dict | None = None
-
-    def process_partial(
-        self, buf: list[str], ctx: EffectContext, partial: PartialUpdate
-    ) -> list[str]:
-        """Handle partial updates efficiently."""
-        if partial.full_buffer:
-            return self.process(buf, ctx)
-        # Always process REPL since it needs to stay visible
-        return self.process(buf, ctx)
-
-    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
-        """Render buffer with REPL overlay."""
-        # Get display dimensions from context
-        height = ctx.terminal_height if hasattr(ctx, "terminal_height") else len(buf)
-        width = ctx.terminal_width if hasattr(ctx, "terminal_width") else 80
-
-        # Calculate areas
-        repl_height = self.config.params.get("display_height", 8)
-        show_hud = self.config.params.get("show_hud", True)
-
-        # Reserve space for REPL at bottom
-        # HUD uses top 3 lines if enabled
-        content_height = max(1, height - repl_height)
-
-        # Build output
-        output = []
-
-        # Add content (truncated or padded)
-        for i in range(content_height):
-            if i < len(buf):
-                output.append(buf[i][:width])
-            else:
-                output.append(" " * width)
-
-        # Add HUD lines if enabled
-        if show_hud:
-            hud_output = self._render_hud(width, ctx)
-            # Overlay HUD on first lines of content
-            for i, line in enumerate(hud_output):
-                if i < len(output):
-                    output[i] = line[:width]
-
-        # Add separator
-        output.append("─" * width)
-
-        # Add REPL area
-        repl_lines = self._render_repl(width, repl_height - 1)
-        output.extend(repl_lines)
-
-        # Ensure correct height
-        while len(output) < height:
-            output.append(" " * width)
-        output = output[:height]
-
-        return output
-
-    def _render_hud(self, width: int, ctx: EffectContext) -> list[str]:
-        """Render HUD-style header with metrics."""
-        lines = []
-
-        # Get metrics
-        metrics = self._get_metrics(ctx)
-        fps = metrics.get("fps", 0.0)
-        frame_time = metrics.get("frame_time", 0.0)
-
-        # Line 1: Title + FPS + Frame time
-        fps_str = f"FPS: {fps:.1f}" if fps > 0 else "FPS: --"
-        time_str = f"{frame_time:.1f}ms" if frame_time > 0 else "--ms"
-        line1 = (
-            f"\033[38;5;46mMAINLINE REPL\033[0m "
-            f"\033[38;5;245m|\033[0m \033[38;5;39m{fps_str}\033[0m "
-            f"\033[38;5;245m|\033[0m \033[38;5;208m{time_str}\033[0m"
-        )
-        lines.append(line1[:width])
-
-        # Line 2: Command count + History index
-        cmd_count = len(self.state.command_history)
-        hist_idx = (
-            f"[{self.state.history_index + 1}/{cmd_count}]" if cmd_count > 0 else ""
-        )
-        line2 = (
-            f"\033[38;5;45mCOMMANDS:\033[0m "
-            f"\033[1;38;5;227m{cmd_count}\033[0m "
-            f"\033[38;5;245m|\033[0m \033[38;5;219m{hist_idx}\033[0m"
-        )
-        lines.append(line2[:width])
-
-        # Line 3: Output buffer count
-        out_count = len(self.state.output_buffer)
-        line3 = f"\033[38;5;44mOUTPUT:\033[0m \033[1;38;5;227m{out_count}\033[0m lines"
-        lines.append(line3[:width])
-
-        return lines
-
-    def _render_repl(self, width: int, height: int) -> list[str]:
-        """Render REPL interface."""
-        lines = []
-
-        # Calculate how many output lines to show
-        # Reserve 1 line for input prompt
-        output_height = height - 1
-        output_start = max(0, len(self.state.output_buffer) - output_height)
-
-        # Render output buffer
-        for i in range(output_height):
-            idx = output_start + i
-            if idx < len(self.state.output_buffer):
-                line = self.state.output_buffer[idx][:width]
-                lines.append(line)
-            else:
-                lines.append(" " * width)
-
-        # Render input prompt
-        prompt = "> "
-        input_line = f"{prompt}{self.state.current_command}"
-        # Add cursor indicator
-        cursor = "█" if len(self.state.current_command) % 2 == 0 else " "
-        input_line += cursor
-        lines.append(input_line[:width])
-
-        return lines
-
-    def _get_metrics(self, ctx: EffectContext) -> dict:
-        """Get pipeline metrics from context."""
-        metrics = ctx.get_state("metrics")
-        if metrics:
-            self._last_metrics = metrics
-
-        if self._last_metrics:
-            # Extract FPS and frame time
-            fps = 0.0
-            frame_time = 0.0
-
-            if "pipeline" in self._last_metrics:
-                avg_ms = self._last_metrics["pipeline"].get("avg_ms", 0.0)
-                frame_count = self._last_metrics.get("frame_count", 0)
-                if frame_count > 0 and avg_ms > 0:
-                    fps = 1000.0 / avg_ms
-                frame_time = avg_ms
-
-            return {"fps": fps, "frame_time": frame_time}
-
-        return {"fps": 0.0, "frame_time": 0.0}
-
-    def process_command(self, command: str, ctx: EffectContext | None = None) -> None:
-        """Process a REPL command."""
-        cmd = command.strip()
-        if not cmd:
-            return
-
-        # Add to history
-        self.state.command_history.append(cmd)
-        if len(self.state.command_history) > self.state.max_history:
-            self.state.command_history.pop(0)
-
-        self.state.history_index = len(self.state.command_history)
-        self.state.current_command = ""
-
-        # Add to output buffer
-        self.state.output_buffer.append(f"> {cmd}")
-
-        # Parse command
-        parts = cmd.split()
-        cmd_name = parts[0].lower()
-        cmd_args = parts[1:] if len(parts) > 1 else []
-
-        # Execute command
-        try:
-            if cmd_name == "help":
-                self._cmd_help()
-            elif cmd_name == "status":
-                self._cmd_status(ctx)
-            elif cmd_name == "effects":
-                self._cmd_effects(ctx)
-            elif cmd_name == "effect":
-                self._cmd_effect(cmd_args, ctx)
-            elif cmd_name == "param":
-                self._cmd_param(cmd_args, ctx)
-            elif cmd_name == "pipeline":
-                self._cmd_pipeline(ctx)
-            elif cmd_name == "clear":
-                self.state.output_buffer.clear()
-            elif cmd_name == "quit" or cmd_name == "exit":
-                self.state.output_buffer.append("Use Ctrl+C to exit")
-            else:
-                self.state.output_buffer.append(f"Unknown command: {cmd_name}")
-                self.state.output_buffer.append("Type 'help' for available commands")
-
-        except Exception as e:
-            self.state.output_buffer.append(f"Error: {e}")
-
-    def _cmd_help(self):
-        """Show help message."""
-        self.state.output_buffer.append("Available commands:")
-        self.state.output_buffer.append("  help - Show this help")
-        self.state.output_buffer.append("  status - Show pipeline status")
-        self.state.output_buffer.append("  effects - List all effects")
-        self.state.output_buffer.append("  effect <name> <on|off> - Toggle effect")
-        self.state.output_buffer.append(
-            "  param <effect> <param> <value> - Set parameter"
-        )
-        self.state.output_buffer.append("  pipeline - Show current pipeline order")
-        self.state.output_buffer.append("  clear - Clear output buffer")
-        self.state.output_buffer.append("  quit - Show exit message")
-
-    def _cmd_status(self, ctx: EffectContext | None):
-        """Show pipeline status."""
-        if ctx:
-            metrics = self._get_metrics(ctx)
-            self.state.output_buffer.append(f"FPS: {metrics['fps']:.1f}")
-            self.state.output_buffer.append(
-                f"Frame time: {metrics['frame_time']:.1f}ms"
-            )
-
-        self.state.output_buffer.append(
-            f"Output lines: {len(self.state.output_buffer)}"
-        )
-        self.state.output_buffer.append(
-            f"History: {len(self.state.command_history)} commands"
-        )
-
-    def _cmd_effects(self, ctx: EffectContext | None):
-        """List all effects."""
-        if ctx:
-            # Try to get effect list from context
-            effects = ctx.get_state("pipeline_order")
-            if effects:
-                self.state.output_buffer.append("Pipeline effects:")
-                for i, name in enumerate(effects):
-                    self.state.output_buffer.append(f"  {i + 1}. {name}")
-            else:
-                self.state.output_buffer.append("No pipeline information available")
-        else:
-            self.state.output_buffer.append("No context available")
-
-    def _cmd_effect(self, args: list[str], ctx: EffectContext | None):
-        """Toggle effect on/off."""
-        if len(args) < 2:
-            self.state.output_buffer.append("Usage: effect <name> <on|off>")
-            return
-
-        effect_name = args[0]
-        state = args[1].lower()
-
-        if state not in ("on", "off"):
-            self.state.output_buffer.append("State must be 'on' or 'off'")
-            return
-
-        # Emit event to toggle effect
-        enabled = state == "on"
-        self.state.output_buffer.append(f"Effect '{effect_name}' set to {state}")
-
-        # Store command for external handling
-        self._pending_command = {
-            "action": "enable_stage" if enabled else "disable_stage",
-            "stage": effect_name,
-        }
-
-    def _cmd_param(self, args: list[str], ctx: EffectContext | None):
-        """Set effect parameter."""
-        if len(args) < 3:
-            self.state.output_buffer.append("Usage: param <effect> <param> <value>")
-            return
-
-        effect_name = args[0]
-        param_name = args[1]
-        try:
-            param_value = float(args[2])
-        except ValueError:
-            self.state.output_buffer.append("Value must be a number")
-            return
-
-        self.state.output_buffer.append(
-            f"Setting {effect_name}.{param_name} = {param_value}"
-        )
-
-        # Store command for external handling
-        self._pending_command = {
-            "action": "adjust_param",
-            "stage": effect_name,
-            "param": param_name,
-            "delta": param_value,  # Note: This sets absolute value, need adjustment
-        }
-
-    def _cmd_pipeline(self, ctx: EffectContext | None):
-        """Show current pipeline order."""
-        if ctx:
-            pipeline_order = ctx.get_state("pipeline_order")
-            if pipeline_order:
-                self.state.output_buffer.append(
-                    "Pipeline: " + " → ".join(pipeline_order)
-                )
-            else:
-                self.state.output_buffer.append("Pipeline information not available")
-        else:
-            self.state.output_buffer.append("No context available")
-
-    def get_pending_command(self) -> dict | None:
-        """Get and clear pending command for external handling."""
-        cmd = getattr(self, "_pending_command", None)
-        if cmd:
-            self._pending_command = None
-        return cmd
-
-    def navigate_history(self, direction: int) -> None:
-        """Navigate command history (up/down)."""
-        if not self.state.command_history:
-            return
-
-        if direction > 0:  # Down
-            self.state.history_index = min(
-                len(self.state.command_history), self.state.history_index + 1
-            )
-        else:  # Up
-            self.state.history_index = max(0, self.state.history_index - 1)
-
-        if self.state.history_index < len(self.state.command_history):
-            self.state.current_command = self.state.command_history[
-                self.state.history_index
-            ]
-        else:
-            self.state.current_command = ""
-
-    def append_to_command(self, char: str) -> None:
-        """Append character to current command."""
-        if len(char) == 1:  # Single character
-            self.state.current_command += char
-
-    def backspace(self) -> None:
-        """Remove last character from command."""
-        self.state.current_command = self.state.current_command[:-1]
-
-    def clear_command(self) -> None:
-        """Clear current command."""
-        self.state.current_command = ""
-
-    def configure(self, config: EffectConfig) -> None:
-        """Configure the effect."""
-        self.config = config

engine/effects/plugins/tint.py

@@ -20,13 +20,13 @@ class TintEffect(EffectPlugin):
     # Define inlet types for PureData-style typing
     @property
     def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.TEXT_BUFFER}
 
     @property
     def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.TEXT_BUFFER}
 

engine/interfaces/__init__.py

@@ -28,7 +28,7 @@ from engine.effects.types import (
     apply_param_bindings,
     create_effect_context,
 )
-from engine.pipeline.core import (
+from engine.pipeline import (
     DataType,
     Stage,
     StageConfig,

engine/pipeline/__init__.py

@@ -1,50 +1,15 @@
 """
-Unified Pipeline Architecture.
+Unified Pipeline Architecture (Compatibility Shim).
 
-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
+This module re-exports the pipeline architecture from Sideline for backward
+compatibility with existing Mainline code. New code should import directly
+from sideline.pipeline.
 
-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)
+Note: This module is deprecated and will be removed in future versions.
 """
 
-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,
-)
+# Re-export from sideline for backward compatibility
+# Re-export from engine.pipeline.presets (Mainline-specific)
 from engine.pipeline.presets import (
     DEMO_PRESET,
     FIREHOSE_PRESET,
@@ -57,8 +22,21 @@ from engine.pipeline.presets import (
     get_preset,
     list_presets,
 )
-from engine.pipeline.registry import (
+
+# Re-export additional functions from sideline.pipeline
+from sideline.pipeline import (
+    Pipeline,
+    PipelineConfig,
+    PipelineContext,
+    PipelineParams,
+    PipelineRunner,
+    Stage,
+    StageConfig,
+    StageError,
     StageRegistry,
+    StageResult,
+    create_default_pipeline,
+    create_pipeline_from_params,
     discover_stages,
     register_camera,
     register_display,
@@ -66,25 +44,37 @@ from engine.pipeline.registry import (
     register_source,
 )
 
+# Also re-export from sideline.core for compatibility
+from sideline.pipeline.core import (
+    DataType,
+)
+
+# Re-export from sideline.pipeline.params
+from sideline.pipeline.params import (
+    DEFAULT_HEADLINE_PARAMS,
+    DEFAULT_PIPELINE_PARAMS,
+    DEFAULT_PYGAME_PARAMS,
+)
+
 __all__ = [
-    # Core
+    # Core (from sideline)
     "Stage",
     "StageConfig",
     "StageError",
     "StageResult",
     "PipelineContext",
-    # Controller
+    # Controller (from sideline)
     "Pipeline",
     "PipelineConfig",
     "PipelineRunner",
     "create_default_pipeline",
     "create_pipeline_from_params",
-    # Params
+    # Params (from sideline)
     "PipelineParams",
     "DEFAULT_HEADLINE_PARAMS",
     "DEFAULT_PIPELINE_PARAMS",
     "DEFAULT_PYGAME_PARAMS",
-    # Presets
+    # Presets (from engine)
     "PipelinePreset",
     "PRESETS",
     "DEMO_PRESET",
@@ -96,11 +86,13 @@ __all__ = [
     "get_preset",
     "list_presets",
     "create_preset_from_params",
-    # Registry
+    # Registry (from sideline)
     "StageRegistry",
     "discover_stages",
     "register_source",
     "register_effect",
     "register_display",
     "register_camera",
+    # Core types (from sideline)
+    "DataType",
 ]

engine/pipeline/adapters/camera.py

@@ -3,7 +3,7 @@
 import time
 from typing import Any
 
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 
 
 class CameraClockStage(Stage):

engine/pipeline/adapters/data_source.py

@@ -8,7 +8,7 @@ This module provides adapters that wrap existing components
 from typing import Any
 
 from engine.data_sources import SourceItem
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 
 
 class DataSourceStage(Stage):

engine/pipeline/adapters/display.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from engine.pipeline.core import PipelineContext, Stage
+from engine.pipeline import PipelineContext, Stage
 
 
 class DisplayStage(Stage):
@@ -59,13 +59,13 @@ class DisplayStage(Stage):
 
     @property
     def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.TEXT_BUFFER}  # Display consumes rendered text
 
     @property
     def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.NONE}  # Display is a terminal stage (no output)
 

engine/pipeline/adapters/effect_plugin.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-from engine.pipeline.core import PipelineContext, Stage
+from engine.pipeline import PipelineContext, Stage
 
 
 class EffectPluginStage(Stage):
@@ -69,13 +69,13 @@ class EffectPluginStage(Stage):
 
     @property
     def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.TEXT_BUFFER}
 
     @property
     def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.TEXT_BUFFER}
 

engine/pipeline/adapters/frame_capture.py

@@ -7,7 +7,7 @@ Wraps pipeline stages to capture frames for animation report generation.
 from typing import Any
 
 from engine.display.backends.animation_report import AnimationReportDisplay
-from engine.pipeline.core import PipelineContext, Stage
+from engine.pipeline import PipelineContext, Stage
 
 
 class FrameCaptureStage(Stage):

engine/pipeline/adapters/message_overlay.py

@@ -12,7 +12,7 @@ from datetime import datetime
 
 from engine import config
 from engine.effects.legacy import vis_trunc
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 from engine.render.blocks import big_wrap
 from engine.render.gradient import msg_gradient
 

engine/pipeline/adapters/positioning.py

@@ -10,7 +10,7 @@ different ANSI positioning approaches:
 from enum import Enum
 from typing import Any
 
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 
 
 class PositioningMode(Enum):

engine/pipeline/adapters/transform.py

@@ -4,7 +4,7 @@ from typing import Any
 
 import engine.render
 from engine.data_sources import SourceItem
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 
 
 def estimate_simple_height(text: str, width: int) -> int:

engine/pipeline/controller.py

@@ -9,7 +9,7 @@ import time
 from dataclasses import dataclass, field
 from typing import Any
 
-from engine.pipeline.core import PipelineContext, Stage, StageError, StageResult
+from engine.pipeline import PipelineContext, Stage, StageError, StageResult
 from engine.pipeline.params import PipelineParams
 from engine.pipeline.registry import StageRegistry
 
@@ -640,7 +640,7 @@ class Pipeline:
 
         Raises StageError if type mismatch is detected.
         """
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         errors: list[str] = []
 
@@ -984,35 +984,6 @@ class Pipeline:
         """Get historical frame times for sparklines/charts."""
         return [f.total_ms for f in self._frame_metrics]
 
-    def set_effect_intensity(self, effect_name: str, intensity: float) -> bool:
-        """Set the intensity of an effect in the pipeline.
-
-        Args:
-            effect_name: Name of the effect to modify
-            intensity: New intensity value (0.0 to 1.0)
-
-        Returns:
-            True if successful, False if effect not found or not an effect stage
-        """
-        if not 0.0 <= intensity <= 1.0:
-            return False
-
-        stage = self._stages.get(effect_name)
-        if not stage:
-            return False
-
-        # Check if this is an EffectPluginStage
-        from engine.pipeline.adapters.effect_plugin import EffectPluginStage
-
-        if isinstance(stage, EffectPluginStage):
-            # Access the underlying effect plugin
-            effect = stage._effect
-            if hasattr(effect, "config"):
-                effect.config.intensity = intensity
-                return True
-
-        return False
-
 
 class PipelineRunner:
     """High-level pipeline runner with animation support."""

engine/pipeline/graph.py

@@ -1,205 +0,0 @@
-"""Graph-based pipeline configuration and orchestration.
-
-This module provides a graph abstraction for defining pipelines as nodes
-and connections, replacing the verbose XYZStage naming convention.
-
-Usage:
-    # Declarative (TOML-like)
-    graph = Graph.from_dict({
-        "nodes": {
-            "source": "headlines",
-            "camera": {"type": "camera", "mode": "scroll"},
-            "display": {"type": "terminal", "positioning": "mixed"}
-        },
-        "connections": ["source -> camera -> display"]
-    })
-
-    # Imperative
-    graph = Graph()
-    graph.node("source", "headlines")
-    graph.node("camera", type="camera", mode="scroll")
-    graph.connect("source", "camera", "display")
-"""
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any
-
-
-class NodeType(Enum):
-    """Types of pipeline nodes."""
-
-    SOURCE = "source"
-    RENDER = "render"
-    CAMERA = "camera"
-    EFFECT = "effect"
-    OVERLAY = "overlay"
-    POSITION = "position"
-    DISPLAY = "display"
-    CUSTOM = "custom"
-
-
-@dataclass
-class Node:
-    """A node in the pipeline graph."""
-
-    name: str
-    type: NodeType
-    config: dict[str, Any] = field(default_factory=dict)
-    enabled: bool = True
-    optional: bool = False
-
-    def __repr__(self) -> str:
-        return f"Node({self.name}, type={self.type.value})"
-
-
-@dataclass
-class Connection:
-    """A connection between two nodes."""
-
-    source: str
-    target: str
-    data_type: str | None = None  # Optional data type constraint
-
-
-@dataclass
-class Graph:
-    """Pipeline graph representation."""
-
-    nodes: dict[str, Node] = field(default_factory=dict)
-    connections: list[Connection] = field(default_factory=list)
-
-    def node(self, name: str, node_type: NodeType | str, **config) -> "Graph":
-        """Add a node to the graph."""
-        if isinstance(node_type, str):
-            # Try to parse as NodeType
-            try:
-                node_type = NodeType(node_type)
-            except ValueError:
-                node_type = NodeType.CUSTOM
-
-        self.nodes[name] = Node(name=name, type=node_type, config=config)
-        return self
-
-    def connect(
-        self, source: str, target: str, data_type: str | None = None
-    ) -> "Graph":
-        """Add a connection between nodes."""
-        if source not in self.nodes:
-            raise ValueError(f"Source node '{source}' not found")
-        if target not in self.nodes:
-            raise ValueError(f"Target node '{target}' not found")
-
-        self.connections.append(Connection(source, target, data_type))
-        return self
-
-    def chain(self, *names: str) -> "Graph":
-        """Connect nodes in a chain."""
-        for i in range(len(names) - 1):
-            self.connect(names[i], names[i + 1])
-        return self
-
-    def from_dict(self, data: dict[str, Any]) -> "Graph":
-        """Load graph from dictionary (TOML-compatible)."""
-        # Parse nodes
-        nodes_data = data.get("nodes", {})
-        for name, node_info in nodes_data.items():
-            if isinstance(node_info, str):
-                # Simple format: "source": "headlines"
-                self.node(name, NodeType.SOURCE, source=node_info)
-            elif isinstance(node_info, dict):
-                # Full format: {"type": "camera", "mode": "scroll"}
-                node_type = node_info.get("type", "custom")
-                config = {k: v for k, v in node_info.items() if k != "type"}
-                self.node(name, node_type, **config)
-
-        # Parse connections
-        connections_data = data.get("connections", [])
-        for conn in connections_data:
-            if isinstance(conn, str):
-                # Parse "source -> target" format
-                parts = conn.split("->")
-                if len(parts) == 2:
-                    self.connect(parts[0].strip(), parts[1].strip())
-            elif isinstance(conn, dict):
-                # Parse dict format: {"source": "a", "target": "b"}
-                self.connect(conn["source"], conn["target"])
-
-        return self
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert graph to dictionary."""
-        return {
-            "nodes": {
-                name: {"type": node.type.value, **node.config}
-                for name, node in self.nodes.items()
-            },
-            "connections": [
-                {"source": conn.source, "target": conn.target}
-                for conn in self.connections
-            ],
-        }
-
-    def validate(self) -> list[str]:
-        """Validate graph structure and return list of errors."""
-        errors = []
-
-        # Check for disconnected nodes
-        connected_nodes = set()
-        for conn in self.connections:
-            connected_nodes.add(conn.source)
-            connected_nodes.add(conn.target)
-
-        for node_name in self.nodes:
-            if node_name not in connected_nodes:
-                errors.append(f"Node '{node_name}' is not connected")
-
-        # Check for cycles (simplified)
-        visited = set()
-        temp = set()
-
-        def has_cycle(node_name: str) -> bool:
-            if node_name in temp:
-                return True
-            if node_name in visited:
-                return False
-
-            temp.add(node_name)
-            for conn in self.connections:
-                if conn.source == node_name and has_cycle(conn.target):
-                    return True
-            temp.remove(node_name)
-            visited.add(node_name)
-            return False
-
-        for node_name in self.nodes:
-            if has_cycle(node_name):
-                errors.append(f"Cycle detected involving node '{node_name}'")
-                break
-
-        return errors
-
-    def __repr__(self) -> str:
-        nodes_str = ", ".join(str(n) for n in self.nodes.values())
-        return f"Graph(nodes=[{nodes_str}])"
-
-
-# Factory functions for common node types
-def source(name: str, source_type: str, **config) -> Node:
-    """Create a source node."""
-    return Node(name, NodeType.SOURCE, {"source": source_type, **config})
-
-
-def camera(name: str, mode: str = "scroll", **config) -> Node:
-    """Create a camera node."""
-    return Node(name, NodeType.CAMERA, {"mode": mode, **config})
-
-
-def display(name: str, backend: str = "terminal", **config) -> Node:
-    """Create a display node."""
-    return Node(name, NodeType.DISPLAY, {"backend": backend, **config})
-
-
-def effect(name: str, effect_name: str, **config) -> Node:
-    """Create an effect node."""
-    return Node(name, NodeType.EFFECT, {"effect": effect_name, **config})

engine/pipeline/graph_adapter.py

@@ -1,158 +0,0 @@
-"""Adapter to convert Graph to Pipeline stages.
-
-This module bridges the new graph-based abstraction with the existing
-Stage-based pipeline system for backward compatibility.
-"""
-
-from typing import Any, Optional
-
-from engine.camera import Camera
-from engine.data_sources.sources import EmptyDataSource, HeadlinesDataSource
-from engine.display import DisplayRegistry
-from engine.effects import get_registry
-from engine.pipeline.adapters import (
-    CameraStage,
-    DataSourceStage,
-    DisplayStage,
-    EffectPluginStage,
-    FontStage,
-    MessageOverlayStage,
-    PositionStage,
-)
-from engine.pipeline.adapters.positioning import PositioningMode
-from engine.pipeline.controller import Pipeline, PipelineConfig
-from engine.pipeline.core import PipelineContext
-from engine.pipeline.graph import Graph, NodeType
-from engine.pipeline.params import PipelineParams
-
-
-class GraphAdapter:
-    """Converts Graph to Pipeline with existing Stage classes."""
-
-    def __init__(self, graph: Graph):
-        self.graph = graph
-        self.pipeline: Pipeline | None = None
-        self.context: PipelineContext | None = None
-
-    def build_pipeline(
-        self, viewport_width: int = 80, viewport_height: int = 24
-    ) -> Pipeline:
-        """Build a Pipeline from the Graph."""
-        # Create pipeline context
-        self.context = PipelineContext()
-        self.context.terminal_width = viewport_width
-        self.context.terminal_height = viewport_height
-
-        # Create params
-        params = PipelineParams(
-            viewport_width=viewport_width,
-            viewport_height=viewport_height,
-        )
-        self.context.params = params
-
-        # Create pipeline config
-        config = PipelineConfig()
-
-        # Create pipeline
-        self.pipeline = Pipeline(config=config, context=self.context)
-
-        # Map graph nodes to pipeline stages
-        self._map_nodes_to_stages()
-
-        # Build pipeline
-        self.pipeline.build()
-
-        return self.pipeline
-
-    def _map_nodes_to_stages(self) -> None:
-        """Map graph nodes to pipeline stages."""
-        for name, node in self.graph.nodes.items():
-            if not node.enabled:
-                continue
-
-            stage = self._create_stage_from_node(name, node)
-            if stage:
-                self.pipeline.add_stage(name, stage)
-
-    def _create_stage_from_node(self, name: str, node) -> Optional:
-        """Create a pipeline stage from a graph node."""
-        stage = None
-
-        if node.type == NodeType.SOURCE:
-            source_type = node.config.get("source", "headlines")
-            if source_type == "headlines":
-                source = HeadlinesDataSource()
-            elif source_type == "empty":
-                source = EmptyDataSource(
-                    width=self.context.terminal_width,
-                    height=self.context.terminal_height,
-                )
-            else:
-                source = EmptyDataSource(
-                    width=self.context.terminal_width,
-                    height=self.context.terminal_height,
-                )
-            stage = DataSourceStage(source, name=name)
-
-        elif node.type == NodeType.CAMERA:
-            mode = node.config.get("mode", "scroll")
-            speed = node.config.get("speed", 1.0)
-            # Map mode string to Camera factory method
-            mode_lower = mode.lower()
-            if hasattr(Camera, mode_lower):
-                camera_factory = getattr(Camera, mode_lower)
-                camera = camera_factory(speed=speed)
-            else:
-                # Fallback to scroll mode
-                camera = Camera.scroll(speed=speed)
-            stage = CameraStage(camera, name=name)
-
-        elif node.type == NodeType.DISPLAY:
-            backend = node.config.get("backend", "terminal")
-            positioning = node.config.get("positioning", "mixed")
-            display = DisplayRegistry.create(backend)
-            if display:
-                stage = DisplayStage(display, name=name, positioning=positioning)
-
-        elif node.type == NodeType.EFFECT:
-            effect_name = node.config.get("effect", "")
-            intensity = node.config.get("intensity", 1.0)
-            effect = get_registry().get(effect_name)
-            if effect:
-                # Set effect intensity (modifies global effect state)
-                effect.config.intensity = intensity
-                # Effects typically depend on rendered output
-                dependencies = {"render.output"}
-                stage = EffectPluginStage(effect, name=name, dependencies=dependencies)
-
-        elif node.type == NodeType.RENDER:
-            stage = FontStage(name=name)
-
-        elif node.type == NodeType.OVERLAY:
-            stage = MessageOverlayStage(name=name)
-
-        elif node.type == NodeType.POSITION:
-            mode_str = node.config.get("mode", "mixed")
-            try:
-                mode = PositioningMode(mode_str)
-            except ValueError:
-                mode = PositioningMode.MIXED
-            stage = PositionStage(mode=mode, name=name)
-
-        return stage
-
-
-def graph_to_pipeline(
-    graph: Graph, viewport_width: int = 80, viewport_height: int = 24
-) -> Pipeline:
-    """Convert a Graph to a Pipeline."""
-    adapter = GraphAdapter(graph)
-    return adapter.build_pipeline(viewport_width, viewport_height)
-
-
-def dict_to_pipeline(
-    data: dict[str, Any], viewport_width: int = 80, viewport_height: int = 24
-) -> Pipeline:
-    """Convert a dictionary to a Pipeline."""
-    graph = Graph().from_dict(data)
-    return graph_to_pipeline(graph, viewport_width, viewport_height)

engine/pipeline/graph_toml.py

@@ -1,113 +0,0 @@
-"""TOML-based graph configuration loader."""
-
-from pathlib import Path
-from typing import Any
-
-import tomllib
-
-from engine.pipeline.graph import Graph, NodeType
-from engine.pipeline.graph_adapter import graph_to_pipeline
-
-
-def load_graph_from_toml(toml_path: str | Path) -> Graph:
-    """Load a graph from a TOML file.
-
-    Args:
-        toml_path: Path to the TOML file
-
-    Returns:
-        Graph instance loaded from the TOML file
-    """
-    with open(toml_path, "rb") as f:
-        data = tomllib.load(f)
-
-    return graph_from_dict(data)
-
-
-def graph_from_dict(data: dict[str, Any]) -> Graph:
-    """Create a graph from a dictionary (TOML-compatible structure).
-
-    Args:
-        data: Dictionary with 'nodes' and 'connections' keys
-
-    Returns:
-        Graph instance
-    """
-    graph = Graph()
-
-    # Parse nodes
-    nodes_data = data.get("nodes", {})
-    for name, node_info in nodes_data.items():
-        if isinstance(node_info, str):
-            # Simple format: "source": "headlines"
-            graph.node(name, NodeType.SOURCE, source=node_info)
-        elif isinstance(node_info, dict):
-            # Full format: {"type": "camera", "mode": "scroll"}
-            node_type = node_info.get("type", "custom")
-            config = {k: v for k, v in node_info.items() if k != "type"}
-            graph.node(name, node_type, **config)
-
-    # Parse connections
-    connections_data = data.get("connections", {})
-    if isinstance(connections_data, dict):
-        # Format: {"list": ["source -> camera -> display"]}
-        connections_list = connections_data.get("list", [])
-    else:
-        # Format: ["source -> camera -> display"]
-        connections_list = connections_data
-
-    for conn in connections_list:
-        if isinstance(conn, str):
-            # Parse "source -> target" format
-            parts = conn.split("->")
-            if len(parts) >= 2:
-                # Connect all nodes in the chain
-                for i in range(len(parts) - 1):
-                    source = parts[i].strip()
-                    target = parts[i + 1].strip()
-                    graph.connect(source, target)
-
-    return graph
-
-
-def load_pipeline_from_toml(
-    toml_path: str | Path, viewport_width: int = 80, viewport_height: int = 24
-):
-    """Load a pipeline from a TOML file.
-
-    Args:
-        toml_path: Path to the TOML file
-        viewport_width: Terminal width for the pipeline
-        viewport_height: Terminal height for the pipeline
-
-    Returns:
-        Pipeline instance loaded from the TOML file
-    """
-    graph = load_graph_from_toml(toml_path)
-    return graph_to_pipeline(graph, viewport_width, viewport_height)
-
-
-# Example TOML structure:
-EXAMPLE_TOML = """
-# Graph-based pipeline configuration
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-speed = 1.0
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> noise -> display"]
-"""

engine/pipeline/hybrid_config.py

@@ -1,282 +0,0 @@
-"""Hybrid Preset-Graph Configuration System
-
-This module provides a configuration format that combines the simplicity
-of presets with the flexibility of graphs.
-
-Example:
-    [pipeline]
-    source = "headlines"
-    camera = { mode = "scroll", speed = 1.0 }
-    effects = [
-        { name = "noise", intensity = 0.3 },
-        { name = "fade", intensity = 0.5 }
-    ]
-    display = { backend = "terminal" }
-
-This is much more concise than the verbose node-based graph DSL while
-providing the same flexibility.
-"""
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-from engine.pipeline.graph import Graph, NodeType
-from engine.pipeline.graph_adapter import graph_to_pipeline
-
-
-@dataclass
-class EffectConfig:
-    """Configuration for a single effect."""
-
-    name: str
-    intensity: float = 1.0
-    enabled: bool = True
-    params: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class CameraConfig:
-    """Configuration for camera."""
-
-    mode: str = "scroll"
-    speed: float = 1.0
-
-
-@dataclass
-class DisplayConfig:
-    """Configuration for display."""
-
-    backend: str = "terminal"
-    positioning: str = "mixed"
-
-
-@dataclass
-class PipelineConfig:
-    """Hybrid pipeline configuration combining preset simplicity with graph flexibility.
-
-    This format provides a concise way to define pipelines that's 70% smaller
-    than the verbose node-based DSL while maintaining full flexibility.
-
-    Example:
-        [pipeline]
-        source = "headlines"
-        camera = { mode = "scroll", speed = 1.0 }
-        effects = [
-            { name = "noise", intensity = 0.3 },
-            { name = "fade", intensity = 0.5 }
-        ]
-        display = { backend = "terminal", positioning = "mixed" }
-    """
-
-    source: str = "headlines"
-    camera: CameraConfig | None = None
-    effects: list[EffectConfig] = field(default_factory=list)
-    display: DisplayConfig | None = None
-    viewport_width: int = 80
-    viewport_height: int = 24
-
-    @classmethod
-    def from_preset(cls, preset_name: str) -> "PipelineConfig":
-        """Create PipelineConfig from a preset name.
-
-        Args:
-            preset_name: Name of preset (e.g., "upstream-default")
-
-        Returns:
-            PipelineConfig instance
-        """
-        from engine.pipeline import get_preset
-
-        preset = get_preset(preset_name)
-        if not preset:
-            raise ValueError(f"Preset '{preset_name}' not found")
-
-        # Convert preset to PipelineConfig
-        effects = [EffectConfig(name=e, intensity=1.0) for e in preset.effects]
-
-        return cls(
-            source=preset.source,
-            camera=CameraConfig(mode=preset.camera, speed=preset.camera_speed),
-            effects=effects,
-            display=DisplayConfig(
-                backend=preset.display, positioning=preset.positioning
-            ),
-            viewport_width=preset.viewport_width,
-            viewport_height=preset.viewport_height,
-        )
-
-    def to_graph(self) -> Graph:
-        """Convert hybrid config to Graph representation."""
-        graph = Graph()
-
-        # Add source node
-        graph.node("source", NodeType.SOURCE, source=self.source)
-
-        # Add camera node if configured
-        if self.camera:
-            graph.node(
-                "camera",
-                NodeType.CAMERA,
-                mode=self.camera.mode,
-                speed=self.camera.speed,
-            )
-
-        # Add effect nodes
-        for effect in self.effects:
-            # Handle both EffectConfig objects and dictionaries
-            if isinstance(effect, dict):
-                name = effect.get("name", "")
-                intensity = effect.get("intensity", 1.0)
-                enabled = effect.get("enabled", True)
-                params = effect.get("params", {})
-            else:
-                name = effect.name
-                intensity = effect.intensity
-                enabled = effect.enabled
-                params = effect.params
-
-            if name:
-                graph.node(
-                    name,
-                    NodeType.EFFECT,
-                    effect=name,
-                    intensity=intensity,
-                    enabled=enabled,
-                    **params,
-                )
-
-        # Add display node
-        if isinstance(self.display, dict):
-            display_backend = self.display.get("backend", "terminal")
-            display_positioning = self.display.get("positioning", "mixed")
-        elif self.display:
-            display_backend = self.display.backend
-            display_positioning = self.display.positioning
-        else:
-            display_backend = "terminal"
-            display_positioning = "mixed"
-
-        graph.node(
-            "display",
-            NodeType.DISPLAY,
-            backend=display_backend,
-            positioning=display_positioning,
-        )
-
-        # Create linear connections
-        # Build chain: source -> camera -> effects... -> display
-        chain = ["source"]
-
-        if self.camera:
-            chain.append("camera")
-
-        # Add all effects in order
-        for effect in self.effects:
-            name = effect.get("name", "") if isinstance(effect, dict) else effect.name
-            if name:
-                chain.append(name)
-
-        chain.append("display")
-
-        # Connect all nodes in chain
-        for i in range(len(chain) - 1):
-            graph.connect(chain[i], chain[i + 1])
-
-        return graph
-
-    def to_pipeline(self, viewport_width: int = 80, viewport_height: int = 24):
-        """Convert to Pipeline instance."""
-        graph = self.to_graph()
-        return graph_to_pipeline(graph, viewport_width, viewport_height)
-
-
-def load_hybrid_config(toml_path: str | Path) -> PipelineConfig:
-    """Load hybrid configuration from TOML file.
-
-    Args:
-        toml_path: Path to TOML file
-
-    Returns:
-        PipelineConfig instance
-    """
-    import tomllib
-
-    with open(toml_path, "rb") as f:
-        data = tomllib.load(f)
-
-    return parse_hybrid_config(data)
-
-
-def parse_hybrid_config(data: dict[str, Any]) -> PipelineConfig:
-    """Parse hybrid configuration from dictionary.
-
-    Expected format:
-    {
-        "pipeline": {
-            "source": "headlines",
-            "camera": {"mode": "scroll", "speed": 1.0},
-            "effects": [
-                {"name": "noise", "intensity": 0.3},
-                {"name": "fade", "intensity": 0.5}
-            ],
-            "display": {"backend": "terminal"}
-        }
-    }
-    """
-    pipeline_data = data.get("pipeline", {})
-
-    # Parse camera config
-    camera = None
-    if "camera" in pipeline_data:
-        camera_data = pipeline_data["camera"]
-        if isinstance(camera_data, dict):
-            camera = CameraConfig(
-                mode=camera_data.get("mode", "scroll"),
-                speed=camera_data.get("speed", 1.0),
-            )
-        elif isinstance(camera_data, str):
-            camera = CameraConfig(mode=camera_data)
-
-    # Parse effects list
-    effects = []
-    if "effects" in pipeline_data:
-        effects_data = pipeline_data["effects"]
-        if isinstance(effects_data, list):
-            for effect_item in effects_data:
-                if isinstance(effect_item, dict):
-                    effects.append(
-                        EffectConfig(
-                            name=effect_item.get("name", ""),
-                            intensity=effect_item.get("intensity", 1.0),
-                            enabled=effect_item.get("enabled", True),
-                            params=effect_item.get("params", {}),
-                        )
-                    )
-                elif isinstance(effect_item, str):
-                    effects.append(EffectConfig(name=effect_item))
-
-    # Parse display config
-    display = None
-    if "display" in pipeline_data:
-        display_data = pipeline_data["display"]
-        if isinstance(display_data, dict):
-            display = DisplayConfig(
-                backend=display_data.get("backend", "terminal"),
-                positioning=display_data.get("positioning", "mixed"),
-            )
-        elif isinstance(display_data, str):
-            display = DisplayConfig(backend=display_data)
-
-    # Parse viewport settings
-    viewport_width = pipeline_data.get("viewport_width", 80)
-    viewport_height = pipeline_data.get("viewport_height", 24)
-
-    return PipelineConfig(
-        source=pipeline_data.get("source", "headlines"),
-        camera=camera,
-        effects=effects,
-        display=display,
-        viewport_width=viewport_width,
-        viewport_height=viewport_height,
-    )

engine/pipeline/registry.py

@@ -8,10 +8,10 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, TypeVar
 
-from engine.pipeline.core import Stage
+from engine.pipeline import Stage
 
 if TYPE_CHECKING:
-    from engine.pipeline.core import Stage
+    from engine.pipeline import Stage
 
 T = TypeVar("T")
 

engine/pipeline/stages/framebuffer.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from engine.display import _strip_ansi
-from engine.pipeline.core import DataType, PipelineContext, Stage
+from engine.pipeline import DataType, PipelineContext, Stage
 
 
 @dataclass

engine/plugins.py

@@ -0,0 +1,90 @@
+"""
+Mainline stage component registration.
+
+This module registers all Mainline-specific stage components with the Sideline framework.
+It should be called during application startup to ensure all components are available.
+
+Terminology:
+- Stage: A pipeline component (source, effect, display, camera, overlay)
+- Plugin: A distributable package containing one or more stages
+- This module registers stage components, not plugins themselves
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def register_stages(registry):
+    """Register Mainline-specific stage components with the Sideline registry.
+
+    This function is called by Sideline's plugin discovery system.
+
+    Args:
+        registry: StageRegistry instance from Sideline
+    """
+    logger.info("Registering Mainline stage components")
+
+    # Register data sources
+    _register_data_sources(registry)
+
+    # Register effects
+    _register_effects(registry)
+
+    # Register any other Mainline-specific stages
+    _register_other_stages(registry)
+
+
+def _register_data_sources(registry):
+    """Register Mainline data source stages."""
+    try:
+        from engine.data_sources.pipeline_introspection import (
+            PipelineIntrospectionSource,
+        )
+        from engine.data_sources.sources import HeadlinesDataSource, PoetryDataSource
+
+        registry.register("source", HeadlinesDataSource)
+        registry.register("source", PoetryDataSource)
+        registry.register("source", PipelineIntrospectionSource)
+
+        # Register with friendly aliases
+        registry._categories["source"]["headlines"] = HeadlinesDataSource
+        registry._categories["source"]["poetry"] = PoetryDataSource
+        registry._categories["source"]["pipeline-inspect"] = PipelineIntrospectionSource
+
+        logger.info("Registered Mainline data sources")
+    except ImportError as e:
+        logger.warning(f"Failed to register data sources: {e}")
+
+
+def _register_effects(registry):
+    """Register Mainline effect stages."""
+    try:
+        # Note: EffectRegistry stores effect instances, not classes
+        # For now, skip effect registration since it requires more refactoring
+        logger.info("Effect registration skipped (requires effect refactoring)")
+    except ImportError as e:
+        logger.warning(f"Failed to register effects: {e}")
+
+
+def _register_other_stages(registry):
+    """Register other Mainline-specific stage components."""
+    try:
+        # Register buffer stages
+        from sideline.pipeline.stages.framebuffer import FrameBufferStage
+
+        registry.register("effect", FrameBufferStage)
+        logger.info("Registered Mainline buffer stages")
+    except ImportError as e:
+        logger.warning(f"Failed to register buffer stages: {e}")
+
+
+# Convenience function for explicit registration
+def register_all_stages():
+    """Explicitly register all Mainline stages.
+
+    This can be called directly instead of using plugin discovery.
+    """
+    from sideline.pipeline import StageRegistry
+
+    register_stages(StageRegistry)

engine/sensors/__init__.py

@@ -25,7 +25,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from engine.pipeline.core import PipelineContext
+    from engine.pipeline import PipelineContext
 
 
 @dataclass
@@ -166,13 +166,13 @@ class SensorStage:
 
     @property
     def inlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.ANY}
 
     @property
     def outlet_types(self) -> set:
-        from engine.pipeline.core import DataType
+        from engine.pipeline import DataType
 
         return {DataType.ANY}
 

examples/README.md

@@ -1,98 +0,0 @@
-# Examples
-
-This directory contains example scripts demonstrating how to use Mainline's features.
-
-## Hybrid Configuration (Recommended)
-
-**`hybrid_visualization.py`** - Renders visualization using the hybrid preset-graph format.
-
-```bash
-python examples/hybrid_visualization.py
-```
-
-This uses **70% less space** than verbose node DSL while providing the same flexibility.
-
-### Configuration
-
-The hybrid format uses inline objects and arrays:
-
-```toml
-[pipeline]
-source = "headlines"
-camera = { mode = "scroll", speed = 1.0 }
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5 }
-]
-display = { backend = "terminal", positioning = "mixed" }
-```
-
-See `docs/hybrid-config.md` for complete documentation.
-
----
-
-## Default Visualization (Verbose Node DSL)
-
-**`default_visualization.py`** - Renders the standard Mainline visualization using the verbose graph DSL.
-
-```bash
-python examples/default_visualization.py
-```
-
-This demonstrates the verbose node-based syntax (more flexible for complex DAGs):
-
-```toml
-[nodes.source] type = "source" source = "headlines"
-[nodes.camera] type = "camera" mode = "scroll"
-[nodes.noise] type = "effect" effect = "noise" intensity = 0.3
-[nodes.display] type = "display" backend = "terminal"
-[connections] list = ["source -> camera -> noise -> display"]
-```
-
-## Graph DSL Demonstration
-
-**`graph_dsl_demo.py`** - Demonstrates the graph-based DSL in multiple ways:
-
-```bash
-python examples/graph_dsl_demo.py
-```
-
-Shows:
-- Imperative Python API for building graphs
-- Dictionary-based API
-- Graph validation (cycles, disconnected nodes)
-- Different node types and configurations
-
-## Integration Test
-
-**`test_graph_integration.py`** - Tests the graph system with actual pipeline execution:
-
-```bash
-python examples/test_graph_integration.py
-```
-
-Verifies:
-- Graph loading from TOML
-- Pipeline execution
-- Output rendering
-- Comparison with preset-based pipelines
-
-## Other Demos
-
-- **`demo-lfo-effects.py`** - LFO modulation of effect intensities (Pygame display)
-- **`demo_oscilloscope.py`** - Oscilloscope visualization
-- **`demo_image_oscilloscope.py`** - Image-based oscilloscope
-
-## Configuration Format Comparison
-
-| Format | Use Case | Lines | Example |
-|--------|----------|-------|---------|
-| **Hybrid** | Recommended for most use cases | 20 | `hybrid_config.toml` |
-| **Verbose Node DSL** | Complex DAGs, branching | 39 | `default_visualization.toml` |
-| **Preset** | Simple configurations | 10 | `presets.toml` |
-
-## Reference
-
-- `docs/hybrid-config.md` - Hybrid preset-graph configuration
-- `docs/graph-dsl.md` - Verbose node-based graph DSL
-- `docs/presets-usage.md` - Preset system usage

examples/default_visualization.py

@@ -1,86 +0,0 @@
-#!/usr/bin/env python3
-"""
-Default Mainline Visualization
-
-Renders the standard Mainline visualization using the graph-based DSL.
-This demonstrates the default behavior: headlines source, scroll camera,
-terminal display, with classic effects (noise, fade, glitch, firehose).
-
-Usage:
-    python examples/default_visualization.py
-
-The visualization will be rendered once and printed to stdout.
-"""
-
-import sys
-from pathlib import Path
-
-# Add the project root to Python path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.graph_toml import load_pipeline_from_toml
-from engine.pipeline.params import PipelineParams
-
-
-def main():
-    """Render the default Mainline visualization."""
-    print("Loading default Mainline visualization...")
-    print("=" * 70)
-
-    # Discover effect plugins
-    discover_plugins()
-
-    # Path to the TOML configuration
-    toml_path = Path(__file__).parent / "default_visualization.toml"
-
-    if not toml_path.exists():
-        print(f"Error: Configuration file not found: {toml_path}", file=sys.stderr)
-        sys.exit(1)
-
-    # Load pipeline from TOML configuration
-    try:
-        pipeline = load_pipeline_from_toml(
-            toml_path, viewport_width=80, viewport_height=24
-        )
-        print(f"✓ Pipeline loaded from {toml_path.name}")
-        print(f"  Stages: {list(pipeline._stages.keys())}")
-    except Exception as e:
-        print(f"Error loading pipeline: {e}", file=sys.stderr)
-        sys.exit(1)
-
-    # Initialize the pipeline
-    if not pipeline.initialize():
-        print("Error: Failed to initialize pipeline", file=sys.stderr)
-        sys.exit(1)
-    print("✓ Pipeline initialized")
-
-    # Set up execution context
-    ctx = pipeline.context
-    ctx.terminal_width = 80
-    ctx.terminal_height = 24
-
-    # Create params for the execution
-    params = PipelineParams(viewport_width=80, viewport_height=24)
-    ctx.params = params
-
-    # Execute the pipeline (empty items list - source will provide content)
-    print("Executing pipeline...")
-    result = pipeline.execute([])
-
-    # Render output
-    if result.success:
-        print("=" * 70)
-        print("Visualization Output:")
-        print("=" * 70)
-        for i, line in enumerate(result.data):
-            print(line)
-        print("=" * 70)
-        print(f"✓ Successfully rendered {len(result.data)} lines")
-    else:
-        print(f"Error: Pipeline execution failed: {result.error}", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

examples/default_visualization.toml

@@ -1,39 +0,0 @@
-# Default Mainline Visualization
-# This configuration renders the standard Mainline visualization using the
-# graph-based DSL. It matches the upstream-default preset behavior.
-
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-speed = 1.0
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.fade]
-type = "effect"
-effect = "fade"
-intensity = 0.5
-
-[nodes.glitch]
-type = "effect"
-effect = "glitch"
-intensity = 0.2
-
-[nodes.firehose]
-type = "effect"
-effect = "firehose"
-intensity = 0.4
-
-[nodes.display]
-type = "display"
-backend = "terminal"
-
-[connections]
-list = ["source -> camera -> noise -> fade -> glitch -> firehose -> display"]

examples/graph_dsl_demo.py

@@ -1,136 +0,0 @@
-#!/usr/bin/env python3
-"""
-Demo script showing the new graph-based DSL for pipeline configuration.
-
-This demonstrates how to define pipelines using the graph abstraction,
-which is more intuitive than the verbose XYZStage naming convention.
-"""
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.graph import Graph, NodeType
-from engine.pipeline.graph_adapter import graph_to_pipeline, dict_to_pipeline
-
-
-def demo_imperative_api():
-    """Demo: Imperative Python API for building graphs."""
-    print("=== Imperative Python API ===")
-
-    graph = Graph()
-    graph.node("source", NodeType.SOURCE, source="headlines")
-    graph.node("camera", NodeType.CAMERA, mode="scroll", speed=1.0)
-    graph.node("noise", NodeType.EFFECT, effect="noise", intensity=0.3)
-    graph.node("display", NodeType.DISPLAY, backend="null")
-
-    # Connect nodes in a chain
-    graph.chain("source", "camera", "noise", "display")
-
-    # Validate the graph
-    errors = graph.validate()
-    if errors:
-        print(f"Validation errors: {errors}")
-        return
-
-    # Convert to pipeline
-    pipeline = graph_to_pipeline(graph, viewport_width=80, viewport_height=24)
-
-    print(f"Pipeline created with {len(pipeline._stages)} stages:")
-    for name, stage in pipeline._stages.items():
-        print(f"  - {name}: {stage.__class__.__name__}")
-
-    return pipeline
-
-
-def demo_dict_api():
-    """Demo: Dictionary-based API for building graphs."""
-    print("\n=== Dictionary API ===")
-
-    data = {
-        "nodes": {
-            "source": "headlines",
-            "camera": {"type": "camera", "mode": "scroll", "speed": 1.0},
-            "noise": {"type": "effect", "effect": "noise", "intensity": 0.5},
-            "fade": {"type": "effect", "effect": "fade", "intensity": 0.8},
-            "display": {"type": "display", "backend": "null"},
-        },
-        "connections": ["source -> camera -> noise -> fade -> display"],
-    }
-
-    pipeline = dict_to_pipeline(data, viewport_width=80, viewport_height=24)
-
-    print(f"Pipeline created with {len(pipeline._stages)} stages:")
-    for name, stage in pipeline._stages.items():
-        print(f"  - {name}: {stage.__class__.__name__}")
-
-    return pipeline
-
-
-def demo_graph_validation():
-    """Demo: Graph validation."""
-    print("\n=== Graph Validation ===")
-
-    # Create a graph with a cycle
-    graph = Graph()
-    graph.node("a", NodeType.SOURCE)
-    graph.node("b", NodeType.CAMERA)
-    graph.node("c", NodeType.DISPLAY)
-    graph.connect("a", "b")
-    graph.connect("b", "c")
-    graph.connect("c", "a")  # Creates cycle
-
-    errors = graph.validate()
-    print(f"Cycle detection errors: {errors}")
-
-    # Create a valid graph
-    graph2 = Graph()
-    graph2.node("source", NodeType.SOURCE, source="headlines")
-    graph2.node("display", NodeType.DISPLAY, backend="null")
-    graph2.connect("source", "display")
-
-    errors2 = graph2.validate()
-    print(f"Valid graph errors: {errors2}")
-
-
-def demo_node_types():
-    """Demo: Different node types."""
-    print("\n=== Node Types ===")
-
-    graph = Graph()
-
-    # Source node
-    graph.node("headlines", NodeType.SOURCE, source="headlines")
-    print("✓ Source node created")
-
-    # Camera node with different modes
-    graph.node("camera_scroll", NodeType.CAMERA, mode="scroll", speed=1.0)
-    graph.node("camera_feed", NodeType.CAMERA, mode="feed", speed=0.5)
-    graph.node("camera_horizontal", NodeType.CAMERA, mode="horizontal", speed=1.0)
-    print("✓ Camera nodes created (scroll, feed, horizontal)")
-
-    # Effect nodes
-    graph.node("noise", NodeType.EFFECT, effect="noise", intensity=0.3)
-    graph.node("fade", NodeType.EFFECT, effect="fade", intensity=0.8)
-    print("✓ Effect nodes created (noise, fade)")
-
-    # Positioning node
-    graph.node("position", NodeType.POSITION, mode="mixed")
-    print("✓ Positioning node created")
-
-    # Display nodes
-    graph.node("terminal", NodeType.DISPLAY, backend="terminal")
-    graph.node("null", NodeType.DISPLAY, backend="null")
-    print("✓ Display nodes created")
-
-    print(f"\nTotal nodes: {len(graph.nodes)}")
-
-
-if __name__ == "__main__":
-    # Discover effect plugins first
-    discover_plugins()
-
-    # Run demos
-    demo_imperative_api()
-    demo_dict_api()
-    demo_graph_validation()
-    demo_node_types()
-
-    print("\n=== Demo Complete ===")

examples/hybrid_config.toml

@@ -1,20 +0,0 @@
-# Hybrid Preset-Graph Configuration
-# Combines preset simplicity with graph flexibility
-# Uses 70% less space than verbose node-based DSL
-
-[pipeline]
-source = "headlines"
-
-camera = { mode = "scroll", speed = 1.0 }
-
-effects = [
-    { name = "noise", intensity = 0.3 },
-    { name = "fade", intensity = 0.5 },
-    { name = "glitch", intensity = 0.2 },
-    { name = "firehose", intensity = 0.4 }
-]
-
-display = { backend = "terminal", positioning = "mixed" }
-
-viewport_width = 80
-viewport_height = 24

examples/hybrid_visualization.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-"""
-Hybrid Preset-Graph Visualization
-
-Demonstrates the new hybrid configuration format that combines
-preset simplicity with graph flexibility.
-
-This uses 70% less space than the verbose node-based DSL while
-providing the same functionality.
-
-Usage:
-    python examples/hybrid_visualization.py
-"""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.hybrid_config import load_hybrid_config
-
-
-def main():
-    """Render visualization using hybrid configuration."""
-    print("Loading hybrid configuration...")
-    print("=" * 70)
-
-    # Discover effect plugins
-    discover_plugins()
-
-    # Path to the hybrid configuration
-    toml_path = Path(__file__).parent / "hybrid_config.toml"
-
-    if not toml_path.exists():
-        print(f"Error: Configuration file not found: {toml_path}", file=sys.stderr)
-        sys.exit(1)
-
-    # Load hybrid configuration
-    try:
-        config = load_hybrid_config(toml_path)
-        print(f"✓ Hybrid config loaded from {toml_path.name}")
-        print(f"  Source: {config.source}")
-        print(f"  Camera: {config.camera.mode if config.camera else 'none'}")
-        print(f"  Effects: {len(config.effects)}")
-        for effect in config.effects:
-            print(f"    - {effect.name}: intensity={effect.intensity}")
-        print(f"  Display: {config.display.backend if config.display else 'terminal'}")
-    except Exception as e:
-        print(f"Error loading config: {e}", file=sys.stderr)
-        import traceback
-
-        traceback.print_exc()
-        sys.exit(1)
-
-    # Convert to pipeline
-    try:
-        pipeline = config.to_pipeline(
-            viewport_width=config.viewport_width, viewport_height=config.viewport_height
-        )
-        print(f"✓ Pipeline created with {len(pipeline._stages)} stages")
-        print(f"  Stages: {list(pipeline._stages.keys())}")
-    except Exception as e:
-        print(f"Error creating pipeline: {e}", file=sys.stderr)
-        import traceback
-
-        traceback.print_exc()
-        sys.exit(1)
-
-    # Initialize the pipeline
-    if not pipeline.initialize():
-        print("Error: Failed to initialize pipeline", file=sys.stderr)
-        sys.exit(1)
-    print("✓ Pipeline initialized")
-
-    # Execute the pipeline
-    print("Executing pipeline...")
-    result = pipeline.execute([])
-
-    # Render output
-    if result.success:
-        print("=" * 70)
-        print("Visualization Output:")
-        print("=" * 70)
-        for i, line in enumerate(result.data):
-            print(line)
-        print("=" * 70)
-        print(f"✓ Successfully rendered {len(result.data)} lines")
-    else:
-        print(f"Error: Pipeline execution failed: {result.error}", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

examples/pipeline_graph.toml

@@ -1,28 +0,0 @@
-# Graph-based pipeline configuration example
-# This defines a pipeline using the new graph DSL
-
-[nodes.source]
-type = "source"
-source = "headlines"
-
-[nodes.camera]
-type = "camera"
-mode = "scroll"
-speed = 1.0
-
-[nodes.noise]
-type = "effect"
-effect = "noise"
-intensity = 0.3
-
-[nodes.fade]
-type = "effect"
-effect = "fade"
-intensity = 0.8
-
-[nodes.display]
-type = "display"
-backend = "null"
-
-[connections]
-list = ["source -> camera -> noise -> fade -> display"]

examples/repl_demo.py

@@ -1,145 +0,0 @@
-#!/usr/bin/env python3
-"""
-REPL Demo - Interactive command-line interface for pipeline control
-
-This demo shows how to use the REPL effect plugin to interact with
-the Mainline pipeline in real-time.
-
-Features:
-- HUD-style overlay showing FPS, frame time, command history
-- Command history navigation (Up/Down arrows)
-- Pipeline inspection and control commands
-- Parameter adjustment in real-time
-
-Usage:
-    python examples/repl_demo.py
-
-Keyboard Controls:
-    Enter     - Execute command
-    Up/Down   - Navigate command history
-    Backspace - Delete character
-    Ctrl+C    - Exit
-"""
-
-import sys
-import time
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.hybrid_config import PipelineConfig
-
-
-def main():
-    """Run the REPL demo."""
-    print("REPL Demo - Interactive Pipeline Control")
-    print("=" * 50)
-    print()
-    print("This demo will:")
-    print("1. Create a pipeline with REPL effect")
-    print("2. Enable raw terminal mode for input")
-    print("3. Show REPL interface with HUD overlay")
-    print()
-    print("Keyboard controls:")
-    print("  Enter     - Execute command")
-    print("  Up/Down   - Navigate command history")
-    print("  Backspace - Delete character")
-    print("  Ctrl+C    - Exit")
-    print()
-    print("Commands to try:")
-    print("  help - Show available commands")
-    print("  status - Show pipeline status")
-    print("  effects - List effects")
-    print("  pipeline - Show pipeline order")
-    print()
-    input("Press Enter to start...")
-
-    # Discover plugins
-    discover_plugins()
-
-    # Create pipeline with REPL effect
-    config = PipelineConfig(
-        source="headlines",
-        camera={"mode": "scroll", "speed": 1.0},
-        effects=[
-            {"name": "noise", "intensity": 0.3},
-            {"name": "fade", "intensity": 0.5},
-            {"name": "repl", "intensity": 1.0},  # Add REPL effect
-        ],
-        display={"backend": "terminal", "positioning": "mixed"},
-    )
-
-    pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-
-    # Initialize pipeline
-    if not pipeline.initialize():
-        print("Failed to initialize pipeline")
-        return
-
-    # Get the REPL effect instance
-    repl_effect = None
-    for stage in pipeline._stages.values():
-        if hasattr(stage, "_effect") and stage._effect.name == "repl":
-            repl_effect = stage._effect
-            break
-
-    if not repl_effect:
-        print("REPL effect not found in pipeline")
-        return
-
-    # Enable raw mode for input
-    display = pipeline.context.get("display")
-    if display and hasattr(display, "set_raw_mode"):
-        display.set_raw_mode(True)
-
-    # Main loop
-    try:
-        frame_count = 0
-        while True:
-            # Get keyboard input
-            if display and hasattr(display, "get_input_keys"):
-                keys = display.get_input_keys(timeout=0.01)
-                for key in keys:
-                    if key == "return":
-                        repl_effect.process_command(
-                            repl_effect.state.current_command, pipeline.context
-                        )
-                    elif key == "up":
-                        repl_effect.navigate_history(-1)
-                    elif key == "down":
-                        repl_effect.navigate_history(1)
-                    elif key == "backspace":
-                        repl_effect.backspace()
-                    elif key == "ctrl_c":
-                        raise KeyboardInterrupt
-                    elif len(key) == 1:
-                        repl_effect.append_to_command(key)
-
-            # Execute pipeline
-            result = pipeline.execute([])
-
-            if not result.success:
-                print(f"Pipeline error: {result.error}")
-                break
-
-            # Check for pending commands
-            pending = repl_effect.get_pending_command()
-            if pending:
-                print(f"\nPending command: {pending}\n")
-
-            frame_count += 1
-            time.sleep(0.033)  # ~30 FPS
-
-    except KeyboardInterrupt:
-        print("\n\nExiting REPL demo...")
-    finally:
-        # Restore terminal mode
-        if display and hasattr(display, "set_raw_mode"):
-            display.set_raw_mode(False)
-        # Cleanup pipeline
-        pipeline.cleanup()
-
-
-if __name__ == "__main__":
-    main()

examples/repl_demo_terminal.py

@@ -1,54 +0,0 @@
-#!/usr/bin/env python3
-"""
-REPL Demo with Terminal Display - Shows how to use the REPL effect
-
-Usage:
-    python examples/repl_demo_terminal.py
-
-This demonstrates the REPL effect with terminal display and interactive input.
-"""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.hybrid_config import PipelineConfig
-
-
-def main():
-    """Run REPL demo with terminal display."""
-    print("REPL Demo with Terminal Display")
-    print("=" * 50)
-
-    # Discover plugins
-    discover_plugins()
-
-    # Create a pipeline with REPL effect
-    # Using empty source so there's content to overlay on
-    config = PipelineConfig(
-        source="empty",
-        effects=[{"name": "repl", "intensity": 1.0}],
-        display="terminal",
-    )
-
-    pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-
-    # Initialize pipeline
-    if not pipeline.initialize():
-        print("Failed to initialize pipeline")
-        return
-
-    print("\nREPL is now active!")
-    print("Try typing commands:")
-    print("  help - Show available commands")
-    print("  status - Show pipeline status")
-    print("  effects - List all effects")
-    print("  pipeline - Show current pipeline order")
-    print("  clear - Clear output buffer")
-    print("\nPress Ctrl+C to exit")
-
-
-if __name__ == "__main__":
-    main()

examples/repl_simple.py

@@ -1,78 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple REPL Demo - Just shows the REPL effect rendering
-
-This is a simpler version that doesn't require raw terminal mode,
-just demonstrates the REPL effect rendering.
-"""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from engine.effects.plugins import discover_plugins
-from engine.effects.registry import get_registry
-from engine.effects.types import EffectContext
-from engine.pipeline.hybrid_config import PipelineConfig
-
-
-def main():
-    """Run simple REPL demo."""
-    print("Simple REPL Demo")
-    print("=" * 50)
-
-    # Discover plugins
-    discover_plugins()
-
-    # Create a simple pipeline with REPL
-    config = PipelineConfig(
-        source="headlines",
-        effects=[{"name": "repl", "intensity": 1.0}],
-        display={"backend": "null"},
-    )
-
-    pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-
-    # Initialize pipeline
-    if not pipeline.initialize():
-        print("Failed to initialize pipeline")
-        return
-
-    # Get the REPL effect
-    repl_effect = None
-    for stage in pipeline._stages.values():
-        if hasattr(stage, "_effect") and stage._effect.name == "repl":
-            repl_effect = stage._effect
-            break
-
-    if not repl_effect:
-        print("REPL effect not found")
-        return
-
-    # Get the EffectContext for REPL
-    # Note: In a real pipeline, the EffectContext is created per-stage
-    # For this demo, we'll simulate by adding commands
-
-    # Add some commands to the output
-    repl_effect.process_command("help")
-    repl_effect.process_command("status")
-    repl_effect.process_command("effects")
-    repl_effect.process_command("pipeline")
-
-    # Execute pipeline to see REPL output
-    result = pipeline.execute([])
-
-    if result.success:
-        print("\nPipeline Output:")
-        print("-" * 50)
-        for line in result.data:
-            print(line)
-        print("-" * 50)
-        print(f"\n✓ Successfully rendered {len(result.data)} lines")
-    else:
-        print(f"✗ Pipeline error: {result.error}")
-
-
-if __name__ == "__main__":
-    main()

examples/test_graph_integration.py

@@ -1,110 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script to verify graph-based pipeline integration.
-
-This script tests that the graph DSL can be used to create working pipelines
-that produce output similar to preset-based pipelines.
-"""
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.graph_toml import load_pipeline_from_toml
-from engine.pipeline.params import PipelineParams
-
-
-def test_graph_pipeline_execution():
-    """Test that a graph-based pipeline can execute and produce output."""
-    print("=== Testing Graph Pipeline Execution ===")
-
-    # Discover plugins
-    discover_plugins()
-
-    # Load pipeline from TOML
-    pipeline = load_pipeline_from_toml(
-        "examples/pipeline_graph.toml", viewport_width=80, viewport_height=24
-    )
-
-    print(f"Pipeline loaded with {len(pipeline._stages)} stages")
-    print(f"Stages: {list(pipeline._stages.keys())}")
-
-    # Initialize pipeline
-    if not pipeline.initialize():
-        print("Failed to initialize pipeline")
-        return False
-
-    print("Pipeline initialized successfully")
-
-    # Set up context
-    ctx = pipeline.context
-    params = PipelineParams(viewport_width=80, viewport_height=24)
-    ctx.params = params
-
-    # Execute pipeline with empty items (source will provide content)
-    result = pipeline.execute([])
-
-    if result.success:
-        print(f"Pipeline executed successfully")
-        print(f"Output type: {type(result.data)}")
-        if isinstance(result.data, list):
-            print(f"Output lines: {len(result.data)}")
-            if len(result.data) > 0:
-                print(f"First line: {result.data[0][:50]}...")
-        return True
-    else:
-        print(f"Pipeline execution failed: {result.error}")
-        return False
-
-
-def test_graph_vs_preset():
-    """Compare graph-based and preset-based pipelines."""
-    print("\n=== Comparing Graph vs Preset ===")
-
-    from engine.pipeline import get_preset
-
-    # Load graph-based pipeline
-    graph_pipeline = load_pipeline_from_toml(
-        "examples/pipeline_graph.toml", viewport_width=80, viewport_height=24
-    )
-
-    # Load preset-based pipeline (using test-basic as a base)
-    preset = get_preset("test-basic")
-    if not preset:
-        print("test-basic preset not found")
-        return False
-
-    # Create pipeline from preset config
-    from engine.pipeline import Pipeline
-
-    preset_pipeline = Pipeline(config=preset.to_config())
-
-    print(f"Graph pipeline stages: {len(graph_pipeline._stages)}")
-    print(f"Preset pipeline stages: {len(preset_pipeline._stages)}")
-
-    # Compare stage types
-    graph_stage_types = {
-        name: stage.__class__.__name__ for name, stage in graph_pipeline._stages.items()
-    }
-    preset_stage_types = {
-        name: stage.__class__.__name__
-        for name, stage in preset_pipeline._stages.items()
-    }
-
-    print("\nGraph pipeline stages:")
-    for name, stage_type in graph_stage_types.items():
-        print(f"  - {name}: {stage_type}")
-
-    print("\nPreset pipeline stages:")
-    for name, stage_type in preset_stage_types.items():
-        print(f"  - {name}: {stage_type}")
-
-    return True
-
-
-if __name__ == "__main__":
-    success1 = test_graph_pipeline_execution()
-    success2 = test_graph_vs_preset()
-
-    if success1 and success2:
-        print("\n✓ All tests passed!")
-    else:
-        print("\n✗ Some tests failed")
-        exit(1)

scripts/demo-lfo-effects.py

@@ -14,7 +14,6 @@ Effects modulated:
 The LFO uses a sine wave to oscillate intensity between 0.0 and 1.0.
 """
 
-import math
 import sys
 import time
 from dataclasses import dataclass
@@ -65,7 +64,7 @@ class LFOEffectDemo:
             angle = (
                 (elapsed * effect_cfg.frequency + effect_cfg.phase_offset) * 2 * 3.14159
             )
-            lfo_value = 0.5 + 0.5 * math.sin(angle)
+            lfo_value = 0.5 + 0.5 * (angle.__sin__())
 
             # Scale to intensity range
             intensity = effect_cfg.min_intensity + lfo_value * (

sideline/__init__.py

@@ -0,0 +1,85 @@
+"""
+Sideline - A modular pipeline framework for real-time terminal visualization.
+
+Sideline provides a Stage-based pipeline architecture with capability-based
+dependency resolution for building real-time visualization applications.
+
+Features:
+- Stage-based pipeline execution with DAG dependency resolution
+- Capability-based dependency injection
+- Display backends (Terminal, WebSocket, Null, etc.)
+- Effect plugin system with param bindings
+- Sensor framework for real-time input
+- Canvas and Camera for 2D rendering
+
+Example:
+    from sideline.pipeline import Pipeline, PipelineConfig, StageRegistry
+
+    pipeline = Pipeline(PipelineConfig(source="custom", display="terminal"))
+    pipeline.add_stage("source", MyDataSourceStage())
+    pipeline.add_stage("display", StageRegistry.create("display", "terminal"))
+    pipeline.build().initialize()
+
+    result = pipeline.execute(initial_data)
+"""
+
+__version__ = "0.1.0"
+
+# Re-export core components for convenience
+from sideline.pipeline import (
+    Pipeline,
+    PipelineConfig,
+    PipelineContext,
+    Stage,
+    StageRegistry,
+)
+
+from sideline.display import Display, DisplayRegistry
+
+from sideline.effects import Effect, EffectPlugin, EffectRegistry
+
+from sideline.plugins import (
+    StagePlugin,
+    Plugin,  # Backward compatibility
+    PluginMetadata,
+    SecurityCapability,
+    SecurityManager,
+    VersionConstraint,
+    CompatibilityManager,
+)
+
+from sideline.preset_packs import (
+    PresetPack,
+    PresetPackMetadata,
+    PresetPackManager,
+    PresetPackEncoder,
+)
+
+__all__ = [
+    # Pipeline
+    "Pipeline",
+    "PipelineConfig",
+    "PipelineContext",
+    "Stage",
+    "StageRegistry",
+    # Display
+    "Display",
+    "DisplayRegistry",
+    # Effects
+    "Effect",  # Primary class name
+    "EffectPlugin",  # Backward compatibility alias
+    "EffectRegistry",
+    # Plugins
+    "StagePlugin",
+    "Plugin",  # Backward compatibility alias
+    "PluginMetadata",
+    "SecurityCapability",
+    "SecurityManager",
+    "VersionConstraint",
+    "CompatibilityManager",
+    # Preset Packs
+    "PresetPack",
+    "PresetPackMetadata",
+    "PresetPackManager",
+    "PresetPackEncoder",
+]

sideline/camera.py

@@ -0,0 +1,473 @@
+"""
+Camera system for viewport scrolling.
+
+Provides abstraction for camera motion in different modes:
+- Vertical: traditional upward scroll
+- Horizontal: left/right movement
+- Omni: combination of both
+- Floating: sinusoidal/bobbing motion
+
+The camera defines a visible viewport into a larger Canvas.
+"""
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+
+class CameraMode(Enum):
+    FEED = auto()  # Single item view (static or rapid cycling)
+    SCROLL = auto()  # Smooth vertical scrolling (movie credits style)
+    HORIZONTAL = auto()
+    OMNI = auto()
+    FLOATING = auto()
+    BOUNCE = auto()
+    RADIAL = auto()  # Polar coordinates (r, theta) for radial scanning
+
+
+@dataclass
+class CameraViewport:
+    """Represents the visible viewport."""
+
+    x: int
+    y: int
+    width: int
+    height: int
+
+
+@dataclass
+class Camera:
+    """Camera for viewport scrolling.
+
+    The camera defines a visible viewport into a Canvas.
+    It can be smaller than the canvas to allow scrolling,
+    and supports zoom to scale the view.
+
+    Attributes:
+        x: Current horizontal offset (positive = scroll left)
+        y: Current vertical offset (positive = scroll up)
+        mode: Current camera mode
+        speed: Base scroll speed
+        zoom: Zoom factor (1.0 = 100%, 2.0 = 200% zoom out)
+        canvas_width: Width of the canvas being viewed
+        canvas_height: Height of the canvas being viewed
+        custom_update: Optional custom update function
+    """
+
+    x: int = 0
+    y: int = 0
+    mode: CameraMode = CameraMode.FEED
+    speed: float = 1.0
+    zoom: float = 1.0
+    canvas_width: int = 200  # Larger than viewport for scrolling
+    canvas_height: int = 200
+    custom_update: Callable[["Camera", float], None] | None = None
+    _x_float: float = field(default=0.0, repr=False)
+    _y_float: float = field(default=0.0, repr=False)
+    _time: float = field(default=0.0, repr=False)
+
+    @property
+    def w(self) -> int:
+        """Shorthand for viewport_width."""
+        return self.viewport_width
+
+    def set_speed(self, speed: float) -> None:
+        """Set the camera scroll speed dynamically.
+
+        This allows camera speed to be modulated during runtime
+        via PipelineParams or directly.
+
+        Args:
+            speed: New speed value (0.0 = stopped, >0 = movement)
+        """
+        self.speed = max(0.0, speed)
+
+    @property
+    def h(self) -> int:
+        """Shorthand for viewport_height."""
+        return self.viewport_height
+
+    @property
+    def viewport_width(self) -> int:
+        """Get the visible viewport width.
+
+        This is the canvas width divided by zoom.
+        """
+        return max(1, int(self.canvas_width / self.zoom))
+
+    @property
+    def viewport_height(self) -> int:
+        """Get the visible viewport height.
+
+        This is the canvas height divided by zoom.
+        """
+        return max(1, int(self.canvas_height / self.zoom))
+
+    def get_viewport(self, viewport_height: int | None = None) -> CameraViewport:
+        """Get the current viewport bounds.
+
+        Args:
+            viewport_height: Optional viewport height to use instead of camera's viewport_height
+
+        Returns:
+            CameraViewport with position and size (clamped to canvas bounds)
+        """
+        vw = self.viewport_width
+        vh = viewport_height if viewport_height is not None else self.viewport_height
+
+        clamped_x = max(0, min(self.x, self.canvas_width - vw))
+        clamped_y = max(0, min(self.y, self.canvas_height - vh))
+
+        return CameraViewport(
+            x=clamped_x,
+            y=clamped_y,
+            width=vw,
+            height=vh,
+        )
+
+        return CameraViewport(
+            x=clamped_x,
+            y=clamped_y,
+            width=vw,
+            height=vh,
+        )
+
+    def set_zoom(self, zoom: float) -> None:
+        """Set the zoom factor.
+
+        Args:
+            zoom: Zoom factor (1.0 = 100%, 2.0 = zoomed out 2x, 0.5 = zoomed in 2x)
+        """
+        self.zoom = max(0.1, min(10.0, zoom))
+
+    def update(self, dt: float) -> None:
+        """Update camera position based on mode.
+
+        Args:
+            dt: Delta time in seconds
+        """
+        self._time += dt
+
+        if self.custom_update:
+            self.custom_update(self, dt)
+            return
+
+        if self.mode == CameraMode.FEED:
+            self._update_feed(dt)
+        elif self.mode == CameraMode.SCROLL:
+            self._update_scroll(dt)
+        elif self.mode == CameraMode.HORIZONTAL:
+            self._update_horizontal(dt)
+        elif self.mode == CameraMode.OMNI:
+            self._update_omni(dt)
+        elif self.mode == CameraMode.FLOATING:
+            self._update_floating(dt)
+        elif self.mode == CameraMode.BOUNCE:
+            self._update_bounce(dt)
+        elif self.mode == CameraMode.RADIAL:
+            self._update_radial(dt)
+
+        # Bounce mode handles its own bounds checking
+        if self.mode != CameraMode.BOUNCE:
+            self._clamp_to_bounds()
+
+    def _clamp_to_bounds(self) -> None:
+        """Clamp camera position to stay within canvas bounds.
+
+        Only clamps if the viewport is smaller than the canvas.
+        If viewport equals canvas (no scrolling needed), allows any position
+        for backwards compatibility with original behavior.
+        """
+        vw = self.viewport_width
+        vh = self.viewport_height
+
+        # Only clamp if there's room to scroll
+        if vw < self.canvas_width:
+            self.x = max(0, min(self.x, self.canvas_width - vw))
+        if vh < self.canvas_height:
+            self.y = max(0, min(self.y, self.canvas_height - vh))
+
+    def _update_feed(self, dt: float) -> None:
+        """Feed mode: rapid scrolling (1 row per frame at speed=1.0)."""
+        self.y += int(self.speed * dt * 60)
+
+    def _update_scroll(self, dt: float) -> None:
+        """Scroll mode: smooth vertical scrolling with float accumulation."""
+        self._y_float += self.speed * dt * 60
+        self.y = int(self._y_float)
+
+    def _update_horizontal(self, dt: float) -> None:
+        self.x += int(self.speed * dt * 60)
+
+    def _update_omni(self, dt: float) -> None:
+        speed = self.speed * dt * 60
+        self.y += int(speed)
+        self.x += int(speed * 0.5)
+
+    def _update_floating(self, dt: float) -> None:
+        base = self.speed * 30
+        self.y = int(math.sin(self._time * 2) * base)
+        self.x = int(math.cos(self._time * 1.5) * base * 0.5)
+
+    def _update_bounce(self, dt: float) -> None:
+        """Bouncing DVD-style camera that bounces off canvas edges."""
+        vw = self.viewport_width
+        vh = self.viewport_height
+
+        # Initialize direction if not set
+        if not hasattr(self, "_bounce_dx"):
+            self._bounce_dx = 1
+            self._bounce_dy = 1
+
+        # Calculate max positions
+        max_x = max(0, self.canvas_width - vw)
+        max_y = max(0, self.canvas_height - vh)
+
+        # Move
+        move_speed = self.speed * dt * 60
+
+        # Bounce off edges - reverse direction when hitting bounds
+        self.x += int(move_speed * self._bounce_dx)
+        self.y += int(move_speed * self._bounce_dy)
+
+        # Bounce horizontally
+        if self.x <= 0:
+            self.x = 0
+            self._bounce_dx = 1
+        elif self.x >= max_x:
+            self.x = max_x
+            self._bounce_dx = -1
+
+        # Bounce vertically
+        if self.y <= 0:
+            self.y = 0
+            self._bounce_dy = 1
+        elif self.y >= max_y:
+            self.y = max_y
+            self._bounce_dy = -1
+
+    def _update_radial(self, dt: float) -> None:
+        """Radial camera mode: polar coordinate scrolling (r, theta).
+
+        The camera rotates around the center of the canvas while optionally
+        moving outward/inward along rays. This enables:
+        - Radar sweep animations
+        - Pendulum view oscillation
+        - Spiral scanning motion
+
+        Uses polar coordinates internally:
+        - _r_float: radial distance from center (accumulates smoothly)
+        - _theta_float: angle in radians (accumulates smoothly)
+        - Updates x, y based on conversion from polar to Cartesian
+        """
+        # Initialize radial state if needed
+        if not hasattr(self, "_r_float"):
+            self._r_float = 0.0
+            self._theta_float = 0.0
+
+        # Update angular position (rotation around center)
+        # Speed controls rotation rate
+        theta_speed = self.speed * dt * 1.0  # radians per second
+        self._theta_float += theta_speed
+
+        # Update radial position (inward/outward from center)
+        # Can be modulated by external sensor
+        if hasattr(self, "_radial_input"):
+            r_input = self._radial_input
+        else:
+            # Default: slow outward drift
+            r_input = 0.0
+
+        r_speed = self.speed * dt * 20.0  # pixels per second
+        self._r_float += r_input + r_speed * 0.01
+
+        # Clamp radial position to canvas bounds
+        max_r = min(self.canvas_width, self.canvas_height) / 2
+        self._r_float = max(0.0, min(self._r_float, max_r))
+
+        # Convert polar to Cartesian, centered at canvas center
+        center_x = self.canvas_width / 2
+        center_y = self.canvas_height / 2
+
+        self.x = int(center_x + self._r_float * math.cos(self._theta_float))
+        self.y = int(center_y + self._r_float * math.sin(self._theta_float))
+
+        # Clamp to canvas bounds
+        self._clamp_to_bounds()
+
+    def set_radial_input(self, value: float) -> None:
+        """Set radial input for sensor-driven radius modulation.
+
+        Args:
+            value: Sensor value (0-1) that modulates radial distance
+        """
+        self._radial_input = value * 10.0  # Scale to reasonable pixel range
+
+    def set_radial_angle(self, angle: float) -> None:
+        """Set radial angle directly (for OSC integration).
+
+        Args:
+            angle: Angle in radians (0 to 2π)
+        """
+        self._theta_float = angle
+
+    def reset(self) -> None:
+        """Reset camera position and state."""
+        self.x = 0
+        self.y = 0
+        self._time = 0.0
+        self.zoom = 1.0
+        # Reset bounce direction state
+        if hasattr(self, "_bounce_dx"):
+            self._bounce_dx = 1
+            self._bounce_dy = 1
+        # Reset radial state
+        if hasattr(self, "_r_float"):
+            self._r_float = 0.0
+            self._theta_float = 0.0
+
+    def set_canvas_size(self, width: int, height: int) -> None:
+        """Set the canvas size and clamp position if needed.
+
+        Args:
+            width: New canvas width
+            height: New canvas height
+        """
+        self.canvas_width = width
+        self.canvas_height = height
+        self._clamp_to_bounds()
+
+    def apply(
+        self, buffer: list[str], viewport_width: int, viewport_height: int | None = None
+    ) -> list[str]:
+        """Apply camera viewport to a text buffer.
+
+        Slices the buffer based on camera position (x, y) and viewport dimensions.
+        Handles ANSI escape codes correctly for colored/styled text.
+
+        Args:
+            buffer: List of strings representing lines of text
+            viewport_width: Width of the visible viewport in characters
+            viewport_height: Height of the visible viewport (overrides camera's viewport_height if provided)
+
+        Returns:
+            Sliced buffer containing only the visible lines and columns
+        """
+        from sideline.effects.legacy import vis_offset, vis_trunc
+
+        if not buffer:
+            return buffer
+
+        # Get current viewport bounds (clamped to canvas size)
+        viewport = self.get_viewport(viewport_height)
+
+        # Use provided viewport_height if given, otherwise use camera's viewport
+        vh = viewport_height if viewport_height is not None else viewport.height
+
+        # Vertical slice: extract lines that fit in viewport height
+        start_y = viewport.y
+        end_y = min(viewport.y + vh, len(buffer))
+
+        if start_y >= len(buffer):
+            # Scrolled past end of buffer, return empty viewport
+            return [""] * vh
+
+        vertical_slice = buffer[start_y:end_y]
+
+        # Horizontal slice: apply horizontal offset and truncate to width
+        horizontal_slice = []
+        for line in vertical_slice:
+            # Apply horizontal offset (skip first x characters, handling ANSI)
+            offset_line = vis_offset(line, viewport.x)
+            # Truncate to viewport width (handling ANSI)
+            truncated_line = vis_trunc(offset_line, viewport_width)
+
+            # Pad line to full viewport width to prevent ghosting when panning
+            # Skip padding for empty lines to preserve intentional blank lines
+            import re
+
+            visible_len = len(re.sub(r"\x1b\[[0-9;]*m", "", truncated_line))
+            if visible_len < viewport_width and visible_len > 0:
+                truncated_line += " " * (viewport_width - visible_len)
+
+            horizontal_slice.append(truncated_line)
+
+        # Pad with empty lines if needed to fill viewport height
+        while len(horizontal_slice) < vh:
+            horizontal_slice.append("")
+
+        return horizontal_slice
+
+    @classmethod
+    def feed(cls, speed: float = 1.0) -> "Camera":
+        """Create a feed camera (rapid single-item scrolling, 1 row/frame at speed=1.0)."""
+        return cls(mode=CameraMode.FEED, speed=speed, canvas_height=200)
+
+    @classmethod
+    def scroll(cls, speed: float = 0.5) -> "Camera":
+        """Create a smooth scrolling camera (movie credits style).
+
+        Uses float accumulation for sub-integer speeds.
+        Sets canvas_width=0 so it matches viewport_width for proper text wrapping.
+        """
+        return cls(
+            mode=CameraMode.SCROLL, speed=speed, canvas_width=0, canvas_height=200
+        )
+
+    @classmethod
+    def vertical(cls, speed: float = 1.0) -> "Camera":
+        """Deprecated: Use feed() or scroll() instead."""
+        return cls(mode=CameraMode.FEED, speed=speed, canvas_height=200)
+
+    @classmethod
+    def horizontal(cls, speed: float = 1.0) -> "Camera":
+        """Create a horizontal scrolling camera."""
+        return cls(mode=CameraMode.HORIZONTAL, speed=speed, canvas_width=200)
+
+    @classmethod
+    def omni(cls, speed: float = 1.0) -> "Camera":
+        """Create an omnidirectional scrolling camera."""
+        return cls(
+            mode=CameraMode.OMNI, speed=speed, canvas_width=200, canvas_height=200
+        )
+
+    @classmethod
+    def floating(cls, speed: float = 1.0) -> "Camera":
+        """Create a floating/bobbing camera."""
+        return cls(
+            mode=CameraMode.FLOATING, speed=speed, canvas_width=200, canvas_height=200
+        )
+
+    @classmethod
+    def bounce(cls, speed: float = 1.0) -> "Camera":
+        """Create a bouncing DVD-style camera that bounces off canvas edges."""
+        return cls(
+            mode=CameraMode.BOUNCE, speed=speed, canvas_width=200, canvas_height=200
+        )
+
+    @classmethod
+    def radial(cls, speed: float = 1.0) -> "Camera":
+        """Create a radial camera (polar coordinate scanning).
+
+        The camera rotates around the center of the canvas with smooth angular motion.
+        Enables radar sweep, pendulum view, and spiral scanning animations.
+
+        Args:
+            speed: Rotation speed (higher = faster rotation)
+
+        Returns:
+            Camera configured for radial polar coordinate scanning
+        """
+        cam = cls(
+            mode=CameraMode.RADIAL, speed=speed, canvas_width=200, canvas_height=200
+        )
+        # Initialize radial state
+        cam._r_float = 0.0
+        cam._theta_float = 0.0
+        return cam
+
+    @classmethod
+    def custom(cls, update_fn: Callable[["Camera", float], None]) -> "Camera":
+        """Create a camera with custom update function."""
+        return cls(custom_update=update_fn)

sideline/canvas.py

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

sideline/data_sources/__init__.py

@@ -0,0 +1,32 @@
+"""
+Data source types for Sideline.
+
+This module defines the data structures used by data sources.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class SourceItem:
+    """A single item from a data source."""
+
+    content: str
+    source: str
+    timestamp: str
+    metadata: Optional[dict[str, Any]] = None
+
+
+@dataclass
+class ImageItem:
+    """An image item from a data source - wraps a PIL Image."""
+
+    image: Any  # PIL Image
+    source: str
+    timestamp: str
+    path: Optional[str] = None  # File path or URL if applicable
+    metadata: Optional[dict[str, Any]] = None
+
+
+__all__ = ["SourceItem", "ImageItem"]

sideline/display/__init__.py

@@ -0,0 +1,296 @@
+"""
+Display backend system with registry pattern.
+
+Allows swapping output backends via the Display protocol.
+Supports auto-discovery of display backends.
+"""
+
+from enum import Enum, auto
+from typing import Protocol
+
+# Optional backend - requires moderngl package
+try:
+    from sideline.display.backends.moderngl import ModernGLDisplay
+
+    _MODERNGL_AVAILABLE = True
+except ImportError:
+    ModernGLDisplay = None
+    _MODERNGL_AVAILABLE = False
+
+from sideline.display.backends.multi import MultiDisplay
+from sideline.display.backends.null import NullDisplay
+from sideline.display.backends.pygame import PygameDisplay
+from sideline.display.backends.replay import ReplayDisplay
+from sideline.display.backends.terminal import TerminalDisplay
+from sideline.display.backends.websocket import WebSocketDisplay
+
+
+class BorderMode(Enum):
+    """Border rendering modes for displays."""
+
+    OFF = auto()  # No border
+    SIMPLE = auto()  # Traditional border with FPS/frame time
+    UI = auto()  # Right-side UI panel with interactive controls
+
+
+class Display(Protocol):
+    """Protocol for display backends.
+
+    Required attributes:
+    - width: int
+    - height: int
+
+    Required methods (duck typing - actual signatures may vary):
+    - init(width, height, reuse=False)
+    - show(buffer, border=False)
+    - clear()
+    - cleanup()
+    - get_dimensions() -> (width, height)
+
+    Optional attributes (for UI mode):
+    - ui_panel: UIPanel instance (set by app when border=UI)
+
+    Optional methods:
+    - is_quit_requested() -> bool
+    - clear_quit_request() -> None
+    """
+
+    width: int
+    height: int
+
+
+class DisplayRegistry:
+    """Registry for display backends with auto-discovery."""
+
+    _backends: dict[str, type[Display]] = {}
+    _initialized = False
+
+    @classmethod
+    def register(cls, name: str, backend_class: type[Display]) -> None:
+        cls._backends[name.lower()] = backend_class
+
+    @classmethod
+    def get(cls, name: str) -> type[Display] | None:
+        return cls._backends.get(name.lower())
+
+    @classmethod
+    def list_backends(cls) -> list[str]:
+        return list(cls._backends.keys())
+
+    @classmethod
+    def create(cls, name: str, **kwargs) -> Display | None:
+        cls.initialize()
+        backend_class = cls.get(name)
+        if backend_class:
+            return backend_class(**kwargs)
+        return None
+
+    @classmethod
+    def initialize(cls) -> None:
+        if cls._initialized:
+            return
+        cls.register("terminal", TerminalDisplay)
+        cls.register("null", NullDisplay)
+        cls.register("replay", ReplayDisplay)
+        cls.register("websocket", WebSocketDisplay)
+        cls.register("pygame", PygameDisplay)
+        if _MODERNGL_AVAILABLE:
+            cls.register("moderngl", ModernGLDisplay)  # type: ignore[arg-type]
+        cls._initialized = True
+
+    @classmethod
+    def create_multi(cls, names: list[str]) -> MultiDisplay | None:
+        displays = []
+        for name in names:
+            backend = cls.create(name)
+            if backend:
+                displays.append(backend)
+            else:
+                return None
+        if not displays:
+            return None
+        return MultiDisplay(displays)
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from sideline.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+def _strip_ansi(s: str) -> str:
+    """Strip ANSI escape sequences from string for length calculation."""
+    import re
+
+    return re.sub(r"\x1b\[[0-9;]*[a-zA-Z]", "", s)
+
+
+def _render_simple_border(
+    buf: list[str], width: int, height: int, fps: float = 0.0, frame_time: float = 0.0
+) -> list[str]:
+    """Render a traditional border around the buffer."""
+    if not buf or width < 3 or height < 3:
+        return buf
+
+    inner_w = width - 2
+    inner_h = height - 2
+
+    cropped = []
+    for i in range(min(inner_h, len(buf))):
+        line = buf[i]
+        visible_len = len(_strip_ansi(line))
+        if visible_len > inner_w:
+            cropped.append(line[:inner_w])
+        else:
+            cropped.append(line + " " * (inner_w - visible_len))
+
+    while len(cropped) < inner_h:
+        cropped.append(" " * inner_w)
+
+    if fps > 0:
+        fps_str = f" FPS:{fps:.0f}"
+        if len(fps_str) < inner_w:
+            right_len = inner_w - len(fps_str)
+            top_border = "┌" + "─" * right_len + fps_str + "┐"
+        else:
+            top_border = "┌" + "─" * inner_w + "┐"
+    else:
+        top_border = "┌" + "─" * inner_w + "┐"
+
+    if frame_time > 0:
+        ft_str = f" {frame_time:.1f}ms"
+        if len(ft_str) < inner_w:
+            right_len = inner_w - len(ft_str)
+            bottom_border = "└" + "─" * right_len + ft_str + "┘"
+        else:
+            bottom_border = "└" + "─" * inner_w + "┘"
+    else:
+        bottom_border = "└" + "─" * inner_w + "┘"
+
+    result = [top_border]
+    for line in cropped:
+        if len(line) < inner_w:
+            line = line + " " * (inner_w - len(line))
+        elif len(line) > inner_w:
+            line = line[:inner_w]
+        result.append("│" + line + "│")
+    result.append(bottom_border)
+
+    return result
+
+
+def render_ui_panel(
+    buf: list[str],
+    width: int,
+    height: int,
+    ui_panel,
+    fps: float = 0.0,
+    frame_time: float = 0.0,
+) -> list[str]:
+    """Render buffer with a right-side UI panel."""
+    # Note: UIPanel is in engine/pipeline/ui.py (Mainline-specific)
+    # This function is kept in sideline for compatibility but requires Mainline import
+    try:
+        from sideline.pipeline.ui import UIPanel
+    except ImportError:
+        # If UIPanel is not available, fall back to simple border
+        return _render_simple_border(buf, width, height, fps, frame_time)
+
+    if not isinstance(ui_panel, UIPanel):
+        return _render_simple_border(buf, width, height, fps, frame_time)
+
+    panel_width = min(ui_panel.config.panel_width, width - 4)
+    main_width = width - panel_width - 1
+
+    panel_lines = ui_panel.render(panel_width, height)
+
+    main_buf = buf[: height - 2]
+    main_result = _render_simple_border(
+        main_buf, main_width + 2, height, fps, frame_time
+    )
+
+    combined = []
+    for i in range(height):
+        if i < len(main_result):
+            main_line = main_result[i]
+            if len(main_line) >= 2:
+                main_content = (
+                    main_line[1:-1] if main_line[-1] in "│┌┐└┘" else main_line[1:]
+                )
+                main_content = main_content.ljust(main_width)[:main_width]
+            else:
+                main_content = " " * main_width
+        else:
+            main_content = " " * main_width
+
+        panel_idx = i
+        panel_line = (
+            panel_lines[panel_idx][:panel_width].ljust(panel_width)
+            if panel_idx < len(panel_lines)
+            else " " * panel_width
+        )
+
+        separator = "│" if 0 < i < height - 1 else "┼" if i == 0 else "┴"
+        combined.append(main_content + separator + panel_line)
+
+    return combined
+
+
+def render_border(
+    buf: list[str],
+    width: int,
+    height: int,
+    fps: float = 0.0,
+    frame_time: float = 0.0,
+    border_mode: BorderMode | bool = BorderMode.SIMPLE,
+) -> list[str]:
+    """Render a border or UI panel around the buffer.
+
+    Args:
+        buf: Input buffer
+        width: Display width
+        height: Display height
+        fps: FPS for top border
+        frame_time: Frame time for bottom border
+        border_mode: Border rendering mode
+
+    Returns:
+        Buffer with border/panel applied
+    """
+    # Normalize border_mode to BorderMode enum
+    if isinstance(border_mode, bool):
+        border_mode = BorderMode.SIMPLE if border_mode else BorderMode.OFF
+
+    if border_mode == BorderMode.UI:
+        # UI panel requires a UIPanel instance (injected separately)
+        # For now, this will be called by displays that have a ui_panel attribute
+        # This function signature doesn't include ui_panel, so we'll handle it in render_ui_panel
+        # Fall back to simple border if no panel available
+        return _render_simple_border(buf, width, height, fps, frame_time)
+    elif border_mode == BorderMode.SIMPLE:
+        return _render_simple_border(buf, width, height, fps, frame_time)
+    else:
+        return buf
+
+
+__all__ = [
+    "Display",
+    "DisplayRegistry",
+    "get_monitor",
+    "render_border",
+    "render_ui_panel",
+    "BorderMode",
+    "TerminalDisplay",
+    "NullDisplay",
+    "ReplayDisplay",
+    "WebSocketDisplay",
+    "MultiDisplay",
+    "PygameDisplay",
+]
+
+if _MODERNGL_AVAILABLE:
+    __all__.append("ModernGLDisplay")

sideline/display/backends/animation_report.py

@@ -0,0 +1,656 @@
+"""
+Animation Report Display Backend
+
+Captures frames from pipeline stages and generates an interactive HTML report
+showing before/after states for each transformative stage.
+"""
+
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from sideline.display.streaming import compute_diff
+
+
+@dataclass
+class CapturedFrame:
+    """A captured frame with metadata."""
+
+    stage: str
+    buffer: list[str]
+    timestamp: float
+    frame_number: int
+    diff_from_previous: dict[str, Any] | None = None
+
+
+@dataclass
+class StageCapture:
+    """Captures frames for a single pipeline stage."""
+
+    name: str
+    frames: list[CapturedFrame] = field(default_factory=list)
+    start_time: float = field(default_factory=time.time)
+    end_time: float = 0.0
+
+    def add_frame(
+        self,
+        buffer: list[str],
+        frame_number: int,
+        previous_buffer: list[str] | None = None,
+    ) -> None:
+        """Add a captured frame."""
+        timestamp = time.time()
+        diff = None
+        if previous_buffer is not None:
+            diff_data = compute_diff(previous_buffer, buffer)
+            diff = {
+                "changed_lines": len(diff_data.changed_lines),
+                "total_lines": len(buffer),
+                "width": diff_data.width,
+                "height": diff_data.height,
+            }
+
+        frame = CapturedFrame(
+            stage=self.name,
+            buffer=list(buffer),
+            timestamp=timestamp,
+            frame_number=frame_number,
+            diff_from_previous=diff,
+        )
+        self.frames.append(frame)
+
+    def finish(self) -> None:
+        """Mark capture as finished."""
+        self.end_time = time.time()
+
+
+class AnimationReportDisplay:
+    """
+    Display backend that captures frames for animation report generation.
+
+    Instead of rendering to terminal, this display captures the buffer at each
+    stage and stores it for later HTML report generation.
+    """
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(self, output_dir: str = "./reports"):
+        """
+        Initialize the animation report display.
+
+        Args:
+            output_dir: Directory where reports will be saved
+        """
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        self._stages: dict[str, StageCapture] = {}
+        self._current_stage: str = ""
+        self._previous_buffer: list[str] | None = None
+        self._frame_number: int = 0
+        self._total_frames: int = 0
+        self._start_time: float = 0.0
+
+    def init(self, width: int, height: int, reuse: bool = False) -> None:
+        """Initialize display with dimensions."""
+        self.width = width
+        self.height = height
+        self._start_time = time.time()
+
+    def show(self, buffer: list[str], border: bool = False) -> None:
+        """
+        Capture a frame for the current stage.
+
+        Args:
+            buffer: The frame buffer to capture
+            border: Border flag (ignored)
+        """
+        if not self._current_stage:
+            # If no stage is set, use a default name
+            self._current_stage = "final"
+
+        if self._current_stage not in self._stages:
+            self._stages[self._current_stage] = StageCapture(self._current_stage)
+
+        stage = self._stages[self._current_stage]
+        stage.add_frame(buffer, self._frame_number, self._previous_buffer)
+
+        self._previous_buffer = list(buffer)
+        self._frame_number += 1
+        self._total_frames += 1
+
+    def start_stage(self, stage_name: str) -> None:
+        """
+        Start capturing frames for a new stage.
+
+        Args:
+            stage_name: Name of the stage (e.g., "noise", "fade", "firehose")
+        """
+        if self._current_stage and self._current_stage in self._stages:
+            # Finish previous stage
+            self._stages[self._current_stage].finish()
+
+        self._current_stage = stage_name
+        self._previous_buffer = None  # Reset for new stage
+
+    def clear(self) -> None:
+        """Clear the display (no-op for report display)."""
+        pass
+
+    def cleanup(self) -> None:
+        """Cleanup resources."""
+        # Finish current stage
+        if self._current_stage and self._current_stage in self._stages:
+            self._stages[self._current_stage].finish()
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current dimensions."""
+        return (self.width, self.height)
+
+    def get_stages(self) -> dict[str, StageCapture]:
+        """Get all captured stages."""
+        return self._stages
+
+    def generate_report(self, title: str = "Animation Report") -> Path:
+        """
+        Generate an HTML report with captured frames and animations.
+
+        Args:
+            title: Title of the report
+
+        Returns:
+            Path to the generated HTML file
+        """
+        report_path = self.output_dir / f"animation_report_{int(time.time())}.html"
+        html_content = self._build_html(title)
+        report_path.write_text(html_content)
+        return report_path
+
+    def _build_html(self, title: str) -> str:
+        """Build the HTML content for the report."""
+        # Collect all frames across stages
+        all_frames = []
+        for stage_name, stage in self._stages.items():
+            for frame in stage.frames:
+                all_frames.append(frame)
+
+        # Sort frames by timestamp
+        all_frames.sort(key=lambda f: f.timestamp)
+
+        # Build stage sections
+        stages_html = ""
+        for stage_name, stage in self._stages.items():
+            stages_html += self._build_stage_section(stage_name, stage)
+
+        # Build full HTML
+        html = f"""
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{title}</title>
+    <style>
+        * {{
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }}
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: #1a1a2e;
+            color: #eee;
+            padding: 20px;
+            line-height: 1.6;
+        }}
+        .container {{
+            max-width: 1400px;
+            margin: 0 auto;
+        }}
+        .header {{
+            background: linear-gradient(135deg, #16213e 0%, #1a1a2e 100%);
+            padding: 30px;
+            border-radius: 12px;
+            margin-bottom: 30px;
+            text-align: center;
+            box-shadow: 0 4px 20px rgba(0,0,0,0.3);
+        }}
+        .header h1 {{
+            font-size: 2.5em;
+            margin-bottom: 10px;
+            background: linear-gradient(90deg, #00d4ff, #00ff88);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+            background-clip: text;
+        }}
+        .header .meta {{
+            color: #888;
+            font-size: 0.9em;
+        }}
+        .stats-grid {{
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+            gap: 15px;
+            margin: 20px 0;
+        }}
+        .stat-card {{
+            background: #16213e;
+            padding: 15px;
+            border-radius: 8px;
+            text-align: center;
+        }}
+        .stat-value {{
+            font-size: 1.8em;
+            font-weight: bold;
+            color: #00ff88;
+        }}
+        .stat-label {{
+            color: #888;
+            font-size: 0.85em;
+            margin-top: 5px;
+        }}
+        .stage-section {{
+            background: #16213e;
+            border-radius: 12px;
+            margin-bottom: 25px;
+            overflow: hidden;
+            box-shadow: 0 2px 10px rgba(0,0,0,0.2);
+        }}
+        .stage-header {{
+            background: #1f2a48;
+            padding: 15px 20px;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            cursor: pointer;
+            user-select: none;
+        }}
+        .stage-header:hover {{
+            background: #253252;
+        }}
+        .stage-name {{
+            font-weight: bold;
+            font-size: 1.1em;
+            color: #00d4ff;
+        }}
+        .stage-info {{
+            color: #888;
+            font-size: 0.9em;
+        }}
+        .stage-content {{
+            padding: 20px;
+        }}
+        .frames-container {{
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+            gap: 15px;
+        }}
+        .frame-card {{
+            background: #0f0f1a;
+            border-radius: 8px;
+            overflow: hidden;
+            border: 1px solid #333;
+            transition: transform 0.2s, box-shadow 0.2s;
+        }}
+        .frame-card:hover {{
+            transform: translateY(-2px);
+            box-shadow: 0 4px 15px rgba(0,212,255,0.2);
+        }}
+        .frame-header {{
+            background: #1a1a2e;
+            padding: 10px 15px;
+            font-size: 0.85em;
+            color: #888;
+            border-bottom: 1px solid #333;
+            display: flex;
+            justify-content: space-between;
+        }}
+        .frame-number {{
+            color: #00ff88;
+        }}
+        .frame-diff {{
+            color: #ff6b6b;
+        }}
+        .frame-content {{
+            padding: 10px;
+            font-family: 'Fira Code', 'Consolas', 'Monaco', monospace;
+            font-size: 11px;
+            line-height: 1.3;
+            white-space: pre;
+            overflow-x: auto;
+            max-height: 200px;
+            overflow-y: auto;
+        }}
+        .timeline-section {{
+            background: #16213e;
+            border-radius: 12px;
+            padding: 20px;
+            margin-bottom: 25px;
+        }}
+        .timeline-header {{
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 15px;
+        }}
+        .timeline-title {{
+            font-weight: bold;
+            color: #00d4ff;
+        }}
+        .timeline-controls {{
+            display: flex;
+            gap: 10px;
+        }}
+        .timeline-controls button {{
+            background: #1f2a48;
+            border: 1px solid #333;
+            color: #eee;
+            padding: 8px 15px;
+            border-radius: 6px;
+            cursor: pointer;
+            transition: all 0.2s;
+        }}
+        .timeline-controls button:hover {{
+            background: #253252;
+            border-color: #00d4ff;
+        }}
+        .timeline-controls button.active {{
+            background: #00d4ff;
+            color: #000;
+        }}
+        .timeline-canvas {{
+            width: 100%;
+            height: 100px;
+            background: #0f0f1a;
+            border-radius: 8px;
+            position: relative;
+            overflow: hidden;
+        }}
+        .timeline-track {{
+            position: absolute;
+            top: 50%;
+            left: 0;
+            right: 0;
+            height: 4px;
+            background: #333;
+            transform: translateY(-50%);
+        }}
+        .timeline-marker {{
+            position: absolute;
+            top: 50%;
+            transform: translate(-50%, -50%);
+            width: 12px;
+            height: 12px;
+            background: #00d4ff;
+            border-radius: 50%;
+            cursor: pointer;
+            transition: all 0.2s;
+        }}
+        .timeline-marker:hover {{
+            transform: translate(-50%, -50%) scale(1.3);
+            box-shadow: 0 0 10px #00d4ff;
+        }}
+        .timeline-marker.stage-{{stage_name}} {{
+            background: var(--stage-color, #00d4ff);
+        }}
+        .comparison-view {{
+            display: grid;
+            grid-template-columns: 1fr 1fr;
+            gap: 20px;
+            margin-top: 20px;
+        }}
+        .comparison-panel {{
+            background: #0f0f1a;
+            border-radius: 8px;
+            padding: 15px;
+            border: 1px solid #333;
+        }}
+        .comparison-panel h4 {{
+            color: #888;
+            margin-bottom: 10px;
+            font-size: 0.9em;
+        }}
+        .comparison-content {{
+            font-family: 'Fira Code', 'Consolas', 'Monaco', monospace;
+            font-size: 11px;
+            line-height: 1.3;
+            white-space: pre;
+        }}
+        .diff-added {{
+            background: rgba(0, 255, 136, 0.2);
+        }}
+        .diff-removed {{
+            background: rgba(255, 107, 107, 0.2);
+        }}
+        @keyframes pulse {{
+            0%, 100% {{ opacity: 1; }}
+            50% {{ opacity: 0.7; }}
+        }}
+        .animating {{
+            animation: pulse 1s infinite;
+        }}
+        .footer {{
+            text-align: center;
+            color: #666;
+            padding: 20px;
+            font-size: 0.9em;
+        }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>🎬 {title}</h1>
+            <div class="meta">
+                Generated: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")} |
+                Total Frames: {self._total_frames} |
+                Duration: {time.time() - self._start_time:.2f}s
+            </div>
+            <div class="stats-grid">
+                <div class="stat-card">
+                    <div class="stat-value">{len(self._stages)}</div>
+                    <div class="stat-label">Pipeline Stages</div>
+                </div>
+                <div class="stat-card">
+                    <div class="stat-value">{self._total_frames}</div>
+                    <div class="stat-label">Total Frames</div>
+                </div>
+                <div class="stat-card">
+                    <div class="stat-value">{time.time() - self._start_time:.2f}s</div>
+                    <div class="stat-label">Capture Duration</div>
+                </div>
+                <div class="stat-card">
+                    <div class="stat-value">{self.width}x{self.height}</div>
+                    <div class="stat-label">Resolution</div>
+                </div>
+            </div>
+        </div>
+
+        <div class="timeline-section">
+            <div class="timeline-header">
+                <div class="timeline-title">Timeline</div>
+                <div class="timeline-controls">
+                    <button onclick="playAnimation()">▶ Play</button>
+                    <button onclick="pauseAnimation()">⏸ Pause</button>
+                    <button onclick="stepForward()">⏭ Step</button>
+                </div>
+            </div>
+            <div class="timeline-canvas" id="timeline">
+                <div class="timeline-track"></div>
+                <!-- Timeline markers will be added by JavaScript -->
+            </div>
+        </div>
+
+        {stages_html}
+
+        <div class="footer">
+            <p>Animation Report generated by Mainline</p>
+            <p>Use the timeline controls above to play/pause the animation</p>
+        </div>
+    </div>
+
+    <script>
+        // Animation state
+        let currentFrame = 0;
+        let isPlaying = false;
+        let animationInterval = null;
+        const totalFrames = {len(all_frames)};
+
+        // Stage colors for timeline markers
+        const stageColors = {{
+            {self._build_stage_colors()}
+        }};
+
+        // Initialize timeline
+        function initTimeline() {{
+            const timeline = document.getElementById('timeline');
+            const track = timeline.querySelector('.timeline-track');
+
+            {self._build_timeline_markers(all_frames)}
+        }}
+
+        function playAnimation() {{
+            if (isPlaying) return;
+            isPlaying = true;
+            animationInterval = setInterval(() => {{
+                currentFrame = (currentFrame + 1) % totalFrames;
+                updateFrameDisplay();
+            }}, 100);
+        }}
+
+        function pauseAnimation() {{
+            isPlaying = false;
+            if (animationInterval) {{
+                clearInterval(animationInterval);
+                animationInterval = null;
+            }}
+        }}
+
+        function stepForward() {{
+            currentFrame = (currentFrame + 1) % totalFrames;
+            updateFrameDisplay();
+        }}
+
+        function updateFrameDisplay() {{
+            // Highlight current frame in timeline
+            const markers = document.querySelectorAll('.timeline-marker');
+            markers.forEach((marker, index) => {{
+                if (index === currentFrame) {{
+                    marker.style.transform = 'translate(-50%, -50%) scale(1.5)';
+                    marker.style.boxShadow = '0 0 15px #00ff88';
+                }} else {{
+                    marker.style.transform = 'translate(-50%, -50%) scale(1)';
+                    marker.style.boxShadow = 'none';
+                }}
+            }});
+        }}
+
+        // Initialize on page load
+        document.addEventListener('DOMContentLoaded', initTimeline);
+    </script>
+</body>
+</html>
+"""
+        return html
+
+    def _build_stage_section(self, stage_name: str, stage: StageCapture) -> str:
+        """Build HTML for a single stage section."""
+        frames_html = ""
+        for i, frame in enumerate(stage.frames):
+            diff_info = ""
+            if frame.diff_from_previous:
+                changed = frame.diff_from_previous.get("changed_lines", 0)
+                total = frame.diff_from_previous.get("total_lines", 0)
+                diff_info = f'<span class="frame-diff">Δ {changed}/{total}</span>'
+
+            frames_html += f"""
+            <div class="frame-card">
+                <div class="frame-header">
+                    <span>Frame <span class="frame-number">{frame.frame_number}</span></span>
+                    {diff_info}
+                </div>
+                <div class="frame-content">{self._escape_html("".join(frame.buffer))}</div>
+            </div>
+            """
+
+        return f"""
+        <div class="stage-section">
+            <div class="stage-header" onclick="this.nextElementSibling.classList.toggle('hidden')">
+                <span class="stage-name">{stage_name}</span>
+                <span class="stage-info">{len(stage.frames)} frames</span>
+            </div>
+            <div class="stage-content">
+                <div class="frames-container">
+                    {frames_html}
+                </div>
+            </div>
+        </div>
+        """
+
+    def _build_timeline(self, all_frames: list[CapturedFrame]) -> str:
+        """Build timeline HTML."""
+        if not all_frames:
+            return ""
+
+        markers_html = ""
+        for i, frame in enumerate(all_frames):
+            left_percent = (i / len(all_frames)) * 100
+            markers_html += f'<div class="timeline-marker" style="left: {left_percent}%" data-frame="{i}"></div>'
+
+        return markers_html
+
+    def _build_stage_colors(self) -> str:
+        """Build stage color mapping for JavaScript."""
+        colors = [
+            "#00d4ff",
+            "#00ff88",
+            "#ff6b6b",
+            "#ffd93d",
+            "#a855f7",
+            "#ec4899",
+            "#14b8a6",
+            "#f97316",
+            "#8b5cf6",
+            "#06b6d4",
+        ]
+        color_map = ""
+        for i, stage_name in enumerate(self._stages.keys()):
+            color = colors[i % len(colors)]
+            color_map += f'            "{stage_name}": "{color}",\n'
+        return color_map.rstrip(",\n")
+
+    def _build_timeline_markers(self, all_frames: list[CapturedFrame]) -> str:
+        """Build timeline markers in JavaScript."""
+        if not all_frames:
+            return ""
+
+        markers_js = ""
+        for i, frame in enumerate(all_frames):
+            left_percent = (i / len(all_frames)) * 100
+            stage_color = f"stageColors['{frame.stage}']"
+            markers_js += f"""
+            const marker{i} = document.createElement('div');
+            marker{i}.className = 'timeline-marker stage-{{frame.stage}}';
+            marker{i}.style.left = '{left_percent}%';
+            marker{i}.style.setProperty('--stage-color', {stage_color});
+            marker{i}.onclick = () => {{
+                currentFrame = {i};
+                updateFrameDisplay();
+            }};
+            timeline.appendChild(marker{i});
+            """
+
+        return markers_js
+
+    def _escape_html(self, text: str) -> str:
+        """Escape HTML special characters."""
+        return (
+            text.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+            .replace("'", "&#39;")
+        )

sideline/display/backends/multi.py

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

sideline/display/backends/null.py

@@ -0,0 +1,183 @@
+"""
+Null/headless display backend.
+"""
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+
+class NullDisplay:
+    """Headless/null display - discards all output.
+
+    This display does nothing - useful for headless benchmarking
+    or when no display output is needed. Captures last buffer
+    for testing purposes. Supports frame recording for replay
+    and file export/import.
+    """
+
+    width: int = 80
+    height: int = 24
+    _last_buffer: list[str] | None = None
+
+    def __init__(self):
+        self._last_buffer = None
+        self._is_recording = False
+        self._recorded_frames: list[dict[str, Any]] = []
+        self._frame_count = 0
+
+    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
+        self._last_buffer = None
+
+    def show(self, buffer: list[str], border: bool = False) -> None:
+        import sys
+
+        from sideline.display import get_monitor, render_border
+
+        fps = 0.0
+        frame_time = 0.0
+        monitor = get_monitor()
+        if monitor:
+            stats = monitor.get_stats()
+            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
+            frame_count = stats.get("frame_count", 0) if stats else 0
+            if avg_ms and frame_count > 0:
+                fps = 1000.0 / avg_ms
+                frame_time = avg_ms
+
+        if border:
+            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
+
+        self._last_buffer = buffer
+
+        if self._is_recording:
+            self._recorded_frames.append(
+                {
+                    "frame_number": self._frame_count,
+                    "buffer": buffer,
+                    "width": self.width,
+                    "height": self.height,
+                }
+            )
+
+        if self._frame_count <= 5 or self._frame_count % 10 == 0:
+            sys.stdout.write("\n" + "=" * 80 + "\n")
+            sys.stdout.write(
+                f"Frame {self._frame_count} (buffer height: {len(buffer)})\n"
+            )
+            sys.stdout.write("=" * 80 + "\n")
+            for i, line in enumerate(buffer[:30]):
+                sys.stdout.write(f"{i:2}: {line}\n")
+            if len(buffer) > 30:
+                sys.stdout.write(f"... ({len(buffer) - 30} more lines)\n")
+            sys.stdout.flush()
+
+        if monitor:
+            t0 = time.perf_counter()
+            chars_in = sum(len(line) for line in buffer)
+            elapsed_ms = (time.perf_counter() - t0) * 1000
+            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
+
+        self._frame_count += 1
+
+    def start_recording(self) -> None:
+        """Begin recording frames."""
+        self._is_recording = True
+        self._recorded_frames = []
+
+    def stop_recording(self) -> None:
+        """Stop recording frames."""
+        self._is_recording = False
+
+    def get_frames(self) -> list[list[str]]:
+        """Get recorded frames as list of buffers.
+
+        Returns:
+            List of buffers, each buffer is a list of strings (lines)
+        """
+        return [frame["buffer"] for frame in self._recorded_frames]
+
+    def get_recorded_data(self) -> list[dict[str, Any]]:
+        """Get full recorded data including metadata.
+
+        Returns:
+            List of frame dicts with 'frame_number', 'buffer', 'width', 'height'
+        """
+        return self._recorded_frames
+
+    def clear_recording(self) -> None:
+        """Clear recorded frames."""
+        self._recorded_frames = []
+
+    def save_recording(self, filepath: str | Path) -> None:
+        """Save recorded frames to a JSON file.
+
+        Args:
+            filepath: Path to save the recording
+        """
+        path = Path(filepath)
+        data = {
+            "version": 1,
+            "display": "null",
+            "width": self.width,
+            "height": self.height,
+            "frame_count": len(self._recorded_frames),
+            "frames": self._recorded_frames,
+        }
+        path.write_text(json.dumps(data, indent=2))
+
+    def load_recording(self, filepath: str | Path) -> list[dict[str, Any]]:
+        """Load recorded frames from a JSON file.
+
+        Args:
+            filepath: Path to load the recording from
+
+        Returns:
+            List of frame dicts
+        """
+        path = Path(filepath)
+        data = json.loads(path.read_text())
+        self._recorded_frames = data.get("frames", [])
+        self.width = data.get("width", 80)
+        self.height = data.get("height", 24)
+        return self._recorded_frames
+
+    def replay_frames(self) -> list[list[str]]:
+        """Get frames for replay.
+
+        Returns:
+            List of buffers for replay
+        """
+        return self.get_frames()
+
+    def clear(self) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current dimensions.
+
+        Returns:
+            (width, height) in character cells
+        """
+        return (self.width, self.height)
+
+    def is_quit_requested(self) -> bool:
+        """Check if quit was requested (optional protocol method)."""
+        return False
+
+    def clear_quit_request(self) -> None:
+        """Clear quit request (optional protocol method)."""
+        pass

sideline/display/backends/pygame.py

@@ -0,0 +1,369 @@
+"""
+Pygame display backend - renders to a native application window.
+"""
+
+import time
+
+from sideline.display.renderer import parse_ansi
+
+
+class PygameDisplay:
+    """Pygame display backend - renders to native window.
+
+    Supports reuse mode - when reuse=True, skips SDL initialization
+    and reuses the existing pygame window from a previous instance.
+    """
+
+    width: int = 80
+    window_width: int = 800
+    window_height: int = 600
+
+    def __init__(
+        self,
+        cell_width: int = 10,
+        cell_height: int = 18,
+        window_width: int = 800,
+        window_height: int = 600,
+        target_fps: float = 30.0,
+    ):
+        self.width = 80
+        self.height = 24
+        self.cell_width = cell_width
+        self.cell_height = cell_height
+        self.window_width = window_width
+        self.window_height = window_height
+        self.target_fps = target_fps
+        self._initialized = False
+        self._pygame = None
+        self._screen = None
+        self._font = None
+        self._resized = False
+        self._quit_requested = False
+        self._last_frame_time = 0.0
+        self._frame_period = 1.0 / target_fps if target_fps > 0 else 0
+        self._glyph_cache = {}
+
+    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
+
+        try:
+            import pygame
+        except ImportError:
+            return
+
+        if reuse and PygameDisplay._pygame_initialized:
+            self._pygame = pygame
+            self._initialized = True
+            return
+
+        pygame.init()
+        pygame.display.set_caption("Mainline")
+
+        self._screen = pygame.display.set_mode(
+            (self.window_width, self.window_height),
+            pygame.RESIZABLE,
+        )
+        self._pygame = pygame
+        PygameDisplay._pygame_initialized = True
+
+        # Calculate character dimensions from actual window size
+        self.width = max(1, self.window_width // self.cell_width)
+        self.height = max(1, self.window_height // self.cell_height)
+
+        font_path = self._get_font_path()
+        if font_path:
+            try:
+                self._font = pygame.font.Font(font_path, self.cell_height - 2)
+            except Exception:
+                self._font = pygame.font.SysFont("monospace", self.cell_height - 2)
+        else:
+            self._font = pygame.font.SysFont("monospace", self.cell_height - 2)
+
+        # Check if font supports box-drawing characters; if not, try to find one
+        self._use_fallback_border = False
+        if self._font:
+            try:
+                # Test rendering some key box-drawing characters
+                test_chars = ["┌", "─", "┐", "│", "└", "┘"]
+                for ch in test_chars:
+                    surf = self._font.render(ch, True, (255, 255, 255))
+                    # If surface is empty (width=0 or all black), font lacks glyph
+                    if surf.get_width() == 0:
+                        raise ValueError("Missing glyph")
+            except Exception:
+                # Font doesn't support box-drawing, will use line drawing fallback
+                self._use_fallback_border = True
+
+        self._initialized = True
+
+    def show(self, buffer: list[str], border: bool = False) -> None:
+        if not self._initialized or not self._pygame:
+            return
+
+        t0 = time.perf_counter()
+
+        for event in self._pygame.event.get():
+            if event.type == self._pygame.QUIT:
+                self._quit_requested = True
+            elif event.type == self._pygame.KEYDOWN:
+                if event.key in (self._pygame.K_ESCAPE, self._pygame.K_c):
+                    if event.key == self._pygame.K_c and not (
+                        event.mod & self._pygame.KMOD_LCTRL
+                        or event.mod & self._pygame.KMOD_RCTRL
+                    ):
+                        continue
+                    self._quit_requested = True
+            elif event.type == self._pygame.VIDEORESIZE:
+                self.window_width = event.w
+                self.window_height = event.h
+                self.width = max(1, self.window_width // self.cell_width)
+                self.height = max(1, self.window_height // self.cell_height)
+                self._resized = True
+
+        # FPS limiting - skip frame if we're going too fast
+        if self._frame_period > 0:
+            now = time.perf_counter()
+            elapsed = now - self._last_frame_time
+            if elapsed < self._frame_period:
+                return  # Skip this frame
+            self._last_frame_time = now
+
+        # Get metrics for border display
+        fps = 0.0
+        frame_time = 0.0
+        from sideline.display import get_monitor
+
+        monitor = get_monitor()
+        if monitor:
+            stats = monitor.get_stats()
+            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
+            frame_count = stats.get("frame_count", 0) if stats else 0
+            if avg_ms and frame_count > 0:
+                fps = 1000.0 / avg_ms
+                frame_time = avg_ms
+
+        self._screen.fill((0, 0, 0))
+
+        # If border requested but font lacks box-drawing glyphs, use graphical fallback
+        if border and self._use_fallback_border:
+            self._draw_fallback_border(fps, frame_time)
+            # Adjust content area to fit inside border
+            content_offset_x = self.cell_width
+            content_offset_y = self.cell_height
+            self.window_width - 2 * self.cell_width
+            self.window_height - 2 * self.cell_height
+        else:
+            # Normal rendering (with or without text border)
+            content_offset_x = 0
+            content_offset_y = 0
+
+            if border:
+                from sideline.display import render_border
+
+                buffer = render_border(buffer, self.width, self.height, fps, frame_time)
+
+        blit_list = []
+
+        for row_idx, line in enumerate(buffer[: self.height]):
+            if row_idx >= self.height:
+                break
+
+            tokens = parse_ansi(line)
+            x_pos = content_offset_x
+
+            for text, fg, bg, _bold in tokens:
+                if not text:
+                    continue
+
+                # Use None as key for no background
+                bg_key = bg if bg != (0, 0, 0) else None
+                cache_key = (text, fg, bg_key)
+
+                if cache_key not in self._glyph_cache:
+                    # Render and cache
+                    if bg_key is not None:
+                        self._glyph_cache[cache_key] = self._font.render(
+                            text, True, fg, bg_key
+                        )
+                    else:
+                        self._glyph_cache[cache_key] = self._font.render(text, True, fg)
+
+                surface = self._glyph_cache[cache_key]
+                blit_list.append(
+                    (surface, (x_pos, content_offset_y + row_idx * self.cell_height))
+                )
+                x_pos += self._font.size(text)[0]
+
+        self._screen.blits(blit_list)
+
+        # Draw fallback border using graphics if needed
+        if border and self._use_fallback_border:
+            self._draw_fallback_border(fps, frame_time)
+
+        self._pygame.display.flip()
+
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("pygame_display", elapsed_ms, chars_in, chars_in)
+
+    def _draw_fallback_border(self, fps: float, frame_time: float) -> None:
+        """Draw border using pygame graphics primitives instead of text."""
+        if not self._screen or not self._pygame:
+            return
+
+        # Colors
+        border_color = (0, 255, 0)  # Green (like terminal border)
+        text_color = (255, 255, 255)
+
+        # Calculate dimensions
+        x1 = 0
+        y1 = 0
+        x2 = self.window_width - 1
+        y2 = self.window_height - 1
+
+        # Draw outer rectangle
+        self._pygame.draw.rect(
+            self._screen, border_color, (x1, y1, x2 - x1 + 1, y2 - y1 + 1), 1
+        )
+
+        # Draw top border with FPS
+        if fps > 0:
+            fps_text = f" FPS:{fps:.0f}"
+        else:
+            fps_text = ""
+        # We need to render this text with a fallback font that has basic ASCII
+        # Use system font which should have these characters
+        try:
+            font = self._font  # May not have box chars but should have alphanumeric
+            text_surf = font.render(fps_text, True, text_color, (0, 0, 0))
+            text_rect = text_surf.get_rect()
+            # Position on top border, right-aligned
+            text_x = x2 - text_rect.width - 5
+            text_y = y1 + 2
+            self._screen.blit(text_surf, (text_x, text_y))
+        except Exception:
+            pass
+
+        # Draw bottom border with frame time
+        if frame_time > 0:
+            ft_text = f" {frame_time:.1f}ms"
+            try:
+                ft_surf = self._font.render(ft_text, True, text_color, (0, 0, 0))
+                ft_rect = ft_surf.get_rect()
+                ft_x = x2 - ft_rect.width - 5
+                ft_y = y2 - ft_rect.height - 2
+                self._screen.blit(ft_surf, (ft_x, ft_y))
+            except Exception:
+                pass
+
+    def clear(self) -> None:
+        if self._screen and self._pygame:
+            self._screen.fill((0, 0, 0))
+            self._pygame.display.flip()
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current terminal dimensions based on window size.
+
+        Returns:
+            (width, height) in character cells
+        """
+        # Query actual window size and recalculate character cells
+        if self._screen and self._pygame:
+            try:
+                w, h = self._screen.get_size()
+                if w != self.window_width or h != self.window_height:
+                    self.window_width = w
+                    self.window_height = h
+                    self.width = max(1, w // self.cell_width)
+                    self.height = max(1, h // self.cell_height)
+            except Exception:
+                pass
+        return self.width, self.height
+
+    def cleanup(self, quit_pygame: bool = True) -> None:
+        """Cleanup display resources.
+
+        Args:
+            quit_pygame: If True, quit pygame entirely. Set to False when
+                        reusing the display to avoid closing shared window.
+        """
+        if quit_pygame and self._pygame:
+            self._pygame.quit()
+            PygameDisplay._pygame_initialized = False
+
+    @classmethod
+    def reset_state(cls) -> None:
+        """Reset pygame state - useful for testing."""
+        cls._pygame_initialized = False
+
+    def is_quit_requested(self) -> bool:
+        """Check if user requested quit (Ctrl+C, Ctrl+Q, or Escape).
+
+        Returns True if the user pressed Ctrl+C, Ctrl+Q, or Escape.
+        The main loop should check this and raise KeyboardInterrupt.
+        """
+        return self._quit_requested
+
+    def clear_quit_request(self) -> bool:
+        """Clear the quit request flag after handling.
+
+        Returns the previous quit request state.
+        """
+        was_requested = self._quit_requested
+        self._quit_requested = False
+        return was_requested

sideline/display/backends/replay.py

@@ -0,0 +1,122 @@
+"""
+Replay display backend - plays back recorded frames.
+"""
+
+from typing import Any
+
+
+class ReplayDisplay:
+    """Replay display - plays back recorded frames.
+
+    This display reads frames from a recording (list of frame data)
+    and yields them sequentially, useful for testing and demo purposes.
+    """
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(self):
+        self._frames: list[dict[str, Any]] = []
+        self._current_frame = 0
+        self._playback_index = 0
+        self._loop = False
+
+    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 ReplayDisplay
+        """
+        self.width = width
+        self.height = height
+
+    def set_frames(self, frames: list[dict[str, Any]]) -> None:
+        """Set frames to replay.
+
+        Args:
+            frames: List of frame dicts with 'buffer', 'width', 'height'
+        """
+        self._frames = frames
+        self._current_frame = 0
+        self._playback_index = 0
+
+    def set_loop(self, loop: bool) -> None:
+        """Set loop playback mode.
+
+        Args:
+            loop: True to loop, False to stop at end
+        """
+        self._loop = loop
+
+    def show(self, buffer: list[str], border: bool = False) -> None:
+        """Display a frame (ignored in replay mode).
+
+        Args:
+            buffer: Buffer to display (ignored)
+            border: Border flag (ignored)
+        """
+        pass
+
+    def get_next_frame(self) -> list[str] | None:
+        """Get the next frame in the recording.
+
+        Returns:
+            Buffer list of strings, or None if playback is done
+        """
+        if not self._frames:
+            return None
+
+        if self._playback_index >= len(self._frames):
+            if self._loop:
+                self._playback_index = 0
+            else:
+                return None
+
+        frame = self._frames[self._playback_index]
+        self._playback_index += 1
+        return frame.get("buffer")
+
+    def reset(self) -> None:
+        """Reset playback to the beginning."""
+        self._playback_index = 0
+
+    def seek(self, index: int) -> None:
+        """Seek to a specific frame.
+
+        Args:
+            index: Frame index to seek to
+        """
+        if 0 <= index < len(self._frames):
+            self._playback_index = index
+
+    def is_finished(self) -> bool:
+        """Check if playback is finished.
+
+        Returns:
+            True if at end of frames and not looping
+        """
+        return not self._loop and self._playback_index >= len(self._frames)
+
+    def clear(self) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current dimensions.
+
+        Returns:
+            (width, height) in character cells
+        """
+        return (self.width, self.height)
+
+    def is_quit_requested(self) -> bool:
+        """Check if quit was requested (optional protocol method)."""
+        return False
+
+    def clear_quit_request(self) -> None:
+        """Clear quit request (optional protocol method)."""
+        pass

sideline/display/backends/terminal.py

@@ -0,0 +1,161 @@
+"""
+ANSI terminal display backend.
+"""
+
+import os
+
+
+class TerminalDisplay:
+    """ANSI terminal display backend.
+
+    Renders buffer to stdout using ANSI escape codes.
+    Supports reuse - when reuse=True, skips re-initializing terminal state.
+    Auto-detects terminal dimensions on init.
+    """
+
+    width: int = 80
+    height: int = 24
+    _initialized: bool = False
+
+    def __init__(self, target_fps: float = 30.0):
+        self.target_fps = target_fps
+        self._frame_period = 1.0 / target_fps if target_fps > 0 else 0
+        self._last_frame_time = 0.0
+        self._cached_dimensions: tuple[int, int] | None = None
+
+    def init(self, width: int, height: int, reuse: bool = False) -> None:
+        """Initialize display with dimensions.
+
+        If width/height are not provided (0/None), auto-detects terminal size.
+        Otherwise uses provided dimensions or falls back to terminal size
+        if the provided dimensions exceed terminal capacity.
+
+        Args:
+            width: Desired terminal width (0 = auto-detect)
+            height: Desired terminal height (0 = auto-detect)
+            reuse: If True, skip terminal re-initialization
+        """
+        from sideline.terminal import CURSOR_OFF
+
+        # Auto-detect terminal size (handle case where no terminal)
+        try:
+            term_size = os.get_terminal_size()
+            term_width = term_size.columns
+            term_height = term_size.lines
+        except OSError:
+            # No terminal available (e.g., in tests)
+            term_width = width if width > 0 else 80
+            term_height = height if height > 0 else 24
+
+        # Use provided dimensions if valid, otherwise use terminal size
+        if width > 0 and height > 0:
+            self.width = min(width, term_width)
+            self.height = min(height, term_height)
+        else:
+            self.width = term_width
+            self.height = term_height
+
+        if not reuse or not self._initialized:
+            print(CURSOR_OFF, end="", flush=True)
+            self._initialized = True
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current terminal dimensions.
+
+        Returns cached dimensions to avoid querying terminal every frame,
+        which can cause inconsistent results. Dimensions are only refreshed
+        when they actually change.
+
+        Returns:
+            (width, height) in character cells
+        """
+        try:
+            term_size = os.get_terminal_size()
+            new_dims = (term_size.columns, term_size.lines)
+        except OSError:
+            new_dims = (self.width, self.height)
+
+        # Only update cached dimensions if they actually changed
+        if self._cached_dimensions is None or self._cached_dimensions != new_dims:
+            self._cached_dimensions = new_dims
+            self.width = new_dims[0]
+            self.height = new_dims[1]
+
+        return self._cached_dimensions
+
+    def show(
+        self, buffer: list[str], border: bool = False, positioning: str = "mixed"
+    ) -> None:
+        """Display buffer with optional border and positioning mode.
+
+        Args:
+            buffer: List of lines to display
+            border: Whether to apply border
+            positioning: Positioning mode - "mixed" (default), "absolute", or "relative"
+        """
+        import sys
+
+        from sideline.display import get_monitor, render_border
+
+        # Note: Frame rate limiting is handled by the caller (e.g., FrameTimer).
+        # This display renders every frame it receives.
+
+        # Get metrics for border display
+        fps = 0.0
+        frame_time = 0.0
+        monitor = get_monitor()
+        if monitor:
+            stats = monitor.get_stats()
+            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
+            frame_count = stats.get("frame_count", 0) if stats else 0
+            if avg_ms and frame_count > 0:
+                fps = 1000.0 / avg_ms
+                frame_time = avg_ms
+
+        # Apply border if requested
+        from sideline.display import BorderMode
+
+        if border and border != BorderMode.OFF:
+            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
+
+        # Apply positioning based on mode
+        if positioning == "absolute":
+            # All lines should have cursor positioning codes
+            # Join with newlines (cursor codes already in buffer)
+            output = "\033[H\033[J" + "\n".join(buffer)
+        elif positioning == "relative":
+            # Remove cursor positioning codes (except colors) and join with newlines
+            import re
+
+            cleaned_buffer = []
+            for line in buffer:
+                # Remove cursor positioning codes but keep color codes
+                # Pattern: \033[row;colH or \033[row;col;...H
+                cleaned = re.sub(r"\033\[[0-9;]*H", "", line)
+                cleaned_buffer.append(cleaned)
+            output = "\033[H\033[J" + "\n".join(cleaned_buffer)
+        else:  # mixed (default)
+            # Current behavior: join with newlines
+            # Effects that need absolute positioning have their own cursor codes
+            output = "\033[H\033[J" + "\n".join(buffer)
+
+        sys.stdout.buffer.write(output.encode())
+        sys.stdout.flush()
+
+    def clear(self) -> None:
+        from sideline.terminal import CLR
+
+        print(CLR, end="", flush=True)
+
+    def cleanup(self) -> None:
+        from sideline.terminal import CURSOR_ON
+
+        print(CURSOR_ON, end="", flush=True)
+
+    def is_quit_requested(self) -> bool:
+        """Check if quit was requested (optional protocol method)."""
+        return False
+
+    def clear_quit_request(self) -> None:
+        """Clear quit request (optional protocol method)."""
+        pass

sideline/display/backends/websocket.py

@@ -0,0 +1,464 @@
+"""
+WebSocket display backend - broadcasts frame buffer to connected web clients.
+
+Supports streaming protocols:
+- Full frame (JSON) - default for compatibility
+- Binary streaming - efficient binary protocol
+- Diff streaming - only sends changed lines
+
+TODO: Transform to a true streaming backend with:
+- Proper WebSocket message streaming (currently sends full buffer each frame)
+- Connection pooling and backpressure handling
+- Binary protocol for efficiency (instead of JSON)
+- Client management with proper async handling
+- Mark for deprecation if replaced by a new streaming implementation
+
+Current implementation: Simple broadcast of text frames to all connected clients.
+"""
+
+import asyncio
+import base64
+import json
+import threading
+import time
+from enum import IntFlag
+
+from sideline.display.streaming import (
+    MessageType,
+    compress_frame,
+    compute_diff,
+    encode_binary_message,
+    encode_diff_message,
+)
+
+
+class StreamingMode(IntFlag):
+    """Streaming modes for WebSocket display."""
+
+    JSON = 0x01  # Full JSON frames (default, compatible)
+    BINARY = 0x02  # Binary compression
+    DIFF = 0x04  # Differential updates
+
+
+try:
+    import websockets
+except ImportError:
+    websockets = None
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from sideline.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+class WebSocketDisplay:
+    """WebSocket display backend - broadcasts to HTML Canvas clients."""
+
+    width: int = 80
+    height: int = 24
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8765,
+        http_port: int = 8766,
+        streaming_mode: StreamingMode = StreamingMode.JSON,
+    ):
+        self.host = host
+        self.port = port
+        self.http_port = http_port
+        self.width = 80
+        self.height = 24
+        self._clients: set = set()
+        self._server_running = False
+        self._http_running = False
+        self._server_thread: threading.Thread | None = None
+        self._http_thread: threading.Thread | None = None
+        self._available = True
+        self._max_clients = 10
+        self._client_connected_callback = None
+        self._client_disconnected_callback = None
+        self._command_callback = None
+        self._controller = None  # Reference to UI panel or pipeline controller
+        self._frame_delay = 0.0
+        self._httpd = None  # HTTP server instance
+
+        # Streaming configuration
+        self._streaming_mode = streaming_mode
+        self._last_buffer: list[str] = []
+        self._client_capabilities: dict = {}  # Track client capabilities
+
+        try:
+            import websockets as _ws
+
+            self._available = _ws is not None
+        except ImportError:
+            self._available = False
+
+    def is_available(self) -> bool:
+        """Check if WebSocket support is available."""
+        return self._available
+
+    def init(self, width: int, height: int, reuse: bool = False) -> None:
+        """Initialize display with dimensions and start server.
+
+        Args:
+            width: Terminal width in characters
+            height: Terminal height in rows
+            reuse: If True, skip starting servers (assume already running)
+        """
+        self.width = width
+        self.height = height
+
+        if not reuse or not self._server_running:
+            self.start_server()
+            self.start_http_server()
+
+    def show(self, buffer: list[str], border: bool = False) -> None:
+        """Broadcast buffer to all connected clients using streaming protocol."""
+        t0 = time.perf_counter()
+
+        # Get metrics for border display
+        fps = 0.0
+        frame_time = 0.0
+        monitor = get_monitor()
+        if monitor:
+            stats = monitor.get_stats()
+            avg_ms = stats.get("pipeline", {}).get("avg_ms", 0) if stats else 0
+            frame_count = stats.get("frame_count", 0) if stats else 0
+            if avg_ms and frame_count > 0:
+                fps = 1000.0 / avg_ms
+                frame_time = avg_ms
+
+        # Apply border if requested
+        if border:
+            from sideline.display import render_border
+
+            buffer = render_border(buffer, self.width, self.height, fps, frame_time)
+
+        if not self._clients:
+            self._last_buffer = buffer
+            return
+
+        # Send to each client based on their capabilities
+        disconnected = set()
+        for client in list(self._clients):
+            try:
+                client_id = id(client)
+                client_mode = self._client_capabilities.get(
+                    client_id, StreamingMode.JSON
+                )
+
+                if client_mode & StreamingMode.DIFF:
+                    self._send_diff_frame(client, buffer)
+                elif client_mode & StreamingMode.BINARY:
+                    self._send_binary_frame(client, buffer)
+                else:
+                    self._send_json_frame(client, buffer)
+            except Exception:
+                disconnected.add(client)
+
+        for client in disconnected:
+            self._clients.discard(client)
+            if self._client_disconnected_callback:
+                self._client_disconnected_callback(client)
+
+        self._last_buffer = buffer
+
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("websocket_display", elapsed_ms, chars_in, chars_in)
+
+    def _send_json_frame(self, client, buffer: list[str]) -> None:
+        """Send frame as JSON."""
+        frame_data = {
+            "type": "frame",
+            "width": self.width,
+            "height": self.height,
+            "lines": buffer,
+        }
+        message = json.dumps(frame_data)
+        asyncio.run(client.send(message))
+
+    def _send_binary_frame(self, client, buffer: list[str]) -> None:
+        """Send frame as compressed binary."""
+        compressed = compress_frame(buffer)
+        message = encode_binary_message(
+            MessageType.FULL_FRAME, self.width, self.height, compressed
+        )
+        encoded = base64.b64encode(message).decode("utf-8")
+        asyncio.run(client.send(encoded))
+
+    def _send_diff_frame(self, client, buffer: list[str]) -> None:
+        """Send frame as diff."""
+        diff = compute_diff(self._last_buffer, buffer)
+
+        if not diff.changed_lines:
+            return
+
+        diff_payload = encode_diff_message(diff)
+        message = encode_binary_message(
+            MessageType.DIFF_FRAME, self.width, self.height, diff_payload
+        )
+        encoded = base64.b64encode(message).decode("utf-8")
+        asyncio.run(client.send(encoded))
+
+    def set_streaming_mode(self, mode: StreamingMode) -> None:
+        """Set the default streaming mode for new clients."""
+        self._streaming_mode = mode
+
+    def get_streaming_mode(self) -> StreamingMode:
+        """Get the current streaming mode."""
+        return self._streaming_mode
+
+    def clear(self) -> None:
+        """Broadcast clear command to all clients."""
+        if self._clients:
+            clear_data = {"type": "clear"}
+            message = json.dumps(clear_data)
+            for client in list(self._clients):
+                try:
+                    asyncio.run(client.send(message))
+                except Exception:
+                    pass
+
+    def cleanup(self) -> None:
+        """Stop the servers."""
+        self.stop_server()
+        self.stop_http_server()
+
+    async def _websocket_handler(self, websocket):
+        """Handle WebSocket connections."""
+        if len(self._clients) >= self._max_clients:
+            await websocket.close()
+            return
+
+        self._clients.add(websocket)
+        if self._client_connected_callback:
+            self._client_connected_callback(websocket)
+
+        try:
+            async for message in websocket:
+                try:
+                    data = json.loads(message)
+                    msg_type = data.get("type")
+
+                    if msg_type == "resize":
+                        self.width = data.get("width", 80)
+                        self.height = data.get("height", 24)
+                    elif msg_type == "command" and self._command_callback:
+                        # Forward commands to the pipeline controller
+                        command = data.get("command", {})
+                        self._command_callback(command)
+                    elif msg_type == "state_request":
+                        # Send current state snapshot
+                        state = self._get_state_snapshot()
+                        if state:
+                            response = {"type": "state", "state": state}
+                            await websocket.send(json.dumps(response))
+                except json.JSONDecodeError:
+                    pass
+        except Exception:
+            pass
+        finally:
+            self._clients.discard(websocket)
+            if self._client_disconnected_callback:
+                self._client_disconnected_callback(websocket)
+
+    async def _run_websocket_server(self):
+        """Run the WebSocket server."""
+        if not websockets:
+            return
+        async with websockets.serve(self._websocket_handler, self.host, self.port):
+            while self._server_running:
+                await asyncio.sleep(0.1)
+
+    async def _run_http_server(self):
+        """Run simple HTTP server for the client."""
+        import os
+        from http.server import HTTPServer, SimpleHTTPRequestHandler
+
+        # Find the project root by locating 'engine' directory in the path
+        websocket_file = os.path.abspath(__file__)
+        parts = websocket_file.split(os.sep)
+        if "engine" in parts:
+            engine_idx = parts.index("engine")
+            project_root = os.sep.join(parts[:engine_idx])
+            client_dir = os.path.join(project_root, "client")
+        else:
+            # Fallback: go up 4 levels from websocket.py
+            # websocket.py: .../engine/display/backends/websocket.py
+            # We need: .../client
+            client_dir = os.path.join(
+                os.path.dirname(
+                    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+                ),
+                "client",
+            )
+
+        class Handler(SimpleHTTPRequestHandler):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, directory=client_dir, **kwargs)
+
+            def log_message(self, format, *args):
+                pass
+
+        httpd = HTTPServer((self.host, self.http_port), Handler)
+        # Store reference for shutdown
+        self._httpd = httpd
+        # Serve requests continuously
+        httpd.serve_forever()
+
+    def _run_async(self, coro):
+        """Run coroutine in background."""
+        try:
+            asyncio.run(coro)
+        except Exception as e:
+            print(f"WebSocket async error: {e}")
+
+    def start_server(self):
+        """Start the WebSocket server in a background thread."""
+        if not self._available:
+            return
+        if self._server_thread is not None:
+            return
+
+        self._server_running = True
+        self._server_thread = threading.Thread(
+            target=self._run_async, args=(self._run_websocket_server(),), daemon=True
+        )
+        self._server_thread.start()
+
+    def stop_server(self):
+        """Stop the WebSocket server."""
+        self._server_running = False
+        self._server_thread = None
+
+    def start_http_server(self):
+        """Start the HTTP server in a background thread."""
+        if not self._available:
+            return
+        if self._http_thread is not None:
+            return
+
+        self._http_running = True
+
+        self._http_running = True
+        self._http_thread = threading.Thread(
+            target=self._run_async, args=(self._run_http_server(),), daemon=True
+        )
+        self._http_thread.start()
+
+    def stop_http_server(self):
+        """Stop the HTTP server."""
+        self._http_running = False
+        if hasattr(self, "_httpd") and self._httpd:
+            self._httpd.shutdown()
+        self._http_thread = None
+
+    def client_count(self) -> int:
+        """Return number of connected clients."""
+        return len(self._clients)
+
+    def get_ws_port(self) -> int:
+        """Return WebSocket port."""
+        return self.port
+
+    def get_http_port(self) -> int:
+        """Return HTTP port."""
+        return self.http_port
+
+    def set_frame_delay(self, delay: float) -> None:
+        """Set delay between frames in seconds."""
+        self._frame_delay = delay
+
+    def get_frame_delay(self) -> float:
+        """Get delay between frames."""
+        return self._frame_delay
+
+    def set_client_connected_callback(self, callback) -> None:
+        """Set callback for client connections."""
+        self._client_connected_callback = callback
+
+    def set_client_disconnected_callback(self, callback) -> None:
+        """Set callback for client disconnections."""
+        self._client_disconnected_callback = callback
+
+    def set_command_callback(self, callback) -> None:
+        """Set callback for incoming command messages from clients."""
+        self._command_callback = callback
+
+    def set_controller(self, controller) -> None:
+        """Set controller (UI panel or pipeline) for state queries and command execution."""
+        self._controller = controller
+
+    def broadcast_state(self, state: dict) -> None:
+        """Broadcast state update to all connected clients.
+
+        Args:
+            state: Dictionary containing state data to send to clients
+        """
+        if not self._clients:
+            return
+
+        message = json.dumps({"type": "state", "state": state})
+
+        disconnected = set()
+        for client in list(self._clients):
+            try:
+                asyncio.run(client.send(message))
+            except Exception:
+                disconnected.add(client)
+
+        for client in disconnected:
+            self._clients.discard(client)
+            if self._client_disconnected_callback:
+                self._client_disconnected_callback(client)
+
+    def _get_state_snapshot(self) -> dict | None:
+        """Get current state snapshot from controller."""
+        if not self._controller:
+            return None
+
+        try:
+            # Expect controller to have methods we need
+            state = {}
+
+            # Get stages info if UIPanel
+            if hasattr(self._controller, "stages"):
+                state["stages"] = {
+                    name: {
+                        "enabled": ctrl.enabled,
+                        "params": ctrl.params,
+                        "selected": ctrl.selected,
+                    }
+                    for name, ctrl in self._controller.stages.items()
+                }
+
+            # Get current preset
+            if hasattr(self._controller, "_current_preset"):
+                state["preset"] = self._controller._current_preset
+            if hasattr(self._controller, "_presets"):
+                state["presets"] = self._controller._presets
+
+            # Get selected stage
+            if hasattr(self._controller, "selected_stage"):
+                state["selected_stage"] = self._controller.selected_stage
+
+            return state
+        except Exception:
+            return None
+
+    def get_dimensions(self) -> tuple[int, int]:
+        """Get current dimensions.
+
+        Returns:
+            (width, height) in character cells
+        """
+        return (self.width, self.height)

sideline/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

sideline/display/streaming.py

@@ -0,0 +1,268 @@
+"""
+Streaming protocol utilities for efficient frame transmission.
+
+Provides:
+- Frame differencing: Only send changed lines
+- Run-length encoding: Compress repeated lines
+- Binary encoding: Compact message format
+"""
+
+import json
+import zlib
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class MessageType(IntEnum):
+    """Message types for streaming protocol."""
+
+    FULL_FRAME = 1
+    DIFF_FRAME = 2
+    STATE = 3
+    CLEAR = 4
+    PING = 5
+    PONG = 6
+
+
+@dataclass
+class FrameDiff:
+    """Represents a diff between two frames."""
+
+    width: int
+    height: int
+    changed_lines: list[tuple[int, str]]  # (line_index, content)
+
+
+def compute_diff(old_buffer: list[str], new_buffer: list[str]) -> FrameDiff:
+    """Compute differences between old and new buffer.
+
+    Args:
+        old_buffer: Previous frame buffer
+        new_buffer: Current frame buffer
+
+    Returns:
+        FrameDiff with only changed lines
+    """
+    height = len(new_buffer)
+    changed_lines = []
+
+    for i, line in enumerate(new_buffer):
+        if i >= len(old_buffer) or line != old_buffer[i]:
+            changed_lines.append((i, line))
+
+    return FrameDiff(
+        width=len(new_buffer[0]) if new_buffer else 0,
+        height=height,
+        changed_lines=changed_lines,
+    )
+
+
+def encode_rle(lines: list[tuple[int, str]]) -> list[tuple[int, str, int]]:
+    """Run-length encode consecutive identical lines.
+
+    Args:
+        lines: List of (index, content) tuples (must be sorted by index)
+
+    Returns:
+        List of (start_index, content, run_length) tuples
+    """
+    if not lines:
+        return []
+
+    encoded = []
+    start_idx = lines[0][0]
+    current_line = lines[0][1]
+    current_rle = 1
+
+    for idx, line in lines[1:]:
+        if line == current_line:
+            current_rle += 1
+        else:
+            encoded.append((start_idx, current_line, current_rle))
+            start_idx = idx
+            current_line = line
+            current_rle = 1
+
+    encoded.append((start_idx, current_line, current_rle))
+    return encoded
+
+
+def decode_rle(encoded: list[tuple[int, str, int]]) -> list[tuple[int, str]]:
+    """Decode run-length encoded lines.
+
+    Args:
+        encoded: List of (start_index, content, run_length) tuples
+
+    Returns:
+        List of (index, content) tuples
+    """
+    result = []
+    for start_idx, line, rle in encoded:
+        for i in range(rle):
+            result.append((start_idx + i, line))
+    return result
+
+
+def compress_frame(buffer: list[str], level: int = 6) -> bytes:
+    """Compress a frame buffer using zlib.
+
+    Args:
+        buffer: Frame buffer (list of lines)
+        level: Compression level (0-9)
+
+    Returns:
+        Compressed bytes
+    """
+    content = "\n".join(buffer)
+    return zlib.compress(content.encode("utf-8"), level)
+
+
+def decompress_frame(data: bytes, height: int) -> list[str]:
+    """Decompress a frame buffer.
+
+    Args:
+        data: Compressed bytes
+        height: Number of lines in original buffer
+
+    Returns:
+        Frame buffer (list of lines)
+    """
+    content = zlib.decompress(data).decode("utf-8")
+    lines = content.split("\n")
+    if len(lines) > height:
+        lines = lines[:height]
+    while len(lines) < height:
+        lines.append("")
+    return lines
+
+
+def encode_binary_message(
+    msg_type: MessageType, width: int, height: int, payload: bytes
+) -> bytes:
+    """Encode a binary message.
+
+    Message format:
+    - 1 byte: message type
+    - 2 bytes: width (uint16)
+    - 2 bytes: height (uint16)
+    - 4 bytes: payload length (uint32)
+    - N bytes: payload
+
+    Args:
+        msg_type: Message type
+        width: Frame width
+        height: Frame height
+        payload: Message payload
+
+    Returns:
+        Encoded binary message
+    """
+    import struct
+
+    header = struct.pack("!BHHI", msg_type.value, width, height, len(payload))
+    return header + payload
+
+
+def decode_binary_message(data: bytes) -> tuple[MessageType, int, int, bytes]:
+    """Decode a binary message.
+
+    Args:
+        data: Binary message data
+
+    Returns:
+        Tuple of (msg_type, width, height, payload)
+    """
+    import struct
+
+    msg_type_val, width, height, payload_len = struct.unpack("!BHHI", data[:9])
+    payload = data[9 : 9 + payload_len]
+    return MessageType(msg_type_val), width, height, payload
+
+
+def encode_diff_message(diff: FrameDiff, use_rle: bool = True) -> bytes:
+    """Encode a diff message for transmission.
+
+    Args:
+        diff: Frame diff
+        use_rle: Whether to use run-length encoding
+
+    Returns:
+        Encoded diff payload
+    """
+
+    if use_rle:
+        encoded_lines = encode_rle(diff.changed_lines)
+        data = [[idx, line, rle] for idx, line, rle in encoded_lines]
+    else:
+        data = [[idx, line] for idx, line in diff.changed_lines]
+
+    payload = json.dumps(data).encode("utf-8")
+    return payload
+
+
+def decode_diff_message(payload: bytes, use_rle: bool = True) -> list[tuple[int, str]]:
+    """Decode a diff message.
+
+    Args:
+        payload: Encoded diff payload
+        use_rle: Whether run-length encoding was used
+
+    Returns:
+        List of (line_index, content) tuples
+    """
+
+    data = json.loads(payload.decode("utf-8"))
+
+    if use_rle:
+        return decode_rle([(idx, line, rle) for idx, line, rle in data])
+    else:
+        return [(idx, line) for idx, line in data]
+
+
+def should_use_diff(
+    old_buffer: list[str], new_buffer: list[str], threshold: float = 0.3
+) -> bool:
+    """Determine if diff or full frame is more efficient.
+
+    Args:
+        old_buffer: Previous frame
+        new_buffer: Current frame
+        threshold: Max changed ratio to use diff (0.0-1.0)
+
+    Returns:
+        True if diff is more efficient
+    """
+    if not old_buffer or not new_buffer:
+        return False
+
+    diff = compute_diff(old_buffer, new_buffer)
+    total_lines = len(new_buffer)
+    changed_ratio = len(diff.changed_lines) / total_lines if total_lines > 0 else 1.0
+
+    return changed_ratio <= threshold
+
+
+def apply_diff(old_buffer: list[str], diff: FrameDiff) -> list[str]:
+    """Apply a diff to an old buffer to get the new buffer.
+
+    Args:
+        old_buffer: Previous frame buffer
+        diff: Frame diff to apply
+
+    Returns:
+        New frame buffer
+    """
+    new_buffer = list(old_buffer)
+
+    for line_idx, content in diff.changed_lines:
+        if line_idx < len(new_buffer):
+            new_buffer[line_idx] = content
+        else:
+            while len(new_buffer) < line_idx:
+                new_buffer.append("")
+            new_buffer.append(content)
+
+    while len(new_buffer) < diff.height:
+        new_buffer.append("")
+
+    return new_buffer[: diff.height]

sideline/effects/__init__.py

@@ -0,0 +1,27 @@
+from sideline.effects.chain import EffectChain
+from sideline.effects.performance import PerformanceMonitor, get_monitor, set_monitor
+from sideline.effects.registry import EffectRegistry, get_registry, set_registry
+from sideline.effects.types import (
+    EffectConfig,
+    EffectContext,
+    Effect,
+    EffectPlugin,  # Backward compatibility alias
+    create_effect_context,
+)
+
+# Note: Legacy effects and controller are Mainline-specific and moved to engine/effects/
+
+__all__ = [
+    "EffectChain",
+    "EffectRegistry",
+    "EffectConfig",
+    "EffectContext",
+    "Effect",  # Primary class name
+    "EffectPlugin",  # Backward compatibility alias
+    "create_effect_context",
+    "get_registry",
+    "set_registry",
+    "get_monitor",
+    "set_monitor",
+    "PerformanceMonitor",
+]

sideline/effects/chain.py

@@ -0,0 +1,87 @@
+import time
+
+from sideline.effects.performance import PerformanceMonitor, get_monitor
+from sideline.effects.registry import EffectRegistry
+from sideline.effects.types import EffectContext, PartialUpdate
+
+
+class EffectChain:
+    def __init__(
+        self, registry: EffectRegistry, monitor: PerformanceMonitor | None = None
+    ):
+        self._registry = registry
+        self._order: list[str] = []
+        self._monitor = monitor
+
+    def _get_monitor(self) -> PerformanceMonitor:
+        if self._monitor is not None:
+            return self._monitor
+        return get_monitor()
+
+    def set_order(self, names: list[str]) -> None:
+        self._order = list(names)
+
+    def get_order(self) -> list[str]:
+        return self._order.copy()
+
+    def add_effect(self, name: str, position: int | None = None) -> bool:
+        if name not in self._registry.list_all():
+            return False
+        if position is None:
+            self._order.append(name)
+        else:
+            self._order.insert(position, name)
+        return True
+
+    def remove_effect(self, name: str) -> bool:
+        if name in self._order:
+            self._order.remove(name)
+            return True
+        return False
+
+    def reorder(self, new_order: list[str]) -> bool:
+        all_plugins = set(self._registry.list_all().keys())
+        if not all(name in all_plugins for name in new_order):
+            return False
+        self._order = list(new_order)
+        return True
+
+    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
+        monitor = self._get_monitor()
+        frame_number = ctx.frame_number
+        monitor.start_frame(frame_number)
+
+        # Get dirty regions from canvas via context (set by CanvasStage)
+        dirty_rows = ctx.get_state("canvas.dirty_rows")
+
+        # Create PartialUpdate for effects that support it
+        full_buffer = dirty_rows is None or len(dirty_rows) == 0
+        partial = PartialUpdate(
+            rows=None,
+            cols=None,
+            dirty=dirty_rows,
+            full_buffer=full_buffer,
+        )
+
+        frame_start = time.perf_counter()
+        result = list(buf)
+        for name in self._order:
+            plugin = self._registry.get(name)
+            if plugin and plugin.config.enabled:
+                chars_in = sum(len(line) for line in result)
+                effect_start = time.perf_counter()
+                try:
+                    # Use process_partial if supported, otherwise fall back to process
+                    if getattr(plugin, "supports_partial_updates", False):
+                        result = plugin.process_partial(result, ctx, partial)
+                    else:
+                        result = plugin.process(result, ctx)
+                except Exception:
+                    plugin.config.enabled = False
+                elapsed = time.perf_counter() - effect_start
+                chars_out = sum(len(line) for line in result)
+                monitor.record_effect(name, elapsed * 1000, chars_in, chars_out)
+
+        total_elapsed = time.perf_counter() - frame_start
+        monitor.end_frame(frame_number, total_elapsed * 1000)
+        return result

sideline/effects/performance.py

@@ -0,0 +1,103 @@
+from collections import deque
+from dataclasses import dataclass
+
+
+@dataclass
+class EffectTiming:
+    name: str
+    duration_ms: float
+    buffer_chars_in: int
+    buffer_chars_out: int
+
+
+@dataclass
+class FrameTiming:
+    frame_number: int
+    total_ms: float
+    effects: list[EffectTiming]
+
+
+class PerformanceMonitor:
+    """Collects and stores performance metrics for effect pipeline."""
+
+    def __init__(self, max_frames: int = 60):
+        self._max_frames = max_frames
+        self._frames: deque[FrameTiming] = deque(maxlen=max_frames)
+        self._current_frame: list[EffectTiming] = []
+
+    def start_frame(self, frame_number: int) -> None:
+        self._current_frame = []
+
+    def record_effect(
+        self, name: str, duration_ms: float, chars_in: int, chars_out: int
+    ) -> None:
+        self._current_frame.append(
+            EffectTiming(
+                name=name,
+                duration_ms=duration_ms,
+                buffer_chars_in=chars_in,
+                buffer_chars_out=chars_out,
+            )
+        )
+
+    def end_frame(self, frame_number: int, total_ms: float) -> None:
+        self._frames.append(
+            FrameTiming(
+                frame_number=frame_number,
+                total_ms=total_ms,
+                effects=self._current_frame,
+            )
+        )
+
+    def get_stats(self) -> dict:
+        if not self._frames:
+            return {"error": "No timing data available"}
+
+        total_times = [f.total_ms for f in self._frames]
+        avg_total = sum(total_times) / len(total_times)
+        min_total = min(total_times)
+        max_total = max(total_times)
+
+        effect_stats: dict[str, dict] = {}
+        for frame in self._frames:
+            for effect in frame.effects:
+                if effect.name not in effect_stats:
+                    effect_stats[effect.name] = {"times": [], "total_chars": 0}
+                effect_stats[effect.name]["times"].append(effect.duration_ms)
+                effect_stats[effect.name]["total_chars"] += effect.buffer_chars_out
+
+        for name, stats in effect_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._frames),
+            "pipeline": {
+                "avg_ms": avg_total,
+                "min_ms": min_total,
+                "max_ms": max_total,
+            },
+            "effects": effect_stats,
+        }
+
+    def reset(self) -> None:
+        self._frames.clear()
+        self._current_frame = []
+
+
+_monitor: PerformanceMonitor | None = None
+
+
+def get_monitor() -> PerformanceMonitor:
+    global _monitor
+    if _monitor is None:
+        _monitor = PerformanceMonitor()
+    return _monitor
+
+
+def set_monitor(monitor: PerformanceMonitor) -> None:
+    global _monitor
+    _monitor = monitor

sideline/effects/registry.py

@@ -0,0 +1,59 @@
+from sideline.effects.types import EffectConfig, EffectPlugin
+
+
+class EffectRegistry:
+    def __init__(self):
+        self._plugins: dict[str, EffectPlugin] = {}
+        self._discovered: bool = False
+
+    def register(self, plugin: EffectPlugin) -> None:
+        self._plugins[plugin.name] = plugin
+
+    def get(self, name: str) -> EffectPlugin | None:
+        return self._plugins.get(name)
+
+    def list_all(self) -> dict[str, EffectPlugin]:
+        return self._plugins.copy()
+
+    def list_enabled(self) -> list[EffectPlugin]:
+        return [p for p in self._plugins.values() if p.config.enabled]
+
+    def enable(self, name: str) -> bool:
+        plugin = self._plugins.get(name)
+        if plugin:
+            plugin.config.enabled = True
+            return True
+        return False
+
+    def disable(self, name: str) -> bool:
+        plugin = self._plugins.get(name)
+        if plugin:
+            plugin.config.enabled = False
+            return True
+        return False
+
+    def configure(self, name: str, config: EffectConfig) -> bool:
+        plugin = self._plugins.get(name)
+        if plugin:
+            plugin.configure(config)
+            return True
+        return False
+
+    def is_enabled(self, name: str) -> bool:
+        plugin = self._plugins.get(name)
+        return plugin.config.enabled if plugin else False
+
+
+_registry: EffectRegistry | None = None
+
+
+def get_registry() -> EffectRegistry:
+    global _registry
+    if _registry is None:
+        _registry = EffectRegistry()
+    return _registry
+
+
+def set_registry(registry: EffectRegistry) -> None:
+    global _registry
+    _registry = registry

sideline/effects/types.py

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

sideline/fonts/__init__.py

@@ -0,0 +1,38 @@
+"""
+Sideline font configuration.
+
+Provides default fonts for block letter rendering.
+"""
+
+import os
+from pathlib import Path
+
+# Directory containing Sideline fonts
+FONTS_DIR = Path(__file__).parent
+
+# Default font for block letter rendering
+DEFAULT_FONT = FONTS_DIR / "Corptic.otf"
+
+# Font size for default rendering
+DEFAULT_FONT_SIZE = 32
+
+
+def get_default_font_path() -> str:
+    """Get path to default font file."""
+    if DEFAULT_FONT.exists():
+        return str(DEFAULT_FONT)
+    raise FileNotFoundError(f"Default font not found: {DEFAULT_FONT}")
+
+
+def get_default_font_size() -> int:
+    """Get default font size."""
+    return DEFAULT_FONT_SIZE
+
+
+__all__ = [
+    "get_default_font_path",
+    "get_default_font_size",
+    "DEFAULT_FONT",
+    "DEFAULT_FONT_SIZE",
+    "FONTS_DIR",
+]

sideline/pipeline/__init__.py

@@ -0,0 +1,94 @@
+"""
+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
+- Plugin system: Support for external stage plugins
+
+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)
+
+Plugin System:
+    Plugins can be registered explicitly or discovered automatically via entry points.
+    Applications can register their own stages using StageRegistry.register() or
+    StageRegistry.register_plugin().
+
+Example:
+    from sideline.pipeline import Pipeline, PipelineConfig, StageRegistry
+
+    # Register application-specific stages
+    StageRegistry.register("source", MyDataSource)
+
+    # Or discover plugins automatically
+    StageRegistry.discover_plugins()
+
+    pipeline = Pipeline(PipelineConfig(source="my_source", display="terminal"))
+    pipeline.add_stage("source", StageRegistry.create("source", "my_source"))
+    pipeline.add_stage("display", StageRegistry.create("display", "terminal"))
+    pipeline.build().initialize()
+
+    result = pipeline.execute(initial_data)
+"""
+
+from sideline.pipeline.controller import (
+    Pipeline,
+    PipelineConfig,
+    PipelineRunner,
+    create_default_pipeline,
+    create_pipeline_from_params,
+)
+from sideline.pipeline.core import (
+    PipelineContext,
+    Stage,
+    StageConfig,
+    StageError,
+    StageResult,
+)
+from sideline.pipeline.params import (
+    DEFAULT_HEADLINE_PARAMS,
+    DEFAULT_PIPELINE_PARAMS,
+    DEFAULT_PYGAME_PARAMS,
+    PipelineParams,
+)
+from sideline.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",
+    # Registry
+    "StageRegistry",
+    "discover_stages",
+    "register_source",
+    "register_effect",
+    "register_display",
+    "register_camera",
+]

sideline/pipeline/adapters.py

@@ -0,0 +1,50 @@
+"""
+Stage adapters - Bridge existing components to the Stage interface.
+
+This module provides adapters that wrap existing components
+(EffectPlugin, Display, DataSource, Camera) as Stage implementations.
+
+DEPRECATED: This file is now a compatibility wrapper.
+Use `engine.pipeline.adapters` package instead.
+"""
+
+# Re-export from the new package structure for backward compatibility
+from sideline.pipeline.adapters import (
+    # Adapter classes
+    CameraStage,
+    CanvasStage,
+    DataSourceStage,
+    DisplayStage,
+    EffectPluginStage,
+    FontStage,
+    ImageToTextStage,
+    PassthroughStage,
+    SourceItemsToBufferStage,
+    ViewportFilterStage,
+    # Factory functions
+    create_stage_from_camera,
+    create_stage_from_display,
+    create_stage_from_effect,
+    create_stage_from_font,
+    create_stage_from_source,
+)
+
+__all__ = [
+    # Adapter classes
+    "EffectPluginStage",
+    "DisplayStage",
+    "DataSourceStage",
+    "PassthroughStage",
+    "SourceItemsToBufferStage",
+    "CameraStage",
+    "ViewportFilterStage",
+    "FontStage",
+    "ImageToTextStage",
+    "CanvasStage",
+    # Factory functions
+    "create_stage_from_display",
+    "create_stage_from_effect",
+    "create_stage_from_source",
+    "create_stage_from_camera",
+    "create_stage_from_font",
+]

sideline/pipeline/adapters/__init__.py

@@ -0,0 +1,55 @@
+"""Stage adapters - Bridge existing components to the Stage interface.
+
+This module provides adapters that wrap existing components
+(EffectPlugin, Display, DataSource, Camera) as Stage implementations.
+"""
+
+from .camera import CameraClockStage, CameraStage
+from .data_source import DataSourceStage, PassthroughStage, SourceItemsToBufferStage
+from .display import DisplayStage
+from .effect_plugin import EffectPluginStage
+from .factory import (
+    create_stage_from_camera,
+    create_stage_from_display,
+    create_stage_from_effect,
+    create_stage_from_font,
+    create_stage_from_source,
+)
+from .message_overlay import MessageOverlayConfig, MessageOverlayStage
+from .positioning import (
+    PositioningMode,
+    PositionStage,
+    create_position_stage,
+)
+from .transform import (
+    CanvasStage,
+    FontStage,
+    ImageToTextStage,
+    ViewportFilterStage,
+)
+
+__all__ = [
+    # Adapter classes
+    "EffectPluginStage",
+    "DisplayStage",
+    "DataSourceStage",
+    "PassthroughStage",
+    "SourceItemsToBufferStage",
+    "CameraStage",
+    "CameraClockStage",
+    "ViewportFilterStage",
+    "FontStage",
+    "ImageToTextStage",
+    "CanvasStage",
+    "MessageOverlayStage",
+    "MessageOverlayConfig",
+    "PositionStage",
+    "PositioningMode",
+    # Factory functions
+    "create_stage_from_display",
+    "create_stage_from_effect",
+    "create_stage_from_source",
+    "create_stage_from_camera",
+    "create_stage_from_font",
+    "create_position_stage",
+]

sideline/pipeline/adapters/camera.py

@@ -0,0 +1,219 @@
+"""Adapter for camera stage."""
+
+import time
+from typing import Any
+
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+
+
+class CameraClockStage(Stage):
+    """Per-frame clock stage that updates camera state.
+
+    This stage runs once per frame and updates the camera's internal state
+    (position, time). It makes camera_y/camera_x available to subsequent
+    stages via the pipeline context.
+
+    Unlike other stages, this is a pure clock stage and doesn't process
+    data - it just updates camera state and passes data through unchanged.
+    """
+
+    def __init__(self, camera, name: str = "camera-clock"):
+        self._camera = camera
+        self.name = name
+        self.category = "camera"
+        self.optional = False
+        self._last_frame_time: float | None = None
+
+    @property
+    def stage_type(self) -> str:
+        return "camera"
+
+    @property
+    def capabilities(self) -> set[str]:
+        # Provides camera state info only
+        # NOTE: Do NOT provide "source" as it conflicts with viewport_filter's "source.filtered"
+        return {"camera.state"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Clock stage - no dependencies (updates every frame regardless of data flow)
+        return set()
+
+    @property
+    def inlet_types(self) -> set:
+        # Accept any data type - this is a pass-through stage
+        return {DataType.ANY}
+
+    @property
+    def outlet_types(self) -> set:
+        # Pass through whatever was received
+        return {DataType.ANY}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Update camera state and pass data through.
+
+        This stage updates the camera's internal state (position, time) and
+        makes the updated camera_y/camera_x available to subsequent stages
+        via the pipeline context.
+
+        The data is passed through unchanged - this stage only updates
+        camera state, it doesn't transform the data.
+        """
+        if data is None:
+            return data
+
+        # Update camera speed from params if explicitly set (for dynamic modulation)
+        # Only update if camera_speed in params differs from the default (1.0)
+        # This preserves camera speed set during construction
+        if (
+            ctx.params
+            and hasattr(ctx.params, "camera_speed")
+            and ctx.params.camera_speed != 1.0
+        ):
+            self._camera.set_speed(ctx.params.camera_speed)
+
+        current_time = time.perf_counter()
+        dt = 0.0
+        if self._last_frame_time is not None:
+            dt = current_time - self._last_frame_time
+            self._camera.update(dt)
+        self._last_frame_time = current_time
+
+        # Update context with current camera position
+        ctx.set_state("camera_y", self._camera.y)
+        ctx.set_state("camera_x", self._camera.x)
+
+        # Pass data through unchanged
+        return data
+
+
+class CameraStage(Stage):
+    """Adapter wrapping Camera as a Stage.
+
+    This stage applies camera viewport transformation to the rendered buffer.
+    Camera state updates are handled by CameraClockStage.
+    """
+
+    def __init__(self, camera, name: str = "vertical"):
+        self._camera = camera
+        self.name = name
+        self.category = "camera"
+        self.optional = True
+        self._last_frame_time: float | None = None
+
+    def save_state(self) -> dict[str, Any]:
+        """Save camera state for restoration after pipeline rebuild.
+
+        Returns:
+            Dictionary containing camera state that can be restored
+        """
+        state = {
+            "x": self._camera.x,
+            "y": self._camera.y,
+            "mode": self._camera.mode.value
+            if hasattr(self._camera.mode, "value")
+            else self._camera.mode,
+            "speed": self._camera.speed,
+            "zoom": self._camera.zoom,
+            "canvas_width": self._camera.canvas_width,
+            "canvas_height": self._camera.canvas_height,
+            "_x_float": getattr(self._camera, "_x_float", 0.0),
+            "_y_float": getattr(self._camera, "_y_float", 0.0),
+            "_time": getattr(self._camera, "_time", 0.0),
+        }
+        # Save radial camera state if present
+        if hasattr(self._camera, "_r_float"):
+            state["_r_float"] = self._camera._r_float
+        if hasattr(self._camera, "_theta_float"):
+            state["_theta_float"] = self._camera._theta_float
+        if hasattr(self._camera, "_radial_input"):
+            state["_radial_input"] = self._camera._radial_input
+        return state
+
+    def restore_state(self, state: dict[str, Any]) -> None:
+        """Restore camera state from saved state.
+
+        Args:
+            state: Dictionary containing camera state from save_state()
+        """
+        from sideline.camera import CameraMode
+
+        self._camera.x = state.get("x", 0)
+        self._camera.y = state.get("y", 0)
+
+        # Restore mode - handle both enum value and direct enum
+        mode_value = state.get("mode", 0)
+        if isinstance(mode_value, int):
+            self._camera.mode = CameraMode(mode_value)
+        else:
+            self._camera.mode = mode_value
+
+        self._camera.speed = state.get("speed", 1.0)
+        self._camera.zoom = state.get("zoom", 1.0)
+        self._camera.canvas_width = state.get("canvas_width", 200)
+        self._camera.canvas_height = state.get("canvas_height", 200)
+
+        # Restore internal state
+        if hasattr(self._camera, "_x_float"):
+            self._camera._x_float = state.get("_x_float", 0.0)
+        if hasattr(self._camera, "_y_float"):
+            self._camera._y_float = state.get("_y_float", 0.0)
+        if hasattr(self._camera, "_time"):
+            self._camera._time = state.get("_time", 0.0)
+
+        # Restore radial camera state if present
+        if hasattr(self._camera, "_r_float"):
+            self._camera._r_float = state.get("_r_float", 0.0)
+        if hasattr(self._camera, "_theta_float"):
+            self._camera._theta_float = state.get("_theta_float", 0.0)
+        if hasattr(self._camera, "_radial_input"):
+            self._camera._radial_input = state.get("_radial_input", 0.0)
+
+    @property
+    def stage_type(self) -> str:
+        return "camera"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"camera"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"render.output", "camera.state"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Apply camera transformation to items."""
+        if data is None:
+            return data
+
+        # Camera state is updated by CameraClockStage
+        # We only apply the viewport transformation here
+
+        if hasattr(self._camera, "apply"):
+            viewport_width = ctx.params.viewport_width if ctx.params else 80
+            viewport_height = ctx.params.viewport_height if ctx.params else 24
+
+            # Use filtered camera position if available (from ViewportFilterStage)
+            # This handles the case where the buffer has been filtered and starts at row 0
+            filtered_camera_y = ctx.get("camera_y", self._camera.y)
+
+            # Temporarily adjust camera position for filtering
+            original_y = self._camera.y
+            self._camera.y = filtered_camera_y
+
+            try:
+                result = self._camera.apply(data, viewport_width, viewport_height)
+            finally:
+                # Restore original camera position
+                self._camera.y = original_y
+
+            return result
+        return data

sideline/pipeline/adapters/data_source.py

@@ -0,0 +1,143 @@
+"""
+Stage adapters - Bridge existing components to the Stage interface.
+
+This module provides adapters that wrap existing components
+(DataSource) as Stage implementations.
+"""
+
+from typing import Any
+
+from sideline.data_sources import SourceItem
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+
+
+class DataSourceStage(Stage):
+    """Adapter wrapping DataSource as a Stage."""
+
+    def __init__(self, data_source, name: str = "headlines"):
+        self._source = data_source
+        self.name = name
+        self.category = "source"
+        self.optional = False
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {f"source.{self.name}"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return set()
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.NONE}  # Sources don't take input
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Fetch data from source."""
+        if hasattr(self._source, "get_items"):
+            return self._source.get_items()
+        return data
+
+
+class PassthroughStage(Stage):
+    """Simple stage that passes data through unchanged.
+
+    Used for sources that already provide the data in the correct format
+    (e.g., pipeline introspection that outputs text directly).
+    """
+
+    def __init__(self, name: str = "passthrough"):
+        self.name = name
+        self.category = "render"
+        self.optional = True
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"source"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Pass data through unchanged."""
+        return data
+
+
+class SourceItemsToBufferStage(Stage):
+    """Convert SourceItem objects to text buffer.
+
+    Takes a list of SourceItem objects and extracts their content,
+    splitting on newlines to create a proper text buffer for display.
+    """
+
+    def __init__(self, name: str = "items-to-buffer"):
+        self.name = name
+        self.category = "render"
+        self.optional = True
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"source"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Convert SourceItem list to text buffer."""
+        if data is None:
+            return []
+
+        # If already a list of strings, return as-is
+        if isinstance(data, list) and data and isinstance(data[0], str):
+            return data
+
+        # If it's a list of SourceItem, extract content
+        if isinstance(data, list):
+            result = []
+            for item in data:
+                if isinstance(item, SourceItem):
+                    # Split content by newline to get individual lines
+                    lines = item.content.split("\n")
+                    result.extend(lines)
+                elif hasattr(item, "content"):  # Has content attribute
+                    lines = str(item.content).split("\n")
+                    result.extend(lines)
+                else:
+                    result.append(str(item))
+            return result
+
+        # Single item
+        if isinstance(data, SourceItem):
+            return data.content.split("\n")
+
+        return [str(data)]

sideline/pipeline/adapters/display.py

@@ -0,0 +1,108 @@
+"""Adapter wrapping Display as a Stage."""
+
+from typing import Any
+
+from sideline.pipeline.core import PipelineContext, Stage
+
+
+class DisplayStage(Stage):
+    """Adapter wrapping Display as a Stage."""
+
+    def __init__(self, display, name: str = "terminal", positioning: str = "mixed"):
+        self._display = display
+        self.name = name
+        self.category = "display"
+        self.optional = False
+        self._initialized = False
+        self._init_width = 80
+        self._init_height = 24
+        self._positioning = positioning
+
+    def save_state(self) -> dict[str, Any]:
+        """Save display state for restoration after pipeline rebuild.
+
+        Returns:
+            Dictionary containing display state that can be restored
+        """
+        return {
+            "initialized": self._initialized,
+            "init_width": self._init_width,
+            "init_height": self._init_height,
+            "width": getattr(self._display, "width", 80),
+            "height": getattr(self._display, "height", 24),
+        }
+
+    def restore_state(self, state: dict[str, Any]) -> None:
+        """Restore display state from saved state.
+
+        Args:
+            state: Dictionary containing display state from save_state()
+        """
+        self._initialized = state.get("initialized", False)
+        self._init_width = state.get("init_width", 80)
+        self._init_height = state.get("init_height", 24)
+
+        # Restore display dimensions if the display supports it
+        if hasattr(self._display, "width"):
+            self._display.width = state.get("width", 80)
+        if hasattr(self._display, "height"):
+            self._display.height = state.get("height", 24)
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"display.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Display needs rendered content and camera transformation
+        return {"render.output", "camera"}
+
+    @property
+    def inlet_types(self) -> set:
+        from sideline.pipeline.core import DataType
+
+        return {DataType.TEXT_BUFFER}  # Display consumes rendered text
+
+    @property
+    def outlet_types(self) -> set:
+        from sideline.pipeline.core import DataType
+
+        return {DataType.NONE}  # Display is a terminal stage (no output)
+
+    def init(self, ctx: PipelineContext) -> bool:
+        w = ctx.params.viewport_width if ctx.params else 80
+        h = ctx.params.viewport_height if ctx.params else 24
+
+        # Try to reuse display if already initialized
+        reuse = self._initialized
+        result = self._display.init(w, h, reuse=reuse)
+
+        # Update initialization state
+        if result is not False:
+            self._initialized = True
+            self._init_width = w
+            self._init_height = h
+
+        return result is not False
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Output data to display."""
+        if data is not None:
+            # Check if positioning mode is specified in context params
+            positioning = self._positioning
+            if ctx and ctx.params and hasattr(ctx.params, "positioning"):
+                positioning = ctx.params.positioning
+
+            # Pass positioning to display if supported
+            if (
+                hasattr(self._display, "show")
+                and "positioning" in self._display.show.__code__.co_varnames
+            ):
+                self._display.show(data, positioning=positioning)
+            else:
+                # Fallback for displays that don't support positioning parameter
+                self._display.show(data)
+        return data
+
+    def cleanup(self) -> None:
+        self._display.cleanup()

sideline/pipeline/adapters/effect_plugin.py

@@ -0,0 +1,124 @@
+"""Adapter wrapping EffectPlugin as a Stage."""
+
+from typing import Any
+
+from sideline.pipeline.core import PipelineContext, Stage
+
+
+class EffectPluginStage(Stage):
+    """Adapter wrapping EffectPlugin as a Stage.
+
+    Supports capability-based dependencies through the dependencies parameter.
+    """
+
+    def __init__(
+        self,
+        effect_plugin,
+        name: str = "effect",
+        dependencies: set[str] | None = None,
+    ):
+        self._effect = effect_plugin
+        self.name = name
+        self.category = "effect"
+        self.optional = False
+        self._dependencies = dependencies or set()
+
+    @property
+    def stage_type(self) -> str:
+        """Return stage_type based on effect name.
+
+        Overlay effects have stage_type "overlay".
+        """
+        if self.is_overlay:
+            return "overlay"
+        return self.category
+
+    @property
+    def render_order(self) -> int:
+        """Return render_order based on effect type.
+
+        Overlay effects have high render_order to appear on top.
+        """
+        if self.is_overlay:
+            return 100  # High order for overlays
+        return 0
+
+    @property
+    def is_overlay(self) -> bool:
+        """Return True for overlay effects.
+
+        Overlay effects compose on top of the buffer
+        rather than transforming it for the next stage.
+        """
+        # Check if the effect has an is_overlay attribute that is explicitly True
+        # (not just any truthy value from a mock object)
+        if hasattr(self._effect, "is_overlay"):
+            effect_overlay = self._effect.is_overlay
+            # Only return True if it's explicitly set to True
+            if effect_overlay is True:
+                return True
+        return self.name == "hud"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {f"effect.{self.name}"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return self._dependencies
+
+    @property
+    def inlet_types(self) -> set:
+        from sideline.pipeline.core import DataType
+
+        return {DataType.TEXT_BUFFER}
+
+    @property
+    def outlet_types(self) -> set:
+        from sideline.pipeline.core import DataType
+
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Process data through the effect."""
+        if data is None:
+            return None
+        from sideline.effects.types import EffectContext, apply_param_bindings
+
+        w = ctx.params.viewport_width if ctx.params else 80
+        h = ctx.params.viewport_height if ctx.params else 24
+        frame = ctx.params.frame_number if ctx.params else 0
+
+        effect_ctx = EffectContext(
+            terminal_width=w,
+            terminal_height=h,
+            scroll_cam=0,
+            ticker_height=h,
+            camera_x=0,
+            mic_excess=0.0,
+            grad_offset=(frame * 0.01) % 1.0,
+            frame_number=frame,
+            has_message=False,
+            items=ctx.get("items", []),
+        )
+
+        # Copy sensor state from PipelineContext to EffectContext
+        for key, value in ctx.state.items():
+            if key.startswith("sensor."):
+                effect_ctx.set_state(key, value)
+
+        # Copy metrics from PipelineContext to EffectContext
+        if "metrics" in ctx.state:
+            effect_ctx.set_state("metrics", ctx.state["metrics"])
+
+        # Copy pipeline_order from PipelineContext services to EffectContext state
+        pipeline_order = ctx.get("pipeline_order")
+        if pipeline_order:
+            effect_ctx.set_state("pipeline_order", pipeline_order)
+
+        # Apply sensor param bindings if effect has them
+        if hasattr(self._effect, "param_bindings") and self._effect.param_bindings:
+            bound_config = apply_param_bindings(self._effect, effect_ctx)
+            self._effect.configure(bound_config)
+
+        return self._effect.process(data, effect_ctx)

sideline/pipeline/adapters/factory.py

@@ -0,0 +1,38 @@
+"""Factory functions for creating stage instances."""
+
+from sideline.pipeline.adapters.camera import CameraStage
+from sideline.pipeline.adapters.data_source import DataSourceStage
+from sideline.pipeline.adapters.display import DisplayStage
+from sideline.pipeline.adapters.effect_plugin import EffectPluginStage
+from sideline.pipeline.adapters.transform import FontStage
+
+
+def create_stage_from_display(display, name: str = "terminal") -> DisplayStage:
+    """Create a DisplayStage from a display instance."""
+    return DisplayStage(display, name=name)
+
+
+def create_stage_from_effect(effect_plugin, name: str) -> EffectPluginStage:
+    """Create an EffectPluginStage from an effect plugin."""
+    return EffectPluginStage(effect_plugin, name=name)
+
+
+def create_stage_from_source(data_source, name: str = "headlines") -> DataSourceStage:
+    """Create a DataSourceStage from a data source."""
+    return DataSourceStage(data_source, name=name)
+
+
+def create_stage_from_camera(camera, name: str = "vertical") -> CameraStage:
+    """Create a CameraStage from a camera instance."""
+    return CameraStage(camera, name=name)
+
+
+def create_stage_from_font(
+    font_path: str | None = None,
+    font_size: int | None = None,
+    font_ref: str | None = "default",
+    name: str = "font",
+) -> FontStage:
+    """Create a FontStage with specified font configuration."""
+    # FontStage currently doesn't use these parameters but keeps them for compatibility
+    return FontStage(name=name)

sideline/pipeline/adapters/frame_capture.py

@@ -0,0 +1,165 @@
+"""
+Frame Capture Stage Adapter
+
+Wraps pipeline stages to capture frames for animation report generation.
+"""
+
+from typing import Any
+
+from sideline.display.backends.animation_report import AnimationReportDisplay
+from sideline.pipeline.core import PipelineContext, Stage
+
+
+class FrameCaptureStage(Stage):
+    """
+    Wrapper stage that captures frames before and after a wrapped stage.
+
+    This allows generating animation reports showing how each stage
+    transforms the data.
+    """
+
+    def __init__(
+        self,
+        wrapped_stage: Stage,
+        display: AnimationReportDisplay,
+        name: str | None = None,
+    ):
+        """
+        Initialize frame capture stage.
+
+        Args:
+            wrapped_stage: The stage to wrap and capture frames from
+            display: The animation report display to send frames to
+            name: Optional name for this capture stage
+        """
+        self._wrapped_stage = wrapped_stage
+        self._display = display
+        self.name = name or f"capture_{wrapped_stage.name}"
+        self.category = wrapped_stage.category
+        self.optional = wrapped_stage.optional
+
+        # Capture state
+        self._captured_input = False
+        self._captured_output = False
+
+    @property
+    def stage_type(self) -> str:
+        return self._wrapped_stage.stage_type
+
+    @property
+    def capabilities(self) -> set[str]:
+        return self._wrapped_stage.capabilities
+
+    @property
+    def dependencies(self) -> set[str]:
+        return self._wrapped_stage.dependencies
+
+    @property
+    def inlet_types(self) -> set:
+        return self._wrapped_stage.inlet_types
+
+    @property
+    def outlet_types(self) -> set:
+        return self._wrapped_stage.outlet_types
+
+    def init(self, ctx: PipelineContext) -> bool:
+        """Initialize the wrapped stage."""
+        return self._wrapped_stage.init(ctx)
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """
+        Process data through wrapped stage and capture frames.
+
+        Args:
+            data: Input data (typically a text buffer)
+            ctx: Pipeline context
+
+        Returns:
+            Output data from wrapped stage
+        """
+        # Capture input frame (before stage processing)
+        if isinstance(data, list) and all(isinstance(line, str) for line in data):
+            self._display.start_stage(f"{self._wrapped_stage.name}_input")
+            self._display.show(data)
+            self._captured_input = True
+
+        # Process through wrapped stage
+        result = self._wrapped_stage.process(data, ctx)
+
+        # Capture output frame (after stage processing)
+        if isinstance(result, list) and all(isinstance(line, str) for line in result):
+            self._display.start_stage(f"{self._wrapped_stage.name}_output")
+            self._display.show(result)
+            self._captured_output = True
+
+        return result
+
+    def cleanup(self) -> None:
+        """Cleanup the wrapped stage."""
+        self._wrapped_stage.cleanup()
+
+
+class FrameCaptureController:
+    """
+    Controller for managing frame capture across the pipeline.
+
+    This class provides an easy way to enable frame capture for
+    specific stages or the entire pipeline.
+    """
+
+    def __init__(self, display: AnimationReportDisplay):
+        """
+        Initialize frame capture controller.
+
+        Args:
+            display: The animation report display to use for capture
+        """
+        self._display = display
+        self._captured_stages: list[FrameCaptureStage] = []
+
+    def wrap_stage(self, stage: Stage, name: str | None = None) -> FrameCaptureStage:
+        """
+        Wrap a stage with frame capture.
+
+        Args:
+            stage: The stage to wrap
+            name: Optional name for the capture stage
+
+        Returns:
+            Wrapped stage that captures frames
+        """
+        capture_stage = FrameCaptureStage(stage, self._display, name)
+        self._captured_stages.append(capture_stage)
+        return capture_stage
+
+    def wrap_stages(self, stages: dict[str, Stage]) -> dict[str, Stage]:
+        """
+        Wrap multiple stages with frame capture.
+
+        Args:
+            stages: Dictionary of stage names to stages
+
+        Returns:
+            Dictionary of stage names to wrapped stages
+        """
+        wrapped = {}
+        for name, stage in stages.items():
+            wrapped[name] = self.wrap_stage(stage, name)
+        return wrapped
+
+    def get_captured_stages(self) -> list[FrameCaptureStage]:
+        """Get list of all captured stages."""
+        return self._captured_stages
+
+    def generate_report(self, title: str = "Pipeline Animation Report") -> str:
+        """
+        Generate the animation report.
+
+        Args:
+            title: Title for the report
+
+        Returns:
+            Path to the generated HTML file
+        """
+        report_path = self._display.generate_report(title)
+        return str(report_path)

sideline/pipeline/adapters/message_overlay.py

@@ -0,0 +1,185 @@
+"""
+Message overlay stage - Renders ntfy messages as an overlay on the buffer.
+
+This stage provides message overlay capability for displaying ntfy.sh messages
+as a centered panel with pink/magenta gradient, matching upstream/main aesthetics.
+"""
+
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime
+
+from engine import config
+from engine.effects.legacy import vis_trunc
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+from sideline.render.blocks import big_wrap
+from sideline.render.gradient import msg_gradient
+
+
+@dataclass
+class MessageOverlayConfig:
+    """Configuration for MessageOverlayStage."""
+
+    enabled: bool = True
+    display_secs: int = 30  # How long to display messages
+    topic_url: str | None = None  # Ntfy topic URL (None = use config default)
+
+
+class MessageOverlayStage(Stage):
+    """Stage that renders ntfy message overlay on the buffer.
+
+    Provides:
+    - message.overlay capability (optional)
+    - Renders centered panel with pink/magenta gradient
+    - Shows title, body, timestamp, and remaining time
+    """
+
+    name = "message_overlay"
+    category = "overlay"
+
+    def __init__(
+        self, config: MessageOverlayConfig | None = None, name: str = "message_overlay"
+    ):
+        self.config = config or MessageOverlayConfig()
+        self._ntfy_poller = None
+        self._msg_cache = (None, None)  # (cache_key, rendered_rows)
+
+    @property
+    def capabilities(self) -> set[str]:
+        """Provides message overlay capability."""
+        return {"message.overlay"} if self.config.enabled else set()
+
+    @property
+    def dependencies(self) -> set[str]:
+        """Needs rendered buffer and camera transformation to overlay onto."""
+        return {"render.output", "camera"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def init(self, ctx: PipelineContext) -> bool:
+        """Initialize ntfy poller if topic URL is configured."""
+        if not self.config.enabled:
+            return True
+
+        # Get or create ntfy poller
+        topic_url = self.config.topic_url or config.NTFY_TOPIC
+        if topic_url:
+            from sideline.ntfy import NtfyPoller
+
+            self._ntfy_poller = NtfyPoller(
+                topic_url=topic_url,
+                reconnect_delay=getattr(config, "NTFY_RECONNECT_DELAY", 5),
+                display_secs=self.config.display_secs,
+            )
+            self._ntfy_poller.start()
+            ctx.set("ntfy_poller", self._ntfy_poller)
+
+        return True
+
+    def process(self, data: list[str], ctx: PipelineContext) -> list[str]:
+        """Render message overlay on the buffer."""
+        if not self.config.enabled or not data:
+            return data
+
+        # Get active message from poller
+        msg = None
+        if self._ntfy_poller:
+            msg = self._ntfy_poller.get_active_message()
+
+        if msg is None:
+            return data
+
+        # Render overlay
+        w = ctx.terminal_width if hasattr(ctx, "terminal_width") else 80
+        h = ctx.terminal_height if hasattr(ctx, "terminal_height") else 24
+
+        overlay, self._msg_cache = self._render_message_overlay(
+            msg, w, h, self._msg_cache
+        )
+
+        # Composite overlay onto buffer
+        result = list(data)
+        for line in overlay:
+            # Overlay uses ANSI cursor positioning, just append
+            result.append(line)
+
+        return result
+
+    def _render_message_overlay(
+        self,
+        msg: tuple[str, str, float] | None,
+        w: int,
+        h: int,
+        msg_cache: tuple,
+    ) -> tuple[list[str], tuple]:
+        """Render ntfy message overlay.
+
+        Args:
+            msg: (title, body, timestamp) or None
+            w: terminal width
+            h: terminal height
+            msg_cache: (cache_key, rendered_rows) for caching
+
+        Returns:
+            (list of ANSI strings, updated cache)
+        """
+        overlay = []
+        if msg is None:
+            return overlay, msg_cache
+
+        m_title, m_body, m_ts = msg
+        display_text = m_body or m_title or "(empty)"
+        display_text = re.sub(r"\s+", " ", display_text.upper())
+
+        cache_key = (display_text, w)
+        if msg_cache[0] != cache_key:
+            msg_rows = big_wrap(display_text, w - 4)
+            msg_cache = (cache_key, msg_rows)
+        else:
+            msg_rows = msg_cache[1]
+
+        msg_rows = msg_gradient(msg_rows, (time.monotonic() * config.GRAD_SPEED) % 1.0)
+
+        elapsed_s = int(time.monotonic() - m_ts)
+        remaining = max(0, self.config.display_secs - elapsed_s)
+        ts_str = datetime.now().strftime("%H:%M:%S")
+        panel_h = len(msg_rows) + 2
+        panel_top = max(0, (h - panel_h) // 2)
+
+        row_idx = 0
+        for mr in msg_rows:
+            ln = vis_trunc(mr, w)
+            overlay.append(f"\033[{panel_top + row_idx + 1};1H  {ln}\033[0m\033[K")
+            row_idx += 1
+
+        meta_parts = []
+        if m_title and m_title != m_body:
+            meta_parts.append(m_title)
+        meta_parts.append(f"ntfy \u00b7 {ts_str} \u00b7 {remaining}s")
+        meta = (
+            "  " + " \u00b7 ".join(meta_parts)
+            if len(meta_parts) > 1
+            else "  " + meta_parts[0]
+        )
+        overlay.append(
+            f"\033[{panel_top + row_idx + 1};1H\033[38;5;245m{meta}\033[0m\033[K"
+        )
+        row_idx += 1
+
+        bar = "\u2500" * (w - 4)
+        overlay.append(
+            f"\033[{panel_top + row_idx + 1};1H  \033[2;38;5;37m{bar}\033[0m\033[K"
+        )
+
+        return overlay, msg_cache
+
+    def cleanup(self) -> None:
+        """Cleanup resources."""
+        pass

sideline/pipeline/adapters/positioning.py

@@ -0,0 +1,185 @@
+"""PositionStage - Configurable positioning mode for terminal rendering.
+
+This module provides positioning stages that allow choosing between
+different ANSI positioning approaches:
+- ABSOLUTE: Use cursor positioning codes (\\033[row;colH) for all lines
+- RELATIVE: Use newlines for all lines
+- MIXED: Base content uses newlines, effects use cursor positioning (default)
+"""
+
+from enum import Enum
+from typing import Any
+
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+
+
+class PositioningMode(Enum):
+    """Positioning mode for terminal rendering."""
+
+    ABSOLUTE = "absolute"  # All lines have cursor positioning codes
+    RELATIVE = "relative"  # Lines use newlines (no cursor codes)
+    MIXED = "mixed"  # Mixed: newlines for base, cursor codes for overlays (default)
+
+
+class PositionStage(Stage):
+    """Applies positioning mode to buffer before display.
+
+    This stage allows configuring how lines are positioned in the terminal:
+    - ABSOLUTE: Each line has \\033[row;colH prefix (precise control)
+    - RELATIVE: Lines are joined with \\n (natural flow)
+    - MIXED: Leaves buffer as-is (effects add their own positioning)
+    """
+
+    def __init__(
+        self, mode: PositioningMode = PositioningMode.RELATIVE, name: str = "position"
+    ):
+        self.mode = mode
+        self.name = name
+        self.category = "position"
+        self._mode_str = mode.value
+
+    def save_state(self) -> dict[str, Any]:
+        """Save positioning mode for restoration."""
+        return {"mode": self.mode.value}
+
+    def restore_state(self, state: dict[str, Any]) -> None:
+        """Restore positioning mode from saved state."""
+        mode_value = state.get("mode", "relative")
+        self.mode = PositioningMode(mode_value)
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"position.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Position stage typically runs after render but before effects
+        # Effects may add their own positioning codes
+        return {"render.output"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def init(self, ctx: PipelineContext) -> bool:
+        """Initialize the positioning stage."""
+        return True
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Apply positioning mode to the buffer.
+
+        Args:
+            data: List of strings (buffer lines)
+            ctx: Pipeline context
+
+        Returns:
+            Buffer with applied positioning mode
+        """
+        if data is None:
+            return data
+
+        if not isinstance(data, list):
+            return data
+
+        if self.mode == PositioningMode.ABSOLUTE:
+            return self._to_absolute(data, ctx)
+        elif self.mode == PositioningMode.RELATIVE:
+            return self._to_relative(data, ctx)
+        else:  # MIXED
+            return data  # No transformation
+
+    def _to_absolute(self, data: list[str], ctx: PipelineContext) -> list[str]:
+        """Convert buffer to absolute positioning (all lines have cursor codes).
+
+        This mode prefixes each line with \\033[row;colH to move cursor
+        to the exact position before writing the line.
+
+        Args:
+            data: List of buffer lines
+            ctx: Pipeline context (provides terminal dimensions)
+
+        Returns:
+            Buffer with cursor positioning codes for each line
+        """
+        result = []
+        viewport_height = ctx.params.viewport_height if ctx.params else 24
+
+        for i, line in enumerate(data):
+            if i >= viewport_height:
+                break  # Don't exceed viewport
+
+            # Check if line already has cursor positioning
+            if "\033[" in line and "H" in line:
+                # Already has cursor positioning - leave as-is
+                result.append(line)
+            else:
+                # Add cursor positioning for this line
+                # Row is 1-indexed
+                result.append(f"\033[{i + 1};1H{line}")
+
+        return result
+
+    def _to_relative(self, data: list[str], ctx: PipelineContext) -> list[str]:
+        """Convert buffer to relative positioning (use newlines).
+
+        This mode removes explicit cursor positioning codes from lines
+        (except for effects that specifically add them).
+
+        Note: Effects like HUD add their own cursor positioning codes,
+        so we can't simply remove all of them. We rely on the terminal
+        display to join lines with newlines.
+
+        Args:
+            data: List of buffer lines
+            ctx: Pipeline context (unused)
+
+        Returns:
+            Buffer with minimal cursor positioning (only for overlays)
+        """
+        # For relative mode, we leave the buffer as-is
+        # The terminal display handles joining with newlines
+        # Effects that need absolute positioning will add their own codes
+
+        # Filter out lines that would cause double-positioning
+        result = []
+        for i, line in enumerate(data):
+            # Check if this line looks like base content (no cursor code at start)
+            # vs an effect line (has cursor code at start)
+            if line.startswith("\033[") and "H" in line[:20]:
+                # This is an effect with positioning - keep it
+                result.append(line)
+            else:
+                # Base content - strip any inline cursor codes (rare)
+                # but keep color codes
+                result.append(line)
+
+        return result
+
+    def cleanup(self) -> None:
+        """Clean up positioning stage."""
+        pass
+
+
+# Convenience function to create positioning stage
+def create_position_stage(
+    mode: str = "relative", name: str = "position"
+) -> PositionStage:
+    """Create a positioning stage with the specified mode.
+
+    Args:
+        mode: Positioning mode ("absolute", "relative", or "mixed")
+        name: Name for the stage
+
+    Returns:
+        PositionStage instance
+    """
+    try:
+        positioning_mode = PositioningMode(mode)
+    except ValueError:
+        positioning_mode = PositioningMode.RELATIVE
+
+    return PositionStage(mode=positioning_mode, name=name)

sideline/pipeline/adapters/transform.py

@@ -0,0 +1,293 @@
+"""Adapters for transform stages (viewport, font, image, canvas)."""
+
+from typing import Any
+
+import sideline.render
+from sideline.data_sources import SourceItem
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+
+
+def estimate_simple_height(text: str, width: int) -> int:
+    """Estimate height in terminal rows using simple word wrap.
+
+    Uses conservative estimation suitable for headlines.
+    Each wrapped line is approximately 6 terminal rows (big block rendering).
+    """
+    words = text.split()
+    if not words:
+        return 6
+
+    lines = 1
+    current_len = 0
+    for word in words:
+        word_len = len(word)
+        if current_len + word_len + 1 > width - 4:  # -4 for margins
+            lines += 1
+            current_len = word_len
+        else:
+            current_len += word_len + 1
+
+    return lines * 6  # 6 rows per line for big block rendering
+
+
+class ViewportFilterStage(Stage):
+    """Filter items to viewport height based on rendered height."""
+
+    def __init__(self, name: str = "viewport-filter"):
+        self.name = name
+        self.category = "render"
+        self.optional = True
+        self._layout: list[int] = []
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"source.filtered"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Always requires camera.state for viewport filtering
+        # CameraUpdateStage provides this (auto-injected if missing)
+        return {"source", "camera.state"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Filter items to viewport height based on rendered height."""
+        if data is None:
+            return data
+
+        if not isinstance(data, list):
+            return data
+
+        if not data:
+            return []
+
+        # Get viewport parameters from context
+        viewport_height = ctx.params.viewport_height if ctx.params else 24
+        viewport_width = ctx.params.viewport_width if ctx.params else 80
+        camera_y = ctx.get("camera_y", 0)
+
+        # Estimate height for each item and cache layout
+        self._layout = []
+        cumulative_heights = []
+        current_height = 0
+
+        for item in data:
+            title = item.content if isinstance(item, SourceItem) else str(item)
+            # Use simple height estimation (not PIL-based)
+            estimated_height = estimate_simple_height(title, viewport_width)
+            self._layout.append(estimated_height)
+            current_height += estimated_height
+            cumulative_heights.append(current_height)
+
+        # Find visible range based on camera_y and viewport_height
+        # camera_y is the scroll offset (how many rows are scrolled up)
+        start_y = camera_y
+        end_y = camera_y + viewport_height
+
+        # Find start index (first item that intersects with visible range)
+        start_idx = 0
+        start_item_y = 0  # Y position where the first visible item starts
+        for i, total_h in enumerate(cumulative_heights):
+            if total_h > start_y:
+                start_idx = i
+                # Calculate the Y position of the start of this item
+                if i > 0:
+                    start_item_y = cumulative_heights[i - 1]
+                break
+
+        # Find end index (first item that extends beyond visible range)
+        end_idx = len(data)
+        for i, total_h in enumerate(cumulative_heights):
+            if total_h >= end_y:
+                end_idx = i + 1
+                break
+
+        # Adjust camera_y for the filtered buffer
+        # The filtered buffer starts at row 0, but the camera position
+        # needs to be relative to where the first visible item starts
+        filtered_camera_y = camera_y - start_item_y
+
+        # Update context with the filtered camera position
+        # This ensures CameraStage can correctly slice the filtered buffer
+        ctx.set_state("camera_y", filtered_camera_y)
+        ctx.set_state("camera_x", ctx.get("camera_x", 0))  # Keep camera_x unchanged
+
+        # Return visible items
+        return data[start_idx:end_idx]
+
+
+class FontStage(Stage):
+    """Render items using font."""
+
+    def __init__(self, name: str = "font"):
+        self.name = name
+        self.category = "render"
+        self.optional = False
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def stage_dependencies(self) -> set[str]:
+        # Must connect to viewport_filter stage to get filtered source
+        return {"viewport_filter"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Depend on source.filtered (provided by viewport_filter)
+        # This ensures we get the filtered/processed source, not raw source
+        return {"source.filtered"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Render items to text buffer using font."""
+        if data is None:
+            return []
+
+        if not isinstance(data, list):
+            return [str(data)]
+
+        import os
+
+        if os.environ.get("DEBUG_CAMERA"):
+            print(f"FontStage: input items={len(data)}")
+
+        viewport_width = ctx.params.viewport_width if ctx.params else 80
+
+        result = []
+        for item in data:
+            if isinstance(item, SourceItem):
+                title = item.content
+                src = item.source
+                ts = item.timestamp
+                content_lines, _, _ = engine.render.make_block(
+                    title, src, ts, viewport_width
+                )
+                result.extend(content_lines)
+            elif hasattr(item, "content"):
+                title = str(item.content)
+                content_lines, _, _ = engine.render.make_block(
+                    title, "", "", viewport_width
+                )
+                result.extend(content_lines)
+            else:
+                result.append(str(item))
+        return result
+
+
+class ImageToTextStage(Stage):
+    """Convert image items to text."""
+
+    def __init__(self, name: str = "image-to-text"):
+        self.name = name
+        self.category = "render"
+        self.optional = True
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"source"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Convert image items to text representation."""
+        if data is None:
+            return []
+
+        if not isinstance(data, list):
+            return [str(data)]
+
+        result = []
+        for item in data:
+            # Check if item is an image
+            if hasattr(item, "image_path") or hasattr(item, "image_data"):
+                # Placeholder: would normally render image to ASCII art
+                result.append(f"[Image: {getattr(item, 'image_path', 'data')}]")
+            elif isinstance(item, SourceItem):
+                result.extend(item.content.split("\n"))
+            else:
+                result.append(str(item))
+        return result
+
+
+class CanvasStage(Stage):
+    """Render items to canvas."""
+
+    def __init__(self, name: str = "canvas"):
+        self.name = name
+        self.category = "render"
+        self.optional = False
+
+    @property
+    def stage_type(self) -> str:
+        return "render"
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {"render.output"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        return {"source"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.SOURCE_ITEMS}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Render items to canvas."""
+        if data is None:
+            return []
+
+        if not isinstance(data, list):
+            return [str(data)]
+
+        # Simple canvas rendering
+        result = []
+        for item in data:
+            if isinstance(item, SourceItem):
+                result.extend(item.content.split("\n"))
+            else:
+                result.append(str(item))
+        return result

sideline/pipeline/core.py

@@ -15,7 +15,7 @@ from enum import Enum, auto
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from engine.pipeline.params import PipelineParams
+    from sideline.pipeline.params import PipelineParams
 
 
 class DataType(Enum):
@@ -245,21 +245,17 @@ class PipelineContext:
         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,
-        }
+        # Lazy resolvers for services (can be added by applications)
+        self._lazy_resolvers: dict[str, Callable[[], Any]] = {}
 
-    def _resolve_config(self) -> Any:
-        from engine.config import get_config
+    def register_service(self, name: str, resolver: Callable[[], Any]) -> None:
+        """Register a lazy service resolver.
 
-        return get_config()
-
-    def _resolve_event_bus(self) -> Any:
-        from engine.eventbus import get_event_bus
-
-        return get_event_bus()
+        Args:
+            name: Service name (e.g., 'config', 'event_bus')
+            resolver: Function that returns the service instance
+        """
+        self._lazy_resolvers[name] = resolver
 
     def get(self, key: str, default: Any = None) -> Any:
         """Get a service or state value by key.

sideline/pipeline/params.py

@@ -0,0 +1,152 @@
+"""
+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
+
+try:
+    from sideline.display import BorderMode
+except ImportError:
+    BorderMode = object  # Fallback for type checking
+
+
+@dataclass
+class PipelineParams:
+    """Runtime configuration for the pipeline.
+
+    This is the canonical config object that AnimationController modifies.
+    Stages read from these params to adjust their behavior.
+    """
+
+    # Source config
+    source: str = "headlines"
+    source_refresh_interval: float = 60.0
+
+    # Display config
+    display: str = "terminal"
+    border: bool | BorderMode = False
+    positioning: str = "mixed"  # Positioning mode: "absolute", "relative", "mixed"
+
+    # Camera config
+    camera_mode: str = "vertical"
+    camera_speed: float = 1.0  # Default speed
+    camera_x: int = 0  # For horizontal scrolling
+
+    # Effect config
+    effect_order: list[str] = field(
+        default_factory=lambda: ["noise", "fade", "glitch", "firehose"]
+    )
+    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,
+            "positioning": self.positioning,
+            "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"],
+)
+
+DEFAULT_PYGAME_PARAMS = PipelineParams(
+    source="headlines",
+    display="pygame",
+    camera_mode="vertical",
+    effect_order=["noise", "fade", "glitch", "firehose"],
+)
+
+DEFAULT_PIPELINE_PARAMS = PipelineParams(
+    source="pipeline",
+    display="pygame",
+    camera_mode="trace",
+    effect_order=[],  # No effects for pipeline viz
+)

sideline/pipeline/registry.py

@@ -0,0 +1,242 @@
+"""
+Stage registry - Unified registration for all pipeline stages.
+
+Provides a single registry for sources, effects, displays, and cameras.
+Supports plugin discovery via entry points and explicit registration.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+import logging
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from sideline.pipeline.core import Stage
+
+if TYPE_CHECKING:
+    from sideline.pipeline.core import Stage
+
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
+
+class StageRegistry:
+    """Unified registry for all pipeline stage types.
+
+    Supports both explicit registration and automatic discovery via entry points.
+    Plugins can be registered manually or discovered automatically.
+    """
+
+    _categories: dict[str, dict[str, type[Any]]] = {}
+    _discovered: bool = False
+    _instances: dict[str, Stage] = {}
+    _plugins_discovered: bool = False
+    _plugin_modules: set[str] = set()  # Track loaded plugin modules
+
+    @classmethod
+    def register(cls, category: str, stage_class: type[Any]) -> None:
+        """Register a stage class in a category.
+
+        Args:
+            category: Category name (source, effect, display, camera)
+            stage_class: Stage subclass to register
+        """
+        if category not in cls._categories:
+            cls._categories[category] = {}
+
+        key = getattr(stage_class, "__name__", stage_class.__class__.__name__)
+        cls._categories[category][key] = stage_class
+
+    @classmethod
+    def get(cls, category: str, name: str) -> type[Any] | None:
+        """Get a stage class by category and name."""
+        return cls._categories.get(category, {}).get(name)
+
+    @classmethod
+    def list(cls, category: str) -> list[str]:
+        """List all stage names in a category."""
+        return list(cls._categories.get(category, {}).keys())
+
+    @classmethod
+    def list_categories(cls) -> list[str]:
+        """List all registered categories."""
+        return list(cls._categories.keys())
+
+    @classmethod
+    def create(cls, category: str, name: str, **kwargs) -> Stage | None:
+        """Create a stage instance by category and name."""
+        stage_class = cls.get(category, name)
+        if stage_class:
+            return stage_class(**kwargs)
+        return None
+
+    @classmethod
+    def create_instance(cls, stage: Stage | type[Stage], **kwargs) -> Stage:
+        """Create an instance from a stage class or return as-is."""
+        if isinstance(stage, Stage):
+            return stage
+        if isinstance(stage, type) and issubclass(stage, Stage):
+            return stage(**kwargs)
+        raise TypeError(f"Expected Stage class or instance, got {type(stage)}")
+
+    @classmethod
+    def register_instance(cls, name: str, stage: Stage) -> None:
+        """Register a stage instance by name."""
+        cls._instances[name] = stage
+
+    @classmethod
+    def get_instance(cls, name: str) -> Stage | None:
+        """Get a registered stage instance by name."""
+        return cls._instances.get(name)
+
+    @classmethod
+    def register_plugin_module(cls, plugin_module: str) -> None:
+        """Register stages from an external plugin module.
+
+        The module should define a register_stages(registry) function.
+
+        Args:
+            plugin_module: Full module path (e.g., 'engine.plugins')
+        """
+        if plugin_module in cls._plugin_modules:
+            logger.debug(f"Plugin module {plugin_module} already loaded")
+            return
+
+        try:
+            module = importlib.import_module(plugin_module)
+            if hasattr(module, "register_stages"):
+                module.register_stages(cls)
+                cls._plugin_modules.add(plugin_module)
+                logger.info(f"Registered stages from {plugin_module}")
+            else:
+                logger.warning(
+                    f"Plugin module {plugin_module} has no register_stages function"
+                )
+        except ImportError as e:
+            logger.warning(f"Failed to import plugin module {plugin_module}: {e}")
+
+    # Backward compatibility alias
+    register_plugin = register_plugin_module
+
+    @classmethod
+    def discover_plugins(cls) -> None:
+        """Auto-discover and register plugins via entry points.
+
+        Looks for 'sideline.stages' entry points in installed packages.
+        Each entry point should point to a register_stages(registry) function.
+        """
+        if cls._plugins_discovered:
+            return
+
+        try:
+            # Discover entry points for sideline.stages
+            # Python 3.12+ changed the entry_points() API
+            try:
+                entry_points = importlib.metadata.entry_points()
+                if hasattr(entry_points, "get"):
+                    # Python < 3.12
+                    stages_eps = entry_points.get("sideline.stages", [])
+                else:
+                    # Python 3.12+
+                    stages_eps = entry_points.select(group="sideline.stages")
+            except Exception:
+                # Fallback: try both approaches
+                try:
+                    entry_points = importlib.metadata.entry_points()
+                    stages_eps = entry_points.get("sideline.stages", [])
+                except Exception:
+                    stages_eps = []
+
+            for ep in stages_eps:
+                try:
+                    register_func = ep.load()
+                    if callable(register_func):
+                        register_func(cls)
+                        logger.info(f"Discovered and registered plugin: {ep.name}")
+                except Exception as e:
+                    logger.warning(f"Failed to load entry point {ep.name}: {e}")
+
+            cls._plugins_discovered = True
+        except Exception as e:
+            logger.warning(f"Failed to discover plugins: {e}")
+
+    @classmethod
+    def get_discovered_modules(cls) -> set[str]:
+        """Get set of plugin modules that have been loaded."""
+        return cls._plugin_modules.copy()
+
+
+def discover_stages() -> None:
+    """Auto-discover and register all stage implementations.
+
+    This function now only registers framework-level stages (displays, etc.).
+    Application-specific stages should be registered via plugins.
+    """
+    if StageRegistry._discovered:
+        return
+
+    # Register display stages (framework-level)
+    _register_display_stages()
+
+    # Discover plugins via entry points
+    StageRegistry.discover_plugins()
+
+    StageRegistry._discovered = True
+
+
+def _register_display_stages() -> None:
+    """Register display backends as stages."""
+    try:
+        from sideline.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 sideline.display import DisplayRegistry
+        from sideline.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)

sideline/pipeline/stages/framebuffer.py

@@ -0,0 +1,174 @@
+"""
+Frame buffer stage - stores previous frames for temporal effects.
+
+Provides (per-instance, using instance name):
+- framebuffer.{name}.history: list of previous buffers (most recent first)
+- framebuffer.{name}.intensity_history: list of corresponding intensity maps
+- framebuffer.{name}.current_intensity: intensity map for current frame
+
+Capability: "framebuffer.history.{name}"
+"""
+
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+from sideline.display import _strip_ansi
+from sideline.pipeline.core import DataType, PipelineContext, Stage
+
+
+@dataclass
+class FrameBufferConfig:
+    """Configuration for FrameBufferStage."""
+
+    history_depth: int = 2  # Number of previous frames to keep
+    name: str = "default"  # Unique instance name for capability and context keys
+
+
+class FrameBufferStage(Stage):
+    """Stores frame history and computes intensity maps.
+
+    Supports multiple instances with unique capabilities and context keys.
+    """
+
+    name = "framebuffer"
+    category = "effect"  # It's an effect that enriches context with frame history
+
+    def __init__(
+        self,
+        config: FrameBufferConfig | None = None,
+        history_depth: int = 2,
+        name: str = "default",
+    ):
+        self.config = config or FrameBufferConfig(
+            history_depth=history_depth, name=name
+        )
+        self._lock = threading.Lock()
+
+    @property
+    def capabilities(self) -> set[str]:
+        return {f"framebuffer.history.{self.config.name}"}
+
+    @property
+    def dependencies(self) -> set[str]:
+        # Depends on rendered output (since we want to capture final buffer)
+        return {"render.output"}
+
+    @property
+    def inlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}
+
+    @property
+    def outlet_types(self) -> set:
+        return {DataType.TEXT_BUFFER}  # Pass through unchanged
+
+    def init(self, ctx: PipelineContext) -> bool:
+        """Initialize framebuffer state in context."""
+        prefix = f"framebuffer.{self.config.name}"
+        ctx.set(f"{prefix}.history", [])
+        ctx.set(f"{prefix}.intensity_history", [])
+        return True
+
+    def process(self, data: Any, ctx: PipelineContext) -> Any:
+        """Store frame in history and compute intensity.
+
+        Args:
+            data: Current text buffer (list[str])
+            ctx: Pipeline context
+
+        Returns:
+            Same buffer (pass-through)
+        """
+        if not isinstance(data, list):
+            return data
+
+        prefix = f"framebuffer.{self.config.name}"
+
+        # Compute intensity map for current buffer (per-row, length = buffer rows)
+        intensity_map = self._compute_buffer_intensity(data, len(data))
+
+        # Store in context
+        ctx.set(f"{prefix}.current_intensity", intensity_map)
+
+        with self._lock:
+            # Get existing histories
+            history = ctx.get(f"{prefix}.history", [])
+            intensity_hist = ctx.get(f"{prefix}.intensity_history", [])
+
+            # Prepend current frame to history
+            history.insert(0, data.copy())
+            intensity_hist.insert(0, intensity_map)
+
+            # Trim to configured depth
+            max_depth = self.config.history_depth
+            ctx.set(f"{prefix}.history", history[:max_depth])
+            ctx.set(f"{prefix}.intensity_history", intensity_hist[:max_depth])
+
+        return data
+
+    def _compute_buffer_intensity(
+        self, buf: list[str], max_rows: int = 24
+    ) -> list[float]:
+        """Compute average intensity per row in buffer.
+
+        Uses ANSI color if available; falls back to character density.
+
+        Args:
+            buf: Text buffer (list of strings)
+            max_rows: Maximum number of rows to process
+
+        Returns:
+            List of intensity values (0.0-1.0) per row
+        """
+        intensities = []
+        # Limit to viewport height
+        lines = buf[:max_rows]
+
+        for line in lines:
+            # Strip ANSI codes for length calc
+
+            plain = _strip_ansi(line)
+            if not plain:
+                intensities.append(0.0)
+                continue
+
+            # Simple heuristic: ratio of non-space characters
+            # More sophisticated version could parse ANSI RGB brightness
+            filled = sum(1 for c in plain if c not in (" ", "\t"))
+            total = len(plain)
+            intensity = filled / total if total > 0 else 0.0
+            intensities.append(max(0.0, min(1.0, intensity)))
+
+        # Pad to max_rows if needed
+        while len(intensities) < max_rows:
+            intensities.append(0.0)
+
+        return intensities
+
+    def get_frame(
+        self, index: int = 0, ctx: PipelineContext | None = None
+    ) -> list[str] | None:
+        """Get frame from history by index (0 = current, 1 = previous, etc)."""
+        if ctx is None:
+            return None
+        prefix = f"framebuffer.{self.config.name}"
+        history = ctx.get(f"{prefix}.history", [])
+        if 0 <= index < len(history):
+            return history[index]
+        return None
+
+    def get_intensity(
+        self, index: int = 0, ctx: PipelineContext | None = None
+    ) -> list[float] | None:
+        """Get intensity map from history by index."""
+        if ctx is None:
+            return None
+        prefix = f"framebuffer.{self.config.name}"
+        intensity_hist = ctx.get(f"{prefix}.intensity_history", [])
+        if 0 <= index < len(intensity_hist):
+            return intensity_hist[index]
+        return None
+
+    def cleanup(self) -> None:
+        """Cleanup resources."""
+        pass

sideline/plugins/__init__.py

@@ -0,0 +1,26 @@
+"""
+Sideline Plugin System.
+
+This module provides the plugin framework for Sideline, allowing applications
+to extend the pipeline with custom stages, effects, and sources.
+
+Features:
+- Plugin base classes with metadata
+- Security permission system
+- Compatibility management
+- Entry point discovery
+"""
+
+from sideline.plugins.base import StagePlugin, Plugin, PluginMetadata
+from sideline.plugins.security import SecurityCapability, SecurityManager
+from sideline.plugins.compatibility import VersionConstraint, CompatibilityManager
+
+__all__ = [
+    "StagePlugin",
+    "Plugin",  # Backward compatibility alias
+    "PluginMetadata",
+    "SecurityCapability",
+    "SecurityManager",
+    "VersionConstraint",
+    "CompatibilityManager",
+]

sideline/plugins/base.py

@@ -0,0 +1,78 @@
+"""
+Base classes for Sideline plugins.
+
+Provides Plugin base class and PluginMetadata for plugin registration.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import ClassVar, Set
+
+
+@dataclass
+class PluginMetadata:
+    """Plugin metadata with security and compatibility information."""
+
+    name: str
+    version: str
+    author: str
+    description: str
+    sideline_version: str  # Compatible Sideline version (semver constraint)
+    permissions: Set[str] = field(default_factory=set)  # Required security permissions
+    capabilities: Set[str] = field(default_factory=set)  # Provided capabilities
+
+    def validate(self) -> None:
+        """Validate metadata fields."""
+        if not self.name:
+            raise ValueError("Plugin name cannot be empty")
+        if not self.version:
+            raise ValueError("Plugin version cannot be empty")
+        if not self.author:
+            raise ValueError("Plugin author cannot be empty")
+        if not self.sideline_version:
+            raise ValueError("Plugin sideline_version cannot be empty")
+
+
+class StagePlugin(ABC):
+    """Base class for Sideline stage plugins (distributable pipeline components).
+
+    A StagePlugin represents a distributable unit that can contain one or more
+    pipeline stages. Plugins provide metadata for security, compatibility,
+    and versioning.
+
+    Subclasses must implement:
+    - validate_security(granted_permissions) -> bool
+    """
+
+    metadata: ClassVar[PluginMetadata]
+
+    @abstractmethod
+    def validate_security(self, granted_permissions: Set[str]) -> bool:
+        """Check if plugin has required permissions.
+
+        Args:
+            granted_permissions: Set of granted security permissions
+
+        Returns:
+            True if plugin has all required permissions
+        """
+        pass
+
+    @classmethod
+    def get_metadata(cls) -> PluginMetadata:
+        """Get plugin metadata."""
+        return cls.metadata
+
+    @classmethod
+    def get_required_permissions(cls) -> Set[str]:
+        """Get required security permissions."""
+        return cls.metadata.permissions
+
+    @classmethod
+    def get_provided_capabilities(cls) -> Set[str]:
+        """Get provided capabilities."""
+        return cls.metadata.capabilities
+
+
+# Backward compatibility alias
+Plugin = StagePlugin

sideline/plugins/compatibility.py

@@ -0,0 +1,259 @@
+"""
+Compatibility management for Sideline plugins.
+
+Provides semantic version constraint checking and validation.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+
+@dataclass
+class Version:
+    """Semantic version representation."""
+
+    major: int
+    minor: int
+    patch: int
+    pre_release: Optional[str] = None
+    build_metadata: Optional[str] = None
+
+    @classmethod
+    def parse(cls, version_str: str) -> "Version":
+        """Parse version string into Version object.
+
+        Supports formats like:
+        - 1.2.3
+        - 1.2.3-alpha
+        - 1.2.3-beta.1
+        - 1.2.3+build.123
+        """
+        # Remove build metadata if present
+        if "+" in version_str:
+            version_str, build_metadata = version_str.split("+", 1)
+        else:
+            build_metadata = None
+
+        # Parse pre-release if present
+        pre_release = None
+        if "-" in version_str:
+            version_str, pre_release = version_str.split("-", 1)
+
+        # Parse major.minor.patch
+        parts = version_str.split(".")
+        if len(parts) != 3:
+            raise ValueError(f"Invalid version format: {version_str}")
+
+        try:
+            major = int(parts[0])
+            minor = int(parts[1])
+            patch = int(parts[2])
+        except ValueError:
+            raise ValueError(f"Invalid version numbers: {version_str}")
+
+        return cls(major, minor, patch, pre_release, build_metadata)
+
+    def __str__(self) -> str:
+        result = f"{self.major}.{self.minor}.{self.patch}"
+        if self.pre_release:
+            result += f"-{self.pre_release}"
+        if self.build_metadata:
+            result += f"+{self.build_metadata}"
+        return result
+
+    def __lt__(self, other: "Version") -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+
+        # Compare major.minor.patch
+        if (self.major, self.minor, self.patch) < (
+            other.major,
+            other.minor,
+            other.patch,
+        ):
+            return True
+        if (self.major, self.minor, self.patch) > (
+            other.major,
+            other.minor,
+            other.patch,
+        ):
+            return False
+
+        # Pre-release versions have lower precedence
+        if self.pre_release and not other.pre_release:
+            return True
+        if not self.pre_release and other.pre_release:
+            return False
+        if self.pre_release and other.pre_release:
+            return self.pre_release < other.pre_release
+
+        return False
+
+    def __le__(self, other: "Version") -> bool:
+        return self < other or self == other
+
+    def __gt__(self, other: "Version") -> bool:
+        return not (self <= other)
+
+    def __ge__(self, other: "Version") -> bool:
+        return not (self < other)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return (
+            self.major == other.major
+            and self.minor == other.minor
+            and self.patch == other.patch
+            and self.pre_release == other.pre_release
+            and self.build_metadata == other.build_metadata
+        )
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+
+class VersionConstraint:
+    """Semantic version constraint parser and evaluator."""
+
+    def __init__(self, constraint: str):
+        """Parse version constraint string.
+
+        Supports formats:
+        - "1.2.3" - exact version
+        - ">=1.2.3" - minimum version
+        - "<2.0.0" - maximum version
+        - ">=1.0.0,<2.0.0" - version range
+        - "~1.2.3" - pessimistic constraint (>=1.2.3,<1.3.0)
+        - "^1.2.3" - caret constraint (>=1.2.3,<2.0.0)
+        """
+        self.constraint_str = constraint
+        self.min_version: Optional[Version] = None
+        self.max_version: Optional[Version] = None
+        self.exact_version: Optional[Version] = None
+
+        self._parse(constraint)
+
+    def _parse(self, constraint: str) -> None:
+        """Parse constraint string."""
+        # Handle comma-separated constraints
+        if "," in constraint:
+            parts = [p.strip() for p in constraint.split(",")]
+            for part in parts:
+                self._parse_single(part)
+        else:
+            self._parse_single(constraint)
+
+    def _parse_single(self, constraint: str) -> None:
+        """Parse a single constraint."""
+        constraint = constraint.strip()
+
+        # Exact version
+        if not any(op in constraint for op in [">=", "<=", ">", "<", "~", "^"]):
+            self.exact_version = Version.parse(constraint)
+            return
+
+        # Operator-based constraints
+        if ">=" in constraint:
+            op, version_str = constraint.split(">=", 1)
+            self.min_version = Version.parse(version_str.strip())
+        elif "<=" in constraint:
+            op, version_str = constraint.split("<=", 1)
+            self.max_version = Version.parse(version_str.strip())
+        elif ">" in constraint:
+            op, version_str = constraint.split(">", 1)
+            # Strict greater than - increment patch version
+            v = Version.parse(version_str.strip())
+            self.min_version = Version(v.major, v.minor, v.patch + 1)
+        elif "<" in constraint:
+            op, version_str = constraint.split("<", 1)
+            # Strict less than - decrement patch version (simplified)
+            v = Version.parse(version_str.strip())
+            self.max_version = Version(v.major, v.minor, v.patch - 1)
+        elif "~" in constraint:
+            # Pessimistic constraint: ~1.2.3 means >=1.2.3,<1.3.0
+            version_str = constraint[1:]  # Remove ~
+            v = Version.parse(version_str.strip())
+            self.min_version = v
+            self.max_version = Version(v.major, v.minor + 1, 0)
+        elif "^" in constraint:
+            # Caret constraint: ^1.2.3 means >=1.2.3,<2.0.0
+            version_str = constraint[1:]  # Remove ^
+            v = Version.parse(version_str.strip())
+            self.min_version = v
+            self.max_version = Version(v.major + 1, 0, 0)
+
+    def is_compatible(self, version: Version | str) -> bool:
+        """Check if a version satisfies this constraint."""
+        if isinstance(version, str):
+            version = Version.parse(version)
+
+        # Exact version match
+        if self.exact_version is not None:
+            return version == self.exact_version
+
+        # Check minimum version
+        if self.min_version is not None:
+            if version < self.min_version:
+                return False
+
+        # Check maximum version
+        if self.max_version is not None:
+            if version >= self.max_version:
+                return False
+
+        return True
+
+    def __str__(self) -> str:
+        return self.constraint_str
+
+
+class CompatibilityManager:
+    """Manages plugin compatibility with Sideline."""
+
+    @classmethod
+    def get_sideline_version(cls) -> Version:
+        """Get the current Sideline version."""
+        # Import here to avoid circular imports
+        import sideline
+
+        return Version.parse(sideline.__version__)
+
+    @classmethod
+    def validate_compatibility(cls, plugin_version_constraint: str) -> bool:
+        """Validate plugin is compatible with current Sideline version.
+
+        Args:
+            plugin_version_constraint: Version constraint string from plugin metadata
+
+        Returns:
+            True if compatible, False otherwise
+        """
+        try:
+            sideline_version = cls.get_sideline_version()
+            constraint = VersionConstraint(plugin_version_constraint)
+            return constraint.is_compatible(sideline_version)
+        except Exception as e:
+            # If parsing fails, consider incompatible
+            import logging
+
+            logger = logging.getLogger(__name__)
+            logger.warning(f"Failed to validate compatibility: {e}")
+            return False
+
+    @classmethod
+    def get_compatibility_error(cls, plugin_version_constraint: str) -> Optional[str]:
+        """Get compatibility error message if incompatible.
+
+        Returns:
+            Error message string or None if compatible
+        """
+        if cls.validate_compatibility(plugin_version_constraint):
+            return None
+
+        sideline_version = cls.get_sideline_version()
+        return (
+            f"Plugin requires Sideline {plugin_version_constraint}, "
+            f"but current version is {sideline_version}"
+        )

sideline/plugins/security.py

@@ -0,0 +1,92 @@
+"""
+Security system for Sideline plugins.
+
+Provides permission-based security model for plugin execution.
+"""
+
+from enum import Enum, auto
+from typing import Set
+
+
+class SecurityCapability(Enum):
+    """Security capability/permission definitions."""
+
+    READ = auto()  # Read access to buffer/data
+    WRITE = auto()  # Write access to buffer
+    NETWORK = auto()  # Network access
+    FILESYSTEM = auto()  # File system access
+    SYSTEM = auto()  # System information access
+
+    def __str__(self) -> str:
+        return f"security.{self.name.lower()}"
+
+    @classmethod
+    def from_string(cls, permission: str) -> "SecurityCapability":
+        """Parse security capability from string."""
+        if permission.startswith("security."):
+            permission = permission[9:]  # Remove "security." prefix
+        try:
+            return cls[permission.upper()]
+        except KeyError:
+            raise ValueError(f"Unknown security capability: {permission}")
+
+
+class SecurityManager:
+    """Manages security permissions for plugin execution."""
+
+    def __init__(self):
+        self._granted_permissions: Set[str] = set()
+
+    def grant(self, permission: SecurityCapability | str) -> None:
+        """Grant a security permission."""
+        if isinstance(permission, SecurityCapability):
+            permission = str(permission)
+        self._granted_permissions.add(permission)
+
+    def revoke(self, permission: SecurityCapability | str) -> None:
+        """Revoke a security permission."""
+        if isinstance(permission, SecurityCapability):
+            permission = str(permission)
+        self._granted_permissions.discard(permission)
+
+    def has(self, permission: SecurityCapability | str) -> bool:
+        """Check if a permission is granted."""
+        if isinstance(permission, SecurityCapability):
+            permission = str(permission)
+        return permission in self._granted_permissions
+
+    def has_all(self, permissions: Set[str]) -> bool:
+        """Check if all permissions are granted."""
+        return all(self.has(p) for p in permissions)
+
+    def get_granted(self) -> Set[str]:
+        """Get all granted permissions."""
+        return self._granted_permissions.copy()
+
+    def reset(self) -> None:
+        """Reset all permissions."""
+        self._granted_permissions.clear()
+
+
+# Global security manager instance
+_global_security = SecurityManager()
+
+
+def get_global_security() -> SecurityManager:
+    """Get the global security manager instance."""
+    return _global_security
+
+
+def grant(permission: SecurityCapability | str) -> None:
+    """Grant a global security permission."""
+    _global_security.grant(permission)
+
+
+def revoke(permission: SecurityCapability | str) -> None:
+    """Revoke a global security permission."""
+    _global_security.revoke(permission)
+
+
+def has(permission: SecurityCapability | str) -> bool:
+    """Check if a global permission is granted."""
+    return _global_security.has(permission)

sideline/preset_packs/__init__.py

@@ -0,0 +1,17 @@
+"""
+Preset pack system for Sideline.
+
+Allows bundling plugins, presets, and configurations into distributable packs
+with ASCII art encoding for fun and version control friendly storage.
+"""
+
+from sideline.preset_packs.pack_format import PresetPack, PresetPackMetadata
+from sideline.preset_packs.manager import PresetPackManager
+from sideline.preset_packs.encoder import PresetPackEncoder
+
+__all__ = [
+    "PresetPack",
+    "PresetPackMetadata",
+    "PresetPackManager",
+    "PresetPackEncoder",
+]

sideline/preset_packs/encoder.py

@@ -0,0 +1,211 @@
+"""
+Preset pack encoder with ASCII art compression.
+
+Compresses plugin code and encodes it as ASCII art for fun and version control.
+"""
+
+import base64
+import zlib
+import textwrap
+from typing import Tuple
+
+
+class PresetPackEncoder:
+    """Encodes and decodes preset packs with ASCII art compression."""
+
+    # ASCII art frame characters
+    FRAME_TOP_LEFT = "┌"
+    FRAME_TOP_RIGHT = "┐"
+    FRAME_BOTTOM_LEFT = "└"
+    FRAME_BOTTOM_RIGHT = "┘"
+    FRAME_HORIZONTAL = "─"
+    FRAME_VERTICAL = "│"
+
+    # Data block characters (for visual representation)
+    DATA_CHARS = " ░▒▓█"
+
+    @classmethod
+    def encode_plugin_code(cls, code: str, name: str = "plugin") -> str:
+        """Encode plugin code as ASCII art.
+
+        Args:
+            code: Python source code to encode
+            name: Plugin name for metadata
+
+        Returns:
+            ASCII art encoded plugin code
+        """
+        # Compress the code
+        compressed = zlib.compress(code.encode("utf-8"))
+
+        # Encode as base64
+        b64 = base64.b64encode(compressed).decode("ascii")
+
+        # Wrap in ASCII art frame
+        return cls._wrap_in_ascii_art(b64, name)
+
+    @classmethod
+    def decode_plugin_code(cls, ascii_art: str) -> str:
+        """Decode ASCII art to plugin code.
+
+        Args:
+            ascii_art: ASCII art encoded plugin code
+
+        Returns:
+            Decoded Python source code
+        """
+        # Extract base64 from ASCII art
+        b64 = cls._extract_from_ascii_art(ascii_art)
+
+        # Decode base64
+        compressed = base64.b64decode(b64)
+
+        # Decompress
+        code = zlib.decompress(compressed).decode("utf-8")
+
+        return code
+
+    @classmethod
+    def _wrap_in_ascii_art(cls, data: str, name: str) -> str:
+        """Wrap data in ASCII art frame."""
+        # Calculate frame width
+        max_line_length = 60
+        lines = textwrap.wrap(data, max_line_length)
+
+        # Find longest line for frame width
+        longest_line = max(len(line) for line in lines) if lines else 0
+        frame_width = longest_line + 4  # 2 padding + 2 borders
+
+        # Build ASCII art
+        result = []
+
+        # Top border
+        result.append(
+            cls.FRAME_TOP_LEFT
+            + cls.FRAME_HORIZONTAL * (frame_width - 2)
+            + cls.FRAME_TOP_RIGHT
+        )
+
+        # Plugin name header
+        name_line = f" {name} "
+        name_padding = frame_width - 2 - len(name_line)
+        left_pad = name_padding // 2
+        right_pad = name_padding - left_pad
+        result.append(
+            cls.FRAME_VERTICAL
+            + " " * left_pad
+            + name_line
+            + " " * right_pad
+            + cls.FRAME_VERTICAL
+        )
+
+        # Separator line
+        result.append(
+            cls.FRAME_VERTICAL
+            + cls.FRAME_HORIZONTAL * (frame_width - 2)
+            + cls.FRAME_VERTICAL
+        )
+
+        # Data lines
+        for line in lines:
+            padding = frame_width - 2 - len(line)
+            result.append(
+                cls.FRAME_VERTICAL + line + " " * padding + cls.FRAME_VERTICAL
+            )
+
+        # Bottom border
+        result.append(
+            cls.FRAME_BOTTOM_LEFT
+            + cls.FRAME_HORIZONTAL * (frame_width - 2)
+            + cls.FRAME_BOTTOM_RIGHT
+        )
+
+        return "\n".join(result)
+
+    @classmethod
+    def _extract_from_ascii_art(cls, ascii_art: str) -> str:
+        """Extract base64 data from ASCII art frame."""
+        lines = ascii_art.strip().split("\n")
+
+        # Skip top and bottom borders, header, and separator
+        data_lines = lines[3:-1]
+
+        # Extract data from between frame characters
+        extracted = []
+        for line in data_lines:
+            if len(line) > 2:
+                # Remove frame characters and extract content
+                content = line[1:-1].rstrip()
+                extracted.append(content)
+
+        return "".join(extracted)
+
+    @classmethod
+    def encode_toml(cls, toml_data: str, name: str = "pack") -> str:
+        """Encode TOML data as ASCII art.
+
+        Args:
+            toml_data: TOML configuration data
+            name: Pack name
+
+        Returns:
+            ASCII art encoded TOML
+        """
+        # Compress
+        compressed = zlib.compress(toml_data.encode("utf-8"))
+
+        # Encode as base64
+        b64 = base64.b64encode(compressed).decode("ascii")
+
+        # Create visual representation using data characters
+        visual_data = cls._data_to_visual(b64)
+
+        return cls._wrap_in_ascii_art(visual_data, name)
+
+    @classmethod
+    def decode_toml(cls, ascii_art: str) -> str:
+        """Decode ASCII art to TOML data.
+
+        Args:
+            ascii_art: ASCII art encoded TOML
+
+        Returns:
+            Decoded TOML data
+        """
+        # Extract base64 from ASCII art
+        b64 = cls._extract_from_ascii_art(ascii_art)
+
+        # Decode base64
+        compressed = base64.b64decode(b64)
+
+        # Decompress
+        toml_data = zlib.decompress(compressed).decode("utf-8")
+
+        return toml_data
+
+    @classmethod
+    def _data_to_visual(cls, data: str) -> str:
+        """Convert base64 data to visual representation.
+
+        This creates a fun visual pattern based on the data.
+        """
+        # Simple mapping: each character to a data block character
+        # This is purely for visual appeal
+        visual = ""
+        for i, char in enumerate(data):
+            # Use character code to select visual block
+            idx = ord(char) % len(cls.DATA_CHARS)
+            visual += cls.DATA_CHARS[idx]
+
+            # Add line breaks for visual appeal
+            if (i + 1) % 60 == 0:
+                visual += "\n"
+
+        return visual
+
+    @classmethod
+    def get_visual_representation(cls, data: str) -> str:
+        """Get a visual representation of data for display."""
+        compressed = zlib.compress(data.encode("utf-8"))
+        b64 = base64.b64encode(compressed).decode("ascii")
+        return cls._data_to_visual(b64)

sideline/preset_packs/manager.py

@@ -0,0 +1,194 @@
+"""
+Preset pack manager for loading, validating, and managing preset packs.
+"""
+
+import logging
+import os
+from typing import Dict, List, Optional
+
+import tomli
+
+from sideline.preset_packs.pack_format import PresetPack, PresetPackMetadata
+from sideline.preset_packs.encoder import PresetPackEncoder
+from sideline.plugins.compatibility import CompatibilityManager
+
+logger = logging.getLogger(__name__)
+
+
+class PresetPackManager:
+    """Manages preset pack loading and validation."""
+
+    def __init__(self, pack_dir: Optional[str] = None):
+        """Initialize preset pack manager.
+
+        Args:
+            pack_dir: Directory to search for preset packs
+        """
+        self.pack_dir = pack_dir or os.path.expanduser("~/.config/sideline/packs")
+        self._packs: Dict[str, PresetPack] = {}
+
+    def load_pack(self, pack_path: str) -> Optional[PresetPack]:
+        """Load a preset pack from a file.
+
+        Args:
+            pack_path: Path to the preset pack file (.tpack or .toml)
+
+        Returns:
+            Loaded PresetPack or None if failed
+        """
+        try:
+            with open(pack_path, "rb") as f:
+                # Try loading as TOML first
+                if pack_path.endswith(".toml"):
+                    data = tomli.load(f)
+                    pack = PresetPack.from_dict(data)
+                elif pack_path.endswith(".tpack"):
+                    # Load ASCII art encoded pack
+                    content = f.read().decode("utf-8")
+                    pack = self._load_ascii_pack(content)
+                else:
+                    logger.error(f"Unknown file format: {pack_path}")
+                    return None
+
+            # Validate compatibility
+            if not CompatibilityManager.validate_compatibility(
+                pack.metadata.sideline_version
+            ):
+                error = CompatibilityManager.get_compatibility_error(
+                    pack.metadata.sideline_version
+                )
+                logger.warning(f"Pack {pack.metadata.name} incompatible: {error}")
+                return None
+
+            # Store pack
+            self._packs[pack.metadata.name] = pack
+            logger.info(
+                f"Loaded preset pack: {pack.metadata.name} v{pack.metadata.version}"
+            )
+            return pack
+
+        except Exception as e:
+            logger.error(f"Failed to load preset pack {pack_path}: {e}")
+            return None
+
+    def _load_ascii_pack(self, content: str) -> PresetPack:
+        """Load pack from ASCII art encoded content."""
+        # Extract TOML from ASCII art
+        toml_data = PresetPackEncoder.decode_toml(content)
+
+        # Parse TOML
+        import tomli
+
+        data = tomli.loads(toml_data)
+
+        return PresetPack.from_dict(data)
+
+    def load_directory(self, directory: Optional[str] = None) -> List[PresetPack]:
+        """Load all preset packs from a directory.
+
+        Args:
+            directory: Directory to search (defaults to pack_dir)
+
+        Returns:
+            List of loaded PresetPack objects
+        """
+        directory = directory or self.pack_dir
+
+        if not os.path.exists(directory):
+            logger.warning(f"Preset pack directory does not exist: {directory}")
+            return []
+
+        loaded = []
+        for filename in os.listdir(directory):
+            if filename.endswith((".toml", ".tpack")):
+                path = os.path.join(directory, filename)
+                pack = self.load_pack(path)
+                if pack:
+                    loaded.append(pack)
+
+        return loaded
+
+    def save_pack(
+        self, pack: PresetPack, output_path: str, format: str = "toml"
+    ) -> bool:
+        """Save a preset pack to a file.
+
+        Args:
+            pack: PresetPack to save
+            output_path: Path to save the pack
+            format: Output format ("toml" or "tpack")
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            if format == "toml":
+                import tomli_w
+
+                with open(output_path, "w") as f:
+                    tomli_w.dump(pack.to_dict(), f)
+            elif format == "tpack":
+                # Encode as ASCII art
+                toml_data = self._pack_to_toml(pack)
+                ascii_art = PresetPackEncoder.encode_toml(toml_data, pack.metadata.name)
+
+                with open(output_path, "w") as f:
+                    f.write(ascii_art)
+            else:
+                logger.error(f"Unknown format: {format}")
+                return False
+
+            logger.info(f"Saved preset pack: {output_path}")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to save preset pack: {e}")
+            return False
+
+    def _pack_to_toml(self, pack: PresetPack) -> str:
+        """Convert PresetPack to TOML string."""
+        import tomli_w
+
+        return tomli_w.dumps(pack.to_dict())
+
+    def get_pack(self, name: str) -> Optional[PresetPack]:
+        """Get a loaded preset pack by name."""
+        return self._packs.get(name)
+
+    def list_packs(self) -> List[str]:
+        """List all loaded preset pack names."""
+        return list(self._packs.keys())
+
+    def register_pack_plugins(self, pack: PresetPack):
+        """Register all plugins from a preset pack.
+
+        Args:
+            pack: PresetPack containing plugins
+        """
+        from sideline.pipeline import StageRegistry
+
+        for plugin_entry in pack.plugins:
+            try:
+                # Decode plugin code
+                code = PresetPackEncoder.decode_plugin_code(plugin_entry.encoded_code)
+
+                # Execute plugin code to get the class
+                local_ns = {}
+                exec(code, local_ns)
+
+                # Find the plugin class (first class defined)
+                plugin_class = None
+                for obj in local_ns.values():
+                    if isinstance(obj, type) and hasattr(obj, "metadata"):
+                        plugin_class = obj
+                        break
+
+                if plugin_class:
+                    # Register the plugin
+                    StageRegistry.register(plugin_entry.category, plugin_class)
+                    logger.info(f"Registered plugin: {plugin_entry.name}")
+                else:
+                    logger.warning(f"No plugin class found in {plugin_entry.name}")
+
+            except Exception as e:
+                logger.error(f"Failed to register plugin {plugin_entry.name}: {e}")

sideline/preset_packs/pack_format.py

@@ -0,0 +1,127 @@
+"""
+Preset pack format definition.
+
+Defines the structure of preset packs and their TOML-based configuration.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class PresetPackMetadata:
+    """Metadata for a preset pack."""
+
+    name: str
+    version: str
+    author: str
+    description: str
+    sideline_version: str  # Compatible Sideline version
+    created: Optional[str] = None  # ISO 8601 timestamp
+    tags: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for TOML serialization."""
+        return {
+            "name": self.name,
+            "version": self.version,
+            "author": self.author,
+            "description": self.description,
+            "sideline_version": self.sideline_version,
+            "created": self.created,
+            "tags": self.tags,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "PresetPackMetadata":
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            version=data["version"],
+            author=data["author"],
+            description=data["description"],
+            sideline_version=data["sideline_version"],
+            created=data.get("created"),
+            tags=data.get("tags", []),
+        )
+
+
+@dataclass
+class PluginEntry:
+    """Entry for a plugin in the preset pack."""
+
+    name: str
+    category: str  # source, effect, display, camera
+    encoded_code: str  # ASCII art encoded plugin code
+    permissions: List[str] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for TOML serialization."""
+        return {
+            "name": self.name,
+            "category": self.category,
+            "code": self.encoded_code,
+            "permissions": self.permissions,
+            "capabilities": self.capabilities,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "PluginEntry":
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            category=data["category"],
+            encoded_code=data["code"],
+            permissions=data.get("permissions", []),
+            capabilities=data.get("capabilities", []),
+        )
+
+
+@dataclass
+class PresetEntry:
+    """Entry for a preset in the preset pack."""
+
+    name: str
+    config: Dict  # Preset configuration (TOML-compatible)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for TOML serialization."""
+        return {
+            "name": self.name,
+            "config": self.config,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "PresetEntry":
+        """Create from dictionary."""
+        return cls(
+            name=data["name"],
+            config=data["config"],
+        )
+
+
+@dataclass
+class PresetPack:
+    """Complete preset pack with metadata, plugins, and presets."""
+
+    metadata: PresetPackMetadata
+    plugins: List[PluginEntry] = field(default_factory=list)
+    presets: List[PresetEntry] = field(default_factory=list)
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary for TOML serialization."""
+        return {
+            "pack": self.metadata.to_dict(),
+            "plugins": [p.to_dict() for p in self.plugins],
+            "presets": [p.to_dict() for p in self.presets],
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "PresetPack":
+        """Create from dictionary."""
+        return cls(
+            metadata=PresetPackMetadata.from_dict(data["pack"]),
+            plugins=[PluginEntry.from_dict(p) for p in data.get("plugins", [])],
+            presets=[PresetEntry.from_dict(p) for p in data.get("presets", [])],
+        )

sideline/render/__init__.py

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

sideline/render/blocks.py

@@ -0,0 +1,245 @@
+"""Block rendering core - Font loading, text rasterization, word-wrap, and headline assembly.
+
+Provides PIL font-based rendering to terminal half-block characters.
+"""
+
+import random
+import re
+from pathlib import Path
+from typing import Optional, Tuple
+
+from PIL import Image, ImageDraw, ImageFont
+
+from sideline.fonts import get_default_font_path, get_default_font_size
+
+
+# ─── FONT LOADING ─────────────────────────────────────────
+_FONT_OBJ = None
+_FONT_OBJ_KEY = None
+_FONT_CACHE = {}
+
+
+def font():
+    """Lazy-load the default Sideline font."""
+    global _FONT_OBJ, _FONT_OBJ_KEY
+
+    try:
+        font_path = get_default_font_path()
+        font_size = get_default_font_size()
+    except FileNotFoundError:
+        # Fallback to system default if Sideline font not found
+        return ImageFont.load_default()
+
+    key = (font_path, font_size)
+    if _FONT_OBJ is None or key != _FONT_OBJ_KEY:
+        try:
+            _FONT_OBJ = ImageFont.truetype(font_path, font_size)
+            _FONT_OBJ_KEY = key
+        except Exception:
+            # If loading fails, fall back to system default
+            _FONT_OBJ = ImageFont.load_default()
+            _FONT_OBJ_KEY = key
+    return _FONT_OBJ
+
+
+def clear_font_cache():
+    """Reset cached font objects."""
+    global _FONT_OBJ, _FONT_OBJ_KEY
+    _FONT_OBJ = None
+    _FONT_OBJ_KEY = None
+
+
+def load_font_face(font_path, font_index=0, size=None):
+    """Load a specific face from a font file or collection."""
+    if size is None:
+        size = get_default_font_size()
+    return ImageFont.truetype(font_path, size, index=font_index)
+
+
+def list_font_faces(font_path, max_faces=64):
+    """Return discoverable face indexes + display names from a font file."""
+    faces = []
+    for idx in range(max_faces):
+        try:
+            fnt = load_font_face(font_path, idx)
+        except Exception:
+            if idx == 0:
+                raise
+            break
+        family, style = fnt.getname()
+        display = f"{family} {style}".strip()
+        if not display:
+            display = f"{Path(font_path).stem} [{idx}]"
+        faces.append({"index": idx, "name": display})
+    return faces
+
+
+def font_for_lang(lang: Optional[str] = None):
+    """Get appropriate font for a language.
+
+    Currently uses the default Sideline font for all languages.
+    Language-specific fonts can be added via the font cache system.
+    """
+    if lang is None:
+        return font()
+    if lang not in _FONT_CACHE:
+        # Try to load language-specific font, fall back to default
+        try:
+            # Could add language-specific font logic here
+            _FONT_CACHE[lang] = font()
+        except Exception:
+            _FONT_CACHE[lang] = font()
+    return _FONT_CACHE[lang]
+
+
+# ─── RASTERIZATION ────────────────────────────────────────
+def render_line(text, fnt=None):
+    """Render a line of text as terminal rows using OTF font + half-blocks."""
+    if fnt is None:
+        fnt = font()
+    bbox = fnt.getbbox(text)
+    if not bbox or bbox[2] <= bbox[0]:
+        return [""]
+    pad = 4
+    img_w = bbox[2] - bbox[0] + pad * 2
+    img_h = bbox[3] - bbox[1] + pad * 2
+    img = Image.new("L", (img_w, img_h), 0)
+    draw = ImageDraw.Draw(img)
+    draw.text((-bbox[0] + pad, -bbox[1] + pad), text, fill=255, font=fnt)
+
+    # Rendering parameters (can be made configurable)
+    render_h = 6  # Terminal rows per rendered line
+    ssaa = 2  # Supersampling anti-aliasing factor
+
+    pix_h = render_h * 2
+    hi_h = pix_h * ssaa
+    scale = hi_h / max(img_h, 1)
+    new_w_hi = max(1, int(img_w * scale))
+    img = img.resize((new_w_hi, hi_h), Image.Resampling.LANCZOS)
+    new_w = max(1, int(new_w_hi / ssaa))
+    img = img.resize((new_w, pix_h), Image.Resampling.LANCZOS)
+    data = img.tobytes()
+    thr = 80
+    rows = []
+    for y in range(0, pix_h, 2):
+        row = []
+        for x in range(new_w):
+            top = data[y * new_w + x] > thr
+            bot = data[(y + 1) * new_w + x] > thr if y + 1 < pix_h else False
+            if top and bot:
+                row.append("█")
+            elif top:
+                row.append("▀")
+            elif bot:
+                row.append("▄")
+            else:
+                row.append(" ")
+        rows.append("".join(row))
+    return rows
+
+
+def big_wrap(text: str, width: int, fnt=None) -> list[str]:
+    """Wrap text and render to big block characters."""
+    if fnt is None:
+        fnt = font()
+    text = re.sub(r"\s+", " ", text.upper())
+    words = text.split()
+    lines = []
+    cur = ""
+
+    # Get font size for height calculation
+    try:
+        font_size = fnt.size if hasattr(fnt, "size") else get_default_font_size()
+    except Exception:
+        font_size = get_default_font_size()
+
+    render_h = 6  # Terminal rows per rendered line
+
+    for word in words:
+        test = f"{cur} {word}".strip() if cur else word
+        bbox = fnt.getbbox(test)
+        if bbox:
+            img_h = bbox[3] - bbox[1] + 8
+            pix_h = render_h * 2
+            scale = pix_h / max(img_h, 1)
+            term_w = int((bbox[2] - bbox[0] + 8) * scale)
+        else:
+            term_w = 0
+        max_term_w = width - 4 - 4
+        if term_w > max_term_w and cur:
+            lines.append(cur)
+            cur = word
+        else:
+            cur = test
+    if cur:
+        lines.append(cur)
+    out = []
+    for i, ln in enumerate(lines):
+        out.extend(render_line(ln, fnt))
+        if i < len(lines) - 1:
+            out.append("")
+    return out
+
+
+# ─── HEADLINE BLOCK ASSEMBLY ─────────────────────────────
+def make_block(title: str, src: str, ts: str, w: int) -> Tuple[list[str], str, int]:
+    """Render a headline into a content block with color.
+
+    Args:
+        title: Headline text to render
+        src: Source identifier (for metadata)
+        ts: Timestamp string (for metadata)
+        w: Width constraint in terminal characters
+
+    Returns:
+        tuple: (content_lines, color_code, meta_row_index)
+            - content_lines: List of rendered text lines
+            - color_code: ANSI color code for display
+            - meta_row_index: Row index of metadata line
+    """
+    # Use default font for all languages (simplified from original)
+    lang_font = font()
+
+    # Simple uppercase conversion (can be made language-aware later)
+    title_up = re.sub(r"\s+", " ", title.upper())
+
+    # Standardize quotes and dashes
+    for old, new in [
+        ("\u2019", "'"),
+        ("\u2018", "'"),
+        ("\u201c", '"'),
+        ("\u201d", '"'),
+        ("\u2013", "-"),
+        ("\u2014", "-"),
+    ]:
+        title_up = title_up.replace(old, new)
+
+    big_rows = big_wrap(title_up, w - 4, lang_font)
+
+    # Matrix-style color selection
+    hc = random.choice(
+        [
+            "\033[38;5;46m",  # matrix green
+            "\033[38;5;34m",  # dark green
+            "\033[38;5;82m",  # lime
+            "\033[38;5;48m",  # sea green
+            "\033[38;5;37m",  # teal
+            "\033[38;5;44m",  # cyan
+            "\033[38;5;87m",  # sky
+            "\033[38;5;117m",  # ice blue
+            "\033[38;5;250m",  # cool white
+            "\033[38;5;156m",  # pale green
+            "\033[38;5;120m",  # mint
+            "\033[38;5;80m",  # dark cyan
+            "\033[38;5;108m",  # grey-green
+            "\033[38;5;115m",  # sage
+            "\033[1;38;5;46m",  # bold green
+            "\033[1;38;5;250m",  # bold white
+        ]
+    )
+
+    content = ["  " + r for r in big_rows]
+    content.append("")
+    meta = f"\u2591 {src} \u00b7 {ts}"
+    content.append(" " * max(2, w - len(meta) - 2) + meta)
+    return content, hc, len(content) - 1  # (rows, color, meta_row_index)

sideline/render/gradient.py

@@ -0,0 +1,136 @@
+"""Gradient coloring for rendered block characters.
+
+Provides left-to-right and complementary gradient effects for terminal display.
+"""
+
+from sideline.terminal import RST
+
+# Left → right: white-hot leading edge fades to near-black
+GRAD_COLS = [
+    "\033[1;38;5;231m",  # white
+    "\033[1;38;5;195m",  # pale cyan-white
+    "\033[38;5;123m",  # bright cyan
+    "\033[38;5;118m",  # bright lime
+    "\033[38;5;82m",  # lime
+    "\033[38;5;46m",  # bright green
+    "\033[38;5;40m",  # green
+    "\033[38;5;34m",  # medium green
+    "\033[38;5;28m",  # dark green
+    "\033[38;5;22m",  # deep green
+    "\033[2;38;5;22m",  # dim deep green
+    "\033[2;38;5;235m",  # near black
+]
+
+# Complementary sweep for queue messages (opposite hue family from ticker greens)
+MSG_GRAD_COLS = [
+    "\033[1;38;5;231m",  # white
+    "\033[1;38;5;225m",  # pale pink-white
+    "\033[38;5;219m",  # bright pink
+    "\033[38;5;213m",  # hot pink
+    "\033[38;5;207m",  # magenta
+    "\033[38;5;201m",  # bright magenta
+    "\033[38;5;165m",  # orchid-red
+    "\033[38;5;161m",  # ruby-magenta
+    "\033[38;5;125m",  # dark magenta
+    "\033[38;5;89m",  # deep maroon-magenta
+    "\033[2;38;5;89m",  # dim deep maroon-magenta
+    "\033[2;38;5;235m",  # near black
+]
+
+
+def lr_gradient(rows, offset=0.0, grad_cols=None):
+    """Color each non-space block character with a shifting left-to-right gradient.
+
+    Args:
+        rows: List of text lines with block characters
+        offset: Gradient offset (0.0-1.0) for animation
+        grad_cols: List of ANSI color codes (default: GRAD_COLS)
+
+    Returns:
+        List of lines with gradient coloring applied
+    """
+    cols = grad_cols or GRAD_COLS
+    n = len(cols)
+    max_x = max((len(r.rstrip()) for r in rows if r.strip()), default=1)
+    out = []
+    for row in rows:
+        if not row.strip():
+            out.append(row)
+            continue
+        buf = []
+        for x, ch in enumerate(row):
+            if ch == " ":
+                buf.append(" ")
+            else:
+                shifted = (x / max(max_x - 1, 1) + offset) % 1.0
+                idx = min(round(shifted * (n - 1)), n - 1)
+                buf.append(f"{cols[idx]}{ch}{RST}")
+        out.append("".join(buf))
+    return out
+
+
+def lr_gradient_opposite(rows, offset=0.0):
+    """Complementary (opposite wheel) gradient used for queue message panels.
+
+    Args:
+        rows: List of text lines with block characters
+        offset: Gradient offset (0.0-1.0) for animation
+
+    Returns:
+        List of lines with complementary gradient coloring applied
+    """
+    return lr_gradient(rows, offset, MSG_GRAD_COLS)
+
+
+def msg_gradient(rows, offset):
+    """Apply message (ntfy) gradient using theme complementary colors.
+
+    Returns colored rows using ACTIVE_THEME.message_gradient if available,
+    falling back to default magenta if no theme is set.
+
+    Args:
+        rows: List of text strings to colorize
+        offset: Gradient offset (0.0-1.0) for animation
+
+    Returns:
+        List of rows with ANSI color codes applied
+    """
+    from engine import config
+
+    # Check if theme is set and use it
+    if config.ACTIVE_THEME:
+        cols = _color_codes_to_ansi(config.ACTIVE_THEME.message_gradient)
+    else:
+        # Fallback to default magenta gradient
+        cols = MSG_GRAD_COLS
+
+    return lr_gradient(rows, offset, cols)
+
+
+def _color_codes_to_ansi(color_codes):
+    """Convert a list of 256-color codes to ANSI escape code strings.
+
+    Pattern: first 2 are bold, middle 8 are normal, last 2 are dim.
+
+    Args:
+        color_codes: List of 12 integers (256-color palette codes)
+
+    Returns:
+        List of ANSI escape code strings
+    """
+    if not color_codes or len(color_codes) != 12:
+        # Fallback to default green if invalid
+        return GRAD_COLS
+
+    result = []
+    for i, code in enumerate(color_codes):
+        if i < 2:
+            # Bold for first 2 (bright leading edge)
+            result.append(f"\033[1;38;5;{code}m")
+        elif i < 10:
+            # Normal for middle 8
+            result.append(f"\033[38;5;{code}m")
+        else:
+            # Dim for last 2 (dark trailing edge)
+            result.append(f"\033[2;38;5;{code}m")
+    return result

sideline/sensors/__init__.py

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

sideline/sensors/mic.py

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

sideline/sensors/oscillator.py

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

sideline/sensors/pipeline_metrics.py

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

sideline/terminal.py

@@ -0,0 +1,108 @@
+"""
+ANSI escape codes and terminal control constants.
+
+Provides standard ANSI escape sequences for terminal manipulation.
+This module belongs in Sideline as it's a framework-level concern.
+"""
+
+# ─── ANSI RESET ──────────────────────────────────────────
+RST = "\033[0m"
+
+# ─── TEXT STYLES ─────────────────────────────────────────
+BOLD = "\033[1m"
+DIM = "\033[2m"
+UNDERLINE = "\033[4m"
+REVERSE = "\033[7m"
+
+# ─── MATRIX GREENS (Sideline default theme) ─────────────
+G_HI = "\033[38;5;46m"  # Bright green
+G_MID = "\033[38;5;34m"  # Medium green
+G_LO = "\033[38;5;22m"  # Dark green
+G_DIM = "\033[2;38;5;34m"  # Dim green
+
+# ─── COOL TONES ──────────────────────────────────────────
+W_COOL = "\033[38;5;250m"  # Cool white
+W_DIM = "\033[2;38;5;245m"  # Dim white
+W_GHOST = "\033[2;38;5;238m"  # Ghost white
+C_DIM = "\033[2;38;5;37m"  # Dim cyan
+
+# ─── TERMINAL CONTROL ────────────────────────────────────
+CLR = "\033[2J\033[H"  # Clear screen and home cursor
+CURSOR_OFF = "\033[?25l"  # Hide cursor
+CURSOR_ON = "\033[?25h"  # Show cursor
+
+
+# ─── CURSOR POSITIONING ──────────────────────────────────
+def cursor_pos(row: int, col: int) -> str:
+    """Move cursor to position (row, col)."""
+    return f"\033[{row};{col}H"
+
+
+# ─── COLOR UTILITIES ─────────────────────────────────────
+def fg_color(code: int) -> str:
+    """Set foreground color (0-255)."""
+    return f"\033[38;5;{code}m"
+
+
+def bg_color(code: int) -> str:
+    """Set background color (0-255)."""
+    return f"\033[48;5;{code}m"
+
+
+# ─── COMMON COLORS ───────────────────────────────────────
+BLACK = "\033[30m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+MAGENTA = "\033[35m"
+CYAN = "\033[36m"
+WHITE = "\033[37m"
+
+# ─── BRIGHT COLORS ───────────────────────────────────────
+BRIGHT_BLACK = "\033[90m"
+BRIGHT_RED = "\033[91m"
+BRIGHT_GREEN = "\033[92m"
+BRIGHT_YELLOW = "\033[93m"
+BRIGHT_BLUE = "\033[94m"
+BRIGHT_MAGENTA = "\033[95m"
+BRIGHT_CYAN = "\033[96m"
+BRIGHT_WHITE = "\033[97m"
+
+__all__ = [
+    "RST",
+    "BOLD",
+    "DIM",
+    "UNDERLINE",
+    "REVERSE",
+    "G_HI",
+    "G_MID",
+    "G_LO",
+    "G_DIM",
+    "W_COOL",
+    "W_DIM",
+    "W_GHOST",
+    "C_DIM",
+    "CLR",
+    "CURSOR_OFF",
+    "CURSOR_ON",
+    "cursor_pos",
+    "fg_color",
+    "bg_color",
+    "BLACK",
+    "RED",
+    "GREEN",
+    "YELLOW",
+    "BLUE",
+    "MAGENTA",
+    "CYAN",
+    "WHITE",
+    "BRIGHT_BLACK",
+    "BRIGHT_RED",
+    "BRIGHT_GREEN",
+    "BRIGHT_YELLOW",
+    "BRIGHT_BLUE",
+    "BRIGHT_MAGENTA",
+    "BRIGHT_CYAN",
+    "BRIGHT_WHITE",
+]

tests/test_graph_pipeline.py

@@ -1,260 +0,0 @@
-"""
-Tests for the graph-based pipeline configuration.
-"""
-
-import pytest
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.graph import Graph, NodeType, Node
-from engine.pipeline.graph_adapter import dict_to_pipeline, graph_to_pipeline
-
-
-@pytest.fixture(autouse=True)
-def setup_effects():
-    """Ensure effects are discovered before each test."""
-    discover_plugins()
-
-
-class TestGraphCreation:
-    """Tests for Graph creation and manipulation."""
-
-    def test_create_empty_graph(self):
-        """Graph can be created empty."""
-        graph = Graph()
-        assert len(graph.nodes) == 0
-        assert len(graph.connections) == 0
-
-    def test_add_node(self):
-        """Graph.node adds a node."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE, source="headlines")
-
-        assert "source" in graph.nodes
-        node = graph.nodes["source"]
-        assert node.name == "source"
-        assert node.type == NodeType.SOURCE
-        assert node.config["source"] == "headlines"
-
-    def test_add_node_string_type(self):
-        """Graph.node accepts string type."""
-        graph = Graph()
-        graph.node("camera", "camera", mode="scroll")
-
-        assert "camera" in graph.nodes
-        assert graph.nodes["camera"].type == NodeType.CAMERA
-
-    def test_connect_nodes(self):
-        """Graph.connect adds connection between nodes."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE)
-        graph.node("display", NodeType.DISPLAY)
-        graph.connect("source", "display")
-
-        assert len(graph.connections) == 1
-        conn = graph.connections[0]
-        assert conn.source == "source"
-        assert conn.target == "display"
-
-    def test_connect_nonexistent_source(self):
-        """Graph.connect raises error for nonexistent source."""
-        graph = Graph()
-        graph.node("display", NodeType.DISPLAY)
-
-        with pytest.raises(ValueError, match="Source node 'missing' not found"):
-            graph.connect("missing", "display")
-
-    def test_connect_nonexistent_target(self):
-        """Graph.connect raises error for nonexistent target."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE)
-
-        with pytest.raises(ValueError, match="Target node 'missing' not found"):
-            graph.connect("source", "missing")
-
-    def test_chain_connects_nodes(self):
-        """Graph.chain connects nodes in sequence."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE)
-        graph.node("camera", NodeType.CAMERA)
-        graph.node("display", NodeType.DISPLAY)
-        graph.chain("source", "camera", "display")
-
-        assert len(graph.connections) == 2
-        assert graph.connections[0].source == "source"
-        assert graph.connections[0].target == "camera"
-        assert graph.connections[1].source == "camera"
-        assert graph.connections[1].target == "display"
-
-
-class TestGraphValidation:
-    """Tests for Graph validation."""
-
-    def test_validate_disconnected_node(self):
-        """Validation detects disconnected nodes."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE)
-        graph.node("orphan", NodeType.EFFECT, effect="noise")
-
-        errors = graph.validate()
-        # Both source and orphan are disconnected
-        assert len(errors) == 2
-        assert any("orphan" in e and "not connected" in e for e in errors)
-        assert any("source" in e and "not connected" in e for e in errors)
-
-    def test_validate_cycle_detection(self):
-        """Validation detects cycles."""
-        graph = Graph()
-        graph.node("a", NodeType.SOURCE)
-        graph.node("b", NodeType.CAMERA)
-        graph.node("c", NodeType.DISPLAY)
-        graph.connect("a", "b")
-        graph.connect("b", "c")
-        graph.connect("c", "a")  # Creates cycle
-
-        errors = graph.validate()
-        assert len(errors) > 0
-        assert any("cycle" in e.lower() for e in errors)
-
-    def test_validate_clean_graph(self):
-        """Validation returns no errors for valid graph."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE)
-        graph.node("display", NodeType.DISPLAY)
-        graph.connect("source", "display")
-
-        errors = graph.validate()
-        assert len(errors) == 0
-
-
-class TestGraphToDict:
-    """Tests for Graph serialization."""
-
-    def test_to_dict_basic(self):
-        """Graph.to_dict produces correct structure."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE, source="headlines")
-        graph.node("display", NodeType.DISPLAY, backend="terminal")
-        graph.connect("source", "display")
-
-        data = graph.to_dict()
-
-        assert "nodes" in data
-        assert "connections" in data
-        assert "source" in data["nodes"]
-        assert "display" in data["nodes"]
-        assert data["nodes"]["source"]["type"] == "source"
-        assert data["nodes"]["display"]["type"] == "display"
-
-    def test_from_dict_simple(self):
-        """Graph.from_dict loads simple format."""
-        data = {
-            "nodes": {
-                "source": "headlines",
-                "display": {"type": "display", "backend": "terminal"},
-            },
-            "connections": ["source -> display"],
-        }
-
-        graph = Graph().from_dict(data)
-
-        assert "source" in graph.nodes
-        assert "display" in graph.nodes
-        assert len(graph.connections) == 1
-
-
-class TestDictToPipeline:
-    """Tests for dict_to_pipeline conversion."""
-
-    def test_convert_minimal_pipeline(self):
-        """dict_to_pipeline creates a working pipeline."""
-        data = {
-            "nodes": {
-                "source": "headlines",
-                "display": {"type": "display", "backend": "null"},
-            },
-            "connections": ["source -> display"],
-        }
-
-        pipeline = dict_to_pipeline(data, viewport_width=80, viewport_height=24)
-
-        assert pipeline is not None
-        assert "source" in pipeline._stages
-        assert "display" in pipeline._stages
-
-    def test_convert_with_effect(self):
-        """dict_to_pipeline handles effect nodes."""
-        data = {
-            "nodes": {
-                "source": "headlines",
-                "noise": {"type": "effect", "effect": "noise", "intensity": 0.5},
-                "display": {"type": "display", "backend": "null"},
-            },
-            "connections": ["source -> noise -> display"],
-        }
-
-        pipeline = dict_to_pipeline(data)
-
-        assert "noise" in pipeline._stages
-        # Check that intensity was set (this is a global state check)
-        from engine.effects import get_registry
-
-        noise_effect = get_registry().get("noise")
-        assert noise_effect.config.intensity == 0.5
-
-    def test_convert_with_positioning(self):
-        """dict_to_pipeline handles positioning nodes."""
-        data = {
-            "nodes": {
-                "source": "headlines",
-                "position": {"type": "position", "mode": "absolute"},
-                "display": {"type": "display", "backend": "null"},
-            },
-            "connections": ["source -> position -> display"],
-        }
-
-        pipeline = dict_to_pipeline(data)
-
-        assert "position" in pipeline._stages
-        pos_stage = pipeline._stages["position"]
-        assert pos_stage.mode.value == "absolute"
-
-
-class TestGraphToPipeline:
-    """Tests for graph_to_pipeline conversion."""
-
-    def test_convert_simple_graph(self):
-        """graph_to_pipeline converts a simple graph."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE, source="headlines")
-        graph.node("display", NodeType.DISPLAY, backend="null")
-        graph.connect("source", "display")
-
-        pipeline = graph_to_pipeline(graph)
-
-        assert pipeline is not None
-        # Pipeline auto-injects missing capabilities (camera, render, etc.)
-        # So we have more stages than just source and display
-        assert "source" in pipeline._stages
-        assert "display" in pipeline._stages
-        # Auto-injected stages include camera, camera_update, render
-        assert "camera" in pipeline._stages
-        assert "camera_update" in pipeline._stages
-        assert "render" in pipeline._stages
-
-    def test_convert_with_camera(self):
-        """graph_to_pipeline handles camera nodes."""
-        graph = Graph()
-        graph.node("source", NodeType.SOURCE, source="headlines")
-        graph.node("camera", NodeType.CAMERA, mode="scroll")
-        graph.node("display", NodeType.DISPLAY, backend="null")
-        graph.chain("source", "camera", "display")
-
-        pipeline = graph_to_pipeline(graph)
-
-        assert "camera" in pipeline._stages
-        camera_stage = pipeline._stages["camera"]
-        assert hasattr(camera_stage, "_camera")
-
-
-if __name__ == "__main__":
-    pytest.main([__file__])

tests/test_hybrid_config.py

@@ -1,262 +0,0 @@
-"""Tests for the hybrid preset-graph configuration system."""
-
-import pytest
-from pathlib import Path
-
-from engine.effects.plugins import discover_plugins
-from engine.pipeline.hybrid_config import (
-    PipelineConfig,
-    CameraConfig,
-    EffectConfig,
-    DisplayConfig,
-    load_hybrid_config,
-    parse_hybrid_config,
-)
-
-
-class TestHybridConfigCreation:
-    """Tests for creating hybrid config objects."""
-
-    def test_create_minimal_config(self):
-        """Can create minimal hybrid config."""
-        config = PipelineConfig()
-        assert config.source == "headlines"
-        assert config.camera is None
-        assert len(config.effects) == 0
-        assert config.display is None
-
-    def test_create_full_config(self):
-        """Can create full hybrid config with all options."""
-        config = PipelineConfig(
-            source="poetry",
-            camera=CameraConfig(mode="scroll", speed=1.5),
-            effects=[
-                EffectConfig(name="noise", intensity=0.3),
-                EffectConfig(name="fade", intensity=0.5),
-            ],
-            display=DisplayConfig(backend="terminal", positioning="mixed"),
-        )
-        assert config.source == "poetry"
-        assert config.camera.mode == "scroll"
-        assert len(config.effects) == 2
-        assert config.display.backend == "terminal"
-
-
-class TestHybridConfigParsing:
-    """Tests for parsing hybrid config from TOML/dict."""
-
-    def test_parse_minimal_dict(self):
-        """Can parse minimal config from dict."""
-        data = {
-            "pipeline": {
-                "source": "headlines",
-            }
-        }
-        config = parse_hybrid_config(data)
-        assert config.source == "headlines"
-        assert config.camera is None
-        assert len(config.effects) == 0
-
-    def test_parse_full_dict(self):
-        """Can parse full config from dict."""
-        data = {
-            "pipeline": {
-                "source": "poetry",
-                "camera": {"mode": "scroll", "speed": 1.5},
-                "effects": [
-                    {"name": "noise", "intensity": 0.3},
-                    {"name": "fade", "intensity": 0.5},
-                ],
-                "display": {"backend": "terminal", "positioning": "mixed"},
-                "viewport_width": 100,
-                "viewport_height": 30,
-            }
-        }
-        config = parse_hybrid_config(data)
-        assert config.source == "poetry"
-        assert config.camera.mode == "scroll"
-        assert config.camera.speed == 1.5
-        assert len(config.effects) == 2
-        assert config.effects[0].name == "noise"
-        assert config.effects[0].intensity == 0.3
-        assert config.effects[1].name == "fade"
-        assert config.effects[1].intensity == 0.5
-        assert config.display.backend == "terminal"
-        assert config.viewport_width == 100
-        assert config.viewport_height == 30
-
-    def test_parse_effect_as_string(self):
-        """Can parse effect specified as string."""
-        data = {
-            "pipeline": {
-                "source": "headlines",
-                "effects": ["noise", "fade"],
-            }
-        }
-        config = parse_hybrid_config(data)
-        assert len(config.effects) == 2
-        assert config.effects[0].name == "noise"
-        assert config.effects[0].intensity == 1.0
-        assert config.effects[1].name == "fade"
-
-    def test_parse_camera_as_string(self):
-        """Can parse camera specified as string."""
-        data = {
-            "pipeline": {
-                "source": "headlines",
-                "camera": "scroll",
-            }
-        }
-        config = parse_hybrid_config(data)
-        assert config.camera.mode == "scroll"
-        assert config.camera.speed == 1.0
-
-    def test_parse_display_as_string(self):
-        """Can parse display specified as string."""
-        data = {
-            "pipeline": {
-                "source": "headlines",
-                "display": "terminal",
-            }
-        }
-        config = parse_hybrid_config(data)
-        assert config.display.backend == "terminal"
-
-
-class TestHybridConfigToGraph:
-    """Tests for converting hybrid config to Graph."""
-
-    def test_minimal_config_to_graph(self):
-        """Can convert minimal config to graph."""
-        config = PipelineConfig(source="headlines")
-        graph = config.to_graph()
-        assert "source" in graph.nodes
-        assert "display" in graph.nodes
-        assert len(graph.connections) == 1  # source -> display
-
-    def test_full_config_to_graph(self):
-        """Can convert full config to graph."""
-        config = PipelineConfig(
-            source="headlines",
-            camera=CameraConfig(mode="scroll"),
-            effects=[EffectConfig(name="noise", intensity=0.3)],
-            display=DisplayConfig(backend="terminal"),
-        )
-        graph = config.to_graph()
-        assert "source" in graph.nodes
-        assert "camera" in graph.nodes
-        assert "noise" in graph.nodes
-        assert "display" in graph.nodes
-        assert len(graph.connections) == 3  # source -> camera -> noise -> display
-
-    def test_graph_node_config(self):
-        """Graph nodes have correct configuration."""
-        config = PipelineConfig(
-            source="headlines",
-            effects=[EffectConfig(name="noise", intensity=0.7)],
-        )
-        graph = config.to_graph()
-        noise_node = graph.nodes["noise"]
-        assert noise_node.config["effect"] == "noise"
-        assert noise_node.config["intensity"] == 0.7
-
-
-class TestHybridConfigToPipeline:
-    """Tests for converting hybrid config to Pipeline."""
-
-    @pytest.fixture(autouse=True)
-    def setup(self):
-        """Setup before each test."""
-        discover_plugins()
-
-    def test_minimal_config_to_pipeline(self):
-        """Can convert minimal config to pipeline."""
-        config = PipelineConfig(source="headlines")
-        pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-        assert pipeline is not None
-        assert "source" in pipeline._stages
-        assert "display" in pipeline._stages
-
-    def test_full_config_to_pipeline(self):
-        """Can convert full config to pipeline."""
-        config = PipelineConfig(
-            source="headlines",
-            camera=CameraConfig(mode="scroll"),
-            effects=[
-                EffectConfig(name="noise", intensity=0.3),
-                EffectConfig(name="fade", intensity=0.5),
-            ],
-            display=DisplayConfig(backend="null"),
-        )
-        pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-        assert pipeline is not None
-        assert "source" in pipeline._stages
-        assert "camera" in pipeline._stages
-        assert "noise" in pipeline._stages
-        assert "fade" in pipeline._stages
-        assert "display" in pipeline._stages
-
-    def test_pipeline_execution(self):
-        """Pipeline can execute and produce output."""
-        config = PipelineConfig(
-            source="headlines",
-            display=DisplayConfig(backend="null"),
-        )
-        pipeline = config.to_pipeline(viewport_width=80, viewport_height=24)
-        pipeline.initialize()
-        result = pipeline.execute([])
-        assert result.success
-        assert len(result.data) > 0
-
-
-class TestHybridConfigLoading:
-    """Tests for loading hybrid config from TOML file."""
-
-    @pytest.fixture(autouse=True)
-    def setup(self):
-        """Setup before each test."""
-        discover_plugins()
-
-    def test_load_hybrid_config_file(self):
-        """Can load hybrid config from TOML file."""
-        toml_path = Path("examples/hybrid_config.toml")
-        if toml_path.exists():
-            config = load_hybrid_config(toml_path)
-            assert config.source == "headlines"
-            assert config.camera is not None
-            assert len(config.effects) == 4
-            assert config.display is not None
-
-
-class TestVerbosityComparison:
-    """Compare verbosity of different configuration formats."""
-
-    def test_hybrid_vs_verbose_dsl(self):
-        """Hybrid config is significantly more compact."""
-        # Hybrid config uses 4 lines for effects vs 16 lines in verbose DSL
-        # Plus no connection string needed
-        # Total: ~20 lines vs ~39 lines (50% reduction)
-
-        hybrid_lines = 20  # approximate from hybrid_config.toml
-        verbose_lines = 39  # approximate from default_visualization.toml
-
-        assert hybrid_lines < verbose_lines
-        assert hybrid_lines <= verbose_lines * 0.6  # At least 40% smaller
-
-
-class TestFromPreset:
-    """Test converting from preset to PipelineConfig."""
-
-    def test_from_preset_upstream_default(self):
-        """Can create PipelineConfig from upstream-default preset."""
-        config = PipelineConfig.from_preset("upstream-default")
-        assert config.source == "headlines"
-        assert config.camera.mode == "scroll"
-        assert len(config.effects) == 4  # noise, fade, glitch, firehose
-        assert config.display.backend == "terminal"
-        assert config.display.positioning == "mixed"
-
-    def test_from_preset_not_found(self):
-        """Raises error for non-existent preset."""
-        with pytest.raises(ValueError, match="Preset 'nonexistent' not found"):
-            PipelineConfig.from_preset("nonexistent")