QueueCube/ios/CLAUDE.md

# CLAUDE.md

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

## Project Overview

QueueCube is a SwiftUI-based jukebox client application for iOS and macOS (via Mac Catalyst). It provides a frontend for controlling a server-based jukebox system that supports playlist management, favorites, and playback controls.

## Architecture

### Core Components

- **API.swift**: Central networking layer that handles all communication with the jukebox server. Includes REST API methods for playback control, playlist management, and WebSocket events for real-time updates.
- **ContentView.swift**: Main view controller containing the `MainViewModel` that coordinates between UI components and API calls. Handles WebSocket event processing and data flow.
- **Server.swift**: Represents individual jukebox servers with support for both manual configuration and Bonjour service discovery.
- **ServerDiscovery.swift**: Main-app Bonjour browsing and bounded, cancellation-safe endpoint resolution for Add Server.
- **RequestBuilder.swift**: Shared extension-safe HTTP builder and error handling.
- **SharePlayback.swift**: Append once, select the new queue item, unpause, and verify playback using existing endpoints.
- **Settings.swift**: Manages multiple server configurations stored in UserDefaults with validation through `SettingsViewModel` that tests connectivity on URL changes.

### Data Flow

1. **Multiple Server Support**: Array of `Server` objects stored in UserDefaults with selected server tracking
2. **Settings**: Server configurations validated asynchronously via API calls with live connectivity testing
3. **Real-time Updates**: WebSocket connection provides live updates for playlist changes, playback state, and volume
4. **API Integration**: All server communication goes through the `API` struct using a fluent `RequestBuilder` pattern
5. **State Management**: Uses SwiftUI's `@Observable` pattern for reactive UI updates

### Request Builder Pattern

The API layer uses a fluent builder pattern for HTTP requests:
```swift
try await request()
    .path("/nowplaying")
    .json()
```

This provides type-safe, composable API calls with automatic error handling and connection state management.

### Key Features

- **Real-time sync**: WebSocket events automatically refresh UI when server state changes
- **Cross-platform**: Supports iOS, iPadOS, and macOS via Mac Catalyst
- **Settings validation**: Live server connectivity testing with visual feedback
- **Error handling**: Connection state management with user-friendly error displays

## Development Commands

### Building
```bash
# Build for iOS Simulator
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=iOS Simulator,name=iPhone 15' build

# Build for Mac Catalyst
xcodebuild -project QueueCube.xcodeproj -scheme QueueCube -destination 'platform=macOS,variant=Mac Catalyst' build
```

### Running
- Open `QueueCube.xcodeproj` in Xcode
- Select target device (iOS Simulator or Mac)
- Run with Cmd+R

## API Endpoints Reference

The server API includes these endpoints:
- `GET /nowplaying` - Current playback status
- `GET /playlist` - Current playlist items  
- `GET /favorites` - User favorites
- `POST /play`, `/pause`, `/skip`, `/previous` - Playback controls
- `POST /playlist` - Append media URL (append-play starts only when idle)
- `POST /skip/{index}` - Select and play a zero-based playlist index; existing queue remains
- `DELETE /playlist/{index}` - Remove playlist item
- `POST /volume` - Set volume level
- `WS /events` - WebSocket for real-time updates

## UI Structure

### View Hierarchy
```
QueueCubeApp
└── ContentView (coordination layer)
    └── MainView (tab management)
        ├── PlaylistView (with embedded NowPlayingView)
        ├── FavoritesView (favorites management)
        └── SettingsView (server configuration)
            ├── ServerListSettingsView
            ├── AddServerView
            └── GeneralSettingsView
```

### Key Views
- **ContentView**: Main coordinator that manages API instances and global state
- **MainView**: Tab-based navigation container with platform-specific adaptations
- **PlaylistView**: Scrollable list of queued media with reorder/delete actions, includes embedded NowPlayingView
- **NowPlayingView**: Playback controls and current track display
- **AddMediaBarView**: Input field for adding new media URLs to playlist
- **SettingsView**: Multi-server configuration with live validation and service discovery

## Share extension

`QueueCubeShare` is embedded in iOS and Mac Catalyst builds. It reads an App Group
settings snapshot and reuses the API code. Tapping a saved player queues and plays
the shared link; discovery remains in the main app. See [SHARE_EXTENSION.md](SHARE_EXTENSION.md)
for authentication limitations, queue/play failure semantics, signing setup, and focused tests.