Add a framework-agnostic data layer to the web core library by jacobsimionato · Pull Request #631 · google/A2UI

jacobsimionato · 2026-02-16T04:06:54Z

This PR introduces a framework-agnostic data model for A2UI within the web_core library, following the architecture outlined in Unified Data Model Architecture.

Key Changes

New v0.9 Data Model: Implemented the three-layer architecture in renderers/web_core/src/v0_9:
- Processing Layer: A2uiMessageProcessor for handling the A2UI message stream.
- Data Layer: Persistent, "dumb" models including SurfaceGroupModel, SurfaceModel, SurfaceComponentsModel, and DataModel.
- Context Layer: Transient DataContext and ComponentContext to facilitate rendering and scope resolution.
Dependency Updates: Added zod and zod-to-json-schema to web_core to support type-safe catalog definitions and schema introspection as planned in the v0.9 evolution.
Package Exports: Added a new ./v0_9 export to @a2ui/web_core to allow framework-specific renderers (like Lit or Angular) to opt-in to the new architecture.
Improved Testing: Added a test script using the native Node.js test runner for the new model.

Architectural Alignment

The implementation adheres to the principles of separation of concerns, mutable but observable "dumb" models, and granular reactivity through standard observer patterns, ensuring it remains framework-agnostic and high-performance.

gemini-code-assist

Code Review

The pull request introduces a framework-agnostic data layer for the web core library, aligning it with the v0.9 specification and the Flutter implementation. It features a reactive DataModel with JSON Pointer support, a MessageProcessor for protocol handling, and Zod-based schema validation for components. The architecture is well-decoupled, allowing for easier integration with different web frameworks. However, the relaxation of TypeScript strictness in tsconfig.json is a concern, and there are potential edge cases in the data model's path resolution and array handling that should be addressed to ensure robustness.

renderers/web_core/tsconfig.json

renderers/web_core/src/v0_9/state/data-model.ts

renderers/web_core/src/v0_9/processing/message-processor.ts

renderers/web_core/src/v0_9/state/data-model.ts

renderers/web_core/src/v0_9/processing/message-processor.ts

Renames the 'A2uiModel' class to 'SurfaceGroupModel' and its corresponding files to better reflect its role in managing groups of surfaces. Updates all internal references and tests accordingly.

…d ComponentsModel Refactors SurfaceGroupModel and ComponentsModel to accept instances via `addSurface` and `addComponent` respectively, improving encapsulation. Implements an observable pattern for action handling in SurfaceModel and SurfaceGroupModel, removing the ActionHandler dependency from the SurfaceModel constructor.

Renames ComponentsModel to SurfaceComponentsModel to better reflect its scope and relationship with SurfaceModel. Updates all references and exports.

jacobsimionato · 2026-02-22T23:45:15Z

I have addressed the feedback. Please take another look.

jacobsimionato · 2026-02-22T23:45:32Z

/gemini review

gemini-code-assist

Code Review

The pull request introduces a framework-agnostic data layer for A2UI, following a clean three-layer architecture (Processing, Data, and Context). The implementation is well-structured and includes a good suite of tests using the native Node.js test runner. The main issues identified relate to the non-incremental nature of component property updates, which could lead to data loss, and opportunities to leverage the newly added Zod library for better type safety in the message processing layer. There are also some TODOs in the rendering context that should be addressed to ensure full protocol support.

renderers/web_core/src/v0_9/state/component-model.ts

gemini-code-assist · 2026-02-22T23:47:01Z

renderers/web_core/src/v0_9/processing/message-processor.ts

+    this.model.removeLifecycleListener(listener);
+  }
+
+  processMessages(messages: any[]): void {


The processMessages method uses any[] for the input messages. Since zod has been added as a dependency and schemas are being defined in schema_types.ts, it is highly recommended to define a schema for the A2UI messages and validate them here. This would provide better type safety at the system boundary and catch malformed messages early.

Gemini is kind of right, don't we have an A2UIMessage type for here?

True true - I defined a type now.

renderers/web_core/src/v0_9/state/surface-group-model.ts

renderers/web_core/src/v0_9/rendering/data-context.ts

renderers/web_core/src/v0_9/schema/common-types.ts

ditman

Some comments!

ditman · 2026-02-24T21:18:16Z

renderers/web_core/src/v0_9/schema/common-types.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';


Should this code be part of the artifacts provided by the A2UI spec, instead of being in web_core?

Are we going to have different schema_types in different parts of the code? I wonder if it'd make sense to have a "schemas" directory to put them all there:

schemas |- catalog -- something_else

Maybe? IDK, but now I don't think these should be vended from the spec, unless it vends something that we can use to codegen the ones in TS (and maybe Dart) from a single source of truth.

I moved things to a "schema" folder, which reflects the structure of the specification. Maybe we can generate this from json schema one day, but for now, I think translating it once per spec revision is fine.

renderers/web_core/src/v0_9/processing/message-processor.ts

ditman · 2026-02-24T21:22:36Z

renderers/web_core/src/v0_9/processing/message-processor.ts

+    this.model.removeLifecycleListener(listener);
+  }
+
+  processMessages(messages: any[]): void {


Gemini is kind of right, don't we have an A2UIMessage type for here?

renderers/web_core/src/v0_9/processing/message-processor.ts

ditman · 2026-02-24T23:53:01Z

renderers/web_core/src/v0_9/state/surface-model.ts

+  async dispatchAction(action: any): Promise<void> {
+    for (const listener of this.actionListeners) {
+      try {
+        await listener(action);


(Same comment as above about awaiting a promise that may never be resolved)

ditman · 2026-02-24T23:54:50Z

renderers/web_core/src/v0_9/index.ts

@@ -0,0 +1,10 @@
+
+export * from './state/data-model.js';
+export * from './rendering/data-context.js';


Should each of these be a different library, so you can import from web_core/v0.9/state or web_core/v0.9/rendering, instead of from a big file? That would also alleviate issues with name collisions down the line?

This makes sense. Maybe we can figure it out later though?

renderers/web_core/package-lock.json

renderers/web_core/package.json

ditman · 2026-02-24T23:59:33Z

specification/v0_9/docs/renderer_guide.md

+A dedicated store for the surface's application data (the "Model" in MVVM).
+
+```typescript
+class DataModel {


Would it be nice to have a way of create SomethingModel extends DataModel and have type-safe versions of the models that "hide" the string paths and T details from users?

We can't do that though, because the DataModel is an untyped thing. The exact structure is defined at runtime according to updateDataModel messages etc.

ditman

Small note about the naming of Schema types (make them all SomethingSomethingSchema?)

ditman · 2026-02-26T19:11:33Z

renderers/web_core/src/v0_9/processing/message-processor.ts

+    const { surfaceId, catalogId, theme } = payload;
+
+    // Find catalog
+    const catalog = this.catalogs.find(c => c.id === catalogId);


(this.catalogs being defined directly in the constructor keeps breaking my brain.)

We should lobby the Dart team to add this! Then it will be the norm in our brains! :-D

ditman · 2026-02-26T19:21:50Z

renderers/web_core/src/v0_9/schema/server-to-client.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+export const A2UIMessageSchema = z.object({


I like that this is called SomethingSomethingSchema. 2 comments:

Keep the capitalization consistent, if the A2uiMessageProcessor uses A2ui, this should be A2uiMessageSchema (same everywhere)

If this is a SomethingSomethingSchema, I'd argue that everything that is defined using Zod should be a SomethingSomethingSchema as well... It's more verbose, but also more descriptive, and frees the "good names" for the actual objects that we may want to use within the rest of the framework.

Great point. I updated this to make all the zod schemas be called SomethingSchema. And then when we do inferType from it, we just name that as Something rather than SomethingDef.

renderers/web_core/src/v0_9/rendering/data-context.ts

ditman · 2026-02-26T19:24:10Z

renderers/web_core/src/v0_9/rendering/data-context.ts

+      return this.path;
+    }
+
+    // Normalize current path (remove trailing slash if exists, unless root)


Do we want/need to support relative path traversal? Something like:

"../id" or similar?

Ummm that's interesting. It's not in the spec right now, so we don't need it. I'm sure we'll find more edge cases to handle here, but at least we will have things more centralized now so it's not so hard to tighten the implementation.

ditman · 2026-02-26T19:25:07Z

renderers/web_core/src/v0_9/state/data-model.test.ts

+      called = true;
+    });
    model.set('/user/name', 'Charlie');
+    assert.strictEqual(called, true, 'Callback was never called');


I like this better!

renderers/web_core/package.json

ditman · 2026-02-26T22:27:29Z

npm error Invalid: lock file's @types/node@25.2.3 does not satisfy @types/node@24.10.15

You need to commit and push the generated lockfiles, unfortunately (just rebuild the examples)

jacobsimionato added 6 commits January 30, 2026 08:28

Add gemignore

6ab973e

Add design docs

89db879

Add core renderer APIs not trimmed

4f43a8e

Merge branch 'main' into data-layer-1

3b9ce30

Make a scaled down version of web-core

d2f663b

Fix client capabilities test

aa1196d

github-project-automation bot added this to A2UI Feb 16, 2026

github-project-automation bot moved this to Todo in A2UI Feb 16, 2026

gemini-code-assist bot reviewed Feb 16, 2026

View reviewed changes

jacobsimionato added 11 commits February 16, 2026 14:50

Update renderers web core

ca866e3

Update data model

a01b828

refactor(web_core): rename A2uiModel to SurfaceGroupModel in v0.9

53e9469

Renames the 'A2uiModel' class to 'SurfaceGroupModel' and its corresponding files to better reflect its role in managing groups of surfaces. Updates all internal references and tests accordingly.

refactor(web_core): rename ComponentsModel to SurfaceComponentsModel

b77455c

Renames ComponentsModel to SurfaceComponentsModel to better reflect its scope and relationship with SurfaceModel. Updates all references and exports.

replace many docs with one doc

a15804d

Fix doc

d82673e

Add manual edits

7647e3d

Improve framework renderer section

310fc80

Simplify design

951fa0b

Merge branch 'main' into data-layer-1

98b26c6

jacobsimionato marked this pull request as ready for review February 19, 2026 05:36

jacobsimionato requested review from ava-cassiopeia, ditman and gspencergoog as code owners February 19, 2026 05:36

Enable scrict mode again

8a088f2

jacobsimionato mentioned this pull request Feb 22, 2026

data-model.ts issue with JSON pointer syntax #651

Open

fix: Address PR feedback

b412047

gemini-code-assist bot reviewed Feb 22, 2026

View reviewed changes

Fix docs

6e15d44

google deleted a comment from gemini-code-assist bot Feb 24, 2026

ditman reviewed Feb 24, 2026

View reviewed changes

jacobsimionato added 12 commits February 26, 2026 10:55

Address feedback

e3b2f65

Improve tests

68efefc

Improve subscription API

bb1e362

fix wishy washy types

95ab135

Fix path comment

dd34140

Add todos for type checks

d70d5ee

Rename to renderer guide

b38c982

Update message processor to remove getSurface

b331957

Fix minor issues

5733cef

Update renderer guide

248e574

Updates including event emitter etc

93bec2b

reduce node version

48edaed

ditman approved these changes Feb 26, 2026

View reviewed changes

jacobsimionato added 4 commits February 27, 2026 13:26

A few updates

f5e3f2d

Update renderer_guide

ed611f1

Fix schema names

b13accd

Some improvements

a4fa67b

jacobsimionato requested review from dmandar, nan-yu, yjbanov and zeroasterisk as code owners February 27, 2026 03:51

jacobsimionato added 3 commits February 27, 2026 15:21

Update surface components and renderer guide

144f703

remvoe design alternatives

4839444

Remove flutter

6a5b9b6

jacobsimionato merged commit e865988 into google:main Feb 27, 2026
8 checks passed

github-project-automation bot moved this from Todo to Done in A2UI Feb 27, 2026

		@@ -0,0 +1,10 @@

		export * from './state/data-model.js';
		export * from './rendering/data-context.js';

		@@ -0,0 +1,23 @@
		import { z } from 'zod';

		export const A2UIMessageSchema = z.object({

Conversation

jacobsimionato commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Architectural Alignment

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jacobsimionato commented Feb 22, 2026

Uh oh!

jacobsimionato commented Feb 22, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist bot Feb 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ditman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ditman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacobsimionato commented Feb 16, 2026 •

edited

Loading