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

§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 catalog tag:vtx.foundation,2026:vtx/catalog/core/1;
  • catalogs: a map from prefix to catalog URI, for types written prefix:type (Section 7);
  • send_data: when true, 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 {}. The data op 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 as schema. Without value the 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 at path. Inside a template, a binding without a leading / is relative to the item.
  • Template instances get IDs of the form node#index, one #index per template level, such as page#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.

  • disabled shows a control as unavailable and ignores input. busy shows a control or region at work and holds back its intents. readonly (on input, choice, checkbox, range and datetime) shows a value that can be copied but not changed. error shows a message with a control and marks it invalid.
  • label is the accessible name; description adds a longer accessible description.
  • live makes a node a live region: polite changes are announced when the user is idle, assertive ones at once. A log is a polite live region by default, and status and progress announce changes of state. Servers use assertive only for critical states.
  • An overlay with modal: true is a dialog. A chart is 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.
  • lang and dir set the language and direction of a node's text and its descendants; pointer_shape sets 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 from args, and pluralize strings fill {count}; {{ and }} stand for literal braces.
  • pluralize picks the category from the CLDR rules of the region's language (its lang, else the session locale). other is required and used for any category not given.
  • regex uses I-Regexp (RFC 9485) and must match the whole value. length counts grapheme clusters. email accepts an RFC 5321 Mailbox.
  • Number inputs and ranges write JSON numbers to the data model; an empty text field writes "".
  • datetime values are RFC 3339 strings: full-date in date mode, partial-time in time mode, and a date-time with an offset in datetime mode. The client shows them in the time zone from HELLO or CAPS; formatDate takes 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.