1# vev-vt
2
3`github.com/bnema/vev-vt` is a frontend-neutral VT terminal engine for Go.
4It provides the terminal screen, scrollback history, immutable snapshots,
5stable history chunks, VTH3 history bytes, and the reusable cell/frame model.
6The `ansi` package turns core frames and damage into transactional ANSI output.
7
8## Packages
9
10- The module root (`github.com/bnema/vev-vt`) owns VT parsing, screen state,
11  history, snapshots, callbacks, and the public model aliases (`Cell`, `Style`,
12  `RGB`, `Frame`, `Damage`, and `RuneWidth`).
13- `github.com/bnema/vev-vt/core` owns the frontend-neutral cell, style, frame,
14  damage, and width implementation. It has no terminal, renderer, transport,
15  or application dependencies.
16- `github.com/bnema/vev-vt/ansi` is the concrete ANSI output package. It consumes
17  core frames and damage; it does not define a renderer-backend interface.
18- `github.com/bnema/vev-vt/graphics` owns bounded renderer-neutral raster assets,
19  sparse placements, clipping fragments, and immutable scene snapshots. It has no
20  Kitty, ANSI, VT-policy, or transport dependency.
21- `github.com/bnema/vev-vt/protocol/kittygraphics` parses bounded Kitty graphics
22  APC commands and translates the supported static/direct subset into `graphics`.
23
24## Ownership contract
25
26Stateful values are single-owner and are not internally synchronized. Serialize
27screen writes, resizes, snapshots, and history mutations in one owner. Parsing
28and callbacks are synchronous: callbacks run before `Write` returns and follow
29parser event order. Consume or copy response bytes during the callback.
30
31`Snapshot`, `HistorySnapshotView`, and `Row` methods provide owned captures or
32copies. `BorrowedRow`, `Frame.Row`, and `HistoryView.Range` expose borrowed
33storage with the lifetimes documented by their APIs; borrowed storage must not
34be mutated or retained beyond its documented lifetime. Sealed `HistoryChunk`
35identity is stable for the lifetime of a view.
36
37## Compatibility
38
39VTH3 history bytes are canonical and are decoded strictly, including malformed,
40truncated, and trailing input rejection. VEVS is an application-owned outer
41snapshot envelope and is intentionally not implemented here.
42
43The module has no production dependencies. `github.com/stretchr/testify` is
44used only by the test suite. Keep the public v0.x API and byte formats immutable
45once released; behavior changes require explicit versioning and compatibility
46evidence.
47
48## Kitty graphics subset
49
50The VT accepts bounded static direct transmissions used by current
51`kitten icat --transfer-mode=stream`: PNG, RGB, and RGBA assets; transmit,
52transmit-and-display, place, query, and supported delete operations; chunked
53Base64 uploads with optional zlib compression; source rectangles; cell extents;
54pixel offsets; z-index; and cursor movement policy. Assets and decoded pixels
55are bounded by explicit scene and parser limits. File, temporary-file,
56shared-memory, animation, composition, relative placement, and
57Unicode-placeholder commands remain unsupported.
58
59`Screen` allocates graphics state only after a Kitty APC. Graphics snapshots are
60separate from cells and history bytes; VTH3 remains text/history-only. Static
61placements move with terminal row scrolling and are clipped by the active
62viewport; reflow and relative-placement movement remain unsupported.
63
64### Headless graphics harness
65
66`cmd/graphics-harness` feeds a terminal byte capture into a fresh `Screen` and
67writes its active graphics snapshot as a PNG using an internal reference
68compositor. It is a development inspection tool, not a terminal emulator.
69
70```sh
71go run ./cmd/graphics-harness \
72  -input internal/graphicsharness/testdata/demo.apc \
73  -output /tmp/graphics-harness.png \
74  -cols 4 -rows 4 -pixel-width 4 -pixel-height 4 -scale 64
75```
76
77The included demo has an opaque blue background and a semi-transparent red
78overlay. Its output is suitable for direct image inspection.
79
80## Checks
81
82```sh
83go test ./...
84go test ./... -race
85go vet ./...
86go test ./... -run '^$' -bench='.' -benchmem
87```