Create a2ui_core library, independent of genui

[jacobsimionato]

Let's implement an a2ui_core library in isolation, following https://github.com/google/A2UI/blob/main/specification/v0_9/docs/renderer_guide.md .

To include:

• Model classes
• MessageProcessor
• Context classes
• Basic catalog API declarations

This way, we can build a Jaspr renderer etc in top of this soon, and refactor the Gen UI SDK to be based on it later.

[jacobsimionato]

Design doc:

A2UI Core Dart Library Design

This document describes the design for a2ui_core, a framework-agnostic Dart library implementing the A2UI (Agent to UI) protocol v0.9.

Overview

The a2ui_core library serves as the foundational data and logic layer for A2UI renderers in Dart. Its primary responsibility is to maintain the state of UI surfaces, manage data model reactivity, and process protocol messages, all while remaining independent of any specific UI framework like Flutter.

Key Design Decisions

1. No Flutter Dependency

The library will depend only on the Dart SDK and selected third-party packages (json_schema_builder, collection, uuid). It will NOT import package:flutter. This allows the core logic to be shared across Flutter apps, CLI tools, server-side renderers, and other Dart environments.

2. Reactive System (Notifiers & Computed State)

To stay idiomatic to the Dart ecosystem while remaining framework-agnostic, the library will use a pure Dart implementation of the ValueNotifier pattern. This avoids the complexity of heavy Rx libraries while providing the "current value" access required for synchronous resolution.

• ValueListenable<T>: The standard interface for observable values.
• ValueNotifier<T>: A container holding a single value that notifies listeners on change.
• ComputedNotifier<T>: A derived notifier that automatically tracks and listens to other ValueListenable dependencies, recalculating its value only when they change. This provides "Signal-like" efficiency for complex data bindings and function calls.

class ValueNotifier<T> extends ValueListenable<T> {
  T _value;
  T get value => _value;
  set value(T newValue);
}

/// Automatically combines multiple inputs into a single reactive output.
class ComputedNotifier<T> extends ValueNotifier<T> {
  ComputedNotifier(List<ValueListenable> dependencies, T Function() compute);
}

3. Data Model & JSON Pointers

The DataModel will implement RFC 6901 (JSON Pointer) for path-based access and subscriptions.

To prevent the classic "unobserved observable" memory leak without forcing developers to manage custom subscription objects, the DataModel will internally cache active ValueNotifiers using Dart's WeakReference. If a UI component calls watch(path) but is later destroyed, the ValueNotifier will be naturally garbage-collected. The DataModel will automatically prune dead weak references during update cycles.

• Auto-vivification: Setting a value at a deep path (e.g., /a/b/c) will automatically create intermediate maps or lists.
• Bubble & Cascade Notifications: Updating a path will notify:
  • Exact matches on that path.
  • All ancestor paths (bubbling up to /).
  • All descendant paths (cascading down to nested children).

4. Schema-First Validation & API Definition

Incoming messages, component properties, and function arguments will be validated using package:json_schema_builder. The Schema object from this package will also be the core representation of the UI contract across ComponentApi, FunctionApi, and the Catalog's themeSchema. This allows us to generate dynamic Client Capabilities, serialize inline catalogs, and strictly validate the JSON protocol before state mutation.

File Layout & Reference Mapping

The library structure follows the modular architecture of the web_core reference implementation.

Dart File Path	Responsibility	Reference (TS/Dart)
Common Utilities
lib/src/common/data_path.dart	JSON Pointer (RFC 6901) logic	web_core/state/data-model.ts
lib/src/common/reactivity.dart	ValueNotifier, ComputedNotifier, batch	(Custom implementation)
lib/src/common/cancellation.dart	CancellationSignal for async cleanup	genui/primitives/cancellation.dart
lib/src/common/errors.dart	A2uiError hierarchy	web_core/errors.ts
Protocol Models
lib/src/protocol/messages.dart	Message envelopes (CreateSurface, etc.)	web_core/schema/server-to-client.ts
lib/src/protocol/capabilities.dart	ClientCapabilities and InlineCatalog	web_core/schema/client-capabilities.ts
lib/src/protocol/common.dart	DynamicValue, Action, ChildList types	web_core/schema/common-types.ts
State Management
lib/src/state/data_model.dart	Reactive Data store w/ WeakReferences	web_core/state/data-model.ts
lib/src/state/component_model.dart	ComponentModel, SurfaceComponentsModel	web_core/state/component-model.ts
lib/src/state/surface_model.dart	SurfaceModel, SurfaceGroupModel	web_core/state/surface-model.ts
Processing & Logic
lib/src/processing/processor.dart	MessageProcessor controller	web_core/processing/message-processor.ts
lib/src/processing/expressions.dart	${expression} interpolation logic	web_core/basic_catalog/expressions/
Rendering Support
lib/src/rendering/contexts.dart	DataContext, ComponentContext	web_core/rendering/data-context.ts
lib/src/rendering/binder.dart	GenericBinder trait-based binding	web_core/rendering/generic-binder.ts
Library Entry
lib/a2ui_core.dart	Main exports	web_core/index.ts

Core APIs & Classes

1. Reactivity (reactivity.dart)

abstract interface class Listenable {
  void addListener(void Function() listener);
  void removeListener(void Function() listener);
}

abstract class ValueListenable<T> implements Listenable {
  T get value;
}

void batch(void Function() callback);

2. Data Model (state/data_model.dart)

Reference: web_core/state/data-model.ts

class DataModel {
  /// Updates data at path and notifies listeners.
  /// See web_core/state/data-model.ts -> set()
  void set(String path, dynamic value);
  
  /// Synchronously gets data at path.
  /// See web_core/state/data-model.ts -> get()
  dynamic get(String path);
  
  /// Returns a ValueListenable for a specific path.
  /// Internally cached using a WeakReference to prevent leaks.
  /// See web_core/state/data-model.ts -> getSignal()
  ValueListenable<T?> watch<T>(String path);
  
  /// Clears all state and notifiers.
  void dispose();
}

3. Message Processor (processing/processor.dart)

Reference: web_core/processing/message-processor.ts

class MessageProcessor<T extends ComponentApi> {
...
  final SurfaceGroupModel<T> groupModel;
  final List<Catalog<T>> catalogs;

  MessageProcessor({required this.catalogs, void Function(A2uiClientAction)? onAction});

  /// Processes a stream of validated A2UI messages.
  void processMessages(List<A2uiMessage> messages);

  /// Generates capabilities including inline catalogs.
  A2uiClientCapabilities getClientCapabilities({bool includeInlineCatalogs = false});

  /// Aggregates data models for surfaces with sendDataModel enabled.
  A2uiClientDataModel? getClientDataModel();
}

4. Catalog & Components (catalog/types.dart)

Reference: web_core/catalog/types.ts

The APIs heavily rely on json_schema_builder to define their structural footprint. This is essential for generating inline catalogs and validating server payloads. Functions must accept a CancellationSignal to support async/stream cleanup (e.g., long-polling tasks or timers).
...

import 'package:json_schema_builder/json_schema_builder.dart';
import '../common/cancellation.dart';

abstract class ComponentApi {
  String get name;
  
  /// The technical definition of the component using json_schema_builder.
  Schema get schema;
}

abstract class FunctionApi {
  String get name;
  String get returnType; // e.g., 'string', 'number', 'boolean'
  
  /// The schema defining the expected arguments for this function.
  Schema get argumentSchema;
}

abstract class FunctionImplementation extends FunctionApi {
  /// Executes the function. Can return a static value or a `ValueListenable<T>`.
  /// Uses [cancellationSignal] to clean up resources like timers (e.g., in a Metronome function).
  dynamic execute(Map<String, dynamic> args, DataContext context, [CancellationSignal? cancellationSignal]);
}

class Catalog<T extends ComponentApi> {
  final String id;
  final Map<String, T> components;
  final Map<String, FunctionImplementation> functions;
  
  /// Optional schema defining the theme parameters.
  final Schema? themeSchema;
}

5. Contexts & Generic Binding (rendering/contexts.dart & rendering/binder.dart)

Reference: web_core/rendering/data-context.ts, web_core/rendering/component-context.ts, web_core/rendering/generic-binder.ts

Because Dart's static type system lacks TypeScript's mapped and conditional types, the GenericBinder cannot automatically infer a strictly typed class directly from the schema at compile time.
...
Instead, the GenericBinder outputs a reactive Map<String, dynamic>. It handles all the complex lifecycle logic (subscribing to JSON pointers, resolving expressions, wrapping actions in callbacks, and evaluating validation checks) and dumps the fully resolved values into this map.

Component developers then use Dart's extension type to provide a zero-cost, strongly-typed wrapper around this map.

Format of Resolved Properties

The GenericBinder scrapes the component's Schema to determine the behavior of each property and resolves them as follows:

1. DYNAMIC Properties (Data Bindings, Functions, Literals):
   Resolved to their primitive Dart types (e.g., String, bool, num, List). The binder subscribes to the data model; when the value changes, a new map is emitted.

   • Example: {"label": "Submit"}

2. ACTION Properties:
   Resolved into a zero-argument Dart callback: Future<void> Function(). The binder automatically handles evaluating the payload's data bindings at the exact moment the user interacts with the component, and dispatches the action to the MessageProcessor.

   • Example: {"onPressed": () => ... }

3. STRUCTURAL Properties (Child References):
   Instead of just returning raw string IDs, the binder resolves child references into a ChildNode object. A ChildNode pairs the target componentId with the basePath it should use for data resolution.
   For ChildList properties using the template feature, the binder automatically iterates over the bound data array, generating a list of ChildNodes with correctly scoped basePaths for each item.

   • Example (Single): {"child": ChildNode(id: "text1", basePath: "/user")}
   • Example (List): {"children": [ChildNode(id: "item_tpl", basePath: "/users/0"), ...]}

4. CHECKABLE Properties (Validation):
   If a component has a checks array, the binder evaluates all conditions reactively. It injects two new properties into the map alongside the original data:

   • isValid (bool)
   • validationErrors (List)

Example: Generic Binder & Extension Types

// 1. The Core Types in a2ui_core
class ChildNode {
  final String id;
  final String basePath;
  ChildNode(this.id, this.basePath);
}

class GenericBinder {
  GenericBinder(this.context, this.schema);
  
  /// A reactive ValueListenable that emits a new map whenever any bound data path, 
  /// function, or validation check changes.
  ValueListenable<Map<String, dynamic>> get resolvedProps;
  
  void dispose();
}

// 2. The Developer defines a zero-cost Extension Type for type safety
extension type ButtonProps(Map<String, dynamic> _props) {
  // Resolved DYNAMIC properties
  String? get label => _props['label'] as String?;
  
  // Resolved ACTION properties (ready-to-call closures)
  Future<void> Function()? get action => _props['action'] as Future<void> Function()?;
  
  // Resolved CHECKABLE properties (injected by the binder)
  bool get isValid => _props['isValid'] as bool? ?? true;
  List<String> get validationErrors => (_props['validationErrors'] as List?)?.cast<String>() ?? [];
  
  // Resolved STRUCTURAL properties
  ChildNode get childNode => _props['child'] as ChildNode;
}

// 3. Example usage in a Framework Adapter (e.g., Flutter)
class ButtonImplementation extends StatefulWidget {
  final ComponentContext context;
  final Schema schema;
  // ... constructor
}

class _ButtonImplementationState extends State<ButtonImplementation> {
  late GenericBinder _binder;

  @override
  void initState() {
    super.initState();
    _binder = GenericBinder(widget.context, widget.schema);
    // Listen to the binder's signal (implementation depends on framework adapter)
    _binder.resolvedProps.addListener(_onPropsChanged);
  }
  
  void _onPropsChanged() => setState((){});

  @override
  Widget build(BuildContext context) {
    // Wrap the raw map in our strictly typed extension
    final props = ButtonProps(_binder.resolvedProps.value);

    return ElevatedButton(
      // The action is ready to call, and validation state is automatically evaluated!
      onPressed: props.isValid ? props.action : null,
      // Build structural child, passing the explicitly scoped data context
      child: widget.context.buildChild(
        props.childNode.id, 
        widget.context.dataContext.nested(props.childNode.basePath)
      ), 
    );
  }
  
  @override
  void dispose() {
    _binder.dispose(); // Cleans up all data model subscriptions!
    super.dispose();
  }
}

Implementation Process

Phase 1: Foundational Utilities

• Implement DataPath with full JSON Pointer support.
• Implement ValueNotifier<T>, ValueListenable<T>, ComputedNotifier<T>, and batch logic in reactivity.dart.
• Set up the A2uiError hierarchy (A2uiValidationError, A2uiDataError, A2uiExpressionError, A2uiStateError).
• Port CancellationSignal for managing asynchronous function lifetimes.

Phase 2: Reactive Models

• Implement DataModel with bubble/cascade notification logic and WeakReference caching for notifiers.
• Implement ComponentModel and SurfaceComponentsModel (the adjacency list).
• Implement SurfaceModel and SurfaceGroupModel.

Phase 3: Protocol, Processing, and Binding

• Define A2uiMessage types and JSON serialization logic.
• Implement MessageProcessor to bridge messages and models.
• Implement DataContext with resolution logic (resolveSync, resolveListenable) and ComponentContext for scoped data access.
• Implement GenericBinder to scrape json_schema_builder schemas and automate reactivity based on inferred traits (DYNAMIC, ACTION, STRUCTURAL, CHECKABLE).

Phase 4: Capabilities & Schemas

• Implement getClientCapabilities with inlineCatalogs generation.
• Implement REF: tag processing for schema references.
• Integrate json_schema_builder for robust validation.

Phase 5: Minimal Catalog

• Implement MinimalCatalog definitions (Text, Row, Column, Button, TextField) as the initial testing target.

Testing Strategy

1. Unit Tests:
   • DataPath: Test parsing, joining, and segment extraction.
   • ValueNotifier and ComputedNotifier: Test notifications, dependency tracking, batching, and disposals.
   • DataModel: Test bubble/cascade notifications across deeply nested paths and verify WeakReference cleanup.
   • MessageProcessor: Test state transitions for all message types.
2. Protocol Tests:
   • Use JSON samples from the A2UI specification to verify parsing and model updates.
3. Validation Tests:
   • Verify that invalid messages (missing IDs, wrong types) are correctly caught and reported.
4. Reactivity Tests:
   • Ensure that updating the DataModel triggers the correct ValueListenable updates and that listeners are notified exactly once per batch.

[jacobsimionato]

I'm trying to implement now with this prompt, in a workspace that has genui and A2UI repos side by side so we can refer to files in both for context purposes.

I pasted the design doc above into a file at a2ui_core_design.md.

Implement a2ui_core at genui/packages/a2ui_core, following @a2ui_core_design.md .

Also see @A2UI/specification/v0_9/docs/renderer_guide.md as a more generic guide.

In web_core, see @A2UI/renderers/web_core/src/v0_9/rendering/generic-binder.ts and
@A2UI/renderers/web_core/src/v0_9/state/data-model.ts and @A2UI/renderers/web_core/src/v0_9/rendering/data-context.ts for specific references.

   *   @A2UI/specification/v0_9/docs/a2ui_protocol.md (for protocol rules)
   *   @A2UI/specification/v0_9/json/common_types.json (for dynamic binding types)
   *   @A2UI/specification/v0_9/json/server_to_client.json (for message envelopes)
   *   @A2UI/specification/v0_9/json/client_to_server.json (for message envelopes)
   *   @A2UI/specification/v0_9/json/catalogs/minimal/minimal_catalog.json (your initial target)
   *   Take inspiration from web_core, at @A2UI/renderers/web_core/src/v0_9/ .

   As you go, write tests to verify things work. Look at the structure of genui/packages/genui/ to follow. See
   @genui/packages/genui/pubspec.yaml etc.

[jacobsimionato]

Here's a prototype PR: #831