Xtream Electron

Read First

• docs/architecture/xtream-portal-compatibility.md
• docs/architecture/portal-detail-navigation.md
• docs/architecture/sqlite-db-worker.md
• docs/architecture/vod-multi-source.md

Ownership And Runtime

Routed screens live in libs/portal/xtream/feature; API, cache, Signal Store, and data sources in libs/portal/xtream/data-access; collection services and reusable multi-source discovery/resolution in libs/portal/shared/data-access; reusable views in libs/portal/shared/ui; pure contracts/helpers only in libs/portal/shared/util. Screen-session multi-source orchestration stays in the Xtream feature.

Select ElectronXtreamDataSource only through RuntimeCapabilitiesService.supportsXtreamSqliteDataSource; otherwise use the PWA data source. A generic window.electron check is not the capability contract; existing favorites/recent branches that still use one are migration debt, not precedent.

Data And Navigation Contracts

• Xtream identity is playlist + normalized content type + provider xtream_id; collection keys include type and ID. Never resolve colliding live/movie/series IDs by number alone. Distinguish SQLite row IDs from provider xtream_id / stream_id / series_id.
• Browse and search use canonical item routes. Favorites/recent use collection-owned inline detail. Preserve enough provider/route identity to recover hidden categories without sending a local database ID to the API.
• Sparse VOD publishes the fallback selection first and recovers its provider category in the background. A playable candidate pairs a positive stream ID with an extension or an explicit HTTP(S) direct address. Never combine fields from incomplete candidates; Favorite/Watched do not require playback fields.
• VOD multi-source is capability-gated, owner-scoped, Electron-only Xtream-to-Xtream movie behavior. Its reusable core belongs in portal shared data access; the screen session/host belongs in the Xtream feature.

XtreamStore composes portal, content, selection, search, EPG, player, favorites, recent items, and playback positions.

On the SQLite path, large import/search/delete/restore work remains worker-backed. Renderer-visible DB progress and cancellation use operationId. Xtream API requests use requestId, import sessions use sessionId, and the DB worker also has an internal transport request ID; never conflate any of them.

Validation

Run both data-source specs plus affected Xtream store/feature tests. Use the closest atomized flow:

• web-e2e:e2e-ci--src/xtream.e2e.ts
• electron-backend-e2e:e2e-ci--src/xtream-responsiveness.e2e.ts
• electron-backend-e2e:e2e-ci--src/xtream-vod-details.e2e.ts
• electron-backend-e2e:e2e-ci--src/vod-multi-source.e2e.ts