Seamless stream switching for the Lume Engine (zero-delay zap/advance)

[bilipp]

Wires the engine's zero-delay switching (bilipp/LumeEngine#31, engine issue bilipp/LumeEngine#16) into the app. Merge the engine PR first — this branch calls the new waitForFirstFrame / public-state API.

What changes

• Channel zapping / episode switches: LumeEngineCoordinator.configure now keeps the current session on screen while the replacement opens through its first decoded frame, then swaps the display layers atomically (displayLayer became @Published so the video surface re-installs). The screen never goes black; a spinner shows over the still-playing outgoing stream.
• Next-episode auto-advance: prepareNext(media:) stages the queued episode in a standby session through first-frame-decoded. PlayerNextUpOverlay fires a latched onPrepareNext hook ~30 s before the end — only when premium + auto-advance/Next-button are actually enabled — so the advance lands on an already-decoded frame with zero delay. Other engines are unaffected (onPrepareNext defaults to nil).
• Safety during a switch: the outgoing session's stall/failure events no longer schedule retries (the switch supersedes them), and its position no longer leaks into the new stream's clock. Generation counters let rapid zapping cancel in-flight switches/prepares cleanly.
• Fallbacks: a failed seamless open falls back to the cold teardown-first path — that also covers providers that cap concurrent connections (teardown frees the slot before the retry). reload() stays cold on purpose: stall recovery re-opens the same URL and must release the connection first.
• Setting: new "Seamless Switching" toggle (default on) in Lume Engine Options — iOS/macOS form and tvOS detail — persisted as player.lume.seamlessSwitching, covered by Restore Defaults. The footer warns that a switch briefly holds two provider connections (the reason to turn it off on single-connection accounts).

Trade-off to know

With the option on, a failed switch costs up to open-timeout + one cold retry before the failure overlay appears — the price of never blanking the screen.

Verification

Builds clean for macOS and tvOS Simulator against the local engine package; the engine-side behavior is covered by 6 new tests in LumeEngine (SeamlessSwitchingTests, full suite 69/69).

[bilipp]

Connection-aware update (12eb1b2): switching now never exceeds the playlist's connection cap.

• PlayableMedia carries maxConnections (from the owning playlist's Xtream max_connections, populated by the factories, forwarded through resuming/replacingURL) and derives playlistID from the 36-char playlist-UUID prefix every catalog id embeds (same recovery StalkerStreamResolver uses).
• Per switch, the coordinator picks: overlapped (old stream keeps playing) only when the streams belong to different playlists, either side is a local file, or the account is known to allow ≥2 concurrent connections; otherwise a new sequential switch closes the outgoing session first (bounded join — the connection is genuinely free before the new open), keeps its last decoded frame frozen on screen, and swaps layers at the replacement's first frame. One provider connection at any moment, still no black gap.
• prepareNext obeys the same budget (a standby holds its own connection), so single-connection accounts skip the pre-open and auto-advance goes through the sequential path instead.
• Unknown caps (m3u, stalker, panels reporting "0") are treated as one connection — a wrong overlap can kill both streams, while sequential only costs the moving picture during the switch. A refused overlapped open retries sequentially before falling back cold.
• The switch flows moved to LumeEngineCoordinator+Switching.swift (file-length lint); the plumbing that mutates private(set) published state stays on the class.

Companion engine change: bilipp/LumeEngine#31 now ships SwitchPolicy (.overlapped/.sequential/.none). Settings footer updated — the toggle no longer needs to be turned off for single-connection providers.

Verified: macOS + tvOS builds, PlayableMediaTests (incl. Codable round-trip) green, engine suite 71/71.