GenerativeUiInterfaceUpdateSurfaceMessage
HTTP API schema
Change the surface that is on screen, in place. Send many small updates rather than one large one; the target is under 300 ms from the call to the frame on screen while the device is connected. Shape: `surfaceId` is the surface shown by show-surface; `a2ui` is a list of A2UI v1.0 `updateComponents` (add or replace components by id, replacing a component whole) and `updateDataModel` (set a value at a JSON Pointer path; a null value deletes it) messages. To remove a component, replace its parent without it. A Timer ticks on the device, so one message starts it; do not update it every second. Example, changing one line of text: ```json {"surfaceId": "hello", "a2ui": [ {"version": "1.0", "updateComponents": {"surfaceId": "hello", "components": [{"id": "body", "component": "Text", "text": "Dinner is ready."}]}}]} ``` Completion: accepted means the gateway took the message, not that it is on screen. Each accepted show-surface, update-surface or close-surface gets the next sequence for its surface and the device applies them in that order, with no gaps and no duplicates, across reconnects. Two calls made concurrently may apply in either order. No ordering across surfaces or with other interfaces (for example play-media). get-surface returns the last applied sequence, so you can tell whether your latest update is on screen. Refused with BAD_REQUEST when a message targets another surface or uses an unsupported component or property (the error names it). Refused with a conflict when `surfaceId` is not the surface Port OS holds for the device; send show-surface instead. If the surface log grows past 1 MiB the call is refused and you must send a fresh show-surface. One call carries at most the device's `maxPayloadBytes` of A2UI; images are URLs, never inline data. See show-surface for the full usage order and for what is not supported.
GenerativeUiInterfaceUpdateSurfaceMessage fields
- surfaceId
stringRequired The surface to change.
minLength: 1
maxLength: 128
pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
- a2ui
array<GenerativeUiA2uiMessage>Required A2UI v1.0 `updateComponents` and `updateDataModel` messages for the surface.