Faster webterm protocol

[FireSquid6]

In cases of spotty network connection, the webterm protocol can feel slow. We need to design a way for it to work faster.

[FireSquid6]

@claude figure out and comment back with some ways we could speed up the webterm protocol

[claude]

Claude finished @FireSquid6's task in 2m 1s —— View job

---

Todo

• Gather context on the request
• Explore webterm protocol implementation (packages/webterm, fleet-ship/fleet-bridge/fleet-client terminal proxies)
• Identify performance bottlenecks
• Propose concrete ways to speed it up
• Post findings

Ways to speed up the webterm protocol

This was an analysis-only request, so no code was changed — findings below, ranked by expected impact on a spotty/low-bandwidth connection.

1. Send diffs, not full grid snapshots (biggest win)

Every grid frame is a complete screen snapshot — serializeGrid re-encodes and re-sends every cell, every ~16 ms (server.ts:122), even if only a couple of cells changed (e.g. cursor blink, one status line). On a fast LAN this is cheap; on a spotty/low-bandwidth link, resending an 80×24+ (or up to 1024×512) grid 60x/sec is the dominant cost. A dirty-cell diff (row/col + changed WireCell, keyed against the last-sent grid) would shrink most frames to a handful of entries. The current "every frame is a full snapshot" property is also what makes frame loss/reconnect trivially safe (docs: webterm.md:57-59) — that has to be preserved, e.g. always send a full snapshot as the first frame after init/reconnect, deltas after that.

2. Respect WebSocket backpressure instead of blind sends

TerminalBridge.send (server.ts:127) and every proxy hop (ship: workspaces.ts:309,314; bridge relay: workspaces.ts:195; fleet-client relay: index.ts:155) call ws.send() without checking the return value or bufferedAmount. On a congested/spotty link this lets frames pile up in the socket's outgoing buffer faster than they drain, so the browser ends up multiple stale frames behind even though each individual frame is small — increasing perceived latency. BACKLOG.md already tracks this exact pattern for the bridge's event stream ("Bridge event backpressure"); the same fix (check send result, skip/drop instead of queueing, or resync on reconnect) should extend to the terminal path.

3. Make frame cadence backpressure-aware, not just time-based

scheduleFrame (server.ts:122-129) fires a fixed 16 ms timer regardless of whether the previous frame has actually left the socket. Pairing this with #2 — skip scheduling a new frame while the outgoing socket still has unsent bytes buffered — turns the existing coalescing logic into real adaptive-rate coalescing: a fast link still gets ~60fps, a slow one naturally drops to whatever it can actually drain, instead of queuing frames behind each other.

4. Enable WebSocket compression (permessage-deflate)

No perMessageDeflate option is set anywhere in the WebSocket configs (fleet-client, fleet-bridge, fleet-ship). The wire format is JSON with heavily repeated short keys (t, f, b, a, u, w, "type":"grid", etc.) — this compresses very well with deflate. Turning on compression for at least the browser-facing leg (fleet-client's websocket config, index.ts:144) is a low-effort win specifically for bandwidth-constrained connections, at the cost of some CPU per frame.

5. (Larger, longer-term) Binary framing instead of JSON text

The protocol currently rejects binary frames outright (protocol.ts:24-25,196). Since the cell encoding already optimizes for compactness (blank → literal 0), a flat binary layout (e.g. typed arrays) would be both smaller on the wire and cheaper to parse than JSON, compounding with compression. This is a real protocol/back-compat change (new close-code semantics, decoder rewrite on both ends), so it's worth doing only if #1–#4 aren't enough — it's the highest effort, highest ceiling option.

Not a bottleneck: the proxy chain (browser → fleet-client → bridge → ship) already forwards server→client frames as raw text without re-decoding/re-serializing at each hop, so added CPU latency per hop is minimal. The reconnect story is also already solid — because every frame is a full snapshot, a dropped/reconnected socket resyncs for free (no missed-delta problem) as long as #1 preserves that behavior for the first frame after reconnect.

No files were changed as part of this — this is a research/investigation issue, not an implementation request. Happy to implement any of the above if you'd like to pick a direction.