Wire messages: decode raw agent→renderer payloads into canonical
A2UICore.Message.Operation structs, and encode operations back to
wire-format maps.
decode/2 accepts everything the transport contract allows — a
single message map, a bare JSON array of messages, a
{"messages": [...]} wrapper, or nil (no-op):
{:ok, ops} = A2UICore.Message.decode(payload)Decoding runs the full reference pipeline: payload sniffing
(A2UICore.Message.AdapterRegistry), recursion/pointer preflight
(A2UICore.Validation.Integrity), per-version envelope validation
against the vendored spec schemas with the active catalog bound to
the catalog.json placeholder, and canonical operation extraction
(A2UICore.Message.Adapter).
Options
:catalog— the active catalog schema map for component validation (defaults to the shipped basic catalog of the message's protocol version).
Examples
iex> {:ok, [%A2UICore.Message.Operation.UpdateDataModel{} = op]} =
...> A2UICore.Message.decode(%{
...> "version" => "v1.0",
...> "updateDataModel" => %{"surfaceId" => "main", "value" => %{"user" => "Ada"}}
...> })
iex> {op.path, op.value}
{"/", %{"user" => "Ada"}}Summary
Functions
Decodes a raw payload into canonical operations.
Like decode/2, raising A2UICore.Error on failure.
Encodes canonical operations back into wire-format message maps.
Types
@type opts() :: keyword()
Decode options (see module docs).
Functions
@spec decode(term(), opts()) :: {:ok, [A2UICore.Message.Operation.t()]} | {:error, A2UICore.Error.t()}
Decodes a raw payload into canonical operations.
Returns {:ok, operations} or {:error, %A2UICore.Error{}} (always
category :validation for wire problems).
nil is a no-op ({:ok, []}) — matching the TypeScript processor
and the reference adapter's own tolerance. (The Python factory
rejects nil instead; we choose the lenient behaviour, and the
registry retains the strict one for direct callers.)
@spec decode!(term(), opts()) :: [A2UICore.Message.Operation.t()]
Like decode/2, raising A2UICore.Error on failure.
@spec encode( A2UICore.Message.Operation.t() | [A2UICore.Message.Operation.t()], keyword() ) :: map() | [map()]
Encodes canonical operations back into wire-format message maps.
overrides may pass :version to force a wire version (e.g.
"v0.9.1" instead of "v0.9"). Without it, createSurface and the
function-call operations use the version they carry, and
updateComponents, updateDataModel and deleteSurface, which carry
none, are encoded as "v0.9".
iex> A2UICore.Message.encode(
...> %A2UICore.Message.Operation.DeleteSurface{surface_id: "main"},
...> version: "v1.0"
...> )
%{"version" => "v1.0", "deleteSurface" => %{"surfaceId" => "main"}}