fix(client): coalesce output-burst frames into one paint (phux-jhv8)

[phall1]

Summary

Opening neovim in a phux attach froze the client for ~0.5s. This coalesces the back-to-back frame burst nvim's startup produces into a single paint, cutting bytes emitted to the host terminal −38% and render+blocking-flush count −66% under the freeze condition.

Root cause (measured, not guessed)

Built a headless repro (phux server + nvim in a sized pty, JSON span capture + emitted-byte accounting). Client render compute is ~4ms total / 0.3ms per frame — not the bottleneck. The freeze is a chain:

• render_at repaints whole dirty rows (CUP + SGR + every column), so a 1KB nvim delta across a 200-col syntax-highlighted screen re-emits full rows — ~3× byte amplification, scaling with window size × highlight richness (hence "depends on your terminal").
• nvim's startup sends a back-to-back burst (61 of 72 inter-frame gaps <2ms); the attach loop rendered and flushed each frame separately. paint → render_at → out.flush() is synchronous in the biased select loop, so on a slow host terminal the blocking flush stalls the whole loop — the freeze (captured a ~2s blocked paint).

Fix — per-pane frame coalescing

• connection.rs: FrameReader now buffers the socket (chunked reads, decode complete frames off the front) and exposes a non-blocking try_recv().
• driver.rs: after a recv wake-up, drain every already-queued frame, apply all vt_writes, and paint once. A frame defers its paint iff a later frame in the same drain repaints the same pane (coalesce_defer_flags) — so every touched pane settles exactly once on its last frame, no pane left stale, and the hot single-pane case collapses to one paint.
• server_frame.rs: defer_paint flag reuses the existing overlay_active "apply vt_write, skip paint" seam.

Measurement (200×60, nvim on a 2,500-line highlighted file, throttled 150KB/s sink = the freeze condition)

Metric	Baseline	Fixed	Δ
Bytes emitted to host	93,418	~57,900	−38%
Render + blocking flushes	74	25	−66%

Savings scale with sink slowness (more frames pile up per stalled flush → bigger coalesce), so a genuinely slow terminal benefits at least this much. On a fast sink it's a no-op (lone frame → old one-frame-one-paint path), so no added latency.

Correctness

Client pty stream rendered through pyte is byte-identical to baseline's final screen (6/6 trials, nvim on a real file). An intermediate "defer to last focused-output frame" variant was multi-pane-correct but lost most of the byte win; the per-pane rule gets both.

Residual (separate lever, not in scope)

Coalescing removes the redundant intermediate redraws (nvim's splash→clear→buffer collapsing to one), not the per-dirty-row amplification itself. Per-column damage-span rendering in render_at_inner would attack that.

Tests

• coalesce_defer_flags: single-pane, interleaved panes, control frames, empty.
• decode_buffered: back-to-back drain, partial-frame hold, empty.
• Full just ci green.

The second commit fixes a pre-existing broken intra-doc link in runtime.rs that was already failing just ci's -D warnings doc gate (unrelated to the freeze; included so CI is green).

🤖 Generated with Claude Code