# adk-fluent Visual Cookbook Runner

See every cookbook agent and A2UI surface in action.

## Quick Start

### Static A2UI Preview (no API key needed)

```bash
just a2ui-preview
```

Exports all A2UI surfaces from cookbooks 70-74, opens a gallery in your browser.
Works offline, no LLM calls.

### Full Interactive Runner (requires API key)

```bash
# 1. Configure credentials (pick one)
cp visual/.env.example visual/.env
# Edit visual/.env with your Gemini API key or Vertex AI project

# 2. Generate agent folders from cookbooks (one-time)
just agents

# 3. Launch
just visual
```

Opens at `http://localhost:8099`:
- **Left sidebar**: all 67 cookbooks, grouped by difficulty
- **Center**: chat with any agent
- **Right panel**: live A2UI surface rendering + JSON inspector

### Visual Regression Tests

```bash
# Run tests (no API key needed — tests compilation, not LLM output)
uv run pytest tests/visual/ -v

# Update golden snapshots after intentional changes
uv run pytest tests/visual/ -v --update-golden
```

## Architecture

```
visual/
├── index.html          # Single-file UI (HTML + CSS + JS, no build step)
├── server.py           # FastAPI dev server (auto-discovers cookbooks)
├── surfaces/           # Exported A2UI JSON (generated by export script)
│   ├── _index.json     # Surface index
│   └── *.json          # Individual surface exports
├── .env.example        # Credentials template
└── README.md           # This file

scripts/
└── export_a2ui_surfaces.py   # Compiles cookbook surfaces → JSON

tests/visual/
├── conftest.py                # Fixtures + golden file comparison
├── test_a2ui_surfaces.py      # Protocol compliance + snapshot tests
└── golden/                    # Golden snapshot files
```

## How It Works

1. **Surface Exporter** (`scripts/export_a2ui_surfaces.py`):
   - Imports each A2UI cookbook (70-74)
   - Finds all `UISurface` and `UIComponent` objects at module scope
   - Compiles them via `compile_surface()` → A2UI JSON messages
   - Writes to `visual/surfaces/`

2. **A2UI Renderer** (embedded in `index.html`):
   - Processes A2UI protocol messages (createSurface, updateComponents, updateDataModel)
   - Renders all 18 basic catalog components to native HTML
   - Supports data binding, validation, theming, modals, tabs
   - Gallery mode shows all surfaces side-by-side

3. **Dev Server** (`visual/server.py`):
   - Auto-discovers cookbooks from `examples/cookbook/`
   - Loads agents from `examples/<name>/agent.py`
   - Runs agents via ADK `InMemoryRunner`
   - Extracts A2UI messages from session state
   - Serves UI + API on port 8099
