Update implementation docs and GEMINI.md (#303)

gspencergoog · web-flow · commit 2121ab8f0957 · 2025-09-15T08:51:10.000-07:00
diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md
@@ -1,48 +1,77 @@
-# Instructions for code review
+# Gemini Code Assistant Context
 
-## CatalogItem
+This document provides context for the Gemini Code Assistant to understand the `genui` project.
 
-A CatalogItem is an object which represents a widget that can be instantiated by an LLM. It centralizes the widgetBuilder function for the widget along with the data schema and name.
+## Project Overview
 
-## Structure of a CatalogItem
+This is a monorepo for a Generative UI SDK (`flutter_genui`). The SDK allows developers to add interactive, dynamic, and graphical UI to their applications, generated by a Large Language Model (LLM). Instead of rendering static text responses from an LLM, this SDK allows the LLM to compose UIs from a developer-provided widget catalog.
 
-- Only the variable that defines the CatalogItem should be public. Everything else should be private.
-- The dataSchema must be defined as a Schema object. Look at `packages/flutter_genui/lib/src/catalog/core_widgets/elevated_button.dart` as a guide.
-- Remember to use `Schema.object` and `Schema.enumString` etc.
-- The Schema should _not_ have a "props" member or an "id" member, as those will be injected at a higher level. The schema should just be an object that includes all the properties that are specific to this widget, e.g. content to display.
-- The only imports should be 'package:flutter/material.dart' and the import for CatalogItem - this will be '../../model/catalog_item.dart' for the SDK, or 'package:flutter_genui/flutter_genui.dart' for the example apps.
-- The name of the CatalogItem variable should be in lowerCamelCase (e.g. `myWidgetName`).
-- The name of the CatalogItem itself (the "name" parameter) should be in PascalCase (e.g. "MyWidgetName").
-- Widgets that require controllers or state in order to instantly reflect user inputs (e.g. Radio buttons, checkboxes, text fields) should be implemented as StatefulWidgets which maintain internal UI state. Look at `packages/flutter_genui/lib/src/catalog/core_widgets/radio_group.dart` as an example. There should be a private StatefulWidget class definition in the file.
-- The input schema for CatalogItems should not include parallel lists of data - instead use a single list of object where it makes sense.
-- If you are implementing a CatalogItem that needs to compose other CatalogItems, include a "child" or "children" parameter of String type, which will contain the ID of the child to reference. When building the child or children, use the buildChild function and pass in the string. See `packages/flutter_genui/lib/src/catalog/core_widgets/elevated_button.dart` and `packages/flutter_genui/lib/src/catalog/core_widgets/column.dart` as examples.
-- All interactive UI elements where the user can input data e.g. by typing or selecting from options, or take action by clicking buttons etc, should handle those actions by calling the `dispatchEvent` callback, and including all the context needed for the LLM to understand what the user has done. E.g. if they have selected a specific option, the handler call should include the name of the selected option as the value.
-- All properties in a schema are optional by default. Use the `required` list to specify required properties.
-- When parsing a catalog item in the widgetBuilder, use extension types for the data required by the catalog item, similar to `examples/travel_app/lib/src/catalog/travel_carousel.dart`.
+The project is structured as a monorepo containing several Dart and Flutter packages, along with example applications.
 
-## How to create a new a CatalogItem
+### Key Packages
 
-1. Understand the structure of a CatalogItem by looking at `packages/flutter_genui/lib/src/model/catalog_item.dart` for the type, and `packages/flutter_genui/lib/src/catalog/core_widgets/elevated_button.dart` as an example to follow.
-2. Create a new file in the relevant app, which contains a declaration of a global variable with a CatalogItem. The location of the file should be:
+| Package                              | Description                                                             |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| `packages/flutter_genui`             | The core framework for employing Generative UI.                         |
+| `packages/flutter_genui_firebase_ai` | Firebase AI integration for `flutter_genui`.                            |
+| `packages/dart_schema_builder`       | A Dart JSON Schema package with validation, used by the core framework. |
 
-   - For the generic flutter_genui SDK: `packages/flutter_genui/lib/src/catalog/`
-   - For an example app, at `examples/[MY_APP]/lib/src/catalog/` e.g. for the travel_app: `examples/travel_app/lib/src/catalog/`
+### Example Applications
 
-3. Review your implementation and compare it to the examples, to ensure that the use of parameters matches and the structure of the code is similar. Fix any mistakes.
-4. Write a test for the CatalogItem and run it, fixing any mistakes.
-5. Update the Catalog definition for the app or SDK to include the new item.
+The `examples` directory contains sample applications demonstrating the usage of the `flutter_genui` SDK.
 
-## How to update the CatalogItem API
+| Example           | Description                                                                                                                                                                                                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `simple_chat`     | A minimal example of a conversational chat application. It demonstrates the fundamental concepts of `flutter_genui`, such as initializing the `UiAgent`, sending user messages, and rendering the AI-generated UI surfaces using the default core widget catalog. |
+| `travel_app`      | A more advanced example of a travel planning assistant. It showcases dynamic UI generation, the use of a custom, domain-specific widget catalog, and how user interactions with the UI can be fed back to the AI to refine the conversation.                      |
+| `catalog_gallery` | A simple application that displays the widgets available in the catalog. It's a useful tool for developers to visualize the components that the AI can use to build UIs.                                                                                          |
 
-When the CatalogItem API changes, it is necessary to update all the existing catalog items to match.
+The `simple_chat` and `travel_app` examples are good starting points for understanding the library's capabilities.
 
-1. Understand the change that has been requested, and carefully update the code at `packages/flutter_genui/lib/src/model/catalog_item.dart`.
-2. Update all places that create and use CatalogItems e.g. `packages/flutter_genui/lib/src/model/catalog.dart`. Consider all the code at `packages/flutter_genui/lib/*` when doing this.
-3. Find all CatalogItem implementations which will be at `examples/travel_app/lib/src/catalog/*`, `packages/flutter_genui/lib/src/catalog/*` etc. Update each of them to match the changes in the API.
+## Implementation Details
 
-## How to update every CatalogItem
+For a deeper understanding of the project's architecture and data flow, refer to the following documents:
 
-1. Find all CatalogItem implementations which will be at `examples/travel_app/lib/src/catalog/*`, `packages/flutter_genui/lib/src/catalog/*` etc. Update each of them.
+- **`packages/flutter_genui/IMPLEMENTATION.md`**: Provides a comprehensive overview of the core `flutter_genui` package's architecture, purpose, and implementation.
+- **`examples/travel_app/IMPLEMENTATION.md`**: Describes the architecture and implementation of the `travel_app` example, showcasing how the `flutter_genui` package is used to build a dynamic, conversational UI.
+
+## Building and Running
+
+The project uses standard `flutter` and `dart` commands. A comprehensive script is provided to automate fixes, formatting, analysis, and testing.
+
+### Key Commands
+
+- **Run all checks and tests:**
+
+  ```bash
+  ./tool/run_all_tests_and_fixes.sh
+  ```
+
+  This is a script used by CI for ensuring code quality. It runs `dart fix`, `dart format`, `flutter test`, and `flutter analyze` for all packages and examples in the repository.
+
+## Development Conventions
+
+### Code Style and Formatting
+
+- The project follows the `dart_flutter_team_lints` linting rules, which is the combination of this [analysis_options.yaml](https://raw.githubusercontent.com/dart-lang/ecosystem/refs/heads/main/pkgs/dart_flutter_team_lints/lib/analysis_options.yaml) file and the [recommended](https://raw.githubusercontent.com/dart-lang/core/refs/heads/main/pkgs/lints/lib/recommended.yaml) and [core](https://raw.githubusercontent.com/dart-lang/core/refs/heads/main/pkgs/lints/lib/core.yaml) lints.
+- Code formatting is enforced using the `dart_format` tool.
+- The `tool/run_all_tests_and_fixes.sh` script should be run before committing to ensure all files are correctly formatted and analyzed.
+
+### Testing
+
+- Widget and unit tests are located in the `test` directory of each package/example.
+- Tests are run using `flutter test`.
+- The CI pipeline, defined in `.github/workflows/flutter_packages.yaml`, runs tests for all packages on every push and pull request to the `main` branch.
+
+### Copyright Headers
+
+- All files must have a copyright header.
+- The `tool/fix_copyright.sh` script (which is called by `run_all_tests_and_fixes.sh`) can be used to automatically add or update copyright headers.
+
+### Firebase Integration
+
+- The examples and the `flutter_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/flutter_genui/USAGE.md`.
 
 ## Folder `spikes`
 
@@ -53,5 +82,4 @@ Skip this folder when reviewing code.
 
 ## Draft pull requests
 
-Do not review pull requests, when they are in draft state.
-Wait them to be ready for review.
+Do not review pull requests when they are in draft state. Wait them to be ready for review.
diff --git a/examples/travel_app/IMPLEMENTATION.md b/examples/travel_app/IMPLEMENTATION.md
@@ -67,34 +67,49 @@ classDiagram
 
 ### 1. UI Layer (`main.dart`)
 
-This is the main entry point and the visible part of the application, primarily managed by the `TravelPlannerPage` widget. Its responsibilities are:
+This is the main entry point for the application. Its responsibilities are:
 
-- **Initialization**: It initializes Firebase, the `GenUiManager`, and the `AiClient`.
-- **UI Scaffolding**: It provides the basic structure of the app, which consists of an app bar, a `ConversationWidget` to render the conversation history, and a custom chat input field.
-- **State Management & App Logic**: It holds the core application logic. It manages the `_conversation` history list, sends prompts to the AI via `_triggerInference`, and handles UI events returned from the `GenUiSurface` widgets.
+- **Initialization**: It initializes Firebase and loads the asset image catalog.
+- **UI Scaffolding**: It sets up the root `MaterialApp` and a `Scaffold` with a `TabBar`. The app has two main tabs:
+  - **"Travel"**: This tab contains the `TravelPlannerPage`, which is the primary interface for the conversational travel agent.
+  - **"Widget Catalog"**: This tab displays a `CatalogView` from the `flutter_genui_dev` package, allowing developers to browse and inspect all the available UI components in the app's catalog.
 
-### 2. UI State Management Layer ([`package:flutter_genui`](../../packages/flutter_genui/IMPLEMENTATION.md))
+### 2. App Logic (`lib/src/travel_planner_page.dart`)
+
+The core application logic resides in the `TravelPlannerPage` widget. Its responsibilities are:
+
+- **Initialization**: It initializes the `GenUiManager` and the `AiClient`.
+- **State Management**: It manages the `_conversation` history list, sends prompts to the AI via `_triggerInference`, and handles UI events returned from the `GenUiSurface` widgets.
+- **UI Rendering**: It provides the structure for the chat interface, which consists of a `Conversation` widget to render the conversation history and a custom chat input field.
+
+### 3. UI State Management Layer ([`package:flutter_genui`](../../packages/flutter_genui/IMPLEMENTATION.md))
 
 The components from the `flutter_genui` package are the central orchestrators of the dynamic UI state.
 
 - **`GenUiManager`**: The core state manager. It maintains the definitions for all active UI "surfaces", provides the UI manipulation tools (`addOrUpdateSurface`, `deleteSurface`) to the app logic, and notifies listening widgets (like `TravelPlannerPage`) of changes via a stream.
-- **`ConversationWidget`**: A facade widget that renders a list of `ChatMessage`s. It is responsible for displaying the conversation history, including text messages and dynamically rendered UI surfaces via `GenUiSurface`.
+- **`Conversation` widget**: A widget defined in the app (`lib/src/widgets/conversation.dart`) that renders a list of `ChatMessage`s. It is responsible for displaying the conversation history, including text messages and dynamically rendered UI surfaces via `GenUiSurface`.
 
-### 3. AI/Model Layer (`package:flutter_genui`)
+### 4. AI/Model Layer (`package:flutter_genui_firebase_ai`)
 
-The `GeminiAiClient` class, also part of `flutter_genui`, abstracts the communication with the underlying generative AI model (a Google Gemini model via Firebase). It handles the API calls to the model, sending prompts and receiving the model's responses, including the tool calls that drive the UI generation.
+The `FirebaseAiClient` class, from the `flutter_genui_firebase_ai` package, abstracts the communication with the underlying generative AI model (a Google Gemini model via Firebase). It handles the API calls to the model, sending prompts and receiving the model's responses, including the tool calls that drive the UI generation.
 
-### 4. Widget Catalog (The "Tools")
+### 5. Widget Catalog (The "Tools")
 
 This is the collection of predefined UI components that the AI can use to construct the interface. It acts as the "API" that the AI targets.
 
 - **Definition**: The catalog is defined in `lib/src/catalog.dart` as a `Catalog` instance, which is a list of `CatalogItem`s.
-- **Custom Components**: The travel app defines several custom `CatalogItem`s in the `lib/src/catalog/` directory, such as `travel_carousel`, `itinerary_with_details`, and `filter_chip_group`.
-- **Standard Components**: It also uses standard, pre-built components from `flutter_genui` like `column`, `text`, `elevatedButton`, etc.
+- **Custom Components**: The travel app defines several custom `CatalogItem`s in the `lib/src/catalog/` directory. Key components include:
+  - `TravelCarousel`: For displaying a horizontal list of selectable options.
+  - `ItineraryWithDetails`, `ItineraryDay`, `ItineraryEntry`: For building structured travel plans.
+  - `InputGroup`: A container for grouping various input widgets.
+  - `OptionsFilterChipInput`, `CheckboxFilterChipsInput`, `TextInputChip`: Different types of input chips for user selections.
+  - `InformationCard`: For displaying detailed information about a topic.
+  - `Trailhead`: For suggesting follow-up prompts to the user.
+- **Standard Components**: It also uses standard, pre-built components from `flutter_genui` like `column`, `text`, `image`, etc.
 
 ## Data Flow: The Generative UI Cycle
 
-The diagram below shows the sequence of events from user input to UI rendering. The application logic in `main.dart` is responsible for driving this cycle.
+The diagram below shows the sequence of events from user input to UI rendering. The application logic in `lib/src/travel_planner_page.dart` is responsible for driving this cycle.
 
 ```mermaid
 sequenceDiagram
@@ -121,14 +136,14 @@ sequenceDiagram
     deactivate AiClient
 
     note right of AppLogic: The AiClient invokes the tool, which calls a method on GenUiManager.
-    
+
     activate GenUiManager
     GenUiManager->>GenUiManager: Updates internal state
     GenUiManager-->>AppLogic: Notifies of state change via Stream
     deactivate GenUiManager
 
     AppLogic->>AppLogic: Updates _conversation list with AiUiMessage
-    
+
     activate ConversationWidget
     AppLogic->>ConversationWidget: Rebuilds with new message list
     ConversationWidget->>ConversationWidget: Renders new UI surface
@@ -141,7 +156,7 @@ sequenceDiagram
 
 ### The System Prompt
 
-The interaction with the model is heavily guided by a detailed **system prompt** defined in `main.dart`. This prompt is critical to the application's success. It instructs the model on:
+The interaction with the model is heavily guided by a detailed **system prompt** defined in `lib/src/travel_planner_page.dart`. This prompt is critical to the application's success. It instructs the model on:
 
 - **Persona**: To act as a helpful travel agent.
 - **Conversation Flow**: To first ask clarifying questions and then present results.
@@ -208,8 +223,8 @@ graph TD
 
 ### User Interaction and Events
 
-The UI is not just for display; it's interactive. Widgets like `optionsFilterChip` and `filterChipGroup` can capture user input.
+The UI is not just for display; it's interactive. Widgets like `InputGroup`, `OptionsFilterChipInput`, and `TravelCarousel` can capture user input.
 
-- **Event Dispatching**: The `widgetBuilder` receives a `dispatchEvent` function. This function is called in response to user actions (like a button press or item selection), creating a `UiEvent` (`UiActionEvent` for submissions, `UiChangeEvent` for value changes).
-- **Event Handling**: The `onEvent` callback on the `GenUiSurface` widget is triggered. The application logic in `main.dart` receives the event via a `UiEventManager`.
-- **Conversation Update**: The app logic processes the event, wraps the information into a new `UserMessage`, adds it to the conversation history, and sends it to the model on the next turn. This informs the model of the user's actions, allowing it to respond accordingly (e.g., refining a search based on a selected filter).
+- **Event Dispatching**: The `widgetBuilder` for each catalog item receives a `dispatchEvent` function. This function is called in response to user actions (like a button press or item selection), creating a `UiEvent` (e.g., `UiActionEvent`).
+- **Event Handling**: The `TravelPlannerPage` listens to the `genUiManager.onSubmit` stream. When an event is dispatched from a widget, the `GenUiManager` processes it and emits a `UserMessage` on this stream.
+- **Conversation Update**: The `TravelPlannerPage`'s stream listener (`_handleUserMessageFromUi`) receives the `UserMessage`, adds it to the conversation history, and triggers a new inference call to the model. This informs the model of the user's actions, allowing it to respond accordingly (e.g., refining a search based on a selected filter).
diff --git a/packages/flutter_genui/IMPLEMENTATION.md b/packages/flutter_genui/IMPLEMENTATION.md
