Add planner previews and streaming

server/planner.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from math import hypot
 from typing import Sequence
 
-from .models import GridCellModel, GridDescriptor
+from .models import ActionPayload, ActionType, GridCellModel, GridDescriptor
 
 
 class GridPlanner:
@@ -23,6 +23,23 @@ class GridPlanner:
         center_point = self._grid_center(descriptor)
         return min(descriptor.cells, key=lambda cell: self._distance(self._cell_center(cell), center_point))
 
+    def build_payload(
+        self,
+        descriptor: GridDescriptor,
+        action: ActionType = ActionType.CLICK,
+        preferred_label: str | None = None,
+        text: str | None = None,
+        comment: str | None = None,
+    ) -> ActionPayload:
+        target = self.select_cell(descriptor, preferred_label)
+        return ActionPayload(
+            grid_id=descriptor.grid_id,
+            action=action,
+            target_cell=target.cell_id if target else None,
+            text=text,
+            comment=comment,
+        )
+
     def describe(self, descriptor: GridDescriptor) -> str:
         cell_count = len(descriptor.cells)
         return (