simplify simulator around local participant core

CLAUDE.md

@@ -4,13 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a **Hyper.Video Browser Client Simulator** - a Rust-based testing framework that simulates multiple browser clients connecting to Hyper.Video sessions. It automates browser interactions using Chromium via the `chromiumoxide` library to test real-time video conferencing functionality at scale.
+This is a **Hyper.Video Browser Client Simulator**: a Rust TUI that spawns and controls Chromium-backed browser participants for manual session testing.
 
-The project is a Cargo workspace with multiple binaries for different use cases:
-- **client-simulator** (main TUI): Interactive terminal UI for manual testing
-- **client-simulator-http**: HTTP/WebSocket server for remote control
-- **client-simulator-orchestrator**: Batch orchestration of multiple simulated clients
-- **client-simulator-stats-gatherer**: Analytics collection from ClickHouse
+The active workspace has one shipped binary:
+- **client-simulator**: main TUI entrypoint
+
+The core crates are:
+- **browser/**: participant automation, shared local runtime, frontend drivers, remote stub
+- **config/**: CLI and YAML configuration
+- **tui/**: ratatui-based interface
 
 ## Build & Development Commands
 
@@ -23,17 +25,6 @@ cargo build --release
 # Run the main TUI simulator
 just run              # release mode
 just dev              # dev mode (faster compilation)
-
-# Run HTTP server (for remote control)
-just serve            # release mode
-just serve-dev        # dev mode
-
-# Run orchestrator (batch mode)
-just orchestrator --config path/to/config.yaml
-just orchestrator-dev --config path/to/config.yaml
-
-# Run stats gatherer
-just stats-gatherer --clickhouse-url http://localhost:8123 --space-url https://...
 ```
 
 ### Testing and Linting
@@ -65,13 +56,9 @@ The project includes Nix flake support for reproducible builds:
 ```bash
 # Build via Nix
 nix build .#client-simulator
-nix build .#client-simulator-http
-nix build .#client-simulator-orchestrator
-nix build .#client-simulator-stats-gatherer
 
 # Run via Nix
 just run-nix
-just serve-nix
 ```
 
 ### Fetch Session Cookie
@@ -91,10 +78,7 @@ just fetch-cookie my-user http://localhost:8081
 client-simulator/           # Main binary (TUI)
 ├── browser/                # Browser automation core
 ├── config/                 # Configuration management
-├── tui/                    # Terminal UI (ratatui-based)
-├── http/                   # HTTP/WebSocket API server
-├── orchestrator/           # Batch orchestration
-└── stats-gatherer/         # ClickHouse analytics
+└── tui/                    # Terminal UI (ratatui-based)
 ```
 
 ### Core Components
@@ -105,71 +89,39 @@ The foundation of all simulation modes. Key responsibilities:
 
 - **Browser Lifecycle**: Launches headless/headed Chromium instances using `chromiumoxide`
 - **Participant**: Central abstraction representing a simulated user
-  - `ParticipantInner`: Full browser-based participant (uses Chromium DevTools Protocol)
-  - `ParticipantInnerLite`: Lightweight participant (direct WebSocket, no browser)
+  - `frontend.rs`: shared local Chromium runtime shell
+  - `ParticipantInner`: hyper core frontend driver
+  - `ParticipantInnerLite`: hyper-lite frontend driver
+  - `remote_stub.rs`: In-process placeholder for the future remote backend
 - **Authentication**: `HyperSessionCookieStash` manages persistent user sessions
 - **Media Handling**: Supports fake media sources (builtin, custom video/audio files)
 
 Key files:
 - `browser/src/participant/mod.rs`: Participant API and lifecycle
-- `browser/src/participant/inner.rs`: Full browser implementation
-- `browser/src/participant/inner_lite.rs`: Lite WebSocket-only implementation
+- `browser/src/participant/frontend.rs`: Shared runtime and frontend resolution
+- `browser/src/participant/inner.rs`: Hyper core frontend driver
+- `browser/src/participant/inner_lite.rs`: Hyper-lite frontend driver
+- `browser/src/participant/remote_stub.rs`: Endpoint-free remote participant stub
 - `browser/src/auth.rs`: Cookie/session management
 
 #### 2. Config Module (`config/`)
 
 Unified configuration system supporting CLI args, YAML files, and environment variables:
 
 - `Config`: Main config struct with media settings, transport modes, etc.
+- `ParticipantBackendKind`: Explicit local vs remote-stub backend selection
 - `ParticipantConfig`: Per-participant settings (username, audio/video, resolution)
 - `BrowserConfig`: Browser-specific settings (user data dir, headless mode)
 
 #### 3. TUI Mode (`tui/` + main binary)
 
 Interactive terminal interface built with `ratatui`:
 - Spawn/control participants manually
+- Pick the participant backend explicitly
 - Toggle audio/video/screenshare
 - View logs in real-time
 - Persist configuration across sessions
 
-#### 4. HTTP Server Mode (`http/`)
-
-Exposes participants via REST API and WebSocket:
-- Create participants remotely
-- Send control commands (join, toggle media, etc.)
-- Stream logs over WebSocket
-- Useful for CI/CD integration
-
-#### 5. Orchestrator Mode (`orchestrator/`)
-
-Batch mode for large-scale testing:
-- YAML-based configuration with participant specs
-- Distributes participants across multiple HTTP workers (round-robin)
-- Supports participant-specific settings and staggered join times
-- Configuration validation before execution
-
-Example orchestrator config structure:
-```yaml
-session_url: https://hyper.video/space/SPACE_ID
-workers:
-  - url: http://worker1:8081
-  - url: http://worker2:8081
-defaults:
-  headless: true
-  audio_enabled: true
-participants_specs:
-  - username: "user-1"
-    wait_to_join_seconds: 5
-```
-
-#### 6. Stats Gatherer (`stats-gatherer/`)
-
-Connects directly to ClickHouse to collect analytics:
-- Server-level metrics
-- Space-level metrics
-- Participant audio/video processing stats
-- Exports as formatted tables or JSON
-
 ### Participant State Machine
 
 Participants follow this lifecycle:
@@ -186,14 +138,14 @@ The simulator uses two approaches:
 
 1. **Full Browser** (`ParticipantInner`):
    - Launches real Chromium via CDP (Chrome DevTools Protocol)
-   - Executes JavaScript in page context
+   - Uses the shared local runtime plus the hyper core driver
    - Supports all features (background blur, noise suppression, etc.)
    - CSS selectors in `browser/src/participant/selectors.rs`
 
 2. **Lite Mode** (`ParticipantInnerLite`):
-   - Direct WebSocket connection (no browser)
-   - Faster, lower resource usage
-   - Limited features (no video rendering, blur, etc.)
+   - Uses the same shared runtime with a hyper-lite-specific driver
+   - Keeps the browser-based participant model
+   - Supports a smaller command surface than hyper core
 
 ### Cookie/Session Management
 
@@ -227,9 +179,10 @@ cargo nextest run -p client-simulator-browser
 ### Adding a New Participant Command
 
 1. Add variant to `ParticipantMessage` enum in `browser/src/participant/messages.rs`
-2. Handle in `ParticipantInner::run()` message loop (`browser/src/participant/inner.rs`)
-3. Add public method to `Participant` struct in `browser/src/participant/mod.rs`
-4. Expose in TUI/HTTP/orchestrator as needed
+2. Handle it in the shared runtime/driver boundary (`browser/src/participant/frontend.rs`)
+3. Implement frontend-specific behavior in `browser/src/participant/inner.rs` and/or `browser/src/participant/inner_lite.rs`
+4. Add the public method to `Participant` in `browser/src/participant/mod.rs`
+5. Expose it in the TUI if needed
 
 ### Debugging Browser Issues
 
@@ -269,15 +222,14 @@ The project allows specific lints (see `Cargo.toml`):
 ### Transport Modes
 
 Participants can use different WebRTC transport modes:
-- **UDP**: Standard WebRTC
-- **TCP**: Fallback for restrictive networks
+- **webtransport**
+- **webrtc**
 - Configured via `TransportMode` enum
 
 ### Noise Suppression & Resolution
 
-- Noise suppression levels: `Off`, `Low`, `Medium`, `High`
-- Webcam resolutions: Multiple presets from 180p to 1080p
-- Configurable per-participant in orchestrator mode
+- Noise suppression is configured via the `NoiseSuppression` enum
+- Webcam resolutions are configured via the `WebcamResolution` enum
 
 ## Important File Locations