gskinnerteam/flutter-hatcha-app/genui

┌─────────────────────────────────────┐
│   Application (Flutter Widgets)     │
├─────────────────────────────────────┤
│   Facade Layer                      │
│   - Conversation                    │
│   - PromptBuilder                   │
│   - Surface (Widget)                │
├─────────────────────────────────────┤
│   Engine Layer                      │
│   - SurfaceController               │
│   - SurfaceRegistry                 │
│   - DataModelStore                  │
├─────────────────────────────────────┤
│   Model Layer                       │
│   - Catalog, CatalogItem            │
│   - DataModel, DataContext          │
│   - A2uiMessage types              │
│   - ChatMessage types               │
│   - A2UiClientCapabilities          │
├─────────────────────────────────────┤
│   Transport Layer                   │
│   - Transport (interface)           │
│   - A2uiTransportAdapter            │
│   - A2uiParserTransformer           │
├─────────────────────────────────────┤
│   Interfaces                        │
│   - SurfaceHost                     │
│   - SurfaceContext                  │
│   - A2uiMessageSink                │
└─────────────────────────────────────┘

User
 │  (1) sendRequest(ChatMessage)
 ▼
Conversation ──► Transport (A2A / Direct AI)
 │                    │
 │  (2) incomingMessages (Stream<A2uiMessage>)
 │      incomingText (Stream<String>)
 ▼                    │
SurfaceController ◄───┘
 │  (3) surfaceUpdates (Stream<SurfaceUpdate>)
 ▼
Surface (Flutter Widget)
 │  (4) Catalog widget builders render
 │      Flutter widgets from Components
 ▼
User interactions → UiEvent → back to Transport

Conversation({
  required SurfaceController controller,
  required Transport transport,
})

class ConversationState {
  final List<String> surfaces;   // Active surface IDs
  final String latestText;       // Latest text received
  final bool isWaiting;          // Waiting for response
}

Surface({
  required SurfaceHost host,
  required String surfaceId,
  WidgetBuilder? defaultBuilder,
})

abstract interface class Transport {
  Stream<String> get incomingText;
  Stream<A2uiMessage> get incomingMessages;
  Future<void> sendRequest(ChatMessage message);
  void dispose();
}

A2uiTransportAdapter({ManualSendCallback? onSend})

SurfaceController({
  required Iterable<Catalog> catalogs,
  Duration pendingUpdateTimeout = const Duration(minutes: 1),
})

// Chat-style: creates new surfaces per response, no deletions
PromptBuilder.chat({
  required Catalog catalog,
  Iterable<String> systemPromptFragments = const [],
  String importancePrefix = 'IMPORTANT: ',
  JsonMap? clientDataModel,
})
 
// Custom operations control
PromptBuilder.custom({
  required Catalog catalog,
  required SurfaceOperations allowedOperations,
  Iterable<String> systemPromptFragments = const [],
  ...
})

A2UiClientCapabilities({
  required List<String> supportedCatalogIds,
  List<JsonMap>? inlineCatalogs,
})
 
// From catalogs:
factory A2UiClientCapabilities.fromCatalogs(
  Iterable<Catalog> catalogs, {
  InlineCatalogHandling inlineHandling = InlineCatalogHandling.missingIds,
})

sealed class SurfaceUpdate {
  final String surfaceId;
}
 
final class SurfaceAdded extends SurfaceUpdate {
  final SurfaceDefinition definition;
}
 
final class ComponentsUpdated extends SurfaceUpdate {
  final SurfaceDefinition definition;
}
 
final class SurfaceRemoved extends SurfaceUpdate {}