feat(display): add configurable multi-backend display system

feat(websocket): add WebSocket display backend for browser client
merge: effects_plugins
2026-03-15 21:17:16 -07:00 · 2026-03-15 20:54:03 -07:00 · 2026-03-15 19:20:53 -07:00 · 2026-03-15 19:20:47 -07:00 · 2026-03-15 19:20:47 -07:00 · 2026-03-15 19:20:47 -07:00
34 changed files with 3453 additions and 22 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ htmlcov/
 .coverage
 .pytest_cache/
 *.egg-info/
 coverage.xml
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,13 +22,23 @@ uv sync
 ### Available Commands
 ```bash
-mise run test       # Run tests
+mise run test           # Run tests
-mise run test-v     # Run tests verbose
+mise run test-v         # Run tests verbose
-mise run test-cov   # Run tests with coverage report
+mise run test-cov       # Run tests with coverage report
-mise run lint       # Run ruff linter
+mise run test-browser   # Run e2e browser tests (requires playwright)
-mise run lint-fix   # Run ruff with auto-fix
+mise run lint           # Run ruff linter
-mise run format     # Run ruff formatter
+mise run lint-fix       # Run ruff with auto-fix
-mise run ci         # Full CI pipeline (sync + test + coverage)
+mise run format         # Run ruff formatter
 mise run ci             # Full CI pipeline (sync + test + coverage)
 ```
 ### Runtime Commands
 ```bash
 mise run run            # Run mainline (terminal)
 mise run run-websocket  # Run with WebSocket display
 mise run run-both       # Run with both terminal and WebSocket
 mise run run-client     # Run both + open browser
 ```
 ## Git Hooks
@@ -108,3 +118,11 @@ The project uses pytest with strict marker enforcement. Test configuration is in
 - **eventbus.py** provides thread-safe event publishing for decoupled communication
 - **controller.py** coordinates ntfy/mic monitoring
 - The render pipeline: fetch → render → effects → scroll → terminal output
 - **Display abstraction** (`engine/display.py`): swap display backends via the Display protocol
  - `TerminalDisplay` - ANSI terminal output
  - `WebSocketDisplay` - broadcasts to web clients via WebSocket
  - `MultiDisplay` - forwards to multiple displays simultaneously
 - **WebSocket display** (`engine/websocket_display.py`): real-time frame broadcasting to web browsers
  - WebSocket server on port 8765
  - HTTP server on port 8766 (serves HTML client)
  - Client at `client/index.html` with ANSI color parsing and fullscreen support
--- a/client/index.html
+++ b/client/index.html
@@ -0,0 +1,366 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Mainline Terminal</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }
        body {
            background: #0a0a0a;
            color: #ccc;
            font-family: 'Fira Code', 'Cascadia Code', 'Consolas', monospace;
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            min-height: 100vh;
            padding: 20px;
        }
        body.fullscreen {
            padding: 0;
        }
        body.fullscreen #controls {
            display: none;
        }
        #container {
            position: relative;
        }
        canvas {
            background: #000;
            border: 1px solid #333;
            image-rendering: pixelated;
            image-rendering: crisp-edges;
        }
        body.fullscreen canvas {
            border: none;
            width: 100vw;
            height: 100vh;
            max-width: 100vw;
            max-height: 100vh;
        }
        #controls {
            display: flex;
            gap: 10px;
            margin-top: 10px;
            align-items: center;
        }
        #controls button {
            background: #333;
            color: #ccc;
            border: 1px solid #555;
            padding: 5px 12px;
            cursor: pointer;
            font-family: inherit;
            font-size: 12px;
        }
        #controls button:hover {
            background: #444;
        }
        #controls input {
            width: 60px;
            background: #222;
            color: #ccc;
            border: 1px solid #444;
            padding: 4px 8px;
            font-family: inherit;
            text-align: center;
        }
        #status {
            margin-top: 10px;
            font-size: 12px;
            color: #666;
        }
        #status.connected {
            color: #4f4;
        }
        #status.disconnected {
            color: #f44;
        }
    </style>
 </head>
 <body>
    <div id="container">
        <canvas id="terminal"></canvas>
    </div>
    <div id="controls">
        <label>Cols: <input type="number" id="cols" value="80" min="20" max="200"></label>
        <label>Rows: <input type="number" id="rows" value="24" min="10" max="60"></label>
        <button id="apply">Apply</button>
        <button id="fullscreen">Fullscreen</button>
    </div>
    <div id="status" class="disconnected">Connecting...</div>
    <script>
        const canvas = document.getElementById('terminal');
        const ctx = canvas.getContext('2d');
        const status = document.getElementById('status');
        const colsInput = document.getElementById('cols');
        const rowsInput = document.getElementById('rows');
        const applyBtn = document.getElementById('apply');
        const fullscreenBtn = document.getElementById('fullscreen');
        const CHAR_WIDTH = 9;
        const CHAR_HEIGHT = 16;
        const ANSI_COLORS = {
            0: '#000000', 1: '#cd3131', 2: '#0dbc79', 3: '#e5e510',
            4: '#2472c8', 5: '#bc3fbc', 6: '#11a8cd', 7: '#e5e5e5',
            8: '#666666', 9: '#f14c4c', 10: '#23d18b', 11: '#f5f543',
            12: '#3b8eea', 13: '#d670d6', 14: '#29b8db', 15: '#ffffff',
        };
        let cols = 80;
        let rows = 24;
        let ws = null;
        function resizeCanvas() {
            canvas.width = cols * CHAR_WIDTH;
            canvas.height = rows * CHAR_HEIGHT;
        }
        function parseAnsi(text) {
            if (!text) return [];
            const tokens = [];
            let currentText = '';
            let fg = '#cccccc';
            let bg = '#000000';
            let bold = false;
            let i = 0;
            let inEscape = false;
            let escapeCode = '';
            while (i < text.length) {
                const char = text[i];
                if (inEscape) {
                    if (char >= '0' && char <= '9' || char === ';' || char === '[') {
                        escapeCode += char;
                    }
                    if (char === 'm') {
                        const codes = escapeCode.replace('\x1b[', '').split(';');
                        for (const code of codes) {
                            const num = parseInt(code) || 0;
                            if (num === 0) {
                                fg = '#cccccc';
                                bg = '#000000';
                                bold = false;
                            } else if (num === 1) {
                                bold = true;
                            } else if (num === 22) {
                                bold = false;
                            } else if (num === 39) {
                                fg = '#cccccc';
                            } else if (num === 49) {
                                bg = '#000000';
                            } else if (num >= 30 && num <= 37) {
                                fg = ANSI_COLORS[num - 30 + (bold ? 8 : 0)] || '#cccccc';
                            } else if (num >= 40 && num <= 47) {
                                bg = ANSI_COLORS[num - 40] || '#000000';
                            } else if (num >= 90 && num <= 97) {
                                fg = ANSI_COLORS[num - 90 + 8] || '#cccccc';
                            } else if (num >= 100 && num <= 107) {
                                bg = ANSI_COLORS[num - 100 + 8] || '#000000';
                            } else if (num >= 1 && num <= 256) {
                                // 256 colors
                                if (num < 16) {
                                    fg = ANSI_COLORS[num] || '#cccccc';
                                } else if (num < 232) {
                                    const c = num - 16;
                                    const r = Math.floor(c / 36) * 51;
                                    const g = Math.floor((c % 36) / 6) * 51;
                                    const b = (c % 6) * 51;
                                    fg = `#${r.toString(16).padStart(2,'0')}${g.toString(16).padStart(2,'0')}${b.toString(16).padStart(2,'0')}`;
                                } else {
                                    const gray = (num - 232) * 10 + 8;
                                    fg = `#${gray.toString(16).repeat(2)}`;
                                }
                            }
                        }
                        if (currentText) {
                            tokens.push({ text: currentText, fg, bg, bold });
                            currentText = '';
                        }
                        inEscape = false;
                        escapeCode = '';
                    }
                } else if (char === '\x1b' && text[i + 1] === '[') {
                    if (currentText) {
                        tokens.push({ text: currentText, fg, bg, bold });
                        currentText = '';
                    }
                    inEscape = true;
                    escapeCode = '';
                    i++;
                } else {
                    currentText += char;
                }
                i++;
            }
            if (currentText) {
                tokens.push({ text: currentText, fg, bg, bold });
            }
            return tokens;
        }
        function renderLine(text, x, y, lineHeight) {
            const tokens = parseAnsi(text);
            let xOffset = x;
            for (const token of tokens) {
                if (token.text) {
                    if (token.bold) {
                        ctx.font = 'bold 16px monospace';
                    } else {
                        ctx.font = '16px monospace';
                    }
                    const metrics = ctx.measureText(token.text);
                    if (token.bg !== '#000000') {
                        ctx.fillStyle = token.bg;
                        ctx.fillRect(xOffset, y - 2, metrics.width + 1, lineHeight);
                    }
                    ctx.fillStyle = token.fg;
                    ctx.fillText(token.text, xOffset, y);
                    xOffset += metrics.width;
                }
            }
        }
        function connect() {
            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
            const wsUrl = `${protocol}//${window.location.hostname}:8765`;
            ws = new WebSocket(wsUrl);
            ws.onopen = () => {
                status.textContent = 'Connected';
                status.className = 'connected';
                sendSize();
            };
            ws.onclose = () => {
                status.textContent = 'Disconnected - Reconnecting...';
                status.className = 'disconnected';
                setTimeout(connect, 1000);
            };
            ws.onerror = () => {
                status.textContent = 'Connection error';
                status.className = 'disconnected';
            };
            ws.onmessage = (event) => {
                try {
                    const data = JSON.parse(event.data);
                    if (data.type === 'frame') {
                        cols = data.width || 80;
                        rows = data.height || 24;
                        colsInput.value = cols;
                        rowsInput.value = rows;
                        resizeCanvas();
                        render(data.lines || []);
                    } else if (data.type === 'clear') {
                        ctx.fillStyle = '#000';
                        ctx.fillRect(0, 0, canvas.width, canvas.height);
                    }
                } catch (e) {
                    console.error('Failed to parse message:', e);
                }
            };
        }
        function sendSize() {
            if (ws && ws.readyState === WebSocket.OPEN) {
                ws.send(JSON.stringify({
                    type: 'resize',
                    width: parseInt(colsInput.value),
                    height: parseInt(rowsInput.value)
                }));
            }
        }
        function render(lines) {
            ctx.fillStyle = '#000';
            ctx.fillRect(0, 0, canvas.width, canvas.height);
            ctx.font = '16px monospace';
            ctx.textBaseline = 'top';
            const lineHeight = CHAR_HEIGHT;
            const maxLines = Math.min(lines.length, rows);
            for (let i = 0; i < maxLines; i++) {
                const line = lines[i] || '';
                renderLine(line, 0, i * lineHeight, lineHeight);
            }
        }
        function calculateViewportSize() {
            const isFullscreen = document.fullscreenElement !== null;
            const padding = isFullscreen ? 0 : 40;
            const controlsHeight = isFullscreen ? 0 : 60;
            const availableWidth = window.innerWidth - padding;
            const availableHeight = window.innerHeight - controlsHeight;
            cols = Math.max(20, Math.floor(availableWidth / CHAR_WIDTH));
            rows = Math.max(10, Math.floor(availableHeight / CHAR_HEIGHT));
            colsInput.value = cols;
            rowsInput.value = rows;
            resizeCanvas();
            console.log('Fullscreen:', isFullscreen, 'Size:', cols, 'x', rows);
            sendSize();
        }
        applyBtn.addEventListener('click', () => {
            cols = parseInt(colsInput.value);
            rows = parseInt(rowsInput.value);
            resizeCanvas();
            sendSize();
        });
        fullscreenBtn.addEventListener('click', () => {
            if (!document.fullscreenElement) {
                document.body.classList.add('fullscreen');
                document.documentElement.requestFullscreen().then(() => {
                    calculateViewportSize();
                });
            } else {
                document.exitFullscreen().then(() => {
                    calculateViewportSize();
                });
            }
        });
        document.addEventListener('fullscreenchange', () => {
            if (!document.fullscreenElement) {
                document.body.classList.remove('fullscreen');
                calculateViewportSize();
            }
        });
        window.addEventListener('resize', () => {
            if (document.fullscreenElement) {
                calculateViewportSize();
            }
        });
        // Initial setup
        resizeCanvas();
        connect();
    </script>
 </body>
 </html>
--- a/cmdline.py
+++ b/cmdline.py
@@ -0,0 +1,250 @@
 #!/usr/bin/env python3
 """
 Command-line utility for interacting with mainline via ntfy.
 Usage:
    python cmdline.py                     # Interactive TUI mode
    python cmdline.py --help              # Show help
    python cmdline.py /effects list       # Send single command via ntfy
    python cmdline.py /effects stats      # Get performance stats via ntfy
    python cmdline.py -w /effects stats   # Watch mode (polls for stats)
 The TUI mode provides:
    - Arrow keys to navigate command history
    - Tab completion for commands
    - Auto-refresh for performance stats
 C&C works like a serial port:
    1. Send command to ntfy_cc_topic
    2. Mainline receives, processes, responds to same topic
    3. Cmdline polls for response
 """
 import argparse
 import json
 import sys
 import time
 import threading
 import urllib.request
 from pathlib import Path
 from engine import config
 from engine.terminal import CLR, CURSOR_OFF, CURSOR_ON, G_DIM, G_HI, RST, W_GHOST
 try:
    CC_CMD_TOPIC = config.NTFY_CC_CMD_TOPIC
    CC_RESP_TOPIC = config.NTFY_CC_RESP_TOPIC
 except AttributeError:
    CC_CMD_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline_cc_cmd/json"
    CC_RESP_TOPIC = "https://ntfy.sh/klubhaus_terminal_mainline_cc_resp/json"
 class NtfyResponsePoller:
    """Polls ntfy for command responses."""
    def __init__(self, cmd_topic: str, resp_topic: str, timeout: float = 10.0):
        self.cmd_topic = cmd_topic
        self.resp_topic = resp_topic
        self.timeout = timeout
        self._last_id = None
        self._lock = threading.Lock()
    def _build_url(self) -> str:
        from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
        parsed = urlparse(self.resp_topic)
        params = parse_qs(parsed.query, keep_blank_values=True)
        params["since"] = [self._last_id if self._last_id else "20s"]
        new_query = urlencode({k: v[0] for k, v in params.items()})
        return urlunparse(parsed._replace(query=new_query))
    def send_and_wait(self, cmd: str) -> str:
        """Send command and wait for response."""
        url = self.cmd_topic.replace("/json", "")
        data = cmd.encode("utf-8")
        req = urllib.request.Request(
            url,
            data=data,
            headers={
                "User-Agent": "mainline-cmdline/0.1",
                "Content-Type": "text/plain",
            },
            method="POST",
        )
        try:
            urllib.request.urlopen(req, timeout=5)
        except Exception as e:
            return f"Error sending command: {e}"
        return self._wait_for_response(cmd)
    def _wait_for_response(self, expected_cmd: str = "") -> str:
        """Poll for response message."""
        start = time.time()
        while time.time() - start < self.timeout:
            try:
                url = self._build_url()
                req = urllib.request.Request(
                    url, headers={"User-Agent": "mainline-cmdline/0.1"}
                )
                with urllib.request.urlopen(req, timeout=10) as resp:
                    for line in resp:
                        try:
                            data = json.loads(line.decode("utf-8", errors="replace"))
                        except json.JSONDecodeError:
                            continue
                        if data.get("event") == "message":
                            self._last_id = data.get("id")
                            msg = data.get("message", "")
                            if msg:
                                return msg
            except Exception:
                pass
            time.sleep(0.5)
        return "Timeout waiting for response"
 AVAILABLE_COMMANDS = """Available commands:
  /effects list          - List all effects and status
  /effects <name> on    - Enable an effect
  /effects <name> off   - Disable an effect
  /effects <name> intensity <0.0-1.0> - Set effect intensity
  /effects reorder <name1>,<name2>,... - Reorder pipeline
  /effects stats        - Show performance statistics
  /help                 - Show this help
  /quit                 - Exit
 """
 def print_header():
    w = 60
    print(CLR, end="")
    print(CURSOR_OFF, end="")
    print(f"\033[1;1H", end="")
    print(f"  \033[1;38;5;231m╔{'═' * (w - 6)}╗\033[0m")
    print(
        f"  \033[1;38;5;231m║\033[0m \033[1;38;5;82mMAINLINE\033[0m \033[3;38;5;245mCommand Center\033[0m \033[1;38;5;231m  ║\033[0m"
    )
    print(f"  \033[1;38;5;231m╚{'═' * (w - 6)}╝\033[0m")
    print(f"  \033[2;38;5;37mCMD: {CC_CMD_TOPIC.split('/')[-2]}\033[0m")
    print(f"  \033[2;38;5;37mRESP: {CC_RESP_TOPIC.split('/')[-2]}\033[0m")
    print()
 def print_response(response: str, is_error: bool = False) -> None:
    """Print response with nice formatting."""
    print()
    if is_error:
        print(f"  \033[1;38;5;196m✗ Error\033[0m")
        print(f"  \033[38;5;196m{'─' * 40}\033[0m")
    else:
        print(f"  \033[1;38;5;82m✓ Response\033[0m")
        print(f"  \033[38;5;37m{'─' * 40}\033[0m")
    for line in response.split("\n"):
        print(f"  {line}")
    print()
 def interactive_mode():
    """Interactive TUI for sending commands."""
    import readline
    print_header()
    poller = NtfyResponsePoller(CC_CMD_TOPIC, CC_RESP_TOPIC)
    print(f"  \033[38;5;245mType /help for commands, /quit to exit\033[0m")
    print()
    while True:
        try:
            cmd = input(f"  \033[1;38;5;82m❯\033[0m {G_HI}").strip()
        except (EOFError, KeyboardInterrupt):
            print()
            break
        if not cmd:
            continue
        if cmd.startswith("/"):
            if cmd == "/quit" or cmd == "/exit":
                print(f"\n  \033[1;38;5;245mGoodbye!{RST}\n")
                break
            if cmd == "/help":
                print(f"\n{AVAILABLE_COMMANDS}\n")
                continue
            print(f"  \033[38;5;245m⟳ Sending to mainline...{RST}")
            result = poller.send_and_wait(cmd)
            print_response(result, is_error=result.startswith("Error"))
        else:
            print(f"\n  \033[1;38;5;196m⚠ Commands must start with /{RST}\n")
    print(CURSOR_ON, end="")
    return 0
 def main():
    parser = argparse.ArgumentParser(
        description="Mainline command-line interface",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=AVAILABLE_COMMANDS,
    )
    parser.add_argument(
        "command",
        nargs="?",
        default=None,
        help="Command to send (e.g., /effects list)",
    )
    parser.add_argument(
        "--watch",
        "-w",
        action="store_true",
        help="Watch mode: continuously poll for stats (Ctrl+C to exit)",
    )
    args = parser.parse_args()
    if args.command is None:
        return interactive_mode()
    poller = NtfyResponsePoller(CC_CMD_TOPIC, CC_RESP_TOPIC)
    if args.watch and "/effects stats" in args.command:
        import signal
        def handle_sigterm(*_):
            print(f"\n  \033[1;38;5;245mStopped watching{RST}")
            print(CURSOR_ON, end="")
            sys.exit(0)
        signal.signal(signal.SIGTERM, handle_sigterm)
        print_header()
        print(f"  \033[38;5;245mWatching /effects stats (Ctrl+C to exit)...{RST}\n")
        try:
            while True:
                result = poller.send_and_wait(args.command)
                print(f"\033[2J\033[1;1H", end="")
                print(
                    f"  \033[1;38;5;82m❯\033[0m Performance Stats - \033[1;38;5;245m{time.strftime('%H:%M:%S')}{RST}"
                )
                print(f"  \033[38;5;37m{'─' * 44}{RST}")
                for line in result.split("\n"):
                    print(f"  {line}")
                time.sleep(2)
        except KeyboardInterrupt:
            print(f"\n  \033[1;38;5;245mStopped watching{RST}")
            return 0
        return 0
    result = poller.send_and_wait(args.command)
    print(result)
    return 0
 if __name__ == "__main__":
    main()
--- a/effects_plugins/init.py
+++ b/effects_plugins/init.py
@@ -0,0 +1,35 @@
 from pathlib import Path
 PLUGIN_DIR = Path(__file__).parent
 def discover_plugins():
    from engine.effects.registry import get_registry
    registry = get_registry()
    imported = {}
    for file_path in PLUGIN_DIR.glob("*.py"):
        if file_path.name.startswith("_"):
            continue
        module_name = file_path.stem
        if module_name in ("base", "types"):
            continue
        try:
            module = __import__(f"effects_plugins.{module_name}", fromlist=[""])
            for attr_name in dir(module):
                attr = getattr(module, attr_name)
                if (
                    isinstance(attr, type)
                    and hasattr(attr, "name")
                    and hasattr(attr, "process")
                    and attr_name.endswith("Effect")
                ):
                    plugin = attr()
                    registry.register(plugin)
                    imported[plugin.name] = plugin
        except Exception:
            pass
    return imported
--- a/effects_plugins/fade.py
+++ b/effects_plugins/fade.py
@@ -0,0 +1,58 @@
 import random
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 class FadeEffect:
    name = "fade"
    config = EffectConfig(enabled=True, intensity=1.0)
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        if not ctx.ticker_height:
            return buf
        result = list(buf)
        intensity = self.config.intensity
        top_zone = max(1, int(ctx.ticker_height * 0.25))
        bot_zone = max(1, int(ctx.ticker_height * 0.10))
        for r in range(len(result)):
            if r >= ctx.ticker_height:
                continue
            top_f = min(1.0, r / top_zone) if top_zone > 0 else 1.0
            bot_f = (
                min(1.0, (ctx.ticker_height - 1 - r) / bot_zone)
                if bot_zone > 0
                else 1.0
            )
            row_fade = min(top_f, bot_f) * intensity
            if row_fade < 1.0 and result[r].strip():
                result[r] = self._fade_line(result[r], row_fade)
        return result
    def _fade_line(self, s: str, fade: float) -> str:
        if fade >= 1.0:
            return s
        if fade <= 0.0:
            return ""
        result = []
        i = 0
        while i < len(s):
            if s[i] == "\033" and i + 1 < len(s) and s[i + 1] == "[":
                j = i + 2
                while j < len(s) and not s[j].isalpha():
                    j += 1
                result.append(s[i : j + 1])
                i = j + 1
            elif s[i] == " ":
                result.append(" ")
                i += 1
            else:
                result.append(s[i] if random.random() < fade else " ")
                i += 1
        return "".join(result)
    def configure(self, cfg: EffectConfig) -> None:
        self.config = cfg
--- a/effects_plugins/firehose.py
+++ b/effects_plugins/firehose.py
@@ -0,0 +1,72 @@
 import random
 from datetime import datetime
 from engine import config
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.sources import FEEDS, POETRY_SOURCES
 from engine.terminal import C_DIM, G_DIM, G_LO, RST, W_GHOST
 class FirehoseEffect:
    name = "firehose"
    config = EffectConfig(enabled=True, intensity=1.0)
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        firehose_h = config.FIREHOSE_H if config.FIREHOSE else 0
        if firehose_h <= 0 or not ctx.items:
            return buf
        result = list(buf)
        intensity = self.config.intensity
        h = ctx.terminal_height
        for fr in range(firehose_h):
            scr_row = h - firehose_h + fr + 1
            fline = self._firehose_line(ctx.items, ctx.terminal_width, intensity)
            result.append(f"\033[{scr_row};1H{fline}\033[K")
        return result
    def _firehose_line(self, items: list, w: int, intensity: float) -> str:
        r = random.random()
        if r < 0.35 * intensity:
            title, src, ts = random.choice(items)
            text = title[: w - 1]
            color = random.choice([G_LO, G_DIM, W_GHOST, C_DIM])
            return f"{color}{text}{RST}"
        elif r < 0.55 * intensity:
            d = random.choice([0.45, 0.55, 0.65, 0.75])
            return "".join(
                f"{random.choice([G_LO, G_DIM, C_DIM, W_GHOST])}"
                f"{random.choice(config.GLITCH + config.KATA)}{RST}"
                if random.random() < d
                else " "
                for _ in range(w)
            )
        elif r < 0.78 * intensity:
            sources = FEEDS if config.MODE == "news" else POETRY_SOURCES
            src = random.choice(list(sources.keys()))
            msgs = [
                f"  SIGNAL :: {src} :: {datetime.now().strftime('%H:%M:%S.%f')[:-3]}",
                f"  ░░ FEED ACTIVE :: {src}",
                f"  >> DECODE 0x{random.randint(0x1000, 0xFFFF):04X} :: {src[:24]}",
                f"  ▒▒ ACQUIRE :: {random.choice(['TCP', 'UDP', 'RSS', 'ATOM', 'XML'])} :: {src}",
                f"  {''.join(random.choice(config.KATA) for _ in range(3))} STRM "
                f"{random.randint(0, 255):02X}:{random.randint(0, 255):02X}",
            ]
            text = random.choice(msgs)[: w - 1]
            color = random.choice([G_LO, G_DIM, W_GHOST])
            return f"{color}{text}{RST}"
        else:
            title, _, _ = random.choice(items)
            start = random.randint(0, max(0, len(title) - 20))
            frag = title[start : start + random.randint(10, 35)]
            pad = random.randint(0, max(0, w - len(frag) - 8))
            gp = "".join(
                random.choice(config.GLITCH) for _ in range(random.randint(1, 3))
            )
            text = (" " * pad + gp + " " + frag)[: w - 1]
            color = random.choice([G_LO, C_DIM, W_GHOST])
            return f"{color}{text}{RST}"
    def configure(self, cfg: EffectConfig) -> None:
        self.config = cfg
--- a/effects_plugins/glitch.py
+++ b/effects_plugins/glitch.py
@@ -0,0 +1,37 @@
 import random
 from engine import config
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST
 class GlitchEffect:
    name = "glitch"
    config = EffectConfig(enabled=True, intensity=1.0)
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        if not buf:
            return buf
        result = list(buf)
        intensity = self.config.intensity
        glitch_prob = 0.32 + min(0.9, ctx.mic_excess * 0.16)
        glitch_prob = glitch_prob * intensity
        n_hits = 4 + int(ctx.mic_excess / 2)
        n_hits = int(n_hits * intensity)
        if random.random() < glitch_prob:
            for _ in range(min(n_hits, len(result))):
                gi = random.randint(0, len(result) - 1)
                scr_row = gi + 1
                result[gi] = f"\033[{scr_row};1H{self._glitch_bar(ctx.terminal_width)}"
        return result
    def _glitch_bar(self, w: int) -> str:
        c = random.choice(["░", "▒", "─", "\xc2"])
        n = random.randint(3, w // 2)
        o = random.randint(0, w - n)
        return " " * o + f"{G_LO}{DIM}" + c * n + RST
    def configure(self, cfg: EffectConfig) -> None:
        self.config = cfg
--- a/effects_plugins/noise.py
+++ b/effects_plugins/noise.py
@@ -0,0 +1,36 @@
 import random
 from engine import config
 from engine.effects.types import EffectConfig, EffectContext, EffectPlugin
 from engine.terminal import C_DIM, G_DIM, G_LO, RST, W_GHOST
 class NoiseEffect:
    name = "noise"
    config = EffectConfig(enabled=True, intensity=0.15)
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        if not ctx.ticker_height:
            return buf
        result = list(buf)
        intensity = self.config.intensity
        probability = intensity * 0.15
        for r in range(len(result)):
            cy = ctx.scroll_cam + r
            if random.random() < probability:
                result[r] = self._generate_noise(ctx.terminal_width, cy)
        return result
    def _generate_noise(self, w: int, cy: int) -> str:
        d = random.choice([0.15, 0.25, 0.35, 0.12])
        return "".join(
            f"{random.choice([G_LO, G_DIM, C_DIM, W_GHOST])}"
            f"{random.choice(config.GLITCH + config.KATA)}{RST}"
            if random.random() < d
            else " "
            for _ in range(w)
        )
    def configure(self, cfg: EffectConfig) -> None:
        self.config = cfg
--- a/engine/app.py
+++ b/engine/app.py
@@ -29,6 +29,30 @@ from engine.terminal import (
    slow_print,
    tw,
 )
 from engine.websocket_display import WebSocketDisplay
 def _get_display():
    """Get the appropriate display(s) based on config."""
    from engine.display import MultiDisplay, TerminalDisplay
    displays = []
    if config.DISPLAY in ("terminal", "both"):
        displays.append(TerminalDisplay())
    if config.DISPLAY in ("websocket", "both") or config.WEBSOCKET:
        ws = WebSocketDisplay(host="0.0.0.0", port=config.WEBSOCKET_PORT)
        ws.start_server()
        ws.start_http_server()
        displays.append(ws)
    if not displays:
        return None
    if len(displays) == 1:
        return displays[0]
    return MultiDisplay(displays)
 TITLE = [
    "  ███╗   ███╗ █████╗ ██╗███╗   ██╗██╗     ██╗███╗   ██╗███████╗",
@@ -343,7 +367,10 @@ def main():
    print()
    time.sleep(0.4)
-    stream(items, ntfy, mic)
+    display = _get_display()
    stream(items, ntfy, mic, display)
    if display:
        display.cleanup()
    print()
    print(f"  {W_GHOST}{'─' * (tw() - 4)}{RST}")
--- a/engine/config.py
+++ b/engine/config.py
@@ -127,6 +127,10 @@ class Config:
    script_fonts: dict[str, str] = field(default_factory=_get_platform_font_paths)
    display: str = "terminal"
    websocket: bool = False
    websocket_port: int = 8765
    @classmethod
    def from_args(cls, argv: list[str] | None = None) -> "Config":
        """Create Config from CLI arguments (or custom argv for testing)."""
@@ -164,6 +168,9 @@ class Config:
            glitch_glyphs="░▒▓█▌▐╌╍╎╏┃┆┇┊┋",
            kata_glyphs="ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ",
            script_fonts=_get_platform_font_paths(),
            display=_arg_value("--display", argv) or "terminal",
            websocket="--websocket" in argv,
            websocket_port=_arg_int("--websocket-port", 8765, argv),
        )
@@ -223,6 +230,11 @@ GRAD_SPEED = 0.08  # gradient traversal speed (cycles/sec, ~12s full sweep)
 GLITCH = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
 KATA = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"
 # ─── WEBSOCKET ─────────────────────────────────────────────
 DISPLAY = _arg_value("--display", sys.argv) or "terminal"
 WEBSOCKET = "--websocket" in sys.argv
 WEBSOCKET_PORT = _arg_int("--websocket-port", 8765)
 def set_font_selection(font_path=None, font_index=None):
    """Set runtime primary font selection."""
--- a/engine/controller.py
+++ b/engine/controller.py
@@ -8,6 +8,17 @@ from engine.events import EventType, StreamEvent
 from engine.mic import MicMonitor
 from engine.ntfy import NtfyPoller
 from engine.scroll import stream
 from engine.websocket_display import WebSocketDisplay
 def _get_display(config: Config):
    """Get the appropriate display based on config."""
    if config.websocket:
        ws = WebSocketDisplay(host="0.0.0.0", port=config.websocket_port)
        ws.start_server()
        ws.start_http_server()
        return ws
    return None
 class StreamController:
@@ -51,7 +62,10 @@ class StreamController:
                ),
            )
-        stream(items, self.ntfy, self.mic)
+        display = _get_display(self.config)
        stream(items, self.ntfy, self.mic, display)
        if display:
            display.cleanup()
        if self.event_bus:
            self.event_bus.publish(
--- a/engine/display.py
+++ b/engine/display.py
@@ -0,0 +1,129 @@
 """
 Display output abstraction - allows swapping output backends.
 Protocol:
    - init(width, height): Initialize display with terminal dimensions
    - show(buffer): Render buffer (list of strings) to display
    - clear(): Clear the display
    - cleanup(): Shutdown display
 """
 import time
 from typing import Protocol
 class Display(Protocol):
    """Protocol for display backends."""
    def init(self, width: int, height: int) -> None:
        """Initialize display with dimensions."""
        ...
    def show(self, buffer: list[str]) -> None:
        """Show buffer on display."""
        ...
    def clear(self) -> None:
        """Clear display."""
        ...
    def cleanup(self) -> None:
        """Shutdown display."""
        ...
 def get_monitor():
    """Get the performance monitor."""
    try:
        from engine.effects.performance import get_monitor as _get_monitor
        return _get_monitor()
    except Exception:
        return None
 class TerminalDisplay:
    """ANSI terminal display backend."""
    def __init__(self):
        self.width = 80
        self.height = 24
    def init(self, width: int, height: int) -> None:
        from engine.terminal import CURSOR_OFF
        self.width = width
        self.height = height
        print(CURSOR_OFF, end="", flush=True)
    def show(self, buffer: list[str]) -> None:
        import sys
        t0 = time.perf_counter()
        sys.stdout.buffer.write("".join(buffer).encode())
        sys.stdout.flush()
        elapsed_ms = (time.perf_counter() - t0) * 1000
        monitor = get_monitor()
        if monitor:
            chars_in = sum(len(line) for line in buffer)
            monitor.record_effect("terminal_display", elapsed_ms, chars_in, chars_in)
    def clear(self) -> None:
        from engine.terminal import CLR
        print(CLR, end="", flush=True)
    def cleanup(self) -> None:
        from engine.terminal import CURSOR_ON
        print(CURSOR_ON, end="", flush=True)
 class NullDisplay:
    """Headless/null display - discards all output."""
    def init(self, width: int, height: int) -> None:
        self.width = width
        self.height = height
    def show(self, buffer: list[str]) -> None:
        monitor = get_monitor()
        if monitor:
            t0 = time.perf_counter()
            chars_in = sum(len(line) for line in buffer)
            elapsed_ms = (time.perf_counter() - t0) * 1000
            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
    def clear(self) -> None:
        pass
    def cleanup(self) -> None:
        pass
 class MultiDisplay:
    """Display that forwards to multiple displays."""
    def __init__(self, displays: list[Display]):
        self.displays = displays
        self.width = 80
        self.height = 24
    def init(self, width: int, height: int) -> None:
        self.width = width
        self.height = height
        for d in self.displays:
            d.init(width, height)
    def show(self, buffer: list[str]) -> None:
        for d in self.displays:
            d.show(buffer)
    def clear(self) -> None:
        for d in self.displays:
            d.clear()
    def cleanup(self) -> None:
        for d in self.displays:
            d.cleanup()
--- a/engine/effects/init.py
+++ b/engine/effects/init.py
@@ -0,0 +1,42 @@
 from engine.effects.chain import EffectChain
 from engine.effects.controller import handle_effects_command, show_effects_menu
 from engine.effects.legacy import (
    fade_line,
    firehose_line,
    glitch_bar,
    next_headline,
    noise,
    vis_trunc,
 )
 from engine.effects.performance import PerformanceMonitor, get_monitor, set_monitor
 from engine.effects.registry import EffectRegistry, get_registry, set_registry
 from engine.effects.types import EffectConfig, EffectContext, PipelineConfig
 def get_effect_chain():
    from engine.layers import get_effect_chain as _chain
    return _chain()
 __all__ = [
    "EffectChain",
    "EffectRegistry",
    "EffectConfig",
    "EffectContext",
    "PipelineConfig",
    "get_registry",
    "set_registry",
    "get_effect_chain",
    "get_monitor",
    "set_monitor",
    "PerformanceMonitor",
    "handle_effects_command",
    "show_effects_menu",
    "fade_line",
    "firehose_line",
    "glitch_bar",
    "noise",
    "next_headline",
    "vis_trunc",
 ]
--- a/engine/effects/chain.py
+++ b/engine/effects/chain.py
@@ -0,0 +1,71 @@
 import time
 from engine.effects.performance import PerformanceMonitor, get_monitor
 from engine.effects.registry import EffectRegistry
 from engine.effects.types import EffectContext
 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)
        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:
                    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
--- a/engine/effects/controller.py
+++ b/engine/effects/controller.py
@@ -0,0 +1,144 @@
 from engine.effects.performance import get_monitor
 from engine.effects.registry import get_registry
 _effect_chain_ref = None
 def _get_effect_chain():
    global _effect_chain_ref
    if _effect_chain_ref is not None:
        return _effect_chain_ref
    try:
        from engine.layers import get_effect_chain as _chain
        return _chain()
    except Exception:
        return None
 def set_effect_chain_ref(chain) -> None:
    global _effect_chain_ref
    _effect_chain_ref = chain
 def handle_effects_command(cmd: str) -> str:
    """Handle /effects command from NTFY message.
    Commands:
        /effects list - list all effects and their status
        /effects <name> on - enable an effect
        /effects <name> off - disable an effect
        /effects <name> intensity <0.0-1.0> - set intensity
        /effects reorder <name1>,<name2>,... - reorder pipeline
        /effects stats - show performance statistics
    """
    parts = cmd.strip().split()
    if not parts or parts[0] != "/effects":
        return "Unknown command"
    registry = get_registry()
    chain = _get_effect_chain()
    if len(parts) == 1 or parts[1] == "list":
        result = ["Effects:"]
        for name, plugin in registry.list_all().items():
            status = "ON" if plugin.config.enabled else "OFF"
            intensity = plugin.config.intensity
            result.append(f"  {name}: {status} (intensity={intensity})")
        if chain:
            result.append(f"Order: {chain.get_order()}")
        return "\n".join(result)
    if parts[1] == "stats":
        return _format_stats()
    if parts[1] == "reorder" and len(parts) >= 3:
        new_order = parts[2].split(",")
        if chain and chain.reorder(new_order):
            return f"Reordered pipeline: {new_order}"
        return "Failed to reorder pipeline"
    if len(parts) < 3:
        return "Usage: /effects <name> on|off|intensity <value>"
    effect_name = parts[1]
    action = parts[2]
    if effect_name not in registry.list_all():
        return f"Unknown effect: {effect_name}"
    if action == "on":
        registry.enable(effect_name)
        return f"Enabled: {effect_name}"
    if action == "off":
        registry.disable(effect_name)
        return f"Disabled: {effect_name}"
    if action == "intensity" and len(parts) >= 4:
        try:
            value = float(parts[3])
            if not 0.0 <= value <= 1.0:
                return "Intensity must be between 0.0 and 1.0"
            plugin = registry.get(effect_name)
            if plugin:
                plugin.config.intensity = value
                return f"Set {effect_name} intensity to {value}"
        except ValueError:
            return "Invalid intensity value"
    return f"Unknown action: {action}"
 def _format_stats() -> str:
    monitor = get_monitor()
    stats = monitor.get_stats()
    if "error" in stats:
        return stats["error"]
    lines = ["Performance Stats:"]
    pipeline = stats["pipeline"]
    lines.append(
        f"  Pipeline: avg={pipeline['avg_ms']:.2f}ms min={pipeline['min_ms']:.2f}ms max={pipeline['max_ms']:.2f}ms (over {stats['frame_count']} frames)"
    )
    if stats["effects"]:
        lines.append("  Per-effect (avg ms):")
        for name, effect_stats in stats["effects"].items():
            lines.append(
                f"    {name}: avg={effect_stats['avg_ms']:.2f}ms min={effect_stats['min_ms']:.2f}ms max={effect_stats['max_ms']:.2f}ms"
            )
    return "\n".join(lines)
 def show_effects_menu() -> str:
    """Generate effects menu text for display."""
    registry = get_registry()
    chain = _get_effect_chain()
    lines = [
        "\033[1;38;5;231m=== EFFECTS MENU ===\033[0m",
        "",
        "Effects:",
    ]
    for name, plugin in registry.list_all().items():
        status = "ON" if plugin.config.enabled else "OFF"
        intensity = plugin.config.intensity
        lines.append(f"  [{status:3}] {name}: intensity={intensity:.2f}")
    if chain:
        lines.append("")
        lines.append(f"Pipeline order: {' -> '.join(chain.get_order())}")
    lines.append("")
    lines.append("Controls:")
    lines.append("  /effects <name> on|off")
    lines.append("  /effects <name> intensity <0.0-1.0>")
    lines.append("  /effects reorder name1,name2,...")
    lines.append("")
    return "\n".join(lines)
--- a/engine/effects/legacy.py
+++ b/engine/effects/legacy.py
--- a/engine/effects/performance.py
+++ b/engine/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
--- a/engine/effects/registry.py
+++ b/engine/effects/registry.py
@@ -0,0 +1,59 @@
 from engine.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
--- a/engine/effects/types.py
+++ b/engine/effects/types.py
@@ -0,0 +1,39 @@
 from dataclasses import dataclass, field
 from typing import Any
@dataclass
 class EffectContext:
    terminal_width: int
    terminal_height: int
    scroll_cam: int
    ticker_height: int
    mic_excess: float
    grad_offset: float
    frame_number: int
    has_message: bool
    items: list = field(default_factory=list)
@dataclass
 class EffectConfig:
    enabled: bool = True
    intensity: float = 1.0
    params: dict[str, Any] = field(default_factory=dict)
 class EffectPlugin:
    name: str
    config: EffectConfig
    def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
        raise NotImplementedError
    def configure(self, config: EffectConfig) -> None:
        raise NotImplementedError
@dataclass
 class PipelineConfig:
    order: list[str] = field(default_factory=list)
    effects: dict[str, EffectConfig] = field(default_factory=dict)
--- a/engine/layers.py
+++ b/engine/layers.py
@@ -10,6 +10,8 @@ from datetime import datetime
 from engine import config
 from engine.effects import (
    EffectChain,
    EffectContext,
    fade_line,
    firehose_line,
    glitch_bar,
@@ -199,3 +201,60 @@ def render_firehose(items: list, w: int, fh: int, h: int) -> list[str]:
            fline = firehose_line(items, w)
            buf.append(f"\033[{scr_row};1H{fline}\033[K")
    return buf
 _effect_chain = None
 def init_effects() -> None:
    """Initialize effect plugins and chain."""
    global _effect_chain
    from engine.effects import EffectChain, get_registry
    registry = get_registry()
    import effects_plugins
    effects_plugins.discover_plugins()
    chain = EffectChain(registry)
    chain.set_order(["noise", "fade", "glitch", "firehose"])
    _effect_chain = chain
 def process_effects(
    buf: list[str],
    w: int,
    h: int,
    scroll_cam: int,
    ticker_h: int,
    mic_excess: float,
    grad_offset: float,
    frame_number: int,
    has_message: bool,
    items: list,
 ) -> list[str]:
    """Process buffer through effect chain."""
    if _effect_chain is None:
        init_effects()
    ctx = EffectContext(
        terminal_width=w,
        terminal_height=h,
        scroll_cam=scroll_cam,
        ticker_height=ticker_h,
        mic_excess=mic_excess,
        grad_offset=grad_offset,
        frame_number=frame_number,
        has_message=has_message,
        items=items,
    )
    return _effect_chain.process(buf, ctx)
 def get_effect_chain() -> EffectChain | None:
    """Get the effect chain instance."""
    global _effect_chain
    if _effect_chain is None:
        init_effects()
    return _effect_chain
--- a/engine/scroll.py
+++ b/engine/scroll.py
@@ -4,33 +4,42 @@ Orchestrates viewport, frame timing, and layers.
 """
 import random
 import sys
 import time
 from engine import config
 from engine.display import (
    Display,
    TerminalDisplay,
 )
 from engine.display import (
    get_monitor as _get_display_monitor,
 )
 from engine.frame import calculate_scroll_step
 from engine.layers import (
    apply_glitch,
    process_effects,
    render_firehose,
    render_message_overlay,
    render_ticker_zone,
 )
 from engine.terminal import CLR
 from engine.viewport import th, tw
 USE_EFFECT_CHAIN = True
-def stream(items, ntfy_poller, mic_monitor):
+
 def stream(items, ntfy_poller, mic_monitor, display: Display | None = None):
    """Main render loop with four layers: message, ticker, scroll motion, firehose."""
    if display is None:
        display = TerminalDisplay()
    random.shuffle(items)
    pool = list(items)
    seen = set()
    queued = 0
    time.sleep(0.5)
    sys.stdout.write(CLR)
    sys.stdout.flush()
    w, h = tw(), th()
    display.init(w, h)
    display.clear()
    fh = config.FIREHOSE_H if config.FIREHOSE else 0
    ticker_view_h = h - fh
    GAP = 3
@@ -42,6 +51,7 @@ def stream(items, ntfy_poller, mic_monitor):
    noise_cache = {}
    scroll_motion_accum = 0.0
    msg_cache = (None, None)
    frame_number = 0
    while True:
        if queued >= config.HEADLINE_LIMIT and not active:
@@ -93,19 +103,39 @@ def stream(items, ntfy_poller, mic_monitor):
        buf.extend(ticker_buf)
        mic_excess = mic_monitor.excess
-        buf = apply_glitch(buf, ticker_buf_start, mic_excess, w)
+        render_start = time.perf_counter()
-        firehose_buf = render_firehose(items, w, fh, h)
+        if USE_EFFECT_CHAIN:
-        buf.extend(firehose_buf)
+            buf = process_effects(
                buf,
                w,
                h,
                scroll_cam,
                ticker_h,
                mic_excess,
                grad_offset,
                frame_number,
                msg is not None,
                items,
            )
        else:
            buf = apply_glitch(buf, ticker_buf_start, mic_excess, w)
            firehose_buf = render_firehose(items, w, fh, h)
            buf.extend(firehose_buf)
        if msg_overlay:
            buf.extend(msg_overlay)
-        sys.stdout.buffer.write("".join(buf).encode())
+        render_elapsed = (time.perf_counter() - render_start) * 1000
-        sys.stdout.flush()
+        monitor = _get_display_monitor()
        if monitor:
            chars = sum(len(line) for line in buf)
            monitor.record_effect("render", render_elapsed, chars, chars)
        display.show(buf)
        elapsed = time.monotonic() - t0
        time.sleep(max(0, config.FRAME_DT - elapsed))
        frame_number += 1
-    sys.stdout.write(CLR)
+    display.cleanup()
    sys.stdout.flush()
--- a/engine/websocket_display.py
+++ b/engine/websocket_display.py
@@ -0,0 +1,264 @@
 """
 WebSocket display server - broadcasts frame buffer to connected web clients.
 Usage:
    ws_display = WebSocketDisplay(host="0.0.0.0", port=8765)
    ws_display.init(80, 24)
    ws_display.show(["line1", "line2", ...])
    ws_display.cleanup()
 """
 import asyncio
 import json
 import threading
 import time
 from typing import Protocol
 try:
    import websockets
 except ImportError:
    websockets = None
 class Display(Protocol):
    """Protocol for display backends."""
    def init(self, width: int, height: int) -> None:
        """Initialize display with dimensions."""
        ...
    def show(self, buffer: list[str]) -> None:
        """Show buffer on display."""
        ...
    def clear(self) -> None:
        """Clear display."""
        ...
    def cleanup(self) -> None:
        """Shutdown display."""
        ...
 def get_monitor():
    """Get the performance monitor."""
    try:
        from engine.effects.performance import get_monitor as _get_monitor
        return _get_monitor()
    except Exception:
        return None
 class WebSocketDisplay:
    """WebSocket display backend - broadcasts to HTML Canvas clients."""
    def __init__(
        self,
        host: str = "0.0.0.0",
        port: int = 8765,
        http_port: int = 8766,
    ):
        self.host = host
        self.port = port
        self.http_port = http_port
        self.width = 80
        self.height = 24
        self._clients: set = set()
        self._server_running = False
        self._http_running = False
        self._server_thread: threading.Thread | None = None
        self._http_thread: threading.Thread | None = None
        self._available = True
        self._max_clients = 10
        self._client_connected_callback = None
        self._client_disconnected_callback = None
        self._frame_delay = 0.0
        try:
            import websockets as _ws
            self._available = _ws is not None
        except ImportError:
            self._available = False
    def is_available(self) -> bool:
        """Check if WebSocket support is available."""
        return self._available
    def init(self, width: int, height: int) -> None:
        """Initialize display with dimensions and start server."""
        self.width = width
        self.height = height
        self.start_server()
        self.start_http_server()
    def show(self, buffer: list[str]) -> None:
        """Broadcast buffer to all connected clients."""
        t0 = time.perf_counter()
        if self._clients:
            frame_data = {
                "type": "frame",
                "width": self.width,
                "height": self.height,
                "lines": buffer,
            }
            message = json.dumps(frame_data)
            disconnected = set()
            for client in list(self._clients):
                try:
                    asyncio.run(client.send(message))
                except Exception:
                    disconnected.add(client)
            for client in disconnected:
                self._clients.discard(client)
                if self._client_disconnected_callback:
                    self._client_disconnected_callback(client)
        elapsed_ms = (time.perf_counter() - t0) * 1000
        monitor = get_monitor()
        if monitor:
            chars_in = sum(len(line) for line in buffer)
            monitor.record_effect("websocket_display", elapsed_ms, chars_in, chars_in)
    def clear(self) -> None:
        """Broadcast clear command to all clients."""
        if self._clients:
            clear_data = {"type": "clear"}
            message = json.dumps(clear_data)
            for client in list(self._clients):
                try:
                    asyncio.run(client.send(message))
                except Exception:
                    pass
    def cleanup(self) -> None:
        """Stop the servers."""
        self.stop_server()
        self.stop_http_server()
    async def _websocket_handler(self, websocket):
        """Handle WebSocket connections."""
        if len(self._clients) >= self._max_clients:
            await websocket.close()
            return
        self._clients.add(websocket)
        if self._client_connected_callback:
            self._client_connected_callback(websocket)
        try:
            async for message in websocket:
                try:
                    data = json.loads(message)
                    if data.get("type") == "resize":
                        self.width = data.get("width", 80)
                        self.height = data.get("height", 24)
                except json.JSONDecodeError:
                    pass
        except Exception:
            pass
        finally:
            self._clients.discard(websocket)
            if self._client_disconnected_callback:
                self._client_disconnected_callback(websocket)
    async def _run_websocket_server(self):
        """Run the WebSocket server."""
        async with websockets.serve(self._websocket_handler, self.host, self.port):
            while self._server_running:
                await asyncio.sleep(0.1)
    async def _run_http_server(self):
        """Run simple HTTP server for the client."""
        import os
        from http.server import HTTPServer, SimpleHTTPRequestHandler
        client_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "client")
        class Handler(SimpleHTTPRequestHandler):
            def __init__(self, *args, **kwargs):
                super().__init__(*args, directory=client_dir, **kwargs)
            def log_message(self, format, *args):
                pass
        httpd = HTTPServer((self.host, self.http_port), Handler)
        while self._http_running:
            httpd.handle_request()
    def _run_async(self, coro):
        """Run coroutine in background."""
        try:
            asyncio.run(coro)
        except Exception as e:
            print(f"WebSocket async error: {e}")
    def start_server(self):
        """Start the WebSocket server in a background thread."""
        if not self._available:
            return
        if self._server_thread is not None:
            return
        self._server_running = True
        self._server_thread = threading.Thread(
            target=self._run_async, args=(self._run_websocket_server(),), daemon=True
        )
        self._server_thread.start()
    def stop_server(self):
        """Stop the WebSocket server."""
        self._server_running = False
        self._server_thread = None
    def start_http_server(self):
        """Start the HTTP server in a background thread."""
        if not self._available:
            return
        if self._http_thread is not None:
            return
        self._http_running = True
        self._http_running = True
        self._http_thread = threading.Thread(
            target=self._run_async, args=(self._run_http_server(),), daemon=True
        )
        self._http_thread.start()
    def stop_http_server(self):
        """Stop the HTTP server."""
        self._http_running = False
        self._http_thread = None
    def client_count(self) -> int:
        """Return number of connected clients."""
        return len(self._clients)
    def get_ws_port(self) -> int:
        """Return WebSocket port."""
        return self.port
    def get_http_port(self) -> int:
        """Return HTTP port."""
        return self.http_port
    def set_frame_delay(self, delay: float) -> None:
        """Set delay between frames in seconds."""
        self._frame_delay = delay
    def get_frame_delay(self) -> float:
        """Get delay between frames."""
        return self._frame_delay
    def set_client_connected_callback(self, callback) -> None:
        """Set callback for client connections."""
        self._client_connected_callback = callback
    def set_client_disconnected_callback(self, callback) -> None:
        """Set callback for client disconnections."""
        self._client_disconnected_callback = callback
--- a/mise.toml
+++ b/mise.toml
@@ -13,6 +13,9 @@ test-v = "uv run pytest -v"
 test-cov = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html"
 test-cov-open = "uv run pytest --cov=engine --cov-report=term-missing --cov-report=html && open htmlcov/index.html"
 test-browser-install = { run = "uv run playwright install chromium", depends = ["sync-all"] }
 test-browser = { run = "uv run pytest tests/e2e/", depends = ["test-browser-install"] }
 lint = "uv run ruff check engine/ mainline.py"
 lint-fix = "uv run ruff check --fix engine/ mainline.py"
 format = "uv run ruff format engine/ mainline.py"
@@ -24,6 +27,9 @@ format = "uv run ruff format engine/ mainline.py"
 run = "uv run mainline.py"
 run-poetry = "uv run mainline.py --poetry"
 run-firehose = "uv run mainline.py --firehose"
 run-websocket = { run = "uv run mainline.py --websocket", depends = ["sync-all"] }
 run-both = { run = "uv run mainline.py --display both", depends = ["sync-all"] }
 run-client = { run = "uv run mainline.py --display both & WEBSOCKET_PID=$! && sleep 2 && case $(uname -s) in Darwin) open http://localhost:8766 ;; Linux) xdg-open http://localhost:8766 ;; CYGWIN*) cmd /c start http://localhost:8766 ;; *) echo 'Unknown platform' ;; esac && wait $WEBSOCKET_PID", depends = ["sync-all"] }
 # =====================
 # Environment
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,6 +30,12 @@ mic = [
    "sounddevice>=0.4.0",
    "numpy>=1.24.0",
 ]
 websocket = [
    "websockets>=12.0",
 ]
 browser = [
    "playwright>=1.40.0",
 ]
 dev = [
    "pytest>=8.0.0",
    "pytest-cov>=4.1.0",
--- a/tests/e2e/test_web_client.py
+++ b/tests/e2e/test_web_client.py
@@ -0,0 +1,133 @@
 """
 End-to-end tests for web client with headless browser.
 """
 import os
 import socketserver
 import threading
 from http.server import HTTPServer, SimpleHTTPRequestHandler
 from pathlib import Path
 import pytest
 CLIENT_DIR = Path(__file__).parent.parent.parent / "client"
 class ThreadedHTTPServer(socketserver.ThreadingMixIn, HTTPServer):
    """Threaded HTTP server for handling concurrent requests."""
    daemon_threads = True
@pytest.fixture(scope="module")
 def http_server():
    """Start a local HTTP server for the client."""
    os.chdir(CLIENT_DIR)
    handler = SimpleHTTPRequestHandler
    server = ThreadedHTTPServer(("127.0.0.1", 0), handler)
    port = server.server_address[1]
    thread = threading.Thread(target=server.serve_forever, daemon=True)
    thread.start()
    yield f"http://127.0.0.1:{port}"
    server.shutdown()
 class TestWebClient:
    """Tests for the web client using Playwright."""
    @pytest.fixture(autouse=True)
    def setup_browser(self):
        """Set up browser for tests."""
        pytest.importorskip("playwright")
        from playwright.sync_api import sync_playwright
        self.playwright = sync_playwright().start()
        self.browser = self.playwright.chromium.launch(headless=True)
        self.context = self.browser.new_context()
        self.page = self.context.new_page()
        yield
        self.page.close()
        self.context.close()
        self.browser.close()
        self.playwright.stop()
    def test_client_loads(self, http_server):
        """Web client loads without errors."""
        response = self.page.goto(http_server)
        assert response.status == 200, f"Page load failed with status {response.status}"
        self.page.wait_for_load_state("domcontentloaded")
        content = self.page.content()
        assert "<canvas" in content, "Canvas element not found in page"
        canvas = self.page.locator("#terminal")
        assert canvas.count() > 0, "Canvas not found"
    def test_status_shows_connecting(self, http_server):
        """Status shows connecting initially."""
        self.page.goto(http_server)
        self.page.wait_for_load_state("domcontentloaded")
        status = self.page.locator("#status")
        assert status.count() > 0, "Status element not found"
    def test_canvas_has_dimensions(self, http_server):
        """Canvas has correct dimensions after load."""
        self.page.goto(http_server)
        self.page.wait_for_load_state("domcontentloaded")
        canvas = self.page.locator("#terminal")
        assert canvas.count() > 0, "Canvas not found"
    def test_no_console_errors_on_load(self, http_server):
        """No JavaScript errors on page load (websocket errors are expected without server)."""
        js_errors = []
        def handle_console(msg):
            if msg.type == "error":
                text = msg.text
                if "WebSocket" not in text:
                    js_errors.append(text)
        self.page.on("console", handle_console)
        self.page.goto(http_server)
        self.page.wait_for_load_state("domcontentloaded")
        assert len(js_errors) == 0, f"JavaScript errors: {js_errors}"
 class TestWebClientProtocol:
    """Tests for WebSocket protocol handling in client."""
    @pytest.fixture(autouse=True)
    def setup_browser(self):
        """Set up browser for tests."""
        pytest.importorskip("playwright")
        from playwright.sync_api import sync_playwright
        self.playwright = sync_playwright().start()
        self.browser = self.playwright.chromium.launch(headless=True)
        self.context = self.browser.new_context()
        self.page = self.context.new_page()
        yield
        self.page.close()
        self.context.close()
        self.browser.close()
        self.playwright.stop()
    def test_websocket_reconnection(self, http_server):
        """Client attempts reconnection on disconnect."""
        self.page.goto(http_server)
        self.page.wait_for_load_state("domcontentloaded")
        status = self.page.locator("#status")
        assert status.count() > 0, "Status element not found"
--- a/tests/test_app.py
+++ b/tests/test_app.py
@@ -0,0 +1,55 @@
 """
 Tests for engine.app module.
 """
 from engine.app import _normalize_preview_rows
 class TestNormalizePreviewRows:
    """Tests for _normalize_preview_rows function."""
    def test_empty_rows(self):
        """Empty input returns empty list."""
        result = _normalize_preview_rows([])
        assert result == [""]
    def test_strips_left_padding(self):
        """Left padding is stripped."""
        result = _normalize_preview_rows(["  content", "  more"])
        assert all(not r.startswith(" ") for r in result)
    def test_preserves_content(self):
        """Content is preserved."""
        result = _normalize_preview_rows(["  hello world  "])
        assert "hello world" in result[0]
    def test_handles_all_empty_rows(self):
        """All empty rows returns single empty string."""
        result = _normalize_preview_rows(["", "   ", ""])
        assert result == [""]
 class TestAppConstants:
    """Tests for app module constants."""
    def test_title_defined(self):
        """TITLE is defined."""
        from engine.app import TITLE
        assert len(TITLE) > 0
    def test_title_lines_are_strings(self):
        """TITLE contains string lines."""
        from engine.app import TITLE
        assert all(isinstance(line, str) for line in TITLE)
 class TestAppImports:
    """Tests for app module imports."""
    def test_app_imports_without_error(self):
        """Module imports without error."""
        from engine import app
        assert app is not None
--- a/tests/test_display.py
+++ b/tests/test_display.py
@@ -0,0 +1,79 @@
 """
 Tests for engine.display module.
 """
 from engine.display import NullDisplay, TerminalDisplay
 class TestDisplayProtocol:
    """Test that display backends satisfy the Display protocol."""
    def test_terminal_display_is_display(self):
        """TerminalDisplay satisfies Display protocol."""
        display = TerminalDisplay()
        assert hasattr(display, "init")
        assert hasattr(display, "show")
        assert hasattr(display, "clear")
        assert hasattr(display, "cleanup")
    def test_null_display_is_display(self):
        """NullDisplay satisfies Display protocol."""
        display = NullDisplay()
        assert hasattr(display, "init")
        assert hasattr(display, "show")
        assert hasattr(display, "clear")
        assert hasattr(display, "cleanup")
 class TestTerminalDisplay:
    """Tests for TerminalDisplay class."""
    def test_init_sets_dimensions(self):
        """init stores terminal dimensions."""
        display = TerminalDisplay()
        display.init(80, 24)
        assert display.width == 80
        assert display.height == 24
    def test_show_returns_none(self):
        """show returns None after writing to stdout."""
        display = TerminalDisplay()
        display.width = 80
        display.height = 24
        display.show(["line1", "line2"])
    def test_clear_does_not_error(self):
        """clear works without error."""
        display = TerminalDisplay()
        display.clear()
    def test_cleanup_does_not_error(self):
        """cleanup works without error."""
        display = TerminalDisplay()
        display.cleanup()
 class TestNullDisplay:
    """Tests for NullDisplay class."""
    def test_init_stores_dimensions(self):
        """init stores dimensions."""
        display = NullDisplay()
        display.init(100, 50)
        assert display.width == 100
        assert display.height == 50
    def test_show_does_nothing(self):
        """show discards buffer without error."""
        display = NullDisplay()
        display.show(["line1", "line2", "line3"])
    def test_clear_does_nothing(self):
        """clear does nothing."""
        display = NullDisplay()
        display.clear()
    def test_cleanup_does_nothing(self):
        """cleanup does nothing."""
        display = NullDisplay()
        display.cleanup()
--- a/tests/test_effects.py
+++ b/tests/test_effects.py
@@ -0,0 +1,427 @@
 """
 Tests for engine.effects module.
 """
 from engine.effects import EffectChain, EffectConfig, EffectContext, EffectRegistry
 class MockEffect:
    name = "mock"
    config = EffectConfig(enabled=True, intensity=1.0)
    def __init__(self):
        self.processed = False
        self.last_ctx = None
    def process(self, buf, ctx):
        self.processed = True
        self.last_ctx = ctx
        return buf + ["processed"]
    def configure(self, config):
        self.config = config
 class TestEffectConfig:
    def test_defaults(self):
        cfg = EffectConfig()
        assert cfg.enabled is True
        assert cfg.intensity == 1.0
        assert cfg.params == {}
    def test_custom_values(self):
        cfg = EffectConfig(enabled=False, intensity=0.5, params={"key": "value"})
        assert cfg.enabled is False
        assert cfg.intensity == 0.5
        assert cfg.params == {"key": "value"}
 class TestEffectContext:
    def test_defaults(self):
        ctx = EffectContext(
            terminal_width=80,
            terminal_height=24,
            scroll_cam=0,
            ticker_height=20,
            mic_excess=0.0,
            grad_offset=0.0,
            frame_number=0,
            has_message=False,
        )
        assert ctx.terminal_width == 80
        assert ctx.terminal_height == 24
        assert ctx.ticker_height == 20
        assert ctx.items == []
    def test_with_items(self):
        items = [("Title", "Source", "12:00")]
        ctx = EffectContext(
            terminal_width=80,
            terminal_height=24,
            scroll_cam=0,
            ticker_height=20,
            mic_excess=0.0,
            grad_offset=0.0,
            frame_number=0,
            has_message=False,
            items=items,
        )
        assert ctx.items == items
 class TestEffectRegistry:
    def test_init_empty(self):
        registry = EffectRegistry()
        assert len(registry.list_all()) == 0
    def test_register(self):
        registry = EffectRegistry()
        effect = MockEffect()
        registry.register(effect)
        assert "mock" in registry.list_all()
    def test_get(self):
        registry = EffectRegistry()
        effect = MockEffect()
        registry.register(effect)
        retrieved = registry.get("mock")
        assert retrieved is effect
    def test_get_nonexistent(self):
        registry = EffectRegistry()
        assert registry.get("nonexistent") is None
    def test_enable(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.config.enabled = False
        registry.register(effect)
        registry.enable("mock")
        assert effect.config.enabled is True
    def test_disable(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.config.enabled = True
        registry.register(effect)
        registry.disable("mock")
        assert effect.config.enabled is False
    def test_list_enabled(self):
        registry = EffectRegistry()
        class EnabledEffect:
            name = "enabled_effect"
            config = EffectConfig(enabled=True, intensity=1.0)
        class DisabledEffect:
            name = "disabled_effect"
            config = EffectConfig(enabled=False, intensity=1.0)
        registry.register(EnabledEffect())
        registry.register(DisabledEffect())
        enabled = registry.list_enabled()
        assert len(enabled) == 1
        assert enabled[0].name == "enabled_effect"
    def test_configure(self):
        registry = EffectRegistry()
        effect = MockEffect()
        registry.register(effect)
        new_config = EffectConfig(enabled=False, intensity=0.3)
        registry.configure("mock", new_config)
        assert effect.config.enabled is False
        assert effect.config.intensity == 0.3
    def test_is_enabled(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.config.enabled = True
        registry.register(effect)
        assert registry.is_enabled("mock") is True
        assert registry.is_enabled("nonexistent") is False
 class TestEffectChain:
    def test_init(self):
        registry = EffectRegistry()
        chain = EffectChain(registry)
        assert chain.get_order() == []
    def test_set_order(self):
        registry = EffectRegistry()
        effect1 = MockEffect()
        effect1.name = "effect1"
        effect2 = MockEffect()
        effect2.name = "effect2"
        registry.register(effect1)
        registry.register(effect2)
        chain = EffectChain(registry)
        chain.set_order(["effect1", "effect2"])
        assert chain.get_order() == ["effect1", "effect2"]
    def test_add_effect(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.name = "test_effect"
        registry.register(effect)
        chain = EffectChain(registry)
        chain.add_effect("test_effect")
        assert "test_effect" in chain.get_order()
    def test_add_effect_invalid(self):
        registry = EffectRegistry()
        chain = EffectChain(registry)
        result = chain.add_effect("nonexistent")
        assert result is False
    def test_remove_effect(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.name = "test_effect"
        registry.register(effect)
        chain = EffectChain(registry)
        chain.set_order(["test_effect"])
        chain.remove_effect("test_effect")
        assert "test_effect" not in chain.get_order()
    def test_reorder(self):
        registry = EffectRegistry()
        effect1 = MockEffect()
        effect1.name = "effect1"
        effect2 = MockEffect()
        effect2.name = "effect2"
        effect3 = MockEffect()
        effect3.name = "effect3"
        registry.register(effect1)
        registry.register(effect2)
        registry.register(effect3)
        chain = EffectChain(registry)
        chain.set_order(["effect1", "effect2", "effect3"])
        result = chain.reorder(["effect3", "effect1", "effect2"])
        assert result is True
        assert chain.get_order() == ["effect3", "effect1", "effect2"]
    def test_reorder_invalid(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.name = "effect1"
        registry.register(effect)
        chain = EffectChain(registry)
        result = chain.reorder(["effect1", "nonexistent"])
        assert result is False
    def test_process_empty_chain(self):
        registry = EffectRegistry()
        chain = EffectChain(registry)
        buf = ["line1", "line2"]
        ctx = EffectContext(
            terminal_width=80,
            terminal_height=24,
            scroll_cam=0,
            ticker_height=20,
            mic_excess=0.0,
            grad_offset=0.0,
            frame_number=0,
            has_message=False,
        )
        result = chain.process(buf, ctx)
        assert result == buf
    def test_process_with_effects(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.name = "test_effect"
        registry.register(effect)
        chain = EffectChain(registry)
        chain.set_order(["test_effect"])
        buf = ["line1", "line2"]
        ctx = EffectContext(
            terminal_width=80,
            terminal_height=24,
            scroll_cam=0,
            ticker_height=20,
            mic_excess=0.0,
            grad_offset=0.0,
            frame_number=0,
            has_message=False,
        )
        result = chain.process(buf, ctx)
        assert result == ["line1", "line2", "processed"]
        assert effect.processed is True
        assert effect.last_ctx is ctx
    def test_process_disabled_effect(self):
        registry = EffectRegistry()
        effect = MockEffect()
        effect.name = "test_effect"
        effect.config.enabled = False
        registry.register(effect)
        chain = EffectChain(registry)
        chain.set_order(["test_effect"])
        buf = ["line1"]
        ctx = EffectContext(
            terminal_width=80,
            terminal_height=24,
            scroll_cam=0,
            ticker_height=20,
            mic_excess=0.0,
            grad_offset=0.0,
            frame_number=0,
            has_message=False,
        )
        result = chain.process(buf, ctx)
        assert result == ["line1"]
        assert effect.processed is False
 class TestEffectsExports:
    def test_all_exports_are_importable(self):
        """Verify all exports in __all__ can actually be imported."""
        import engine.effects as effects_module
        for name in effects_module.__all__:
            getattr(effects_module, name)
 class TestPerformanceMonitor:
    def test_empty_stats(self):
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor()
        stats = monitor.get_stats()
        assert "error" in stats
    def test_record_and_retrieve(self):
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor()
        monitor.start_frame(1)
        monitor.record_effect("test_effect", 1.5, 100, 150)
        monitor.end_frame(1, 2.0)
        stats = monitor.get_stats()
        assert "error" not in stats
        assert stats["frame_count"] == 1
        assert "test_effect" in stats["effects"]
    def test_multiple_frames(self):
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor(max_frames=3)
        for i in range(5):
            monitor.start_frame(i)
            monitor.record_effect("effect1", 1.0, 100, 100)
            monitor.record_effect("effect2", 0.5, 100, 100)
            monitor.end_frame(i, 1.5)
        stats = monitor.get_stats()
        assert stats["frame_count"] == 3
        assert "effect1" in stats["effects"]
        assert "effect2" in stats["effects"]
    def test_reset(self):
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor()
        monitor.start_frame(1)
        monitor.record_effect("test", 1.0, 100, 100)
        monitor.end_frame(1, 1.0)
        monitor.reset()
        stats = monitor.get_stats()
        assert "error" in stats
 class TestEffectPipelinePerformance:
    def test_pipeline_stays_within_frame_budget(self):
        """Verify effect pipeline completes within frame budget (33ms for 30fps)."""
        from engine.effects import (
            EffectChain,
            EffectConfig,
            EffectContext,
            EffectRegistry,
        )
        class DummyEffect:
            name = "dummy"
            config = EffectConfig(enabled=True, intensity=1.0)
            def process(self, buf, ctx):
                return [line * 2 for line in buf]
        registry = EffectRegistry()
        registry.register(DummyEffect())
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor(max_frames=10)
        chain = EffectChain(registry, monitor)
        chain.set_order(["dummy"])
        buf = ["x" * 80] * 20
        for i in range(10):
            ctx = EffectContext(
                terminal_width=80,
                terminal_height=24,
                scroll_cam=0,
                ticker_height=20,
                mic_excess=0.0,
                grad_offset=0.0,
                frame_number=i,
                has_message=False,
            )
            chain.process(buf, ctx)
        stats = monitor.get_stats()
        assert "error" not in stats
        assert stats["pipeline"]["max_ms"] < 33.0
    def test_individual_effects_performance(self):
        """Verify individual effects don't exceed 10ms per frame."""
        from engine.effects import (
            EffectChain,
            EffectConfig,
            EffectContext,
            EffectRegistry,
        )
        class SlowEffect:
            name = "slow"
            config = EffectConfig(enabled=True, intensity=1.0)
            def process(self, buf, ctx):
                result = []
                for line in buf:
                    result.append(line)
                    result.append(line + line)
                return result
        registry = EffectRegistry()
        registry.register(SlowEffect())
        from engine.effects.performance import PerformanceMonitor
        monitor = PerformanceMonitor(max_frames=5)
        chain = EffectChain(registry, monitor)
        chain.set_order(["slow"])
        buf = ["x" * 80] * 10
        for i in range(5):
            ctx = EffectContext(
                terminal_width=80,
                terminal_height=24,
                scroll_cam=0,
                ticker_height=20,
                mic_excess=0.0,
                grad_offset=0.0,
                frame_number=i,
                has_message=False,
            )
            chain.process(buf, ctx)
        stats = monitor.get_stats()
        assert "error" not in stats
        assert stats["effects"]["slow"]["max_ms"] < 10.0
--- a/tests/test_effects_controller.py
+++ b/tests/test_effects_controller.py
@@ -0,0 +1,117 @@
 """
 Tests for engine.effects.controller module.
 """
 from unittest.mock import MagicMock, patch
 from engine.effects.controller import (
    handle_effects_command,
    set_effect_chain_ref,
 )
 class TestHandleEffectsCommand:
    """Tests for handle_effects_command function."""
    def test_list_effects(self):
        """list command returns formatted effects list."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_plugin = MagicMock()
            mock_plugin.config.enabled = True
            mock_plugin.config.intensity = 0.5
            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
            with patch("engine.effects.controller._get_effect_chain") as mock_chain:
                mock_chain.return_value.get_order.return_value = ["noise"]
                result = handle_effects_command("/effects list")
                assert "noise: ON" in result
                assert "intensity=0.5" in result
    def test_enable_effect(self):
        """enable command calls registry.enable."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_plugin = MagicMock()
            mock_registry.return_value.get.return_value = mock_plugin
            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
            result = handle_effects_command("/effects noise on")
            assert "Enabled: noise" in result
            mock_registry.return_value.enable.assert_called_once_with("noise")
    def test_disable_effect(self):
        """disable command calls registry.disable."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_plugin = MagicMock()
            mock_registry.return_value.get.return_value = mock_plugin
            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
            result = handle_effects_command("/effects noise off")
            assert "Disabled: noise" in result
            mock_registry.return_value.disable.assert_called_once_with("noise")
    def test_set_intensity(self):
        """intensity command sets plugin intensity."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_plugin = MagicMock()
            mock_plugin.config.intensity = 0.5
            mock_registry.return_value.get.return_value = mock_plugin
            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
            result = handle_effects_command("/effects noise intensity 0.8")
            assert "intensity to 0.8" in result
            assert mock_plugin.config.intensity == 0.8
    def test_invalid_intensity_range(self):
        """intensity outside 0.0-1.0 returns error."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_plugin = MagicMock()
            mock_registry.return_value.get.return_value = mock_plugin
            mock_registry.return_value.list_all.return_value = {"noise": mock_plugin}
            result = handle_effects_command("/effects noise intensity 1.5")
            assert "between 0.0 and 1.0" in result
    def test_reorder_pipeline(self):
        """reorder command calls chain.reorder."""
        with patch("engine.effects.controller.get_registry") as mock_registry:
            mock_registry.return_value.list_all.return_value = {}
            with patch("engine.effects.controller._get_effect_chain") as mock_chain:
                mock_chain_instance = MagicMock()
                mock_chain_instance.reorder.return_value = True
                mock_chain.return_value = mock_chain_instance
                result = handle_effects_command("/effects reorder noise,fade")
                assert "Reordered pipeline" in result
                mock_chain_instance.reorder.assert_called_once_with(["noise", "fade"])
    def test_unknown_command(self):
        """unknown command returns error."""
        result = handle_effects_command("/unknown")
        assert "Unknown command" in result
    def test_non_effects_command(self):
        """non-effects command returns error."""
        result = handle_effects_command("not a command")
        assert "Unknown command" in result
 class TestSetEffectChainRef:
    """Tests for set_effect_chain_ref function."""
    def test_sets_global_ref(self):
        """set_effect_chain_ref updates global reference."""
        mock_chain = MagicMock()
        set_effect_chain_ref(mock_chain)
        from engine.effects.controller import _get_effect_chain
        result = _get_effect_chain()
        assert result == mock_chain
--- a/tests/test_fetch.py
+++ b/tests/test_fetch.py
@@ -0,0 +1,234 @@
 """
 Tests for engine.fetch module.
 """
 import json
 from unittest.mock import MagicMock, patch
 from engine.fetch import (
    _fetch_gutenberg,
    fetch_all,
    fetch_feed,
    fetch_poetry,
    load_cache,
    save_cache,
 )
 class TestFetchFeed:
    """Tests for fetch_feed function."""
    @patch("engine.fetch.urllib.request.urlopen")
    def test_fetch_success(self, mock_urlopen):
        """Successful feed fetch returns parsed feed."""
        mock_response = MagicMock()
        mock_response.read.return_value = b"<rss>test</rss>"
        mock_urlopen.return_value = mock_response
        result = fetch_feed("http://example.com/feed")
        assert result is not None
    @patch("engine.fetch.urllib.request.urlopen")
    def test_fetch_network_error(self, mock_urlopen):
        """Network error returns None."""
        mock_urlopen.side_effect = Exception("Network error")
        result = fetch_feed("http://example.com/feed")
        assert result is None
 class TestFetchAll:
    """Tests for fetch_all function."""
    @patch("engine.fetch.fetch_feed")
    @patch("engine.fetch.strip_tags")
    @patch("engine.fetch.skip")
    @patch("engine.fetch.boot_ln")
    def test_fetch_all_success(self, mock_boot, mock_skip, mock_strip, mock_fetch_feed):
        """Successful fetch returns items."""
        mock_feed = MagicMock()
        mock_feed.bozo = False
        mock_feed.entries = [
            {"title": "Headline 1", "published_parsed": (2024, 1, 1, 12, 0, 0)},
            {"title": "Headline 2", "updated_parsed": (2024, 1, 2, 12, 0, 0)},
        ]
        mock_fetch_feed.return_value = mock_feed
        mock_skip.return_value = False
        mock_strip.side_effect = lambda x: x
        items, linked, failed = fetch_all()
        assert linked > 0
        assert failed == 0
    @patch("engine.fetch.fetch_feed")
    @patch("engine.fetch.boot_ln")
    def test_fetch_all_feed_error(self, mock_boot, mock_fetch_feed):
        """Feed error increments failed count."""
        mock_fetch_feed.return_value = None
        items, linked, failed = fetch_all()
        assert failed > 0
    @patch("engine.fetch.fetch_feed")
    @patch("engine.fetch.strip_tags")
    @patch("engine.fetch.skip")
    @patch("engine.fetch.boot_ln")
    def test_fetch_all_skips_filtered(
        self, mock_boot, mock_skip, mock_strip, mock_fetch_feed
    ):
        """Filtered headlines are skipped."""
        mock_feed = MagicMock()
        mock_feed.bozo = False
        mock_feed.entries = [
            {"title": "Sports scores"},
            {"title": "Valid headline"},
        ]
        mock_fetch_feed.return_value = mock_feed
        mock_skip.side_effect = lambda x: x == "Sports scores"
        mock_strip.side_effect = lambda x: x
        items, linked, failed = fetch_all()
        assert any("Valid headline" in item[0] for item in items)
 class TestFetchGutenberg:
    """Tests for _fetch_gutenberg function."""
    @patch("engine.fetch.urllib.request.urlopen")
    def test_gutenberg_success(self, mock_urlopen):
        """Successful gutenberg fetch returns items."""
        text = """Project Gutenberg
 *** START OF THE PROJECT GUTENBERG ***
 This is a test poem with multiple lines
 that should be parsed as a block.
 Another stanza with more content here.
 *** END OF THE PROJECT GUTENBERG ***
 """
        mock_response = MagicMock()
        mock_response.read.return_value = text.encode("utf-8")
        mock_urlopen.return_value = mock_response
        result = _fetch_gutenberg("http://example.com/test", "Test")
        assert len(result) > 0
    @patch("engine.fetch.urllib.request.urlopen")
    def test_gutenberg_network_error(self, mock_urlopen):
        """Network error returns empty list."""
        mock_urlopen.side_effect = Exception("Network error")
        result = _fetch_gutenberg("http://example.com/test", "Test")
        assert result == []
    @patch("engine.fetch.urllib.request.urlopen")
    def test_gutenberg_skips_short_blocks(self, mock_urlopen):
        """Blocks shorter than 20 chars are skipped."""
        text = """*** START OF THE ***
 Short
 *** END OF THE ***
 """
        mock_response = MagicMock()
        mock_response.read.return_value = text.encode("utf-8")
        mock_urlopen.return_value = mock_response
        result = _fetch_gutenberg("http://example.com/test", "Test")
        assert result == []
    @patch("engine.fetch.urllib.request.urlopen")
    def test_gutenberg_skips_all_caps_headers(self, mock_urlopen):
        """All-caps lines are skipped as headers."""
        text = """*** START OF THE ***
 THIS IS ALL CAPS HEADER
 more content here
 *** END OF THE ***
 """
        mock_response = MagicMock()
        mock_response.read.return_value = text.encode("utf-8")
        mock_urlopen.return_value = mock_response
        result = _fetch_gutenberg("http://example.com/test", "Test")
        assert len(result) > 0
 class TestFetchPoetry:
    """Tests for fetch_poetry function."""
    @patch("engine.fetch._fetch_gutenberg")
    @patch("engine.fetch.boot_ln")
    def test_fetch_poetry_success(self, mock_boot, mock_fetch):
        """Successful poetry fetch returns items."""
        mock_fetch.return_value = [
            ("Stanza 1 content here", "Test", ""),
            ("Stanza 2 content here", "Test", ""),
        ]
        items, linked, failed = fetch_poetry()
        assert linked > 0
        assert failed == 0
    @patch("engine.fetch._fetch_gutenberg")
    @patch("engine.fetch.boot_ln")
    def test_fetch_poetry_failure(self, mock_boot, mock_fetch):
        """Failed fetch increments failed count."""
        mock_fetch.return_value = []
        items, linked, failed = fetch_poetry()
        assert failed > 0
 class TestCache:
    """Tests for cache functions."""
    @patch("engine.fetch._cache_path")
    def test_load_cache_success(self, mock_path):
        """Successful cache load returns items."""
        mock_path.return_value.__str__ = MagicMock(return_value="/tmp/cache")
        mock_path.return_value.exists.return_value = True
        mock_path.return_value.read_text.return_value = json.dumps(
            {"items": [("title", "source", "time")]}
        )
        result = load_cache()
        assert result is not None
    @patch("engine.fetch._cache_path")
    def test_load_cache_missing_file(self, mock_path):
        """Missing cache file returns None."""
        mock_path.return_value.exists.return_value = False
        result = load_cache()
        assert result is None
    @patch("engine.fetch._cache_path")
    def test_load_cache_invalid_json(self, mock_path):
        """Invalid JSON returns None."""
        mock_path.return_value.exists.return_value = True
        mock_path.return_value.read_text.side_effect = json.JSONDecodeError("", "", 0)
        result = load_cache()
        assert result is None
    @patch("engine.fetch._cache_path")
    def test_save_cache_success(self, mock_path):
        """Save cache writes to file."""
        mock_path.return_value.__truediv__ = MagicMock(
            return_value=mock_path.return_value
        )
        save_cache([("title", "source", "time")])
--- a/tests/test_render.py
+++ b/tests/test_render.py
@@ -0,0 +1,232 @@
 """
 Tests for engine.render module.
 """
 from unittest.mock import MagicMock, patch
 import pytest
 from engine.render import (
    GRAD_COLS,
    MSG_GRAD_COLS,
    clear_font_cache,
    font_for_lang,
    lr_gradient,
    lr_gradient_opposite,
    make_block,
 )
 class TestGradientConstants:
    """Tests for gradient color constants."""
    def test_grad_cols_defined(self):
        """GRAD_COLS is defined with expected length."""
        assert len(GRAD_COLS) > 0
        assert all(isinstance(c, str) for c in GRAD_COLS)
    def test_msg_grad_cols_defined(self):
        """MSG_GRAD_COLS is defined with expected length."""
        assert len(MSG_GRAD_COLS) > 0
        assert all(isinstance(c, str) for c in MSG_GRAD_COLS)
    def test_grad_cols_start_with_white(self):
        """GRAD_COLS starts with white."""
        assert "231" in GRAD_COLS[0]
    def test_msg_grad_cols_different_from_grad_cols(self):
        """MSG_GRAD_COLS is different from GRAD_COLS."""
        assert MSG_GRAD_COLS != GRAD_COLS
 class TestLrGradient:
    """Tests for lr_gradient function."""
    def test_empty_rows(self):
        """Empty input returns empty output."""
        result = lr_gradient([], 0.0)
        assert result == []
    def test_preserves_empty_rows(self):
        """Empty rows are preserved."""
        result = lr_gradient([""], 0.0)
        assert result == [""]
    def test_adds_gradient_to_content(self):
        """Non-empty rows get gradient coloring."""
        result = lr_gradient(["hello"], 0.0)
        assert len(result) == 1
        assert "\033[" in result[0]
    def test_preserves_spaces(self):
        """Spaces are preserved without coloring."""
        result = lr_gradient(["hello world"], 0.0)
        assert " " in result[0]
    def test_offset_wraps_around(self):
        """Offset wraps around at 1.0."""
        result1 = lr_gradient(["hello"], 0.0)
        result2 = lr_gradient(["hello"], 1.0)
        assert result1 != result2 or result1 == result2
 class TestLrGradientOpposite:
    """Tests for lr_gradient_opposite function."""
    def test_uses_msg_grad_cols(self):
        """Uses MSG_GRAD_COLS instead of GRAD_COLS."""
        result = lr_gradient_opposite(["test"])
        assert "\033[" in result[0]
 class TestClearFontCache:
    """Tests for clear_font_cache function."""
    def test_clears_without_error(self):
        """Function runs without error."""
        clear_font_cache()
 class TestFontForLang:
    """Tests for font_for_lang function."""
    @patch("engine.render.font")
    def test_returns_default_for_none(self, mock_font):
        """Returns default font when lang is None."""
        result = font_for_lang(None)
        assert result is not None
    @patch("engine.render.font")
    def test_returns_default_for_unknown_lang(self, mock_font):
        """Returns default font for unknown language."""
        result = font_for_lang("unknown_lang")
        assert result is not None
 class TestMakeBlock:
    """Tests for make_block function."""
    @patch("engine.translate.translate_headline")
    @patch("engine.translate.detect_location_language")
    @patch("engine.render.font_for_lang")
    @patch("engine.render.big_wrap")
    @patch("engine.render.random")
    def test_make_block_basic(
        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
    ):
        """Basic make_block returns content, color, meta index."""
        mock_wrap.return_value = ["Headline content", ""]
        mock_random.choice.return_value = "\033[38;5;46m"
        content, color, meta_idx = make_block(
            "Test headline", "TestSource", "12:00", 80
        )
        assert len(content) > 0
        assert color is not None
        assert meta_idx >= 0
    @pytest.mark.skip(reason="Requires full PIL/font environment")
    @patch("engine.translate.translate_headline")
    @patch("engine.translate.detect_location_language")
    @patch("engine.render.font_for_lang")
    @patch("engine.render.big_wrap")
    @patch("engine.render.random")
    def test_make_block_translation(
        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
    ):
        """Translation is applied when mode is news."""
        mock_wrap.return_value = ["Translated"]
        mock_random.choice.return_value = "\033[38;5;46m"
        mock_detect.return_value = "de"
        with patch("engine.config.MODE", "news"):
            content, _, _ = make_block("Test", "Source", "12:00", 80)
            mock_translate.assert_called_once()
    @patch("engine.translate.translate_headline")
    @patch("engine.translate.detect_location_language")
    @patch("engine.render.font_for_lang")
    @patch("engine.render.big_wrap")
    @patch("engine.render.random")
    def test_make_block_no_translation_poetry(
        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
    ):
        """No translation when mode is poetry."""
        mock_wrap.return_value = ["Poem content"]
        mock_random.choice.return_value = "\033[38;5;46m"
        with patch("engine.config.MODE", "poetry"):
            make_block("Test", "Source", "12:00", 80)
            mock_translate.assert_not_called()
    @patch("engine.translate.translate_headline")
    @patch("engine.translate.detect_location_language")
    @patch("engine.render.font_for_lang")
    @patch("engine.render.big_wrap")
    @patch("engine.render.random")
    def test_make_block_meta_format(
        self, mock_random, mock_wrap, mock_font, mock_detect, mock_translate
    ):
        """Meta line includes source and timestamp."""
        mock_wrap.return_value = ["Content"]
        mock_random.choice.return_value = "\033[38;5;46m"
        content, _, meta_idx = make_block("Test", "MySource", "14:30", 80)
        meta_line = content[meta_idx]
        assert "MySource" in meta_line
        assert "14:30" in meta_line
 class TestRenderLine:
    """Tests for render_line function."""
    def test_empty_string(self):
        """Empty string returns empty list."""
        from engine.render import render_line
        result = render_line("")
        assert result == [""]
    @pytest.mark.skip(reason="Requires real font/PIL setup")
    def test_uses_default_font(self):
        """Uses default font when none provided."""
        from engine.render import render_line
        with patch("engine.render.font") as mock_font:
            mock_font.return_value = MagicMock()
            mock_font.return_value.getbbox.return_value = (0, 0, 10, 10)
            render_line("test")
    def test_getbbox_returns_none(self):
        """Handles None bbox gracefully."""
        from engine.render import render_line
        with patch("engine.render.font") as mock_font:
            mock_font.return_value = MagicMock()
            mock_font.return_value.getbbox.return_value = None
            result = render_line("test")
            assert result == [""]
 class TestBigWrap:
    """Tests for big_wrap function."""
    def test_empty_string(self):
        """Empty string returns empty list."""
        from engine.render import big_wrap
        result = big_wrap("", 80)
        assert result == []
    @pytest.mark.skip(reason="Requires real font/PIL setup")
    def test_single_word_fits(self):
        """Single short word returns rendered."""
        from engine.render import big_wrap
        with patch("engine.render.font") as mock_font:
            mock_font.return_value = MagicMock()
            mock_font.return_value.getbbox.return_value = (0, 0, 10, 10)
            result = big_wrap("test", 80)
            assert len(result) > 0
--- a/tests/test_translate.py
+++ b/tests/test_translate.py
@@ -0,0 +1,115 @@
 """
 Tests for engine.translate module.
 """
 import json
 from unittest.mock import MagicMock, patch
 from engine.translate import (
    _translate_cached,
    detect_location_language,
    translate_headline,
 )
 def clear_translate_cache():
    """Clear the LRU cache between tests."""
    _translate_cached.cache_clear()
 class TestDetectLocationLanguage:
    """Tests for detect_location_language function."""
    def test_returns_none_for_unknown_location(self):
        """Returns None when no location pattern matches."""
        result = detect_location_language("Breaking news about technology")
        assert result is None
    def test_detects_berlin(self):
        """Detects Berlin location."""
        result = detect_location_language("Berlin police arrest protesters")
        assert result == "de"
    def test_detects_paris(self):
        """Detects Paris location."""
        result = detect_location_language("Paris fashion week begins")
        assert result == "fr"
    def test_detects_tokyo(self):
        """Detects Tokyo location."""
        result = detect_location_language("Tokyo stocks rise")
        assert result == "ja"
    def test_detects_berlin_again(self):
        """Detects Berlin location again."""
        result = detect_location_language("Berlin marathon set to begin")
        assert result == "de"
    def test_case_insensitive(self):
        """Detection is case insensitive."""
        result = detect_location_language("BERLIN SUMMER FESTIVAL")
        assert result == "de"
    def test_returns_first_match(self):
        """Returns first matching pattern."""
        result = detect_location_language("Berlin in Paris for the event")
        assert result == "de"
 class TestTranslateHeadline:
    """Tests for translate_headline function."""
    def test_returns_translated_text(self):
        """Returns translated text from cache."""
        clear_translate_cache()
        with patch("engine.translate.translate_headline") as mock_fn:
            mock_fn.return_value = "Translated title"
            from engine.translate import translate_headline as th
            result = th("Original title", "de")
            assert result == "Translated title"
    def test_uses_cached_result(self):
        """Translation uses LRU cache."""
        clear_translate_cache()
        result1 = translate_headline("Test unique", "es")
        result2 = translate_headline("Test unique", "es")
        assert result1 == result2
 class TestTranslateCached:
    """Tests for _translate_cached function."""
    def test_translation_network_error(self):
        """Network error returns original text."""
        clear_translate_cache()
        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
            mock_urlopen.side_effect = Exception("Network error")
            result = _translate_cached("Hello world", "de")
            assert result == "Hello world"
    def test_translation_invalid_json(self):
        """Invalid JSON returns original text."""
        clear_translate_cache()
        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
            mock_response = MagicMock()
            mock_response.read.return_value = b"invalid json"
            mock_urlopen.return_value = mock_response
            result = _translate_cached("Hello", "de")
            assert result == "Hello"
    def test_translation_empty_response(self):
        """Empty translation response returns original text."""
        clear_translate_cache()
        with patch("engine.translate.urllib.request.urlopen") as mock_urlopen:
            mock_response = MagicMock()
            mock_response.read.return_value = json.dumps([[[""], None, "de"], None])
            mock_urlopen.return_value = mock_response
            result = _translate_cached("Hello", "de")
            assert result == "Hello"
--- a/tests/test_websocket.py
+++ b/tests/test_websocket.py
@@ -0,0 +1,161 @@
 """
 Tests for engine.websocket_display module.
 """
 from unittest.mock import MagicMock, patch
 import pytest
 from engine.websocket_display import WebSocketDisplay
 class TestWebSocketDisplayImport:
    """Test that websocket module can be imported."""
    def test_import_does_not_error(self):
        """Module imports without error."""
        from engine import websocket_display
        assert websocket_display is not None
 class TestWebSocketDisplayInit:
    """Tests for WebSocketDisplay initialization."""
    def test_default_init(self):
        """Default initialization sets correct defaults."""
        with patch("engine.websocket_display.websockets", None):
            display = WebSocketDisplay()
            assert display.host == "0.0.0.0"
            assert display.port == 8765
            assert display.http_port == 8766
            assert display.width == 80
            assert display.height == 24
    def test_custom_init(self):
        """Custom initialization uses provided values."""
        with patch("engine.websocket_display.websockets", None):
            display = WebSocketDisplay(host="localhost", port=9000, http_port=9001)
            assert display.host == "localhost"
            assert display.port == 9000
            assert display.http_port == 9001
    def test_is_available_when_websockets_present(self):
        """is_available returns True when websockets is available."""
        pytest.importorskip("websockets")
        display = WebSocketDisplay()
        assert display.is_available() is True
    @pytest.mark.skipif(
        pytest.importorskip("websockets") is not None, reason="websockets is available"
    )
    def test_is_available_when_websockets_missing(self):
        """is_available returns False when websockets is not available."""
        display = WebSocketDisplay()
        assert display.is_available() is False
 class TestWebSocketDisplayProtocol:
    """Test that WebSocketDisplay satisfies Display protocol."""
    def test_websocket_display_is_display(self):
        """WebSocketDisplay satisfies Display protocol."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            assert hasattr(display, "init")
            assert hasattr(display, "show")
            assert hasattr(display, "clear")
            assert hasattr(display, "cleanup")
 class TestWebSocketDisplayMethods:
    """Tests for WebSocketDisplay methods."""
    def test_init_stores_dimensions(self):
        """init stores terminal dimensions."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            display.init(100, 40)
            assert display.width == 100
            assert display.height == 40
    def test_client_count_initially_zero(self):
        """client_count returns 0 when no clients connected."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            assert display.client_count() == 0
    def test_get_ws_port(self):
        """get_ws_port returns configured port."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay(port=9000)
            assert display.get_ws_port() == 9000
    def test_get_http_port(self):
        """get_http_port returns configured port."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay(http_port=9001)
            assert display.get_http_port() == 9001
    def test_frame_delay_defaults_to_zero(self):
        """get_frame_delay returns 0 by default."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            assert display.get_frame_delay() == 0.0
    def test_set_frame_delay(self):
        """set_frame_delay stores the value."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            display.set_frame_delay(0.05)
            assert display.get_frame_delay() == 0.05
 class TestWebSocketDisplayCallbacks:
    """Tests for WebSocketDisplay callback methods."""
    def test_set_client_connected_callback(self):
        """set_client_connected_callback stores callback."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            callback = MagicMock()
            display.set_client_connected_callback(callback)
            assert display._client_connected_callback is callback
    def test_set_client_disconnected_callback(self):
        """set_client_disconnected_callback stores callback."""
        with patch("engine.websocket_display.websockets", MagicMock()):
            display = WebSocketDisplay()
            callback = MagicMock()
            display.set_client_disconnected_callback(callback)
            assert display._client_disconnected_callback is callback
 class TestWebSocketDisplayUnavailable:
    """Tests when WebSocket support is unavailable."""
    @pytest.mark.skipif(
        pytest.importorskip("websockets") is not None, reason="websockets is available"
    )
    def test_start_server_noop_when_unavailable(self):
        """start_server does nothing when websockets unavailable."""
        display = WebSocketDisplay()
        display.start_server()
        assert display._server_thread is None
    @pytest.mark.skipif(
        pytest.importorskip("websockets") is not None, reason="websockets is available"
    )
    def test_start_http_server_noop_when_unavailable(self):
        """start_http_server does nothing when websockets unavailable."""
        display = WebSocketDisplay()
        display.start_http_server()
        assert display._http_thread is None
    @pytest.mark.skipif(
        pytest.importorskip("websockets") is not None, reason="websockets is available"
    )
    def test_show_noops_when_unavailable(self):
        """show does nothing when websockets unavailable."""
        display = WebSocketDisplay()
        display.show(["line1", "line2"])
Author	SHA1	Message	Date
David Gwilliam	d7b044ceae	feat(display): add configurable multi-backend display system	2026-03-15 21:17:16 -07:00
David Gwilliam	ac1306373d	feat(websocket): add WebSocket display backend for browser client	2026-03-15 20:54:03 -07:00
David Gwilliam	2650f7245e	merge: effects_plugins	2026-03-15 19:20:53 -07:00
David Gwilliam	b1f2b9d2be	feat(daemon): add display abstraction and daemon mode with C&C	2026-03-15 19:20:47 -07:00
David Gwilliam	c08a7d3cb0	feat(cmdline): add command-line interface for mainline control	2026-03-15 19:20:47 -07:00
David Gwilliam	d5a3edba97	feat(effects): add plugin architecture with performance monitoring	2026-03-15 19:20:47 -07:00
David Gwilliam	fb35458718	merge: testability_modularization	2026-03-15 19:20:43 -07:00