Stream effective PTY geometry to clients (#135)

Author: myobie

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+### Stream-ordered effective geometry for embedded clients
+
+- Writable clients still select the shared PTY grid by independent row/column
+  minima, and zero viewers still preserve the last size. The daemon now sends
+  a framed `GEOMETRY` packet to writable and read-only output streams before
+  every affected `SCREEN`/`DATA`, including peer attach, resize, and
+  disconnect changes.
+- `SessionConnection` exposes `effectiveRows`/`effectiveCols` and a `geometry`
+  event. `attachPty()` and server-mode testing sessions resize their local
+  xterm grid from the same stream event before parsing later output. Older
+  clients safely ignore the bounded unknown packet and retain raw-byte
+  behavior.
+
 ### Read-only session listing
 
 - `listSessions()` and `pty list` are now strictly observational: they no

README.md

@@ -406,11 +406,15 @@ const stats = await queryStats("myserver");
 
 ```typescript
 const conn = new SessionConnection({ name: "myserver", rows: 24, cols: 80 });
-const initialScreen = await conn.connect();
 
+conn.on("geometry", ({ rows, cols }) => myTerminalView.resize(cols, rows));
 conn.on("data", (data) => myTerminalView.write(data));
 conn.on("exit", (code) => console.log(`Exited: ${code}`));
 
+const initialScreen = await conn.connect();
+myTerminalView.resize(conn.effectiveCols, conn.effectiveRows);
+myTerminalView.write(initialScreen);
+
 conn.write("hello\r");
 conn.press("ctrl+c");
 conn.resize(30, 100);

docs/client.md

@@ -186,25 +186,38 @@ Bidirectional, event-driven connection to a session.
 
 ```typescript
 const conn = new SessionConnection({ name: "myserver", rows: 24, cols: 80 });
-const initialScreen = await conn.connect();
 
+conn.on("geometry", ({ rows, cols }) => {
+  // Resize your emulator before the following screen/data bytes are parsed.
+  terminal.resize(cols, rows);
+});
 conn.on("data", (data: string) => { /* terminal output */ });
 conn.on("exit", (code: number) => { /* process exited */ });
 conn.on("close", () => { /* connection closed */ });
 conn.on("error", (err: Error) => { /* connection error */ });
 
+const initialScreen = await conn.connect();
+// Initial GEOMETRY is stream-ordered before SCREEN. The effective getters are
+// therefore authoritative before applying the returned replay.
+terminal.resize(conn.effectiveCols, conn.effectiveRows);
+terminal.write(initialScreen);
+
 conn.write("hello\r");          // send raw data
 conn.press("ctrl+c");           // send named key
-conn.resize(30, 100);           // resize terminal
+conn.resize(30, 100);           // request a shared-grid size
 conn.disconnect();               // close connection
 ```
 
 **Properties:**
 - `connected: boolean` — whether the connection is active
+- `effectiveRows: number` / `effectiveCols: number` — current authoritative
+  shared-grid dimensions. These can differ from the client's requested size
+  when another writable client is smaller.
 
 **Events:**
 | Event | Payload | Description |
 |---|---|---|
+| `geometry` | `{ rows, cols }` | Effective shared geometry, ordered before affected `screen`/`data` |
 | `data` | `string` | Terminal output from the session |
 | `screen` | `string` | Initial screen replay on connect |
 | `exit` | `number` | Session process exited with code |
@@ -384,9 +397,15 @@ const MessageType = {
   SCREEN: 5,   // Screen replay
   PEEK: 6,     // Read-only peek request
   STATUS: 7,   // Stats query/response
+  GEOMETRY: 10, // Effective shared rows/cols (server → client)
 };
 ```
 
+Packet types are length-delimited. Clients predating `GEOMETRY` ignore the
+unknown bounded packet and continue with following `SCREEN`/`DATA`, preserving
+their historical raw-byte behavior. Embedders that reconstruct a terminal grid
+must handle `GEOMETRY`.
+
 ### `TERMINAL_SANITIZE: string`
 
 ANSI sequence that resets all terminal modes (mouse tracking, cursor visibility, alternate screen, etc.). Useful after disconnecting from a session.

docs/testing.md

@@ -335,6 +335,11 @@ Resize the terminal dimensions:
 session.resize(40, 120);
 ```
 
+In server mode this requests a size from the daemon. `session.rows` and
+`session.cols` update when the daemon reports the effective min-wins geometry;
+another smaller writable client can keep the effective grid below the requested
+size. Geometry is applied before affected screen/output bytes are parsed.
+
 ### connectToExisting(session)
 
 Create a second client attached to the same server process:
@@ -356,7 +361,7 @@ await session2.waitForText("shared");
 - `session.hasExited` — whether the process has exited (always `false` for spawn-mode)
 - `session.name` — the session name (server-mode only)
 - `session.server` — the underlying `PtyServer` instance (server-mode only)
-- `session.rows` / `session.cols` — current terminal dimensions
+- `session.rows` / `session.cols` — current effective terminal dimensions
 
 ## Running Tests
 

src/connection.ts

@@ -8,6 +8,7 @@ import {
   encodeDetach,
   encodePeek,
   encodeResize,
+  decodeGeometry,
   decodeExit,
 } from "./protocol.ts";
 import { getSocketPath } from "./sessions.ts";
@@ -47,6 +48,7 @@ export interface PeekScreenOptions {
  *
  * Events:
  * - 'data' (data: string) — terminal output from the session
+ * - 'geometry' ({ rows, cols }) — effective shared grid before affected output
  * - 'screen' (screen: string) — initial screen replay on connect
  * - 'exit' (code: number) — session process exited
  * - 'close' () — connection closed
@@ -57,16 +59,28 @@ export class SessionConnection extends EventEmitter {
   private reader = new PacketReader();
   private _connected = false;
   private options: SessionConnectionOptions;
+  private _effectiveRows: number;
+  private _effectiveCols: number;
 
   constructor(options: SessionConnectionOptions) {
     super();
     this.options = options;
+    this._effectiveRows = options.rows;
+    this._effectiveCols = options.cols;
   }
 
   get connected(): boolean {
     return this._connected;
   }
 
+  get effectiveRows(): number {
+    return this._effectiveRows;
+  }
+
+  get effectiveCols(): number {
+    return this._effectiveCols;
+  }
+
   connect(): Promise<string> {
     return new Promise((resolve, reject) => {
       const socketPath = getSocketPath(this.options.name);
@@ -88,6 +102,13 @@ export class SessionConnection extends EventEmitter {
         }
         for (const packet of packets) {
           switch (packet.type) {
+            case MessageType.GEOMETRY: {
+              const geometry = decodeGeometry(packet.payload);
+              this._effectiveRows = geometry.rows;
+              this._effectiveCols = geometry.cols;
+              this.emit("geometry", geometry);
+              break;
+            }
             case MessageType.SCREEN: {
               const screen = packet.payload.toString();
               if (!initialScreenResolved) {
@@ -147,6 +168,8 @@ export class SessionConnection extends EventEmitter {
 
   resize(rows: number, cols: number): void {
     if (!this.socket || !this._connected) return;
+    this.options.rows = rows;
+    this.options.cols = cols;
     this.socket.write(encodeResize(rows, cols));
   }
 

src/protocol.ts

@@ -9,6 +9,8 @@ export const MessageType = {
   SCREEN: 5, // Server → Client: screen buffer replay on attach
   PEEK: 6, // Client → Server: read-only attach (no input, no resize)
   STATUS: 7, // Client → Server: request stats; Server → Client: JSON stats response
+  // Values 8 and 9 are reserved for independent protocol extensions.
+  GEOMETRY: 10, // Server → Client: effective shared rows/cols
 } as const;
 
 export type MessageType = (typeof MessageType)[keyof typeof MessageType];
@@ -69,6 +71,13 @@ export function encodeResize(rows: number, cols: number): Buffer {
   return encodePacket(MessageType.RESIZE, payload);
 }
 
+export function encodeGeometry(rows: number, cols: number): Buffer {
+  const payload = Buffer.alloc(4);
+  payload.writeUInt16BE(rows, 0);
+  payload.writeUInt16BE(cols, 2);
+  return encodePacket(MessageType.GEOMETRY, payload);
+}
+
 export function encodeExit(code: number): Buffer {
   const payload = Buffer.alloc(4);
   payload.writeInt32BE(code, 0);
@@ -104,6 +113,10 @@ export function decodeSize(payload: Buffer): { rows: number; cols: number } {
   };
 }
 
+export function decodeGeometry(payload: Buffer): { rows: number; cols: number } {
+  return decodeSize(payload);
+}
+
 export function decodeExit(payload: Buffer): number {
   if (payload.length < 4) {
     return -1;

src/server.ts

@@ -16,6 +16,7 @@ import {
   encodeExit,
   encodeScreen,
   encodeStatusResponse,
+  encodeGeometry,
   decodeSize,
 } from "./protocol.ts";
 import {
@@ -628,6 +629,9 @@ export class PtyServer {
             client.cols = size.cols;
             client.attachSeq = ++this.attachCounter;
             const resized = this.negotiateSize();
+            if (!resized) {
+              socket.write(encodeGeometry(this.terminal.rows, this.terminal.cols));
+            }
             // Stamp the last-attach timestamp so `pty gc --idle-days N`
             // (and per-session `strategy.idle-days=N` tags) can detect
             // abandonment. Best-effort — if the metadata file was
@@ -686,6 +690,7 @@ export class PtyServer {
 
           case MessageType.PEEK: {
             client.readonly = true;
+            socket.write(encodeGeometry(this.terminal.rows, this.terminal.cols));
             const flags = packet.payload.length > 0 ? packet.payload.readUInt8(0) : 0;
             const plain = (flags & 1) !== 0;
             const full = (flags & 2) !== 0;
@@ -837,15 +842,25 @@ export class PtyServer {
 
     if (rows > 0 && cols > 0) {
       if (rows !== this.terminal.rows || cols !== this.terminal.cols) {
-        this.ptyProcess.resize(cols, rows);
         this.terminal.resize(cols, rows);
+        this.broadcastGeometry(rows, cols);
+        this.ptyProcess.resize(cols, rows);
         this.lastResizeTime = Date.now();
         return true;
       }
     }
     return false;
   }
 
+  private broadcastGeometry(rows: number, cols: number): void {
+    const packet = encodeGeometry(rows, cols);
+    for (const client of this.clients.values()) {
+      if (client.attachSeq > 0 || client.readonly) {
+        client.socket.write(packet);
+      }
+    }
+  }
+
   /** Briefly resize the PTY by 1 column and back to trigger SIGWINCH,
    *  forcing the child to do a complete redraw. The xterm-headless terminal
    *  is resized in sync so its buffer stays correct. */

src/testing/session.ts

@@ -11,6 +11,7 @@ import {
   encodeAttach,
   encodeData,
   encodeResize,
+  decodeGeometry,
 } from "../protocol.ts";
 import { getSocketPath } from "../sessions.ts";
 import { resolveKey } from "../keys.ts";
@@ -64,6 +65,8 @@ export class Session {
   private backend: Backend;
   private _rows: number;
   private _cols: number;
+  private _requestedRows: number;
+  private _requestedCols: number;
 
   private constructor(
     terminal: Terminal,
@@ -77,6 +80,8 @@ export class Session {
     this.backend = backend;
     this._rows = rows;
     this._cols = cols;
+    this._requestedRows = rows;
+    this._requestedCols = cols;
   }
 
   // ── Factories ──
@@ -190,8 +195,8 @@ export class Session {
       throw new Error("connectToExisting() requires a server-mode session");
     }
 
-    const rows = opts.rows ?? existing._rows;
-    const cols = opts.cols ?? existing._cols;
+    const rows = opts.rows ?? existing._requestedRows;
+    const cols = opts.cols ?? existing._requestedCols;
 
     const terminal = new xterm.Terminal({
       rows,
@@ -357,7 +362,7 @@ export class Session {
         resolve();
       });
     });
-    backend.socket.write(encodeAttach(this._rows, this._cols));
+    backend.socket.write(encodeAttach(this._requestedRows, this._requestedCols));
     await screenPromise;
   }
 
@@ -378,10 +383,9 @@ export class Session {
     if (this.backend.kind !== "server") {
       throw new Error("resize() is only available in server mode");
     }
-    this._rows = rows;
-    this._cols = cols;
+    this._requestedRows = rows;
+    this._requestedCols = cols;
     this.backend.socket.write(encodeResize(rows, cols));
-    this.terminal.resize(cols, rows);
   }
 
   // ── Lifecycle ──
@@ -426,6 +430,13 @@ export class Session {
       }
       for (const packet of packets) {
         switch (packet.type) {
+          case MessageType.GEOMETRY: {
+            const geometry = decodeGeometry(packet.payload);
+            this._rows = geometry.rows;
+            this._cols = geometry.cols;
+            this.terminal.resize(geometry.cols, geometry.rows);
+            break;
+          }
           case MessageType.SCREEN:
             this.terminal.reset();
             this.terminal.write(packet.payload.toString(), () => {