vtsnapshot

package
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 14, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package vtsnapshot resolves a recorded PTY byte stream into the screen it would have painted, so a client attaching mid-session can be handed the current screen instead of the whole recording.

A full-screen TUI — Claude Code enters the alternate screen once at startup and never leaves it — emits a stream of width-dependent relative cursor moves that overdraw the same cells thousands of times. Two things go wrong when that raw stream is replayed to a late-joining client:

  • Volume. Measured on a single production job: 8.7 MB of transcript, 39699 render frames, median frame 57 bytes. The client paints every intermediate frame — the "the whole session scrolls past on connect" symptom — to arrive at a screen the last frame alone describes.
  • Correctness. Those relative moves were recorded at one terminal width. Replaying them at another accumulates into garbage, which is why a naive "just replay the tail" bound does not work either: the median frame patches a handful of cells and means nothing without its predecessors.

Resolving the stream through a virtual terminal sized to the recording and dumping the resulting grid fixes both: the payload is one screen (plus bounded scrollback), and the dump is absolute, so the client's own xterm reflows it to whatever width the client actually has.

This is a reinstatement, not a new idea: the same rendering lived in the userns backend's runtime_local_linux.go until a47f02bf removed that backend wholesale, leaving the container backend replaying raw bytes and go.mod carrying an unused x/vt dependency. See docs/plans/web-terminal-vt-emulator.md.

Index

Constants

View Source
const MaxScrollbackLines = 2000

MaxScrollbackLines bounds how many scrolled-off lines a snapshot prepends ahead of the visible screen. It exists for the session shape the alternate screen does NOT cover — a plain shell, where output scrolls rather than overdraws, and where an unbounded dump would be just as large as the raw replay it replaces.

Keep aligned with the xterm scrollback in web/static/boid-terminal.js: lines beyond what the client's own buffer holds are paid for on the wire and then immediately discarded.

Variables

This section is empty.

Functions

func Render

func Render(raw []byte, cols, rows int) []byte

Render feeds raw through a virtual terminal of the given geometry and returns the resolved screen as a width-independent ANSI dump with SGR styles preserved: the most recent MaxScrollbackLines scrolled-off lines, then the visible screen. The caller paints it onto a cleared terminal.

Non-positive cols/rows fall back to 80x24. An empty raw returns nil.

Render is CPU-bound and proportional to len(raw); callers must not hold a lock across it (the transcript it resolves is appended to by a live read loop). Rendering the 8.7 MB job above takes on the order of a tenth of a second.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL