[idea] Socket API: cursor position in pane.read, more key names for send_keys, and a changing revision

[ya-luotao]

Hi! I'm building a GUI companion that shows herdr panes through the socket API. It reads pane.read {source: "visible", format: "ansi"} and types into panes with pane.send_keys / pane.send_text. On 0.9.0 (protocol 22) this already works well: the ansi output is clean SGR plus CRLF, reads have no side effects, and key encoding follows the app's keyboard mode. Three gaps get in the way of making it feel like a real terminal:

1. Cursor position in pane.read. PaneReadResult has no cursor, so a client can't show where the shell's cursor is. TUIs that draw their own highlight are fine; a plain shell prompt shows no cursor at all. Something like cursor: {row, col, visible} relative to the returned text, for source: "visible", would be enough.

2. Home / End / PageUp / PageDown / Insert / Delete in API key names. On 0.9.0 every spelling I tried returns invalid_key: home, end, pageup, PageUp, PgUp, pgdn, page_down, insert, delete, Delete, del. It looks like the key-combo parser behind send_keys has no names for them. Raw escapes through send_text aren't a good substitute, because they bypass the app's keyboard mode and bracketed-paste state. (Minor: f13 is accepted but sends nothing.)

3. A revision that changes with the screen, or an output-changed event. revision is always 0 in pane.read and in session.snapshot panes, so clients poll and diff the text. A per-pane content revision, or a lightweight pane.output_changed subscription, would let clients skip unchanged reads.

Happy to test any of these. Thanks for herdr!

[HadsonRamalho]

+1 on point 1 (cursor position in pane.read), with one data point against "TUIs that draw their own highlight are fine": Claude Code does not draw its own highlight.

We render herdr panes in a web canvas from pane.read (source: "visible") and pane.send_keys. With Claude Code 2.1.318 in the pane, the raw PTY bytes show it hides the cursor (?25l), redraws the input box, then ends each frame with a CUP to the edit position plus ?25h. There is no reverse-video cell: the caret only exists as the real terminal cursor. After four Left arrows the cursor moves from column 13 to 9, but the pane.read text is byte-identical (❯ abcdefghij) in both cases.

So a client cannot show where the user is editing in the Claude Code prompt. Guessing from the end of the text is right only when the caret is at the end. Checked on 0.8.2 in pane read (text, ansi, --raw), pane get, pane layout and api snapshot; none of them carries a cursor. cursor: {row, col, visible} relative to the returned text, as proposed above, would cover it.