feat(perception): sample OCR text foreground/background colors

PaddleOCR itself returns no color info, only text/bounds/confidence.
Add pixel-level post-processing in perception/ocr.py: crop the
screenshot to each OCR box, split pixels into two luminance clusters
via Otsu threshold, and treat the minority cluster as the text stroke
(foreground) and the majority as the background. New
SceneElement.foreground_color/background_color fields ("#rrggbb",
None when not OCR-sourced or sampling fails) round-trip through
to_dict/from_dict alongside the existing accessibility-state fields.
Planner system prompt documents the new fields as a secondary signal.

pillow is promoted from an implicit paddleocr transitive dependency to
an explicit direct dependency since perception/ocr.py now imports PIL
directly; uv.lock re-resolved with no version change (already locked
at 12.3.0).

perception/ocr.py

@@ -4,7 +4,7 @@ import os
 import tempfile
 import logging
 from collections.abc import Iterable
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from numbers import Real
 from pathlib import Path
 from typing import Any
@@ -19,6 +19,8 @@ class OCRBox:
     text: str
     bounds: Bounds
     confidence: float | None = None
+    foreground_color: str | None = None
+    background_color: str | None = None
 
     def to_scene_element(self, element_id: str) -> SceneElement:
         return SceneElement(
@@ -28,6 +30,8 @@ class OCRBox:
             bounds=self.bounds,
             confidence=self.confidence,
             source="ocr",
+            foreground_color=self.foreground_color,
+            background_color=self.background_color,
         )
 
 
@@ -54,7 +58,8 @@ class PaddleOCREngine:
                 raw = engine.predict(input=image_input)
             else:
                 raw = engine.ocr(image_input, cls=True)
-            return parse_paddle_result(raw)
+            boxes = parse_paddle_result(raw)
+            return _with_sampled_colors(boxes, image_input)
         finally:
             if temp_path:
                 temp_path.unlink(missing_ok=True)
@@ -83,6 +88,106 @@ def run_ocr(
     return [box.to_scene_element(f"ocr-{index:03d}") for index, box in enumerate(boxes)]
 
 
+def _with_sampled_colors(boxes: list[OCRBox], image_path: str) -> list[OCRBox]:
+    if not boxes:
+        return boxes
+    try:
+        from PIL import Image
+
+        with Image.open(image_path) as source:
+            picture = source.convert("RGB")
+            sampled = []
+            for box in boxes:
+                foreground, background = _estimate_colors(picture, box.bounds)
+                sampled.append(
+                    replace(
+                        box,
+                        foreground_color=foreground,
+                        background_color=background,
+                    )
+                )
+            return sampled
+    except Exception:
+        logger.warning(
+            "OCR color sampling failed; continuing without foreground/background colors",
+            exc_info=True,
+        )
+        return boxes
+
+
+def _estimate_colors(picture: Any, bounds: Bounds) -> tuple[str | None, str | None]:
+    left = max(0, int(bounds.x))
+    top = max(0, int(bounds.y))
+    right = min(picture.width, int(round(bounds.right)))
+    bottom = min(picture.height, int(round(bounds.bottom)))
+    if right - left < 2 or bottom - top < 2:
+        return (None, None)
+
+    pixels = list(picture.crop((left, top, right, bottom)).get_flattened_data())
+    threshold = _otsu_threshold(pixels)
+    if threshold is None:
+        return (None, None)
+
+    dark = [pixel for pixel in pixels if _luminance(pixel) <= threshold]
+    light = [pixel for pixel in pixels if _luminance(pixel) > threshold]
+    if not dark or not light:
+        return (None, None)
+
+    # Text strokes normally cover a minority of the box's pixels regardless of
+    # whether the text is dark-on-light or light-on-dark, so the smaller of
+    # the two luminance clusters is treated as the foreground (text) color.
+    foreground, background = (dark, light) if len(dark) <= len(light) else (light, dark)
+    return _average_hex(foreground), _average_hex(background)
+
+
+def _luminance(pixel: tuple[int, int, int]) -> float:
+    r, g, b = pixel
+    return 0.299 * r + 0.587 * g + 0.114 * b
+
+
+def _otsu_threshold(pixels: list[tuple[int, int, int]]) -> float | None:
+    total = len(pixels)
+    if total == 0:
+        return None
+
+    histogram = [0] * 256
+    for pixel in pixels:
+        histogram[int(_luminance(pixel))] += 1
+
+    sum_total = sum(level * count for level, count in enumerate(histogram))
+    sum_background = 0.0
+    weight_background = 0
+    best_variance = -1.0
+    threshold = 0
+    for level, count in enumerate(histogram):
+        weight_background += count
+        if weight_background == 0:
+            continue
+        weight_foreground = total - weight_background
+        if weight_foreground == 0:
+            break
+        sum_background += level * count
+        mean_background = sum_background / weight_background
+        mean_foreground = (sum_total - sum_background) / weight_foreground
+        variance = (
+            weight_background
+            * weight_foreground
+            * (mean_background - mean_foreground) ** 2
+        )
+        if variance > best_variance:
+            best_variance = variance
+            threshold = level
+    return float(threshold)
+
+
+def _average_hex(pixels: list[tuple[int, int, int]]) -> str:
+    count = len(pixels)
+    r = sum(pixel[0] for pixel in pixels) // count
+    g = sum(pixel[1] for pixel in pixels) // count
+    b = sum(pixel[2] for pixel in pixels) // count
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
 def parse_paddle_result(raw: Any) -> list[OCRBox]:
     boxes: list[OCRBox] = []
     for item in _flatten_pages(raw):