For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/genui/a2ui/protocol-1.0-audit.md.
This is the dev preview website. Check out the document at lynx-stack.dev
  • English

      • A2UI 1.0 migration audit

      English | 简体中文

      This audit compares the six migration commits from c118dd9fd through 9f8404e0a, including their tests, generated catalogs, prompts, examples, transport adapters, and documentation, with the official specification at 24d1bf9c830071f74c9c908433e73cc6cbe0aa33. The upstream version registry marks 1.0 as current. The previous branch pinned 1c45c809b655878d06e3afc6dda22100afecc0a4.

      Changes from the previous branch contract

      AreaPrevious branchCurrent contract and implementation
      Wire version"v1.0""1.0" in both directions, metadata, examples, and prompts. Old and missing versions are rejected.
      Dynamic valuespath, call@path, @call. Plain keys remain literal data. @@ escapes one leading @; unknown directives fail.
      Component envelopecatalogId, metadata, accessibility, checks@catalogId, @metadata, @accessibility, @checks. Surface and function catalogId, ChildList path, and updateDataModel path remain bare.
      Renderer RPCNo data-model scopeOptional surfaceId; omitted scope is an isolated empty model. Invalid scope or permissions produces a correlated rendererFunctionResponse.
      Function executionIncomplete permission and schema handlingEnforce allowedCallers, requiresUserActivation, resolved argument validation, and defaults. Schema-only functions can route to the Agent. Actions await nested asynchronous results and make fresh calls.
      FailuresSome failures silently became undefined or timed outDynamic failures become null; routed errors identify functionCallId, local errors identify surfaceId. Transport rejection ends pending RPCs.
      ValidationMixed Boolean and ValidationResult behaviorApply explicit DynamicBoolean coercion. Preserve optional CheckRule.message, result message precedence, code, and severity.
      Interpolation and regexOlder Web function dependencyLocal implementations; interpolation inherits the enclosing function catalog and resolves @index. Regex uses the portable dialect, static safety analysis, Unicode code points, and absolute end anchors.
      CatalogsOlder function/envelope schemasCurrent discriminators and relative common-type references. Preserve user activation declarations; reject the reserved Surface component name; enforce composition constraints.
      SnapshotsSerialized renderer clone contextsPreserve wire templates and metadata. Internal clone IDs and data contexts are not serialized as component props.
      PlaygroundClick-only transportForward protocol messages and renderer data-model metadata. Validate all local and gallery messages against pinned schemas and the generated Lynx catalog.

      Walkthrough by implementation area

      • src/store: lifecycle, JSON subtree updates, catalog lookup, expressions, template expansion, RPC correlation, asynchronous values, and composition constraints. Internal beginRendering/surfaceUpdate resource names are not accepted wire operations and do not provide 0.9 compatibility.
      • src/react and src/catalog: actions, validation, qualified components, accessibility attributes, and catalog serialization. Checks and actions remain unevaluated until their own execution boundary. The old Modal field aliases and wrapped template-child fallback were removed.
      • src/functions: 14 official basic functions plus 11 explicitly declared Lynx utilities. The utilities are custom catalog entries, not support for an old protocol. The 0.9 Web SDK dependency was removed. Function schemas and regex analysis are pinned to the same upstream revision as the protocol fixtures.
      • src/snapshot: retain typed data, deletion semantics, reachable component definitions, collection templates, and surface extension metadata.
      • a2ui-catalog-extractor: emit component/function discriminators, reference types, and catalog union definitions; update schema fixtures and documentation.
      • server/agent/a2ui: current prompts, messages, catalog data, common types, source guards, streaming validation, and composition checks. Strict envelope parsing rejects removed fields such as protocol-level theme.
      • server/app/a2ui: validate renderer envelopes independently of HTTP options; preserve JSON/SSE RPC responses and action metadata. The stateless service acknowledges surface-independent renderer feedback without inventing a surface.
      • playground, CLI templates, and examples: current wire keys and catalog IDs, valid component identifiers, visible protocol failures, and RPC forwarding. Gallery media examples use supported link actions instead of advertising unavailable AudioPlayer/Video renderers.
      • Bench adapters and runner: protocol version, message extraction, source guards, and replay fixtures use the same contract; evaluation behavior is unchanged.

      Scope and host responsibilities

      The published catalog is the Lynx catalog, not an assertion that every component in the official basic catalog has a native implementation. Agent functions are not installed in the GenUI service; unsupported calls return UNKNOWN_FUNCTION. Hosts can register trusted implementations. No remote code or catalog references are fetched by the client expression evaluator.

      Accessibility label/description and hidden state map to Lynx attributes; Web attributes also carry live-region intent. Actual screen-reader behavior depends on the host platform. openUrl needs a browser or a host-provided native implementation. Native bytecode compilation is checked; it does not replace physical-device accessibility testing.

      The regression suite uses pinned upstream schemas, local mocks, and generated catalogs. It does not rely on live model output or claim certification against an external conformance program.

      Verification

      • Full repository build: 75 tasks passed, including native bytecode and Web.
      • Related regressions: 114 files, 1,028 tests passed, including all 8 Local Examples and 35 Gallery examples against the pinned schemas.
      • Client, server, and extractor type checks passed; API Extractor passed all 26 tasks.
      • Changed-file ESLint, Biome, dprint, and git diff --check passed. Changeset status reports the intended GenUI minor release with a documented breaking change.
      • The unfiltered repository Biome command also scans ignored build outputs under examples/react-debug-metadata/dist-consumer, reporting generated-code errors. The scoped source check passes; no generated output is included in the change.
      • Playground's standalone tsc --noEmit command is blocked by its existing project reference configuration (TS6310). Its Web and native production builds pass.

      Integration with main

      Merged main at 3ff5a0282 after the protocol audit. Preserve its split Playground renderer and batch-aware streaming placeholders. Forward protocol RPC and metadata from playground/src/render/a2ui.ts; migrate Jev generation, restored inline snapshots, and the standalone preview to the current contract. Jev action responses update the existing surface without sending another createSurface.

      The merged tree passes all 80 repository build tasks, 1,948 tests across 170 files, and 26 API Extractor tasks. Client, server, and extractor type checks and scoped ESLint, Biome, and dprint checks pass. Refresh the server catalog with the current extractor output and include the API translations required by the new docs site.