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; source rectangles; cell extents; pixel offsets; z-index; and
54cursor movement policy. Assets and decoded pixels are bounded by explicit scene
55and parser limits. File, temporary-file, shared-memory, animation, composition,
56relative placement, and Unicode-placeholder commands remain unsupported.
57
58`Screen` allocates graphics state only after a Kitty APC. Graphics snapshots are
59separate from cells and history bytes; VTH3 remains text/history-only. Static
60placements retain their configured pixel rectangles across text scrolling and
61reflow; row-anchored and relative-placement movement is unsupported.
62
63### Headless graphics harness
64
65`cmd/graphics-harness` feeds a terminal byte capture into a fresh `Screen` and
66writes its active graphics snapshot as a PNG using an internal reference
67compositor. It is a development inspection tool, not a terminal emulator.
68
69```sh
70go run ./cmd/graphics-harness \
71  -input internal/graphicsharness/testdata/demo.apc \
72  -output /tmp/graphics-harness.png \
73  -cols 4 -rows 4 -pixel-width 4 -pixel-height 4 -scale 64
74```
75
76The included demo has an opaque blue background and a semi-transparent red
77overlay. Its output is suitable for direct image inspection.
78
79## Checks
80
81```sh
82go test ./...
83go test ./... -race
84go vet ./...
85go test ./... -run '^$' -bench='.' -benchmem
86```