Fix JSON fragment

gspencergoog · gspencergoog · commit 437c7e370465 · 2025-10-20T15:10:37.000-07:00
diff --git a/docs/a2ui_protocol.md b/docs/a2ui_protocol.md
@@ -10,7 +10,7 @@ The A2UI (Agent to UI) protocol should be a system where an LLM can stream a pla
 
 ### Requirement: The protocol must be easily generated by a Transformer Large Language Model (LLM)
 
-This is the most critical driver. "LLM-friendliness" is explicitly mentioned. This requirement directly leads to several design choices:
+This is the most critical driver. This requirement directly leads to several design choices:
 
 Declarative, Simple Structure: The protocol should use a straightforward, declarative format ("this is a column with these children") rather than an imperative one ("now, add a column; then, append a text widget to it"). LLMs excel at generating structured, declarative data.
 
@@ -95,14 +95,13 @@ The A2UI protocol is composed of a server-to-client stream describing UI and ind
 1.  **Server Stream:** The server begins sending the JSONL stream over an SSE connection.
 2.  **Client-Side Buffering:** The client receives messages and buffers them:
 
-    - `updateSurface`: Component definitions are stored in a `Map<String, Component>`, organized by `surfaceId`. If a surface doesn't exist, it is created.
+    - `surfaceUpdate`: Component definitions are stored in a `Map<String, Component>`, organized by `surfaceId`. If a surface doesn't exist, it is created.
     - `dataModelUpdate`: The client's internal JSON data model is built or updated.
 
 3.  **Render Signal:** The server sends a `beginRendering` message with the `root` component's ID. This prevents a "flash of incomplete content." The client buffers incoming components and data but waits for this explicit signal before attempting the first render, ensuring the initial view is coherent.
 4.  **Client-Side Rendering:** The client, now in a "ready" state, starts at the `root` component. It recursively walks the component tree by looking up component IDs in its buffer. It resolves any data bindings against the data model and uses its `WidgetRegistry` to instantiate native widgets.
 5.  **User Interaction and Event Handling:** The user interacts with a rendered widget (e.g., taps a button). The client constructs a `userAction` JSON payload, resolving any data bindings from the component's `action.context`. It sends this payload to the server via an A2A message.
-
-6.  **Dynamic Updates:** The server processes the `userAction`. If the UI needs to change in response, the server sends new `updateSurface` and `dataModelUpdate` messages over the original SSE stream. As these arrive, the client updates its component buffer and data model, and the UI re-renders to reflect the changes. The server can also send `deleteSurface` to remove a UI region.
+6.  **Dynamic Updates:** The server processes the `userAction`. If the UI needs to change in response, the server sends new `surfaceUpdate` and `dataModelUpdate` messages over the original SSE stream. As these arrive, the client updates its component buffer and data model, and the UI re-renders to reflect the changes. The server can also send `deleteSurface` to remove a UI region.
 
 ```mermaid
 sequenceDiagram
@@ -112,8 +111,8 @@ sequenceDiagram
     Server->>+Client: SSE Connection (JSONL Stream)
     Client->>Client: 1. Parse JSONL message
     loop Until 'beginRendering'
-        Client->>Client: 2a. Process surfaceUpdate (store components in map for surfaceId)
-        Client->>Client: 2b. Process dataModelUpdate (update data model)
+        Client->>Client: 2a. Process surfaceUpdate
+        Client->>Client: 2b. Process dataModelUpdate
     end
     Client->>Client: 3. Process beginRendering (rootId: 'root', isReady: true)
     Note right of Client: 4. Triggers UI build for a surface
@@ -140,15 +139,15 @@ sequenceDiagram
 The following is a complete, minimal example of a JSONL stream that renders a user profile card.
 
 ```jsonl
-{"updateSurface": {"components": [{"id": "root", "component": {"Column": {"children": {"explicitList": ["profile_card"]}}}}]}}
-{"updateSurface": {"components": [{"id": "profile_card", "component": {"Card": {"child": "card_content"}}}]}}
-{"updateSurface": {"components": [{"id": "card_content", "component": {"Column": {"children": {"explicitList": ["header_row", "bio_text"]}}}}]}}
-{"updateSurface": {"components": [{"id": "header_row", "component": {"Row": {"alignment": "center", "children": {"explicitList": ["avatar", "name_column"]}}}}]}}
-{"updateSurface": {"components": [{"id": "avatar", "component": {"Image": {"url": {"literalString": "[https://www.example.com/profile.jpg)"}}}}]}}
-{"updateSurface": {"components": [{"id": "name_column", "component": {"Column": {"alignment": "start", "children": {"explicitList": ["name_text", "handle_text"]}}}}]}}
-{"updateSurface": {"components": [{"id": "name_text", "component": {"Heading": {"level": "3", "text": {"literalString": "Flutter Fan"}}}}]}}
-{"updateSurface": {"components": [{"id": "handle_text", "component": {"Text": {"text": {"literalString": "@flutterdev"}}}}]}}
-{"updateSurface": {"components": [{"id": "bio_text", "component": {"Text": {"text": {"literalString": "Building beautiful apps from a single codebase."}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "root", "component": {"Column": {"children": {"explicitList": ["profile_card"]}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "profile_card", "component": {"Card": {"child": "card_content"}}}]}}
+{"surfaceUpdate": {"components": [{"id": "card_content", "component": {"Column": {"children": {"explicitList": ["header_row", "bio_text"]}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "header_row", "component": {"Row": {"alignment": "center", "children": {"explicitList": ["avatar", "name_column"]}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "avatar", "component": {"Image": {"url": {"literalString": "[https://www.example.com/profile.jpg)"}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "name_column", "component": {"Column": {"alignment": "start", "children": {"explicitList": ["name_text", "handle_text"]}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "name_text", "component": {"Heading": {"level": "3", "text": {"literalString": "Flutter Fan"}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "handle_text", "component": {"Text": {"text": {"literalString": "@flutterdev"}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "bio_text", "component": {"Text": {"text": {"literalString": "Building beautiful apps from a single codebase."}}}}]}}
 {"dataModelUpdate": {"contents": {}}}
 {"beginRendering": {"root": "root"}}
 ```
@@ -159,9 +158,9 @@ A2UI's component model is designed for flexibility, separating the protocol from
 
 ### 2.1. The Catalog: Defining Components
 
-Unlike previous versions with a fixed component set, A2UI now defines components in a **Catalog**. A catalog is a schema that defines the available component types (e.g., `Row`, `Text`) and their supported properties. This allows for different clients to support different sets of components, including custom ones. The server must generate `updateSurface` messages that conform to the component catalog understood by the client. Clients can inform the server of the catalog they support using the `clientUiCapabilities` message.
+Unlike previous versions with a fixed component set, A2UI now defines components in a **Catalog**. A catalog is a schema that defines the available component types (e.g., `Row`, `Text`) and their supported properties. This allows for different clients to support different sets of components, including custom ones. The server must generate `surfaceUpdate` messages that conform to the component catalog understood by the client. Clients can inform the server of the catalog they support using the `clientUiCapabilities` message.
 
-### 2.2. The `updateSurface` Message
+### 2.2. The `surfaceUpdate` Message
 
 This message is the primary way UI structure is defined. It contains a `surfaceId` and a `components` array.
 
@@ -430,30 +429,40 @@ This message provides a feedback mechanism for the server. It is sent when the c
 
 ### 5.5. Event Flow Example (`userAction`)
 
-1.  **Component Definition** (from `updateSurface`):
+1.  **Component Definition** (from `surfaceUpdate`):
 
     ```json
     {
-      "id": "submit_btn_text",
-      "component": {
-        "Text": {
-          "text": { "literalString": "Submit" }
-        }
-      }
-    },
-    {
-      "id": "submit_btn",
-      "component": {
-        "Button": {
-          "child": "submit_btn_text",
-          "action": {
-            "name": "submit_form",
-            "context": [
-              { "key": "userInput", "value": { "path": "form.textField" } },
-              { "key": "formId", "value": { "literalString": "f-123" } }
-            ]
+      "surfaceUpdate": {
+        "surfaceId": "main_content_area",
+        "components": [
+          {
+            "id": "submit_btn_text",
+            "component": {
+              "Text": {
+                "text": { "literalString": "Submit" }
+              }
+            }
+          },
+          {
+            "id": "submit_btn",
+            "component": {
+              "Button": {
+                "child": "submit_btn_text",
+                "action": {
+                  "name": "submit_form",
+                  "context": [
+                    {
+                      "key": "userInput",
+                      "value": { "path": "form.textField" }
+                    },
+                    { "key": "formId", "value": { "literalString": "f-123" } }
+                  ]
+                }
+              }
+            }
           }
-        }
+        ]
       }
     }
     ```
@@ -462,8 +471,11 @@ This message provides a feedback mechanism for the server. It is sent when the c
 
     ```json
     {
-      "form": {
-        "textField": "User input text"
+      "dataModelUpdate": {
+        "surfaceId": "main_content_area",
+        "form": {
+          "textField": "User input text"
+        }
       }
     }
     ```
@@ -487,7 +499,7 @@ This message provides a feedback mechanism for the server. It is sent when the c
     }
     ```
 
-6.  **Server Response:** The server processes this event. If the UI needs to change as a result, the server sends new `updateSurface` or `dataModelUpdate` messages over the **separate SSE stream**.
+6.  **Server Response:** The server processes this event. If the UI needs to change as a result, the server sends new `surfaceUpdate` or `dataModelUpdate` messages over the **separate SSE stream**.
 
 ## Section 6: Client-Side Implementation
 
diff --git a/docs/proposals/v0_8.md b/docs/proposals/v0_8.md
@@ -91,7 +91,7 @@ We will update the standard catalog in the following ways:
 
 The schema adapter is an agent-side utility that can accept a custom widget catalog and convert it to a schema which allows the LLM to generate `surfaceUpdate` messages for a particular catalog reliably.
 
-The most simple adapter, which will work for Gemini and other common LLMs, will simply take the “components” from a “Catalog description object” and paste it into `updateSurface.components.componentProperties` and takes the “styles” and pastes them into `beginRendering.styles`. This creates a new schema which includes the detailed widget catalog, and can be passed to the LLM. This schema should be almost identical in structure to a v0.7 A2UI schema. This schema is a strict subset of the more generic v0.8 “Server-to-Client Protocol Schema” and thus messages generated this way do formally conform to the protocol spec.
+The most simple adapter, which will work for Gemini and other common LLMs, will simply take the “components” from a “Catalog description object” and paste it into `surfaceUpdate.components.componentProperties` and takes the “styles” and pastes them into `beginRendering.styles`. This creates a new schema which includes the detailed widget catalog, and can be passed to the LLM. This schema should be almost identical in structure to a v0.7 A2UI schema. This schema is a strict subset of the more generic v0.8 “Server-to-Client Protocol Schema” and thus messages generated this way do formally conform to the protocol spec.
 
 ## Detailed design
 
@@ -300,7 +300,7 @@ To simplify the generation of UIs, especially for LLMs, we propose a shorthand f
 Currently, to display a dynamic value that has a default, the server must send two separate messages:
 
 1. A `dataModelUpdate` message to set the initial value in the data model.
-2. An `updateSurface` message with a component that has a property bound to that data model path.
+2. An `surfaceUpdate` message with a component that has a property bound to that data model path.
 
 The proposed shorthand combines these two steps. When a component property that accepts a `BoundValue` (e.g., `text`, `value`) is defined with _both_ a `path` and a `literal*` value (e.g., `literalString`), it should be interpreted as follows:
 
@@ -313,14 +313,14 @@ Instead of sending two messages:
 
 ```json
 {"dataModelUpdate": {"path": "form.name", "contents": "John Doe"}}
-{"updateSurface": {"components": [{"id": "name_field", "componentProperties": {"TextField": {"text": {"path": "form.name"}}}}]}}
+{"surfaceUpdate": {"components": [{"id": "name_field", "componentProperties": {"TextField": {"text": {"path": "form.name"}}}}]}}
 ```
 
 The server can send a single message:
 
 ```json
 {
-  "updateSurface": {
+  "surfaceUpdate": {
     "components": [
       {
         "id": "name_field",
