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/canvas.py

@@ -21,6 +21,10 @@ class CanvasRegion:
         """Check if region has positive dimensions."""
         return self.width > 0 and self.height > 0
 
+    def rows(self) -> set[int]:
+        """Return set of row indices in this region."""
+        return set(range(self.y, self.y + self.height))
+
 
 class Canvas:
     """2D canvas for rendering content.
@@ -39,10 +43,33 @@ class Canvas:
         self._grid: list[list[str]] = [
             [" " for _ in range(width)] for _ in range(height)
         ]
+        self._dirty_regions: list[CanvasRegion] = []  # Track dirty regions
 
     def clear(self) -> None:
         """Clear the entire canvas."""
         self._grid = [[" " for _ in range(self.width)] for _ in range(self.height)]
+        self._dirty_regions = [CanvasRegion(0, 0, self.width, self.height)]
+
+    def mark_dirty(self, x: int, y: int, width: int, height: int) -> None:
+        """Mark a region as dirty (caller declares what they changed)."""
+        self._dirty_regions.append(CanvasRegion(x, y, width, height))
+
+    def get_dirty_regions(self) -> list[CanvasRegion]:
+        """Get all dirty regions and clear the set."""
+        regions = self._dirty_regions
+        self._dirty_regions = []
+        return regions
+
+    def get_dirty_rows(self) -> set[int]:
+        """Get union of all dirty rows."""
+        rows: set[int] = set()
+        for region in self._dirty_regions:
+            rows.update(region.rows())
+        return rows
+
+    def is_dirty(self) -> bool:
+        """Check if any region is dirty."""
+        return len(self._dirty_regions) > 0
 
     def get_region(self, x: int, y: int, width: int, height: int) -> list[list[str]]:
         """Get a rectangular region from the canvas.
@@ -90,6 +117,9 @@ class Canvas:
             y: Top position
             content: 2D list of characters to place
         """
+        height = len(content) if content else 0
+        width = len(content[0]) if height > 0 else 0
+
         for py, row in enumerate(content):
             for px, char in enumerate(row):
                 canvas_x = x + px
@@ -97,6 +127,9 @@ class Canvas:
                 if 0 <= canvas_y < self.height and 0 <= canvas_x < self.width:
                     self._grid[canvas_y][canvas_x] = char
 
+        if width > 0 and height > 0:
+            self.mark_dirty(x, y, width, height)
+
     def put_text(self, x: int, y: int, text: str) -> None:
         """Put a single line of text at position.
 
@@ -105,11 +138,15 @@ class Canvas:
             y: Row position
             text: Text to place
         """
+        text_len = len(text)
         for i, char in enumerate(text):
             canvas_x = x + i
             if 0 <= canvas_x < self.width and 0 <= y < self.height:
                 self._grid[y][canvas_x] = char
 
+        if text_len > 0:
+            self.mark_dirty(x, y, text_len, 1)
+
     def fill(self, x: int, y: int, width: int, height: int, char: str = " ") -> None:
         """Fill a rectangular region with a character.
 
@@ -125,6 +162,9 @@ class Canvas:
                 if 0 <= py < self.height and 0 <= px < self.width:
                     self._grid[py][px] = char
 
+        if width > 0 and height > 0:
+            self.mark_dirty(x, y, width, height)
+
     def resize(self, width: int, height: int) -> None:
         """Resize the canvas.