# ShowRunner

**Workflow capture and grounding system**

ShowRunner 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 event logs, semantic annotations, and reproducible step sequences.

Built for developers and teams who need to document operational workflows, onboard teammates, or create reproducible process guides.

## Features

**Capture**

- Multi-display screen recording (display, window, or region)
- Click and keyboard/app-focus event capture with timestamps
- Optional browser DOM-semantics capture (Chrome extension -> `dom_*` events)
- Terminal session recording (optional `terminal.cast` capture)
- Step markers during recording

**Structure**

- Timeline editor with hotspot annotations
- AI-assisted step detection and action typing
- Structured event log (`events.ndjson`) for replay
- Click ripple visualization

**Export**

- Markdown documentation generation
- MP4 export (optional chapter cards)
- Embeddable widget player
- Share links for team distribution

## Tech Stack

- **Desktop**: [Tauri](https://tauri.app/) (Rust backend + React frontend)
- **UI**: React 18 + TypeScript + React Router
- **Backend**: Rust Tauri host + Python FastAPI sidecar for accessibility/event capture + AI analysis
- **Storage**: Local filesystem (sessions stored in `~/Library/Application Support/ShowRunner/`)

## Development Setup

### Prerequisites

- **Node.js** >= 18
- **Rust** >= 1.93 (install via [rustup](https://rustup.rs/))
- **Python** >= 3.11
- **FFmpeg** (for export functionality)

### Quick Start

```bash
# Install dependencies
npm install
cd python_sidecar && python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]' && cd ..

# Run development environment (Python sidecar + Tauri)
./scripts/dev.sh
```

The app will open automatically, and the Python sidecar will run on `http://127.0.0.1:8765`.

### Manual Development

```bash
# 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
```

## Packaging & Distribution (macOS)

### Fastest tester distribution (unsigned beta zip)

```bash
./scripts/package-beta-macos.sh
```

This creates:

- `artifacts/beta/ShowRunner-macos-beta.zip`

You can share that zip directly with testers for rapid feedback.

GitHub option:

- Run the `Desktop Beta Artifact` workflow (manual dispatch) and download the zip from workflow artifacts.

### Local beta build

```bash
# Build bundled Python sidecar executable into src-tauri/binaries/
./scripts/build-sidecar.sh

# Build desktop app bundle
npm run tauri:build -- --bundles app
```

Build output:

- `src-tauri/target/release/bundle/macos/ShowRunner.app`

### CI release pipeline

Tagging `v*` runs `.github/workflows/release.yml`, which:

1. Builds a packaged sidecar binary.
2. Builds a signed Tauri macOS app bundle.
3. Publishes a draft GitHub Release artifact.

Required GitHub secrets for signing/notarization:

- `APPLE_CERTIFICATE`
- `APPLE_CERTIFICATE_PASSWORD`
- `APPLE_SIGNING_IDENTITY`
- `APPLE_ID`
- `APPLE_PASSWORD`
- `APPLE_TEAM_ID`

## Project Structure

```
showrunner/
├── src/                     # React frontend
│   ├── views/               # Recording, Editor, Upload views
│   ├── components/          # UI components
│   └── lib/                 # API wrappers
├── src-tauri/               # Rust backend
│   └── src/
│       ├── recording.rs     # Screen capture
│       ├── devices.rs       # Device enumeration
│       ├── session.rs       # Session storage
│       ├── python_bridge.rs # HTTP client for sidecar
│       └── errors.rs        # Error taxonomy
├── python_sidecar/          # FastAPI sidecar
│   ├── api/                 # Event, export, upload endpoints
│   └── services/            # Overlay mapping, FFmpeg rendering
└── scripts/                 # Development utilities
```

## Code Quality

### Rust

```bash
cargo build --manifest-path src-tauri/Cargo.toml
cargo test --manifest-path src-tauri/Cargo.toml
```

### Python (Strict Type Checking)

```bash
cd python_sidecar
source .venv/bin/activate
mypy .                  # Must pass strict mode
ruff check .            # Must pass with no errors
pytest                  # Run tests
```

### TypeScript

```bash
npm run build           # Type-checks + builds
npm run lint            # ESLint checks for TS/TSX
npm run format:check    # Prettier formatting check
```

### Pre-commit Hooks

```bash
python3 -m pip install pre-commit
pre-commit install
pre-commit run --all-files
```

## Session Data Model

Sessions are stored in `~/Library/Application Support/ShowRunner/sessions/{session_id}/`:

| File            | Purpose                                                                     |
| --------------- | --------------------------------------------------------------------------- |
| `recording.mp4` | Visual recording (never modified)                                           |
| `events.ndjson` | Append-only event log — app focus, key metadata, shortcuts, clicks, markers |
| `steps.json`    | Structured workflow steps with action typing                                |
| `edits.json`    | Non-destructive edit patches                                                |
| `metadata.json` | Session info (timestamp, display, duration)                                 |

The `events.ndjson` format is designed for replay — each line is a timestamped event that can be used for documentation, assisted replay, or eventual automated execution.

Notes:

- Alphanumeric key values are redacted by default (`"<redacted>"`).
- For richer web workflows (search, form submit, “open first email”), you can load the optional
  Chrome extension from `docs/` (see `docs/SHOWRUNNER_DOM_CAPTURE_EXTENSION.md`).
- Region capture on macOS requires careful coordinate handling (Retina / mixed-DPI). See
  `SYSTEM_DESIGN.md` section "Region Capture (macOS): Coordinate Spaces + Persistent Frame".
- `Auto Steps` / `Generate Steps from Activity` runs in the editor client using captured timeline events and clicks.
- Export now shows persistent in-app status with output path (copy/reveal actions).

## Roadmap

### ✅ Phase 1: Capture (Complete)

- Tauri + React infrastructure with multi-window architecture
- Display, window, and region capture modes
- Click/keyboard event capture during recording
- Step markers and countdown timer
- Terminal session recording

### ✅ Phase 2: Structure (Complete)

- Timeline editor with hotspot annotations
- Click ripple visualization
- AI-assisted step detection
- Markdown documentation export
- Embeddable widget player

### 🚧 Phase 3: Enhanced Capture (In Progress)

- Audio capture (mic + system audio)
- Keyboard shortcut visualization
- Accessibility-based action typing (app-dependent)
- Improved step boundary detection

### 📋 Phase 4: Assisted Replay (Planned)

- Ghost overlay highlights next target during playback
- Step-by-step guided execution
- Workflow validation (did user complete step correctly?)

### 📋 Phase 5: Optional Execution (Future)

- Agent-driven replay with human approval
- Per-step execution controls
- Dry-run mode

## Contributing

See [implementation_plan.md](.gemini/antigravity/brain/.../implementation_plan.md) for detailed architecture and commit strategy.

## License

MIT