# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Product Vision

**ShowRunner is a workflow capture and grounding system.**

It captures _how work gets done_ — not just what it looks like — so workflows can be documented, shared, and eventually replayed.

Unlike screen recorders (Loom, OBS) or marketing tools (Arcade), ShowRunner produces structured, executable artifacts:

- **Temporal grounding**: Timeline with structured events (`events.ndjson`)
- **Human-legible intent**: Hotspots and annotations capture _why_ each action matters
- **Reproducibility**: Sessions are durable artifacts, not ephemeral recordings

Target users: developers and teams who need to document operational workflows, onboard teammates, or create reproducible process guides.

**Evolution path** (current → future):

1. **Capture** — Record workflows with click/keyboard events, step markers, annotations ✅
2. **Structure** — AI-assisted step detection, action typing, workflow boundaries (in progress)
3. **Assisted replay** — Ghost overlays guide users through workflows live
4. **Optional execution** — Agent-driven replay with human approval

## Build & Run Commands

```bash
# Development (recommended - runs Python sidecar + Tauri together)
./scripts/dev.sh

# Or manually:
# Terminal 1: Python sidecar
cd python_sidecar && source .venv/bin/activate && python3 -m uvicorn python_sidecar.main:app --reload

# Terminal 2: Tauri app
npm run tauri:dev

# Build frontend only (TypeScript check + Vite)
npm run build

# Check Rust backend
cd src-tauri && cargo check

# Build production app
npm run tauri build
```

### Testing & Linting

```bash
# TypeScript
npm run test              # Vitest with coverage
npm run lint              # ESLint
npm run format:check      # Prettier check

# Python (strict mypy)
cd python_sidecar && source .venv/bin/activate
mypy .                    # Must pass strict mode
ruff check .              # Linting
pytest                    # Tests with coverage

# Rust
cargo test --manifest-path src-tauri/Cargo.toml

# Pre-commit (runs all checks)
pre-commit run --all-files
```

## Architecture

ShowRunner is a Tauri desktop app with three runtime components:

1. **Rust backend** (`src-tauri/`) - Window management, screen capture, FFmpeg recording
2. **React frontend** (`src/`) - UI views and components
3. **Python sidecar** (`python_sidecar/`) - FastAPI server for accessibility/event capture and AI analysis

The Python sidecar runs on `http://127.0.0.1:8765` and communicates with Rust via HTTP (`python_bridge.rs`).

### Three Modules

1. **Recording** - Screen capture via floating overlay
    - Frontend: `src/views/OverlayView.tsx` (overlay), `src/views/RecordingView.tsx` (terminal mode)
    - Backend: `src-tauri/src/recording.rs` (screencapture + ffmpeg), `src-tauri/src/overlay.rs` (window mgmt)

2. **Editor** - Video playback + hotspot editing
    - Entry: `src/views/EditorView.tsx`
    - Refactored structure: `src/views/Editor/` (EditorContext, EditorMain, EditorSidebar, EditorHeader)
    - Components: `Timeline.tsx`, `HotspotEditor.tsx`, `HotspotOverlay.tsx`, `VideoPlayer.tsx`

3. **Library** - Session management
    - Frontend: `src/views/LibraryView.tsx`
    - Backend: `src-tauri/src/session.rs`

### Key Files

| Purpose         | Frontend         | Backend                               |
| --------------- | ---------------- | ------------------------------------- |
| API wrappers    | `src/lib/api.ts` | `src-tauri/src/commands.rs`           |
| App routes      | `src/App.tsx`    | -                                     |
| Window config   | -                | `src-tauri/tauri.conf.json`           |
| Permissions     | -                | `src-tauri/capabilities/default.json` |
| Python bridge   | -                | `src-tauri/src/python_bridge.rs`      |
| AI analysis     | -                | `python_sidecar/ai/analyzer.py`       |
| Export/markdown | -                | `python_sidecar/export/markdown.py`   |

### Adding a Tauri Command

1. Add function in `src-tauri/src/commands.rs`:

    ```rust
    #[tauri::command]
    pub async fn my_command(arg: String) -> Result<String, String> { ... }
    ```

2. Register in `src-tauri/src/main.rs` invoke_handler

3. Add TypeScript wrapper in `src/lib/api.ts`:
    ```typescript
    export async function myCommand(arg: string): Promise<string> {
        return await invoke("my_command", { arg });
    }
    ```

### Two Windows

- `main` - Library, Editor, full Recording view (starts hidden)
- `recording-overlay` - Floating minimal recording controls (transparent, always-on-top)

Windows communicate via Tauri events (`emit`/`listen`). When emitting navigation events from overlay to main, use `emitTo("main", ...)` to target the specific window.

## Data Storage

Sessions: `~/Library/Application Support/dev.showrunner.app/sessions/{session-id}/`

- `metadata.json` - Title, duration, hotspots
- `recording.mp4` - Screen capture video (never modified)
- `events.ndjson` - Timeline events (commands, annotations, markers)
- `steps.json` - Structured workflow steps
- `edits.json` - Non-destructive edit patches

## Known Issues

- Editor navigation can cause duplicate windows if events aren't targeted to specific window labels