feat(effects): add plugin architecture for visual effects

- Extract effects as fully decoupled plugins in engine/effects/
- Add EffectConfig, EffectContext dataclasses and EffectPlugin protocol
- Add EffectRegistry for plugin discovery and management
- Add EffectChain for ordered pipeline execution
- Move built-in effects to effects_plugins/ directory
- Add interactive effects config picker during startup
- Add NTFY command handler for /effects commands
- Add tests for effects system (24 new tests)
- Update AGENTS.md with effects plugin documentation
- Add conventional commits section to AGENTS.md

chore: add coverage.xml to .gitignore

engine/effects/__init__.py

@@ -0,0 +1,38 @@
+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.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",
+    "handle_effects_command",
+    "show_effects_menu",
+    "fade_line",
+    "firehose_line",
+    "glitch_bar",
+    "noise",
+    "next_headline",
+    "vis_trunc",
+]

engine/effects/chain.py

@@ -0,0 +1,47 @@
+from engine.effects.registry import EffectRegistry
+from engine.effects.types import EffectContext
+
+
+class EffectChain:
+    def __init__(self, registry: EffectRegistry):
+        self._registry = registry
+        self._order: list[str] = []
+
+    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]:
+        result = list(buf)
+        for name in self._order:
+            plugin = self._registry.get(name)
+            if plugin and plugin.config.enabled:
+                try:
+                    result = plugin.process(result, ctx)
+                except Exception:
+                    plugin.config.enabled = False
+        return result

engine/effects/controller.py

@@ -0,0 +1,102 @@
+from engine.effects.registry import get_registry
+
+
+def _get_effect_chain():
+    from engine.layers import get_effect_chain as _chain
+
+    return _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
+    """
+    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 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"
+
+    if action == "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"
+
+    return f"Unknown action: {action}"
+
+
+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/legacy.py

@@ -0,0 +1,134 @@
+"""
+Visual effects: noise, glitch, fade, ANSI-aware truncation, firehose, headline pool.
+Depends on: config, terminal, sources.
+"""
+
+import random
+from datetime import datetime
+
+from engine import config
+from engine.sources import FEEDS, POETRY_SOURCES
+from engine.terminal import C_DIM, DIM, G_DIM, G_LO, RST, W_GHOST
+
+
+def noise(w):
+    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 glitch_bar(w):
+    c = random.choice(["░", "▒", "─", "╌"])
+    n = random.randint(3, w // 2)
+    o = random.randint(0, w - n)
+    return " " * o + f"{G_LO}{DIM}" + c * n + RST
+
+
+def fade_line(s, fade):
+    """Dissolve a rendered line by probabilistically dropping characters."""
+    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 vis_trunc(s, w):
+    """Truncate string to visual width w, skipping ANSI escape codes."""
+    result = []
+    vw = 0
+    i = 0
+    while i < len(s):
+        if vw >= w:
+            break
+        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
+        else:
+            result.append(s[i])
+            vw += 1
+            i += 1
+    return "".join(result)
+
+
+def next_headline(pool, items, seen):
+    """Pull the next unique headline from pool, refilling as needed."""
+    while True:
+        if not pool:
+            pool.extend(items)
+            random.shuffle(pool)
+            seen.clear()
+        title, src, ts = pool.pop()
+        sig = title.lower().strip()
+        if sig not in seen:
+            seen.add(sig)
+            return title, src, ts
+
+
+def firehose_line(items, w):
+    """Generate one line of rapidly cycling firehose content."""
+    r = random.random()
+    if r < 0.35:
+        # Raw headline text
+        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:
+        # Dense glitch noise
+        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:
+        # Status / program output
+        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:
+        # Headline fragment with glitch prefix
+        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}"

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)