4grayandClaude Opus 5
5e4f2ca3dd
Nine PRs landed between 2026-08-01 and 2026-08-04 in parallel worktrees, each
editing its own section of docs/architecture/stalker-portal.md and CLAUDE.md.
Sections that were correct when written disagreed with each other, or with
master, afterwards. Every claim here was verified against the code.
Corrected in stalker-portal.md: routes listed without the /workspace prefix;
"simple portals carry only the mac= cookie" (every request goes through the
shared identity builder — but the direct branch forwards no serial, so no
SN/__cfduid either, while playback headers are NOT mode-gated); a facade
introduced as "three modules" above a list of five; the pre-#1370 "blank
fields are not generated" opening; an ambiguous stalker-identity.utils.ts
citation (two files share the name); two of the three surfaces that apply the
scoped header override; a bare {status: 1} now being a refusal; and the
session-state fields #1354 added to the backup exclusion list (mirrored in
playlist-backup-restore.md).
CLAUDE.md had no entry at all for portal mode / endpoint discovery / lazy
repair — the largest change of the series; added one. Its session-facade list
was missing two modules and status 1 still read as plain "blocked".
Mock server: documented the /stalker, /stream/gated and marketing-poster
routes and the HOST variable; replaced the global POST /reset guidance with
the real per-MAC isolation contract (OWNED_MACS, the sibling 00:1A:79:5F:*
range, mode: 'serial'); added get_main_info; refreshed the project tree; fixed
a broken anchor; and corrected MOCK_PORT, which moves the client side only —
nothing maps it to the server's PORT.
The repo skill's "keep Stalker request rules in Stalker data access" no longer
holds: the wire-format, identity, portal-mode and auth-failure contracts live
in shared/interfaces because the Electron main process cannot import renderer
libs.
Also fixes four stale code comments carrying the same claims, including
"Single choke point for Stalker API calls" — four callers deliberately go
direct, and only fetchViaProfile() wires repair itself.
Docs and comments only; no executable change. No release note (no user-visible
behavior); no-release-note label applied for the libs/** paths.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
3.9 KiB
name, description
| name | description |
|---|---|
| stalker-portal | Use when changing Stalker or Ministra routes, stores, catalog or series shapes, playback progress, favorites and recent items, EPG, or remote control. |
Stalker Portal
Read First
docs/architecture/stalker-portal.mddocs/architecture/stalker-epg.mdfor ITV EPGdocs/architecture/remote-control.mdfor 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,cmdencoder, 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;
only the active channel may fall back to
get_short_epg. - 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-interfacespnpm nx test portal-stalker-data-accesspnpm nx test portal-stalker-feature- the affected
portal-shared-data-access/portal-shared-uitarget for collection or radio behavior - the affected
workspace-dashboard-data-accessandworkspace-dashboard-featuretest targets
For the user workflow, run
pnpm nx run web-e2e:e2e-ci--src/stalker.e2e.ts or document the strongest
focused coverage available.