Stalker Portal

Read First

• docs/architecture/stalker-portal.md
• docs/architecture/stalker-epg.md for ITV EPG
• docs/architecture/remote-control.md for live remote control

Ownership

• Routed UI: libs/portal/stalker/feature/src/lib/
• Session, store, and normalization: libs/portal/stalker/data-access/src/lib/
• Wire-format and identity contracts: libs/shared/interfaces/src/lib/ — portal-mode predicate, MAC/device-ID utils, auth-failure classifier, cmd encoder, URL/identity builders. There because Electron main cannot import renderer libs; never fork them.
• Electron transport: apps/electron-backend/src/app/events/stalker.events.ts
• Provider-neutral collections: libs/portal/shared/data-access/src/lib/

Keep Stalker shape and store rules in Stalker data access. Shared portal UI must remain provider-neutral.

Portal Mode And Session

Full vs. simple mode is decided by observed behavior, not URL shape, and read only through isFullStalkerPortalPlaylist(). Route playlist-backed catalog, content and playback calls through executeStalkerRequest(). Auth, discovery, account-profile refresh and row-less collection resolution go direct; read stalker-request.utils.ts before adding a fifth. Repair is lazy per session, never eager. Full portals reuse the persisted idempotent handshake token while its session fingerprint matches, and ping get_events at the profile cadence (default 120 s). Auth failures are HTTP 200 plus plain text.

Series Contract

Inside Stalker portal code, isStalkerSeriesFlag() is the canonical predicate and accepts exactly true, 1, and '1'. normalizeStalkerSeriesFlag() delegates to it and produces the normalized positive marker true or undefined. The activity normalizer in shared interfaces keeps its dependency-neutral equivalent for favorites/recent and dashboard classification. Preserve all three modes: regular /series, VOD with embedded series[], and lazy Ministra VOD is_series.

Favorites/recent preserve the normalized positive marker and VOD origin so reopening still uses the correct lazy or embedded mode. Keep quick-start translation parameters and the naturally ordered season fallback when season_number is absent.

Lazy episodes use a deterministic tracking ID scoped by parent series, provider episode, season key, and episode number. legacyTrackingId is only a guarded compatibility alias. Reconciliation is limited to the current parent series and optional matching season/episode metadata; an exact scoped row always wins the resolved display position, while a compatible legacy row may remain tracked only for cleanup. The scoped ID is the in-memory key. At the strict migration boundary, save the scoped row before clearing a confirmed legacy row, and keep legacy progress when the save fails.

Before inline or external handoff, attach parent seriesXtreamId and resolved season/episode numbers. Keep them on subsequent position writes.

Live Contract

• Start bulk ITV EPG eagerly once channel rows exist. Rows read the bulk cache, falling back to throttled get_short_epg previews when it lacks "now".
• Radio skips EPG and external players, preserves live collection identity with radio: 'true', and uses the shared inline audio player.

Validation

Run:

• pnpm nx test shared-interfaces
• pnpm nx test portal-stalker-data-access
• pnpm nx test portal-stalker-feature
• the affected portal-shared-data-access / portal-shared-ui target for collection or radio behavior
• the affected workspace-dashboard-data-access and workspace-dashboard-feature test targets

For the user workflow, run pnpm nx run web-e2e:e2e-ci--src/stalker.e2e.ts or document the strongest focused coverage available.