Cold launch without connectivity blocks completed offline downloads #259

Summary

A user who already has completed local downloads can be locked out of them when Labstream cold-launches or relaunches without a reachable network/server session.

The credentials are generally preserved on transient transport failure, and the offline index/files are already loaded, but the top-level UI gate requires a live browse session before it mounts the only navigation surface that contains Offline. The result is a reconnect/sign-in surface with no route to playable local content.

This affects the download-capable visionOS, iOS/iPadOS, and macOS products. tvOS intentionally has no downloads capability.

Current behavior found in code

• ContentView runs AuthManager.restoreSession() and then chooses between RootView and LoginView through BrowseUIGate.
• On a cold launch, a transient restore failure leaves appModel.isBrowseReady == false; once restoration finishes, BrowseUIGate resolves to .login.
• Plex preserves the saved account token and shows PlexRestoreFailureView, but clears resolved server state, so the browse root is still unavailable.
• Jellyfin and Emby preserve their Keychain snapshots on transport/unreachable failure but clear their runtime lanes, which also leaves the browse root unavailable.
• DownloadManager is constructed before authentication, loads DownloadStore.records, and builds offlineLibrarySnapshot immediately.
• OfflineLibraryView plays completed media through CustomPlayerView(localFile:...); local playback itself does not require a live backend session.
• Offline navigation exists only inside the platform root shells, which are mounted by RootView after the live browse gate succeeds.

If connectivity disappears after RootView is already mounted, Offline generally remains reachable. The principal gap is cold launch/relaunch and a failed restore/switch that removes the root UI.

Expected behavior

A transient inability to reach the internet or configured server must not prevent access to valid completed local downloads.

Labstream should clearly distinguish:

1. no saved credentials / explicit sign-out;
2. confirmed invalid or revoked credentials;
3. saved credentials with a transient network, DNS, TLS, timeout, discovery, or server-unreachable failure.

For case 3, users with playable local content should have an obvious Open Offline path while retaining retry/reconnect and sign-in controls.

Suggested direction

• Add a typed selected-session restore outcome rather than deriving product behavior from a Boolean plus user-facing error text, e.g. restored, missingCredential, invalidCredential, and temporarilyUnavailable.
• Extend the top-level launch gate with an offline-capable state when:
  • downloads are supported;
  • restore failed transiently; and
  • at least one completed record still has its local media file.
• Prefer a deliberately restricted offline launch surface over mounting the complete online browse hierarchy with a fabricated authenticated session.
• The offline surface should provide:
  • completed-download list and local playback;
  • cached poster, subtitle, chapter, and trick-play assets when present;
  • local resume-position updates and delete controls;
  • reconnect/retry and Settings/sign-in access;
  • honest presentation for incomplete/active rows that cannot progress while unreachable.
• On successful reconnect, transition back to the normal root without destroying local playback state unnecessarily.
• Do not weaken credential validation, fabricate BackendSession, or treat transient failure as authenticated online browse readiness.

Product decisions to make explicitly

• Whether local downloads remain accessible after a deliberate sign-out or confirmed credential revocation. This issue at minimum covers saved credentials plus transient unreachability.
• Whether the offline entry should appear when durable rows exist but no completed local file survives.
• Whether Plex should separately cache enough selected-server connection metadata to reach a LAN PMS when plex.tv resource discovery is unavailable. That is related but not required to solve local-file access.

Acceptance criteria

• Cold-launch each download-capable platform with a saved session, at least one completed local download, and network/server reachability disabled.
• The app does not require re-authentication merely to open and play the completed local file.
• Plex, Jellyfin, and Emby transient restore failures preserve credentials and expose the same offline-access contract.
• A real unauthorized response remains distinct and does not silently create online browse authority.
• The offline-only surface does not issue browse/playback metadata requests for local playback.
• Cached offline posters, subtitles, chapters, trick-play data, and local playback position continue to work where present.
• Reconnect/retry upgrades to normal browse UI without losing the offline library.
• Behavior is covered by pure gate/restore-outcome tests plus platform integration tests for visionOS, iOS/iPadOS, and macOS.
• Manual airplane-mode/unreachable-server validation is recorded for at least one physical mobile device and Vision Pro; macOS network-unavailable launch is also checked.

Related context

• Audit long-lived auth/session handling for Plex, Jellyfin, and Emby #229 hardened credential preservation for transient network failures, but did not add an offline-content route around the live browse gate.
• Support simultaneous downloads across multiple backends #84 made persisted downloads backend-independent and hydrates inactive lanes, which means the local data plane is already largely separated from the selected browse session.