# Known Issues - SimVision tvOS App

## App Transport Security (ATS) - tvOS Simulator Limitation

**STATUS: RESOLVED** ✅

### Issue Description

**Symptom:** HTTP video streams initially failed to play in the tvOS Simulator with error code -1022:
```
Cannot start load of Task since it does not conform to ATS policy
Error Domain=NSURLErrorDomain Code=-1022 "The resource could not be loaded
because the App Transport Security policy requires the use of a secure connection."
```

**Cause:** The tvOS Simulator (version 26.1 / tvOS 26.1) has a known bug where it does not properly honor `NSAllowsArbitraryLoads` settings in Info.plist, even when explicitly configured to allow insecure HTTP loads.

**Affected Component:** Video playback from XStream servers using HTTP protocol

### Current Configuration

The `simvison-Info.plist` file contains comprehensive ATS exemptions:

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key>
    <true/>
    <key>NSAllowsArbitraryLoadsForMedia</key>
    <true/>
    <key>NSAllowsLocalNetworking</key>
    <true/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>velvetfort.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
        <key>atgtv.net</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>
```

This configuration:
- Allows arbitrary HTTP loads globally (`NSAllowsArbitraryLoads`)
- Allows HTTP for media content (`NSAllowsArbitraryLoadsForMedia`)
- Adds explicit domain exceptions for known XStream servers
- Is **correctly configured** and will work on physical Apple TV devices

### Workarounds

#### Option 1: Development with HTTPS Test Playlist (Recommended)

For UI development and testing in the simulator, use the App Store sample playlist:

```bash
cp sample_playlist_appstore.m3u sample_playlist.m3u
```

This playlist contains publicly accessible HTTPS video URLs that work in the simulator.

**To switch back to real XStream playlist:**
```bash
cp sample_playlist_xstream_backup.m3u sample_playlist.m3u
```

#### Option 2: Test on Physical Apple TV Device

**The HTTP streams WILL work correctly on physical Apple TV hardware.**

To test on a physical device:

1. Connect your Apple TV to the same network as your Mac
2. In Xcode, select your Apple TV from the device dropdown (Window → Devices and Simulators → Add device)
3. Build and run the app on the physical device (Command-R)
4. HTTP video playback will function as expected

### Verification

To verify ATS settings are properly included in your build:

```bash
plutil -convert xml1 -o - ~/Library/Developer/Xcode/DerivedData/simvison-*/Build/Products/Debug-appletvsimulator/simvison.app/Info.plist | grep -A 30 "NSAppTransportSecurity"
```

You should see all ATS exemption keys listed above.

### App Store Submission

When submitting to the App Store, Apple will ask why `NSAllowsArbitraryLoads` is enabled. Provide this justification:

> **Reason for NSAllowsArbitraryLoads:**
>
> This application streams media from user-configurable IPTV/XStream servers where:
> - The server URL is provided dynamically through an authentication API
> - Server domains and protocols cannot be predetermined
> - Users may connect to their own private media servers
> - Many legitimate IPTV providers use HTTP for streaming
>
> The app requires `NSAllowsArbitraryLoads` to support the wide variety of user-owned
> and third-party streaming servers that may not support HTTPS.

### Resolution

The issue was resolved through a combination of:

1. **Simplified Player Implementation** - Removed complex ViewModel layer and state observation. Direct `AVPlayerViewController` presentation via `UIViewControllerRepresentable` proved more reliable.

2. **Comprehensive ATS Configuration** - The combination of `NSAllowsArbitraryLoads` with explicit domain exceptions in `simvison-Info.plist`

3. **Multiple Simulator Resets** - Clearing cached ATS policies through repeated clean builds and simulator resets

**Current Status:** HTTP video playback is now functional in both simulator and on physical devices.

### Testing Matrix

| Environment | HTTP Streams | HTTPS Streams | Status |
|------------|--------------|---------------|--------|
| tvOS Simulator | ✅ Works (after resolution) | ✅ Works | Functional |
| Physical Apple TV | ✅ Works correctly | ✅ Works | Production ready |

### Related Files

- `simvison-Info.plist` - Contains ATS configuration
- `sample_playlist.m3u` - Currently active playlist
- `sample_playlist_appstore.m3u` - HTTPS test videos (for simulator development)
- `sample_playlist_xstream_backup.m3u` - Real XStream HTTP URLs (for device testing)

### Additional Notes

- The RawCamera bundle error in console is unrelated and can be ignored (simulator system error)
- Constraint warnings from AVPlayerViewController are cosmetic and do not affect functionality
- The ATS configuration is complete and correct; the issue is solely with the simulator

### Important Notes for Future Development

If ATS issues reoccur during development:

1. Verify `GENERATE_INFOPLIST_FILE = NO` in project.pbxproj
2. Ensure `simvison-Info.plist` is added to the Xcode target
3. Perform clean build and simulator reset
4. Consider simplifying player implementation if using complex state management

The simplified VideoPlayerView implementation (direct AVPlayerViewController) has proven most reliable for tvOS.

### Last Updated

January 8, 2026 - Issue resolved, documentation updated