# Frontend Architecture (Atomic Design)

This doc describes the **current** ShowRunner desktop UI (React + TypeScript in `src/`) using an **Atomic Design** lens so you can reason about pages, layout blocks, and reusable UI pieces.

It is intentionally **layout-first**: what renders where, which blocks compose which screens, and where state/data flows live.

## Scope

- Codebase: `src/` (React + TS) running inside Tauri webviews.
- Focus: UI composition, navigation, and how editor/library/recording are assembled.
- Not covered: Rust/Tauri commands (`src-tauri/`), sidecar (`python_sidecar/`), widget (`widget/`) except where relevant to UI data flow.

## Runtime Surfaces (Windows)

The frontend runs in multiple webview windows:

- **Main window**
    - Hosts the app shell and routes.
    - Pages: Library, Recording, Editor.
- **Overlay window**
    - Floating recording controls (always-on-top UX).
    - Route: `/overlay`.
- **Region selector window**
    - Fullscreen transparent region selection overlay.
    - Route: `/region-selector`.

## Routing / Pages

Defined in `src/App.tsx`:

- `/library` -> `src/views/LibraryView.tsx`
- `/record` -> `src/views/RecordingView.tsx`
- `/editor/:sessionId` -> `src/views/EditorView.tsx`
- `/overlay` -> `src/views/OverlayView.tsx`
- `/region-selector` -> `src/views/RegionSelectorView.tsx`

## Styling System

- Global tokens via CSS variables in `src/styles/tokens.css` (fonts, colors, spacing, radii, shadows, z-index).
- Views/components predominantly use **inline style objects** referencing tokens (e.g. `var(--bg-surface)`).
- Global CSS entrypoint: `src/index.css` (base resets + imports tokens).

## State Management Overview

There are two primary state “axes”:

- **Global shortcuts/help**
    - `src/contexts/ShortcutContext.tsx`
    - Used by: Library, Recording, Editor (to register page-specific shortcut categories)
    - UI: `src/components/ShortcutHelp.tsx` rendered by `src/App.tsx`

- **Editor state**
    - `src/views/Editor/useEditorState.ts` is the source of truth (session metadata, player state, steps, hotspots, export state).
    - `src/views/Editor/EditorContext.tsx` exposes the state via context.
    - `src/views/EditorView.tsx` composes the editor shell using these state hooks.

Data access:

- Most IO calls are in `src/lib/api.ts` (Tauri `invoke(...)` + Tauri `listen(...)` events).

## Atomic Design Taxonomy (How To Read This Doc)

Atomic design layers used here:

- **Atoms**: Single UI primitives (Button, Icon, Input, Badge).
- **Molecules**: Small compositions of atoms (Search field with icon and kbd hint).
- **Organisms**: Larger sections/blocks (Sidebar, Steps rail, Timeline, Inspector).
- **Templates**: Page-level layout skeletons (header + columns + footer).
- **Pages**: Route-level screens (LibraryView, EditorView, etc.).

The codebase currently does not strictly separate `atoms/`, `molecules/`, etc. The mapping below explains “what it _is_” even if the folder is `views/` or `components/`.

## Current Inventory (By Atomic Layer)

### Atoms (Mostly Inline Today)

In practice, atoms are repeated inline across views as styled `<button>`, `<input>`, `<kbd>`, etc.

Common atoms you effectively have:

- `Button` (primary/secondary/ghost, disabled states)
- `IconButton` (square button containing an SVG icon)
- `Input` (text input, placeholder, focus ring)
- `Badge` (small pill/chip for status)
- `KbdHint` (⌘F style hint)
- `Tooltip` (editor canvas tools tooltip uses fixed-position popover)
- `Toggle` (switch-like input; appears in inspector patterns)

### Molecules (Implemented Inline or As Small Components)

Representative molecules (names are conceptual):

- **SearchField**
    - Library sidebar search: icon + input + kbd hint
    - File: `src/views/LibraryView.tsx`
- **SegmentedControl**
    - Editor header “Edit / Preview” and “Screen / Terminal / Both”
    - File: `src/views/Editor/EditorHeader.tsx`
- **ActionIconGroup**
    - Session card actions (Share/Delete) and editor header actions (Export/Share)
    - Files: `src/views/LibraryView.tsx`, `src/views/Editor/EditorHeader.tsx`
- **Hotspot Style Picker**
    - Hotspot/Area/Callout cards in inspector
    - File: `src/views/Editor/EditorHotspotInspector.tsx`

### Organisms (Major UI Blocks)

#### Library (Organisms)

- **LibrarySidebar**
    - Workspace header, SearchField, nav items, plan card
    - File: `src/views/LibraryView.tsx`
- **LibraryToolbarRow**
    - Filter pills, sort dropdown, grid/list toggle
    - File: `src/views/LibraryView.tsx`
- **SessionGrid / SessionList**
    - Cards/rows; each session has thumbnail/title/meta and action buttons
    - File: `src/views/LibraryView.tsx`
- **ShareDialog**
    - Modal-ish dialog for sharing
    - File: `src/components/ShareDialog.tsx`

#### Editor (Organisms)

Editor is composed in `src/views/EditorView.tsx`:

- **EditorHeader**
    - Back to library, title, mode tabs (Edit/Preview), export/share
    - File: `src/views/Editor/EditorHeader.tsx`
- **EditorStepsRail** (Edit mode only)
    - Steps list with split/merge and reordering
    - File: `src/views/Editor/EditorStepsRail.tsx`
- **EditorMain (Stage Area)**
    - Stage top bar for canvas tools
    - Video/terminal stage rendering
    - Timeline footer always present
    - File: `src/views/Editor/EditorMain.tsx`
- **EditorSidebar** (Edit mode when not editing hotspots)
    - Capture summary, activity, transcript, actions (Generate steps, etc.)
    - File: `src/views/Editor/EditorSidebar.tsx`
- **EditorHotspotInspector** (Edit mode when editing hotspots)
    - Hotspot/Area/Callout editor: text, colors, destination
    - File: `src/views/Editor/EditorHotspotInspector.tsx`

Supporting stage organisms:

- **VideoPlayer**
    - Video container, play/seek plumbing; hosts overlays via children
    - File: `src/components/VideoPlayer.tsx`
- **HotspotOverlay**
    - Renders hotspots/areas/callouts on top of video; supports selection/drag in edit mode
    - File: `src/components/HotspotOverlay.tsx`
- **ClickRippleOverlay**
    - Optional click visualization
    - File: `src/components/ClickRippleOverlay.tsx`
- **Timeline**
    - Playhead, markers, scrubbing
    - File: `src/components/Timeline.tsx`
- **TerminalPlayer**
    - Terminal replay surface (asciinema-like)
    - File: `src/components/TerminalPlayer.tsx`
- **WalkthroughPlayer**
    - Preview-mode walkthrough UI
    - File: `src/components/WalkthroughPlayer.tsx`

#### Recording (Organisms)

- **Recording Sidebar**
    - Mode selection (screen/terminal/both), source selection (display/window), display list/window list
    - File: `src/views/RecordingView.tsx`
- **LiveTerminal**
    - Live terminal preview/streaming during terminal capture
    - File: `src/components/LiveTerminal.tsx`

#### Overlay / Region Selector (Organisms)

- **Overlay Recording Controls**
    - Minimal floating UI: modes, window picker, record/stop, timer, markers
    - File: `src/views/OverlayView.tsx`
- **Region Selector Canvas**
    - Fullscreen selection overlay; lock state; confirm/cancel
    - File: `src/views/RegionSelectorView.tsx`

### Templates (Page Layout Skeletons)

Templates are currently implemented as view-level layout code rather than reusable components.

- **LibraryTemplate**
    - Two columns: sidebar (fixed width) + main (scrolling)
    - Implemented in `src/views/LibraryView.tsx`
- **EditorTemplate**
    - Column layout: header (fixed), body (steps rail + stage + inspector), footer timeline
    - Implemented in `src/views/EditorView.tsx` + `src/views/Editor/EditorMain.tsx`
- **RecordingTemplate**
    - Two columns: sidebar configuration + main preview area
    - Implemented in `src/views/RecordingView.tsx`
- **OverlayTemplate**
    - Single compact overlay container
    - Implemented in `src/views/OverlayView.tsx`
- **RegionSelectorTemplate**
    - Fullscreen transparent canvas
    - Implemented in `src/views/RegionSelectorView.tsx`

### Pages (Route-Level)

- **Library**: `src/views/LibraryView.tsx`
- **Recording**: `src/views/RecordingView.tsx`
- **Editor**: `src/views/EditorView.tsx` (shell) + `src/views/Editor/*` (blocks)
- **Overlay**: `src/views/OverlayView.tsx`
- **Region Selector**: `src/views/RegionSelectorView.tsx`

## Page Composition Diagrams

### Editor Page Layout (Template -> Organisms)

```mermaid
flowchart TB
  subgraph "EditorView (src/views/EditorView.tsx)"
    H["EditorHeader"]
    subgraph Body["Body Row (flex)"]
      SR["EditorStepsRail (edit mode only)"]
      ST["EditorMain (Stage)"]
      SB["EditorSidebar OR EditorHotspotInspector (edit mode only)"]
    end
  end

  H --> Body
  SR --> ST
  ST --> SB
```

### Editor Stage Internals (Organisms)

```mermaid
flowchart TB
  subgraph "EditorMain (src/views/Editor/EditorMain.tsx)"
    TBAR["StageTopBar (canvas tools: Hotspot/Callout/Chapter)"]
    subgraph STAGE["Stage Area"]
      VP["VideoPlayer"]
      HSO["HotspotOverlay (inside VideoPlayer children)"]
      CRO["ClickRippleOverlay (inside VideoPlayer children)"]
      WTP["WalkthroughPlayer (preview mode)"]
      TP["TerminalPlayer (activeTab terminal/both)"]
    end
    TL["Timeline"]
  end

  TBAR --> STAGE
  VP --> HSO
  VP --> CRO
  VP --> WTP
  STAGE --> TL
```

### Library Page Layout (Template -> Organisms)

```mermaid
flowchart LR
  subgraph "LibraryView (src/views/LibraryView.tsx)"
    LS["LibrarySidebar"]
    subgraph LM["LibraryMain"]
      LTop["Header (My Library + Create)"]
      LTools["ToolbarRow (filters/sort/view)"]
      LGrid["SessionGrid / SessionList"]
    end
  end

  LS --> LM
  LTop --> LTools --> LGrid
```

## Data Flow (UI -> Tauri)

At a high level:

- UI events call functions in `src/lib/api.ts`
- `api.ts` uses Tauri `invoke(...)` to talk to Rust commands
- UI also uses Tauri `listen(...)` for events (navigation events, processing events, hotkeys)

```mermaid
flowchart LR
  UI["React UI (views/components)"] --> API["src/lib/api.ts (invoke/listen)"]
  API --> TAURI["Tauri IPC"]
  TAURI --> RUST["src-tauri commands"]
  RUST --> TAURI
  TAURI --> UI
```

## Suggested (Optional) Folder Organization For Atomic Design

If/when you decide to enforce atomic design in code, a practical structure that maps well to this app:

- `src/ui/atoms/`
    - `Button.tsx`, `IconButton.tsx`, `Input.tsx`, `Kbd.tsx`, `Badge.tsx`, `Tooltip.tsx`, `Toggle.tsx`
- `src/ui/molecules/`
    - `SearchField.tsx`, `SegmentedControl.tsx`, `ActionMenu.tsx`, `ColorField.tsx`
- `src/ui/organisms/`
    - `LibrarySidebar.tsx`, `SessionGrid.tsx`, `EditorHeader.tsx`, `StepsRail.tsx`, `InspectorPanel.tsx`
- `src/ui/templates/`
    - `LibraryTemplate.tsx`, `EditorTemplate.tsx`, `RecordingTemplate.tsx`
- `src/pages/`
    - `LibraryPage.tsx`, `EditorPage.tsx`, `RecordingPage.tsx`, `OverlayPage.tsx`, `RegionSelectorPage.tsx`

You can migrate incrementally:

1. Extract atoms used across multiple pages (Button/IconButton/Input/Tooltip).
2. Extract molecules with repeated structure (SearchField, SegmentedControl).
3. Then lift organisms out of `views/*` into `ui/organisms/` while keeping routes stable.

## Practical “Block List” (What You Think In When Designing UI)

This is a “mentally complete” list of the blocks you move around when iterating on UX:

- Global
    - Shortcut system + help modal
    - Design tokens (colors, spacing, radii)
- Library
    - Sidebar: workspace header, search, nav, plan card
    - Main header: title + Create
    - Toolbar: filters, sorting, view mode toggle
    - Sessions: grid/list items + actions
    - Share dialog
- Editor
    - Header: navigation, title, Edit/Preview tabs, export/share
    - Steps rail: step list + split/merge/reorder
    - Stage top bar: canvas tools (hotspot/callout/chapter)
    - Stage: video/terminal surface, overlays (hotspots/click ripples/walkthrough)
    - Timeline: scrub + markers
    - Inspector: sidebar vs hotspot inspector
- Recording
    - Sidebar: recording mode + source selection (display/window)
    - Main: preview (screen/terminal/both)
- Overlay
    - Floating controls + dropdown pickers
- Region selector
    - Fullscreen drag-to-select + confirm/cancel/locked state