packages/frontend/docs/examples.md

# 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](#structure)
- [YAML Manifest](#yaml-manifest)
- [Bundling](#bundling)
- [Runtime Behavior](#runtime-behavior)
- [Adding a New Example](#adding-a-new-example)
- Examples
  - [Counter App](#counter-app)
  - [Overflow Debug](#overflow-debug)
  - [Rebuild Weather App](#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 |

```yaml
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.

```bash
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`:
   ```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`:
   ```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`:
   ```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.