Migrate package:genui onto package:a2ui_core (state engine + messages)

[andrewkolos]

Advances #811. Supersedes #956.

Migrates package:genui's runtime onto the shared, pure-Dart package:a2ui_core: protocol parsing, message processing, and surface/component/data-model state. SurfaceController becomes a thin wrapper over a2ui_core.MessageProcessor; genui no longer maintains its own parallel A2UI runtime.

The catalog-widget authoring API is unchanged; only the A2UI message types move onto a2ui_core. Unifying the catalog/component types with the core models is a separate follow-up (#801) that also changes the authoring API.

Breaking changes

• The a2ui_core message types are now used over genui's bespoke ones. The genui message classes (A2uiMessage, CreateSurface, UpdateComponents, UpdateDataModel, DeleteSurface) are removed. SurfaceController.handleMessage, Transport.incomingMessages, and A2uiMessageEvent.message use core.A2uiMessage. Construct with core.CreateSurfaceMessage(...) etc.; core.UpdateComponentsMessage carries raw component JSON maps. Message-handling consumers should depend on a2ui_core directly.
• SurfaceController.store / DataModelStore removed. Access a surface's data model via SurfaceController.contextFor(id).dataModel.
• SurfaceRegistry.updateSurface(...) removed. Surface lifecycle flows through SurfaceController.handleMessage.

Behavioral changes inherited from a2ui_core

• DataModel writes are stricter (errors on type-mismatched intermediate paths and very large list indices; sparse list writes fill skipped entries with null).
• A duplicate createSurface for an active surface id is now an error.

Full list in packages/genui/CHANGELOG.md. Consumer-facing details migration_0.9.1_to_0.10.0.md.

Note for reviewers

The significant changes are found across less than 10 files. Everything else is mechanical renames and tests.
Some files of note:

• packages/genui/lib/src/engine/surface_controller.dart: MessageProcessor delegation, handleMessage(core.A2uiMessage), and buffering of messages that arrive before their target surface is created.
• packages/genui/lib/src/model/data_model.dart: InMemoryDataModel over core.DataModel; _SignalNotifier exposes core signals as ValueListenables.
• packages/genui/lib/src/model/ui_models.dart: SurfaceDefinition / Component snapshots; SurfaceUpdate events.
• packages/genui/lib/src/engine/surface_registry.dart: surface lifecycle.
• packages/genui/lib/src/widgets/surface.dart: definition-snapshot render path.
• packages/genui/lib/src/model/a2ui_message.dart: now just the catalog-parameterized message schema (the message classes are gone).
• packages/genui/lib/src/model/schema_validation.dart, widget_utilities.dart.

[andrewkolos]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors package:genui to run on the shared package:a2ui_core runtime. Key changes include migrating A2UI message types to a2ui_core, removing DataModelStore and SurfaceController.store in favor of accessing data models via SurfaceController.contextFor(id).dataModel, and updating dependent packages, examples, and tests.

Several improvement opportunities were identified during the review:

• In surface_editor.dart, the old _dataModelNotifier should be explicitly disposed before creating a new subscription to prevent memory leaks.
• In catalog.dart, a public effectiveCatalogId extension should be added to allow SurfaceController to correctly match inline catalogs.
• In surface_registry.dart, removeSurface should set notifier.value = null before disposal to satisfy the contract of watchSurface and notify active builders.
• In schema_validation.dart, validateComponents should directly use schema.value instead of performing expensive JSON serialization and parsing on every validation.

_{Note: Security Review did not run due to the size of the PR.}

[gemini-code-assist]

When catalogId is null (for inline catalogs), _inlineCatalogId is used to register the catalog in a2ui_core. However, since _inlineCatalogId is private to catalog.dart, other files like surface_controller.dart cannot access it to match the catalog with surface.catalog.id.\n\nAdding a public CatalogIdExtension with effectiveCatalogId allows SurfaceController to correctly match and find inline catalogs.

core.Catalog<core.ComponentApi> coreCatalogFor(Catalog catalog) =>\n    core.Catalog<core.ComponentApi>(\n      id: catalog.effectiveCatalogId,\n      components: catalog.items\n          .map<core.ComponentApi>(_CatalogItemComponentApi.new)\n          .toList(growable: false),\n    );\n\nextension CatalogIdExtension on Catalog {\n  /// The effective catalog ID, using [catalogId] if non-null, or a synthesized\n  /// ID if null.\n  String get effectiveCatalogId => catalogId ?? _inlineCatalogId;\n}

[jacobsimionato]

Hey overall, this looks miraculously non-disruptive for developers to me! Nice work!

My main question is whether you have any ideas about avoiding developers needing to add the core. import prefixes to resolve symbol conflicts temporarily. Probably there's nothing we can do, but it'd be amazing if we could avoid it. Could we have a separate top-level import file for the conflicting symbols perhaps?

I didn't hit LGTM yet just because I ran out of time and want to spend a bit more tomorrow.

[jacobsimionato]

What are the symbol conflicts that prevent importing both libraries? I think it's worth us making sure that they don't have conflicting symbols in the longer run. If there's some easy way to avoid it now, that would be nice to, avoid all our clients adding as core throughout their codebase then needing to remove it later.

[andrewkolos]

I think you've since found them, but for future reference, the collisions are: Catalog, DataModel, DataPath, DataContext, CancellationException, CancellationSignal, ExpressionParser, and FormatStringFunction

[jacobsimionato]

Ahhh this is where the symbol collisions happen! I wonder if there is something we can do here to avoid developers needing to add core. everywhere in their codebases temporarily, and the removing it when we resolve the conflicts.

I can't think of a better solution than what you've done though. Could we make Catalog implement core.Catalog<core.ComponentApi> somehow, rather than needing it to be converted?

[jacobsimionato]

Is the plan to later refactor this to use SurfaceModel instead? I wonder if it could have an alternative constructor or something, so we can start checking in the new logic now without breaking things?

[andrewkolos]

I like the thinking, ActionDelegate.handleEvent¹ already exposes SurfaceDefinition, so we'd still have to reconstruct that every time to avoid breaking component authoring API. I think per our discussion today, it would be more economical to get through a2ui-project/a2ui#1282 first.

Footnotes

1. https://github.com/flutter/genui/blob/bb50a983c49216348a0de91751585f60e6cbcd6b/packages/genui/lib/src/widgets/surface.dart#L183 ↩

[andrewkolos]

My main question is whether you have any ideas about avoiding developers needing to add the core. import prefixes to resolve symbol conflicts temporarily. Probably there's nothing we can do, but it'd be amazing if we could avoid it.

I didn't consider this exhaustively. I pretty much always default to the aliasing import/as syntax whenever name collisions are involved`–it's more robust when working on frequently changing code and reduces ambiguity when reading code when the reader knows there are many name collisions in the current context¹.

Could we have a separate top-level import file for the conflicting symbols perhaps?

Unless I'm missing something, isn't this equivalent to consumers switching to the selective show import syntax? Regardless, if you have a preference for show over as, I'm happy to reconsider more thoughtfully.

Footnotes

1. Aside : a classic example from my personal experience is from game programming where libraries for physics, 3d rendering, computer vision, spatial audio, etc. all export primitive math types/functions like Vector3 etc. ↩

[jacobsimionato]

Overall, I like this light-touch approach of migrating models to start with and avoiding breaking things.

My main concern is not breaking functionality with each step. I tried the PR out locally, and it did seem like there were some issues with conversation flow etc which I couldn't replicate at head, so wondering if you can look into them before merging?

Do you mind trying out my party planning prompt and seeing if you see the same issues? It could be that my experience is just LLM noise and it's intermittently broken at head already.

Basically, if we can be confident this isn't breaking anything in an obvious way, then I'm keen to merge.

With PR

Issue with data model references shown to user

Issue with conversation flow

The agent is not seeing the item that was chosen in the radio buttons for some reason. It didn't know that it's a graduation party.

At head

I didn't see these issues, not sure if it's a fluke. The agent did know it's a graduation party though.

[jacobsimionato]

Not for this PR: A good next step could be to update this so that it can accept a core SurfaceModel and render based on that, doing whatever conversions are necessary. I think the SurfaceModel should expose the necessary data, and allow us to delete SurfaceRegistry etc.

[jacobsimionato]

BTW all this extra Flutter-specific logic to handle missing catalogs, and cache messages for surfaces that don't exist isn't necessary in the long run. If we want to add this functionality, we can add it to the unified core library design, or more likely to agent SDKs, to ensure they fix payloads before being sent to the client.

But I think it's awesome that this avoids breaking changes for now. I think we can remove this class later, once we add the node API and are ready to complete the migration.

[andrewkolos]

Agreed. I Added a TODO to increase our chances of remembering to do this later.

[jacobsimionato]

I'm trying to think of how we can advance aspects of this towards the unified design as fast as possible with minimal confusion. What do you think about just making the genui CatalogItem and Catalog just inherit from the Core models directly, so no conversion is necessary?

This could be a followup PR, if you agree with the approach. Here's a proposal from Gemini - not sure if it has holes:

Design Document: Catalog Unification & Signal-Based Reactivity

1. Goal

Unify the genui and a2ui_core Catalog and Client Function APIs. By aligning genui components and functions directly with a2ui_core interfaces, we can:

• Eliminate the translational/adapter layers (coreCatalogFor, _CatalogItemComponentApi).
• Replace complex, resource-heavy Stream-based reactivity with lightweight, synchronous, and Signal-based updates using preact_signals.
• Remove the redundant ExpressionParser in genui in favor of a2ui_core's native Expression and Data Pointer resolution.

---

2. Current Architecture & Bottlenecks

Component API Redundancy

genui uses CatalogItem to define a component, which is then mapped at runtime to core.ComponentApi via a helper _CatalogItemComponentApi inside coreCatalogFor. This translation happens during every surface creation.

Stream vs. Signal Impedance Mismatch

genui.ClientFunction is asynchronous and returns a Stream<Object?>:

abstract interface class ClientFunction {
  Stream<Object?> execute(JsonMap args, ExecutionContext context);
}

However, the underlying a2ui_core engine is built on Signals (preact_signals). This forces genui to:

1. Wrap synchronous functions (e.g., and, or, regex, length) in Stream.value(...).
2. Maintain a complex, recursive Stream-based ExpressionParser in genui to combine and evaluate multiple stream arguments.
3. Convert streams back to signals/notifiers at the widget rendering layer (e.g., BoundString).

---

3. Proposed Unified Architecture

                 +-----------------------+
                 |   core.ComponentApi   |
                 +-----------+-----------+
                             ^
                             | (Implements)
                 +-----------+-----------+
                 |   genui.CatalogItem   |
                 +-----------------------+

             +-------------------------------+
             |  core.FunctionImplementation  |
             +---------------+---------------+
                             ^
                             | (Implements)
             +---------------+---------------+
             |     genui.ClientFunction      |
             +-------------------------------+

A. Unified Component API

CatalogItem will directly implement core.ComponentApi:

class CatalogItem implements core.ComponentApi {
  @override
  final String name;

  @override
  Schema get schema => dataSchema;

  final CatalogWidgetBuilder widgetBuilder;
  final bool isImplicitlyFlexible;
  final List<ExampleBuilderCallback> exampleData;
}

B. Signal-Based Client Functions

ClientFunction will directly implement core.FunctionImplementation, returning either a static value or a ReadonlySignal<Object?>:

abstract class ClientFunction implements core.FunctionImplementation {
  @override
  String get name;

  @override
  String get description;

  @override
  Schema get argumentSchema;

  @override
  core.A2uiReturnType get returnType;

  /// Executes synchronously. Returns a raw value, a ReadonlySignal, or null.
  @override
  Object? execute(
    Map<String, dynamic> args,
    core.DataContext context, [
    core.CancellationSignal? cancellationSignal,
  ]);
}

C. Direct Catalog Inheritance

genui.Catalog directly extends core.Catalog<CatalogItem>, eliminating adapter wrappers:

class Catalog extends core.Catalog<CatalogItem> {
  final List<String> systemPromptFragments;

  const Catalog(
    List<CatalogItem> components, {
    List<ClientFunction> functions = const [],
    required String super.id,
    this.systemPromptFragments = const [],
  }) : super(components: components, functions: functions);
}

---

4. Key Simplifications & Code Deletions

1. Simplify BasicFunctions

We can convert all basic functions to pure, synchronous logic returning static values. For example, AndFunction:

class AndFunction extends ClientFunction {
  @override
  Object? execute(Map<String, dynamic> args, core.DataContext context, [...]) {
    final values = args['values'];
    if (values is! List) return false;
    return values.every((v) => _isTruthy(v));
  }
}

2. Delete redundant parser

genui/lib/src/functions/format_string.dart and ExpressionParser can be completely removed. We can reuse the formatString function already present in a2ui_core/lib/src/processing/basic_functions.dart or keep a simplified version returning ReadonlySignal.

3. Streamlined Widget Data Binding

Widget-binding helpers (e.g., BoundString, BoundBool) can directly use the signal-backed values from the context since core.DataContext provides signal-based resolution (resolveListenable).

---

5. Migration Strategy

1. Phase 1: Update Core Interfaces
   Change CatalogItem and ClientFunction to implement core.ComponentApi and core.FunctionImplementation.

2. Phase 2: Migrate Call Sites & Standard Functions
   Rewrite the 14 standard functions in BasicFunctions to return static values or ReadonlySignals.

3. Phase 3: Clean up rendering adapters
   Update SurfaceController to pass Catalog directly to core.MessageProcessor and remove coreCatalogFor.

4. Phase 4: Delete stream parser
   Delete ExpressionParser and the stream_transform dependency. Update BoundValue widgets to listen to the signal notifier natively provided by the core layer.

[jacobsimionato]

My main question is whether you have any ideas about avoiding developers needing to add the core. import prefixes to resolve symbol conflicts temporarily. Probably there's nothing we can do, but it'd be amazing if we could avoid it.

I didn't consider this exhaustively. I pretty much always default to the aliasing import/as syntax whenever name collisions are involved`–it's more robust when working on frequently changing code and reduces ambiguity when reading code when the reader knows there are many name collisions in the current context1.

Could we have a separate top-level import file for the conflicting symbols perhaps?

Unless I'm missing something, isn't this equivalent to consumers switching to the selective show import syntax? Regardless, if you have a preference for show over as, I'm happy to reconsider more thoughtfully.

Footnotes

1. Aside : a classic example from my personal experience is from game programming where libraries for physics, 3d rendering, computer vision, spatial audio, etc. all export primitive math types/functions like Vector3 etc. ↩

Hey no worries, let's leave this, no need to think hard about it. Thanks so much for giving me more context.

[andrewkolos]

Thanks for all the additional feedback! I'll be going through each individually, but I can start with the quality regression quality concern since that's also the thing I want to get right here. I actually wasn't able to repro your report here, I experienced failure on both main and here on the 5+ attempts I tried (e.g. I would select "birthday" and the generated text did not acknowledge this in any way and the rest of the generation remained very generic, or I would get into an infinite loop where I kept getting asked for the party type).

At first glance, it doesn't even look like user input gets routed to the LLM at all. The submit button seems to only send up an empty context {"action":{"name":"submitPartyDetails","context":{}}}. The client data model isn't being included in the payload.

However, what I am completely confounded by is that when you ran the app on main, the text produced by the agent acknowledges that the party is for a graduation, it sees the date, it sees the number of guests. I don't see how. Regardless, I can fix this in this PR.

As an aside, I notice that earlier text in the conversation seems to be getting retroactively updated. Said another way, the agent is not acting with an append-only approach (or perhaps payloads are malformed). I think simple_chat has been buggy for quite a while, but I digress.

[jacobsimionato]

Hey thanks for bearing with me with investigating the regressions. As discussed over VC today, it seems like both of the issues I mentioned are actually not regressions and we were able to reproduce them at head. So let's merge this and move on! I can file bugs for the issues.