feat: add isolated pane graphics streaming

2 files changed, 184 insertions, 1 deletions

diff --git a/docs/next/api/herdr-api.schema.json b/docs/next/api/herdr-api.schema.json
index a769d050..d146e11b 100644
--- a/docs/next/api/herdr-api.schema.json
+++ b/docs/next/api/herdr-api.schema.json
@@ -2075,6 +2075,92 @@
           ],
           "type": "object"
         },
+        "PaneGraphicsClearParams": {
+          "properties": {
+            "pane_id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "pane_id"
+          ],
+          "type": "object"
+        },
+        "PaneGraphicsFormat": {
+          "enum": [
+            "png",
+            "rgb",
+            "rgba"
+          ],
+          "type": "string"
+        },
+        "PaneGraphicsPlacementParams": {
+          "properties": {
+            "grid_cols": {
+              "default": 0,
+              "format": "uint32",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "grid_rows": {
+              "default": 0,
+              "format": "uint32",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "viewport_col": {
+              "default": 0,
+              "format": "int32",
+              "type": "integer"
+            },
+            "viewport_row": {
+              "default": 0,
+              "format": "int32",
+              "type": "integer"
+            }
+          },
+          "type": "object"
+        },
+        "PaneGraphicsSetParams": {
+          "properties": {
+            "data_base64": {
+              "default": "",
+              "type": "string"
+            },
+            "format": {
+              "$ref": "#/schemas/request/$defs/PaneGraphicsFormat"
+            },
+            "image_height": {
+              "format": "uint32",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "image_width": {
+              "format": "uint32",
+              "minimum": 0,
+              "type": "integer"
+            },
+            "pane_id": {
+              "type": "string"
+            },
+            "placement": {
+              "$ref": "#/schemas/request/$defs/PaneGraphicsPlacementParams",
+              "default": {
+                "grid_cols": 0,
+                "grid_rows": 0,
+                "viewport_col": 0,
+                "viewport_row": 0
+              }
+            }
+          },
+          "required": [
+            "pane_id",
+            "format",
+            "image_width",
+            "image_height"
+          ],
+          "type": "object"
+        },
         "PaneLayoutParams": {
           "properties": {
             "pane_id": {
@@ -4800,6 +4886,54 @@
         {
           "properties": {
             "method": {
+              "const": "pane.graphics.set",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/schemas/request/$defs/PaneGraphicsSetParams"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "method": {
+              "const": "pane.graphics.clear",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/schemas/request/$defs/PaneGraphicsClearParams"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "method": {
+              "const": "pane.graphics.info",
+              "type": "string"
+            },
+            "params": {
+              "$ref": "#/schemas/request/$defs/PaneTarget"
+            }
+          },
+          "required": [
+            "method",
+            "params"
+          ],
+          "type": "object"
+        },
+        {
+          "properties": {
+            "method": {
               "const": "pane.report_agent",
               "type": "string"
             },
@@ -8352,6 +8486,30 @@
             },
             {
               "properties": {
+                "cell_height_px": {
+                  "format": "uint32",
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "cell_width_px": {
+                  "format": "uint32",
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "type": {
+                  "const": "pane_graphics_info",
+                  "type": "string"
+                }
+              },
+              "required": [
+                "type",
+                "cell_width_px",
+                "cell_height_px"
+              ],
+              "type": "object"
+            },
+            {
+              "properties": {
                 "explain": true,
                 "type": {
                   "const": "agent_explain",
diff --git a/docs/next/website/src/content/docs/socket-api.mdx b/docs/next/website/src/content/docs/socket-api.mdx
index c02a83d1..e914eabc 100644
--- a/docs/next/website/src/content/docs/socket-api.mdx
+++ b/docs/next/website/src/content/docs/socket-api.mdx
@@ -103,7 +103,7 @@ Raw socket method names use dot notation:
 | Workspace | `workspace.create`, `workspace.list`, `workspace.get`, `workspace.focus`, `workspace.rename`, `workspace.move`, `workspace.report_metadata`, `workspace.close` |
 | Worktree | `worktree.list`, `worktree.create`, `worktree.open`, `worktree.remove` |
 | Tab | `tab.create`, `tab.list`, `tab.get`, `tab.focus`, `tab.rename`, `tab.move`, `tab.close` |
-| Pane | `pane.split`, `pane.swap`, `pane.move`, `pane.zoom`, `pane.layout`, `pane.process_info`, `pane.neighbor`, `pane.edges`, `pane.focus_direction`, `pane.resize`, `pane.list`, `pane.current`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
+| Pane | `pane.split`, `pane.swap`, `pane.move`, `pane.zoom`, `pane.layout`, `pane.process_info`, `pane.neighbor`, `pane.edges`, `pane.focus_direction`, `pane.resize`, `pane.list`, `pane.current`, `pane.get`, `pane.rename`, `pane.send_text`, `pane.send_keys`, `pane.send_input`, `pane.read`, `pane.graphics.info`, `pane.graphics.set`, `pane.graphics.clear`, `pane.graphics.stream`, `pane.report_agent`, `pane.report_agent_session`, `pane.report_metadata`, `pane.clear_agent_authority`, `pane.release_agent`, `pane.close`, `pane.wait_for_output` |
 | Layout | `layout.export`, `layout.apply`, `layout.set_split_ratio` |
 | Agent | `agent.list`, `agent.get`, `agent.read`, `agent.explain`, `agent.send`, `agent.rename`, `agent.focus`, `agent.start` |
 | Events | `events.subscribe`, `events.wait` |
@@ -162,6 +162,31 @@ pane.
 
 Clients can treat `offset_from_bottom == 0` as at-bottom state.
 
+### Experimental pane graphics
+
+Pane graphics let a plugin place image data over a pane. They are available
+only when `[experimental].kitty_graphics = true`; otherwise every pane graphics
+method returns `feature_disabled`. Calling `pane.graphics.info` returns the
+attached client's cell width and height in pixels without creating a graphics
+layer. `pane.graphics.set` accepts `png`, `rgb`, or `rgba` data in `data_base64`,
+and `pane.graphics.clear` removes the layer.
+
+```json
+{"id":"graphics_info","method":"pane.graphics.info","params":{"pane_id":"w1:p1"}}
+{"id":"graphics_set","method":"pane.graphics.set","params":{"pane_id":"w1:p1","format":"png","image_width":800,"image_height":600,"data_base64":"...","placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}}
+{"id":"graphics_clear","method":"pane.graphics.clear","params":{"pane_id":"w1:p1"}}
+```
+
+For repeated frames, open a dedicated socket with `pane.graphics.stream`. After
+Herdr replies with `ok`, send one JSON header and then exactly `data_length` raw
+bytes per frame. A stream owns that pane's graphics layer until the socket
+closes; concurrent set, clear, or stream requests return `stream_conflict`.
+
+```json
+{"id":"graphics_stream","method":"pane.graphics.stream","params":{"pane_id":"w1:p1"}}
+{"format":"png","image_width":800,"image_height":600,"data_length":12345,"placement":{"viewport_col":0,"viewport_row":0,"grid_cols":80,"grid_rows":30}}
+```
+
 `pane.layout` returns the tab layout snapshot with `workspace_id`, `tab_id`,
 `zoomed`, outer `area`, `focused_pane_id`, pane rects, and split rects/ratios.
 `pane.neighbor` and `pane.edges` include that same layout snapshot so clients