dreamio/PLAN.md

# Dreamio iOS Plan

## Goal

Build **Dreamio**, a thin iOS wrapper around `stremio-web` for TestFlight, personal sideload, and private-device use. The v1 target is direct web playback only: debrid-backed HTTP/HLS sources that iOS WebKit can play without an on-device torrent engine or local streaming server.

## Product Positioning

Dreamio is not a public App Store product by default. Treat TestFlight and personal sideload as the intended distribution path until a separate App Store review strategy exists.

Avoid bundling, hardcoding, or presenting anything that implies unauthorized content access. Dreamio should behave like a web shell for user-configured Stremio flows, not a content service.

## Non-Goals

- On-device torrent engine
- Local streaming server parity with desktop
- Public App Store release in v1
- Full desktop feature parity in v1
- Large native rewrite in Swift/UIKit
- Native player bridge unless real-device testing proves it is needed

## Recommended Base

1. Use `stremio-web` as the app UI and flow source.
2. Do not start from `stremio-shell` because the desktop Qt shell does not map cleanly to iOS.
3. Keep native iOS code minimal; let the web app do most work.
4. Start with hosted `stremio-web` in `WKWebView` before investing in local bundling.
5. Pin the upstream `stremio-web` version or commit once bundling begins.

## Architecture (v1)

1. Native iOS host app using `WKWebView`.
2. Hosted `stremio-web` viability check first.
3. Bundled `stremio-web` static assets only after hosted viability passes.
4. Local `index.html` loaded inside `WKWebView`, assuming routing, storage, CORS, CSP, and auth still work from the bundled context.
5. Tiny JS <-> native bridge only for proven gaps such as fullscreen, PiP, external links, share sheet behavior, or subtitles.
6. Optional `AVPlayer` bridge only if real-device playback or subtitle behavior makes web playback unacceptable.

## Why This Is Feasible

- Direct web playback removes the hardest iOS blockers.
- No torrent/local-streaming process is needed.
- iOS WebKit can handle a practical subset of media formats, especially HLS and many MP4 streams.
- `WKWebView` can host the Stremio web flow with minimal native code if auth, storage, and media constraints are handled carefully.

## Feasibility Gates

Do not move to the next phase until the current gate passes on a real iPhone.

1. **Hosted web gate:** hosted `stremio-web` works inside `WKWebView` for login, browsing, addon flow, and library screens.
2. **Playback gate:** representative debrid-backed HLS and MP4 streams play on real iPhone/iPad hardware.
3. **Bundled app gate:** bundled static assets work without routing, storage, CORS, CSP, service worker, or auth regressions.
4. **Web-player sufficiency gate:** fullscreen, subtitles, PiP expectations, pause/resume, and background/foreground behavior are acceptable without a native player bridge.

## Hard Blockers / Stop Conditions

Pause or redesign the approach if any of these remain unresolved after focused investigation:

1. Login cannot persist reliably in `WKWebView`.
2. Direct playback fails for both HLS and MP4 on real iOS devices.
3. `stremio-web` depends on browser APIs unavailable in `WKWebView` with no practical workaround.
4. Debrid or addon flows depend on blocked origins, popups, redirects, or auth behavior that cannot be safely handled.
5. Bundled local assets introduce CORS, CSP, or storage behavior that cannot be fixed without turning Dreamio into a large fork.

## Implementation Steps

### 1) Fast viability check

1. Create a throwaway iOS app with a single `WKWebView`.
2. Point it to hosted `stremio-web` first.
3. Enable Safari Web Inspector for real-device debugging.
4. Verify login, browsing, addon install/config, catalog navigation, and library sync.
5. Test one representative playback flow before doing any local bundling.

### 2) Playback validation (critical)

1. Test known direct debrid streams on real iPhone and iPad hardware.
2. Validate at minimum:
   - HLS (`.m3u8`), expected best path
   - MP4, expected generally workable
   - MKV/custom codecs, expected mixed or unsupported
   - HEVC/H.265, especially device-generation differences
   - HDR, surround audio, and embedded subtitles as likely edge cases
3. Track failures by protocol, container, codec, subtitle type, MIME/content type, HTTP status, and WebKit media error.
4. Do not track failures only by provider name; provider labels are less useful than format behavior.

### 3) Local bundle integration

1. Pin the upstream `stremio-web` version or commit.
2. Build `stremio-web` static assets.
3. Copy build output into Xcode project resources through a reproducible script or documented build step.
4. Load bundled `index.html` from the app sandbox.
5. Verify routing, static asset paths, service worker behavior, API origins, CSP, CORS, auth redirects, cookies, local storage, and IndexedDB.
6. Document any local patches separately so upstream updates remain possible.

### 4) WebKit compatibility patches

1. Handle service worker limitations by disabling, bypassing, or adapting the affected behavior if needed.
2. Fix popup and new-tab flows in `WKWebView`.
3. Confirm auth/session persistence across app relaunch.
4. Confirm local storage and IndexedDB behavior under normal iOS cache pressure.
5. Confirm touch UX, viewport sizing, safe areas, and rotation.
6. Confirm ATS/HTTPS behavior for all required remote requests.

### 5) Optional native bridge additions

Add only when real-device tests show a specific gap:

- Fullscreen controls
- Picture in Picture
- External URL handling
- Share sheet/open-in-app behavior
- Subtitle import glue
- Minimal native player surface using `AVPlayer`

## Native Bridge Decision Rule

Stay web-only if HTML `<video>` playback, fullscreen, subtitles, and PiP behavior are good enough for v1.

Add a minimal JS <-> native bridge only for specific, test-proven gaps. Do not add broad native abstractions preemptively.

Consider an `AVPlayer` bridge only if one of these is true:

1. HLS/MP4 playback is materially more reliable in `AVPlayer` than in WebKit.
2. Subtitle behavior is unacceptable in WebKit but practical with native playback.
3. PiP, backgrounding, or fullscreen behavior cannot meet the v1 bar through the web path.

## Auth, Origin, and Storage Risks

Plan for these differences between hosted web, bundled local files, and `WKWebView`:

- OAuth/login redirects may need explicit navigation handling.
- Popup/new-tab flows need a `WKUIDelegate` path.
- Cookies may not behave exactly like Safari.
- Session persistence must be tested across app relaunch.
- Local storage and IndexedDB may be affected by iOS storage pressure.
- CORS and CSP behavior may differ between HTTPS origins and bundled local files.
- Raw `file://` loading may be insufficient; a local app-origin strategy may be needed if APIs assume a web origin.

## iOS Constraints To Plan For

- ATS/HTTPS requirements
- Autoplay and user-gesture media rules
- Background/foreground transitions during playback
- PiP entitlement and behavior
- Rotation and safe-area handling
- Storage limits and cache eviction patterns
- WebKit codec/container support differences by device generation
- AirPlay behavior if users expect it

## Debugging / Diagnostics

During PoC, keep a small manual compatibility log for every playback attempt:

1. Device and iOS version
2. Hosted or bundled build
3. Stream protocol and URL type, without storing sensitive tokens
4. MIME/content type and HTTP status
5. Container and codec guess
6. Subtitle type
7. WebKit media error, console error, or native navigation error
8. Outcome: plays, partially plays, fails clearly, or fails confusingly

Use Safari Web Inspector for console, network, storage, and media debugging wherever possible.

## v1 Scope

In scope:

1. Login/account sync
2. Catalog/discovery/library navigation
3. Addon install/config flow, assuming the web path supports it in `WKWebView`
4. Debrid-backed direct stream playback for iOS-compatible formats
5. Basic subtitle, fullscreen, rotation, and pause/resume behavior
6. TestFlight or personal sideload packaging

Out of scope:

1. Torrent-backed streaming
2. Universal codec parity with desktop
3. Desktop-equivalent advanced playback features
4. Public App Store optimization or review strategy
5. Native browsing/library rewrite

## Success Criteria

1. Dreamio starts quickly and consistently on real devices.
2. Login/session survives app relaunch.
3. Addon and library flows work without major rendering or redirect bugs.
4. Core browse flows work without major rendering bugs.
5. Representative HLS and MP4 direct streams play reliably.
6. Playback handles fullscreen, rotation, pause/resume, and background/foreground transitions acceptably.
7. Unsupported formats fail clearly rather than confusingly.
8. The build and bundle process is reproducible from a pinned `stremio-web` source version.

## Test Matrix (minimum)

Devices:

- One recent iPhone
- One older iPhone
- One iPad

Core flows:

1. Cold launch -> login -> browse -> select stream -> play
2. App relaunch preserves session
3. Addon install/config flow works
4. Library/catalog navigation works

Playback:

1. HLS baseline stream
2. MP4 baseline stream
3. MKV or codec-problem stream, documented as expected failure if unsupported
4. Subtitle on/off and language switch
5. Fullscreen enter/exit and rotation
6. Pause/resume -> background -> return -> continue
7. Network switch, Wi-Fi <-> cellular/hotspot

Bundle-specific checks:

1. Hosted `stremio-web` behavior compared against bundled build
2. Routing and asset loading
3. Storage persistence
4. CORS/CSP/auth redirect behavior
5. Service worker behavior

## Delivery Strategy

1. Build the `WKWebView` PoC against hosted `stremio-web`.
2. Continue only if hosted `stremio-web` inside `WKWebView` can complete login, browse, addon flow, and at least HLS/MP4 playback on a real iPhone.
3. If playback is good enough, bundle pinned `stremio-web` assets and harden routing, storage, auth, and media behavior.
4. Package for TestFlight or personal sideload.
5. Add native bridge features only when real-device tests prove they are necessary.

## Distribution and Review Risk

Dreamio should be treated as a private/TestFlight/sideload project unless and until a separate public App Store strategy exists.

A public App Store path may require changes to addon discovery, content positioning, account flows, and review messaging. Do not assume the private/TestFlight version can ship unchanged through public review.

## Bottom Line

For direct web-only debrid playback, Dreamio as a `stremio-web` + `WKWebView` wrapper is a realistic path if the real-device feasibility gates pass. Keep v1 narrow, prove hosted-web playback first, bundle only after the web flow works, and add native code only for specific problems that WebKit cannot solve well enough.