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:

   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:

   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:

   <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):

{
  "serverUrl": "xstream.example.com",
  "port": "8080",
  "username": "user123",
  "password": "pass456"
}

Error Response (401):

{
  "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