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 ZIP files.

## Table of Contents

- [Structure](#structure)
- [Bundling](#bundling)
- [Runtime](#runtime)
- [Adding a new example](#adding-a-new-example)
- Examples
  - [Counter App](#counter-app)

## Structure

```
examples/
├── examples.json                    # Manifest: list of all examples
└── simple_counter/                  # Directory name = id from the manifest
    ├── pubspec.yaml                 # Must be directly in the example root
    └── lib/
        ├── main.dart
        └── counter.dart
```

The manifest (`examples.json`) defines `id` and `title` for each example:

```json
[
  {
    "id": "simple_counter",
    "title": "Counter Template"
  }
]
```

The `id` must exactly match the directory name under `examples/`.

## Bundling

The script `tool/bundle_examples.dart` zips each example and copies the ZIPs together with the manifest to `packages/frontend/web/examples/`. From there they are served by the web server as static assets.

```bash
dart run tool/bundle_examples.dart
```

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

## Runtime

On startup the frontend fetches `examples/examples.json` and displays the templates on the prompt page. When a template is selected it fetches the corresponding ZIP (`examples/<id>.zip`), extracts it, and writes the files into the workspace.

## Adding a new example

1. Create a directory `examples/<id>/` with a `pubspec.yaml` and `lib/`
2. Add an entry to `examples/examples.json`
3. Run `dart run tool/bundle_examples.dart`

---

## Counter App

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