Update dot guides based on latest API surface (#531)

Author: jacobsimionato

.gemini/GEMINI.md

@@ -73,12 +73,16 @@ The project uses standard `flutter` and `dart` commands. A comprehensive script
 - The examples and the `genui_firebase_ai` package use Firebase.
 - A script at `tool/stub_firebase_options.sh` is used in CI to create a stub `firebase_options.dart` file. For local development, developers need to configure their own Firebase project by following the instructions in `packages/genui/USAGE.md`.
 
-## Folder `spikes`
+## Updating the Guides (`packages/genui/.guides`)
 
-The folder `spikes` contains experiments and proof of concepts,
-that does not have to be of good quality.
+When asked to update the developer guides located in `packages/genui/.guides`, it is critical to ensure the documentation accurately reflects the current state of the codebase. Before making any changes to the guides, you must read *all* the Dart code in the following packages:
 
-Skip this folder when reviewing code.
+-   `packages/genui`
+-   `packages/genui_firebase_ai`
+-   `packages/genui_google_generative_ai`
+-   `packages/genui_a2ui`
+
+This ensures that any code examples, API references, and architectural explanations in the guides are up-to-date and consistent with the actual implementation.
 
 ## Draft pull requests
 

packages/genui/.guides/docs/connect_to_agent_provider.md

@@ -2,7 +2,8 @@
 title: Connecting to an agent provider
 description: |
   Instructions for connecting `genui` to the agent provider of your
-  choice.
+  choice. See `setup.md` for a description of the different `ContentGenerator`
+  implementations that are available.
 ---
 
 Follow these steps to connect `genui` to an agent provider and give
@@ -32,65 +33,60 @@ and a `ContentGenerator`.
     ```dart
     import 'package:flutter/material.dart';
     import 'package:genui/genui.dart';
-
-    // Replace with your actual ContentGenerator implementation
-    class YourContentGenerator implements ContentGenerator {
-      // ... implementation details ...
-      @override
-      Stream<A2uiMessage> get a2uiMessageStream => Stream.empty(); // Replace
-      @override
-      Stream<String> get textResponseStream => Stream.empty(); // Replace
-      @override
-      Stream<ContentGeneratorError> get errorStream => Stream.empty(); // Replace
-      @override
-      ValueListenable<bool> get isProcessing => ValueNotifier(false); // Replace
-      @override
-      Future<void> sendRequest(
-        ChatMessage message, {
-        Iterable<ChatMessage>? history,
-      }) async { /* ... */ }
-      @override
-      void dispose() { /* ... */ }
-    }
+    import 'package:genui_firebase_ai/genui_firebase_ai.dart';
 
     class _MyHomePageState extends State<MyHomePage> {
       late final GenUiManager _genUiManager;
       late final GenUiConversation _genUiConversation;
-      final _surfaceIds = <String>[];
+      final _messages = <ChatMessage>[];
 
       @override
       void initState() {
         super.initState();
 
         _genUiManager = GenUiManager(catalog: CoreCatalogItems.asCatalog());
 
-        // NOTE: You need a concrete implementation of ContentGenerator here.
-        // The 'genui_firebase_ai' package provides implementations
-        // like FirebaseAiContentGenerator.
-        final contentGenerator = YourContentGenerator();
+        // Use a concrete implementation of ContentGenerator.
+        final contentGenerator = FirebaseAiContentGenerator(
+          catalog: _genUiManager.catalog,
+          systemInstruction: 'You are a helpful assistant.',
+          additionalTools: const [],
+        );
 
         _genUiConversation = GenUiConversation(
           genUiManager: _genUiManager,
           contentGenerator: contentGenerator,
           onSurfaceAdded: _onSurfaceAdded,
-          onSurfaceUpdated: _onSurfaceUpdated, // Example callback
+          onSurfaceUpdated: _onSurfaceUpdated,
           onSurfaceDeleted: _onSurfaceDeleted,
           onTextResponse: (text) => print('AI Text: $text'),
           onError: (error) => print('AI Error: ${error.error}'),
         );
       }
 
       void _onSurfaceAdded(SurfaceAdded update) {
-        setState(() => _surfaceIds.add(update.surfaceId));
+        setState(() {
+          _messages.add(
+            AiUiMessage(
+              definition: update.definition,
+              surfaceId: update.surfaceId,
+            ),
+          );
+        });
       }
 
       void _onSurfaceUpdated(SurfaceUpdated update) {
-        // Handle surface updates if needed
+        // Handle surface updates if needed. For example, you might want to
+        // scroll to the bottom of a list when a surface is updated.
         print('Surface ${update.surfaceId} updated');
       }
 
       void _onSurfaceDeleted(SurfaceRemoved update) {
-        setState(() => _surfaceIds.remove(update.surfaceId));
+        setState(
+          () => _messages.removeWhere(
+            (m) => m is AiUiMessage && m.surfaceId == update.surfaceId,
+          ),
+        );
       }
 
       @override
@@ -122,18 +118,28 @@ To receive and display generated UI:
       // ...
 
       final _textController = TextEditingController();
-      final _surfaceIds = <String>[];
+      final _messages = <ChatMessage>[];
 
       // Send a message containing the user's text to the agent.
       void _sendMessage(String text) {
         if (text.trim().isEmpty) return;
-        _genUiConversation.sendRequest(UserMessage.text(text));
+        final message = UserMessage.text(text);
+        setState(() => _messages.add(message));
+        _genUiConversation.sendRequest(message);
+      }
+
+      void _onSurfaceAdded(SurfaceAdded update) {
+        setState(() {
+          _messages.add(
+            AiUiMessage(
+              definition: update.definition,
+              surfaceId: update.surfaceId,
+            ),
+          );
+        });
       }
 
-      // Callbacks for GenUiConversation (defined in initState example above)
-      // void _onSurfaceAdded(SurfaceAdded update) { ... }
-      // void _onSurfaceUpdated(SurfaceUpdated update) { ... }
-      // void _onSurfaceDeleted(SurfaceRemoved update) { ... }
+      // ... other callbacks
 
       @override
       Widget build(BuildContext context) {
@@ -146,40 +152,22 @@ To receive and display generated UI:
             children: [
               Expanded(
                 child: ListView.builder(
-                  itemCount: _surfaceIds.length,
+                  itemCount: _messages.length,
                   itemBuilder: (context, index) {
-                    // For each surface, create a GenUiSurface to display it.
-                    final id = _surfaceIds[index];
-                    return GenUiSurface(host: _genUiConversation.host, surfaceId: id);
-                  },
-                ),
-              ),
-              SafeArea(
-                child: Padding(
-                  padding: const EdgeInsets.symmetric(horizontal: 16.0),
-                  child: Row(
-                    children: [
-                      Expanded(
-                        child: TextField(
-                          controller: _textController,
-                          decoration: const InputDecoration(
-                            hintText: 'Enter a message',
-                          ),
+                    final message = _messages[index];
+                    return switch (message) {
+                      AiUiMessage() => GenUiSurface(
+                          host: _genUiConversation.host,
+                          surfaceId: message.surfaceId,
                         ),
-                      ),
-                      const SizedBox(width: 16),
-                      ElevatedButton(
-                        onPressed: () {
-                          // Send the user's text to the agent.
-                          _sendMessage(_textController.text);
-                          _textController.clear();
-                        },
-                        child: const Text('Send'),
-                      ),
-                    ],
-                  ),
+                      AiTextMessage() => ListTile(title: Text(message.text)),
+                      UserMessage() => ListTile(title: Text(message.text)),
+                      _ => const SizedBox.shrink(),
+                    };
+                  },
                 ),
               ),
+              // ... text input row
             ],
           ),
         );

packages/genui/.guides/docs/create_a_custom_catalogitem.md

@@ -60,21 +60,10 @@ final riddleCard = CatalogItem(
   }) {
     final json = data as Map<String, Object?>;
 
-    // 1. Resolve the question reference
-    final questionRef = json['question'] as Map<String, Object?>;
-    final questionPath = questionRef['path'] as String?;
-    final questionLiteral = questionRef['literalString'] as String?;
-    final questionNotifier = questionPath != null
-        ? dataContext.subscribe<String>(questionPath)
-        : ValueNotifier<String?>(questionLiteral);
-
-    // 2. Resolve the answer reference
-    final answerRef = json['answer'] as Map<String, Object?>;
-    final answerPath = answerRef['path'] as String?;
-    final answerLiteral = answerRef['literalString'] as String?;
-    final answerNotifier = answerPath != null
-        ? dataContext.subscribe<String>(answerPath)
-        : ValueNotifier<String?>(answerLiteral);
+    final questionNotifier =
+        dataContext.subscribeToString(json['question'] as Map<String, Object?>?);
+    final answerNotifier =
+        dataContext.subscribeToString(json['answer'] as Map<String, Object?>?);
 
     // 3. Use ValueListenableBuilder to build the UI reactively
     return ValueListenableBuilder<String?>(

packages/genui/.guides/examples/riddles.dart

@@ -254,8 +254,6 @@ final riddleCard = CatalogItem(
     required context,
     required dataContext,
   }) {
-    final json = data as Map<String, Object?>;
-
     final questionNotifier =
         dataContext.subscribeToString(json['question'] as Map<String, Object?>?);
     final answerNotifier =

packages/genui/.guides/setup.md

@@ -4,7 +4,25 @@ Use the following instructions to add `genui` to your Flutter app. The
 code examples show how to perform the instructions on a brand new app created by
 running `flutter create`.
 
-## 1. Configure your agent provider
+## 1. Choosing a ContentGenerator
+
+`genui` provides three `ContentGenerator` implementations for connecting to
+different types of agent providers. Use the following guide to choose the one
+that best fits your needs.
+
+- **`FirebaseAiContentGenerator`**: Use this when you are ready to deploy your
+  app. This generator connects to Gemini via Firebase AI Logic, and is the
+  recommended approach for production apps.
+
+- **`GoogleGenerativeAiContentGenerator`**: Use this for prototyping and local
+  development. This generator connects to the Google Generative AI API using an
+  API key, and is a good choice for getting started quickly.
+
+- **`A2uiContentGenerator`**: Use this to connect to a server that implements
+  the A2UI protocol. This is a good choice if you have an existing agent that
+  you want to connect to `genui`.
+
+## 2. Configure your agent provider
 
 `genui` can connect to a variety of agent providers. Choose the section
 below for your preferred provider.
@@ -20,15 +38,16 @@ Logic, follow these instructions:
    for that project. This should also be done by a human.
 3. Follow the first three steps in
    [Firebase's Flutter Setup guide](https://firebase.google.com/docs/flutter/setup)
-   to add Firebase to your app. **Ask me to run `flutterfire configure` for you.**
+   to add Firebase to your app. Run `flutterfire configure` to configure your
+   app.
 4. In `pubspec.yaml`, add `genui` and `genui_firebase_ai` to the
    `dependencies` section. As of this writing, it's best to use pub's git
    dependency to refer directly to this project's source.
 
    ```yaml
    dependencies:
-     genui: ^0.5.1 # Or the latest version
-     genui_firebase_ai: ^0.5.1 # Or the latest version
+     genui: ^0.5.1
+     genui_firebase_ai: ^0.5.1
    ```
 
 5. In your app's `main` method, ensure that the widget bindings are initialized,
@@ -42,12 +61,51 @@ Logic, follow these instructions:
    }
    ```
 
-### Configure another agent provider
+### Configure with the A2UI protocol
+
+To use `genui` with a generic agent provider that supports the A2UI protocol,
+use the `genui_a2ui` package.
+
+1. In `pubspec.yaml`, add `genui` and `genui_a2ui` to the `dependencies`
+   section.
+
+   ```yaml
+   dependencies:
+     genui: ^0.5.1
+     genui_a2ui: ^0.5.1
+   ```
+
+2. Use the `A2uiContentGenerator` to connect to your agent provider.
+
+### Configure with Google Generative AI
+
+To use `genui` with the Google Generative AI API, use the
+`genui_google_generative_ai` package.
+
+1. In `pubspec.yaml`, add `genui` and `genui_google_generative_ai` to the
+   `dependencies` section.
+
+   ```yaml
+   dependencies:
+     genui: ^0.5.1
+     genui_google_generative_ai: ^0.5.1
+   ```
+
+2. Use the `GoogleGenerativeAiContentGenerator` to connect to the Google
+   Generative AI API. You will need to provide your own API key.
+
+### Connecting to a custom backend
+
+There are two ways to connect to a custom backend.
+
+1.  Use the `genui_a2ui` package to connect to a server that implements the
+    A2UI protocol. This is the recommended approach if you have an existing
+    agent that you want to connect to `genui`.
 
-To use `genui` with another agent provider, you need to follow that
-provider's instructions to configure your app, and then create your own subclass
-of `ContentGenerator` to connect to that provider. Use `FirebaseContentGenerator` as an example
-of how to do so.
+2.  Implement your own `ContentGenerator`. This is a good choice if you have a
+    custom backend that does not implement the A2UI protocol. This will require
+    you to convert your UI data source into a stream of `A2uiMessage` messages
+    that can be rendered by the Gen UI SDK.
 
 ## 2. Create the connection to an agent