vtx.foundation draft d03

VTX 1 · core · beta draft d03

VTX 1 Wire Specification: core

Oct 11, 2026, revised Nov 16, 202639 pagesALPN vtx1-d03MIT licence

§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 with patch. Its title names 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. root is 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) and hidden, and the state and accessibility props of Section 9: autofocus, disabled, busy, description, live, lang, dir and pointer_shape.
  • A node with template: true is 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 fallback and is reported as unknown_type; an unknown op is skipped as invalid_op; a bad value is skipped as schema; an unknown ID or missing parent is unknown_id or parent_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 state and 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"}
]}