Add 'ios/' from commit '2220a0d4f2bb0f0ebca509581c21d6c90359bd14'

git-subtree-dir: ios
git-subtree-mainline: 52968df567
git-subtree-split: 2220a0d4f2

ios/CLAUDE.md

@@ -0,0 +1,93 @@
+# 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.
+- **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` - Add media URL to playlist
+- `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