play/CLAUDE.md

# CLAUDE.md

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

## Project Overview

**Video Player with Remote Control** - A desktop video player built with Nuxt 4 and Tauri 2 that supports WebSocket-based remote control. The application automatically searches for and plays `video.mp4` files from multiple locations and provides a fullscreen video experience with remote control capabilities.

## Architecture

### Tech Stack
- **Frontend**: Nuxt 4 (Vue 3) with TypeScript
- **Backend**: Rust with Tauri 2 framework
- **UI Framework**: NuxtUI v3 with TailwindCSS v4
- **Communication**: WebSocket server (port 6666) for remote control
- **Package Manager**: pnpm (enforced)

### Key Components

#### Frontend (`app/`)
- **Main Page**: `app/pages/index.vue` - Fullscreen video player with connection status
- **Tauri Module**: `app/modules/tauri.ts` - Auto-imports Tauri APIs
- **Assets**: `app/assets/` - CSS and icons
- **Layouts**: `app/layouts/` - Application layouts
- **Components**: `app/components/` - Reusable UI components

#### Backend (`src-tauri/`)
- **Main Entry**: `src-tauri/src/main.rs` - Application bootstrap
- **Library**: `src-tauri/src/lib.rs` - Tauri application setup and state management
- **WebSocket Server**: `src-tauri/src/websocket_server.rs` - Remote control server on port 6666
- **Player State**: `src-tauri/src/player_state.rs` - Video playback state management
- **Commands**: `src-tauri/src/commands.rs` - Tauri commands for frontend interaction
- **Permissions**: `src-tauri/capabilities/main.json` - Tauri v2 permission configuration

### Communication Flow
1. **Backend-to-Frontend**: Tauri events (`player-command`, `connection-status`)
2. **Frontend-to-Backend**: Tauri commands (`get_player_state`, `load_video`, etc.)
3. **Remote Control**: WebSocket server accepts JSON commands for playback control
4. **Auto-discovery**: Backend searches for `video.mp4` in multiple directories on startup

## Development Commands

### Setup & Installation
```bash
# Install dependencies (requires Node.js 23+)
pnpm install

# Verify Rust toolchain is installed for Tauri
rustc --version  # Should be >= 1.70
cargo --version
```

### Development
```bash
# Start development server with Tauri
pnpm tauri:dev

# Frontend only (port 3000)
pnpm dev

# Lint and fix code
pnpm lint
```

### Build & Distribution
```bash
# Build production application
pnpm tauri:build

# Build with debug symbols
pnpm tauri:build:debug

# Generate static site only
pnpm generate

# Version bump
pnpm bump
```

### Testing WebSocket Control
```bash
# Test WebSocket connection (requires Node.js)
node test_websocket.js
```

## Key Features

### Video Playback
- **Auto-loading**: Searches for `video.mp4` in current directory, public folder, and executable path
- **Fullscreen**: Auto-fullscreen mode configurable via `app.config.ts`
- **Controls**: Play/pause, seek, volume, loop, fullscreen toggle
- **Format Support**: MP4 with fallback handling

### Remote Control
- **WebSocket Server**: Runs on port 6666
- **JSON Protocol**: Standardized message format for all commands
- **Connection Status**: Real-time connection indicator in UI
- **Playlist Support**: Load and play from video playlists

### State Management
- **PlayerState**: Comprehensive video state including position, volume, loop status
- **VideoInfo**: Metadata tracking for loaded videos
- **Real-time Sync**: Frontend/backend state synchronization via Tauri events

## Configuration Files

### Application Config
- `app.config.ts` - Player settings (volume, fullscreen, etc.)
- `player_config.json` - Runtime configuration
- `nuxt.config.ts` - Nuxt and Tauri integration settings

### Build Configuration
- `src-tauri/tauri.conf.json` - Tauri application settings
- `src-tauri/Cargo.toml` - Rust dependencies and features
- `package.json` - Node.js dependencies and scripts

## Important Notes

### Permissions
- Tauri v2 uses capabilities-based permissions in `src-tauri/capabilities/main.json`
- Required permissions: file system access, notifications, OS info, shell commands
- WebSocket server runs on port 6666 (configurable in `src-tauri/src/lib.rs`)

### Development Gotchas
- **SSR Disabled**: `ssr: false` in nuxt.config.ts is required for Tauri
- **Asset URLs**: Uses `asset://localhost/` protocol for local file access
- **Auto-fullscreen**: Configurable but may be disabled in some environments
- **Video Discovery**: Searches up to 6 directory levels up from executable

### File Structure
```
video-player/
├── app/                    # Nuxt frontend
│   ├── pages/index.vue    # Main video player
│   ├── modules/tauri.ts   # Tauri API auto-imports
│   └── assets/            # Static assets
├── src-tauri/             # Rust backend
│   ├── src/
│   │   ├── lib.rs         # Main Tauri app
│   │   ├── websocket_server.rs  # Remote control
│   │   └── player_state.rs      # Video state
│   └── capabilities/      # Tauri permissions
├── public/                # Static files (video.mp4)
└── types/                 # TypeScript definitions
```

### Environment Requirements
- **Node.js**: >= 23.0.0
- **Rust**: >= 1.70.0
- **pnpm**: >= 10.13.1 (enforced)
- **Platform**: Windows, macOS, or Linux with Tauri prerequisites

## Common Development Tasks

### Adding New Tauri Commands
1. Add command function in `src-tauri/src/commands.rs`
2. Register command in `src-tauri/src/lib.rs` invoke_handler
3. Add TypeScript bindings in frontend
4. Update capabilities if new permissions needed

### WebSocket Protocol
- **Connect**: `ws://localhost:6666`
- **Commands**: JSON format `{"type":"command","data":{"type":"play"}}`
- **Status**: Real-time updates after each command
- **Playlist**: Support for multiple video files