VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§9Layer 2: components, data model and intents
Applications describe what a component is; the client decides how it looks. The v1 catalog is tag:vtx.foundation,2026:vtx/catalog/core/1 (a tag URI, RFC 4151). The client offers it in the components capability, and a server MUST NOT open component types outside the accepted catalogs.
Regions. A region node holds layer 2 content and its own data model. Every component sits inside a region, and a binding resolves against the nearest enclosing region. A region corresponds to an A2UI surface. Props:
title;catalog: the URI of the catalog its plain type names come from; without it, the core catalogtag:vtx.foundation,2026:vtx/catalog/core/1;catalogs: a map from prefix to catalog URI, for types writtenprefix:type(Section 7);send_data: whentrue, intents carry the region's whole data model.
A server uses only catalogs the client accepted in its components capability. Catalog URIs are immutable: a changed catalog gets a new URI, and declares the one it builds on in extends, so a client that knows the older catalog still renders the types they share. The core catalog also lists the icon names that icon accepts.
Data model and bindings
- Each region has a JSON value, initially
{}. Thedataop writes into it at a JSON Pointer (RFC 6901): a missing member is created, missing parents are created as objects,-as the last token appends to an array, and a write below a value that is neither object nor array is skipped asschema. Withoutvaluethe member is removed; removing an array element shifts the later elements down. - Props marked dynamic accept a literal, a binding
{"bind": "/agents/0/name"}, or a formatter{"fn": …}. - Input components bind two ways. The client writes user edits into the model at once, re-renders everything bound to it, and sends nothing until an intent fires.
- A container with
each: { path, template }repeats its template node once per item of the array atpath. Inside a template, a binding without a leading/is relative to the item. - Template instances get IDs of the form
node#index, one#indexper template level, such aspage#1. These IDs appear in input targets, intents and scene errors; the server addresses the template itself.
Core catalog
| Type | Key props | Fallback rendering |
|---|---|---|
stack |
dir v/h, gap 0–4, align, justify, wrap, each |
Children in order; horizontal children joined by two spaces |
split |
dir, sizes |
Children stacked vertically |
group |
title, style plain/card |
Title line, then children indented |
tabs, tab |
selected; tab: title |
Tab titles on one line, the selected tab's content below |
divider |
axis |
A line of ─ |
overlay |
modal, title, dismiss |
Framed block after the content |
text |
text (dynamic, inline Markdown), role, size |
Plain text; links as text <url> |
heading |
text, level 1–3 |
Text, underlined at levels 1–2 |
markdown |
text (dynamic): CommonMark with tables; no images, no raw HTML |
The Markdown source, wrapped to width |
log |
lines, max, follow |
Lines as-is |
code, diff |
text, lang |
Verbatim |
kv |
items [[key, value]] |
Aligned key: value lines |
table |
cols, rows, key, sort, select, activate, each |
Aligned columns under a header, truncated to width |
tree, item |
item: label, icon, open |
Indented with ├─ and └─ |
list |
each |
One - line per child |
progress |
value 0–1 or null, label |
[#####-----] 50% label |
status |
state ok/info/warning/critical/pending, text |
[ OK ], [INFO], [WARN], [CRIT] or [WAIT] by state, then the text |
chart |
kind line/bar/spark, x, series |
One sparkline per series with its range |
icon |
name |
Its label, if any |
form |
submit, cancel (intent names) |
Fields as prompts, one after another |
input |
kind text/password/number/email/multiline, label, bind, placeholder, checks |
label: prompt |
choice |
label, options, multi, style radio/dropdown/chips, bind, checks |
Numbered options |
checkbox |
label, bind |
[x] label, toggled by y/n |
range |
label, min, max, step, bind |
Number prompt with its bounds |
datetime |
label, mode date/time/datetime, bind, checks |
Prompt with an ISO 8601 hint |
action |
label, intent, role primary/secondary/danger, context |
Numbered menu entry |
Table columns are { key, label, kind, align }; kind is text, number, status, progress or spark. A table's key names the column whose value identifies a row. A table's bind binds its selection two ways: as an array of key values when the table has a key, otherwise as an array of row indices in the order the rows were sent. An activated row's INTENT carries key as well as row. role on text is one of the semantic colour roles (Section 8). Inline Markdown in text means CommonMark emphasis, strong emphasis, code spans and links (https, http, mailto) only: no images, no raw HTML, no blocks; the markdown component takes blocks and tables too. Links in either open through the trusted zone (Section 12). Exact prop types are in vtx-ops-1.schema.json.
States and accessibility.
disabledshows a control as unavailable and ignores input.busyshows a control or region at work and holds back its intents.readonly(oninput,choice,checkbox,rangeanddatetime) shows a value that can be copied but not changed.errorshows a message with a control and marks it invalid.labelis the accessible name;descriptionadds a longer accessible description.livemakes a node a live region:politechanges are announced when the user is idle,assertiveones at once. Alogis a polite live region by default, andstatusandprogressannounce changes of state. Servers useassertiveonly for critical states.- An
overlaywithmodal: trueis a dialog. Achartis exposed to assistive technology as a table of its data, and a grid as a terminal document. - Clients map component roles to the platform's accessibility API: ARIA in browsers, UI Automation on Windows, NSAccessibility on macOS and iOS, AccessibilityNodeInfo on Android and AT-SPI on Linux.
langanddirset the language and direction of a node's text and its descendants;pointer_shapesets the pointer over a node.
Checks run on the client before submit, and the application MUST validate again: required; regex with pattern; length with min/max; numeric with min/max; email. Each may carry a message.
Formatters use the session locale: formatString (template, args), formatNumber (value, decimals), formatCurrency (value, currency as ISO 4217), formatDate (value, style) and pluralize (count, and a string per CLDR plural category: zero, one, two, few, many, other). The function names match A2UI's.
Exact semantics.
- Templates fill
{name}placeholders fromargs, andpluralizestrings fill{count};{{and}}stand for literal braces. pluralizepicks the category from the CLDR rules of the region's language (itslang, else the session locale).otheris required and used for any category not given.regexuses I-Regexp (RFC 9485) and must match the whole value.lengthcounts grapheme clusters.emailaccepts an RFC 5321 Mailbox.- Number inputs and ranges write JSON numbers to the data model; an empty text field writes
"". datetimevalues are RFC 3339 strings: full-date indatemode, partial-time intimemode, and a date-time with an offset indatetimemode. The client shows them in the time zone from HELLO or CAPS;formatDatetakes the same strings.
Focus. Keyboard focus and Tab order are handled by the client, in document order. Initial focus goes to the first node with autofocus, else the first grid with keys: raw, else the first control. A modal overlay keeps focus inside itself until it closes. The client follows a focus op unless the user moved focus in the last second, and reports focus changes with FOCUS (Section 11).
Intents. When the user activates an action, submits a form or activates a table row, the client sends an INTENT on the input channel:
{"intent":"deploy","source":"deploy","region":"ops","values":{"env":"production","note":"hotfix 2.4.1"},"seq":3,"seen":42}
| Field | Meaning |
|---|---|
intent |
The intent name from the component |
source |
ID of the component that fired it. An action whose intent equals its form's submit or cancel acts for the form: the source is the form's ID, and a submit carries values. Inside a template, the instance ID |
region |
Its region |
context |
The action's context, with bindings resolved |
values |
For forms: each field's ID mapped to its value |
row |
For table activation: the row's index in the order the rows were sent, not as the client sorted them |
key |
For table activation, when the table has a key: the row's value in that column |
data |
The region's data model, when send_data is set |
seq |
Input sequence number, for delivery across resumes (Section 6) |
more |
true when the intent is too large for one frame and continues in the next INTENT with the same seq; the server joins the parts' values and data before delivering |
seen |
The last applied scene state (Section 6) |
Applications receive intents in the same JSON form, validated by vtx-intent-1.schema.json. An agent therefore gets typed, validated input rather than raw events to interpret.