Examples

Examples are Flutter projects offered as templates on the prompt page. They live as real files in the repository under examples/ and are served to the frontend as TAR files.

Table of Contents

• Structure
• YAML Manifest
• Bundling
• Runtime Behavior
• Adding a New Example
• Examples
  • Counter App
  • Overflow Debug
  • Rebuild Weather App

Structure

examples/
├── examples.yaml                    # Source of truth for all examples
├── simple_counter/                  # Directory name = id from the manifest
│   ├── pubspec.yaml
│   └── lib/
│       ├── main.dart
│       └── counter.dart
├── overflow_debug/
│   ├── pubspec.yaml
│   └── lib/
│       └── main.dart
└── rebuild_weather_app/
    ├── pubspec.yaml                 # Minimal pubspec (no code)
    └── weather_app_screenshot.png   # Image attached to the prompt

YAML Manifest

The source of truth for all examples is examples/examples.yaml. Each entry defines:

Field	Required	Description
id	✅	Must match the directory name under examples/
title	✅	Display name shown on the prompt page
prompt	❌	Optional agent prompt pre-filled in the composer
image	❌	Optional image file (relative to the example dir) attached to the prompt

examples:
  - id: simple_counter
    title: Counter Template

  - id: overflow_debug
    title: Overflow Debug
    prompt: >-
      My profile screen doesn't look right — some content seems to be cut off
      or missing. Can you take a screenshot and help me figure out what's wrong?

  - id: rebuild_weather_app
    title: Rebuild Weather App
    prompt: >-
      Rebuild this weather app and verify your result with screenshots. Generate
      background images for the different weather conditions.
    image: weather_app_screenshot.png

Template behavior based on fields

Has prompt?	Has image?	Behavior
❌	❌	Opens editor with lib/main.dart. No agent panel.
✅	❌	Opens editor + agent panel. Prompt is pre-filled in the composer.
✅	✅	Opens editor + agent panel. Prompt + image thumbnail pre-filled.

In all cases, the user reviews the prompt and hits Send manually — the agent does not start automatically.

Bundling

The script tool/bundle_examples.dart reads examples.yaml and:

1. Generates examples.json in packages/frontend/web/examples/ (with id, title, optional prompt, and optional base64-embedded image data).
2. Creates TAR files for each example directory.
3. Tracks checksums — unchanged examples are not re-bundled.

dart run tool/bundle_examples.dart

The generated files under web/examples/ are checked in.

Note: The yaml package is required as a dev dependency (already in pubspec.yaml).

Runtime Behavior

On startup the frontend fetches examples/examples.json and displays the templates on the prompt page. When a template is selected:

1. The corresponding TAR (examples/<id>.tar) is fetched and extracted into the workspace.
2. If the template has a prompt (and/or image), the agent panel opens with the prompt pre-filled in the composer.
3. If the template has no prompt, only the editor opens with lib/main.dart.

Adding a New Example

Code template (with existing Flutter code)

1. Create examples/<id>/ with a pubspec.yaml and lib/main.dart
2. Add an entry to examples/examples.yaml:

   - id: my_example
     title: My Example
   

3. Run dart run tool/bundle_examples.dart

Prompt-driven template (with agent pre-fill)

1. Create examples/<id>/ with at least a pubspec.yaml
2. Optionally add code in lib/ and/or an image file
3. Add an entry to examples/examples.yaml:

   - id: my_example
     title: My Example
     prompt: >-
       Describe what the agent should do...
     image: screenshot.png   # optional
   

4. Run dart run tool/bundle_examples.dart

Empty template (agent builds from scratch)

For examples where the agent should build everything from a prompt (no starter code):

1. Create examples/<id>/ with only a minimal pubspec.yaml:

   name: my_example
   environment:
     sdk: ">=3.6.0"
   

2. Add the entry with prompt (and optionally image) to examples.yaml
3. Run dart run tool/bundle_examples.dart

---

Counter App

A minimal Flutter counter app. Demonstrates basic StatefulWidget usage with setState.

Overflow Debug

A Flutter profile screen with intentional overflow and layout issues. The pre-filled prompt asks the agent to take screenshots, diagnose the problems, and fix them iteratively.

Rebuild Weather App

An empty project with a screenshot of a weather app UI. The agent is asked to rebuild the app from the screenshot and generate background images for different weather conditions.