Refactor the Lit renderer to introduce a concept of CatalogApi and CatalogImplementation etc #487

jacobsimionato · 2026-01-14T04:32:28Z

Summary

This PR implements a major architectural refactor of the A2UI web renderers, aligning the Lit implementation with the design principles outlined in types_design.md. The primary goal is to decouple the core A2UI message processing logic from framework-specific rendering details, creating a robust, type-safe, and extensible foundation for the A2UI ecosystem.

Architectural Changes (Design Focus)

1. Framework-Agnostic Core

The core logic has been extracted and separated from Lit-specific code:

A2uiMessageProcessor: Now a standalone, framework-agnostic engine residing in core/a2ui_message_processor.ts. It handles message processing, state management, and node resolution without any knowledge of the rendering layer.
ComponentApi & CatalogApi: Introduced purely abstract definitions for components and catalogs in core/types. This allows defining a component's contract (e.g., properties, resolution logic) independent of its visual implementation.

2. Rendering Abstraction

We introduced new interfaces to bridge the core logic with specific frameworks:

ComponentRenderer: Defines the interface for converting a fully resolved node into a specific framework's output (e.g., TemplateResult for Lit).
CatalogImplementation: Maps a CatalogApi to a set of ComponentRenderers. This layer ensures compile-time safety by enforcing that every component defined in the API has a corresponding renderer implementation.

3. Directory Restructure

The codebase has been reorganized to reflect this separation of concerns:

src/0.8/core/: Contains all framework-agnostic code, including types, guards, the message processor, and standard catalog definitions.
src/0.8/lit/: Contains Lit-specific implementations, including the LitRenderer, component renderers, and web components.

Key Improvements & Fixes

Surface Initialization: Fixed a critical issue where Surface components would fail to render if a renderer wasn't explicitly provided. The Surface class now correctly initializes with a default standardLitCatalogImplementation.
Dependency Injection: The A2uiMessageProcessor constructor now accepts a CatalogApi, enabling dynamic injection of component definitions.
Type Safety: Enhanced type definitions and guards (e.g., AnyResolvedNode, CatalogApi) to fully support the new architecture.
Exports: Corrected package.json exports to point to the correct paths for the new core and UI modules.

Debugging Notes

Added renderers/lit/fixing.md to document the investigation into rendering issues (specifically the "no model" issue) and the solutions applied during this refactor.

Next Steps

Implement ProcessorContext (using Lit Context) to resolve the pending issue where data-bound components render (no model). This will provide descendant components access to the MessageProcessor injected at the Surface level.

gemini-code-assist

Code Review

This pull request introduces a significant architectural refactoring to the A2UI Lit renderer, aligning it with a new framework-agnostic type system design. Key changes include the introduction of ComponentApi definitions for each standard component (e.g., AudioPlayer, Button, Card), a CatalogApi to manage these definitions, and a FrameworkRenderer (LitRenderer) that uses a CatalogImplementation to map component APIs to their Lit-specific ComponentRenderer implementations. The A2uiMessageProcessor has been updated to leverage this new catalog-based resolution, replacing a large switch statement with a more extensible approach. Individual Lit components (a2ui-text, a2ui-card, etc.) have been updated to receive a generic node property and a renderChild callback, decoupling them from direct knowledge of the message processor and enabling recursive rendering. The Root base class for Lit components now uses Lit Context to provide MessageProcessor and SurfaceID to its descendants, addressing a previous issue where leaf components couldn't resolve data bindings. Debugging logs have been added throughout the A2uiMessageProcessor and Lit components, and the package.json exports and internal import paths have been updated to reflect the new file structure. Review comments highlight the need to remove temporary console logs, improve encapsulation by adding a public method to CatalogApi for iterating components, and make the child property in CardNode optional to match its usage.

gemini-code-assist · 2026-01-14T04:35:24Z

renderers/lit/src/0.8/core/a2ui_message_processor.ts

  }

  private setDataByPath(root: DataMap, path: string, value: DataValue): void {
+    console.log(`[setDataByPath] Path: ${path}, Value:`, value);


This file and several others in the PR (e.g., surface.ts, text.ts, lit_renderer.ts) include many console.log and console.warn statements. While these are helpful for debugging during development, they should be removed before merging to avoid cluttering the browser console in production. Please consider removing all temporary debugging logs.

While this is true, I think we should consider add some logging capabilities to the library through some Logger interface. I don't know if this needs to be homebrew, or we can pull in some dependency to have it, but it'd be useful to have an entrypoint on the library to inject some observability into its innards :)

gemini-code-assist · 2026-01-14T04:35:25Z

renderers/lit/src/0.8/core/types/types.ts

+    for (const api of (catalogApi as any)['components'].values()) {
+        if (!this.renderers.has(api.name)) {
+            throw new Error(`Missing renderer implementation for component: ${api.name}`);
+        }
+    }


Accessing the private components property of CatalogApi using (catalogApi as any)['components'] is not ideal as it breaks encapsulation and is brittle. A better approach would be to expose a public method on CatalogApi to iterate over its components.

For example, you could add the following method to the CatalogApi class:

// In CatalogApi class public getApis(): IterableIterator<AnyComponentApi> { return this.components.values(); }

Then you can use it here.

Suggested change

for (const api of (catalogApi as any)['components'].values()) {

if (!this.renderers.has(api.name)) {

throw new Error(`Missing renderer implementation for component: ${api.name}`);

}

}

for (const api of catalogApi.getApis()) {

if (!this.renderers.has(api.name)) {

throw new Error(`Missing renderer implementation for component: ${api.name}`);

}

}

gemini-code-assist · 2026-01-14T04:35:25Z

renderers/lit/src/0.8/core/standard_catalog_api/card.ts

+    child: AnyResolvedNode;
+    children: AnyResolvedNode[];


The child property in CardNode is currently typed as required (AnyResolvedNode), but the resolveProperties function and the component's render function can handle it being undefined (for example, when only children is provided). This can lead to type mismatches. It would be better to make child optional.

Suggested change

child: AnyResolvedNode;

children: AnyResolvedNode[];

child?: AnyResolvedNode;

children: AnyResolvedNode[];

gemini-code-assist · 2026-01-14T04:35:25Z

renderers/lit/src/0.8/core/standard_catalog_api/card.ts

+      throw new Error('Invalid properties for Card: missing child or children.');
+    }
+
+    const child = resolver(unresolved.child) as AnyResolvedNode;


The type assertion as AnyResolvedNode is unsafe here. If unresolved.child is undefined, resolver(unresolved.child) will return undefined, and the cast will hide a potential type error. It's better to handle the optional nature of child explicitly, especially after making it optional in the CardNode interface.

Suggested change

const child = resolver(unresolved.child) as AnyResolvedNode;

const child = unresolved.child ? resolver(unresolved.child) as AnyResolvedNode : undefined;

gemini-code-assist · 2026-01-14T04:35:25Z

types_design.md

+    *   When the signal changes, it passes the new resolved node tree to the `frameworkRenderer.renderNode()`.
+    *   The `FrameworkRenderer` recursively walks the tree, using the `CatalogImplementation` to find the right `ComponentRenderer` for each node, until the entire tree is converted into the framework's renderable format.
+
+![Data Flow Diagram](https://i.imgur.com/your-diagram-image.png)


This appears to be a placeholder link for the data flow diagram. Please update it with the correct image URL.

yuantian-agentspace · 2026-01-14T05:08:16Z

renderers/lit/src/0.8/core/standard_catalog_api/datetime_input.ts

+
+export interface DateTimeInputNode extends BaseResolvedNode<'DateTimeInput'> {
+  properties: {
+    value: StringValue;


In some implementation, value is reserved for input[type=datetime]. To avoid conflict, use a different property name like dtValue, see https://source.corp.google.com/piper///depot/google3/third_party/a2ui/renderers/lit_internal/src/v0_8/ui/datetime-input.ts;l=28#:~:text=27-,28,-29

yuantian-agentspace · 2026-01-14T05:17:50Z

renderers/lit/src/0.8/lit/components/audio.ts

    `,
  ];

  #renderAudio() {


Google3 does not like #, use private renderAudio instead.

yuantian-agentspace · 2026-01-14T05:21:45Z

renderers/lit/src/0.8/lit/components/datetime-input.ts

    </section>`;
  }

  #getInputType() {


Replace # with private .

yuantian-agentspace · 2026-01-14T05:22:31Z

renderers/lit/src/0.8/lit/components/datetime-input.ts

    return value.toString().padStart(2, "0");
  }

  #getPlaceholderText() {


Replace # with private

yuantian-agentspace · 2026-01-14T05:25:34Z

renderers/lit/src/0.8/lit/components/root.ts

+    return this.#weight;
+  }
+
+  #weight: string | number = 1;


Replace # with private

yuantian-agentspace · 2026-01-14T05:27:59Z

renderers/lit/src/0.8/lit/components/surface.ts


-  #renderLogo() {
-    if (!this.surface?.styles.logoUrl) {
+  #renderLogo(surface: SurfaceState) {


Replace # with private .

jacobsimionato added 13 commits January 14, 2026 11:06

add types design initial version

555c9a8

update plan

6f3debe

Update design

06ca73a

Update lit renderer almost working

4f2b562

Fix lit renderer

479aa17

More improvements to lit

40f045c

Improve resolution etc

99b811f

Remove redundant type checks

4f9d7e1

Improve the lit renderer structure

92b8d78

Use standard catalog in sample app

e842945

Add console warnings

d96e918

Add some fixes including a lot of logging

8083f66

add even more logging

1dcc922

gemini-code-assist bot reviewed Jan 14, 2026

View reviewed changes

yuantian-agentspace reviewed Jan 14, 2026

View reviewed changes

jacobsimionato added 6 commits January 15, 2026 08:02

UPdates to message processor casting etc

f0d38a5

Further improvements to renderers to make events work properly

5eda728

Update client app event handling logic

235a03c

Update A2UI message process to fix surface management

3f081f3

Make contact sample work

ac8d47d

update angular plan

5d9186e

	const child = resolver(unresolved.child) as AnyResolvedNode;
	const child = unresolved.child ? resolver(unresolved.child) as AnyResolvedNode : undefined;

Refactor the Lit renderer to introduce a concept of CatalogApi and CatalogImplementation etc #487

Are you sure you want to change the base?

Refactor the Lit renderer to introduce a concept of CatalogApi and CatalogImplementation etc #487

Conversation

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

Uh oh!

Summary

Architectural Changes (Design Focus)

1. Framework-Agnostic Core

2. Rendering Abstraction

3. Directory Restructure

Key Improvements & Fixes

Debugging Notes

Next Steps

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

ditman Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

yuantian-agentspace Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacobsimionato commented Jan 14, 2026 •

edited

Loading

yuantian-agentspace Jan 14, 2026 •

edited

Loading