Merge origin/main into feat/color-pick

Resolved conflicts in tests/test_config.py by keeping TestActiveTheme tests.
Main branch has new architecture components (controller, events, layers, effects).
Color scheme feature preserved and compatible.

engine/config.py

@@ -1,25 +1,28 @@
 """
 Configuration constants, CLI flags, and glyph tables.
+Supports both global constants (backward compatible) and injected config for testing.
 """
 
 import sys
+from dataclasses import dataclass, field
 from pathlib import Path
 
 _REPO_ROOT = Path(__file__).resolve().parent.parent
 _FONT_EXTENSIONS = {".otf", ".ttf", ".ttc"}
 
 
-def _arg_value(flag):
+def _arg_value(flag, argv: list[str] | None = None):
     """Get value following a CLI flag, if present."""
-    if flag not in sys.argv:
+    argv = argv or sys.argv
+    if flag not in argv:
         return None
-    i = sys.argv.index(flag)
-    return sys.argv[i + 1] if i + 1 < len(sys.argv) else None
+    i = argv.index(flag)
+    return argv[i + 1] if i + 1 < len(argv) else None
 
 
-def _arg_int(flag, default):
+def _arg_int(flag, default, argv: list[str] | None = None):
     """Get int CLI argument with safe fallback."""
-    raw = _arg_value(flag)
+    raw = _arg_value(flag, argv)
     if raw is None:
         return default
     try:
@@ -53,6 +56,134 @@ def list_repo_font_files():
     return _list_font_files(FONT_DIR)
 
 
+def _get_platform_font_paths() -> dict[str, str]:
+    """Get platform-appropriate font paths for non-Latin scripts."""
+    import platform
+
+    system = platform.system()
+
+    if system == "Darwin":
+        return {
+            "zh-cn": "/System/Library/Fonts/STHeiti Medium.ttc",
+            "ja": "/System/Library/Fonts/ヒラギノ角ゴシック W9.ttc",
+            "ko": "/System/Library/Fonts/AppleSDGothicNeo.ttc",
+            "ru": "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "uk": "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "el": "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "he": "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "ar": "/System/Library/Fonts/GeezaPro.ttc",
+            "fa": "/System/Library/Fonts/GeezaPro.ttc",
+            "hi": "/System/Library/Fonts/Kohinoor.ttc",
+            "th": "/System/Library/Fonts/ThonburiUI.ttc",
+        }
+    elif system == "Linux":
+        return {
+            "zh-cn": "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+            "ja": "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+            "ko": "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+            "ru": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "uk": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "el": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "he": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "ar": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "fa": "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "hi": "/usr/share/fonts/truetype/noto/NotoSansDevanagari-Regular.ttf",
+            "th": "/usr/share/fonts/truetype/noto/NotoSansThai-Regular.ttf",
+        }
+    else:
+        return {}
+
+
+@dataclass(frozen=True)
+class Config:
+    """Immutable configuration container for injected config."""
+
+    headline_limit: int = 1000
+    feed_timeout: int = 10
+    mic_threshold_db: int = 50
+    mode: str = "news"
+    firehose: bool = False
+
+    ntfy_topic: str = "https://ntfy.sh/klubhaus_terminal_mainline/json"
+    ntfy_reconnect_delay: int = 5
+    message_display_secs: int = 30
+
+    font_dir: str = "fonts"
+    font_path: str = ""
+    font_index: int = 0
+    font_picker: bool = True
+    font_sz: int = 60
+    render_h: int = 8
+
+    ssaa: int = 4
+
+    scroll_dur: float = 5.625
+    frame_dt: float = 0.05
+    firehose_h: int = 12
+    grad_speed: float = 0.08
+
+    glitch_glyphs: str = "░▒▓█▌▐╌╍╎╏┃┆┇┊┋"
+    kata_glyphs: str = "ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ"
+
+    script_fonts: dict[str, str] = field(default_factory=_get_platform_font_paths)
+
+    @classmethod
+    def from_args(cls, argv: list[str] | None = None) -> "Config":
+        """Create Config from CLI arguments (or custom argv for testing)."""
+        argv = argv or sys.argv
+
+        font_dir = _resolve_font_path(_arg_value("--font-dir", argv) or "fonts")
+        font_file_arg = _arg_value("--font-file", argv)
+        font_files = _list_font_files(font_dir)
+        font_path = (
+            _resolve_font_path(font_file_arg)
+            if font_file_arg
+            else (font_files[0] if font_files else "")
+        )
+
+        return cls(
+            headline_limit=1000,
+            feed_timeout=10,
+            mic_threshold_db=50,
+            mode="poetry" if "--poetry" in argv or "-p" in argv else "news",
+            firehose="--firehose" in argv,
+            ntfy_topic="https://ntfy.sh/klubhaus_terminal_mainline/json",
+            ntfy_reconnect_delay=5,
+            message_display_secs=30,
+            font_dir=font_dir,
+            font_path=font_path,
+            font_index=max(0, _arg_int("--font-index", 0, argv)),
+            font_picker="--no-font-picker" not in argv,
+            font_sz=60,
+            render_h=8,
+            ssaa=4,
+            scroll_dur=5.625,
+            frame_dt=0.05,
+            firehose_h=12,
+            grad_speed=0.08,
+            glitch_glyphs="░▒▓█▌▐╌╍╎╏┃┆┇┊┋",
+            kata_glyphs="ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍ",
+            script_fonts=_get_platform_font_paths(),
+        )
+
+
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get the global config instance (lazy-loaded)."""
+    global _config
+    if _config is None:
+        _config = Config.from_args()
+    return _config
+
+
+def set_config(config: Config) -> None:
+    """Set the global config instance (for testing)."""
+    global _config
+    _config = config
+
+
 # ─── RUNTIME ──────────────────────────────────────────────
 HEADLINE_LIMIT = 1000
 FEED_TIMEOUT = 10

engine/controller.py

@@ -0,0 +1,68 @@
+"""
+Stream controller - manages input sources and orchestrates the render stream.
+"""
+
+from engine.config import Config, get_config
+from engine.eventbus import EventBus
+from engine.events import EventType, StreamEvent
+from engine.mic import MicMonitor
+from engine.ntfy import NtfyPoller
+from engine.scroll import stream
+
+
+class StreamController:
+    """Controls the stream lifecycle - initializes sources and runs the stream."""
+
+    def __init__(self, config: Config | None = None, event_bus: EventBus | None = None):
+        self.config = config or get_config()
+        self.event_bus = event_bus
+        self.mic: MicMonitor | None = None
+        self.ntfy: NtfyPoller | None = None
+
+    def initialize_sources(self) -> tuple[bool, bool]:
+        """Initialize microphone and ntfy sources.
+
+        Returns:
+            (mic_ok, ntfy_ok) - success status for each source
+        """
+        self.mic = MicMonitor(threshold_db=self.config.mic_threshold_db)
+        mic_ok = self.mic.start() if self.mic.available else False
+
+        self.ntfy = NtfyPoller(
+            self.config.ntfy_topic,
+            reconnect_delay=self.config.ntfy_reconnect_delay,
+            display_secs=self.config.message_display_secs,
+        )
+        ntfy_ok = self.ntfy.start()
+
+        return bool(mic_ok), ntfy_ok
+
+    def run(self, items: list) -> None:
+        """Run the stream with initialized sources."""
+        if self.mic is None or self.ntfy is None:
+            self.initialize_sources()
+
+        if self.event_bus:
+            self.event_bus.publish(
+                EventType.STREAM_START,
+                StreamEvent(
+                    event_type=EventType.STREAM_START,
+                    headline_count=len(items),
+                ),
+            )
+
+        stream(items, self.ntfy, self.mic)
+
+        if self.event_bus:
+            self.event_bus.publish(
+                EventType.STREAM_END,
+                StreamEvent(
+                    event_type=EventType.STREAM_END,
+                    headline_count=len(items),
+                ),
+            )
+
+    def cleanup(self) -> None:
+        """Clean up resources."""
+        if self.mic:
+            self.mic.stop()

engine/display.py

@@ -0,0 +1,102 @@
+"""
+Display output abstraction - allows swapping output backends.
+
+Protocol:
+    - init(width, height): Initialize display with terminal dimensions
+    - show(buffer): Render buffer (list of strings) to display
+    - clear(): Clear the display
+    - cleanup(): Shutdown display
+"""
+
+import time
+from typing import Protocol
+
+
+class Display(Protocol):
+    """Protocol for display backends."""
+
+    def init(self, width: int, height: int) -> None:
+        """Initialize display with dimensions."""
+        ...
+
+    def show(self, buffer: list[str]) -> None:
+        """Show buffer on display."""
+        ...
+
+    def clear(self) -> None:
+        """Clear display."""
+        ...
+
+    def cleanup(self) -> None:
+        """Shutdown display."""
+        ...
+
+
+def get_monitor():
+    """Get the performance monitor."""
+    try:
+        from engine.effects.performance import get_monitor as _get_monitor
+
+        return _get_monitor()
+    except Exception:
+        return None
+
+
+class TerminalDisplay:
+    """ANSI terminal display backend."""
+
+    def __init__(self):
+        self.width = 80
+        self.height = 24
+
+    def init(self, width: int, height: int) -> None:
+        from engine.terminal import CURSOR_OFF
+
+        self.width = width
+        self.height = height
+        print(CURSOR_OFF, end="", flush=True)
+
+    def show(self, buffer: list[str]) -> None:
+        import sys
+
+        t0 = time.perf_counter()
+        sys.stdout.buffer.write("".join(buffer).encode())
+        sys.stdout.flush()
+        elapsed_ms = (time.perf_counter() - t0) * 1000
+
+        monitor = get_monitor()
+        if monitor:
+            chars_in = sum(len(line) for line in buffer)
+            monitor.record_effect("terminal_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        from engine.terminal import CLR
+
+        print(CLR, end="", flush=True)
+
+    def cleanup(self) -> None:
+        from engine.terminal import CURSOR_ON
+
+        print(CURSOR_ON, end="", flush=True)
+
+
+class NullDisplay:
+    """Headless/null display - discards all output."""
+
+    def init(self, width: int, height: int) -> None:
+        self.width = width
+        self.height = height
+
+    def show(self, buffer: list[str]) -> None:
+        monitor = get_monitor()
+        if monitor:
+            t0 = time.perf_counter()
+            chars_in = sum(len(line) for line in buffer)
+            elapsed_ms = (time.perf_counter() - t0) * 1000
+            monitor.record_effect("null_display", elapsed_ms, chars_in, chars_in)
+
+    def clear(self) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass

engine/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",
+]

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

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)

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

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

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)

engine/emitters.py

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

engine/eventbus.py

@@ -0,0 +1,72 @@
+"""
+Event bus - pub/sub messaging for decoupled component communication.
+"""
+
+import threading
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+from engine.events import EventType
+
+
+class EventBus:
+    """Thread-safe event bus for publish-subscribe messaging."""
+
+    def __init__(self):
+        self._subscribers: dict[EventType, list[Callable[[Any], None]]] = defaultdict(
+            list
+        )
+        self._lock = threading.Lock()
+
+    def subscribe(self, event_type: EventType, callback: Callable[[Any], None]) -> None:
+        """Register a callback for a specific event type."""
+        with self._lock:
+            self._subscribers[event_type].append(callback)
+
+    def unsubscribe(
+        self, event_type: EventType, callback: Callable[[Any], None]
+    ) -> None:
+        """Remove a callback for a specific event type."""
+        with self._lock:
+            if callback in self._subscribers[event_type]:
+                self._subscribers[event_type].remove(callback)
+
+    def publish(self, event_type: EventType, event: Any = None) -> None:
+        """Publish an event to all subscribers."""
+        with self._lock:
+            callbacks = list(self._subscribers.get(event_type, []))
+        for callback in callbacks:
+            try:
+                callback(event)
+            except Exception:
+                pass
+
+    def clear(self) -> None:
+        """Remove all subscribers."""
+        with self._lock:
+            self._subscribers.clear()
+
+    def subscriber_count(self, event_type: EventType | None = None) -> int:
+        """Get subscriber count for an event type, or total if None."""
+        with self._lock:
+            if event_type is None:
+                return sum(len(cb) for cb in self._subscribers.values())
+            return len(self._subscribers.get(event_type, []))
+
+
+_event_bus: EventBus | None = None
+
+
+def get_event_bus() -> EventBus:
+    """Get the global event bus instance."""
+    global _event_bus
+    if _event_bus is None:
+        _event_bus = EventBus()
+    return _event_bus
+
+
+def set_event_bus(bus: EventBus) -> None:
+    """Set the global event bus instance (for testing)."""
+    global _event_bus
+    _event_bus = bus

engine/events.py

@@ -0,0 +1,67 @@
+"""
+Event types for the mainline application.
+Defines the core events that flow through the system.
+These types support a future migration to an event-driven architecture.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum, auto
+
+
+class EventType(Enum):
+    """Core event types in the mainline application."""
+
+    NEW_HEADLINE = auto()
+    FRAME_TICK = auto()
+    MIC_LEVEL = auto()
+    NTFY_MESSAGE = auto()
+    STREAM_START = auto()
+    STREAM_END = auto()
+
+
+@dataclass
+class HeadlineEvent:
+    """Event emitted when a new headline is ready for display."""
+
+    title: str
+    source: str
+    timestamp: str
+    language: str | None = None
+
+
+@dataclass
+class FrameTickEvent:
+    """Event emitted on each render frame."""
+
+    frame_number: int
+    timestamp: datetime
+    delta_seconds: float
+
+
+@dataclass
+class MicLevelEvent:
+    """Event emitted when microphone level changes significantly."""
+
+    db_level: float
+    excess_above_threshold: float
+    timestamp: datetime
+
+
+@dataclass
+class NtfyMessageEvent:
+    """Event emitted when an ntfy message is received."""
+
+    title: str
+    body: str
+    message_id: str | None = None
+    timestamp: datetime | None = None
+
+
+@dataclass
+class StreamEvent:
+    """Event emitted when stream starts or ends."""
+
+    event_type: EventType
+    headline_count: int = 0
+    timestamp: datetime | None = None

engine/fetch.py

@@ -8,6 +8,7 @@ import pathlib
 import re
 import urllib.request
 from datetime import datetime
+from typing import Any
 
 import feedparser
 
@@ -16,9 +17,13 @@ from engine.filter import skip, strip_tags
 from engine.sources import FEEDS, POETRY_SOURCES
 from engine.terminal import boot_ln
 
+# Type alias for headline items
+HeadlineTuple = tuple[str, str, str]
+
 
 # ─── SINGLE FEED ──────────────────────────────────────────
-def fetch_feed(url):
+def fetch_feed(url: str) -> Any | None:
+    """Fetch and parse a single RSS feed URL."""
     try:
         req = urllib.request.Request(url, headers={"User-Agent": "mainline/0.1"})
         resp = urllib.request.urlopen(req, timeout=config.FEED_TIMEOUT)
@@ -28,8 +33,9 @@ def fetch_feed(url):
 
 
 # ─── ALL RSS FEEDS ────────────────────────────────────────
-def fetch_all():
-    items = []
+def fetch_all() -> tuple[list[HeadlineTuple], int, int]:
+    """Fetch all RSS feeds and return items, linked count, failed count."""
+    items: list[HeadlineTuple] = []
     linked = failed = 0
     for src, url in FEEDS.items():
         feed = fetch_feed(url)
@@ -59,7 +65,7 @@ def fetch_all():
 
 
 # ─── PROJECT GUTENBERG ────────────────────────────────────
-def _fetch_gutenberg(url, label):
+def _fetch_gutenberg(url: str, label: str) -> list[HeadlineTuple]:
     """Download and parse stanzas/passages from a Project Gutenberg text."""
     try:
         req = urllib.request.Request(url, headers={"User-Agent": "mainline/0.1"})

engine/frame.py

@@ -0,0 +1,57 @@
+"""
+Frame timing utilities — FPS control and precise timing.
+"""
+
+import time
+
+
+class FrameTimer:
+    """Frame timer for consistent render loop timing."""
+
+    def __init__(self, target_frame_dt: float = 0.05):
+        self.target_frame_dt = target_frame_dt
+        self._frame_count = 0
+        self._start_time = time.monotonic()
+        self._last_frame_time = self._start_time
+
+    @property
+    def fps(self) -> float:
+        """Current FPS based on elapsed frames."""
+        elapsed = time.monotonic() - self._start_time
+        if elapsed > 0:
+            return self._frame_count / elapsed
+        return 0.0
+
+    def sleep_until_next_frame(self) -> float:
+        """Sleep to maintain target frame rate. Returns actual elapsed time."""
+        now = time.monotonic()
+        elapsed = now - self._last_frame_time
+        self._last_frame_time = now
+        self._frame_count += 1
+
+        sleep_time = max(0, self.target_frame_dt - elapsed)
+        if sleep_time > 0:
+            time.sleep(sleep_time)
+        return elapsed
+
+    def reset(self) -> None:
+        """Reset frame counter and start time."""
+        self._frame_count = 0
+        self._start_time = time.monotonic()
+        self._last_frame_time = self._start_time
+
+
+def calculate_scroll_step(
+    scroll_dur: float, view_height: int, padding: int = 15
+) -> float:
+    """Calculate scroll step interval for smooth scrolling.
+
+    Args:
+        scroll_dur: Duration in seconds for one headline to scroll through view
+        view_height: Terminal height in rows
+        padding: Extra rows for off-screen content
+
+    Returns:
+        Time in seconds between scroll steps
+    """
+    return scroll_dur / (view_height + padding) * 2

engine/layers.py

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

engine/mic.py

@@ -4,6 +4,8 @@ Gracefully degrades if sounddevice/numpy are unavailable.
 """
 
 import atexit
+from collections.abc import Callable
+from datetime import datetime
 
 try:
     import numpy as _np
@@ -14,6 +16,9 @@ except Exception:
     _HAS_MIC = False
 
 
+from engine.events import MicLevelEvent
+
+
 class MicMonitor:
     """Background mic stream that exposes current RMS dB level."""
 
@@ -21,6 +26,7 @@ class MicMonitor:
         self.threshold_db = threshold_db
         self._db = -99.0
         self._stream = None
+        self._subscribers: list[Callable[[MicLevelEvent], None]] = []
 
     @property
     def available(self):
@@ -37,6 +43,23 @@ class MicMonitor:
         """dB above threshold (clamped to 0)."""
         return max(0.0, self._db - self.threshold_db)
 
+    def subscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
+        """Register a callback to be called when mic level changes."""
+        self._subscribers.append(callback)
+
+    def unsubscribe(self, callback: Callable[[MicLevelEvent], None]) -> None:
+        """Remove a registered callback."""
+        if callback in self._subscribers:
+            self._subscribers.remove(callback)
+
+    def _emit(self, event: MicLevelEvent) -> None:
+        """Emit an event to all subscribers."""
+        for cb in self._subscribers:
+            try:
+                cb(event)
+            except Exception:
+                pass
+
     def start(self):
         """Start background mic stream. Returns True on success, False/None otherwise."""
         if not _HAS_MIC:
@@ -45,6 +68,13 @@ class MicMonitor:
         def _cb(indata, frames, t, status):
             rms = float(_np.sqrt(_np.mean(indata**2)))
             self._db = 20 * _np.log10(rms) if rms > 0 else -99.0
+            if self._subscribers:
+                event = MicLevelEvent(
+                    db_level=self._db,
+                    excess_above_threshold=max(0.0, self._db - self.threshold_db),
+                    timestamp=datetime.now(),
+                )
+                self._emit(event)
 
         try:
             self._stream = _sd.InputStream(

engine/ntfy.py

@@ -16,8 +16,12 @@ import json
 import threading
 import time
 import urllib.request
+from collections.abc import Callable
+from datetime import datetime
 from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
+from engine.events import NtfyMessageEvent
+
 
 class NtfyPoller:
     """SSE stream listener for ntfy.sh topics. Messages arrive in ~1s (network RTT)."""
@@ -28,6 +32,24 @@ class NtfyPoller:
         self.display_secs = display_secs
         self._message = None  # (title, body, monotonic_timestamp) or None
         self._lock = threading.Lock()
+        self._subscribers: list[Callable[[NtfyMessageEvent], None]] = []
+
+    def subscribe(self, callback: Callable[[NtfyMessageEvent], None]) -> None:
+        """Register a callback to be called when a message is received."""
+        self._subscribers.append(callback)
+
+    def unsubscribe(self, callback: Callable[[NtfyMessageEvent], None]) -> None:
+        """Remove a registered callback."""
+        if callback in self._subscribers:
+            self._subscribers.remove(callback)
+
+    def _emit(self, event: NtfyMessageEvent) -> None:
+        """Emit an event to all subscribers."""
+        for cb in self._subscribers:
+            try:
+                cb(event)
+            except Exception:
+                pass
 
     def start(self):
         """Start background stream thread. Returns True."""
@@ -88,6 +110,13 @@ class NtfyPoller:
                                 data.get("message", ""),
                                 time.monotonic(),
                             )
+                        event = NtfyMessageEvent(
+                            title=data.get("title", ""),
+                            body=data.get("message", ""),
+                            message_id=data.get("id"),
+                            timestamp=datetime.now(),
+                        )
+                        self._emit(event)
             except Exception:
                 pass
             time.sleep(self.reconnect_delay)

engine/scroll.py

@@ -1,148 +1,92 @@
 """
 Render engine — ticker content, scroll motion, message panel, and firehose overlay.
-Depends on: config, terminal, render, effects, ntfy, mic.
+Orchestrates viewport, frame timing, and layers.
 """
 
 import random
-import re
-import sys
 import time
-from datetime import datetime
 
 from engine import config
-from engine.effects import (
-    fade_line,
-    firehose_line,
-    glitch_bar,
-    next_headline,
-    noise,
-    vis_trunc,
+from engine.display import (
+    Display,
+    TerminalDisplay,
 )
-from engine.render import big_wrap, lr_gradient, make_block, msg_gradient
-from engine.terminal import CLR, RST, W_COOL, th, tw
+from engine.display import (
+    get_monitor as _get_display_monitor,
+)
+from engine.frame import calculate_scroll_step
+from engine.layers import (
+    apply_glitch,
+    process_effects,
+    render_firehose,
+    render_message_overlay,
+    render_ticker_zone,
+)
+from engine.viewport import th, tw
+
+USE_EFFECT_CHAIN = True
 
 
-def stream(items, ntfy_poller, mic_monitor):
+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  # reserve fixed firehose strip at bottom
-    GAP = 3  # blank rows between headlines
-    scroll_step_interval = config.SCROLL_DUR / (ticker_view_h + 15) * 2
+    ticker_view_h = h - fh
+    GAP = 3
+    scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, ticker_view_h)
 
-    # Taxonomy:
-    # - message: centered ntfy overlay panel
-    # - ticker: large headline text content
-    # - scroll: upward camera motion applied to ticker content
-    # - firehose: fixed carriage-return style strip pinned at bottom
-    # Active ticker blocks: (content_rows, color, canvas_y, meta_idx)
     active = []
-    scroll_cam = 0  # viewport top in virtual canvas coords
-    ticker_next_y = (
-        ticker_view_h  # canvas-y where next block starts (off-screen bottom)
-    )
+    scroll_cam = 0
+    ticker_next_y = ticker_view_h
     noise_cache = {}
     scroll_motion_accum = 0.0
+    msg_cache = (None, None)
+    frame_number = 0
 
-    def _noise_at(cy):
-        if cy not in noise_cache:
-            noise_cache[cy] = noise(w) if random.random() < 0.15 else None
-        return noise_cache[cy]
+    while True:
+        if queued >= config.HEADLINE_LIMIT and not active:
+            break
 
-    # Message color: bright cyan/white — distinct from headline greens
-    MSG_META = "\033[38;5;245m"  # cool grey
-    MSG_BORDER = "\033[2;38;5;37m"  # dim teal
-    _msg_cache = (None, None)  # (cache_key, rendered_rows)
-
-    while queued < config.HEADLINE_LIMIT or active:
         t0 = time.monotonic()
         w, h = tw(), th()
         fh = config.FIREHOSE_H if config.FIREHOSE else 0
         ticker_view_h = h - fh
+        scroll_step_interval = calculate_scroll_step(config.SCROLL_DUR, ticker_view_h)
 
-        # ── Check for ntfy message ────────────────────────
-        msg_h = 0
-        msg_overlay = []
         msg = ntfy_poller.get_active_message()
+        msg_overlay, msg_cache = render_message_overlay(msg, w, h, msg_cache)
 
         buf = []
-        if msg is not None:
-            m_title, m_body, m_ts = msg
-            # ── Message overlay: centered in the viewport ──
-            display_text = m_body or m_title or "(empty)"
-            display_text = re.sub(r"\s+", " ", display_text.upper())
-            cache_key = (display_text, w)
-            if _msg_cache[0] != cache_key:
-                msg_rows = big_wrap(display_text, w - 4)
-                _msg_cache = (cache_key, msg_rows)
-            else:
-                msg_rows = _msg_cache[1]
-            msg_rows = msg_gradient(
-                msg_rows, (time.monotonic() * config.GRAD_SPEED) % 1.0
-            )
-            # Layout: rendered text + meta + border
-            elapsed_s = int(time.monotonic() - m_ts)
-            remaining = max(0, config.MESSAGE_DISPLAY_SECS - elapsed_s)
-            ts_str = datetime.now().strftime("%H:%M:%S")
-            panel_h = len(msg_rows) + 2  # meta + border
-            panel_top = max(0, (h - panel_h) // 2)
-            row_idx = 0
-            for mr in msg_rows:
-                ln = vis_trunc(mr, w)
-                msg_overlay.append(
-                    f"\033[{panel_top + row_idx + 1};1H  {ln}{RST}\033[K"
-                )
-                row_idx += 1
-            # Meta line: title (if distinct) + source + countdown
-            meta_parts = []
-            if m_title and m_title != m_body:
-                meta_parts.append(m_title)
-            meta_parts.append(f"ntfy \u00b7 {ts_str} \u00b7 {remaining}s")
-            meta = (
-                "  " + " \u00b7 ".join(meta_parts)
-                if len(meta_parts) > 1
-                else "  " + meta_parts[0]
-            )
-            msg_overlay.append(
-                f"\033[{panel_top + row_idx + 1};1H{MSG_META}{meta}{RST}\033[K"
-            )
-            row_idx += 1
-            # Border — constant boundary under message panel
-            bar = "\u2500" * (w - 4)
-            msg_overlay.append(
-                f"\033[{panel_top + row_idx + 1};1H  {MSG_BORDER}{bar}{RST}\033[K"
-            )
+        ticker_h = ticker_view_h
 
-        # Ticker draws above the fixed firehose strip; message is a centered overlay.
-        ticker_h = ticker_view_h - msg_h
-
-        # ── Ticker content + scroll motion (always runs) ──
         scroll_motion_accum += config.FRAME_DT
         while scroll_motion_accum >= scroll_step_interval:
             scroll_motion_accum -= scroll_step_interval
             scroll_cam += 1
 
-            # Enqueue new headlines when room at the bottom
             while (
                 ticker_next_y < scroll_cam + ticker_view_h + 10
                 and queued < config.HEADLINE_LIMIT
             ):
+                from engine.effects import next_headline
+                from engine.render import make_block
+
                 t, src, ts = next_headline(pool, items, seen)
                 ticker_content, hc, midx = make_block(t, src, ts, w)
                 active.append((ticker_content, hc, ticker_next_y, midx))
                 ticker_next_y += len(ticker_content) + GAP
                 queued += 1
 
-            # Prune off-screen blocks and stale noise
             active = [
                 (c, hc, by, mi) for c, hc, by, mi in active if by + len(c) > scroll_cam
             ]
@@ -150,71 +94,48 @@ def stream(items, ntfy_poller, mic_monitor):
                 if k < scroll_cam:
                     del noise_cache[k]
 
-        # Draw ticker zone (above fixed firehose strip)
-        top_zone = max(1, int(ticker_h * 0.25))
-        bot_zone = max(1, int(ticker_h * 0.10))
         grad_offset = (time.monotonic() * config.GRAD_SPEED) % 1.0
-        ticker_buf_start = len(buf)  # track where ticker rows start in buf
-        for r in range(ticker_h):
-            scr_row = r + 1  # 1-indexed ANSI screen row
-            cy = scroll_cam + r
-            top_f = min(1.0, r / top_zone) if top_zone > 0 else 1.0
-            bot_f = min(1.0, (ticker_h - 1 - r) / bot_zone) if bot_zone > 0 else 1.0
-            row_fade = min(top_f, bot_f)
-            drawn = False
-            for content, hc, by, midx in active:
-                cr = cy - by
-                if 0 <= cr < len(content):
-                    raw = content[cr]
-                    if cr != midx:
-                        colored = lr_gradient([raw], grad_offset)[0]
-                    else:
-                        colored = raw
-                    ln = vis_trunc(colored, w)
-                    if row_fade < 1.0:
-                        ln = fade_line(ln, row_fade)
-                    if cr == midx:
-                        buf.append(f"\033[{scr_row};1H{W_COOL}{ln}{RST}\033[K")
-                    elif ln.strip():
-                        buf.append(f"\033[{scr_row};1H{ln}{RST}\033[K")
-                    else:
-                        buf.append(f"\033[{scr_row};1H\033[K")
-                    drawn = True
-                    break
-            if not drawn:
-                n = _noise_at(cy)
-                if row_fade < 1.0 and n:
-                    n = fade_line(n, row_fade)
-                if n:
-                    buf.append(f"\033[{scr_row};1H{n}")
-                else:
-                    buf.append(f"\033[{scr_row};1H\033[K")
+        ticker_buf_start = len(buf)
+
+        ticker_buf, noise_cache = render_ticker_zone(
+            active, scroll_cam, ticker_h, w, noise_cache, grad_offset
+        )
+        buf.extend(ticker_buf)
 
-        # Glitch — base rate + mic-reactive spikes (ticker zone only)
         mic_excess = mic_monitor.excess
-        glitch_prob = 0.32 + min(0.9, mic_excess * 0.16)
-        n_hits = 4 + int(mic_excess / 2)
-        ticker_buf_len = len(buf) - ticker_buf_start
-        if random.random() < glitch_prob and ticker_buf_len > 0:
-            for _ in range(min(n_hits, ticker_buf_len)):
-                gi = random.randint(0, ticker_buf_len - 1)
-                scr_row = gi + 1
-                buf[ticker_buf_start + gi] = f"\033[{scr_row};1H{glitch_bar(w)}"
+        render_start = time.perf_counter()
+
+        if USE_EFFECT_CHAIN:
+            buf = process_effects(
+                buf,
+                w,
+                h,
+                scroll_cam,
+                ticker_h,
+                mic_excess,
+                grad_offset,
+                frame_number,
+                msg is not None,
+                items,
+            )
+        else:
+            buf = apply_glitch(buf, ticker_buf_start, mic_excess, w)
+            firehose_buf = render_firehose(items, w, fh, h)
+            buf.extend(firehose_buf)
 
-        if config.FIREHOSE and fh > 0:
-            for fr in range(fh):
-                scr_row = h - fh + fr + 1
-                fline = firehose_line(items, w)
-                buf.append(f"\033[{scr_row};1H{fline}\033[K")
         if msg_overlay:
             buf.extend(msg_overlay)
 
-        sys.stdout.buffer.write("".join(buf).encode())
-        sys.stdout.flush()
+        render_elapsed = (time.perf_counter() - render_start) * 1000
+        monitor = _get_display_monitor()
+        if monitor:
+            chars = sum(len(line) for line in buf)
+            monitor.record_effect("render", render_elapsed, chars, chars)
+
+        display.show(buf)
 
-        # Precise frame timing
         elapsed = time.monotonic() - t0
         time.sleep(max(0, config.FRAME_DT - elapsed))
+        frame_number += 1
 
-    sys.stdout.write(CLR)
-    sys.stdout.flush()
+    display.cleanup()

engine/translate.py

@@ -7,26 +7,16 @@ import json
 import re
 import urllib.parse
 import urllib.request
+from functools import lru_cache
 
 from engine.sources import LOCATION_LANGS
 
-_TRANSLATE_CACHE = {}
+TRANSLATE_CACHE_SIZE = 500
 
 
-def detect_location_language(title):
-    """Detect if headline mentions a location, return target language."""
-    title_lower = title.lower()
-    for pattern, lang in LOCATION_LANGS.items():
-        if re.search(pattern, title_lower):
-            return lang
-    return None
-
-
-def translate_headline(title, target_lang):
-    """Translate headline via Google Translate API (zero dependencies)."""
-    key = (title, target_lang)
-    if key in _TRANSLATE_CACHE:
-        return _TRANSLATE_CACHE[key]
+@lru_cache(maxsize=TRANSLATE_CACHE_SIZE)
+def _translate_cached(title: str, target_lang: str) -> str:
+    """Cached translation implementation."""
     try:
         q = urllib.parse.quote(title)
         url = (
@@ -39,5 +29,18 @@ def translate_headline(title, target_lang):
         result = "".join(p[0] for p in data[0] if p[0]) or title
     except Exception:
         result = title
-    _TRANSLATE_CACHE[key] = result
     return result
+
+
+def detect_location_language(title):
+    """Detect if headline mentions a location, return target language."""
+    title_lower = title.lower()
+    for pattern, lang in LOCATION_LANGS.items():
+        if re.search(pattern, title_lower):
+            return lang
+    return None
+
+
+def translate_headline(title: str, target_lang: str) -> str:
+    """Translate headline via Google Translate API (zero dependencies)."""
+    return _translate_cached(title, target_lang)

engine/types.py

@@ -0,0 +1,60 @@
+"""
+Shared dataclasses for the mainline application.
+Provides named types for tuple returns across modules.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class HeadlineItem:
+    """A single headline item: title, source, and timestamp."""
+
+    title: str
+    source: str
+    timestamp: str
+
+    def to_tuple(self) -> tuple[str, str, str]:
+        """Convert to tuple for backward compatibility."""
+        return (self.title, self.source, self.timestamp)
+
+    @classmethod
+    def from_tuple(cls, t: tuple[str, str, str]) -> "HeadlineItem":
+        """Create from tuple for backward compatibility."""
+        return cls(title=t[0], source=t[1], timestamp=t[2])
+
+
+def items_to_tuples(items: list[HeadlineItem]) -> list[tuple[str, str, str]]:
+    """Convert list of HeadlineItem to list of tuples."""
+    return [item.to_tuple() for item in items]
+
+
+def tuples_to_items(tuples: list[tuple[str, str, str]]) -> list[HeadlineItem]:
+    """Convert list of tuples to list of HeadlineItem."""
+    return [HeadlineItem.from_tuple(t) for t in tuples]
+
+
+@dataclass
+class FetchResult:
+    """Result from fetch_all() or fetch_poetry()."""
+
+    items: list[HeadlineItem]
+    linked: int
+    failed: int
+
+    def to_legacy_tuple(self) -> tuple[list[tuple], int, int]:
+        """Convert to legacy tuple format for backward compatibility."""
+        return ([item.to_tuple() for item in self.items], self.linked, self.failed)
+
+
+@dataclass
+class Block:
+    """Rendered headline block from make_block()."""
+
+    content: list[str]
+    color: str
+    meta_row_index: int
+
+    def to_legacy_tuple(self) -> tuple[list[str], str, int]:
+        """Convert to legacy tuple format for backward compatibility."""
+        return (self.content, self.color, self.meta_row_index)

engine/viewport.py

@@ -0,0 +1,37 @@
+"""
+Viewport utilities — terminal dimensions and ANSI positioning helpers.
+No internal dependencies.
+"""
+
+import os
+
+
+def tw() -> int:
+    """Get terminal width (columns)."""
+    try:
+        return os.get_terminal_size().columns
+    except Exception:
+        return 80
+
+
+def th() -> int:
+    """Get terminal height (lines)."""
+    try:
+        return os.get_terminal_size().lines
+    except Exception:
+        return 24
+
+
+def move_to(row: int, col: int = 1) -> str:
+    """Generate ANSI escape to move cursor to row, col (1-indexed)."""
+    return f"\033[{row};{col}H"
+
+
+def clear_screen() -> str:
+    """Clear screen and move cursor to home."""
+    return "\033[2J\033[H"
+
+
+def clear_line() -> str:
+    """Clear current line."""
+    return "\033[K"