simvision/NEXT_STEPS.md

# 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