Safe API use

Screens and snapshots

A Screen changes as bytes arrive. Keep writes, resizes, reads and snapshot capture in one goroutine, or use a lock in your application. The library does not provide a screen-wide lock.

screen.Snapshot() makes an independent screen copy. You can keep that snapshot while the live screen changes. History views similarly preserve the rows they captured. Old, finished history chunks are shared instead of copied repeatedly.

Screen, ScreenSnapshot and core.Frame all support core.CellSource: read dimensions with Columns() and Rows(), and a cell with Cell(x, y). Renderers should use these methods rather than assuming a particular memory layout.

Rows returned by public extraction methods are copies. For a writable core.Frame, use Set, WriteRow, FillRow, CopyRow and the scroll operations. A plain Go assignment of a Frame shares its storage; use Clone() when you need an independent grid. CopyFrom reuses the destination's storage, so every Frame assigned from it sees the overwrite: call it only on a frame you own exclusively. core.RowsEqualAt compares rows of two frames without copying.

Callbacks

Callbacks run synchronously, before Screen.Write returns. Avoid slow work in them. Copy response bytes during the callback if you need to retain them.

Borrowed and owned byte slices

A few entry points skip a copy when the caller can promise exclusive ownership:

kittygraphics.ParseAPCBorrowed returns a command whose payload aliases the input. Keep the input unchanged while the command is in use. Session.Process never retains a command's payload, so the input may be reused once it returns.
graphics.Scene.AddAssetOwned and ReplaceAssetOwned keep Encoded instead of copying it. Do not read or modify it afterwards. A slice with large spare capacity is still copied, so the scene retains only accounted bytes. On error the scene keeps nothing.

The copying variants (ParseAPC, AddAsset, ReplaceAsset) remain the safe default.

Styles

Use DefaultStyle() to leave foreground and background colors at the terminal's defaults. Style{} is different: its zero color indexes are active colors.

For style comparison, use Style.Equal. Style.Canonical() removes fields that do not affect the displayed style, such as an indexed foreground when an RGB foreground is active. Canonical styles can also be compared with Go's ==. This lets storage share identical styles without keeping irrelevant differences.

Exceptional cell data

core.NewCellPayload(grapheme, hyperlink) creates a read-only value for Cell.Payload. It checks UTF-8, rejects terminal control characters and limits strings to 128 grapheme bytes and 4,096 hyperlink bytes.

Pages share equal values locally and reclaim entries after overwrite or clear. Copies, resize/reflow, snapshots, history and persistence preserve those values. Callers never receive internal page handles.

This is storage support only. It does not add full grapheme segmentation or an OSC 8 hyperlink parser. The VT parser and ANSI renderer still use their existing rune-based text behavior.

Stability and dependencies

vev-vt is v0.x software. APIs and saved-history formats may change without compatibility adapters. Check the history guide before updating an application that persists terminal state.

There are no third-party production dependencies. testify is used by tests.

source

1# Safe API use
2
3[Back to the README](../README.md)
4
5## Screens and snapshots
6
7A `Screen` changes as bytes arrive. Keep writes, resizes, reads and snapshot
8capture in one goroutine, or use a lock in your application. The library does
9not provide a screen-wide lock.
10
11`screen.Snapshot()` makes an independent screen copy. You can keep that snapshot
12while the live screen changes. History views similarly preserve the rows they
13captured. Old, finished history chunks are shared instead of copied repeatedly.
14
15`Screen`, `ScreenSnapshot` and `core.Frame` all support `core.CellSource`: read
16dimensions with `Columns()` and `Rows()`, and a cell with `Cell(x, y)`. Renderers
17should use these methods rather than assuming a particular memory layout.
18
19Rows returned by public extraction methods are copies. For a writable
20`core.Frame`, use `Set`, `WriteRow`, `FillRow`, `CopyRow` and the scroll operations.
21A plain Go assignment of a `Frame` shares its storage; use `Clone()` when you need
22an independent grid. `CopyFrom` reuses the destination's storage, so every
23`Frame` assigned from it sees the overwrite: call it only on a frame you own
24exclusively. `core.RowsEqualAt` compares rows of two frames without copying.
25
26## Callbacks
27
28Callbacks run synchronously, before `Screen.Write` returns. Avoid slow work in
29them. Copy response bytes during the callback if you need to retain them.
30
31## Borrowed and owned byte slices
32
33A few entry points skip a copy when the caller can promise exclusive ownership:
34
35- `kittygraphics.ParseAPCBorrowed` returns a command whose payload aliases the
36  input. Keep the input unchanged while the command is in use.
37  `Session.Process` never retains a command's payload, so the input may be
38  reused once it returns.
39- `graphics.Scene.AddAssetOwned` and `ReplaceAssetOwned` keep `Encoded` instead
40  of copying it. Do not read or modify it afterwards. A slice with large spare
41  capacity is still copied, so the scene retains only accounted bytes. On error
42  the scene keeps nothing.
43
44The copying variants (`ParseAPC`, `AddAsset`, `ReplaceAsset`) remain the safe
45default.
46
47## Styles
48
49Use `DefaultStyle()` to leave foreground and background colors at the terminal's
50defaults. `Style{}` is different: its zero color indexes are active colors.
51
52For style comparison, use `Style.Equal`. `Style.Canonical()` removes fields that
53do not affect the displayed style, such as an indexed foreground when an RGB
54foreground is active. Canonical styles can also be compared with Go's `==`.
55This lets storage share identical styles without keeping irrelevant differences.
56
57## Exceptional cell data
58
59`core.NewCellPayload(grapheme, hyperlink)` creates a read-only value for
60`Cell.Payload`. It checks UTF-8, rejects terminal control characters and limits
61strings to 128 grapheme bytes and 4,096 hyperlink bytes.
62
63Pages share equal values locally and reclaim entries after overwrite or clear.
64Copies, resize/reflow, snapshots, history and persistence preserve those values.
65Callers never receive internal page handles.
66
67**This is storage support only.** It does not add full grapheme segmentation or
68an OSC 8 hyperlink parser. The VT parser and ANSI renderer still use their
69existing rune-based text behavior.
70
71## Stability and dependencies
72
73vev-vt is v0.x software. APIs and saved-history formats may change without
74compatibility adapters. Check the history guide before updating an application
75that persists terminal state.
76
77There are no third-party production dependencies. `testify` is used by tests.

ownership.md RawHistoryFolder