Merge branch 'main' into fix/lit-multiple-choice-binding

Author: shantoislamdev

.geminiignore

@@ -0,0 +1,4 @@
+# Ignore large lock files that aren't useful for context
+**/pnpm-lock.yaml
+**/package-lock.json
+**/uv.lock

specification/v0_9/docs/a2ui_extension_specification.md

@@ -21,8 +21,8 @@ Catalog Definition Document: The a2ui extension is catalog-agnostic. All UI comp
 Schemas: The a2ui extension is defined by several primary JSON schemas:
 
 - Catalog Definition Schema: A standard format for defining a library of components and functions.
-- Server-to-Client Message Schema: The core wire format for messages sent from the agent to the client (e.g., updateComponents, updateDataModel).
-- Client-to-Server Event Schema: The core wire format for messages sent from the client to the agent (e.g., action).
+- Server-to-Client Message List Schema: The core wire format for messages sent from the agent to the client (e.g., updateComponents, updateDataModel).
+- Client-to-Server Message List Schema: The core wire format for messages sent from the client to the agent (e.g., action).
 - Client Capabilities Schema: The schema for the `a2uiClientCapabilities` object.
 
 Client Capabilities: The client sends its capabilities to the server in an `a2uiClientCapabilities` object. This object is included in the `metadata` field of every A2A `Message` sent from the client to the server. This object allows the client to declare which catalogs it supports.
@@ -69,28 +69,47 @@ To identify a `DataPart` as containing A2UI data, it must have the following met
 
 - `mimeType`: `application/json+a2ui`
 
-The `data` field of the `DataPart` contains a **single** A2UI JSON message (e.g., `createSurface`, `updateComponents`, `action`). It MUST NOT be an array of messages.
+The `data` field of the `DataPart` contains a **list** of A2UI JSON messages (e.g., `createSurface`, `updateComponents`, `action`). It MUST be an array of messages.
 
-### Atomicity and multiple messages
+### Processing Rules
 
-To send multiple A2UI messages that should be processed atomically (e.g., creating a surface and immediately populating it), the sender MUST include multiple `DataPart`s within a single A2A `Message`.
+The `data` field contains a list of messages. This list is **NOT** a transactional unit. Receivers (both Clients and Agents) MUST process messages in the list sequentially.
 
-Receivers (both Clients and Agents) MUST process all A2UI `DataPart`s within a single A2A `Message` sequentially and atomically. For a renderer, this means the UI should not be repainted until all parts in the message have been applied.
+If a single message in the list fails to validate or apply (e.g., due to a schema violation or invalid reference), the receiver SHOULD report/log the error for that specific message and MUST continue processing the remaining messages in the list.
+
+Atomicity is guaranteed only at the **individual message** level. However, for a better user experience, a renderer SHOULD NOT repaint the UI until all messages in the list have been processed. This prevents intermediate states from flickering to the user.
 
 ### Server-to-client messages
 
-When an agent sends a message to a client (or another agent acting as a client/renderer), the `data` payload must validate against the **Server-to-Client Message Schema**.
+When an agent sends a message to a client (or another agent acting as a client/renderer), the `data` payload must validate against the **Server-to-Client Message List Schema**.
 
-Example `createSurface` DataPart:
+Example DataPart:
 
 ```json
 {
-  "data": {
-    "createSurface": {
-      "surfaceId": "user_profile_surface",
-      "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json"
+  "data": [
+    {
+      "version": "v0.9",
+      "createSurface": {
+        "surfaceId": "example_surface",
+        "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json"
+      }
+    },
+    {
+      "version": "v0.9",
+      "updateComponents": {
+        "surfaceId": "example_surface",
+        "components": [
+          {
+            "Text": {
+              "id": "root",
+              "text": "Hello!"
+            }
+          }
+        ]
+      }
     }
-  },
+  ],
   "kind": "data",
   "metadata": {
     "mimeType": "application/json+a2ui"
@@ -100,23 +119,26 @@ Example `createSurface` DataPart:
 
 ### Client-to-server events
 
-When a client (or an agent forwarding an event) sends a message to an agent, it also uses a `DataPart` with the same `application/json+a2ui` MIME type. However, the `data` payload must validate against the **Client-to-Server Event Schema**.
+When a client (or an agent forwarding an event) sends a message to an agent, it also uses a `DataPart` with the same `application/json+a2ui` MIME type. However, the `data` payload must validate against the **Client-to-Server Message List Schema**.
 
 Example `action` DataPart:
 
 ```json
 {
-  "data": {
-    "action": {
-      "name": "submit_form",
-      "surfaceId": "contact_form_1",
-      "sourceComponentId": "submit_button",
-      "timestamp": "2026-01-15T12:00:00Z",
-      "context": {
-        "email": "user@example.com"
+  "data": [
+    {
+      "version": "v0.9",
+      "action": {
+        "name": "submit_form",
+        "surfaceId": "contact_form_1",
+        "sourceComponentId": "submit_button",
+        "timestamp": "2026-01-15T12:00:00Z",
+        "context": {
+          "email": "user@example.com"
+        }
       }
     }
-  },
+  ],
   "kind": "data",
   "metadata": {
     "mimeType": "application/json+a2ui"

specification/v0_9/docs/a2ui_protocol.md

@@ -189,6 +189,7 @@ This message signals the client to create a new surface and begin rendering it.
 
 ```json
 {
+  "version": "v0.9",
   "createSurface": {
     "surfaceId": "user_profile_card",
     "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
@@ -213,6 +214,7 @@ This message provides a list of UI components to be added to or updated within a
 
 ```json
 {
+  "version": "v0.9",
   "updateComponents": {
     "surfaceId": "user_profile_card",
     "components": [
@@ -250,6 +252,7 @@ This message is used to send or update the data that populates the UI components
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "user_profile_card",
     "path": "/user/name",
@@ -270,6 +273,7 @@ This message instructs the client to remove a surface and all its associated com
 
 ```json
 {
+  "version": "v0.9",
   "deleteSurface": {
     "surfaceId": "user_profile_card"
   }
@@ -281,10 +285,10 @@ This message instructs the client to remove a surface and all its associated com
 The following example demonstrates a complete interaction to render a Contact Form, expressed as a JSONL stream.
 
 ```jsonl
-{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.org/specification/v0_9/standard_catalog.json"}}
-{"updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","args":{"value":{"path":"/contact/email"}},"message":"Email is required."},{"call":"email","args":{"value":{"path":"/contact/email"}},"message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"value":{"path":"/contact/phone"},"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","variant":"primary","action":{"event":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","args":{},"returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}}]}}
-{"updateDataModel":{"surfaceId":"contact_form_1","path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true}}}
-{"deleteSurface":{"surfaceId":"contact_form_1"}}
+{"version": "v0.9", "createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.org/specification/v0_9/standard_catalog.json"}}
+{"version": "v0.9", "updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","args":{"value":{"path":"/contact/email"}},"message":"Email is required."},{"call":"email","args":{"value":{"path":"/contact/email"}},"message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"value":{"path":"/contact/phone"},"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","variant":"primary","action":{"event":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","args":{},"returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}}]}}
+{"version": "v0.9", "updateDataModel":{"surfaceId":"contact_form_1","path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true}}}
+{"version": "v0.9", "deleteSurface":{"surfaceId":"contact_form_1"}}
 ```
 
 ## Component model
@@ -531,6 +535,7 @@ _Update a specific field:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "path": "/user/firstName",
@@ -543,6 +548,7 @@ _Remove a field:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "path": "/user/tempData"
@@ -554,6 +560,7 @@ _Replace the entire data model:_
 
 ```json
 {
+  "version": "v0.9",
   "updateDataModel": {
     "surfaceId": "surface_123",
     "value": {

specification/v0_9/docs/evolution_guide.md

@@ -103,6 +103,7 @@ Version 0.9 represents a fundamental philosophical shift from "Structured Output
 
 ```json
 {
+  "version": "v0.9",
   "createSurface": {
     "surfaceId": "user_profile_card",
     "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
@@ -155,6 +156,7 @@ Specifying an unknown surfaceId will cause an error. It is recommended that clie
 
 ```json
 {
+  "version": "v0.9",
   "updateComponents": {
     "surfaceId": "main",
     "components": [

specification/v0_9/eval/src/generation_flow.ts

@@ -56,6 +56,7 @@ Standard Instructions:
 13. Do NOT use a 'style' property. Use standard properties like 'align', 'justify', 'variant', etc.
 14. Do NOT invent properties that are not in the schema. Check the 'properties' list for each component type.
 15. Use 'checks' property for validation rules if required.
+16. EVERY message object MUST include the property "version": "v0.9" at the top level.
 ${catalogRules ? `\nInstructions specific to this catalog:\n${catalogRules}` : ""}
 
 Schemas:

specification/v0_9/json/a2ui_client_capabilities.json

@@ -5,18 +5,25 @@
   "description": "A schema for the a2uiClientCapabilities object, which is sent from the client to the server as part of the A2A metadata to describe the client's UI rendering capabilities.",
   "type": "object",
   "properties": {
-    "supportedCatalogIds": {
-      "type": "array",
-      "description": "The URI of each of the component and function catalogs that is supported by the client.",
-      "items": { "type": "string" }
-    },
-    "inlineCatalogs": {
-      "type": "array",
-      "description": "An array of inline catalog definitions, which can contain both components and functions. This should only be provided if the agent declares 'acceptsInlineCatalogs: true' in its capabilities.",
-      "items": { "$ref": "#/$defs/Catalog" }
+    "v0.9": {
+      "type": "object",
+      "description": "The capabilities structure for version 0.9 of the A2UI protocol.",
+      "properties": {
+        "supportedCatalogIds": {
+          "type": "array",
+          "description": "The URI of each of the component and function catalogs that is supported by the client.",
+          "items": { "type": "string" }
+        },
+        "inlineCatalogs": {
+          "type": "array",
+          "description": "An array of inline catalog definitions, which can contain both components and functions. This should only be provided if the agent declares 'acceptsInlineCatalogs: true' in its capabilities.",
+          "items": { "$ref": "#/$defs/Catalog" }
+        }
+      },
+      "required": ["supportedCatalogIds"]
     }
   },
-  "required": ["supportedCatalogIds"],
+  "required": ["v0.9"],
   "$defs": {
     "FunctionDefinition": {
       "type": "object",

specification/v0_9/json/a2ui_client_data_model.json

@@ -5,6 +5,9 @@
   "description": "Schema for attaching the client data model to A2A message metadata. This object should be placed in the `a2uiClientDataModel` field of the metadata.",
   "type": "object",
   "properties": {
+    "version": {
+      "const": "v0.9"
+    },
     "surfaces": {
       "type": "object",
       "description": "A map of surface IDs to their current data models.",
@@ -14,6 +17,6 @@
       }
     }
   },
-  "required": ["surfaces"],
+  "required": ["version", "surfaces"],
   "additionalProperties": false
 }

specification/v0_9/json/client_to_server.json

@@ -2,9 +2,12 @@
   "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
   "description": "Describes a JSON payload for a client-to-server event message.",
   "type": "object",
-  "minProperties": 1,
-  "maxProperties": 1,
+  "minProperties": 2,
+  "maxProperties": 2,
   "properties": {
+    "version": {
+      "const": "v0.9"
+    },
     "action": {
       "type": "object",
       "description": "Reports a user-initiated action from a component.",
@@ -92,10 +95,10 @@
   },
   "oneOf": [
     {
-      "required": ["action"]
+      "required": ["action", "version"]
     },
     {
-      "required": ["error"]
+      "required": ["error", "version"]
     }
   ]
 }

specification/v0_9/json/client_to_server_list.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://a2ui.org/specification/v0_9/client_to_server_list.json",
+  "title": "A2UI Client-to-Server Message List",
+  "description": "A list of A2UI Client-to-Server messages.",
+  "type": "array",
+  "items": {
+    "$ref": "client_to_server.json"
+  }
+}