NIB / DOCUMENTATION
Protocol scope — NibGenUI
Separate the four wire envelopes from the four built-in widgets.
Open interactive viewFour v0.9.1 envelopes
The adapter accepts version: v0.9.1 with exactly one createSurface, updateComponents, updateDataModel, or deleteSurface body. Unknown envelope fields or versions are rejected. This is a tested subset of A2UI v0.9.1, not full conformance or v0.9/v1 compatibility.
createSurface chooses an exact catalog ID. updateComponents adds or replaces IDs in one surface; it does not erase all old definitions. deleteSurface permits later reuse of an ID, but old packets after reuse cannot be identified because this protocol slice has no sequence number.
| API | Type | Default | Behavior |
|---|---|---|---|
| createSurface | A2UI envelope | — | Creates one surface with an exact catalog ID. |
| updateComponents | A2UI envelope | — | Upserts node IDs; existing definitions not named in the frame remain. |
| updateDataModel | A2UI envelope | — | Writes or removes a value at a JSON Pointer. |
| deleteSurface | A2UI envelope | — | Clears the surface, nodes, and data model. |
Read an envelope from outside to inside
Use this guide after replaying the local fixture. The outer version identifies the wire format. One envelope key identifies the operation. surfaceId selects the runtime surface, and the operation body contains only fields supported for that operation. A JSON object can be syntactically valid while its version, catalog, component or property is invalid for this runtime.
The frame below changes the title in an already-created main surface. It does not define a Text widget. A previously accepted Text with text bound to /title reads the new string. Send the same frame before createSurface and it is rejected because there is no surface to update. This separation lets structure arrive once and data change repeatedly without retransmitting the whole tree.
{
"version": "v0.9.1",
"updateDataModel": {
"surfaceId": "main",
"path": "/title",
"value": "Your draft is ready"
}
}Four Basic Catalog components
NibCatalog.basic() includes Text(text, optional variant), Column(static children IDs), Button(child ID and event action), and TextField(label, optional value and variant). A host can register its own schema and matching trusted Flutter builders; a schema alone does not render a widget.
Forward child references and temporarily missing bound data are legal during incremental construction. The renderer shows a safe placeholder for a missing child. An unknown component, wrong property type, cycle, or shared child is rejected.
| API | Type | Default | Behavior |
|---|---|---|---|
| Text | component | text required | Plain text; variant values are restricted by the Basic schema. |
| Column | component | children required | Static array of child IDs. |
| Button | component | child and action required | Registered event action with one child ID. |
| TextField | component | label required | Local bound editing when value points to a data path. |
Distinguish a missing reference from an invalid tree
A Column may list a child ID before that child’s definition arrives. The renderer shows a placeholder while waiting; a later updateComponents frame can supply the missing definition. Try this by splitting the fixture’s component frame into a root-only frame and a child-definition frame. Increase the fixture’s message budget when adding frames, or its limit will correctly reject your extra operation.
A cycle is different: if a child eventually points back to its ancestor, the completed graph is invalid. This subset also requires one parent per child ID, so two Columns cannot share the same child definition as a reusable subtree. Give each visual instance its own ID. Keeping stable IDs for the same instance helps preserve field state and avoids unnecessary structural replacements.
updateComponents upserts listed IDs. Omitting an old node from the next frame does not delete it. To remove it from view, update the parent’s children or child reference. Detached definitions remain in storage and can be attached later. Deleting the whole surface clears both definitions and data. This is why removing a visible branch and freeing all of its storage are separate operations.
Keep protocol version, catalog ID and Dart package version separate in saved fixtures. The package being 0.0.1 does not change the frame’s v0.9.1 string. A custom catalog name does not grant support for every Basic component. The four accepted envelopes and four built-in components form a useful tested slice; the excluded fields below remain rejected even if another A2UI implementation supports them.
Know the excluded wire features
This catalog does not include resource widgets or URL loading. createSurface.theme, sendDataModel, dynamic child templates, protocol checks, functionCall actions, and Basic Catalog components beyond the four above are outside the supported slice.
A root data replacement currently requires a JSON object, although the upstream envelope allows any JSON value. An omitted updateDataModel value removes a map key; an explicit null stores null. Array removal leaves a null slot because JSON has no undefined value.