Merge remote-tracking branch 'upstream/main' into fix-padding

Author: andrewkolos

CONTRIBUTING.md

@@ -113,3 +113,10 @@ releasing a new version.
 [P1]: https://github.com/flutter/genui/labels?q=P1
 [P2]: https://github.com/flutter/genui/labels?q=P2
 [P3]: https://github.com/flutter/genui/labels?q=P3
+
+## pubspec.lock files
+
+`pubspec.lock` files are not git ignored to make the bots faster.
+
+If you include `pubspec.lock` file to your PR, make sure to run `flutter pub upgrade`,
+when your Flutter is latest at beta channel.

README.md

@@ -7,7 +7,7 @@ See the [Getting started with GenUI](https://www.youtube.com/watch?v=nWr6eZKM6no
 
 [<img src="docs/assets/genui_intro_video_still.png" alt="GenUI Intro video still" height="500">](https://www.youtube.com/watch?v=nWr6eZKM6no)
 
-## Status: Highly Experimental
+## Status: highly experimental
 
 This is a highly experimental package, which means the API will change (sometimes drastically).
 [Feedback is very welcome](https://github.com/flutter/genui/issues/new/choose).
@@ -41,16 +41,16 @@ chatbots and next-generation agent-based user experiences.
 - Create dynamically composed UIs: an agent can generate a complete form with sliders, date pickers,
   and text fields on the fly based on a user's request to "book a flight."
 
-## Look & Feel
+## Look & feel
 
-### Interactive [Travel App Example](examples/travel_app/)
+### Interactive [travel app example](examples/travel_app/)
 
 <img src="docs/assets/travel_app_genui_example.gif" alt="GenUI Travel App Demo" height="500">
 
 _The GIF above shows how GenUI enables dynamic, interactive UI generation,_
 _instead of text descriptions or code from a traditional AI coding agent._
 
-### Core Difference
+### Core difference
 
 This UI is not generated in the form of code; rather, it's generated at runtime
 based on a widget catalog from the developers' project.
@@ -72,7 +72,7 @@ based on a widget catalog from the developers' project.
 - **Basic Layout:** LLM-driven basic layout generation.
 - **Any Model:** Integrate with any LLM that can generate structured JSON output.
 
-## Connecting to an AI Agent
+## Connecting to an AI agent
 
 The `genui` framework uses a `ContentGenerator` to communicate with a generative AI model,
 allowing `genui` to be backend agnostic. You can choose the implementation that best fits
@@ -84,15 +84,33 @@ See the package table below for more details on each.
 
 ## Packages
 
-| Package                                                            | Description                                                                                                                                                                  |
-| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [genui](packages/genui/)                                           | The core framework to employ Generative UI.                                                                                                                                  |
-| [genui_firebase_ai](packages/genui_firebase_ai/)                   | Provides **`FirebaseAiContentGenerator`** to connect to Gemini via Firebase AI Logic. This is the recommended approach for production apps based on client-side agents.      |
-| [genui_google_generative_ai](packages/genui_google_generative_ai/) | Provides **`GoogleGenerativeAiContentGenerator`** for connecting to the Google Generative AI API with only an API key. Ideal for getting started quickly.                    |
-| [genui_a2ui](packages/genui_a2ui/)                                 | Provides **`A2uiContentGenerator`** for connecting to any server that implements the [A2UI protocol](https://a2ui.org). Use this for integrating with custom agent backends. |
-| [json_schema_builder](packages/json_schema_builder/)               | A fully featured Dart JSON Schema package with validation, used by the core framework to define widget data structures.                                                      |
-
-## Getting Started
+| Package | Description | Version |
+| :--- | :--- | :--- |
+| [genui](packages/genui/) | The core framework to employ Generative UI. | [![pub package](https://img.shields.io/pub/v/genui.svg)](https://pub.dev/packages/genui) |
+| [genui_firebase_ai](packages/genui_firebase_ai/) | Provides **`FirebaseAiContentGenerator`** to connect to Gemini via Firebase AI Logic. This is the recommended approach for production apps based on client-side agents. | [![pub package](https://img.shields.io/pub/v/genui_firebase_ai.svg)](https://pub.dev/packages/genui_firebase_ai) |
+| [genui_google_generative_ai](packages/genui_google_generative_ai/) | Provides **`GoogleGenerativeAiContentGenerator`** for connecting to the Google Generative AI API with only an API key. Ideal for getting started quickly. | [![pub package](https://img.shields.io/pub/v/genui_google_generative_ai.svg)](https://pub.dev/packages/genui_google_generative_ai) |
+| [genui_a2ui](packages/genui_a2ui/) | Provides **`A2uiContentGenerator`** for connecting to any server that implements the [A2UI protocol](https://a2ui.org). Use this for integrating with custom agent backends. | [![pub package](https://img.shields.io/pub/v/genui_a2ui.svg)](https://pub.dev/packages/genui_a2ui) |
+| [json_schema_builder](packages/json_schema_builder/) | A fully featured Dart JSON Schema package with validation, used by the core framework to define widget data structures. | [![pub package](https://img.shields.io/pub/v/json_schema_builder.svg)](https://pub.dev/packages/json_schema_builder) |
+
+### Dependencies
+
+This diagram shows how packages depend on each other and how examples use them.
+
+```mermaid
+graph TD
+  examples/simple_chat --> genui_google_generative_ai
+  examples/simple_chat --> genui_firebase_ai
+  examples/travel_app --> genui_google_generative_ai
+  examples/travel_app --> genui_firebase_ai
+  examples/verdure --> genui_a2ui
+  examples/custom_backend --> genui
+  genui --> json_schema_builder
+  genui_a2ui --> genui
+  genui_firebase_ai --> genui
+  genui_google_generative_ai --> genui
+```
+
+## Getting started
 
 See the [genui getting started guide](packages/genui/README.md#getting-started-with-genui).
 

examples/catalog_gallery/lib/samples_view.dart

@@ -31,7 +31,7 @@ class _SamplesViewState extends State<SamplesView> {
   List<File> _sampleFiles = [];
   File? _selectedFile;
   Sample? _selectedSample;
-  late GenUiManager _genUiManager;
+  late A2uiMessageProcessor _a2uiMessageProcessor;
   final List<String> _surfaceIds = [];
   int _currentSurfaceIndex = 0;
   StreamSubscription<GenUiUpdate>? _surfaceSubscription;
@@ -40,7 +40,7 @@ class _SamplesViewState extends State<SamplesView> {
   @override
   void initState() {
     super.initState();
-    _genUiManager = GenUiManager(catalogs: [widget.catalog]);
+    _a2uiMessageProcessor = A2uiMessageProcessor(catalogs: [widget.catalog]);
     _loadSamples();
     _setupSurfaceListener();
   }
@@ -49,12 +49,14 @@ class _SamplesViewState extends State<SamplesView> {
   void dispose() {
     _surfaceSubscription?.cancel();
     _messageSubscription?.cancel();
-    _genUiManager.dispose();
+    _a2uiMessageProcessor.dispose();
     super.dispose();
   }
 
   void _setupSurfaceListener() {
-    _surfaceSubscription = _genUiManager.surfaceUpdates.listen((update) {
+    _surfaceSubscription = _a2uiMessageProcessor.surfaceUpdates.listen((
+      update,
+    ) {
       if (update is SurfaceAdded) {
         if (!_surfaceIds.contains(update.surfaceId)) {
           setState(() {
@@ -107,9 +109,10 @@ class _SamplesViewState extends State<SamplesView> {
       _surfaceIds.clear();
       _currentSurfaceIndex = 0;
     });
-    // Re-create GenUiManager to ensure a clean state for the new sample.
-    _genUiManager.dispose();
-    _genUiManager = GenUiManager(catalogs: [widget.catalog]);
+    // Re-create A2uiMessageProcessor to ensure a clean state for the new
+    // sample.
+    _a2uiMessageProcessor.dispose();
+    _a2uiMessageProcessor = A2uiMessageProcessor(catalogs: [widget.catalog]);
     _setupSurfaceListener();
 
     try {
@@ -120,7 +123,7 @@ class _SamplesViewState extends State<SamplesView> {
       });
 
       _messageSubscription = sample.messages.listen(
-        _genUiManager.handleMessage,
+        _a2uiMessageProcessor.handleMessage,
         onError: (Object e) {
           debugPrint('Error processing message: $e');
           if (!context.mounted) return;
@@ -226,7 +229,7 @@ class _SamplesViewState extends State<SamplesView> {
                           ? const Center(child: Text('No surfaces'))
                           : GenUiSurface(
                               key: ValueKey(_surfaceIds[_currentSurfaceIndex]),
-                              host: _genUiManager,
+                              host: _a2uiMessageProcessor,
                               surfaceId: _surfaceIds[_currentSurfaceIndex],
                             ),
                     ),

examples/custom_backend/lib/main.dart

@@ -77,7 +77,9 @@ class _IntegrationTesterState extends State<_IntegrationTester> {
   final _controller = TextEditingController(text: requestText);
 
   final _protocol = Backend(uiSchema);
-  late final GenUiManager _genUi = GenUiManager(catalogs: [_catalog]);
+  late final A2uiMessageProcessor _a2uiMessageProcessor = A2uiMessageProcessor(
+    catalogs: [_catalog],
+  );
   String? _selectedResponse;
   bool _isLoading = false;
   String? _errorMessage;
@@ -116,7 +118,7 @@ class _IntegrationTesterState extends State<_IntegrationTester> {
               }
               _surfaceId = parsedToolCall.surfaceId;
               for (final A2uiMessage message in parsedToolCall.messages) {
-                _genUi.handleMessage(message);
+                _a2uiMessageProcessor.handleMessage(message);
               }
               print('UI received for surfaceId=${parsedToolCall.surfaceId}');
               setState(() => _isLoading = false);
@@ -157,7 +159,7 @@ class _IntegrationTesterState extends State<_IntegrationTester> {
     }
     return GenUiSurface(
       surfaceId: surfaceId,
-      host: _genUi,
+      host: _a2uiMessageProcessor,
       defaultBuilder: (_) => const Text('Fallback to defaultBuilder'),
     );
   }

examples/simple_chat/README.md

@@ -32,7 +32,7 @@ The application's logic is contained almost entirely within `lib/main.dart`.
 5. **UI Rendering**:
    - `GenUiConversation` listens to the stream and processes the `A2uiMessage`s, invoking the appropriate callbacks like `onSurfaceAdded`.
    - The `_handleSurfaceAdded` callback adds a new message item to the list, containing the `surfaceId`.
-   - The `ListView` rebuilds, and a `GenUiSurface` widget is rendered for the AI's message, dynamically building the UI based on the `UiDefinition` managed by `GenUiManager`.
+   - The `ListView` rebuilds, and a `GenUiSurface` widget is rendered for the AI's message, dynamically building the UI based on the `UiDefinition` managed by `A2uiMessageProcessor`.
 
 ## Getting Started
 

…ples/simple_chat/lib/io_get_api_key.dart …ple_chat/lib/api_key/io_get_api_key.dartexamples/simple_chat/lib/io_get_api_key.dart renamed to examples/simple_chat/lib/api_key/io_get_api_key.dart examples/simple_chat/lib/io_get_api_key.dart renamed to examples/simple_chat/lib/api_key/io_get_api_key.dart

@@ -7,12 +7,17 @@ import 'dart:io';
 /// API key for Google Generative AI (only needed if using google backend).
 /// Get an API key from https://aistudio.google.com/app/apikey
 /// Specify this when running the app with "-D GEMINI_API_KEY=$GEMINI_API_KEY"
-const String geminiApiKey = String.fromEnvironment('GEMINI_API_KEY');
+const String _geminiApiKey = String.fromEnvironment('GEMINI_API_KEY');
+
+String? debugApiKey;
 
 String getApiKey() {
-  String apiKey = geminiApiKey.isEmpty
+  if (debugApiKey != null) {
+    return debugApiKey!;
+  }
+  String apiKey = _geminiApiKey.isEmpty
       ? Platform.environment['GEMINI_API_KEY'] ?? ''
-      : geminiApiKey;
+      : _geminiApiKey;
   if (apiKey.isEmpty) {
     throw Exception(
       '''Gemini API key is required when using google backend. Run the app with a GEMINI_API_KEY as a Dart environment variable, for example by running with -D GEMINI_API_KEY=\$GEMINI_API_KEY or set the GEMINI_API_KEY environment variable in your shell environment.''',

…les/simple_chat/lib/web_get_api_key.dart …le_chat/lib/api_key/web_get_api_key.dartexamples/simple_chat/lib/web_get_api_key.dart renamed to examples/simple_chat/lib/api_key/web_get_api_key.dart examples/simple_chat/lib/web_get_api_key.dart renamed to examples/simple_chat/lib/api_key/web_get_api_key.dart

@@ -4,13 +4,18 @@
 
 /// API key for Google Generative AI (only needed if using google backend).
 /// Get an API key from https://aistudio.google.com/app/apikey
-const String geminiApiKey = String.fromEnvironment('GEMINI_API_KEY');
+const String _geminiApiKey = String.fromEnvironment('GEMINI_API_KEY');
+
+String? debugApiKey;
 
 String getApiKey() {
-  if (geminiApiKey.isEmpty) {
+  if (debugApiKey != null) {
+    return debugApiKey!;
+  }
+  if (_geminiApiKey.isEmpty) {
     throw Exception(
       '''Gemini API key is required when using google backend. Run the app with a GEMINI_API_KEY as a Dart environment variable. You can do this by running with -D GEMINI_API_KEY=\$GEMINI_API_KEY''',
     );
   }
-  return geminiApiKey;
+  return _geminiApiKey;
 }

examples/simple_chat/lib/main.dart

@@ -11,8 +11,6 @@ import 'package:genui_firebase_ai/genui_firebase_ai.dart';
 import 'package:genui_google_generative_ai/genui_google_generative_ai.dart';
 import 'package:logging/logging.dart';
 
-import 'configuration.dart';
-
 // If you want to convert to using Firebase AI, run:
 //
 //   sh tool/refresh_firebase.sh <project_id>
@@ -26,7 +24,9 @@ import 'configuration.dart';
 
 // Conditionally import non-web version so we can read from shell env vars in
 // non-web version.
-import 'io_get_api_key.dart' if (dart.library.html) 'web_get_api_key.dart';
+import 'api_key/io_get_api_key.dart'
+    if (dart.library.html) 'api_key/web_get_api_key.dart';
+import 'configuration.dart';
 import 'message.dart';
 
 void main() async {
@@ -69,14 +69,14 @@ class _ChatScreenState extends State<ChatScreen> {
   final TextEditingController _textController = TextEditingController();
   final List<MessageController> _messages = [];
   late final GenUiConversation _genUiConversation;
-  late final GenUiManager _genUiManager;
+  late final A2uiMessageProcessor _a2uiMessageProcessor;
   final ScrollController _scrollController = ScrollController();
 
   @override
   void initState() {
     super.initState();
     final Catalog catalog = CoreCatalogItems.asCatalog();
-    _genUiManager = GenUiManager(catalogs: [catalog]);
+    _a2uiMessageProcessor = A2uiMessageProcessor(catalogs: [catalog]);
 
     final systemInstruction =
         '''You are a helpful assistant who chats with a user,
@@ -107,7 +107,7 @@ ${GenUiPromptFragments.basicChat}''';
     };
 
     _genUiConversation = GenUiConversation(
-      genUiManager: _genUiManager,
+      a2uiMessageProcessor: _a2uiMessageProcessor,
       contentGenerator: contentGenerator,
       onSurfaceAdded: _handleSurfaceAdded,
       onTextResponse: _onTextResponse,

examples/simple_chat/test/smoke_test.dart

@@ -0,0 +1,24 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:simple_chat/api_key/io_get_api_key.dart';
+import 'package:simple_chat/main.dart';
+
+void main() {
+  setUp(() {
+    debugApiKey = 'dummy_api_key';
+  });
+
+  tearDown(() {
+    debugApiKey = null;
+  });
+
+  testWidgets('Smoke test: App starts without issues', (
+    WidgetTester tester,
+  ) async {
+    await tester.pumpWidget(const MyApp());
+    expect(find.byType(ChatScreen), findsOneWidget);
+  });
+}

examples/travel_app/README.md

@@ -23,7 +23,7 @@ This example highlights several core concepts of the `genui` package:
 - **Dynamic UI Generation**: The entire user interface is constructed on-the-fly by the AI based on the conversation.
 - **Component Catalog**: The AI builds the UI from a custom, domain-specific catalog of widgets defined in `lib/src/catalog.dart`. This includes widgets like `TravelCarousel`, `ItineraryEntry`, and `OptionsFilterChipInput`.
 - **System Prompt Engineering**: The behavior of the AI is guided by a detailed system prompt located in `lib/src/travel_planner_page.dart`. This prompt instructs the AI on how to act like a travel agent and which widgets to use in various scenarios.
-- **Dynamic UI State Management**: The `GenUiConversation` and `GenUiManager` from `genui` handle the orchestration of AI interaction, state of the dynamically generated UI surfaces, and event processing.
+- **Dynamic UI State Management**: The `GenUiConversation` and `A2uiMessageProcessor` from `genui` handle the orchestration of AI interaction, state of the dynamically generated UI surfaces, and event processing.
 - **Multiple AI Backends**: The app supports switching between **Google Generative AI** (direct API) and **Firebase Vertex AI**. This is configured in `lib/src/config/configuration.dart`.
 - **Tool Use**: The AI uses tools like `ListHotelsTool` to fetch real-world data (mocked in this example) and present it to the user.
 - **Widget Catalog**: A dedicated tab allows developers to inspect all available widgets in the catalog, facilitating development and debugging.