Initial commit: SimVision tvOS streaming app

Features: - VOD library with movie grouping and version detection - TV show library with season/episode organization - TMDB integration for trending shows and recently aired episodes - Recent releases section with TMDB release date sorting - Watch history tracking with continue watching - Playlist caching (12-hour TTL) for offline support - M3U playlist parsing with XStream API support - Authentication with credential storage Technical: - SwiftUI for tvOS - Actor-based services for thread safety - Persistent caching for playlists, TMDB data, and watch history - KSPlayer integration for video playback Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-21 22:12:08 -06:00
commit 872354b834
283 changed files with 338296 additions and 0 deletions
--- a/NEXT_STEPS.md
+++ b/NEXT_STEPS.md
@@ -0,0 +1,400 @@
+# Next Steps - SimVision Project Setup
+
+## Current Status
+
+✅ All source code files have been created (24 Swift files)
+✅ Architecture documentation completed
+✅ README documentation completed
+
+⚠️ **Xcode project needs to be created and configured**
+
+---
+
+## Step-by-Step Setup Instructions
+
+### Step 1: Create Xcode Project
+
+1. Launch Xcode (version 15.0 or later required)
+
+2. Select **File → New → Project** (⌘⇧N)
+
+3. In the template chooser:
+   - Select **tvOS** tab at the top
+   - Select **App** template
+   - Click **Next**
+
+4. Configure the project:
+   ```
+   Product Name:               simvision
+   Team:                       [Select your team]
+   Organization Identifier:    com.yourdomain
+   Bundle Identifier:          com.yourdomain.simvision
+   Interface:                  SwiftUI
+   Language:                   Swift
+   Include Tests:              ✓ (recommended)
+   ```
+   - Click **Next**
+
+5. Save location:
+   - Navigate to: `/Users/michaelsimard/dev/tvos/simvision`
+   - **Important**: Choose the existing `simvision` folder
+   - Uncheck "Create Git repository" (if not needed)
+   - Click **Create**
+
+### Step 2: Add Source Files to Xcode Project
+
+1. In Xcode Project Navigator (left sidebar):
+   - Right-click on the **simvision** folder (blue folder icon)
+   - Select **Add Files to "simvision"...**
+
+2. In the file browser:
+   - Navigate to `/Users/michaelsimard/dev/tvos/simvision/simvision`
+   - Select **all subdirectories**:
+     - App/
+     - Models/
+     - Views/
+     - Services/
+     - Parsers/
+     - ViewModels/
+     - Utilities/
+
+3. Configuration options (bottom of dialog):
+   - ✓ **Copy items if needed** (uncheck this - files already in correct location)
+   - ✓ **Create groups** (should be selected)
+   - ✓ **Add to targets: simvision** (ensure checked)
+   - Click **Add**
+
+4. Verify file structure in Project Navigator matches:
+   ```
+   simvision
+   ├── App
+   │   ├── simvisionApp.swift
+   │   └── AppState.swift
+   ├── Models
+   │   ├── Credentials.swift
+   │   ├── VODItem.swift
+   │   ├── Playlist.swift
+   │   └── APIResponse.swift
+   ├── Views
+   │   ├── Authentication
+   │   ├── Main
+   │   ├── Detail
+   │   ├── Player
+   │   └── Components
+   ├── Services
+   ├── Parsers
+   ├── ViewModels
+   └── Utilities
+   ```
+
+### Step 3: Delete Default Files
+
+Xcode creates default files that are not needed:
+
+1. In Project Navigator, select and delete these files:
+   - `ContentView.swift` (if created)
+   - Move to Trash when prompted
+
+### Step 4: Configure Project Settings
+
+#### A. Set Deployment Target
+
+1. Select the **simvision** project (blue icon at top of navigator)
+2. Select the **simvision** target (under TARGETS)
+3. In **General** tab:
+   - Set **Minimum Deployments: tvOS 17.0**
+
+#### B. Add Required Capabilities
+
+1. Stay in target settings
+2. Select **Signing & Capabilities** tab
+3. Click **+ Capability** button
+4. Search for and add: **Outgoing Connections (Client)**
+5. This capability is required for network requests
+
+#### C. Configure Code Signing
+
+1. In **Signing & Capabilities** tab:
+   - Select your **Team** from dropdown
+   - Ensure **Automatically manage signing** is checked
+   - Xcode will generate provisioning profile
+
+### Step 5: Update Configuration File
+
+1. In Xcode, open `simvision/Utilities/Constants.swift`
+
+2. Locate this section:
+   ```swift
+   enum API {
+       static let authenticationBaseURL = "https://your-web-service.com"
+       static let authenticationEndpoint = "/api/auth"
+       static let authenticationHeaderKey = "X-Password"
+       // ...
+   }
+   ```
+
+3. Replace the URL with your actual web service endpoint:
+   ```swift
+   static let authenticationBaseURL = "https://your-actual-domain.com"
+   ```
+
+4. If needed, update:
+   - `authenticationEndpoint` (if different from `/api/auth`)
+   - `authenticationHeaderKey` (if different from `X-Password`)
+
+5. Save the file (⌘S)
+
+### Step 6: Build the Project
+
+1. Select a tvOS Simulator from the scheme selector:
+   - Click the device selector next to the play/stop buttons
+   - Choose **Apple TV** (any tvOS 17.0+ simulator)
+
+2. Build the project:
+   - Select **Product → Build** (⌘B)
+   - Or click the play button to build and run
+
+3. Resolve any build errors:
+   - **Common issue**: File not found
+     - Solution: Ensure all files were added to target (Step 2)
+   - **Common issue**: Missing imports
+     - Solution: Verify deployment target is tvOS 17.0+
+   - **Common issue**: Duplicate symbols
+     - Solution: Check that default ContentView.swift was deleted
+
+### Step 7: Run in Simulator
+
+1. Ensure tvOS Simulator is selected
+
+2. Run the application:
+   - Select **Product → Run** (⌘R)
+   - Or click the play button (▶)
+
+3. Wait for simulator to launch and app to install
+
+4. Test the authentication flow:
+   - Password entry screen should appear
+   - Enter a test password
+   - Verify network request to your web service
+
+### Step 8: Test on Physical Apple TV (Optional)
+
+1. Connect Apple TV to your Mac via USB-C (Apple TV 4K) or network
+
+2. In Xcode:
+   - Select your Apple TV device from scheme selector
+   - You may need to pair the device first
+
+3. Build and run:
+   - Same process as simulator
+   - App will install on physical device
+
+4. Test with Siri Remote:
+   - Navigate using touchpad
+   - Select items with center button
+   - Test focus states and animations
+
+---
+
+## Verification Checklist
+
+After completing setup, verify the following:
+
+### Project Structure
+- [ ] Xcode project exists at `/Users/michaelsimard/dev/tvos/simvision/simvision.xcodeproj`
+- [ ] All 24 Swift files are visible in Project Navigator
+- [ ] Files are organized in groups (App, Models, Views, etc.)
+- [ ] No duplicate files or conflicts
+
+### Build Configuration
+- [ ] Project builds without errors (⌘B succeeds)
+- [ ] Deployment target is tvOS 17.0 or later
+- [ ] Outgoing Connections capability is enabled
+- [ ] Code signing is configured with valid team
+
+### Runtime Configuration
+- [ ] Constants.swift has correct web service URL
+- [ ] App launches in simulator without crashes
+- [ ] PasswordEntryView appears as first screen
+- [ ] Text input works on password field
+
+### Functionality Tests
+- [ ] Can enter password in authentication view
+- [ ] Sign In button becomes active when password is valid
+- [ ] Network request sends to configured endpoint
+- [ ] Error messages display correctly for invalid password
+- [ ] (After successful auth) VOD library view loads
+
+---
+
+## Troubleshooting Common Issues
+
+### Issue: "No such module 'SwiftUI'"
+
+**Cause**: Deployment target is too low
+
+**Solution**:
+1. Select project → Target → General
+2. Set **Minimum Deployments** to tvOS 17.0
+
+---
+
+### Issue: Build fails with "Command CompileSwift failed"
+
+**Cause**: Swift syntax errors or missing files
+
+**Solution**:
+1. Check error details in Report Navigator (⌘9)
+2. Common fixes:
+   - Ensure all files are added to target
+   - Verify no typos in file names
+   - Check that simvisionApp.swift exists
+
+---
+
+### Issue: "Thread 1: signal SIGABRT" at runtime
+
+**Cause**: SwiftUI preview crashes or missing environment object
+
+**Solution**:
+1. Check console output for specific error
+2. Ensure AppState is injected as environment object
+3. Verify all @EnvironmentObject declarations match
+
+---
+
+### Issue: Network requests fail immediately
+
+**Cause**: Outgoing Connections capability not enabled or App Transport Security
+
+**Solution**:
+1. Verify capability is added (Step 4B)
+2. If using HTTP (not HTTPS):
+   - Add to Info.plist:
+   ```xml
+   <key>NSAppTransportSecurity</key>
+   <dict>
+       <key>NSAllowsArbitraryLoads</key>
+       <true/>
+   </dict>
+   ```
+   - **Warning**: Only use for development
+
+---
+
+### Issue: Cannot type in password field in simulator
+
+**Cause**: Simulator keyboard not enabled
+
+**Solution**:
+1. In Simulator menu: **I/O → Keyboard → Toggle Software Keyboard**
+2. Or press: ⌘K
+
+---
+
+## Web Service Requirements Reminder
+
+Your authentication web service must implement:
+
+**Endpoint**: `POST {baseURL}/api/auth`
+
+**Request**:
+```
+Headers:
+  X-Password: user_entered_password
+```
+
+**Success Response** (200 OK):
+```json
+{
+  "serverUrl": "xstream.example.com",
+  "port": "8080",
+  "username": "user123",
+  "password": "pass456"
+}
+```
+
+**Error Response** (401):
+```json
+{
+  "error": "Invalid password"
+}
+```
+
+---
+
+## Next Development Steps (After Setup Complete)
+
+Once the basic setup is complete and the app runs successfully:
+
+1. **Implement your web service**
+   - Create authentication endpoint
+   - Test with Postman/curl first
+   - Update Constants.swift with real URL
+
+2. **Test with real XStream server**
+   - Obtain test XStream credentials
+   - Verify m3u playlist format matches parser expectations
+   - Test video stream playback
+
+3. **Customize UI** (optional)
+   - Update app icon
+   - Adjust colors in Constants.swift
+   - Modify grid layout (column count, spacing)
+
+4. **Add features**
+   - Implement search functionality
+   - Add favorites system
+   - Implement continue watching
+   - Add Live TV support
+
+5. **Prepare for release**
+   - Add app icon (1280x768 pixels)
+   - Create launch screen
+   - Test on multiple tvOS versions
+   - Submit to App Store Connect
+
+---
+
+## Important File Locations
+
+For future reference:
+
+| Purpose | File Path |
+|---------|-----------|
+| Xcode Project | `/Users/michaelsimard/dev/tvos/simvision/simvision.xcodeproj` |
+| Source Files | `/Users/michaelsimard/dev/tvos/simvision/simvision/` |
+| Configuration | `/Users/michaelsimard/dev/tvos/simvision/simvision/Utilities/Constants.swift` |
+| Architecture Docs | `/Users/michaelsimard/dev/tvos/simvision/ARCHITECTURE.md` |
+| Setup Guide | `/Users/michaelsimard/dev/tvos/simvision/README.md` |
+| This File | `/Users/michaelsimard/dev/tvos/simvision/NEXT_STEPS.md` |
+
+---
+
+## Support & Documentation
+
+- **README.md**: Overview, features, troubleshooting
+- **ARCHITECTURE.md**: Detailed system architecture and design decisions
+- **Apple Documentation**: https://developer.apple.com/tvos/
+- **SwiftUI Documentation**: https://developer.apple.com/documentation/swiftui/
+
+---
+
+## Status Tracking
+
+Current step: **Step 1 - Create Xcode Project**
+
+Mark steps as completed:
+- [ ] Step 1: Create Xcode Project
+- [ ] Step 2: Add Source Files
+- [ ] Step 3: Delete Default Files
+- [ ] Step 4: Configure Project Settings
+- [ ] Step 5: Update Configuration
+- [ ] Step 6: Build Project
+- [ ] Step 7: Run in Simulator
+- [ ] Step 8: Test on Device (optional)
+
+---
+
+**Last Updated**: 2026-01-08
+**Status**: Ready for Xcode project creation