waveterm/aiprompts/tsunami-builder.md

# Tsunami AI Builder - V1 Architecture

## Overview

A split-screen builder for creating Tsunami applications: chat interface on left, tabbed preview/code/files on right. Users describe what they want, AI edits the code iteratively.

## UI Layout

### Left Panel

- **💬 Chat** - Conversation with AI

### Right Panel

**Top Section - Tabs:**
- **👁️ Preview** (default) - Live preview of running Tsunami app, updates automatically after successful compilation
- **📝 Code** - Monaco editor for manual edits to app.go
- **📁 Files** - Static assets browser (images, etc)

**Bottom Section - Build Panel (closable):**
- Shows compilation status and output (like VSCode's terminal panel)
- Displays success messages or errors with line numbers
- Auto-runs after AI edits
- For manual Code tab edits: auto-reruns or user clicks build button
- Can be manually closed/reopened by user

### Top Bar

- Current AppTitle (extracted from app.go)
- **Publish** button - Moves draft → published version
- **Revert** button - Copies published → draft (discards draft changes)

## Version Management

**Draft mode**: Auto-saved on every edit, persists when builder closes
**Published version**: What runs in main Wave Terminal, only updates on explicit "Publish"

Flow:

1. Edit in builder (always editing draft)
2. Click "Publish" when ready (copies draft → published)
3. Continue editing draft OR click "Revert" to abandon changes

## Context Structure

Every AI request includes:

```
[System Instructions]
  - General system prompt
  - Full system.md (Tsunami framework guide)

[Conversation History]
  - Recent messages (with prompt caching)

[Current Context] (injected fresh each turn, removed from previous turns)
  - Current app.go content
  - Compilation results (success or errors with line numbers)
  - Static files listing (e.g., "/static/logo.png")
```

**Context cleanup**: Old "current context" blocks are removed from previous messages and replaced with "[OLD CONTEXT REMOVED]" to save tokens. Only the latest app.go + compile results stay in context.

## AI Tools

### edit_appgo (str_replace)

**Primary editing tool**

- `old_str` - Unique string to find in app.go
- `new_str` - Replacement string
- `description` - What this change does

**Backend behavior**:

1. Apply string replacement to app.go
2. Immediately run `go build`
3. Return tool result:
   - ✓ Success: "Edit applied, compilation successful"
   - ✗ Failure: "Edit applied, compilation failed: [error details]"

AI can make multiple edits in one response, getting compile feedback after each.

### create_appgo

**Bootstrap new apps**

- `content` - Full app.go file content
- Only used for initial app creation or total rewrites

Same compilation behavior as str_replace.

### web_search

**Look up APIs, docs, examples**

- Implemented via provider backend (OpenAI/Anthropic)
- AI can research before making edits

### read_file

**Read user-provided documentation**

- `path` - Path to file (e.g., "/docs/api-spec.md")
- User can upload docs/examples for AI to reference

## User Actions (Not AI Tools)

### Manage Static Assets

- Upload via drag & drop into Files tab or file picker
- Delete files from Files tab
- Rename files from Files tab
- Appear in `/static/` directory
- Auto-injected into AI context as available files

### Share Screenshot

- User clicks "📷 Share preview with AI" button
- Captures current preview state
- Attaches to user's next message
- Useful for debugging layout/visual issues

### Manual Code Editing

- User can switch to Code tab
- Edit app.go directly in Monaco editor
- Changes auto-compile
- AI sees manual edits in next chat turn

## Compilation Pipeline

After every code change (AI or user):

```
1. Write app.go to disk
2. Run: go build app.go
3. Show build output in build panel
4. If success:
   - Start/restart app process
   - Update preview iframe
   - Show success message in build panel
5. If failure:
   - Parse error output (line numbers, messages)
   - Show error in build panel (bottom of right side)
   - Inject into AI context for next turn
```

**Auto-retry**: AI can fix its own compilation errors within the same response (up to 3 attempts).

## Error Handling

### Compilation Errors

Shown in build panel at bottom of right side.

Format for AI:

```
COMPILATION FAILED

Error at line 45:
  43 | func(props TodoProps) any {
  44 |     return vdom.H("div", nil
> 45 |         vdom.H("span", nil, "test")
     |         ^ missing closing parenthesis
  46 |     )

Message: expected ')', found 'vdom'
```

### Runtime Errors

- Shown in preview tab (not errors panel)
- User can screenshot and report to AI
- Not auto-injected (v1 simplification)

### Linting (Future)

- Could add custom Tsunami-specific linting
- Would inject warnings alongside compile results
- Not required for v1

## Secrets/Configuration

Apps can declare secrets using Tsunami's ConfigAtom:

```go
var apiKeyAtom = app.ConfigAtom("api_key", "", &app.AtomMeta{
    Desc: "OpenAI API Key",
    Secret: true,
})
```

Builder detects these and shows input fields in UI for user to fill in.

## Conversation Limits

**V1 approach**: No summarization, no smart handling.

When context limit hit: Show message "You've hit the conversation limit. Click 'Start Fresh' to continue editing this app in a new chat."

Starting fresh uses current app.go as the beginning state.

## Token Optimization

- System.md + early messages benefit from prompt caching
- Only pay per-turn for: current app.go + new messages
- Old context blocks removed to prevent bloat
- Estimated: 10-20k tokens per turn (very manageable)

## Example Flow

```
User: "Create a counter app"
AI: [calls create_appgo with full counter app]
Backend: ✓ Compiled successfully
Preview: Shows counter app

User: "Add a reset button"
AI: [calls str_replace to add reset button]
Backend: ✓ Compiled successfully
Preview: Updates with reset button

User: "Make buttons bigger"
AI: [calls str_replace to update button classes]
Backend: ✓ Compiled successfully
Preview: Updates with larger buttons

User: [switches to Code tab, tweaks color manually]
Backend: ✓ Compiled successfully
Preview: Updates

User: "Add a chart showing count over time"
AI: [calls web_search for "go charting library"]
AI: [calls str_replace to add chart]
Backend: ✗ Compilation failed - missing import
AI: [calls str_replace to add import]
Backend: ✓ Compiled successfully
Preview: Shows chart
```

## Out of Scope (V1)

- Version history / snapshots
- Multiple files / project structure
- Collaboration / sharing
- Advanced linting
- Runtime error auto-injection
- Conversation summarization
- Component-specific editing tools

These can be added in v2+ based on user feedback.

## Success Criteria

- User can create functional Tsunami app through chat in <5 minutes
- AI successfully fixes its own compilation errors 80%+ of the time
- Iteration cycle (message → edit → preview) takes <10 seconds
- Users can publish working apps to Wave Terminal
- Draft state persists across sessions