feat: add partial update support with caller-declared dirty tracking

- Add PartialUpdate dataclass and supports_partial_updates to EffectPlugin
- Add dirty region tracking to Canvas (mark_dirty, get_dirty_rows, etc.)
- Canvas auto-marks dirty on put_region, put_text, fill
- CanvasStage exposes dirty rows via pipeline context
- EffectChain creates PartialUpdate and calls process_partial() for optimized effects
- HudEffect implements process_partial() to skip processing when rows 0-2 not dirty
- This enables effects to skip work when canvas regions haven't changed

engine/effects/chain.py

@@ -2,7 +2,7 @@ import time
 
 from engine.effects.performance import PerformanceMonitor, get_monitor
 from engine.effects.registry import EffectRegistry
-from engine.effects.types import EffectContext
+from engine.effects.types import EffectContext, PartialUpdate
 
 
 class EffectChain:
@@ -51,6 +51,18 @@ class EffectChain:
         frame_number = ctx.frame_number
         monitor.start_frame(frame_number)
 
+        # Get dirty regions from canvas via context (set by CanvasStage)
+        dirty_rows = ctx.get_state("canvas.dirty_rows")
+
+        # Create PartialUpdate for effects that support it
+        full_buffer = dirty_rows is None or len(dirty_rows) == 0
+        partial = PartialUpdate(
+            rows=None,
+            cols=None,
+            dirty=dirty_rows,
+            full_buffer=full_buffer,
+        )
+
         frame_start = time.perf_counter()
         result = list(buf)
         for name in self._order:
@@ -59,7 +71,11 @@ class EffectChain:
                 chars_in = sum(len(line) for line in result)
                 effect_start = time.perf_counter()
                 try:
-                    result = plugin.process(result, ctx)
+                    # Use process_partial if supported, otherwise fall back to process
+                    if getattr(plugin, "supports_partial_updates", False):
+                        result = plugin.process_partial(result, ctx, partial)
+                    else:
+                        result = plugin.process(result, ctx)
                 except Exception:
                     plugin.config.enabled = False
                 elapsed = time.perf_counter() - effect_start

engine/effects/types.py

@@ -23,6 +23,25 @@ from dataclasses import dataclass, field
 from typing import Any
 
 
+@dataclass
+class PartialUpdate:
+    """Represents a partial buffer update for optimized rendering.
+
+    Instead of processing the full buffer every frame, effects that support
+    partial updates can process only changed regions.
+
+    Attributes:
+        rows: Row indices that changed (None = all rows)
+        cols: Column range that changed (None = full width)
+        dirty: Set of dirty row indices
+    """
+
+    rows: tuple[int, int] | None = None  # (start, end) inclusive
+    cols: tuple[int, int] | None = None  # (start, end) inclusive
+    dirty: set[int] | None = None  # Set of dirty row indices
+    full_buffer: bool = True  # If True, process entire buffer
+
+
 @dataclass
 class EffectContext:
     terminal_width: int
@@ -101,6 +120,7 @@ class EffectPlugin(ABC):
     name: str
     config: EffectConfig
     param_bindings: dict[str, dict[str, str | float]] = {}
+    supports_partial_updates: bool = False  # Override in subclasses for optimization
 
     @abstractmethod
     def process(self, buf: list[str], ctx: EffectContext) -> list[str]:
@@ -115,6 +135,25 @@ class EffectPlugin(ABC):
         """
         ...
 
+    def process_partial(
+        self, buf: list[str], ctx: EffectContext, partial: PartialUpdate
+    ) -> list[str]:
+        """Process a partial buffer for optimized rendering.
+
+        Override this in subclasses that support partial updates for performance.
+        Default implementation falls back to full buffer processing.
+
+        Args:
+            buf: List of lines to process
+            ctx: Effect context with terminal state
+            partial: PartialUpdate indicating which regions changed
+
+        Returns:
+            Processed buffer (may be same object or new list)
+        """
+        # Default: fall back to full processing
+        return self.process(buf, ctx)
+
     @abstractmethod
     def configure(self, config: EffectConfig) -> None:
         """Configure the effect with new settings.