# ShowRunner - Project Context

## Product Vision

**ShowRunner is screen recording software for workflow-driven tasks and operations.**

Unlike generic screen recorders (Loom, OBS) or polished marketing tools (Arcade), ShowRunner focuses on capturing *how work gets done* so teams can replicate it.

Target users: developers and teams who need to document and share operational workflows.

Core value: Turn screen recordings into reproducible workflow documentation with click highlights, step annotations, terminal capture, and exportable guides.

## Project Overview

**ShowRunner** is a desktop application designed for creating interactive screen recordings with "arcade-style" overlays and timeline editing. It combines a Rust-based Tauri backend for system-level operations with a React frontend for the UI and a Python sidecar for heavy lifting (video processing, event handling).

## Architecture & Tech Stack

### Core Architecture

ShowRunner is a Tauri desktop app: **Rust backend** + **React frontend**.
It uses a **Python sidecar** for AI and heavy video processing tasks.

### 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
    -   Frontend: `src/views/EditorView.tsx` (monolith - video, timeline, hotspots all in one)
    -   Components: `Timeline.tsx`, `HotspotEditor.tsx`, `HotspotOverlay.tsx`

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

### Windows

-   `main`: Library, Editor, full Recording view (starts hidden)
-   `recording-overlay`: Floating minimal recording controls (transparent, always-on-top)
-   `region-selector`: Fullscreen transparent window for selecting capture regions.

Windows communicate via Tauri events (`emit`/`listen`).

### Tech Stack Details

#### Frontend
-   **Framework:** React 18 + TypeScript + Vite
-   **Routing:** React Router
-   **Terminal Rendering:** `xterm.js`
-   **Key Files:**
    -   `src/views/`: Main application views.
    -   `src/components/`: Reusable UI components.
    -   `src/lib/api.ts`: Tauri command wrappers.

#### Backend (Tauri/Rust)
-   **Framework:** Tauri 2.2
-   **Language:** Rust
-   **Responsibilities:** Application lifecycle, system tray, `screencapture` spawning, Python sidecar interface, file system.
-   **Key Files:**
    -   `src-tauri/src/main.rs`: Entry point.
    -   `src-tauri/src/commands.rs`: IPC command handlers.
    -   `src-tauri/src/recording.rs`: Capture logic.

#### Sidecar (Python)
-   **Framework:** FastAPI
-   **Language:** Python 3.11+
-   **Responsibilities:** Event log processing, FFmpeg video rendering, AI integration (Anthropic).
-   **Key Files:**
    -   `python_sidecar/main.py`: Entry point.
    -   `python_sidecar/pyproject.toml`: Dependencies.

## Data Storage

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

-   `metadata.json`: Title, duration, hotspots
-   `recording.mp4`: Screen capture video
-   `events.ndjson`: Timeline events

## Development Setup

### Prerequisites
-   Node.js >= 18
-   Rust >= 1.93
-   Python >= 3.11
-   FFmpeg

### Initial Setup
1.  **Frontend:** `npm install`
2.  **Python:**
    ```bash
    cd python_sidecar
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -e '.[dev]'
    cd ..
    ```

### Running the App
Use the provided script to start both the Python sidecar and the Tauri app:

```bash
./scripts/dev.sh
```
-   **Python Sidecar:** Runs on `http://127.0.0.1:8765`
-   **Tauri App:** Launches the desktop window.

### Manual Run
-   **Python:** `cd python_sidecar && source .venv/bin/activate && python3 -m uvicorn python_sidecar.main:app --reload`
-   **Tauri:** `npm run tauri:dev`

## Development Guides

### 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 });
    }
    ```

## Code Standards & Testing

### Rust
-   Format: `cargo fmt`
-   Lint: `cargo clippy`
-   Test: `cargo test`

### Python
-   Type Check: `mypy .` (Strict mode required)
-   Lint: `ruff check .`
-   Test: `pytest`

### TypeScript
-   Type Check: `npm run build`

## Pro Tips & Troubleshooting

### Idiomatic Patterns
-   **Session Navigation**: Use `step_count` in Library to identify complex workflows.
-   **Fixture-Driven Development**: Update `tests/fixtures/session_v1/events.ndjson` when adding new event types.
-   **Markdown Exports**: Commit exported `README.md` to `docs/` for instant documentation.

### Troubleshooting
-   **FFmpeg Errors**: Ensure `ffmpeg` is in PATH (`brew install ffmpeg` on macOS).
-   **CI Failures**: Rust CI requires system libraries (`libgtk-3-dev`). Update `.github/workflows/ci.yml` if adding native dependencies.

### Known Issues
-   **Monolith Component:** `src/views/EditorView.tsx` is overly complex and needs refactoring.
-   **UI Redundancy:** `OverlayView` vs `RecordingView` overlap; `OverlayView` is primary but has sync issues.
-   **Platform:** Focused on macOS (`screencapture`, `pyobjc`).