VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§7Scene model and operations
The scene is a tree of nodes, built and changed only through ops. Layer 1 and layer 2 share the same tree and the same op stream, so a terminal grid and an agent's form can sit side by side.
Nodes
- Every session starts with one node,
root: a vertical stack that fills the display. The server can change its props withpatch. Itstitlenames the window or tab; the VT engine sets it from OSC 0 and 2. - Each node has an ID, a type, a parent, ordered children and props.
- IDs are 1–64 characters from
A–Z a–z 0–9 _ . : -, unique within the session.rootis reserved. - Every node accepts the common props
fallback(plain text shown where the type is unsupported, and used by fallback rendering, Section 18),label(accessible name) andhidden, and the state and accessibility props of Section 9:autofocus,disabled,busy,description,live,lang,dirandpointer_shape. - A node with
template: trueis not rendered itself; it is instantiated per item of a bound array (Section 9).
Ops
| Op | Fields | Effect |
|---|---|---|
open |
id, type, parent (default root), before, props |
Creates a node. If the ID exists with the same type, its props are replaced; with another type, it is an error |
patch |
id, set, unset |
Sets or removes props |
append |
id, text or lines |
Adds content to text, code and log nodes |
rows |
id, rows, at, replace |
Inserts table rows at at (default: the end); replace swaps that many rows instead |
move |
id, parent, before |
Re-parents or reorders a node |
close |
id |
Marks a node complete; clients may drop loading indicators |
remove |
id |
Deletes a node and its descendants |
data |
region, path, value |
Sets a value in a region's data model at a JSON Pointer; without value, deletes it |
cells, fill, scroll, cursor, style, clear |
See Section 8 | Layer 1 grid content |
glyph |
slot, res, cells |
Binds a custom glyph slot to a glyph resource |
focus |
id |
Moves keyboard focus to a node, unless the user moved focus in the last second (Section 9) |
attention |
kind (bell or urgent), id |
Asks for the user's attention: a bell sound or flash, or an urgent mark on the window or tab. The optional id names the node it concerns |
begin, commit |
none | Text form only: group ops into one update |
Rules
- The ops of one update apply in order and render atomically: the client never shows a half-applied update.
- A parent MUST exist before its children are opened.
- An op that fails is skipped. The client reports it with a scene ERROR and continues with the next op, so one bad line costs one node, not the screen.
- Clients check each op against the node types they know. Unknown props are ignored; a node of an unknown type renders its
fallbackand is reported asunknown_type; an unknown op is skipped asinvalid_op; a bad value is skipped asschema; an unknown ID or missing parent isunknown_idorparent_missing.
Text in the scene. Strings in scene ops must not contain C0 control characters other than tab and line feed, nor DEL or C1 controls; an op with one is invalid (schema). Escape sequences reach a terminal only through the VT engine, which turns them into ops. In code, diff and grids, where they could hide what a command does, clients show bidirectional controls and zero-width characters visibly. Copying yields the semantic text, not its rendering.
Extension types. A type of the form prefix:type comes from a catalog that the enclosing region declares under that prefix (Section 9). Such a node must carry fallback and may carry props the core schema does not know. A client without that catalog renders the fallback; a prefix the region does not declare is unknown_type.
Scene frames (channel 1)
| Type | Name | Direction | Payload |
|---|---|---|---|
| 0x10 | UPDATE | S→C | { state: uint, ops: [* op], ? reset: bool, ? more: bool } |
| 0x11 | ACK | C→S | { state: uint } |
| 0x12 | ERROR | C→S | { state, index, code, ? id, ? path, ? message } |
ERROR codes: unknown_id, unknown_type, invalid_op, schema, parent_missing, limit, resource. With reset: true, the client clears the scene back to an empty root before applying the ops.
Large updates. An update larger than max_frame is split over several UPDATE frames with the same state; every part but the last carries more: true. The client applies the whole update atomically when the last part arrives. Reset snapshots are sent the same way. All parts together must stay within the client's max_update (default 1 MiB), reset snapshots included, so the server keeps the whole scene within it; a larger update is limit_exceeded.
Text form. Applications and agents write ops as JSON Lines: UTF-8 JSON (RFC 8259), one op per line, media type application/vnd.vtx.jsonl (to be registered in the vendor tree; file extension .vtxl).
- Ops between
{"op":"begin"}and{"op":"commit"}form one update. Outside a group each line is its own update, and the server MAY merge lines that arrive within one frame interval (about 16 ms). - The server library adds
stateand turns each JSON op into a CBOR map with the same keys and values. JSON numbers with an integral value from −2^64 to 2^64 − 1 become CBOR integers, and all other numbers become floats (Section 3); JSON objects with duplicate names are rejected. Every value survives the round trip, so agents never handle CBOR and clients never parse JSON. vtx-ops-1.schema.json(Appendix) is the producer contract for the core catalog: every line an application or agent writes validates against it. Other catalogs publish their own schemas.
Applications. Applications produce these ops through the application interface (Section 17), which carries them as JSON Lines; the server turns them into UPDATE frames.
{"op":"begin"}
{"op":"open","id":"ops","type":"region","title":"Agent fleet","catalog":"tag:vtx.foundation,2026:vtx/catalog/core/1"}
{"op":"open","id":"agents","type":"table","parent":"ops","cols":[{"key":"name","label":"Agent"},{"key":"state","label":"State","kind":"status"}]}
{"op":"rows","id":"agents","rows":[["build-07","warning"],["index-02","ok"]]}
{"op":"close","id":"agents"}
{"op":"commit"}
On the wire this becomes one UPDATE frame on channel 1, shown in CBOR diagnostic notation:
{"state": 42, "ops": [
{"op": "open", "id": "ops", "type": "region", ...},
{"op": "open", "id": "agents", "type": "table", ...},
{"op": "rows", "id": "agents", "rows": [["build-07", "warning"], ["index-02", "ok"]]},
{"op": "close", "id": "agents"}
]}