From 26ca8e2cb0bccc0c3763619fb0631d93dfd639e9 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Sun, 4 Oct 2026 16:44:40 +0200
Subject: [PATCH 01/20] perf(ui): make the libs/ui Eager components OnPush
 (#1818)

* docs(performance): inventory the zoneless change-detection migration

Plan item C6 step 2. docs/architecture/zoneless-migration.md lists the 66
production files (67 components) that still set
ChangeDetectionStrategy.Eager, the ten places where a template-read plain
field is written outside an Angular event, the NgZone and
ChangeDetectorRef calls to remove at the flip, and the IPC, player,
observer, timer and dialog paths checked as signal-safe.

On Angular 22 an unset changeDetection already means OnPush, so only the
explicit Eager components re-render on every tick.

zoneless-migration.spec.ts in the performance harness compares the
checklist with the code: a new Eager component, or a converted one left
unticked, fails it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf(ui): make the libs/ui Eager components OnPush

Plan item C6 step 3 for libs/ui/components and libs/ui/epg: eleven
components (twelve with the EPG trust dialog) set
ChangeDetectionStrategy.Eager and were checked on every tick, among them
the always-mounted EPG progress panel the idle audit found re-rendering
on every idle tick. Their template state is already signals, signal
inputs, immutable dialog data or fields written from template events, so
they switch to OnPush without other changes.

The epg-item-description spec mutated dialog data after creation and
marked only the fixture's host view; it now marks the component's own
view, which OnPush requires. The libs/ui playback and remote-control
components stay Eager for their own PRs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../performance/zoneless-migration.spec.ts    |  91 +++++++
 docs/architecture/performance-journeys.md     |   3 +-
 docs/architecture/zoneless-migration.md       | 254 ++++++++++++++++++
 docs/maintenance/agent-context-map.md         |   1 +
 .../confirm-dialog.component.ts               |   3 +-
 .../content-hero/content-hero.component.ts    |   3 +-
 .../expandable-text.component.ts              |   3 +-
 .../content-about.component.ts                |   3 +-
 .../portal-detail-shell.component.ts          |   3 +-
 .../progress-capsule.component.ts             |   3 +-
 .../episode-info-dialog.component.ts          |   3 +-
 .../watched-badge/watched-badge.component.ts  |   3 +-
 .../epg-item-description.component.spec.ts    |  10 +-
 .../epg-item-description.component.ts         |   2 +-
 .../epg-progress-panel.component.ts           |   4 +-
 .../epg-source-status.component.ts            |   2 +-
 16 files changed, 367 insertions(+), 24 deletions(-)
 create mode 100644 apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
 create mode 100644 docs/architecture/zoneless-migration.md

diff --git a/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
new file mode 100644
index 000000000..c326c4a92
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
@@ -0,0 +1,91 @@
+/* eslint-disable playwright/expect-expect -- These are Node assertion-based repository contract tests. */
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+// docs/architecture/zoneless-migration.md lists every component that still
+// opts out of OnPush. This keeps the checklist and the code in step: a new
+// Eager component fails here, and so does a converted one left unticked.
+
+const workspaceRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const checklistPath = 'docs/architecture/zoneless-migration.md';
+const sourceRoots = ['apps', 'libs'];
+const skippedDirectories = new Set(['node_modules', 'dist', 'coverage']);
+const testOnlyFile =
+    /(\.spec|\.spec-stubs|\.spec-data|\.test-helpers|test-setup)\.ts$/;
+
+function listProductionSources(directory: string): string[] {
+    const files: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectories.has(entry.name)) continue;
+            if (entry.name.endsWith('-e2e')) continue;
+            files.push(...listProductionSources(path));
+        } else if (
+            entry.name.endsWith('.ts') &&
+            !entry.name.endsWith('.d.ts') &&
+            !testOnlyFile.test(entry.name)
+        ) {
+            files.push(relative(workspaceRoot, path).split(sep).join('/'));
+        }
+    }
+    return files;
+}
+
+function readSources(): Map<string, string> {
+    const sources = new Map<string, string>();
+    for (const root of sourceRoots) {
+        for (const file of listProductionSources(join(workspaceRoot, root))) {
+            sources.set(file, readFileSync(join(workspaceRoot, file), 'utf8'));
+        }
+    }
+    return sources;
+}
+
+function readEagerChecklist(): { open: string[]; done: string[] } {
+    const markdown = readFileSync(join(workspaceRoot, checklistPath), 'utf8');
+    const section = markdown.split(/^## Eager components$/m)[1];
+    assert.ok(
+        section,
+        `${checklistPath} must have an "Eager components" section`
+    );
+    const body = section.split(/^## /m)[0];
+    const open: string[] = [];
+    const done: string[] = [];
+    for (const match of body.matchAll(/^- \[( |x)\] `([^`]+\.ts)`/gm)) {
+        (match[1] === 'x' ? done : open).push(match[2]);
+    }
+    return { open: open.sort(), done: done.sort() };
+}
+
+const sources = readSources();
+
+test('the zoneless checklist lists exactly the components that are still Eager', () => {
+    const eager = [...sources]
+        .filter(([, text]) => text.includes('ChangeDetectionStrategy.Eager'))
+        .map(([file]) => file)
+        .sort();
+    const { open } = readEagerChecklist();
+
+    assert.deepEqual(
+        eager,
+        open,
+        `Production files with ChangeDetectionStrategy.Eager must match the unticked entries in ${checklistPath}. ` +
+            'Do not add Eager components; tick an entry when its component is converted.'
+    );
+});
+
+test('ticked checklist entries name files that exist', () => {
+    for (const file of readEagerChecklist().done) {
+        assert.ok(sources.has(file), `${file} is ticked but does not exist`);
+    }
+});
+
+test('no production component uses the deprecated Default strategy alias', () => {
+    for (const [file, text] of sources) {
+        assert.doesNotMatch(text, /ChangeDetectionStrategy\.Default\b/, file);
+    }
+});
diff --git a/docs/architecture/performance-journeys.md b/docs/architecture/performance-journeys.md
index 776e5c3dd..25ab024cf 100644
--- a/docs/architecture/performance-journeys.md
+++ b/docs/architecture/performance-journeys.md
@@ -208,7 +208,8 @@ window, and `evidence.idle.domMutations` the mutation records in the whole
 document. The [idle work audit](idle-work-audit-2026-09.md) found Eager
 components re-rendering on every such tick in a dev build; this counter
 measures the ticks in the optimized build, so plan item C6 can show what
-zoneless change detection removes.
+zoneless change detection removes; its checklist is the
+[zoneless migration](zoneless-migration.md).
 
 The window opens when the settle window closes, so startup data still
 landing is not idle work, and it is timed by a renderer `setTimeout`. The
diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
new file mode 100644
index 000000000..630d51ff2
--- /dev/null
+++ b/docs/architecture/zoneless-migration.md
@@ -0,0 +1,254 @@
+# Zoneless change-detection migration
+
+Working checklist for plan item C6 of the performance journeys plan: move the
+renderer (`apps/web`) from zone.js to `provideZonelessChangeDetection()`.
+The win is measured with the change-detection tick counters described in
+[performance journeys](performance-journeys.md#change-detection-ticks); the
+[idle work audit](idle-work-audit-2026-09.md) found the Eager roots that
+re-render on every tick. Update this file in the same PR that converts an item.
+
+The inventory was taken on `e8b181fce` (2026-10-04, Angular 22.1.6). Run
+`pnpm nx run electron-backend-e2e:test-performance-harness` after editing the
+Eager list: `zoneless-migration.spec.ts` fails when the list and the code
+disagree, so a new Eager component cannot land unnoticed and a converted one
+must be ticked here.
+
+## Starting point
+
+- **OnPush is already the default.** Since Angular 22 an unset
+  `changeDetection` means OnPush, and the old `Default` strategy is spelled
+  `ChangeDetectionStrategy.Eager`. Only components that set `Eager` are
+  checked on every tick. `ChangeDetectionStrategy.Default` is not used.
+- **Renderer bootstrap.** `apps/web/src/app/app.config.ts` provides
+  `provideZoneChangeDetection({ eventCoalescing: true })` and
+  `apps/web/project.json` builds with `"polyfills": ["zone.js"]`.
+  `apps/remote-control-web` does the same; it is a separate app and outside
+  this migration unless a step says otherwise.
+- **Unit tests already run zoneless.** Every `src/test-setup.ts` (apps/web,
+  apps/remote-control-web and 24 libs) calls `setupZonelessTestEnv` and loads
+  `zone.js`/`zone.js/testing` only for `fakeAsync` and `waitForAsync`. A
+  component that passes its specs is therefore not proof of zone-free
+  production behavior when the spec calls `fixture.detectChanges()` itself.
+- **IPC callbacks never ran in the Angular zone.** `window.electron.on*`
+  listeners arrive through `contextBridge` and are not zone-patched, so every
+  one that works today already writes signals or calls `NgZone.run`.
+- **Counters before the migration** (macOS, from
+  [performance journeys](performance-journeys.md#change-detection-ticks)):
+  `renderer.cdTicksToFirstCard` 20–21 (the one-tick zone.js race),
+  `renderer.cdTicksIdle30s` 3, `renderer.cdTicksToFirstPage` 22;
+  `renderer.cdTicksToPlaying` has no recorded run yet.
+
+## PR sequence
+
+1. [ ] Keep `@ngrx/store-devtools` out of production bundles (#1810, open). Not a
+   zone change; it lowered `renderer.initialBytes` before the migration
+   starts moving it.
+2. [x] This inventory and its guard spec.
+3. [ ] Per-project PRs, in this order, each converting the project's Eager
+   components and fixing its zone-dependent sites while zone.js stays on:
+   `libs/ui/*`, `libs/workspace/*`, `libs/playlist/*`, `libs/portal/*`,
+   playback (`libs/ui/playback`, `libs/playlist/m3u/feature-player`),
+   `apps/web`. Each reports the tick counters before and after and runs the
+   affected unit and E2E tests.
+4. [ ] `provideZonelessChangeDetection()` behind a build-time
+   `fileReplacements` flag, off by default; all four journeys and the
+   Electron E2E suite run with it on.
+5. [ ] Flag on by default, `zone.js` out of `polyfills`, new tick baselines
+   (`renderer.cdTicksIdle30s` and any counter that becomes deterministic once
+   the zone.js race is gone).
+
+## Eager components
+
+66 production files, 67 components (`epg-progress-panel.component.ts` holds
+two). Tick an entry by deleting `changeDetection: ChangeDetectionStrategy.Eager`
+(or setting OnPush) once its template state is signals, signal inputs or
+explicitly marked. The guard spec compares the unticked entries with the
+files that still contain `ChangeDetectionStrategy.Eager`.
+
+### apps/web (15)
+
+- [ ] `apps/web/src/app/app.component.ts` (idle audit root)
+- [ ] `apps/web/src/app/app-update-notification-panel.component.ts` (idle audit root)
+- [ ] `apps/web/src/app/settings/app-update-release-notes-dialog.component.ts`
+- [ ] `apps/web/src/app/settings/settings.component.ts`
+- [ ] `apps/web/src/app/settings/settings-about-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-backup-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-dashboard-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts`
+- [ ] `apps/web/src/app/settings/settings-epg-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-general-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-playback-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-remote-control-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-reset-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-tmdb-section.component.ts`
+- [ ] `apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts`
+
+### libs/ui (20 files, 21 components)
+
+- [x] `libs/ui/components/src/lib/confirm-dialog/confirm-dialog.component.ts`
+- [x] `libs/ui/components/src/lib/content-hero/content-hero.component.ts`
+- [x] `libs/ui/components/src/lib/expandable-text/expandable-text.component.ts`
+- [x] `libs/ui/components/src/lib/portal-detail-shell/content-about.component.ts`
+- [x] `libs/ui/components/src/lib/portal-detail-shell/portal-detail-shell.component.ts`
+- [x] `libs/ui/components/src/lib/progress-capsule/progress-capsule.component.ts`
+- [x] `libs/ui/components/src/lib/season-container/episode-info-dialog.component.ts`
+- [x] `libs/ui/components/src/lib/watched-badge/watched-badge.component.ts`
+- [x] `libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.ts`
+- [x] `libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts` (idle audit root; also `EpgTrustConfirmDialogComponent`)
+- [x] `libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts`
+- [ ] `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` (`apps/remote-control-web` only)
+- [ ] `libs/ui/playback/src/lib/art-player/art-player.component.ts`
+- [ ] `libs/ui/playback/src/lib/audio-player/audio-player.component.ts`
+- [ ] `libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts`
+- [ ] `libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts`
+- [ ] `libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts`
+- [ ] `libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts`
+- [ ] `libs/ui/playback/src/lib/vod-details/vod-details.component.ts`
+- [ ] `libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts`
+
+`libs/ui/playback` (8) goes with the playback PR, not the `libs/ui` one.
+
+### apps/remote-control-web (1)
+
+- [ ] `apps/remote-control-web/src/app/app.ts` (separate app; converts with `remote-control.component.ts`)
+
+### libs/workspace (7)
+
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts`
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts`
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts`
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts`
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts`
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts` (idle audit root)
+- [ ] `libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts`
+
+### libs/playlist (14)
+
+- [ ] `libs/playlist/import/feature/src/lib/add-playlist-dialog/add-playlist-dialog.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/auto-import/auto-import.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/file-upload/file-upload.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/stalker-portal-import/stalker-portal-import.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/text-import/text-import.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/url-upload/url-upload.component.ts`
+- [ ] `libs/playlist/import/feature/src/lib/xtream-code-import/xtream-code-import.component.ts`
+- [ ] `libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts`
+- [ ] `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts`
+- [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/empty-state/empty-state.component.ts`
+- [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-info/playlist-info.component.ts`
+- [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-item/playlist-item.component.ts`
+- [ ] `libs/playlist/shared/ui/src/lib/source-health/source-cleanup-dialog.component.ts`
+- [ ] `libs/playlist/shared/ui/src/lib/source-health/source-health-indicator.component.ts`
+
+`libs/playlist/m3u/feature-player` (2) goes with the playback PR.
+
+### libs/portal (9)
+
+- [ ] `libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts`
+- [ ] `libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts`
+- [ ] `libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts`
+- [ ] `libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts`
+- [ ] `libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts`
+- [ ] `libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts`
+- [ ] `libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts`
+- [ ] `libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts`
+- [ ] `libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts`
+
+Test stubs that set Eager (`*.spec.ts`, `*.spec-stubs.ts`, `*.spec-data.ts`,
+`*.test-helpers.ts`) are not listed; they do not ship.
+
+## Zone-dependent sites
+
+Plain (non-signal) fields read by a template and written from a callback
+that is not an Angular template event. Under zone.js the next tick happens to
+refresh an Eager view; under zoneless nothing schedules one. Each fix makes
+the field a signal (or a `computed`), or writes it through one.
+
+| Done | Site | What depends on the zone | Owning PR |
+| --- | --- | --- | --- |
+| [ ] | `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts` `onChannelNumberInput`/`clearChannelNumberInput` | 2 s `window.setTimeout` hides the channel-number overlay through plain `showChannelNumberOverlay`/`channelNumberInput` | playback |
+| [ ] | same file, `applySettings` and the settings `effect()` | IndexedDB `storage.get(...).subscribe` and an effect assign plain `playerSettings`, which picks the player in the template | playback |
+| [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-item/playlist-item.component.ts` `checkPortalStatus` | plain `portalStatus` assigned after `await` in `ngOnInit` (PWA only: skipped when source health is supported) | playlist |
+| [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-info/playlist-info.component.ts` (EPG clear and EPG file pick handlers) | plain `playlist` reassigned after `await` | playlist |
+| [ ] | `libs/playlist/import/feature/src/lib/stalker-portal-import/stalker-portal-import.component.ts` (device-id derivation) | `form.patchValue` after `await`; template getters read `control.value`, which is not signal-backed | playlist |
+| [ ] | `libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts` (favorites load) | `favorites` Map filled in a `subscribe` without `markForCheck`; the component is OnPush already, so this is a latent bug today | portal |
+| [ ] | `libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts` (favorites load) | same pattern; the neighbouring `favoriteMarks.changes$` handler does call `markForCheck` | portal |
+| [ ] | same file, programme dialog `afterClosed` | deletes from `epgPrograms`/`currentProgramsProgress` after `await` without marking | portal |
+| [ ] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize` | apps/web |
+| [ ] | `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` | plain `isLoading`/`error`/`status` written after `await` and from a 2 s `setInterval` | only if `apps/remote-control-web` goes zoneless |
+
+## Explicit zone and change-detector calls
+
+They keep working under zoneless (`NgZone` becomes `NoopNgZone`, so `run`
+and `runOutsideAngular` just call through). Remove them in the flip PR, not
+before: with zone.js on they still matter.
+
+- [ ] `apps/web/src/app/settings/settings-unload-guard.service.ts`: two
+  `zone.run` calls around the window-close dialog (IPC
+  `onWindowCloseRequested` and `beforeunload`).
+- [ ] `libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts`:
+  `runOutsideAngular(() => setInterval(...))` for the position poll;
+  `embedded-mpv-session-controller.position.spec.ts` asserts the call and
+  changes with it.
+- [ ] `libs/workspace/dashboard/data-access/src/lib/dashboard-data.service.ts`:
+  18 `ngZone.run(() => signal.set(...))` calls, all redundant around signal
+  writes.
+- [ ] `libs/workspace/dashboard/data-access/src/lib/dashboard-source-expiry.service.ts`:
+  one `ngZone.run` around a signal update.
+- `ChangeDetectorRef` in `stalker-live-stream-layout.component.ts`
+  (4 × `markForCheck`, 1 × `detectChanges` before measuring a row) and
+  `portal-channels-list.component.ts` (3 × `markForCheck`, 2 ×
+  `detectChanges`): correct under zoneless; replace the Maps with signals in
+  the portal PR if it stays small.
+
+## Checked and signal-safe
+
+No change needed; recorded so the flag PR knows where to look if a journey
+regresses. Embedded MPV and external players are the riskiest paths because
+their events arrive over IPC.
+
+- **IPC listeners** (17 registrations): app update status, external player
+  sessions, window close and window state, player errors, playlist open
+  requests, embedded MPV sessions, playback history gate, downloads,
+  recordings, playlist refresh, DB operation and save progress, EPG progress,
+  playback position updates, channel change and remote-control commands. All
+  write signals, signal stores or NgRx, or have no UI state.
+- **Player libraries** (video.js, mpegts.js, hls.js, artplayer, shaka, native
+  `<video>`): callbacks bump signals in the control adapters or emit outputs
+  whose parent handlers write signals.
+- **Observers** (13 Intersection/Resize/Mutation observers) and **document
+  and window listeners** (~40): signals or DOM only. `@HostListener`
+  bindings are Angular listeners and mark their view.
+- **Timers** (~130 `setTimeout`/`setInterval`/rAF/`queueMicrotask`): all
+  write signals, touch the DOM or focus, or have no UI state, apart from the
+  two in the table above.
+- **Dialogs and snackbars** (20 `afterClosed`/`onAction` sites): signals,
+  stores, outputs or navigation, apart from the one in the table above.
+- No production code uses `NgZone.onStable`, `onMicrotaskEmpty`, `isStable`,
+  `ApplicationRef.tick()`, `Zone.current` or `ngDoCheck`.
+
+## Build, tests and runtime details
+
+- [ ] `provideServiceWorker(..., { registrationStrategy:
+  'registerWhenStable:30000' })`: under zoneless "stable" means no pending
+  tasks. The 30 s bound still registers the worker; check the PWA build in
+  the flag PR.
+- [ ] `change-detection-tick-counter.ts` wraps `ApplicationRef._tick`, which
+  the zoneless scheduler also calls, so the counters stay comparable.
+- [ ] Specs that need zone.js: `fakeAsync` in
+  `playlist-switcher.component.spec.ts` and `stalker-live-navigation.spec.ts`,
+  `waitForAsync` in 13 files. They keep `zone.js/testing` until rewritten;
+  removing zone.js from the build polyfills does not affect them.
+- [ ] Unreferenced leftovers to delete in the flip PR:
+  `apps/web/src/polyfills.ts`, `apps/web/src/polyfills-test.ts`,
+  `apps/web/src/setup-jest.ts` (no project, tsconfig or Jest config uses
+  them).
+
+## Measuring a PR
+
+Build `electron-performance` and run the journeys as described in
+[performance journeys](performance-journeys.md), then paste
+`renderer.cdTicksToFirstCard`, `renderer.cdTicksIdle30s`,
+`renderer.cdTicksToFirstPage` and `renderer.cdTicksToPlaying` before and
+after. While zone.js is on, removing Eager does not change the number of
+ticks, only the work per tick; expect the counters to stay put until the flag
+PR and the template work (DOM mutations, profile time) to drop.
diff --git a/docs/maintenance/agent-context-map.md b/docs/maintenance/agent-context-map.md
index cc49ce265..41b6ba28c 100644
--- a/docs/maintenance/agent-context-map.md
+++ b/docs/maintenance/agent-context-map.md
@@ -15,6 +15,7 @@ are not prerequisites for reading repository contracts.
 | Angular conventions; docs and skills maintenance; local review before a pull request | [Agent workflow](../development/agent-workflow.md) | Use the area's skill below |
 | Unit, E2E, lint and coverage; `tools/coverage`, `tools/typecheck` | [Validation map](../architecture/validation-map.md) | Use the area's validation section |
 | Performance journeys, counters, benchmark probes and the CI ratchet; `apps/electron-backend-e2e/src/journeys`, `apps/electron-backend-e2e/src/performance`, `tools/performance` | [Performance journeys](../architecture/performance-journeys.md) | Read the contract directly |
+| Zoneless change detection, `ChangeDetectionStrategy.Eager` components, `NgZone` usage | [Zoneless migration](../architecture/zoneless-migration.md) | Read the checklist directly |
 | Electron entry/events/preload and CDP; `apps/electron-backend` | [Debugging and trace flags](../development/electron-debugging.md), [Electron security](../architecture/electron-security.md) | Use the available global electron skill for automation |
 | Releases, notes, screenshots, native assets, Linux manager metadata; `tools/release` | [Release pipeline](../architecture/release-pipeline.md), [note format](../../.changes/README.md) | [Release notes](../../.codex/skills/release-notes/SKILL.md), [release cut](../../.codex/skills/release-cut/SKILL.md) |
 
diff --git a/libs/ui/components/src/lib/confirm-dialog/confirm-dialog.component.ts b/libs/ui/components/src/lib/confirm-dialog/confirm-dialog.component.ts
index 937c06e54..375f073d2 100644
--- a/libs/ui/components/src/lib/confirm-dialog/confirm-dialog.component.ts
+++ b/libs/ui/components/src/lib/confirm-dialog/confirm-dialog.component.ts
@@ -29,8 +29,7 @@ export interface ConfirmDialogData {
 
 @Component({
     imports: [MatButtonModule, MatDialogModule, TranslateModule],
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     template: `
         <h2 mat-dialog-title>
             {{ dialogData.title }}
diff --git a/libs/ui/components/src/lib/content-hero/content-hero.component.ts b/libs/ui/components/src/lib/content-hero/content-hero.component.ts
index 5917e374e..6413a66b5 100644
--- a/libs/ui/components/src/lib/content-hero/content-hero.component.ts
+++ b/libs/ui/components/src/lib/content-hero/content-hero.component.ts
@@ -34,8 +34,7 @@ export type ContentHeroLayout = 'stage' | 'compact';
         TranslateModule,
     ],
     templateUrl: './content-hero.component.html',
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrls: ['./content-hero.component.scss'],
 })
 export class ContentHeroComponent {
diff --git a/libs/ui/components/src/lib/expandable-text/expandable-text.component.ts b/libs/ui/components/src/lib/expandable-text/expandable-text.component.ts
index a35f18b95..1b50a3fcf 100644
--- a/libs/ui/components/src/lib/expandable-text/expandable-text.component.ts
+++ b/libs/ui/components/src/lib/expandable-text/expandable-text.component.ts
@@ -47,8 +47,7 @@ import { TranslateModule } from '@ngx-translate/core';
             </button>
         }
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             :host {
diff --git a/libs/ui/components/src/lib/portal-detail-shell/content-about.component.ts b/libs/ui/components/src/lib/portal-detail-shell/content-about.component.ts
index 1d55c39f6..71328b8bd 100644
--- a/libs/ui/components/src/lib/portal-detail-shell/content-about.component.ts
+++ b/libs/ui/components/src/lib/portal-detail-shell/content-about.component.ts
@@ -56,8 +56,7 @@ import { TranslateModule } from '@ngx-translate/core';
             </div>
         </section>
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrls: ['./content-about.component.scss'],
 })
 export class ContentAboutComponent {
diff --git a/libs/ui/components/src/lib/portal-detail-shell/portal-detail-shell.component.ts b/libs/ui/components/src/lib/portal-detail-shell/portal-detail-shell.component.ts
index e47c41426..4b368c609 100644
--- a/libs/ui/components/src/lib/portal-detail-shell/portal-detail-shell.component.ts
+++ b/libs/ui/components/src/lib/portal-detail-shell/portal-detail-shell.component.ts
@@ -43,8 +43,7 @@ import {
     imports: [ContentHeroComponent, ContentAboutComponent, NgTemplateOutlet],
     templateUrl: './portal-detail-shell.component.html',
     styleUrls: ['./portal-detail-shell.component.scss'],
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     host: {
         tabindex: '0',
         role: 'region',
diff --git a/libs/ui/components/src/lib/progress-capsule/progress-capsule.component.ts b/libs/ui/components/src/lib/progress-capsule/progress-capsule.component.ts
index c1394d165..253703482 100644
--- a/libs/ui/components/src/lib/progress-capsule/progress-capsule.component.ts
+++ b/libs/ui/components/src/lib/progress-capsule/progress-capsule.component.ts
@@ -19,8 +19,7 @@ import {
             ></div>
         </div>
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             .progress-capsule {
diff --git a/libs/ui/components/src/lib/season-container/episode-info-dialog.component.ts b/libs/ui/components/src/lib/season-container/episode-info-dialog.component.ts
index 59c78ca4c..e08e4dbf4 100644
--- a/libs/ui/components/src/lib/season-container/episode-info-dialog.component.ts
+++ b/libs/ui/components/src/lib/season-container/episode-info-dialog.component.ts
@@ -105,8 +105,7 @@ export const EPISODE_INFO_PLAY = 'play' as const;
             </button>
         </div>
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             :host {
diff --git a/libs/ui/components/src/lib/watched-badge/watched-badge.component.ts b/libs/ui/components/src/lib/watched-badge/watched-badge.component.ts
index cba3fe79a..582e7dcb5 100644
--- a/libs/ui/components/src/lib/watched-badge/watched-badge.component.ts
+++ b/libs/ui/components/src/lib/watched-badge/watched-badge.component.ts
@@ -12,8 +12,7 @@ import { MatIcon } from '@angular/material/icon';
             </div>
         }
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             .watched-badge {
diff --git a/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.spec.ts b/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.spec.ts
index ce7dd3c79..bd8c5ec1f 100644
--- a/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.spec.ts
+++ b/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.spec.ts
@@ -1,4 +1,4 @@
-import { signal } from '@angular/core';
+import { ChangeDetectorRef, signal } from '@angular/core';
 import { ComponentFixture, TestBed, waitForAsync } from '@angular/core/testing';
 import { MAT_DIALOG_DATA, MatDialogModule } from '@angular/material/dialog';
 import { By } from '@angular/platform-browser';
@@ -72,8 +72,12 @@ describe('EpgItemDescriptionComponent', () => {
     });
 
     it('offers archive URL copying only with explicit capability and explains credentials', () => {
+        // The component is OnPush and dialog data is fixed once the dialog
+        // opens, so the test marks the component's own view after mutating it.
+        const componentView =
+            fixture.debugElement.injector.get(ChangeDetectorRef);
         Object.assign(component.dialogData, { archiveUrlAvailable: true });
-        fixture.changeDetectorRef.markForCheck();
+        componentView.markForCheck();
         fixture.detectChanges();
         expect(
             fixture.nativeElement.querySelector(
@@ -84,7 +88,7 @@ describe('EpgItemDescriptionComponent', () => {
             'EPG.PROGRAM_DIALOG.ARCHIVE_URL_NOTICE'
         );
         Object.assign(component.dialogData, { archiveUrlAvailable: false });
-        fixture.changeDetectorRef.markForCheck();
+        componentView.markForCheck();
         fixture.detectChanges();
         expect(
             fixture.nativeElement.querySelector(
diff --git a/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.ts b/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.ts
index de527bda8..98ad0ff77 100644
--- a/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.ts
+++ b/libs/ui/epg/src/lib/epg-item-description/epg-item-description.component.ts
@@ -38,7 +38,7 @@ export type EpgItemDialogData = EpgProgram & {
     selector: 'app-epg-item-description',
     templateUrl: './epg-item-description.component.html',
     styleUrls: ['./epg-item-description.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [DatePipe, MatDialogModule, MatIcon, TranslatePipe],
 })
 export class EpgItemDescriptionComponent {
diff --git a/libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts b/libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts
index d0e47b8e9..a1011039b 100644
--- a/libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts
+++ b/libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts
@@ -32,7 +32,7 @@ interface EpgTrustConfirmDialogData {
 @Component({
     selector: 'app-epg-trust-confirm-dialog',
     imports: [MatButtonModule, MatDialogModule, TranslatePipe],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     template: `
         <h2 mat-dialog-title>{{ data.title }}</h2>
         <mat-dialog-content class="mat-typography">
@@ -64,7 +64,7 @@ class EpgTrustConfirmDialogComponent {
         TranslatePipe,
     ],
     templateUrl: './epg-progress-panel.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './epg-progress-panel.component.scss',
 })
 export class EpgProgressPanelComponent {
diff --git a/libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts b/libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts
index e5fb3777d..12d5fc93d 100644
--- a/libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts
+++ b/libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts
@@ -30,7 +30,7 @@ type BadgeStatus =
         TranslatePipe,
     ],
     templateUrl: './epg-source-status.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './epg-source-status.component.scss',
 })
 export class EpgSourceStatusComponent implements OnInit {

From 7a629f5fe5c98552045b5268ac1ded5a8eb8235d Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Sun, 4 Oct 2026 16:51:58 +0200
Subject: [PATCH 02/20] fix(dashboard): hero legibility in the light theme and
 stable page heading (#1811)

UI-24 from the UI consistency audit.

- No-artwork slides paint their gradient in CSS from the slide hue: a light
  tint in the light theme, unchanged near-black in the dark one. The dark
  gradient under the light page-coloured scrim read as a grey slab.
- The side scrim holds 88% of the page colour up to the slide's right edge
  (inset + min(560px, 55%)), so the end of a full slide no longer sits on
  about 45%.
- Narrow layout (container <= 720px): a full-bleed 90% scrim behind the text
  block, a scrim-coloured text shadow, and an entrance without a fade so
  that scrim never flashes the art on a rotation.
- --hero-body is 85% of the heading colour (was 72%).
- Light --app-rating-color #a16207 -> #7a4a00: measured 3.36:1 on the chip
  over artwork, now 5.10:1. The details pages share the chip and token.
- Buttons cap at the slide width and end long labels in an ellipsis.
- The page gets one visually hidden h1 ("Dashboard"); slide titles are h2.
- One live region outside the re-created slide announces slide changes;
  progress bars are named and VOD ones read "N% watched"; dots are 24px.

dashboard-hero-legibility.e2e.ts replaces every image with a checkerboard
and measures each piece of slide text from the screen in both themes, wide
and narrow, for backdrop, poster, no-artwork and live slides. On master the
worst cases were 2.35:1 (body text) and 2.65:1 (pills).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changes/dashboard-hero-light-legibility.md   |  10 +
 .../src/dashboard-activation.e2e.ts           |  54 +--
 .../src/dashboard-e2e-flows.ts                |  54 +++
 .../src/dashboard-hero-legibility.e2e.ts      | 355 ++++++++++++++++++
 .../src/theme-contrast.ts                     |  95 +++++
 apps/web/src/m3-theme.scss                    |   5 +-
 docs/architecture/workspace-dashboard.md      |  28 +-
 .../rails/dashboard-hero-slides.presenter.ts  |   1 -
 .../lib/rails/dashboard-hero.component.html   |  35 +-
 .../lib/rails/dashboard-hero.component.scss   |  96 ++++-
 .../rails/dashboard-hero.component.spec.ts    |  76 +++-
 .../src/lib/rails/dashboard-hero.utils.ts     |  43 +--
 .../workspace-dashboard-rails.component.html  |   5 +
 ...orkspace-dashboard-rails.component.spec.ts |   6 +-
 14 files changed, 743 insertions(+), 120 deletions(-)
 create mode 100644 .changes/dashboard-hero-light-legibility.md
 create mode 100644 apps/electron-backend-e2e/src/dashboard-e2e-flows.ts
 create mode 100644 apps/electron-backend-e2e/src/dashboard-hero-legibility.e2e.ts

diff --git a/.changes/dashboard-hero-light-legibility.md b/.changes/dashboard-hero-light-legibility.md
new file mode 100644
index 000000000..f0dd60918
--- /dev/null
+++ b/.changes/dashboard-hero-light-legibility.md
@@ -0,0 +1,10 @@
+---
+type: fix
+area: dashboard
+---
+
+The dashboard hero stays readable in the light theme: titles without artwork
+get a light tinted backdrop instead of a dark slab, text keeps a solid backing
+over busy artwork (also in narrow windows), and the star rating is darker.
+Screen readers now find one stable "Dashboard" page heading and hear slide
+changes they make.
diff --git a/apps/electron-backend-e2e/src/dashboard-activation.e2e.ts b/apps/electron-backend-e2e/src/dashboard-activation.e2e.ts
index 51eb37830..745b78058 100644
--- a/apps/electron-backend-e2e/src/dashboard-activation.e2e.ts
+++ b/apps/electron-backend-e2e/src/dashboard-activation.e2e.ts
@@ -29,6 +29,11 @@ import {
     routePlayableStreams,
     startAndConfirmPlayback,
 } from './playable-stream-fixture';
+import {
+    addCurrentDetailToFavorites,
+    goBackFromDetail,
+    toggleFavoriteForChannel,
+} from './dashboard-e2e-flows';
 
 test.describe('Dashboard Activation', () => {
     test('opens live favorites in the collection route and movies/series in global collection detail views from the dashboard', async ({
@@ -305,38 +310,6 @@ function dashboardRailCardByTitle(
         .first();
 }
 
-async function goBackFromDetail(page: Page): Promise<void> {
-    // Return to the list: the header's Back is route-level in browse and
-    // watch alike (closing the player is the bar's own Close button).
-    const backButton = page.getByTestId('workspace-header-back');
-
-    await expect(backButton).toBeVisible({ timeout: 20000 });
-    try {
-        await backButton.click({ timeout: 5000 });
-    } catch {
-        await backButton.evaluate((button: HTMLButtonElement) =>
-            button.click()
-        );
-    }
-}
-
-// By accessible name, not class: the Xtream movie detail's favorite control is
-// an icon-only button that carries its label in aria-label, while series and
-// Stalker details still use the labeled variant. This matches both.
-async function addCurrentDetailToFavorites(page: Page): Promise<void> {
-    const addButton = page
-        .getByRole('button', { name: /add to favorites/i })
-        .first();
-
-    await expect(addButton).toBeVisible({ timeout: 20000 });
-    await addButton.click();
-    await expect(
-        page.getByRole('button', { name: /remove from favorites/i }).first()
-    ).toBeVisible({
-        timeout: 20000,
-    });
-}
-
 async function expectInlineCollectionDetail(
     page: Page,
     params: {
@@ -383,20 +356,3 @@ async function playFirstSeriesEpisode(page: Page): Promise<void> {
     await expect(episodeCard).toBeVisible({ timeout: 20000 });
     await episodeCard.click();
 }
-
-async function toggleFavoriteForChannel(
-    page: Page,
-    title: string
-): Promise<void> {
-    const item = page
-        .locator('[data-test-id="channel-item"]')
-        .filter({ hasText: title })
-        .first();
-
-    await expect(item).toBeVisible({ timeout: 20000 });
-    await item.hover();
-    await item.locator('.favorite-button').first().click();
-    await expect(item.locator('.favorite-button mat-icon').first()).toHaveText(
-        /star/
-    );
-}
diff --git a/apps/electron-backend-e2e/src/dashboard-e2e-flows.ts b/apps/electron-backend-e2e/src/dashboard-e2e-flows.ts
new file mode 100644
index 000000000..208900940
--- /dev/null
+++ b/apps/electron-backend-e2e/src/dashboard-e2e-flows.ts
@@ -0,0 +1,54 @@
+import type { Page } from '@playwright/test';
+import { expect } from './electron-test-fixtures';
+
+// Steps that put content on the dashboard: favourites from the Live TV list
+// and from a detail page, and the way back from that detail page.
+
+export async function goBackFromDetail(page: Page): Promise<void> {
+    // Return to the list: the header's Back is route-level in browse and
+    // watch alike (closing the player is the bar's own Close button).
+    const backButton = page.getByTestId('workspace-header-back');
+
+    await expect(backButton).toBeVisible({ timeout: 20000 });
+    try {
+        await backButton.click({ timeout: 5000 });
+    } catch {
+        await backButton.evaluate((button: HTMLButtonElement) =>
+            button.click()
+        );
+    }
+}
+
+// By accessible name, not class: the Xtream movie detail's favorite control is
+// an icon-only button that carries its label in aria-label, while series and
+// Stalker details still use the labeled variant. This matches both.
+export async function addCurrentDetailToFavorites(page: Page): Promise<void> {
+    const addButton = page
+        .getByRole('button', { name: /add to favorites/i })
+        .first();
+
+    await expect(addButton).toBeVisible({ timeout: 20000 });
+    await addButton.click();
+    await expect(
+        page.getByRole('button', { name: /remove from favorites/i }).first()
+    ).toBeVisible({
+        timeout: 20000,
+    });
+}
+
+export async function toggleFavoriteForChannel(
+    page: Page,
+    title: string
+): Promise<void> {
+    const item = page
+        .locator('[data-test-id="channel-item"]')
+        .filter({ hasText: title })
+        .first();
+
+    await expect(item).toBeVisible({ timeout: 20000 });
+    await item.hover();
+    await item.locator('.favorite-button').first().click();
+    await expect(item.locator('.favorite-button mat-icon').first()).toHaveText(
+        /star/
+    );
+}
diff --git a/apps/electron-backend-e2e/src/dashboard-hero-legibility.e2e.ts b/apps/electron-backend-e2e/src/dashboard-hero-legibility.e2e.ts
new file mode 100644
index 000000000..7accbb72e
--- /dev/null
+++ b/apps/electron-backend-e2e/src/dashboard-hero-legibility.e2e.ts
@@ -0,0 +1,355 @@
+import type { Locator, Page } from '@playwright/test';
+import { writeFileSync } from 'node:fs';
+import sharp = require('sharp');
+import {
+    addXtreamPortal,
+    clickCategoryByNameExact,
+    clickFirstGridListCard,
+    closeElectronApp,
+    defaultXtreamPassword,
+    defaultXtreamUsername,
+    expect,
+    goToDashboard,
+    launchElectronApp,
+    openWorkspaceSection,
+    resetMockServers,
+    test,
+    waitForXtreamWorkspaceReady,
+} from './electron-test-fixtures';
+import {
+    fetchXtreamLiveFixture,
+    fetchXtreamSeriesFixture,
+    fetchXtreamVodFixture,
+    getXtreamTitle,
+} from './portal-mock-fixtures';
+import { applyTheme, measureBackdropTextContrast } from './theme-contrast';
+import {
+    addCurrentDetailToFavorites,
+    goBackFromDetail,
+    toggleFavoriteForChannel,
+} from './dashboard-e2e-flows';
+
+// ---------------------------------------------------------------------------
+// The dashboard hero's text must stay legible over any artwork, in both
+// themes and in the narrow layout where the slide spans the whole width.
+// Every mock image is replaced by a black-and-white checkerboard, the worst
+// case for either theme's scrim; series images fail, so the favourited
+// series falls back to the generated gradient. Each slide kind (16:9
+// backdrop, blurred poster, no artwork, live channel) is measured from the
+// screen at a wide and a narrow content width.
+// ---------------------------------------------------------------------------
+
+type SlideKind = 'backdrop' | 'poster' | 'fallback' | 'live';
+
+const widths = { wide: 1280, narrow: 760 } as const;
+const minimumContrast = 4.5;
+const xtreamCredentials = {
+    username: defaultXtreamUsername,
+    password: defaultXtreamPassword,
+};
+/** A full TMDB slide has a rating and a two-line overview; the mock has no
+ * TMDB, so the measurement adds both, styled by the hero's own rules. */
+const sampleOverview =
+    'A long synopsis that wraps onto a second line, so the body text of a ' +
+    'fully enriched slide is measured where it really sits over the artwork.';
+
+async function busyArtwork(): Promise<Buffer> {
+    const width = 1280;
+    const height = 720;
+    const square = 40;
+    const pixels = Buffer.alloc(width * height * 3);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const white =
+                (Math.floor(x / square) + Math.floor(y / square)) % 2 === 0;
+            pixels.fill(
+                white ? 255 : 0,
+                (y * width + x) * 3,
+                (y * width + x) * 3 + 3
+            );
+        }
+    }
+    return sharp(pixels, { raw: { width, height, channels: 3 } })
+        .png()
+        .toBuffer();
+}
+
+/** Serves the checkerboard for every mock image except series artwork,
+ * which fails: an image the page has already shown is reused from memory,
+ * so the failure has to be in place before the series is first opened. */
+async function routeArtwork(page: Page): Promise<void> {
+    const image = await busyArtwork();
+    await page.route(
+        (url) => url.hostname === 'picsum.photos',
+        (route) =>
+            /\/seed\/series-/.test(route.request().url())
+                ? route.fulfill({ status: 404, body: '' })
+                : route.fulfill({
+                      status: 200,
+                      contentType: 'image/png',
+                      body: image,
+                  })
+    );
+}
+
+async function slideKinds(page: Page): Promise<SlideKind[]> {
+    return page.locator('.hero__backdrop').evaluateAll((backdrops) =>
+        backdrops.map((backdrop): SlideKind => {
+            if (backdrop.classList.contains('hero__backdrop--live')) {
+                return 'live';
+            }
+            if (!backdrop.querySelector('.hero__backdrop-image')) {
+                return 'fallback';
+            }
+            return backdrop.classList.contains('hero__backdrop--poster')
+                ? 'poster'
+                : 'backdrop';
+        })
+    );
+}
+
+async function showSlide(page: Page, index: number): Promise<Locator> {
+    const dot = page.getByTestId('dashboard-hero-dot').nth(index);
+    await dot.click();
+    await expect(dot).toHaveAttribute('aria-current', 'true');
+    // The backdrop crossfade and the slide's entrance have finished (not the
+    // image's slow zoom, which never changes what is under the text).
+    await expect
+        .poll(() =>
+            page.evaluate(() =>
+                [
+                    document.querySelector('.hero__backdrop--active'),
+                    document.querySelector('.hero__content'),
+                ].every(
+                    (element) =>
+                        element &&
+                        element
+                            .getAnimations()
+                            .every(
+                                (animation) => animation.playState !== 'running'
+                            )
+                )
+            )
+        )
+        .toBe(true);
+    return page.getByTestId('dashboard-hero-slide');
+}
+
+/** Sum of non-input layout shifts while the hero runs through every slide
+ * on its own, at a shortened interval. */
+async function rotationLayoutShift(page: Page): Promise<number> {
+    const hero = page.getByTestId('dashboard-hero');
+    const dots = page.getByTestId('dashboard-hero-dot');
+    const count = await dots.count();
+    await page.mouse.move(1, 1);
+    await hero.evaluate((element) => {
+        (element as HTMLElement).style.setProperty(
+            '--hero-rotation-ms',
+            '600ms'
+        );
+        const shifts: number[] = [];
+        new PerformanceObserver((list) => {
+            for (const entry of list.getEntries() as (PerformanceEntry & {
+                value: number;
+                hadRecentInput: boolean;
+            })[]) {
+                if (!entry.hadRecentInput) {
+                    shifts.push(entry.value);
+                }
+            }
+        }).observe({ type: 'layout-shift' });
+        (window as unknown as { __heroShifts: number[] }).__heroShifts = shifts;
+    });
+    // Back to the first slide after one full cycle, then a quiet moment.
+    const first = await dots.evaluateAll((all) =>
+        all.findIndex((dot) => dot.getAttribute('aria-current') === 'true')
+    );
+    for (let step = 1; step <= count; step++) {
+        await expect(dots.nth((first + step) % count)).toHaveAttribute(
+            'aria-current',
+            'true',
+            { timeout: 5_000 }
+        );
+    }
+    await page.waitForTimeout(500);
+    return page.evaluate(() =>
+        (window as unknown as { __heroShifts: number[] }).__heroShifts.reduce(
+            (sum, value) => sum + value,
+            0
+        )
+    );
+}
+
+/** Adds what a TMDB-enriched slide shows: a rating chip and an overview. */
+async function enrichSlide(slide: Locator): Promise<void> {
+    await slide.evaluate((content, overview) => {
+        const chip = content.querySelector('.hero__pill');
+        if (chip) {
+            const rating = chip.cloneNode() as HTMLElement;
+            rating.classList.add('meta-chip--rating');
+            rating.textContent = '★ 7.4';
+            chip.before(rating);
+        }
+        // The overview takes the title's view encapsulation attribute, so the
+        // hero's `.hero__description` rule styles it.
+        const title = content.querySelector('.hero__title');
+        const scope = Array.from(title?.attributes ?? []).find((attribute) =>
+            attribute.name.startsWith('_ngcontent')
+        );
+        const actions = content.querySelector('.hero__actions');
+        if (scope && actions && !content.querySelector('.hero__description')) {
+            const description = document.createElement('p');
+            description.setAttribute(scope.name, '');
+            description.className = 'hero__description';
+            description.textContent = overview;
+            actions.before(description);
+        }
+    }, sampleOverview);
+    await expect(slide.locator('.hero__description')).toHaveCount(1);
+}
+
+/** Every piece of slide text a viewer reads, one element per colour. */
+function slideTexts(slide: Locator): Record<string, Locator> {
+    return {
+        eyebrow: slide.locator('.hero__eyebrow > span:not(.hero__eyebrow-sep)'),
+        title: slide.locator('.hero__title'),
+        pill: slide.locator('.hero__pill'),
+        programme: slide.locator('.hero__programme'),
+        description: slide.locator('.hero__description'),
+        button: slide.locator('.hero__button > span'),
+    };
+}
+
+test.describe('Dashboard hero legibility', () => {
+    test('keeps slide text at 4.5:1 over any artwork in both themes and widths', async ({
+        dataDir,
+        request,
+    }, testInfo) => {
+        test.setTimeout(240_000);
+        await resetMockServers(request, ['xtream']);
+        const live = await fetchXtreamLiveFixture(request, xtreamCredentials);
+        const vod = await fetchXtreamVodFixture(request, xtreamCredentials);
+        const series = await fetchXtreamSeriesFixture(
+            request,
+            xtreamCredentials
+        );
+        const app = await launchElectronApp(dataDir);
+        const page = app.mainWindow;
+        const results: string[] = [];
+
+        try {
+            await routeArtwork(page);
+            await page.setViewportSize({ width: widths.wide, height: 800 });
+            await addXtreamPortal(page);
+            await waitForXtreamWorkspaceReady(page);
+
+            // Live slide: a favourite channel with a programme on air.
+            await openWorkspaceSection(page, 'Live TV');
+            await clickCategoryByNameExact(page, live.categoryName);
+            await toggleFavoriteForChannel(page, getXtreamTitle(live.items[0]));
+            // Backdrop slide: favouriting from the detail page stores the
+            // movie's 16:9 backdrop.
+            await page
+                .getByRole('link', { name: 'Movies', exact: true })
+                .click();
+            await clickCategoryByNameExact(page, vod.categoryName);
+            await clickFirstGridListCard(page);
+            await addCurrentDetailToFavorites(page);
+            await goBackFromDetail(page);
+            // No-artwork slide: series images fail, poster and backdrop.
+            await page
+                .getByRole('link', { name: 'Series', exact: true })
+                .click();
+            await clickCategoryByNameExact(page, series.categoryName);
+            await clickFirstGridListCard(page);
+            await addCurrentDetailToFavorites(page);
+
+            await goToDashboard(page);
+            await expect(page.getByTestId('dashboard-hero')).toBeVisible({
+                timeout: 20_000,
+            });
+            // Poster-only slides come from the Xtream "recently added" list.
+            await expect
+                .poll(async () => [...new Set(await slideKinds(page))].sort(), {
+                    timeout: 20_000,
+                })
+                .toEqual(['backdrop', 'fallback', 'live', 'poster']);
+
+            // One stable page heading; the rotating slide title is an h2.
+            await expect(page.locator('h1')).toHaveCount(1);
+            await expect(page.getByTestId('dashboard-page-heading')).toHaveText(
+                'Dashboard'
+            );
+            await expect(
+                page
+                    .getByTestId('dashboard-hero-slide')
+                    .locator('h2.hero__title')
+            ).toHaveCount(1);
+
+            // An unattended rotation, counted like the launch journey's
+            // settled layout-shift counter (non-input shifts only). Slides of
+            // different heights still resize the hero by a few pixels and
+            // move the rails below (0.005 here, 0.013 before this change);
+            // a scrim or heading that reflowed the slide would add lines.
+            const shift = await rotationLayoutShift(page);
+            results.push(`rotation layout shift ${shift.toFixed(3)}`);
+            expect(shift).toBeLessThan(0.02);
+
+            await page.getByTestId('dashboard-hero-pause').click();
+            const kinds = await slideKinds(page);
+            for (const theme of ['light', 'dark'] as const) {
+                await applyTheme(page, theme);
+                for (const [layout, width] of Object.entries(widths)) {
+                    await page.setViewportSize({ width, height: 800 });
+                    // The narrow layout is the dashboard container's
+                    // ≤720px query, not the window width.
+                    const narrow = await page
+                        .locator('.hero__content')
+                        .evaluate(
+                            (content) =>
+                                getComputedStyle(content).maxWidth === 'none'
+                        );
+                    expect(narrow).toBe(layout === 'narrow');
+                    for (const [index, kind] of kinds.entries()) {
+                        const slide = await showSlide(page, index);
+                        await enrichSlide(slide);
+                        await page.mouse.move(1, 1);
+                        const name = `${theme}-${layout}-${kind}`;
+                        const shot = testInfo.outputPath(`hero-${name}.png`);
+                        await page
+                            .getByTestId('dashboard-hero')
+                            .screenshot({ path: shot });
+                        await testInfo.attach(name, {
+                            path: shot,
+                            contentType: 'image/png',
+                        });
+                        for (const [part, texts] of Object.entries(
+                            slideTexts(slide)
+                        )) {
+                            for (const text of await texts.all()) {
+                                const ratio = await measureBackdropTextContrast(
+                                    page,
+                                    text
+                                );
+                                results.push(
+                                    `${name} ${part} ${ratio.toFixed(2)}`
+                                );
+                                expect
+                                    .soft(ratio, `${name} ${part}`)
+                                    .toBeGreaterThanOrEqual(minimumContrast);
+                            }
+                        }
+                    }
+                }
+            }
+        } finally {
+            const report = testInfo.outputPath('contrast.txt');
+            writeFileSync(report, results.join('\n'));
+            await testInfo.attach('contrast', {
+                path: report,
+                contentType: 'text/plain',
+            });
+            await closeElectronApp(app);
+        }
+    });
+});
diff --git a/apps/electron-backend-e2e/src/theme-contrast.ts b/apps/electron-backend-e2e/src/theme-contrast.ts
index ab8ac2cf0..895698d31 100644
--- a/apps/electron-backend-e2e/src/theme-contrast.ts
+++ b/apps/electron-backend-e2e/src/theme-contrast.ts
@@ -198,3 +198,98 @@ export async function expectSkeletonContrast(
         ).toBeGreaterThanOrEqual(1.3);
     }
 }
+
+/** Contrast of an element's own text against whatever is painted behind it
+ * (images, gradient scrims, translucent chips), read back from the screen.
+ * The text is made transparent for the capture, so its `text-shadow` stays
+ * in the backdrop it is meant to support; its CSS colour (with alpha and
+ * ancestor opacity) is then composited over every pixel under its line
+ * boxes. Returns the worst ratio, so one dark patch of artwork under one
+ * letter fails it. */
+export async function measureBackdropTextContrast(
+    page: Page,
+    text: Locator
+): Promise<number> {
+    await expect(text).toBeVisible();
+    const probe = await text.evaluate((element) => {
+        const canvas = document.createElement('canvas');
+        canvas.width = canvas.height = 1;
+        const ctx = canvas.getContext('2d')!;
+        ctx.fillStyle = getComputedStyle(element).color;
+        ctx.fillRect(0, 0, 1, 1);
+        const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+        let alpha = a / 255;
+        for (
+            let node: Element | null = element;
+            node;
+            node = node.parentElement
+        ) {
+            alpha *= Number(getComputedStyle(node).opacity);
+        }
+        const range = document.createRange();
+        range.selectNodeContents(element);
+        const box = range.getBoundingClientRect();
+        const style = (element as HTMLElement).style;
+        const previous = style.getPropertyValue('color');
+        style.setProperty('color', 'transparent', 'important');
+        (element as HTMLElement).dataset['contrastPrevious'] = previous;
+        return {
+            color: [r, g, b, alpha],
+            // Whole pixels inside the line boxes, clear of glyph edges that
+            // spill past them.
+            clip: {
+                x: Math.ceil(box.left),
+                y: Math.ceil(box.top),
+                width: Math.max(1, Math.floor(box.width) - 1),
+                height: Math.max(1, Math.floor(box.height) - 1),
+            },
+        };
+    });
+    try {
+        const { data, info } = await sharp(
+            await page.screenshot({ clip: probe.clip })
+        )
+            .removeAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        const [fr, fg, fb, fa] = probe.color;
+        const luminance = (r: number, g: number, b: number) =>
+            [r, g, b]
+                .map((value) => {
+                    const s = value / 255;
+                    return s <= 0.04045
+                        ? s / 12.92
+                        : ((s + 0.055) / 1.055) ** 2.4;
+                })
+                .reduce(
+                    (sum, value, index) =>
+                        sum + value * [0.2126, 0.7152, 0.0722][index],
+                    0
+                );
+        let worst = Infinity;
+        for (let i = 0; i < data.length; i += info.channels) {
+            const [br, bg, bb] = [data[i], data[i + 1], data[i + 2]];
+            const front = luminance(
+                fr * fa + br * (1 - fa),
+                fg * fa + bg * (1 - fa),
+                fb * fa + bb * (1 - fa)
+            );
+            const back = luminance(br, bg, bb);
+            worst = Math.min(
+                worst,
+                (Math.max(front, back) + 0.05) / (Math.min(front, back) + 0.05)
+            );
+        }
+        return worst;
+    } finally {
+        await text.evaluate((element) => {
+            const style = (element as HTMLElement).style;
+            const previous = (element as HTMLElement).dataset[
+                'contrastPrevious'
+            ];
+            style.removeProperty('color');
+            if (previous) style.setProperty('color', previous);
+            delete (element as HTMLElement).dataset['contrastPrevious'];
+        });
+    }
+}
diff --git a/apps/web/src/m3-theme.scss b/apps/web/src/m3-theme.scss
index 439ccfd9e..f37d6d652 100644
--- a/apps/web/src/m3-theme.scss
+++ b/apps/web/src/m3-theme.scss
@@ -157,8 +157,9 @@ html {
     --app-cta-fg: #f5f6f8;
     --app-cta-hover-bg: #2a2f3a;
     --app-cta-meta-fg: rgba(245, 246, 248, 0.68);
-    // Star rating chip: amber on white needs a deeper tone than gold on dark.
-    --app-rating-color: #a16207;
+    // Star rating chip: a deep amber, since the chip's 12px text needs
+    // 4.5:1 over hero artwork under the light scrim (#a16207 measured 3.4:1).
+    --app-rating-color: #7a4a00;
 
     .dark-theme {
         @include mat.all-component-colors($dark-theme);
diff --git a/docs/architecture/workspace-dashboard.md b/docs/architecture/workspace-dashboard.md
index 692771f36..96caaf115 100644
--- a/docs/architecture/workspace-dashboard.md
+++ b/docs/architecture/workspace-dashboard.md
@@ -137,7 +137,33 @@ edges (no second, sharp copy); a live channel's logo sits on the right as key
 art over its own wash. Series titles drop their season marker
 (`splitSeasonSuffix`) — the `S1·E1` chip names the season. Chips are
 `app-meta-chip`; the primary is the details pages' light primary
-(`light-primary-button` from `libs/ui/styles`).
+(`light-primary-button` from `libs/ui/styles`). With no artwork at all the
+stage is a gradient in the title's hue (`--hero-hue`), light in the light
+theme and near-black in the dark one; a dark gradient under the light
+theme's page-coloured scrim read as a grey slab behind dark text.
+
+Legibility: slide text stays at 4.5:1 or more over any artwork. The side
+scrim holds 88% of the page colour up to the slide's right edge
+(`--hero-text-edge`: the inset plus `min(560px, 55%)`, the slide's own
+`max-width`) before it opens onto the art. In the narrow layout (`dashboard`
+container ≤ 720px) the slide spans the width, so a full-bleed scrim sits
+behind the text block (90%, fading in just above the eyebrow), the copy gets
+a scrim-coloured text shadow, and the slide enters without a fade so that
+scrim never flashes the art on a rotation. Body text is 85% of the heading
+colour; the rating chip uses `--app-rating-color`, set per theme in
+`m3-theme.scss`. Buttons end long labels in an ellipsis.
+`dashboard-hero-legibility.e2e.ts` replaces every image with a black-and-white
+checkerboard and measures each piece of slide text from the screen in both
+themes, at a wide and a narrow width, for a backdrop, a blurred-poster, a
+no-artwork and a live slide.
+
+Semantics: the page has one stable, visually hidden `h1` ("Dashboard",
+`dashboard-page-heading`); each slide title is an `h2`, like the rail titles.
+Slide changes are announced by one polite live region
+(`dashboard-hero-announcement`, position and title) that lives outside the
+re-created slide and is silent while the slides rotate on their own. A
+slide's progress bar is named after its title (a live slide: the programme)
+and a title's reads "N% watched". The dots are 24px targets (WCAG 2.5.8).
 
 Rotation is the active dot's CSS fill animation (8 s); its `animationend`
 advances. The fill animates `transform` only (a bar sliding in under the
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero-slides.presenter.ts b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero-slides.presenter.ts
index bbc15e4d0..c94f0f1f7 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero-slides.presenter.ts
+++ b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero-slides.presenter.ts
@@ -221,7 +221,6 @@ export class DashboardHeroSlidesPresenter {
             {
                 backdropUrl: item.backdrop_url || extras?.backdropUrl || null,
                 posterUrl: item.poster_url,
-                title: item.title,
             },
             this.failedImages()
         );
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.html b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.html
index 078bd04e7..cb0d80a23 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.html
+++ b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.html
@@ -26,14 +26,7 @@
                     [class.hero__backdrop--live]="slide.contentType === 'live'"
                     [style.--hero-hue]="slide.accentHue"
                 >
-                    <span
-                        class="hero__backdrop-fallback"
-                        [style.background]="
-                            slide.contentType === 'live'
-                                ? null
-                                : slide.fallbackBackdropBackground
-                        "
-                    ></span>
+                    <span class="hero__backdrop-fallback"></span>
                     @if (slide.backdropUrl; as backdropUrl) {
                         <img
                             class="hero__backdrop-image"
@@ -80,7 +73,6 @@
                                   count: slides().length,
                               }
                 "
-                [attr.aria-live]="canRotate() && !paused() ? 'off' : 'polite'"
             >
                 <p class="hero__eyebrow">
                     <span
@@ -92,7 +84,7 @@
                     <span>{{ slide.reasonLabelKey | translate }}</span>
                 </p>
 
-                <h1 class="hero__title">{{ slide.title }}</h1>
+                <h2 class="hero__title">{{ slide.title }}</h2>
 
                 <p class="hero__meta" data-test-id="dashboard-hero-badges">
                     @if (slide.episodeBadge) {
@@ -154,6 +146,13 @@
                         aria-valuemin="0"
                         aria-valuemax="100"
                         [attr.aria-valuenow]="slide.progress"
+                        [attr.aria-label]="slide.programmeTitle ?? slide.title"
+                        [attr.aria-valuetext]="
+                            slide.contentType === 'live'
+                                ? null
+                                : ('WORKSPACE.DASHBOARD.PERCENT_WATCHED'
+                                  | translate: { value: slide.progress })
+                        "
                     >
                         <i [style.--hero-progress]="slide.progress"></i>
                     </span>
@@ -196,6 +195,22 @@
                 </div>
             </div>
         }
+        <!-- Outside the @for: a live region has to be in the page before
+             its text changes, or the change is not announced. Silent while
+             the slides rotate on their own. -->
+        <p
+            class="visually-hidden"
+            data-test-id="dashboard-hero-announcement"
+            aria-atomic="true"
+            [attr.aria-live]="canRotate() && !paused() ? 'off' : 'polite'"
+        >
+            {{
+                'WORKSPACE.DASHBOARD.HERO_SLIDE_POSITION'
+                    | translate
+                        : { index: activeIndex() + 1, count: slides().length }
+            }}
+            {{ active.title }}
+        </p>
 
         @if (slides().length > 1) {
             <div class="hero__controls">
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.scss b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.scss
index d7a580fd7..07ce89e4e 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.scss
+++ b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.scss
@@ -24,13 +24,22 @@
         var(--dashboard-gutter, 28px) +
             max(0px, (100cqw - var(--dashboard-max-width, 1440px)) / 2)
     );
+    // The slide's widest extent, and its right edge measured from the
+    // hero's left edge: the scrim holds its text-safe opacity up to there.
+    --hero-text-width: min(560px, 55%);
+    --hero-text-edge: calc(var(--hero-inset) + var(--hero-text-width));
     --hero-scrim: var(--app-content-bg, #161a22);
     --hero-heading: var(--app-heading-color, #d8dce8);
     --hero-body: color-mix(
         in srgb,
-        var(--app-heading-color, #d8dce8) 72%,
+        var(--app-heading-color, #d8dce8) 85%,
         var(--hero-scrim)
     );
+    // Saturation and lightness of the no-artwork gradient. Light by
+    // default: a near-black gradient under the light theme's page-coloured
+    // scrim turned into a grey slab behind dark text.
+    --hero-fallback-from: 55% 90%;
+    --hero-fallback-to: 60% 78%;
     --hero-pill-bg: color-mix(
         in srgb,
         var(--app-on-surface, #e6e1e5) 12%,
@@ -61,6 +70,11 @@
     }
 }
 
+:host-context(.dark-theme) .hero {
+    --hero-fallback-from: 50% 15%;
+    --hero-fallback-to: 80% 5%;
+}
+
 // ── Backdrops ──────────────────────────────────────────────────────────────
 .hero__stage {
     position: absolute;
@@ -88,6 +102,15 @@
     height: 100%;
 }
 
+// No artwork at all: a gradient tinted by the title's hue (`--hero-hue`).
+.hero__backdrop-fallback {
+    background: linear-gradient(
+        135deg,
+        hsl(var(--hero-hue) var(--hero-fallback-from)) 0%,
+        hsl(calc(var(--hero-hue) + 60) var(--hero-fallback-to)) 100%
+    );
+}
+
 .hero__backdrop-image {
     display: block;
     object-fit: cover;
@@ -173,6 +196,9 @@
     }
 }
 
+// Text never sits on less than 88% of the page colour: the side gradient
+// holds that up to the slide's right edge and only then opens onto the art.
+// Fixed stops at 30% / 60% left the end of a full-width slide on ~45%.
 .hero__scrim {
     position: absolute;
     inset: 0;
@@ -180,8 +206,10 @@
         linear-gradient(
             90deg,
             color-mix(in srgb, var(--hero-scrim) 96%, transparent) 0%,
-            color-mix(in srgb, var(--hero-scrim) 85%, transparent) 30%,
-            color-mix(in srgb, var(--hero-scrim) 35%, transparent) 60%,
+            color-mix(in srgb, var(--hero-scrim) 88%, transparent)
+                var(--hero-text-edge),
+            color-mix(in srgb, var(--hero-scrim) 35%, transparent)
+                calc(var(--hero-text-edge) + 18%),
             transparent 100%
         ),
         linear-gradient(
@@ -205,7 +233,7 @@
     flex-direction: column;
     align-items: flex-start;
     gap: 12px;
-    max-width: min(560px, 55%);
+    max-width: var(--hero-text-width);
     animation: hero-content-in 420ms cubic-bezier(0.2, 0.7, 0.2, 1) both;
 }
 
@@ -220,6 +248,17 @@
     }
 }
 
+// The narrow layout's entrance: no fade, because the slide carries its own
+// scrim there and a fading scrim would flash the art on every rotation.
+@keyframes hero-content-rise {
+    from {
+        transform: translateY(8px);
+    }
+    to {
+        transform: none;
+    }
+}
+
 .hero__eyebrow {
     display: flex;
     align-items: center;
@@ -356,6 +395,10 @@
     padding: 0 18px 0 14px;
     box-sizing: border-box;
     border-radius: 10px;
+    // A long label (or translation) ends in an ellipsis instead of pushing
+    // the button past a narrow slide; the icon keeps its size.
+    max-width: 100%;
+    min-width: 0;
     font-size: 13px;
     font-weight: 600;
     line-height: 1;
@@ -366,7 +409,14 @@
         box-shadow 0.15s ease,
         transform 0.15s ease;
 
+    > span {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+
     mat-icon {
+        flex: 0 0 auto;
         width: 20px;
         height: 20px;
         font-size: 20px;
@@ -471,15 +521,16 @@
 .hero__dots {
     display: flex;
     align-items: center;
+    gap: 2px;
 }
 
-// 6px dots inside a 20px hit area; the active one stretches into a pill
-// whose fill runs for one rotation interval.
+// 6px dots inside a 24px hit area (WCAG 2.5.8 target size), 2px apart; the
+// active one stretches into a pill whose fill runs for one rotation interval.
 .hero__dot {
     display: grid;
     place-items: center;
-    width: 20px;
-    height: 20px;
+    width: 24px;
+    height: 24px;
     padding: 0;
     border: 0;
     background: transparent;
@@ -516,7 +567,7 @@
     }
 
     &--active {
-        width: 30px;
+        width: 32px;
 
         &::before {
             width: 18px;
@@ -527,8 +578,8 @@
 .hero__dot-fill {
     grid-area: 1 / 1;
     justify-self: start;
-    // Aligns with the 18px pill centred in the 30px button.
-    margin-left: 6px;
+    // Aligns with the 18px pill centred in the 32px button.
+    margin-left: 7px;
     width: 0;
     height: 6px;
     border-radius: 3px;
@@ -632,6 +683,29 @@
         // Clears the rotation controls, which move to the top here.
         padding: 64px 0 28px;
         max-width: none;
+        animation-name: hero-content-rise;
+        text-shadow: 0 1px 2px
+            color-mix(in srgb, var(--hero-scrim) 80%, transparent);
+    }
+
+    // The slide spans the whole width here, over the art: the full-bleed
+    // scrim behind the text block keeps it on at least 90% of the page
+    // colour, fading in just above the eyebrow.
+    .hero__content::before {
+        content: '';
+        position: absolute;
+        z-index: -1;
+        inset: 24px calc(-1 * var(--hero-inset)) 0;
+        background: linear-gradient(
+            180deg,
+            transparent,
+            color-mix(in srgb, var(--hero-scrim) 90%, transparent) 40px
+        );
+        pointer-events: none;
+    }
+
+    .hero__button {
+        text-shadow: none;
     }
 
     .hero__controls {
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.spec.ts b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.spec.ts
index 3e63eb74b..68000d5f4 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.spec.ts
+++ b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.component.spec.ts
@@ -27,8 +27,6 @@ const slide = (id: string, title: string): DashboardHeroSlide => ({
     progress: null,
     accentHue: 200,
     backdropSource: 'fallback',
-    fallbackBackdropBackground: 'none',
-    fallbackPosterBackground: 'none',
     hasBackdrop: false,
     primaryAction: {
         labelKey: 'WORKSPACE.DASHBOARD.HERO_CONTINUE',
@@ -46,7 +44,7 @@ describe('DashboardHeroComponent', () => {
 
     const host = () => fixture.nativeElement as HTMLElement;
     const activeTitle = () =>
-        host().querySelector('[data-test-id=dashboard-hero-slide] h1')
+        host().querySelector('[data-test-id=dashboard-hero-slide] h2')
             ?.textContent;
     const dots = () =>
         Array.from(
@@ -256,6 +254,78 @@ describe('DashboardHeroComponent', () => {
         ).toBe('/workspace/a');
     });
 
+    it('titles each slide with an h2 and leaves the h1 to the page', () => {
+        render();
+
+        expect(host().querySelector('h1')).toBeNull();
+        expect(activeTitle()).toBe('First');
+    });
+
+    it('announces slide changes through one live region that outlives the slides', () => {
+        // A live region inserted together with its text is not announced,
+        // so it must not belong to the slide that the @for re-creates.
+        render();
+        const announcement = () =>
+            host().querySelector<HTMLElement>(
+                '[data-test-id=dashboard-hero-announcement]'
+            );
+        const region = announcement();
+        expect(region).not.toBeNull();
+        expect(
+            region?.closest('[data-test-id=dashboard-hero-slide]')
+        ).toBeNull();
+        expect(
+            host()
+                .querySelector('[data-test-id=dashboard-hero-slide]')
+                ?.hasAttribute('aria-live')
+        ).toBe(false);
+        // Rotating on its own: silent.
+        expect(region?.getAttribute('aria-live')).toBe('off');
+        expect(region?.textContent).toContain('First');
+
+        const section = host().querySelector(
+            '[data-test-id=dashboard-hero]'
+        ) as HTMLElement;
+        section.dispatchEvent(new Event('focusin'));
+        dots()[1].click();
+        fixture.detectChanges();
+
+        expect(announcement()).toBe(region);
+        expect(region?.getAttribute('aria-live')).toBe('polite');
+        expect(region?.getAttribute('aria-atomic')).toBe('true');
+        expect(region?.textContent).toContain('Second');
+    });
+
+    it('names the progress bar after what is progressing', () => {
+        slides.set([
+            { ...slide('a', 'Movie'), progress: 42 },
+            {
+                ...slide('b', 'Channel'),
+                contentType: 'live',
+                programmeTitle: 'Evening programme',
+                progress: 10,
+            },
+        ]);
+        render();
+        const bar = () =>
+            host().querySelector(
+                '[data-test-id=dashboard-hero-slide] [role=progressbar]'
+            );
+
+        expect(bar()?.getAttribute('aria-label')).toBe('Movie');
+        // The translate pipe echoes the key in this test bed.
+        expect(bar()?.getAttribute('aria-valuetext')).toBe(
+            'WORKSPACE.DASHBOARD.PERCENT_WATCHED'
+        );
+
+        dots()[1].click();
+        fixture.detectChanges();
+        expect(bar()?.getAttribute('aria-label')).toBe('Evening programme');
+        // Elapsed share of a live programme: the plain percentage.
+        expect(bar()?.hasAttribute('aria-valuetext')).toBe(false);
+        expect(bar()?.getAttribute('aria-valuenow')).toBe('10');
+    });
+
     it('positions the progress fill through a custom property, never its width', () => {
         // Animating width re-lays out the page on every live-EPG tick; the
         // stylesheet slides the fill with a transform driven by this property.
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.utils.ts b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.utils.ts
index 6f210ac20..4171992bb 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.utils.ts
+++ b/libs/workspace/dashboard/feature/src/lib/rails/dashboard-hero.utils.ts
@@ -40,7 +40,7 @@ export interface DashboardHeroSlide extends DashboardHeroArtwork {
     readonly description: string | null;
     /** 0-100: watched share, or elapsed share of the live programme */
     readonly progress: number | null;
-    /** Title-derived hue for the live slide's glow (0-359) */
+    /** Title-derived hue (0-359): the live glow and the no-artwork gradient */
     readonly accentHue: number;
     readonly primaryAction: DashboardHeroAction;
     readonly secondaryAction: DashboardHeroAction | null;
@@ -51,14 +51,11 @@ export type DashboardHeroBackdropSource = 'backdrop' | 'poster' | 'fallback';
 export interface DashboardHeroArtworkInput {
     readonly backdropUrl?: string | null;
     readonly posterUrl?: string | null;
-    readonly title: string;
 }
 
 export interface DashboardHeroArtwork {
     readonly backdropUrl?: string;
     readonly backdropSource: DashboardHeroBackdropSource;
-    readonly fallbackBackdropBackground: string;
-    readonly fallbackPosterBackground: string;
     readonly hasBackdrop: boolean;
     readonly posterUrl?: string;
 }
@@ -85,49 +82,17 @@ export function resolveDashboardHeroArtwork(
     return {
         backdropUrl,
         backdropSource,
-        fallbackBackdropBackground: buildFallbackBackground(
-            item.title,
-            50,
-            15,
-            80,
-            5,
-            60
-        ),
-        fallbackPosterBackground: buildFallbackBackground(
-            item.title,
-            40,
-            25,
-            50,
-            15,
-            40
-        ),
         hasBackdrop: backdropSource === 'backdrop',
         posterUrl,
     };
 }
 
-function buildFallbackBackground(
-    title: string,
-    saturationA: number,
-    lightnessA: number,
-    saturationB: number,
-    lightnessB: number,
-    hueOffset: number
-): string {
-    const hue = calculateHue(title || 'placeholder');
-    const h2 = (hue + hueOffset) % 360;
-    return `linear-gradient(135deg, hsl(${hue}, ${saturationA}%, ${lightnessA}%) 0%, hsl(${h2}, ${saturationB}%, ${lightnessB}%) 100%)`;
-}
-
 /** Stable hue for a title, shared by every generated fallback surface. */
 export function dashboardHeroHue(text: string): number {
-    return calculateHue(text || 'placeholder');
-}
-
-function calculateHue(text: string): number {
+    const key = text || 'placeholder';
     let hash = 0;
-    for (let i = 0; i < text.length; i++) {
-        hash = text.charCodeAt(i) + ((hash << 5) - hash);
+    for (let i = 0; i < key.length; i++) {
+        hash = key.charCodeAt(i) + ((hash << 5) - hash);
         hash = hash & hash;
     }
     return Math.abs(hash) % 360;
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.html b/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.html
index a842cb511..29406c54e 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.html
+++ b/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.html
@@ -3,6 +3,11 @@
     [class.rails-page--empty]="ready() && !hasPlaylists()"
     data-test-id="dashboard-page"
 >
+    <!-- The page's one stable h1: the rail already names the page, and the
+         hero's rotating title is only the current slide (an h2). -->
+    <h1 class="visually-hidden" data-test-id="dashboard-page-heading">
+        {{ 'WORKSPACE.SHELL.RAIL_DASHBOARD' | translate }}
+    </h1>
     @if (data.playlistsLoaded() && !hasPlaylists()) {
         <app-empty-state
             [type]="'welcome-dashboard'"
diff --git a/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.spec.ts b/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.spec.ts
index 6d16a412c..7d3a2fc1f 100644
--- a/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.spec.ts
+++ b/libs/workspace/dashboard/feature/src/lib/rails/workspace-dashboard-rails.component.spec.ts
@@ -146,7 +146,6 @@ describe('buildDashboardContinueWatchingActions', () => {
 
 describe('resolveDashboardHeroArtwork', () => {
     const item = {
-        title: 'Broken Hero',
         posterUrl: 'https://images.example.test/poster.jpg',
         backdropUrl: 'https://images.example.test/backdrop.jpg',
     };
@@ -173,7 +172,8 @@ describe('resolveDashboardHeroArtwork', () => {
         });
     });
 
-    it('uses generated fallback artwork when backdrop and poster both fail', () => {
+    // The stylesheet paints the no-artwork gradient from the slide's hue.
+    it('reports no artwork when backdrop and poster both fail', () => {
         const artwork = resolveDashboardHeroArtwork(item, {
             [item.backdropUrl]: true,
             [item.posterUrl]: true,
@@ -185,8 +185,6 @@ describe('resolveDashboardHeroArtwork', () => {
             posterUrl: undefined,
             backdropUrl: undefined,
         });
-        expect(artwork.fallbackBackdropBackground).toContain('linear-gradient');
-        expect(artwork.fallbackPosterBackground).toContain('linear-gradient');
     });
 });
 

From 2dfdd65f533dc5c243a39482ab7005ac3844f75a Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Sun, 4 Oct 2026 16:52:53 +0200
Subject: [PATCH 03/20] refactor(details): give the detail-page files real
 max-lines headroom (#1813)

* refactor(xtream): split the series details page into focused services

serial-details.component.ts sat at the 400-line max-lines limit and its
playback service and spec were close behind. Move cohesive concerns out
without changing behavior:

- route params, the provider-only flag and the (re)load of the addressed
  series go to SerialDetailsRouteService; the component still registers
  the effect, so effect order is unchanged
- season descriptions, posters and the TMDB season enrichment go to
  SerialDetailsSeasonsService
- actor, Similar and Discover navigation go to injectXtreamDetailNavigation,
  shared with the movie page
- the watched toggles and the episode playback payload leave
  SerialDetailsPlaybackService for SerialDetailsWatchToggles and
  buildSerialEpisodePlayback
- the spec's TestBed moves to a harness and the watched-toggle cases to
  serial-details.season-watch.spec.ts

Counted lines: component 400 -> 318, playback service 388 -> 342,
component spec 1196 -> 674.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(xtream): move VOD route selection and position state out of the page

vod-details-route.component.ts grew from 618 to 741 counted lines and
vod-details-playback.service.ts reached 395. Extract without changing
behavior:

- the route-derived read model (selected movie, category, catalog item,
  fallback view, multi-source identity, session and content keys) goes to
  VodDetailsSelectionService; the component keeps the same member names
- trailer state and the Similar-rail click move into the hero presenter,
  the cancel-download prompt and the progress-ring geometry into the
  downloads service, navigation into injectXtreamDetailNavigation
- stored positions (last seen, route row, guarded load) become
  VodDetailsPositionState and the external-launch bookkeeping becomes
  VodExternalLaunchClaim
- drop the unused MatTooltip import (NG8113) and eight unused imports

Counted lines: route component 741 -> 492, playback service 395 -> 344.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(stalker): extract series-view positions and watched toggles

stalker-series-view.component.ts grew from 1601 to 1813 counted lines and
its spec reached 1198 of 1200. Move code out verbatim:

- saved positions, their reconcile and the persist/clear writes go to the
  component-provided StalkerSeriesPositionsService; the ordering of reads
  and writes goes to StalkerSeriesPositionQueue
- episode, season and series watched toggles go to
  StalkerSeriesWatchToggleService, the batch core to
  runStalkerWatchToggleBatch
- the lazy VOD season loads go to StalkerVodSeasonEpisodeLoader

Every effect stays registered in the component constructor in its original
order; template bindings and public member names are unchanged.

The spec setup moves to a shared harness and the spillover-prefetch and
TMDB season cases to their own specs; the 184 cases of the directory are
unchanged.

Counted lines: component 1813 -> 1136, component spec 1198 -> 670.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(stalker): extract catalog-detail position and search paging

- stalker-catalog-detail.component.ts (397): the stored VOD position and
  its runtime updates become StalkerCatalogVodPosition, the Play/Resume
  start becomes startStalkerCatalogVodPlayback
- stalker-search.component.ts (776, baselined): the paging resource, the
  accumulated results and the parental-lock bookkeeping become
  StalkerSearchPagingController, with pure helpers in
  stalker-search-results.util.ts. The spec reaches the moved members
  through component.paging; its cases and assertions are unchanged.

Counted lines: catalog detail 397 -> 317, search 776 -> 482.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* refactor(ui): give season-container and vod-details real line headroom

- season-container.component.ts (396): season auto-selection and the
  seasonSelected emission move to createSeasonAutoSelectState, called at
  the same place in the constructor so effect order is unchanged; the
  episode subline becomes buildEpisodeSubline
- vod-details.component.ts (393): the cross-portal Similar loader, the
  provider-only download state and the actor/Similar route helpers move to
  sibling modules

Inputs, outputs, selectors and public members are unchanged.

Counted lines: season container 396 -> 341, vod details 393 -> 337.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* test(web-e2e): move Stalker portal helpers into fixtures

stalker.e2e.ts was at 1196 of 1200 counted lines. Move the mock endpoints,
scenario MACs and page helpers to stalker-portal.fixture.ts and the
embedded-series steps three tests repeated to
stalker-embedded-series.fixture.ts. Every test stays in stalker.e2e.ts in
the same order, with the same serial mode and OWNED_MACS reset.

Counted lines: 1196 -> 981.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs: follow the detail-page extractions

Name the Stalker watched-toggle and position services that now own the
batch and reconcile code, point AUTH_REJECTED_MAC and the scenario MACs at
stalker-portal.fixture.ts, and drop two stale statements about components
sitting at the max-lines cap.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(xtream): note why the seasons service is injected last

Its TMDB enrichment effect keeps the position it had as the first effect
of the component constructor only while it is created after the other
services' effects.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/stalker-embedded-series.fixture.ts    | 104 ++
 apps/web-e2e/src/stalker-portal.fixture.ts    | 238 +++++
 apps/web-e2e/src/stalker.e2e.ts               | 366 +------
 docs/architecture/embedded-inline-playback.md |  13 +-
 docs/architecture/stalker-mock-server.md      |   3 +-
 docs/architecture/stalker-portal.md           |   3 +-
 docs/architecture/tmdb-roadmap.md             |   2 +-
 .../stalker-catalog-detail.component.ts       | 161 +--
 .../stalker-catalog-vod-playback.ts           |  84 ++
 .../stalker-catalog-vod-position.ts           | 110 +++
 .../stalker-search-paging.controller.ts       | 391 ++++++++
 .../stalker-search-results.util.ts            | 138 +++
 .../stalker-search.component.spec.ts          | 101 +-
 .../stalker-search.component.ts               | 450 +--------
 .../stalker-series-view/stalker-series-id.ts  |  12 +
 .../stalker-series-position-queue.ts          | 187 ++++
 .../stalker-series-positions.service.ts       | 331 +++++++
 .../stalker-series-view.component.spec.ts     | 648 +-----------
 .../stalker-series-view.component.ts          | 934 ++----------------
 ...ker-series-view.spillover-prefetch.spec.ts | 281 ++++++
 .../stalker-series-view.test-harness.ts       | 273 +++++
 .../stalker-series-view.tmdb-season.spec.ts   | 192 ++++
 .../stalker-series-watch-batch.ts             | 113 +++
 .../stalker-series-watch-toggle.service.ts    | 323 ++++++
 .../stalker-vod-season-episode-loader.ts      | 125 +++
 .../serial-details-playback.service.ts        |  97 +-
 .../serial-details-route.service.ts           |  75 ++
 .../serial-details-seasons.service.ts         |  75 ++
 .../serial-details-watch-toggles.ts           | 104 ++
 .../serial-details.component.spec.ts          | 608 +-----------
 .../serial-details.component.ts               | 163 +--
 .../serial-details/serial-details.harness.ts  | 314 ++++++
 .../serial-details.season-watch.spec.ts       | 267 +++++
 .../serial-details.test-stubs.ts              |  70 ++
 .../serial-details/serial-episode-playback.ts |  58 ++
 .../vod-details-downloads.service.ts          |  38 +
 .../vod-details-external-launch.ts            |  48 +-
 .../vod-details/vod-details-hero.presenter.ts |  62 +-
 .../vod-details-playback.service.ts           | 162 +--
 .../vod-details/vod-details-position-state.ts | 121 +++
 .../vod-details-route.component.ts            | 358 +------
 .../vod-details-selection.service.ts          | 213 ++++
 .../src/lib/xtream-detail-navigation.spec.ts  | 114 +++
 .../src/lib/xtream-detail-navigation.ts       |  73 ++
 .../season-container/episode-subline.util.ts  |  37 +
 .../season-auto-select.state.ts               | 136 +++
 .../season-container.component.ts             | 140 +--
 .../vod-details-navigation.util.ts            |  43 +
 .../lib/vod-details/vod-details.component.ts  | 111 +--
 .../vod-details/vod-download-state.util.ts    |  55 ++
 .../vod-similar-in-portals.state.ts           |  51 +
 51 files changed, 5326 insertions(+), 3850 deletions(-)
 create mode 100644 apps/web-e2e/src/stalker-embedded-series.fixture.ts
 create mode 100644 apps/web-e2e/src/stalker-portal.fixture.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-playback.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-position.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-paging.controller.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-results.util.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-id.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-position-queue.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-positions.service.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.spillover-prefetch.spec.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.test-harness.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.tmdb-season.spec.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-batch.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-toggle.service.ts
 create mode 100644 libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-vod-season-episode-loader.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details-route.service.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details-seasons.service.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details-watch-toggles.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details.harness.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details.season-watch.spec.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-details.test-stubs.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/serial-details/serial-episode-playback.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/vod-details/vod-details-position-state.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/vod-details/vod-details-selection.service.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/xtream-detail-navigation.spec.ts
 create mode 100644 libs/portal/xtream/feature/src/lib/xtream-detail-navigation.ts
 create mode 100644 libs/ui/components/src/lib/season-container/episode-subline.util.ts
 create mode 100644 libs/ui/components/src/lib/season-container/season-auto-select.state.ts
 create mode 100644 libs/ui/playback/src/lib/vod-details/vod-details-navigation.util.ts
 create mode 100644 libs/ui/playback/src/lib/vod-details/vod-similar-in-portals.state.ts

diff --git a/apps/web-e2e/src/stalker-embedded-series.fixture.ts b/apps/web-e2e/src/stalker-embedded-series.fixture.ts
new file mode 100644
index 000000000..67096aef6
--- /dev/null
+++ b/apps/web-e2e/src/stalker-embedded-series.fixture.ts
@@ -0,0 +1,104 @@
+import type { APIRequestContext, Locator, Page } from '@playwright/test';
+import { expect } from './fixtures';
+import {
+    BACKEND_PROXY,
+    EMBEDDED_SERIES_MAC,
+    MOCK_SERVER,
+} from './stalker-portal.fixture';
+
+/** A VOD row of the embedded-series scenario carrying a `series[]` array. */
+interface EmbeddedSeriesItem {
+    name: string;
+    series: unknown[];
+}
+
+/**
+ * Finds a VOD item carrying an embedded series[] array in the mock catalog
+ * and reports how many episodes it currently has.
+ */
+export async function findEmbeddedSeriesItem(
+    request: APIRequestContext
+): Promise<{ embeddedItem: EmbeddedSeriesItem; episodeCount: number }> {
+    const listResponse = await request.get(
+        `${MOCK_SERVER}/stalker?action=get_ordered_list&type=vod&category=2001&p=1&macAddress=${EMBEDDED_SERIES_MAC}&JsHttpRequest=1-xml`
+    );
+    const listBody = await listResponse.json();
+    const embeddedItem = listBody.payload.js.data.find(
+        (item: { series?: unknown[] }) =>
+            Array.isArray(item.series) && item.series.length > 0
+    );
+    expect(embeddedItem).toBeDefined();
+    const episodeCount: number = embeddedItem.series.length;
+
+    return { embeddedItem, episodeCount };
+}
+
+/**
+ * Opens the embedded-series item from its category (the first row is "All")
+ * and waits until the series detail lists its last episode. Returns the
+ * item's card in the category grid.
+ */
+export async function openEmbeddedSeriesItem(
+    page: Page,
+    itemName: string,
+    episodeCount: number
+): Promise<Locator> {
+    const categories = page.locator('.category-item');
+    await expect(categories.first()).toBeVisible({ timeout: 10_000 });
+    await categories.nth(1).click();
+    const card = page.getByText(itemName).first();
+    await expect(card).toBeVisible({ timeout: 10_000 });
+    await card.click();
+
+    await expect(
+        page.getByRole('heading', {
+            name: `${episodeCount}. Episode ${episodeCount}`,
+            exact: true,
+        })
+    ).toBeVisible({ timeout: 10_000 });
+
+    return card;
+}
+
+/**
+ * From now on the portal has "released" one more episode: extend series[] in
+ * every search response (the background snapshot refresh re-fetches the item
+ * via a title search).
+ */
+export async function releaseExtraEpisodeInSearchResponses(
+    page: Page
+): Promise<void> {
+    await page.route('**/localhost:3000/stalker**', async (route) => {
+        const originalUrl = new URL(route.request().url());
+        if (!originalUrl.searchParams.get('search')) {
+            await route.fallback();
+            return;
+        }
+
+        const mockUrl = new URL(BACKEND_PROXY);
+        const targetId = originalUrl.searchParams.get('targetId');
+        const providerUrl = targetId
+            ? Buffer.from(targetId, 'base64url').toString()
+            : originalUrl.searchParams.get('url');
+        if (providerUrl) {
+            mockUrl.searchParams.set('url', providerUrl);
+        }
+        originalUrl.searchParams.forEach((value, key) => {
+            if (key === 'targetId') {
+                return;
+            }
+            mockUrl.searchParams.set(key, value);
+        });
+
+        const response = await route.fetch({ url: mockUrl.toString() });
+        const body = await response.json();
+        const rows: { series?: string[] }[] =
+            body?.payload?.js?.data ?? body?.js?.data ?? [];
+        for (const row of rows) {
+            if (Array.isArray(row.series) && row.series.length > 0) {
+                row.series = [...row.series, String(row.series.length + 1)];
+            }
+        }
+        await route.fulfill({ response, body: JSON.stringify(body) });
+    });
+}
diff --git a/apps/web-e2e/src/stalker-portal.fixture.ts b/apps/web-e2e/src/stalker-portal.fixture.ts
new file mode 100644
index 000000000..08d0f0985
--- /dev/null
+++ b/apps/web-e2e/src/stalker-portal.fixture.ts
@@ -0,0 +1,238 @@
+import type { Page } from '@playwright/test';
+import { setInputValue } from './e2e-helpers';
+import { expect } from './fixtures';
+import {
+    getRegisteredProviderUrl,
+    interceptProviderTargetRegistration,
+} from './provider-target-route';
+
+/**
+ * Mock-portal endpoints, scenario MACs and page helpers of `stalker.e2e.ts`.
+ *
+ * The scenario MACs declared here belong to that spec alone: it lists them in
+ * its `OWNED_MACS` and resets them before every test, so a sibling spec that
+ * reused one would have its mock state cleared mid-run. See the isolation
+ * notes at the top of `stalker.e2e.ts`.
+ */
+
+const MOCK_PORT = process.env['MOCK_PORT'] ?? '3210';
+export const MOCK_SERVER = `http://localhost:${MOCK_PORT}`;
+const PORTAL_URL = `${MOCK_SERVER}/portal.php`;
+/**
+ * Canonical Ministra path. `PORTAL_URL` above is classified by the app as a
+ * "simple" portal (no handshake, no token, no watchdog); this shape is the
+ * authenticated branch, which the mock guards like the real middleware.
+ */
+export const FULL_PORTAL_URL = `${MOCK_SERVER}/stalker_portal/server/load.php`;
+export const BACKEND_PROXY = `${MOCK_SERVER}/stalker`;
+
+/** Default scenario MAC — balanced catalog, 8 categories, 40 items */
+export const DEFAULT_MAC = '00:1A:79:00:00:01';
+
+/** Minimal scenario MAC — 2 categories, 5 items (edge case testing) */
+export const MINIMAL_MAC = '00:1A:79:00:00:03';
+
+/** Embedded-series MAC — 50% of VOD items carry an embedded series[] array */
+export const EMBEDDED_SERIES_MAC = '00:1A:79:00:00:05';
+
+/** Legacy pagination MAC — portal without get_all_channels support */
+export const LEGACY_PAGINATION_MAC = '00:1A:79:00:00:06';
+
+/**
+ * Static-cmd MAC — ITV rows carrying a directly playable `cmd` with
+ * `use_http_tmp_link` and `use_load_balancing` both `'0'`, i.e. a portal that
+ * expects no `create_link` call at all.
+ */
+export const STATIC_CMD_MAC = '00:1A:79:00:00:0A';
+
+/**
+ * The full-portal authentication tests assert state transitions within one
+ * portal session, so a reset from a concurrent browser project or repeat
+ * worker would invalidate the assertion itself. Giving every concurrent
+ * worker slot its own MAC range preserves browser parallelism and also keeps
+ * `--repeat-each` runs isolated.
+ */
+export interface StatefulAuthMacs {
+    authenticatedFlow: string;
+    loginRequired: string;
+    tokenReuse: string;
+    deviceConflict: string;
+    reauthentication: string;
+}
+
+export function getStatefulAuthMacs({
+    parallelIndex,
+}: {
+    parallelIndex: number;
+}): StatefulAuthMacs {
+    if (
+        !Number.isSafeInteger(parallelIndex) ||
+        parallelIndex < 0 ||
+        parallelIndex > 255
+    ) {
+        throw new Error(
+            `Unsupported Playwright parallel index: ${parallelIndex}`
+        );
+    }
+
+    const workerOctet = parallelIndex
+        .toString(16)
+        .padStart(2, '0')
+        .toUpperCase();
+    const workerPrefix = `00:1A:79:AE:${workerOctet}`;
+
+    return {
+        authenticatedFlow: `${workerPrefix}:01`,
+        loginRequired: `${workerPrefix}:02`,
+        tokenReuse: `${workerPrefix}:03`,
+        deviceConflict: `${workerPrefix}:04`,
+        reauthentication: `${workerPrefix}:05`,
+    };
+}
+
+/**
+ * Deliberately NOT an Infomir MAC: the strict endpoint rejects get_profile for
+ * it, so no token is ever adopted and content requests fail permanently.
+ */
+export const AUTH_REJECTED_MAC = 'AA:BB:CC:DD:EE:01';
+
+/**
+ * Intercept calls to the Angular dev backend (/stalker proxy) and redirect
+ * them to the mock server. This avoids needing a real backend or changing
+ * any app environment configuration.
+ */
+export async function interceptStalkerRequests(page: Page): Promise<void> {
+    const providerTargets = await interceptProviderTargetRegistration(page);
+
+    await page.route('**/localhost:3000/stalker**', async (route) => {
+        const originalUrl = new URL(route.request().url());
+        const mockUrl = new URL(BACKEND_PROXY);
+        const providerUrl = getRegisteredProviderUrl(
+            originalUrl,
+            providerTargets
+        );
+
+        if (providerUrl) {
+            mockUrl.searchParams.set('url', providerUrl);
+        }
+
+        originalUrl.searchParams.forEach((value, key) => {
+            if (key === 'targetId') {
+                return;
+            }
+
+            mockUrl.searchParams.set(key, value);
+        });
+        await route.continue({ url: mockUrl.toString() });
+    });
+}
+
+/**
+ * Add a Stalker portal via the UI:
+ * 1. Click the "add playlist" button to open the unified dialog
+ * 2. Select "Stalker" toggle
+ * 3. Fill in the form and submit
+ */
+export async function addStalkerPortal(
+    page: Page,
+    options: { name?: string; mac?: string } = {}
+): Promise<void> {
+    const { name = 'Mock Stalker Portal', mac = DEFAULT_MAC } = options;
+
+    await page.getByRole('button', { name: 'Add playlist' }).click();
+    const dialog = page.locator('mat-dialog-container');
+    await expect(dialog).toBeVisible();
+    // v0.22 redesign: tabs were replaced with a flat 5-card radio picker.
+    await dialog.getByRole('radio', { name: /Stalker portal/i }).click();
+
+    await setInputValue(dialog.locator('input#title'), name);
+    await setInputValue(dialog.locator('input#portalUrl'), PORTAL_URL);
+    await setInputValue(dialog.locator('input#macAddress'), mac);
+
+    const addButton = dialog.getByRole('button', {
+        name: 'Add playlist',
+        exact: true,
+    });
+    await expect(addButton).toBeEnabled({ timeout: 10_000 });
+    await addButton.click();
+    await expect(dialog).toBeHidden();
+    await page.waitForURL(/stalker.*vod/);
+}
+
+/**
+ * Add a Stalker portal through the canonical Ministra URL, which the app
+ * imports as a FULL portal: handshake, Bearer token and watchdog.
+ */
+export async function addFullStalkerPortal(
+    page: Page,
+    options: {
+        name?: string;
+        mac: string;
+        expectContent?: boolean;
+        username?: string;
+        password?: string;
+    }
+): Promise<void> {
+    const {
+        name = 'Full Stalker Portal',
+        mac,
+        expectContent = true,
+        username,
+        password,
+    } = options;
+
+    await page.getByRole('button', { name: 'Add playlist' }).click();
+    const dialog = page.locator('mat-dialog-container');
+    await expect(dialog).toBeVisible();
+    await dialog.getByRole('radio', { name: /Stalker portal/i }).click();
+
+    await setInputValue(dialog.locator('input#title'), name);
+    await setInputValue(dialog.locator('input#portalUrl'), FULL_PORTAL_URL);
+    await setInputValue(dialog.locator('input#macAddress'), mac);
+    if (username !== undefined) {
+        await setInputValue(dialog.locator('input#username'), username);
+    }
+    if (password !== undefined) {
+        await setInputValue(dialog.locator('input#password'), password);
+    }
+
+    const addButton = dialog.getByRole('button', {
+        name: 'Add playlist',
+        exact: true,
+    });
+    await expect(addButton).toBeEnabled({ timeout: 10_000 });
+    await addButton.click();
+    await expect(dialog).toBeHidden();
+
+    if (expectContent) {
+        await page.waitForURL(/stalker.*vod/, { timeout: 30_000 });
+    }
+}
+
+export const CONTENT_ACTIONS = [
+    'get_categories',
+    'get_genres',
+    'get_ordered_list',
+    'get_all_channels',
+];
+
+/** Every portal request in order, with the token it carried. */
+export function recordPortalRequests(
+    page: Page
+): Array<{ action: string; token: string | null }> {
+    const requests: Array<{ action: string; token: string | null }> = [];
+
+    page.on('request', (request) => {
+        const url = new URL(request.url());
+        if (!url.pathname.endsWith('/stalker')) {
+            return;
+        }
+        const action = url.searchParams.get('action');
+        if (!action) {
+            return;
+        }
+        requests.push({ action, token: url.searchParams.get('token') });
+    });
+
+    return requests;
+}
diff --git a/apps/web-e2e/src/stalker.e2e.ts b/apps/web-e2e/src/stalker.e2e.ts
index 99bd00708..051acc8af 100644
--- a/apps/web-e2e/src/stalker.e2e.ts
+++ b/apps/web-e2e/src/stalker.e2e.ts
@@ -1,4 +1,4 @@
-import { type APIRequestContext, type Page } from '@playwright/test';
+import { type APIRequestContext } from '@playwright/test';
 import {
     closeSeriesMenu,
     expectSeriesSurfacesInBothThemes,
@@ -10,14 +10,33 @@ import {
     verifyStalkerPlaybackCategoryReturn,
     verifyUncachedStalkerSearch,
 } from './stalker-category-search.fixture';
+import {
+    findEmbeddedSeriesItem,
+    openEmbeddedSeriesItem,
+    releaseExtraEpisodeInSearchResponses,
+} from './stalker-embedded-series.fixture';
 import { verifyStalkerSeasonMarkers } from './stalker-season-markers.fixture';
 import { verifyStalkerOpenInPlaylist } from './stalker-open-in-playlist.fixture';
 import { playFirstItvChannel } from './stalker-itv-playback.fixture';
-import { expect, test } from './fixtures';
 import {
-    getRegisteredProviderUrl,
-    interceptProviderTargetRegistration,
-} from './provider-target-route';
+    AUTH_REJECTED_MAC,
+    BACKEND_PROXY,
+    CONTENT_ACTIONS,
+    DEFAULT_MAC,
+    EMBEDDED_SERIES_MAC,
+    FULL_PORTAL_URL,
+    LEGACY_PAGINATION_MAC,
+    MINIMAL_MAC,
+    MOCK_SERVER,
+    STATIC_CMD_MAC,
+    type StatefulAuthMacs,
+    addFullStalkerPortal,
+    addStalkerPortal,
+    getStatefulAuthMacs,
+    interceptStalkerRequests,
+    recordPortalRequests,
+} from './stalker-portal.fixture';
+import { expect, test } from './fixtures';
 
 /**
  * Stalker Portal E2E Tests
@@ -58,121 +77,10 @@ import {
 
 test.describe.configure({ mode: 'serial' });
 
-const MOCK_PORT = process.env['MOCK_PORT'] ?? '3210';
-const MOCK_SERVER = `http://localhost:${MOCK_PORT}`;
-const PORTAL_URL = `${MOCK_SERVER}/portal.php`;
-/**
- * Canonical Ministra path. `PORTAL_URL` above is classified by the app as a
- * "simple" portal (no handshake, no token, no watchdog); this shape is the
- * authenticated branch, which the mock guards like the real middleware.
- */
-const FULL_PORTAL_URL = `${MOCK_SERVER}/stalker_portal/server/load.php`;
-const BACKEND_PROXY = `${MOCK_SERVER}/stalker`;
-
-/** Default scenario MAC — balanced catalog, 8 categories, 40 items */
-const DEFAULT_MAC = '00:1A:79:00:00:01';
-
-/** Minimal scenario MAC — 2 categories, 5 items (edge case testing) */
-const MINIMAL_MAC = '00:1A:79:00:00:03';
-
-/** Embedded-series MAC — 50% of VOD items carry an embedded series[] array */
-const EMBEDDED_SERIES_MAC = '00:1A:79:00:00:05';
-
-/** Legacy pagination MAC — portal without get_all_channels support */
-const LEGACY_PAGINATION_MAC = '00:1A:79:00:00:06';
-
-/**
- * Static-cmd MAC — ITV rows carrying a directly playable `cmd` with
- * `use_http_tmp_link` and `use_load_balancing` both `'0'`, i.e. a portal that
- * expects no `create_link` call at all.
- */
-const STATIC_CMD_MAC = '00:1A:79:00:00:0A';
-
-/**
- * These tests assert state transitions within one portal session, so a reset
- * from a concurrent browser project or repeat worker would invalidate the
- * assertion itself. Giving every concurrent worker slot its own MAC range
- * preserves browser parallelism and also keeps `--repeat-each` runs isolated.
- */
-interface StatefulAuthMacs {
-    authenticatedFlow: string;
-    loginRequired: string;
-    tokenReuse: string;
-    deviceConflict: string;
-    reauthentication: string;
-}
-
-function getStatefulAuthMacs({
-    parallelIndex,
-}: {
-    parallelIndex: number;
-}): StatefulAuthMacs {
-    if (
-        !Number.isSafeInteger(parallelIndex) ||
-        parallelIndex < 0 ||
-        parallelIndex > 255
-    ) {
-        throw new Error(
-            `Unsupported Playwright parallel index: ${parallelIndex}`
-        );
-    }
-
-    const workerOctet = parallelIndex
-        .toString(16)
-        .padStart(2, '0')
-        .toUpperCase();
-    const workerPrefix = `00:1A:79:AE:${workerOctet}`;
-
-    return {
-        authenticatedFlow: `${workerPrefix}:01`,
-        loginRequired: `${workerPrefix}:02`,
-        tokenReuse: `${workerPrefix}:03`,
-        deviceConflict: `${workerPrefix}:04`,
-        reauthentication: `${workerPrefix}:05`,
-    };
-}
-
-/**
- * Deliberately NOT an Infomir MAC: the strict endpoint rejects get_profile for
- * it, so no token is ever adopted and content requests fail permanently.
- */
-const AUTH_REJECTED_MAC = 'AA:BB:CC:DD:EE:01';
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Intercept calls to the Angular dev backend (/stalker proxy) and redirect
- * them to the mock server. This avoids needing a real backend or changing
- * any app environment configuration.
- */
-async function interceptStalkerRequests(page: Page): Promise<void> {
-    const providerTargets = await interceptProviderTargetRegistration(page);
-
-    await page.route('**/localhost:3000/stalker**', async (route) => {
-        const originalUrl = new URL(route.request().url());
-        const mockUrl = new URL(BACKEND_PROXY);
-        const providerUrl = getRegisteredProviderUrl(
-            originalUrl,
-            providerTargets
-        );
-
-        if (providerUrl) {
-            mockUrl.searchParams.set('url', providerUrl);
-        }
-
-        originalUrl.searchParams.forEach((value, key) => {
-            if (key === 'targetId') {
-                return;
-            }
-
-            mockUrl.searchParams.set(key, value);
-        });
-        await route.continue({ url: mockUrl.toString() });
-    });
-}
-
 /** Every MAC this file owns; all are cleared in one batched reset request. */
 const OWNED_MACS = [
     DEFAULT_MAC,
@@ -223,116 +131,6 @@ async function resetMockServer(
     throw lastError;
 }
 
-/**
- * Add a Stalker portal via the UI:
- * 1. Click the "add playlist" button to open the unified dialog
- * 2. Select "Stalker" toggle
- * 3. Fill in the form and submit
- */
-async function addStalkerPortal(
-    page: Page,
-    options: { name?: string; mac?: string } = {}
-): Promise<void> {
-    const { name = 'Mock Stalker Portal', mac = DEFAULT_MAC } = options;
-
-    await page.getByRole('button', { name: 'Add playlist' }).click();
-    const dialog = page.locator('mat-dialog-container');
-    await expect(dialog).toBeVisible();
-    // v0.22 redesign: tabs were replaced with a flat 5-card radio picker.
-    await dialog.getByRole('radio', { name: /Stalker portal/i }).click();
-
-    await setInputValue(dialog.locator('input#title'), name);
-    await setInputValue(dialog.locator('input#portalUrl'), PORTAL_URL);
-    await setInputValue(dialog.locator('input#macAddress'), mac);
-
-    const addButton = dialog.getByRole('button', {
-        name: 'Add playlist',
-        exact: true,
-    });
-    await expect(addButton).toBeEnabled({ timeout: 10_000 });
-    await addButton.click();
-    await expect(dialog).toBeHidden();
-    await page.waitForURL(/stalker.*vod/);
-}
-
-/**
- * Add a Stalker portal through the canonical Ministra URL, which the app
- * imports as a FULL portal: handshake, Bearer token and watchdog.
- */
-async function addFullStalkerPortal(
-    page: Page,
-    options: {
-        name?: string;
-        mac: string;
-        expectContent?: boolean;
-        username?: string;
-        password?: string;
-    }
-): Promise<void> {
-    const {
-        name = 'Full Stalker Portal',
-        mac,
-        expectContent = true,
-        username,
-        password,
-    } = options;
-
-    await page.getByRole('button', { name: 'Add playlist' }).click();
-    const dialog = page.locator('mat-dialog-container');
-    await expect(dialog).toBeVisible();
-    await dialog.getByRole('radio', { name: /Stalker portal/i }).click();
-
-    await setInputValue(dialog.locator('input#title'), name);
-    await setInputValue(dialog.locator('input#portalUrl'), FULL_PORTAL_URL);
-    await setInputValue(dialog.locator('input#macAddress'), mac);
-    if (username !== undefined) {
-        await setInputValue(dialog.locator('input#username'), username);
-    }
-    if (password !== undefined) {
-        await setInputValue(dialog.locator('input#password'), password);
-    }
-
-    const addButton = dialog.getByRole('button', {
-        name: 'Add playlist',
-        exact: true,
-    });
-    await expect(addButton).toBeEnabled({ timeout: 10_000 });
-    await addButton.click();
-    await expect(dialog).toBeHidden();
-
-    if (expectContent) {
-        await page.waitForURL(/stalker.*vod/, { timeout: 30_000 });
-    }
-}
-
-const CONTENT_ACTIONS = [
-    'get_categories',
-    'get_genres',
-    'get_ordered_list',
-    'get_all_channels',
-];
-
-/** Every portal request in order, with the token it carried. */
-function recordPortalRequests(
-    page: Page
-): Array<{ action: string; token: string | null }> {
-    const requests: Array<{ action: string; token: string | null }> = [];
-
-    page.on('request', (request) => {
-        const url = new URL(request.url());
-        if (!url.pathname.endsWith('/stalker')) {
-            return;
-        }
-        const action = url.searchParams.get('action');
-        if (!action) {
-            return;
-        }
-        requests.push({ action, token: url.searchParams.get('token') });
-    });
-
-    return requests;
-}
-
 // ---------------------------------------------------------------------------
 // Test setup
 // ---------------------------------------------------------------------------
@@ -967,16 +765,8 @@ test('@stalker favorites — embedded-series favorite refreshes newly released e
     request,
 }) => {
     // Find an embedded-series VOD item in the mock catalog first
-    const listResponse = await request.get(
-        `${MOCK_SERVER}/stalker?action=get_ordered_list&type=vod&category=2001&p=1&macAddress=${EMBEDDED_SERIES_MAC}&JsHttpRequest=1-xml`
-    );
-    const listBody = await listResponse.json();
-    const embeddedItem = listBody.payload.js.data.find(
-        (item: { series?: unknown[] }) =>
-            Array.isArray(item.series) && item.series.length > 0
-    );
-    expect(embeddedItem).toBeDefined();
-    const episodeCount: number = embeddedItem.series.length;
+    const { embeddedItem, episodeCount } =
+        await findEmbeddedSeriesItem(request);
 
     await addStalkerPortal(page, {
         name: 'Embedded Series Portal',
@@ -985,19 +775,7 @@ test('@stalker favorites — embedded-series favorite refreshes newly released e
 
     // Open the embedded-series item from its category and favorite it —
     // this persists a snapshot with the current episode list
-    const categories = page.locator('.category-item');
-    await expect(categories.first()).toBeVisible({ timeout: 10_000 });
-    await categories.nth(1).click();
-    const card = page.getByText(embeddedItem.name).first();
-    await expect(card).toBeVisible({ timeout: 10_000 });
-    await card.click();
-
-    await expect(
-        page.getByRole('heading', {
-            name: `${episodeCount}. Episode ${episodeCount}`,
-            exact: true,
-        })
-    ).toBeVisible({ timeout: 10_000 });
+    await openEmbeddedSeriesItem(page, embeddedItem.name, episodeCount);
     await page.getByRole('button', { name: 'Add to favorites' }).click();
     // Wait for the async favorite persistence before navigating away
     await expect(
@@ -1007,39 +785,7 @@ test('@stalker favorites — embedded-series favorite refreshes newly released e
     // From now on the portal has "released" one more episode: extend
     // series[] in every search response (the background snapshot refresh
     // re-fetches the item via a title search)
-    await page.route('**/localhost:3000/stalker**', async (route) => {
-        const originalUrl = new URL(route.request().url());
-        if (!originalUrl.searchParams.get('search')) {
-            await route.fallback();
-            return;
-        }
-
-        const mockUrl = new URL(BACKEND_PROXY);
-        const targetId = originalUrl.searchParams.get('targetId');
-        const providerUrl = targetId
-            ? Buffer.from(targetId, 'base64url').toString()
-            : originalUrl.searchParams.get('url');
-        if (providerUrl) {
-            mockUrl.searchParams.set('url', providerUrl);
-        }
-        originalUrl.searchParams.forEach((value, key) => {
-            if (key === 'targetId') {
-                return;
-            }
-            mockUrl.searchParams.set(key, value);
-        });
-
-        const response = await route.fetch({ url: mockUrl.toString() });
-        const body = await response.json();
-        const rows: { series?: string[] }[] =
-            body?.payload?.js?.data ?? body?.js?.data ?? [];
-        for (const row of rows) {
-            if (Array.isArray(row.series) && row.series.length > 0) {
-                row.series = [...row.series, String(row.series.length + 1)];
-            }
-        }
-        await route.fulfill({ response, body: JSON.stringify(body) });
-    });
+    await releaseExtraEpisodeInSearchResponses(page);
 
     // Open the item from the Favorites view: the stored snapshot renders
     // first, then the background refresh patches in the new episode
@@ -1083,35 +829,15 @@ test('@stalker season watched toggle — embedded series marks and clears every
     // Reuse the modeled embedded-series flow: find a VOD item carrying an
     // embedded series[] array, open it from its category, and land on the
     // series detail with its episode list.
-    const listResponse = await request.get(
-        `${MOCK_SERVER}/stalker?action=get_ordered_list&type=vod&category=2001&p=1&macAddress=${EMBEDDED_SERIES_MAC}&JsHttpRequest=1-xml`
-    );
-    const listBody = await listResponse.json();
-    const embeddedItem = listBody.payload.js.data.find(
-        (item: { series?: unknown[] }) =>
-            Array.isArray(item.series) && item.series.length > 0
-    );
-    expect(embeddedItem).toBeDefined();
-    const episodeCount: number = embeddedItem.series.length;
+    const { embeddedItem, episodeCount } =
+        await findEmbeddedSeriesItem(request);
 
     await addStalkerPortal(page, {
         name: 'Embedded Series Watch Portal',
         mac: EMBEDDED_SERIES_MAC,
     });
 
-    const categories = page.locator('.category-item');
-    await expect(categories.first()).toBeVisible({ timeout: 10_000 });
-    await categories.nth(1).click();
-    const card = page.getByText(embeddedItem.name).first();
-    await expect(card).toBeVisible({ timeout: 10_000 });
-    await card.click();
-
-    await expect(
-        page.getByRole('heading', {
-            name: `${episodeCount}. Episode ${episodeCount}`,
-            exact: true,
-        })
-    ).toBeVisible({ timeout: 10_000 });
+    await openEmbeddedSeriesItem(page, embeddedItem.name, episodeCount);
 
     await expectSeriesSurfacesInBothThemes(page, testInfo);
 
@@ -1153,35 +879,19 @@ test('@stalker series watched toggle — embedded series marks and clears from t
 }) => {
     // Same modeled embedded-series flow as the season test above, driven
     // through the series-level ⋮ menu instead of the season button.
-    const listResponse = await request.get(
-        `${MOCK_SERVER}/stalker?action=get_ordered_list&type=vod&category=2001&p=1&macAddress=${EMBEDDED_SERIES_MAC}&JsHttpRequest=1-xml`
-    );
-    const listBody = await listResponse.json();
-    const embeddedItem = listBody.payload.js.data.find(
-        (item: { series?: unknown[] }) =>
-            Array.isArray(item.series) && item.series.length > 0
-    );
-    expect(embeddedItem).toBeDefined();
-    const episodeCount: number = embeddedItem.series.length;
+    const { embeddedItem, episodeCount } =
+        await findEmbeddedSeriesItem(request);
 
     await addStalkerPortal(page, {
         name: 'Embedded Series Watch Menu Portal',
         mac: EMBEDDED_SERIES_MAC,
     });
 
-    const categories = page.locator('.category-item');
-    await expect(categories.first()).toBeVisible({ timeout: 10_000 });
-    await categories.nth(1).click();
-    const card = page.getByText(embeddedItem.name).first();
-    await expect(card).toBeVisible({ timeout: 10_000 });
-    await card.click();
-
-    await expect(
-        page.getByRole('heading', {
-            name: `${episodeCount}. Episode ${episodeCount}`,
-            exact: true,
-        })
-    ).toBeVisible({ timeout: 10_000 });
+    const card = await openEmbeddedSeriesItem(
+        page,
+        embeddedItem.name,
+        episodeCount
+    );
 
     // The series row sits in the hero's "…" menu (data-test-id with a dash —
     // getByTestId only matches data-testid in this suite; the row renders
diff --git a/docs/architecture/embedded-inline-playback.md b/docs/architecture/embedded-inline-playback.md
index 38751413c..d03a8e67e 100644
--- a/docs/architecture/embedded-inline-playback.md
+++ b/docs/architecture/embedded-inline-playback.md
@@ -383,15 +383,17 @@ meanwhile. The host reports busy-state back through the
 
 A series-level counterpart lives in a `⋮` menu at the end of the same
 header row (`SeasonWatchPresenter` in `libs/ui/components` owns the state
-math for both scopes; the container component sits at the max-lines cap).
+math for both scopes, which keeps the container component under the
+max-lines cap).
 `buildSeriesWatchToggleRequest` flattens every LOADED season with the same
 mark/unmark semantics, and the direction is always the one the label
 advertised (`markWatched: !seriesFullyWatched()`), never re-inferred from
 data at persist time. Hosts route the request through the same machinery
 as the season toggle — Xtream via the scope-parameterized
-`SerialDetailsSeasonWatchService.handle(..., scope)`, Stalker via the
-extracted `runWatchToggleBatch` core — sharing the busy flag, the
-ownership guards, and the catalog-badge refresh. Stalker lazy-VOD is the
+`SerialDetailsSeasonWatchService.handle(..., scope)`, Stalker via
+`StalkerSeriesWatchToggleService` and its `runStalkerWatchToggleBatch`
+core — sharing the busy flag, the ownership guards, and the catalog-badge
+refresh. Stalker lazy-VOD is the
 special case: unopened seasons have empty episode lists, so the container
 reports them through the `hasUnloadedSeasons` input (blocks the
 "fully watched" verdict and switches the label to its countless variant),
@@ -412,7 +414,8 @@ series-toggle hydration join one in-flight request instead of
 duplicating it (a second request's failure could abort a toggle whose
 original request succeeded).
 The host synchronously re-runs the position reconcile
-(`applyReconciledSeriesPositions` — the effect-fed maps only update on
+(`StalkerSeriesPositionsService.applyReconciledSeriesPositions` — the
+effect-fed maps only update on
 the next change-detection tick, and enqueuing against stale maps would
 miss the hydrated episodes' legacy rows), rebuilds the request from the
 now-complete seasons keeping the captured direction, and reports an
diff --git a/docs/architecture/stalker-mock-server.md b/docs/architecture/stalker-mock-server.md
index 93cd022ef..bd17dd53b 100644
--- a/docs/architecture/stalker-mock-server.md
+++ b/docs/architecture/stalker-mock-server.md
@@ -408,7 +408,8 @@ file running in parallel workers, so isolation is per-MAC rather than global:
   else is talking to the server — a spec that used it would wipe a sibling
   spec's session mid-test.
 - `apps/web-e2e/src/stalker.e2e.ts` declares its shared scenario MACs in
-  `OWNED_MACS` and clears them in one batched request. The sibling specs that
+  `OWNED_MACS` (the constants live in `stalker-portal.fixture.ts`) and clears
+  them in one batched request. The sibling specs that
   reach this server (`self-hosted.e2e.ts`, the `sources-pwa` helpers) own a
   disjoint `00:1A:79:5F:*` range, so neither file can clear the other's state.
 - Within each browser project, tests deliberately share content-scenario MACs
diff --git a/docs/architecture/stalker-portal.md b/docs/architecture/stalker-portal.md
index d39c1f61b..ccc755405 100644
--- a/docs/architecture/stalker-portal.md
+++ b/docs/architecture/stalker-portal.md
@@ -484,7 +484,8 @@ the format at all, so a large share of working installations use a non-Infomir
 MAC. Refusing one would stop those users adding or editing a portal that works
 for them. The mock encodes the same split (`enforceMacFormat` is set only on
 the strict endpoint; `/portal.php` ignores it), and `AUTH_REJECTED_MAC` in
-`stalker.e2e.ts` depends on it — a non-Infomir MAC that must reach the strict
+`stalker-portal.fixture.ts` (used by `stalker.e2e.ts`) depends on it — a
+non-Infomir MAC that must reach the strict
 endpoint and be refused _there_, not in the form.
 
 In the edit dialog **both** passes — blur and submit — normalize only a MAC the
diff --git a/docs/architecture/tmdb-roadmap.md b/docs/architecture/tmdb-roadmap.md
index 67adfa664..64b429ad1 100644
--- a/docs/architecture/tmdb-roadmap.md
+++ b/docs/architecture/tmdb-roadmap.md
@@ -257,7 +257,7 @@ Zero i18n keys. Zero UI change.
 - populated in all three of `mergeVodInfoWithTmdb` (`:168`), `mergeSerieInfoWithTmdb` (`:215`), `mergeStalkerInfoWithTmdb` (`:257`)
 - through `NormalizedVodMeta` (`libs/shared/interfaces/src/lib/vod-details-item.interface.ts`) + **both** normalizers in `vod-details-adapters.ts` — the single convergence point where Xtream and Stalker meet
 
-**Component.** New standalone `app-tmdb-extras-shelf` in `libs/ui/shared-portals`. It must **not** go inline: `libs/ui/playback/src/lib/vod-details/vod-details.component.ts` is **388 lines and is NOT in `tools/eslint/max-lines-baseline.mjs`** — roughly 12 lines of headroom against the hard 400 lint cap.
+**Component.** New standalone `app-tmdb-extras-shelf` in `libs/ui/shared-portals`. It must **not** go inline: `libs/ui/playback/src/lib/vod-details/vod-details.component.ts` is **NOT in `tools/eslint/max-lines-baseline.mjs`** and stays under the hard 400 lint cap only because its state lives in sibling helpers (about 340 counted lines today).
 
 **Render** into the `detail-extras` projection slot at **four** sites (`vod-details.component.html:225`, `serial-details.component.html:201`, `vod-details-route.component.html:247`, `stalker-series-view.component.html:202`) — note Xtream `serial-details` has no trailer block today, so it either gains one or the shelf lands inconsistently. Reuse the existing nocookie iframe + `| safe` pipe so the Electron Referer shim keeps working; clicking swaps the embed `src` rather than opening a new player. Cards use `https://img.youtube.com/vi/{key}/hqdefault.jpg` (CSP verified: `img-src` covers it, `frame-src https://www.youtube-nocookie.com` covers the embed). `@if (extras().length > 1)` … `@else` the existing single-trailer markup **verbatim**.
 
diff --git a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
index 23ed55ada..488abdeeb 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
@@ -38,7 +38,6 @@ import {
     PlaylistsService,
 } from '@iptvnator/services';
 import {
-    PlaybackPositionData,
     ResolvedPortalPlayback,
     StalkerVodDetails,
     VodDetailsItem,
@@ -47,6 +46,8 @@ import {
 import { StalkerCatalogFacadeService } from '../stalker-catalog-facade.service';
 import { StalkerSeriesViewComponent } from '../stalker-series-view/stalker-series-view.component';
 
+import { startStalkerCatalogVodPlayback } from './stalker-catalog-vod-playback';
+import { StalkerCatalogVodPosition } from './stalker-catalog-vod-position';
 import { startStalkerVodDownload } from './stalker-vod-download';
 import { createStalkerVodWatchedToggle } from '../stalker-vod-watched-toggle';
 import {
@@ -107,13 +108,16 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
     readonly playbackOwnerKey = computed(() =>
         JSON.stringify([this.playbackSessionKey(), this.contentType()])
     );
-    private readonly selectedVodPosition = signal<PlaybackPositionData | null>(
-        null
-    );
-    private unsubscribePositionUpdates: (() => void) | null = null;
-    private positionLoadGeneration = 0;
+    private readonly vodPosition = new StalkerCatalogVodPosition({
+        playbackPositions: this.playbackPositions,
+        playbackPositionBridge: this.playbackPositionBridge,
+        playlistId: () => this.catalog.playlist()?.id,
+        selectedItem: this.selectedItem,
+        contentType: this.contentType,
+        isSeriesDetail: () => this.isSeriesDetail(),
+    });
     /** The stored row is in hand (not the placeholder shown while reading). */
-    readonly positionLoaded = signal(false);
+    readonly positionLoaded = this.vodPosition.loaded;
     /**
      * The start still waiting on the portal between the click and playback,
      * keyed by its owner: a stale resolution for the previous movie must not
@@ -146,13 +150,13 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
     });
 
     readonly selectedVodPlaybackDuration = computed<number | null>(
-        () => this.selectedVodPosition()?.durationSeconds ?? null
+        () => this.vodPosition.position()?.durationSeconds ?? null
     );
     readonly sourceLabel = computed(
         () => this.catalog.playlist()?.title ?? null
     );
     readonly selectedVodPlaybackPosition = computed<number | null>(
-        () => this.selectedVodPosition()?.positionSeconds ?? null
+        () => this.vodPosition.position()?.positionSeconds ?? null
     );
 
     /** Manual watched toggle; the child gates it on live playback itself. */
@@ -165,7 +169,7 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
                 : null;
         },
         playbackPositions: this.playbackPositions,
-        position: this.selectedVodPosition,
+        position: this.vodPosition.position,
         playingNow: computed(
             () => this.inlinePlayback() !== null || this.playbackStartPending()
         ),
@@ -173,8 +177,8 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
         applyPosition: (position) => {
             // A read still in flight started from the pre-write row; letting
             // it land would revert the toggle it never saw.
-            this.positionLoadGeneration++;
-            this.selectedVodPosition.set(position);
+            this.vodPosition.discardPendingLoad();
+            this.vodPosition.position.set(position);
         },
         snackBar: this.snackBar,
         translateService: this.translateService,
@@ -196,22 +200,7 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
     );
 
     constructor() {
-        effect(() => {
-            const item = this.selectedItem();
-            const playlistId = this.catalog.playlist()?.id;
-
-            if (
-                !item ||
-                !playlistId ||
-                this.contentType() !== 'vod' ||
-                this.isSeriesDetail()
-            ) {
-                this.selectedVodPosition.set(null);
-                return;
-            }
-
-            void this.loadSelectedVodPosition(playlistId, Number(item.id));
-        });
+        this.vodPosition.connect();
 
         effect(() => {
             const ownerKey = this.playbackOwnerKey();
@@ -222,22 +211,6 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
             this.currentPlaybackOwnerKey = ownerKey;
             this.closeInlinePlayer();
         });
-
-        this.unsubscribePositionUpdates =
-            this.playbackPositionBridge.onPlaybackPositionUpdate(
-                (data: PlaybackPositionData) => {
-                    const currentItem = this.selectedItem();
-                    if (
-                        data.contentType !== 'vod' ||
-                        data.playlistId !== this.catalog.playlist()?.id ||
-                        data.contentXtreamId !== Number(currentItem?.id)
-                    ) {
-                        return;
-                    }
-
-                    this.selectedVodPosition.set(data);
-                }
-            ) ?? null;
     }
 
     onVodPlay(item: VodDetailsItem, positionSeconds?: number): void {
@@ -281,8 +254,8 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
             this.contentType() === 'vod' && !this.isSeriesDetail()
                 ? Number(this.selectedItem()?.id) || null
                 : null,
-        selectedVodPosition: this.selectedVodPosition,
-        discardPendingPositionLoad: () => ++this.positionLoadGeneration,
+        selectedVodPosition: this.vodPosition.position,
+        discardPendingPositionLoad: () => this.vodPosition.discardPendingLoad(),
         beforeExternalLaunch: () => this.closeInlinePlayer(),
         beginPendingStart: () => beginTrackedExternalLaunch(this),
         afterProgressReset: (playlistId) =>
@@ -338,7 +311,7 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
                 playlistId,
                 position
             ),
-        onSaved: (position) => this.selectedVodPosition.set(position),
+        onSaved: (position) => this.vodPosition.position.set(position),
     });
 
     handleInlineTimeUpdate(event: {
@@ -356,36 +329,7 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
 
     ngOnDestroy(): void {
         this.closeInlinePlayer();
-        this.unsubscribePositionUpdates?.();
-    }
-
-    private async loadSelectedVodPosition(
-        playlistId: string,
-        vodId: number
-    ): Promise<void> {
-        const generation = ++this.positionLoadGeneration;
-        this.positionLoaded.set(false);
-        if (Number.isNaN(vodId)) {
-            this.selectedVodPosition.set(null);
-            return;
-        }
-
-        const position = await this.playbackPositions.getPlaybackPosition(
-            playlistId,
-            vodId,
-            'vod'
-        );
-        // Only the newest read for the item still on screen may land: an
-        // older one would revert a watched toggle or a later selection.
-        if (
-            generation !== this.positionLoadGeneration ||
-            this.catalog.playlist()?.id !== playlistId ||
-            Number(this.selectedItem()?.id) !== vodId
-        ) {
-            return;
-        }
-        this.selectedVodPosition.set(position ?? null);
-        this.positionLoaded.set(true);
+        this.vodPosition.disconnect();
     }
 
     private async startStalkerVodPlayback(
@@ -394,54 +338,19 @@ export class StalkerCatalogDetailComponent implements OnDestroy {
         thumbnail?: string,
         startTime?: number
     ): Promise<void> {
-        const requestId = ++this.playbackRequestId;
-        const sessionKey = this.playbackSessionKey();
-        const ownerKey = this.playbackOwnerKey();
-        const usesEmbeddedPlayer = this.portalPlayer.isEmbeddedPlayer();
-        if (usesEmbeddedPlayer && !sessionKey) return;
-
-        const startId = this.pendingStart.begin(ownerKey);
-        try {
-            const playback = await this.catalog.resolveVodPlayback(
-                cmd,
-                title,
-                thumbnail,
-                startTime
-            );
-            if (
-                requestId !== this.playbackRequestId ||
-                this.playbackOwnerKey() !== ownerKey
-            ) {
-                return;
-            }
-
-            this.positionWriter.reset();
-            if (usesEmbeddedPlayer) {
-                this.inlinePlayback.set(playback);
-                return;
-            }
-
-            this.closeInlinePlayer();
-            void this.portalPlayer.openResolvedPlayback(playback, true);
-        } catch (error) {
-            if (
-                requestId !== this.playbackRequestId ||
-                this.playbackOwnerKey() !== ownerKey
-            ) {
-                return;
-            }
-            this.logger.error('Failed to start inline VOD playback', error);
-            const errorMessage =
-                error instanceof Error && error.message === 'nothing_to_play'
-                    ? this.translateService.instant(
-                          'PORTALS.CONTENT_NOT_AVAILABLE'
-                      )
-                    : this.translateService.instant('PORTALS.PLAYBACK_ERROR');
-            this.snackBar.open(errorMessage, undefined, {
-                duration: 3000,
-            });
-        } finally {
-            this.pendingStart.settle(startId);
-        }
+        await startStalkerCatalogVodPlayback(this, {
+            resolvePlayback: () =>
+                this.catalog.resolveVodPlayback(
+                    cmd,
+                    title,
+                    thumbnail,
+                    startTime
+                ),
+            portalPlayer: this.portalPlayer,
+            resetPositionWriter: () => this.positionWriter.reset(),
+            logger: this.logger,
+            translate: this.translateService,
+            snackBar: this.snackBar,
+        });
     }
 }
diff --git a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-playback.ts b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-playback.ts
new file mode 100644
index 000000000..b26f4f11c
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-playback.ts
@@ -0,0 +1,84 @@
+import type { WritableSignal } from '@angular/core';
+import type { MatSnackBar } from '@angular/material/snack-bar';
+import type { TranslateService } from '@ngx-translate/core';
+import type { Logger, PortalPlayer } from '@iptvnator/portal/shared/util';
+import type { ResolvedPortalPlayback } from '@iptvnator/shared/interfaces';
+
+/** The detail page as the owner of its inline player: it tracks its own request ids. */
+interface StalkerCatalogVodPlaybackHost {
+    playbackRequestId: number;
+    readonly pendingStart: {
+        begin(owner: string): number;
+        settle(startId: number): void;
+    };
+    playbackOwnerKey(): string;
+    playbackSessionKey(): string;
+    readonly inlinePlayback: WritableSignal<ResolvedPortalPlayback | null>;
+    closeInlinePlayer(): void;
+}
+
+interface StalkerCatalogVodPlaybackDeps {
+    readonly resolvePlayback: () => Promise<ResolvedPortalPlayback>;
+    readonly portalPlayer: Pick<
+        PortalPlayer,
+        'isEmbeddedPlayer' | 'openResolvedPlayback'
+    >;
+    /** Clears the inline position writer for the playback about to mount. */
+    readonly resetPositionWriter: () => void;
+    readonly logger: Pick<Logger, 'error'>;
+    readonly translate: Pick<TranslateService, 'instant'>;
+    readonly snackBar: Pick<MatSnackBar, 'open'>;
+}
+
+/**
+ * Play/Resume of the movie on the routed catalog detail: resolves the
+ * stream and hands it to the inline or the configured player, unless the
+ * page moved on or a newer start took over while the portal answered.
+ */
+export async function startStalkerCatalogVodPlayback(
+    host: StalkerCatalogVodPlaybackHost,
+    deps: StalkerCatalogVodPlaybackDeps
+): Promise<void> {
+    const requestId = ++host.playbackRequestId;
+    const sessionKey = host.playbackSessionKey();
+    const ownerKey = host.playbackOwnerKey();
+    const usesEmbeddedPlayer = deps.portalPlayer.isEmbeddedPlayer();
+    if (usesEmbeddedPlayer && !sessionKey) return;
+
+    const startId = host.pendingStart.begin(ownerKey);
+    try {
+        const playback = await deps.resolvePlayback();
+        if (
+            requestId !== host.playbackRequestId ||
+            host.playbackOwnerKey() !== ownerKey
+        ) {
+            return;
+        }
+
+        deps.resetPositionWriter();
+        if (usesEmbeddedPlayer) {
+            host.inlinePlayback.set(playback);
+            return;
+        }
+
+        host.closeInlinePlayer();
+        void deps.portalPlayer.openResolvedPlayback(playback, true);
+    } catch (error) {
+        if (
+            requestId !== host.playbackRequestId ||
+            host.playbackOwnerKey() !== ownerKey
+        ) {
+            return;
+        }
+        deps.logger.error('Failed to start inline VOD playback', error);
+        const errorMessage =
+            error instanceof Error && error.message === 'nothing_to_play'
+                ? deps.translate.instant('PORTALS.CONTENT_NOT_AVAILABLE')
+                : deps.translate.instant('PORTALS.PLAYBACK_ERROR');
+        deps.snackBar.open(errorMessage, undefined, {
+            duration: 3000,
+        });
+    } finally {
+        host.pendingStart.settle(startId);
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-position.ts b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-position.ts
new file mode 100644
index 000000000..f60b4176b
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-vod-position.ts
@@ -0,0 +1,110 @@
+import { type Signal, effect, signal } from '@angular/core';
+import type { PortalPlaybackPositions } from '@iptvnator/portal/shared/util';
+import type { StalkerSelectedVodItem } from '@iptvnator/portal/stalker/data-access';
+import type { PlaybackPositionRuntimeBridgeService } from '@iptvnator/services';
+import type { PlaybackPositionData } from '@iptvnator/shared/interfaces';
+
+interface StalkerCatalogVodPositionConfig {
+    readonly playbackPositions: Pick<
+        PortalPlaybackPositions,
+        'getPlaybackPosition'
+    >;
+    readonly playbackPositionBridge: Pick<
+        PlaybackPositionRuntimeBridgeService,
+        'onPlaybackPositionUpdate'
+    >;
+    readonly playlistId: () => string | undefined;
+    readonly selectedItem: Signal<StalkerSelectedVodItem | null>;
+    readonly contentType: () => string;
+    readonly isSeriesDetail: () => boolean;
+}
+
+/**
+ * The stored playback position of the movie the routed catalog detail
+ * shows: read whenever the selection changes and kept current from the
+ * playback runtime while that movie stays on screen.
+ */
+export class StalkerCatalogVodPosition {
+    readonly position = signal<PlaybackPositionData | null>(null);
+    /** The stored row is in hand (not the placeholder shown while reading). */
+    readonly loaded = signal(false);
+    private unsubscribePositionUpdates: (() => void) | null = null;
+    private loadGeneration = 0;
+
+    constructor(private readonly config: StalkerCatalogVodPositionConfig) {}
+
+    /**
+     * Starts following the selection and the playback runtime. Registers an
+     * effect, so the host calls it from its constructor.
+     */
+    connect(): void {
+        effect(() => {
+            const item = this.config.selectedItem();
+            const playlistId = this.config.playlistId();
+
+            if (
+                !item ||
+                !playlistId ||
+                this.config.contentType() !== 'vod' ||
+                this.config.isSeriesDetail()
+            ) {
+                this.position.set(null);
+                return;
+            }
+
+            void this.load(playlistId, Number(item.id));
+        });
+
+        this.unsubscribePositionUpdates =
+            this.config.playbackPositionBridge.onPlaybackPositionUpdate(
+                (data: PlaybackPositionData) => {
+                    const currentItem = this.config.selectedItem();
+                    if (
+                        data.contentType !== 'vod' ||
+                        data.playlistId !== this.config.playlistId() ||
+                        data.contentXtreamId !== Number(currentItem?.id)
+                    ) {
+                        return;
+                    }
+
+                    this.position.set(data);
+                }
+            ) ?? null;
+    }
+
+    disconnect(): void {
+        this.unsubscribePositionUpdates?.();
+    }
+
+    /** Retires a stored-position read still in flight (a row was written since). */
+    discardPendingLoad(): void {
+        this.loadGeneration++;
+    }
+
+    private async load(playlistId: string, vodId: number): Promise<void> {
+        const generation = ++this.loadGeneration;
+        this.loaded.set(false);
+        if (Number.isNaN(vodId)) {
+            this.position.set(null);
+            return;
+        }
+
+        const position =
+            await this.config.playbackPositions.getPlaybackPosition(
+                playlistId,
+                vodId,
+                'vod'
+            );
+        // Only the newest read for the item still on screen may land: an
+        // older one would revert a watched toggle or a later selection.
+        if (
+            generation !== this.loadGeneration ||
+            this.config.playlistId() !== playlistId ||
+            Number(this.config.selectedItem()?.id) !== vodId
+        ) {
+            return;
+        }
+        this.position.set(position ?? null);
+        this.loaded.set(true);
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-paging.controller.ts b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-paging.controller.ts
new file mode 100644
index 000000000..f261c0598
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-paging.controller.ts
@@ -0,0 +1,391 @@
+import {
+    type Signal,
+    computed,
+    linkedSignal,
+    resource,
+    signal,
+} from '@angular/core';
+import type { Logger } from '@iptvnator/portal/shared/util';
+import {
+    executeStalkerRequest,
+    type StalkerPortalRepairService,
+    type StalkerSessionService,
+    type StalkerVodSource,
+    withoutWithheldStalkerItems,
+} from '@iptvnator/portal/stalker/data-access';
+import {
+    type DataService,
+    type ParentalLockService,
+    resetHostConnectivityGuard,
+} from '@iptvnator/services';
+import {
+    type PlaylistMeta,
+    StalkerPortalActions,
+} from '@iptvnator/shared/interfaces';
+import { isStalkerSearchRequestCurrent } from './stalker-search-request.util';
+import {
+    buildStalkerSearchRequestParams,
+    dedupeSearchResults,
+    recordNewWithheldRows,
+    resolveSearchWithheldCategoryIds,
+    type StalkerSearchContentType,
+    type StalkerSearchResponse,
+    withAbsoluteScreenshotUri,
+} from './stalker-search-results.util';
+
+interface StalkerSearchPagingControllerConfig {
+    searchTerm: Signal<string>;
+    selectedFilterType: Signal<StalkerSearchContentType>;
+    /** The portal being searched; null while none is resolved. */
+    currentPlaylist: Signal<PlaylistMeta | null>;
+    dataService: DataService;
+    parentalLock: ParentalLockService;
+    stalkerSession: StalkerSessionService;
+    portalRepair: StalkerPortalRepairService;
+    logger: Logger;
+    /** Closes the host's open detail when its genre became withheld. */
+    closeWithheldDetail: (withheldCategoryIds: ReadonlySet<string>) => void;
+}
+
+/**
+ * Owns the result paging of the Stalker search page: the portal page being
+ * requested, the pages accumulated into one list and the parental-lock
+ * bookkeeping that decides whether paging continues.
+ */
+export class StalkerSearchPagingController {
+    /** Lock version the accumulated results were built under. */
+    private searchResultsLockVersion: number | null = null;
+    /**
+     * Withheld row ids seen for the current search identity. A page adding
+     * only new withheld ids is still progress and is skipped automatically;
+     * a page adding nothing new is the end of the results.
+     */
+    private searchWithheldKey = '';
+    private readonly searchWithheldIds = new Set<string>();
+
+    constructor(private readonly config: StalkerSearchPagingControllerConfig) {}
+
+    /**
+     * Portal page for the current term+filter+portal; resets when any of
+     * them changes. The playlist belongs to the identity: Angular reuses the
+     * search route across `/stalker/A/search` -> `/stalker/B/search`, and a
+     * surviving page number would append portal B's later page onto portal
+     * A's accumulated results while skipping B's first page.
+     */
+    readonly searchPage = linkedSignal({
+        source: () => ({
+            term: this.config.searchTerm(),
+            type: this.config.selectedFilterType(),
+            playlistId: this.config.currentPlaylist()?._id ?? null,
+        }),
+        computation: () => 1,
+    });
+    /** Pages accumulated into one continuous, deduplicated result list. */
+    private readonly accumulatedSearchResults = signal<StalkerVodSource[]>([]);
+    readonly searchResults = this.accumulatedSearchResults.asReadonly();
+    readonly searchHasMore = signal(false);
+    /**
+     * A failed append page. The next near-end RETRIES that page instead of
+     * advancing — incrementing past it would silently omit its results.
+     */
+    readonly searchAppendError = signal(false);
+
+    readonly searchResultsResource = resource({
+        params: () => ({
+            contentType: this.config.selectedFilterType(),
+            search: this.config.searchTerm(),
+            page: this.searchPage(),
+            playlistId: this.config.currentPlaylist()?._id ?? null,
+            action: StalkerPortalActions.GetOrderedList,
+            // Lock/unlock re-fires the search: withheld rows are dropped at
+            // page time, so the results must be rebuilt when they change.
+            parentalLockVersion: this.config.parentalLock.version(),
+        }),
+        loader: async ({ params }) => {
+            if (params.search.length < 3) {
+                this.resetSearchAccumulator();
+                return [];
+            }
+            const playlist = this.config.currentPlaylist();
+            if (!playlist) {
+                // A reused route can land on a deleted/unresolved portal —
+                // the previous portal's cards must not keep rendering.
+                this.resetSearchAccumulator();
+                return [];
+            }
+            const { portalUrl, macAddress } = playlist;
+            if (!portalUrl || !macAddress) {
+                this.resetSearchAccumulator();
+                return [];
+            }
+            const contentType = params.contentType;
+            const withheldCategoryIds = resolveSearchWithheldCategoryIds(
+                this.config.parentalLock,
+                playlist._id,
+                contentType
+            );
+            const lockVersionChanged =
+                this.searchResultsLockVersion !== null &&
+                this.searchResultsLockVersion !== params.parentalLockVersion;
+            this.searchResultsLockVersion = params.parentalLockVersion;
+            if (lockVersionChanged) {
+                this.applyRelockToResults(withheldCategoryIds, contentType);
+            }
+            if (lockVersionChanged && params.page > 1) {
+                // A lock flip past page 1: rebuild from page 1 rather than
+                // appending to pages accumulated under the old lock state.
+                this.searchPage.set(1);
+                return this.accumulatedSearchResults();
+            }
+            const withheldKey = JSON.stringify([
+                params.playlistId,
+                contentType,
+                params.search,
+                params.parentalLockVersion,
+            ]);
+            if (params.page === 1 || this.searchWithheldKey !== withheldKey) {
+                this.searchWithheldKey = withheldKey;
+                this.searchWithheldIds.clear();
+            }
+
+            const requestParams = buildStalkerSearchRequestParams(
+                contentType,
+                params.search,
+                params.page
+            );
+
+            // A stale response (term/filter/page/portal — or the parental
+            // lock — moved on while this page was in flight) must not clobber
+            // the accumulated list: the request is not aborted, and a
+            // pre-relock response was filtered with the pre-relock set.
+            const isCurrent = (): boolean =>
+                isStalkerSearchRequestCurrent(params, {
+                    search: this.config.searchTerm(),
+                    contentType: this.config.selectedFilterType(),
+                    page: this.searchPage(),
+                    playlistId: this.config.currentPlaylist()?._id ?? null,
+                    parentalLockVersion: this.config.parentalLock.version(),
+                });
+
+            try {
+                // executeStalkerRequest owns the portal-mode decision (shared
+                // predicate with URL fallback for legacy rows) and the lazy
+                // portal repair, so search cannot drift from the catalog
+                // paths.
+                const response =
+                    await executeStalkerRequest<StalkerSearchResponse>(
+                        {
+                            dataService: this.config.dataService,
+                            stalkerSession: this.config.stalkerSession,
+                            portalRepair: this.config.portalRepair,
+                        },
+                        playlist,
+                        requestParams
+                    );
+                const rawItems = (response.js?.data || []).map(
+                    (item: StalkerVodSource) =>
+                        withAbsoluteScreenshotUri(item, portalUrl)
+                );
+                const items = withoutWithheldStalkerItems(
+                    rawItems,
+                    contentType,
+                    withheldCategoryIds
+                );
+                // Before the withheld-id bookkeeping: a stale page must not
+                // pre-record ids into a set a newer relock request cleared,
+                // or that request's page counts no new withheld rows and
+                // stops paging short of later visible matches.
+                if (!isCurrent()) {
+                    return items;
+                }
+                const newWithheldCount = recordNewWithheldRows(
+                    rawItems,
+                    items,
+                    this.searchWithheldIds
+                );
+
+                const merged = this.applySearchPageSuccess(
+                    params.page,
+                    items,
+                    response.js?.total_items,
+                    // A page made only of withheld rows still is a page the
+                    // portal served; judge progress on what it sent.
+                    rawItems.length > 0 &&
+                        (items.length > 0 || newWithheldCount > 0)
+                );
+                this.advancePastWithheldPage(
+                    params.page,
+                    items.length,
+                    newWithheldCount,
+                    isCurrent
+                );
+                return merged;
+            } catch (error) {
+                this.config.logger.warn('Stalker search page failed', {
+                    page: params.page,
+                    error,
+                });
+                if (!isCurrent()) {
+                    return this.accumulatedSearchResults();
+                }
+
+                return this.applySearchPageFailure(params.page);
+            }
+        },
+    });
+
+    /**
+     * Empties the accumulator and every paging flag — used whenever there is
+     * no searchable portal (short term, missing playlist, malformed row).
+     */
+    resetSearchAccumulator(): void {
+        this.accumulatedSearchResults.set([]);
+        this.searchHasMore.set(false);
+        this.searchAppendError.set(false);
+    }
+
+    /** Merges a successful portal page into the accumulated result list. */
+    applySearchPageSuccess(
+        page: number,
+        items: StalkerVodSource[],
+        totalItems: number | undefined,
+        pageHadRows: boolean = items.length > 0
+    ): StalkerVodSource[] {
+        const previous = page === 1 ? [] : this.accumulatedSearchResults();
+        const merged =
+            page === 1 ? items : dedupeSearchResults([...previous, ...items]);
+        // Paging continues only while pages make progress — with OR without
+        // a reported total. Dedup after mid-list portal mutations can leave
+        // the unique list permanently shorter than total_items, and a
+        // repeated page dedupes to no growth; either way a no-progress
+        // append is the practical end of the results. A page whose rows were
+        // all withheld by the parental lock counts as progress too.
+        const withheldRows = pageHadRows && items.length === 0;
+        const madeProgress =
+            page === 1 || merged.length > previous.length || withheldRows;
+        this.searchHasMore.set(
+            madeProgress &&
+                (typeof totalItems === 'number' && totalItems >= 0
+                    ? merged.length < totalItems
+                    : pageHadRows)
+        );
+        this.searchAppendError.set(false);
+        this.accumulatedSearchResults.set(merged);
+        return merged;
+    }
+
+    /**
+     * A failed FRESH search (page 1) must not keep rendering the previous
+     * query's cards; a failed append keeps the accumulated pages and flags
+     * the error so the next near-end retries this page instead of advancing.
+     */
+    applySearchPageFailure(page: number): StalkerVodSource[] {
+        if (page === 1) {
+            this.accumulatedSearchResults.set([]);
+            this.searchHasMore.set(false);
+            this.searchAppendError.set(false);
+            return [];
+        }
+
+        this.searchAppendError.set(true);
+        return this.accumulatedSearchResults();
+    }
+
+    /**
+     * Result-set identity for the layout's near-end latch and auto-fill
+     * budget — term, filter, and portal, mirroring the paging identity.
+     */
+    readonly searchScrollResetKey = computed(() =>
+        [
+            this.config.searchTerm(),
+            this.config.selectedFilterType(),
+            this.config.currentPlaylist()?._id ?? '',
+        ].join('|')
+    );
+
+    readonly isInitialSearchLoading = computed(
+        () => this.searchResultsResource.isLoading() && this.searchPage() === 1
+    );
+    readonly isAppendingSearchResults = computed(
+        () => this.searchResultsResource.isLoading() && this.searchPage() > 1
+    );
+
+    loadMoreSearchResults(): void {
+        if (this.searchResultsResource.isLoading() || !this.searchHasMore()) {
+            return;
+        }
+
+        if (this.searchAppendError()) {
+            // Retry the SAME page — advancing would permanently omit it.
+            void this.retrySearchPage();
+            return;
+        }
+
+        this.searchPage.update((page) => page + 1);
+    }
+
+    /**
+     * Two failed search pages are exactly what opens the main process'
+     * connectivity guard, so the reset has to precede the reload — otherwise
+     * this retry fast-fails without contacting a portal that may have
+     * recovered, and keeps repeating the same error until the window expires.
+     */
+    private async retrySearchPage(): Promise<void> {
+        // Clear the flag synchronously: awaiting first would leave this branch
+        // re-enterable, and the next `nearEnd` event would fire a second retry.
+        this.searchAppendError.set(false);
+        await resetHostConnectivityGuard(
+            this.config.dataService,
+            this.config.currentPlaylist()?.portalUrl
+        );
+        this.searchResultsResource.reload();
+    }
+
+    /**
+     * The infinite scroll gives up after a few loads that add no height, so
+     * a run of pages made only of parental-locked rows must advance by
+     * itself until a visible row (or the real end) is reached. Only a page
+     * that added withheld ids not seen before counts — a stalled portal
+     * repeating the same locked rows must still end the loop.
+     */
+    advancePastWithheldPage(
+        page: number,
+        visibleCount: number,
+        newWithheldCount: number,
+        isCurrent: () => boolean
+    ): void {
+        if (
+            visibleCount > 0 ||
+            newWithheldCount === 0 ||
+            !this.searchHasMore()
+        ) {
+            return;
+        }
+        queueMicrotask(() => {
+            if (isCurrent()) {
+                this.searchPage.set(page + 1);
+            }
+        });
+    }
+
+    /**
+     * A lock change reached the results on screen, which were read under
+     * the old lock state: close an open detail of a now-withheld genre (the
+     * list hiding it is not enough) and drop the withheld rows NOW, before
+     * the replacement page is awaited — on page 1 too, or they stay
+     * clickable while (or, if it hangs, after) that request is pending.
+     */
+    applyRelockToResults(
+        withheldCategoryIds: ReadonlySet<string>,
+        contentType: Parameters<typeof withoutWithheldStalkerItems>[1]
+    ): void {
+        this.config.closeWithheldDetail(withheldCategoryIds);
+        this.accumulatedSearchResults.set(
+            withoutWithheldStalkerItems(
+                this.accumulatedSearchResults(),
+                contentType,
+                withheldCategoryIds
+            )
+        );
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-results.util.ts b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-results.util.ts
new file mode 100644
index 000000000..d49a76884
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search-results.util.ts
@@ -0,0 +1,138 @@
+import {
+    StalkerContentTypes,
+    type StalkerVodSource,
+    stalkerWithheldRowKey,
+} from '@iptvnator/portal/stalker/data-access';
+import type { ParentalLockService } from '@iptvnator/services';
+import { ALL_CATEGORIES_WITHHELD } from '@iptvnator/shared/interfaces';
+
+export type StalkerSearchContentType = 'vod' | 'series';
+
+export interface StalkerSearchResponse {
+    js?: {
+        data?: StalkerVodSource[];
+        total_items?: number;
+    };
+    message?: string;
+    status?: number;
+}
+
+/** Portals can shift items between pages mid-append — drop duplicate ids. */
+export function dedupeSearchResults(
+    items: StalkerVodSource[]
+): StalkerVodSource[] {
+    const seenIds = new Set<string>();
+    return items.filter((item) => {
+        const id =
+            item.id === undefined || item.id === null ? null : String(item.id);
+        if (id === null) {
+            return true;
+        }
+        if (seenIds.has(id)) {
+            return false;
+        }
+        seenIds.add(id);
+        return true;
+    });
+}
+
+/**
+ * The dedicated search route has no category guard, so it filters the
+ * portal's rows itself: a locked genre's title must not reach the grid, its
+ * detail or playback through search.
+ */
+export function resolveSearchWithheldCategoryIds(
+    parentalLock: ParentalLockService,
+    playlistId: string,
+    contentType: StalkerSearchContentType
+): ReadonlySet<string> {
+    return !parentalLock.active()
+        ? new Set<string>()
+        : parentalLock.withholdsEverything?.()
+          ? ALL_CATEGORIES_WITHHELD
+          : new Set(parentalLock.lockedStalkerIds(playlistId, contentType));
+}
+
+/**
+ * Mirror the catalog request shape: many Ministra portals return an empty
+ * list for get_ordered_list without the category/genre/sortby params the STB
+ * client always sends. `max_page_items` is a HINT — plenty of portals ignore
+ * it and return their own page size, which is why paging cannot rely on it
+ * (progress and `total_items` decide hasMore instead).
+ */
+export function buildStalkerSearchRequestParams(
+    contentType: StalkerSearchContentType,
+    search: string,
+    page: number
+): Record<string, string | number> {
+    return {
+        action: StalkerContentTypes[contentType].getContentAction,
+        type: contentType,
+        sortby: 'added',
+        search,
+        p: page,
+        max_page_items: 100,
+        category: '*',
+        ...(contentType === 'vod' ? { genre: '0' } : {}),
+    };
+}
+
+/**
+ * Records the rows of `rawItems` the parental lock withheld (those missing
+ * from `keptItems`) into `seenWithheldIds` and returns how many of them were
+ * not seen before.
+ */
+export function recordNewWithheldRows(
+    rawItems: StalkerVodSource[],
+    keptItems: StalkerVodSource[],
+    seenWithheldIds: Set<string>
+): number {
+    let newWithheldCount = 0;
+    if (keptItems.length < rawItems.length) {
+        const kept = new Set(keptItems);
+        for (const item of rawItems) {
+            const id = stalkerWithheldRowKey(item);
+            if (!kept.has(item) && !seenWithheldIds.has(id)) {
+                seenWithheldIds.add(id);
+                newWithheldCount += 1;
+            }
+        }
+    }
+    return newWithheldCount;
+}
+
+/** Resolves a result row's portal-relative poster against the portal origin. */
+export function withAbsoluteScreenshotUri(
+    item: StalkerVodSource,
+    portalUrl: string
+): StalkerVodSource {
+    const processed = { ...item };
+
+    if (processed.screenshot_uri) {
+        processed.screenshot_uri = makeAbsoluteUrl(
+            portalUrl,
+            processed.screenshot_uri
+        );
+    }
+
+    return processed;
+}
+
+function makeAbsoluteUrl(baseUrl: string, relativePath: string): string {
+    if (!relativePath) return '';
+    if (
+        relativePath.startsWith('http://') ||
+        relativePath.startsWith('https://')
+    ) {
+        return relativePath;
+    }
+    try {
+        const url = new URL(baseUrl);
+        const path = relativePath.startsWith('/')
+            ? relativePath
+            : `/${relativePath}`;
+        return `${url.origin}${path}`;
+    } catch {
+        return relativePath;
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.spec.ts b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.spec.ts
index 9bc96671b..f1e5bdec6 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.spec.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.spec.ts
@@ -429,12 +429,12 @@ describe('StalkerSearchComponent result paging', () => {
             ...searchItems('page1', 3),
             { id: 'shared', name: 'Shared item' },
         ];
-        component.applySearchPageSuccess(1, pageOne, 7);
+        component.paging.applySearchPageSuccess(1, pageOne, 7);
         expect(component.searchResults()).toHaveLength(4);
         expect(component.searchHasMore()).toBe(true);
 
         // The portal shifted `shared` between pages — it must not duplicate.
-        component.applySearchPageSuccess(
+        component.paging.applySearchPageSuccess(
             2,
             [...searchItems('page2', 2), { id: 'shared', name: 'Shared item' }],
             7
@@ -442,31 +442,46 @@ describe('StalkerSearchComponent result paging', () => {
         expect(component.searchResults()).toHaveLength(6);
         expect(component.searchHasMore()).toBe(true);
 
-        component.applySearchPageSuccess(3, searchItems('page3', 1), 7);
+        component.paging.applySearchPageSuccess(3, searchItems('page3', 1), 7);
         expect(component.searchResults()).toHaveLength(7);
         expect(component.searchHasMore()).toBe(false);
     });
 
     it('advances past a page made only of parental-locked rows, but not past a repeated one', async () => {
-        component.applySearchPageSuccess(1, searchItems('page1', 3), 10);
-        const pageBefore = component.searchPage();
+        component.paging.applySearchPageSuccess(1, searchItems('page1', 3), 10);
+        const pageBefore = component.paging.searchPage();
 
         // Locked rows the list had not seen: schedule the next page.
-        component.advancePastWithheldPage(pageBefore, 0, 2, () => true);
+        component.paging.advancePastWithheldPage(pageBefore, 0, 2, () => true);
         await flushMicrotasks();
-        expect(component.searchPage()).toBe(pageBefore + 1);
+        expect(component.paging.searchPage()).toBe(pageBefore + 1);
 
         // A page with visible rows, or one adding no new withheld ids, or a
         // request that is no longer current: stay put.
-        component.advancePastWithheldPage(pageBefore + 1, 1, 2, () => true);
-        component.advancePastWithheldPage(pageBefore + 1, 0, 0, () => true);
-        component.advancePastWithheldPage(pageBefore + 1, 0, 2, () => false);
+        component.paging.advancePastWithheldPage(
+            pageBefore + 1,
+            1,
+            2,
+            () => true
+        );
+        component.paging.advancePastWithheldPage(
+            pageBefore + 1,
+            0,
+            0,
+            () => true
+        );
+        component.paging.advancePastWithheldPage(
+            pageBefore + 1,
+            0,
+            2,
+            () => false
+        );
         await flushMicrotasks();
-        expect(component.searchPage()).toBe(pageBefore + 1);
+        expect(component.paging.searchPage()).toBe(pageBefore + 1);
     });
 
     it('drops withheld rows on screen at relock time, page 1 included', () => {
-        component.applySearchPageSuccess(
+        component.paging.applySearchPageSuccess(
             1,
             [
                 { id: 'news-1', name: 'News', category_id: '5' },
@@ -476,7 +491,7 @@ describe('StalkerSearchComponent result paging', () => {
         );
         expect(component.searchResults()).toHaveLength(2);
 
-        component.applyRelockToResults(new Set(['9']), 'vod');
+        component.paging.applyRelockToResults(new Set(['9']), 'vod');
 
         expect(component.searchResults().map((item) => item.id)).toEqual([
             'news-1',
@@ -509,46 +524,54 @@ describe('StalkerSearchComponent result paging', () => {
     });
 
     it('keeps paging past a page whose rows were all withheld by the parental lock', () => {
-        component.applySearchPageSuccess(1, searchItems('page1', 3), 10);
+        component.paging.applySearchPageSuccess(1, searchItems('page1', 3), 10);
         expect(component.searchHasMore()).toBe(true);
 
         // The portal sent rows, every one of them locked: no visible growth,
         // but not the end of the results either.
-        component.applySearchPageSuccess(2, [], 10, true);
+        component.paging.applySearchPageSuccess(2, [], 10, true);
         expect(component.searchResults()).toHaveLength(3);
         expect(component.searchHasMore()).toBe(true);
 
         // An actually empty page still ends it.
-        component.applySearchPageSuccess(3, [], 10, false);
+        component.paging.applySearchPageSuccess(3, [], 10, false);
         expect(component.searchHasMore()).toBe(false);
     });
 
     it('stops paging when a total-backed append makes no progress', () => {
-        component.applySearchPageSuccess(1, searchItems('page1', 3), 10);
+        component.paging.applySearchPageSuccess(1, searchItems('page1', 3), 10);
         expect(component.searchHasMore()).toBe(true);
 
         // The portal repeats page 1 under a larger claimed total — dedupe
         // yields no growth, which must still end the paging loop.
-        component.applySearchPageSuccess(2, searchItems('page1', 3), 10);
+        component.paging.applySearchPageSuccess(2, searchItems('page1', 3), 10);
         expect(component.searchResults()).toHaveLength(3);
         expect(component.searchHasMore()).toBe(false);
     });
 
     it('stops paging without a total once pages stop making progress', () => {
-        component.applySearchPageSuccess(1, searchItems('page1', 3), undefined);
+        component.paging.applySearchPageSuccess(
+            1,
+            searchItems('page1', 3),
+            undefined
+        );
         expect(component.searchHasMore()).toBe(true);
 
         // The portal ignores paging and repeats the same page — dedupe
         // yields no growth, which must terminate the loop.
-        component.applySearchPageSuccess(2, searchItems('page1', 3), undefined);
+        component.paging.applySearchPageSuccess(
+            2,
+            searchItems('page1', 3),
+            undefined
+        );
         expect(component.searchHasMore()).toBe(false);
     });
 
     it('keeps accumulated pages on a failed append and retries the SAME page', async () => {
-        component.applySearchPageSuccess(1, searchItems('page1', 3), 6);
+        component.paging.applySearchPageSuccess(1, searchItems('page1', 3), 6);
         expect(component.searchHasMore()).toBe(true);
 
-        component.applySearchPageFailure(2);
+        component.paging.applySearchPageFailure(2);
         // The failed append kept page 1 on screen and flagged the error.
         expect(component.searchResults()).toHaveLength(3);
         expect(component.searchAppendError()).toBe(true);
@@ -557,16 +580,16 @@ describe('StalkerSearchComponent result paging', () => {
         // The real resource never settles in this template-less harness —
         // substitute a deterministic stand-in for the guard checks.
         const reload = jest.fn(() => true);
-        Object.defineProperty(component, 'searchResultsResource', {
+        Object.defineProperty(component.paging, 'searchResultsResource', {
             configurable: true,
             value: { isLoading: () => false, reload },
         });
 
         // The next near-end must RETRY page 2 (page stays put, the error is
         // consumed) instead of advancing to page 3 and skipping results.
-        const pageBefore = component.searchPage();
+        const pageBefore = component.paging.searchPage();
         component.loadMoreSearchResults();
-        expect(component.searchPage()).toBe(pageBefore);
+        expect(component.paging.searchPage()).toBe(pageBefore);
         // Cleared synchronously, so a second near-end cannot re-enter the retry
         // while the connectivity-guard reset is still in flight.
         expect(component.searchAppendError()).toBe(false);
@@ -583,15 +606,15 @@ describe('StalkerSearchComponent result paging', () => {
 
         // With the error cleared, the following near-end advances normally.
         component.loadMoreSearchResults();
-        expect(component.searchPage()).toBe(pageBefore + 1);
+        expect(component.paging.searchPage()).toBe(pageBefore + 1);
         expect(reload).toHaveBeenCalledTimes(1);
     });
 
     it("clears the previous query's results when a fresh search fails", () => {
-        component.applySearchPageSuccess(1, searchItems('matrix', 3), 3);
+        component.paging.applySearchPageSuccess(1, searchItems('matrix', 3), 3);
         expect(component.searchResults()).toHaveLength(3);
 
-        component.applySearchPageFailure(1);
+        component.paging.applySearchPageFailure(1);
 
         expect(component.searchResults()).toHaveLength(0);
         expect(component.searchHasMore()).toBe(false);
@@ -644,11 +667,15 @@ describe('StalkerSearchComponent result paging', () => {
         // The loader calls this on every no-portal early return (deleted or
         // malformed playlist on a reused route, short term) so the previous
         // portal's cards cannot keep rendering under the new context.
-        component.applySearchPageSuccess(1, searchItems('portalA', 3), 6);
-        component.applySearchPageFailure(2);
+        component.paging.applySearchPageSuccess(
+            1,
+            searchItems('portalA', 3),
+            6
+        );
+        component.paging.applySearchPageFailure(2);
         expect(component.searchResults()).toHaveLength(3);
 
-        component.resetSearchAccumulator();
+        component.paging.resetSearchAccumulator();
 
         expect(component.searchResults()).toHaveLength(0);
         expect(component.searchHasMore()).toBe(false);
@@ -659,13 +686,17 @@ describe('StalkerSearchComponent result paging', () => {
         // Regression: /stalker/A/search -> /stalker/B/search reuses the
         // component; a surviving page number would append portal B's later
         // page onto portal A's results and skip B's first page.
-        Object.defineProperty(component, 'searchResultsResource', {
+        Object.defineProperty(component.paging, 'searchResultsResource', {
             configurable: true,
             value: { isLoading: () => false, reload: jest.fn(() => true) },
         });
-        component.applySearchPageSuccess(1, searchItems('portalA', 3), 6);
+        component.paging.applySearchPageSuccess(
+            1,
+            searchItems('portalA', 3),
+            6
+        );
         component.loadMoreSearchResults();
-        expect(component.searchPage()).toBe(2);
+        expect(component.paging.searchPage()).toBe(2);
 
         activePlaylist.set({
             _id: 'playlist|two',
@@ -674,7 +705,7 @@ describe('StalkerSearchComponent result paging', () => {
             macAddress: '00:1A:79:00:00:02',
         });
 
-        expect(component.searchPage()).toBe(1);
+        expect(component.paging.searchPage()).toBe(1);
         expect(component.searchScrollResetKey()).toContain('playlist|two');
     });
 });
diff --git a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts
index 15fc9eaea..0c2a71fd6 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-search/stalker-search.component.ts
@@ -4,8 +4,6 @@ import {
     computed,
     effect,
     inject,
-    linkedSignal,
-    resource,
     signal,
     untracked,
     viewChild,
@@ -18,30 +16,24 @@ import { MatSnackBar } from '@angular/material/snack-bar';
 import { ActivatedRoute } from '@angular/router';
 import { TranslatePipe, TranslateService } from '@ngx-translate/core';
 import {
-    executeStalkerRequest,
     StalkerPortalRepairService,
     StalkerSessionService,
-    stalkerWithheldRowKey,
-    withoutWithheldStalkerItems,
 } from '@iptvnator/portal/stalker/data-access';
 import {
     DataService,
     ParentalLockService,
     PlaylistsService,
-    resetHostConnectivityGuard,
 } from '@iptvnator/services';
 import {
     ALL_CATEGORIES_WITHHELD,
     PlaybackPositionData,
     ResolvedPortalPlayback,
-    StalkerPortalActions,
     VodDetailsItem,
 } from '@iptvnator/shared/interfaces';
 import type { PlaybackFallbackRequest } from '@iptvnator/ui/playback';
 import { ContentCardComponent } from '@iptvnator/portal/shared/ui';
 import { SearchLayoutComponent } from '@iptvnator/portal/shared/ui';
 import { StalkerInlineDetailComponent } from '../stalker-inline-detail/stalker-inline-detail.component';
-import { StalkerContentTypes } from '@iptvnator/portal/stalker/data-access';
 import { StalkerStore } from '@iptvnator/portal/stalker/data-access';
 import { PlaylistContextFacade } from '@iptvnator/playlist/shared/util';
 import {
@@ -71,7 +63,8 @@ import {
 import { StalkerVodPlaybackController } from '../stalker-vod-playback-controller';
 import { createPlaybackSessionKey } from '@iptvnator/playback/util';
 import { createStalkerVodDetailActions } from '../stalker-vod-detail-actions';
-import { isStalkerSearchRequestCurrent } from './stalker-search-request.util';
+import { StalkerSearchPagingController } from './stalker-search-paging.controller';
+import type { StalkerSearchContentType } from './stalker-search-results.util';
 
 interface StalkerFilter {
     key: StalkerSearchContentType;
@@ -79,34 +72,6 @@ interface StalkerFilter {
     translationKey: string;
 }
 
-type StalkerSearchContentType = 'vod' | 'series';
-
-interface StalkerSearchResponse {
-    js?: {
-        data?: StalkerVodSource[];
-        total_items?: number;
-    };
-    message?: string;
-    status?: number;
-}
-
-/** Portals can shift items between pages mid-append — drop duplicate ids. */
-function dedupeSearchResults(items: StalkerVodSource[]): StalkerVodSource[] {
-    const seenIds = new Set<string>();
-    return items.filter((item) => {
-        const id =
-            item.id === undefined || item.id === null ? null : String(item.id);
-        if (id === null) {
-            return true;
-        }
-        if (seenIds.has(id)) {
-            return false;
-        }
-        seenIds.add(id);
-        return true;
-    });
-}
-
 @Component({
     selector: 'app-stalker-search',
     imports: [
@@ -127,15 +92,6 @@ export class StalkerSearchComponent {
     private readonly location = inject(Location);
     private readonly dataService = inject(DataService);
     private readonly parentalLock = inject(ParentalLockService);
-    /** Lock version the accumulated results were built under. */
-    private searchResultsLockVersion: number | null = null;
-    /**
-     * Withheld row ids seen for the current search identity. A page adding
-     * only new withheld ids is still progress and is skipped automatically;
-     * a page adding nothing new is the end of the results.
-     */
-    private searchWithheldKey = '';
-    private readonly searchWithheldIds = new Set<string>();
     private readonly playlistContext = inject(PlaylistContextFacade);
     private readonly playlistService = inject(PlaylistsService);
     readonly externalPlayback = inject(PORTAL_EXTERNAL_PLAYBACK);
@@ -235,309 +191,28 @@ export class StalkerSearchComponent {
         () => this.favoritesRefresh.refreshVersion()
     );
 
-    /**
-     * Portal page for the current term+filter+portal; resets when any of
-     * them changes. The playlist belongs to the identity: Angular reuses the
-     * search route across `/stalker/A/search` -> `/stalker/B/search`, and a
-     * surviving page number would append portal B's later page onto portal
-     * A's accumulated results while skipping B's first page.
-     */
-    readonly searchPage = linkedSignal({
-        source: () => ({
-            term: this.searchTerm(),
-            type: this.selectedFilterType(),
-            playlistId: this.currentPlaylist()?._id ?? null,
-        }),
-        computation: () => 1,
+    /** Result paging: the portal page, the accumulated list and its flags. */
+    readonly paging = new StalkerSearchPagingController({
+        searchTerm: this.searchTerm,
+        selectedFilterType: this.selectedFilterType,
+        currentPlaylist: this.currentPlaylist,
+        dataService: this.dataService,
+        parentalLock: this.parentalLock,
+        stalkerSession: this.stalkerSession,
+        portalRepair: this.portalRepair,
+        logger: this.logger,
+        closeWithheldDetail: (withheldCategoryIds) =>
+            this.closeWithheldDetail(withheldCategoryIds),
     });
-    /** Pages accumulated into one continuous, deduplicated result list. */
-    private readonly accumulatedSearchResults = signal<StalkerVodSource[]>([]);
-    readonly searchResults = this.accumulatedSearchResults.asReadonly();
-    readonly searchHasMore = signal(false);
-    /**
-     * A failed append page. The next near-end RETRIES that page instead of
-     * advancing — incrementing past it would silently omit its results.
-     */
-    readonly searchAppendError = signal(false);
-
-    readonly searchResultsResource = resource({
-        params: () => ({
-            contentType: this.selectedFilterType(),
-            search: this.searchTerm(),
-            page: this.searchPage(),
-            playlistId: this.currentPlaylist()?._id ?? null,
-            action: StalkerPortalActions.GetOrderedList,
-            // Lock/unlock re-fires the search: withheld rows are dropped at
-            // page time, so the results must be rebuilt when they change.
-            parentalLockVersion: this.parentalLock.version(),
-        }),
-        loader: async ({ params }) => {
-            if (params.search.length < 3) {
-                this.resetSearchAccumulator();
-                return [];
-            }
-            const playlist = this.currentPlaylist();
-            if (!playlist) {
-                // A reused route can land on a deleted/unresolved portal —
-                // the previous portal's cards must not keep rendering.
-                this.resetSearchAccumulator();
-                return [];
-            }
-            const { portalUrl, macAddress } = playlist;
-            if (!portalUrl || !macAddress) {
-                this.resetSearchAccumulator();
-                return [];
-            }
-            const contentType = params.contentType;
-            // The dedicated search route has no category guard, so it filters
-            // the portal's rows itself: a locked genre's title must not reach
-            // the grid, its detail or playback through search.
-            const withheldCategoryIds: ReadonlySet<string> =
-                !this.parentalLock.active()
-                    ? new Set<string>()
-                    : this.parentalLock.withholdsEverything?.()
-                      ? ALL_CATEGORIES_WITHHELD
-                      : new Set(
-                            this.parentalLock.lockedStalkerIds(
-                                playlist._id,
-                                contentType
-                            )
-                        );
-            const lockVersionChanged =
-                this.searchResultsLockVersion !== null &&
-                this.searchResultsLockVersion !== params.parentalLockVersion;
-            this.searchResultsLockVersion = params.parentalLockVersion;
-            if (lockVersionChanged) {
-                this.applyRelockToResults(withheldCategoryIds, contentType);
-            }
-            if (lockVersionChanged && params.page > 1) {
-                // A lock flip past page 1: rebuild from page 1 rather than
-                // appending to pages accumulated under the old lock state.
-                this.searchPage.set(1);
-                return this.accumulatedSearchResults();
-            }
-            const withheldKey = JSON.stringify([
-                params.playlistId,
-                contentType,
-                params.search,
-                params.parentalLockVersion,
-            ]);
-            if (params.page === 1 || this.searchWithheldKey !== withheldKey) {
-                this.searchWithheldKey = withheldKey;
-                this.searchWithheldIds.clear();
-            }
-
-            // Mirror the catalog request shape: many Ministra portals
-            // return an empty list for get_ordered_list without the
-            // category/genre/sortby params the STB client always sends.
-            // `max_page_items` is a HINT — plenty of portals ignore it and
-            // return their own page size, which is why paging cannot rely
-            // on it (progress and `total_items` decide hasMore instead).
-            const requestParams: Record<string, string | number> = {
-                action: StalkerContentTypes[contentType].getContentAction,
-                type: contentType,
-                sortby: 'added',
-                search: params.search,
-                p: params.page,
-                max_page_items: 100,
-                category: '*',
-                ...(contentType === 'vod' ? { genre: '0' } : {}),
-            };
-
-            // A stale response (term/filter/page/portal — or the parental
-            // lock — moved on while this page was in flight) must not clobber
-            // the accumulated list: the request is not aborted, and a
-            // pre-relock response was filtered with the pre-relock set.
-            const isCurrent = (): boolean =>
-                isStalkerSearchRequestCurrent(params, {
-                    search: this.searchTerm(),
-                    contentType: this.selectedFilterType(),
-                    page: this.searchPage(),
-                    playlistId: this.currentPlaylist()?._id ?? null,
-                    parentalLockVersion: this.parentalLock.version(),
-                });
-
-            try {
-                // executeStalkerRequest owns the portal-mode decision (shared
-                // predicate with URL fallback for legacy rows) and the lazy
-                // portal repair, so search cannot drift from the catalog
-                // paths.
-                const response =
-                    await executeStalkerRequest<StalkerSearchResponse>(
-                        {
-                            dataService: this.dataService,
-                            stalkerSession: this.stalkerSession,
-                            portalRepair: this.portalRepair,
-                        },
-                        playlist,
-                        requestParams
-                    );
-                const rawItems = (response.js?.data || []).map(
-                    (item: StalkerVodSource) =>
-                        this.processItemUrls(item, portalUrl)
-                );
-                const items = withoutWithheldStalkerItems(
-                    rawItems,
-                    contentType,
-                    withheldCategoryIds
-                );
-                // Before the withheld-id bookkeeping: a stale page must not
-                // pre-record ids into a set a newer relock request cleared,
-                // or that request's page counts no new withheld rows and
-                // stops paging short of later visible matches.
-                if (!isCurrent()) {
-                    return items;
-                }
-                let newWithheldCount = 0;
-                if (items.length < rawItems.length) {
-                    const kept = new Set(items);
-                    for (const item of rawItems) {
-                        const id = stalkerWithheldRowKey(item);
-                        if (
-                            !kept.has(item) &&
-                            !this.searchWithheldIds.has(id)
-                        ) {
-                            this.searchWithheldIds.add(id);
-                            newWithheldCount += 1;
-                        }
-                    }
-                }
-
-                const merged = this.applySearchPageSuccess(
-                    params.page,
-                    items,
-                    response.js?.total_items,
-                    // A page made only of withheld rows still is a page the
-                    // portal served; judge progress on what it sent.
-                    rawItems.length > 0 &&
-                        (items.length > 0 || newWithheldCount > 0)
-                );
-                this.advancePastWithheldPage(
-                    params.page,
-                    items.length,
-                    newWithheldCount,
-                    isCurrent
-                );
-                return merged;
-            } catch (error) {
-                this.logger.warn('Stalker search page failed', {
-                    page: params.page,
-                    error,
-                });
-                if (!isCurrent()) {
-                    return this.accumulatedSearchResults();
-                }
-
-                return this.applySearchPageFailure(params.page);
-            }
-        },
-    });
-
-    /**
-     * Empties the accumulator and every paging flag — used whenever there is
-     * no searchable portal (short term, missing playlist, malformed row).
-     */
-    resetSearchAccumulator(): void {
-        this.accumulatedSearchResults.set([]);
-        this.searchHasMore.set(false);
-        this.searchAppendError.set(false);
-    }
-
-    /** Merges a successful portal page into the accumulated result list. */
-    applySearchPageSuccess(
-        page: number,
-        items: StalkerVodSource[],
-        totalItems: number | undefined,
-        pageHadRows: boolean = items.length > 0
-    ): StalkerVodSource[] {
-        const previous = page === 1 ? [] : this.accumulatedSearchResults();
-        const merged =
-            page === 1 ? items : dedupeSearchResults([...previous, ...items]);
-        // Paging continues only while pages make progress — with OR without
-        // a reported total. Dedup after mid-list portal mutations can leave
-        // the unique list permanently shorter than total_items, and a
-        // repeated page dedupes to no growth; either way a no-progress
-        // append is the practical end of the results. A page whose rows were
-        // all withheld by the parental lock counts as progress too.
-        const withheldRows = pageHadRows && items.length === 0;
-        const madeProgress =
-            page === 1 || merged.length > previous.length || withheldRows;
-        this.searchHasMore.set(
-            madeProgress &&
-                (typeof totalItems === 'number' && totalItems >= 0
-                    ? merged.length < totalItems
-                    : pageHadRows)
-        );
-        this.searchAppendError.set(false);
-        this.accumulatedSearchResults.set(merged);
-        return merged;
-    }
-
-    /**
-     * A failed FRESH search (page 1) must not keep rendering the previous
-     * query's cards; a failed append keeps the accumulated pages and flags
-     * the error so the next near-end retries this page instead of advancing.
-     */
-    applySearchPageFailure(page: number): StalkerVodSource[] {
-        if (page === 1) {
-            this.accumulatedSearchResults.set([]);
-            this.searchHasMore.set(false);
-            this.searchAppendError.set(false);
-            return [];
-        }
-
-        this.searchAppendError.set(true);
-        return this.accumulatedSearchResults();
-    }
-
-    /**
-     * Result-set identity for the layout's near-end latch and auto-fill
-     * budget — term, filter, and portal, mirroring the paging identity.
-     */
-    readonly searchScrollResetKey = computed(() =>
-        [
-            this.searchTerm(),
-            this.selectedFilterType(),
-            this.currentPlaylist()?._id ?? '',
-        ].join('|')
-    );
-
-    readonly isInitialSearchLoading = computed(
-        () => this.searchResultsResource.isLoading() && this.searchPage() === 1
-    );
-    readonly isAppendingSearchResults = computed(
-        () => this.searchResultsResource.isLoading() && this.searchPage() > 1
-    );
+    readonly searchResults = this.paging.searchResults;
+    readonly searchHasMore = this.paging.searchHasMore;
+    readonly searchAppendError = this.paging.searchAppendError;
+    readonly searchScrollResetKey = this.paging.searchScrollResetKey;
+    readonly isInitialSearchLoading = this.paging.isInitialSearchLoading;
+    readonly isAppendingSearchResults = this.paging.isAppendingSearchResults;
 
     loadMoreSearchResults(): void {
-        if (this.searchResultsResource.isLoading() || !this.searchHasMore()) {
-            return;
-        }
-
-        if (this.searchAppendError()) {
-            // Retry the SAME page — advancing would permanently omit it.
-            void this.retrySearchPage();
-            return;
-        }
-
-        this.searchPage.update((page) => page + 1);
-    }
-
-    /**
-     * Two failed search pages are exactly what opens the main process'
-     * connectivity guard, so the reset has to precede the reload — otherwise
-     * this retry fast-fails without contacting a portal that may have
-     * recovered, and keeps repeating the same error until the window expires.
-     */
-    private async retrySearchPage(): Promise<void> {
-        // Clear the flag synchronously: awaiting first would leave this branch
-        // re-enterable, and the next `nearEnd` event would fire a second retry.
-        this.searchAppendError.set(false);
-        await resetHostConnectivityGuard(
-            this.dataService,
-            this.currentPlaylist()?.portalUrl
-        );
-        this.searchResultsResource.reload();
+        this.paging.loadMoreSearchResults();
     }
 
     readonly isSelectedVodFavorite = signal<boolean>(false);
@@ -713,59 +388,11 @@ export class StalkerSearchComponent {
         });
     }
 
-    /**
-     * The infinite scroll gives up after a few loads that add no height, so
-     * a run of pages made only of parental-locked rows must advance by
-     * itself until a visible row (or the real end) is reached. Only a page
-     * that added withheld ids not seen before counts — a stalled portal
-     * repeating the same locked rows must still end the loop.
-     */
-    advancePastWithheldPage(
-        page: number,
-        visibleCount: number,
-        newWithheldCount: number,
-        isCurrent: () => boolean
-    ): void {
-        if (
-            visibleCount > 0 ||
-            newWithheldCount === 0 ||
-            !this.searchHasMore()
-        ) {
-            return;
-        }
-        queueMicrotask(() => {
-            if (isCurrent()) {
-                this.searchPage.set(page + 1);
-            }
-        });
-    }
-
     /**
      * Closes the open detail when its genre is withheld by the parental
      * lock (Lock now, idle relock): the title, its playback actions and the
      * store's selected item must not outlive the list row.
      */
-    /**
-     * A lock change reached the results on screen, which were read under
-     * the old lock state: close an open detail of a now-withheld genre (the
-     * list hiding it is not enough) and drop the withheld rows NOW, before
-     * the replacement page is awaited — on page 1 too, or they stay
-     * clickable while (or, if it hangs, after) that request is pending.
-     */
-    applyRelockToResults(
-        withheldCategoryIds: ReadonlySet<string>,
-        contentType: Parameters<typeof withoutWithheldStalkerItems>[1]
-    ): void {
-        this.closeWithheldDetail(withheldCategoryIds);
-        this.accumulatedSearchResults.set(
-            withoutWithheldStalkerItems(
-                this.accumulatedSearchResults(),
-                contentType,
-                withheldCategoryIds
-            )
-        );
-    }
-
     closeWithheldDetail(withheldCategoryIds: ReadonlySet<string>): void {
         const details = this.itemDetails();
         if (!details) {
@@ -871,41 +498,6 @@ export class StalkerSearchComponent {
         );
     }
 
-    private processItemUrls(
-        item: StalkerVodSource,
-        portalUrl: string
-    ): StalkerVodSource {
-        const processed = { ...item };
-
-        if (processed.screenshot_uri) {
-            processed.screenshot_uri = this.makeAbsoluteUrl(
-                portalUrl,
-                processed.screenshot_uri
-            );
-        }
-
-        return processed;
-    }
-
-    private makeAbsoluteUrl(baseUrl: string, relativePath: string): string {
-        if (!relativePath) return '';
-        if (
-            relativePath.startsWith('http://') ||
-            relativePath.startsWith('https://')
-        ) {
-            return relativePath;
-        }
-        try {
-            const url = new URL(baseUrl);
-            const path = relativePath.startsWith('/')
-                ? relativePath
-                : `/${relativePath}`;
-            return `${url.origin}${path}`;
-        } catch {
-            return relativePath;
-        }
-    }
-
     readonly vodDetailActions = createStalkerVodDetailActions({
         resolvePlayback: (cmd, title, thumbnail, startTime) =>
             this.stalkerStore.resolveVodPlayback(
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-id.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-id.ts
new file mode 100644
index 000000000..877482424
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-id.ts
@@ -0,0 +1,12 @@
+/**
+ * The numeric series id of a Stalker item id: the part before the first `:`
+ * when the id carries a suffix. An empty or non-numeric id resolves to 0,
+ * which callers treat as "no series".
+ */
+export function toStalkerSeriesId(id: string | number): number {
+    const raw = String(id ?? '').trim();
+    if (!raw) return 0;
+    const primary = raw.includes(':') ? raw.split(':')[0] : raw;
+    const parsed = Number(primary);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-position-queue.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-position-queue.ts
new file mode 100644
index 000000000..2a30fc75b
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-position-queue.ts
@@ -0,0 +1,187 @@
+import type { PlaybackPositionData } from '@iptvnator/shared/interfaces';
+
+/** The playlist and series one generation of position reads and writes belongs to. */
+export interface StalkerSeriesPositionContext {
+    readonly generation: number;
+    readonly playlistId: string;
+    readonly seriesXtreamId: number;
+    readonly mutationKey: string;
+}
+
+/** What the queue needs from the owner of the position rows. */
+export interface StalkerSeriesPositionQueueHost {
+    /** Whether the page still shows the playlist and series of `context`. */
+    readonly isShown: (context: StalkerSeriesPositionContext) => boolean;
+    /** Reads the persisted position rows of `context`. */
+    readonly read: (
+        context: StalkerSeriesPositionContext
+    ) => Promise<PlaybackPositionData[]>;
+    /** Takes over rows read for a context that is still the active one. */
+    readonly publish: (
+        context: StalkerSeriesPositionContext,
+        positions: PlaybackPositionData[]
+    ) => void;
+}
+
+/**
+ * Orders the position reads and writes of the Stalker series view. Writes of
+ * one playlist/series run one after another; a read waits for the writes
+ * queued before it, and its answer is dropped once a newer read or write
+ * started or the page moved on to another series. A write that overtakes a
+ * read still in flight re-reads the rows after the queue drained.
+ */
+export class StalkerSeriesPositionQueue {
+    private activeContext: StalkerSeriesPositionContext | null = null;
+    private contextGeneration = 0;
+    private readonly mutationQueues = new Map<string, Promise<void>>();
+    private readonly pendingLoads = new Map<
+        StalkerSeriesPositionContext,
+        Set<number>
+    >();
+    private readonly reloadKeys = new Set<string>();
+    private loadGeneration = 0;
+
+    constructor(private readonly host: StalkerSeriesPositionQueueHost) {}
+
+    /** Makes `playlistId`/`seriesXtreamId` the series reads and writes apply to. */
+    activate(
+        playlistId: string,
+        seriesXtreamId: number
+    ): StalkerSeriesPositionContext {
+        const context: StalkerSeriesPositionContext = {
+            generation: ++this.contextGeneration,
+            playlistId,
+            seriesXtreamId,
+            mutationKey: JSON.stringify([playlistId, seriesXtreamId]),
+        };
+        this.activeContext = context;
+        return context;
+    }
+
+    /** No series is shown: retires the active context and every read in flight. */
+    deactivate(): void {
+        this.activeContext = null;
+        this.contextGeneration++;
+        this.loadGeneration++;
+    }
+
+    isActive(context: StalkerSeriesPositionContext): boolean {
+        const activeContext = this.activeContext;
+        return (
+            activeContext === context &&
+            activeContext.generation === context.generation &&
+            this.host.isShown(context)
+        );
+    }
+
+    /** The active context when it belongs to `playlistId` (and `seriesXtreamId`, if given). */
+    mutationContext(
+        playlistId: string,
+        seriesXtreamId?: number | null
+    ): StalkerSeriesPositionContext | null {
+        const context = this.activeContext;
+        if (
+            !context ||
+            context.playlistId !== playlistId ||
+            (seriesXtreamId != null &&
+                context.seriesXtreamId !== seriesXtreamId)
+        ) {
+            return null;
+        }
+        return context;
+    }
+
+    async load(context: StalkerSeriesPositionContext): Promise<void> {
+        const generation = ++this.loadGeneration;
+        this.trackPendingLoad(context, generation);
+        try {
+            await this.waitForMutations(context.mutationKey);
+
+            if (generation !== this.loadGeneration || !this.isActive(context)) {
+                return;
+            }
+
+            const positions = await this.host.read(context);
+
+            if (generation !== this.loadGeneration || !this.isActive(context)) {
+                return;
+            }
+
+            this.host.publish(context, positions);
+        } finally {
+            this.untrackPendingLoad(context, generation);
+        }
+    }
+
+    enqueue(
+        context: StalkerSeriesPositionContext,
+        operation: () => Promise<void>
+    ): Promise<void> {
+        if (this.hasCurrentPendingLoad(context)) {
+            this.reloadKeys.add(context.mutationKey);
+        }
+        this.loadGeneration++;
+        const previous = this.waitForMutations(context.mutationKey);
+        const result = previous.then(operation);
+        const barrier = result.then(
+            () => undefined,
+            () => undefined
+        );
+        this.mutationQueues.set(context.mutationKey, barrier);
+        void barrier.then(() => {
+            if (this.mutationQueues.get(context.mutationKey) === barrier) {
+                this.mutationQueues.delete(context.mutationKey);
+                this.reloadAfterMutations(context.mutationKey);
+            }
+        });
+        return result;
+    }
+
+    private waitForMutations(mutationKey: string): Promise<void> {
+        return this.mutationQueues.get(mutationKey) ?? Promise.resolve();
+    }
+
+    private trackPendingLoad(
+        context: StalkerSeriesPositionContext,
+        generation: number
+    ): void {
+        const generations = this.pendingLoads.get(context) ?? new Set<number>();
+        generations.add(generation);
+        this.pendingLoads.set(context, generations);
+    }
+
+    private untrackPendingLoad(
+        context: StalkerSeriesPositionContext,
+        generation: number
+    ): void {
+        const generations = this.pendingLoads.get(context);
+        generations?.delete(generation);
+        if (generations?.size === 0) {
+            this.pendingLoads.delete(context);
+        }
+    }
+
+    private hasCurrentPendingLoad(
+        context: StalkerSeriesPositionContext
+    ): boolean {
+        return Boolean(
+            this.pendingLoads.get(context)?.has(this.loadGeneration)
+        );
+    }
+
+    private reloadAfterMutations(mutationKey: string): void {
+        if (!this.reloadKeys.delete(mutationKey)) {
+            return;
+        }
+        const context = this.activeContext;
+        if (
+            !context ||
+            context.mutationKey !== mutationKey ||
+            !this.isActive(context) ||
+            this.hasCurrentPendingLoad(context)
+        ) {
+            return;
+        }
+        void this.load(context);
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-positions.service.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-positions.service.ts
new file mode 100644
index 000000000..ee3004f93
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-positions.service.ts
@@ -0,0 +1,331 @@
+import { Injectable, Signal, inject, signal, untracked } from '@angular/core';
+import {
+    PORTAL_PLAYBACK_POSITIONS,
+    createLogger,
+} from '@iptvnator/portal/shared/util';
+import {
+    StalkerStore,
+    type StalkerSelectedVodItem,
+} from '@iptvnator/portal/stalker/data-access';
+import type {
+    PlaybackPositionData,
+    XtreamSerieEpisode,
+} from '@iptvnator/shared/interfaces';
+import { toStalkerSeriesId } from './stalker-series-id';
+import {
+    clearStalkerSeriesPosition,
+    reconcileStalkerSeriesPositions,
+    saveStalkerSeriesPosition,
+    StalkerSeriesPositionPartialSaveError,
+} from './stalker-series-position-compatibility';
+import { StalkerSeriesPositionQueue } from './stalker-series-position-queue';
+
+interface StalkerSeriesPositionsBindings {
+    readonly displayItem: Signal<StalkerSelectedVodItem | null>;
+    readonly mappedSeasons: Signal<Record<string, XtreamSerieEpisode[]>>;
+}
+
+/**
+ * Saved episode positions of the series the Stalker series view shows: the
+ * rows read from the repository, their mapping onto the episodes on the page
+ * (scoped rows plus compatible legacy promotions) and the writes that keep
+ * both in step. Component-scoped (provide it in the component's `providers`).
+ */
+@Injectable()
+export class StalkerSeriesPositionsService {
+    private readonly stalkerStore = inject(StalkerStore);
+    private readonly playbackPositions = inject(PORTAL_PLAYBACK_POSITIONS);
+    private readonly migrationPlaybackPositions = {
+        savePlaybackPosition: (
+            playlistId: string,
+            data: PlaybackPositionData
+        ) =>
+            this.playbackPositions.savePlaybackPositionOrThrow(
+                playlistId,
+                data
+            ),
+        clearPlaybackPosition: (
+            playlistId: string,
+            contentXtreamId: number,
+            contentType: 'vod' | 'episode'
+        ) =>
+            this.playbackPositions.clearPlaybackPositionOrThrow(
+                playlistId,
+                contentXtreamId,
+                contentType
+            ),
+    };
+    private readonly logger = createLogger('StalkerSeriesView');
+    private readonly bindings = signal<StalkerSeriesPositionsBindings | null>(
+        null
+    );
+    readonly episodePlaybackPositions = signal<
+        Map<number, PlaybackPositionData>
+    >(new Map());
+    readonly rawSeriesPositions = signal<readonly PlaybackPositionData[]>([]);
+    /**
+     * `playlistId:seriesId` once the persisted positions for the shown
+     * series have been READ (a failed read leaves it null): the dashboard
+     * resume handoff must not start an episode from the beginning because
+     * the offsets have not arrived yet.
+     */
+    readonly seriesPositionsLoadedKey = signal<string | null>(null);
+    private readonly legacyPositionByTrackingId = signal<
+        Map<number, PlaybackPositionData>
+    >(new Map());
+    private readonly queue = new StalkerSeriesPositionQueue({
+        isShown: (context) =>
+            this.stalkerStore.currentPlaylist()?._id === context.playlistId &&
+            this.shownSeriesId() === context.seriesXtreamId,
+        read: (context) =>
+            this.playbackPositions.getSeriesPlaybackPositions(
+                context.playlistId,
+                context.seriesXtreamId
+            ),
+        publish: (context, positions) => {
+            this.rawSeriesPositions.set(positions);
+            this.seriesPositionsLoadedKey.set(
+                this.seriesPositionsKey(
+                    context.playlistId,
+                    context.seriesXtreamId
+                )
+            );
+        },
+    });
+
+    bind(bindings: StalkerSeriesPositionsBindings): void {
+        this.bindings.set(bindings);
+    }
+
+    /**
+     * Starts over for the series on screen: drops what the previous series
+     * left behind and reads the persisted rows. Reads the shown item and the
+     * playlist, so an `effect` calling it re-runs when either changes.
+     */
+    loadShownSeries(): void {
+        const item = this.displayItem();
+        const playlist = this.stalkerStore.currentPlaylist();
+        const normalizedSeriesId = toStalkerSeriesId(item?.id ?? 0);
+        if (item && playlist?._id && normalizedSeriesId > 0) {
+            this.logger.debug('Loading positions for series', {
+                id: item.id,
+                seriesId: normalizedSeriesId,
+                isSeries: item.is_series,
+            });
+            this.rawSeriesPositions.set([]);
+            this.seriesPositionsLoadedKey.set(null);
+            this.episodePlaybackPositions.set(new Map());
+            this.legacyPositionByTrackingId.set(new Map());
+            const context = this.queue.activate(
+                playlist._id,
+                normalizedSeriesId
+            );
+            void this.queue.load(context);
+        } else {
+            this.queue.deactivate();
+        }
+    }
+
+    /**
+     * Maps the raw series position rows onto the currently mapped episodes
+     * (scoped rows plus compatible legacy promotions). Runs reactively from
+     * the component's constructor effect, and synchronously from the
+     * series-level watch toggle right after it hydrates lazy seasons — the
+     * effect only re-runs on the next change-detection tick, and enqueuing
+     * the batch against the stale maps would miss the hydrated episodes'
+     * legacy rows (an unwatch would leave rows behind that a later reconcile
+     * resurrects as watched).
+     */
+    applyReconciledSeriesPositions(): void {
+        const item = this.displayItem();
+        const playlistId = this.stalkerStore.currentPlaylist()?._id;
+        const seriesXtreamId = toStalkerSeriesId(item?.id ?? 0);
+        const rawSeriesPositions = this.rawSeriesPositions();
+        const episodesBySeason = this.bindings()?.mappedSeasons() ?? {};
+
+        if (!item || !playlistId || seriesXtreamId <= 0) {
+            if (rawSeriesPositions.length > 0) {
+                this.rawSeriesPositions.set([]);
+            }
+            if (this.episodePlaybackPositions().size > 0) {
+                this.episodePlaybackPositions.set(new Map());
+            }
+            if (this.legacyPositionByTrackingId().size > 0) {
+                this.legacyPositionByTrackingId.set(new Map());
+            }
+            return;
+        }
+
+        const reconciled = reconcileStalkerSeriesPositions({
+            seriesXtreamId,
+            episodesBySeason,
+            seriesPositions: rawSeriesPositions,
+        });
+        if (
+            rawSeriesPositions.length === 0 &&
+            reconciled.positionsByTrackingId.size === 0 &&
+            untracked(() => this.episodePlaybackPositions().size) > 0
+        ) {
+            return;
+        }
+        this.episodePlaybackPositions.set(reconciled.positionsByTrackingId);
+        this.legacyPositionByTrackingId.set(
+            reconciled.legacyPositionByTrackingId
+        );
+    }
+
+    seriesPositionsKey(playlistId: string, seriesXtreamId: number): string {
+        return `${playlistId}:${seriesXtreamId}`;
+    }
+
+    persistSeriesPosition(
+        playlistId: string,
+        position: PlaybackPositionData
+    ): Promise<void> {
+        const context = this.queue.mutationContext(
+            playlistId,
+            position.seriesXtreamId
+        );
+        if (!context) {
+            return Promise.resolve();
+        }
+        const legacyPosition = this.legacyPositionByTrackingId().get(
+            position.contentXtreamId
+        );
+        return this.queue.enqueue(context, async () => {
+            let clearedLegacy: boolean;
+            try {
+                clearedLegacy = await saveStalkerSeriesPosition({
+                    repository: this.migrationPlaybackPositions,
+                    playlistId,
+                    position,
+                    legacyPosition,
+                });
+            } catch (error) {
+                if (
+                    error instanceof StalkerSeriesPositionPartialSaveError &&
+                    this.queue.isActive(context)
+                ) {
+                    this.publishSavedSeriesPosition(
+                        position,
+                        legacyPosition,
+                        false
+                    );
+                }
+                throw error;
+            }
+            if (!this.queue.isActive(context)) {
+                return;
+            }
+            this.publishSavedSeriesPosition(
+                position,
+                legacyPosition,
+                clearedLegacy
+            );
+        });
+    }
+
+    clearSeriesPosition(
+        playlistId: string,
+        contentXtreamId: number
+    ): Promise<void> {
+        const context = this.queue.mutationContext(playlistId);
+        if (!context) {
+            return Promise.resolve();
+        }
+        const position = this.episodePlaybackPositions().get(
+            contentXtreamId
+        ) ?? {
+            contentXtreamId,
+            contentType: 'episode',
+            positionSeconds: 0,
+            playlistId,
+            seriesXtreamId: context.seriesXtreamId,
+        };
+        const legacyPosition =
+            this.legacyPositionByTrackingId().get(contentXtreamId);
+        return this.queue.enqueue(context, async () => {
+            const clearedLegacy = await clearStalkerSeriesPosition({
+                repository: this.migrationPlaybackPositions,
+                playlistId,
+                position,
+                legacyPosition,
+            });
+            if (!this.queue.isActive(context)) {
+                return;
+            }
+            this.publishClearedSeriesPosition(
+                contentXtreamId,
+                legacyPosition,
+                clearedLegacy
+            );
+        });
+    }
+
+    private displayItem(): StalkerSelectedVodItem | null {
+        return this.bindings()?.displayItem() ?? null;
+    }
+
+    private shownSeriesId(): number {
+        return toStalkerSeriesId(this.displayItem()?.id ?? 0);
+    }
+
+    private publishSavedSeriesPosition(
+        position: PlaybackPositionData,
+        legacyPosition: PlaybackPositionData | undefined,
+        clearedLegacy: boolean
+    ): void {
+        const removedTrackingIds = new Set([position.contentXtreamId]);
+        if (clearedLegacy && legacyPosition) {
+            removedTrackingIds.add(legacyPosition.contentXtreamId);
+            const legacyPositions = new Map(this.legacyPositionByTrackingId());
+            legacyPositions.delete(position.contentXtreamId);
+            this.legacyPositionByTrackingId.set(legacyPositions);
+        }
+
+        this.rawSeriesPositions.set([
+            ...this.rawSeriesPositions().filter(
+                (candidate) =>
+                    !removedTrackingIds.has(candidate.contentXtreamId)
+            ),
+            position,
+        ]);
+        this.updateEpisodePlaybackPosition(position);
+    }
+
+    private publishClearedSeriesPosition(
+        contentXtreamId: number,
+        legacyPosition: PlaybackPositionData | undefined,
+        clearedLegacy: boolean
+    ): void {
+        const removedTrackingIds = new Set([contentXtreamId]);
+        if (clearedLegacy && legacyPosition) {
+            removedTrackingIds.add(legacyPosition.contentXtreamId);
+            const legacyPositions = new Map(this.legacyPositionByTrackingId());
+            legacyPositions.delete(contentXtreamId);
+            this.legacyPositionByTrackingId.set(legacyPositions);
+        }
+
+        this.rawSeriesPositions.set(
+            this.rawSeriesPositions().filter(
+                (candidate) =>
+                    !removedTrackingIds.has(candidate.contentXtreamId)
+            )
+        );
+        this.removeEpisodePlaybackPosition(contentXtreamId);
+    }
+
+    private updateEpisodePlaybackPosition(
+        position: PlaybackPositionData
+    ): void {
+        const updated = new Map(this.episodePlaybackPositions());
+        updated.set(position.contentXtreamId, position);
+        this.episodePlaybackPositions.set(updated);
+    }
+
+    private removeEpisodePlaybackPosition(contentXtreamId: number): void {
+        const updated = new Map(this.episodePlaybackPositions());
+        updated.delete(contentXtreamId);
+        this.episodePlaybackPositions.set(updated);
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.spec.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.spec.ts
index d6937ca07..e27488ffc 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.spec.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.spec.ts
@@ -1,54 +1,30 @@
-import { signal } from '@angular/core';
-import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { ComponentFixture } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
-import { Router } from '@angular/router';
-import { MatSnackBar } from '@angular/material/snack-bar';
-import { TranslatePipe, TranslateService } from '@ngx-translate/core';
-import { MockPipe } from 'ng-mocks';
-import { SeasonContainerComponent } from '@iptvnator/ui/components';
-import {
-    PORTAL_EXTERNAL_PLAYBACK,
-    PORTAL_PLAYBACK_POSITIONS,
-    PORTAL_PLAYER,
-} from '@iptvnator/portal/shared/util';
-import {
-    StalkerStore,
-    StalkerVodSource,
-} from '@iptvnator/portal/stalker/data-access';
 import { PlaybackPositionData } from '@iptvnator/shared/interfaces';
-import { PortalInlinePlayerComponent } from '@iptvnator/ui/playback';
-import { TmdbEnrichmentService } from '@iptvnator/services';
-import { EMPTY, of } from 'rxjs';
-import { FavoritesButtonComponent } from '../stalker-favorites-button/stalker-favorites-button.component';
 import { StalkerSeriesViewComponent } from './stalker-series-view.component';
+import { createStalkerSeriesViewHarness } from './stalker-series-view.test-harness';
 
 import {
-    StubFavoritesButtonComponent,
     StubPortalInlinePlayerComponent,
     StubSeasonContainerComponent,
 } from './stalker-series-view.test-helpers';
 
 describe('StalkerSeriesViewComponent', () => {
     let fixture: ComponentFixture<StalkerSeriesViewComponent>;
-    const selectedContentType = signal<'series' | 'vod'>('series');
-    const selectedItem = signal<StalkerVodSource | null>(null);
-    const serialSeasonsResource = signal<unknown[]>([]);
-    const vodSeriesSeasonsResource = signal<unknown[]>([]);
-    const isSerialSeasonsLoading = signal(false);
-    const fetchVodSeriesEpisodes = jest.fn();
-    const resolveVodPlayback = jest.fn();
-    const getSeriesPlaybackPositions = jest.fn().mockResolvedValue([]);
-    const openResolvedPlayback = jest.fn();
-    const openExternalPlayback = jest.fn();
-    const isEmbeddedPlayer = jest.fn();
-    const tmdbGetSeason = jest.fn();
-    const fetchLinkToPlay = jest.fn();
-    const currentPlaylist = signal({
-        _id: 'stalker-1',
-        title: 'Living Room Portal',
-        portalUrl: 'https://stalker.example.test',
-        macAddress: '00:1A:79:12:34:56',
-    });
+    const {
+        selectedContentType,
+        selectedItem,
+        serialSeasonsResource,
+        vodSeriesSeasonsResource,
+        fetchVodSeriesEpisodes,
+        resolveVodPlayback,
+        openResolvedPlayback,
+        openExternalPlayback,
+        isEmbeddedPlayer,
+        fetchLinkToPlay,
+        currentPlaylist,
+        createFixture,
+    } = createStalkerSeriesViewHarness(() => jest.fn());
 
     async function stabilize(): Promise<void> {
         fixture.detectChanges();
@@ -63,184 +39,7 @@ describe('StalkerSeriesViewComponent', () => {
     }
 
     beforeEach(async () => {
-        selectedContentType.set('series');
-        selectedItem.set({
-            id: '30001',
-            cmd: '/media/file_30001.mpg',
-            info: {
-                name: 'Regular Series',
-                description: 'Series description',
-                movie_image: 'poster.jpg',
-            },
-        });
-        serialSeasonsResource.set([
-            {
-                id: 'season-1',
-                name: 'Season 1',
-                cmd: '/media/file_30001.mpg',
-                series: [1, 2],
-            },
-        ]);
-        vodSeriesSeasonsResource.set([]);
-        isSerialSeasonsLoading.set(false);
-        fetchVodSeriesEpisodes.mockReset();
-        resolveVodPlayback.mockReset();
-        resolveVodPlayback.mockImplementation(
-            async (
-                _cmd?: string,
-                title?: string,
-                thumbnail?: string,
-                _episodeNum?: number,
-                episodeId?: number,
-                startTime?: number
-            ) => ({
-                streamUrl: 'http://stalker.example/episode.mpg',
-                title: title ?? 'Regular Series',
-                thumbnail: thumbnail ?? 'poster.jpg',
-                startTime,
-                contentInfo: {
-                    playlistId: 'stalker-1',
-                    contentXtreamId:
-                        episodeId ?? Number(selectedItem()?.id ?? 0),
-                    contentType: episodeId ? 'episode' : 'vod',
-                    seriesXtreamId: episodeId
-                        ? Number(selectedItem()?.id ?? 0)
-                        : undefined,
-                },
-            })
-        );
-        getSeriesPlaybackPositions.mockClear();
-        getSeriesPlaybackPositions.mockResolvedValue([]);
-        openResolvedPlayback.mockClear();
-        openExternalPlayback.mockReset();
-        isEmbeddedPlayer.mockReset();
-        isEmbeddedPlayer.mockReturnValue(false);
-        tmdbGetSeason.mockReset();
-        tmdbGetSeason.mockResolvedValue({
-            overview: 'Season overview from TMDB',
-            episodes: [],
-        });
-        fetchLinkToPlay
-            .mockReset()
-            .mockResolvedValue('https://cdn.example.test/episode.mpg');
-        currentPlaylist.set({
-            _id: 'stalker-1',
-            title: 'Living Room Portal',
-            portalUrl: 'https://stalker.example.test',
-            macAddress: '00:1A:79:12:34:56',
-        });
-
-        await TestBed.configureTestingModule({
-            imports: [StalkerSeriesViewComponent],
-            providers: [
-                {
-                    provide: StalkerStore,
-                    useValue: {
-                        selectedItem,
-                        selectedContentType,
-                        currentPlaylist,
-                        getSerialSeasonsResource: () => serialSeasonsResource(),
-                        getVodSeriesSeasonsResource: () =>
-                            vodSeriesSeasonsResource(),
-                        isVodSeriesSeasonsLoading: signal(false),
-                        isSerialSeasonsLoading,
-                        fetchVodSeriesEpisodes,
-                        resolveVodPlayback,
-                        fetchLinkToPlay,
-                    },
-                },
-                {
-                    provide: PORTAL_EXTERNAL_PLAYBACK,
-                    useValue: {
-                        activeSession: signal(null),
-                    },
-                },
-                {
-                    provide: PORTAL_PLAYBACK_POSITIONS,
-                    useValue: {
-                        getSeriesPlaybackPositions,
-                        savePlaybackPosition: jest.fn(),
-                        clearPlaybackPosition: jest.fn(),
-                    },
-                },
-                {
-                    provide: PORTAL_PLAYER,
-                    useValue: {
-                        isEmbeddedPlayer,
-                        openResolvedPlayback,
-                        openExternalPlayback,
-                    },
-                },
-                {
-                    provide: Router,
-                    useValue: {
-                        navigateByUrl: jest.fn(),
-                    },
-                },
-                {
-                    provide: TmdbEnrichmentService,
-                    useValue: {
-                        isEnabled: () => true,
-                        getSeason: tmdbGetSeason,
-                    },
-                },
-                {
-                    provide: MatSnackBar,
-                    useValue: {
-                        open: jest.fn(),
-                    },
-                },
-                {
-                    provide: TranslateService,
-                    useValue: {
-                        instant: (key: string) => key,
-                        get: (key: string) => of(key),
-                        stream: (key: string) => of(key),
-                        currentLang: 'en',
-                        defaultLang: 'en',
-                        // EMPTY (not of(null)): the real TranslatePipe inside
-                        // the detail shell reads `event.lang` from emissions.
-                        onLangChange: EMPTY,
-                        onTranslationChange: EMPTY,
-                        onDefaultLangChange: EMPTY,
-                    },
-                },
-            ],
-        })
-            .overrideComponent(StalkerSeriesViewComponent, {
-                remove: {
-                    imports: [
-                        FavoritesButtonComponent,
-                        PortalInlinePlayerComponent,
-                        SeasonContainerComponent,
-                        TranslatePipe,
-                    ],
-                },
-                add: {
-                    imports: [
-                        StubFavoritesButtonComponent,
-                        StubPortalInlinePlayerComponent,
-                        StubSeasonContainerComponent,
-                        MockPipe(
-                            TranslatePipe,
-                            (
-                                value: string | null | undefined,
-                                params?: Record<string, number>
-                            ) => {
-                                if (value === 'XTREAM.PLAY_EPISODE') {
-                                    return `Play episode ${
-                                        params?.['episode'] ?? '{{episode}}'
-                                    }`;
-                                }
-                                return value ?? '';
-                            }
-                        ),
-                    ],
-                },
-            })
-            .compileComponents();
-
-        fixture = TestBed.createComponent(StalkerSeriesViewComponent);
+        fixture = await createFixture();
     });
 
     afterEach(() => {
@@ -783,10 +582,12 @@ describe('StalkerSeriesViewComponent', () => {
                 }),
             })
         );
-        // Prettier expands these compact fixtures enough to breach the spec's
-        // hard 1,200-line lint limit.
-        // prettier-ignore
-        expect(inlinePlayer.episodeMetadata()).toEqual({ label: 'S01E01', title: 'Pilot', seasonNumber: 1, episodeNumber: 1 });
+        expect(inlinePlayer.episodeMetadata()).toEqual({
+            label: 'S01E01',
+            title: 'Pilot',
+            seasonNumber: 1,
+            episodeNumber: 1,
+        });
         expect(inlinePlayer.seriesNavigation()).toEqual({
             canPrevious: false,
             canNext: true,
@@ -834,251 +635,6 @@ describe('StalkerSeriesViewComponent', () => {
         );
     });
 
-    it('prefetches the next unopened season so the Up Next rail can spill over', async () => {
-        selectedContentType.set('vod');
-        selectedItem.set({
-            id: '50001',
-            is_series: true,
-            info: {
-                name: 'VOD Flagged Series',
-                description: 'Lazy seasons',
-                movie_image: 'vod-series.jpg',
-            },
-        });
-        serialSeasonsResource.set([]);
-        vodSeriesSeasonsResource.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-            },
-        ]);
-        isEmbeddedPlayer.mockReturnValue(true);
-
-        await stabilize();
-
-        // Season 1 loaded, season 2 still empty — the state a user is in
-        // right after opening the series and starting the first episode.
-        fixture.componentInstance.vodSeriesSeasons.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-                episodes: [
-                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
-                ],
-                isLoading: false,
-                isExpanded: false,
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-                episodes: [],
-                isLoading: false,
-                isExpanded: false,
-            },
-        ]);
-        fetchVodSeriesEpisodes.mockClear();
-        fetchVodSeriesEpisodes.mockResolvedValue([
-            { id: 'episode-3', series_number: 1, name: 'Next Season' },
-        ]);
-
-        const firstEpisode = fixture.componentInstance.mappedSeasons()['1'][0];
-        fixture.componentInstance.onEpisodeClicked(firstEpisode);
-        await fixture.whenStable();
-        await stabilize();
-        fixture.detectChanges();
-
-        expect(fetchVodSeriesEpisodes).toHaveBeenCalledWith(
-            '50001',
-            'season-2'
-        );
-
-        const inlinePlayer = fixture.debugElement.query(
-            By.directive(StubPortalInlinePlayerComponent)
-        ).componentInstance as StubPortalInlinePlayerComponent;
-        const railItems = inlinePlayer.upNextEpisodes() as Array<{
-            label: string;
-        }>;
-        expect(railItems.map((item) => item.label)).toEqual([
-            'S01E01',
-            'S02E01',
-        ]);
-    });
-
-    it('does not re-request a spillover season that came back empty', async () => {
-        selectedContentType.set('vod');
-        selectedItem.set({
-            id: '50001',
-            is_series: true,
-            info: {
-                name: 'VOD Flagged Series',
-                description: 'Lazy seasons',
-                movie_image: 'vod-series.jpg',
-            },
-        });
-        serialSeasonsResource.set([]);
-        vodSeriesSeasonsResource.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-            },
-        ]);
-        isEmbeddedPlayer.mockReturnValue(true);
-
-        await stabilize();
-
-        fixture.componentInstance.vodSeriesSeasons.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-                episodes: [
-                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
-                    { id: 'episode-2', series_number: 2, name: 'Second' },
-                ],
-                isLoading: false,
-                isExpanded: false,
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-                episodes: [],
-                isLoading: false,
-                isExpanded: false,
-            },
-        ]);
-        fetchVodSeriesEpisodes.mockClear();
-        // Failed or genuinely empty season: isLoading returns to false while
-        // episodes stays empty — the retry trap.
-        fetchVodSeriesEpisodes.mockResolvedValue([]);
-
-        const seasonOne = fixture.componentInstance.mappedSeasons()['1'];
-        fixture.componentInstance.onEpisodeClicked(seasonOne[0]);
-        await fixture.whenStable();
-        await stabilize();
-        fixture.detectChanges();
-
-        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
-
-        // Further playback activity in the same season must not retrigger it.
-        fixture.componentInstance.onEpisodeClicked(seasonOne[1]);
-        await fixture.whenStable();
-        await stabilize();
-        fixture.detectChanges();
-
-        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
-    });
-
-    it('retries a failed spillover prefetch on the next episode', async () => {
-        selectedContentType.set('vod');
-        selectedItem.set({
-            id: '50001',
-            is_series: true,
-            info: {
-                name: 'VOD Flagged Series',
-                description: 'Lazy seasons',
-                movie_image: 'vod-series.jpg',
-            },
-        });
-        serialSeasonsResource.set([]);
-        vodSeriesSeasonsResource.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-            },
-        ]);
-        isEmbeddedPlayer.mockReturnValue(true);
-
-        await stabilize();
-
-        fixture.componentInstance.vodSeriesSeasons.set([
-            {
-                id: 'season-1',
-                video_id: '50001',
-                season_number: '1',
-                name: 'Season 1',
-                episodes: [
-                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
-                    { id: 'episode-2', series_number: 2, name: 'Second' },
-                ],
-                isLoading: false,
-                isExpanded: false,
-            },
-            {
-                id: 'season-2',
-                video_id: '50001',
-                season_number: '2',
-                name: 'Season 2',
-                episodes: [],
-                isLoading: false,
-                isExpanded: false,
-            },
-        ]);
-        fetchVodSeriesEpisodes.mockClear();
-        fetchVodSeriesEpisodes.mockRejectedValueOnce(new Error('network'));
-
-        const seasonOne = fixture.componentInstance.mappedSeasons()['1'];
-        fixture.componentInstance.onEpisodeClicked(seasonOne[0]);
-        await fixture.whenStable();
-        await stabilize();
-        fixture.detectChanges();
-
-        // The failure must not loop while the same episode keeps playing.
-        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
-
-        // Moving to the next episode gives the transient failure a new chance.
-        fetchVodSeriesEpisodes.mockResolvedValue([
-            { id: 'episode-3', series_number: 1, name: 'Next Season' },
-        ]);
-        fixture.componentInstance.onEpisodeClicked(seasonOne[1]);
-        await fixture.whenStable();
-        await stabilize();
-        fixture.detectChanges();
-
-        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(2);
-
-        const inlinePlayer = fixture.debugElement.query(
-            By.directive(StubPortalInlinePlayerComponent)
-        ).componentInstance as StubPortalInlinePlayerComponent;
-        const railItems = inlinePlayer.upNextEpisodes() as Array<{
-            label: string;
-        }>;
-        expect(railItems.map((item) => item.label)).toEqual([
-            'S01E02',
-            'S02E01',
-        ]);
-    });
-
     it('loads the next unloaded VOD-series season after the loaded season is watched', async () => {
         selectedContentType.set('vod');
         selectedItem.set({
@@ -1180,162 +736,4 @@ describe('StalkerSeriesViewComponent', () => {
             undefined
         );
     });
-
-    it('fetches the TMDB season once the show-level match arrives after auto-select', async () => {
-        await stabilize();
-        fixture.detectChanges();
-
-        // Season tabs auto-select immediately — usually before the async
-        // show-level enrichment has written tmdb_id.
-        const seasonContainer = fixture.debugElement.query(
-            By.directive(StubSeasonContainerComponent)
-        ).componentInstance as StubSeasonContainerComponent;
-        seasonContainer.seasonSelected.emit('1');
-        await stabilize();
-        expect(tmdbGetSeason).not.toHaveBeenCalled();
-
-        // The TMDB match lands afterwards — the fetch must run now.
-        selectedItem.set({
-            id: '30001',
-            cmd: '/media/file_30001.mpg',
-            info: {
-                name: 'Regular Series',
-                description: 'Series description',
-                movie_image: 'poster.jpg',
-                tmdb_id: 777,
-            },
-        } as never);
-        await stabilize();
-
-        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 1);
-    });
-
-    it('waits for the season map before fetching so a per-season slice gets the title-marked season', async () => {
-        serialSeasonsResource.set([]);
-        selectedItem.set({
-            id: '30001',
-            cmd: '/media/file_30001.mpg',
-            info: {
-                name: 'Regular Series (2 season)',
-                description: 'Series description',
-                movie_image: 'poster.jpg',
-                tmdb_id: 777,
-            },
-        } as never);
-        await stabilize();
-
-        fixture.componentInstance.onSeasonSelected('2');
-        await stabilize();
-
-        // Season resource still loading — fetching now would pass a zero
-        // season count, suppress the title-marker override and cache the
-        // wrong season forever (fetchSeason is idempotent).
-        expect(tmdbGetSeason).not.toHaveBeenCalled();
-
-        serialSeasonsResource.set([
-            {
-                id: 'season-1',
-                name: 'Season 1',
-                cmd: '/media/file_30001.mpg',
-                series: [1, 2],
-            },
-        ]);
-        await stabilize();
-
-        // Single-season slice whose provider season is renumbered to 1:
-        // the title marker names the real TMDB season.
-        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 2);
-    });
-
-    it('gates the fetch on the reloading season resource during detail-to-detail navigation', async () => {
-        await stabilize();
-
-        fixture.componentInstance.onSeasonSelected('1');
-        await stabilize();
-        // No show-level TMDB match yet — nothing fetched for the first item
-        expect(tmdbGetSeason).not.toHaveBeenCalled();
-
-        // Detail-to-detail navigation reuses the component; the new item's
-        // TMDB match can arrive while the season resource reloads and the
-        // map still shows the previous series' seasons.
-        isSerialSeasonsLoading.set(true);
-        selectedItem.set({
-            id: '30002',
-            cmd: '/media/file_30002.mpg',
-            info: {
-                name: 'Other Series (2 season)',
-                description: 'Other description',
-                movie_image: 'poster2.jpg',
-                tmdb_id: 888,
-            },
-        } as never);
-        await stabilize();
-
-        // The new tmdb_id must NOT pair with the previous series' season
-        // context while the resource reloads.
-        expect(tmdbGetSeason).not.toHaveBeenCalled();
-
-        // Once the new item's own seasons land, the fetch runs without a
-        // stale-season fetch. The container selects the corrected key once
-        // the new season map is rendered.
-        serialSeasonsResource.set([
-            {
-                id: 'season-1',
-                name: 'Season 1',
-                cmd: '/media/file_30002.mpg',
-                series: [1, 2],
-            },
-        ]);
-        isSerialSeasonsLoading.set(false);
-        fixture.componentInstance.onSeasonSelected('2');
-        await stabilize();
-        expect(tmdbGetSeason).toHaveBeenCalledWith(888, 2);
-    });
-
-    it('enriches after equal-id navigation once the season resource settles', async () => {
-        await stabilize();
-        fixture.componentInstance.onSeasonSelected('1');
-        await stabilize();
-
-        // Distinct items can reuse a provider id; the loading gate (not an
-        // id comparison) keeps the stale map from being used.
-        isSerialSeasonsLoading.set(true);
-        selectedItem.set({
-            id: '30001',
-            cmd: '/media/file_30001.mpg',
-            info: {
-                name: 'Different Series (3 season)',
-                description: 'Different description',
-                movie_image: 'poster3.jpg',
-                tmdb_id: 999,
-            },
-        } as never);
-        await stabilize();
-        expect(tmdbGetSeason).not.toHaveBeenCalled();
-
-        isSerialSeasonsLoading.set(false);
-        fixture.componentInstance.onSeasonSelected('3');
-        await stabilize();
-        expect(tmdbGetSeason).toHaveBeenCalledWith(999, 3);
-    });
-
-    it('reads the season marker from o_name when name is generic', async () => {
-        selectedItem.set({
-            id: '30001',
-            cmd: '/media/file_30001.mpg',
-            info: {
-                name: 'Regular Series',
-                o_name: 'Regular Series (2 season)',
-                description: 'Series description',
-                movie_image: 'poster.jpg',
-                tmdb_id: 777,
-            },
-        } as never);
-        await stabilize();
-
-        fixture.componentInstance.onSeasonSelected('2');
-        await stabilize();
-
-        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 2);
-    });
 });
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
index 3c250b61b..a4fd531f4 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
@@ -16,7 +16,6 @@ import { MatSnackBar } from '@angular/material/snack-bar';
 import { Router } from '@angular/router';
 import { TranslatePipe, TranslateService } from '@ngx-translate/core';
 import { FavoritesButtonComponent } from '../stalker-favorites-button/stalker-favorites-button.component';
-import { StalkerCatalogFacadeService } from '../stalker-catalog-facade.service';
 import {
     findStalkerResumeLazySeason,
     resolveStalkerResumeEpisode,
@@ -40,7 +39,6 @@ import {
     SimilarRailComponent,
     ViewInPortalActionComponent,
     VodMoreMenuComponent,
-    buildSeriesWatchToggleRequest,
     scrollToCastCrewRow,
 } from '@iptvnator/ui/components';
 import {
@@ -53,14 +51,11 @@ import {
     XtreamSerieEpisode,
     pickSeasonMarkedTitle,
     seriesStatusLabelKey,
-    youtubeEmbedUrl,
 } from '@iptvnator/shared/interfaces';
 import {
     isLiveExternalPlayerSession,
     replaceOwnedExternalSession,
-    isPortalPlaybackWatched,
     PORTAL_EXTERNAL_PLAYBACK,
-    PORTAL_PLAYBACK_POSITIONS,
     PORTAL_PLAYER,
     createLogger,
     consumeStalkerReturnMarker,
@@ -108,12 +103,10 @@ import {
     getStalkerSeriesQuickStartButton,
     type StalkerQuickStartButton,
 } from './stalker-series-quick-start';
-import {
-    clearStalkerSeriesPosition,
-    reconcileStalkerSeriesPositions,
-    saveStalkerSeriesPosition,
-    StalkerSeriesPositionPartialSaveError,
-} from './stalker-series-position-compatibility';
+import { toStalkerSeriesId } from './stalker-series-id';
+import { StalkerSeriesPositionsService } from './stalker-series-positions.service';
+import { StalkerSeriesWatchToggleService } from './stalker-series-watch-toggle.service';
+import { StalkerVodSeasonEpisodeLoader } from './stalker-vod-season-episode-loader';
 import {
     createStalkerSeriesDownloadAdapter,
     STALKER_SERIES_DOWNLOAD_MODES,
@@ -128,40 +121,6 @@ import {
     type StalkerEpisodePlaybackStructuralIdentity,
 } from './stalker-episode-playback-session-key';
 
-interface SeriesPositionContext {
-    readonly generation: number;
-    readonly playlistId: string;
-    readonly seriesXtreamId: number;
-    readonly mutationKey: string;
-}
-
-interface StalkerWatchToggleFeedback {
-    readonly marked: string;
-    readonly unmarked: string;
-    readonly partialMarked: string;
-    readonly partialUnmarked: string;
-    readonly failed: string;
-}
-
-// The marked and partial keys are scope-generic on purpose ("{{count}}
-// episodes marked as watched", "{{count}} marked · {{failed}} failed");
-// only unmark-success and failure name their scope.
-const SEASON_WATCH_FEEDBACK: StalkerWatchToggleFeedback = {
-    marked: 'XTREAM.SEASON_MARKED_WATCHED',
-    unmarked: 'XTREAM.SEASON_MARKED_UNWATCHED',
-    partialMarked: 'XTREAM.SEASON_MARKED_WATCHED_PARTIAL',
-    partialUnmarked: 'XTREAM.SEASON_MARKED_UNWATCHED_PARTIAL',
-    failed: 'XTREAM.SEASON_WATCH_UPDATE_FAILED',
-};
-
-const SERIES_WATCH_FEEDBACK: StalkerWatchToggleFeedback = {
-    marked: 'XTREAM.SEASON_MARKED_WATCHED',
-    unmarked: 'XTREAM.SERIES_MARKED_UNWATCHED',
-    partialMarked: 'XTREAM.SEASON_MARKED_WATCHED_PARTIAL',
-    partialUnmarked: 'XTREAM.SEASON_MARKED_UNWATCHED_PARTIAL',
-    failed: 'XTREAM.SERIES_WATCH_UPDATE_FAILED',
-};
-
 interface StalkerSeriesPlaybackRequestContext {
     readonly generation: number;
     readonly usesEmbeddedPlayer: boolean;
@@ -201,6 +160,8 @@ interface StalkerSeriesPlaybackRequestContext {
         StalkerSeriesTmdbSeasonsService,
         StalkerSeriesHeroPresenter,
         StalkerSeriesMenuService,
+        StalkerSeriesPositionsService,
+        StalkerSeriesWatchToggleService,
     ],
 })
 export class StalkerSeriesViewComponent implements OnDestroy {
@@ -209,27 +170,8 @@ export class StalkerSeriesViewComponent implements OnDestroy {
     readonly menu = inject(StalkerSeriesMenuService);
     private readonly seasonContainerRef =
         viewChild<SeasonContainerComponent>('seasonContainer');
-    private readonly playbackPositions = inject(PORTAL_PLAYBACK_POSITIONS);
-    private readonly migrationPlaybackPositions = {
-        savePlaybackPosition: (
-            playlistId: string,
-            data: PlaybackPositionData
-        ) =>
-            this.playbackPositions.savePlaybackPositionOrThrow(
-                playlistId,
-                data
-            ),
-        clearPlaybackPosition: (
-            playlistId: string,
-            contentXtreamId: number,
-            contentType: 'vod' | 'episode'
-        ) =>
-            this.playbackPositions.clearPlaybackPositionOrThrow(
-                playlistId,
-                contentXtreamId,
-                contentType
-            ),
-    };
+    private readonly positions = inject(StalkerSeriesPositionsService);
+    private readonly watchToggle = inject(StalkerSeriesWatchToggleService);
     private readonly portalPlayer = inject(PORTAL_PLAYER);
     private readonly router = inject(Router);
     private readonly location = inject(Location);
@@ -238,46 +180,15 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         PlaybackPositionRuntimeBridgeService
     );
     private readonly snackBar = inject(MatSnackBar);
-    // Optional: absent in collection-detail mounts outside the catalog.
-    private readonly catalogFacade = inject(StalkerCatalogFacadeService, {
-        optional: true,
-    });
     private readonly translateService = inject(TranslateService);
     readonly backClicked = output<void>();
     private readonly logger = createLogger('StalkerSeriesView');
     readonly inlinePlayback = signal<ResolvedPortalPlayback | null>(null);
-    readonly episodePlaybackPositions = signal<
-        Map<number, PlaybackPositionData>
-    >(new Map());
-    private readonly rawSeriesPositions = signal<
-        readonly PlaybackPositionData[]
-    >([]);
-    /**
-     * `playlistId:seriesId` once the persisted positions for the shown
-     * series have been READ (a failed read leaves it null): the dashboard
-     * resume handoff must not start an episode from the beginning because
-     * the offsets have not arrived yet.
-     */
-    private readonly seriesPositionsLoadedKey = signal<string | null>(null);
+    readonly episodePlaybackPositions = this.positions.episodePlaybackPositions;
     private readonly seriesResumeTarget = inject(STALKER_SERIES_RESUME_TARGET);
     private consumedSeriesResumeKey: string | null = null;
     private readonly seriesResumeSeasonHydration =
         new StalkerResumeSeasonHydration();
-    private readonly legacyPositionByTrackingId = signal<
-        Map<number, PlaybackPositionData>
-    >(new Map());
-    private activeSeriesPositionContext: SeriesPositionContext | null = null;
-    private seriesPositionContextGeneration = 0;
-    private readonly seriesPositionMutationQueues = new Map<
-        string,
-        Promise<void>
-    >();
-    private readonly pendingSeriesPositionLoads = new Map<
-        SeriesPositionContext,
-        Set<number>
-    >();
-    private readonly seriesPositionReloadKeys = new Set<string>();
-    private seriesPositionsLoadGeneration = 0;
     private seriesPlaybackRequestGeneration = 0;
     private currentSeriesPlaybackOwnerKey = '';
     private readonly inlinePlaybackEpisodeIdentity =
@@ -294,15 +205,6 @@ export class StalkerSeriesViewComponent implements OnDestroy {
     private readonly pendingStartSeriesIds = signal<readonly string[]>([]);
     /** Episode choices made while a forced MPV/VLC launch is mid-flight. */
     private readonly launchQueue = new StalkerSeriesLaunchQueue();
-    /**
-     * The episode chosen while a watched/reset batch still rewrote the rows
-     * a start resumes from; the last choice plays once the batch settled,
-     * and only on the series it was made for.
-     */
-    private choiceHeldForBatch: {
-        readonly seriesKey: string;
-        readonly play: () => void;
-    } | null = null;
     /** `playlist:series` of the series on screen; provider ids collide across playlists. */
     readonly currentSeriesKey = computed(
         () =>
@@ -312,7 +214,7 @@ export class StalkerSeriesViewComponent implements OnDestroy {
     readonly startPending = computed(() =>
         this.pendingStartSeriesIds().includes(this.currentSeriesKey())
     );
-    readonly seasonWatchBatchRunning = signal(false);
+    readonly seasonWatchBatchRunning = this.watchToggle.seasonWatchBatchRunning;
 
     /**
      * Optional input for VOD items with embedded series array (vclub mode)
@@ -437,6 +339,20 @@ export class StalkerSeriesViewComponent implements OnDestroy {
             resetProgress: () => this.resetProgress(),
             openExternal: (player) => this.openQuickStartExternally(player),
         });
+        this.positions.bind({
+            displayItem: this.displayItem,
+            mappedSeasons: this.mappedSeasons,
+        });
+        this.watchToggle.bind({
+            displayItem: this.displayItem,
+            currentSeriesKey: this.currentSeriesKey,
+            isVodSeries: this.isVodSeries,
+            vodSeriesSeasons: this.vodSeriesSeasons,
+            mappedSeasons: this.mappedSeasons,
+            excludedEpisodeIds: () => this.seriesWatchExcludedIds(),
+            loadEpisodesForSeason: (season) =>
+                this.loadEpisodesForSeason(season),
+        });
         effect(() => {
             const ownerKey = this.seriesPlaybackOwnerKey();
             untracked(() => this.syncSeriesPlaybackOwner(ownerKey));
@@ -506,33 +422,11 @@ export class StalkerSeriesViewComponent implements OnDestroy {
 
         // Effect to load playback positions for Stalker series
         effect(() => {
-            const item = this.displayItem();
-            const playlist = this.stalkerStore.currentPlaylist();
-            const normalizedSeriesId = this.toSeriesId(item?.id ?? 0);
-            if (item && playlist?._id && normalizedSeriesId > 0) {
-                this.logger.debug('Loading positions for series', {
-                    id: item.id,
-                    seriesId: normalizedSeriesId,
-                    isSeries: item.is_series,
-                });
-                this.rawSeriesPositions.set([]);
-                this.seriesPositionsLoadedKey.set(null);
-                this.episodePlaybackPositions.set(new Map());
-                this.legacyPositionByTrackingId.set(new Map());
-                const context = this.activateSeriesPositionContext(
-                    playlist._id,
-                    normalizedSeriesId
-                );
-                void this.loadSeriesPositions(context);
-            } else {
-                this.activeSeriesPositionContext = null;
-                this.seriesPositionContextGeneration++;
-                this.seriesPositionsLoadGeneration++;
-            }
+            this.positions.loadShownSeries();
         });
 
         effect(() => {
-            this.applyReconciledSeriesPositions();
+            this.positions.applyReconciledSeriesPositions();
         });
 
         // Dashboard "Continue watching" handoff: once the persisted
@@ -557,8 +451,11 @@ export class StalkerSeriesViewComponent implements OnDestroy {
                 !playlistId ||
                 seriesXtreamId <= 0 ||
                 target.seriesXtreamId !== seriesXtreamId ||
-                this.seriesPositionsLoadedKey() !==
-                    this.seriesPositionsKey(playlistId, seriesXtreamId)
+                this.positions.seriesPositionsLoadedKey() !==
+                    this.positions.seriesPositionsKey(
+                        playlistId,
+                        seriesXtreamId
+                    )
             ) {
                 return;
             }
@@ -577,10 +474,12 @@ export class StalkerSeriesViewComponent implements OnDestroy {
                 // Reconciliation attaches positions by exact or legacy
                 // tracking id only; an episode found by coordinates still
                 // resumes at the offset the dashboard card displayed.
-                const savedOffset = this.rawSeriesPositions().find(
-                    (position) =>
-                        position.contentXtreamId === target.contentXtreamId
-                )?.positionSeconds;
+                const savedOffset = this.positions
+                    .rawSeriesPositions()
+                    .find(
+                        (position) =>
+                            position.contentXtreamId === target.contentXtreamId
+                    )?.positionSeconds;
                 untracked(() => this.onEpisodeClicked(episode, savedOffset));
                 return;
             }
@@ -661,14 +560,14 @@ export class StalkerSeriesViewComponent implements OnDestroy {
                     // The facade/runtime already saved this row. Repeat the
                     // idempotent upsert because only this view owns the
                     // scoped-to-legacy cleanup mapping.
-                    void this.persistSeriesPosition(playlistId, data).catch(
-                        (error: unknown) => {
+                    void this.positions
+                        .persistSeriesPosition(playlistId, data)
+                        .catch((error: unknown) => {
                             this.logger.error(
                                 'Failed to persist runtime series position',
                                 error
                             );
-                        }
-                    );
+                        });
                 }
             ) ?? null;
     }
@@ -915,106 +814,17 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         }
     }
 
-    private readonly vodSeasonEpisodeLoads = new Map<
-        string,
-        { season: VodSeriesSeasonVm; promise: Promise<boolean> }
-    >();
+    private readonly vodSeasonLoader = new StalkerVodSeasonEpisodeLoader({
+        seasons: this.vodSeriesSeasons,
+        ownerKey: () => this.seriesPlaybackOwnerKey(),
+        fetchEpisodes: (videoId, seasonId) =>
+            this.stalkerStore.fetchVodSeriesEpisodes(videoId, seasonId),
+        logError: (message, error) => this.logger.error(message, error),
+    });
 
-    /**
-     * Loads episodes for a specific VOD season.
-     *
-     * Single-flight per season: a tab click, the spillover prefetch, the
-     * quick-start recursion, and the series-toggle hydration can all ask for
-     * the same season — a second concurrent request would duplicate portal
-     * traffic, and its failure could abort a series toggle whose original
-     * request succeeded.
-     */
     /** Resolves true when the portal answered, false when the request failed. */
     loadEpisodesForSeason(season: VodSeriesSeasonVm): Promise<boolean> {
-        const key = JSON.stringify([
-            this.seriesPlaybackOwnerKey(),
-            season.video_id,
-            season.id,
-            getVodSeriesSeasonKey(season),
-        ]);
-        const inFlight = this.vodSeasonEpisodeLoads.get(key);
-        if (inFlight && this.vodSeriesSeasons().includes(inFlight.season)) {
-            return inFlight.promise;
-        }
-        const load = this.fetchEpisodesForSeason(season).finally(() => {
-            if (this.vodSeasonEpisodeLoads.get(key)?.promise === load) {
-                this.vodSeasonEpisodeLoads.delete(key);
-            }
-        });
-        const loadingSeason = this.vodSeriesSeasons().find(
-            (candidate) =>
-                candidate.id === season.id &&
-                candidate.video_id === season.video_id
-        );
-        if (loadingSeason) {
-            this.vodSeasonEpisodeLoads.set(key, {
-                season: loadingSeason,
-                promise: load,
-            });
-        }
-        return load;
-    }
-
-    private async fetchEpisodesForSeason(
-        season: VodSeriesSeasonVm
-    ): Promise<boolean> {
-        // Set loading state in local signal
-        const seasons = this.vodSeriesSeasons();
-        const index = seasons.findIndex(
-            (s) =>
-                s.id === season.id &&
-                s.video_id === season.video_id &&
-                getVodSeriesSeasonKey(s) === getVodSeriesSeasonKey(season)
-        );
-        if (index === -1) return false;
-
-        const updatedSeasons = [...seasons];
-        const loadingSeason = { ...updatedSeasons[index], isLoading: true };
-        updatedSeasons[index] = loadingSeason;
-        this.vodSeriesSeasons.set(updatedSeasons);
-
-        try {
-            const episodes = await this.stalkerStore.fetchVodSeriesEpisodes(
-                season.video_id,
-                season.id
-            );
-
-            // Update with loaded episodes
-            const newSeasons = [...this.vodSeriesSeasons()];
-            // Only the exact loading VM owns this response. A navigation or
-            // refresh can reuse provider ids while replacing the season list.
-            const newIndex = newSeasons.indexOf(loadingSeason);
-            if (newIndex !== -1) {
-                newSeasons[newIndex] = {
-                    ...newSeasons[newIndex],
-                    episodes: episodes,
-                    // Even an EMPTY answer marks the season loaded: the
-                    // portal spoke, so it must stop counting as "unloaded"
-                    // (label/verdict gating and series-toggle hydration).
-                    episodesLoaded: true,
-                    isLoading: false,
-                };
-                this.vodSeriesSeasons.set(newSeasons);
-            }
-            return newIndex !== -1;
-        } catch (error) {
-            this.logger.error('Failed to load episodes', error);
-            const newSeasons = [...this.vodSeriesSeasons()];
-            const newIndex = newSeasons.indexOf(loadingSeason);
-            if (newIndex !== -1) {
-                newSeasons[newIndex] = {
-                    ...newSeasons[newIndex],
-                    isLoading: false,
-                };
-                this.vodSeriesSeasons.set(newSeasons);
-            }
-            return false;
-        }
+        return this.vodSeasonLoader.load(season);
     }
 
     /**
@@ -1045,15 +855,9 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         if (this.seasonWatchBatchRunning()) {
             // The batch rewrites the very rows a start resumes from: the
             // choice waits for it, like the Reset and watched rows do.
-            this.choiceHeldForBatch = {
-                seriesKey: this.currentSeriesKey(),
-                play: () =>
-                    this.onEpisodeClicked(
-                        episode,
-                        startTimeOverride,
-                        forcePlayer
-                    ),
-            };
+            this.watchToggle.holdChoice(() =>
+                this.onEpisodeClicked(episode, startTimeOverride, forcePlayer)
+            );
             return;
         }
         const seriesKey = this.currentSeriesKey();
@@ -1068,20 +872,6 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         this.startEpisode(episode, startTimeOverride, forcePlayer);
     }
 
-    /**
-     * The batch settled: the choice held meanwhile goes through the usual
-     * gates, unless the viewer switched series since. Episode identities
-     * overlap across series, so it must never resolve against another one.
-     */
-    private endWatchBatch(): void {
-        this.seasonWatchBatchRunning.set(false);
-        const held = this.choiceHeldForBatch;
-        this.choiceHeldForBatch = null;
-        if (held && held.seriesKey === this.currentSeriesKey()) {
-            held.play();
-        }
-    }
-
     private startEpisode(
         episode: XtreamSerieEpisode,
         startTimeOverride?: number,
@@ -1208,11 +998,7 @@ export class StalkerSeriesViewComponent implements OnDestroy {
     }
 
     toSeriesId(id: string | number): number {
-        const raw = String(id ?? '').trim();
-        if (!raw) return 0;
-        const primary = raw.includes(':') ? raw.split(':')[0] : raw;
-        const parsed = Number(primary);
-        return Number.isFinite(parsed) ? parsed : 0;
+        return toStalkerSeriesId(id);
     }
 
     closeInlinePlayer(): void {
@@ -1239,15 +1025,14 @@ export class StalkerSeriesViewComponent implements OnDestroy {
             positionSeconds: Math.floor(event.currentTime),
             durationSeconds: Math.floor(event.duration),
         };
-        void this.persistSeriesPosition(
-            playback.contentInfo.playlistId,
-            position
-        ).catch((error: unknown) => {
-            this.logger.error(
-                'Failed to persist inline series position',
-                error
-            );
-        });
+        void this.positions
+            .persistSeriesPosition(playback.contentInfo.playlistId, position)
+            .catch((error: unknown) => {
+                this.logger.error(
+                    'Failed to persist inline series position',
+                    error
+                );
+            });
     }
 
     showCopyNotification(): void {
@@ -1517,27 +1302,10 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         this.closeInlinePlayer();
     }
 
-    async handlePlaybackToggleRequested(
+    handlePlaybackToggleRequested(
         request: SeasonContainerPlaybackToggleRequest
     ): Promise<void> {
-        const playlistId = this.stalkerStore.currentPlaylist()?._id;
-        if (!playlistId) {
-            return;
-        }
-
-        if (request.nextPosition) {
-            await this.persistSeriesPosition(playlistId, request.nextPosition);
-        } else {
-            await this.clearSeriesPosition(playlistId, request.contentXtreamId);
-        }
-        // Keep the catalog grid's progress badge in sync (ownership-checked
-        // inside the facade; no-op outside the catalog context). A failed
-        // refresh keeps the cache populated-but-stale.
-        await this.catalogFacade
-            ?.refreshPositions(playlistId)
-            .catch((error: unknown) =>
-                this.logger.warn('Catalog position refresh failed', error)
-            );
+        return this.watchToggle.handlePlaybackToggleRequested(request);
     }
 
     handlePlaybackToggleRequestedFromUi(
@@ -1553,36 +1321,10 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         );
     }
 
-    async handleSeasonPlaybackToggleRequested(
+    handleSeasonPlaybackToggleRequested(
         request: SeasonContainerSeasonPlaybackToggleRequest
     ): Promise<void> {
-        const playlistId = this.stalkerStore.currentPlaylist()?._id;
-        if (
-            !playlistId ||
-            request.requests.length === 0 ||
-            this.seasonWatchBatchRunning()
-        ) {
-            return;
-        }
-        // The mutation context already keeps a stale batch out of the next
-        // series' state; the snackbars need the same ownership so feedback
-        // for the old season is not presented on a newly opened page.
-        const seriesXtreamId = this.toSeriesId(this.displayItem()?.id ?? 0);
-        const stillCurrent = () =>
-            this.stalkerStore.currentPlaylist()?._id === playlistId &&
-            this.toSeriesId(this.displayItem()?.id ?? 0) === seriesXtreamId;
-
-        this.seasonWatchBatchRunning.set(true);
-        try {
-            await this.runWatchToggleBatch(
-                request,
-                playlistId,
-                stillCurrent,
-                SEASON_WATCH_FEEDBACK
-            );
-        } finally {
-            this.endWatchBatch();
-        }
+        return this.watchToggle.handleSeasonPlaybackToggleRequested(request);
     }
 
     handleSeasonPlaybackToggleRequestedFromUi(
@@ -1624,89 +1366,10 @@ export class StalkerSeriesViewComponent implements OnDestroy {
             : {}
     );
 
-    async handleSeriesPlaybackToggleRequested(
+    handleSeriesPlaybackToggleRequested(
         request: SeasonContainerSeriesPlaybackToggleRequest
     ): Promise<void> {
-        const playlistId = this.stalkerStore.currentPlaylist()?._id;
-        if (!playlistId || this.seasonWatchBatchRunning()) {
-            return;
-        }
-        const pendingSeasons = this.isVodSeries()
-            ? this.vodSeriesSeasons().filter((season) =>
-                  this.isSeasonHydrationPending(season)
-              )
-            : [];
-        // An empty request is only meaningful when unloaded seasons remain:
-        // every loaded episode is watched, so the container could not build
-        // a target list, but hydration below may still surface unwatched
-        // episodes to mark.
-        if (request.requests.length === 0 && pendingSeasons.length === 0) {
-            return;
-        }
-
-        const seriesXtreamId = this.toSeriesId(this.displayItem()?.id ?? 0);
-        const stillCurrent = () =>
-            this.stalkerStore.currentPlaylist()?._id === playlistId &&
-            this.toSeriesId(this.displayItem()?.id ?? 0) === seriesXtreamId;
-
-        this.seasonWatchBatchRunning.set(true);
-        try {
-            let effective: SeasonContainerSeriesPlaybackToggleRequest | null =
-                request;
-            if (pendingSeasons.length > 0) {
-                const hydrated = await this.hydrateSeasonsForSeriesToggle(
-                    pendingSeasons,
-                    stillCurrent
-                );
-                if (hydrated !== 'complete') {
-                    if (hydrated === 'failed' && stillCurrent()) {
-                        this.notifySeasonWatchToggle(
-                            SERIES_WATCH_FEEDBACK.failed
-                        );
-                    }
-                    return;
-                }
-                // The reconcile effect only flushes on the next change-
-                // detection tick; rebuild the maps synchronously so the
-                // batch below sees the hydrated episodes' scoped and legacy
-                // rows (see applyReconciledSeriesPositions).
-                this.applyReconciledSeriesPositions();
-                effective = buildSeriesWatchToggleRequest({
-                    seasons: this.mappedSeasons(),
-                    seriesId: seriesXtreamId,
-                    playlistId,
-                    isEpisodeWatched: (episode) =>
-                        isPortalPlaybackWatched(
-                            this.episodePlaybackPositions().get(
-                                Number(episode.id)
-                            )
-                        ),
-                    excludedEpisodeIds: this.seriesWatchExcludedIds(),
-                    // Keep the direction the user clicked; re-inference over
-                    // the now-complete data could flip a "mark" into an
-                    // unwatch when everything turned out watched.
-                    markWatched: request.markWatched,
-                });
-                if (!effective) {
-                    if (stillCurrent()) {
-                        this.notifySeasonWatchToggle(
-                            SERIES_WATCH_FEEDBACK.marked,
-                            { count: 0 }
-                        );
-                    }
-                    return;
-                }
-            }
-
-            await this.runWatchToggleBatch(
-                effective,
-                playlistId,
-                stillCurrent,
-                SERIES_WATCH_FEEDBACK
-            );
-        } finally {
-            this.endWatchBatch();
-        }
+        return this.watchToggle.handleSeriesPlaybackToggleRequested(request);
     }
 
     handleSeriesPlaybackToggleRequestedFromUi(
@@ -1722,34 +1385,6 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         );
     }
 
-    /**
-     * Sequential on purpose: loadEpisodesForSeason snapshots the season VM
-     * array before its writes, so concurrent calls clobber each other's
-     * loading flags; and one request at a time keeps the portal load bounded.
-     */
-    private async hydrateSeasonsForSeriesToggle(
-        pendingSeasons: readonly VodSeriesSeasonVm[],
-        stillCurrent: () => boolean
-    ): Promise<'complete' | 'failed' | 'superseded'> {
-        for (const season of pendingSeasons) {
-            // A tab click may have loaded this season meanwhile.
-            const current = this.vodSeriesSeasons().find(
-                (candidate) => candidate.id === season.id
-            );
-            if (!current || !this.isSeasonHydrationPending(current)) {
-                continue;
-            }
-            const answered = await this.loadEpisodesForSeason(current);
-            if (!stillCurrent()) {
-                return 'superseded';
-            }
-            if (!answered) {
-                return 'failed';
-            }
-        }
-        return 'complete';
-    }
-
     /**
      * Mirrors the exclusions the template binds into the season container
      * (playingEpisodeId / activeEpisodeId / openingEpisodeId): the episode
@@ -1765,427 +1400,6 @@ export class StalkerSeriesViewComponent implements OnDestroy {
         return new Set(ids);
     }
 
-    private async runWatchToggleBatch(
-        request: SeasonContainerSeriesPlaybackToggleRequest,
-        playlistId: string,
-        stillCurrent: () => boolean,
-        feedback: StalkerWatchToggleFeedback
-    ): Promise<void> {
-        // Enqueue every episode synchronously: each mutation chains on
-        // the previous one's never-rejecting barrier, so the queue
-        // serializes the writes (incl. per-episode legacy-row cleanup)
-        // and reloads positions once after the whole chain drains.
-        const outcomes = await Promise.all(
-            request.requests.map((item) =>
-                (item.nextPosition
-                    ? this.persistSeriesPosition(playlistId, item.nextPosition)
-                    : this.clearSeriesPosition(playlistId, item.contentXtreamId)
-                ).then(
-                    () => true,
-                    // The scoped watched row was saved and published —
-                    // only the legacy-row cleanup failed. The episode IS
-                    // watched, so it must not count against the batch.
-                    (error: unknown) =>
-                        error instanceof StalkerSeriesPositionPartialSaveError
-                )
-            )
-        );
-
-        const failed = outcomes.filter((ok) => !ok).length;
-        const succeeded = outcomes.length - failed;
-        if (failed > 0) {
-            this.logger.error(
-                `Watched toggle: ${failed} of ${outcomes.length} episodes failed`
-            );
-        }
-        if (succeeded > 0) {
-            // Partial successes changed rows too — the catalog badge
-            // must follow even when the user already moved on. A failed
-            // refresh must not break the feedback flow below.
-            await this.catalogFacade
-                ?.refreshPositions(playlistId)
-                .catch((error: unknown) =>
-                    this.logger.warn('Catalog position refresh failed', error)
-                );
-        }
-        if (!stillCurrent()) {
-            return;
-        }
-
-        if (failed === 0) {
-            this.notifySeasonWatchToggle(
-                request.markWatched ? feedback.marked : feedback.unmarked,
-                { count: succeeded }
-            );
-        } else if (succeeded > 0) {
-            this.notifySeasonWatchToggle(
-                request.markWatched
-                    ? feedback.partialMarked
-                    : feedback.partialUnmarked,
-                { count: succeeded, failed }
-            );
-        } else {
-            this.notifySeasonWatchToggle(feedback.failed);
-        }
-    }
-
-    /**
-     * Maps the raw series position rows onto the currently mapped episodes
-     * (scoped rows plus compatible legacy promotions). Runs reactively from
-     * the constructor effect, and synchronously from the series-level watch
-     * toggle right after it hydrates lazy seasons — the effect only re-runs
-     * on the next change-detection tick, and enqueuing the batch against the
-     * stale maps would miss the hydrated episodes' legacy rows (an unwatch
-     * would leave rows behind that a later reconcile resurrects as watched).
-     */
-    private applyReconciledSeriesPositions(): void {
-        const item = this.displayItem();
-        const playlistId = this.stalkerStore.currentPlaylist()?._id;
-        const seriesXtreamId = this.toSeriesId(item?.id ?? 0);
-        const rawSeriesPositions = this.rawSeriesPositions();
-        const episodesBySeason = this.mappedSeasons();
-
-        if (!item || !playlistId || seriesXtreamId <= 0) {
-            if (rawSeriesPositions.length > 0) {
-                this.rawSeriesPositions.set([]);
-            }
-            if (this.episodePlaybackPositions().size > 0) {
-                this.episodePlaybackPositions.set(new Map());
-            }
-            if (this.legacyPositionByTrackingId().size > 0) {
-                this.legacyPositionByTrackingId.set(new Map());
-            }
-            return;
-        }
-
-        const reconciled = reconcileStalkerSeriesPositions({
-            seriesXtreamId,
-            episodesBySeason,
-            seriesPositions: rawSeriesPositions,
-        });
-        if (
-            rawSeriesPositions.length === 0 &&
-            reconciled.positionsByTrackingId.size === 0 &&
-            untracked(() => this.episodePlaybackPositions().size) > 0
-        ) {
-            return;
-        }
-        this.episodePlaybackPositions.set(reconciled.positionsByTrackingId);
-        this.legacyPositionByTrackingId.set(
-            reconciled.legacyPositionByTrackingId
-        );
-    }
-
-    private notifySeasonWatchToggle(key: string, params?: object): void {
-        this.snackBar.open(
-            this.translateService.instant(key, params),
-            undefined,
-            { duration: 5000 }
-        );
-    }
-
-    private async loadSeriesPositions(
-        context: SeriesPositionContext
-    ): Promise<void> {
-        const generation = ++this.seriesPositionsLoadGeneration;
-        this.trackPendingSeriesPositionLoad(context, generation);
-        try {
-            await this.waitForSeriesPositionMutations(context.mutationKey);
-
-            if (
-                generation !== this.seriesPositionsLoadGeneration ||
-                !this.isSeriesPositionContextActive(context)
-            ) {
-                return;
-            }
-
-            const positions =
-                await this.playbackPositions.getSeriesPlaybackPositions(
-                    context.playlistId,
-                    context.seriesXtreamId
-                );
-
-            if (
-                generation !== this.seriesPositionsLoadGeneration ||
-                !this.isSeriesPositionContextActive(context)
-            ) {
-                return;
-            }
-
-            this.rawSeriesPositions.set(positions);
-            this.seriesPositionsLoadedKey.set(
-                this.seriesPositionsKey(
-                    context.playlistId,
-                    context.seriesXtreamId
-                )
-            );
-        } finally {
-            this.untrackPendingSeriesPositionLoad(context, generation);
-        }
-    }
-
-    private seriesPositionsKey(
-        playlistId: string,
-        seriesXtreamId: number
-    ): string {
-        return `${playlistId}:${seriesXtreamId}`;
-    }
-
-    private activateSeriesPositionContext(
-        playlistId: string,
-        seriesXtreamId: number
-    ): SeriesPositionContext {
-        const context: SeriesPositionContext = {
-            generation: ++this.seriesPositionContextGeneration,
-            playlistId,
-            seriesXtreamId,
-            mutationKey: JSON.stringify([playlistId, seriesXtreamId]),
-        };
-        this.activeSeriesPositionContext = context;
-        return context;
-    }
-
-    private isSeriesPositionContextActive(
-        context: SeriesPositionContext
-    ): boolean {
-        const activeContext = this.activeSeriesPositionContext;
-        return (
-            activeContext === context &&
-            activeContext.generation === context.generation &&
-            this.stalkerStore.currentPlaylist()?._id === context.playlistId &&
-            this.toSeriesId(this.displayItem()?.id ?? 0) ===
-                context.seriesXtreamId
-        );
-    }
-
-    private waitForSeriesPositionMutations(mutationKey: string): Promise<void> {
-        return (
-            this.seriesPositionMutationQueues.get(mutationKey) ??
-            Promise.resolve()
-        );
-    }
-
-    private trackPendingSeriesPositionLoad(
-        context: SeriesPositionContext,
-        generation: number
-    ): void {
-        const generations =
-            this.pendingSeriesPositionLoads.get(context) ?? new Set<number>();
-        generations.add(generation);
-        this.pendingSeriesPositionLoads.set(context, generations);
-    }
-
-    private untrackPendingSeriesPositionLoad(
-        context: SeriesPositionContext,
-        generation: number
-    ): void {
-        const generations = this.pendingSeriesPositionLoads.get(context);
-        generations?.delete(generation);
-        if (generations?.size === 0) {
-            this.pendingSeriesPositionLoads.delete(context);
-        }
-    }
-
-    private hasCurrentPendingSeriesPositionLoad(
-        context: SeriesPositionContext
-    ): boolean {
-        return Boolean(
-            this.pendingSeriesPositionLoads
-                .get(context)
-                ?.has(this.seriesPositionsLoadGeneration)
-        );
-    }
-
-    private enqueueSeriesPositionMutation(
-        context: SeriesPositionContext,
-        operation: () => Promise<void>
-    ): Promise<void> {
-        if (this.hasCurrentPendingSeriesPositionLoad(context)) {
-            this.seriesPositionReloadKeys.add(context.mutationKey);
-        }
-        this.seriesPositionsLoadGeneration++;
-        const previous = this.waitForSeriesPositionMutations(
-            context.mutationKey
-        );
-        const result = previous.then(operation);
-        const barrier = result.then(
-            () => undefined,
-            () => undefined
-        );
-        this.seriesPositionMutationQueues.set(context.mutationKey, barrier);
-        void barrier.then(() => {
-            if (
-                this.seriesPositionMutationQueues.get(context.mutationKey) ===
-                barrier
-            ) {
-                this.seriesPositionMutationQueues.delete(context.mutationKey);
-                this.reloadSeriesPositionsAfterMutations(context.mutationKey);
-            }
-        });
-        return result;
-    }
-
-    private reloadSeriesPositionsAfterMutations(mutationKey: string): void {
-        if (!this.seriesPositionReloadKeys.delete(mutationKey)) {
-            return;
-        }
-        const context = this.activeSeriesPositionContext;
-        if (
-            !context ||
-            context.mutationKey !== mutationKey ||
-            !this.isSeriesPositionContextActive(context) ||
-            this.hasCurrentPendingSeriesPositionLoad(context)
-        ) {
-            return;
-        }
-        void this.loadSeriesPositions(context);
-    }
-
-    private getSeriesPositionMutationContext(
-        playlistId: string,
-        seriesXtreamId?: number | null
-    ): SeriesPositionContext | null {
-        const context = this.activeSeriesPositionContext;
-        if (
-            !context ||
-            context.playlistId !== playlistId ||
-            (seriesXtreamId != null &&
-                context.seriesXtreamId !== seriesXtreamId)
-        ) {
-            return null;
-        }
-        return context;
-    }
-
-    private persistSeriesPosition(
-        playlistId: string,
-        position: PlaybackPositionData
-    ): Promise<void> {
-        const context = this.getSeriesPositionMutationContext(
-            playlistId,
-            position.seriesXtreamId
-        );
-        if (!context) {
-            return Promise.resolve();
-        }
-        const legacyPosition = this.legacyPositionByTrackingId().get(
-            position.contentXtreamId
-        );
-        return this.enqueueSeriesPositionMutation(context, async () => {
-            let clearedLegacy: boolean;
-            try {
-                clearedLegacy = await saveStalkerSeriesPosition({
-                    repository: this.migrationPlaybackPositions,
-                    playlistId,
-                    position,
-                    legacyPosition,
-                });
-            } catch (error) {
-                if (
-                    error instanceof StalkerSeriesPositionPartialSaveError &&
-                    this.isSeriesPositionContextActive(context)
-                ) {
-                    this.publishSavedSeriesPosition(
-                        position,
-                        legacyPosition,
-                        false
-                    );
-                }
-                throw error;
-            }
-            if (!this.isSeriesPositionContextActive(context)) {
-                return;
-            }
-            this.publishSavedSeriesPosition(
-                position,
-                legacyPosition,
-                clearedLegacy
-            );
-        });
-    }
-
-    private publishSavedSeriesPosition(
-        position: PlaybackPositionData,
-        legacyPosition: PlaybackPositionData | undefined,
-        clearedLegacy: boolean
-    ): void {
-        const removedTrackingIds = new Set([position.contentXtreamId]);
-        if (clearedLegacy && legacyPosition) {
-            removedTrackingIds.add(legacyPosition.contentXtreamId);
-            const legacyPositions = new Map(this.legacyPositionByTrackingId());
-            legacyPositions.delete(position.contentXtreamId);
-            this.legacyPositionByTrackingId.set(legacyPositions);
-        }
-
-        this.rawSeriesPositions.set([
-            ...this.rawSeriesPositions().filter(
-                (candidate) =>
-                    !removedTrackingIds.has(candidate.contentXtreamId)
-            ),
-            position,
-        ]);
-        this.updateEpisodePlaybackPosition(position);
-    }
-
-    private clearSeriesPosition(
-        playlistId: string,
-        contentXtreamId: number
-    ): Promise<void> {
-        const context = this.getSeriesPositionMutationContext(playlistId);
-        if (!context) {
-            return Promise.resolve();
-        }
-        const position = this.episodePlaybackPositions().get(
-            contentXtreamId
-        ) ?? {
-            contentXtreamId,
-            contentType: 'episode',
-            positionSeconds: 0,
-            playlistId,
-            seriesXtreamId: context.seriesXtreamId,
-        };
-        const legacyPosition =
-            this.legacyPositionByTrackingId().get(contentXtreamId);
-        return this.enqueueSeriesPositionMutation(context, async () => {
-            const clearedLegacy = await clearStalkerSeriesPosition({
-                repository: this.migrationPlaybackPositions,
-                playlistId,
-                position,
-                legacyPosition,
-            });
-            if (!this.isSeriesPositionContextActive(context)) {
-                return;
-            }
-            this.publishClearedSeriesPosition(
-                contentXtreamId,
-                legacyPosition,
-                clearedLegacy
-            );
-        });
-    }
-
-    private publishClearedSeriesPosition(
-        contentXtreamId: number,
-        legacyPosition: PlaybackPositionData | undefined,
-        clearedLegacy: boolean
-    ): void {
-        const removedTrackingIds = new Set([contentXtreamId]);
-        if (clearedLegacy && legacyPosition) {
-            removedTrackingIds.add(legacyPosition.contentXtreamId);
-            const legacyPositions = new Map(this.legacyPositionByTrackingId());
-            legacyPositions.delete(contentXtreamId);
-            this.legacyPositionByTrackingId.set(legacyPositions);
-        }
-
-        this.rawSeriesPositions.set(
-            this.rawSeriesPositions().filter(
-                (candidate) =>
-                    !removedTrackingIds.has(candidate.contentXtreamId)
-            )
-        );
-        this.removeEpisodePlaybackPosition(contentXtreamId);
-    }
-
     private async loadAndPlayVodSeriesSeason(
         season: VodSeriesSeasonVm,
         visitedSeasonIds = new Set<string>()
@@ -2216,18 +1430,4 @@ export class StalkerSeriesViewComponent implements OnDestroy {
             );
         }
     }
-
-    private updateEpisodePlaybackPosition(
-        position: PlaybackPositionData
-    ): void {
-        const updated = new Map(this.episodePlaybackPositions());
-        updated.set(position.contentXtreamId, position);
-        this.episodePlaybackPositions.set(updated);
-    }
-
-    private removeEpisodePlaybackPosition(contentXtreamId: number): void {
-        const updated = new Map(this.episodePlaybackPositions());
-        updated.delete(contentXtreamId);
-        this.episodePlaybackPositions.set(updated);
-    }
 }
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.spillover-prefetch.spec.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.spillover-prefetch.spec.ts
new file mode 100644
index 000000000..d7a506ff8
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.spillover-prefetch.spec.ts
@@ -0,0 +1,281 @@
+import { ComponentFixture } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { StalkerSeriesViewComponent } from './stalker-series-view.component';
+import { createStalkerSeriesViewHarness } from './stalker-series-view.test-harness';
+import { StubPortalInlinePlayerComponent } from './stalker-series-view.test-helpers';
+
+/**
+ * The inline player's "Up Next" rail across lazy Ministra VOD-series seasons:
+ * the season after the playing one is fetched ahead so the rail can spill
+ * over into it.
+ */
+describe('StalkerSeriesViewComponent Up Next spillover prefetch', () => {
+    let fixture: ComponentFixture<StalkerSeriesViewComponent>;
+    const {
+        selectedContentType,
+        selectedItem,
+        serialSeasonsResource,
+        vodSeriesSeasonsResource,
+        fetchVodSeriesEpisodes,
+        isEmbeddedPlayer,
+        createFixture,
+    } = createStalkerSeriesViewHarness(() => jest.fn());
+
+    async function stabilize(): Promise<void> {
+        fixture.detectChanges();
+        await fixture.whenStable();
+    }
+
+    beforeEach(async () => {
+        fixture = await createFixture();
+    });
+
+    afterEach(() => {
+        fixture?.destroy();
+    });
+
+    it('prefetches the next unopened season so the Up Next rail can spill over', async () => {
+        selectedContentType.set('vod');
+        selectedItem.set({
+            id: '50001',
+            is_series: true,
+            info: {
+                name: 'VOD Flagged Series',
+                description: 'Lazy seasons',
+                movie_image: 'vod-series.jpg',
+            },
+        });
+        serialSeasonsResource.set([]);
+        vodSeriesSeasonsResource.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+            },
+        ]);
+        isEmbeddedPlayer.mockReturnValue(true);
+
+        await stabilize();
+
+        // Season 1 loaded, season 2 still empty — the state a user is in
+        // right after opening the series and starting the first episode.
+        fixture.componentInstance.vodSeriesSeasons.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+                episodes: [
+                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
+                ],
+                isLoading: false,
+                isExpanded: false,
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+                episodes: [],
+                isLoading: false,
+                isExpanded: false,
+            },
+        ]);
+        fetchVodSeriesEpisodes.mockClear();
+        fetchVodSeriesEpisodes.mockResolvedValue([
+            { id: 'episode-3', series_number: 1, name: 'Next Season' },
+        ]);
+
+        const firstEpisode = fixture.componentInstance.mappedSeasons()['1'][0];
+        fixture.componentInstance.onEpisodeClicked(firstEpisode);
+        await fixture.whenStable();
+        await stabilize();
+        fixture.detectChanges();
+
+        expect(fetchVodSeriesEpisodes).toHaveBeenCalledWith(
+            '50001',
+            'season-2'
+        );
+
+        const inlinePlayer = fixture.debugElement.query(
+            By.directive(StubPortalInlinePlayerComponent)
+        ).componentInstance as StubPortalInlinePlayerComponent;
+        const railItems = inlinePlayer.upNextEpisodes() as Array<{
+            label: string;
+        }>;
+        expect(railItems.map((item) => item.label)).toEqual([
+            'S01E01',
+            'S02E01',
+        ]);
+    });
+
+    it('does not re-request a spillover season that came back empty', async () => {
+        selectedContentType.set('vod');
+        selectedItem.set({
+            id: '50001',
+            is_series: true,
+            info: {
+                name: 'VOD Flagged Series',
+                description: 'Lazy seasons',
+                movie_image: 'vod-series.jpg',
+            },
+        });
+        serialSeasonsResource.set([]);
+        vodSeriesSeasonsResource.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+            },
+        ]);
+        isEmbeddedPlayer.mockReturnValue(true);
+
+        await stabilize();
+
+        fixture.componentInstance.vodSeriesSeasons.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+                episodes: [
+                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
+                    { id: 'episode-2', series_number: 2, name: 'Second' },
+                ],
+                isLoading: false,
+                isExpanded: false,
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+                episodes: [],
+                isLoading: false,
+                isExpanded: false,
+            },
+        ]);
+        fetchVodSeriesEpisodes.mockClear();
+        // Failed or genuinely empty season: isLoading returns to false while
+        // episodes stays empty — the retry trap.
+        fetchVodSeriesEpisodes.mockResolvedValue([]);
+
+        const seasonOne = fixture.componentInstance.mappedSeasons()['1'];
+        fixture.componentInstance.onEpisodeClicked(seasonOne[0]);
+        await fixture.whenStable();
+        await stabilize();
+        fixture.detectChanges();
+
+        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
+
+        // Further playback activity in the same season must not retrigger it.
+        fixture.componentInstance.onEpisodeClicked(seasonOne[1]);
+        await fixture.whenStable();
+        await stabilize();
+        fixture.detectChanges();
+
+        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
+    });
+
+    it('retries a failed spillover prefetch on the next episode', async () => {
+        selectedContentType.set('vod');
+        selectedItem.set({
+            id: '50001',
+            is_series: true,
+            info: {
+                name: 'VOD Flagged Series',
+                description: 'Lazy seasons',
+                movie_image: 'vod-series.jpg',
+            },
+        });
+        serialSeasonsResource.set([]);
+        vodSeriesSeasonsResource.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+            },
+        ]);
+        isEmbeddedPlayer.mockReturnValue(true);
+
+        await stabilize();
+
+        fixture.componentInstance.vodSeriesSeasons.set([
+            {
+                id: 'season-1',
+                video_id: '50001',
+                season_number: '1',
+                name: 'Season 1',
+                episodes: [
+                    { id: 'episode-1', series_number: 1, name: 'Pilot' },
+                    { id: 'episode-2', series_number: 2, name: 'Second' },
+                ],
+                isLoading: false,
+                isExpanded: false,
+            },
+            {
+                id: 'season-2',
+                video_id: '50001',
+                season_number: '2',
+                name: 'Season 2',
+                episodes: [],
+                isLoading: false,
+                isExpanded: false,
+            },
+        ]);
+        fetchVodSeriesEpisodes.mockClear();
+        fetchVodSeriesEpisodes.mockRejectedValueOnce(new Error('network'));
+
+        const seasonOne = fixture.componentInstance.mappedSeasons()['1'];
+        fixture.componentInstance.onEpisodeClicked(seasonOne[0]);
+        await fixture.whenStable();
+        await stabilize();
+        fixture.detectChanges();
+
+        // The failure must not loop while the same episode keeps playing.
+        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(1);
+
+        // Moving to the next episode gives the transient failure a new chance.
+        fetchVodSeriesEpisodes.mockResolvedValue([
+            { id: 'episode-3', series_number: 1, name: 'Next Season' },
+        ]);
+        fixture.componentInstance.onEpisodeClicked(seasonOne[1]);
+        await fixture.whenStable();
+        await stabilize();
+        fixture.detectChanges();
+
+        expect(fetchVodSeriesEpisodes).toHaveBeenCalledTimes(2);
+
+        const inlinePlayer = fixture.debugElement.query(
+            By.directive(StubPortalInlinePlayerComponent)
+        ).componentInstance as StubPortalInlinePlayerComponent;
+        const railItems = inlinePlayer.upNextEpisodes() as Array<{
+            label: string;
+        }>;
+        expect(railItems.map((item) => item.label)).toEqual([
+            'S01E02',
+            'S02E01',
+        ]);
+    });
+});
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.test-harness.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.test-harness.ts
new file mode 100644
index 000000000..d9b043755
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.test-harness.ts
@@ -0,0 +1,273 @@
+import { signal } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { Router } from '@angular/router';
+import { MatSnackBar } from '@angular/material/snack-bar';
+import { TranslatePipe, TranslateService } from '@ngx-translate/core';
+import { MockPipe } from 'ng-mocks';
+import { SeasonContainerComponent } from '@iptvnator/ui/components';
+import {
+    PORTAL_EXTERNAL_PLAYBACK,
+    PORTAL_PLAYBACK_POSITIONS,
+    PORTAL_PLAYER,
+} from '@iptvnator/portal/shared/util';
+import {
+    StalkerStore,
+    StalkerVodSource,
+} from '@iptvnator/portal/stalker/data-access';
+import { PortalInlinePlayerComponent } from '@iptvnator/ui/playback';
+import { TmdbEnrichmentService } from '@iptvnator/services';
+import { EMPTY, of } from 'rxjs';
+import { FavoritesButtonComponent } from '../stalker-favorites-button/stalker-favorites-button.component';
+import { StalkerSeriesViewComponent } from './stalker-series-view.component';
+import {
+    StubFavoritesButtonComponent,
+    StubPortalInlinePlayerComponent,
+    StubSeasonContainerComponent,
+} from './stalker-series-view.test-helpers';
+
+/**
+ * The slice of a Jest mock the harness drives. This file is part of the
+ * library's own type-check, which has no Jest globals, so a spec hands in
+ * the factory (`() => jest.fn()`) and gets its own mock type back.
+ */
+export interface StalkerSeriesViewTestMock {
+    mockReset(): this;
+    mockClear(): this;
+    mockReturnValue(value: unknown): this;
+    mockResolvedValue(value: unknown): this;
+    mockImplementation(implementation: (...args: never[]) => unknown): this;
+}
+
+/**
+ * The TestBed the Stalker series-view component specs share: the store
+ * signals and collaborator mocks a case drives, and `createFixture()`, which
+ * puts them back to the state every case starts from (a regular series with
+ * one two-episode season, no embedded player) before building the component
+ * with its stubbed children.
+ *
+ * Call it once per `describe`; the mocks live as long as that block.
+ */
+export function createStalkerSeriesViewHarness<
+    TMock extends StalkerSeriesViewTestMock,
+>(createMock: () => TMock) {
+    const selectedContentType = signal<'series' | 'vod'>('series');
+    const selectedItem = signal<StalkerVodSource | null>(null);
+    const serialSeasonsResource = signal<unknown[]>([]);
+    const vodSeriesSeasonsResource = signal<unknown[]>([]);
+    const isSerialSeasonsLoading = signal(false);
+    const fetchVodSeriesEpisodes = createMock();
+    const resolveVodPlayback = createMock();
+    const getSeriesPlaybackPositions = createMock().mockResolvedValue([]);
+    const openResolvedPlayback = createMock();
+    const openExternalPlayback = createMock();
+    const isEmbeddedPlayer = createMock();
+    const tmdbGetSeason = createMock();
+    const fetchLinkToPlay = createMock();
+    const currentPlaylist = signal({
+        _id: 'stalker-1',
+        title: 'Living Room Portal',
+        portalUrl: 'https://stalker.example.test',
+        macAddress: '00:1A:79:12:34:56',
+    });
+
+    async function createFixture(): Promise<
+        ComponentFixture<StalkerSeriesViewComponent>
+    > {
+        selectedContentType.set('series');
+        selectedItem.set({
+            id: '30001',
+            cmd: '/media/file_30001.mpg',
+            info: {
+                name: 'Regular Series',
+                description: 'Series description',
+                movie_image: 'poster.jpg',
+            },
+        });
+        serialSeasonsResource.set([
+            {
+                id: 'season-1',
+                name: 'Season 1',
+                cmd: '/media/file_30001.mpg',
+                series: [1, 2],
+            },
+        ]);
+        vodSeriesSeasonsResource.set([]);
+        isSerialSeasonsLoading.set(false);
+        fetchVodSeriesEpisodes.mockReset();
+        resolveVodPlayback.mockReset();
+        resolveVodPlayback.mockImplementation(
+            async (
+                _cmd?: string,
+                title?: string,
+                thumbnail?: string,
+                _episodeNum?: number,
+                episodeId?: number,
+                startTime?: number
+            ) => ({
+                streamUrl: 'http://stalker.example/episode.mpg',
+                title: title ?? 'Regular Series',
+                thumbnail: thumbnail ?? 'poster.jpg',
+                startTime,
+                contentInfo: {
+                    playlistId: 'stalker-1',
+                    contentXtreamId:
+                        episodeId ?? Number(selectedItem()?.id ?? 0),
+                    contentType: episodeId ? 'episode' : 'vod',
+                    seriesXtreamId: episodeId
+                        ? Number(selectedItem()?.id ?? 0)
+                        : undefined,
+                },
+            })
+        );
+        getSeriesPlaybackPositions.mockClear();
+        getSeriesPlaybackPositions.mockResolvedValue([]);
+        openResolvedPlayback.mockClear();
+        openExternalPlayback.mockReset();
+        isEmbeddedPlayer.mockReset();
+        isEmbeddedPlayer.mockReturnValue(false);
+        tmdbGetSeason.mockReset();
+        tmdbGetSeason.mockResolvedValue({
+            overview: 'Season overview from TMDB',
+            episodes: [],
+        });
+        fetchLinkToPlay
+            .mockReset()
+            .mockResolvedValue('https://cdn.example.test/episode.mpg');
+        currentPlaylist.set({
+            _id: 'stalker-1',
+            title: 'Living Room Portal',
+            portalUrl: 'https://stalker.example.test',
+            macAddress: '00:1A:79:12:34:56',
+        });
+
+        await TestBed.configureTestingModule({
+            imports: [StalkerSeriesViewComponent],
+            providers: [
+                {
+                    provide: StalkerStore,
+                    useValue: {
+                        selectedItem,
+                        selectedContentType,
+                        currentPlaylist,
+                        getSerialSeasonsResource: () => serialSeasonsResource(),
+                        getVodSeriesSeasonsResource: () =>
+                            vodSeriesSeasonsResource(),
+                        isVodSeriesSeasonsLoading: signal(false),
+                        isSerialSeasonsLoading,
+                        fetchVodSeriesEpisodes,
+                        resolveVodPlayback,
+                        fetchLinkToPlay,
+                    },
+                },
+                {
+                    provide: PORTAL_EXTERNAL_PLAYBACK,
+                    useValue: {
+                        activeSession: signal(null),
+                    },
+                },
+                {
+                    provide: PORTAL_PLAYBACK_POSITIONS,
+                    useValue: {
+                        getSeriesPlaybackPositions,
+                        savePlaybackPosition: createMock(),
+                        clearPlaybackPosition: createMock(),
+                    },
+                },
+                {
+                    provide: PORTAL_PLAYER,
+                    useValue: {
+                        isEmbeddedPlayer,
+                        openResolvedPlayback,
+                        openExternalPlayback,
+                    },
+                },
+                {
+                    provide: Router,
+                    useValue: {
+                        navigateByUrl: createMock(),
+                    },
+                },
+                {
+                    provide: TmdbEnrichmentService,
+                    useValue: {
+                        isEnabled: () => true,
+                        getSeason: tmdbGetSeason,
+                    },
+                },
+                {
+                    provide: MatSnackBar,
+                    useValue: {
+                        open: createMock(),
+                    },
+                },
+                {
+                    provide: TranslateService,
+                    useValue: {
+                        instant: (key: string) => key,
+                        get: (key: string) => of(key),
+                        stream: (key: string) => of(key),
+                        currentLang: 'en',
+                        defaultLang: 'en',
+                        // EMPTY (not of(null)): the real TranslatePipe inside
+                        // the detail shell reads `event.lang` from emissions.
+                        onLangChange: EMPTY,
+                        onTranslationChange: EMPTY,
+                        onDefaultLangChange: EMPTY,
+                    },
+                },
+            ],
+        })
+            .overrideComponent(StalkerSeriesViewComponent, {
+                remove: {
+                    imports: [
+                        FavoritesButtonComponent,
+                        PortalInlinePlayerComponent,
+                        SeasonContainerComponent,
+                        TranslatePipe,
+                    ],
+                },
+                add: {
+                    imports: [
+                        StubFavoritesButtonComponent,
+                        StubPortalInlinePlayerComponent,
+                        StubSeasonContainerComponent,
+                        MockPipe(
+                            TranslatePipe,
+                            (
+                                value: string | null | undefined,
+                                params?: Record<string, number>
+                            ) => {
+                                if (value === 'XTREAM.PLAY_EPISODE') {
+                                    return `Play episode ${
+                                        params?.['episode'] ?? '{{episode}}'
+                                    }`;
+                                }
+                                return value ?? '';
+                            }
+                        ),
+                    ],
+                },
+            })
+            .compileComponents();
+
+        return TestBed.createComponent(StalkerSeriesViewComponent);
+    }
+
+    return {
+        selectedContentType,
+        selectedItem,
+        serialSeasonsResource,
+        vodSeriesSeasonsResource,
+        isSerialSeasonsLoading,
+        fetchVodSeriesEpisodes,
+        resolveVodPlayback,
+        getSeriesPlaybackPositions,
+        openResolvedPlayback,
+        openExternalPlayback,
+        isEmbeddedPlayer,
+        tmdbGetSeason,
+        fetchLinkToPlay,
+        currentPlaylist,
+        createFixture,
+    };
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.tmdb-season.spec.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.tmdb-season.spec.ts
new file mode 100644
index 000000000..3440d321c
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.tmdb-season.spec.ts
@@ -0,0 +1,192 @@
+import { ComponentFixture } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { StalkerSeriesViewComponent } from './stalker-series-view.component';
+import { createStalkerSeriesViewHarness } from './stalker-series-view.test-harness';
+import { StubSeasonContainerComponent } from './stalker-series-view.test-helpers';
+
+/**
+ * The lazy TMDB season fetch of the Stalker series view: when it runs
+ * relative to the show-level TMDB match and the season resource, and which
+ * TMDB season it asks for.
+ */
+describe('StalkerSeriesViewComponent TMDB season fetch', () => {
+    let fixture: ComponentFixture<StalkerSeriesViewComponent>;
+    const {
+        selectedItem,
+        serialSeasonsResource,
+        isSerialSeasonsLoading,
+        tmdbGetSeason,
+        createFixture,
+    } = createStalkerSeriesViewHarness(() => jest.fn());
+
+    async function stabilize(): Promise<void> {
+        fixture.detectChanges();
+        await fixture.whenStable();
+    }
+
+    beforeEach(async () => {
+        fixture = await createFixture();
+    });
+
+    afterEach(() => {
+        fixture?.destroy();
+    });
+
+    it('fetches the TMDB season once the show-level match arrives after auto-select', async () => {
+        await stabilize();
+        fixture.detectChanges();
+
+        // Season tabs auto-select immediately — usually before the async
+        // show-level enrichment has written tmdb_id.
+        const seasonContainer = fixture.debugElement.query(
+            By.directive(StubSeasonContainerComponent)
+        ).componentInstance as StubSeasonContainerComponent;
+        seasonContainer.seasonSelected.emit('1');
+        await stabilize();
+        expect(tmdbGetSeason).not.toHaveBeenCalled();
+
+        // The TMDB match lands afterwards — the fetch must run now.
+        selectedItem.set({
+            id: '30001',
+            cmd: '/media/file_30001.mpg',
+            info: {
+                name: 'Regular Series',
+                description: 'Series description',
+                movie_image: 'poster.jpg',
+                tmdb_id: 777,
+            },
+        } as never);
+        await stabilize();
+
+        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 1);
+    });
+
+    it('waits for the season map before fetching so a per-season slice gets the title-marked season', async () => {
+        serialSeasonsResource.set([]);
+        selectedItem.set({
+            id: '30001',
+            cmd: '/media/file_30001.mpg',
+            info: {
+                name: 'Regular Series (2 season)',
+                description: 'Series description',
+                movie_image: 'poster.jpg',
+                tmdb_id: 777,
+            },
+        } as never);
+        await stabilize();
+
+        fixture.componentInstance.onSeasonSelected('2');
+        await stabilize();
+
+        // Season resource still loading — fetching now would pass a zero
+        // season count, suppress the title-marker override and cache the
+        // wrong season forever (fetchSeason is idempotent).
+        expect(tmdbGetSeason).not.toHaveBeenCalled();
+
+        serialSeasonsResource.set([
+            {
+                id: 'season-1',
+                name: 'Season 1',
+                cmd: '/media/file_30001.mpg',
+                series: [1, 2],
+            },
+        ]);
+        await stabilize();
+
+        // Single-season slice whose provider season is renumbered to 1:
+        // the title marker names the real TMDB season.
+        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 2);
+    });
+
+    it('gates the fetch on the reloading season resource during detail-to-detail navigation', async () => {
+        await stabilize();
+
+        fixture.componentInstance.onSeasonSelected('1');
+        await stabilize();
+        // No show-level TMDB match yet — nothing fetched for the first item
+        expect(tmdbGetSeason).not.toHaveBeenCalled();
+
+        // Detail-to-detail navigation reuses the component; the new item's
+        // TMDB match can arrive while the season resource reloads and the
+        // map still shows the previous series' seasons.
+        isSerialSeasonsLoading.set(true);
+        selectedItem.set({
+            id: '30002',
+            cmd: '/media/file_30002.mpg',
+            info: {
+                name: 'Other Series (2 season)',
+                description: 'Other description',
+                movie_image: 'poster2.jpg',
+                tmdb_id: 888,
+            },
+        } as never);
+        await stabilize();
+
+        // The new tmdb_id must NOT pair with the previous series' season
+        // context while the resource reloads.
+        expect(tmdbGetSeason).not.toHaveBeenCalled();
+
+        // Once the new item's own seasons land, the fetch runs without a
+        // stale-season fetch. The container selects the corrected key once
+        // the new season map is rendered.
+        serialSeasonsResource.set([
+            {
+                id: 'season-1',
+                name: 'Season 1',
+                cmd: '/media/file_30002.mpg',
+                series: [1, 2],
+            },
+        ]);
+        isSerialSeasonsLoading.set(false);
+        fixture.componentInstance.onSeasonSelected('2');
+        await stabilize();
+        expect(tmdbGetSeason).toHaveBeenCalledWith(888, 2);
+    });
+
+    it('enriches after equal-id navigation once the season resource settles', async () => {
+        await stabilize();
+        fixture.componentInstance.onSeasonSelected('1');
+        await stabilize();
+
+        // Distinct items can reuse a provider id; the loading gate (not an
+        // id comparison) keeps the stale map from being used.
+        isSerialSeasonsLoading.set(true);
+        selectedItem.set({
+            id: '30001',
+            cmd: '/media/file_30001.mpg',
+            info: {
+                name: 'Different Series (3 season)',
+                description: 'Different description',
+                movie_image: 'poster3.jpg',
+                tmdb_id: 999,
+            },
+        } as never);
+        await stabilize();
+        expect(tmdbGetSeason).not.toHaveBeenCalled();
+
+        isSerialSeasonsLoading.set(false);
+        fixture.componentInstance.onSeasonSelected('3');
+        await stabilize();
+        expect(tmdbGetSeason).toHaveBeenCalledWith(999, 3);
+    });
+
+    it('reads the season marker from o_name when name is generic', async () => {
+        selectedItem.set({
+            id: '30001',
+            cmd: '/media/file_30001.mpg',
+            info: {
+                name: 'Regular Series',
+                o_name: 'Regular Series (2 season)',
+                description: 'Series description',
+                movie_image: 'poster.jpg',
+                tmdb_id: 777,
+            },
+        } as never);
+        await stabilize();
+
+        fixture.componentInstance.onSeasonSelected('2');
+        await stabilize();
+
+        expect(tmdbGetSeason).toHaveBeenCalledWith(777, 2);
+    });
+});
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-batch.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-batch.ts
new file mode 100644
index 000000000..73c4d510c
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-batch.ts
@@ -0,0 +1,113 @@
+import type { Logger } from '@iptvnator/portal/shared/util';
+import type { PlaybackPositionData } from '@iptvnator/shared/interfaces';
+import type { SeasonContainerSeriesPlaybackToggleRequest } from '@iptvnator/ui/components';
+import { StalkerSeriesPositionPartialSaveError } from './stalker-series-position-compatibility';
+
+export interface StalkerWatchToggleFeedback {
+    readonly marked: string;
+    readonly unmarked: string;
+    readonly partialMarked: string;
+    readonly partialUnmarked: string;
+    readonly failed: string;
+}
+
+// The marked and partial keys are scope-generic on purpose ("{{count}}
+// episodes marked as watched", "{{count}} marked · {{failed}} failed");
+// only unmark-success and failure name their scope.
+export const SEASON_WATCH_FEEDBACK: StalkerWatchToggleFeedback = {
+    marked: 'XTREAM.SEASON_MARKED_WATCHED',
+    unmarked: 'XTREAM.SEASON_MARKED_UNWATCHED',
+    partialMarked: 'XTREAM.SEASON_MARKED_WATCHED_PARTIAL',
+    partialUnmarked: 'XTREAM.SEASON_MARKED_UNWATCHED_PARTIAL',
+    failed: 'XTREAM.SEASON_WATCH_UPDATE_FAILED',
+};
+
+export const SERIES_WATCH_FEEDBACK: StalkerWatchToggleFeedback = {
+    marked: 'XTREAM.SEASON_MARKED_WATCHED',
+    unmarked: 'XTREAM.SERIES_MARKED_UNWATCHED',
+    partialMarked: 'XTREAM.SEASON_MARKED_WATCHED_PARTIAL',
+    partialUnmarked: 'XTREAM.SEASON_MARKED_UNWATCHED_PARTIAL',
+    failed: 'XTREAM.SERIES_WATCH_UPDATE_FAILED',
+};
+
+/** One watched/unwatched batch and what it needs from the page running it. */
+export interface StalkerWatchToggleBatch {
+    readonly request: SeasonContainerSeriesPlaybackToggleRequest;
+    readonly playlistId: string;
+    /** Whether the page still shows the series the batch was started on. */
+    readonly stillCurrent: () => boolean;
+    readonly feedback: StalkerWatchToggleFeedback;
+    readonly persist: (
+        playlistId: string,
+        position: PlaybackPositionData
+    ) => Promise<void>;
+    readonly clear: (
+        playlistId: string,
+        contentXtreamId: number
+    ) => Promise<void>;
+    /** Re-reads the catalog grid's progress badges; must not reject. */
+    readonly refreshCatalogPositions: (
+        playlistId: string
+    ) => Promise<void> | undefined;
+    /** Shows the translated feedback for `key`. */
+    readonly notify: (key: string, params?: object) => void;
+    readonly logger: Logger;
+}
+
+export async function runStalkerWatchToggleBatch(
+    batch: StalkerWatchToggleBatch
+): Promise<void> {
+    const { request, playlistId, feedback } = batch;
+    // Enqueue every episode synchronously: each mutation chains on
+    // the previous one's never-rejecting barrier, so the queue
+    // serializes the writes (incl. per-episode legacy-row cleanup)
+    // and reloads positions once after the whole chain drains.
+    const outcomes = await Promise.all(
+        request.requests.map((item) =>
+            (item.nextPosition
+                ? batch.persist(playlistId, item.nextPosition)
+                : batch.clear(playlistId, item.contentXtreamId)
+            ).then(
+                () => true,
+                // The scoped watched row was saved and published —
+                // only the legacy-row cleanup failed. The episode IS
+                // watched, so it must not count against the batch.
+                (error: unknown) =>
+                    error instanceof StalkerSeriesPositionPartialSaveError
+            )
+        )
+    );
+
+    const failed = outcomes.filter((ok) => !ok).length;
+    const succeeded = outcomes.length - failed;
+    if (failed > 0) {
+        batch.logger.error(
+            `Watched toggle: ${failed} of ${outcomes.length} episodes failed`
+        );
+    }
+    if (succeeded > 0) {
+        // Partial successes changed rows too — the catalog badge
+        // must follow even when the user already moved on. A failed
+        // refresh must not break the feedback flow below.
+        await batch.refreshCatalogPositions(playlistId);
+    }
+    if (!batch.stillCurrent()) {
+        return;
+    }
+
+    if (failed === 0) {
+        batch.notify(
+            request.markWatched ? feedback.marked : feedback.unmarked,
+            { count: succeeded }
+        );
+    } else if (succeeded > 0) {
+        batch.notify(
+            request.markWatched
+                ? feedback.partialMarked
+                : feedback.partialUnmarked,
+            { count: succeeded, failed }
+        );
+    } else {
+        batch.notify(feedback.failed);
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-toggle.service.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-toggle.service.ts
new file mode 100644
index 000000000..98fdb20a8
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-watch-toggle.service.ts
@@ -0,0 +1,323 @@
+import { Injectable, Signal, inject, signal } from '@angular/core';
+import { MatSnackBar } from '@angular/material/snack-bar';
+import { TranslateService } from '@ngx-translate/core';
+import {
+    createLogger,
+    isPortalPlaybackWatched,
+} from '@iptvnator/portal/shared/util';
+import {
+    isVodSeasonHydrationPending,
+    StalkerStore,
+    type StalkerSelectedVodItem,
+    type VodSeriesSeasonVm,
+} from '@iptvnator/portal/stalker/data-access';
+import type { XtreamSerieEpisode } from '@iptvnator/shared/interfaces';
+import {
+    buildSeriesWatchToggleRequest,
+    type SeasonContainerPlaybackToggleRequest,
+    type SeasonContainerSeasonPlaybackToggleRequest,
+    type SeasonContainerSeriesPlaybackToggleRequest,
+} from '@iptvnator/ui/components';
+import { StalkerCatalogFacadeService } from '../stalker-catalog-facade.service';
+import { toStalkerSeriesId } from './stalker-series-id';
+import { StalkerSeriesPositionsService } from './stalker-series-positions.service';
+import {
+    runStalkerWatchToggleBatch,
+    SEASON_WATCH_FEEDBACK,
+    SERIES_WATCH_FEEDBACK,
+    type StalkerWatchToggleFeedback,
+} from './stalker-series-watch-batch';
+
+interface StalkerSeriesWatchToggleBindings {
+    readonly displayItem: Signal<StalkerSelectedVodItem | null>;
+    /** `playlist:series` of the series on screen. */
+    readonly currentSeriesKey: Signal<string>;
+    readonly isVodSeries: Signal<boolean>;
+    readonly vodSeriesSeasons: Signal<VodSeriesSeasonVm[]>;
+    readonly mappedSeasons: Signal<Record<string, XtreamSerieEpisode[]>>;
+    /** Episodes playing or launching, which a series toggle never marks. */
+    readonly excludedEpisodeIds: () => ReadonlySet<number>;
+    /** Resolves true when the portal answered, false when the request failed. */
+    readonly loadEpisodesForSeason: (
+        season: VodSeriesSeasonVm
+    ) => Promise<boolean>;
+}
+
+/**
+ * Watched toggles of the Stalker series view: one episode, a season or the
+ * whole series (which also backs "Reset progress"). Component-scoped
+ * (provide it in the component's `providers`).
+ */
+@Injectable()
+export class StalkerSeriesWatchToggleService {
+    private readonly stalkerStore = inject(StalkerStore);
+    private readonly positions = inject(StalkerSeriesPositionsService);
+    private readonly snackBar = inject(MatSnackBar);
+    private readonly translateService = inject(TranslateService);
+    // Optional: absent in collection-detail mounts outside the catalog.
+    private readonly catalogFacade = inject(StalkerCatalogFacadeService, {
+        optional: true,
+    });
+    private readonly logger = createLogger('StalkerSeriesView');
+    private readonly bindings = signal<StalkerSeriesWatchToggleBindings | null>(
+        null
+    );
+    readonly seasonWatchBatchRunning = signal(false);
+    /**
+     * The episode chosen while a watched/reset batch still rewrote the rows
+     * a start resumes from; the last choice plays once the batch settled,
+     * and only on the series it was made for.
+     */
+    private choiceHeldForBatch: {
+        readonly seriesKey: string;
+        readonly play: () => void;
+    } | null = null;
+
+    bind(bindings: StalkerSeriesWatchToggleBindings): void {
+        this.bindings.set(bindings);
+    }
+
+    /** Holds `play` until the running batch settled, replacing an earlier choice. */
+    holdChoice(play: () => void): void {
+        this.choiceHeldForBatch = {
+            seriesKey: this.currentSeriesKey(),
+            play,
+        };
+    }
+
+    async handlePlaybackToggleRequested(
+        request: SeasonContainerPlaybackToggleRequest
+    ): Promise<void> {
+        const playlistId = this.stalkerStore.currentPlaylist()?._id;
+        if (!playlistId) {
+            return;
+        }
+
+        if (request.nextPosition) {
+            await this.positions.persistSeriesPosition(
+                playlistId,
+                request.nextPosition
+            );
+        } else {
+            await this.positions.clearSeriesPosition(
+                playlistId,
+                request.contentXtreamId
+            );
+        }
+        // Keep the catalog grid's progress badge in sync (ownership-checked
+        // inside the facade; no-op outside the catalog context). A failed
+        // refresh keeps the cache populated-but-stale.
+        await this.catalogFacade
+            ?.refreshPositions(playlistId)
+            .catch((error: unknown) =>
+                this.logger.warn('Catalog position refresh failed', error)
+            );
+    }
+
+    async handleSeasonPlaybackToggleRequested(
+        request: SeasonContainerSeasonPlaybackToggleRequest
+    ): Promise<void> {
+        const playlistId = this.stalkerStore.currentPlaylist()?._id;
+        if (
+            !playlistId ||
+            request.requests.length === 0 ||
+            this.seasonWatchBatchRunning()
+        ) {
+            return;
+        }
+        // The mutation context already keeps a stale batch out of the next
+        // series' state; the snackbars need the same ownership so feedback
+        // for the old season is not presented on a newly opened page.
+        const seriesXtreamId = this.shownSeriesId();
+        const stillCurrent = () =>
+            this.stalkerStore.currentPlaylist()?._id === playlistId &&
+            this.shownSeriesId() === seriesXtreamId;
+
+        this.seasonWatchBatchRunning.set(true);
+        try {
+            await this.runWatchToggleBatch(
+                request,
+                playlistId,
+                stillCurrent,
+                SEASON_WATCH_FEEDBACK
+            );
+        } finally {
+            this.endWatchBatch();
+        }
+    }
+
+    async handleSeriesPlaybackToggleRequested(
+        request: SeasonContainerSeriesPlaybackToggleRequest
+    ): Promise<void> {
+        const bindings = this.bindings();
+        const playlistId = this.stalkerStore.currentPlaylist()?._id;
+        if (!bindings || !playlistId || this.seasonWatchBatchRunning()) {
+            return;
+        }
+        const pendingSeasons = bindings.isVodSeries()
+            ? bindings
+                  .vodSeriesSeasons()
+                  .filter((season) => isVodSeasonHydrationPending(season))
+            : [];
+        // An empty request is only meaningful when unloaded seasons remain:
+        // every loaded episode is watched, so the container could not build
+        // a target list, but hydration below may still surface unwatched
+        // episodes to mark.
+        if (request.requests.length === 0 && pendingSeasons.length === 0) {
+            return;
+        }
+
+        const seriesXtreamId = this.shownSeriesId();
+        const stillCurrent = () =>
+            this.stalkerStore.currentPlaylist()?._id === playlistId &&
+            this.shownSeriesId() === seriesXtreamId;
+
+        this.seasonWatchBatchRunning.set(true);
+        try {
+            let effective: SeasonContainerSeriesPlaybackToggleRequest | null =
+                request;
+            if (pendingSeasons.length > 0) {
+                const hydrated = await this.hydrateSeasonsForSeriesToggle(
+                    bindings,
+                    pendingSeasons,
+                    stillCurrent
+                );
+                if (hydrated !== 'complete') {
+                    if (hydrated === 'failed' && stillCurrent()) {
+                        this.notifySeasonWatchToggle(
+                            SERIES_WATCH_FEEDBACK.failed
+                        );
+                    }
+                    return;
+                }
+                // The reconcile effect only flushes on the next change-
+                // detection tick; rebuild the maps synchronously so the
+                // batch below sees the hydrated episodes' scoped and legacy
+                // rows (see applyReconciledSeriesPositions).
+                this.positions.applyReconciledSeriesPositions();
+                effective = buildSeriesWatchToggleRequest({
+                    seasons: bindings.mappedSeasons(),
+                    seriesId: seriesXtreamId,
+                    playlistId,
+                    isEpisodeWatched: (episode) =>
+                        isPortalPlaybackWatched(
+                            this.positions
+                                .episodePlaybackPositions()
+                                .get(Number(episode.id))
+                        ),
+                    excludedEpisodeIds: bindings.excludedEpisodeIds(),
+                    // Keep the direction the user clicked; re-inference over
+                    // the now-complete data could flip a "mark" into an
+                    // unwatch when everything turned out watched.
+                    markWatched: request.markWatched,
+                });
+                if (!effective) {
+                    if (stillCurrent()) {
+                        this.notifySeasonWatchToggle(
+                            SERIES_WATCH_FEEDBACK.marked,
+                            { count: 0 }
+                        );
+                    }
+                    return;
+                }
+            }
+
+            await this.runWatchToggleBatch(
+                effective,
+                playlistId,
+                stillCurrent,
+                SERIES_WATCH_FEEDBACK
+            );
+        } finally {
+            this.endWatchBatch();
+        }
+    }
+
+    private currentSeriesKey(): string {
+        return this.bindings()?.currentSeriesKey() ?? '';
+    }
+
+    private shownSeriesId(): number {
+        return toStalkerSeriesId(this.bindings()?.displayItem()?.id ?? 0);
+    }
+
+    /**
+     * The batch settled: the choice held meanwhile goes through the usual
+     * gates, unless the viewer switched series since. Episode identities
+     * overlap across series, so it must never resolve against another one.
+     */
+    private endWatchBatch(): void {
+        this.seasonWatchBatchRunning.set(false);
+        const held = this.choiceHeldForBatch;
+        this.choiceHeldForBatch = null;
+        if (held && held.seriesKey === this.currentSeriesKey()) {
+            held.play();
+        }
+    }
+
+    /**
+     * Sequential on purpose: loadEpisodesForSeason snapshots the season VM
+     * array before its writes, so concurrent calls clobber each other's
+     * loading flags; and one request at a time keeps the portal load bounded.
+     */
+    private async hydrateSeasonsForSeriesToggle(
+        bindings: StalkerSeriesWatchToggleBindings,
+        pendingSeasons: readonly VodSeriesSeasonVm[],
+        stillCurrent: () => boolean
+    ): Promise<'complete' | 'failed' | 'superseded'> {
+        for (const season of pendingSeasons) {
+            // A tab click may have loaded this season meanwhile.
+            const current = bindings
+                .vodSeriesSeasons()
+                .find((candidate) => candidate.id === season.id);
+            if (!current || !isVodSeasonHydrationPending(current)) {
+                continue;
+            }
+            const answered = await bindings.loadEpisodesForSeason(current);
+            if (!stillCurrent()) {
+                return 'superseded';
+            }
+            if (!answered) {
+                return 'failed';
+            }
+        }
+        return 'complete';
+    }
+
+    private runWatchToggleBatch(
+        request: SeasonContainerSeriesPlaybackToggleRequest,
+        playlistId: string,
+        stillCurrent: () => boolean,
+        feedback: StalkerWatchToggleFeedback
+    ): Promise<void> {
+        return runStalkerWatchToggleBatch({
+            request,
+            playlistId,
+            stillCurrent,
+            feedback,
+            persist: (id, position) =>
+                this.positions.persistSeriesPosition(id, position),
+            clear: (id, contentXtreamId) =>
+                this.positions.clearSeriesPosition(id, contentXtreamId),
+            refreshCatalogPositions: (id) =>
+                this.catalogFacade
+                    ?.refreshPositions(id)
+                    .catch((error: unknown) =>
+                        this.logger.warn(
+                            'Catalog position refresh failed',
+                            error
+                        )
+                    ),
+            notify: (key, params) => this.notifySeasonWatchToggle(key, params),
+            logger: this.logger,
+        });
+    }
+
+    private notifySeasonWatchToggle(key: string, params?: object): void {
+        this.snackBar.open(
+            this.translateService.instant(key, params),
+            undefined,
+            { duration: 5000 }
+        );
+    }
+}
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-vod-season-episode-loader.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-vod-season-episode-loader.ts
new file mode 100644
index 000000000..585f71e05
--- /dev/null
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-vod-season-episode-loader.ts
@@ -0,0 +1,125 @@
+import type { WritableSignal } from '@angular/core';
+import {
+    getVodSeriesSeasonKey,
+    type VodSeriesSeasonVm,
+} from '@iptvnator/portal/stalker/data-access';
+
+/** What the loader needs from the page that shows the seasons. */
+export interface StalkerVodSeasonEpisodeLoaderHost {
+    /** Seasons of the series on screen; a load writes its loading flag and episodes here. */
+    readonly seasons: WritableSignal<VodSeriesSeasonVm[]>;
+    /** Identity of the series on screen: part of the key in-flight loads are shared by. */
+    readonly ownerKey: () => string;
+    readonly fetchEpisodes: (
+        videoId: string,
+        seasonId: string
+    ) => Promise<VodSeriesSeasonVm['episodes']>;
+    readonly logError: (message: string, error: unknown) => void;
+}
+
+/** Lazy episode loads of Ministra VOD-series seasons (`is_series=1`). */
+export class StalkerVodSeasonEpisodeLoader {
+    private readonly loads = new Map<
+        string,
+        { season: VodSeriesSeasonVm; promise: Promise<boolean> }
+    >();
+
+    constructor(private readonly host: StalkerVodSeasonEpisodeLoaderHost) {}
+
+    /**
+     * Loads episodes for a specific VOD season.
+     *
+     * Single-flight per season: a tab click, the spillover prefetch, the
+     * quick-start recursion, and the series-toggle hydration can all ask for
+     * the same season — a second concurrent request would duplicate portal
+     * traffic, and its failure could abort a series toggle whose original
+     * request succeeded.
+     */
+    /** Resolves true when the portal answered, false when the request failed. */
+    load(season: VodSeriesSeasonVm): Promise<boolean> {
+        const key = JSON.stringify([
+            this.host.ownerKey(),
+            season.video_id,
+            season.id,
+            getVodSeriesSeasonKey(season),
+        ]);
+        const inFlight = this.loads.get(key);
+        if (inFlight && this.host.seasons().includes(inFlight.season)) {
+            return inFlight.promise;
+        }
+        const load = this.fetch(season).finally(() => {
+            if (this.loads.get(key)?.promise === load) {
+                this.loads.delete(key);
+            }
+        });
+        const loadingSeason = this.host
+            .seasons()
+            .find(
+                (candidate) =>
+                    candidate.id === season.id &&
+                    candidate.video_id === season.video_id
+            );
+        if (loadingSeason) {
+            this.loads.set(key, {
+                season: loadingSeason,
+                promise: load,
+            });
+        }
+        return load;
+    }
+
+    private async fetch(season: VodSeriesSeasonVm): Promise<boolean> {
+        // Set loading state in local signal
+        const seasons = this.host.seasons();
+        const index = seasons.findIndex(
+            (s) =>
+                s.id === season.id &&
+                s.video_id === season.video_id &&
+                getVodSeriesSeasonKey(s) === getVodSeriesSeasonKey(season)
+        );
+        if (index === -1) return false;
+
+        const updatedSeasons = [...seasons];
+        const loadingSeason = { ...updatedSeasons[index], isLoading: true };
+        updatedSeasons[index] = loadingSeason;
+        this.host.seasons.set(updatedSeasons);
+
+        try {
+            const episodes = await this.host.fetchEpisodes(
+                season.video_id,
+                season.id
+            );
+
+            // Update with loaded episodes
+            const newSeasons = [...this.host.seasons()];
+            // Only the exact loading VM owns this response. A navigation or
+            // refresh can reuse provider ids while replacing the season list.
+            const newIndex = newSeasons.indexOf(loadingSeason);
+            if (newIndex !== -1) {
+                newSeasons[newIndex] = {
+                    ...newSeasons[newIndex],
+                    episodes: episodes,
+                    // Even an EMPTY answer marks the season loaded: the
+                    // portal spoke, so it must stop counting as "unloaded"
+                    // (label/verdict gating and series-toggle hydration).
+                    episodesLoaded: true,
+                    isLoading: false,
+                };
+                this.host.seasons.set(newSeasons);
+            }
+            return newIndex !== -1;
+        } catch (error) {
+            this.host.logError('Failed to load episodes', error);
+            const newSeasons = [...this.host.seasons()];
+            const newIndex = newSeasons.indexOf(loadingSeason);
+            if (newIndex !== -1) {
+                newSeasons[newIndex] = {
+                    ...newSeasons[newIndex],
+                    isLoading: false,
+                };
+                this.host.seasons.set(newSeasons);
+            }
+            return false;
+        }
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-playback.service.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-playback.service.ts
index 023dd595e..0ebc12109 100644
--- a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-playback.service.ts
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-playback.service.ts
@@ -23,7 +23,6 @@ import {
     ExternalPlayerName,
     ExternalPlayerSession,
     PlaybackPositionData,
-    PlayerContentInfo,
     ResolvedPortalPlayback,
     XtreamSerieDetails,
     XtreamSerieEpisode,
@@ -37,7 +36,6 @@ import {
     getSeriesPlaybackNavigation,
     inlineSeriesEpisodeState,
     type PlaybackFallbackRequest,
-    resolveSeriesPlaybackEpisodeState,
     type SeriesPlaybackEpisodeState,
 } from '@iptvnator/ui/playback';
 import { injectXtreamRecentHistory } from '../xtream-recent-history';
@@ -53,6 +51,8 @@ import {
     SerialDetailsSeasonWatchService,
     type SerialDetailsWatchScope,
 } from './serial-details-season-watch.service';
+import { SerialDetailsWatchToggles } from './serial-details-watch-toggles';
+import { buildSerialEpisodePlayback } from './serial-episode-playback';
 
 export type XtreamSerieDetailsView = XtreamSerieDetails & {
     readonly series_id: number;
@@ -97,6 +97,15 @@ export class SerialDetailsPlaybackService {
     );
     private readonly playbackPositionState =
         new SerialDetailsPlaybackPositionState();
+    private readonly watchToggles = new SerialDetailsWatchToggles({
+        playbackPositions: this.playbackPositions,
+        seasonWatch: this.seasonWatch,
+        state: this.playbackPositionState,
+        playlistId: () => this.currentPlaylistId(),
+        seriesXtreamId: () => Number(this.selectedItem()?.series_id ?? 0),
+        reloadStorePositions: (playlistId) =>
+            this.xtreamStore.loadAllPositions(playlistId),
+    });
     private lastSaveTime = 0;
 
     readonly inlinePlayback = signal<ResolvedPortalPlayback | null>(null);
@@ -229,32 +238,15 @@ export class SerialDetailsPlaybackService {
             contentType: 'series',
             backdropUrl: selectedItem.info?.backdrop_path?.[0],
         });
-        const contentInfo: PlayerContentInfo = {
-            playlistId: playlist.id,
-            contentXtreamId: Number(episode.id),
-            contentType: 'episode',
-            seriesXtreamId: Number(selectedItem.series_id),
-            seasonNumber: Number(episode.season),
-            episodeNumber: Number(episode.episode_num),
-        };
-
         const position = this.episodePlaybackPositions().get(
             Number(episode.id)
         );
-
-        const playback: ResolvedPortalPlayback = {
+        const { playback, episodeState } = buildSerialEpisodePlayback({
+            playlistId: playlist.id,
+            selectedItem,
+            episode,
             streamUrl,
-            title: episode.title,
-            thumbnail: selectedItem.info.cover,
             startTime: position?.positionSeconds,
-            contentInfo,
-        };
-
-        const episodeState = resolveSeriesPlaybackEpisodeState({
-            episodesBySeason: selectedItem.episodes,
-            currentEpisodeId: episode.id,
-            fallbackSeasonNumber: Number(episode.season),
-            fallbackEpisodeNumber: Number(episode.episode_num),
         });
         return this.startPlayback(playback, episodeState, player);
     }
@@ -322,68 +314,17 @@ export class SerialDetailsPlaybackService {
         );
     }
 
-    async handlePlaybackToggleRequested(
+    handlePlaybackToggleRequested(
         request: SeasonContainerPlaybackToggleRequest
     ): Promise<void> {
-        const playlistId = this.currentPlaylistId();
-        if (!playlistId) {
-            return;
-        }
-
-        if (request.nextPosition) {
-            await this.playbackPositions.savePlaybackPosition(
-                playlistId,
-                request.nextPosition
-            );
-            this.playbackPositionState.update(request.nextPosition);
-        } else {
-            await this.playbackPositions.clearPlaybackPosition(
-                playlistId,
-                request.contentXtreamId,
-                'episode'
-            );
-            this.playbackPositionState.remove(request.contentXtreamId);
-        }
-        await this.refreshStorePositions(playlistId);
+        return this.watchToggles.toggleEpisode(request);
     }
 
-    async handleWatchToggleRequested(
+    handleWatchToggleRequested(
         request: SeasonContainerSeriesPlaybackToggleRequest,
         scope: SerialDetailsWatchScope
     ): Promise<void> {
-        const playlistId = this.currentPlaylistId();
-        const seriesXtreamId = Number(this.selectedItem()?.series_id ?? 0);
-        const persisted = await this.seasonWatch.handle(
-            request,
-            playlistId,
-            this.playbackPositionState,
-            () =>
-                this.currentPlaylistId() === playlistId &&
-                Number(this.selectedItem()?.series_id ?? 0) === seriesXtreamId,
-            scope
-        );
-        if (persisted) {
-            await this.refreshStorePositions(playlistId);
-        }
-    }
-
-    /**
-     * The catalog reads series progress from XtreamStore, whose positions
-     * load once per playlist (XtreamCatalogFacadeService.initialize), so a
-     * toggle must push the change back or badges go stale on return. Skipped
-     * after a playlist switch — the store then holds the other playlist.
-     */
-    private async refreshStorePositions(playlistId: string): Promise<void> {
-        if (this.currentPlaylistId() !== playlistId) {
-            return;
-        }
-        try {
-            await this.xtreamStore.loadAllPositions(playlistId);
-        } catch (error) {
-            // The toggle itself succeeded; a failed refresh keeps the store
-            // populated-but-stale, which beats wiping it with a bad read.
-            this.logger.warn('Store position refresh failed', error);
-        }
+        return this.watchToggles.toggleBatch(request, scope);
     }
 
     async loadSeriesPlaybackPositions(
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-route.service.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-route.service.ts
new file mode 100644
index 000000000..c819a3631
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-route.service.ts
@@ -0,0 +1,75 @@
+import { computed, inject, Injectable, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { ActivatedRoute } from '@angular/router';
+import { isProviderOnlyDetailState } from '@iptvnator/portal/shared/util';
+import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
+import { SerialDetailsPlaybackService } from './serial-details-playback.service';
+
+/**
+ * Route side of the series page: its params, the provider-only flag of the
+ * navigation that opened it, and the (re)load of the series the route
+ * addresses.
+ */
+@Injectable()
+export class SerialDetailsRouteService {
+    private readonly route = inject(ActivatedRoute);
+    private readonly xtreamStore = inject(XtreamStore);
+    private readonly playback = inject(SerialDetailsPlaybackService);
+    /** `playlistId:categoryId:serialId` of the last initialized view */
+    private readonly lastInitKey = signal<string | null>(null);
+
+    /**
+     * Reactive route params: the component is reused when navigating
+     * between two series details (e.g. via the Similar rail).
+     */
+    readonly params = toSignal(this.route.params, {
+        initialValue: this.route.snapshot.params,
+    });
+    readonly providerOnly = computed(() => {
+        this.params();
+        return isProviderOnlyDetailState(window.history.state);
+    });
+
+    /**
+     * Initializes on first render and RE-initializes when the route params
+     * change while the component is reused (Similar rail). Reads signals, so
+     * the owning component runs it from an effect.
+     */
+    loadAddressedSeries(): void {
+        const playlistId = this.xtreamStore.currentPlaylist()?.id;
+        const { categoryId, serialId } = this.params();
+        if (!playlistId || !serialId) {
+            return;
+        }
+
+        const initKey = `${playlistId}:${categoryId}:${serialId}`;
+        if (this.lastInitKey() === initKey) {
+            return;
+        }
+        this.lastInitKey.set(initKey);
+
+        this.playback.resetForNewSeries();
+        this.initializeSerialDetails(playlistId, categoryId, serialId);
+    }
+
+    private initializeSerialDetails(
+        playlistId: string,
+        categoryId: string | number,
+        serialId: string
+    ): void {
+        this.xtreamStore.fetchSerialDetailsWithMetadata({
+            serialId,
+            categoryId: Number(categoryId),
+        });
+        const serialXtreamId = Number(serialId);
+        this.xtreamStore.checkFavoriteStatus(
+            serialXtreamId,
+            playlistId,
+            'series'
+        );
+        void this.playback.loadSeriesPlaybackPositions(
+            playlistId,
+            serialXtreamId
+        );
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-seasons.service.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-seasons.service.ts
new file mode 100644
index 000000000..7da3ed964
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-seasons.service.ts
@@ -0,0 +1,75 @@
+import {
+    computed,
+    effect,
+    inject,
+    Injectable,
+    Signal,
+    signal,
+    untracked,
+} from '@angular/core';
+import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
+import { buildSeasonDescriptions } from './season-descriptions.util';
+import { buildSeasonPosters } from './season-posters.util';
+import type { XtreamSerieDetailsView } from './serial-details-playback.service';
+
+interface SerialDetailsSeasonsBindings {
+    readonly selectedItem: Signal<XtreamSerieDetailsView | null>;
+}
+
+/**
+ * Season presentation of the series page: the descriptions and posters the
+ * season container and the inline player show, and the TMDB enrichment of
+ * the season the viewer selected.
+ */
+@Injectable()
+export class SerialDetailsSeasonsService {
+    private readonly xtreamStore = inject(XtreamStore);
+    private readonly bindings = signal<SerialDetailsSeasonsBindings | null>(
+        null
+    );
+    private readonly selectedItem = computed(
+        () => this.bindings()?.selectedItem() ?? null
+    );
+
+    /** Season currently selected in the season container. */
+    private readonly selectedSeasonKey = signal<string | null>(null);
+
+    /** Season descriptions (provider text, TMDB fallback, URL junk dropped). */
+    readonly descriptions = computed<Record<string, string>>(() =>
+        buildSeasonDescriptions(this.selectedItem())
+    );
+
+    /** Season posters (TMDB season poster first, provider season cover next). */
+    readonly posters = computed<Record<string, string>>(() =>
+        buildSeasonPosters(this.selectedItem())
+    );
+
+    constructor() {
+        // TMDB season enrichment, keyed on (tmdb_id, selected season). With
+        // season tabs the first seasonSelected fires as soon as seasons load —
+        // usually BEFORE the async show-level TMDB match has written
+        // info.tmdb_id, and enrichSelectedSerialSeason no-ops without it. So
+        // the call must re-run when the match arrives, not only on selection.
+        // The store-side enrichment is idempotent per (serial, season).
+        effect(() => {
+            const tmdbId = this.selectedItem()?.info?.tmdb_id;
+            const seasonKey = this.selectedSeasonKey();
+            if (tmdbId && seasonKey) {
+                untracked(() =>
+                    this.xtreamStore.enrichSelectedSerialSeason(seasonKey)
+                );
+            }
+        });
+    }
+
+    /** Connects the service to the owning component's reactive state. */
+    bind(bindings: SerialDetailsSeasonsBindings): void {
+        this.bindings.set(bindings);
+    }
+
+    select(seasonKey: string): void {
+        // The enrichment call itself runs from the constructor effect keyed
+        // on (tmdb_id, selectedSeasonKey) — see the race note there.
+        this.selectedSeasonKey.set(seasonKey);
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-watch-toggles.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-watch-toggles.ts
new file mode 100644
index 000000000..e3df80803
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-watch-toggles.ts
@@ -0,0 +1,104 @@
+import {
+    createLogger,
+    type PortalPlaybackPositions,
+} from '@iptvnator/portal/shared/util';
+import type {
+    SeasonContainerPlaybackToggleRequest,
+    SeasonContainerSeriesPlaybackToggleRequest,
+} from '@iptvnator/ui/components';
+import type { SerialDetailsPlaybackPositionState } from './serial-details-playback-position-state';
+import type {
+    SerialDetailsSeasonWatchService,
+    SerialDetailsWatchScope,
+} from './serial-details-season-watch.service';
+
+const logger = createLogger('SerialDetailsPlayback');
+
+/** What the watched toggles of the series page persist through and report to. */
+export interface SerialDetailsWatchToggleDeps {
+    readonly playbackPositions: Pick<
+        PortalPlaybackPositions,
+        'savePlaybackPosition' | 'clearPlaybackPosition'
+    >;
+    readonly seasonWatch: Pick<SerialDetailsSeasonWatchService, 'handle'>;
+    readonly state: SerialDetailsPlaybackPositionState;
+    /** Playlist on screen, empty while none is current. */
+    readonly playlistId: () => string;
+    /** Series on screen, 0 while none is selected. */
+    readonly seriesXtreamId: () => number;
+    /** Reloads the catalog store's positions of a playlist. */
+    readonly reloadStorePositions: (playlistId: string) => Promise<unknown>;
+}
+
+/**
+ * Episode, season and series watched toggles of the series page: persists
+ * the change, mirrors it into the page's position state, and pushes it back
+ * to the catalog store.
+ */
+export class SerialDetailsWatchToggles {
+    constructor(private readonly deps: SerialDetailsWatchToggleDeps) {}
+
+    async toggleEpisode(
+        request: SeasonContainerPlaybackToggleRequest
+    ): Promise<void> {
+        const playlistId = this.deps.playlistId();
+        if (!playlistId) {
+            return;
+        }
+
+        if (request.nextPosition) {
+            await this.deps.playbackPositions.savePlaybackPosition(
+                playlistId,
+                request.nextPosition
+            );
+            this.deps.state.update(request.nextPosition);
+        } else {
+            await this.deps.playbackPositions.clearPlaybackPosition(
+                playlistId,
+                request.contentXtreamId,
+                'episode'
+            );
+            this.deps.state.remove(request.contentXtreamId);
+        }
+        await this.refreshStorePositions(playlistId);
+    }
+
+    async toggleBatch(
+        request: SeasonContainerSeriesPlaybackToggleRequest,
+        scope: SerialDetailsWatchScope
+    ): Promise<void> {
+        const playlistId = this.deps.playlistId();
+        const seriesXtreamId = this.deps.seriesXtreamId();
+        const persisted = await this.deps.seasonWatch.handle(
+            request,
+            playlistId,
+            this.deps.state,
+            () =>
+                this.deps.playlistId() === playlistId &&
+                this.deps.seriesXtreamId() === seriesXtreamId,
+            scope
+        );
+        if (persisted) {
+            await this.refreshStorePositions(playlistId);
+        }
+    }
+
+    /**
+     * The catalog reads series progress from XtreamStore, whose positions
+     * load once per playlist (XtreamCatalogFacadeService.initialize), so a
+     * toggle must push the change back or badges go stale on return. Skipped
+     * after a playlist switch — the store then holds the other playlist.
+     */
+    private async refreshStorePositions(playlistId: string): Promise<void> {
+        if (this.deps.playlistId() !== playlistId) {
+            return;
+        }
+        try {
+            await this.deps.reloadStorePositions(playlistId);
+        } catch (error) {
+            // The toggle itself succeeded; a failed refresh keeps the store
+            // populated-but-stale, which beats wiping it with a bad read.
+            logger.warn('Store position refresh failed', error);
+        }
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.spec.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.spec.ts
index 7b2b21177..6cb7cc12d 100644
--- a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.spec.ts
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.spec.ts
@@ -1,361 +1,46 @@
-import {
-    Component,
-    input,
-    output,
-    signal,
-    ChangeDetectionStrategy,
-} from '@angular/core';
 import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
-import { Location } from '@angular/common';
-import { MatIcon } from '@angular/material/icon';
-import { MatSnackBar } from '@angular/material/snack-bar';
-import { ActivatedRoute } from '@angular/router';
-import { TranslatePipe, TranslateService } from '@ngx-translate/core';
-import { MockPipe } from 'ng-mocks';
-import {
-    ContentHeroComponent,
-    SeasonContainerComponent,
-} from '@iptvnator/ui/components';
-import {
-    PORTAL_EXTERNAL_PLAYBACK,
-    PORTAL_PLAYBACK_POSITIONS,
-    PORTAL_PLAYER,
-    SeriesResumeTarget,
-} from '@iptvnator/portal/shared/util';
-import type { SeasonEpisodeDownloadAdapter } from '@iptvnator/portal/shared/data-access';
-import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
-import {
-    DownloadsService,
-    PlaybackPositionRuntimeBridgeService,
-    SettingsStore,
-} from '@iptvnator/services';
+import { ContentHeroComponent } from '@iptvnator/ui/components';
 import { PlaybackHistoryGate } from '@iptvnator/playback/data-access';
-import {
-    PlaybackPositionData,
-    VideoPlayer,
-} from '@iptvnator/shared/interfaces';
-import { PortalInlinePlayerComponent } from '@iptvnator/ui/playback';
-import { BehaviorSubject, EMPTY, of } from 'rxjs';
+import { PlaybackPositionData } from '@iptvnator/shared/interfaces';
 import { SerialDetailsComponent } from './serial-details.component';
 import { SerialDetailsMenuService } from './serial-details-menu.service';
 import { SerialDetailsPlaybackService } from './serial-details-playback.service';
-import { XTREAM_SERIES_RESUME_TARGET } from './serial-details-resume-target.token';
 import { createPlaybackSessionKey } from '@iptvnator/playback/util';
-
-@Component({
-    selector: 'app-season-container',
-    standalone: true,
-    changeDetection: ChangeDetectionStrategy.Eager,
-    template: '<div data-testid="season-container"></div>',
-})
-class StubSeasonContainerComponent {
-    readonly seasons = input<unknown>(null);
-    readonly seriesId = input<number | string | null>(null);
-    readonly playlistId = input('');
-    readonly seriesTitle = input<string | undefined>(undefined);
-    readonly playbackPositions = input<unknown>(null);
-    readonly downloadAdapter = input<SeasonEpisodeDownloadAdapter | null>(null);
-    readonly downloadsEnabled = input(true);
-    readonly openingEpisodeId = input<number | null>(null);
-    readonly activeEpisodeId = input<number | null>(null);
-    readonly playingEpisodeId = input<number | null>(null);
-    readonly seasonDescriptions = input<unknown>(null);
-    readonly seasonPosters = input<unknown>(null);
-    readonly seasonWatchBatchRunning = input(false);
-    readonly episodeClicked = output<unknown>();
-    readonly playbackToggleRequested = output<unknown>();
-    readonly seasonPlaybackToggleRequested = output<unknown>();
-}
-
-@Component({
-    selector: 'app-portal-inline-player',
-    standalone: true,
-    changeDetection: ChangeDetectionStrategy.Eager,
-    template: '',
-})
-class StubPortalInlinePlayerComponent {
-    readonly playbackSessionKey = input.required<string>();
-    readonly playback = input<unknown>(null);
-    readonly episodeMetadata = input<unknown>(null);
-    readonly seriesTitle = input<string | null>(null);
-    readonly seriesNavigation = input<unknown>(null);
-    readonly upNextEpisodes = input<unknown>(null);
-    readonly seriesEpisodes = input<unknown>(null);
-    readonly seasonPosters = input<unknown>(null);
-    readonly episodePlaybackPositions = input<unknown>(null);
-    readonly seasonLoadStates = input<unknown>(null);
-    readonly timeUpdate = output<unknown>();
-    readonly closed = output<void>();
-    readonly streamUrlCopied = output<void>();
-    readonly externalFallbackRequested = output<unknown>();
-    readonly playbackEnded = output<void>();
-    readonly previousEpisodeRequested = output<void>();
-    readonly nextEpisodeRequested = output<void>();
-    readonly upNextEpisodeSelected = output<unknown>();
-    readonly episodePanelSeasonSelected = output<string>();
-}
-
-@Component({
-    selector: 'mat-icon',
-    standalone: true,
-    changeDetection: ChangeDetectionStrategy.Eager,
-    template: '<ng-content />',
-})
-class StubMatIconComponent {}
+import {
+    configureSerialDetailsTestBed,
+    createSerialDetailsStubs,
+    resetSerialDetailsStubs,
+} from './serial-details.harness';
+import {
+    StubPortalInlinePlayerComponent,
+    StubSeasonContainerComponent,
+} from './serial-details.test-stubs';
 
 describe('SerialDetailsComponent', () => {
     let fixture: ComponentFixture<SerialDetailsComponent>;
-    const selectedItem = signal<unknown>(null);
-    const selectedContentType = signal<'series'>('series');
-    const isFavorite = signal(false);
-    const isLoadingDetails = signal(false);
-    const detailsError = signal<string | null>(null);
-    const currentPlaylist = signal({
-        id: 'xtream-1',
-        serverUrl: 'http://xtream.example',
-        username: 'user',
-        password: 'pass',
-        userAgent: 'ProtectedProvider/2.0',
-        referrer: 'https://referrer.example/series',
-        origin: 'https://origin.example',
-    });
-    const fetchSerialDetailsWithMetadata = jest.fn();
-    const cancelDetailsRequest = jest.fn();
-    const checkFavoriteStatus = jest.fn();
-    const constructEpisodeStreamUrl = jest.fn();
-    const addRecentItem = jest.fn();
-    const openResolvedPlayback = jest.fn();
-    const openExternalPlayback = jest.fn();
-    const savePlaybackPosition = jest.fn();
-    const clearPlaybackPosition = jest.fn();
-    const savePlaybackPositionsBatch = jest.fn();
-    const clearPlaybackPositionsBatch = jest.fn();
-    const loadAllPositions = jest.fn();
-    const isEmbeddedPlayer = jest.fn();
-    const getSeriesPlaybackPositions = jest.fn().mockResolvedValue([]);
-    let positionUpdateCallback: ((data: PlaybackPositionData) => void) | null =
-        null;
-    let seriesResumeTarget: ReturnType<
-        typeof signal<SeriesResumeTarget | null>
-    >;
-    let routeParams: BehaviorSubject<{
-        categoryId: string;
-        serialId: string;
-    }>;
+    const stubs = createSerialDetailsStubs();
+    const {
+        selectedItem,
+        currentPlaylist,
+        fetchSerialDetailsWithMetadata,
+        cancelDetailsRequest,
+        checkFavoriteStatus,
+        constructEpisodeStreamUrl,
+        addRecentItem,
+        openResolvedPlayback,
+        openExternalPlayback,
+        savePlaybackPosition,
+        isEmbeddedPlayer,
+        getSeriesPlaybackPositions,
+        seriesResumeTarget,
+        routeParams,
+    } = stubs;
 
     beforeEach(async () => {
         window.history.replaceState({}, '', window.location.href);
-        selectedItem.set({
-            series_id: 103,
-            info: {
-                name: 'Series One',
-                plot: 'Series plot',
-                cover: 'cover.jpg',
-                backdrop_path: [],
-                genre: 'Drama',
-                category_id: '3',
-                tmdb_id: 901,
-                tmdb_cast: [{ name: 'Sienna Wave', character: 'Mara' }],
-            },
-            episodes: {
-                '1': [
-                    {
-                        id: '1001',
-                        episode_num: 1,
-                        title: 'Episode 1',
-                        season: 1,
-                    },
-                    {
-                        id: '1002',
-                        episode_num: 2,
-                        title: 'Episode 2',
-                        season: 1,
-                    },
-                ],
-                '2': [
-                    {
-                        id: '2001',
-                        episode_num: 1,
-                        title: 'Season 2 Episode 1',
-                        season: 2,
-                    },
-                ],
-            },
-        });
-        isFavorite.set(false);
-        isLoadingDetails.set(false);
-        detailsError.set(null);
-        fetchSerialDetailsWithMetadata.mockClear();
-        cancelDetailsRequest.mockClear();
-        checkFavoriteStatus.mockClear();
-        constructEpisodeStreamUrl.mockReset();
-        constructEpisodeStreamUrl.mockImplementation(
-            (episode: { id: string | number }) =>
-                `http://xtream.example/series/${episode.id}.mp4`
-        );
-        addRecentItem.mockClear();
-        openResolvedPlayback.mockReset();
-        openResolvedPlayback.mockResolvedValue(undefined);
-        openExternalPlayback.mockReset();
-        openExternalPlayback.mockResolvedValue(undefined);
-        savePlaybackPosition.mockReset();
-        savePlaybackPosition.mockResolvedValue(undefined);
-        clearPlaybackPosition.mockReset();
-        clearPlaybackPosition.mockResolvedValue(undefined);
-        savePlaybackPositionsBatch.mockReset();
-        savePlaybackPositionsBatch.mockResolvedValue(undefined);
-        clearPlaybackPositionsBatch.mockReset();
-        clearPlaybackPositionsBatch.mockResolvedValue(undefined);
-        loadAllPositions.mockReset();
-        loadAllPositions.mockResolvedValue(undefined);
-        positionUpdateCallback = null;
-        isEmbeddedPlayer.mockReset();
-        isEmbeddedPlayer.mockReturnValue(false);
-        getSeriesPlaybackPositions.mockClear();
-        getSeriesPlaybackPositions.mockResolvedValue([]);
-        seriesResumeTarget = signal<SeriesResumeTarget | null>(null);
-        routeParams = new BehaviorSubject({
-            categoryId: '3',
-            serialId: '103',
-        });
-
-        await TestBed.configureTestingModule({
-            imports: [SerialDetailsComponent],
-            providers: [
-                {
-                    provide: ActivatedRoute,
-                    useValue: {
-                        params: routeParams,
-                        snapshot: {
-                            params: {
-                                categoryId: '3',
-                                serialId: '103',
-                            },
-                        },
-                    },
-                },
-                {
-                    provide: XtreamStore,
-                    useValue: {
-                        selectedItem,
-                        selectedContentType,
-                        isFavorite,
-                        isLoadingDetails,
-                        detailsError,
-                        currentPlaylist,
-                        fetchSerialDetailsWithMetadata,
-                        cancelDetailsRequest,
-                        checkFavoriteStatus,
-                        setSelectedItem: jest.fn((value: unknown) =>
-                            selectedItem.set(value)
-                        ),
-                        toggleFavorite: jest.fn(),
-                        constructEpisodeStreamUrl,
-                        addRecentItem,
-                        backfillContentMetadata: jest.fn(),
-                        loadAllPositions,
-                        recentItems: signal([]),
-                        serialCategories: signal([]),
-                        loadRecentItems: jest.fn(),
-                    },
-                },
-                {
-                    provide: SettingsStore,
-                    useValue: { player: signal(VideoPlayer.Html5Player) },
-                },
-                {
-                    provide: DownloadsService,
-                    useValue: { isAvailable: signal(false) },
-                },
-                {
-                    provide: PORTAL_EXTERNAL_PLAYBACK,
-                    useValue: {
-                        activeSession: signal(null),
-                    },
-                },
-                {
-                    provide: PORTAL_PLAYBACK_POSITIONS,
-                    useValue: {
-                        getSeriesPlaybackPositions,
-                        savePlaybackPosition,
-                        clearPlaybackPosition,
-                        savePlaybackPositionsBatch,
-                        clearPlaybackPositionsBatch,
-                    },
-                },
-                {
-                    provide: PORTAL_PLAYER,
-                    useValue: {
-                        isEmbeddedPlayer,
-                        openResolvedPlayback,
-                        openExternalPlayback,
-                    },
-                },
-                {
-                    provide: PlaybackPositionRuntimeBridgeService,
-                    useValue: {
-                        onPlaybackPositionUpdate: (
-                            callback: (data: PlaybackPositionData) => void
-                        ) => {
-                            positionUpdateCallback = callback;
-                            return () => {
-                                positionUpdateCallback = null;
-                            };
-                        },
-                    },
-                },
-                {
-                    provide: XTREAM_SERIES_RESUME_TARGET,
-                    useValue: seriesResumeTarget,
-                },
-                {
-                    provide: MatSnackBar,
-                    useValue: {
-                        open: jest.fn(),
-                    },
-                },
-                {
-                    provide: TranslateService,
-                    useValue: {
-                        instant: (key: string) => key,
-                        get: (key: string) => of(key),
-                        stream: (key: string) => of(key),
-                        onLangChange: EMPTY,
-                        onTranslationChange: EMPTY,
-                        onDefaultLangChange: EMPTY,
-                    },
-                },
-                {
-                    provide: Location,
-                    useValue: {
-                        back: jest.fn(),
-                    },
-                },
-            ],
-        })
-            .overrideComponent(SerialDetailsComponent, {
-                remove: {
-                    imports: [
-                        MatIcon,
-                        PortalInlinePlayerComponent,
-                        SeasonContainerComponent,
-                        TranslatePipe,
-                    ],
-                },
-                add: {
-                    imports: [
-                        StubMatIconComponent,
-                        StubPortalInlinePlayerComponent,
-                        StubSeasonContainerComponent,
-                        MockPipe(
-                            TranslatePipe,
-                            (value: string | null | undefined) => value ?? ''
-                        ),
-                    ],
-                },
-            })
-            .compileComponents();
+        resetSerialDetailsStubs(stubs);
+        await configureSerialDetailsTestBed(stubs);
 
         fixture = TestBed.createComponent(SerialDetailsComponent);
     });
@@ -779,6 +464,7 @@ describe('SerialDetailsComponent', () => {
     it('applies streamed playback-position updates for the selected series only', async () => {
         fixture.detectChanges();
         await fixture.whenStable();
+        const positionUpdateCallback = stubs.positionUpdates.callback;
         if (!positionUpdateCallback) {
             throw new Error('expected a playback-position subscription');
         }
@@ -936,238 +622,6 @@ describe('SerialDetailsComponent', () => {
         expect(savePlaybackPosition).not.toHaveBeenCalled();
     });
 
-    it('saves and clears positions for season-container toggle requests', async () => {
-        fixture.detectChanges();
-        await fixture.whenStable();
-
-        const playbackService = fixture.debugElement.injector.get(
-            SerialDetailsPlaybackService
-        );
-        await playbackService.handlePlaybackToggleRequested({
-            contentXtreamId: 1001,
-            nextPosition: {
-                playlistId: 'xtream-1',
-                contentXtreamId: 1001,
-                contentType: 'episode',
-                seriesXtreamId: 103,
-                seasonNumber: 1,
-                episodeNumber: 1,
-                positionSeconds: 950,
-                durationSeconds: 1000,
-            },
-        } as never);
-        expect(savePlaybackPosition).toHaveBeenCalledWith(
-            'xtream-1',
-            expect.objectContaining({ contentXtreamId: 1001 })
-        );
-
-        await playbackService.handlePlaybackToggleRequested({
-            contentXtreamId: 1001,
-            nextPosition: null,
-        } as never);
-        expect(clearPlaybackPosition).toHaveBeenCalledWith(
-            'xtream-1',
-            1001,
-            'episode'
-        );
-    });
-
-    it('marks a season watched through one batch save and updates rendered positions', async () => {
-        fixture.detectChanges();
-        await fixture.whenStable();
-
-        const playbackService = fixture.debugElement.injector.get(
-            SerialDetailsPlaybackService
-        );
-        const snackBar = TestBed.inject(MatSnackBar);
-        const seasonPosition = (
-            contentXtreamId: number,
-            episodeNumber: number
-        ) => ({
-            playlistId: 'xtream-1',
-            contentXtreamId,
-            contentType: 'episode' as const,
-            seriesXtreamId: 103,
-            seasonNumber: 1,
-            episodeNumber,
-            positionSeconds: 1200,
-            durationSeconds: 1200,
-        });
-
-        await playbackService.handleWatchToggleRequested(
-            {
-                seasonKey: '1',
-                markWatched: true,
-                requests: [
-                    {
-                        contentXtreamId: 1001,
-                        nextPosition: seasonPosition(1001, 1),
-                    },
-                    {
-                        contentXtreamId: 1002,
-                        nextPosition: seasonPosition(1002, 2),
-                    },
-                ],
-            } as never,
-            'season'
-        );
-
-        expect(savePlaybackPositionsBatch).toHaveBeenCalledTimes(1);
-        expect(savePlaybackPositionsBatch).toHaveBeenCalledWith('xtream-1', [
-            expect.objectContaining({ contentXtreamId: 1001 }),
-            expect.objectContaining({ contentXtreamId: 1002 }),
-        ]);
-        expect(savePlaybackPosition).not.toHaveBeenCalled();
-        expect(playbackService.episodePlaybackPositions().get(1001)).toEqual(
-            expect.objectContaining({ positionSeconds: 1200 })
-        );
-        expect(
-            playbackService.episodePlaybackPositions().get(1002)
-        ).toBeDefined();
-        expect(snackBar.open).toHaveBeenCalledWith(
-            'XTREAM.SEASON_MARKED_WATCHED',
-            undefined,
-            { duration: 5000 }
-        );
-        // The catalog badge source must follow the batch.
-        expect(loadAllPositions).toHaveBeenCalledWith('xtream-1');
-        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
-    });
-
-    it('unwatches a season through one batch clear', async () => {
-        fixture.detectChanges();
-        await fixture.whenStable();
-
-        const playbackService = fixture.debugElement.injector.get(
-            SerialDetailsPlaybackService
-        );
-        await playbackService.handleWatchToggleRequested(
-            {
-                seasonKey: '1',
-                markWatched: false,
-                requests: [
-                    { contentXtreamId: 1001, nextPosition: null },
-                    { contentXtreamId: 1002, nextPosition: null },
-                ],
-            } as never,
-            'season'
-        );
-
-        expect(clearPlaybackPositionsBatch).toHaveBeenCalledTimes(1);
-        expect(clearPlaybackPositionsBatch).toHaveBeenCalledWith('xtream-1', [
-            { contentXtreamId: 1001, contentType: 'episode' },
-            { contentXtreamId: 1002, contentType: 'episode' },
-        ]);
-        expect(clearPlaybackPosition).not.toHaveBeenCalled();
-        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
-            false
-        );
-    });
-
-    it('does not write a stale season batch into another playlist state', async () => {
-        fixture.detectChanges();
-        await fixture.whenStable();
-
-        let resolveBatch!: () => void;
-        savePlaybackPositionsBatch.mockImplementation(
-            () =>
-                new Promise<void>((resolve) => {
-                    resolveBatch = resolve;
-                })
-        );
-        const playbackService = fixture.debugElement.injector.get(
-            SerialDetailsPlaybackService
-        );
-        const pending = playbackService.handleWatchToggleRequested(
-            {
-                seasonKey: '1',
-                markWatched: true,
-                requests: [
-                    {
-                        contentXtreamId: 1001,
-                        nextPosition: {
-                            playlistId: 'xtream-1',
-                            contentXtreamId: 1001,
-                            contentType: 'episode',
-                            seriesXtreamId: 103,
-                            seasonNumber: 1,
-                            episodeNumber: 1,
-                            positionSeconds: 1200,
-                            durationSeconds: 1200,
-                        },
-                    },
-                ],
-            } as never,
-            'season'
-        );
-
-        // The user navigates to another playlist while the batch is pending.
-        const initialPlaylist = currentPlaylist();
-        currentPlaylist.set({ ...initialPlaylist, id: 'xtream-2' });
-        resolveBatch();
-        await pending;
-
-        expect(savePlaybackPositionsBatch).toHaveBeenCalledWith(
-            'xtream-1',
-            expect.anything()
-        );
-        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
-            false
-        );
-        expect(TestBed.inject(MatSnackBar).open).not.toHaveBeenCalled();
-        // The store now belongs to the other playlist — no stale refresh.
-        expect(loadAllPositions).not.toHaveBeenCalled();
-        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
-        currentPlaylist.set(initialPlaylist);
-    });
-
-    it('keeps rendered positions and reports the error when the season batch fails', async () => {
-        const consoleError = jest
-            .spyOn(console, 'error')
-            .mockImplementation(() => undefined);
-        savePlaybackPositionsBatch.mockRejectedValue(new Error('batch failed'));
-        fixture.detectChanges();
-        await fixture.whenStable();
-
-        const playbackService = fixture.debugElement.injector.get(
-            SerialDetailsPlaybackService
-        );
-        const snackBar = TestBed.inject(MatSnackBar);
-        await playbackService.handleWatchToggleRequested(
-            {
-                seasonKey: '1',
-                markWatched: true,
-                requests: [
-                    {
-                        contentXtreamId: 1001,
-                        nextPosition: {
-                            playlistId: 'xtream-1',
-                            contentXtreamId: 1001,
-                            contentType: 'episode',
-                            seriesXtreamId: 103,
-                            seasonNumber: 1,
-                            episodeNumber: 1,
-                            positionSeconds: 1200,
-                            durationSeconds: 1200,
-                        },
-                    },
-                ],
-            } as never,
-            'season'
-        );
-
-        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
-            false
-        );
-        expect(snackBar.open).toHaveBeenCalledWith(
-            'XTREAM.SEASON_WATCH_UPDATE_FAILED',
-            undefined,
-            { duration: 5000 }
-        );
-        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
-        consoleError.mockRestore();
-    });
-
     it('passes inline episode metadata and autoplays only inside the current season', async () => {
         isEmbeddedPlayer.mockReturnValue(true);
         fixture.detectChanges();
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
index 9c40d2b12..c29a4e087 100644
--- a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
@@ -6,13 +6,11 @@ import {
     inject,
     OnDestroy,
     signal,
-    untracked,
     ChangeDetectionStrategy,
     viewChild,
 } from '@angular/core';
-import { toSignal } from '@angular/core/rxjs-interop';
 import { MatSnackBar } from '@angular/material/snack-bar';
-import { ActivatedRoute, Router } from '@angular/router';
+import { ActivatedRoute } from '@angular/router';
 import { TranslatePipe, TranslateService } from '@ngx-translate/core';
 import {
     CastCrewRowComponent,
@@ -49,24 +47,15 @@ import {
     XtreamSerieEpisode,
     XtreamSerieInfo,
 } from '@iptvnator/shared/interfaces';
-import { buildSeasonDescriptions } from './season-descriptions.util';
-import { buildSeasonPosters } from './season-posters.util';
-import {
-    createDiscoverFacetNavigation,
-    isProviderOnlyDetailState,
-} from '@iptvnator/portal/shared/util';
-import {
-    CrossPortalSimilarItem,
-    CrossPortalSimilarService,
-    TmdbEnrichmentService,
-} from '@iptvnator/services';
+import { injectXtreamDetailNavigation } from '../xtream-detail-navigation';
 import {
     SerialDetailsPlaybackService,
     type XtreamSerieDetailsView,
 } from './serial-details-playback.service';
+import { SerialDetailsRouteService } from './serial-details-route.service';
 import { SerialDetailsSeasonWatchService } from './serial-details-season-watch.service';
+import { SerialDetailsSeasonsService } from './serial-details-seasons.service';
 import { SerialDetailsSimilarService } from './serial-details-similar.service';
-import { SimilarCatalogItem } from '../tmdb-similar.util';
 import { createSerialPlaybackSessionKey } from './serial-playback-session-key';
 import { SerialDetailsHeroPresenter } from './serial-details-hero.presenter';
 import { SerialDetailsMenuService } from './serial-details-menu.service';
@@ -90,7 +79,9 @@ import { SerialDetailsDownloadAdapterService } from './serial-details-download-a
     ],
     providers: [
         SerialDetailsPlaybackService,
+        SerialDetailsRouteService,
         SerialDetailsSeasonWatchService,
+        SerialDetailsSeasonsService,
         SerialDetailsSimilarService,
         SerialDetailsHeroPresenter,
         SerialDetailsMenuService,
@@ -118,8 +109,7 @@ import { SerialDetailsDownloadAdapterService } from './serial-details-download-a
 export class SerialDetailsComponent implements OnDestroy {
     private readonly location = inject(Location);
     private readonly route = inject(ActivatedRoute);
-    private readonly router = inject(Router);
-    private readonly crossPortalSimilar = inject(CrossPortalSimilarService);
+    private readonly navigation = injectXtreamDetailNavigation('tv');
 
     private readonly xtreamStore = inject(XtreamStore);
     private readonly playback = inject(SerialDetailsPlaybackService);
@@ -142,20 +132,9 @@ export class SerialDetailsComponent implements OnDestroy {
         SerialDetailsDownloadAdapterService
     );
     readonly episodeDownloadAdapter = this.downloadAdapter.adapter;
-    /** `playlistId:categoryId:serialId` of the last initialized view */
-    private readonly lastInitKey = signal<string | null>(null);
-
-    /**
-     * Reactive route params: the component is reused when navigating
-     * between two series details (e.g. via the Similar rail).
-     */
-    private readonly routeParams = toSignal(this.route.params, {
-        initialValue: this.route.snapshot.params,
-    });
-    readonly providerOnly = computed(() => {
-        this.routeParams();
-        return isProviderOnlyDetailState(window.history.state);
-    });
+    private readonly routeState = inject(SerialDetailsRouteService);
+    private readonly routeParams = this.routeState.params;
+    readonly providerOnly = this.routeState.providerOnly;
 
     // Episode playback state, re-exposed for the template.
     readonly inlinePlayback = this.playback.inlinePlayback;
@@ -182,27 +161,27 @@ export class SerialDetailsComponent implements OnDestroy {
         })
     );
 
-    /** Season currently selected in the season container. */
-    private readonly selectedSeasonKey = signal<string | null>(null);
-
-    /** Season descriptions (provider text, TMDB fallback, URL junk dropped). */
-    readonly seasonDescriptions = computed<Record<string, string>>(() =>
-        buildSeasonDescriptions(this.selectedItem())
-    );
-
-    /** Season posters (TMDB season poster first, provider season cover next). */
-    readonly seasonPosters = computed<Record<string, string>>(() =>
-        buildSeasonPosters(this.selectedItem())
-    );
-
     /** The "Similar" rail: catalog matches plus cross-portal matches */
     private readonly similar = inject(SerialDetailsSimilarService);
     readonly similarItems = this.similar.similarItems;
     readonly similarInPortals = this.similar.similarInPortals;
 
+    /**
+     * Season descriptions and posters, and the selected season's enrichment.
+     * Injected after the other services that register effects: its enrichment
+     * effect then runs after theirs and before the constructor's.
+     */
+    private readonly seasons = inject(SerialDetailsSeasonsService);
+    readonly seasonDescriptions = this.seasons.descriptions;
+    readonly seasonPosters = this.seasons.posters;
+
+    /** Clickable year/genre/country chips (Discover pages) */
+    readonly discover = this.navigation.discover;
+
     constructor() {
         this.playback.bind({ selectedItem: this.selectedItem });
         this.similar.bind({ selectedItem: this.selectedItem });
+        this.seasons.bind({ selectedItem: this.selectedItem });
         this.downloadAdapter.bind(this.selectedItem);
         this.heroPresenter.bind({
             selectedItem: this.selectedItem,
@@ -210,8 +189,9 @@ export class SerialDetailsComponent implements OnDestroy {
             yearLabel: (releaseDate) => this.discover.yearLabel(releaseDate),
             similarItems: this.similarItems,
             similarInPortals: this.similarInPortals,
-            openSimilar: (item) => this.openSimilar(item),
-            openSimilarInPortals: (item) => this.openSimilarInPortals(item),
+            openSimilar: (item) => this.navigation.openSimilar(item),
+            openSimilarInPortals: (item) =>
+                this.navigation.openSimilarInPortals(item),
         });
         this.menu.bind({
             selectedItem: this.selectedItem,
@@ -235,22 +215,6 @@ export class SerialDetailsComponent implements OnDestroy {
                 this.playback.playEpisode(episode, player),
         });
 
-        // TMDB season enrichment, keyed on (tmdb_id, selected season). With
-        // season tabs the first seasonSelected fires as soon as seasons load —
-        // usually BEFORE the async show-level TMDB match has written
-        // info.tmdb_id, and enrichSelectedSerialSeason no-ops without it. So
-        // the call must re-run when the match arrives, not only on selection.
-        // The store-side enrichment is idempotent per (serial, season).
-        effect(() => {
-            const tmdbId = this.selectedItem()?.info?.tmdb_id;
-            const seasonKey = this.selectedSeasonKey();
-            if (tmdbId && seasonKey) {
-                untracked(() =>
-                    this.xtreamStore.enrichSelectedSerialSeason(seasonKey)
-                );
-            }
-        });
-
         effect(() => {
             const item = this.xtreamStore.selectedItem() as unknown as
                 | (XtreamSerieDetails & {
@@ -274,22 +238,7 @@ export class SerialDetailsComponent implements OnDestroy {
 
         // Initializes on first render and RE-initializes when the route
         // params change while the component is reused (Similar rail).
-        effect(() => {
-            const playlistId = this.xtreamStore.currentPlaylist()?.id;
-            const { categoryId, serialId } = this.routeParams();
-            if (!playlistId || !serialId) {
-                return;
-            }
-
-            const initKey = `${playlistId}:${categoryId}:${serialId}`;
-            if (this.lastInitKey() === initKey) {
-                return;
-            }
-            this.lastInitKey.set(initKey);
-
-            this.playback.resetForNewSeries();
-            this.initializeSerialDetails(playlistId, categoryId, serialId);
-        });
+        effect(() => this.routeState.loadAddressedSeries());
 
         registerContentMetadataBackfill({
             store: this.xtreamStore,
@@ -306,10 +255,6 @@ export class SerialDetailsComponent implements OnDestroy {
         this.xtreamStore.setSelectedItem(null);
     }
 
-    openSimilarInPortals(item: CrossPortalSimilarItem): void {
-        void this.router.navigate(this.crossPortalSimilar.buildLink(item));
-    }
-
     /** Clears every saved episode position of the series. */
     resetProgress(): Promise<void> {
         const request =
@@ -319,41 +264,12 @@ export class SerialDetailsComponent implements OnDestroy {
             : Promise.resolve();
     }
 
-    openSimilar(item: SimilarCatalogItem): void {
-        void this.router.navigate(['../..', item.categoryId, item.id], {
-            relativeTo: this.route,
-        });
-    }
-
     openActor(member: TmdbEnrichedCastMember): void {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        if (!playlistId || !member.tmdbPersonId) {
-            return;
-        }
-        void this.router.navigate([
-            '/workspace/xtreams',
-            playlistId,
-            'actor',
-            member.tmdbPersonId,
-        ]);
+        this.navigation.openActor(member);
     }
 
-    /** Clickable year/genre/country chips (Discover pages) */
-    private readonly tmdbEnrichment = inject(TmdbEnrichmentService);
-
-    readonly discover = createDiscoverFacetNavigation(() => {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        // Discover reads its results from TMDB, so a chip must not offer a
-        // page that enrichment cannot fill
-        return playlistId && this.tmdbEnrichment.isEnabled()
-            ? { portal: 'xtream', mediaType: 'tv', playlistId }
-            : null;
-    });
-
     onSeasonSelected(seasonKey: string): void {
-        // The enrichment call itself runs from the constructor effect keyed
-        // on (tmdb_id, selectedSeasonKey) — see the race note there.
-        this.selectedSeasonKey.set(seasonKey);
+        this.seasons.select(seasonKey);
     }
 
     playEpisode(episode: XtreamSerieEpisode): void {
@@ -445,25 +361,4 @@ export class SerialDetailsComponent implements OnDestroy {
             }
         );
     }
-
-    private initializeSerialDetails(
-        playlistId: string,
-        categoryId: string | number,
-        serialId: string
-    ): void {
-        this.xtreamStore.fetchSerialDetailsWithMetadata({
-            serialId,
-            categoryId: Number(categoryId),
-        });
-        const serialXtreamId = Number(serialId);
-        this.xtreamStore.checkFavoriteStatus(
-            serialXtreamId,
-            playlistId,
-            'series'
-        );
-        void this.playback.loadSeriesPlaybackPositions(
-            playlistId,
-            serialXtreamId
-        );
-    }
 }
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.harness.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.harness.ts
new file mode 100644
index 000000000..5a57feb7f
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.harness.ts
@@ -0,0 +1,314 @@
+import { Location } from '@angular/common';
+import { signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { MatIcon } from '@angular/material/icon';
+import { MatSnackBar } from '@angular/material/snack-bar';
+import { ActivatedRoute } from '@angular/router';
+import { TranslatePipe, TranslateService } from '@ngx-translate/core';
+import { MockPipe } from 'ng-mocks';
+import {
+    PORTAL_EXTERNAL_PLAYBACK,
+    PORTAL_PLAYBACK_POSITIONS,
+    PORTAL_PLAYER,
+    SeriesResumeTarget,
+} from '@iptvnator/portal/shared/util';
+import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
+import {
+    DownloadsService,
+    PlaybackPositionRuntimeBridgeService,
+    SettingsStore,
+} from '@iptvnator/services';
+import {
+    PlaybackPositionData,
+    VideoPlayer,
+} from '@iptvnator/shared/interfaces';
+import { SeasonContainerComponent } from '@iptvnator/ui/components';
+import { PortalInlinePlayerComponent } from '@iptvnator/ui/playback';
+import { BehaviorSubject, EMPTY, of } from 'rxjs';
+import { SerialDetailsComponent } from './serial-details.component';
+import { XTREAM_SERIES_RESUME_TARGET } from './serial-details-resume-target.token';
+import {
+    StubMatIconComponent,
+    StubPortalInlinePlayerComponent,
+    StubSeasonContainerComponent,
+} from './serial-details.test-stubs';
+
+/**
+ * The TestBed every series-details component spec needs.
+ *
+ * The page pulls in the store, the playback ports, the position bridge,
+ * downloads, settings and the router, so standing it up costs ~200 lines.
+ * One harness keeps the specs split by concern from carrying a copy each.
+ */
+
+/** The series every spec starts from: two seasons, three episodes. */
+function createSeriesFixture(): unknown {
+    return {
+        series_id: 103,
+        info: {
+            name: 'Series One',
+            plot: 'Series plot',
+            cover: 'cover.jpg',
+            backdrop_path: [],
+            genre: 'Drama',
+            category_id: '3',
+            tmdb_id: 901,
+            tmdb_cast: [{ name: 'Sienna Wave', character: 'Mara' }],
+        },
+        episodes: {
+            '1': [
+                {
+                    id: '1001',
+                    episode_num: 1,
+                    title: 'Episode 1',
+                    season: 1,
+                },
+                {
+                    id: '1002',
+                    episode_num: 2,
+                    title: 'Episode 2',
+                    season: 1,
+                },
+            ],
+            '2': [
+                {
+                    id: '2001',
+                    episode_num: 1,
+                    title: 'Season 2 Episode 1',
+                    season: 2,
+                },
+            ],
+        },
+    };
+}
+
+const initialPlaylist = {
+    id: 'xtream-1',
+    serverUrl: 'http://xtream.example',
+    username: 'user',
+    password: 'pass',
+    userAgent: 'ProtectedProvider/2.0',
+    referrer: 'https://referrer.example/series',
+    origin: 'https://origin.example',
+};
+
+/** Every stub the harness installs, so specs can drive and assert on them. */
+export function createSerialDetailsStubs() {
+    return {
+        selectedItem: signal<unknown>(null),
+        selectedContentType: signal<'series'>('series'),
+        isFavorite: signal(false),
+        isLoadingDetails: signal(false),
+        detailsError: signal<string | null>(null),
+        currentPlaylist: signal(initialPlaylist),
+        fetchSerialDetailsWithMetadata: jest.fn(),
+        cancelDetailsRequest: jest.fn(),
+        checkFavoriteStatus: jest.fn(),
+        constructEpisodeStreamUrl: jest.fn(),
+        addRecentItem: jest.fn(),
+        openResolvedPlayback: jest.fn(),
+        openExternalPlayback: jest.fn(),
+        savePlaybackPosition: jest.fn(),
+        clearPlaybackPosition: jest.fn(),
+        savePlaybackPositionsBatch: jest.fn(),
+        clearPlaybackPositionsBatch: jest.fn(),
+        loadAllPositions: jest.fn(),
+        isEmbeddedPlayer: jest.fn(),
+        getSeriesPlaybackPositions: jest.fn().mockResolvedValue([]),
+        seriesResumeTarget: signal<SeriesResumeTarget | null>(null),
+        routeParams: new BehaviorSubject({
+            categoryId: '3',
+            serialId: '103',
+        }),
+        /** The page's subscription to streamed position updates, once made. */
+        positionUpdates: {
+            callback: null as ((data: PlaybackPositionData) => void) | null,
+        },
+    };
+}
+
+export type SerialDetailsStubs = ReturnType<typeof createSerialDetailsStubs>;
+
+/** Back to the state a fresh `beforeEach` expects. */
+export function resetSerialDetailsStubs(stubs: SerialDetailsStubs): void {
+    stubs.selectedItem.set(createSeriesFixture());
+    stubs.isFavorite.set(false);
+    stubs.isLoadingDetails.set(false);
+    stubs.detailsError.set(null);
+    stubs.currentPlaylist.set(initialPlaylist);
+    stubs.fetchSerialDetailsWithMetadata.mockClear();
+    stubs.cancelDetailsRequest.mockClear();
+    stubs.checkFavoriteStatus.mockClear();
+    stubs.constructEpisodeStreamUrl.mockReset();
+    stubs.constructEpisodeStreamUrl.mockImplementation(
+        (episode: { id: string | number }) =>
+            `http://xtream.example/series/${episode.id}.mp4`
+    );
+    stubs.addRecentItem.mockClear();
+    stubs.openResolvedPlayback.mockReset();
+    stubs.openResolvedPlayback.mockResolvedValue(undefined);
+    stubs.openExternalPlayback.mockReset();
+    stubs.openExternalPlayback.mockResolvedValue(undefined);
+    stubs.savePlaybackPosition.mockReset();
+    stubs.savePlaybackPosition.mockResolvedValue(undefined);
+    stubs.clearPlaybackPosition.mockReset();
+    stubs.clearPlaybackPosition.mockResolvedValue(undefined);
+    stubs.savePlaybackPositionsBatch.mockReset();
+    stubs.savePlaybackPositionsBatch.mockResolvedValue(undefined);
+    stubs.clearPlaybackPositionsBatch.mockReset();
+    stubs.clearPlaybackPositionsBatch.mockResolvedValue(undefined);
+    stubs.loadAllPositions.mockReset();
+    stubs.loadAllPositions.mockResolvedValue(undefined);
+    stubs.positionUpdates.callback = null;
+    stubs.isEmbeddedPlayer.mockReset();
+    stubs.isEmbeddedPlayer.mockReturnValue(false);
+    stubs.getSeriesPlaybackPositions.mockClear();
+    stubs.getSeriesPlaybackPositions.mockResolvedValue([]);
+    stubs.seriesResumeTarget.set(null);
+    stubs.routeParams.next({ categoryId: '3', serialId: '103' });
+}
+
+export async function configureSerialDetailsTestBed(
+    stubs: SerialDetailsStubs
+): Promise<void> {
+    await TestBed.configureTestingModule({
+        imports: [SerialDetailsComponent],
+        providers: [
+            {
+                provide: ActivatedRoute,
+                useValue: {
+                    params: stubs.routeParams,
+                    snapshot: {
+                        params: {
+                            categoryId: '3',
+                            serialId: '103',
+                        },
+                    },
+                },
+            },
+            {
+                provide: XtreamStore,
+                useValue: {
+                    selectedItem: stubs.selectedItem,
+                    selectedContentType: stubs.selectedContentType,
+                    isFavorite: stubs.isFavorite,
+                    isLoadingDetails: stubs.isLoadingDetails,
+                    detailsError: stubs.detailsError,
+                    currentPlaylist: stubs.currentPlaylist,
+                    fetchSerialDetailsWithMetadata:
+                        stubs.fetchSerialDetailsWithMetadata,
+                    cancelDetailsRequest: stubs.cancelDetailsRequest,
+                    checkFavoriteStatus: stubs.checkFavoriteStatus,
+                    setSelectedItem: jest.fn((value: unknown) =>
+                        stubs.selectedItem.set(value)
+                    ),
+                    toggleFavorite: jest.fn(),
+                    constructEpisodeStreamUrl: stubs.constructEpisodeStreamUrl,
+                    addRecentItem: stubs.addRecentItem,
+                    backfillContentMetadata: jest.fn(),
+                    loadAllPositions: stubs.loadAllPositions,
+                    recentItems: signal([]),
+                    serialCategories: signal([]),
+                    loadRecentItems: jest.fn(),
+                },
+            },
+            {
+                provide: SettingsStore,
+                useValue: { player: signal(VideoPlayer.Html5Player) },
+            },
+            {
+                provide: DownloadsService,
+                useValue: { isAvailable: signal(false) },
+            },
+            {
+                provide: PORTAL_EXTERNAL_PLAYBACK,
+                useValue: {
+                    activeSession: signal(null),
+                },
+            },
+            {
+                provide: PORTAL_PLAYBACK_POSITIONS,
+                useValue: {
+                    getSeriesPlaybackPositions:
+                        stubs.getSeriesPlaybackPositions,
+                    savePlaybackPosition: stubs.savePlaybackPosition,
+                    clearPlaybackPosition: stubs.clearPlaybackPosition,
+                    savePlaybackPositionsBatch:
+                        stubs.savePlaybackPositionsBatch,
+                    clearPlaybackPositionsBatch:
+                        stubs.clearPlaybackPositionsBatch,
+                },
+            },
+            {
+                provide: PORTAL_PLAYER,
+                useValue: {
+                    isEmbeddedPlayer: stubs.isEmbeddedPlayer,
+                    openResolvedPlayback: stubs.openResolvedPlayback,
+                    openExternalPlayback: stubs.openExternalPlayback,
+                },
+            },
+            {
+                provide: PlaybackPositionRuntimeBridgeService,
+                useValue: {
+                    onPlaybackPositionUpdate: (
+                        callback: (data: PlaybackPositionData) => void
+                    ) => {
+                        stubs.positionUpdates.callback = callback;
+                        return () => {
+                            stubs.positionUpdates.callback = null;
+                        };
+                    },
+                },
+            },
+            {
+                provide: XTREAM_SERIES_RESUME_TARGET,
+                useValue: stubs.seriesResumeTarget,
+            },
+            {
+                provide: MatSnackBar,
+                useValue: {
+                    open: jest.fn(),
+                },
+            },
+            {
+                provide: TranslateService,
+                useValue: {
+                    instant: (key: string) => key,
+                    get: (key: string) => of(key),
+                    stream: (key: string) => of(key),
+                    onLangChange: EMPTY,
+                    onTranslationChange: EMPTY,
+                    onDefaultLangChange: EMPTY,
+                },
+            },
+            {
+                provide: Location,
+                useValue: {
+                    back: jest.fn(),
+                },
+            },
+        ],
+    })
+        .overrideComponent(SerialDetailsComponent, {
+            remove: {
+                imports: [
+                    MatIcon,
+                    PortalInlinePlayerComponent,
+                    SeasonContainerComponent,
+                    TranslatePipe,
+                ],
+            },
+            add: {
+                imports: [
+                    StubMatIconComponent,
+                    StubPortalInlinePlayerComponent,
+                    StubSeasonContainerComponent,
+                    MockPipe(
+                        TranslatePipe,
+                        (value: string | null | undefined) => value ?? ''
+                    ),
+                ],
+            },
+        })
+        .compileComponents();
+}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.season-watch.spec.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.season-watch.spec.ts
new file mode 100644
index 000000000..a4e9252b2
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.season-watch.spec.ts
@@ -0,0 +1,267 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { MatSnackBar } from '@angular/material/snack-bar';
+import { SerialDetailsComponent } from './serial-details.component';
+import { SerialDetailsPlaybackService } from './serial-details-playback.service';
+import {
+    configureSerialDetailsTestBed,
+    createSerialDetailsStubs,
+    resetSerialDetailsStubs,
+} from './serial-details.harness';
+
+describe('SerialDetailsComponent watched toggles', () => {
+    let fixture: ComponentFixture<SerialDetailsComponent>;
+    const stubs = createSerialDetailsStubs();
+    const {
+        currentPlaylist,
+        savePlaybackPosition,
+        clearPlaybackPosition,
+        savePlaybackPositionsBatch,
+        clearPlaybackPositionsBatch,
+        loadAllPositions,
+    } = stubs;
+
+    beforeEach(async () => {
+        window.history.replaceState({}, '', window.location.href);
+        resetSerialDetailsStubs(stubs);
+        await configureSerialDetailsTestBed(stubs);
+
+        fixture = TestBed.createComponent(SerialDetailsComponent);
+    });
+
+    afterEach(() => {
+        window.history.replaceState({}, '', window.location.href);
+        fixture?.destroy();
+    });
+
+    it('saves and clears positions for season-container toggle requests', async () => {
+        fixture.detectChanges();
+        await fixture.whenStable();
+
+        const playbackService = fixture.debugElement.injector.get(
+            SerialDetailsPlaybackService
+        );
+        await playbackService.handlePlaybackToggleRequested({
+            contentXtreamId: 1001,
+            nextPosition: {
+                playlistId: 'xtream-1',
+                contentXtreamId: 1001,
+                contentType: 'episode',
+                seriesXtreamId: 103,
+                seasonNumber: 1,
+                episodeNumber: 1,
+                positionSeconds: 950,
+                durationSeconds: 1000,
+            },
+        } as never);
+        expect(savePlaybackPosition).toHaveBeenCalledWith(
+            'xtream-1',
+            expect.objectContaining({ contentXtreamId: 1001 })
+        );
+
+        await playbackService.handlePlaybackToggleRequested({
+            contentXtreamId: 1001,
+            nextPosition: null,
+        } as never);
+        expect(clearPlaybackPosition).toHaveBeenCalledWith(
+            'xtream-1',
+            1001,
+            'episode'
+        );
+    });
+
+    it('marks a season watched through one batch save and updates rendered positions', async () => {
+        fixture.detectChanges();
+        await fixture.whenStable();
+
+        const playbackService = fixture.debugElement.injector.get(
+            SerialDetailsPlaybackService
+        );
+        const snackBar = TestBed.inject(MatSnackBar);
+        const seasonPosition = (
+            contentXtreamId: number,
+            episodeNumber: number
+        ) => ({
+            playlistId: 'xtream-1',
+            contentXtreamId,
+            contentType: 'episode' as const,
+            seriesXtreamId: 103,
+            seasonNumber: 1,
+            episodeNumber,
+            positionSeconds: 1200,
+            durationSeconds: 1200,
+        });
+
+        await playbackService.handleWatchToggleRequested(
+            {
+                seasonKey: '1',
+                markWatched: true,
+                requests: [
+                    {
+                        contentXtreamId: 1001,
+                        nextPosition: seasonPosition(1001, 1),
+                    },
+                    {
+                        contentXtreamId: 1002,
+                        nextPosition: seasonPosition(1002, 2),
+                    },
+                ],
+            } as never,
+            'season'
+        );
+
+        expect(savePlaybackPositionsBatch).toHaveBeenCalledTimes(1);
+        expect(savePlaybackPositionsBatch).toHaveBeenCalledWith('xtream-1', [
+            expect.objectContaining({ contentXtreamId: 1001 }),
+            expect.objectContaining({ contentXtreamId: 1002 }),
+        ]);
+        expect(savePlaybackPosition).not.toHaveBeenCalled();
+        expect(playbackService.episodePlaybackPositions().get(1001)).toEqual(
+            expect.objectContaining({ positionSeconds: 1200 })
+        );
+        expect(
+            playbackService.episodePlaybackPositions().get(1002)
+        ).toBeDefined();
+        expect(snackBar.open).toHaveBeenCalledWith(
+            'XTREAM.SEASON_MARKED_WATCHED',
+            undefined,
+            { duration: 5000 }
+        );
+        // The catalog badge source must follow the batch.
+        expect(loadAllPositions).toHaveBeenCalledWith('xtream-1');
+        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
+    });
+
+    it('unwatches a season through one batch clear', async () => {
+        fixture.detectChanges();
+        await fixture.whenStable();
+
+        const playbackService = fixture.debugElement.injector.get(
+            SerialDetailsPlaybackService
+        );
+        await playbackService.handleWatchToggleRequested(
+            {
+                seasonKey: '1',
+                markWatched: false,
+                requests: [
+                    { contentXtreamId: 1001, nextPosition: null },
+                    { contentXtreamId: 1002, nextPosition: null },
+                ],
+            } as never,
+            'season'
+        );
+
+        expect(clearPlaybackPositionsBatch).toHaveBeenCalledTimes(1);
+        expect(clearPlaybackPositionsBatch).toHaveBeenCalledWith('xtream-1', [
+            { contentXtreamId: 1001, contentType: 'episode' },
+            { contentXtreamId: 1002, contentType: 'episode' },
+        ]);
+        expect(clearPlaybackPosition).not.toHaveBeenCalled();
+        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
+            false
+        );
+    });
+
+    it('does not write a stale season batch into another playlist state', async () => {
+        fixture.detectChanges();
+        await fixture.whenStable();
+
+        let resolveBatch!: () => void;
+        savePlaybackPositionsBatch.mockImplementation(
+            () =>
+                new Promise<void>((resolve) => {
+                    resolveBatch = resolve;
+                })
+        );
+        const playbackService = fixture.debugElement.injector.get(
+            SerialDetailsPlaybackService
+        );
+        const pending = playbackService.handleWatchToggleRequested(
+            {
+                seasonKey: '1',
+                markWatched: true,
+                requests: [
+                    {
+                        contentXtreamId: 1001,
+                        nextPosition: {
+                            playlistId: 'xtream-1',
+                            contentXtreamId: 1001,
+                            contentType: 'episode',
+                            seriesXtreamId: 103,
+                            seasonNumber: 1,
+                            episodeNumber: 1,
+                            positionSeconds: 1200,
+                            durationSeconds: 1200,
+                        },
+                    },
+                ],
+            } as never,
+            'season'
+        );
+
+        // The user navigates to another playlist while the batch is pending.
+        const initialPlaylist = currentPlaylist();
+        currentPlaylist.set({ ...initialPlaylist, id: 'xtream-2' });
+        resolveBatch();
+        await pending;
+
+        expect(savePlaybackPositionsBatch).toHaveBeenCalledWith(
+            'xtream-1',
+            expect.anything()
+        );
+        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
+            false
+        );
+        expect(TestBed.inject(MatSnackBar).open).not.toHaveBeenCalled();
+        // The store now belongs to the other playlist — no stale refresh.
+        expect(loadAllPositions).not.toHaveBeenCalled();
+        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
+        currentPlaylist.set(initialPlaylist);
+    });
+
+    it('keeps rendered positions and reports the error when the season batch fails', async () => {
+        const consoleError = jest
+            .spyOn(console, 'error')
+            .mockImplementation(() => undefined);
+        savePlaybackPositionsBatch.mockRejectedValue(new Error('batch failed'));
+        fixture.detectChanges();
+        await fixture.whenStable();
+
+        const playbackService = fixture.debugElement.injector.get(
+            SerialDetailsPlaybackService
+        );
+        const snackBar = TestBed.inject(MatSnackBar);
+        await playbackService.handleWatchToggleRequested(
+            {
+                seasonKey: '1',
+                markWatched: true,
+                requests: [
+                    {
+                        contentXtreamId: 1001,
+                        nextPosition: {
+                            playlistId: 'xtream-1',
+                            contentXtreamId: 1001,
+                            contentType: 'episode',
+                            seriesXtreamId: 103,
+                            seasonNumber: 1,
+                            episodeNumber: 1,
+                            positionSeconds: 1200,
+                            durationSeconds: 1200,
+                        },
+                    },
+                ],
+            } as never,
+            'season'
+        );
+
+        expect(playbackService.episodePlaybackPositions().has(1001)).toBe(
+            false
+        );
+        expect(snackBar.open).toHaveBeenCalledWith(
+            'XTREAM.SEASON_WATCH_UPDATE_FAILED',
+            undefined,
+            { duration: 5000 }
+        );
+        expect(playbackService.seasonWatchBatchRunning()).toBe(false);
+        consoleError.mockRestore();
+    });
+});
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.test-stubs.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.test-stubs.ts
new file mode 100644
index 000000000..a093e78f9
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.test-stubs.ts
@@ -0,0 +1,70 @@
+import {
+    ChangeDetectionStrategy,
+    Component,
+    input,
+    output,
+} from '@angular/core';
+import type { SeasonEpisodeDownloadAdapter } from '@iptvnator/portal/shared/data-access';
+
+/** Stand-ins for the heavy children of the series-details page in specs. */
+
+@Component({
+    selector: 'app-season-container',
+    standalone: true,
+    changeDetection: ChangeDetectionStrategy.Eager,
+    template: '<div data-testid="season-container"></div>',
+})
+export class StubSeasonContainerComponent {
+    readonly seasons = input<unknown>(null);
+    readonly seriesId = input<number | string | null>(null);
+    readonly playlistId = input('');
+    readonly seriesTitle = input<string | undefined>(undefined);
+    readonly playbackPositions = input<unknown>(null);
+    readonly downloadAdapter = input<SeasonEpisodeDownloadAdapter | null>(null);
+    readonly downloadsEnabled = input(true);
+    readonly openingEpisodeId = input<number | null>(null);
+    readonly activeEpisodeId = input<number | null>(null);
+    readonly playingEpisodeId = input<number | null>(null);
+    readonly seasonDescriptions = input<unknown>(null);
+    readonly seasonPosters = input<unknown>(null);
+    readonly seasonWatchBatchRunning = input(false);
+    readonly episodeClicked = output<unknown>();
+    readonly playbackToggleRequested = output<unknown>();
+    readonly seasonPlaybackToggleRequested = output<unknown>();
+}
+
+@Component({
+    selector: 'app-portal-inline-player',
+    standalone: true,
+    changeDetection: ChangeDetectionStrategy.Eager,
+    template: '',
+})
+export class StubPortalInlinePlayerComponent {
+    readonly playbackSessionKey = input.required<string>();
+    readonly playback = input<unknown>(null);
+    readonly episodeMetadata = input<unknown>(null);
+    readonly seriesTitle = input<string | null>(null);
+    readonly seriesNavigation = input<unknown>(null);
+    readonly upNextEpisodes = input<unknown>(null);
+    readonly seriesEpisodes = input<unknown>(null);
+    readonly seasonPosters = input<unknown>(null);
+    readonly episodePlaybackPositions = input<unknown>(null);
+    readonly seasonLoadStates = input<unknown>(null);
+    readonly timeUpdate = output<unknown>();
+    readonly closed = output<void>();
+    readonly streamUrlCopied = output<void>();
+    readonly externalFallbackRequested = output<unknown>();
+    readonly playbackEnded = output<void>();
+    readonly previousEpisodeRequested = output<void>();
+    readonly nextEpisodeRequested = output<void>();
+    readonly upNextEpisodeSelected = output<unknown>();
+    readonly episodePanelSeasonSelected = output<string>();
+}
+
+@Component({
+    selector: 'mat-icon',
+    standalone: true,
+    changeDetection: ChangeDetectionStrategy.Eager,
+    template: '<ng-content />',
+})
+export class StubMatIconComponent {}
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-episode-playback.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-episode-playback.ts
new file mode 100644
index 000000000..28766621f
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-episode-playback.ts
@@ -0,0 +1,58 @@
+import type {
+    PlayerContentInfo,
+    ResolvedPortalPlayback,
+    XtreamSerieEpisode,
+} from '@iptvnator/shared/interfaces';
+import {
+    resolveSeriesPlaybackEpisodeState,
+    type SeriesPlaybackEpisodeState,
+} from '@iptvnator/ui/playback';
+import type { XtreamSerieDetailsView } from './serial-details-playback.service';
+
+export interface SerialEpisodePlaybackRequest {
+    readonly playlistId: string;
+    readonly selectedItem: XtreamSerieDetailsView;
+    readonly episode: XtreamSerieEpisode;
+    readonly streamUrl: string;
+    /** The episode's saved offset, when it has one. */
+    readonly startTime: number | undefined;
+}
+
+export interface SerialEpisodePlayback {
+    readonly playback: ResolvedPortalPlayback;
+    readonly episodeState: SeriesPlaybackEpisodeState<XtreamSerieEpisode> | null;
+}
+
+/**
+ * The playback an episode of the series on screen resolves to, and its place
+ * among the series' episodes for the inline player's navigation.
+ */
+export function buildSerialEpisodePlayback(
+    request: SerialEpisodePlaybackRequest
+): SerialEpisodePlayback {
+    const { episode, selectedItem } = request;
+    const contentInfo: PlayerContentInfo = {
+        playlistId: request.playlistId,
+        contentXtreamId: Number(episode.id),
+        contentType: 'episode',
+        seriesXtreamId: Number(selectedItem.series_id),
+        seasonNumber: Number(episode.season),
+        episodeNumber: Number(episode.episode_num),
+    };
+
+    const playback: ResolvedPortalPlayback = {
+        streamUrl: request.streamUrl,
+        title: episode.title,
+        thumbnail: selectedItem.info.cover,
+        startTime: request.startTime,
+        contentInfo,
+    };
+
+    const episodeState = resolveSeriesPlaybackEpisodeState({
+        episodesBySeason: selectedItem.episodes,
+        currentEpisodeId: episode.id,
+        fallbackSeasonNumber: Number(episode.season),
+        fallbackEpisodeNumber: Number(episode.episode_num),
+    });
+    return { playback, episodeState };
+}
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-downloads.service.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-downloads.service.ts
index 653897d79..7535070e5 100644
--- a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-downloads.service.ts
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-downloads.service.ts
@@ -2,6 +2,7 @@ import { Injectable, Signal, computed, inject, signal } from '@angular/core';
 import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
 import { createMovieDownloadSnapshot } from '@iptvnator/portal/shared/util';
 import { DownloadsService } from '@iptvnator/services';
+import { DialogService } from '@iptvnator/ui/components';
 import { resolveXtreamVodPlaybackSource } from '@iptvnator/portal/xtream/data-access';
 import {
     getXtreamVodInfo,
@@ -54,6 +55,7 @@ export class VodDetailsDownloadsService {
     private readonly downloadsService = inject(DownloadsService);
     private readonly xtreamStore = inject(XtreamStore);
     private readonly translateService = inject(TranslateService);
+    private readonly dialogService = inject(DialogService);
 
     private routeContentId: Signal<number> = signal(NaN);
 
@@ -124,6 +126,20 @@ export class VodDetailsDownloadsService {
             : null;
     });
 
+    /** 2πr of the r=15.5 progress-ring circle in its 36×36 viewBox. */
+    readonly ringCircumference = 2 * Math.PI * 15.5;
+
+    /**
+     * Dash offset that leaves the arc at the real percent — or a fixed
+     * quarter arc when the total size is unknown and the ring spins instead.
+     */
+    readonly ringOffset = computed(() => {
+        const percent = this.downloadPercent();
+        return percent === null
+            ? this.ringCircumference * 0.75
+            : this.ringCircumference * (1 - percent / 100);
+    });
+
     /** Cancel whatever download is running or queued for this movie. */
     async cancelActive(): Promise<void> {
         const item = this.activeDownload();
@@ -132,6 +148,28 @@ export class VodDetailsDownloadsService {
         }
     }
 
+    /**
+     * A running download is destroyed by one click, so the icon button asks
+     * first — there is no label left to warn what the click does.
+     */
+    promptCancel(): void {
+        this.dialogService.openConfirmDialog({
+            title: this.translateService.instant(
+                'DOWNLOADS.CANCEL_CONFIRM_TITLE'
+            ),
+            message: this.translateService.instant(
+                'DOWNLOADS.CANCEL_CONFIRM_MESSAGE'
+            ),
+            confirmLabel: this.translateService.instant(
+                'DOWNLOADS.CANCEL_CONFIRM_TITLE'
+            ),
+            // "Cancel" next to "Cancel download" would read as the same action.
+            cancelLabel: this.translateService.instant('CLOSE'),
+            tone: 'destructive',
+            onConfirm: () => void this.cancelActive(),
+        });
+    }
+
     /** Open the finished file's location in the system file manager. */
     async revealDownloaded(): Promise<void> {
         const playlistId = this.xtreamStore.currentPlaylist()?.id;
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-external-launch.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-external-launch.ts
index 7575eee04..233353a99 100644
--- a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-external-launch.ts
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-external-launch.ts
@@ -1,4 +1,9 @@
-import type { ExternalPlayerSession } from '@iptvnator/shared/interfaces';
+import { signal } from '@angular/core';
+import type {
+    ExternalPlayerSession,
+    ResolvedPortalPlayback,
+} from '@iptvnator/shared/interfaces';
+import type { ExternalLaunchOwner } from './vod-details-external-launch-owner';
 
 interface OwnedExternalLaunchOptions {
     launch: Promise<ExternalPlayerSession | void>;
@@ -63,3 +68,44 @@ function isClosableExternalLaunch(
             (session.status === 'error' && session.canClose))
     );
 }
+
+/**
+ * The MPV/VLC launch a VOD page made last and the one it still waits on.
+ *
+ * What was launched is remembered independently of the controller's active
+ * source, so a refresh or an overlapping handoff cannot make the exact
+ * process this page launched look foreign before its teardown has been
+ * confirmed. Its route owner prevents a reused component from attributing
+ * that process to a different movie.
+ */
+export class VodExternalLaunchClaim {
+    private launchedGeneration = 0;
+    /** Start generation of the launch still awaiting its player, if any. */
+    readonly pendingGeneration = signal<number | null>(null);
+
+    constructor(private readonly owner: ExternalLaunchOwner) {}
+
+    claim(playback: ResolvedPortalPlayback, generation: number): void {
+        this.owner.set(playback.contentInfo);
+        this.launchedGeneration = generation;
+        this.pendingGeneration.set(generation);
+    }
+
+    /** An inline start took over: nothing external is owned or awaited. */
+    release(): void {
+        this.owner.clear();
+        this.pendingGeneration.set(null);
+    }
+
+    clearOwnership(generation: number): void {
+        if (this.launchedGeneration === generation) {
+            this.owner.clear();
+        }
+    }
+
+    clearPending(generation: number): void {
+        if (this.pendingGeneration() === generation) {
+            this.pendingGeneration.set(null);
+        }
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-hero.presenter.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-hero.presenter.ts
index 5093b4cdb..6ef9f4c61 100644
--- a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-hero.presenter.ts
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-hero.presenter.ts
@@ -10,17 +10,20 @@ import {
     type RemainingTimeLabel,
 } from '@iptvnator/portal/shared/util';
 import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
-import type {
-    PlaybackPositionData,
-    TmdbCountryFacet,
-    TmdbEnrichedCastMember,
-    TmdbGenreFacet,
-    XtreamVodInfo,
+import {
+    youtubeEmbedUrl,
+    type PlaybackPositionData,
+    type TmdbCountryFacet,
+    type TmdbEnrichedCastMember,
+    type TmdbGenreFacet,
+    type XtreamVodInfo,
 } from '@iptvnator/shared/interfaces';
+import { SettingsStore } from '@iptvnator/services';
 import type { CrossPortalSimilarItem } from '@iptvnator/services';
 import {
     castMembersFromNames,
     splitPeopleNames,
+    TrailerDialogService,
     type DetailActionButtonState,
     type SimilarRailItem,
 } from '@iptvnator/ui/components';
@@ -54,17 +57,21 @@ interface VodDetailsHeroBindings {
     readonly formatPosition: () => string;
     readonly similarItems: Signal<readonly SimilarCatalogItem[]>;
     readonly similarInPortals: Signal<readonly CrossPortalSimilarItem[]>;
+    readonly openSimilar: (item: SimilarCatalogItem) => void;
+    readonly openSimilarInPortals: (item: CrossPortalSimilarItem) => void;
 }
 
 /**
  * Presentation of the Xtream movie hero: the kind label, the chips, the
- * primary button's two lines, the resume bar, the credits and the Similar
- * rail, all derived from the route's selected movie.
+ * primary button's two lines, the resume bar, the credits, the trailer and
+ * the Similar rail, all derived from the route's selected movie.
  */
 @Injectable()
 export class VodDetailsHeroPresenter {
     private readonly translate = inject(TranslateService);
     private readonly xtreamStore = inject(XtreamStore);
+    private readonly settingsStore = inject(SettingsStore);
+    private readonly trailerDialog = inject(TrailerDialogService);
     private readonly bindings = signal<VodDetailsHeroBindings | null>(null);
 
     bind(bindings: VodDetailsHeroBindings): void {
@@ -208,6 +215,45 @@ export class VodDetailsHeroPresenter {
         return [...local, ...crossPortal];
     });
 
+    readonly trailerEmbedUrl = computed(() =>
+        youtubeEmbedUrl(this.info()?.youtube_trailer)
+    );
+    /** Settings → Playback → Play trailers in details background. */
+    readonly trailerBackdropUrl = computed(() =>
+        this.settingsStore.detailTrailerBackdrop?.() === true
+            ? this.trailerEmbedUrl()
+            : null
+    );
+
+    openTrailer(): void {
+        const embedUrl = this.trailerEmbedUrl();
+        const title = this.info()?.name;
+        if (embedUrl) {
+            this.trailerDialog.open({ embedUrl, title: title ?? '' });
+        }
+    }
+
+    openSimilarRailItem(item: SimilarRailItem): void {
+        const bindings = this.bindings();
+        const local = bindings
+            ?.similarItems()
+            .find((candidate) => `c${candidate.id}` === item.key);
+        if (local) {
+            bindings?.openSimilar(local);
+            return;
+        }
+        const crossPortal = bindings
+            ?.similarInPortals()
+            .find(
+                (candidate) =>
+                    `x${candidate.match.playlistId}-${candidate.match.xtreamId}` ===
+                    item.key
+            );
+        if (crossPortal) {
+            bindings?.openSimilarInPortals(crossPortal);
+        }
+    }
+
     private label(label: RemainingTimeLabel | null): string | null {
         return label ? this.translate.instant(label.key, label.params) : null;
     }
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-playback.service.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-playback.service.ts
index b43a64d66..8984fe555 100644
--- a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-playback.service.ts
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-playback.service.ts
@@ -32,7 +32,6 @@ import {
 import type { PlaybackFallbackRequest } from '@iptvnator/ui/playback';
 import {
     closeRunningExternalSession,
-    ownsContent,
     runningExternalSession,
 } from './vod-details-external-session';
 import {
@@ -40,13 +39,16 @@ import {
     startRouteOwnedPlayback,
 } from './vod-details-external-launch-owner';
 import { injectXtreamRecentHistory } from '../xtream-recent-history';
-import { settleOwnedExternalLaunch } from './vod-details-external-launch';
+import {
+    settleOwnedExternalLaunch,
+    VodExternalLaunchClaim,
+} from './vod-details-external-launch';
 import { resolveXtreamVodPlaybackPresentation } from './vod-details-playback-presentation';
+import { VodDetailsPositionState } from './vod-details-position-state';
 import {
     hasVodResetTarget,
     type VodResetTarget,
 } from './vod-details-reset-target';
-import { isResumablePosition } from './vod-primary-action-position';
 
 export interface VodDetailsPlaybackBindings {
     /** Current vod id resolved from the route */
@@ -83,8 +85,6 @@ export class VodDetailsPlaybackService {
         PlaybackPositionRuntimeBridgeService
     );
     private readonly logger = createLogger('VodDetailsPlayback');
-    private positionLoadGeneration = 0;
-    private destroyed = false;
 
     /** Signals bound from the host component via `bind()` */
     private readonly bindings = signal<VodDetailsPlaybackBindings | null>(null);
@@ -92,27 +92,23 @@ export class VodDetailsPlaybackService {
         () => this.xtreamStore.currentPlaylist()?.id,
         () => this.bindings()?.vodId()
     );
+    /** What this page launched externally, see {@link VodExternalLaunchClaim}. */
+    private readonly externalLaunch = new VodExternalLaunchClaim(
+        this.externalLaunchOwner
+    );
+
+    /** Stored positions of the page, see {@link VodDetailsPositionState}. */
+    private readonly positions = new VodDetailsPositionState({
+        playlistId: () => this.xtreamStore.currentPlaylist()?.id,
+        contentId: () => this.bindings()?.vodId(),
+        alternative: () => this.bindings()?.activeSource?.() ?? null,
+    });
 
     readonly inlinePlayback = signal<ResolvedPortalPlayback | null>(null);
-    /**
-     * The LAST position seen, whichever copy produced it.
-     *
-     * Multi-source can put playback on a copy in another playlist, and this
-     * follows it — the progress bar and the switch feed both want the stream
-     * on screen, not the one the route happens to address.
-     */
-    readonly vodPlaybackPosition = signal<PlaybackPositionData | null>(null);
-
-    /**
-     * The ROUTE copy's own row.
-     *
-     * Everything that acts on the route's stream — Resume, its label, its
-     * timecode — has to read this instead. Positions are keyed by (playlist,
-     * stream), so once an alternative has played, `vodPlaybackPosition` names
-     * a different film's row entirely and resuming from it would jump the
-     * route copy to a timecode nobody reached in it.
-     */
-    readonly routePlaybackPosition = signal<PlaybackPositionData | null>(null);
+    /** The LAST position seen, whichever copy produced it. */
+    readonly vodPlaybackPosition = this.positions.last;
+    /** The ROUTE copy's own row: what Resume, its label and its timecode read. */
+    readonly routePlaybackPosition = this.positions.route;
 
     private readonly externalButton = createExternalPlaybackButtonState({
         session: this.externalPlayback.activeSession,
@@ -131,59 +127,27 @@ export class VodDetailsPlaybackService {
     readonly externalPrimaryIcon = this.externalButton.primaryIcon;
     readonly isExternalLaunchPending = computed(
         () =>
-            this.externalLaunchGeneration() !== null ||
+            this.externalLaunch.pendingGeneration() !== null ||
             this.externalButton.isLaunchPending()
     );
     readonly isExternalStopAction = this.externalButton.isStopAction;
     readonly externalPrimaryButtonState = this.externalButton.buttonState;
-    /** Mirrors an incoming position into the route's row when it owns it. */
-    private trackPosition(position: PlaybackPositionData | null): void {
-        this.vodPlaybackPosition.set(position);
-        if (this.isRouteContent(position)) {
-            this.routePlaybackPosition.set(position);
-        }
-    }
-
-    private isRouteContent(position: PlaybackPositionData | null): boolean {
-        return (
-            !!position &&
-            position.playlistId === this.xtreamStore.currentPlaylist()?.id &&
-            position.contentXtreamId === this.bindings()?.vodId()
-        );
-    }
 
     /** Whether the ROUTE copy has somewhere to resume from. */
-    readonly hasPlaybackPosition = computed(() =>
-        isResumablePosition(this.routePlaybackPosition())
-    );
+    readonly hasPlaybackPosition = this.positions.hasResumable;
 
     constructor() {
         const unsubscribePositionUpdates =
             this.playbackPositionBridge.onPlaybackPositionUpdate(
-                (data: PlaybackPositionData) => {
-                    // An external player on an ALTERNATIVE reports under
-                    // that playlist's ids; dropping those rewinds a switch.
-                    if (this.ownsContent(data)) {
-                        this.trackPosition(data);
-                    }
-                }
+                (data: PlaybackPositionData) => this.positions.trackOwned(data)
             ) ?? null;
 
         inject(DestroyRef).onDestroy(() => {
-            this.destroyed = true;
-            this.positionLoadGeneration++;
+            this.positions.destroy();
             unsubscribePositionUpdates?.();
         });
     }
 
-    private ownsContent(info: Parameters<typeof ownsContent>[0]): boolean {
-        return ownsContent(info, {
-            routePlaylistId: this.xtreamStore.currentPlaylist()?.id,
-            routeContentId: this.bindings()?.vodId(),
-            alternative: this.bindings()?.activeSource?.() ?? null,
-        });
-    }
-
     /** Wires the host component's context signals. Call once at construction. */
     bind(bindings: VodDetailsPlaybackBindings): void {
         this.bindings.set(bindings);
@@ -285,7 +249,7 @@ export class VodDetailsPlaybackService {
                 playlistId,
                 position
             ),
-        onSaved: (position) => this.trackPosition(position),
+        onSaved: (position) => this.positions.track(position),
     });
 
     /**
@@ -318,7 +282,7 @@ export class VodDetailsPlaybackService {
         const routeIdentity = this.externalLaunchOwner.captureRoute();
         this.bindings()?.supersedePendingSwitch();
         const generation = ++this.startGeneration;
-        this.claimExternalLaunch(playback, generation);
+        this.externalLaunch.claim(playback, generation);
         const launch = this.portalPlayer.openExternalPlayback(playback, player);
         void this.settleExternalLaunch(
             generation,
@@ -334,32 +298,16 @@ export class VodDetailsPlaybackService {
      * answer that read started from.
      */
     discardPendingPositionLoads(): void {
-        this.positionLoadGeneration++;
+        this.positions.discardPendingLoads();
     }
 
     /** The route copy's row is in hand; fails closed while a read is in flight. */
-    readonly positionLoaded = signal(false);
+    readonly positionLoaded = this.positions.loaded;
 
-    async loadPosition(playlistId: string, vodId: number): Promise<void> {
-        const generation = ++this.positionLoadGeneration;
-        this.positionLoaded.set(false);
-        const position = await this.playbackPositions.getPlaybackPosition(
-            playlistId,
-            vodId,
-            'vod'
+    loadPosition(playlistId: string, vodId: number): Promise<void> {
+        return this.positions.load(playlistId, vodId, () =>
+            this.playbackPositions.getPlaybackPosition(playlistId, vodId, 'vod')
         );
-        if (
-            this.destroyed ||
-            generation !== this.positionLoadGeneration ||
-            this.xtreamStore.currentPlaylist()?.id !== playlistId ||
-            this.bindings()?.vodId() !== vodId
-        ) {
-            return;
-        }
-
-        this.vodPlaybackPosition.set(position);
-        this.routePlaybackPosition.set(position);
-        this.positionLoaded.set(true);
     }
 
     /**
@@ -374,18 +322,6 @@ export class VodDetailsPlaybackService {
     /** Bumped by every start; only the newest may launch after its close. */
     private startGeneration = 0;
 
-    /**
-     * What we last launched externally, remembered independently of the
-     * controller's active source.
-     *
-     * Kept independently of the controller so a refresh or an overlapping
-     * handoff cannot make the exact process this page launched look foreign
-     * before its teardown has been confirmed. Its route owner prevents a
-     * reused component from attributing that process to a different movie.
-     */
-    private launchedExternallyGeneration = 0;
-    private readonly externalLaunchGeneration = signal<number | null>(null);
-
     /**
      * Starts still between the click and `inlinePlayback` / the external
      * launch (closing the previous player is a round-trip). The watched
@@ -421,7 +357,10 @@ export class VodDetailsPlaybackService {
         isCurrent: () => boolean = () => true,
         player?: ExternalPlayerName
     ): Promise<boolean> {
-        if (this.externalLaunchGeneration() !== null || this.resetPending()) {
+        if (
+            this.externalLaunch.pendingGeneration() !== null ||
+            this.resetPending()
+        ) {
             return false;
         }
         const runningSession = runningExternalSession(
@@ -497,28 +436,18 @@ export class VodDetailsPlaybackService {
         this.positionWriter.reset();
         if (!player && this.portalPlayer.isEmbeddedPlayer()) {
             this.inlinePlayback.set(playback);
-            this.externalLaunchOwner.clear();
-            this.externalLaunchGeneration.set(null);
+            this.externalLaunch.release();
             return true;
         }
 
         this.closeInlinePlayer();
-        this.claimExternalLaunch(playback, generation);
+        this.externalLaunch.claim(playback, generation);
         const launch = player
             ? this.portalPlayer.openExternalPlayback(playback, player)
             : this.portalPlayer.openResolvedPlayback(playback, true);
         return await this.settleExternalLaunch(generation, isCurrent, launch);
     }
 
-    private claimExternalLaunch(
-        playback: ResolvedPortalPlayback,
-        generation: number
-    ): void {
-        this.externalLaunchOwner.set(playback.contentInfo);
-        this.launchedExternallyGeneration = generation;
-        this.externalLaunchGeneration.set(generation);
-    }
-
     private async settleExternalLaunch(
         generation: number,
         isCurrent: () => boolean,
@@ -535,20 +464,9 @@ export class VodDetailsPlaybackService {
                 ),
             reportLaunchFailure: (error) =>
                 this.bindings()?.reportExternalLaunchFailure?.(error),
-            clearPending: () => this.clearExternalLaunchPending(generation),
-            clearOwnership: () => this.clearExternalLaunchOwnership(generation),
+            clearPending: () => this.externalLaunch.clearPending(generation),
+            clearOwnership: () =>
+                this.externalLaunch.clearOwnership(generation),
         });
     }
-
-    private clearExternalLaunchOwnership(generation: number): void {
-        if (this.launchedExternallyGeneration === generation) {
-            this.externalLaunchOwner.clear();
-        }
-    }
-
-    private clearExternalLaunchPending(generation: number): void {
-        if (this.externalLaunchGeneration() === generation) {
-            this.externalLaunchGeneration.set(null);
-        }
-    }
 }
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-position-state.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-position-state.ts
new file mode 100644
index 000000000..24571b753
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-position-state.ts
@@ -0,0 +1,121 @@
+import { computed, signal } from '@angular/core';
+import type {
+    PlaybackPositionData,
+    PlayerContentInfo,
+} from '@iptvnator/shared/interfaces';
+import { ownsContent } from './vod-details-external-session';
+import { isResumablePosition } from './vod-primary-action-position';
+
+/** The copies the page's position state belongs to. */
+export interface VodDetailsPositionRoute {
+    readonly playlistId: () => string | undefined;
+    readonly contentId: () => number | undefined;
+    /** The alternative currently in use, if it is not the route's own. */
+    readonly alternative: () => PlayerContentInfo | null;
+}
+
+/**
+ * Stored playback positions of the VOD details page: the last one seen, the
+ * route copy's own row, and the guarded read that fills both.
+ */
+export class VodDetailsPositionState {
+    private loadGeneration = 0;
+    private destroyed = false;
+
+    /**
+     * The LAST position seen, whichever copy produced it.
+     *
+     * Multi-source can put playback on a copy in another playlist, and this
+     * follows it — the progress bar and the switch feed both want the stream
+     * on screen, not the one the route happens to address.
+     */
+    readonly last = signal<PlaybackPositionData | null>(null);
+
+    /**
+     * The ROUTE copy's own row.
+     *
+     * Everything that acts on the route's stream — Resume, its label, its
+     * timecode — has to read this instead. Positions are keyed by (playlist,
+     * stream), so once an alternative has played, `last` names a different
+     * film's row entirely and resuming from it would jump the route copy to
+     * a timecode nobody reached in it.
+     */
+    readonly route = signal<PlaybackPositionData | null>(null);
+
+    /** Whether the ROUTE copy has somewhere to resume from. */
+    readonly hasResumable = computed(() => isResumablePosition(this.route()));
+
+    /** The route copy's row is in hand; fails closed while a read is in flight. */
+    readonly loaded = signal(false);
+
+    constructor(private readonly routeCopy: VodDetailsPositionRoute) {}
+
+    /** Mirrors an incoming position into the route's row when it owns it. */
+    track(position: PlaybackPositionData | null): void {
+        this.last.set(position);
+        if (this.isRouteContent(position)) {
+            this.route.set(position);
+        }
+    }
+
+    /**
+     * Takes a streamed position when the page owns its content. An external
+     * player on an ALTERNATIVE reports under that playlist's ids; dropping
+     * those rewinds a switch.
+     */
+    trackOwned(position: PlaybackPositionData): void {
+        const owned = {
+            routePlaylistId: this.routeCopy.playlistId(),
+            routeContentId: this.routeCopy.contentId(),
+            alternative: this.routeCopy.alternative(),
+        };
+        if (ownsContent(position, owned)) {
+            this.track(position);
+        }
+    }
+
+    /**
+     * Retires every stored-position read still in flight. A row written
+     * since (the manual watched toggle) must not be overwritten by the older
+     * answer that read started from.
+     */
+    discardPendingLoads(): void {
+        this.loadGeneration++;
+    }
+
+    /** The page is gone: no read still in flight may land. */
+    destroy(): void {
+        this.destroyed = true;
+        this.loadGeneration++;
+    }
+
+    async load(
+        playlistId: string,
+        vodId: number,
+        read: () => Promise<PlaybackPositionData | null>
+    ): Promise<void> {
+        const generation = ++this.loadGeneration;
+        this.loaded.set(false);
+        const position = await read();
+        if (
+            this.destroyed ||
+            generation !== this.loadGeneration ||
+            this.routeCopy.playlistId() !== playlistId ||
+            this.routeCopy.contentId() !== vodId
+        ) {
+            return;
+        }
+
+        this.last.set(position);
+        this.route.set(position);
+        this.loaded.set(true);
+    }
+
+    private isRouteContent(position: PlaybackPositionData | null): boolean {
+        return (
+            !!position &&
+            position.playlistId === this.routeCopy.playlistId() &&
+            position.contentXtreamId === this.routeCopy.contentId()
+        );
+    }
+}
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-route.component.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-route.component.ts
index ffa450009..68b956e63 100644
--- a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-route.component.ts
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-route.component.ts
@@ -8,13 +8,10 @@ import {
     effect,
     inject,
     signal,
-    untracked,
 } from '@angular/core';
-import { toSignal } from '@angular/core/rxjs-interop';
 import { MatIcon } from '@angular/material/icon';
 import { MatSnackBar } from '@angular/material/snack-bar';
-import { MatTooltip } from '@angular/material/tooltip';
-import { ActivatedRoute, Router } from '@angular/router';
+import { ActivatedRoute } from '@angular/router';
 import { TranslateModule, TranslateService } from '@ngx-translate/core';
 import {
     CastCrewRowComponent,
@@ -24,90 +21,40 @@ import {
     DetailIconButtonComponent,
     DetailMetaTemplateDirective,
     DetailTagsTemplateDirective,
-    DialogService,
     MetaChipComponent,
     PortalDetailShellComponent,
     SimilarRailComponent,
     type SimilarRailItem,
-    TrailerDialogService,
     ViewInPortalActionComponent,
     VodMoreMenuComponent,
+    scrollToCastCrewRow,
 } from '@iptvnator/ui/components';
-import {
-    createDiscoverFacetNavigation,
-    createLogger,
-    isProviderOnlyDetailState,
-} from '@iptvnator/portal/shared/util';
+import { createLogger } from '@iptvnator/portal/shared/util';
 import {
     registerContentMetadataBackfill,
-    resolveXtreamVodPlaybackSource,
     XtreamStore,
 } from '@iptvnator/portal/xtream/data-access';
 import {
     type PlaybackFallbackRequest,
     PortalInlinePlayerComponent,
 } from '@iptvnator/ui/playback';
+import { DownloadsService, SettingsStore } from '@iptvnator/services';
 import {
-    CrossPortalSimilarItem,
-    CrossPortalSimilarService,
-    DownloadsService,
-    SettingsStore,
-    TmdbEnrichmentService,
-} from '@iptvnator/services';
-import {
-    getXtreamVodInfo,
-    normalizeTitleKeys,
-    playlistDisplayLabel,
-    reportsPlaybackFailures,
     TmdbEnrichedCastMember,
-    XtreamCategory,
     XtreamVodDetails,
     XtreamVodInfo,
-    XtreamVodStream,
-    youtubeEmbedUrl,
     type ExternalPlayerName,
-    type PlaybackPositionData,
-    type VodSourceCandidate,
-    type VodSourceDescriptor,
 } from '@iptvnator/shared/interfaces';
-import {
-    SimilarCatalogItem,
-    matchRecommendationsToCatalog,
-} from '../tmdb-similar.util';
-import {
-    buildXtreamVodFallbackViewModel,
-    hasUsableXtreamVodMetadata,
-} from './vod-details-fallback.util';
+import { injectXtreamDetailNavigation } from '../xtream-detail-navigation';
 import { VodDetailsPlaybackService } from './vod-details-playback.service';
 import { VodDetailsMultiSourceUiService } from './vod-details-multi-source-ui.service';
 import { VodDetailsDownloadsService } from './vod-details-downloads.service';
 import { VodDetailsWatchedService } from './vod-details-watched.service';
 import { VodDetailsHeroPresenter } from './vod-details-hero.presenter';
 import { VodDetailsMenuService } from './vod-details-menu.service';
+import { VodDetailsSelectionService } from './vod-details-selection.service';
 import { VodDetailsSimilarService } from './vod-details-similar.service';
 import { VodMultiSourceHostService } from './vod-multi-source-host.service';
-import { resolveVodMultiSourceMovie } from './vod-multi-source-identity';
-import { createPlaybackSessionKey } from '@iptvnator/playback/util';
-
-type XtreamVodIdentityItem = XtreamVodDetails & {
-    readonly id?: number | string;
-    readonly stream_id?: number | string;
-    readonly xtream_id?: number | string;
-};
-
-function resolveVodIdentity(item: XtreamVodDetails): number | null {
-    const candidate = item as XtreamVodIdentityItem;
-    const value =
-        item.movie_data?.stream_id ??
-        candidate.xtream_id ??
-        candidate.stream_id ??
-        candidate.id;
-    const id = typeof value === 'string' ? Number(value) : value;
-
-    return typeof id === 'number' && Number.isSafeInteger(id) && id > 0
-        ? id
-        : null;
-}
 
 @Component({
     templateUrl: './vod-details-route.component.html',
@@ -117,6 +64,7 @@ function resolveVodIdentity(item: XtreamVodDetails): number | null {
     ],
     changeDetection: ChangeDetectionStrategy.OnPush,
     providers: [
+        VodDetailsSelectionService,
         VodDetailsPlaybackService,
         VodMultiSourceHostService,
         VodDetailsMultiSourceUiService,
@@ -131,7 +79,6 @@ function resolveVodIdentity(item: XtreamVodDetails): number | null {
         DetailMetaTemplateDirective,
         DetailTagsTemplateDirective,
         MatIcon,
-        MatTooltip,
         NgTemplateOutlet,
         PortalDetailShellComponent,
         ViewInPortalActionComponent,
@@ -151,11 +98,9 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
     private readonly location = inject(Location);
     private readonly settingsStore = inject(SettingsStore);
     private readonly route = inject(ActivatedRoute);
-    private readonly router = inject(Router);
-    private readonly crossPortalSimilar = inject(CrossPortalSimilarService);
+    private readonly navigation = injectXtreamDetailNavigation('movie');
     private readonly xtreamStore = inject(XtreamStore);
     private readonly downloadsService = inject(DownloadsService);
-    private readonly dialogService = inject(DialogService);
     private readonly snackBar = inject(MatSnackBar);
     private readonly translateService = inject(TranslateService);
     private readonly playback = inject(VodDetailsPlaybackService);
@@ -167,7 +112,8 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
     private readonly watched = inject(VodDetailsWatchedService);
     readonly hero = inject(VodDetailsHeroPresenter);
     readonly menu = inject(VodDetailsMenuService);
-    private readonly trailerDialog = inject(TrailerDialogService);
+    /** The movie the route addresses, see {@link VodDetailsSelectionService}. */
+    private readonly selection = inject(VodDetailsSelectionService);
     private readonly logger = createLogger('VodDetailsRoute');
     /** `playlistId:vodId` of the last initialized detail view */
     private readonly lastInitKey = signal<string | null>(null);
@@ -176,167 +122,22 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
     /** The route copy's own row — what Resume acts on. */
     readonly routePlaybackPosition = this.playback.routePlaybackPosition;
 
-    /**
-     * Reactive route params: the component is reused when navigating
-     * between two VOD details (e.g. via the Similar rail), so computeds
-     * must not read the one-shot snapshot.
-     */
-    private readonly routeParams = toSignal(this.route.params, {
-        initialValue: this.route.snapshot.params,
-    });
-
     readonly theme = this.settingsStore.theme;
     readonly isElectron = this.downloadsService.isAvailable;
 
     readonly isFavorite = this.xtreamStore.isFavorite;
     readonly isWatched = this.watched.isWatched;
     readonly canToggleWatched = this.watched.canToggle;
-    readonly selectedVodId = computed(() =>
-        Number(this.routeParams()['vodId'])
-    );
-    readonly playbackSessionKey = computed(() => {
-        const sourceId = this.xtreamStore.currentPlaylist()?.id;
-        const contentId = this.selectedVodId();
-        return sourceId && Number.isFinite(contentId) && contentId > 0
-            ? createPlaybackSessionKey({ kind: 'vod', sourceId, contentId })
-            : '';
-    });
-    readonly providerOnly = computed(() => {
-        this.routeParams();
-        return isProviderOnlyDetailState(window.history.state);
-    });
-    readonly selectedItem = computed(() => {
-        const item =
-            this.xtreamStore.selectedItem() as unknown as XtreamVodDetails | null;
-
-        return item && resolveVodIdentity(item) === this.selectedVodId()
-            ? item
-            : null;
-    });
-    private readonly scopedVodCategories = computed(() => {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        return playlistId &&
-            this.xtreamStore.vodCategoriesPlaylistId() === playlistId
-            ? this.xtreamStore.vodCategories()
-            : [];
-    });
-    private readonly scopedVodStreams = computed(() => {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        return playlistId &&
-            this.xtreamStore.vodStreamsPlaylistId() === playlistId
-            ? this.xtreamStore.vodStreams()
-            : [];
-    });
-    readonly selectedCategory = computed<Partial<XtreamCategory> | null>(() => {
-        const categoryId = this.routeParams()['categoryId'];
-        if (!categoryId) {
-            return null;
-        }
-
-        return (
-            this.scopedVodCategories().find(
-                (category) =>
-                    String(
-                        (
-                            category as XtreamCategory & {
-                                id?: string | number;
-                            }
-                        ).category_id ??
-                            (
-                                category as XtreamCategory & {
-                                    id?: string | number;
-                                }
-                            ).id
-                    ) === String(categoryId)
-            ) ?? null
-        );
-    });
-    readonly selectedCatalogItem = computed<
-        | (Partial<XtreamVodStream> & {
-              id?: string | number;
-              poster_url?: string;
-              title?: string;
-              xtream_id?: string | number;
-          })
-        | null
-    >(() => {
-        const vodId = this.selectedVodId();
-        if (!Number.isFinite(vodId) || vodId <= 0) {
-            return null;
-        }
-
-        return (
-            this.scopedVodStreams().find(
-                (item) =>
-                    Number(
-                        (
-                            item as XtreamVodStream & {
-                                id?: string | number;
-                                xtream_id?: string | number;
-                            }
-                        ).xtream_id ??
-                            (
-                                item as XtreamVodStream & {
-                                    id?: string | number;
-                                }
-                            ).stream_id ??
-                            (
-                                item as XtreamVodStream & {
-                                    id?: string | number;
-                                }
-                            ).id
-                    ) === vodId
-            ) ?? null
-        );
-    });
-    /** Movie identity for multi-source discovery; null until a title exists */
-    private readonly multiSourceMovie = computed(() => {
-        // Electron stores categories under `name`, the live API under
-        // `category_name` — the same duality the fallback view reads.
-        const category = this.selectedCategory() as {
-            name?: string;
-            category_name?: string;
-        } | null;
-
-        return resolveVodMultiSourceMovie({
-            playlistId: this.xtreamStore.currentPlaylist()?.id,
-            // `title` is the alias the Xtream data source actually writes
-            // (createPlaylist maps name -> title), so reading only `name`
-            // would fall back to the raw playlist UUID in the sources list.
-            playlistName:
-                this.xtreamStore.currentPlaylist()?.name ??
-                this.xtreamStore.currentPlaylist()?.title,
-            vodId: this.selectedVodId(),
-            vodInfo: this.selectedVodInfo(),
-            catalogItem: this.selectedCatalogItem(),
-            containerExtension:
-                this.selectedItem()?.movie_data?.container_extension,
-            categoryName: category?.name ?? category?.category_name ?? null,
-        });
-    });
-    readonly selectedVodInfo = computed(() => {
-        const item = this.selectedItem();
-        return item && hasUsableXtreamVodMetadata(item)
-            ? getXtreamVodInfo(item)
-            : null;
-    });
-    readonly playableVodItem = computed(() => {
-        const item = this.selectedItem();
-        return item && resolveXtreamVodPlaybackSource(item) ? item : null;
-    });
-    readonly fallbackView = computed(() => {
-        const item = this.selectedItem();
-        if (!item || this.selectedVodInfo()) {
-            return null;
-        }
-
-        return buildXtreamVodFallbackViewModel({
-            vodDetails: item,
-            catalogItem: this.selectedCatalogItem(),
-            category: this.selectedCategory(),
-            vodId: this.selectedVodId(),
-        });
-    });
+    readonly selectedVodId = this.selection.selectedVodId;
+    readonly playbackSessionKey = this.selection.playbackSessionKey;
+    readonly providerOnly = this.selection.providerOnly;
+    readonly selectedItem = this.selection.selectedItem;
+    readonly selectedCategory = this.selection.selectedCategory;
+    readonly selectedCatalogItem = this.selection.selectedCatalogItem;
+    private readonly multiSourceMovie = this.selection.multiSourceMovie;
+    readonly selectedVodInfo = this.selection.selectedVodInfo;
+    readonly playableVodItem = this.selection.playableVodItem;
+    readonly fallbackView = this.selection.fallbackView;
     readonly isLoadingDetails = this.xtreamStore.isLoadingDetails;
     readonly detailsError = this.xtreamStore.detailsError;
     readonly matchedExternalPlayback = this.playback.matchedExternalPlayback;
@@ -362,38 +163,19 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
             this.isDownloaded() && this.externalPrimaryButtonState() === 'idle'
     );
 
-    /** 2πr of the r=15.5 progress-ring circle in its 36×36 viewBox. */
-    readonly downloadRingCircumference = 2 * Math.PI * 15.5;
-
-    /**
-     * Dash offset that leaves the arc at the real percent — or a fixed
-     * quarter arc when the total size is unknown and the ring spins instead.
-     */
-    readonly downloadRingOffset = computed(() => {
-        const percent = this.downloadPercent();
-        return percent === null
-            ? this.downloadRingCircumference * 0.75
-            : this.downloadRingCircumference * (1 - percent / 100);
-    });
+    readonly downloadRingCircumference = this.downloads.ringCircumference;
+    readonly downloadRingOffset = this.downloads.ringOffset;
 
     /** Drives the heart's brief scale pulse when favoriting toggles. */
     readonly favoritePulse = signal(false);
     private favoritePulseTimer: ReturnType<typeof setTimeout> | null = null;
 
-    readonly trailerEmbedUrl = computed(() =>
-        youtubeEmbedUrl(this.selectedVodInfo()?.youtube_trailer)
-    );
-    /** `playlist:vod`: the hero keys its one-time layout decision on it. */
-    readonly contentKey = computed(
-        () =>
-            `xtream-vod:${this.xtreamStore.currentPlaylist()?.id ?? ''}:${this.selectedVodId()}`
-    );
-    /** Settings → Playback → Play trailers in details background. */
-    readonly trailerBackdropUrl = computed(() =>
-        this.settingsStore.detailTrailerBackdrop?.() === true
-            ? this.trailerEmbedUrl()
-            : null
-    );
+    readonly trailerEmbedUrl = this.hero.trailerEmbedUrl;
+    readonly contentKey = this.selection.contentKey;
+    readonly trailerBackdropUrl = this.hero.trailerBackdropUrl;
+    readonly scrollToCast = scrollToCastCrewRow;
+    /** Clickable year/genre/country chips (Discover pages) */
+    readonly discover = this.navigation.discover;
 
     readonly similarItems = this.similar.similarItems;
     readonly similarInPortals = this.similar.similarInPortals;
@@ -511,6 +293,9 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
             formatPosition: () => this.formatPosition(),
             similarItems: this.similarItems,
             similarInPortals: this.similarInPortals,
+            openSimilar: (item) => this.navigation.openSimilar(item),
+            openSimilarInPortals: (item) =>
+                this.navigation.openSimilarInPortals(item),
         });
         this.menu.bind({
             item: this.playableVodItem,
@@ -538,73 +323,18 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
         }
     }
 
-    openSimilarInPortals(item: CrossPortalSimilarItem): void {
-        void this.router.navigate(this.crossPortalSimilar.buildLink(item));
-    }
-
-    openSimilar(item: SimilarCatalogItem): void {
-        void this.router.navigate(['../..', item.categoryId, item.id], {
-            relativeTo: this.route,
-        });
-    }
-
     openSimilarRailItem(item: SimilarRailItem): void {
-        const local = this.similarItems().find(
-            (candidate) => `c${candidate.id}` === item.key
-        );
-        if (local) {
-            this.openSimilar(local);
-            return;
-        }
-        const crossPortal = this.similarInPortals().find(
-            (candidate) =>
-                `x${candidate.match.playlistId}-${candidate.match.xtreamId}` ===
-                item.key
-        );
-        if (crossPortal) {
-            this.openSimilarInPortals(crossPortal);
-        }
+        this.hero.openSimilarRailItem(item);
     }
 
     openTrailer(): void {
-        const embedUrl = this.trailerEmbedUrl();
-        const title = this.selectedVodInfo()?.name;
-        if (embedUrl) {
-            this.trailerDialog.open({ embedUrl, title: title ?? '' });
-        }
-    }
-
-    scrollToCast(): void {
-        document
-            .getElementById('detail-cast-crew')
-            ?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        this.hero.openTrailer();
     }
 
     openActor(member: TmdbEnrichedCastMember): void {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        if (!playlistId || !member.tmdbPersonId) {
-            return;
-        }
-        void this.router.navigate([
-            '/workspace/xtreams',
-            playlistId,
-            'actor',
-            member.tmdbPersonId,
-        ]);
+        this.navigation.openActor(member);
     }
 
-    /** Clickable year/genre/country chips (Discover pages) */
-    private readonly tmdbEnrichment = inject(TmdbEnrichmentService);
-
-    readonly discover = createDiscoverFacetNavigation(() => {
-        const playlistId = this.xtreamStore.currentPlaylist()?.id;
-        // Discover reads its results from TMDB, so a chip must not offer a
-        // page that enrichment cannot fill
-        return playlistId && this.tmdbEnrichment.isEnabled()
-            ? { portal: 'xtream', mediaType: 'movie', playlistId }
-            : null;
-    });
-
     ngOnDestroy(): void {
         if (this.favoritePulseTimer) {
             clearTimeout(this.favoritePulseTimer);
@@ -869,26 +599,8 @@ export class VodDetailsRouteComponent implements OnInit, OnDestroy {
         return this.downloads.resumePaused();
     }
 
-    /**
-     * A running download is destroyed by one click, so the icon button asks
-     * first — there is no label left to warn what the click does.
-     */
     promptCancelDownload(): void {
-        this.dialogService.openConfirmDialog({
-            title: this.translateService.instant(
-                'DOWNLOADS.CANCEL_CONFIRM_TITLE'
-            ),
-            message: this.translateService.instant(
-                'DOWNLOADS.CANCEL_CONFIRM_MESSAGE'
-            ),
-            confirmLabel: this.translateService.instant(
-                'DOWNLOADS.CANCEL_CONFIRM_TITLE'
-            ),
-            // "Cancel" next to "Cancel download" would read as the same action.
-            cancelLabel: this.translateService.instant('CLOSE'),
-            tone: 'destructive',
-            onConfirm: () => void this.downloads.cancelActive(),
-        });
+        this.downloads.promptCancel();
     }
 
     revealDownloadedFile(): Promise<void> {
diff --git a/libs/portal/xtream/feature/src/lib/vod-details/vod-details-selection.service.ts b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-selection.service.ts
new file mode 100644
index 000000000..cc4458b67
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/vod-details/vod-details-selection.service.ts
@@ -0,0 +1,213 @@
+import { Injectable, computed, inject } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { ActivatedRoute } from '@angular/router';
+import { createPlaybackSessionKey } from '@iptvnator/playback/util';
+import { isProviderOnlyDetailState } from '@iptvnator/portal/shared/util';
+import {
+    resolveXtreamVodPlaybackSource,
+    XtreamStore,
+} from '@iptvnator/portal/xtream/data-access';
+import {
+    getXtreamVodInfo,
+    XtreamCategory,
+    XtreamVodDetails,
+    XtreamVodStream,
+} from '@iptvnator/shared/interfaces';
+import {
+    buildXtreamVodFallbackViewModel,
+    hasUsableXtreamVodMetadata,
+} from './vod-details-fallback.util';
+import { resolveVodMultiSourceMovie } from './vod-multi-source-identity';
+
+type XtreamVodIdentityItem = XtreamVodDetails & {
+    readonly id?: number | string;
+    readonly stream_id?: number | string;
+    readonly xtream_id?: number | string;
+};
+
+function resolveVodIdentity(item: XtreamVodDetails): number | null {
+    const candidate = item as XtreamVodIdentityItem;
+    const value =
+        item.movie_data?.stream_id ??
+        candidate.xtream_id ??
+        candidate.stream_id ??
+        candidate.id;
+    const id = typeof value === 'string' ? Number(value) : value;
+
+    return typeof id === 'number' && Number.isSafeInteger(id) && id > 0
+        ? id
+        : null;
+}
+
+/**
+ * What the VOD details route selects: the movie the params address, as the
+ * store, the loaded catalog and the route's category describe it. Read-only
+ * derivations of the route and the store, shared by the page and the
+ * services it binds.
+ */
+@Injectable()
+export class VodDetailsSelectionService {
+    private readonly route = inject(ActivatedRoute);
+    private readonly xtreamStore = inject(XtreamStore);
+
+    /**
+     * Reactive route params: the component is reused when navigating
+     * between two VOD details (e.g. via the Similar rail), so computeds
+     * must not read the one-shot snapshot.
+     */
+    private readonly routeParams = toSignal(this.route.params, {
+        initialValue: this.route.snapshot.params,
+    });
+
+    readonly selectedVodId = computed(() =>
+        Number(this.routeParams()['vodId'])
+    );
+    readonly playbackSessionKey = computed(() => {
+        const sourceId = this.xtreamStore.currentPlaylist()?.id;
+        const contentId = this.selectedVodId();
+        return sourceId && Number.isFinite(contentId) && contentId > 0
+            ? createPlaybackSessionKey({ kind: 'vod', sourceId, contentId })
+            : '';
+    });
+    readonly providerOnly = computed(() => {
+        this.routeParams();
+        return isProviderOnlyDetailState(window.history.state);
+    });
+    readonly selectedItem = computed(() => {
+        const item =
+            this.xtreamStore.selectedItem() as unknown as XtreamVodDetails | null;
+
+        return item && resolveVodIdentity(item) === this.selectedVodId()
+            ? item
+            : null;
+    });
+    private readonly scopedVodCategories = computed(() => {
+        const playlistId = this.xtreamStore.currentPlaylist()?.id;
+        return playlistId &&
+            this.xtreamStore.vodCategoriesPlaylistId() === playlistId
+            ? this.xtreamStore.vodCategories()
+            : [];
+    });
+    private readonly scopedVodStreams = computed(() => {
+        const playlistId = this.xtreamStore.currentPlaylist()?.id;
+        return playlistId &&
+            this.xtreamStore.vodStreamsPlaylistId() === playlistId
+            ? this.xtreamStore.vodStreams()
+            : [];
+    });
+    readonly selectedCategory = computed<Partial<XtreamCategory> | null>(() => {
+        const categoryId = this.routeParams()['categoryId'];
+        if (!categoryId) {
+            return null;
+        }
+
+        return (
+            this.scopedVodCategories().find(
+                (category) =>
+                    String(
+                        (
+                            category as XtreamCategory & {
+                                id?: string | number;
+                            }
+                        ).category_id ??
+                            (
+                                category as XtreamCategory & {
+                                    id?: string | number;
+                                }
+                            ).id
+                    ) === String(categoryId)
+            ) ?? null
+        );
+    });
+    readonly selectedCatalogItem = computed<
+        | (Partial<XtreamVodStream> & {
+              id?: string | number;
+              poster_url?: string;
+              title?: string;
+              xtream_id?: string | number;
+          })
+        | null
+    >(() => {
+        const vodId = this.selectedVodId();
+        if (!Number.isFinite(vodId) || vodId <= 0) {
+            return null;
+        }
+
+        return (
+            this.scopedVodStreams().find(
+                (item) =>
+                    Number(
+                        (
+                            item as XtreamVodStream & {
+                                id?: string | number;
+                                xtream_id?: string | number;
+                            }
+                        ).xtream_id ??
+                            (
+                                item as XtreamVodStream & {
+                                    id?: string | number;
+                                }
+                            ).stream_id ??
+                            (
+                                item as XtreamVodStream & {
+                                    id?: string | number;
+                                }
+                            ).id
+                    ) === vodId
+            ) ?? null
+        );
+    });
+    /** Movie identity for multi-source discovery; null until a title exists */
+    readonly multiSourceMovie = computed(() => {
+        // Electron stores categories under `name`, the live API under
+        // `category_name` — the same duality the fallback view reads.
+        const category = this.selectedCategory() as {
+            name?: string;
+            category_name?: string;
+        } | null;
+
+        return resolveVodMultiSourceMovie({
+            playlistId: this.xtreamStore.currentPlaylist()?.id,
+            // `title` is the alias the Xtream data source actually writes
+            // (createPlaylist maps name -> title), so reading only `name`
+            // would fall back to the raw playlist UUID in the sources list.
+            playlistName:
+                this.xtreamStore.currentPlaylist()?.name ??
+                this.xtreamStore.currentPlaylist()?.title,
+            vodId: this.selectedVodId(),
+            vodInfo: this.selectedVodInfo(),
+            catalogItem: this.selectedCatalogItem(),
+            containerExtension:
+                this.selectedItem()?.movie_data?.container_extension,
+            categoryName: category?.name ?? category?.category_name ?? null,
+        });
+    });
+    readonly selectedVodInfo = computed(() => {
+        const item = this.selectedItem();
+        return item && hasUsableXtreamVodMetadata(item)
+            ? getXtreamVodInfo(item)
+            : null;
+    });
+    readonly playableVodItem = computed(() => {
+        const item = this.selectedItem();
+        return item && resolveXtreamVodPlaybackSource(item) ? item : null;
+    });
+    readonly fallbackView = computed(() => {
+        const item = this.selectedItem();
+        if (!item || this.selectedVodInfo()) {
+            return null;
+        }
+
+        return buildXtreamVodFallbackViewModel({
+            vodDetails: item,
+            catalogItem: this.selectedCatalogItem(),
+            category: this.selectedCategory(),
+            vodId: this.selectedVodId(),
+        });
+    });
+    /** `playlist:vod`: the hero keys its one-time layout decision on it. */
+    readonly contentKey = computed(
+        () =>
+            `xtream-vod:${this.xtreamStore.currentPlaylist()?.id ?? ''}:${this.selectedVodId()}`
+    );
+}
diff --git a/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.spec.ts b/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.spec.ts
new file mode 100644
index 000000000..aa6cc02c7
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.spec.ts
@@ -0,0 +1,114 @@
+import { signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { ActivatedRoute, Router } from '@angular/router';
+import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
+import {
+    CrossPortalSimilarService,
+    TmdbEnrichmentService,
+} from '@iptvnator/services';
+import {
+    injectXtreamDetailNavigation,
+    type XtreamDetailNavigation,
+} from './xtream-detail-navigation';
+
+describe('injectXtreamDetailNavigation', () => {
+    const route = { snapshot: { params: {} } };
+    const navigate = jest.fn();
+    const buildLink = jest.fn();
+    const currentPlaylist = signal<{ id: string } | null>(null);
+    const enrichmentEnabled = signal(true);
+
+    function create(mediaType: 'movie' | 'tv'): XtreamDetailNavigation {
+        return TestBed.runInInjectionContext(() =>
+            injectXtreamDetailNavigation(mediaType)
+        );
+    }
+
+    beforeEach(() => {
+        navigate.mockReset();
+        buildLink.mockReset();
+        currentPlaylist.set({ id: 'xtream-1' });
+        enrichmentEnabled.set(true);
+        TestBed.configureTestingModule({
+            providers: [
+                { provide: Router, useValue: { navigate } },
+                { provide: ActivatedRoute, useValue: route },
+                { provide: XtreamStore, useValue: { currentPlaylist } },
+                { provide: CrossPortalSimilarService, useValue: { buildLink } },
+                {
+                    provide: TmdbEnrichmentService,
+                    useValue: { isEnabled: () => enrichmentEnabled() },
+                },
+            ],
+        });
+    });
+
+    it('opens the actor page of a TMDB-matched cast member', () => {
+        create('movie').openActor({ name: 'Mara', tmdbPersonId: 77 } as never);
+
+        expect(navigate).toHaveBeenCalledWith([
+            '/workspace/xtreams',
+            'xtream-1',
+            'actor',
+            77,
+        ]);
+    });
+
+    it('opens no actor page without a playlist or a TMDB person', () => {
+        const navigation = create('movie');
+
+        navigation.openActor({ name: 'Mara' } as never);
+        currentPlaylist.set(null);
+        navigation.openActor({ name: 'Mara', tmdbPersonId: 77 } as never);
+
+        expect(navigate).not.toHaveBeenCalled();
+    });
+
+    it('opens a similar title of this playlist relative to the details route', () => {
+        create('tv').openSimilar({ categoryId: 12, id: 345 } as never);
+
+        expect(navigate).toHaveBeenCalledWith(['../..', 12, 345], {
+            relativeTo: route,
+        });
+    });
+
+    it('opens a similar title of another portal through its link', () => {
+        const item = { match: { playlistId: 'xtream-2' } } as never;
+        const link = ['/workspace/xtreams', 'xtream-2', 'series', '3', '9'];
+        buildLink.mockReturnValue(link);
+
+        create('tv').openSimilarInPortals(item);
+
+        expect(buildLink).toHaveBeenCalledWith(item);
+        expect(navigate).toHaveBeenCalledWith(link);
+    });
+
+    it.each(['movie', 'tv'] as const)(
+        'sends the facet chips to the %s Discover page of the playlist',
+        (mediaType) => {
+            const { discover } = create(mediaType);
+
+            expect(discover.canOpenYear('1999-03-31')).toBe(true);
+            discover.openYear('1999-03-31');
+
+            expect(navigate).toHaveBeenCalledWith(
+                ['/workspace', 'xtreams', 'xtream-1', 'discover'],
+                { queryParams: { type: mediaType, year: '1999' } }
+            );
+        }
+    );
+
+    it('offers no facet chip while enrichment cannot fill Discover', () => {
+        const { discover } = create('movie');
+
+        enrichmentEnabled.set(false);
+        expect(discover.canOpenYear('1999-03-31')).toBe(false);
+
+        enrichmentEnabled.set(true);
+        currentPlaylist.set(null);
+        expect(discover.canOpenYear('1999-03-31')).toBe(false);
+        discover.openYear('1999-03-31');
+
+        expect(navigate).not.toHaveBeenCalled();
+    });
+});
diff --git a/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.ts b/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.ts
new file mode 100644
index 000000000..f0c2d93a2
--- /dev/null
+++ b/libs/portal/xtream/feature/src/lib/xtream-detail-navigation.ts
@@ -0,0 +1,73 @@
+import { inject } from '@angular/core';
+import { ActivatedRoute, Router } from '@angular/router';
+import {
+    createDiscoverFacetNavigation,
+    type DiscoverFacetNavigation,
+} from '@iptvnator/portal/shared/util';
+import { XtreamStore } from '@iptvnator/portal/xtream/data-access';
+import {
+    CrossPortalSimilarItem,
+    CrossPortalSimilarService,
+    TmdbEnrichmentService,
+} from '@iptvnator/services';
+import type { TmdbEnrichedCastMember } from '@iptvnator/shared/interfaces';
+import type { SimilarCatalogItem } from './tmdb-similar.util';
+
+/** Where an Xtream movie or series details page can send the viewer. */
+export interface XtreamDetailNavigation {
+    /** Clickable year/genre/country chips (Discover pages) */
+    readonly discover: DiscoverFacetNavigation;
+    /** The actor page of a TMDB-matched cast member. */
+    openActor(member: TmdbEnrichedCastMember): void;
+    /** A Similar-rail title of this playlist: the same route, another id. */
+    openSimilar(item: SimilarCatalogItem): void;
+    /** A Similar-rail title found in another of the user's portals. */
+    openSimilarInPortals(item: CrossPortalSimilarItem): void;
+}
+
+/**
+ * Outbound navigation shared by the Xtream movie (`movie`) and series (`tv`)
+ * details pages.
+ *
+ * Must run in an injection context.
+ */
+export function injectXtreamDetailNavigation(
+    mediaType: 'movie' | 'tv'
+): XtreamDetailNavigation {
+    const router = inject(Router);
+    const route = inject(ActivatedRoute);
+    const xtreamStore = inject(XtreamStore);
+    const crossPortalSimilar = inject(CrossPortalSimilarService);
+    const tmdbEnrichment = inject(TmdbEnrichmentService);
+
+    return {
+        discover: createDiscoverFacetNavigation(() => {
+            const playlistId = xtreamStore.currentPlaylist()?.id;
+            // Discover reads its results from TMDB, so a chip must not offer a
+            // page that enrichment cannot fill
+            return playlistId && tmdbEnrichment.isEnabled()
+                ? { portal: 'xtream', mediaType, playlistId }
+                : null;
+        }),
+        openActor(member) {
+            const playlistId = xtreamStore.currentPlaylist()?.id;
+            if (!playlistId || !member.tmdbPersonId) {
+                return;
+            }
+            void router.navigate([
+                '/workspace/xtreams',
+                playlistId,
+                'actor',
+                member.tmdbPersonId,
+            ]);
+        },
+        openSimilar(item) {
+            void router.navigate(['../..', item.categoryId, item.id], {
+                relativeTo: route,
+            });
+        },
+        openSimilarInPortals(item) {
+            void router.navigate(crossPortalSimilar.buildLink(item));
+        },
+    };
+}
diff --git a/libs/ui/components/src/lib/season-container/episode-subline.util.ts b/libs/ui/components/src/lib/season-container/episode-subline.util.ts
new file mode 100644
index 000000000..2b73f8b50
--- /dev/null
+++ b/libs/ui/components/src/lib/season-container/episode-subline.util.ts
@@ -0,0 +1,37 @@
+import type { TranslateService } from '@ngx-translate/core';
+import {
+    formatDurationLabel,
+    formatRemainingLabel,
+    isPortalPlaybackWatched,
+} from '@iptvnator/portal/shared/util';
+import {
+    PlaybackPositionData,
+    XtreamSerieEpisodeInfo,
+} from '@iptvnator/shared/interfaces';
+import {
+    episodeRuntimeSeconds,
+    formatEpisodePositionText,
+} from './episode-progress.util';
+
+/**
+ * The line under an episode card's title, built from the episode's runtime
+ * and its saved playback position:
+ * "42 min · 18m left", "42 min · watched", "42 min" — or null.
+ */
+export function buildEpisodeSubline(
+    info: XtreamSerieEpisodeInfo | undefined,
+    position: PlaybackPositionData | undefined,
+    translate: Pick<TranslateService, 'instant'>
+): string | null {
+    const duration = formatDurationLabel(episodeRuntimeSeconds(info));
+    const remaining = formatRemainingLabel(position);
+    const parts = [
+        duration ? translate.instant(duration.key, duration.params) : null,
+        isPortalPlaybackWatched(position)
+            ? translate.instant('PORTALS.DETAIL.WATCHED')
+            : remaining
+              ? translate.instant(remaining.key, remaining.params)
+              : formatEpisodePositionText(position),
+    ].filter((part): part is string => !!part);
+    return parts.length ? parts.join(' · ') : null;
+}
diff --git a/libs/ui/components/src/lib/season-container/season-auto-select.state.ts b/libs/ui/components/src/lib/season-container/season-auto-select.state.ts
new file mode 100644
index 000000000..d7a4ce22e
--- /dev/null
+++ b/libs/ui/components/src/lib/season-container/season-auto-select.state.ts
@@ -0,0 +1,136 @@
+import {
+    type Signal,
+    type WritableSignal,
+    computed,
+    effect,
+    untracked,
+} from '@angular/core';
+import {
+    PlaybackPositionData,
+    XtreamSerieEpisode,
+} from '@iptvnator/shared/interfaces';
+import { resolveAutoSelectedSeason } from './season-auto-select.util';
+
+export interface SeasonAutoSelectSources {
+    /**
+     * The container's selection (see `SeasonContainerComponent.selectedSeason`).
+     * Auto-select writes to it; user tab clicks write to it too and stick
+     * until the auto-select key changes.
+     */
+    readonly selectedSeason: WritableSignal<string | undefined>;
+    readonly seasons: Signal<Record<string, XtreamSerieEpisode[]>>;
+    /** Season keys in display order. */
+    readonly sortedSeasonKeys: Signal<readonly string[]>;
+    /** Season key of the inline-playing episode, if it is in the loaded set. */
+    readonly playingSeasonKey: Signal<string | null>;
+    readonly playbackPositions: Signal<
+        ReadonlyMap<number, PlaybackPositionData>
+    >;
+    readonly positionOf: (
+        episode: XtreamSerieEpisode
+    ) => PlaybackPositionData | undefined;
+    /** Stalker lazy-VOD: some seasons' episode lists are not loaded yet. */
+    readonly hasUnloadedSeasons: Signal<boolean>;
+    readonly episodeCounts: Signal<Record<string, number>>;
+    readonly watchedCounts: Signal<Record<string, number>>;
+    readonly emitSeasonSelected: (seasonKey: string) => void;
+}
+
+export interface SeasonAutoSelectState {
+    /**
+     * Record that this session toggled watched state itself: the positions
+     * flip that follows is then not treated as an initial load.
+     */
+    markLocalWatchedMutation(): void;
+}
+
+/** Key of the loaded season that holds the episode with this content id. */
+export function findSeasonOfEpisode(
+    seasons: Record<string, XtreamSerieEpisode[]>,
+    episodeId: number
+): string | null {
+    for (const [key, episodes] of Object.entries(seasons)) {
+        if (episodes?.some((episode) => Number(episode.id) === episodeId)) {
+            return key;
+        }
+    }
+    return null;
+}
+
+/**
+ * Season auto-selection and `seasonSelected` emission of
+ * `SeasonContainerComponent`. The selection re-resolves when the season key
+ * set changes or when playback positions first arrive; ongoing position
+ * saves do not reset it — only the empty→loaded transition of the positions
+ * map does, and even that is ignored once this session toggled watched state
+ * itself.
+ *
+ * Registers two effects, so it must be called in an injection context (the
+ * container's constructor).
+ */
+export function createSeasonAutoSelectState(
+    sources: SeasonAutoSelectSources
+): SeasonAutoSelectState {
+    const autoSelectKey = computed(
+        () =>
+            `${sources.sortedSeasonKeys().join('|')}::${
+                sources.playbackPositions().size > 0 ? '1' : '0'
+            }`
+    );
+    let lastAutoSelectKey: string | null = null;
+    let lastAutoSelectSeasonSet: string | null = null;
+    /**
+     * True once this session toggled watched state itself. From then on an
+     * empty↔loaded flip of the positions map is the echo of that action, not
+     * an async initial load — re-resolving on it would yank the user off the
+     * season they just marked (e.g. all-watched season 1 → jump to season 2).
+     */
+    let hasLocalWatchedMutation = false;
+    let lastEmittedSeason: string | undefined;
+
+    /** Auto-select rules live in season-auto-select.util.ts. */
+    const resolveAutoSeason = (): string | undefined =>
+        resolveAutoSelectedSeason({
+            keys: sources.sortedSeasonKeys(),
+            playingSeasonKey: sources.playingSeasonKey(),
+            seasons: sources.seasons(),
+            positionOf: sources.positionOf,
+            hasUnloadedSeasons: sources.hasUnloadedSeasons(),
+            episodeCounts: sources.episodeCounts(),
+            watchedCounts: sources.watchedCounts(),
+        });
+
+    effect(() => {
+        const key = autoSelectKey();
+        if (key === lastAutoSelectKey) {
+            return;
+        }
+        const seasonSet = untracked(() => sources.sortedSeasonKeys().join('|'));
+        const seasonSetUnchanged = seasonSet === lastAutoSelectSeasonSet;
+        lastAutoSelectKey = key;
+        lastAutoSelectSeasonSet = seasonSet;
+        // A positions-emptiness flip after a local watched toggle keeps
+        // the current selection; only the async initial positions load
+        // (or a season-set change) re-resolves the season.
+        if (seasonSetUnchanged && hasLocalWatchedMutation) {
+            return;
+        }
+        sources.selectedSeason.set(untracked(() => resolveAutoSeason()));
+    });
+
+    // Fire the lazy-load/enrichment hooks for auto-selected seasons too —
+    // with tabs there is no initial "pick a season" click anymore.
+    effect(() => {
+        const selected = sources.selectedSeason();
+        if (selected && selected !== lastEmittedSeason) {
+            lastEmittedSeason = selected;
+            sources.emitSeasonSelected(selected);
+        }
+    });
+
+    return {
+        markLocalWatchedMutation: () => {
+            hasLocalWatchedMutation = true;
+        },
+    };
+}
diff --git a/libs/ui/components/src/lib/season-container/season-container.component.ts b/libs/ui/components/src/lib/season-container/season-container.component.ts
index 26b265c13..c857f5530 100644
--- a/libs/ui/components/src/lib/season-container/season-container.component.ts
+++ b/libs/ui/components/src/lib/season-container/season-container.component.ts
@@ -4,12 +4,10 @@ import {
     ElementRef,
     OnInit,
     computed,
-    effect,
     inject,
     input,
     output,
     signal,
-    untracked,
 } from '@angular/core';
 import { MatButtonModule } from '@angular/material/button';
 import { MatButtonToggleModule } from '@angular/material/button-toggle';
@@ -21,8 +19,6 @@ import { TranslateModule, TranslateService } from '@ngx-translate/core';
 import { type SeasonEpisodeDownloadAdapter } from '@iptvnator/portal/shared/data-access';
 import {
     createLogger,
-    formatDurationLabel,
-    formatRemainingLabel,
     getPortalPlaybackProgressPercent,
     isPortalPlaybackInProgress,
     isPortalPlaybackWatched,
@@ -38,11 +34,13 @@ import {
     EpisodeInfoDialogComponent,
     buildEpisodeInfoDialogData,
 } from './episode-info-dialog.component';
+import { formatEpisodePositionText } from './episode-progress.util';
+import { buildEpisodeSubline } from './episode-subline.util';
 import {
-    formatEpisodePositionText,
-    episodeRuntimeSeconds,
-} from './episode-progress.util';
-import { resolveAutoSelectedSeason } from './season-auto-select.util';
+    type SeasonAutoSelectState,
+    createSeasonAutoSelectState,
+    findSeasonOfEpisode,
+} from './season-auto-select.state';
 import { SeasonDownloadPresenter } from './season-download-presenter';
 import { SeasonTabsComponent } from './season-tabs.component';
 import { SeasonWatchPresenter } from './season-watch-presenter';
@@ -80,7 +78,8 @@ export class SeasonContainerComponent implements OnInit {
     private readonly translate = inject(TranslateService);
     private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
     private readonly logger = createLogger('SeasonContainer');
-    private lastEmittedSeason: string | undefined;
+    /** Auto-select + `seasonSelected` emission; wired in the constructor. */
+    private readonly autoSelect: SeasonAutoSelectState;
     readonly downloadPresenter = inject(SeasonDownloadPresenter);
     readonly watchPresenter = inject(SeasonWatchPresenter);
 
@@ -148,9 +147,12 @@ export class SeasonContainerComponent implements OnInit {
     });
 
     /** Season key of the inline-playing episode, if it is in the loaded set. */
-    readonly playingSeasonKey = computed(() =>
-        this.findSeasonOfEpisode(this.playingEpisodeId())
-    );
+    readonly playingSeasonKey = computed(() => {
+        const episodeId = this.playingEpisodeId();
+        return episodeId === null
+            ? null
+            : findSeasonOfEpisode(this.seasons(), episodeId);
+    });
 
     /**
      * Selected season. Auto-resolves when the season key set changes or when
@@ -171,22 +173,6 @@ export class SeasonContainerComponent implements OnInit {
         return selected ? (this.seasons()[selected] ?? []) : [];
     });
 
-    private readonly autoSelectKey = computed(
-        () =>
-            `${this.sortedSeasonKeys().join('|')}::${
-                this.playbackPositions().size > 0 ? '1' : '0'
-            }`
-    );
-    private lastAutoSelectKey: string | null = null;
-    private lastAutoSelectSeasonSet: string | null = null;
-    /**
-     * True once this session toggled watched state itself. From then on an
-     * empty↔loaded flip of the positions map is the echo of that action, not
-     * an async initial load — re-resolving on it would yank the user off the
-     * season they just marked (e.g. all-watched season 1 → jump to season 2).
-     */
-    private hasLocalWatchedMutation = false;
-
     /**
      * Show thumbnails in the list view only when episodes have genuinely
      * distinct stills (TMDB or per-episode provider art). When every episode
@@ -254,44 +240,29 @@ export class SeasonContainerComponent implements OnInit {
             openingEpisodeId: this.openingEpisodeId,
             isEpisodeWatched: (episode) => this.isEpisodeWatched(episode),
             emitSeasonToggle: (request) => {
-                this.hasLocalWatchedMutation = true;
+                this.autoSelect.markLocalWatchedMutation();
                 this.seasonPlaybackToggleRequested.emit(request);
             },
             emitSeriesToggle: (request) => {
-                this.hasLocalWatchedMutation = true;
+                this.autoSelect.markLocalWatchedMutation();
                 this.seriesPlaybackToggleRequested.emit(request);
             },
         });
 
-        effect(() => {
-            const key = this.autoSelectKey();
-            if (key === this.lastAutoSelectKey) {
-                return;
-            }
-            const seasonSet = untracked(() =>
-                this.sortedSeasonKeys().join('|')
-            );
-            const seasonSetUnchanged =
-                seasonSet === this.lastAutoSelectSeasonSet;
-            this.lastAutoSelectKey = key;
-            this.lastAutoSelectSeasonSet = seasonSet;
-            // A positions-emptiness flip after a local watched toggle keeps
-            // the current selection; only the async initial positions load
-            // (or a season-set change) re-resolves the season.
-            if (seasonSetUnchanged && this.hasLocalWatchedMutation) {
-                return;
-            }
-            this.selectedSeason.set(untracked(() => this.resolveAutoSeason()));
-        });
-
-        // Fire the lazy-load/enrichment hooks for auto-selected seasons too —
-        // with tabs there is no initial "pick a season" click anymore.
-        effect(() => {
-            const selected = this.selectedSeason();
-            if (selected && selected !== this.lastEmittedSeason) {
-                this.lastEmittedSeason = selected;
-                this.seasonSelected.emit(selected);
-            }
+        // Auto-select rules and the effects driving them live in
+        // season-auto-select.state.ts / season-auto-select.util.ts.
+        this.autoSelect = createSeasonAutoSelectState({
+            selectedSeason: this.selectedSeason,
+            seasons: this.seasons,
+            sortedSeasonKeys: this.sortedSeasonKeys,
+            playingSeasonKey: this.playingSeasonKey,
+            playbackPositions: this.playbackPositions,
+            positionOf: (episode) => this.getEpisodePosition(episode),
+            hasUnloadedSeasons: this.hasUnloadedSeasons,
+            episodeCounts: this.episodeCounts,
+            watchedCounts: this.watchedCounts,
+            emitSeasonSelected: (seasonKey) =>
+                this.seasonSelected.emit(seasonKey),
         });
     }
 
@@ -376,7 +347,7 @@ export class SeasonContainerComponent implements OnInit {
             this.logger.warn('Cannot toggle watched: no playlist ID');
             return;
         }
-        this.hasLocalWatchedMutation = true;
+        this.autoSelect.markLocalWatchedMutation();
 
         const contentXtreamId = this.getEpisodeContentId(episode);
         const currentPosition = this.getEpisodePosition(episode);
@@ -434,21 +405,11 @@ export class SeasonContainerComponent implements OnInit {
 
     /** "42 min · 18m left", "42 min · watched", "42 min" — or null. */
     getEpisodeSubline(episode: XtreamSerieEpisode): string | null {
-        const info = this.getEpisodeInfo(episode);
-        const duration = formatDurationLabel(episodeRuntimeSeconds(info));
-        const position = this.playbackPositions().get(Number(episode.id));
-        const remaining = formatRemainingLabel(position);
-        const parts = [
-            duration
-                ? this.translate.instant(duration.key, duration.params)
-                : null,
-            this.isEpisodeWatched(episode)
-                ? this.translate.instant('PORTALS.DETAIL.WATCHED')
-                : remaining
-                  ? this.translate.instant(remaining.key, remaining.params)
-                  : this.getEpisodePositionText(episode),
-        ].filter((part): part is string => !!part);
-        return parts.length ? parts.join(' · ') : null;
+        return buildEpisodeSubline(
+            this.getEpisodeInfo(episode),
+            this.getEpisodePosition(episode),
+            this.translate
+        );
     }
 
     getEpisodePositionText(episode: XtreamSerieEpisode): string | null {
@@ -464,33 +425,4 @@ export class SeasonContainerComponent implements OnInit {
     ): PlaybackPositionData | undefined {
         return this.playbackPositions().get(this.getEpisodeContentId(episode));
     }
-
-    private findSeasonOfEpisode(episodeId: number | null): string | null {
-        if (episodeId === null) {
-            return null;
-        }
-        for (const [key, episodes] of Object.entries(this.seasons())) {
-            if (
-                episodes?.some(
-                    (episode) => this.getEpisodeContentId(episode) === episodeId
-                )
-            ) {
-                return key;
-            }
-        }
-        return null;
-    }
-
-    /** Auto-select rules live in season-auto-select.util.ts. */
-    private resolveAutoSeason(): string | undefined {
-        return resolveAutoSelectedSeason({
-            keys: this.sortedSeasonKeys(),
-            playingSeasonKey: this.playingSeasonKey(),
-            seasons: this.seasons(),
-            positionOf: (episode) => this.getEpisodePosition(episode),
-            hasUnloadedSeasons: this.hasUnloadedSeasons(),
-            episodeCounts: this.episodeCounts(),
-            watchedCounts: this.watchedCounts(),
-        });
-    }
 }
diff --git a/libs/ui/playback/src/lib/vod-details/vod-details-navigation.util.ts b/libs/ui/playback/src/lib/vod-details/vod-details-navigation.util.ts
new file mode 100644
index 000000000..0e5ddea55
--- /dev/null
+++ b/libs/ui/playback/src/lib/vod-details/vod-details-navigation.util.ts
@@ -0,0 +1,43 @@
+import type { CrossPortalSimilarItem } from '@iptvnator/services';
+import type {
+    TmdbEnrichedCastMember,
+    VodDetailsItem,
+} from '@iptvnator/shared/interfaces';
+
+/**
+ * Pure helpers resolving where the VOD details page's extras rows (cast &
+ * crew, Similar rail) lead. The component owns the actual navigation.
+ */
+
+/**
+ * Router commands of the actor page for a cast/crew member, inside the
+ * item's own portal workspace. Null when the member has no TMDB person id
+ * (names parsed from provider text): there is no actor page to open.
+ */
+export function buildVodActorRoute(
+    item: VodDetailsItem,
+    member: TmdbEnrichedCastMember
+): (string | number)[] | null {
+    if (!member.tmdbPersonId) {
+        return null;
+    }
+    const basePath =
+        item.type === 'stalker' ? '/workspace/stalker' : '/workspace/xtreams';
+    return [basePath, item.playlistId, 'actor', member.tmdbPersonId];
+}
+
+/**
+ * The cross-portal match behind a Similar-rail card. Rail keys are built by
+ * `buildSimilarRailItems` (vod-details-presentation.ts) as
+ * `x<playlistId>-<xtreamId>`.
+ */
+export function findSimilarByRailKey(
+    items: readonly CrossPortalSimilarItem[],
+    railKey: string
+): CrossPortalSimilarItem | undefined {
+    return items.find(
+        (candidate) =>
+            `x${candidate.match.playlistId}-${candidate.match.xtreamId}` ===
+            railKey
+    );
+}
diff --git a/libs/ui/playback/src/lib/vod-details/vod-details.component.ts b/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
index a2d6eb523..4d3b658e2 100644
--- a/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
+++ b/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
@@ -1,12 +1,9 @@
 import {
     Component,
     computed,
-    effect,
     inject,
     input,
     output,
-    signal,
-    untracked,
     ChangeDetectionStrategy,
 } from '@angular/core';
 import { TranslatePipe, TranslateService } from '@ngx-translate/core';
@@ -53,9 +50,14 @@ import {
 } from '@iptvnator/services';
 import { VOD_DETAILS_MENU_ACTION } from './vod-details-presentation';
 import { createVodDetailsHeroState } from './vod-details-hero.state';
+import {
+    buildVodActorRoute,
+    findSimilarByRailKey,
+} from './vod-details-navigation.util';
 import type { PlaybackFallbackRequest } from '@iptvnator/playback/util';
 import { PortalInlinePlayerComponent } from '../portal-inline-player/portal-inline-player.component';
-import { createVodDownloadState } from './vod-download-state.util';
+import { createVodLocalDownloadState } from './vod-download-state.util';
+import { createVodSimilarInPortals } from './vod-similar-in-portals.state';
 
 /**
  * Unified VOD details component for both Xtream and Stalker portals.
@@ -231,38 +233,12 @@ export class VodDetailsComponent {
      * TMDB recommendations found in the user's OTHER portals (batched DB
      * match, Electron only). Loaded async — the section appears when
      * resolved; staleness-guarded against item changes in flight.
+     * Filtered on read: a relock hides matches cached while unlocked.
      */
-    private readonly similarInPortalsMatched = signal<CrossPortalSimilarItem[]>(
-        []
+    readonly similarInPortals = createVodSimilarInPortals(
+        this.normalizedMeta,
+        this.crossPortalSimilar
     );
-    /** Filtered on read: a relock hides matches cached while unlocked. */
-    readonly similarInPortals = computed(() =>
-        this.crossPortalSimilar.visible(this.similarInPortalsMatched())
-    );
-
-    private readonly loadSimilarInPortals = effect(() => {
-        const meta = this.normalizedMeta();
-        const recommendations = meta.tmdbRecommendations;
-        untracked(() => {
-            this.similarInPortalsMatched.set([]);
-            if (
-                !recommendations?.length ||
-                !this.crossPortalSimilar.isAvailable
-            ) {
-                return;
-            }
-            void this.crossPortalSimilar
-                .matchRecommendations(recommendations, 'movie')
-                .then((items) => {
-                    if (
-                        this.normalizedMeta().tmdbRecommendations ===
-                        recommendations
-                    ) {
-                        this.similarInPortalsMatched.set(items);
-                    }
-                });
-        });
-    });
 
     openSimilarInPortals(item: CrossPortalSimilarItem): void {
         void this.router.navigate(this.crossPortalSimilar.buildLink(item));
@@ -276,19 +252,14 @@ export class VodDetailsComponent {
         () => (this.playbackPosition() ?? 0) > 0 && !this.isWatched()
     );
 
-    private readonly downloadState = createVodDownloadState(
-        this.downloadsService,
-        this.item
-    );
-    readonly isDownloaded = computed(
-        () => !this.providerOnly() && this.downloadState.isDownloaded()
-    );
-    readonly isDownloading = computed(
-        () => !this.providerOnly() && this.downloadState.isDownloading()
-    );
-    readonly isPausedDownload = computed(
-        () => !this.providerOnly() && this.downloadState.isPausedDownload()
-    );
+    private readonly localDownload = createVodLocalDownloadState({
+        downloadsService: this.downloadsService,
+        item: this.item,
+        providerOnly: this.providerOnly,
+    });
+    readonly isDownloaded = this.localDownload.isDownloaded;
+    readonly isDownloading = this.localDownload.isDownloading;
+    readonly isPausedDownload = this.localDownload.isPausedDownload;
 
     private readonly externalButton = createExternalPlaybackButtonState({
         session: this.externalPlayback,
@@ -360,11 +331,7 @@ export class VodDetailsComponent {
     readonly scrollToCast = scrollToCastCrewRow;
 
     openSimilarRailItem(item: SimilarRailItem): void {
-        const match = this.similarInPortals().find(
-            (candidate) =>
-                `x${candidate.match.playlistId}-${candidate.match.xtreamId}` ===
-                item.key
-        );
+        const match = findSimilarByRailKey(this.similarInPortals(), item.key);
         if (match) {
             this.openSimilarInPortals(match);
         }
@@ -450,20 +417,10 @@ export class VodDetailsComponent {
 
     /** Handle back navigation - emit event for parent to handle */
     openActor(member: TmdbEnrichedCastMember): void {
-        if (!member.tmdbPersonId) {
-            return;
+        const commands = buildVodActorRoute(this.item(), member);
+        if (commands) {
+            void this.router.navigate(commands);
         }
-        const item = this.item();
-        const basePath =
-            item.type === 'stalker'
-                ? '/workspace/stalker'
-                : '/workspace/xtreams';
-        void this.router.navigate([
-            basePath,
-            item.playlistId,
-            'actor',
-            member.tmdbPersonId,
-        ]);
     }
 
     goBack(): void {
@@ -494,13 +451,8 @@ export class VodDetailsComponent {
     }
 
     /** Resume the paused download of this VOD */
-    async resumePausedDownload(): Promise<void> {
-        const item = this.item();
-        await this.downloadsService.resumeDownloadByContent(
-            getVodNumericId(item),
-            item.playlistId,
-            'vod'
-        );
+    resumePausedDownload(): Promise<void> {
+        return this.localDownload.resumePausedDownload();
     }
 
     onInlineTimeUpdate(event: { currentTime: number; duration: number }): void {
@@ -526,18 +478,7 @@ export class VodDetailsComponent {
     }
 
     /** Play from local downloaded file */
-    async playFromLocal(): Promise<void> {
-        const item = this.item();
-        const vodId = getVodNumericId(item);
-
-        const filePath = this.downloadsService.getDownloadedFilePath(
-            vodId,
-            item.playlistId,
-            'vod'
-        );
-
-        if (filePath) {
-            await this.downloadsService.playDownload(filePath);
-        }
+    playFromLocal(): Promise<void> {
+        return this.localDownload.playFromLocal();
     }
 }
diff --git a/libs/ui/playback/src/lib/vod-details/vod-download-state.util.ts b/libs/ui/playback/src/lib/vod-details/vod-download-state.util.ts
index 7adf76ba5..b17070ec8 100644
--- a/libs/ui/playback/src/lib/vod-details/vod-download-state.util.ts
+++ b/libs/ui/playback/src/lib/vod-details/vod-download-state.util.ts
@@ -32,3 +32,58 @@ export function createVodDownloadState(
         ),
     };
 }
+
+export interface VodLocalDownloadStateDeps {
+    readonly downloadsService: DownloadsService;
+    readonly item: Signal<VodDetailsItem>;
+    /** Provider detail handoff hides local/download presentation only. */
+    readonly providerOnly: Signal<boolean>;
+}
+
+/**
+ * The VOD details page's view of its own download: the download-state
+ * signals (always false in provider-only mode) and the two actions that
+ * act on the local copy.
+ */
+export function createVodLocalDownloadState(deps: VodLocalDownloadStateDeps) {
+    const { downloadsService, item, providerOnly } = deps;
+    const downloadState = createVodDownloadState(downloadsService, item);
+
+    return {
+        isDownloaded: computed(
+            () => !providerOnly() && downloadState.isDownloaded()
+        ),
+        isDownloading: computed(
+            () => !providerOnly() && downloadState.isDownloading()
+        ),
+        isPausedDownload: computed(
+            () => !providerOnly() && downloadState.isPausedDownload()
+        ),
+
+        /** Resume the paused download of this VOD */
+        async resumePausedDownload(): Promise<void> {
+            const currentItem = item();
+            await downloadsService.resumeDownloadByContent(
+                getVodNumericId(currentItem),
+                currentItem.playlistId,
+                'vod'
+            );
+        },
+
+        /** Play from local downloaded file */
+        async playFromLocal(): Promise<void> {
+            const currentItem = item();
+            const vodId = getVodNumericId(currentItem);
+
+            const filePath = downloadsService.getDownloadedFilePath(
+                vodId,
+                currentItem.playlistId,
+                'vod'
+            );
+
+            if (filePath) {
+                await downloadsService.playDownload(filePath);
+            }
+        },
+    };
+}
diff --git a/libs/ui/playback/src/lib/vod-details/vod-similar-in-portals.state.ts b/libs/ui/playback/src/lib/vod-details/vod-similar-in-portals.state.ts
new file mode 100644
index 000000000..5e3855a89
--- /dev/null
+++ b/libs/ui/playback/src/lib/vod-details/vod-similar-in-portals.state.ts
@@ -0,0 +1,51 @@
+import {
+    type Signal,
+    computed,
+    effect,
+    signal,
+    untracked,
+} from '@angular/core';
+import type {
+    CrossPortalSimilarItem,
+    CrossPortalSimilarService,
+} from '@iptvnator/services';
+import type { NormalizedVodMeta } from '@iptvnator/shared/interfaces';
+
+/**
+ * TMDB recommendations found in the user's OTHER portals (batched DB
+ * match, Electron only). Loaded async — the section appears when
+ * resolved; staleness-guarded against item changes in flight.
+ *
+ * Registers the loading effect, so call it from a field initializer
+ * (injection context).
+ */
+export function createVodSimilarInPortals(
+    normalizedMeta: Signal<NormalizedVodMeta>,
+    crossPortalSimilar: CrossPortalSimilarService
+): Signal<CrossPortalSimilarItem[]> {
+    const matched = signal<CrossPortalSimilarItem[]>([]);
+    /** Filtered on read: a relock hides matches cached while unlocked. */
+    const visible = computed(() => crossPortalSimilar.visible(matched()));
+
+    effect(() => {
+        const meta = normalizedMeta();
+        const recommendations = meta.tmdbRecommendations;
+        untracked(() => {
+            matched.set([]);
+            if (!recommendations?.length || !crossPortalSimilar.isAvailable) {
+                return;
+            }
+            void crossPortalSimilar
+                .matchRecommendations(recommendations, 'movie')
+                .then((items) => {
+                    if (
+                        normalizedMeta().tmdbRecommendations === recommendations
+                    ) {
+                        matched.set(items);
+                    }
+                });
+        });
+    });
+
+    return visible;
+}

From 2738bc28a1335ff19f87d67c5b1bbec3881b8e85 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Sun, 4 Oct 2026 17:19:59 +0200
Subject: [PATCH 04/20] docs(portals): document forced MPV/VLC launch and
 pending-start contracts (#1809)

* docs(portals): document forced MPV/VLC launch and pending-start contracts

The rules #1792 settled for forced external launches and playback-start
bookkeeping lived only in code comments and specs. Record them as
contracts in the owning documents:

- embedded-inline-playback.md: the shared detail-host rules (one external
  player per title, unconfirmed teardown cancels, ownership rechecked
  after every await, owner-scoped pending state).
- xtream-portal-compatibility.md: the series launch chain, page-token
  duplicate guard and queued choice.
- vod-multi-source.md: the movie menu launch and reset follow the copy
  the primary button acts on; pending resets are a list of targets.
- stalker-portal.md: the per-series launch queue, the batch-held choice
  and the movie launch/reset pending start.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(portals): correct launch-contract claims against the code

- A launching session is published before the launch IPC resolves; what
  it lacks until then is an exact closer.
- The series watched/reset batch and the Xtream movie launch gate are
  page-wide, not owner-scoped.
- Only the Stalker movie hosts retire a pending start, and that does not
  clear the repeat guard of a launch still in flight.
- Name only the specs that exercise the Xtream series rules.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(portals): tighten closer timing and page-wide gate wording

A launching session may already have its closer before the launch IPC
resolves, the Xtream movie launch gate does not cover the inline
player's diagnostic fallback, and the hero-state spec covers only the
external-player and reset rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(portals): fix stale session-timing comment and search guard wording

- serial-details-external-launch.ts: Electron publishes a `launching`
  session as soon as the launch IPC arrives, not only after the launch
  settles. Comment only; no behaviour change.
- stalker-portal.md: the search host's selection check does not include
  the content type; a switch to a series supersedes the launch through
  the playback owner key instead.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/architecture/embedded-inline-playback.md | 52 +++++++++++++++
 docs/architecture/stalker-portal.md           | 63 +++++++++++++++++++
 docs/architecture/vod-multi-source.md         | 26 ++++++++
 .../xtream-portal-compatibility.md            | 37 +++++++++++
 .../serial-details-external-launch.ts         |  9 +--
 5 files changed, 183 insertions(+), 4 deletions(-)

diff --git a/docs/architecture/embedded-inline-playback.md b/docs/architecture/embedded-inline-playback.md
index d03a8e67e..dca9795c3 100644
--- a/docs/architecture/embedded-inline-playback.md
+++ b/docs/architecture/embedded-inline-playback.md
@@ -471,6 +471,58 @@ position telemetry overwrites this launch marker when available. This keeps the
 last-watched season and episode correct even when an external player's progress
 interface is unavailable; exact external timestamps remain best-effort.
 
+## Forced External Launches From Detail Pages
+
+The detail "…" menu's "Open in external player" sends the title to MPV/VLC
+through `PortalPlayer.openExternalPlayback(playback, player)` whatever the
+configured player is. The launch IPC cannot be cancelled, and until it
+resolves the session is at most `launching` and may not have a closer yet.
+Every detail host therefore keeps these rules:
+
+- **One external player per owner.** Before launching, the host closes the
+  external session the page owns: the session of the same title on the
+  Stalker pages and the Xtream series page; the session it launched, else the
+  one matching its movie, on the Xtream movie page. Sessions the page does not
+  own are left alone. With instance reuse off, a second detached player would
+  otherwise start beside the first. Stalker hosts use
+  `replaceOwnedExternalSession` from
+  `@iptvnator/portal/shared/util`; the Xtream pages use
+  `closeRunningExternalSession` with the same outcome rules.
+- **Unconfirmed teardown cancels the launch.** A live session without a
+  closer, or a close that rejects, leaves the running player in place and
+  nothing new launches.
+- **Ownership is rechecked after every await.** Stream resolution, the close
+  and the launch IPC can each outlive the page or be superseded by a newer
+  start. A stale step stops without reporting, and a launch that resolves
+  stale closes the session it just opened.
+- **No second player while a launch settles.** A repeat of the same launch is
+  ignored, or its control stays disabled. Movie pages refuse or disable every
+  other start of that title until the launch settles. Series pages hold the
+  latest episode choice and, once the launch settled, replace the player it
+  opened, only while that series is still on screen.
+- **Pending starts are owner-scoped.** A start still resolving holds the
+  actions of its own title only: another title shown by the reused page is
+  not blocked by it. Movie hosts track starts with
+  `createPendingPlaybackStart` (`@iptvnator/portal/shared/util`): only the
+  latest start may clear the flag, and `isPendingFor(owner)` answers for one
+  owner. The Stalker movie hosts, whose starts wait on a portal round trip,
+  also `retire(owner)` when the selection leaves it, so a start that never
+  settles does not keep the flag set on a return to the same title. A movie's
+  "Reset progress" is scoped the same way.
+- **Two gates are page-wide.** The Xtream movie page refuses Play, Start
+  over, source switches and the menu launch while an external launch it made
+  has not settled. A series page runs one watched or reset batch at a time,
+  whichever series is shown; the Stalker page also holds episode starts until
+  that batch settles.
+
+Owner keys and queueing are provider contracts:
+
+| Host | Contract |
+| --- | --- |
+| Xtream series | [Forced external launches from detail pages](./xtream-portal-compatibility.md#forced-external-launches-from-detail-pages) |
+| Xtream movie | [Menu launch and reset follow the primary button](./vod-multi-source.md#menu-launch-and-reset-follow-the-primary-button) |
+| Stalker series and movies | [Forced External Launches](./stalker-portal.md#forced-external-launches) |
+
 ## Series Quick Start CTA
 
 Xtream and Stalker series detail views share the quick-start decision helper in
diff --git a/docs/architecture/stalker-portal.md b/docs/architecture/stalker-portal.md
index ccc755405..8d0520070 100644
--- a/docs/architecture/stalker-portal.md
+++ b/docs/architecture/stalker-portal.md
@@ -1559,6 +1559,69 @@ Core decision logic and normalization are centralized in:
 - `libs/portal/stalker/data-access/src/lib/stalker-vod.utils.ts`
 - `libs/portal/stalker/data-access/src/lib/models/*.ts`
 
+## Forced External Launches
+
+"Open in external player" needs a `create_link` round trip before it reaches
+MPV/VLC. The shared rules are in
+[Forced External Launches From Detail Pages](./embedded-inline-playback.md#forced-external-launches-from-detail-pages);
+the Stalker keys and queues are:
+
+Series (`StalkerSeriesViewComponent`, `stalker-series-launch-queue.ts`):
+
+- Pending starts and the launch queue's held choices are keyed by
+  `playlist:series` (`currentSeriesKey`). The view is reused across series
+  and provider ids collide across playlists, so one series settling never
+  drops what another holds.
+- A start is pending for its series from the click until it settles. A forced
+  launch stays pending through the close of the previous player, the launch
+  and the release of a held choice. The pending flag disables the hero button
+  and the menu's external-player and watched rows.
+- Before launching, an episode of the same series still running externally is
+  closed (`replaceOwnedExternalSession`). The request is rechecked after that
+  close and after the launch IPC; a superseded launch closes the session it
+  opened.
+- An episode chosen while a forced launch of its series is mid-flight is held
+  (`StalkerSeriesLaunchQueue.hold`); the latest choice per series wins. On
+  release it is dropped when the series is no longer shown. Otherwise
+  `replacePlayer` closes what the launch opened before the choice starts, and
+  an unconfirmed close drops the choice.
+- An episode chosen while a watched or reset batch runs is held in one slot
+  tagged with its series; the last choice wins. When the batch settles it
+  goes through the usual gates only if that series is still shown: episode
+  identities overlap across series.
+
+Movies (`createStalkerVodDetailActions`, used by the catalog detail, the
+collection detail and search):
+
+- A repeat for the same `playlist:movie` while its launch is in flight is
+  ignored, also after leaving the movie and returning to it. Launches of
+  other movies are not held back.
+- The launch joins the host's starts (`beginPendingStart`): it supersedes an
+  earlier start, is dropped once a later one begins, and keeps Play, Start
+  over, the watched toggle and the menu rows disabled until it settles.
+- The resolved stream is discarded when the movie is no longer selected or a
+  newer start took over. Movie and series ids collide, so the catalog and
+  collection details include the content type in the selection check; in
+  search, a switch to a series changes the playback owner instead, which
+  supersedes the launch. Otherwise the movie's own external
+  session is replaced, the host's `beforeExternalLaunch` hook runs (the
+  catalog and collection details close their inline player there), and the
+  launch is sent. A launch that resolves after either condition changed
+  closes the session it opened; one that fails by then is not reported.
+- "Reset progress" counts as a pending start of the movie until the write
+  lands, so a start made meanwhile cannot resume from the row being cleared.
+- The pending start is owner-scoped (`createPendingPlaybackStart`). Each host
+  retires it when the selection leaves the owner; that clears the pending
+  flag, not the repeat guard of a launch still in flight.
+
+Regression coverage: `stalker-series-launch-queue.spec.ts`,
+`stalker-series-view.component.spec.ts`,
+`stalker-series-view.season-watch.spec.ts`,
+`stalker-vod-detail-actions.spec.ts`,
+`stalker-vod-playback-controller.spec.ts` and, in
+`libs/portal/shared/util/src/lib/`, `pending-playback-start.spec.ts` and
+`replace-owned-external-session.spec.ts`.
+
 ## Favorites and Recently Viewed
 
 Current implementation is shared via Stalker-specific helpers:
diff --git a/docs/architecture/vod-multi-source.md b/docs/architecture/vod-multi-source.md
index ebd6e1cd2..11c13119b 100644
--- a/docs/architecture/vod-multi-source.md
+++ b/docs/architecture/vod-multi-source.md
@@ -757,6 +757,32 @@ lookup comes back empty, because "never watched" is an answer: the button must
 read Play, not `Resume 42:18` on a stream that starts at zero. A pin on the
 route's own row changes nothing; the loaded position already IS that copy's.
 
+## Menu launch and reset follow the primary button
+
+The "…" menu acts on the copy the primary button acts on. The shared launch
+rules are in
+[Forced External Launches From Detail Pages](./embedded-inline-playback.md#forced-external-launches-from-detail-pages).
+
+- "Open in external player" and "Start over" are host-owned
+  (`VodDetailsMenuBindings.openExternal` / `restart`); the menu service never
+  builds a playback itself. The route forces MPV/VLC for the pinned copy from
+  that copy's own resume point (`playPinnedSource` with `player` and
+  `replacePlaying`), also while that copy already plays: it is relaunched,
+  never swapped for the route copy. Only an `unavailable` pin falls through
+  to the route copy's Resume or Play.
+- "Reset progress" clears the row of `primaryTarget`: the pinned copy's own
+  row, otherwise the route copy's.
+- Resets in flight are a list of targets
+  (`VodDetailsPlaybackService.pendingResets`, `vod-details-reset-target.ts`),
+  not one flag: the reused page can show another movie and come back, and
+  resets of one copy can overlap, so each reset removes only its own entry.
+- A start is refused (`startResolvedPlayback`) while a launch this page made
+  has not settled or the list holds the copy the page currently acts on
+  (`resetTarget`). `startBlocked` disables Play, Start over and the menu
+  launch on those conditions and while a matched session is still
+  `launching`; the menu rows are also held while a start is pending. A reset
+  still writing for another copy does not block it.
+
 ## Provider codec metadata
 
 `info.video` / `info.audio` come back in two shapes: the declared string array
diff --git a/docs/architecture/xtream-portal-compatibility.md b/docs/architecture/xtream-portal-compatibility.md
index 6545321e0..bf3fb37da 100644
--- a/docs/architecture/xtream-portal-compatibility.md
+++ b/docs/architecture/xtream-portal-compatibility.md
@@ -405,3 +405,40 @@ deduplicated list, `hasMoreContent` derives from accumulated length vs
 and the facade maps page 0 to the skeleton and later pages to the tail
 spinner. These catalog/search surfaces use incremental loading instead of
 page buttons.
+
+## Forced external launches from detail pages
+
+The "…" menu's MPV/VLC launch follows the shared rules in
+[Forced External Launches From Detail Pages](./embedded-inline-playback.md#forced-external-launches-from-detail-pages).
+The movie page's pin and reset rules are in
+[VOD Multi-Source](./vod-multi-source.md#menu-launch-and-reset-follow-the-primary-button).
+
+The series page keeps its launch state at module level in
+`serial-details-external-launch.ts`, so it outlives a recreated page:
+
+- The owner is `playlist:series` (`launchOwner()`). It changes when the page
+  shows another series and is null once the page is gone.
+- Forced launches of one owner run on one chain. A later launch waits for the
+  earlier one to settle, closes the owner's running episode session and then
+  launches. Each step rechecks the owner, and a launch that resolves after the
+  page left the owner closes the session it opened.
+- The duplicate guard is keyed by page token plus episode. The token
+  (`pageToken()`) is owner, page instance and visit, so a launch left behind
+  by an earlier visit of the same series does not swallow a launch from the
+  reopened page; that launch queues on the owner's chain.
+- While a forced launch of the owner is pending (`forcedLaunchPending`), a
+  start that does not force a player is queued instead of started. One choice
+  is kept per owner, the latest wins, and it carries the host and `start` of
+  the page that made it. Once the chain settles, the player the launch opened
+  is closed first while the owner stays pending. The choice is dropped when
+  that page no longer shows the owner or the close was not confirmed.
+- The pending flag also disables the menu's external-player row and the
+  season and series watched actions, and counts as active playback for "Reset
+  progress".
+- The launch-position marker and a launch-failure message apply only while
+  the page token is unchanged.
+
+Regression coverage: `serial-details-external-launch.spec.ts` (chain,
+duplicate guard, queued choice), `serial-details-playback.service.spec.ts`
+(page token) and, for the external-player and reset rows,
+`libs/ui/components/src/lib/detail-ui/series-hero.state.spec.ts`.
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-external-launch.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-external-launch.ts
index 1b7b16a75..699069e5b 100644
--- a/libs/portal/xtream/feature/src/lib/serial-details/serial-details-external-launch.ts
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details-external-launch.ts
@@ -198,10 +198,11 @@ function closeOwnedEpisodeSession(
  * still running externally is closed first: with instance reuse off a
  * second detached player would start beside it. When that close fails, or
  * the user moved on while it ran, the running player stays and nothing new
- * launches. A repeat of the same episode before its launch settled
- * (Electron publishes the session only afterwards) is ignored; another
- * episode of the series waits for that launch to settle and then replaces
- * it like any later start.
+ * launches. A repeat of the same episode before its launch settled is
+ * ignored (the session cannot stand in for this guard: Electron publishes
+ * it only once the launch IPC arrives, as `launching` until that resolves);
+ * another episode of the series waits for that launch to settle and then
+ * replaces it like any later start.
  */
 export async function openEpisodeExternally(
     host: SeriesExternalLaunchHost,

From b782243760e1af876d824ff5acb9306a93df2df4 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Mon, 5 Oct 2026 22:55:58 +0200
Subject: [PATCH 05/20] test(performance): skip every test-only file suffix in
 the zoneless guard (#1831)

* test(performance): skip every test-only file suffix in the zoneless guard

#1813 added serial-details.test-stubs.ts, whose stub components set
ChangeDetectionStrategy.Eager. The zoneless checklist guard listed only
some test-only suffixes, counted the stub file as production code and has
failed the performance-harness job on master since. It now skips every
`.spec` / `.test` file with or without a suffix, test-setup.ts and
test-stubs/ directories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(performance): accept multi-segment test-only suffixes in the zoneless guard

Review follow-up (Greptile): `(-\w+)?` allowed one suffix segment, so a
file such as `rail.test-data-stubs.ts` would be scanned as production.
The suffix now repeats, and a classifier test pins which names are
skipped and which ship.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../performance/zoneless-migration.spec.ts    | 34 +++++++++++++++++--
 docs/architecture/zoneless-migration.md       |  7 ++--
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
index c326c4a92..f9a67c9d7 100644
--- a/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
@@ -12,9 +12,16 @@ import { fileURLToPath } from 'node:url';
 const workspaceRoot = fileURLToPath(new URL('../../../../', import.meta.url));
 const checklistPath = 'docs/architecture/zoneless-migration.md';
 const sourceRoots = ['apps', 'libs'];
-const skippedDirectories = new Set(['node_modules', 'dist', 'coverage']);
-const testOnlyFile =
-    /(\.spec|\.spec-stubs|\.spec-data|\.test-helpers|test-setup)\.ts$/;
+const skippedDirectories = new Set([
+    'node_modules',
+    'dist',
+    'coverage',
+    'test-stubs',
+]);
+// Test-only files follow the repository's `.spec` / `.test` naming, with an
+// optional suffix of one or more segments (`.spec-stubs.ts`,
+// `.test-helpers.ts`, `.test-data-stubs.ts`).
+const testOnlyFile = /(\.(spec|test)(-\w+)*|^test-setup)\.ts$/;
 
 function listProductionSources(directory: string): string[] {
     const files: string[] = [];
@@ -78,6 +85,27 @@ test('the zoneless checklist lists exactly the components that are still Eager',
     );
 });
 
+test('the guard skips test-only file names and keeps production ones', () => {
+    for (const name of [
+        'player.component.spec.ts',
+        'serial-details.test-stubs.ts',
+        'dashboard.spec-stubs.ts',
+        'rail.test-data-stubs.ts',
+        'test-setup.ts',
+    ]) {
+        assert.ok(testOnlyFile.test(name), `${name} is test-only`);
+    }
+    for (const name of [
+        'player.component.ts',
+        'spec-utils.ts',
+        'contest.ts',
+        'latest-setup.ts',
+        'testing.service.ts',
+    ]) {
+        assert.ok(!testOnlyFile.test(name), `${name} ships`);
+    }
+});
+
 test('ticked checklist entries name files that exist', () => {
     for (const file of readEagerChecklist().done) {
         assert.ok(sources.has(file), `${file} is ticked but does not exist`);
diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 630d51ff2..84fdb1ede 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -153,8 +153,11 @@ files that still contain `ChangeDetectionStrategy.Eager`.
 - [ ] `libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts`
 - [ ] `libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts`
 
-Test stubs that set Eager (`*.spec.ts`, `*.spec-stubs.ts`, `*.spec-data.ts`,
-`*.test-helpers.ts`) are not listed; they do not ship.
+Test-only files that set Eager are not listed; they do not ship. The guard
+skips every `*.spec.ts` / `*.test.ts` file with or without a suffix of one
+or more segments (`*.spec-stubs.ts`, `*.test-helpers.ts`,
+`*.test-data-stubs.ts`, …),
+`test-setup.ts` and `test-stubs/` directories.
 
 ## Zone-dependent sites
 

From b315f8564d80a604f2bfdea76aaa9ef482585768 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 10:34:08 +0200
Subject: [PATCH 06/20] fix(electron): show the main window once its document
 has loaded; enforce J1 IPC and mutation counters (#1828)

* fix(electron): show the main window once its document has loaded; enforce J1 IPC and mutation counters

Re-lands #1788, which merged into #1782's branch after #1782 had already
reached master, so none of it is on master.

The hidden main window was shown on ready-to-show only. On Linux under
X11, when the startup scripts run before the window's first frame, the
next frame comes about a second later: nothing is on screen and the
splash's requestAnimationFrame waits, so J1's first card came ~940 ms
after load instead of ~480 ms in most runner launches (18 bridge calls /
1,031-1,033 DOM mutations instead of 15 / 558).

The window is now shown at ready-to-show or the main frame's
did-finish-load, whichever comes first, with the splash colour as its
background so showing before the first paint does not flash. The journey
gate keeps the app's did-finish-load listeners away from its about:blank
detour, as it already does for ready-to-show.

Three dispatched runs on this branch (37192092882, 37192097790,
37192103151) read 15 calls and 558 mutations in all 18 iterations,
stable: true. Both become baselines (slack 0), and the Performance
journeys job checks them with check-journey-ratchet.mjs --only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(perf): record the evidence PR of the J1 runtime baselines

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: 4gray <fourgray@proton.me>
---
 .changes/electron-window-shown-on-load.md     |   8 +
 .github/workflows/ci.yml                      |  15 ++
 .../journeys/journey-renderer-gate-client.ts  |   2 +
 .../journey-renderer-gate-client.spec.ts      |   1 +
 .../src/performance/journey-renderer-gate.cjs |  39 +++++
 .../performance/journey-renderer-gate.spec.ts |  46 +++++-
 .../performance/launch-journey-record.spec.ts |   2 +
 .../src/performance/launch-journey-record.ts  |   2 +
 .../src/window-visibility.e2e.ts              |   5 +-
 apps/electron-backend/src/app/app.spec.ts     |  33 ++++
 apps/electron-backend/src/app/app.ts          |  25 ++-
 .../services/main-window-first-show.spec.ts   |  71 +++++++++
 .../app/services/main-window-first-show.ts    |  52 ++++++
 docs/architecture/performance-journeys.md     | 149 +++++++++++++++---
 docs/architecture/validation-map.md           |   5 +-
 docs/architecture/workspace-shell.md          |  17 +-
 tools/performance/journey-baselines.json      |  18 +++
 17 files changed, 451 insertions(+), 39 deletions(-)
 create mode 100644 .changes/electron-window-shown-on-load.md
 create mode 100644 apps/electron-backend/src/app/services/main-window-first-show.spec.ts
 create mode 100644 apps/electron-backend/src/app/services/main-window-first-show.ts

diff --git a/.changes/electron-window-shown-on-load.md b/.changes/electron-window-shown-on-load.md
new file mode 100644
index 000000000..49dc2ef01
--- /dev/null
+++ b/.changes/electron-window-shown-on-load.md
@@ -0,0 +1,8 @@
+---
+type: perf
+area: electron
+---
+
+On Linux the desktop app's window no longer sometimes appears about a second
+late at launch: it now opens as soon as the app has loaded, showing the
+loading screen until the dashboard is ready.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 967d2f03a..e1a028afb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -324,8 +324,23 @@ jobs:
             # Electron dependency check, the xvfb run, the summary lookup and
             # the job-summary report; shared with performance-ratchet.yml.
             - name: Run the performance journeys
+              id: journeys
               uses: ./.github/actions/performance-journeys
 
+            # Only the J1 counters shown deterministic on this runner; the
+            # other journey measurements stay evidence (see Ratchet in
+            # docs/architecture/performance-journeys.md). Here and not in
+            # the composite action, so the weekly tightening still measures
+            # a run that would fail it.
+            - name: Check the J1 runtime counters against the baselines
+              env:
+                  SUMMARY: ${{ steps.journeys.outputs.summary }}
+              run: >-
+                  node tools/performance/check-journey-ratchet.mjs
+                  --summary "$SUMMARY"
+                  --only launch/renderer.ipcCallsToFirstCard
+                  --only launch/renderer.domMutationsToFirstCard
+
             - name: Upload journey summaries
               if: always()
               uses: actions/upload-artifact@v7
diff --git a/apps/electron-backend-e2e/src/journeys/journey-renderer-gate-client.ts b/apps/electron-backend-e2e/src/journeys/journey-renderer-gate-client.ts
index 91387fc9d..61c0b2957 100644
--- a/apps/electron-backend-e2e/src/journeys/journey-renderer-gate-client.ts
+++ b/apps/electron-backend-e2e/src/journeys/journey-renderer-gate-client.ts
@@ -12,6 +12,8 @@ export interface JourneyRendererGateState {
     readonly gatedEpochMs: number | null;
     readonly gatedMethod: string | null;
     readonly passThroughLoads: number;
+    /** `did-finish-load` events kept from the app's listeners on about:blank. */
+    readonly didFinishLoadHeldOnBlank: number;
     /** `ready-to-show` events dropped while the window was on about:blank. */
     readonly readyToShowHeldOnBlank: number;
     readonly releasedEpochMs: number | null;
diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-gate-client.spec.ts b/apps/electron-backend-e2e/src/performance/journey-renderer-gate-client.spec.ts
index e203d4540..2cbae397d 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-gate-client.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-gate-client.spec.ts
@@ -14,6 +14,7 @@ function gate(
         blankLoadedEpochMs: 1_050,
         errors: [],
         gatedEpochMs: 1_020,
+        didFinishLoadHeldOnBlank: 1,
         gatedMethod: 'loadFile',
         passThroughLoads: 0,
         readyToShowHeldOnBlank: 1,
diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-gate.cjs b/apps/electron-backend-e2e/src/performance/journey-renderer-gate.cjs
index be80ae151..baca328c4 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-gate.cjs
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-gate.cjs
@@ -22,6 +22,11 @@
  * therefore drops `ready-to-show` while the window is on `about:blank`;
  * Electron emits it again for the real document's first paint, because the
  * window is still hidden, which is the moment production sees.
+ * The app also shows its window at the main frame's `did-finish-load`
+ * when that comes first, so the gate keeps the app's `did-finish-load`
+ * listeners (those registered before the gated load) away from the
+ * about:blank load too. Electron's own listener that resolves
+ * `loadURL(about:blank)` is registered later and still runs.
  *
  * With `ipcMain` passed in, the gate also keeps the listeners registered
  * with `ipcMain.handle` for `TAPPED_IPC_CHANNELS`, so the test can call a
@@ -53,6 +58,38 @@ function holdReadyToShowWhileBlank(window, state) {
     };
 }
 
+function holdDidFinishLoadWhileBlank(window, state) {
+    const contents = window.webContents;
+    if (
+        !contents ||
+        typeof contents.emit !== 'function' ||
+        typeof contents.rawListeners !== 'function'
+    ) {
+        return;
+    }
+    const appListeners = contents.rawListeners('did-finish-load');
+    const originalEmit = contents.emit;
+    contents.emit = function gatedContentsEmit(eventName, ...args) {
+        if (eventName !== 'did-finish-load' || !isShowingBlank(window)) {
+            return originalEmit.call(this, eventName, ...args);
+        }
+        state.didFinishLoadHeldOnBlank += 1;
+        const attached = this.rawListeners(eventName);
+        const held = appListeners.filter((listener) =>
+            attached.includes(listener)
+        );
+        for (const listener of held) this.removeListener(eventName, listener);
+        try {
+            return originalEmit.call(this, eventName, ...args);
+        } finally {
+            // Raw listeners keep their `once` wrappers, so a re-added once
+            // listener still fires once for the real document.
+            for (const listener of held)
+                this.prependListener(eventName, listener);
+        }
+    };
+}
+
 function tapIpcHandlers(ipcMain, channels) {
     const handlers = new Map();
     const originalHandle = ipcMain.handle;
@@ -78,6 +115,7 @@ function installJourneyRendererGate(BrowserWindow, target, options = {}) {
         errors: [],
         gatedEpochMs: null,
         gatedMethod: null,
+        didFinishLoadHeldOnBlank: 0,
         passThroughLoads: 0,
         readyToShowHeldOnBlank: 0,
         releasedEpochMs: null,
@@ -128,6 +166,7 @@ function installJourneyRendererGate(BrowserWindow, target, options = {}) {
             state.gatedEpochMs = now();
             state.gatedMethod = method;
             holdReadyToShowWhileBlank(this, state);
+            holdDidFinishLoadWhileBlank(this, state);
             try {
                 await this.webContents.loadURL(BLANK_URL);
                 state.blankLoadedEpochMs = now();
diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-gate.spec.ts b/apps/electron-backend-e2e/src/performance/journey-renderer-gate.spec.ts
index a6e44978d..8eb336dee 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-gate.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-gate.spec.ts
@@ -4,6 +4,7 @@ import test from 'node:test';
 
 interface GateState {
     blankLoadedEpochMs: number | null;
+    didFinishLoadHeldOnBlank: number;
     errors: string[];
     gatedEpochMs: number | null;
     gatedMethod: string | null;
@@ -155,13 +156,13 @@ test('records a failed about:blank navigation and still loads after release', as
 function createEmittingBrowserWindow(log: string[]) {
     class EmittingBrowserWindow extends EventEmitter {
         url = '';
-        webContents = {
+        webContents = Object.assign(new EventEmitter(), {
             getURL: () => this.url,
             loadURL: async (url: string) => {
                 this.url = url;
                 log.push(`webContents.loadURL:${url}`);
             },
-        };
+        });
         async loadFile(file: string): Promise<void> {
             this.url = `file:///${file}`;
             log.push(`loadFile:${file}`);
@@ -201,6 +202,47 @@ test('holds ready-to-show while the window shows about:blank, then lets the real
     assert.equal(api.state.readyToShowHeldOnBlank, 1);
 });
 
+test('keeps did-finish-load of about:blank from the app listeners, not from later ones', async () => {
+    const log: string[] = [];
+    const EmittingBrowserWindow = createEmittingBrowserWindow(log);
+    const api = gateModule.installJourneyRendererGate(
+        EmittingBrowserWindow as unknown as {
+            prototype: Record<string, unknown>;
+        },
+        {},
+        { timeoutMs: 60_000 }
+    );
+    const window = new EmittingBrowserWindow();
+    // The app shows its window at the first did-finish-load.
+    window.webContents.once('did-finish-load', () =>
+        log.push('app:did-finish-load')
+    );
+    const load = window.loadFile('index.html');
+    await settle();
+    // Registered after the gated load, like Electron's own listener that
+    // resolves loadURL(about:blank).
+    window.webContents.on('did-finish-load', () =>
+        log.push('electron:did-finish-load')
+    );
+    window.webContents.emit('did-finish-load');
+    assert.equal(api.state.didFinishLoadHeldOnBlank, 1);
+
+    api.release();
+    await load;
+    window.webContents.emit('did-finish-load');
+    window.webContents.emit('did-finish-load');
+
+    assert.deepEqual(log, [
+        'webContents.loadURL:about:blank',
+        'electron:did-finish-load',
+        'loadFile:index.html',
+        'app:did-finish-load',
+        'electron:did-finish-load',
+        'electron:did-finish-load',
+    ]);
+    assert.equal(api.state.didFinishLoadHeldOnBlank, 1);
+});
+
 test('taps ipcMain.handle for the counters channel and passes registrations through', async () => {
     const registered: string[] = [];
     const ipcMain: FakeIpcMain = {
diff --git a/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts b/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
index 02bfe3d21..f2084d099 100644
--- a/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
@@ -112,6 +112,7 @@ function measurement(
             blankLoadedEpochMs: 1_050,
             errors: [],
             gatedEpochMs: 1_020,
+            didFinishLoadHeldOnBlank: 1,
             gatedMethod: 'loadFile',
             passThroughLoads: 0,
             readyToShowHeldOnBlank: 1,
@@ -185,6 +186,7 @@ test('maps the probe, IPC capture and main counters to exact counters and spawn-
         'main.startupPhases': 9,
     });
     assert.equal(record.evidence['rendererGateReadyToShowHeldOnBlank'], 1);
+    assert.equal(record.evidence['rendererGateDidFinishLoadHeldOnBlank'], 1);
     assert.deepEqual(record.evidence['epochs'], {
         firstCard: 2_600.04,
         firstCardPaint: 2_650,
diff --git a/apps/electron-backend-e2e/src/performance/launch-journey-record.ts b/apps/electron-backend-e2e/src/performance/launch-journey-record.ts
index 2349648fe..f0ec0b053 100644
--- a/apps/electron-backend-e2e/src/performance/launch-journey-record.ts
+++ b/apps/electron-backend-e2e/src/performance/launch-journey-record.ts
@@ -185,6 +185,8 @@ export function toLaunchIterationRecord(
             mainCountersAtRead: mainCounters.counters,
             rendererGateReadyToShowHeldOnBlank:
                 measurement.gate.readyToShowHeldOnBlank,
+            rendererGateDidFinishLoadHeldOnBlank:
+                measurement.gate.didFinishLoadHeldOnBlank,
             ipcCallsByMethod: ipc.callsByMethod,
             ipcSerialDepth: serialDepth,
             ipcTimelineAmbiguousCompletions: ipc.ambiguousTimelineCompletions,
diff --git a/apps/electron-backend-e2e/src/window-visibility.e2e.ts b/apps/electron-backend-e2e/src/window-visibility.e2e.ts
index ae323c541..777101efd 100644
--- a/apps/electron-backend-e2e/src/window-visibility.e2e.ts
+++ b/apps/electron-backend-e2e/src/window-visibility.e2e.ts
@@ -27,8 +27,9 @@ const setWindowState = (
     );
 
 /**
- * The app creates its window with `show: false` and shows it on
- * `ready-to-show`; a `hide()` sent earlier would be undone by that `show()`.
+ * The app creates its window with `show: false` and shows it at
+ * `ready-to-show` or `did-finish-load`, whichever comes first; a `hide()`
+ * sent earlier would be undone by that `show()`.
  */
 async function waitUntilShown(app: UnautomatedElectronApp): Promise<void> {
     await expect
diff --git a/apps/electron-backend/src/app/app.spec.ts b/apps/electron-backend/src/app/app.spec.ts
index 7e597144d..f8f12e5bd 100644
--- a/apps/electron-backend/src/app/app.spec.ts
+++ b/apps/electron-backend/src/app/app.spec.ts
@@ -75,11 +75,14 @@ type MockMainWindow = {
     maximize: jest.Mock<void, []>;
     on: jest.Mock<void, [string, (...args: unknown[]) => void]>;
     once: jest.Mock<void, [string, (...args: unknown[]) => void]>;
+    removeListener: jest.Mock<void, [string, (...args: unknown[]) => void]>;
     setFullScreen: jest.Mock<void, [boolean]>;
     setMenu: jest.Mock<void, [unknown]>;
     show: jest.Mock<void, []>;
     webContents: {
         on: jest.Mock<void, [string, (...args: unknown[]) => void]>;
+        once: jest.Mock<void, [string, (...args: unknown[]) => void]>;
+        removeListener: jest.Mock<void, [string, (...args: unknown[]) => void]>;
         openDevTools: jest.Mock<void, []>;
         setWindowOpenHandler: jest.Mock<void, [unknown]>;
         getZoomLevel: jest.Mock<number, []>;
@@ -98,12 +101,18 @@ function createMockMainWindow(): MockMainWindow {
         maximize: jest.fn<void, []>(),
         on: jest.fn<void, [string, (...args: unknown[]) => void]>(),
         once: jest.fn<void, [string, (...args: unknown[]) => void]>(),
+        removeListener: jest.fn<void, [string, (...args: unknown[]) => void]>(),
         isDestroyed: jest.fn<boolean, []>().mockReturnValue(false),
         setFullScreen: jest.fn<void, [boolean]>(),
         setMenu: jest.fn<void, [unknown]>(),
         show: jest.fn<void, []>(),
         webContents: {
             on: jest.fn<void, [string, (...args: unknown[]) => void]>(),
+            once: jest.fn<void, [string, (...args: unknown[]) => void]>(),
+            removeListener: jest.fn<
+                void,
+                [string, (...args: unknown[]) => void]
+            >(),
             openDevTools: jest.fn<void, []>(),
             setWindowOpenHandler: jest.fn<void, [unknown]>(),
             getZoomLevel: jest.fn<number, []>().mockReturnValue(0),
@@ -366,6 +375,30 @@ describe('Electron app security helpers', () => {
             expect(mainWindow.show).toHaveBeenCalledTimes(1);
         });
 
+        it('shows the window at did-finish-load when ready-to-show has not come yet', () => {
+            storeStartupWindowMode('maximized');
+            const mainWindow = createWindowViaOnReady();
+
+            expect(BrowserWindow).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    show: false,
+                    backgroundColor: '#1f1f23',
+                })
+            );
+            const [loadHandler] = mainWindow.webContents.once.mock.calls
+                .filter(([eventName]) => eventName === 'did-finish-load')
+                .map(([, handler]) => handler);
+            loadHandler();
+
+            expect(mainWindow.maximize).toHaveBeenCalledTimes(1);
+            expect(mainWindow.show).toHaveBeenCalledTimes(1);
+
+            // The later ready-to-show is a no-op.
+            fireReadyToShow(mainWindow);
+            expect(mainWindow.show).toHaveBeenCalledTimes(1);
+            expect(mainWindow.maximize).toHaveBeenCalledTimes(1);
+        });
+
         it('creates the window fullscreen when the stored mode says so', () => {
             storeStartupWindowMode('fullscreen');
 
diff --git a/apps/electron-backend/src/app/app.ts b/apps/electron-backend/src/app/app.ts
index 09b927e6c..0573c4bba 100644
--- a/apps/electron-backend/src/app/app.ts
+++ b/apps/electron-backend/src/app/app.ts
@@ -15,6 +15,10 @@ import {
     trace,
     traceStartupPhase,
 } from './services/debug-trace';
+import {
+    MAIN_WINDOW_BACKGROUND_COLOR,
+    showMainWindowWhenLoaded,
+} from './services/main-window-first-show';
 import { attachMainWindowPerformanceCounters } from './services/performance-counters';
 import {
     STARTUP_WINDOW_MODE,
@@ -512,6 +516,9 @@ export default class App {
             width: width,
             height: height,
             show: false,
+            // The splash colour: the window can be shown before its first
+            // paint (main-window-first-show.ts).
+            backgroundColor: MAIN_WINDOW_BACKGROUND_COLOR,
             webPreferences: getMainWindowWebPreferences(),
             ...savedWindowBounds,
             // Fullscreen is a constructor option: the window is created
@@ -543,15 +550,17 @@ export default class App {
             App.mainWindow.center();
         }
 
-        // if main window is ready to show, close the splash window and show the main window
-        App.mainWindow.once('ready-to-show', () => {
+        // Shown at ready-to-show or did-finish-load, whichever comes first
+        // (see main-window-first-show.ts).
+        const mainWindow = App.mainWindow;
+        showMainWindowWhenLoaded(mainWindow, () => {
             // maximize() on a hidden window shows it (Electron docs), so it
-            // has to wait for ready-to-show like show() does — any earlier
-            // and a blank window flashes before the renderer paints.
+            // waits for the document like show() does — any earlier and a
+            // blank window flashes before the splash is there.
             if (startupWindowMode === 'maximized') {
-                App.mainWindow.maximize();
+                mainWindow.maximize();
             }
-            App.mainWindow.show();
+            mainWindow.show();
             // macOS ignores the constructor's `fullscreen` while the window
             // is hidden — an NSWindow can only toggle fullscreen once it is
             // on screen — so the request is repeated after show() wherever
@@ -562,9 +571,9 @@ export default class App {
             // asking for it again.
             if (
                 startupWindowMode === 'fullscreen' &&
-                !App.mainWindow.isFullScreen()
+                !mainWindow.isFullScreen()
             ) {
-                requestFullScreen(App.mainWindow, true);
+                requestFullScreen(mainWindow, true);
             }
         });
 
diff --git a/apps/electron-backend/src/app/services/main-window-first-show.spec.ts b/apps/electron-backend/src/app/services/main-window-first-show.spec.ts
new file mode 100644
index 000000000..9ce24d815
--- /dev/null
+++ b/apps/electron-backend/src/app/services/main-window-first-show.spec.ts
@@ -0,0 +1,71 @@
+import { EventEmitter } from 'events';
+import {
+    type FirstShowWindow,
+    showMainWindowWhenLoaded,
+} from './main-window-first-show';
+
+function createWindow(): FirstShowWindow &
+    EventEmitter & {
+        webContents: EventEmitter;
+        destroyed: boolean;
+    } {
+    const window = Object.assign(new EventEmitter(), {
+        destroyed: false,
+        webContents: new EventEmitter(),
+        isDestroyed(): boolean {
+            return window.destroyed;
+        },
+    });
+    return window;
+}
+
+describe('showMainWindowWhenLoaded', () => {
+    it('shows the window at did-finish-load when ready-to-show has not fired', () => {
+        // The Linux race: the hidden window gets no frame for its first
+        // paint, so ready-to-show (and the splash's animation frame) would
+        // wait about a second after the document has loaded.
+        const window = createWindow();
+        const show = jest.fn();
+        showMainWindowWhenLoaded(window, show);
+
+        window.webContents.emit('did-finish-load');
+
+        expect(show).toHaveBeenCalledTimes(1);
+    });
+
+    it('shows the window at ready-to-show when that comes first', () => {
+        const window = createWindow();
+        const show = jest.fn();
+        showMainWindowWhenLoaded(window, show);
+
+        window.emit('ready-to-show');
+
+        expect(show).toHaveBeenCalledTimes(1);
+    });
+
+    it('shows the window only once and detaches the other listener', () => {
+        const window = createWindow();
+        const show = jest.fn();
+        showMainWindowWhenLoaded(window, show);
+
+        window.webContents.emit('did-finish-load');
+        window.emit('ready-to-show');
+        // A reload loads the document again; the window is already shown.
+        window.webContents.emit('did-finish-load');
+
+        expect(show).toHaveBeenCalledTimes(1);
+        expect(window.listenerCount('ready-to-show')).toBe(0);
+        expect(window.webContents.listenerCount('did-finish-load')).toBe(0);
+    });
+
+    it('does not show a window that was destroyed before it loaded', () => {
+        const window = createWindow();
+        const show = jest.fn();
+        showMainWindowWhenLoaded(window, show);
+
+        window.destroyed = true;
+        window.emit('ready-to-show');
+
+        expect(show).not.toHaveBeenCalled();
+    });
+});
diff --git a/apps/electron-backend/src/app/services/main-window-first-show.ts b/apps/electron-backend/src/app/services/main-window-first-show.ts
new file mode 100644
index 000000000..b7c0ff38d
--- /dev/null
+++ b/apps/electron-backend/src/app/services/main-window-first-show.ts
@@ -0,0 +1,52 @@
+/**
+ * When the hidden main window is first shown.
+ *
+ * The window is created with `show: false` and used to be shown on
+ * `ready-to-show` only. That event needs the window's first visually
+ * non-empty paint, and a hidden window does not always get a frame for it:
+ * on Linux under X11, when the startup scripts run before that frame, the
+ * next one comes about a second later. Until then nothing is on screen and
+ * the renderer gets no animation frames, so the splash that `main.ts`
+ * removes in a `requestAnimationFrame` stays even after the dashboard has
+ * rendered (J1 on the CI runner: about 450 ms later to the first card, in
+ * roughly one launch out of three, see docs/architecture/performance-journeys.md).
+ *
+ * The window is therefore shown at whichever comes first: `ready-to-show`
+ * or the main frame's `did-finish-load`. At `did-finish-load` the inline
+ * splash is parsed and styled, and the window's `backgroundColor` matches
+ * it, so showing before the first paint does not flash.
+ */
+
+/** Matches `#initial-splash` in `apps/web/src/index.html`. */
+export const MAIN_WINDOW_BACKGROUND_COLOR = '#1f1f23';
+
+type OnceEmitter = {
+    once(event: string, listener: () => void): unknown;
+    removeListener(event: string, listener: () => void): unknown;
+};
+
+export type FirstShowWindow = OnceEmitter & {
+    isDestroyed(): boolean;
+    readonly webContents: OnceEmitter;
+};
+
+/** Calls `show` once, at `ready-to-show` or `did-finish-load`, whichever comes first. */
+export function showMainWindowWhenLoaded(
+    window: FirstShowWindow,
+    show: () => void
+): void {
+    let shown = false;
+    const showOnce = (): void => {
+        if (shown) {
+            return;
+        }
+        shown = true;
+        window.removeListener('ready-to-show', showOnce);
+        window.webContents.removeListener('did-finish-load', showOnce);
+        if (!window.isDestroyed()) {
+            show();
+        }
+    };
+    window.once('ready-to-show', showOnce);
+    window.webContents.once('did-finish-load', showOnce);
+}
diff --git a/docs/architecture/performance-journeys.md b/docs/architecture/performance-journeys.md
index 25ab024cf..984ec766a 100644
--- a/docs/architecture/performance-journeys.md
+++ b/docs/architecture/performance-journeys.md
@@ -89,7 +89,14 @@ main-process counters below, which exist only with `IPTVNATOR_PERF_CAPTURE=1`:
   show a blank window and freeze its `ready-to-show` counter before its own
   document exists. Electron emits the event again for the real document's
   first paint because the window is still hidden, which is the moment
-  production sees. The gate also keeps the listener the app registers with
+  production sees. The app also shows its window at the main frame's
+  `did-finish-load` when that comes first (see
+  [When the window is shown](#when-the-window-is-shown)), so the gate keeps
+  the `did-finish-load` listeners registered before the gated load (the
+  app's) away from the `about:blank` load as well
+  (`evidence.rendererGateDidFinishLoadHeldOnBlank`, 1 per launch); Electron's
+  own listener that resolves `loadURL('about:blank')` is registered later
+  and still runs. The gate also keeps the listener the app registers with
   `ipcMain.handle('performance:read-counters')`, so the test can call it from
   the main process.
 - `journey-renderer-probe.ts` is registered with `addInitScript` on that
@@ -199,6 +206,12 @@ the playlist inventory has loaded. After the fix (macOS, 2026-09-30): both
 counters were 0 in all 12 iterations of two runs, every window closed on
 `quiet` and `lateShifts` was empty.
 
+On the runner the flicker was only visible on J1's fast path: on the slow
+path the window got its first frame only after the hero had already
+changed, so the settle window opened after the shifts (see
+[When the window is shown](#when-the-window-is-shown)). With both fixes,
+all 18 iterations of three runner runs read 0 (`stable: true`).
+
 #### Idle window
 
 After the settle point J1 leaves the dashboard alone for
@@ -469,6 +482,76 @@ waits for the playlist migrations, the inventory read and
 `reconcileEpgSources`. No baseline yet: the counter is promoted only after a
 PR that lowers it also lowers `spawnToFirstCardMs` (Principle 3).
 
+### When the window is shown
+
+J1 on the CI runner was bimodal from the first runner measurements (#1717)
+until 2026-10-01: 6 of 14 `master` runs between 2026-09-30 and 2026-10-01
+mixed two paths. On the slow path the first card came with 18 bridge
+calls and 1,018 DOM mutations, about 940 ms after the load event. On the
+fast path it came with 15 calls and 559 mutations, 280-500 ms after it.
+The race also marked `renderer.ipcSerialDepthToFirstCard` (9 vs 6),
+`renderer.cdTicksToFirstCard` (31 vs 21), `renderer.cdTicksIdle30s`,
+`main.sqlStatementsBeforeReadyToShow` (119 vs 93) and
+`renderer.layoutShiftScoreSettled` as `stable: false`.
+
+The three extra calls (`downloadsGetDefaultFolder` and two
+`dbGetGlobalRecentlyAdded`, after `dbGetAllGlobalFavorites`) were not what
+the card waited for. They only had time to finish before the card. What
+ordered the card was when the hidden window got a frame. In every one of
+the 48 iterations of those eight runs (two of them #1782's), `ready-to-show`
+came within 180 ms of the load event on the fast path (usually about 15 ms),
+and 4-5 ms after the first card on the slow path. The app showed its window only on
+`ready-to-show`, and `main.ts` removes the splash in a
+`requestAnimationFrame`, which the journey's end condition waits for. On
+the slow path the dashboard had rendered and its data had arrived, but the
+window was still hidden, no frame came, and the splash stayed.
+
+A minimal Electron 43.3.0 app under Xvfb in a Debian container reproduces
+it deterministically. It has the same hidden window, splash and
+`requestAnimationFrame` removal, plus a 3.5 MB module script before the
+first frame. Its window got no frame for about a second after load, and the
+`requestAnimationFrame` and `ready-to-show` both landed at about 1.25 s, in
+5 of 5 launches. Without the large script, `ready-to-show` came at load. A
+`backgroundColor` alone changed nothing. Showing the window at
+`did-finish-load` made the `requestAnimationFrame` run on time in 5 of 5.
+#1782's skeleton gates do not touch this ordering: its own run 36917107231
+still had one fast iteration among slow ones.
+
+The fix is in the app, so it applies to users and not only to the
+journey. `apps/electron-backend/src/app/services/main-window-first-show.ts`
+shows the window at `ready-to-show` or the main frame's `did-finish-load`,
+whichever comes first. The window's `backgroundColor` is the splash colour,
+so showing it before the first paint does not flash. `ready-to-show` still
+fires after the early show (on the runner 10-190 ms after load), so
+`main.sqlStatementsBeforeReadyToShow` keeps its meaning.
+
+Validation (Principle 3, the same journey on the same runner): three
+dispatched runs of the fix (36928706097, 36928716010, 36928725392) and the
+run of the commit that added the baselines (36930457538) took the fast path
+in all 24 iterations, with 15 calls and 559 mutations each.
+
+| Runs                                                        | Slow iterations | `spawnToFirstCardMs.p50`  | load → card                   |
+| ----------------------------------------------------------- | --------------- | ------------------------- | ----------------------------- |
+| `master` and #1782, 2026-09-30 to 10-01 (8 runs, see above) | 29 of 40        | 1,478-1,613 ms (one 760)  | ~940 ms slow, 280-500 ms fast |
+| this fix (4 runs)                                           | 0 of 20         | 988, 1,139, 923, 1,205 ms | 360-515 ms                    |
+
+The eight earlier runs are `master` 36768881838, 36814964563, 36842198653,
+36861129953, 36861409057 and 36915979562, and #1782's 36816552353 and
+36917107231. The runner's own speed moves `spawnToDidFinishLoadMs.p50` between 430 and
+710 ms from run to run, so compare load → card rather than absolute numbers.
+The one fast master run (36915979562, P50 760 ms) had a fast runner and four
+fast iterations.
+
+The fix first merged (#1788) into #1782's branch after #1782 had already
+reached `master`, so it landed again on its own. Measured again on `master`
+at bc5a7fcbf, which by then carried the redesigned dashboard hero (#1792):
+three dispatched runs (37192092882, 37192097790, 37192103151) took the fast
+path in all 18 iterations, with 15 calls and 558 mutations each, 466-528 ms
+from load to the first card and `spawnToFirstCardMs.p50` 1,149, 1,122 and
+1,170 ms. `master` without the fix was still bimodal then: its last six push
+runs before 2738bc28a had 30 of 36 iterations on the slow path (18 calls,
+1,031-1,033 mutations, about 940 ms from load to the card).
+
 ### Summary schema
 
 ```json
@@ -545,8 +628,9 @@ numbers so `tools/performance/check-journey-ratchet.mjs` can compare them with
 `tools/performance/journey-baselines.json`. The summary writer checks only
 that every measured iteration reports the same counter names with finite
 values, so a new counter needs no schema change. A J1 runtime baseline is added
-once its counter is deterministic on the CI runner; the launch counters are
-not yet (see [Ratchet](#ratchet)), so the summary is evidence only.
+once its counter is deterministic on the CI runner. Two are enforced
+(`renderer.ipcCallsToFirstCard` and `renderer.domMutationsToFirstCard`, see
+[Ratchet](#ratchet)); the other runtime counters are evidence only.
 
 J3 adds the `journeys.playback` entry with the same shape and no schema
 version change: `counters` and `wallClock` hold only plain numbers, and its
@@ -957,25 +1041,46 @@ Pushes to `master` and manual dispatches always run it. The job is warn-only (`c
 weeks (plan item B3): a regression marks the job failed without failing the
 workflow. Making it required is a maintainer decision.
 
-No J1 runtime counter is enforced yet. Three dispatched runs on 2026-09-27
-(CI runs 36271875209, 36271879955 and 36271884616) reported the same summary
-values, `renderer.ipcCallsToFirstCard` 16 and
-`renderer.domMutationsToFirstCard` 939, but the third run marked both
-`stable: false`: its warm-up and one measured iteration reached the first
-card in about 750 ms with 13 bridge calls and 576 mutations, the others in
-about 1,400 ms with 16 and 939. The three extra calls
-(`downloadsGetDefaultFolder` and two `dbGetGlobalRecentlyAdded`) land before
-or after the first card depending on that race, so neither counter is
-promoted until the race is understood and the counters are deterministic.
-`renderer.layoutShiftScore` (0) and `renderer.longTasks` (2) were identical
-in all eighteen runner iterations; the `spawnToFirstCardMs` P50 ranged from
-1,401 to 1,674 ms. All four stay evidence for now. Runner counters also
-differ from a Mac (12 and 571 there, the fast path without the Linux-only
-`getWindowState` call), so take J1 baseline values from the runner only.
-`renderer.layoutShiftScoreSettled` has no baseline either: the runner read
-it as `stable: false` because the dashboard hero flicker it reported was a
-race there (see [Settle window](#settle-window)). That flicker is fixed; add
-the runner's number once runner runs read it as `stable` too.
+The job enforces two J1 runtime counters: `renderer.ipcCallsToFirstCard`
+(15 calls) and `renderer.domMutationsToFirstCard` (558 mutations). After the
+`Run the performance journeys` step it runs
+`check-journey-ratchet.mjs --only launch/renderer.ipcCallsToFirstCard --only launch/renderer.domMutationsToFirstCard`
+on the summary that step wrote. Both entries have `slack` 0 and
+`evidenceRun` 37192092882, and were identical and `stable: true` in all
+three dispatched runs of the fix that removed the launch race on `master`
+(see
+[When the window is shown](#when-the-window-is-shown)). The step is in the
+job, not in the composite action, so the weekly tightening still measures a
+run that would fail it. While the job is warn-only, a regression fails the
+job and not the workflow. The two summaries of #1782 before that fix (18
+and 1,018) fail the check.
+
+Until that fix, J1 had two paths on the runner and no runtime counter could
+be enforced. Three dispatched runs on 2026-09-27 (36271875209, 36271879955
+and 36271884616) already showed both paths (16 calls / 939 mutations against
+13 / 576 at the time), and later `master` runs mixed them more often.
+
+The other J1 counters in the same three runs:
+
+| Counter                               | Value | `stable` in all three runs                                                |
+| ------------------------------------- | ----- | ------------------------------------------------------------------------- |
+| `main.modulesRegisteredBeforeWindow`  | 2     | yes                                                                       |
+| `renderer.ipcSerialDepthToFirstCard`  | 6     | yes (was unstable through the race)                                       |
+| `renderer.cdTicksIdle30s`             | 4     | yes (was unstable through the race)                                       |
+| `renderer.layoutShiftScore`           | 0     | yes                                                                       |
+| `renderer.layoutShiftScoreSettled`    | 0     | yes (#1782's hero fix plus this one)                                      |
+| `renderer.longTasks`                  | 2     | yes                                                                       |
+| `renderer.cdTicksToFirstCard`         | 21    | no: one iteration of 36928725392 read 22 (and one of 36930457538 read 20) |
+| `main.sqlStatementsBeforeReadyToShow` | 95    | no: 93 or 95 in every run                                                 |
+
+`renderer.cdTicksToFirstCard` keeps the one-tick race described under
+[change detection](#change-detection-ticks), which the Mac shows too (20 or
+21). `main.sqlStatementsBeforeReadyToShow` keeps the download and recording
+recovery racing `ready-to-show` (plan item A2). The six stable counters are
+candidates for further baselines once more runs agree. Wall-clock entries
+stay evidence. Runner counters still differ from a Mac (14 calls and 554
+mutations there; the missing call is the Linux-only `getWindowState`), so
+take J1 baseline values from the runner only.
 
 ### Weekly tightening
 
diff --git a/docs/architecture/validation-map.md b/docs/architecture/validation-map.md
index c380f3ee4..bd2fe853e 100644
--- a/docs/architecture/validation-map.md
+++ b/docs/architecture/validation-map.md
@@ -293,7 +293,10 @@ on `master`; before that, see the temporary-trigger note under Weekly
 tightening in the performance journeys document. `perf:journeys` builds the `electron-performance` configuration and runs every
 journey spec against the Xtream mock: J1 launch, then J2 open-source (a
 second set of launches, each followed by the click on the portal card), both
-written to the same summary file; its probe specs run with
+written to the same summary file. The `Performance journeys` job of `ci.yml`
+(warn-only) checks `renderer.ipcCallsToFirstCard` and
+`renderer.domMutationsToFirstCard` of that summary against the baselines;
+its probe specs run with
 `pnpm nx run electron-backend-e2e:test-performance-harness`, which CI runs in
 the `Unit Tests and Typechecks` job of `ci.yml` on every run. The
 `electron-backend-e2e` command targets call `tsx` and `playwright` directly,
diff --git a/docs/architecture/workspace-shell.md b/docs/architecture/workspace-shell.md
index 44f4d2771..af2bc2a68 100644
--- a/docs/architecture/workspace-shell.md
+++ b/docs/architecture/workspace-shell.md
@@ -510,15 +510,24 @@ Startup window mode (`Settings.startupWindowMode`, issue #1455):
 3. `fullscreen` is the `BrowserWindow` constructor option: on Windows/Linux
    the window is created hidden and enters fullscreen before its first
    paint. macOS ignores the option while the window is hidden (an NSWindow
-   only toggles fullscreen once it is on screen), so `ready-to-show` repeats
+   only toggles fullscreen once it is on screen), so the first show repeats
    the request with `setFullScreen(true)` right after `show()` wherever
    `isFullScreen()` is still false — never unconditionally, or the
    platforms that honoured the option would animate a second toggle. The
    saved bounds stay spread into the options — they are the normal bounds
    the window returns to, and the close handler keeps persisting
-   `getNormalBounds()`. `maximized` calls `maximize()` inside
-   `ready-to-show` right before `show()`, never earlier: `maximize()` on a
-   hidden window shows it, and a blank window would flash.
+   `getNormalBounds()`. `maximized` calls `maximize()` right before the
+   first `show()`, never earlier: `maximize()` on a hidden window shows it,
+   and a blank window would flash. That first show happens at
+   `ready-to-show` or the main frame's `did-finish-load`, whichever comes
+   first (`services/main-window-first-show.ts`): on Linux a hidden window
+   whose startup scripts ran before its first frame gets the next one about
+   a second later, so `ready-to-show` alone left the window off screen and
+   the splash's animation frame waiting. At `did-finish-load` the inline
+   splash is parsed, and the window's `backgroundColor` is the splash colour
+   (`MAIN_WINDOW_BACKGROUND_COLOR`, keep it in sync with `#initial-splash`
+   in `apps/web/src/index.html`), so showing before the first paint does
+   not flash.
 4. `iptvnator --fullscreen` (read via `app.commandLine.hasSwitch`, so it can
    sit anywhere in argv; the playlist-path extractor already skips every
    `-`-prefixed argument) forces `fullscreen` for that launch only and is
diff --git a/tools/performance/journey-baselines.json b/tools/performance/journey-baselines.json
index 56c319574..205353e56 100644
--- a/tools/performance/journey-baselines.json
+++ b/tools/performance/journey-baselines.json
@@ -9,6 +9,24 @@
                 "updatedAt": "2026-10-01",
                 "evidencePr": 1775,
                 "measuredWith": "pnpm nx build web && pnpm run perf:initial-bytes"
+            },
+            "renderer.ipcCallsToFirstCard": {
+                "value": 15,
+                "unit": "calls",
+                "slack": 0,
+                "updatedAt": "2026-10-04",
+                "evidencePr": 1828,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37192092882",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in 3 runs"
+            },
+            "renderer.domMutationsToFirstCard": {
+                "value": 558,
+                "unit": "mutations",
+                "slack": 0,
+                "updatedAt": "2026-10-04",
+                "evidencePr": 1828,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37192092882",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in 3 runs"
             }
         }
     }

From de2e1b19d7c56cdf856c20f0ef454c5b307acdb2 Mon Sep 17 00:00:00 2001
From: 4gray <fourgray@proton.me>
Date: Tue, 6 Oct 2026 10:49:44 +0200
Subject: [PATCH 07/20] docs(website): publish player controls and library
 guides

---
 .../src/content/blog/library-organization-guide.mdx       | 7 ++++---
 apps/website/src/content/blog/player-controls-guide.mdx   | 4 ++--
 tools/testing/website-guides.test.mjs                     | 8 ++++++++
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/apps/website/src/content/blog/library-organization-guide.mdx b/apps/website/src/content/blog/library-organization-guide.mdx
index db4c04d76..a01bd14c6 100644
--- a/apps/website/src/content/blog/library-organization-guide.mdx
+++ b/apps/website/src/content/blog/library-organization-guide.mdx
@@ -1,16 +1,16 @@
 ---
 title: "Keep Your Library Tidy: Sources, Favorites and Watched Titles"
 description: Review source availability, return from a favorite channel to its playlist, mark titles watched and simplify catalog views in IPTVnator without confusing hidden items with missing data.
-pubDate: 2026-09-27
+pubDate: 2026-10-06
 author: 4gray
 heroImage: /iptvnator/blog/feature-guides/screenshots/guide-library-watched-dark.png
 tags:
     - guide
-draft: true
+draft: false
 faq:
     - q: Does an unavailable source mean my channels were deleted?
       a: No. Availability describes a connection check. A timeout, a temporary outage or an unverified account is different from deleting a saved source or losing its channels.
-    - q: Does library watched state delete entries automatically?
+    - q: Does source cleanup delete entries automatically?
       a: No. The desktop cleanup dialog checks sources and lets you review the selection before deleting. Confirmed expired or disabled accounts can be preselected; uncertain results need review.
     - q: What happens when I delete a source?
       a: Its saved favorites, history and playback progress are removed with it. Downloaded files are kept. Export a playlist backup first if you want a restorable copy of supported source state.
@@ -111,6 +111,7 @@ permanent labels are more useful than an extra row of posters.
 
 ## Related
 
+- [Back up your playlists before removing sources](/iptvnator/blog/playlist-backup-restore-guide/)
 - [Movie and series metadata with TMDB](/iptvnator/blog/tmdb-metadata-guide/)
 - [Alternative movie sources](/iptvnator/blog/alternative-sources-guide/)
 - [Library changes in 0.24](/iptvnator/blog/v0-24-release-notes/)
diff --git a/apps/website/src/content/blog/player-controls-guide.mdx b/apps/website/src/content/blog/player-controls-guide.mdx
index 085b2a475..aa6686561 100644
--- a/apps/website/src/content/blog/player-controls-guide.mdx
+++ b/apps/website/src/content/blog/player-controls-guide.mdx
@@ -1,13 +1,13 @@
 ---
 title: "Subtitles, Quality and Picture-in-Picture: Get More from the Player"
 description: Use IPTVnator's unified player controls to choose stream quality, load subtitles, adjust their timing and keep video visible in picture-in-picture. Learn why some options depend on the stream or player.
-pubDate: 2026-09-27
+pubDate: 2026-10-06
 author: 4gray
 heroImage: /iptvnator/blog/feature-guides/screenshots/guide-player-subtitles-dark.png
 tags:
     - guide
     - playback
-draft: true
+draft: false
 faq:
     - q: Why is there no quality menu?
       a: The menu appears when the stream exposes more than one video quality. A single video file or a channel with only one rendition has no alternatives for the player to select.
diff --git a/tools/testing/website-guides.test.mjs b/tools/testing/website-guides.test.mjs
index 97bd4e8f4..8ad84375a 100644
--- a/tools/testing/website-guides.test.mjs
+++ b/tools/testing/website-guides.test.mjs
@@ -15,6 +15,14 @@ const distRoot = new URL('../../dist/apps/website/', import.meta.url);
 const SITE = 'https://4gray.github.io/iptvnator';
 
 const GUIDES = [
+  {
+    slug: 'player-controls-guide',
+    screenshots: ['blog/feature-guides/screenshots/guide-player-subtitles-dark.png'],
+  },
+  {
+    slug: 'library-organization-guide',
+    screenshots: ['blog/feature-guides/screenshots/guide-library-watched-dark.png'],
+  },
   {
     slug: 'stable-nightly-updates-guide',
     screenshots: ['blog/feature-guides/screenshots/guide-update-channel-dark.png'],

From 0a006cb02797a13c2d873e728bb6b254089cbfa3 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 11:43:55 +0200
Subject: [PATCH 08/20] ci(perf): enforce the journey counters stable on master
 (#1829)

* ci(perf): enforce the journey counters stable on master

Promote the J1, J2 and J3 counters that were identical in all 55 measured
iterations of the 11 master runs from 2026-10-03 to 2026-10-04 to
journey-baselines.json, and check them in the Performance journeys job
(still warn-only), in one step together with #1828's two validated J1
entries. None of the new ones has Principle 3 evidence, so each carries a
"guard only, not validated" note that the checker prints with a failure.
A performance-tools test keeps the job's --only list equal to the journey
entries. Number formatting uses three decimals, the precision of the
layout-shift scores.

J2 renderer.layoutShiftScore is 0.233, not the window's 0.222: every
master run from #1814 (page Back buttons in the header) on reads 0.233.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci(perf): check the journey counters whenever a summary was written

Review follow-up (Greptile): the check ran only after the composite
action succeeded, so a failed job-summary report after a written
summary.json skipped every baseline. It now runs unless the job was
cancelled, as long as the action produced a summary path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |  25 ++-
 .github/workflows/performance-ratchet.yml     |   2 +-
 docs/architecture/performance-journeys.md     | 149 ++++++++++++------
 docs/architecture/validation-map.md           |  14 +-
 .../performance/check-baseline-direction.mjs  |   3 +-
 tools/performance/check-journey-ratchet.mjs   |  12 +-
 .../check-journey-ratchet.test.mjs            |  68 ++++++++
 tools/performance/journey-baselines.json      |  84 ++++++++++
 tools/performance/project.json                |   1 +
 tools/performance/tighten-baselines.mjs       |   3 +-
 tools/performance/tighten-baselines.test.mjs  |  60 +++++++
 11 files changed, 357 insertions(+), 64 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e1a028afb..08f56981e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -327,12 +327,17 @@ jobs:
               id: journeys
               uses: ./.github/actions/performance-journeys
 
-            # Only the J1 counters shown deterministic on this runner; the
-            # other journey measurements stay evidence (see Ratchet in
-            # docs/architecture/performance-journeys.md). Here and not in
-            # the composite action, so the weekly tightening still measures
-            # a run that would fail it.
-            - name: Check the J1 runtime counters against the baselines
+            # Only the counters identical in every measured iteration of
+            # recent master runs; their entries say whether a counter is
+            # validated against wall-clock or a guard only (see Ratchet in
+            # docs/architecture/performance-journeys.md). Here and not in the
+            # composite action, so the weekly tightening still measures a run
+            # that would fail it. tools/performance tests keep this list equal
+            # to the journey entries of journey-baselines.json. It also runs
+            # when a later step of the action (the job-summary report) failed
+            # after the summary was written, so the counters are still checked.
+            - name: Check the journey counters against the baselines
+              if: ${{ !cancelled() && steps.journeys.outputs.summary != '' }}
               env:
                   SUMMARY: ${{ steps.journeys.outputs.summary }}
               run: >-
@@ -340,6 +345,14 @@ jobs:
                   --summary "$SUMMARY"
                   --only launch/renderer.ipcCallsToFirstCard
                   --only launch/renderer.domMutationsToFirstCard
+                  --only launch/main.modulesRegisteredBeforeWindow
+                  --only launch/renderer.layoutShiftScore
+                  --only launch/renderer.layoutShiftScoreSettled
+                  --only open-source/main.mockHttpRequestsToSettled
+                  --only open-source/renderer.ipcCallsToFirstPage
+                  --only open-source/renderer.layoutShiftScore
+                  --only playback/renderer.httpRequestsToPlaying
+                  --only playback/renderer.layoutShiftScore
 
             - name: Upload journey summaries
               if: always()
diff --git a/.github/workflows/performance-ratchet.yml b/.github/workflows/performance-ratchet.yml
index 39e3a0c4d..2f77794bb 100644
--- a/.github/workflows/performance-ratchet.yml
+++ b/.github/workflows/performance-ratchet.yml
@@ -240,7 +240,7 @@ jobs:
                       git diff "$HEAD_SHA" HEAD -- "$baselines"
                       echo '```'
                       echo
-                      echo "If \`master\` moved since \`$HEAD_SHA\`, make sure the Initial bytes ratchet job passes on this PR before merging."
+                      echo "If \`master\` moved since \`$HEAD_SHA\`, make sure the Initial bytes ratchet and Performance journeys jobs pass on this PR before merging."
                   } > "$BODY"
                   gh api -X PATCH "repos/$REPOSITORY/pulls/$pr" -F "body=@$BODY" --silent
                   echo "Pull request: ${GITHUB_SERVER_URL}/$REPOSITORY/pull/$pr"
diff --git a/docs/architecture/performance-journeys.md b/docs/architecture/performance-journeys.md
index 984ec766a..d16fb4f50 100644
--- a/docs/architecture/performance-journeys.md
+++ b/docs/architecture/performance-journeys.md
@@ -627,10 +627,10 @@ runs before 2738bc28a had 30 of 36 iterations on the slow path (18 calls,
 numbers so `tools/performance/check-journey-ratchet.mjs` can compare them with
 `tools/performance/journey-baselines.json`. The summary writer checks only
 that every measured iteration reports the same counter names with finite
-values, so a new counter needs no schema change. A J1 runtime baseline is added
-once its counter is deterministic on the CI runner. Two are enforced
-(`renderer.ipcCallsToFirstCard` and `renderer.domMutationsToFirstCard`, see
-[Ratchet](#ratchet)); the other runtime counters are evidence only.
+values, so a new counter needs no schema change. A runtime baseline is added
+once its counter is deterministic on the CI runner; the enforced ones and the
+reasons for the others are under
+[Enforced journey counters](#enforced-journey-counters).
 
 J3 adds the `journeys.playback` entry with the same shape and no schema
 version change: `counters` and `wallClock` hold only plain numbers, and its
@@ -864,8 +864,9 @@ mutations come from the EPG timeline rendering about 240 programme blocks
 from the `get_simple_data_table` response before the first frame. Whether
 that response and its render land before `playing` is a race on a slower
 machine, so check the runner's `counterStability` before trusting the
-mutation and request counts. No J3 baseline exists yet; J3 counters join the
-ratchet once three runner runs agree.
+mutation and request counts. On the runner `renderer.httpRequestsToPlaying`
+and `renderer.layoutShiftScore` are enforced as guards; see
+[Enforced journey counters](#enforced-journey-counters).
 
 ## `renderer.initialBytes`
 
@@ -943,7 +944,10 @@ that file:
 - a measurement below its baseline passes and prints a "tighten" hint;
 - a measured counter without a baseline is noted, not failed;
 - checking nothing fails: an empty baselines file, or `--only` naming an
-  entry that does not exist, cannot exit 0.
+  entry that does not exist, cannot exit 0;
+- an optional `note` (a string) is printed with the entry's failure; journey
+  entries use it to mark a guard that is not validated against wall-clock
+  (see [Enforced journey counters](#enforced-journey-counters)).
 
 `--only <journey>/<counter>` (repeatable) restricts the check to the named
 baselines. A script that measures one counter writes its own summary file
@@ -1041,46 +1045,85 @@ Pushes to `master` and manual dispatches always run it. The job is warn-only (`c
 weeks (plan item B3): a regression marks the job failed without failing the
 workflow. Making it required is a maintainer decision.
 
-The job enforces two J1 runtime counters: `renderer.ipcCallsToFirstCard`
-(15 calls) and `renderer.domMutationsToFirstCard` (558 mutations). After the
-`Run the performance journeys` step it runs
-`check-journey-ratchet.mjs --only launch/renderer.ipcCallsToFirstCard --only launch/renderer.domMutationsToFirstCard`
-on the summary that step wrote. Both entries have `slack` 0 and
-`evidenceRun` 37192092882, and were identical and `stable: true` in all
-three dispatched runs of the fix that removed the launch race on `master`
-(see
-[When the window is shown](#when-the-window-is-shown)). The step is in the
-job, not in the composite action, so the weekly tightening still measures a
-run that would fail it. While the job is warn-only, a regression fails the
-job and not the workflow. The two summaries of #1782 before that fix (18
-and 1,018) fail the check.
+After the `Run the performance journeys` step, the job runs
+`check-journey-ratchet.mjs --only …` on the summary that step wrote, for the
+journey entries of `journey-baselines.json` (every entry except
+`renderer.initialBytes`, which the `Initial bytes ratchet` job checks). A
+`performance-tools` test keeps that `--only` list equal to those entries, so
+a baseline cannot be added without being enforced. The step is in the job,
+not in the composite action, so the weekly tightening still measures a run
+that would fail it. While the job is warn-only, a regression fails the job
+and not the workflow.
 
-Until that fix, J1 had two paths on the runner and no runtime counter could
-be enforced. Three dispatched runs on 2026-09-27 (36271875209, 36271879955
-and 36271884616) already showed both paths (16 calls / 939 mutations against
-13 / 576 at the time), and later `master` runs mixed them more often.
+#### Enforced journey counters
 
-The other J1 counters in the same three runs:
+Two J1 entries are validated (Principle 3) and carry no note:
+`launch/renderer.ipcCallsToFirstCard` 15 and
+`launch/renderer.domMutationsToFirstCard` 558 (#1828, `evidenceRun`
+37192092882). #1828 removed the launch race (the window shown at
+`did-finish-load`, see [When the window is shown](#when-the-window-is-shown)):
+three dispatched runs on `master` read 15 / 558 in all 18 iterations, and
+load to the first card went from about 940 ms to 466-528 ms. Slow-path
+summaries (18 / 1,018 or more) fail the check.
 
-| Counter                               | Value | `stable` in all three runs                                                |
-| ------------------------------------- | ----- | ------------------------------------------------------------------------- |
-| `main.modulesRegisteredBeforeWindow`  | 2     | yes                                                                       |
-| `renderer.ipcSerialDepthToFirstCard`  | 6     | yes (was unstable through the race)                                       |
-| `renderer.cdTicksIdle30s`             | 4     | yes (was unstable through the race)                                       |
-| `renderer.layoutShiftScore`           | 0     | yes                                                                       |
-| `renderer.layoutShiftScoreSettled`    | 0     | yes (#1782's hero fix plus this one)                                      |
-| `renderer.longTasks`                  | 2     | yes                                                                       |
-| `renderer.cdTicksToFirstCard`         | 21    | no: one iteration of 36928725392 read 22 (and one of 36930457538 read 20) |
-| `main.sqlStatementsBeforeReadyToShow` | 95    | no: 93 or 95 in every run                                                 |
+A counter is enforced once it was identical in every measured iteration of
+every recent `master` run. The other entries were identical in all 55
+measured iterations of the 11 `master` runs from 2026-10-03 08:25 to
+2026-10-04 06:55 (CI runs 37109621784 to 37184230956), with `slack` 0:
 
-`renderer.cdTicksToFirstCard` keeps the one-tick race described under
-[change detection](#change-detection-ticks), which the Mac shows too (20 or
-21). `main.sqlStatementsBeforeReadyToShow` keeps the download and recording
-recovery racing `ready-to-show` (plan item A2). The six stable counters are
-candidates for further baselines once more runs agree. Wall-clock entries
-stay evidence. Runner counters still differ from a Mac (14 calls and 554
-mutations there; the missing call is the Linux-only `getWindowState`), so
-take J1 baseline values from the runner only.
+| Entry                                        | Value | Week (69 runs since 2026-09-27)                                           |
+| -------------------------------------------- | ----- | ------------------------------------------------------------------------- |
+| `launch/main.modulesRegisteredBeforeWindow`  | 2     | identical                                                                 |
+| `launch/renderer.layoutShiftScore`           | 0     | identical                                                                 |
+| `launch/renderer.layoutShiftScoreSettled`    | 0     | 0.235 in some iterations of 8 runs up to 2026-10-02 (hero flicker, #1782) |
+| `open-source/main.mockHttpRequestsToSettled` | 1     | identical                                                                 |
+| `open-source/renderer.ipcCallsToFirstPage`   | 17    | identical                                                                 |
+| `open-source/renderer.layoutShiftScore`      | 0.233 | 0.221, then 0.222; 0.233 since #1814, never mixed within a run            |
+| `playback/renderer.httpRequestsToPlaying`    | 2     | identical                                                                 |
+| `playback/renderer.layoutShiftScore`         | 0.001 | identical                                                                 |
+
+`open-source/renderer.layoutShiftScore` read 0.222 in that window and 0.233
+in every iteration of every `master` run from 84aef83a6 (#1814, page Back
+buttons moved into the header) on, so its value is 0.233 with `evidenceRun`
+37372780064 (b78224376). The 0.011 that #1814 added is not explained yet;
+lowering it back is a separate change.
+
+Being deterministic is not the same as being validated. Principle 3 of the
+plan promotes a counter to a guardrail once a PR has shown that lowering it
+lowered the journey's wall-clock. None of these counters has that evidence
+yet: `main.modulesRegisteredBeforeWindow` waits for the deferred IPC
+registration (plan item C4), the layout-shift scores measure visual
+stability rather than time, and no PR has moved a J2 or J3 counter. Each
+entry therefore carries
+`"note": "guard only, not validated: …"`. A guard stops a regression of a
+deterministic number, and the checker prints the note with a failure; it
+says nothing about whether lowering that number makes the journey faster.
+When a PR shows that link, it drops the note and names the evidence in
+`evidencePr`. `renderer.initialBytes` predates the note and carries none;
+this document records no wall-clock change for it either.
+
+Not enforced, with the reason:
+
+- J1 `renderer.ipcSerialDepthToFirstCard` (6): bimodal on `master` until
+  #1828 (9 or 6) and identical in its three dispatched runs; a candidate
+  once `master` runs agree.
+- J1 `main.sqlStatementsBeforeReadyToShow`: 93 or 95 even without the launch
+  race, because the download and recording recovery races `ready-to-show`
+  (plan item A2).
+- Every `renderer.longTasks` (J1 2 or 1, J2 0 with one 1 earlier in the
+  week, J3 1 or 2): a long task is a task over 50 ms, so the count follows
+  runner speed, not work.
+- Every `cdTicks` counter: the zoneless migration (plan item C6) changes
+  them.
+- J2 `renderer.domMutationsToFirstPage`: 1,602 or 1,603 between runs of
+  recent commits.
+- J3 `renderer.ipcCallsToPlaying` (4 or 5) and
+  `renderer.domMutationsToPlaying` (6,182, 6,183 or 6,199): not identical,
+  and the EPG rendering work changes the mutation count.
+- J4: not measured yet.
+
+Runner counters differ from a Mac (the Linux-only `getWindowState` call, for
+one), so take every journey baseline value from the runner only.
 
 ### Weekly tightening
 
@@ -1105,7 +1148,11 @@ its job; its entries are then unmeasured in that run. A final job runs
   `check-baseline-direction.mjs` without `--allow-increase`, which both the
   script and the job check;
 - a lowered entry gets `updatedAt`, `measuredWith` and `evidenceRun` (the
-  workflow run URL); `evidencePr` is set to the tightening PR once it exists.
+  workflow run URL); `evidencePr` is set to the tightening PR once it exists;
+  every other field, including a `note`, is kept, so a guard stays marked as
+  not validated after it is lowered;
+- a counter already at 0 is never lowered; a layout-shift score is lowered
+  to the three-decimal value the summary reports.
 
 When the file changed and the run is on `master`, the job pushes
 `automation/performance-ratchet` and opens (or updates) a pull request with
@@ -1124,8 +1171,10 @@ dispatches workflows that exist on the default branch, so before the first
 merge of a new or renamed workflow add a temporary `push` trigger for the
 branch and drop it before review, as #1760 did. Review the pull request like a manual
 tightening: if `master` moved since the measured commit, the
-`Initial bytes ratchet` job on the pull request is what shows that the new
-value still holds (the concurrent-merge effect above).
+`Initial bytes ratchet` job (for `renderer.initialBytes`) and the
+`Performance journeys` job (for the journey counters) on the pull request
+are what show that the new values still hold (the concurrent-merge effect
+above).
 
 ## Charset parse benchmark
 
@@ -1172,7 +1221,13 @@ reports slow imports of non-Latin playlists.
 3. Cover the extraction and the failure modes with `node --test` and register
    the test file in `tools/performance/project.json`.
 4. Validate the counter before it becomes a guardrail: one PR must show that
-   lowering it moved wall-clock in the same journey.
+   lowering it moved wall-clock in the same journey. A counter that is
+   deterministic but not validated may be enforced as a guard: its baseline
+   entry carries a `note` saying so (see
+   [Enforced journey counters](#enforced-journey-counters)).
+5. A journey counter's baseline is enforced only when it is also in the
+   `--only` list of the `Performance journeys` job in `ci.yml`; the
+   `performance-tools` tests fail when the two differ.
 
 ## Adding a journey
 
diff --git a/docs/architecture/validation-map.md b/docs/architecture/validation-map.md
index bd2fe853e..4ee3ee303 100644
--- a/docs/architecture/validation-map.md
+++ b/docs/architecture/validation-map.md
@@ -276,7 +276,7 @@ pnpm nx build web
 pnpm run perf:initial-bytes         # breakdown only
 pnpm run perf:initial-bytes:check   # measure, then compare with the committed baseline
 pnpm nx test performance-tools
-pnpm run perf:journeys              # J1 launch + J2 open-source journeys, one dist/performance/journeys/<timestamp>/summary.json
+pnpm run perf:journeys              # J1 launch, J2 open-source and J3 playback journeys, one dist/performance/journeys/<timestamp>/summary.json
 ```
 
 `perf:initial-bytes` reads the built `dist/apps/web/index.html` and sums the
@@ -285,7 +285,12 @@ bytes on the initial path (the J1 counter `renderer.initialBytes`).
 `tools/performance/journey-baselines.json`; baselines only move down. CI runs
 the same check in the `Initial bytes ratchet` job of `ci.yml` for PRs that
 target `master` and for `master` pushes (dispatch it with
-`gh workflow run ci.yml --ref <branch>` for a stacked branch). The weekly
+`gh workflow run ci.yml --ref <branch>` for a stacked branch). The
+`Performance journeys` job checks the journey counters listed with `--only`
+in its `Check the journey counters against the baselines` step against the
+same file (warn-only); a new journey baseline
+must be added to that list too, which `pnpm nx test performance-tools`
+checks. The weekly
 `performance-ratchet.yml` workflow lowers baselines through a bot PR; validate
 a change to it with `gh workflow run performance-ratchet.yml --ref <branch>`,
 which measures but opens no PR off `master`. Dispatch needs the workflow file
@@ -293,10 +298,7 @@ on `master`; before that, see the temporary-trigger note under Weekly
 tightening in the performance journeys document. `perf:journeys` builds the `electron-performance` configuration and runs every
 journey spec against the Xtream mock: J1 launch, then J2 open-source (a
 second set of launches, each followed by the click on the portal card), both
-written to the same summary file. The `Performance journeys` job of `ci.yml`
-(warn-only) checks `renderer.ipcCallsToFirstCard` and
-`renderer.domMutationsToFirstCard` of that summary against the baselines;
-its probe specs run with
+written to the same summary file; its probe specs run with
 `pnpm nx run electron-backend-e2e:test-performance-harness`, which CI runs in
 the `Unit Tests and Typechecks` job of `ci.yml` on every run. The
 `electron-backend-e2e` command targets call `tsx` and `playwright` directly,
diff --git a/tools/performance/check-baseline-direction.mjs b/tools/performance/check-baseline-direction.mjs
index 41816767c..e5a0ada85 100644
--- a/tools/performance/check-baseline-direction.mjs
+++ b/tools/performance/check-baseline-direction.mjs
@@ -49,8 +49,9 @@ function entries(baselines) {
     return flat;
 }
 
+// Three decimals: journey summaries round layout-shift scores to three.
 function formatNumber(value) {
-    return value.toLocaleString('en-US', { maximumFractionDigits: 2 });
+    return value.toLocaleString('en-US', { maximumFractionDigits: 3 });
 }
 
 /**
diff --git a/tools/performance/check-journey-ratchet.mjs b/tools/performance/check-journey-ratchet.mjs
index b03bd70eb..3459b5506 100644
--- a/tools/performance/check-journey-ratchet.mjs
+++ b/tools/performance/check-journey-ratchet.mjs
@@ -14,6 +14,9 @@
  *   are lowered by hand, with the measured output as evidence, never raised.
  * - Checking nothing is a failure: an empty baselines file, or `--only`
  *   naming an entry that does not exist, must not exit 0.
+ * - An optional `note` (a string) says why an entry is enforced, such as a
+ *   guard whose link to wall-clock is not validated (Principle 3). It is
+ *   printed with a failure, so the author sees what the counter stands for.
  *
  * `--only <journey>/<counter>` (repeatable) restricts the check to the named
  * baselines, so a script that measures one counter can check that counter
@@ -34,10 +37,11 @@ export const DEFAULT_BASELINES_PATH =
 /** The PR label that lets check-baseline-direction.mjs accept a weakening. */
 export const BASELINE_INCREASE_LABEL = 'perf-baseline-increase';
 
+// Three decimals: journey summaries round layout-shift scores to three.
 function formatNumber(value) {
     return Number.isInteger(value)
         ? value.toLocaleString('en-US')
-        : value.toLocaleString('en-US', { maximumFractionDigits: 2 });
+        : value.toLocaleString('en-US', { maximumFractionDigits: 3 });
 }
 
 function isPlainObject(value) {
@@ -82,6 +86,9 @@ export function validateBaselines(baselines) {
                     `Baseline ${label} has an invalid "slack" (must be an integer >= 0).`
                 );
             }
+            if (entry.note !== undefined && typeof entry.note !== 'string') {
+                throw new Error(`Baseline ${label} has a non-string "note".`);
+            }
             if (
                 entry.slack !== undefined &&
                 entry.toleranceRatio !== undefined
@@ -185,8 +192,9 @@ export function compareToBaselines({ baselines, summary, only = [] }) {
             const limitText = describeLimit(entry, unit);
 
             if (measured > limit) {
+                const note = entry.note ? ` Note: ${entry.note}` : '';
                 result.failures.push(
-                    `${label}: ${formatNumber(measured)}${unit} exceeds ${limitText} by ${formatNumber(measured - limit)}${unit}. Bring the value back down; baselines only move down. If the growth is a deliberate trade-off, raise the baseline in ${DEFAULT_BASELINES_PATH}, make the case in the PR, and ask a maintainer to add the ${BASELINE_INCREASE_LABEL} label.`
+                    `${label}: ${formatNumber(measured)}${unit} exceeds ${limitText} by ${formatNumber(measured - limit)}${unit}. Bring the value back down; baselines only move down. If the growth is a deliberate trade-off, raise the baseline in ${DEFAULT_BASELINES_PATH}, make the case in the PR, and ask a maintainer to add the ${BASELINE_INCREASE_LABEL} label.${note}`
                 );
             } else if (entry.slack && measured > entry.value) {
                 result.passed.push(
diff --git a/tools/performance/check-journey-ratchet.test.mjs b/tools/performance/check-journey-ratchet.test.mjs
index dd3a44cf7..2b4a04c08 100644
--- a/tools/performance/check-journey-ratchet.test.mjs
+++ b/tools/performance/check-journey-ratchet.test.mjs
@@ -21,6 +21,10 @@ const committedBaselinesPath = fileURLToPath(
     new URL('./journey-baselines.json', import.meta.url)
 );
 
+const ciWorkflowPath = fileURLToPath(
+    new URL('../../.github/workflows/ci.yml', import.meta.url)
+);
+
 const baselines = {
     version: 1,
     journeys: {
@@ -357,6 +361,49 @@ test('rejects malformed baseline files', () => {
             }),
         /sets both "slack" and "toleranceRatio"/
     );
+    assert.throws(
+        () =>
+            validateBaselines({
+                journeys: { launch: { x: { value: 1, note: true } } },
+            }),
+        /non-string "note"/
+    );
+});
+
+test('a failing entry prints its note; a fractional score is exact', () => {
+    const guarded = {
+        journeys: {
+            'open-source': {
+                'renderer.layoutShiftScore': {
+                    value: 0.222,
+                    unit: 'score',
+                    slack: 0,
+                    note: 'guard only, not validated',
+                },
+            },
+        },
+    };
+    const check = (score) =>
+        compareToBaselines({
+            baselines: guarded,
+            summary: {
+                journeys: {
+                    'open-source': {
+                        counters: { 'renderer.layoutShiftScore': score },
+                    },
+                },
+            },
+        });
+
+    assert.deepEqual(check(0.222).failures, []);
+    const above = check(0.223);
+    assert.equal(above.failures.length, 1);
+    assert.match(
+        above.failures[0],
+        /0\.223 score exceeds baseline 0\.222 by 0\.001 score/
+    );
+    assert.match(above.failures[0], /Note: guard only, not validated$/);
+    assert.equal(check(0.221).tightenable.length, 1);
 });
 
 test('formats a summary line for both outcomes', () => {
@@ -444,6 +491,27 @@ test('the committed baselines file is valid and every entry names its evidence f
     }
 });
 
+test('the Performance journeys job checks every journey-run baseline', async () => {
+    const committed = JSON.parse(
+        await readFile(committedBaselinesPath, 'utf8')
+    );
+    const workflow = await readFile(ciWorkflowPath, 'utf8');
+    const step = workflow.match(
+        /- name: Check the journey counters against the baselines\n([\s\S]*?)(?=\n\s*- name: )/
+    );
+    assert.ok(step, 'ci.yml must keep the journey counter check step');
+    const only = [...step[1].matchAll(/--only (\S+)/g)].map((m) => m[1]);
+    // renderer.initialBytes is measured from the web build by the Initial
+    // bytes ratchet job (perf:initial-bytes:check); every other baseline comes
+    // from the journeys and must be enforced by this step, or it guards nothing.
+    const expected = Object.entries(committed.journeys)
+        .flatMap(([journey, entries]) =>
+            Object.keys(entries).map((name) => `${journey}/${name}`)
+        )
+        .filter((label) => label !== 'launch/renderer.initialBytes');
+    assert.deepEqual([...only].sort(), [...expected].sort());
+});
+
 async function runCli(summary, extraBaselines = baselines) {
     const summaryPath = path.join(
         workDir,
diff --git a/tools/performance/journey-baselines.json b/tools/performance/journey-baselines.json
index 205353e56..6b5cd01ee 100644
--- a/tools/performance/journey-baselines.json
+++ b/tools/performance/journey-baselines.json
@@ -27,6 +27,90 @@
                 "evidencePr": 1828,
                 "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37192092882",
                 "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in 3 runs"
+            },
+            "main.modulesRegisteredBeforeWindow": {
+                "value": 2,
+                "unit": "phases",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            },
+            "renderer.layoutShiftScore": {
+                "value": 0,
+                "unit": "score",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            },
+            "renderer.layoutShiftScoreSettled": {
+                "value": 0,
+                "unit": "score",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            }
+        },
+        "open-source": {
+            "main.mockHttpRequestsToSettled": {
+                "value": 1,
+                "unit": "requests",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            },
+            "renderer.ipcCallsToFirstPage": {
+                "value": 17,
+                "unit": "calls",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            },
+            "renderer.layoutShiftScore": {
+                "value": 0.233,
+                "unit": "score",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-06",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37372780064",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in every measured iteration of the 7 master runs from 84aef83a6 (#1814, which moved it from 0.222) to b78224376"
+            }
+        },
+        "playback": {
+            "renderer.httpRequestsToPlaying": {
+                "value": 2,
+                "unit": "requests",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
+            },
+            "renderer.layoutShiftScore": {
+                "value": 0.001,
+                "unit": "score",
+                "slack": 0,
+                "note": "guard only, not validated: no PR has yet shown that lowering this counter lowers the journey wall-clock (Principle 3)",
+                "updatedAt": "2026-10-04",
+                "evidencePr": null,
+                "evidenceRun": "https://github.com/4gray/iptvnator/actions/runs/37184230956",
+                "measuredWith": "pnpm run perf:journeys (ubuntu-latest, xvfb), identical in all 55 measured iterations of 11 master runs, 2026-10-03 to 2026-10-04"
             }
         }
     }
diff --git a/tools/performance/project.json b/tools/performance/project.json
index 106390896..9f0e3936a 100644
--- a/tools/performance/project.json
+++ b/tools/performance/project.json
@@ -11,6 +11,7 @@
             "inputs": [
                 "{projectRoot}/*.mjs",
                 "{projectRoot}/*.json",
+                "{workspaceRoot}/.github/workflows/ci.yml",
                 { "externalDependencies": ["parse5"] }
             ],
             "options": {
diff --git a/tools/performance/tighten-baselines.mjs b/tools/performance/tighten-baselines.mjs
index 0c82bf09e..8ae7786d6 100644
--- a/tools/performance/tighten-baselines.mjs
+++ b/tools/performance/tighten-baselines.mjs
@@ -54,8 +54,9 @@ function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+// Three decimals: journey summaries round layout-shift scores to three.
 function formatNumber(value) {
-    return value.toLocaleString('en-US', { maximumFractionDigits: 2 });
+    return value.toLocaleString('en-US', { maximumFractionDigits: 3 });
 }
 
 /**
diff --git a/tools/performance/tighten-baselines.test.mjs b/tools/performance/tighten-baselines.test.mjs
index 4c3542719..ccd3e5b25 100644
--- a/tools/performance/tighten-baselines.test.mjs
+++ b/tools/performance/tighten-baselines.test.mjs
@@ -93,6 +93,66 @@ test('a counter below its value in every run drops to the largest run', () => {
     assert.match(direction.lowered[0], /1,064 -> 1,059 bytes/);
 });
 
+test('a journey-run entry keeps its note and is lowered to three decimals', () => {
+    const score = {
+        value: 0.222,
+        unit: 'score',
+        slack: 0,
+        note: 'guard only, not validated',
+        updatedAt: '2026-10-04',
+        evidencePr: 1,
+        measuredWith: 'pnpm run perf:journeys',
+    };
+    const baselines = {
+        version: 1,
+        journeys: {
+            ...baselinesFile().journeys,
+            'open-source': { 'renderer.layoutShiftScore': score },
+            playback: { 'renderer.layoutShiftScore': { ...score, value: 0 } },
+        },
+    };
+    // The weekly job merges each runner's initial-bytes and journey summaries.
+    const runs = [0.221, 0.22, 0.221].map((value, index) =>
+        mergeRunSummaries(
+            [
+                bytesRun(1000),
+                {
+                    journeys: {
+                        'open-source': {
+                            counters: { 'renderer.layoutShiftScore': value },
+                        },
+                        playback: {
+                            counters: { 'renderer.layoutShiftScore': 0 },
+                        },
+                    },
+                },
+            ],
+            `run ${index + 1}`
+        )
+    );
+    const result = tighten(baselines, runs);
+    assert.deepEqual(
+        result.baselines.journeys['open-source']['renderer.layoutShiftScore'],
+        {
+            ...score,
+            value: 0.221,
+            updatedAt: '2026-10-05',
+            measuredWith:
+                '.github/workflows/performance-ratchet.yml, max of 3 runs',
+            evidenceRun: RUN_URL,
+        }
+    );
+    assert.deepEqual(
+        result.baselines.journeys.playback,
+        baselines.journeys.playback,
+        'a counter already at 0 is kept'
+    );
+    assert.match(
+        formatReport(result),
+        /\| `open-source\/renderer\.layoutShiftScore` \| 0\.222 score \| 0\.221 \| 0\.22 \| 0\.221 \| lowered to 0\.221 score \|/
+    );
+});
+
 test('one run at or above the value keeps the baseline untouched', () => {
     for (const measured of [1000, 1010]) {
         const baselines = baselinesFile();

From e998d7418a60d02af91dd4b9d17cf4cdf6d7f7c0 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 12:59:54 +0200
Subject: [PATCH 09/20] chore(deps): bump the actions-minor-patch group across
 1 directory with 2 updates (#1840)

* chore(deps): bump the actions-minor-patch group across 1 directory with 2 updates

Bumps the actions-minor-patch group with 2 updates in the / directory: [pnpm/action-setup](https://github.com/pnpm/action-setup) and [github/codeql-action](https://github.com/github/codeql-action).


Updates `pnpm/action-setup` from 6.0.10 to 6.1.0
- [Release notes](https://github.com/pnpm/action-setup/releases)
- [Commits](https://github.com/pnpm/action-setup/compare/v6.0.10...v6.1.0)

Updates `github/codeql-action` from 4.37.7 to 4.38.2
- [Release notes](https://github.com/github/codeql-action/releases)
- [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md)
- [Commits](https://github.com/github/codeql-action/compare/v4.37.7...v4.38.2)

---
updated-dependencies:
- dependency-name: github/codeql-action
  dependency-version: 4.38.2
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions-minor-patch
- dependency-name: pnpm/action-setup
  dependency-version: 6.1.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions-minor-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* test(packaging): allow pnpm/action-setup v6.1.0 in the Snap build workflow policy

The bump moves every workflow to pnpm/action-setup@v6.1.0; the build
workflow's allowlist pins the exact version and must move with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/build-and-make.yaml                 | 2 +-
 .github/workflows/ci.yml                              | 8 ++++----
 .github/workflows/codeql-analysis.yml                 | 4 ++--
 .github/workflows/deploy-website.yml                  | 2 +-
 .github/workflows/e2e-tests.yaml                      | 4 ++--
 .github/workflows/performance-ratchet.yml             | 2 +-
 tools/packaging/snap-workflow-policy.test-helpers.mjs | 2 +-
 7 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/build-and-make.yaml b/.github/workflows/build-and-make.yaml
index e31a370fc..3036c9153 100644
--- a/.github/workflows/build-and-make.yaml
+++ b/.github/workflows/build-and-make.yaml
@@ -416,7 +416,7 @@ jobs:
               uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 08f56981e..df41ce995 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -98,7 +98,7 @@ jobs:
                   fetch-depth: 0
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
@@ -140,7 +140,7 @@ jobs:
               uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
@@ -310,7 +310,7 @@ jobs:
               uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
@@ -377,7 +377,7 @@ jobs:
               uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml
index 74e397a8f..93a615c45 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -54,7 +54,7 @@ jobs:
     # commit checked out above (the modern default); JavaScript is
     # interpreted, so no build step is needed before analysis.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v4.37.7
+      uses: github/codeql-action/init@v4.38.2
       with:
         languages: ${{ matrix.language }}
         # Excludes the localhost dev/E2E mock servers from analysis; see the
@@ -66,4 +66,4 @@ jobs:
         # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v4.37.7
+      uses: github/codeql-action/analyze@v4.38.2
diff --git a/.github/workflows/deploy-website.yml b/.github/workflows/deploy-website.yml
index a8cf6f076..f6e7dec04 100644
--- a/.github/workflows/deploy-website.yml
+++ b/.github/workflows/deploy-website.yml
@@ -27,7 +27,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Install pnpm
-        uses: pnpm/action-setup@v6.0.10
+        uses: pnpm/action-setup@v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@v7
diff --git a/.github/workflows/e2e-tests.yaml b/.github/workflows/e2e-tests.yaml
index d3fb6874b..42bbd8f98 100644
--- a/.github/workflows/e2e-tests.yaml
+++ b/.github/workflows/e2e-tests.yaml
@@ -67,7 +67,7 @@ jobs:
             - uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
@@ -201,7 +201,7 @@ jobs:
             - uses: actions/checkout@v7
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
diff --git a/.github/workflows/performance-ratchet.yml b/.github/workflows/performance-ratchet.yml
index 2f77794bb..857240120 100644
--- a/.github/workflows/performance-ratchet.yml
+++ b/.github/workflows/performance-ratchet.yml
@@ -43,7 +43,7 @@ jobs:
                   persist-credentials: false
 
             - name: Install pnpm
-              uses: pnpm/action-setup@v6.0.10
+              uses: pnpm/action-setup@v6.1.0
 
             - name: Setup Node.js
               uses: actions/setup-node@v7
diff --git a/tools/packaging/snap-workflow-policy.test-helpers.mjs b/tools/packaging/snap-workflow-policy.test-helpers.mjs
index 28d9f5d84..f66e88544 100644
--- a/tools/packaging/snap-workflow-policy.test-helpers.mjs
+++ b/tools/packaging/snap-workflow-policy.test-helpers.mjs
@@ -72,7 +72,7 @@ const BUILD_ACTION_ALLOWLIST = Object.freeze([
     'actions/download-artifact@v8',
     'actions/setup-node@v7',
     'actions/upload-artifact@v7',
-    'pnpm/action-setup@v6.0.10',
+    'pnpm/action-setup@v6.1.0',
     'softprops/action-gh-release@v3',
 ]);
 const VERIFY_JOB_ID = 'verify-snap';

From d73bb7ca16bb7d2dfff49a96f0d9c41a86f4873f Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 13:00:33 +0200
Subject: [PATCH 10/20] chore(deps): bump shaka-player from 5.2.4 to 5.2.12
 (#1836)

* chore(deps): bump shaka-player from 5.2.4 to 5.2.12

Bumps [shaka-player](https://github.com/shaka-project/shaka-player) from 5.2.4 to 5.2.12.
- [Release notes](https://github.com/shaka-project/shaka-player/releases)
- [Changelog](https://github.com/shaka-project/shaka-player/blob/v5.2.12/CHANGELOG.md)
- [Commits](https://github.com/shaka-project/shaka-player/compare/v5.2.4...v5.2.12)

---
updated-dependencies:
- dependency-name: shaka-player
  dependency-version: 5.2.12
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* test(playback): accept the Shaka 5.2.12 error contract

5.2.12 keeps the public error severities, categories, codes and request
types of 5.2.4, so the version lock moves to v5.2.12 with the same
accepted contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/embedded-inline-playback.md |  2 +-
 docs/architecture/m3u-playlist-module.md      |  2 +-
 .../lib/diagnostics/shaka-error-contract.ts   |  6 +--
 .../shaka-playback-evidence.util.spec.ts      |  2 +-
 .../shaka-playback-evidence.util.ts           |  2 +-
 package.json                                  |  2 +-
 pnpm-lock.yaml                                | 41 ++++++++++++++-----
 7 files changed, 38 insertions(+), 19 deletions(-)

diff --git a/docs/architecture/embedded-inline-playback.md b/docs/architecture/embedded-inline-playback.md
index dca9795c3..3c19e5a58 100644
--- a/docs/architecture/embedded-inline-playback.md
+++ b/docs/architecture/embedded-inline-playback.md
@@ -695,7 +695,7 @@ external-player workflows; it is not copied from the HLS error payload into
 the evidence or technical details. HLS startup development logs are event-only:
 they do not include provider-supplied channel names or source URLs.
 
-Shaka Player `5.2.4` errors cross a separate structured boundary before the
+Shaka Player `5.2.12` errors cross a separate structured boundary before the
 HTML5 or ArtPlayer DASH session emits a diagnostic. Version-locked tests assert
 the installed Shaka version plus the public `Severity`, `Category`, and selected
 online-playback `Code` values used by the boundary. Evidence retains only
diff --git a/docs/architecture/m3u-playlist-module.md b/docs/architecture/m3u-playlist-module.md
index 585ec4245..011fd5760 100644
--- a/docs/architecture/m3u-playlist-module.md
+++ b/docs/architecture/m3u-playlist-module.md
@@ -1513,7 +1513,7 @@ does not change the saved player preference. Clear DASH needs this routing too.
   engine: lazy `import('shaka-player')` on first use (the module is a separate
   lazy chunk, ~217 KB transfer), `drm.clearKeys` configuration, an operation
   queue + generation guard against channel-switch races. The DOM-free Shaka
-  `5.2.4` public-error boundary lives in `libs/playback/util`; it version-locks
+  `5.2.12` public-error boundary lives in `libs/playback/util`; it version-locks
   its allowlisted
   severity/category/code values, emits only structured sanitized
   `PlaybackDiagnosticSource.Shaka` evidence, ignores recoverable error events,
diff --git a/libs/playback/util/src/lib/diagnostics/shaka-error-contract.ts b/libs/playback/util/src/lib/diagnostics/shaka-error-contract.ts
index 5624dc09c..82c2ff85f 100644
--- a/libs/playback/util/src/lib/diagnostics/shaka-error-contract.ts
+++ b/libs/playback/util/src/lib/diagnostics/shaka-error-contract.ts
@@ -1,10 +1,10 @@
 /**
- * Public Shaka error values audited against the locked 5.2.4 runtime.
+ * Public Shaka error values audited against the locked 5.2.12 runtime.
  *
  * Keep the version assertion in the contract spec: a Shaka upgrade must stop
  * here for a new audit instead of silently accepting new error layouts.
  */
-export const SHAKA_DIAGNOSTIC_VERSION = 'v5.2.4';
+export const SHAKA_DIAGNOSTIC_VERSION = 'v5.2.12';
 
 export const SHAKA_ERROR_SEVERITY = {
     RECOVERABLE: 1,
@@ -123,7 +123,7 @@ export const SHAKA_ERROR_CODE = {
     MISSING_EME_SUPPORT: 6020,
     LOAD_INTERRUPTED: 7000,
 } as const;
-/** Shaka 5.2.4 public NetworkingEngine request types used by diagnostics. */
+/** Shaka 5.2.12 public NetworkingEngine request types used by diagnostics. */
 export const SHAKA_REQUEST_TYPE = {
     MANIFEST: 0,
     SEGMENT: 1,
diff --git a/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.spec.ts b/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.spec.ts
index 2e0b61ca3..737e2b50b 100644
--- a/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.spec.ts
+++ b/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.spec.ts
@@ -65,7 +65,7 @@ describe('Shaka playback evidence', () => {
         }
     );
 
-    it('matches the installed public Shaka 5.2.4 error contract', () => {
+    it('matches the installed public Shaka 5.2.12 error contract', () => {
         const installed = getInstalledShakaContract();
         expect(installed.requestTypes).toEqual(
             expect.objectContaining(SHAKA_REQUEST_TYPE)
diff --git a/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.ts b/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.ts
index 33a3e345d..3a924778c 100644
--- a/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.ts
+++ b/libs/playback/util/src/lib/diagnostics/shaka-playback-evidence.util.ts
@@ -51,7 +51,7 @@ export function createShakaPlaybackEvidence(
     return httpStatus === undefined ? evidence : { ...evidence, httpStatus };
 }
 
-/** Public error.data request-type slots in Shaka 5.2.4; no URL inspection. */
+/** Public error.data request-type slots in Shaka 5.2.12; no URL inspection. */
 function getNetworkStage(error: Partial<ShakaErrorLike> | null | undefined) {
     if (
         error?.category !== SHAKA_ERROR_CATEGORY.NETWORK ||
diff --git a/package.json b/package.json
index 77a6d364f..6a3fe916a 100644
--- a/package.json
+++ b/package.json
@@ -149,7 +149,7 @@
         "proxy-from-env": "2.1.0",
         "rxjs": "7.8.2",
         "saxes": "6.0.0",
-        "shaka-player": "5.2.4",
+        "shaka-player": "5.2.12",
         "shell-path": "3.1.0",
         "video.js": "8.24.0",
         "videojs-contrib-quality-levels": "4.1.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 333c06d8b..93e5f04d4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -176,8 +176,8 @@ importers:
         specifier: 6.0.0
         version: 6.0.0
       shaka-player:
-        specifier: 5.2.4
-        version: 5.2.4
+        specifier: 5.2.12
+        version: 5.2.12
       shell-path:
         specifier: 3.1.0
         version: 3.1.0
@@ -1593,8 +1593,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@bufbuild/protobuf@2.15.0':
-    resolution: {integrity: sha512-DAheWUkVr/SJTWCc+lg9dhY0eN4SaWlf4+bG1KzHeXbnqt0AfB/NX0Z+VunGlM1ki1B4zVvye27MpKh/svySUA==}
+  '@bufbuild/protobuf@2.16.0':
+    resolution: {integrity: sha512-FWa0sPlqYGJgpTs6OxBRcL/AW4JT0OIO+W1ajerluoTVh8CV0B7XM1qsNCRgnkSCkRCgOICKHRQlY17jrsm0+Q==}
 
   '@capsizecss/unpack@4.0.0':
     resolution: {integrity: sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==}
@@ -6276,6 +6276,10 @@ packages:
     resolution: {integrity: sha512-EQsFzMUJkCKGr1ePqlYADkIUmHW1s3ZXr5Yqy6wbGrfUCphpl2maM/kyOIRA2HpP3AaFQTZXD4ldjek+nccddA==}
     engines: {node: '>=14.14'}
 
+  fs-extra@11.4.1:
+    resolution: {integrity: sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==}
+    engines: {node: '>=14.14'}
+
   fs-extra@7.0.1:
     resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==}
     engines: {node: '>=6 <7 || >=8'}
@@ -8848,8 +8852,9 @@ packages:
   setprototypeof@1.2.0:
     resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
 
-  shaka-player@5.2.4:
-    resolution: {integrity: sha512-vf81av2EIcb03jRpeeZBhrPT3PMyggXnZA9k4sxGBxpr/H6v0iEL6b51T2Kwz5YNrQG/yDYoadgBW+oW40LeoA==}
+  shaka-player@5.2.12:
+    resolution: {integrity: sha512-vEsuVDI3+oLh+yqpjXexQZlg2XMUBI0VrqatDuKWacPaxAud6Uph5uCowUPLhUgNG5XKWCpoM4l1r8qYzWH+zg==}
+    engines: {node: '>=18'}
 
   shallow-clone@3.0.1:
     resolution: {integrity: sha512-/6KqX+GVUdqPuPPd2LxDDxzX6CAbjJehAAOKlNpqqUpAqPM6HeL8f+o3a+JsyGjn2lv0WY8UsTgUJjU9Ok55NA==}
@@ -8947,6 +8952,10 @@ packages:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
+  source-map-js@1.2.2:
+    resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
+    engines: {node: '>=0.10.0'}
+
   source-map-support@0.5.19:
     resolution: {integrity: sha512-Wonm7zOCIJzBGQdB+thsPar0kYuCIzYvxZwlBa87yi/Mdjv7Tip2cyVbLj5o0cFPN4EVkuTwb3GDDyUx2DGnGw==}
 
@@ -11328,7 +11337,7 @@ snapshots:
   '@bruits/satteri-win32-x64-msvc@0.10.5':
     optional: true
 
-  '@bufbuild/protobuf@2.15.0':
+  '@bufbuild/protobuf@2.16.0':
     optional: true
 
   '@capsizecss/unpack@4.0.0':
@@ -11460,7 +11469,7 @@ snapshots:
     dependencies:
       cross-dirname: 0.1.0
       debug: 4.4.3(supports-color@7.2.0)
-      fs-extra: 11.4.0
+      fs-extra: 11.4.1
       minimist: 1.2.8
       postject: 1.0.0-alpha.6
     transitivePeerDependencies:
@@ -16032,6 +16041,13 @@ snapshots:
       jsonfile: 6.2.1
       universalify: 2.0.1
 
+  fs-extra@11.4.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.1
+      universalify: 2.0.1
+    optional: true
+
   fs-extra@7.0.1:
     dependencies:
       graceful-fs: 4.2.11
@@ -19385,7 +19401,7 @@ snapshots:
 
   sass-embedded@1.100.0:
     dependencies:
-      '@bufbuild/protobuf': 2.15.0
+      '@bufbuild/protobuf': 2.16.0
       colorjs.io: 0.5.2
       immutable: 5.1.9
       rxjs: 7.8.2
@@ -19417,7 +19433,7 @@ snapshots:
     dependencies:
       chokidar: 5.0.0
       immutable: 5.1.9
-      source-map-js: 1.2.1
+      source-map-js: 1.2.2
     optionalDependencies:
       '@parcel/watcher': 2.6.0
     optional: true
@@ -19543,7 +19559,7 @@ snapshots:
 
   setprototypeof@1.2.0: {}
 
-  shaka-player@5.2.4: {}
+  shaka-player@5.2.12: {}
 
   shallow-clone@3.0.1:
     dependencies:
@@ -19680,6 +19696,9 @@ snapshots:
 
   source-map-js@1.2.1: {}
 
+  source-map-js@1.2.2:
+    optional: true
+
   source-map-support@0.5.19:
     dependencies:
       buffer-from: 1.1.2

From e315467c2d2a3a3a28b209664ac62a3e3d8d48f1 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 13:56:12 +0200
Subject: [PATCH 11/20] test(perf): record which nodes move in a journey's
 layout shift (#1845)

* test(perf): record which nodes move in a journey's layout shift

J2's renderer.layoutShiftScore went from 0.222 to 0.233 with #1814, and
its evidence only held the recent-input / without-recent-input split, so
the moved element could not be named from a summary. The probe now keeps
the first 20 counted shifts (value, recent input, time since the journey
start and the moved nodes, as J1's late shifts do), and J2 writes them to
evidence.layoutShift.shifts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(perf): record the horizontal move of layout-shift sources

J2's 0.233 shift on the runner moves main.workspace-content, the header
search field and the header actions with deltaY and deltaHeight 0, so
the move is horizontal and the probe could not show it. Sources now also
carry deltaX and deltaWidth.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(perf): count every layout shift next to the capped list

Review follow-up (Greptile): the score counts every shift but the
evidence lists only the first 20, so a reader could not tell that later
shifts were omitted. The probe now keeps shiftCount, and J2 writes it
beside evidence.layoutShift.shifts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../journey-renderer-probe.spec.ts            | 30 ++++++++++++
 .../journey-renderer-probe.test-helpers.ts    |  4 +-
 .../src/performance/journey-renderer-probe.ts | 49 +++++++++++++++++--
 .../performance/launch-journey-record.spec.ts |  6 +++
 .../open-source-journey-record.spec.ts        | 35 +++++++++++++
 .../performance/open-source-journey-record.ts | 11 +++++
 .../playback-journey-record.spec.ts           |  2 +
 docs/architecture/performance-journeys.md     |  6 +--
 8 files changed, 133 insertions(+), 10 deletions(-)

diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.spec.ts b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.spec.ts
index c42b35f59..37f86d4d5 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.spec.ts
@@ -341,6 +341,8 @@ test('keeps summing shifts without recent input after the first-card cutoff unti
                 [
                     {
                         deltaHeight: 0,
+                        deltaWidth: 0,
+                        deltaX: 0,
                         deltaY: -240,
                         node: 'lib-dashboard-rail[data-test-id="dashboard-favorites-rail"]',
                     },
@@ -798,6 +800,13 @@ test('drops performance entries from before the click and keeps recent-input shi
         {
             entryType: 'layout-shift',
             hadRecentInput: true,
+            sources: [
+                {
+                    currentRect: { height: 40, width: 300, x: 48, y: 152 },
+                    node: fixture.card,
+                    previousRect: { height: 40, width: 320, x: 0, y: 100 },
+                },
+            ],
             startTime: now(),
             value: 0.25,
         },
@@ -823,6 +832,25 @@ test('drops performance entries from before the click and keeps recent-input shi
     assert.equal(state.final, true);
     assert.equal(state.counters.layoutShiftScore, 0.125);
     assert.equal(state.counters.recentInputLayoutShiftScore, 0.25);
+    // Each counted shift keeps its nodes; the pre-click ones are not listed.
+    assert.deepEqual(
+        state.shifts.map((shift) => [
+            shift.hadRecentInput,
+            shift.value,
+            shift.sources.map((source) => [
+                source.deltaX,
+                source.deltaY,
+                source.deltaWidth,
+            ]),
+        ]),
+        [
+            [true, 0.25, [[48, 52, -20]]],
+            [false, 0.125, []],
+        ]
+    );
+    assert.equal(state.shiftCount, 2);
+    assert.ok(state.shifts.every((shift) => shift.sinceStartMs >= 0));
+    assert.match(state.shifts[0]?.sources[0]?.node ?? '', /^[a-z-]+/);
     // J2 has no settle window: the observers close at the cutoff.
     assert.equal(state.settle.status, 'disabled');
     assert.equal(state.counters.layoutShiftScoreSettled, 0);
@@ -869,6 +897,8 @@ test('rejects a click start whose sentinel could not be sent', async () => {
     const started = {
         ...state,
         sentinel: { epochMs: 1, status: 'sent' as const },
+        shiftCount: 0,
+        shifts: [],
     };
     assert.throws(
         () => assertJourneyRendererProbeState(started),
diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.test-helpers.ts b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.test-helpers.ts
index 799aeeb48..3fcf9142f 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.test-helpers.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.test-helpers.ts
@@ -17,9 +17,9 @@ export interface FakeEntry {
     entryType: string;
     hadRecentInput?: boolean;
     sources?: {
-        currentRect: { height: number; y: number };
+        currentRect: { height: number; width?: number; x?: number; y: number };
         node: unknown;
-        previousRect: { height: number; y: number };
+        previousRect: { height: number; width?: number; x?: number; y: number };
     }[];
     startTime: number;
     value?: number;
diff --git a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.ts b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.ts
index 71a321a23..7ee9bac31 100644
--- a/apps/electron-backend-e2e/src/performance/journey-renderer-probe.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-renderer-probe.ts
@@ -166,12 +166,24 @@ export interface JourneyRendererProbeCounters {
     recentInputLayoutShiftScore: number;
 }
 
+/** A shift counted in `layoutShiftScore` or `recentInputLayoutShiftScore`. */
+export interface JourneyRendererProbeShift {
+    readonly hadRecentInput: boolean;
+    /** Entry start minus the journey start (navigation start for J1). */
+    readonly sinceStartMs: number;
+    /** `tag.class[data-test-id]` and the move of each source. */
+    readonly sources: JourneyRendererProbeLateShift['sources'];
+    readonly value: number;
+}
+
 export interface JourneyRendererProbeLateShift {
     /** Entry start minus the first-card terminal epoch. */
     readonly afterFirstCardMs: number;
-    /** `tag.class[data-test-id]` and the vertical move of each source. */
+    /** `tag.class[data-test-id]` and the move of each source. */
     readonly sources: readonly {
         readonly deltaHeight: number;
+        readonly deltaWidth: number;
+        readonly deltaX: number;
         readonly deltaY: number;
         readonly node: string;
     }[];
@@ -237,6 +249,13 @@ export interface JourneyRendererProbeState {
         readonly epochMs: number | null;
         readonly status: 'bridge-missing' | 'failed' | 'not-sent' | 'sent';
     };
+    /** Every shift counted until the cutoff; `shifts` keeps the first 20. */
+    shiftCount: number;
+    /**
+     * The first 20 shifts counted until the cutoff, with the nodes that
+     * moved, so a layout-shift score can be traced to its components.
+     */
+    shifts: JourneyRendererProbeShift[];
     /** `final` freezes the first-card counters; the settle window ends later. */
     settle: {
         /** Mutation records under the settle root after the cutoff. */
@@ -329,6 +348,8 @@ export function journeyRendererProbeScript(
         preStart: { domMutations: 0, lastMutationEpochMs: null },
         schemaVersion: 1,
         sentinel: { epochMs: null, status: 'not-sent' },
+        shiftCount: 0,
+        shifts: [],
         settle: {
             domMutations: 0,
             epochMs: null,
@@ -389,6 +410,7 @@ export function journeyRendererProbeScript(
         for (const entry of entries) {
             const shift = entry as PerformanceEntry & {
                 hadRecentInput?: boolean;
+                sources?: readonly LateShiftSource[];
                 value?: number;
             };
             if (
@@ -397,6 +419,18 @@ export function journeyRendererProbeScript(
             ) {
                 continue;
             }
+            state.shiftCount += 1;
+            if (state.shifts.length < 20) {
+                state.shifts.push({
+                    hadRecentInput: shift.hadRecentInput === true,
+                    sinceStartMs:
+                        performance.timeOrigin +
+                        entry.startTime -
+                        (state.start?.epochMs ?? performance.timeOrigin),
+                    sources: (shift.sources ?? []).map(describeSource),
+                    value: shift.value,
+                });
+            }
             if (shift.hadRecentInput === true) {
                 state.counters.recentInputLayoutShiftScore += shift.value;
                 continue;
@@ -530,10 +564,11 @@ export function journeyRendererProbeScript(
             state.idle.status = 'done';
         }, idle.durationMs);
     };
+    type ShiftRect = { height: number; width?: number; x?: number; y: number };
     type LateShiftSource = {
-        currentRect?: { height: number; y: number };
+        currentRect?: ShiftRect;
         node?: Node | null;
-        previousRect?: { height: number; y: number };
+        previousRect?: ShiftRect;
     };
     const describeSource = (source: LateShiftSource) => {
         const node = source.node;
@@ -550,9 +585,13 @@ export function journeyRendererProbeScript(
         }
         const before = source.previousRect;
         const after = source.currentRect;
+        const delta = (key: keyof ShiftRect) =>
+            before && after ? (after[key] ?? 0) - (before[key] ?? 0) : 0;
         return {
-            deltaHeight: before && after ? after.height - before.height : 0,
-            deltaY: before && after ? after.y - before.y : 0,
+            deltaHeight: delta('height'),
+            deltaWidth: delta('width'),
+            deltaX: delta('x'),
+            deltaY: delta('y'),
             node: label,
         };
     };
diff --git a/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts b/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
index f2084d099..b5123cd3b 100644
--- a/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/launch-journey-record.spec.ts
@@ -54,6 +54,8 @@ function measurement(
         preStart: { domMutations: 0, lastMutationEpochMs: null },
         schemaVersion: 1,
         sentinel: { epochMs: 2_601, status: 'sent' },
+        shiftCount: 0,
+        shifts: [],
         settle: {
             domMutations: 37,
             epochMs: 3_180.06,
@@ -64,6 +66,8 @@ function measurement(
                     sources: [
                         {
                             deltaHeight: 0,
+                            deltaWidth: 0,
+                            deltaX: 0,
                             deltaY: -240,
                             node: 'section.dashboard-rail',
                         },
@@ -210,6 +214,8 @@ test('maps the probe, IPC capture and main counters to exact counters and spawn-
                 sources: [
                     {
                         deltaHeight: 0,
+                        deltaWidth: 0,
+                        deltaX: 0,
                         deltaY: -240,
                         node: 'section.dashboard-rail',
                     },
diff --git a/apps/electron-backend-e2e/src/performance/open-source-journey-record.spec.ts b/apps/electron-backend-e2e/src/performance/open-source-journey-record.spec.ts
index 95cb2fb4d..f17f7b390 100644
--- a/apps/electron-backend-e2e/src/performance/open-source-journey-record.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/open-source-journey-record.spec.ts
@@ -59,6 +59,23 @@ function measurement(
         preStart: { domMutations: 4, lastMutationEpochMs: 9_100 },
         schemaVersion: 1,
         sentinel: { epochMs: 10_080.5, status: 'sent' },
+        shiftCount: 23,
+        shifts: [
+            {
+                hadRecentInput: true,
+                sinceStartMs: 41.26,
+                sources: [
+                    {
+                        deltaHeight: 0,
+                        deltaWidth: 0,
+                        deltaX: 0,
+                        deltaY: 52,
+                        node: 'div.content[data-test-id="category-list"]',
+                    },
+                ],
+                value: 0.22106,
+            },
+        ],
         settle: {
             domMutations: 0,
             epochMs: null,
@@ -147,6 +164,24 @@ test('maps the click-started probe, IPC window and mock ledger to exact counters
     });
     assert.deepEqual(record.evidence['layoutShift'], {
         recentInput: 0.221,
+        // More shifts were counted than listed.
+        shiftCount: 23,
+        shifts: [
+            {
+                hadRecentInput: true,
+                sinceStartMs: 41.3,
+                sources: [
+                    {
+                        deltaHeight: 0,
+                        deltaWidth: 0,
+                        deltaX: 0,
+                        deltaY: 52,
+                        node: 'div.content[data-test-id="category-list"]',
+                    },
+                ],
+                value: 0.2211,
+            },
+        ],
         withoutRecentInput: 0,
     });
     assert.deepEqual(record.evidence['httpRequestsByRoute'], {
diff --git a/apps/electron-backend-e2e/src/performance/open-source-journey-record.ts b/apps/electron-backend-e2e/src/performance/open-source-journey-record.ts
index 4d68bdcaa..ef9e61403 100644
--- a/apps/electron-backend-e2e/src/performance/open-source-journey-record.ts
+++ b/apps/electron-backend-e2e/src/performance/open-source-journey-record.ts
@@ -184,6 +184,17 @@ export function toOpenSourceIterationRecord(
                 recentInput: roundThousandth(
                     renderer.counters.recentInputLayoutShiftScore
                 ),
+                // Every counted shift; `shifts` lists the first 20.
+                shiftCount: renderer.shiftCount,
+                // The first 20 counted shifts and the nodes that moved.
+                shifts: renderer.shifts.map((shift) =>
+                    Object.freeze({
+                        hadRecentInput: shift.hadRecentInput,
+                        sinceStartMs: roundTenth(shift.sinceStartMs),
+                        sources: shift.sources,
+                        value: Math.round(shift.value * 10_000) / 10_000,
+                    })
+                ),
                 withoutRecentInput: roundThousandth(
                     renderer.counters.layoutShiftScore
                 ),
diff --git a/apps/electron-backend-e2e/src/performance/playback-journey-record.spec.ts b/apps/electron-backend-e2e/src/performance/playback-journey-record.spec.ts
index ee228c1c8..2b4246025 100644
--- a/apps/electron-backend-e2e/src/performance/playback-journey-record.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/playback-journey-record.spec.ts
@@ -74,6 +74,8 @@ function measurement(
         preStart: { domMutations: 53, lastMutationEpochMs: 8_900 },
         schemaVersion: 1,
         sentinel: { epochMs: 10_350, status: 'sent' },
+        shiftCount: 0,
+        shifts: [],
         settle: {
             domMutations: 0,
             epochMs: null,
diff --git a/docs/architecture/performance-journeys.md b/docs/architecture/performance-journeys.md
index d16fb4f50..dfb8a2824 100644
--- a/docs/architecture/performance-journeys.md
+++ b/docs/architecture/performance-journeys.md
@@ -175,8 +175,8 @@ closed or closed before the cutoff. J2's probe has no settle window
 most 20): the time after the first card, the value and, for each source the
 browser attributes the shift to, the node (`tag.class[data-test-id]`; a
 component host such as `lib-dashboard-rail` takes its first child's test id)
-and its vertical move. A late shift can therefore be traced to its component
-from the summary alone.
+and its move (`deltaX`, `deltaY`, `deltaWidth`, `deltaHeight`). A late shift
+can therefore be traced to its component from the summary alone.
 
 First local measurement (macOS, 2026-09-29, `master` with #1738): all
 windows closed on `quiet`, `renderer.layoutShiftScore` stayed 0, and
@@ -719,7 +719,7 @@ strings and stream paths carry credentials and are never stored.
 | `renderer.ipcCallsToFirstPage`     | Bridge `start` trace events between the start and end sentinels, counted by a second `journey-main-ipc-capture.ts` instance installed with `startSentinelId`. Calls before the start marker are tallied separately (`callsBeforeStart`); a start marker that is missing, repeated or received after the end sentinel fails the iteration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `renderer.domMutationsToFirstPage` | `MutationRecord`s from the click until the terminal batch. Records produced before the click (hover, settling) are taken from the observer at the start and counted under `evidence.settle` instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `renderer.cdTicksToFirstPage`      | `ApplicationRef` ticks from the click until the terminal batch: the counter's running total read in the capture-phase click listener, before the app handles the click, subtracted from its value at the terminal batch (see [Change-detection ticks](#change-detection-ticks)). |
-| `renderer.layoutShiftScore`        | Sum of all `layout-shift` entries from the click until the post-paint cutoff, rounded to three decimals. Unlike J1 it includes entries with `hadRecentInput === true`: the journey is a response to the click and runs inside the 500 ms input window, so the CLS filter would always read 0. The split is under `evidence.layoutShift`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `renderer.layoutShiftScore`        | Sum of all `layout-shift` entries from the click until the post-paint cutoff, rounded to three decimals. Unlike J1 it includes entries with `hadRecentInput === true`: the journey is a response to the click and runs inside the 500 ms input window, so the CLS filter would always read 0. The split is under `evidence.layoutShift`, and `evidence.layoutShift.shifts` lists the first 20 counted shifts (`shiftCount` is the total) with their value, `hadRecentInput`, time since the click and the nodes that moved (`tag.class[data-test-id]` and their `deltaX`, `deltaY`, `deltaWidth` and `deltaHeight`, as J1's late shifts).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `renderer.longTasks`               | `longtask` entries over 50 ms whose time range overlaps the window from the click to the cutoff. The task that dispatches the click began before the event's timestamp and still counts; buffered J1 tasks that ended before the click are dropped. Evidence until it is shown to be stable on the CI runner, as for J1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `main.mockHttpRequestsToSettled`   | Requests the proxy received from the click until, after the terminal batch, no new request had arrived for 1 s and none was in flight (a response slower than that, and what it triggers, stays inside the window). The window ends at the ledger position read by that accepted quiet sample; a request arriving after it was never seen in flight, so it goes to `evidence.httpRequestsAfterSettledByRoute` instead of the counter. The ledger is read 1 s after that sample, so that late traffic is actually observed. The window starts at the renderer's click stamp, the same boundary as every other J2 counter, not when Playwright began its actionability checks; the proxy stamps requests with the test process's wall clock, and both processes read the same host clock. Bounding by the terminal would compare the test process's clock with the renderer's, so the count up to the terminal epoch is evidence only (`evidence.httpRequestsToFirstPage`); `evidence.httpRequestsByRoute` names the requests. |
 

From 3cc5af14926c6403e1fe6b2538f2b66f1d5babee Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 14:12:52 +0200
Subject: [PATCH 12/20] perf(playback): make the web players and M3U player
 OnPush (#1822)

* perf(playback): make the web players and M3U player OnPush

Plan item C6 step 3 for playback: the eight Eager components in
libs/ui/playback (video.js, ArtPlayer, HTML5/hls/mpegts, audio player,
web player view, VOD details, sidebar, external-player dialog) and the M3U
video player and VOD detail switch to OnPush. The player libraries' events
already reach the UI through the signal-backed controls adapter or
outputs, and the players' DOM belongs to the libraries.

The M3U video player rendered three plain fields written outside template
events: the channel-number overlay, cleared by a 2 s debounce timer, and
the player choice, written from an IndexedDB read and a settings effect.
They are signals now, and a test checks that the overlay leaves the DOM
when the timer fires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(playback): let the overlay's signal write schedule its own render

Review follow-up (Greptile): the test forced a render with
fixture.detectChanges() after the debounce timer, so it would pass even
if the signal write stopped scheduling an OnPush render. It now runs the
fixture with autoDetectChanges and only advances the fake timers; with
plain fields under OnPush the overlay never renders and the test fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/zoneless-migration.md       | 26 ++++++-------
 .../m3u-vod-detail.component.ts               |  2 +-
 ...-player.component.fullscreen-panel.spec.ts | 37 +++++++++++++++++--
 .../video-player/video-player.component.html  |  8 ++--
 .../video-player/video-player.component.ts    | 34 +++++++++--------
 .../lib/art-player/art-player.component.ts    |  2 +-
 .../audio-player/audio-player.component.ts    |  2 +-
 .../external-player-info-dialog.component.ts  |  2 +-
 .../html-video-player.component.ts            |  2 +-
 .../video-player/sidebar/sidebar.component.ts |  2 +-
 .../lib/vjs-player/vjs-player.component.ts    |  2 +-
 .../lib/vod-details/vod-details.component.ts  |  2 +-
 .../web-player-view.component.ts              |  2 +-
 13 files changed, 78 insertions(+), 45 deletions(-)

diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 84fdb1ede..63e70d481 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -97,14 +97,14 @@ files that still contain `ChangeDetectionStrategy.Eager`.
 - [x] `libs/ui/epg/src/lib/epg-progress-panel/epg-progress-panel.component.ts` (idle audit root; also `EpgTrustConfirmDialogComponent`)
 - [x] `libs/ui/epg/src/lib/epg-source-status/epg-source-status.component.ts`
 - [ ] `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` (`apps/remote-control-web` only)
-- [ ] `libs/ui/playback/src/lib/art-player/art-player.component.ts`
-- [ ] `libs/ui/playback/src/lib/audio-player/audio-player.component.ts`
-- [ ] `libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts`
-- [ ] `libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts`
-- [ ] `libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts`
-- [ ] `libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts`
-- [ ] `libs/ui/playback/src/lib/vod-details/vod-details.component.ts`
-- [ ] `libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts`
+- [x] `libs/ui/playback/src/lib/art-player/art-player.component.ts`
+- [x] `libs/ui/playback/src/lib/audio-player/audio-player.component.ts`
+- [x] `libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts`
+- [x] `libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts`
+- [x] `libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts`
+- [x] `libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts`
+- [x] `libs/ui/playback/src/lib/vod-details/vod-details.component.ts`
+- [x] `libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts`
 
 `libs/ui/playback` (8) goes with the playback PR, not the `libs/ui` one.
 
@@ -131,8 +131,8 @@ files that still contain `ChangeDetectionStrategy.Eager`.
 - [ ] `libs/playlist/import/feature/src/lib/text-import/text-import.component.ts`
 - [ ] `libs/playlist/import/feature/src/lib/url-upload/url-upload.component.ts`
 - [ ] `libs/playlist/import/feature/src/lib/xtream-code-import/xtream-code-import.component.ts`
-- [ ] `libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts`
-- [ ] `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts`
+- [x] `libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts`
+- [x] `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts`
 - [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/empty-state/empty-state.component.ts`
 - [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-info/playlist-info.component.ts`
 - [ ] `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-item/playlist-item.component.ts`
@@ -168,8 +168,8 @@ the field a signal (or a `computed`), or writes it through one.
 
 | Done | Site | What depends on the zone | Owning PR |
 | --- | --- | --- | --- |
-| [ ] | `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts` `onChannelNumberInput`/`clearChannelNumberInput` | 2 s `window.setTimeout` hides the channel-number overlay through plain `showChannelNumberOverlay`/`channelNumberInput` | playback |
-| [ ] | same file, `applySettings` and the settings `effect()` | IndexedDB `storage.get(...).subscribe` and an effect assign plain `playerSettings`, which picks the player in the template | playback |
+| [x] | `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts` `onChannelNumberInput`/`clearChannelNumberInput` | 2 s `window.setTimeout` hides the channel-number overlay through plain `showChannelNumberOverlay`/`channelNumberInput` | playback |
+| [x] | same file, `applySettings` and the settings `effect()` | IndexedDB `storage.get(...).subscribe` and an effect assign plain `playerSettings`, which picks the player in the template | playback |
 | [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-item/playlist-item.component.ts` `checkPortalStatus` | plain `portalStatus` assigned after `await` in `ngOnInit` (PWA only: skipped when source health is supported) | playlist |
 | [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-info/playlist-info.component.ts` (EPG clear and EPG file pick handlers) | plain `playlist` reassigned after `await` | playlist |
 | [ ] | `libs/playlist/import/feature/src/lib/stalker-portal-import/stalker-portal-import.component.ts` (device-id derivation) | `form.patchValue` after `await`; template getters read `control.value`, which is not signal-backed | playlist |
@@ -188,7 +188,7 @@ before: with zone.js on they still matter.
 - [ ] `apps/web/src/app/settings/settings-unload-guard.service.ts`: two
   `zone.run` calls around the window-close dialog (IPC
   `onWindowCloseRequested` and `beforeunload`).
-- [ ] `libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts`:
+- [x] `libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts`:
   `runOutsideAngular(() => setInterval(...))` for the position poll;
   `embedded-mpv-session-controller.position.spec.ts` asserts the call and
   changes with it.
diff --git a/libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts b/libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts
index cd5b6adb8..c5d7fcb18 100644
--- a/libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts
+++ b/libs/playlist/m3u/feature-player/src/lib/m3u-vod-detail/m3u-vod-detail.component.ts
@@ -71,7 +71,7 @@ import {
         TranslatePipe,
     ],
     templateUrl: './m3u-vod-detail.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrls: ['./m3u-vod-detail.component.scss'],
 })
 export class M3uVodDetailComponent {
diff --git a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.fullscreen-panel.spec.ts b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.fullscreen-panel.spec.ts
index d8ebfef71..72af02b4e 100644
--- a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.fullscreen-panel.spec.ts
+++ b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.fullscreen-panel.spec.ts
@@ -231,8 +231,12 @@ describe('VideoPlayerComponent fullscreen channel panel + zapping', () => {
             .overrideComponent(VideoPlayerComponent, {
                 set: {
                     imports: [],
-                    template:
-                        '<ng-template #fullscreenChannelPanel></ng-template>',
+                    // The real template's channel-number overlay, so the
+                    // OnPush timer test below can read the rendered state.
+                    template: `<ng-template #fullscreenChannelPanel></ng-template>
+                        @if (showChannelNumberOverlay()) {
+                            <div class="channel-number-overlay">{{ channelNumberInput() }}</div>
+                        }`,
                 },
             })
             .compileComponents();
@@ -247,6 +251,33 @@ describe('VideoPlayerComponent fullscreen channel panel + zapping', () => {
         fixture.destroy();
     });
 
+    // OnPush: the overlay hides from a 2 s timer, outside any template
+    // event, so the signal write itself must schedule the render. The test
+    // never forces one after the timer: a plain-field write would leave the
+    // overlay in the DOM.
+    it('hides the channel-number overlay when its debounce fires', async () => {
+        jest.useFakeTimers();
+        try {
+            const overlay = () =>
+                (fixture.nativeElement as HTMLElement).querySelector(
+                    '.channel-number-overlay'
+                );
+            fixture.autoDetectChanges();
+            component.handleChannelNumberInput('2');
+            await jest.advanceTimersByTimeAsync(50);
+            expect(overlay()?.textContent).toBe('2');
+
+            await jest.advanceTimersByTimeAsync(2000);
+
+            expect(overlay()).toBeNull();
+            expect(storeMock.dispatch).toHaveBeenCalledWith(
+                setActiveChannelDispatch(nextChannel)
+            );
+        } finally {
+            jest.useRealTimers();
+        }
+    });
+
     describe('FULLSCREEN_CHANNEL_PANEL host', () => {
         it.each([VideoPlayer.MPV, VideoPlayer.VLC])(
             'withholds rows that would leave forced-inline DASH for %s',
@@ -260,7 +291,7 @@ describe('VideoPlayerComponent fullscreen channel panel + zapping', () => {
                     url: 'http://localhost/next.mpd',
                 };
                 player.set(externalPlayer);
-                component.playerSettings.player = externalPlayer;
+                component.playerSettings.set({ player: externalPlayer });
                 setActive(dashChannel);
                 channels.set([dashChannel, sampleChannel, nextDashChannel]);
 
diff --git a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.html b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.html
index 481352fc8..274f29958 100644
--- a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.html
+++ b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.html
@@ -85,7 +85,7 @@
                 [playbackSessionKey]="playbackSessionKey()"
                 [inlinePlayerAvailable]="shouldShowInlinePlayer(activeChannel)"
                 [volume]="volume()"
-                [playerOverride]="playerSettings.player ?? null"
+                [playerOverride]="playerSettings().player ?? null"
                 (playbackStarted)="refreshVolumeFromBus()"
                 (externalFallbackRequested)="
                     handleExternalFallbackRequest($event)
@@ -124,7 +124,7 @@
                             [playerOverride]="
                                 activeChannelIsDash()
                                     ? dashPlayerOverride()
-                                    : (playerSettings.player ?? null)
+                                    : (playerSettings().player ?? null)
                             "
                             [volume]="volume()"
                             [timelineSegments]="catchupTimelineSegments()"
@@ -255,10 +255,10 @@
             }
         }
 
-        @if (showChannelNumberOverlay) {
+        @if (showChannelNumberOverlay()) {
             <div class="channel-number-overlay">
                 <div class="channel-number-display">
-                    {{ channelNumberInput }}
+                    {{ channelNumberInput() }}
                 </div>
             </div>
         }
diff --git a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts
index e10c4f119..592f5bd55 100644
--- a/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts
+++ b/libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.ts
@@ -231,7 +231,7 @@ function isInsideScrollableRegion(
         { provide: EPG_GUIDE_SOURCE, useExisting: M3uEpgGuideSourceService },
     ],
     templateUrl: './video-player.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './video-player.component.scss',
 })
 export class VideoPlayerComponent
@@ -713,9 +713,9 @@ export class VideoPlayerComponent
     );
 
     /** Selected video player options */
-    playerSettings: Partial<Settings> = {
+    readonly playerSettings = signal<Partial<Settings>>({
         player: VideoPlayer.VideoJs,
-    };
+    });
 
     readonly isDesktop = this.runtime.isElectron;
     readonly supportsEpg = this.runtime.supportsEpg;
@@ -731,8 +731,8 @@ export class VideoPlayerComponent
     );
 
     /** Channel number input state */
-    channelNumberInput = '';
-    showChannelNumberOverlay = false;
+    readonly channelNumberInput = signal('');
+    readonly showChannelNumberOverlay = signal(false);
     private channelNumberTimeout?: number;
 
     /**
@@ -795,9 +795,9 @@ export class VideoPlayerComponent
 
         // React to settings changes
         effect(() => {
-            this.playerSettings = {
+            this.playerSettings.set({
                 player: this.settingsStore.player(),
-            };
+            });
         });
 
         // Keep "now" fresh so EPG state re-evaluates over time.
@@ -1191,10 +1191,10 @@ export class VideoPlayerComponent
     applySettings(): void {
         this.storage.get(STORE_KEY.Settings).subscribe((settings: unknown) => {
             if (settings && Object.keys(settings as Settings).length > 0) {
-                this.playerSettings = {
+                this.playerSettings.set({
                     player:
                         (settings as Settings).player || VideoPlayer.VideoJs,
-                };
+                });
             }
         });
     }
@@ -1472,12 +1472,14 @@ export class VideoPlayerComponent
         }
 
         // Add digit to current input
-        this.channelNumberInput += digit;
-        this.showChannelNumberOverlay = true;
+        this.channelNumberInput.update((input) => input + digit);
+        this.showChannelNumberOverlay.set(true);
 
         // Set timeout to switch channel after 2 seconds of no input
         this.channelNumberTimeout = window.setTimeout(() => {
-            this.switchToChannelByNumber(parseInt(this.channelNumberInput, 10));
+            this.switchToChannelByNumber(
+                parseInt(this.channelNumberInput(), 10)
+            );
             this.clearChannelNumberInput();
         }, 2000);
     }
@@ -1547,8 +1549,8 @@ export class VideoPlayerComponent
      * Clear channel number input and hide overlay
      */
     clearChannelNumberInput(): void {
-        this.channelNumberInput = '';
-        this.showChannelNumberOverlay = false;
+        this.channelNumberInput.set('');
+        this.showChannelNumberOverlay.set(false);
         if (this.channelNumberTimeout) {
             clearTimeout(this.channelNumberTimeout);
             this.channelNumberTimeout = undefined;
@@ -1663,7 +1665,7 @@ export class VideoPlayerComponent
             return true;
         }
 
-        const player = this.playerSettings.player;
+        const player = this.playerSettings().player;
         return (
             !this.isExternalPlayer(player) && player !== VideoPlayer.EmbeddedMpv
         );
@@ -1685,7 +1687,7 @@ export class VideoPlayerComponent
             return true;
         }
 
-        return !this.isExternalPlayer(this.playerSettings.player);
+        return !this.isExternalPlayer(this.playerSettings().player);
     }
 
     handleExternalFallbackRequest(request: PlaybackFallbackRequest): void {
diff --git a/libs/ui/playback/src/lib/art-player/art-player.component.ts b/libs/ui/playback/src/lib/art-player/art-player.component.ts
index 208b36c4f..5710777a8 100644
--- a/libs/ui/playback/src/lib/art-player/art-player.component.ts
+++ b/libs/ui/playback/src/lib/art-player/art-player.component.ts
@@ -51,7 +51,7 @@ Artplayer.AUTO_PLAYBACK_TIMEOUT = 10000;
     ],
     providers: [WebVideoControlsAdapter],
     templateUrl: './art-player.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrls: ['./art-player.component.scss'],
 })
 export class ArtPlayerComponent implements OnInit, OnDestroy, OnChanges {
diff --git a/libs/ui/playback/src/lib/audio-player/audio-player.component.ts b/libs/ui/playback/src/lib/audio-player/audio-player.component.ts
index 34469d51a..b8464d100 100644
--- a/libs/ui/playback/src/lib/audio-player/audio-player.component.ts
+++ b/libs/ui/playback/src/lib/audio-player/audio-player.component.ts
@@ -167,7 +167,7 @@ import { PlaybackHistoryConfirmation } from '../playback-history/playback-histor
         </div>
     `,
     styleUrls: ['./audio-player.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         FormsModule,
         MatButtonModule,
diff --git a/libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts b/libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts
index f9e3ab956..415a2ab28 100644
--- a/libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts
+++ b/libs/ui/playback/src/lib/external-player-info-dialog/external-player-info-dialog.component.ts
@@ -57,7 +57,7 @@ import { TranslateModule } from '@ngx-translate/core';
             }
         `,
     ],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         MatButtonModule,
         MatCheckboxModule,
diff --git a/libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts b/libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts
index a0384a293..924e72e07 100644
--- a/libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts
+++ b/libs/ui/playback/src/lib/html-video-player/html-video-player.component.ts
@@ -71,7 +71,7 @@ const debugHtmlPlayer = createDevLogger('HtmlVideoPlayer');
         SeriesPlaybackNavigationControlsComponent,
     ],
     providers: [WebVideoControlsAdapter],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     standalone: true,
 })
 export class HtmlVideoPlayerComponent implements OnInit, OnChanges, OnDestroy {
diff --git a/libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts b/libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts
index 3e2cc0cfe..3f97a4dbe 100644
--- a/libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts
+++ b/libs/ui/playback/src/lib/video-player/sidebar/sidebar.component.ts
@@ -20,7 +20,7 @@ import { ChannelListContainerComponent } from '@iptvnator/ui/components';
     selector: 'app-sidebar',
     templateUrl: './sidebar.component.html',
     styleUrls: ['./sidebar.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         ChannelListContainerComponent,
         MatIcon,
diff --git a/libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts b/libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts
index 6770f466e..2996a44cc 100644
--- a/libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts
+++ b/libs/ui/playback/src/lib/vjs-player/vjs-player.component.ts
@@ -66,7 +66,7 @@ const debugVjsPlayer = createDevLogger('VjsPlayer');
         SeriesPlaybackNavigationControlsComponent,
     ],
     providers: [WebVideoControlsAdapter],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     standalone: true,
 })
 export class VjsPlayerComponent implements OnInit, OnChanges, OnDestroy {
diff --git a/libs/ui/playback/src/lib/vod-details/vod-details.component.ts b/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
index 4d3b658e2..9e4e4f49f 100644
--- a/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
+++ b/libs/ui/playback/src/lib/vod-details/vod-details.component.ts
@@ -82,7 +82,7 @@ import { createVodSimilarInPortals } from './vod-similar-in-portals.state';
     selector: 'app-vod-details',
     templateUrl: './vod-details.component.html',
     styleUrls: ['../styles/detail-view.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         CastCrewRowComponent,
         DetailActionButtonComponent,
diff --git a/libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts b/libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts
index a1c55b8f9..ab0ee9aff 100644
--- a/libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts
+++ b/libs/ui/playback/src/lib/web-player-view/web-player-view.component.ts
@@ -91,7 +91,7 @@ import { resolveWebPlayerSharedControls } from './web-player-shared-controls';
             useFactory: resolveWebPlayerSharedControls,
         },
     ],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     encapsulation: ViewEncapsulation.None,
 })
 export class WebPlayerViewComponent implements OnDestroy {

From 2e321cb1bd772d80e9c8b1c6089a1c634bff1e6e Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 14:20:13 +0200
Subject: [PATCH 13/20] chore(deps): bump mpegts.js from 1.8.1 to 1.8.2 (#1835)

* chore(deps): bump mpegts.js from 1.8.1 to 1.8.2

Bumps [mpegts.js](https://github.com/xqq/mpegts.js) from 1.8.1 to 1.8.2.
- [Release notes](https://github.com/xqq/mpegts.js/releases)
- [Commits](https://github.com/xqq/mpegts.js/compare/v1.8.1...v1.8.2)

---
updated-dependencies:
- dependency-name: mpegts.js
  dependency-version: 1.8.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>

* test(playback): accept the mpegts.js 1.8.2 error contract

1.8.2 keeps the public ErrorTypes and ErrorDetails exports unchanged, so
the version lock moves to 1.8.2 with the same accepted contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/embedded-inline-playback.md         |  2 +-
 .../diagnostics/mpegts-playback-evidence.util.spec.ts |  2 +-
 .../lib/diagnostics/mpegts-playback-evidence.util.ts  |  2 +-
 package.json                                          |  2 +-
 pnpm-lock.yaml                                        | 11 +++++------
 5 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/architecture/embedded-inline-playback.md b/docs/architecture/embedded-inline-playback.md
index 3c19e5a58..8f98857af 100644
--- a/docs/architecture/embedded-inline-playback.md
+++ b/docs/architecture/embedded-inline-playback.md
@@ -749,7 +749,7 @@ allowlisted display name.
 
 `network-error` is reserved for provider/network loading failures. Engines that expose concrete browser security evidence, such as CORS, mixed content, Content Security Policy, or private-network-access blocks, use `browser-access-error` so the UI can explain that the browser player was blocked before playback reached decoding.
 
-mpegts.js `1.8.1` errors cross one shared structured boundary before the HTML5,
+mpegts.js `1.8.2` errors cross one shared structured boundary before the HTML5,
 Video.js, or ArtPlayer owner emits a diagnostic. Version-locked tests compare
 the installed public `ErrorTypes` and `ErrorDetails` exports with the accepted
 contract. Evidence retains only an exact type/detail pair, terminal
diff --git a/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.spec.ts b/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.spec.ts
index 4c9613bc7..d225076ed 100644
--- a/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.spec.ts
+++ b/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.spec.ts
@@ -21,7 +21,7 @@ const METADATA = createPlaybackSourceMetadata({
 });
 
 describe('mpegts.js playback evidence', () => {
-    it('locks the accepted public contract to mpegts.js 1.8.1', () => {
+    it('locks the accepted public contract to mpegts.js 1.8.2', () => {
         expect(mpegts.version).toBe(MPEGTS_DIAGNOSTIC_VERSION);
         expect(mpegts.ErrorTypes).toEqual({
             NETWORK_ERROR: MpegTsPlaybackEngineType.Network,
diff --git a/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.ts b/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.ts
index e09a80088..dbae7fe68 100644
--- a/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.ts
+++ b/libs/playback/util/src/lib/diagnostics/mpegts-playback-evidence.util.ts
@@ -11,7 +11,7 @@ import {
     MpegTsPlaybackStage,
 } from './mpegts-playback-evidence.model';
 
-export const MPEGTS_DIAGNOSTIC_VERSION = '1.8.1';
+export const MPEGTS_DIAGNOSTIC_VERSION = '1.8.2';
 
 interface MpegTsPlaybackCause {
     readonly stage: MpegTsPlaybackStageValue;
diff --git a/package.json b/package.json
index 6a3fe916a..406ec03df 100644
--- a/package.json
+++ b/package.json
@@ -142,7 +142,7 @@
         "hls.js": "1.7.1",
         "iptv-playlist-parser": "github:4gray/iptv-playlist-parser#v0.15.2-iptvnator.2",
         "marked": "18.0.11",
-        "mpegts.js": "1.8.1",
+        "mpegts.js": "1.8.2",
         "ms": "2.1.3",
         "ngx-indexed-db": "22.0.0",
         "ngx-skeleton-loader": "11.3.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 93e5f04d4..244eb6e6a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -155,8 +155,8 @@ importers:
         specifier: 18.0.11
         version: 18.0.11
       mpegts.js:
-        specifier: 1.8.1
-        version: 1.8.1
+        specifier: 1.8.2
+        version: 1.8.2
       ms:
         specifier: 2.1.3
         version: 2.1.3
@@ -7701,8 +7701,8 @@ packages:
     resolution: {integrity: sha512-blbA7XpAaOdC/PR0Tu8GiUxlx6CpBuRowQPYV7lhi9Yr9G9+dkPXIUjqjzc/NCn/uZZPopluaJlIYntIEI/VLw==}
     hasBin: true
 
-  mpegts.js@1.8.1:
-    resolution: {integrity: sha512-mQ2daxqBaS+QmBYTmJMDUGwAOw08534b08KSyqUGkjkhuBODNod15j8pnRfVEIQVWulKNe201/6UqILe4m4YRQ==}
+  mpegts.js@1.8.2:
+    resolution: {integrity: sha512-cZYMa5muASH55wrS6JK5IGkUqnCA96c0f+WdnW91jIK9s/N6NzjmTQDJNYg9A5u/G2Q5nj2b3w1Zwzze/9guxA==}
     engines: {node: '>=20.9.0'}
 
   mrmime@2.0.1:
@@ -8854,7 +8854,6 @@ packages:
 
   shaka-player@5.2.12:
     resolution: {integrity: sha512-vEsuVDI3+oLh+yqpjXexQZlg2XMUBI0VrqatDuKWacPaxAud6Uph5uCowUPLhUgNG5XKWCpoM4l1r8qYzWH+zg==}
-    engines: {node: '>=18'}
 
   shallow-clone@3.0.1:
     resolution: {integrity: sha512-/6KqX+GVUdqPuPPd2LxDDxzX6CAbjJehAAOKlNpqqUpAqPM6HeL8f+o3a+JsyGjn2lv0WY8UsTgUJjU9Ok55NA==}
@@ -18064,7 +18063,7 @@ snapshots:
       '@xmldom/xmldom': 0.8.15
       global: 4.4.0
 
-  mpegts.js@1.8.1:
+  mpegts.js@1.8.2:
     dependencies:
       es6-promise: 4.2.8
       events: 3.3.0

From 77458b393194258e37340ff5e111eaa51affcdf3 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:58:28 +0200
Subject: [PATCH 14/20] perf(web): make the app root and settings components
 OnPush (#1823)

* perf(web): make the app root and settings components OnPush

Plan item C6 step 3 for apps/web: the fifteen Eager components switch to
OnPush, among them the app root and the update notification panel that
the idle audit found re-rendering on every idle tick. Their template
state is signals from the settings facades, signal inputs and the shared
reactive settings form.

The checklist flagged the backup import, which patches the form from a
detached file input with no template event. A new spec patches only a
value, which changes no form status, and confirms the OnPush general
section still shows the new theme; it guards that path for the zoneless
flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(settings): re-render OnPush sections when the form changes outside them

Review follow-ups (Greptile, Codex):

- The settings sections read form values in their templates (selected
  theme and cover size, epgField.value, form().value.player), and the
  parent changes the form outside their events: Discard and backup import
  patch it, the store hydrates it, the EPG file picker sets a control
  after an await. Under OnPush the section kept the old selection or EPG
  status. Each section now marks itself on its form's events
  (markSectionForCheckOnFormEvents).
- The value-only patch test no longer forces detectChanges(); with the
  fixture rendering on its own it fails without the marking, and so does
  a new test for a control set outside the EPG section.
- The zoneless guard counts only changeDetection metadata outside
  comments, so a comment naming the strategy is not an Eager component.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(settings): guard the unsaved-changes bar after a save off the sections

Review follow-up (Codex): Save marks the form pristine after an async
store write, also on Backup, Reset or search, where no form section is
rendered. The OnPush page re-renders anyway because pristine and valid
read the form's state signals; the new test checks that on the Backup
page without forcing a render (it waits for the scheduled one).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../performance/zoneless-migration.spec.ts    | 31 ++++++++-
 ...app-update-notification-panel.component.ts |  3 +-
 apps/web/src/app/app.component.ts             |  3 +-
 ...p-update-release-notes-dialog.component.ts |  3 +-
 .../settings-about-section.component.ts       | 11 +++-
 .../settings-backup-section.component.ts      |  3 +-
 .../settings-dashboard-section.component.ts   | 10 ++-
 ...s-delete-all-playlists-dialog.component.ts |  3 +-
 .../settings-epg-section.component.ts         | 11 +++-
 .../settings-general-section.component.ts     | 11 +++-
 .../settings-playback-section.component.ts    | 11 +++-
 ...ttings-remote-control-section.component.ts | 11 +++-
 .../settings-reset-section.component.ts       |  3 +-
 .../settings/settings-section-form-render.ts  | 30 +++++++++
 .../settings-tmdb-section.component.ts        |  5 +-
 ...ttings-unsaved-changes-dialog.component.ts |  3 +-
 .../settings/settings.component.form.spec.ts  | 63 +++++++++++++++++++
 .../src/app/settings/settings.component.ts    |  3 +-
 docs/architecture/zoneless-migration.md       | 41 ++++++------
 19 files changed, 210 insertions(+), 49 deletions(-)
 create mode 100644 apps/web/src/app/settings/settings-section-form-render.ts

diff --git a/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
index f9a67c9d7..3137c0f1f 100644
--- a/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/zoneless-migration.spec.ts
@@ -70,9 +70,21 @@ function readEagerChecklist(): { open: string[]; done: string[] } {
 
 const sources = readSources();
 
+// Component metadata only: a comment or string that names the strategy is
+// not an Eager component.
+const eagerMetadata = /changeDetection\s*:\s*ChangeDetectionStrategy\.Eager\b/;
+
+function withoutComments(text: string): string {
+    return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+
+function isEagerComponent(text: string): boolean {
+    return eagerMetadata.test(withoutComments(text));
+}
+
 test('the zoneless checklist lists exactly the components that are still Eager', () => {
     const eager = [...sources]
-        .filter(([, text]) => text.includes('ChangeDetectionStrategy.Eager'))
+        .filter(([, text]) => isEagerComponent(text))
         .map(([file]) => file)
         .sort();
     const { open } = readEagerChecklist();
@@ -106,6 +118,23 @@ test('the guard skips test-only file names and keeps production ones', () => {
     }
 });
 
+test('a comment that names the Eager strategy is not an Eager component', () => {
+    assert.equal(
+        isEagerComponent(
+            '// was ChangeDetectionStrategy.Eager before C6\n' +
+                '/* changeDetection: ChangeDetectionStrategy.Eager */\n' +
+                '@Component({ changeDetection: ChangeDetectionStrategy.OnPush })'
+        ),
+        false
+    );
+    assert.equal(
+        isEagerComponent(
+            '@Component({\n    changeDetection: ChangeDetectionStrategy.Eager,\n})'
+        ),
+        true
+    );
+});
+
 test('ticked checklist entries name files that exist', () => {
     for (const file of readEagerChecklist().done) {
         assert.ok(sources.has(file), `${file} is ticked but does not exist`);
diff --git a/apps/web/src/app/app-update-notification-panel.component.ts b/apps/web/src/app/app-update-notification-panel.component.ts
index a99e814ad..91afea93b 100644
--- a/apps/web/src/app/app-update-notification-panel.component.ts
+++ b/apps/web/src/app/app-update-notification-panel.component.ts
@@ -101,8 +101,7 @@ import { AppUpdateInstallService } from './services/app-update-install.service';
             </section>
         }
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             .app-update-notification {
diff --git a/apps/web/src/app/app.component.ts b/apps/web/src/app/app.component.ts
index 15c3df9c3..804899aa4 100644
--- a/apps/web/src/app/app.component.ts
+++ b/apps/web/src/app/app.component.ts
@@ -55,8 +55,7 @@ const debugAppComponent = createDevLogger('AppComponent');
 @Component({
     selector: 'app-root',
     templateUrl: './app.component.html',
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         AppStartupStatusComponent,
         AppUpdateNotificationPanelComponent,
diff --git a/apps/web/src/app/settings/app-update-release-notes-dialog.component.ts b/apps/web/src/app/settings/app-update-release-notes-dialog.component.ts
index 870e1c142..afacf4eff 100644
--- a/apps/web/src/app/settings/app-update-release-notes-dialog.component.ts
+++ b/apps/web/src/app/settings/app-update-release-notes-dialog.component.ts
@@ -178,8 +178,7 @@ function decorateReleaseNotesHtml(html: string): string {
             </button>
         </mat-dialog-actions>
     `,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             .release-notes-dialog {
diff --git a/apps/web/src/app/settings/settings-about-section.component.ts b/apps/web/src/app/settings/settings-about-section.component.ts
index 9d6f1f6a0..028522a27 100644
--- a/apps/web/src/app/settings/settings-about-section.component.ts
+++ b/apps/web/src/app/settings/settings-about-section.component.ts
@@ -19,6 +19,7 @@ import {
     ElectronBridgeAppUpdateStatus,
 } from '@iptvnator/shared/interfaces';
 import { UpdateChannelOption } from './settings.models';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-about-section',
@@ -32,8 +33,7 @@ import { UpdateChannelOption } from './settings.models';
     ],
     templateUrl: './settings-about-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         ':host { display: contents; }',
         '.version-block .build-commit { opacity: 0.65; font-size: 0.85em; }',
@@ -58,6 +58,13 @@ export class SettingsAboutSectionComponent {
      * setting. Absent in hosts that only render the version block.
      */
     readonly form = input<FormGroup | null>(null);
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
+
     readonly updateChannelOptions = input<UpdateChannelOption[]>([]);
 
     readonly buildCommitShort = computed(() => {
diff --git a/apps/web/src/app/settings/settings-backup-section.component.ts b/apps/web/src/app/settings/settings-backup-section.component.ts
index f383c6163..0af8aefba 100644
--- a/apps/web/src/app/settings/settings-backup-section.component.ts
+++ b/apps/web/src/app/settings/settings-backup-section.component.ts
@@ -20,8 +20,7 @@ import { TranslateModule } from '@ngx-translate/core';
     ],
     templateUrl: './settings-backup-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsBackupSectionComponent {
diff --git a/apps/web/src/app/settings/settings-dashboard-section.component.ts b/apps/web/src/app/settings/settings-dashboard-section.component.ts
index 3cb1739b6..c39bdbca5 100644
--- a/apps/web/src/app/settings/settings-dashboard-section.component.ts
+++ b/apps/web/src/app/settings/settings-dashboard-section.component.ts
@@ -9,6 +9,7 @@ import { FormGroup, ReactiveFormsModule } from '@angular/forms';
 import { MatCheckboxModule } from '@angular/material/checkbox';
 import { MatIconModule } from '@angular/material/icon';
 import { TranslateModule } from '@ngx-translate/core';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-dashboard-section',
@@ -21,10 +22,15 @@ import { TranslateModule } from '@ngx-translate/core';
     ],
     templateUrl: './settings-dashboard-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsDashboardSectionComponent {
     readonly form = input.required<FormGroup>();
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
 }
diff --git a/apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts b/apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts
index 87dd57aa2..9f4a0fea2 100644
--- a/apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts
+++ b/apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts
@@ -31,8 +31,7 @@ type SettingsDeleteSummaryItem = {
     selector: 'app-settings-delete-all-playlists-dialog',
     templateUrl: './settings-delete-all-playlists-dialog.component.html',
     styleUrls: ['./settings-delete-all-playlists-dialog.component.scss'],
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         CommonModule,
         MatButtonModule,
diff --git a/apps/web/src/app/settings/settings-epg-section.component.ts b/apps/web/src/app/settings/settings-epg-section.component.ts
index 8f07d4124..8152b24da 100644
--- a/apps/web/src/app/settings/settings-epg-section.component.ts
+++ b/apps/web/src/app/settings/settings-epg-section.component.ts
@@ -17,6 +17,7 @@ import { EpgViewMode } from '@iptvnator/shared/interfaces';
 import { EpgSourceStatusComponent } from '@iptvnator/ui/epg';
 import { TranslateModule } from '@ngx-translate/core';
 import { EpgViewModeOption } from './settings.models';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-epg-section',
@@ -34,12 +35,18 @@ import { EpgViewModeOption } from './settings.models';
     ],
     templateUrl: './settings-epg-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsEpgSectionComponent {
     readonly form = input.required<FormGroup>();
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
+
     readonly epgUrl = input.required<FormArray>();
     readonly isClearingEpgData = input(false);
     readonly canBrowseFiles = input(false);
diff --git a/apps/web/src/app/settings/settings-general-section.component.ts b/apps/web/src/app/settings/settings-general-section.component.ts
index b24d2afbc..b44971bf0 100644
--- a/apps/web/src/app/settings/settings-general-section.component.ts
+++ b/apps/web/src/app/settings/settings-general-section.component.ts
@@ -19,6 +19,7 @@ import {
     StartupWindowModeOption,
     ThemeOption,
 } from './settings.models';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-general-section',
@@ -33,12 +34,18 @@ import {
     ],
     templateUrl: './settings-general-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsGeneralSectionComponent {
     readonly form = input.required<FormGroup>();
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
+
     readonly languageEnum = input.required<typeof Language>();
     readonly themeOptions = input.required<ThemeOption[]>();
     readonly coverSizeOptions = input.required<CoverSizeOption[]>();
diff --git a/apps/web/src/app/settings/settings-playback-section.component.ts b/apps/web/src/app/settings/settings-playback-section.component.ts
index 6b0afd01f..5a3eee85d 100644
--- a/apps/web/src/app/settings/settings-playback-section.component.ts
+++ b/apps/web/src/app/settings/settings-playback-section.component.ts
@@ -20,6 +20,7 @@ import {
     reportsPlaybackFailures,
 } from '@iptvnator/shared/interfaces';
 import { SettingsPlayerOption } from './settings.models';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-playback-section',
@@ -36,8 +37,7 @@ import { SettingsPlayerOption } from './settings.models';
     ],
     templateUrl: './settings-playback-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsPlaybackSectionComponent {
@@ -53,6 +53,13 @@ export class SettingsPlaybackSectionComponent {
     ].join('\n');
 
     readonly form = input.required<FormGroup>();
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
+
     readonly players = input.required<SettingsPlayerOption[]>();
     readonly streamFormatEnum = input.required<typeof StreamFormat>();
     readonly isDesktop = input(false);
diff --git a/apps/web/src/app/settings/settings-remote-control-section.component.ts b/apps/web/src/app/settings/settings-remote-control-section.component.ts
index 37b6408ef..7d667f46a 100644
--- a/apps/web/src/app/settings/settings-remote-control-section.component.ts
+++ b/apps/web/src/app/settings/settings-remote-control-section.component.ts
@@ -14,6 +14,7 @@ import { MatInputModule } from '@angular/material/input';
 import { MatTooltipModule } from '@angular/material/tooltip';
 import { TranslateModule } from '@ngx-translate/core';
 import { QRCodeComponent } from 'angularx-qrcode';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 @Component({
     selector: 'app-settings-remote-control-section',
@@ -30,12 +31,18 @@ import { QRCodeComponent } from 'angularx-qrcode';
     ],
     templateUrl: './settings-remote-control-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsRemoteControlSectionComponent {
     readonly form = input.required<FormGroup>();
+
+    constructor() {
+        // Parent patches (Discard, backup import) change the form outside
+        // this OnPush section's events.
+        markSectionForCheckOnFormEvents(this.form);
+    }
+
     readonly localIpAddresses = input.required<string[]>();
     readonly visibleQrCodeIp = input<string | null>(null);
 
diff --git a/apps/web/src/app/settings/settings-reset-section.component.ts b/apps/web/src/app/settings/settings-reset-section.component.ts
index ae6d5226f..8396ee5c4 100644
--- a/apps/web/src/app/settings/settings-reset-section.component.ts
+++ b/apps/web/src/app/settings/settings-reset-section.component.ts
@@ -22,8 +22,7 @@ import { SettingsPlaylistDeleteSummary } from './settings.models';
     ],
     templateUrl: './settings-reset-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [':host { display: contents; }'],
 })
 export class SettingsResetSectionComponent {
diff --git a/apps/web/src/app/settings/settings-section-form-render.ts b/apps/web/src/app/settings/settings-section-form-render.ts
new file mode 100644
index 000000000..f0c19729b
--- /dev/null
+++ b/apps/web/src/app/settings/settings-section-form-render.ts
@@ -0,0 +1,30 @@
+import { ChangeDetectorRef, inject, type Signal } from '@angular/core';
+import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
+import type { AbstractControl } from '@angular/forms';
+import { EMPTY, switchMap } from 'rxjs';
+
+/**
+ * Marks an OnPush settings section for check on every event of its form.
+ *
+ * The sections read form values and states in their templates (selected
+ * theme, `epgField.value`, `form().value.player`), which are not signals.
+ * The parent changes the form outside the section's template events: Discard
+ * and backup import patch it, the store hydrates it, and the EPG file picker
+ * sets a control after an `await`. Without this the section keeps showing
+ * the previous value until some unrelated event marks it. `events` covers
+ * value, status, touched and pristine changes, including those of child
+ * controls, which bubble up to the group.
+ *
+ * Call it from a field initializer or the constructor.
+ */
+export function markSectionForCheckOnFormEvents(
+    form: Signal<AbstractControl | null>
+): void {
+    const changeDetector = inject(ChangeDetectorRef);
+    toObservable(form)
+        .pipe(
+            switchMap((control) => control?.events ?? EMPTY),
+            takeUntilDestroyed()
+        )
+        .subscribe(() => changeDetector.markForCheck());
+}
diff --git a/apps/web/src/app/settings/settings-tmdb-section.component.ts b/apps/web/src/app/settings/settings-tmdb-section.component.ts
index 4b57acfba..0959308c7 100644
--- a/apps/web/src/app/settings/settings-tmdb-section.component.ts
+++ b/apps/web/src/app/settings/settings-tmdb-section.component.ts
@@ -16,6 +16,7 @@ import { MatProgressSpinnerModule } from '@angular/material/progress-spinner';
 import { TranslateModule } from '@ngx-translate/core';
 import { TmdbApiService, TmdbCacheService } from '@iptvnator/services';
 import type { TmdbCacheStats } from '@iptvnator/shared/interfaces';
+import { markSectionForCheckOnFormEvents } from './settings-section-form-render';
 
 type TmdbKeyTestState = 'idle' | 'testing' | 'success' | 'error';
 
@@ -33,8 +34,7 @@ type TmdbKeyTestState = 'idle' | 'testing' | 'success' | 'error';
     ],
     templateUrl: './settings-tmdb-section.component.html',
     encapsulation: ViewEncapsulation.None,
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             app-settings-tmdb-section {
@@ -92,6 +92,7 @@ export class SettingsTmdbSectionComponent {
     readonly isClearing = signal(false);
 
     constructor() {
+        markSectionForCheckOnFormEvents(this.form);
         // Sizing the cache is a full table scan, but this component only
         // exists while its section page is open, so loading on construction
         // preserves the old "wait until the user is actually looking"
diff --git a/apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts b/apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts
index c556f7d1b..c709a9e06 100644
--- a/apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts
+++ b/apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts
@@ -54,8 +54,7 @@ export interface SettingsUnsavedChangesDialogData {
             }
         `,
     ],
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     template: `
         <h2 mat-dialog-title>
             {{ 'SETTINGS.UNSAVED_DIALOG_TITLE' | translate }}
diff --git a/apps/web/src/app/settings/settings.component.form.spec.ts b/apps/web/src/app/settings/settings.component.form.spec.ts
index 5cd4b2d3d..bf9b9b1d2 100644
--- a/apps/web/src/app/settings/settings.component.form.spec.ts
+++ b/apps/web/src/app/settings/settings.component.form.spec.ts
@@ -1,3 +1,4 @@
+import { FormArray, FormControl } from '@angular/forms';
 import { ComponentFixture, TestBed, waitForAsync } from '@angular/core/testing';
 import { MatSnackBar } from '@angular/material/snack-bar';
 import { EpgRuntimeBridgeService } from '@iptvnator/epg/data-access';
@@ -143,6 +144,25 @@ describe('SettingsComponent form', () => {
             });
         });
 
+        // The sections are OnPush and a Discard or backup import patches the
+        // form outside their template events, so the section must mark
+        // itself on the form's events. The fixture renders on its own here:
+        // a forced detectChanges() would hide a section that is not marked.
+        it('re-renders section selections after a value-only form patch', async () => {
+            const darkTheme = () =>
+                (fixture.nativeElement as HTMLElement).querySelector(
+                    '[data-test-id="DARK_THEME"]'
+                );
+            fixture.autoDetectChanges();
+            await fixture.whenStable();
+            expect(darkTheme()?.getAttribute('aria-checked')).toBe('false');
+
+            component.settingsForm.patchValue({ theme: Theme.DarkTheme });
+            await fixture.whenStable();
+
+            expect(darkTheme()?.getAttribute('aria-checked')).toBe('true');
+        });
+
         it('hydrates a shared web controls opt-out from the settings store', () => {
             settingsStore._setSettings({
                 webPlayerSharedControls: false,
@@ -185,6 +205,26 @@ describe('SettingsComponent form', () => {
             expect(settingsStore.updateSettings).not.toHaveBeenCalled();
         });
 
+        // The native file picker sets the EPG control after an await, with
+        // no template event in the OnPush section; its status must follow.
+        it('shows the source status after a control is set outside the section', async () => {
+            setSettingsSection('epg');
+            fixture.autoDetectChanges();
+            const epgUrls = component.settingsForm.get('epgUrl') as FormArray;
+            epgUrls.push(new FormControl(''));
+            await fixture.whenStable();
+            const status = () =>
+                (fixture.nativeElement as HTMLElement).querySelector(
+                    'app-epg-source-status'
+                );
+            expect(status()).toBeNull();
+
+            epgUrls.at(epgUrls.length - 1).setValue('/tmp/guide.xml');
+            await fixture.whenStable();
+
+            expect(status()).not.toBeNull();
+        });
+
         it('stages the EPG view mode without writing to the store until Save', () => {
             setSettingsSection('epg');
             fixture.detectChanges();
@@ -314,6 +354,29 @@ describe('SettingsComponent form', () => {
             expect(unsavedBar()).toBeNull();
         });
 
+        // The page owns the bar and is OnPush, and Save marks the form
+        // pristine after an async store write, also on a page without a form
+        // section. `pristine` and `valid` read the form's state signals, so
+        // the page re-renders without a form subscription; no forced render
+        // here, so a regression shows.
+        it('hides after a save on a page without a form section', async () => {
+            settingsStore.updateSettings.mockResolvedValue(undefined);
+            setSettingsSection('backup');
+            fixture.autoDetectChanges();
+            component.settingsForm.get('theme')?.setValue(Theme.DarkTheme);
+            component.settingsForm.markAsDirty();
+            await fixture.whenStable();
+            expect(unsavedBar()).not.toBeNull();
+
+            component.onSubmit();
+            await fixture.whenStable();
+            // The render the form event scheduled runs in the next macrotask.
+            await new Promise((resolve) => setTimeout(resolve));
+
+            expect(component.settingsForm.pristine).toBe(true);
+            expect(unsavedBar()).toBeNull();
+        });
+
         it('discard reverts a staged cover size (regression: eager persist made it stick)', () => {
             const largeCoverButton = (
                 fixture.nativeElement as HTMLElement
diff --git a/apps/web/src/app/settings/settings.component.ts b/apps/web/src/app/settings/settings.component.ts
index 5f95e8b07..f43b3eb30 100644
--- a/apps/web/src/app/settings/settings.component.ts
+++ b/apps/web/src/app/settings/settings.component.ts
@@ -102,8 +102,7 @@ export const SETTINGS_DEFAULT_SECTION = 'general';
         SettingsSearchResultsComponent,
         SettingsTmdbSectionComponent,
     ],
-    // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection -- Preserve pre-Angular 22 eager checking during the framework upgrade.
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     providers: [
         SettingsAppUpdateFacade,
         SettingsBackupFacade,
diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 63e70d481..4d7e804f7 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -63,25 +63,30 @@ must be ticked here.
 two). Tick an entry by deleting `changeDetection: ChangeDetectionStrategy.Eager`
 (or setting OnPush) once its template state is signals, signal inputs or
 explicitly marked. The guard spec compares the unticked entries with the
-files that still contain `ChangeDetectionStrategy.Eager`.
+files whose component metadata still sets
+`changeDetection: ChangeDetectionStrategy.Eager` (comments do not count).
+The settings sections read form values in their templates and the parent
+patches the form outside their events (Discard, backup import, the EPG file
+picker), so each marks itself on the form's `events` through
+`markSectionForCheckOnFormEvents` (`apps/web/src/app/settings`).
 
 ### apps/web (15)
 
-- [ ] `apps/web/src/app/app.component.ts` (idle audit root)
-- [ ] `apps/web/src/app/app-update-notification-panel.component.ts` (idle audit root)
-- [ ] `apps/web/src/app/settings/app-update-release-notes-dialog.component.ts`
-- [ ] `apps/web/src/app/settings/settings.component.ts`
-- [ ] `apps/web/src/app/settings/settings-about-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-backup-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-dashboard-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts`
-- [ ] `apps/web/src/app/settings/settings-epg-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-general-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-playback-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-remote-control-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-reset-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-tmdb-section.component.ts`
-- [ ] `apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts`
+- [x] `apps/web/src/app/app.component.ts` (idle audit root)
+- [x] `apps/web/src/app/app-update-notification-panel.component.ts` (idle audit root)
+- [x] `apps/web/src/app/settings/app-update-release-notes-dialog.component.ts`
+- [x] `apps/web/src/app/settings/settings.component.ts`
+- [x] `apps/web/src/app/settings/settings-about-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-backup-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-dashboard-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-delete-all-playlists-dialog.component.ts`
+- [x] `apps/web/src/app/settings/settings-epg-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-general-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-playback-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-remote-control-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-reset-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-tmdb-section.component.ts`
+- [x] `apps/web/src/app/settings/settings-unsaved-changes-dialog.component.ts`
 
 ### libs/ui (20 files, 21 components)
 
@@ -176,7 +181,7 @@ the field a signal (or a `computed`), or writes it through one.
 | [ ] | `libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts` (favorites load) | `favorites` Map filled in a `subscribe` without `markForCheck`; the component is OnPush already, so this is a latent bug today | portal |
 | [ ] | `libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts` (favorites load) | same pattern; the neighbouring `favoriteMarks.changes$` handler does call `markForCheck` | portal |
 | [ ] | same file, programme dialog `afterClosed` | deletes from `epgPrograms`/`currentProgramsProgress` after `await` without marking | portal |
-| [ ] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize` | apps/web |
+| [x] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize`; no fix needed: a value-only `patchValue` re-renders the OnPush sections (`settings.component.form.spec.ts` guards it) | apps/web |
 | [ ] | `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` | plain `isLoading`/`error`/`status` written after `await` and from a 2 s `setInterval` | only if `apps/remote-control-web` goes zoneless |
 
 ## Explicit zone and change-detector calls
@@ -185,7 +190,7 @@ They keep working under zoneless (`NgZone` becomes `NoopNgZone`, so `run`
 and `runOutsideAngular` just call through). Remove them in the flip PR, not
 before: with zone.js on they still matter.
 
-- [ ] `apps/web/src/app/settings/settings-unload-guard.service.ts`: two
+- [x] `apps/web/src/app/settings/settings-unload-guard.service.ts`: two
   `zone.run` calls around the window-close dialog (IPC
   `onWindowCloseRequested` and `beforeunload`).
 - [x] `libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts`:

From e17ee53a22df226a0d941f50e1edaf423ce57252 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 16:31:15 +0200
Subject: [PATCH 15/20] perf(workspace): make the workspace shell Eager
 components OnPush (#1819)

Plan item C6 step 3 for libs/workspace: the seven Eager components in
workspace/shell/feature, including the workspace shell root the idle audit
found re-rendering on every idle tick. Their templates read signals,
signal inputs, computed values and template-event state only; the one
plain field written outside the template (categoryLockTarget) is not
rendered. They switch to OnPush without other changes.

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/zoneless-migration.md            | 14 +++++++-------
 .../workspace-command-palette.component.ts         |  2 +-
 ...workspace-collection-context-panel.component.ts |  2 +-
 .../workspace-context-panel.component.ts           |  2 +-
 .../workspace-settings-context-panel.component.ts  |  2 +-
 ...orkspace-keyboard-shortcuts-dialog.component.ts |  2 +-
 .../workspace-shell/workspace-shell.component.ts   |  2 +-
 .../workspace-sources.component.ts                 |  2 +-
 8 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 4d7e804f7..0da8ce02d 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -119,13 +119,13 @@ picker), so each marks itself on the form's `events` through
 
 ### libs/workspace (7)
 
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts`
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts`
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts`
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts`
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts`
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts` (idle audit root)
-- [ ] `libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts`
+- [x] `libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts` (idle audit root)
+- [x] `libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts`
 
 ### libs/playlist (14)
 
diff --git a/libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts b/libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts
index b0d8f3889..56833b25a 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-command-palette/workspace-command-palette.component.ts
@@ -45,7 +45,7 @@ interface WorkspaceCommandGroupSection {
     selector: 'app-workspace-command-palette',
     imports: [MatDialogModule, MatIconModule, TranslatePipe],
     templateUrl: './workspace-command-palette.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './workspace-command-palette.component.scss',
 })
 export class WorkspaceCommandPaletteComponent implements AfterViewInit {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts
index ca0f75f30..70f638bfb 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-collection-context-panel.component.ts
@@ -54,7 +54,7 @@ import { WorkspaceShellContextDrawerService } from '@iptvnator/workspace/shell/u
             />
         </div>
     `,
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './workspace-context-panel.component.scss',
 })
 export class WorkspaceCollectionContextPanelComponent {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts
index a2b87f5bd..ff449972a 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-context-panel.component.ts
@@ -82,7 +82,7 @@ interface WorkspaceCategoryLike {
         WorkspaceContextErrorViewComponent,
     ],
     templateUrl: './workspace-context-panel.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './workspace-context-panel.component.scss',
 })
 export class WorkspaceContextPanelComponent {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts
index 5a93f9125..cdfb1669c 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-context-panel/workspace-settings-context-panel.component.ts
@@ -11,7 +11,7 @@ import { SettingsContextService } from '@iptvnator/workspace/shell/util/settings
     selector: 'app-workspace-settings-context-panel',
     imports: [MatIconModule, RouterLink, RouterLinkActive, TranslateModule],
     styleUrls: ['./workspace-settings-context-panel.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     template: `
         <h2 class="panel-title">{{ 'SETTINGS.TITLE' | translate }}</h2>
         <div class="settings-panel-body">
diff --git a/libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts b/libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts
index 6140c36b0..07d5c036c 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-keyboard-shortcuts/workspace-keyboard-shortcuts-dialog.component.ts
@@ -19,7 +19,7 @@ export interface WorkspaceKeyboardShortcutsDialogData {
     selector: 'app-workspace-keyboard-shortcuts-dialog',
     imports: [MatButtonModule, MatDialogModule, MatIconModule, TranslatePipe],
     templateUrl: './workspace-keyboard-shortcuts-dialog.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './workspace-keyboard-shortcuts-dialog.component.scss',
 })
 export class WorkspaceKeyboardShortcutsDialogComponent {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
index a86114ed7..98e433cb5 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
@@ -49,7 +49,7 @@ import { LIVE_CATEGORIES_POPOVER } from '@iptvnator/portal/shared/util';
     ],
     templateUrl: './workspace-shell.component.html',
     styleUrl: './workspace-shell.component.scss',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     providers: [
         WorkspaceShellFacade,
         WorkspaceShellRouteStateService,
diff --git a/libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts b/libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts
index 76c60d2a3..168d3924e 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-sources/workspace-sources.component.ts
@@ -61,7 +61,7 @@ interface SortOption {
         TranslatePipe,
     ],
     templateUrl: './workspace-sources.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './workspace-sources.component.scss',
 })
 export class WorkspaceSourcesComponent {

From 22a9c1f1e56eb2367dada17bee06591fbfb961ef Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 17:52:47 +0200
Subject: [PATCH 16/20] perf(web): add an opt-in zoneless change-detection
 build flag (#1824)

* perf(web): add an opt-in zoneless change-detection build flag

Plan item C6 step 4. app.config.ts takes its change-detection providers
from environments/change-detection.providers.ts, which keeps
provideZoneChangeDetection({ eventCoalescing: true }) for every existing
build. The new electron-performance-zoneless and electron-e2e-zoneless
web configurations are their base configuration plus one fileReplacements
swap to provideZonelessChangeDetection(), so the journeys and the Electron
E2E suite can run zoneless while nothing ships it. zone.js stays in the
polyfills until the flip.

A build-config test pins each *-zoneless configuration to its base plus
the swap and refuses the swap anywhere else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(epg): schedule the guide's post-render scroll without zone.js

The programme guide jumps to now once the virtual list first renders rows,
and focuses cells after keyboard scrolls, from afterNextRender hooks
registered in CDK and RxJS callbacks. zone.js followed those callbacks
with a tick; under zoneless change detection a render hook schedules no
render, so the guide opened at midnight (epg-guide.e2e.ts on the zoneless
build). The guide now marks itself when it registers one, which is
harmless with zone.js.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(performance): record the zoneless flag measurements and E2E run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(performance): say the zoneless flag ran with the three implemented journeys

Review follow-up (Greptile): J4 search is still planned, so the flag was
validated with J1-J3 and the Electron E2E suite, not all four journeys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../performance-build-config.spec.ts          | 46 +++++++++++-
 apps/web/project.json                         | 38 ++++++++++
 apps/web/src/app/app.config.ts                | 10 +--
 .../change-detection.providers.ts             | 12 ++++
 .../change-detection.providers.zoneless.ts    | 11 +++
 docs/architecture/zoneless-migration.md       | 70 +++++++++++++++++--
 .../src/lib/epg-guide/epg-guide.component.ts  | 21 ++++--
 7 files changed, 190 insertions(+), 18 deletions(-)
 create mode 100644 apps/web/src/environments/change-detection.providers.ts
 create mode 100644 apps/web/src/environments/change-detection.providers.zoneless.ts

diff --git a/apps/electron-backend-e2e/src/performance/performance-build-config.spec.ts b/apps/electron-backend-e2e/src/performance/performance-build-config.spec.ts
index 0ff7caa34..91a8701f4 100644
--- a/apps/electron-backend-e2e/src/performance/performance-build-config.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/performance-build-config.spec.ts
@@ -10,6 +10,7 @@ import { JOURNEY_CD_TICK_COUNTER_KEY } from './journey-renderer-probe';
 
 interface TargetConfiguration {
     configurations?: Record<string, Record<string, unknown>>;
+    defaultConfiguration?: string;
     dependsOn?: unknown;
     executor?: unknown;
     options?: Record<string, unknown>;
@@ -162,7 +163,12 @@ test('only the web performance build installs the tick counter the journeys read
     for (const [name, configuration] of Object.entries(
         webProject.targets['build'].configurations ?? {}
     )) {
-        if (name === 'electron-performance') continue;
+        if (
+            name === 'electron-performance' ||
+            name === 'electron-performance-zoneless'
+        ) {
+            continue;
+        }
         assert.doesNotMatch(
             JSON.stringify(configuration['fileReplacements'] ?? []),
             /environment\.performance/,
@@ -171,6 +177,44 @@ test('only the web performance build installs the tick counter the journeys read
     }
 });
 
+// Plan item C6 measures zoneless change detection behind a build-time flag:
+// each *-zoneless configuration is its base configuration plus one swap of
+// the change-detection providers, and nothing else selects that swap.
+test('the zoneless flag is opt-in through the *-zoneless web configurations only', () => {
+    const configurations = webProject.targets['build'].configurations ?? {};
+    const zonelessReplacement = {
+        replace: 'apps/web/src/environments/change-detection.providers.ts',
+        with: 'apps/web/src/environments/change-detection.providers.zoneless.ts',
+    };
+
+    for (const base of ['electron-performance', 'electron-e2e']) {
+        const baseConfiguration = configurations[base];
+        const zoneless = configurations[`${base}-zoneless`];
+        assert.ok(zoneless, `web:build must define ${base}-zoneless`);
+        assert.ok(baseConfiguration, `web:build must define ${base}`);
+        const { fileReplacements: baseReplacements, ...baseRest } =
+            baseConfiguration;
+        const { fileReplacements, ...rest } = zoneless;
+        assert.deepEqual(rest, baseRest, base);
+        assert.deepEqual(fileReplacements, [
+            ...((baseReplacements as unknown[] | undefined) ?? []),
+            zonelessReplacement,
+        ]);
+    }
+    for (const [name, configuration] of Object.entries(configurations)) {
+        if (name.endsWith('-zoneless')) continue;
+        assert.doesNotMatch(
+            JSON.stringify(configuration['fileReplacements'] ?? []),
+            /change-detection\.providers/,
+            name
+        );
+    }
+    assert.equal(
+        webProject.targets['build'].defaultConfiguration,
+        'production'
+    );
+});
+
 test('the resolved web build cache output is the renderer directory', () => {
     const task = readResolvedWebBuildTask();
 
diff --git a/apps/web/project.json b/apps/web/project.json
index 7244c4ac5..74c415311 100644
--- a/apps/web/project.json
+++ b/apps/web/project.json
@@ -143,12 +143,50 @@
                         }
                     ]
                 },
+                "electron-performance-zoneless": {
+                    "baseHref": "./",
+                    "serviceWorker": false,
+                    "optimization": {
+                        "scripts": true,
+                        "styles": {
+                            "minify": true,
+                            "inlineCritical": false,
+                            "removeSpecialComments": true
+                        },
+                        "fonts": true
+                    },
+                    "outputHashing": "all",
+                    "sourceMap": true,
+                    "fileReplacements": [
+                        {
+                            "replace": "apps/web/src/environments/environment.ts",
+                            "with": "apps/web/src/environments/environment.performance.ts"
+                        },
+                        {
+                            "replace": "apps/web/src/environments/change-detection.providers.ts",
+                            "with": "apps/web/src/environments/change-detection.providers.zoneless.ts"
+                        }
+                    ]
+                },
                 "electron-e2e": {
                     "baseHref": "./",
                     "serviceWorker": false,
                     "optimization": false,
                     "extractLicenses": false,
                     "sourceMap": true
+                },
+                "electron-e2e-zoneless": {
+                    "baseHref": "./",
+                    "serviceWorker": false,
+                    "optimization": false,
+                    "extractLicenses": false,
+                    "sourceMap": true,
+                    "fileReplacements": [
+                        {
+                            "replace": "apps/web/src/environments/change-detection.providers.ts",
+                            "with": "apps/web/src/environments/change-detection.providers.zoneless.ts"
+                        }
+                    ]
                 }
             },
             "defaultConfiguration": "production"
diff --git a/apps/web/src/app/app.config.ts b/apps/web/src/app/app.config.ts
index 1fc0d8950..edd657996 100644
--- a/apps/web/src/app/app.config.ts
+++ b/apps/web/src/app/app.config.ts
@@ -8,12 +8,7 @@ import {
     FullscreenOverlayContainer,
     OverlayContainer,
 } from '@angular/cdk/overlay';
-import {
-    ApplicationConfig,
-    inject,
-    importProvidersFrom,
-    provideZoneChangeDetection,
-} from '@angular/core';
+import { ApplicationConfig, inject, importProvidersFrom } from '@angular/core';
 import { MAT_FORM_FIELD_DEFAULT_OPTIONS } from '@angular/material/form-field';
 import { provideAnimations } from '@angular/platform-browser/animations';
 import { provideRouter, withComponentInputBinding } from '@angular/router';
@@ -39,6 +34,7 @@ import {
 } from '@iptvnator/services';
 import { dbConfig } from '@iptvnator/shared/interfaces';
 import { AppConfig } from '../environments/environment';
+import { changeDetectionProviders } from '../environments/change-detection.providers';
 import { routes } from './app.routes';
 import { ElectronService } from './services/electron.service';
 import { ExternalPlaybackService } from './services/external-playback.service';
@@ -110,7 +106,7 @@ export function DataFactory() {
 
 export const appConfig: ApplicationConfig = {
     providers: [
-        provideZoneChangeDetection({ eventCoalescing: true }),
+        ...changeDetectionProviders,
         provideRouter(routes, withComponentInputBinding()),
         provideAnimations(),
         // CDK overlays (menus, tooltips, dialogs) live in a container under
diff --git a/apps/web/src/environments/change-detection.providers.ts b/apps/web/src/environments/change-detection.providers.ts
new file mode 100644
index 000000000..d0cf2caa0
--- /dev/null
+++ b/apps/web/src/environments/change-detection.providers.ts
@@ -0,0 +1,12 @@
+import {
+    EnvironmentProviders,
+    provideZoneChangeDetection,
+} from '@angular/core';
+
+// Change detection for every build: zone.js schedules the ticks. The
+// *-zoneless build configurations replace this file with
+// change-detection.providers.zoneless.ts while plan item C6 measures
+// zoneless change detection; see docs/architecture/zoneless-migration.md.
+export const changeDetectionProviders: EnvironmentProviders[] = [
+    provideZoneChangeDetection({ eventCoalescing: true }),
+];
diff --git a/apps/web/src/environments/change-detection.providers.zoneless.ts b/apps/web/src/environments/change-detection.providers.zoneless.ts
new file mode 100644
index 000000000..30e71ff06
--- /dev/null
+++ b/apps/web/src/environments/change-detection.providers.zoneless.ts
@@ -0,0 +1,11 @@
+import {
+    EnvironmentProviders,
+    provideZonelessChangeDetection,
+} from '@angular/core';
+
+// Swapped in for change-detection.providers.ts by the *-zoneless build
+// configurations only. zone.js stays in the polyfills until the flip, so
+// Angular logs NG0914 in these builds; nothing patches through it.
+export const changeDetectionProviders: EnvironmentProviders[] = [
+    provideZonelessChangeDetection(),
+];
diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 0da8ce02d..08dddfcec 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -50,9 +50,10 @@ must be ticked here.
    playback (`libs/ui/playback`, `libs/playlist/m3u/feature-player`),
    `apps/web`. Each reports the tick counters before and after and runs the
    affected unit and E2E tests.
-4. [ ] `provideZonelessChangeDetection()` behind a build-time
-   `fileReplacements` flag, off by default; all four journeys and the
-   Electron E2E suite run with it on.
+4. [x] `provideZonelessChangeDetection()` behind a build-time
+   `fileReplacements` flag, off by default; the three implemented journeys
+   (J1-J3; J4 is still planned) and the Electron E2E suite run with it on
+   (see [Zoneless flag](#zoneless-flag)).
 5. [ ] Flag on by default, `zone.js` out of `polyfills`, new tick baselines
    (`renderer.cdTicksIdle30s` and any counter that becomes deterministic once
    the zone.js race is gone).
@@ -181,7 +182,8 @@ the field a signal (or a `computed`), or writes it through one.
 | [ ] | `libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts` (favorites load) | `favorites` Map filled in a `subscribe` without `markForCheck`; the component is OnPush already, so this is a latent bug today | portal |
 | [ ] | `libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts` (favorites load) | same pattern; the neighbouring `favoriteMarks.changes$` handler does call `markForCheck` | portal |
 | [ ] | same file, programme dialog `afterClosed` | deletes from `epgPrograms`/`currentProgramsProgress` after `await` without marking | portal |
-| [x] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize`; no fix needed: a value-only `patchValue` re-renders the OnPush sections (`settings.component.form.spec.ts` guards it) | apps/web |
+| [x] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize`; each section now marks itself on its form's `events` (`markSectionForCheckOnFormEvents`), which `settings.component.form.spec.ts` guards without a forced render | apps/web |
+| [x] | `libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts` (jump to now, keyboard focus) | `afterNextRender` registered from CDK/RxJS callbacks; zone.js followed them with a tick, zoneless schedules no render, so the guide opened at midnight. It now marks itself when it registers the hook. Found by `epg-guide.e2e.ts` on the zoneless build | flag |
 | [ ] | `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` | plain `isLoading`/`error`/`status` written after `await` and from a 2 s `setInterval` | only if `apps/remote-control-web` goes zoneless |
 
 ## Explicit zone and change-detector calls
@@ -251,6 +253,66 @@ their events arrive over IPC.
   `apps/web/src/setup-jest.ts` (no project, tsconfig or Jest config uses
   them).
 
+## Zoneless flag
+
+`app.config.ts` takes its change-detection providers from
+`apps/web/src/environments/change-detection.providers.ts`
+(`provideZoneChangeDetection({ eventCoalescing: true })`). The
+`electron-performance-zoneless` and `electron-e2e-zoneless` web
+configurations are their base configuration plus one `fileReplacements`
+swap to `change-detection.providers.zoneless.ts`
+(`provideZonelessChangeDetection()`); a test in
+`performance-build-config.spec.ts` pins that and refuses the swap in any
+other configuration. zone.js stays in the polyfills, so these builds log
+NG0914 in dev mode and nothing schedules through the zone. The Electron app
+loads the renderer from `dist/apps/web`, so rebuilding only the web app
+switches an existing Electron build:
+
+```bash
+pnpm nx run electron-backend:build-performance          # or build-e2e
+pnpm nx run web:build:electron-performance-zoneless     # or electron-e2e-zoneless
+cd apps/electron-backend-e2e
+../../node_modules/.bin/playwright test --config=playwright.journeys.config.ts
+../../node_modules/.bin/playwright test --grep-invert packaged
+```
+
+Do not run `pnpm run perf:journeys` or `pnpm nx run electron-backend-e2e:e2e`
+afterwards: their build dependencies restore the zone.js renderer.
+
+First measurement (macOS, 2026-10-04, the six OnPush PRs merged locally on
+the flag branch; the same integration build measured with the flag off and
+on, five iterations each):
+
+| Counter | flag off | flag on |
+| --- | --- | --- |
+| `renderer.cdTicksToFirstCard` | 22, 20, 22, 21, 21 | 7, 7, 7, 7, 7 |
+| `renderer.cdTicksIdle30s` | 4, 4, 4, 4, 4 | 3, 3, 3, 3, 3 |
+| `renderer.cdTicksToFirstPage` | 22 (all) | 8 (all) |
+| `renderer.cdTicksToPlaying` | 16, 15, 15, 17, 15 | 6, 8, 10, 10, 7 |
+| DOM mutations J1 / J2 / J3 | 553 / 1,603 / 6,182 | 553 / 1,603 / 6,182 (one J3 iteration 6,199, as on master) |
+| `spawnToFirstCardMs` p50 | 3,071 | 828 |
+| `clickToFirstPageMs` p50 | 82.8 | 80.4 |
+| `clickToLoadedMetadataMs` / `clickToPlayingMs` p50 | 94.8 / 268.7 | 158.3 / 409.3 |
+
+J1 and J2 tick counts become deterministic without the zone.js one-tick
+race, and the DOM mutations are unchanged, so nothing renders differently.
+J3's tick count still varies with player events and its wall-clock
+numbers rose locally; the machine was shared with other runs (load 26 to 58
+during these two runs, master itself read 363.8 ms `clickToPlayingMs` p50
+earlier the same day), so judge J3 on the CI runner before the flip.
+
+Electron E2E suite on `electron-e2e-zoneless` (all specs except the
+packaged frame-copy ones): 203 passed, 7 skipped, 3 failed. `epg-guide`
+failed on every run and is fixed above; `playlist-auto-refresh` passed on
+`--repeat-each=2`; `dash-clearkey` "reopens from recent and favorites" is the
+known local flake (it fails as often on master). The IPC-driven paths
+passed zoneless: external-player launch states and the MPV/VLC DASH
+fallbacks in `dash-clearkey`, the MPV double-click gate in `settings`,
+`remote-control`, `picture-in-picture` and `stream-info`. Their state reaches
+the renderer over IPC into signals and never ran in the zone. Embedded MPV
+playback itself is covered only by the packaged frame-copy E2E, which these
+runs left out; run it on a packaged zoneless build before the flip.
+
 ## Measuring a PR
 
 Build `electron-performance` and run the journeys as described in
diff --git a/libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts b/libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts
index dfed6d379..c6ba666d3 100644
--- a/libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts
+++ b/libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts
@@ -6,6 +6,7 @@ import { DatePipe } from '@angular/common';
 import {
     afterNextRender,
     ChangeDetectionStrategy,
+    ChangeDetectorRef,
     Component,
     computed,
     DestroyRef,
@@ -83,6 +84,7 @@ export class EpgGuideComponent implements OnDestroy {
     private readonly translate = inject(TranslateService);
     private readonly destroyRef = inject(DestroyRef);
     private readonly injector = inject(Injector);
+    private readonly changeDetector = inject(ChangeDetectorRef);
     private readonly hostElement = inject<ElementRef<HTMLElement>>(ElementRef);
 
     readonly close = output<void>();
@@ -185,8 +187,7 @@ export class EpgGuideComponent implements OnDestroy {
         activeRow: () => this.activeRowIndex(),
         ensureLoaded: (channels) => this.programsService.ensureLoaded(channels),
         setScrollLeft: (left) => this.view.scrollLeft.set(left),
-        afterRender: (callback) =>
-            afterNextRender(callback, { injector: this.injector }),
+        afterRender: (callback) => this.afterNextGuideRender(callback),
     });
 
     private readonly dialogs = new EpgGuideDialogController(
@@ -237,15 +238,23 @@ export class EpgGuideComponent implements OnDestroy {
                 this.viewportController.whenRowsRendered(
                     viewport,
                     this.destroyRef,
-                    () =>
-                        afterNextRender(() => this.jumpNow(false), {
-                            injector: this.injector,
-                        })
+                    () => this.afterNextGuideRender(() => this.jumpNow(false))
                 );
             });
         });
     }
 
+    /**
+     * Run `callback` after the next render. The callers register from CDK
+     * and RxJS callbacks, outside any template event: zone.js used to follow
+     * those with a tick, but without it registering a render hook schedules
+     * no render, so the guide also marks itself for one.
+     */
+    private afterNextGuideRender(callback: () => void): void {
+        afterNextRender(callback, { injector: this.injector });
+        this.changeDetector.markForCheck();
+    }
+
     ngOnDestroy(): void {
         this.view.destroy();
         this.search.destroy();

From 5f21e240e99fa80c456b2c51d6ee75bdf852af21 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 18:46:57 +0200
Subject: [PATCH 17/20] test(performance): add J4 search journey (#1816)

* test(performance): add J4 search journey

Measures typing a six-character query into the header search box on
/workspace/search until the global search results settle, on a profile
with the M3U fixture and the mock's existing 12,000-item `large` Xtream
catalog. Counters: bridge calls and SQL statements per search (with a
per-keystroke breakdown), serial IPC depth, DOM mutations, change-detection
ticks, layout shift and long tasks; wall-clock last keystroke to settled
and first keystroke to first result.

Runs in the existing journeys target and the warn-only CI job, whose
summary now prints the per-keystroke table. Moves J3's picsum artwork
blocker into a shared helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(performance): J4 settles only on the final term's query

The probe could settle on cards of an earlier term that stay visible while
the final term debounces. The journey now stamps every dbGlobalSearch trace
event in the main process, and the record requires the last query between
the sentinels to be for the final term and to have completed before the
end sentinel. Iterations with a keydown gap over 250 ms (below the 350 ms
debounce) are rejected; gaps and the final query are kept as evidence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(performance): anchor J4's SQL count to the journey sentinels

renderer.sqlStatementsPerSearch was the difference of test-side samples
taken before the first key and after the end sentinel had been read, so
database work in either gap could be counted. The main process now reads
main.sqlStatements when the start and end sentinels arrive, and the counter
is their difference; sqlStatementsAfterSettled starts at the end sentinel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../actions/performance-journeys/action.yml   |   8 +-
 .github/workflows/ci.yml                      |   4 +-
 .../src/journeys/playback-journey-app.ts      |  57 +-
 .../src/journeys/search-journey-app.ts        | 435 +++++++++++++++
 .../src/journeys/search.journey.ts            |  79 +++
 .../performance/journey-external-artwork.ts   |  51 ++
 .../performance/journey-launch-environment.ts |   4 +-
 .../performance/journey-main-counters.spec.ts |  19 +-
 .../performance/search-journey-probe.spec.ts  | 348 ++++++++++++
 .../src/performance/search-journey-probe.ts   | 507 ++++++++++++++++++
 .../performance/search-journey-record.spec.ts | 451 ++++++++++++++++
 .../src/performance/search-journey-record.ts  | 330 ++++++++++++
 docs/architecture/performance-journeys.md     | 188 ++++++-
 13 files changed, 2414 insertions(+), 67 deletions(-)
 create mode 100644 apps/electron-backend-e2e/src/journeys/search-journey-app.ts
 create mode 100644 apps/electron-backend-e2e/src/journeys/search.journey.ts
 create mode 100644 apps/electron-backend-e2e/src/performance/journey-external-artwork.ts
 create mode 100644 apps/electron-backend-e2e/src/performance/search-journey-probe.spec.ts
 create mode 100644 apps/electron-backend-e2e/src/performance/search-journey-probe.ts
 create mode 100644 apps/electron-backend-e2e/src/performance/search-journey-record.spec.ts
 create mode 100644 apps/electron-backend-e2e/src/performance/search-journey-record.ts

diff --git a/.github/actions/performance-journeys/action.yml b/.github/actions/performance-journeys/action.yml
index 5b9ead263..5a5246eec 100644
--- a/.github/actions/performance-journeys/action.yml
+++ b/.github/actions/performance-journeys/action.yml
@@ -72,5 +72,11 @@ runs:
                       (($j.wallClock // {}) | to_entries[] | "| `\(.key)` | \(.value) | |"),
                       "",
                       ([($j.iterations // [])[] | select(.warmup | not) | .evidence.ipcSerialDepth // empty][0] // empty |
-                          "Serial IPC chain (first measured iteration): \(.chain | map("`\(.)`") | join(" → "))", ""))
+                          "Serial IPC chain (first measured iteration): \(.chain | map("`\(.)`") | join(" → "))", ""),
+                      ([($j.iterations // [])[] | select(.warmup | not) | .evidence.perKeystroke // empty][0] // empty |
+                          "Per keystroke (first measured iteration):", "",
+                          "| Key | Query calls | Bridge calls | SQL statements | DOM mutations | CD ticks |",
+                          "| --- | ---: | ---: | ---: | ---: | ---: |",
+                          (.[] | "| `\(.key)` | \(.queryCalls) | \(.ipcCalls) | \(.sqlStatements) | \(.domMutations) | \(.cdTicks) |"),
+                          ""))
               ' "$SUMMARY" | tee -a "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index df41ce995..3a8b8cf4c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -296,8 +296,8 @@ jobs:
         if: needs.performance-journeys-scope.outputs.run == 'true'
         runs-on: ubuntu-latest
         # The electron-performance build is the bulk of the time; each journey
-        # (launch, open-source, playback) is six fresh Electron processes plus
-        # one seeding run.
+        # (launch, open-source, playback, search) is six fresh Electron
+        # processes plus one seeding run.
         timeout-minutes: 30
         # Warn-only for the first two weeks of plan item B3: a failure is
         # visible on the run but does not fail the workflow.
diff --git a/apps/electron-backend-e2e/src/journeys/playback-journey-app.ts b/apps/electron-backend-e2e/src/journeys/playback-journey-app.ts
index 1068f9f83..9b80ced07 100644
--- a/apps/electron-backend-e2e/src/journeys/playback-journey-app.ts
+++ b/apps/electron-backend-e2e/src/journeys/playback-journey-app.ts
@@ -1,10 +1,14 @@
-import type { ElectronApplication, Page } from '@playwright/test';
+import type { Page } from '@playwright/test';
 
 import { configureLiveFormat } from '../xtream-live-format.fixture';
 import {
     JOURNEY_CLICK_QUIET_MS,
     waitForJourneyClickQuiet,
 } from '../performance/journey-click-settle';
+import {
+    blockJourneyExternalArtwork,
+    readJourneyExternalArtworkCancelled,
+} from '../performance/journey-external-artwork';
 import {
     detachJourneyMainIpcCapture,
     installJourneyMainIpcCapture,
@@ -47,14 +51,6 @@ export const PLAYBACK_JOURNEY_MAIN_IPC_STATE_KEY =
     '__iptvnatorJourneyPlaybackMainIpcCapture';
 export const PLAYBACK_JOURNEY_PORTAL_NAME = 'Journey live portal';
 const ERROR_PREFIX = 'playback-journey';
-const EXTERNAL_ARTWORK_STATE_KEY = '__iptvnatorJourneyExternalArtwork';
-/**
- * The generated live catalog's channel and category logos point at
- * picsum.photos. They are cancelled in the main process, so no request of
- * the journey leaves the machine and a logo never loads, or fails, at a
- * different moment on a runner with a different network.
- */
-const EXTERNAL_ARTWORK_URLS = ['*://picsum.photos/*', '*://*.picsum.photos/*'];
 
 /** Seeds J2's profile with the local-media portal and the HTML5 player. */
 export const PLAYBACK_JOURNEY_SEED: LaunchJourneySeedOptions = {
@@ -68,45 +64,6 @@ export const PLAYBACK_JOURNEY_SEED: LaunchJourneySeedOptions = {
     },
 };
 
-async function blockExternalArtwork(
-    electronApp: ElectronApplication
-): Promise<void> {
-    await electronApp.evaluate(
-        ({ session }, input) => {
-            const target = globalThis as unknown as Record<string, unknown>;
-            if (target[input.key] !== undefined) {
-                throw new Error('playback-journey-artwork-block-installed');
-            }
-            const state = { cancelled: 0 };
-            target[input.key] = state;
-            // The app registers no onBeforeRequest listener of its own
-            // (only onBeforeSendHeaders), so this replaces nothing.
-            session.defaultSession.webRequest.onBeforeRequest(
-                { urls: input.urls },
-                (_details, callback) => {
-                    state.cancelled += 1;
-                    callback({ cancel: true });
-                }
-            );
-        },
-        { key: EXTERNAL_ARTWORK_STATE_KEY, urls: EXTERNAL_ARTWORK_URLS }
-    );
-}
-
-async function readCancelledExternalArtwork(
-    electronApp: ElectronApplication
-): Promise<number> {
-    return electronApp.evaluate(
-        (_electron, key) =>
-            (
-                (globalThis as unknown as Record<string, unknown>)[key] as {
-                    cancelled: number;
-                }
-            ).cancelled,
-        EXTERNAL_ARTWORK_STATE_KEY
-    );
-}
-
 /** Dashboard card → live section → first category, as a user would. */
 async function openLiveCategory(page: Page, timeoutMs: number): Promise<void> {
     await page
@@ -143,7 +100,7 @@ export async function measurePlaybackJourney(
     if (!startClick) {
         throw new Error('playback-journey-probe-without-start');
     }
-    await blockExternalArtwork(electronApp);
+    await blockJourneyExternalArtwork(electronApp);
     await openLiveCategory(mainWindow, timeoutMs);
     const channel = mainWindow.locator(startClick.selector).first();
     await channel.waitFor({ state: 'visible', timeout: timeoutMs });
@@ -199,7 +156,7 @@ export async function measurePlaybackJourney(
     );
     return {
         externalArtworkCancelled:
-            await readCancelledExternalArtwork(electronApp),
+            await readJourneyExternalArtworkCancelled(electronApp),
         http: {
             afterPlaying: sinceSpawn.filter(
                 (entry) =>
diff --git a/apps/electron-backend-e2e/src/journeys/search-journey-app.ts b/apps/electron-backend-e2e/src/journeys/search-journey-app.ts
new file mode 100644
index 000000000..7d76b54fe
--- /dev/null
+++ b/apps/electron-backend-e2e/src/journeys/search-journey-app.ts
@@ -0,0 +1,435 @@
+import type { ElectronApplication, Page } from '@playwright/test';
+
+import {
+    blockJourneyExternalArtwork,
+    readJourneyExternalArtworkCancelled,
+} from '../performance/journey-external-artwork';
+import {
+    JOURNEY_MAIN_COUNTER,
+    JOURNEY_PERFORMANCE_COUNTERS_CHANNEL,
+} from '../performance/journey-main-counters';
+import {
+    countJourneyMainIpcInFlight,
+    detachJourneyMainIpcCapture,
+    installJourneyMainIpcCapture,
+    JOURNEY_MAIN_IPC_STATE_KEY,
+    JOURNEY_RENDERER_API_TRACE_CHANNEL,
+    peekJourneyMainIpcCaptures,
+    readJourneyMainIpcCapture,
+} from '../performance/journey-main-ipc-capture';
+import { waitForJourneyQuiet } from '../performance/journey-quiet-wait';
+import {
+    armSearchJourneyProbe,
+    createSearchJourneyProbeOptions,
+    readSearchJourneyPreStartMutations,
+    type SearchJourneyProbeOptions,
+    SEARCH_JOURNEY_INPUT_SELECTOR,
+    SEARCH_JOURNEY_ROUTE_PATH,
+    waitForSearchJourneyProbe,
+} from '../performance/search-journey-probe';
+import {
+    SEARCH_JOURNEY_QUERY_METHOD,
+    type SearchJourneyActivitySample,
+    type SearchJourneyMeasurement,
+    type SearchJourneyQueryTraceEntry,
+    type SearchJourneySettle,
+} from '../performance/search-journey-record';
+import { JOURNEY_RENDERER_GATE_KEY } from './journey-renderer-gate-client';
+import type {
+    LaunchJourneySeedOptions,
+    LaunchJourneySession,
+} from './launch-journey-app';
+
+/**
+ * J4 "Search": runs inside a process that J1 has just launched with the
+ * main-process counters on (SQL statements are counted). The test opens
+ * global search from the rail and focuses the header search box (not
+ * measured), lets the app settle, then types the query one key at a time
+ * at a fixed interval and measures until the results have settled.
+ *
+ * Main-process activity (bridge calls, SQL statements) is sampled before
+ * every keystroke, so the record can show what each key caused: with the
+ * shell's debounce, only the last interval should run a query. Contract:
+ * docs/architecture/performance-journeys.md.
+ */
+export const SEARCH_JOURNEY_MAIN_IPC_STATE_KEY =
+    '__iptvnatorJourneySearchMainIpcCapture';
+export const SEARCH_JOURNEY_PORTAL_NAME = 'Journey search portal';
+/**
+ * Six characters; on the mock's `large` account (12,000 items) the term
+ * matches 170 series titles, more than the first page of 100.
+ */
+export const SEARCH_JOURNEY_QUERY = 'system';
+/** Well below the shell's 350 ms input debounce, like steady typing. */
+export const SEARCH_JOURNEY_KEY_DELAY_MS = 100;
+const QUIET_MS = 1_000;
+const QUIET_POLL_MS = 100;
+const QUIET_TIMEOUT_MS = 30_000;
+const AFTER_SETTLED_WINDOW_MS = 500;
+const ERROR_PREFIX = 'search-journey';
+
+/** J1's M3U source plus the mock's existing 12,000-item `large` catalog. */
+export const SEARCH_JOURNEY_SEED: LaunchJourneySeedOptions = {
+    portal: {
+        name: SEARCH_JOURNEY_PORTAL_NAME,
+        password: 'large',
+        username: 'large',
+    },
+};
+
+/**
+ * One synchronous pass in the main process: the capture's counts and the
+ * registered counters handler (which reads the registry synchronously), so
+ * no bridge call or SQL report can land between the two reads.
+ */
+async function sampleActivity(
+    electronApp: ElectronApplication
+): Promise<SearchJourneyActivitySample> {
+    return electronApp.evaluate(
+        async (_electron, input) => {
+            const target = globalThis as unknown as Record<string, unknown>;
+            const capture = target[input.captureKey] as
+                | {
+                      callsBeforeSentinel: number;
+                      callsByMethod: Record<string, number>;
+                  }
+                | undefined;
+            const gate = target[input.gateKey] as
+                | { invokeHandler?: (channel: string) => Promise<unknown> }
+                | undefined;
+            if (!capture || typeof gate?.invokeHandler !== 'function') {
+                throw new Error('search-journey-sample-unavailable');
+            }
+            const ipcCalls = capture.callsBeforeSentinel;
+            const queryCalls = capture.callsByMethod[input.queryMethod] ?? 0;
+            const pending = gate.invokeHandler(input.channel);
+            const snapshot = (await pending) as {
+                counters?: Record<string, number>;
+            } | null;
+            const sqlStatements = snapshot?.counters?.[input.sqlCounter];
+            if (typeof sqlStatements !== 'number') {
+                throw new Error('search-journey-sql-counter-missing');
+            }
+            return { ipcCalls, queryCalls, sqlStatements };
+        },
+        {
+            captureKey: SEARCH_JOURNEY_MAIN_IPC_STATE_KEY,
+            channel: JOURNEY_PERFORMANCE_COUNTERS_CHANNEL,
+            gateKey: JOURNEY_RENDERER_GATE_KEY,
+            queryMethod: SEARCH_JOURNEY_QUERY_METHOD,
+            sqlCounter: JOURNEY_MAIN_COUNTER.SQL_STATEMENTS,
+        }
+    );
+}
+
+/**
+ * Waits until DOM, bridge calls (started and in flight) and SQL statements
+ * have all been unchanged for `QUIET_MS`, so leftovers of the launch and of
+ * the navigation to global search are not attributed to the first key.
+ */
+async function waitForSearchQuiet(
+    electronApp: ElectronApplication,
+    page: Page,
+    probeStateKey: string
+): Promise<SearchJourneySettle> {
+    const { sample, waitedMs } = await waitForJourneyQuiet({
+        inFlight: (activity) => activity.ipcInFlight,
+        pollMs: QUIET_POLL_MS,
+        quietMs: QUIET_MS,
+        sample: async () => {
+            const [launchCapture, journeyCapture] =
+                await peekJourneyMainIpcCaptures(electronApp, [
+                    JOURNEY_MAIN_IPC_STATE_KEY,
+                    SEARCH_JOURNEY_MAIN_IPC_STATE_KEY,
+                ]);
+            if (launchCapture.unmatchedCompletions > 0) {
+                throw new Error(`${ERROR_PREFIX}-bridge-completions-unmatched`);
+            }
+            return {
+                domMutations: await readSearchJourneyPreStartMutations(
+                    page,
+                    probeStateKey
+                ),
+                ipcCalls: journeyCapture.callsBeforeStart,
+                ipcInFlight: countJourneyMainIpcInFlight(launchCapture),
+                sqlStatements: (await sampleActivity(electronApp))
+                    .sqlStatements,
+            };
+        },
+        timeoutError: (activity) =>
+            new Error(`${ERROR_PREFIX}-not-quiet: ${JSON.stringify(activity)}`),
+        timeoutMs: QUIET_TIMEOUT_MS,
+    });
+    return {
+        preStartDomMutations: sample.domMutations,
+        preStartIpcCalls: sample.ipcCalls,
+        quietMs: QUIET_MS,
+        sqlStatements: sample.sqlStatements,
+        waitedMs,
+    };
+}
+
+function sleepUntil(epochMs: number): Promise<void> {
+    const remainingMs = epochMs - Date.now();
+    return remainingMs > 0
+        ? new Promise((resolve) => setTimeout(resolve, remainingMs))
+        : Promise.resolve();
+}
+
+const QUERY_TRACE_KEY = '__iptvnatorJourneySearchQueryTrace';
+
+/**
+ * Records every trace event of the query method in the main process, with
+ * the term and result length the preload's summaries carry and the main
+ * process's arrival epoch (the clock the IPC capture stamps its sentinels
+ * with). The record uses it to prove the final term's query completed
+ * before the settle, so results of an earlier term cannot end the journey.
+ * The summaries hold the search term and counts only.
+ */
+async function traceQueryCalls(
+    electronApp: ElectronApplication
+): Promise<void> {
+    await electronApp.evaluate(
+        ({ ipcMain }, input) => {
+            const entries: unknown[] = [];
+            (globalThis as unknown as Record<string, unknown>)[input.key] =
+                entries;
+            ipcMain.on(input.channel, (_event, payload: unknown) => {
+                const record = payload as Record<string, unknown> | null;
+                if (record?.['method'] !== input.method) return;
+                const args = record['args'] as { items?: unknown[] } | null;
+                const result = record['result'] as { length?: unknown } | null;
+                const term = args?.items?.[0];
+                entries.push({
+                    epochMs: Date.now(),
+                    phase: String(record['phase']),
+                    resultLength:
+                        typeof result?.length === 'number'
+                            ? result.length
+                            : null,
+                    term: typeof term === 'string' ? term : null,
+                });
+            });
+        },
+        {
+            channel: JOURNEY_RENDERER_API_TRACE_CHANNEL,
+            key: QUERY_TRACE_KEY,
+            method: SEARCH_JOURNEY_QUERY_METHOD,
+        }
+    );
+}
+
+const SENTINEL_SQL_KEY = '__iptvnatorJourneySearchSentinelSql';
+
+/**
+ * Reads `main.sqlStatements` in the main process when the start and the end
+ * sentinel arrive, so the SQL counter covers exactly the IPC capture's
+ * window: database work just before the first key or after the settle is
+ * not counted. The gate's `invokeHandler` runs the counters handler
+ * synchronously, so the value is the total at the sentinel's arrival even
+ * though it is stored when the promise settles.
+ */
+async function stampSqlAtSentinels(
+    electronApp: ElectronApplication,
+    probeOptions: SearchJourneyProbeOptions
+): Promise<void> {
+    await electronApp.evaluate(
+        ({ ipcMain }, input) => {
+            const target = globalThis as unknown as Record<string, unknown>;
+            const gate = target[input.gateKey] as {
+                invokeHandler: (channel: string) => Promise<unknown>;
+            };
+            const state: Record<'end' | 'start', number | null> = {
+                end: null,
+                start: null,
+            };
+            target[input.key] = state;
+            ipcMain.on(input.channel, (_event, payload: unknown) => {
+                const record = payload as Record<string, unknown> | null;
+                if (
+                    record?.['method'] !== input.sentinelMethod ||
+                    record['phase'] !== 'start'
+                ) {
+                    return;
+                }
+                const args = JSON.stringify(record['args'] ?? null);
+                const which = args.includes(input.startId)
+                    ? 'start'
+                    : args.includes(input.endId)
+                      ? 'end'
+                      : null;
+                if (which === null || state[which] !== null) return;
+                void gate
+                    .invokeHandler(input.countersChannel)
+                    .then((snapshot) => {
+                        const value = (
+                            snapshot as { counters?: Record<string, number> }
+                        )?.counters?.[input.sqlCounter];
+                        state[which] = typeof value === 'number' ? value : null;
+                    });
+            });
+        },
+        {
+            channel: JOURNEY_RENDERER_API_TRACE_CHANNEL,
+            countersChannel: JOURNEY_PERFORMANCE_COUNTERS_CHANNEL,
+            endId: probeOptions.endSentinelId,
+            gateKey: JOURNEY_RENDERER_GATE_KEY,
+            key: SENTINEL_SQL_KEY,
+            sentinelMethod: probeOptions.sentinelMethod,
+            sqlCounter: JOURNEY_MAIN_COUNTER.SQL_STATEMENTS,
+            startId: probeOptions.startSentinelId,
+        }
+    );
+}
+
+async function readQueryTrace(
+    electronApp: ElectronApplication
+): Promise<SearchJourneyQueryTraceEntry[]> {
+    return electronApp.evaluate(
+        (_electron, key) =>
+            JSON.parse(
+                JSON.stringify(
+                    (globalThis as unknown as Record<string, unknown>)[key]
+                )
+            ) as SearchJourneyQueryTraceEntry[],
+        QUERY_TRACE_KEY
+    );
+}
+
+/**
+ * What a failed settle saw: the bridge calls of the search, renderer errors
+ * (a search that threw shows the same empty view as one that found
+ * nothing), SQL statements before each key and now, and the traced query
+ * calls with their terms and result lengths.
+ */
+async function describeSettleFailure(
+    electronApp: ElectronApplication,
+    samples: readonly SearchJourneyActivitySample[],
+    consoleErrors: readonly string[]
+): Promise<string> {
+    const [capture] = await peekJourneyMainIpcCaptures(electronApp, [
+        SEARCH_JOURNEY_MAIN_IPC_STATE_KEY,
+    ]);
+    const now = await sampleActivity(electronApp);
+    const queryTrace = await readQueryTrace(electronApp);
+    return JSON.stringify({
+        bridgeCalls: capture.callsByMethod,
+        consoleErrors,
+        queryTrace,
+        sqlBeforeKeysAndNow: [...samples, now].map(
+            (entry) => entry.sqlStatements
+        ),
+    });
+}
+
+/** Rail link → global search, then focus the header box. Not measured. */
+async function openGlobalSearch(page: Page, timeoutMs: number): Promise<void> {
+    await page
+        .getByRole('link', { name: 'Global search', exact: true })
+        .click({ timeout: timeoutMs });
+    // A router navigation, not a document load: wait on the path itself.
+    await page
+        .waitForFunction(
+            (path) => location.pathname.endsWith(path),
+            SEARCH_JOURNEY_ROUTE_PATH,
+            { timeout: timeoutMs }
+        )
+        .catch((failure: unknown) => {
+            throw new Error(
+                `${ERROR_PREFIX}-route-not-reached: ${page.url()} (${String(failure)})`
+            );
+        });
+    const input = page.locator(SEARCH_JOURNEY_INPUT_SELECTOR);
+    await input.waitFor({ state: 'visible', timeout: timeoutMs });
+    await input.focus({ timeout: timeoutMs });
+}
+
+export async function measureSearchJourney(
+    session: LaunchJourneySession,
+    timeoutMs: number
+): Promise<SearchJourneyMeasurement> {
+    const { electronApp, mainWindow } = session;
+    const query = SEARCH_JOURNEY_QUERY;
+    const probeOptions = createSearchJourneyProbeOptions(query);
+    // Kept for the message of a failed settle.
+    const consoleErrors: string[] = [];
+    mainWindow.on('console', (message) => {
+        if (message.type() === 'error' && consoleErrors.length < 10) {
+            consoleErrors.push(message.text().slice(0, 300));
+        }
+    });
+    await blockJourneyExternalArtwork(electronApp);
+    await traceQueryCalls(electronApp);
+    await stampSqlAtSentinels(electronApp, probeOptions);
+    await openGlobalSearch(mainWindow, timeoutMs);
+    await installJourneyMainIpcCapture(electronApp, {
+        channel: JOURNEY_RENDERER_API_TRACE_CHANNEL,
+        sentinelId: probeOptions.endSentinelId,
+        sentinelMethod: probeOptions.sentinelMethod,
+        startSentinelId: probeOptions.startSentinelId,
+        stateKey: SEARCH_JOURNEY_MAIN_IPC_STATE_KEY,
+    });
+    await armSearchJourneyProbe(mainWindow, probeOptions);
+    const settle = await waitForSearchQuiet(
+        electronApp,
+        mainWindow,
+        probeOptions.stateKey
+    );
+    await detachJourneyMainIpcCapture(electronApp, JOURNEY_MAIN_IPC_STATE_KEY);
+    const focused = await mainWindow
+        .locator(SEARCH_JOURNEY_INPUT_SELECTOR)
+        .evaluate((input) => input === document.activeElement);
+    if (!focused) {
+        throw new Error(`${ERROR_PREFIX}-input-not-focused`);
+    }
+    // One `keyboard.type` per character on a fixed schedule, so the
+    // main-process sample before each key sits between two keystrokes.
+    const samples: SearchJourneyActivitySample[] = [];
+    const firstKeyAtMs = Date.now();
+    for (let position = 0; position < query.length; position += 1) {
+        await sleepUntil(firstKeyAtMs + position * SEARCH_JOURNEY_KEY_DELAY_MS);
+        samples.push(await sampleActivity(electronApp));
+        await mainWindow.keyboard.type(query[position]);
+    }
+    const renderer = await waitForSearchJourneyProbe(
+        mainWindow,
+        probeOptions.stateKey,
+        timeoutMs
+    ).catch(async (failure: unknown) => {
+        throw new Error(
+            `${String(failure)} ${await describeSettleFailure(electronApp, samples, consoleErrors)}`
+        );
+    });
+    const ipc = await readJourneyMainIpcCapture(
+        electronApp,
+        SEARCH_JOURNEY_MAIN_IPC_STATE_KEY,
+        10_000
+    );
+    samples.push(await sampleActivity(electronApp));
+    await new Promise((resolve) =>
+        setTimeout(resolve, AFTER_SETTLED_WINDOW_MS)
+    );
+    return {
+        afterSettled: await sampleActivity(electronApp),
+        afterSettledWindowMs: AFTER_SETTLED_WINDOW_MS,
+        externalArtworkCancelled:
+            await readJourneyExternalArtworkCancelled(electronApp),
+        ipc,
+        keyDelayMs: SEARCH_JOURNEY_KEY_DELAY_MS,
+        pid: session.launch.pid,
+        query,
+        queryTrace: await readQueryTrace(electronApp),
+        sqlAtSentinels: await electronApp.evaluate(
+            (_electron, key) =>
+                JSON.parse(
+                    JSON.stringify(
+                        (globalThis as unknown as Record<string, unknown>)[key]
+                    )
+                ) as SearchJourneyMeasurement['sqlAtSentinels'],
+            SENTINEL_SQL_KEY
+        ),
+        renderer,
+        samples,
+        settle,
+    };
+}
diff --git a/apps/electron-backend-e2e/src/journeys/search.journey.ts b/apps/electron-backend-e2e/src/journeys/search.journey.ts
new file mode 100644
index 000000000..5663b4f27
--- /dev/null
+++ b/apps/electron-backend-e2e/src/journeys/search.journey.ts
@@ -0,0 +1,79 @@
+import { test } from '@playwright/test';
+
+import type { JourneyIterationRecord } from '../performance/journey-summary';
+import {
+    SEARCH_JOURNEY_ID,
+    SEARCH_JOURNEY_UNAVAILABLE_COUNTERS,
+    toSearchIterationRecord,
+} from '../performance/search-journey-record';
+import {
+    JOURNEY_ITERATION_TIMEOUT_MS,
+    JOURNEY_MEASURED_ITERATIONS,
+    JOURNEY_WARMUP_ITERATIONS,
+    logJourneyIteration,
+    writeJourneyRunEntry,
+} from './journey-run';
+import {
+    LAUNCH_JOURNEY_MOCK_ORIGIN,
+    removeLaunchJourneyProfile,
+    runLaunchJourney,
+    seedLaunchJourneyProfile,
+} from './launch-journey-app';
+import {
+    measureSearchJourney,
+    SEARCH_JOURNEY_SEED,
+} from './search-journey-app';
+
+/**
+ * J4 "Search": type a six-character query into the header search box on
+ * /workspace/search until the global search results have settled. Every
+ * iteration is a fresh J1 launch on a copy of the seeded profile (one M3U
+ * source and the mock's 12,000-item `large` Xtream catalog), with the
+ * main-process counters on so SQL statements are counted.
+ * Contract: docs/architecture/performance-journeys.md.
+ */
+test.describe.configure({ mode: 'serial' });
+
+test('J4 search', async () => {
+    const iterations: JourneyIterationRecord[] = [];
+    let electronVersion = 'unknown';
+    const templateDirectory = await seedLaunchJourneyProfile(
+        LAUNCH_JOURNEY_MOCK_ORIGIN,
+        SEARCH_JOURNEY_SEED
+    );
+    try {
+        const total = JOURNEY_WARMUP_ITERATIONS + JOURNEY_MEASURED_ITERATIONS;
+        for (let index = 0; index < total; index += 1) {
+            const warmup = index < JOURNEY_WARMUP_ITERATIONS;
+            const { continuation, launch } = await runLaunchJourney(
+                templateDirectory,
+                JOURNEY_ITERATION_TIMEOUT_MS,
+                // SQL statements are a J4 counter, so unlike J2 and J3 the
+                // launch runs with the main-process counters and SQL hook.
+                { idleWindowMs: null, mainCounters: true },
+                (session) =>
+                    measureSearchJourney(
+                        session,
+                        JOURNEY_ITERATION_TIMEOUT_MS
+                    ).catch((failure: unknown) => {
+                        throw new Error(
+                            `iteration ${index}: ${String(failure)}`
+                        );
+                    })
+            );
+            electronVersion = launch.electronVersion;
+            const record = toSearchIterationRecord(index, warmup, continuation);
+            iterations.push(record);
+            logJourneyIteration(SEARCH_JOURNEY_ID, record);
+        }
+    } finally {
+        await removeLaunchJourneyProfile(templateDirectory);
+    }
+
+    await writeJourneyRunEntry(
+        SEARCH_JOURNEY_ID,
+        iterations,
+        SEARCH_JOURNEY_UNAVAILABLE_COUNTERS,
+        electronVersion
+    );
+});
diff --git a/apps/electron-backend-e2e/src/performance/journey-external-artwork.ts b/apps/electron-backend-e2e/src/performance/journey-external-artwork.ts
new file mode 100644
index 000000000..e9cd7ce12
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/journey-external-artwork.ts
@@ -0,0 +1,51 @@
+import type { ElectronApplication } from '@playwright/test';
+
+/**
+ * The mock's generated catalogs point channel, category, poster and cover
+ * artwork at picsum.photos. Journeys that render that artwork (J3, J4)
+ * cancel those requests in the main process, so no request of the journey
+ * leaves the machine and an image never loads, or fails, at a different
+ * moment on a runner with a different network. Contract:
+ * docs/architecture/performance-journeys.md.
+ */
+const EXTERNAL_ARTWORK_STATE_KEY = '__iptvnatorJourneyExternalArtwork';
+const EXTERNAL_ARTWORK_URLS = ['*://picsum.photos/*', '*://*.picsum.photos/*'];
+
+export async function blockJourneyExternalArtwork(
+    electronApp: ElectronApplication
+): Promise<void> {
+    await electronApp.evaluate(
+        ({ session }, input) => {
+            const target = globalThis as unknown as Record<string, unknown>;
+            if (target[input.key] !== undefined) {
+                throw new Error('journey-artwork-block-installed');
+            }
+            const state = { cancelled: 0 };
+            target[input.key] = state;
+            // The app registers no onBeforeRequest listener of its own
+            // (only onBeforeSendHeaders), so this replaces nothing.
+            session.defaultSession.webRequest.onBeforeRequest(
+                { urls: input.urls },
+                (_details, callback) => {
+                    state.cancelled += 1;
+                    callback({ cancel: true });
+                }
+            );
+        },
+        { key: EXTERNAL_ARTWORK_STATE_KEY, urls: EXTERNAL_ARTWORK_URLS }
+    );
+}
+
+export async function readJourneyExternalArtworkCancelled(
+    electronApp: ElectronApplication
+): Promise<number> {
+    return electronApp.evaluate(
+        (_electron, key) =>
+            (
+                (globalThis as unknown as Record<string, unknown>)[key] as {
+                    cancelled: number;
+                }
+            ).cancelled,
+        EXTERNAL_ARTWORK_STATE_KEY
+    );
+}
diff --git a/apps/electron-backend-e2e/src/performance/journey-launch-environment.ts b/apps/electron-backend-e2e/src/performance/journey-launch-environment.ts
index acd9f58af..d109a2d8f 100644
--- a/apps/electron-backend-e2e/src/performance/journey-launch-environment.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-launch-environment.ts
@@ -2,8 +2,8 @@
  * Instrumentation flags a journey launch sets on the Electron process.
  *
  * Every journey needs the renderer-API trace (`IPTVNATOR_TRACE_IPC`) for its
- * IPC counters. Only J1 records the main-process counters:
- * `IPTVNATOR_PERF_CAPTURE` turns on the counters and their read handler, and
+ * IPC counters. Only J1 and J4 (for its SQL count) record the main-process
+ * counters: `IPTVNATOR_PERF_CAPTURE` turns on the counters and their read handler, and
  * `IPTVNATOR_PERF_COUNT_SQL` wraps every main-thread and worker SQLite
  * statement to count it (see journey-main-counters.ts). A journey that
  * continues from the launch without reading them (J2) leaves both off, so
diff --git a/apps/electron-backend-e2e/src/performance/journey-main-counters.spec.ts b/apps/electron-backend-e2e/src/performance/journey-main-counters.spec.ts
index 7b02bc5f0..4d07ef2b8 100644
--- a/apps/electron-backend-e2e/src/performance/journey-main-counters.spec.ts
+++ b/apps/electron-backend-e2e/src/performance/journey-main-counters.spec.ts
@@ -127,7 +127,7 @@ test('rejects snapshots that were not frozen at the moments they claim', () => {
     );
 });
 
-test('only the launch journey opts into SQL statement counting', () => {
+test('only the launch and search journeys opt into SQL statement counting', () => {
     // The import benchmarks also run with IPTVNATOR_PERF_CAPTURE=1; the SQL
     // hook wraps every row of a bulk insert, so they must not enable it.
     const sourceRoot = resolve(__dirname, '..');
@@ -146,12 +146,25 @@ test('only the launch journey opts into SQL statement counting', () => {
     assert.deepEqual(containing(/IPTVNATOR_PERF_COUNT_SQL/), [
         join('performance', 'journey-launch-environment.ts'),
     ]);
-    // ...and only J1's launch asks for them there. Another journey that
+    // ...and only J1's launch and J4, which records the count as
+    // renderer.sqlStatementsPerSearch, ask for them. Another journey that
     // passed `mainCounters: true` to runLaunchJourney would be measured
     // under the statement hook without recording its count.
-    assert.deepEqual(containing(/mainCounters:\s*true/), [
+    assert.deepEqual(containing(/mainCounters:\s*true/).sort(), [
         join('journeys', 'launch-journey-app.ts'),
+        join('journeys', 'search.journey.ts'),
     ]);
+    assert.match(
+        readFileSync(join(sourceRoot, 'journeys', 'search.journey.ts'), 'utf8'),
+        /\{ idleWindowMs: null, mainCounters: true \}/
+    );
+    assert.match(
+        readFileSync(
+            join(sourceRoot, 'performance', 'search-journey-record.ts'),
+            'utf8'
+        ),
+        /SQL_STATEMENTS: 'renderer\.sqlStatementsPerSearch'/
+    );
     const launchApp = readFileSync(
         join(sourceRoot, 'journeys', 'launch-journey-app.ts'),
         'utf8'
diff --git a/apps/electron-backend-e2e/src/performance/search-journey-probe.spec.ts b/apps/electron-backend-e2e/src/performance/search-journey-probe.spec.ts
new file mode 100644
index 000000000..7c7d9e66d
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/search-journey-probe.spec.ts
@@ -0,0 +1,348 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { JSDOM } from 'jsdom';
+
+import {
+    JOURNEY_CD_TICK_COUNTER_KEY,
+    JOURNEY_IPC_SENTINEL_METHOD,
+    JOURNEY_PLAYBACK_PROBE_STATE_KEY,
+    JOURNEY_PROBE_STATE_KEY,
+} from './journey-renderer-probe';
+import {
+    installFakePerformance,
+    type FakeObserver,
+} from './journey-renderer-probe.test-helpers';
+import {
+    assertSearchJourneyProbeState,
+    createSearchJourneyProbeOptions,
+    SEARCH_JOURNEY_END_SENTINEL_ID,
+    SEARCH_JOURNEY_PROBE_STATE_KEY,
+    SEARCH_JOURNEY_START_SENTINEL_ID,
+    searchJourneyProbeScript,
+    type SearchJourneyProbeOptions,
+    type SearchJourneyProbeState,
+} from './search-journey-probe';
+
+const QUERY = 'system';
+
+interface SearchFixture {
+    readonly bridgeCalls: unknown[];
+    readonly input: HTMLInputElement;
+    readonly observers: FakeObserver[];
+    readonly results: HTMLElement;
+    readonly state: () => SearchJourneyProbeState;
+    readonly ticks: { count: number };
+    readonly window: JSDOM['window'];
+}
+
+function createSearchFixture(
+    overrides: Partial<SearchJourneyProbeOptions> = {}
+): SearchFixture {
+    const dom = new JSDOM(
+        `<!doctype html><html><body><app-root>
+<app-workspace-shell-header><label class="search-field">
+<input type="search" /></label></app-workspace-shell-header>
+<button id="elsewhere">x</button>
+<app-search-results><div class="results-container"></div></app-search-results>
+</app-root></body></html>`,
+        {
+            pretendToBeVisual: true,
+            runScripts: 'outside-only',
+            url: 'http://localhost/workspace/search',
+        }
+    );
+    const { window } = dom;
+    const observers: FakeObserver[] = [];
+    const bridgeCalls: unknown[] = [];
+    installFakePerformance(window, observers);
+    // See journey-renderer-probe.test-helpers.ts: tsx keeps names.
+    Object.defineProperty(window, '__name', {
+        configurable: true,
+        value: (target: unknown) => target,
+    });
+    Object.defineProperty(window, 'electron', {
+        configurable: true,
+        value: Object.freeze({
+            [JOURNEY_IPC_SENTINEL_METHOD]: (id: unknown) => {
+                bridgeCalls.push(id);
+                return Promise.resolve(null);
+            },
+        }),
+    });
+    const ticks = { count: 40 };
+    Object.defineProperty(window, JOURNEY_CD_TICK_COUNTER_KEY, {
+        configurable: true,
+        value: ticks,
+    });
+    const options = {
+        ...createSearchJourneyProbeOptions(QUERY),
+        quietMs: 30,
+        ...overrides,
+    };
+    window.eval(
+        `(${searchJourneyProbeScript.toString()})(${JSON.stringify(options)})`
+    );
+    const { document } = window;
+    return {
+        bridgeCalls,
+        input: document.querySelector('input') as HTMLInputElement,
+        observers,
+        results: document.querySelector('.results-container') as HTMLElement,
+        state: () =>
+            JSON.parse(
+                JSON.stringify(
+                    (window as unknown as Record<string, unknown>)[
+                        options.stateKey
+                    ]
+                )
+            ) as SearchJourneyProbeState,
+        ticks,
+        window,
+    };
+}
+
+function wait(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** A keydown in the input plus what the shell renders for it. */
+async function typeKey(fixture: SearchFixture, key: string): Promise<void> {
+    fixture.input.dispatchEvent(
+        new fixture.window.KeyboardEvent('keydown', { bubbles: true, key })
+    );
+    fixture.input.setAttribute('data-value', fixture.input.value + key);
+    fixture.input.value += key;
+    await wait(0);
+}
+
+function setQuery(fixture: SearchFixture, query: string): void {
+    fixture.window.history.replaceState(
+        null,
+        '',
+        `/workspace/search?q=${encodeURIComponent(query)}`
+    );
+}
+
+function addCards(fixture: SearchFixture, count: number): void {
+    for (let index = 0; index < count; index += 1) {
+        fixture.results.append(
+            fixture.window.document.createElement('app-content-card')
+        );
+    }
+}
+
+async function waitForFinal(fixture: SearchFixture): Promise<void> {
+    const deadline = Date.now() + 2_000;
+    while (!fixture.state().final && Date.now() < deadline) {
+        await wait(5);
+    }
+}
+
+test('search options use their own state key, sentinels and the query length', () => {
+    const options = createSearchJourneyProbeOptions(QUERY);
+    assert.equal(options.keystrokes, 6);
+    assert.equal(options.query, QUERY);
+    assert.equal(options.quietMs, 200);
+    assert.equal(options.stateKey, SEARCH_JOURNEY_PROBE_STATE_KEY);
+    assert.notEqual(options.stateKey, JOURNEY_PROBE_STATE_KEY);
+    assert.notEqual(options.stateKey, JOURNEY_PLAYBACK_PROBE_STATE_KEY);
+    assert.equal(options.startSentinelId, SEARCH_JOURNEY_START_SENTINEL_ID);
+    assert.equal(options.endSentinelId, SEARCH_JOURNEY_END_SENTINEL_ID);
+    assert.equal(options.sentinelMethod, JOURNEY_IPC_SENTINEL_METHOD);
+    assert.equal(options.cdTickCounterKey, JOURNEY_CD_TICK_COUNTER_KEY);
+});
+
+test('starts at the first keydown in the search box and buckets work per key', async () => {
+    const fixture = createSearchFixture();
+    fixture.results.setAttribute('data-before', '1');
+    await wait(0);
+    // A key elsewhere does not start the journey.
+    fixture.window.document.getElementById('elsewhere')?.dispatchEvent(
+        new fixture.window.KeyboardEvent('keydown', {
+            bubbles: true,
+            key: 'x',
+        })
+    );
+    assert.equal(fixture.state().start, null);
+    assert.deepEqual(fixture.bridgeCalls, []);
+
+    for (const key of QUERY) {
+        fixture.ticks.count += 1;
+        await typeKey(fixture, key);
+    }
+    let state = fixture.state();
+    assert.equal(state.preStart.domMutations, 1);
+    assert.deepEqual(fixture.bridgeCalls, [SEARCH_JOURNEY_START_SENTINEL_ID]);
+    assert.deepEqual(
+        state.keystrokes.map((key) => key.key),
+        [...QUERY]
+    );
+    assert.deepEqual(
+        state.keystrokes.map((key) => key.ticks),
+        [41, 42, 43, 44, 45, 46]
+    );
+    // One attribute record per key, each in its own bucket.
+    assert.deepEqual(state.domMutationsByKeystroke, [1, 1, 1, 1, 1, 1]);
+
+    // The debounced term lands: results for the final query.
+    setQuery(fixture, QUERY);
+    fixture.ticks.count += 4;
+    addCards(fixture, 3);
+    await waitForFinal(fixture);
+    state = assertSearchJourneyProbeState(fixture.state());
+    assert.equal(state.settle.status, 'quiet');
+    assert.equal(state.settle.query, QUERY);
+    assert.equal(state.settle.cardCount, 3);
+    assert.equal(state.settle.ticks, 50);
+    assert.equal(state.capabilities.changeDetectionTicks, 'counted');
+    assert.deepEqual(state.domMutationsByKeystroke, [1, 1, 1, 1, 1, 4]);
+    assert.equal(state.counters.domMutations, 9);
+    assert.equal(state.firstResult?.query, QUERY);
+    assert.equal(state.firstResult?.cardCount, 3);
+    assert.ok(
+        (state.settle.confirmedEpochMs ?? 0) - (state.settle.epochMs ?? 0) >= 25
+    );
+    assert.deepEqual(fixture.bridgeCalls, [
+        SEARCH_JOURNEY_START_SENTINEL_ID,
+        SEARCH_JOURNEY_END_SENTINEL_ID,
+    ]);
+});
+
+test('does not settle on results for an intermediate term or while loading', async () => {
+    const fixture = createSearchFixture();
+    for (const key of QUERY) {
+        await typeKey(fixture, key);
+    }
+    // Results of an earlier term are a first result, not the settle.
+    setQuery(fixture, 'syst');
+    addCards(fixture, 2);
+    await wait(80);
+    let state = fixture.state();
+    assert.equal(state.final, false);
+    assert.equal(state.firstResult?.query, 'syst');
+
+    // The final term's spinner keeps the window closed.
+    setQuery(fixture, QUERY);
+    const spinner = fixture.window.document.createElement('div');
+    spinner.className = 'loading-state';
+    fixture.window.document
+        .querySelector('app-search-results')
+        ?.append(spinner);
+    await wait(80);
+    assert.equal(fixture.state().final, false);
+
+    spinner.remove();
+    await waitForFinal(fixture);
+    state = assertSearchJourneyProbeState(fixture.state());
+    assert.equal(state.settle.query, QUERY);
+    assert.equal(state.settle.cardCount, 2);
+});
+
+test('a mutation inside the quiet window restarts it', async () => {
+    const fixture = createSearchFixture({ quietMs: 60 });
+    for (const key of QUERY) {
+        await typeKey(fixture, key);
+    }
+    setQuery(fixture, QUERY);
+    addCards(fixture, 1);
+    await wait(30);
+    addCards(fixture, 1);
+    const lastMutationAt = Date.now();
+    await waitForFinal(fixture);
+    const state = assertSearchJourneyProbeState(fixture.state());
+    assert.equal(state.settle.cardCount, 2);
+    assert.ok(Date.now() - lastMutationAt >= 55);
+});
+
+test('fails the iteration when results never settle', async () => {
+    const fixture = createSearchFixture({ settleTimeoutMs: 40 });
+    for (const key of QUERY) {
+        await typeKey(fixture, key);
+    }
+    await waitForFinal(fixture);
+    const state = fixture.state();
+    assert.equal(state.settle.status, 'timeout');
+    assert.throws(
+        () => assertSearchJourneyProbeState(state),
+        /search-journey-probe-invalid: settle-timeout/
+    );
+});
+
+test('flags a keystroke beyond the expected count', async () => {
+    const fixture = createSearchFixture({ keystrokes: 2 });
+    await typeKey(fixture, 'a');
+    await typeKey(fixture, 'b');
+    await typeKey(fixture, 'c');
+    assert.deepEqual(fixture.state().invalidReasons, ['unexpected-keystroke']);
+});
+
+test('counts shifts and long tasks from the first key until the settle only', async () => {
+    const fixture = createSearchFixture();
+    const shifts = fixture.observers.find(
+        (observer) => observer.type === 'layout-shift'
+    );
+    const tasks = fixture.observers.find(
+        (observer) => observer.type === 'longtask'
+    );
+    assert.ok(shifts && tasks);
+    // Buffered launch entries before the first key are dropped.
+    shifts.emit([{ entryType: 'layout-shift', startTime: 0, value: 0.5 }]);
+    tasks.emit([{ duration: 60, entryType: 'longtask', startTime: 0 }]);
+    // jsdom's clock starts with the fixture: let that task end first.
+    await wait(100);
+    for (const key of QUERY) {
+        await typeKey(fixture, key);
+    }
+    const now = fixture.window.performance.now();
+    shifts.emit([
+        {
+            entryType: 'layout-shift',
+            hadRecentInput: true,
+            startTime: now,
+            value: 0.02,
+        },
+        { entryType: 'layout-shift', startTime: now, value: 0.01 },
+    ]);
+    tasks.emit([
+        { duration: 30, entryType: 'longtask', startTime: now },
+        { duration: 80, entryType: 'longtask', startTime: now },
+    ]);
+    setQuery(fixture, QUERY);
+    addCards(fixture, 1);
+    await waitForFinal(fixture);
+    const state = assertSearchJourneyProbeState(fixture.state());
+    assert.equal(state.counters.recentInputLayoutShiftScore, 0.02);
+    assert.equal(state.counters.layoutShiftScore, 0.01);
+    assert.equal(state.counters.longTasks, 1);
+    assert.deepEqual(state.longTaskDurationsMs, [80]);
+    assert.ok(shifts.disconnected && tasks.disconnected);
+});
+
+test('rejects a state without the tick counter or the end sentinel', () => {
+    assert.throws(
+        () => assertSearchJourneyProbeState({ schemaVersion: 1 }),
+        /search-journey-probe-incomplete/
+    );
+    const base = {
+        capabilities: { layoutShift: true, longTask: true },
+        final: true,
+        invalidReasons: [],
+        schemaVersion: 1,
+        sentinel: { status: 'bridge-missing' },
+        start: { sentinelStatus: 'sent' },
+    };
+    assert.throws(
+        () => assertSearchJourneyProbeState(base),
+        /search-journey-probe-sentinel-bridge-missing/
+    );
+    assert.throws(
+        () =>
+            assertSearchJourneyProbeState({
+                ...base,
+                capabilities: { layoutShift: false, longTask: true },
+                sentinel: { status: 'sent' },
+            }),
+        /search-journey-probe-observer-unavailable/
+    );
+});
diff --git a/apps/electron-backend-e2e/src/performance/search-journey-probe.ts b/apps/electron-backend-e2e/src/performance/search-journey-probe.ts
new file mode 100644
index 000000000..3bef31100
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/search-journey-probe.ts
@@ -0,0 +1,507 @@
+import type { Page } from '@playwright/test';
+
+import {
+    JOURNEY_CD_TICK_COUNTER_KEY,
+    JOURNEY_IPC_SENTINEL_METHOD,
+} from './journey-renderer-probe';
+
+/**
+ * Renderer-side probe for J4 "Search" (docs/architecture/performance-journeys.md).
+ *
+ * Armed in the loaded `/workspace/search` document after the header search
+ * input has focus. A capture-phase `keydown` listener on `window`, which runs
+ * before every listener of the app, stamps each keystroke in the input; the
+ * first one starts the journey and sends the start sentinel
+ * (`cancelSourceProbe`, as in J2 and J3). DOM mutation records and
+ * change-detection ticks are bucketed by the keystroke they follow, so the
+ * debounce behaviour is visible per key.
+ *
+ * End: after the last expected keystroke, the results for the final term are
+ * shown (URL `q` equals the query, a result card is visible and no loading
+ * state is rendered) and then no DOM mutation arrives for `quietMs`. The
+ * settled moment is the last mutation before that quiet window; the counters
+ * run until the quiet window is confirmed, when the end sentinel is sent. A
+ * plain "quiet after the last keystroke" would close inside the shell's
+ * debounce before any query ran. Without a settle by `settleTimeoutMs`
+ * after the last keystroke the iteration is invalid.
+ *
+ * The script must stay self-contained: Playwright serializes it with
+ * `toString()`, so it may only use its argument and browser globals.
+ */
+export const SEARCH_JOURNEY_PROBE_STATE_KEY = '__iptvnatorJourneySearchProbe';
+export const SEARCH_JOURNEY_PROBE_SCHEMA_VERSION = 1;
+export const SEARCH_JOURNEY_START_SENTINEL_ID =
+    '__iptvnator-journey-search-start__';
+export const SEARCH_JOURNEY_END_SENTINEL_ID =
+    '__iptvnator-journey-search-end__';
+/** The workspace shell header's search box. */
+export const SEARCH_JOURNEY_INPUT_SELECTOR =
+    'app-workspace-shell-header .search-field input[type="search"]';
+/** A rendered global search result (grouped or flat). */
+export const SEARCH_JOURNEY_RESULT_SELECTOR =
+    'app-search-results .results-container app-content-card';
+/** The search layout's spinner while a query runs. */
+export const SEARCH_JOURNEY_LOADING_SELECTOR =
+    'app-search-results .loading-state';
+export const SEARCH_JOURNEY_ROUTE_PATH = '/workspace/search';
+export const SEARCH_JOURNEY_QUIET_MS = 200;
+export const SEARCH_JOURNEY_SETTLE_TIMEOUT_MS = 15_000;
+
+export interface SearchJourneyProbeOptions {
+    readonly cdTickCounterKey: string;
+    readonly endSentinelId: string;
+    readonly inputSelector: string;
+    /** Keystrokes the test types; the settle waits for the last one. */
+    readonly keystrokes: number;
+    readonly loadingSelector: string;
+    /** Term the URL `q` must carry when the results count as final. */
+    readonly query: string;
+    readonly quietMs: number;
+    readonly resultSelector: string;
+    /** The route the results must be on; the renderer path ends with it. */
+    readonly routePath: string;
+    readonly sentinelMethod: string;
+    /** Hard limit from the last keystroke to the settle. */
+    readonly settleTimeoutMs: number;
+    readonly startSentinelId: string;
+    readonly stateKey: string;
+}
+
+export interface SearchJourneyProbeKeystroke {
+    /** `min(event.timeStamp, listener time)` as epoch milliseconds. */
+    readonly epochMs: number;
+    readonly key: string;
+    /** Running tick total at the keydown, before the app handles it. */
+    readonly ticks: number | null;
+}
+
+export type SentinelStatus = 'bridge-missing' | 'failed' | 'not-sent' | 'sent';
+
+export interface SearchJourneyProbeState {
+    readonly capabilities: {
+        changeDetectionTicks:
+            'counted' | 'pending' | 'unavailable-counter-missing';
+        layoutShift: boolean;
+        longTask: boolean;
+    };
+    readonly counters: {
+        domMutations: number;
+        layoutShiftScore: number;
+        longTasks: number;
+        /** Shifts with `hadRecentInput === true`; typing is input. */
+        recentInputLayoutShiftScore: number;
+    };
+    /** Mutation records after each keystroke, until the next or the end. */
+    readonly domMutationsByKeystroke: number[];
+    final: boolean;
+    /** First batch with a visible result card, for any term. */
+    firstResult: {
+        readonly cardCount: number;
+        readonly epochMs: number;
+        readonly query: string | null;
+    } | null;
+    readonly invalidReasons: string[];
+    readonly keystrokes: SearchJourneyProbeKeystroke[];
+    readonly longTaskDurationsMs: number[];
+    readonly preStart: {
+        domMutations: number;
+        lastMutationEpochMs: number | null;
+    };
+    readonly schemaVersion: number;
+    sentinel: { epochMs: number | null; status: SentinelStatus };
+    settle: {
+        cardCount: number;
+        /** When the quiet window was confirmed; the counters stop here. */
+        confirmedEpochMs: number | null;
+        /** Last mutation batch before the quiet window: "settled". */
+        epochMs: number | null;
+        query: string | null;
+        status: 'pending' | 'quiet' | 'timeout';
+        ticks: number | null;
+    };
+    start: {
+        readonly epochMs: number;
+        readonly pathname: string;
+        readonly sentinelStatus: SentinelStatus;
+    } | null;
+}
+
+export function searchJourneyProbeScript(
+    options: SearchJourneyProbeOptions
+): void {
+    const target = globalThis as unknown as Record<string, unknown>;
+    if (target[options.stateKey] !== undefined) {
+        return;
+    }
+    const epoch = (): number => performance.timeOrigin + performance.now();
+    const bridge = target['electron'] as Record<string, unknown> | undefined;
+    const state: SearchJourneyProbeState = {
+        capabilities: {
+            changeDetectionTicks: 'pending',
+            layoutShift: false,
+            longTask: false,
+        },
+        counters: {
+            domMutations: 0,
+            layoutShiftScore: 0,
+            longTasks: 0,
+            recentInputLayoutShiftScore: 0,
+        },
+        domMutationsByKeystroke: [],
+        final: false,
+        firstResult: null,
+        invalidReasons: [],
+        keystrokes: [],
+        longTaskDurationsMs: [],
+        preStart: { domMutations: 0, lastMutationEpochMs: null },
+        schemaVersion: 1,
+        sentinel: { epochMs: null, status: 'not-sent' },
+        settle: {
+            cardCount: 0,
+            confirmedEpochMs: null,
+            epochMs: null,
+            query: null,
+            status: 'pending',
+            ticks: null,
+        },
+        start: null,
+    };
+    target[options.stateKey] = state;
+    const readTicks = (): number | null => {
+        const counter = target[options.cdTickCounterKey] as
+            { count?: unknown } | undefined;
+        return typeof counter?.count === 'number' ? counter.count : null;
+    };
+    const callSentinel = (id: string): SentinelStatus => {
+        const method = bridge?.[options.sentinelMethod];
+        if (typeof method !== 'function') return 'bridge-missing';
+        try {
+            void Promise.resolve(method.call(bridge, id)).catch(
+                () => undefined
+            );
+            return 'sent';
+        } catch {
+            return 'failed';
+        }
+    };
+    const readQuery = (): string | null =>
+        new URLSearchParams(location.search).get('q');
+    const visibleCards = (): number => {
+        let count = 0;
+        for (const card of Array.from(
+            document.querySelectorAll(options.resultSelector)
+        )) {
+            if (card.getClientRects().length > 0) count += 1;
+        }
+        return count;
+    };
+
+    // Entries before the first keystroke belong to the launch (buffered
+    // entries included) and are dropped.
+    let fromEpochMs = Number.POSITIVE_INFINITY;
+    const shifts: PerformanceEntry[] = [];
+    const tasks: PerformanceEntry[] = [];
+    const observe = (
+        type: string,
+        sink: PerformanceEntry[]
+    ): PerformanceObserver | null => {
+        try {
+            const observer = new PerformanceObserver((list) => {
+                if (!state.final) sink.push(...list.getEntries());
+            });
+            observer.observe({ type, buffered: true });
+            return observer;
+        } catch {
+            return null;
+        }
+    };
+    const shiftObserver = observe('layout-shift', shifts);
+    const taskObserver = observe('longtask', tasks);
+    state.capabilities.layoutShift = shiftObserver !== null;
+    state.capabilities.longTask = taskObserver !== null;
+
+    const countEntries = (untilEpochMs: number): void => {
+        if (shiftObserver) shifts.push(...shiftObserver.takeRecords());
+        if (taskObserver) tasks.push(...taskObserver.takeRecords());
+        shiftObserver?.disconnect();
+        taskObserver?.disconnect();
+        for (const entry of shifts) {
+            const shift = entry as PerformanceEntry & {
+                hadRecentInput?: boolean;
+                value?: number;
+            };
+            const at = performance.timeOrigin + entry.startTime;
+            if (
+                typeof shift.value !== 'number' ||
+                at < fromEpochMs ||
+                at > untilEpochMs
+            ) {
+                continue;
+            }
+            if (shift.hadRecentInput === true) {
+                state.counters.recentInputLayoutShiftScore += shift.value;
+            } else {
+                state.counters.layoutShiftScore += shift.value;
+            }
+        }
+        // A task overlaps the window when it ends after the first keydown:
+        // the task that dispatched it still counts.
+        for (const entry of tasks) {
+            const at = performance.timeOrigin + entry.startTime;
+            if (
+                entry.duration <= 50 ||
+                at + entry.duration < fromEpochMs ||
+                at > untilEpochMs
+            ) {
+                continue;
+            }
+            state.counters.longTasks += 1;
+            state.longTaskDurationsMs.push(entry.duration);
+        }
+    };
+
+    let quietTimer: ReturnType<typeof setTimeout> | undefined;
+    let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+    let lastMutationEpochMs: number | null = null;
+    const accept = (count: number): void => {
+        if (count === 0) return;
+        if (state.start === null) {
+            state.preStart.domMutations += count;
+            state.preStart.lastMutationEpochMs = epoch();
+            return;
+        }
+        state.counters.domMutations += count;
+        const bucket = state.keystrokes.length - 1;
+        state.domMutationsByKeystroke[bucket] =
+            (state.domMutationsByKeystroke[bucket] ?? 0) + count;
+        lastMutationEpochMs = epoch();
+    };
+    const ready = (): boolean =>
+        location.pathname.endsWith(options.routePath) &&
+        readQuery() === options.query &&
+        document.querySelector(options.loadingSelector) === null &&
+        visibleCards() > 0;
+    const end = (status: 'quiet' | 'timeout'): void => {
+        if (state.settle.status !== 'pending') return;
+        clearTimeout(quietTimer);
+        clearTimeout(timeoutTimer);
+        accept(mutationObserver.takeRecords().length);
+        mutationObserver.disconnect();
+        const confirmedEpochMs = epoch();
+        const ticks = readTicks();
+        state.settle = {
+            cardCount: visibleCards(),
+            confirmedEpochMs,
+            epochMs: lastMutationEpochMs,
+            query: readQuery(),
+            status,
+            ticks,
+        };
+        if (status === 'timeout') {
+            // What the ready condition saw, so a timeout says which part
+            // never held.
+            const input = document.querySelector(options.inputSelector);
+            state.invalidReasons.push(
+                `settle-timeout ${JSON.stringify({
+                    cards: visibleCards(),
+                    input:
+                        input instanceof HTMLInputElement ? input.value : null,
+                    loading:
+                        document.querySelector(options.loadingSelector) !==
+                        null,
+                    path: location.pathname.slice(-40),
+                    q: readQuery(),
+                    view:
+                        document.querySelector(
+                            'app-search-results .results-container'
+                        )?.firstElementChild?.className ?? null,
+                })}`
+            );
+        }
+        state.capabilities.changeDetectionTicks =
+            ticks === null || state.keystrokes[0]?.ticks === null
+                ? 'unavailable-counter-missing'
+                : 'counted';
+        countEntries(confirmedEpochMs);
+        const sentinelStatus = callSentinel(options.endSentinelId);
+        state.sentinel = {
+            epochMs: sentinelStatus === 'sent' ? epoch() : null,
+            status: sentinelStatus,
+        };
+        window.removeEventListener('keydown', onKeydown, true);
+        state.final = true;
+    };
+    const mutationObserver = new MutationObserver((records) => {
+        if (state.settle.status !== 'pending') return;
+        accept(records.length);
+        if (state.start === null) return;
+        if (state.firstResult === null) {
+            const cardCount = visibleCards();
+            if (cardCount > 0) {
+                state.firstResult = {
+                    cardCount,
+                    epochMs: epoch(),
+                    query: readQuery(),
+                };
+            }
+        }
+        // Every batch after the last keystroke restarts the quiet window,
+        // which only opens once the final term's results are shown.
+        clearTimeout(quietTimer);
+        if (state.keystrokes.length >= options.keystrokes && ready()) {
+            quietTimer = setTimeout(() => end('quiet'), options.quietMs);
+        }
+    });
+    mutationObserver.observe(document.documentElement ?? document, {
+        attributes: true,
+        characterData: true,
+        childList: true,
+        subtree: true,
+    });
+
+    // Capture phase on window runs before every listener of the app, so the
+    // start sentinel precedes any bridge call the first key causes, and the
+    // records queued before a key belong to the previous bucket.
+    const onKeydown = (event: Event): void => {
+        const origin =
+            event.target instanceof Element
+                ? event.target.closest(options.inputSelector)
+                : null;
+        if (origin === null || state.settle.status !== 'pending') return;
+        if (state.keystrokes.length >= options.keystrokes) {
+            state.invalidReasons.push('unexpected-keystroke');
+            return;
+        }
+        accept(mutationObserver.takeRecords().length);
+        const listenerEpochMs = epoch();
+        const eventEpochMs = performance.timeOrigin + event.timeStamp;
+        const epochMs =
+            Number.isFinite(eventEpochMs) && eventEpochMs <= listenerEpochMs
+                ? eventEpochMs
+                : listenerEpochMs;
+        if (state.start === null) {
+            state.start = {
+                epochMs,
+                pathname: location.pathname,
+                sentinelStatus: callSentinel(options.startSentinelId),
+            };
+            fromEpochMs = epochMs;
+        }
+        state.keystrokes.push({
+            epochMs,
+            key: (event as KeyboardEvent).key ?? '',
+            ticks: readTicks(),
+        });
+        state.domMutationsByKeystroke.push(0);
+        if (state.keystrokes.length === options.keystrokes) {
+            timeoutTimer = setTimeout(
+                () => end('timeout'),
+                options.settleTimeoutMs
+            );
+        }
+    };
+    window.addEventListener('keydown', onKeydown, true);
+}
+
+export function createSearchJourneyProbeOptions(
+    query: string
+): SearchJourneyProbeOptions {
+    return {
+        cdTickCounterKey: JOURNEY_CD_TICK_COUNTER_KEY,
+        endSentinelId: SEARCH_JOURNEY_END_SENTINEL_ID,
+        inputSelector: SEARCH_JOURNEY_INPUT_SELECTOR,
+        keystrokes: query.length,
+        loadingSelector: SEARCH_JOURNEY_LOADING_SELECTOR,
+        query,
+        quietMs: SEARCH_JOURNEY_QUIET_MS,
+        resultSelector: SEARCH_JOURNEY_RESULT_SELECTOR,
+        routePath: SEARCH_JOURNEY_ROUTE_PATH,
+        sentinelMethod: JOURNEY_IPC_SENTINEL_METHOD,
+        settleTimeoutMs: SEARCH_JOURNEY_SETTLE_TIMEOUT_MS,
+        startSentinelId: SEARCH_JOURNEY_START_SENTINEL_ID,
+        stateKey: SEARCH_JOURNEY_PROBE_STATE_KEY,
+    };
+}
+
+export async function armSearchJourneyProbe(
+    page: Page,
+    options: SearchJourneyProbeOptions
+): Promise<void> {
+    await page.evaluate(searchJourneyProbeScript, options);
+}
+
+export async function readSearchJourneyPreStartMutations(
+    page: Page,
+    stateKey: string
+): Promise<number> {
+    return page.evaluate((key) => {
+        const state = (globalThis as unknown as Record<string, unknown>)[
+            key
+        ] as { preStart?: { domMutations?: number } } | undefined;
+        const count = state?.preStart?.domMutations;
+        if (typeof count !== 'number') {
+            throw new Error('search-journey-probe-not-armed');
+        }
+        return count;
+    }, stateKey);
+}
+
+export async function waitForSearchJourneyProbe(
+    page: Page,
+    stateKey: string,
+    timeoutMs: number
+): Promise<SearchJourneyProbeState> {
+    await page.waitForFunction(
+        (key) =>
+            (
+                (globalThis as unknown as Record<string, unknown>)[key] as
+                    { final?: boolean } | undefined
+            )?.final === true,
+        stateKey,
+        { polling: 50, timeout: timeoutMs }
+    );
+    const state = await page.evaluate(
+        (key) =>
+            JSON.parse(
+                JSON.stringify(
+                    (globalThis as unknown as Record<string, unknown>)[key]
+                )
+            ) as unknown,
+        stateKey
+    );
+    return assertSearchJourneyProbeState(state);
+}
+
+export function assertSearchJourneyProbeState(
+    value: unknown
+): SearchJourneyProbeState {
+    const state = value as SearchJourneyProbeState | null;
+    if (
+        !state ||
+        state.schemaVersion !== SEARCH_JOURNEY_PROBE_SCHEMA_VERSION ||
+        state.final !== true ||
+        state.start === null
+    ) {
+        throw new Error('search-journey-probe-incomplete');
+    }
+    if (state.invalidReasons.length > 0) {
+        throw new Error(
+            `search-journey-probe-invalid: ${state.invalidReasons.join(', ')}`
+        );
+    }
+    if (state.start.sentinelStatus !== 'sent') {
+        throw new Error(
+            `search-journey-probe-start-sentinel-${state.start.sentinelStatus}`
+        );
+    }
+    if (state.sentinel.status !== 'sent') {
+        throw new Error(
+            `search-journey-probe-sentinel-${state.sentinel.status}`
+        );
+    }
+    // A zero from an observer that never ran is not a measurement.
+    if (!state.capabilities.layoutShift || !state.capabilities.longTask) {
+        throw new Error('search-journey-probe-observer-unavailable');
+    }
+    return state;
+}
diff --git a/apps/electron-backend-e2e/src/performance/search-journey-record.spec.ts b/apps/electron-backend-e2e/src/performance/search-journey-record.spec.ts
new file mode 100644
index 000000000..f14587e53
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/search-journey-record.spec.ts
@@ -0,0 +1,451 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { JourneyMainIpcCaptureState } from './journey-main-ipc-capture';
+import { summarizeJourneyIterations } from './journey-summary';
+import type { SearchJourneyProbeState } from './search-journey-probe';
+import {
+    SEARCH_JOURNEY_COUNTER,
+    SEARCH_JOURNEY_UNAVAILABLE_COUNTERS,
+    SEARCH_JOURNEY_WALL_CLOCK,
+    toSearchIterationRecord,
+    type SearchJourneyActivitySample,
+    type SearchJourneyMeasurement,
+} from './search-journey-record';
+
+const QUERY = 'system';
+
+function sample(
+    ipcCalls: number,
+    queryCalls: number,
+    sqlStatements: number
+): SearchJourneyActivitySample {
+    return { ipcCalls, queryCalls, sqlStatements };
+}
+
+/** The shape of a debounced search: only the last key runs a query. */
+function measurement(
+    overrides: Partial<SearchJourneyMeasurement> = {},
+    rendererOverrides: Partial<SearchJourneyProbeState> = {}
+): SearchJourneyMeasurement {
+    const keystrokes = [...QUERY].map((key, position) => ({
+        epochMs: 10_000 + position * 100,
+        key,
+        ticks: 40 + position,
+    }));
+    const renderer: SearchJourneyProbeState = {
+        capabilities: {
+            changeDetectionTicks: 'counted',
+            layoutShift: true,
+            longTask: true,
+        },
+        counters: {
+            domMutations: 402,
+            layoutShiftScore: 0.0004,
+            longTasks: 0,
+            recentInputLayoutShiftScore: 0.0011,
+        },
+        domMutationsByKeystroke: [0, 0, 0, 0, 0, 402],
+        final: true,
+        firstResult: { cardCount: 100, epochMs: 11_180, query: QUERY },
+        invalidReasons: [],
+        keystrokes,
+        longTaskDurationsMs: [],
+        preStart: { domMutations: 5, lastMutationEpochMs: 8_000 },
+        schemaVersion: 1,
+        sentinel: { epochMs: 11_400, status: 'sent' },
+        settle: {
+            cardCount: 100,
+            confirmedEpochMs: 11_399.6,
+            epochMs: 11_192.54,
+            query: QUERY,
+            status: 'quiet',
+            ticks: 54,
+        },
+        start: {
+            epochMs: 10_000,
+            pathname: '/w/search',
+            sentinelStatus: 'sent',
+        },
+        ...rendererOverrides,
+    };
+    const ipc: JourneyMainIpcCaptureState = {
+        ambiguousTimelineCompletions: 0,
+        callsAfterSentinel: 0,
+        callsBeforeStart: 0,
+        callsBeforeSentinel: 1,
+        callsByMethod: { dbGlobalSearch: 1 },
+        inFlightByMethod: {},
+        installedEpochMs: 9_000,
+        malformedEvents: 0,
+        processStartEpochMs: 1_000,
+        senderIds: [1],
+        sentinel: { occurrences: 1, receivedEpochMs: 11_401 },
+        start: { occurrences: 1, receivedEpochMs: 10_001 },
+        timeline: [
+            { method: 'dbGlobalSearch', phase: 'start' },
+            { method: 'dbGlobalSearch', phase: 'end' },
+        ],
+        unmatchedCompletions: 0,
+    };
+    return {
+        afterSettled: sample(1, 1, 121),
+        afterSettledWindowMs: 500,
+        externalArtworkCancelled: 42,
+        ipc,
+        keyDelayMs: 100,
+        pid: 4242,
+        query: QUERY,
+        sqlAtSentinels: { end: 121, start: 119 },
+        queryTrace: [
+            {
+                epochMs: 11_150,
+                phase: 'start',
+                resultLength: null,
+                term: QUERY,
+            },
+            {
+                epochMs: 11_170,
+                phase: 'success',
+                resultLength: 101,
+                term: null,
+            },
+        ],
+        renderer,
+        samples: [
+            sample(0, 0, 119),
+            sample(0, 0, 119),
+            sample(0, 0, 119),
+            sample(0, 0, 119),
+            sample(0, 0, 119),
+            sample(0, 0, 119),
+            sample(1, 1, 121),
+        ],
+        settle: {
+            preStartDomMutations: 5,
+            preStartIpcCalls: 0,
+            quietMs: 1_000,
+            sqlStatements: 119,
+            waitedMs: 1_226,
+        },
+        ...overrides,
+    };
+}
+
+test('maps a settled search to exact counters and wall-clock', () => {
+    const record = toSearchIterationRecord(1, false, measurement());
+    assert.deepEqual(record.counters, {
+        [SEARCH_JOURNEY_COUNTER.CD_TICKS]: 14,
+        [SEARCH_JOURNEY_COUNTER.DOM_MUTATIONS]: 402,
+        [SEARCH_JOURNEY_COUNTER.IPC_CALLS]: 1,
+        [SEARCH_JOURNEY_COUNTER.IPC_SERIAL_DEPTH]: 1,
+        [SEARCH_JOURNEY_COUNTER.LAYOUT_SHIFT_SCORE]: 0.002,
+        [SEARCH_JOURNEY_COUNTER.LONG_TASKS]: 0,
+        [SEARCH_JOURNEY_COUNTER.SQL_STATEMENTS]: 2,
+    });
+    assert.deepEqual(record.wallClock, {
+        [SEARCH_JOURNEY_WALL_CLOCK.FIRST_KEYSTROKE_TO_FIRST_RESULT]: 1_180,
+        [SEARCH_JOURNEY_WALL_CLOCK.LAST_KEYSTROKE_TO_SETTLED]: 692.5,
+    });
+    assert.equal(record.pid, 4242);
+    assert.equal(record.warmup, false);
+});
+
+test('breaks every counter down by keystroke', () => {
+    const record = toSearchIterationRecord(1, false, measurement());
+    const perKeystroke = record.evidence['perKeystroke'] as {
+        cdTicks: number;
+        domMutations: number;
+        ipcCalls: number;
+        key: string;
+        queryCalls: number;
+        sqlStatements: number;
+    }[];
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.key),
+        [...QUERY]
+    );
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.cdTicks),
+        [1, 1, 1, 1, 1, 9]
+    );
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.queryCalls),
+        [0, 0, 0, 0, 0, 1]
+    );
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.sqlStatements),
+        [0, 0, 0, 0, 0, 2]
+    );
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.domMutations),
+        [0, 0, 0, 0, 0, 402]
+    );
+    assert.deepEqual(record.evidence['sqlStatementsAfterSettled'], {
+        count: 0,
+        windowMs: 500,
+    });
+    assert.deepEqual(record.evidence['ipcTimeline'], [
+        '+dbGlobalSearch',
+        '-dbGlobalSearch',
+    ]);
+});
+
+test('a query per keystroke shows up per key, not only in the total', () => {
+    const record = toSearchIterationRecord(
+        1,
+        false,
+        measurement({
+            samples: [
+                sample(0, 0, 100),
+                sample(0, 0, 100),
+                sample(1, 1, 102),
+                sample(2, 2, 104),
+                sample(3, 3, 106),
+                sample(4, 4, 108),
+                sample(5, 5, 110),
+            ],
+            settle: {
+                preStartDomMutations: 5,
+                preStartIpcCalls: 0,
+                quietMs: 1_000,
+                sqlStatements: 100,
+                waitedMs: 1_000,
+            },
+            sqlAtSentinels: { end: 110, start: 100 },
+            ipc: {
+                ...measurement().ipc,
+                callsBeforeSentinel: 5,
+                callsByMethod: { dbGlobalSearch: 5 },
+            },
+            queryTrace: ['sy', 'sys', 'syst', 'syste', QUERY].flatMap(
+                (term, position) => [
+                    {
+                        epochMs: 10_150 + position * 100,
+                        phase: 'start',
+                        resultLength: null,
+                        term,
+                    },
+                    {
+                        epochMs: 10_170 + position * 100,
+                        phase: 'success',
+                        resultLength: 101,
+                        term: null,
+                    },
+                ]
+            ),
+        })
+    );
+    assert.equal(record.counters[SEARCH_JOURNEY_COUNTER.IPC_CALLS], 5);
+    assert.equal(record.counters[SEARCH_JOURNEY_COUNTER.SQL_STATEMENTS], 10);
+    const perKeystroke = record.evidence['perKeystroke'] as {
+        queryCalls: number;
+    }[];
+    assert.deepEqual(
+        perKeystroke.map((entry) => entry.queryCalls),
+        [0, 1, 1, 1, 1, 1]
+    );
+});
+
+test('rejects iterations that did not measure a settled search', () => {
+    const cases: [Partial<SearchJourneyProbeState>, RegExp][] = [
+        [{ start: null }, /incomplete-probe/],
+        [
+            {
+                settle: { ...measurement().renderer.settle, status: 'timeout' },
+            },
+            /incomplete-probe/,
+        ],
+        [
+            { keystrokes: measurement().renderer.keystrokes.slice(1) },
+            /keystroke-count/,
+        ],
+        [
+            {
+                keystrokes: measurement().renderer.keystrokes.map((key) => ({
+                    ...key,
+                    key: 'x',
+                })),
+            },
+            /typed-text/,
+        ],
+        [
+            { settle: { ...measurement().renderer.settle, query: 'syste' } },
+            /no-results/,
+        ],
+        [{ firstResult: null }, /no-results/],
+        [
+            { settle: { ...measurement().renderer.settle, epochMs: 9_000 } },
+            /clock-order/,
+        ],
+        [{ preStart: { domMutations: 6, lastMutationEpochMs: 9_990 } }, /dom/],
+        [
+            {
+                capabilities: {
+                    changeDetectionTicks: 'unavailable-counter-missing',
+                    layoutShift: true,
+                    longTask: true,
+                },
+            },
+            /cd-ticks-unavailable-counter-missing/,
+        ],
+    ];
+    for (const [overrides, error] of cases) {
+        assert.throws(
+            () => toSearchIterationRecord(1, false, measurement({}, overrides)),
+            error
+        );
+    }
+});
+
+test('rejects work that moved between the quiet snapshot and the first key', () => {
+    const base = measurement();
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({ ipc: { ...base.ipc, callsBeforeStart: 1 } })
+            ),
+        /activity-before-first-key-ipc/
+    );
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({ sqlAtSentinels: { end: 122, start: 120 } })
+            ),
+        /activity-before-first-key-sql/
+    );
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({
+                    samples: [...base.samples.slice(0, 6), sample(2, 1, 121)],
+                })
+            ),
+        /ipc-sample-mismatch/
+    );
+});
+
+test('summarizes with the shared summary and nothing unavailable', () => {
+    const iterations = [0, 1, 2].map((index) =>
+        toSearchIterationRecord(
+            index,
+            index === 0,
+            measurement({ pid: 4_000 + index })
+        )
+    );
+    const entry = summarizeJourneyIterations(
+        iterations,
+        SEARCH_JOURNEY_UNAVAILABLE_COUNTERS
+    );
+    assert.equal(entry.counters[SEARCH_JOURNEY_COUNTER.IPC_CALLS], 1);
+    assert.equal(
+        entry.counterStability[SEARCH_JOURNEY_COUNTER.SQL_STATEMENTS]?.stable,
+        true
+    );
+    assert.equal(
+        entry.wallClock[
+            `${SEARCH_JOURNEY_WALL_CLOCK.LAST_KEYSTROKE_TO_SETTLED}.p50`
+        ],
+        692.5
+    );
+    assert.deepEqual(entry.unavailable, {});
+});
+
+test('rejects a settle that did not wait for the final query', () => {
+    const start = (epochMs: number, term: string) => ({
+        epochMs,
+        phase: 'start',
+        resultLength: null,
+        term,
+    });
+    const success = (epochMs: number) => ({
+        epochMs,
+        phase: 'success',
+        resultLength: 101,
+        term: null,
+    });
+    // Results of an earlier term were shown; the final query never ran
+    // before the end sentinel.
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({
+                    queryTrace: [
+                        start(10_500, 'syste'),
+                        success(10_520),
+                        start(11_500, QUERY),
+                        success(11_520),
+                    ],
+                })
+            ),
+        /final-query-not-run/
+    );
+    // The final query started but had not completed at the end sentinel.
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({ queryTrace: [start(11_390, QUERY)] })
+            ),
+        /final-query-incomplete/
+    );
+    const record = toSearchIterationRecord(1, false, measurement());
+    assert.deepEqual(record.evidence['finalQuery'], {
+        durationMs: 20,
+        resultLength: 101,
+        term: QUERY,
+    });
+});
+
+test('rejects typing slower than the accepted cadence', () => {
+    const base = measurement();
+    const keystrokes = base.renderer.keystrokes.map((key, position) => ({
+        ...key,
+        epochMs: key.epochMs + (position >= 3 ? 200 : 0),
+    }));
+    assert.throws(
+        () =>
+            toSearchIterationRecord(1, false, measurement({}, { keystrokes })),
+        /typing-cadence: 100, 100, 300, 100, 100/
+    );
+    assert.deepEqual(
+        toSearchIterationRecord(1, false, base).evidence['keyIntervalsMs'],
+        [100, 100, 100, 100, 100]
+    );
+});
+
+test('counts SQL between the sentinels only', () => {
+    // Background statements after the end sentinel reach the final sample
+    // but not the counter; they show up after the settle instead.
+    const record = toSearchIterationRecord(
+        1,
+        false,
+        measurement({
+            afterSettled: sample(1, 1, 126),
+            samples: [...measurement().samples.slice(0, 6), sample(1, 1, 125)],
+        })
+    );
+    assert.equal(record.counters[SEARCH_JOURNEY_COUNTER.SQL_STATEMENTS], 2);
+    assert.deepEqual(record.evidence['sqlStatementsAfterSettled'], {
+        count: 5,
+        windowMs: 500,
+    });
+    assert.throws(
+        () =>
+            toSearchIterationRecord(
+                1,
+                false,
+                measurement({ sqlAtSentinels: { end: null, start: 119 } })
+            ),
+        /sql-at-sentinels-missing/
+    );
+});
diff --git a/apps/electron-backend-e2e/src/performance/search-journey-record.ts b/apps/electron-backend-e2e/src/performance/search-journey-record.ts
new file mode 100644
index 000000000..556f378e8
--- /dev/null
+++ b/apps/electron-backend-e2e/src/performance/search-journey-record.ts
@@ -0,0 +1,330 @@
+import { computeJourneyIpcSerialDepth } from './journey-ipc-serial-depth';
+import type { JourneyMainIpcCaptureState } from './journey-main-ipc-capture';
+import type { JourneyIterationRecord } from './journey-summary';
+import type { SearchJourneyProbeState } from './search-journey-probe';
+
+/**
+ * Maps one measured global search (renderer probe from the first keystroke
+ * until the results settled, main IPC capture between the start and end
+ * sentinels, main-process activity sampled before every keystroke) to the
+ * journey summary's iteration record for J4.
+ */
+export const SEARCH_JOURNEY_ID = 'search';
+
+export const SEARCH_JOURNEY_COUNTER = {
+    CD_TICKS: 'renderer.cdTicksToResults',
+    DOM_MUTATIONS: 'renderer.domMutationsToResults',
+    IPC_CALLS: 'renderer.ipcCallsPerSearch',
+    IPC_SERIAL_DEPTH: 'renderer.ipcSerialDepthToResults',
+    LAYOUT_SHIFT_SCORE: 'renderer.layoutShiftScore',
+    LONG_TASKS: 'renderer.longTasks',
+    SQL_STATEMENTS: 'renderer.sqlStatementsPerSearch',
+} as const;
+
+export const SEARCH_JOURNEY_WALL_CLOCK = {
+    FIRST_KEYSTROKE_TO_FIRST_RESULT: 'firstKeystrokeToFirstResultMs',
+    LAST_KEYSTROKE_TO_SETTLED: 'lastKeystrokeToSettledMs',
+} as const;
+
+export const SEARCH_JOURNEY_UNAVAILABLE_COUNTERS: Readonly<
+    Record<string, string>
+> = Object.freeze({});
+
+/** Bridge method of a global search query (`DatabaseService`). */
+export const SEARCH_JOURNEY_QUERY_METHOD = 'dbGlobalSearch';
+
+/**
+ * Longest accepted gap between two keydowns. Below the shell's 350 ms input
+ * debounce, so a late key on a busy machine cannot let an intermediate term
+ * run a query that steady typing would not.
+ */
+export const SEARCH_JOURNEY_MAX_KEY_INTERVAL_MS = 250;
+
+/** One traced query event, stamped in the main process on arrival. */
+export interface SearchJourneyQueryTraceEntry {
+    readonly epochMs: number;
+    readonly phase: string;
+    /** Length of the returned array, on `success`. */
+    readonly resultLength: number | null;
+    readonly term: string | null;
+}
+
+/**
+ * Main-process activity read in one synchronous pass: the journey capture's
+ * call counts and the running `main.sqlStatements` total.
+ */
+export interface SearchJourneyActivitySample {
+    readonly ipcCalls: number;
+    readonly queryCalls: number;
+    readonly sqlStatements: number;
+}
+
+/** How long the app was left alone before the first keystroke. */
+export interface SearchJourneySettle {
+    readonly preStartDomMutations: number;
+    readonly preStartIpcCalls: number;
+    readonly quietMs: number;
+    readonly sqlStatements: number;
+    readonly waitedMs: number;
+}
+
+export interface SearchJourneyMeasurement {
+    readonly externalArtworkCancelled: number;
+    readonly ipc: JourneyMainIpcCaptureState;
+    readonly keyDelayMs: number;
+    readonly pid: number;
+    readonly query: string;
+    readonly renderer: SearchJourneyProbeState;
+    /**
+     * Before each keystroke (index i before key i + 1), then once after the
+     * probe settled and once more `afterSettledWindowMs` later.
+     */
+    readonly samples: readonly SearchJourneyActivitySample[];
+    readonly afterSettled: SearchJourneyActivitySample;
+    readonly afterSettledWindowMs: number;
+    readonly settle: SearchJourneySettle;
+    /**
+     * `main.sqlStatements` read in the main process when the start and the
+     * end sentinel arrived; null when it was not read.
+     */
+    readonly sqlAtSentinels: {
+        readonly end: number | null;
+        readonly start: number | null;
+    };
+    /** Every traced query event of the process, in arrival order. */
+    readonly queryTrace: readonly SearchJourneyQueryTraceEntry[];
+}
+
+function roundTenth(value: number): number {
+    return Math.round(value * 10) / 10;
+}
+
+function roundThousandth(value: number): number {
+    return Math.round(value * 1_000) / 1_000;
+}
+
+function difference(
+    samples: readonly SearchJourneyActivitySample[],
+    index: number,
+    key: keyof SearchJourneyActivitySample
+): number {
+    return samples[index + 1][key] - samples[index][key];
+}
+
+/**
+ * The query the settle waited for: the last one started between the start
+ * and end sentinels. It must be for the final term and must have completed
+ * before the end sentinel, otherwise the probe settled on results of an
+ * earlier term (still shown while the final term debounced).
+ */
+function finalQuery(
+    trace: readonly SearchJourneyQueryTraceEntry[],
+    fromEpochMs: number,
+    untilEpochMs: number,
+    query: string
+) {
+    const inWindow = trace.filter(
+        (entry) => entry.epochMs >= fromEpochMs && entry.epochMs <= untilEpochMs
+    );
+    const starts = inWindow.filter((entry) => entry.phase === 'start');
+    const completions = inWindow.filter(
+        (entry) => entry.phase === 'success' || entry.phase === 'error'
+    );
+    const last = starts.at(-1);
+    if (last === undefined || last.term !== query) {
+        throw new Error('search-journey-record-final-query-not-run');
+    }
+    const completion = completions.find(
+        (entry) => entry.epochMs >= last.epochMs && entry.phase === 'success'
+    );
+    if (completion === undefined || completions.length < starts.length) {
+        throw new Error('search-journey-record-final-query-incomplete');
+    }
+    return Object.freeze({
+        durationMs: completion.epochMs - last.epochMs,
+        resultLength: completion.resultLength,
+        term: last.term,
+    });
+}
+
+export function toSearchIterationRecord(
+    index: number,
+    warmup: boolean,
+    measurement: SearchJourneyMeasurement
+): JourneyIterationRecord {
+    const { ipc, renderer, samples, settle } = measurement;
+    const { keystrokes, start } = renderer;
+    const keys = measurement.query.length;
+    if (start === null || renderer.settle.status !== 'quiet') {
+        throw new Error('search-journey-record-incomplete-probe');
+    }
+    if (ipc.start === null) {
+        throw new Error('search-journey-record-ipc-without-start');
+    }
+    if (keystrokes.length !== keys || samples.length !== keys + 1) {
+        throw new Error('search-journey-record-keystroke-count');
+    }
+    if (keystrokes.map((key) => key.key).join('') !== measurement.query) {
+        throw new Error('search-journey-record-typed-text');
+    }
+    if (
+        renderer.settle.query !== measurement.query ||
+        renderer.settle.cardCount === 0 ||
+        renderer.firstResult === null
+    ) {
+        throw new Error('search-journey-record-no-results');
+    }
+    const settledEpochMs = renderer.settle.epochMs;
+    const lastKeyEpochMs = keystrokes[keys - 1].epochMs;
+    if (
+        settledEpochMs === null ||
+        settledEpochMs < lastKeyEpochMs ||
+        renderer.firstResult.epochMs < start.epochMs
+    ) {
+        throw new Error('search-journey-record-clock-order');
+    }
+    const { end: sqlAtEnd, start: sqlAtStart } = measurement.sqlAtSentinels;
+    if (sqlAtStart === null || sqlAtEnd === null || sqlAtEnd < sqlAtStart) {
+        throw new Error('search-journey-record-sql-at-sentinels-missing');
+    }
+    // Activity between the quiet snapshot and the first key could finish
+    // after it and be counted as the search's. The probe, the capture and
+    // the SQL total read at the start sentinel all reflect the first
+    // keydown, so they must still match the snapshot.
+    const moved = [
+        renderer.preStart.domMutations !== settle.preStartDomMutations
+            ? 'dom'
+            : null,
+        ipc.callsBeforeStart !== settle.preStartIpcCalls ? 'ipc' : null,
+        sqlAtStart !== settle.sqlStatements ? 'sql' : null,
+    ].filter((kind): kind is string => kind !== null);
+    if (moved.length > 0) {
+        throw new Error(
+            `search-journey-record-activity-before-first-key-${moved.join('-')}`
+        );
+    }
+    const keyIntervalsMs = keystrokes
+        .slice(1)
+        .map((key, position) =>
+            roundTenth(key.epochMs - keystrokes[position].epochMs)
+        );
+    if (
+        keyIntervalsMs.some(
+            (interval) => interval > SEARCH_JOURNEY_MAX_KEY_INTERVAL_MS
+        )
+    ) {
+        throw new Error(
+            `search-journey-record-typing-cadence: ${keyIntervalsMs.join(', ')}`
+        );
+    }
+    if (ipc.sentinel.receivedEpochMs === null) {
+        throw new Error('search-journey-record-ipc-without-end');
+    }
+    const lastQuery = finalQuery(
+        measurement.queryTrace,
+        ipc.start.receivedEpochMs ?? Number.POSITIVE_INFINITY,
+        ipc.sentinel.receivedEpochMs,
+        measurement.query
+    );
+    const finalSample = samples[keys];
+    if (finalSample.ipcCalls !== ipc.callsBeforeSentinel) {
+        throw new Error('search-journey-record-ipc-sample-mismatch');
+    }
+    const settleTicks = renderer.settle.ticks;
+    const ticks = keystrokes.map((key) => key.ticks);
+    if (
+        renderer.capabilities.changeDetectionTicks !== 'counted' ||
+        settleTicks === null ||
+        ticks.some((value) => value === null)
+    ) {
+        throw new Error(
+            `search-journey-record-cd-ticks-${renderer.capabilities.changeDetectionTicks}`
+        );
+    }
+    const tickAt = (position: number): number =>
+        position < keys ? (ticks[position] as number) : settleTicks;
+    const serialDepth = computeJourneyIpcSerialDepth(ipc.timeline);
+    const perKeystroke = keystrokes.map((key, position) =>
+        Object.freeze({
+            atMs: roundTenth(key.epochMs - start.epochMs),
+            cdTicks: tickAt(position + 1) - tickAt(position),
+            domMutations: renderer.domMutationsByKeystroke[position] ?? 0,
+            ipcCalls: difference(samples, position, 'ipcCalls'),
+            key: key.key,
+            queryCalls: difference(samples, position, 'queryCalls'),
+            sqlStatements: difference(samples, position, 'sqlStatements'),
+        })
+    );
+    return Object.freeze({
+        counters: Object.freeze({
+            [SEARCH_JOURNEY_COUNTER.CD_TICKS]: settleTicks - tickAt(0),
+            [SEARCH_JOURNEY_COUNTER.DOM_MUTATIONS]:
+                renderer.counters.domMutations,
+            [SEARCH_JOURNEY_COUNTER.IPC_CALLS]: ipc.callsBeforeSentinel,
+            [SEARCH_JOURNEY_COUNTER.IPC_SERIAL_DEPTH]: serialDepth.depth,
+            // Typing is input, so shifts flagged hadRecentInput are
+            // included, as in J2 and J3.
+            [SEARCH_JOURNEY_COUNTER.LAYOUT_SHIFT_SCORE]: roundThousandth(
+                renderer.counters.layoutShiftScore +
+                    renderer.counters.recentInputLayoutShiftScore
+            ),
+            [SEARCH_JOURNEY_COUNTER.LONG_TASKS]: renderer.counters.longTasks,
+            [SEARCH_JOURNEY_COUNTER.SQL_STATEMENTS]: sqlAtEnd - sqlAtStart,
+        }),
+        evidence: Object.freeze({
+            capabilities: renderer.capabilities,
+            epochs: Object.freeze({
+                firstKeystroke: start.epochMs,
+                firstResult: renderer.firstResult.epochMs,
+                lastKeystroke: lastKeyEpochMs,
+                mainIpcSentinel: ipc.sentinel.receivedEpochMs,
+                mainIpcStart: ipc.start.receivedEpochMs,
+                settleConfirmed: renderer.settle.confirmedEpochMs,
+                settled: settledEpochMs,
+            }),
+            externalArtworkCancelled: measurement.externalArtworkCancelled,
+            firstResult: Object.freeze({
+                cardCount: renderer.firstResult.cardCount,
+                query: renderer.firstResult.query,
+            }),
+            ipcCallsAfterSettled: ipc.callsAfterSentinel,
+            ipcCallsByMethod: ipc.callsByMethod,
+            ipcSerialDepth: serialDepth,
+            ipcTimeline: ipc.timeline.map(
+                (event) =>
+                    `${event.phase === 'start' ? '+' : '-'}${event.method}`
+            ),
+            finalQuery: lastQuery,
+            keyDelayMs: measurement.keyDelayMs,
+            keyIntervalsMs,
+            layoutShift: Object.freeze({
+                recentInput: roundThousandth(
+                    renderer.counters.recentInputLayoutShiftScore
+                ),
+                withoutRecentInput: roundThousandth(
+                    renderer.counters.layoutShiftScore
+                ),
+            }),
+            longTaskDurationsMs: renderer.longTaskDurationsMs.map(roundTenth),
+            perKeystroke,
+            query: measurement.query,
+            results: Object.freeze({ cardCount: renderer.settle.cardCount }),
+            settle,
+            sqlAtSentinels: measurement.sqlAtSentinels,
+            sqlStatementsAfterSettled: Object.freeze({
+                count: measurement.afterSettled.sqlStatements - sqlAtEnd,
+                windowMs: measurement.afterSettledWindowMs,
+            }),
+        }),
+        index,
+        pid: measurement.pid,
+        wallClock: Object.freeze({
+            [SEARCH_JOURNEY_WALL_CLOCK.FIRST_KEYSTROKE_TO_FIRST_RESULT]:
+                roundTenth(renderer.firstResult.epochMs - start.epochMs),
+            [SEARCH_JOURNEY_WALL_CLOCK.LAST_KEYSTROKE_TO_SETTLED]: roundTenth(
+                settledEpochMs - lastKeyEpochMs
+            ),
+        }),
+        warmup,
+    });
+}
diff --git a/docs/architecture/performance-journeys.md b/docs/architecture/performance-journeys.md
index dfb8a2824..3071a139f 100644
--- a/docs/architecture/performance-journeys.md
+++ b/docs/architecture/performance-journeys.md
@@ -19,9 +19,9 @@ live in `tools/performance/`.
 | J4 `search`      | six-character query typed into global search | results list settled                                                          |
 
 J1 is instrumented: `renderer.initialBytes` from the built output, and the
-runtime counters of the launch benchmark below. J2 and J3 are instrumented by
-their own specs (below). J4 follows the plan in `.plans/` and is added in its
-own thread; each thread names its journey and counter in the PR description.
+runtime counters of the launch benchmark below. J2, J3 and J4 are
+instrumented by their own specs (below). Each thread names its journey and
+counter in the PR description.
 
 ## Running the journeys
 
@@ -305,10 +305,12 @@ registers the `performance:read-counters` IPC handler. Without the flag
 nothing is counted, no listener is attached and the handler does not exist;
 the preload never exposes the channel. SQL statements are counted only with
 `IPTVNATOR_PERF_COUNT_SQL=1` as well, because the hook wraps every statement
-execution: the launch journey sets both (the flags are built in
-`journey-launch-environment.ts`), while J2's launches and the M3U, refresh
-and Xtream benchmarks do not set the SQL flag and keep measuring unwrapped
-statements. A harness test fails if any other source sets the SQL flag. After the renderer probe completes,
+execution: the launch journey and J4, which reports
+`renderer.sqlStatementsPerSearch`, set both (the flags are built in
+`journey-launch-environment.ts`), while J2's and J3's launches and the M3U,
+refresh and Xtream benchmarks do not set the SQL flag and keep measuring
+unwrapped statements. A harness test fails if any other source sets the SQL
+flag. After the renderer probe completes,
 `journey-main-counters.ts` calls the handler through `electronApp.evaluate`
 and the gate's tap.
 
@@ -639,6 +641,13 @@ iterations carry `evidence.media` (the video element at `playing`) and
 a `media` field (`null` for J1 and J2), which the probe's
 `schemaVersion` 1 readers ignore.
 
+J4 adds the `journeys.search` entry, again with the same shape. Its
+iterations carry `evidence.perKeystroke` (one entry per typed key, see
+[J4](#j4-search-type-a-query-until-the-results-settle)), which the CI job
+summary prints as a table for the first measured iteration. J4 has its own
+renderer probe (`search-journey-probe.ts`, `schemaVersion` 1); the shared
+probe is unchanged.
+
 ## J2 `open-source`: open a source to a browsable list
 
 `open-source.journey.ts` reuses the J1 profile and process pattern: the
@@ -868,6 +877,165 @@ mutation and request counts. On the runner `renderer.httpRequestsToPlaying`
 and `renderer.layoutShiftScore` are enforced as guards; see
 [Enforced journey counters](#enforced-journey-counters).
 
+## J4 `search`: type a query until the results settle
+
+`search.journey.ts` follows J3: the profile is seeded once through the "Add
+playlist" dialogs (`seedLaunchJourneyProfile` with `SEARCH_JOURNEY_SEED`),
+every iteration copies it, spawns a fresh process through `runLaunchJourney`
+and hands the running app to `measureSearchJourney` in
+`src/journeys/search-journey-app.ts`. One warm-up and five measured
+iterations. Unlike J2 and J3 the launch runs with the main-process counters
+(`mainCounters: true`, so `IPTVNATOR_PERF_CAPTURE` and
+`IPTVNATOR_PERF_COUNT_SQL`), because SQL statements are a J4 counter; every
+statement then runs through the counting hook.
+
+**Profile.** J1's M3U source plus an Xtream portal ("Journey search portal")
+on the mock's existing `large:large` scenario: 60 categories of 200 items,
+so 4,000 live channels, 4,000 movies and 4,000 series. No fixture was added
+for the journey. The query is `system`, which matches 170 series titles of
+that deterministic catalog: more than global search's first page of 100, so
+the page is full and more results are available. Six characters take the
+title FTS path of `globalSearch`
+(`apps/electron-backend/src/app/database/operations/content.operations.ts`);
+the M3U arm runs as well, because live content is included, but none of the
+four fixture channels matches. Poster artwork points at `picsum.photos` and
+is cancelled in the main process as in J3
+(`src/performance/journey-external-artwork.ts`, shared by both journeys);
+the count is kept as `evidence.externalArtworkCancelled`. The mock is not
+put behind the request ledger: global search reads only the local database.
+
+**What typing does.** The header search box
+(`app-workspace-shell-header .search-field input[type="search"]`) applies
+its term after `SEARCH_INPUT_DEBOUNCE_MS` (350 ms,
+`WorkspaceShellSearchSyncService`) and writes it to the URL as `q`. On
+`/workspace/search` (`app.routes.ts`, Electron only) `SearchResultsComponent`
+adopts `q` and runs `executeSearch` after its own 300 ms debounce, which
+calls the `dbGlobalSearch` bridge method once with a limit of 101.
+
+**Start.** After J1 has ended, the test clicks the rail's **Global search**
+link and focuses the header search box (not measured), installs the IPC
+capture with a start sentinel, arms the probe
+(`src/performance/search-journey-probe.ts`) and waits until the app has
+been quiet for 1 s: no DOM mutation, no new or pending bridge call, and an
+unchanged `main.sqlStatements` total (30 s timeout, which fails the
+iteration). J1's capture is detached. The test then types the query with one
+`keyboard.type` call per character on a fixed schedule, 100 ms apart from
+the first key (well below the 350 ms debounce, as steady typing would be),
+and samples the main process just before each key. The probe's
+capture-phase `keydown` listener on `window` stamps every key in the search
+box before the app sees it; the first one starts the journey and sends
+`cancelSourceProbe('__iptvnator-journey-search-start__')`. The record
+rejects an iteration whose DOM mutations, bridge calls or SQL statements
+moved between the quiet snapshot and the first key.
+
+**End.** "No DOM mutation for 200 ms after the last keystroke" alone would
+end inside the 650 ms of debounce, before any query ran: nothing in the DOM
+changes while the term waits. So after the sixth key the probe waits for
+the results of the final term to be shown (the path ends with
+`/workspace/search`, the URL `q` is the query, no `.loading-state` is
+rendered and an `app-content-card` in the results container is visible). The
+mutation batch that first meets that condition opens a 200 ms quiet window,
+and every later batch restarts it. When the window elapses the journey has
+settled: the settled moment is the last mutation batch, the counters stop at
+the confirmation, and the probe sends
+`cancelSourceProbe('__iptvnator-journey-search-end__')`. Without a settle
+within 15 s of the last key the probe marks the iteration invalid
+(`settle-timeout`).
+
+The DOM alone cannot tell the final term's results from an earlier term's
+that are still shown while the final term debounces, so the main process
+also checks. A listener on the renderer-API trace channel stamps every
+`dbGlobalSearch` event on arrival, with the term and result length that the
+preload's summaries carry. The record requires that the last query started
+between the start and end sentinels is for the final term and completed
+before the end sentinel (`final-query-not-run`, `final-query-incomplete`).
+The final query's start shows the loading state, which keeps the quiet
+window closed until its results replace the old ones.
+`evidence.finalQuery` keeps its term, result length and duration. The
+record also rejects an iteration in which two keydowns were more than
+250 ms apart (`typing-cadence`; the gaps are `evidence.keyIntervalsMs`).
+At that point a late key on a busy machine could let the 350 ms debounce
+apply an intermediate term, which steady typing does not.
+
+A settle that times out fails the iteration with what the probe and the
+main process saw: the URL `q`, the input's value, the results view, the
+bridge calls, renderer console errors, the SQL totals before each key, and
+the traced `dbGlobalSearch` calls with their terms and result lengths.
+
+### Counters
+
+| Counter                            | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `renderer.ipcCallsPerSearch`       | Bridge `start` trace events between the start and end sentinels, as `renderer.ipcCallsToFirstPage` in J2. `evidence.ipcCallsByMethod` names them.                                                                                                                                                                                                                                                                                                                                              |
+| `renderer.sqlStatementsPerSearch`  | `main.sqlStatements` (main thread and database worker, see [Main-process counters](#main-process-counters)) read in the main process when the start sentinel and the end sentinel arrive (a listener on the trace channel calls the counters handler through the gate, which reads the registry synchronously), so the count covers exactly the IPC capture's window and never work just before the first key or after the settle. The worker reports its count before the response it belongs to, so the statements of a query are counted before its results reach the renderer. The two values are `evidence.sqlAtSentinels`; statements from the end sentinel until 500 ms after the test read the summary are kept as `evidence.sqlStatementsAfterSettled`. |
+| `renderer.ipcSerialDepthToResults` | `computeJourneyIpcSerialDepth` over the capture's timeline between the sentinels (see [Serial IPC depth](#serial-ipc-depth)); `evidence.ipcSerialDepth.chain` and `evidence.ipcTimeline` show the calls.                                                                                                                                                                                                                                                                                       |
+| `renderer.domMutationsToResults`   | `MutationRecord`s from the first keydown until the quiet window was confirmed (by definition none arrive inside it).                                                                                                                                                                                                                                                                                                                                                                           |
+| `renderer.cdTicksToResults`        | `ApplicationRef` ticks from the first keydown (read in the capture-phase listener, before the app handles the key) until the confirmation (see [Change-detection ticks](#change-detection-ticks)).                                                                                                                                                                                                                                                                                             |
+| `renderer.layoutShiftScore`        | All `layout-shift` entries from the first keydown until the confirmation, including `hadRecentInput` ones (typing is input, as in J2 and J3), rounded to three decimals; the split is under `evidence.layoutShift`.                                                                                                                                                                                                                                                                            |
+| `renderer.longTasks`               | `longtask` entries over 50 ms whose time range overlaps the window from the first keydown to the confirmation. Evidence until shown to be stable on the runner.                                                                                                                                                                                                                                                                                                                                |
+
+`evidence.perKeystroke` breaks the journey down by key: for each typed
+character, what happened from that key until the next one (the last entry:
+until the settle). `domMutations` and `cdTicks` are split at the renderer's
+keydown stamps. `ipcCalls`, `queryCalls` (`dbGlobalSearch` calls) and
+`sqlStatements` are differences of the main-process samples taken just
+before each key, so their boundaries sit a few milliseconds before the
+renderer's. A search with working debounce shows zeros for the first five
+keys and one query after the last; a search that queried on every key from
+the second character on would show a `dbGlobalSearch` call and its
+statements in each of those entries, even when a later key superseded the
+result.
+
+No counter is listed under `unavailable`. HTTP requests are not a J4
+counter: global search does not touch the network.
+
+### Wall-clock
+
+| Entry                                    | Derivation                                                                                                                               |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `firstKeystrokeToFirstResultMs.p50/.p90` | First mutation batch with a visible result card (for any term) minus the first keydown.                                                  |
+| `lastKeystrokeToSettledMs.p50/.p90`      | Settled moment (the last mutation batch before the 200 ms quiet window) minus the last keydown. The quiet window itself is not included. |
+
+Both are taken in the renderer. With the current debounces both include
+the 650 ms the term waits (350 ms in the shell, then 300 ms in the results
+component); the first also includes the 500 ms of typing.
+
+### First measurement
+
+Local, macOS, 2026-10-04, three full `perf:journeys` runs plus repeated J4
+runs. In the runs where J4 completed (the first and third full runs), every
+counter was identical in all ten measured iterations except one:
+`renderer.ipcCallsPerSearch` 1 (`dbGlobalSearch`),
+`renderer.sqlStatementsPerSearch` 2, `renderer.ipcSerialDepthToResults` 1,
+`renderer.domMutationsToResults` 402 (100 cards on the first page),
+`renderer.layoutShiftScore` 0 and `renderer.longTasks` 0.
+`renderer.cdTicksToResults` read 14 in all five iterations of the third run
+and 13, 18, 13, 15, 13 in the first, so check the runner's
+`counterStability` before trusting it. P50/P90
+`lastKeystrokeToSettledMs` 686/692 ms and `firstKeystrokeToFirstResultMs`
+1,178/1,184 ms in the third run (699/720 and 1,193/1,210 in the first).
+
+Per keystroke, the first five keys caused one change-detection tick each
+and nothing else: no bridge call, no SQL statement and no DOM mutation.
+All of the work followed the sixth key. Search therefore does not run a
+query per keystroke. The debounce does dominate the wall clock: about
+650 ms of the 686 ms from the last key to settled is the two stacked
+debounces (350 ms in the shell, then 300 ms in the results component). The
+query itself, from the bridge call to the rendered first page, takes the
+remaining 30-40 ms.
+
+About one launch in sixty showed the empty-results view: the single
+`dbGlobalSearch` call went out with the same arguments (`system`, all three
+types, hidden categories included, limit 101) and the main process answered
+with an empty array in about 20 ms, with no renderer error. The database
+was unchanged from passing launches (the same 119 statements before the
+first key, the usual 2 for the query, none afterwards), and every failure
+traced was the first launch after seeding. The journey fails such an
+iteration instead of measuring it, so a full run occasionally fails J4.
+The cause is in the app, not the harness, and is not fixed here. No J4
+baseline exists yet; J4 counters join the ratchet once three runner runs
+agree.
+
 ## `renderer.initialBytes`
 
 The bytes a browser fetches before Angular can bootstrap, read from the built
@@ -1240,8 +1408,10 @@ reports slow imports of non-Latin playlists.
 2. Give the journey its own probe options (`cardSelector`,
    `companionSelectors`, `routeFragment`, `startClick` for a click start,
    `media` for a media-event end such as J3's `playing`) or extend
-   `journey-renderer-probe.ts` when the end condition is neither. Use a state
-   key and sentinel ids of its own. Keep the probe self-contained: Playwright
+   `journey-renderer-probe.ts` when the end condition is neither. A journey
+   whose start or end does not fit that probe gets a probe of its own, as
+   J4's typed start and quiet-window end do (`search-journey-probe.ts`). Use
+   a state key and sentinel ids of its own. Keep the probe self-contained: Playwright
    serializes it with `toString()`. A click-started journey settles with
    `waitForJourneyClickQuiet` from `journey-click-settle.ts`.
 3. Map the measurement to a `JourneyIterationRecord` in a

From 5e5b483dca2dc8ddbad2bf41904e9dd0ed6cbc7b Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 19:15:58 +0200
Subject: [PATCH 18/20] fix(workspace): keep the macOS header clear of the
 lights when zoomed out (#1815)

* fix(workspace): keep the macOS header clear of the lights when zoomed out

App zoom scales CSS pixels but not the native traffic lights. At zoom
-3/-4 the header column starts near 29 window pixels, so Back and the
playlist switcher slid under the lights, and the 27px header band let
the lights overlap the context panel below.

A shell-level TrafficLightsClearanceDirective now publishes the lights'
clearance in CSS pixels (84 x 48 window pixels, from the page zoom
factor) on macOS. The header band grows to the vertical clearance (the
rail starts its first link at the same band, replacing the rail's own
zoom listener), and the header's leading padding grows to the
horizontal clearance less the rail column. Both equal the default
layout at 100 %; Windows/Linux and the phone layout are unchanged. The
native position is shared with the main process as
MACOS_TRAFFIC_LIGHTS_POSITION.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(workspace): pass the header clearance poll labels as options

Equivalent to the string form, which Playwright 1.62 also accepts, but
explicit in every version (Greptile review).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(workspace): check the header switcher before history exists

Since the header's history fallback, a list reached by navigation
leads with Back. The macOS check now takes the switcher on the first
page, which has nothing to go back to, and Back on a detail page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../workspace-header-traffic-light-zoom.md    |   6 +
 .../src/window-controls.e2e.ts                | 192 +++++++++++++++---
 apps/electron-backend/src/app/app.ts          |   3 +-
 docs/architecture/workspace-shell.md          |  35 +++-
 libs/shared/interfaces/src/index.ts           |   1 +
 .../src/lib/macos-traffic-lights.ts           |   7 +
 .../workspace-shell-header.component.scss     |  10 +-
 .../workspace-shell-rail.component.html       |   6 +-
 .../workspace-shell-rail.component.scss       |   9 +-
 .../workspace-shell-rail.component.spec.ts    |  42 ----
 .../workspace-shell-rail.component.ts         |  35 +---
 ...traffic-lights-clearance.directive.spec.ts | 157 ++++++++++++++
 .../traffic-lights-clearance.directive.ts     | 100 +++++++++
 .../workspace-shell.component.html            |   7 +-
 .../workspace-shell.component.scss            |  24 ++-
 .../workspace-shell.component.spec.ts         |  14 ++
 .../workspace-shell.component.ts              |   2 +
 17 files changed, 519 insertions(+), 131 deletions(-)
 create mode 100644 .changes/workspace-header-traffic-light-zoom.md
 create mode 100644 libs/shared/interfaces/src/lib/macos-traffic-lights.ts
 create mode 100644 libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.spec.ts
 create mode 100644 libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.ts

diff --git a/.changes/workspace-header-traffic-light-zoom.md b/.changes/workspace-header-traffic-light-zoom.md
new file mode 100644
index 000000000..4263f10ac
--- /dev/null
+++ b/.changes/workspace-header-traffic-light-zoom.md
@@ -0,0 +1,6 @@
+---
+type: fix
+area: workspace
+---
+
+On macOS, zooming the app out no longer slides the Back button and the playlist switcher under the window's close, minimize and zoom buttons; the top bar also stays tall enough that the buttons never overlap the page below.
diff --git a/apps/electron-backend-e2e/src/window-controls.e2e.ts b/apps/electron-backend-e2e/src/window-controls.e2e.ts
index da90fec62..f60b844fb 100644
--- a/apps/electron-backend-e2e/src/window-controls.e2e.ts
+++ b/apps/electron-backend-e2e/src/window-controls.e2e.ts
@@ -1,8 +1,14 @@
+import type { Page } from '@playwright/test';
 import {
+    addXtreamPortal,
+    clickFirstGridListCard,
     closeElectronApp,
     expect,
     launchElectronApp,
+    LaunchedElectronApp,
+    resetMockServers,
     test,
+    waitForXtreamWorkspaceReady,
 } from './electron-test-fixtures';
 
 // Custom window controls are only rendered on Windows/Linux; macOS keeps
@@ -188,6 +194,93 @@ test.describe('Custom window controls', () => {
     });
 });
 
+// The native buttons are 14pt circles. At 100 % zoom the first header
+// control starts 60pt right of their origin, where macOS 26 ends them
+// (earlier releases end them at 52pt).
+const lightsHeight = 14;
+const headerControlOffset = 60;
+
+/** Where macOS drew the native window buttons, in window points. */
+async function trafficLights(
+    app: LaunchedElectronApp
+): Promise<{ x: number; y: number }> {
+    const lights = await app.electronApp.evaluate(({ BrowserWindow }) =>
+        BrowserWindow.getAllWindows()[0]?.getWindowButtonPosition()
+    );
+    expect(lights, 'native window button position').toBeTruthy();
+    return lights ?? { x: Number.NaN, y: Number.NaN };
+}
+
+/** Window pixels per CSS pixel. */
+function zoomFactor(page: Page): Promise<number> {
+    return page.evaluate(() => window.outerWidth / window.innerWidth);
+}
+
+/**
+ * Steps the app zoom to its minimum (−4, ≈48 %). App zoom scales CSS pixels
+ * but not the native buttons.
+ */
+async function zoomOutFully(page: Page): Promise<void> {
+    for (let step = 0; step < 8; step++) {
+        await page.evaluate(() => window.electron.adjustZoomLevel('out'));
+    }
+    await expect.poll(() => zoomFactor(page)).toBeLessThan(0.6);
+}
+
+async function resetZoom(page: Page): Promise<void> {
+    await page.evaluate(() => window.electron.adjustZoomLevel('reset'));
+    await expect.poll(() => zoomFactor(page)).toBeCloseTo(1, 2);
+}
+
+/**
+ * The header's first rendered control and the top of the content area, in
+ * window pixels (CSS pixels times the zoom factor).
+ */
+function headerLayout(
+    page: Page
+): Promise<{ control?: string; left: number; contentTop: number }> {
+    return page.locator('.workspace-header').evaluate((header) => {
+        const zoom = window.outerWidth / window.innerWidth;
+        const first = [...header.children].find(
+            (child) => child.getBoundingClientRect().width > 0
+        );
+        const body = document.querySelector('.workspace-body');
+        return {
+            control:
+                first?.getAttribute('data-test-id') ??
+                first?.tagName.toLowerCase(),
+            left: (first?.getBoundingClientRect().left ?? 0) * zoom,
+            contentTop: (body?.getBoundingClientRect().top ?? 0) * zoom,
+        };
+    });
+}
+
+/**
+ * The first header control starts right of the lights and the content area
+ * below them. Polled: the layout follows a zoom change after its resize.
+ */
+async function expectHeaderClearOfLights(
+    page: Page,
+    lights: { x: number; y: number },
+    control: string,
+    label: string
+): Promise<void> {
+    const layout = () => headerLayout(page);
+    await expect
+        .poll(async () => (await layout()).control, { message: label })
+        .toBe(control);
+    await expect
+        .poll(async () => (await layout()).left, {
+            message: `${label}: first control`,
+        })
+        .toBeGreaterThanOrEqual(lights.x + headerControlOffset);
+    await expect
+        .poll(async () => (await layout()).contentTop, {
+            message: `${label}: content top`,
+        })
+        .toBeGreaterThanOrEqual(lights.y + lightsHeight);
+}
+
 test.describe('macOS traffic lights', () => {
     test.skip(
         process.platform !== 'darwin',
@@ -205,49 +298,88 @@ test.describe('macOS traffic lights', () => {
             const firstLink = page.locator('.app-rail a').first();
             await expect(firstLink).toBeVisible();
 
-            const [linkBox, contentBox] = await Promise.all([
-                firstLink.boundingBox(),
-                page.locator('.workspace-content').boundingBox(),
-            ]);
             // Aligned with the content area, where the dashboard hero starts.
-            expect(
-                Math.abs((linkBox?.y ?? 0) - (contentBox?.y ?? -100))
-            ).toBeLessThanOrEqual(1);
+            const linkOffsetFromContent = async (): Promise<number> => {
+                const [linkBox, contentBox] = await Promise.all([
+                    firstLink.boundingBox(),
+                    page.locator('.workspace-content').boundingBox(),
+                ]);
+                return Math.abs(
+                    (linkBox?.y ?? 0) - (contentBox?.y ?? Number.NaN)
+                );
+            };
+            expect(await linkOffsetFromContent()).toBeLessThanOrEqual(1);
 
-            const lights = await app.electronApp.evaluate(({ BrowserWindow }) =>
-                BrowserWindow.getAllWindows()[0]?.getWindowButtonPosition()
-            );
-            expect(lights, 'native window button position').toBeTruthy();
-            const lightsY = lights?.y ?? Number.NaN;
-            // The buttons are about 14pt tall; keep a visible gap below them,
-            // measured in window pixels (CSS pixels times the zoom factor).
+            const lights = await trafficLights(app);
+            // Keep a visible gap below the buttons, measured in window pixels
+            // (CSS pixels times the zoom factor).
             const linkTopInWindowPixels = async (): Promise<number> => {
                 const [box, zoom] = await Promise.all([
                     firstLink.boundingBox(),
-                    page.evaluate(() => window.outerWidth / window.innerWidth),
+                    zoomFactor(page),
                 ]);
                 return (box?.y ?? Number.NaN) * zoom;
             };
             expect(await linkTopInWindowPixels()).toBeGreaterThanOrEqual(
-                lightsY + 14 + 16
+                lights.y + lightsHeight + 16
             );
 
-            // App zoom scales CSS pixels but not the native buttons: at the
-            // smallest zoom the inset must still clear them.
-            for (let step = 0; step < 8; step++) {
-                await page.evaluate(() =>
-                    window.electron.adjustZoomLevel('out')
-                );
-            }
-            await expect
-                .poll(() =>
-                    page.evaluate(() => window.outerWidth / window.innerWidth)
-                )
-                .toBeLessThan(0.6);
+            // At the smallest zoom the inset must still clear the buttons,
+            // and the link still starts with the content area.
+            await zoomOutFully(page);
             await expect
                 .poll(linkTopInWindowPixels)
-                .toBeGreaterThanOrEqual(lightsY + 14 + 8);
-            await page.evaluate(() => window.electron.adjustZoomLevel('reset'));
+                .toBeGreaterThanOrEqual(lights.y + lightsHeight + 8);
+            await expect.poll(linkOffsetFromContent).toBeLessThanOrEqual(1);
+            await resetZoom(page);
+        } finally {
+            await closeElectronApp(app);
+        }
+    });
+
+    test('@xtream @electron the first header control clears the lights at default and minimum zoom', async ({
+        dataDir,
+        request,
+    }) => {
+        await resetMockServers(request, ['xtream']);
+        const app = await launchElectronApp(dataDir);
+
+        try {
+            const page = app.mainWindow;
+            const lights = await trafficLights(app);
+            const switcher = 'app-playlist-switcher';
+            const back = 'workspace-header-back';
+
+            // The first page has no history to go back to: the switcher leads.
+            await expectHeaderClearOfLights(page, lights, switcher, 'start');
+            await zoomOutFully(page);
+            await expectHeaderClearOfLights(
+                page,
+                lights,
+                switcher,
+                'start at min zoom'
+            );
+            await resetZoom(page);
+
+            // A detail page puts its Back first, pulled 8px toward the edge.
+            await addXtreamPortal(page);
+            await waitForXtreamWorkspaceReady(page);
+            await page
+                .getByRole('link', { name: 'Series', exact: true })
+                .click();
+            await clickFirstGridListCard(page);
+            await expect(page.getByTestId(back)).toBeVisible({
+                timeout: 20_000,
+            });
+            await expectHeaderClearOfLights(page, lights, back, 'detail');
+            await zoomOutFully(page);
+            await expectHeaderClearOfLights(
+                page,
+                lights,
+                back,
+                'detail at min zoom'
+            );
+            await resetZoom(page);
         } finally {
             await closeElectronApp(app);
         }
diff --git a/apps/electron-backend/src/app/app.ts b/apps/electron-backend/src/app/app.ts
index 0573c4bba..e60b010c1 100644
--- a/apps/electron-backend/src/app/app.ts
+++ b/apps/electron-backend/src/app/app.ts
@@ -1,6 +1,7 @@
 import { app, BrowserWindow, Menu, screen, session, shell } from 'electron';
 import {
     ElectronBridgeWindowState,
+    MACOS_TRAFFIC_LIGHTS_POSITION,
     WINDOW_STATE_CHANGED,
 } from '@iptvnator/shared/interfaces';
 import { join, resolve } from 'path';
@@ -401,7 +402,7 @@ export default class App {
             return {
                 titleBarStyle: 'hidden',
                 titleBarOverlay: true,
-                trafficLightPosition: { x: 16, y: 20 },
+                trafficLightPosition: { ...MACOS_TRAFFIC_LIGHTS_POSITION },
             };
         }
 
diff --git a/docs/architecture/workspace-shell.md b/docs/architecture/workspace-shell.md
index af2bc2a68..6f6772a0a 100644
--- a/docs/architecture/workspace-shell.md
+++ b/docs/architecture/workspace-shell.md
@@ -390,15 +390,32 @@ The Electron window hides the native title bar on all desktop platforms
 (`titleBarStyle: 'hidden'` in `apps/electron-backend/src/app/app.ts`):
 
 1. macOS keeps the native traffic lights (`titleBarOverlay: true`,
-   `trafficLightPosition`); the renderer draws no window buttons. The lights
-   sit in the 56 px header band above the rail, so the macOS rail
-   (`.app-rail.is-macos`) starts its first link at 56 px: level with the
-   content area and the dashboard hero, with its hover surface clear of the
-   lights. App zoom scales CSS pixels but not the lights, so the rail
-   publishes the page zoom factor (`outerWidth / innerWidth`, refreshed on
-   `resize`) as `--rail-zoom-factor` and keeps at least 48 window pixels when
-   zoomed out. `window-controls.e2e.ts` checks the alignment and the gap at
-   default and minimum zoom on macOS.
+   `trafficLightPosition` from `MACOS_TRAFFIC_LIGHTS_POSITION` in
+   `@iptvnator/shared/interfaces`); the renderer draws no window buttons.
+   The lights sit in the header band (`--workspace-header-band`, 56 px) over
+   the rail and the header's leading padding. The macOS rail
+   (`.app-rail.is-macos`) starts its first link below the band: level with
+   the content area and the dashboard hero, with its hover surface clear of
+   the lights. The header's content starts 84 window pixels from the
+   window's left edge (60 px rail plus 24 px padding). macOS 26 ends the
+   lights at 76 (earlier releases at 68), which is where Back's left edge
+   sits at 100 % because of its 8 px pull-in.
+
+   App zoom (see "Zoom level") scales CSS pixels but not the lights. On
+   macOS, `TrafficLightsClearanceDirective` on `.workspace-shell` reads the
+   page zoom factor (`outerWidth / innerWidth`, refreshed on `resize`) and
+   publishes the clearance in CSS pixels as `--traffic-lights-clear-x` (84
+   window pixels) and `--traffic-lights-clear-y` (48: the lights' bottom
+   plus a gap). Zoomed out, the band grows to the vertical clearance, so the
+   lights never overlap the content area. The header's leading padding grows
+   to the horizontal clearance, less the rail column
+   (`--workspace-header-lights-inset`). At 100 % both match the default
+   layout. Off macOS nothing is published and the defaults apply. The phone
+   layout, which puts the rail in a row above the header, ignores the
+   inset. `window-controls.e2e.ts` ("macOS traffic lights") checks the rail
+   alignment, the first header control (the switcher on the first page,
+   which has no history fallback yet, then a detail page's Back) and the
+   content top at default and minimum zoom.
 2. Windows and Linux use renderer-drawn window controls
    (`app-window-controls`, `libs/ui/components/src/lib/window-controls/`).
    `frame` is intentionally left untouched so native resize borders and
diff --git a/libs/shared/interfaces/src/index.ts b/libs/shared/interfaces/src/index.ts
index 95a3a08f2..4b5fedb14 100644
--- a/libs/shared/interfaces/src/index.ts
+++ b/libs/shared/interfaces/src/index.ts
@@ -9,6 +9,7 @@ export * from './lib/embedded-mpv-session.interface';
 export * from './lib/embedded-mpv-support-watch.util';
 export * from './lib/subtitle-style.util';
 export * from './lib/zoom-level.util';
+export * from './lib/macos-traffic-lights';
 export * from './lib/electron-api.interface';
 export * from './lib/epg-channel-metadata.model';
 export * from './lib/epg-channel-with-programs.interface';
diff --git a/libs/shared/interfaces/src/lib/macos-traffic-lights.ts b/libs/shared/interfaces/src/lib/macos-traffic-lights.ts
new file mode 100644
index 000000000..a9fcac3f9
--- /dev/null
+++ b/libs/shared/interfaces/src/lib/macos-traffic-lights.ts
@@ -0,0 +1,7 @@
+/**
+ * Where macOS draws the native window buttons (close, minimize, zoom), in
+ * window points from the window's top-left corner. The main process places
+ * them (`trafficLightPosition`); the workspace shell keeps its controls clear
+ * of them at every app zoom, which scales CSS pixels but not the buttons.
+ */
+export const MACOS_TRAFFIC_LIGHTS_POSITION = { x: 16, y: 20 } as const;
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-header/workspace-shell-header.component.scss b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-header/workspace-shell-header.component.scss
index 169a8561f..6ebbbdc01 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-header/workspace-shell-header.component.scss
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-header/workspace-shell-header.component.scss
@@ -7,8 +7,12 @@
     display: flex;
     align-items: center;
     gap: 12px;
-    height: 56px;
+    // The shell's header band: 56px, taller on macOS when zoomed out.
+    height: 100%;
     padding: 0 24px;
+    // macOS: app zoom does not scale the traffic lights, so zoomed out the
+    // leading controls keep their 100 % distance from them (see the shell).
+    padding-inline-start: max(24px, var(--workspace-header-lights-inset, 0px));
     border-bottom: 1px solid var(--mat-sys-outline-variant);
     background: var(--app-header-bg, var(--mat-sys-surface-container-low));
     app-region: drag;
@@ -318,6 +322,10 @@
 @media (max-width: 780px) {
     .workspace-header {
         padding-inline: 10px;
+        padding-inline-start: max(
+            10px,
+            var(--workspace-header-lights-inset, 0px)
+        );
         gap: 10px;
     }
 
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.html b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.html
index 13e259f50..04dadb780 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.html
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.html
@@ -1,10 +1,6 @@
 <!-- No brand mark: it linked to the page the first workspace link opens.
      The page's Back lives in the header's leading slot. -->
-<aside
-    class="app-rail"
-    [class.is-macos]="isMacOS()"
-    [style.--rail-zoom-factor]="isMacOS() ? zoomFactor() : null"
->
+<aside class="app-rail" [class.is-macos]="isMacOS()">
     <app-workspace-shell-rail-links [links]="workspaceLinks()" />
 
     @if (primaryContextLinks().length > 0) {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.scss b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.scss
index 31c6b985a..805b211ae 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.scss
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.scss
@@ -29,13 +29,12 @@
     --rail-link-active-border: var(--app-selection-border);
     --rail-link-active-glow: var(--app-selection-glow);
 
-    // The traffic lights sit in the header band (56px, see the shell grid).
-    // The first link starts below that band, where the content area and the
+    // The traffic lights sit in the header band (see the shell grid). The
+    // first link starts below that band, where the content area and the
     // dashboard hero start, so its hover surface never touches the lights.
-    // App zoom scales CSS pixels but not the lights: zoomed out, the inset
-    // keeps 48 window pixels (lights' bottom plus a gap) instead.
+    // Zoomed out, the band grows to keep the lights inside it.
     &.is-macos {
-        padding-top: max(56px, calc(48px / var(--rail-zoom-factor, 1)));
+        padding-top: var(--workspace-header-band, 56px);
     }
 
     &::-webkit-scrollbar {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.spec.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.spec.ts
index efd193052..212bbf2b5 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.spec.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.spec.ts
@@ -84,48 +84,6 @@ describe('WorkspaceShellRailComponent', () => {
         ).not.toBeNull();
     });
 
-    describe('macOS zoom inset', () => {
-        const setWindowWidths = (outer: number, inner: number) => {
-            Object.defineProperty(window, 'outerWidth', {
-                configurable: true,
-                value: outer,
-            });
-            Object.defineProperty(window, 'innerWidth', {
-                configurable: true,
-                value: inner,
-            });
-        };
-        const zoomVar = () =>
-            (
-                fixture.nativeElement.querySelector('.app-rail') as HTMLElement
-            ).style.getPropertyValue('--rail-zoom-factor');
-
-        afterEach(() => setWindowWidths(1024, 1024));
-
-        it('publishes the page zoom factor on macOS and follows resize', () => {
-            setWindowWidths(1200, 1200);
-            fixture.componentRef.setInput('isMacOS', true);
-            fixture.detectChanges();
-            TestBed.tick();
-            fixture.detectChanges();
-            expect(zoomVar()).toBe('1');
-
-            // Zoomed out to 50%: the viewport holds twice the CSS pixels.
-            setWindowWidths(1200, 2400);
-            window.dispatchEvent(new Event('resize'));
-            fixture.detectChanges();
-            expect(zoomVar()).toBe('0.5');
-        });
-
-        it('leaves the inset alone off macOS', () => {
-            setWindowWidths(1200, 2400);
-            fixture.detectChanges();
-            TestBed.tick();
-            fixture.detectChanges();
-            expect(zoomVar()).toBe('');
-        });
-    });
-
     it('has no brand mark duplicating the first workspace link', () => {
         fixture.detectChanges();
 
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.ts
index 95343f6e9..980d29bf0 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/components/workspace-shell-rail/workspace-shell-rail.component.ts
@@ -1,12 +1,4 @@
-import { DOCUMENT } from '@angular/common';
-import {
-    ChangeDetectionStrategy,
-    Component,
-    effect,
-    inject,
-    input,
-    signal,
-} from '@angular/core';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { MatIcon } from '@angular/material/icon';
 import { MatTooltip } from '@angular/material/tooltip';
 import { RouterLink } from '@angular/router';
@@ -40,29 +32,4 @@ export class WorkspaceShellRailComponent {
     >(null);
     readonly railProviderClass = input('rail-context-region');
     readonly isSettingsRoute = input(false);
-
-    /**
-     * The page zoom factor. App zoom (`webFrame.setZoomLevel`) scales CSS
-     * pixels but not the native traffic lights, so the macOS top inset is
-     * kept in window pixels when zoomed out. Chromium reports the window in
-     * window pixels and the viewport in CSS pixels, and fires `resize` when
-     * the zoom changes.
-     */
-    protected readonly zoomFactor = signal(1);
-
-    constructor() {
-        const view = inject(DOCUMENT).defaultView;
-        effect((onCleanup) => {
-            if (!this.isMacOS() || !view) return;
-            const update = () =>
-                this.zoomFactor.set(
-                    view.innerWidth > 0 && view.outerWidth > 0
-                        ? view.outerWidth / view.innerWidth
-                        : 1
-                );
-            update();
-            view.addEventListener('resize', update);
-            onCleanup(() => view.removeEventListener('resize', update));
-        });
-    }
 }
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.spec.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.spec.ts
new file mode 100644
index 000000000..aadd31a62
--- /dev/null
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.spec.ts
@@ -0,0 +1,157 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import {
+    ZOOM_LEVEL_MAX,
+    ZOOM_LEVEL_MIN,
+    ZOOM_LEVEL_STEP,
+} from '@iptvnator/shared/interfaces';
+import {
+    pageZoomFactor,
+    TrafficLightsClearanceDirective,
+    trafficLightsClearance,
+} from './traffic-lights-clearance.directive';
+
+@Component({
+    template: `<div [appTrafficLightsClearance]="enabled()"></div>`,
+    imports: [TrafficLightsClearanceDirective],
+    changeDetection: ChangeDetectionStrategy.OnPush,
+})
+class HostComponent {
+    readonly enabled = signal(true);
+}
+
+function setWindowWidths(outer: number, inner: number): void {
+    Object.defineProperty(window, 'outerWidth', {
+        configurable: true,
+        value: outer,
+    });
+    Object.defineProperty(window, 'innerWidth', {
+        configurable: true,
+        value: inner,
+    });
+}
+
+describe('trafficLightsClearance', () => {
+    it('matches the default layout at 100 %', () => {
+        // x: the rail (60px) plus the header's padding (24px), where the
+        // header content already starts; y: inside the 56px header band.
+        expect(trafficLightsClearance(1)).toEqual({ x: 84, y: 48 });
+    });
+
+    it('keeps the same window pixels at every supported zoom', () => {
+        for (
+            let level = ZOOM_LEVEL_MIN;
+            level <= ZOOM_LEVEL_MAX;
+            level += ZOOM_LEVEL_STEP
+        ) {
+            const factor = 1.2 ** level;
+            const clearance = trafficLightsClearance(factor);
+            expect(clearance.x * factor).toBeCloseTo(84);
+            expect(clearance.y * factor).toBeCloseTo(48);
+        }
+    });
+
+    it('outgrows the default inset and band when zoomed out', () => {
+        const clearance = trafficLightsClearance(1.2 ** ZOOM_LEVEL_MIN);
+        // Past the 60px rail: wider than the header's 24px padding.
+        expect(clearance.x - 60).toBeGreaterThan(24);
+        expect(clearance.y).toBeGreaterThan(56);
+    });
+
+    it('treats an unusable factor as 100 %', () => {
+        for (const factor of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+            expect(trafficLightsClearance(factor)).toEqual({ x: 84, y: 48 });
+        }
+    });
+});
+
+describe('pageZoomFactor', () => {
+    it('divides window pixels by CSS pixels', () => {
+        expect(pageZoomFactor({ outerWidth: 1200, innerWidth: 2400 })).toBe(
+            0.5
+        );
+        expect(pageZoomFactor({ outerWidth: 1200, innerWidth: 1000 })).toBe(
+            1.2
+        );
+    });
+
+    it('falls back to 100 % without a measured window', () => {
+        expect(pageZoomFactor({ outerWidth: 0, innerWidth: 1200 })).toBe(1);
+        expect(pageZoomFactor({ outerWidth: 1200, innerWidth: 0 })).toBe(1);
+    });
+});
+
+describe('TrafficLightsClearanceDirective', () => {
+    let fixture: ComponentFixture<HostComponent>;
+
+    const clearance = () => {
+        const style = (
+            fixture.nativeElement.querySelector('div') as HTMLElement
+        ).style;
+        return {
+            x: style.getPropertyValue('--traffic-lights-clear-x'),
+            y: style.getPropertyValue('--traffic-lights-clear-y'),
+        };
+    };
+    const render = () => {
+        fixture.detectChanges();
+        TestBed.tick();
+        fixture.detectChanges();
+    };
+
+    beforeEach(() => {
+        setWindowWidths(1200, 1200);
+        fixture = TestBed.createComponent(HostComponent);
+    });
+
+    afterEach(() => setWindowWidths(1024, 1024));
+
+    it('publishes the clearance and follows zoom changes', () => {
+        render();
+        expect(clearance()).toEqual({ x: '84px', y: '48px' });
+
+        // Zoomed out to 50%: the viewport holds twice the CSS pixels.
+        setWindowWidths(1200, 2400);
+        window.dispatchEvent(new Event('resize'));
+        fixture.detectChanges();
+        expect(clearance()).toEqual({ x: '168px', y: '96px' });
+    });
+
+    it('measures the zoom before the first render', () => {
+        setWindowWidths(1200, 2400);
+        fixture.detectChanges();
+        expect(clearance()).toEqual({ x: '168px', y: '96px' });
+    });
+
+    it('publishes nothing off macOS and stops listening when disabled', () => {
+        render();
+        const removeListener = jest.spyOn(window, 'removeEventListener');
+
+        fixture.componentInstance.enabled.set(false);
+        render();
+        expect(clearance()).toEqual({ x: '', y: '' });
+        expect(removeListener).toHaveBeenCalledWith(
+            'resize',
+            expect.any(Function)
+        );
+
+        setWindowWidths(1200, 2400);
+        window.dispatchEvent(new Event('resize'));
+        fixture.componentInstance.enabled.set(true);
+        render();
+        // Re-enabled, it measures the current zoom.
+        expect(clearance()).toEqual({ x: '168px', y: '96px' });
+        removeListener.mockRestore();
+    });
+
+    it('stops listening when destroyed', () => {
+        render();
+        const removeListener = jest.spyOn(window, 'removeEventListener');
+        fixture.destroy();
+        expect(removeListener).toHaveBeenCalledWith(
+            'resize',
+            expect.any(Function)
+        );
+        removeListener.mockRestore();
+    });
+});
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.ts
new file mode 100644
index 000000000..d1154eef0
--- /dev/null
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/traffic-lights-clearance.directive.ts
@@ -0,0 +1,100 @@
+import { DOCUMENT } from '@angular/common';
+import {
+    computed,
+    Directive,
+    effect,
+    inject,
+    input,
+    signal,
+} from '@angular/core';
+import { MACOS_TRAFFIC_LIGHTS_POSITION } from '@iptvnator/shared/interfaces';
+
+/**
+ * The three buttons are 14 pt circles. macOS 26 spaces them 23 pt apart
+ * (60 pt in all); earlier releases 20 pt (52 pt).
+ */
+const LIGHTS_WIDTH = 60;
+const LIGHTS_HEIGHT = 14;
+/**
+ * Window points from the window's left edge to where header content may
+ * start: the lights plus a gap. 84 is also where the header's content starts
+ * at 100 % (the 60 px rail plus 24 px padding), so default zoom is unchanged.
+ */
+const CLEAR_X = MACOS_TRAFFIC_LIGHTS_POSITION.x + LIGHTS_WIDTH + 8;
+/** Window points from the top to where the content area may start. */
+const CLEAR_Y = MACOS_TRAFFIC_LIGHTS_POSITION.y + LIGHTS_HEIGHT + 14;
+
+/** CSS pixels from the window's top-left corner that clear the lights. */
+export interface TrafficLightsClearance {
+    readonly x: number;
+    readonly y: number;
+}
+
+/**
+ * The page zoom factor. Chromium reports the window in window pixels and the
+ * viewport in CSS pixels, so their ratio is the app zoom.
+ */
+export function pageZoomFactor(
+    view: Pick<Window, 'innerWidth' | 'outerWidth'>
+): number {
+    return view.innerWidth > 0 && view.outerWidth > 0
+        ? view.outerWidth / view.innerWidth
+        : 1;
+}
+
+/**
+ * The clearance at `zoomFactor`. App zoom (`webFrame.setZoomLevel`) scales
+ * CSS pixels but not the native buttons: zoomed out, the same window points
+ * hold more CSS pixels.
+ */
+export function trafficLightsClearance(
+    zoomFactor: number
+): TrafficLightsClearance {
+    const factor =
+        Number.isFinite(zoomFactor) && zoomFactor > 0 ? zoomFactor : 1;
+    return { x: CLEAR_X / factor, y: CLEAR_Y / factor };
+}
+
+/**
+ * Publishes the macOS traffic-light clearance on its host as
+ * `--traffic-lights-clear-x` and `--traffic-lights-clear-y`, refreshed on
+ * `resize` (Chromium fires it when the zoom changes). The shell grid, the
+ * rail and the header read them; without them (off macOS) they fall back to
+ * their default layout.
+ */
+@Directive({
+    selector: '[appTrafficLightsClearance]',
+    host: {
+        '[style.--traffic-lights-clear-x]': 'clearX()',
+        '[style.--traffic-lights-clear-y]': 'clearY()',
+    },
+})
+export class TrafficLightsClearanceDirective {
+    /** True where the native traffic lights overlay the window (macOS). */
+    readonly enabled = input(false, { alias: 'appTrafficLightsClearance' });
+
+    private readonly view = inject(DOCUMENT).defaultView;
+    private readonly zoomFactor = signal(
+        this.view ? pageZoomFactor(this.view) : 1
+    );
+    private readonly clearance = computed(() =>
+        this.enabled() ? trafficLightsClearance(this.zoomFactor()) : null
+    );
+    protected readonly clearX = computed(() => toPx(this.clearance()?.x));
+    protected readonly clearY = computed(() => toPx(this.clearance()?.y));
+
+    constructor() {
+        effect((onCleanup) => {
+            const view = this.view;
+            if (!this.enabled() || !view) return;
+            const update = () => this.zoomFactor.set(pageZoomFactor(view));
+            update();
+            view.addEventListener('resize', update);
+            onCleanup(() => view.removeEventListener('resize', update));
+        });
+    }
+}
+
+function toPx(value: number | undefined): string | null {
+    return value === undefined ? null : `${value}px`;
+}
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.html b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.html
index 884cd045f..4506a2c18 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.html
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.html
@@ -1,4 +1,9 @@
-<div class="workspace-shell" appPlaylistDropZone #dropZone="playlistDropZone">
+<div
+    class="workspace-shell"
+    appPlaylistDropZone
+    #dropZone="playlistDropZone"
+    [appTrafficLightsClearance]="facade.isMacOS"
+>
     <app-playlist-drop-overlay [state]="dropZone.overlayState()" />
     @if (facade.showXtreamImportOverlay()) {
         <app-workspace-shell-import-overlay />
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.scss b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.scss
index 8fffb65b0..b95fa4dd2 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.scss
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.scss
@@ -6,9 +6,14 @@
 }
 
 .workspace-shell {
+    // The header band. On macOS it also holds the traffic lights, which app
+    // zoom does not scale: zoomed out, it stays tall enough to contain them
+    // (`TrafficLightsClearanceDirective` publishes the clearance), so no
+    // content starts beside them. The macOS rail starts its first link here.
+    --workspace-header-band: max(56px, var(--traffic-lights-clear-y, 0px));
     display: grid;
     grid-template-columns: 60px 1fr;
-    grid-template-rows: 56px minmax(0, 1fr) auto;
+    grid-template-rows: var(--workspace-header-band) minmax(0, 1fr) auto;
     width: 100%;
     height: 100%;
     min-height: 0;
@@ -27,6 +32,12 @@ app-workspace-shell-header {
     grid-column: 2;
     grid-row: 1;
     min-width: 0;
+    // The leading inset that keeps the header's controls clear of the macOS
+    // traffic lights: their clearance minus the rail column. It equals the
+    // header's 24px padding at 100 % zoom and is negative off macOS.
+    --workspace-header-lights-inset: calc(
+        var(--traffic-lights-clear-x, 0px) - 60px
+    );
 }
 
 .workspace-body {
@@ -72,11 +83,16 @@ app-workspace-shell-context-sidebar {
     box-shadow: -4px 8px 20px var(--app-content-shadow, rgba(0, 0, 0, 0.18));
 }
 
-
 @media (max-width: 780px) {
     .workspace-shell {
         grid-template-columns: 56px 1fr;
-        grid-template-rows: 56px 1fr auto;
+        grid-template-rows: var(--workspace-header-band) 1fr auto;
+    }
+
+    app-workspace-shell-header {
+        --workspace-header-lights-inset: calc(
+            var(--traffic-lights-clear-x, 0px) - 56px
+        );
     }
 }
 
@@ -91,9 +107,11 @@ app-workspace-shell-context-sidebar {
         grid-row: 1;
     }
 
+    // Below the rail's row, the header never meets the traffic lights.
     app-workspace-shell-header {
         grid-column: 1;
         grid-row: 2;
+        --workspace-header-lights-inset: 0px;
     }
 
     .workspace-body {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.spec.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.spec.ts
index dd168da3f..5624bb823 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.spec.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.spec.ts
@@ -18,6 +18,7 @@ import {
     WorkspacePortalContext,
     WorkspaceShellContextPanel,
 } from '@iptvnator/workspace/shell/util';
+import { TrafficLightsClearanceDirective } from './traffic-lights-clearance.directive';
 import { WorkspaceShellComponent } from './workspace-shell.component';
 import {
     WorkspaceHeaderBulkAction,
@@ -270,6 +271,7 @@ describe('WorkspaceShellComponent', () => {
                         MockWorkspaceShellHeaderComponent,
                         MockWorkspaceShellImportOverlayComponent,
                         MockWorkspaceShellRailComponent,
+                        TrafficLightsClearanceDirective,
                     ],
                     providers: [
                         {
@@ -307,6 +309,14 @@ describe('WorkspaceShellComponent', () => {
             By.directive(MockWorkspaceShellHeaderComponent)
         ).componentInstance as MockWorkspaceShellHeaderComponent;
         expect(header.activeDownloadsCount()).toBe(3);
+        // macOS: the rail and header read the traffic-light clearance.
+        expect(
+            (
+                fixture.nativeElement.querySelector(
+                    '.workspace-shell'
+                ) as HTMLElement
+            ).style.getPropertyValue('--traffic-lights-clear-x')
+        ).toMatch(/px$/);
         expect(
             fixture.nativeElement.querySelector(
                 'app-workspace-shell-context-sidebar'
@@ -357,6 +367,7 @@ describe('WorkspaceShellComponent', () => {
                         MockWorkspaceShellHeaderComponent,
                         MockWorkspaceShellImportOverlayComponent,
                         MockWorkspaceShellRailComponent,
+                        TrafficLightsClearanceDirective,
                     ],
                     providers: [
                         {
@@ -434,6 +445,7 @@ describe('WorkspaceShellComponent', () => {
                         MockWorkspaceShellHeaderComponent,
                         MockWorkspaceShellImportOverlayComponent,
                         MockWorkspaceShellRailComponent,
+                        TrafficLightsClearanceDirective,
                     ],
                     providers: [
                         {
@@ -507,6 +519,7 @@ describe('WorkspaceShellComponent', () => {
                         MockWorkspaceShellHeaderComponent,
                         MockWorkspaceShellImportOverlayComponent,
                         MockWorkspaceShellRailComponent,
+                        TrafficLightsClearanceDirective,
                     ],
                     providers: [
                         {
@@ -606,6 +619,7 @@ describe('WorkspaceShellComponent', () => {
                         MockWorkspaceShellHeaderComponent,
                         MockWorkspaceShellImportOverlayComponent,
                         MockWorkspaceShellRailComponent,
+                        TrafficLightsClearanceDirective,
                     ],
                     providers: [
                         {
diff --git a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
index 98e433cb5..3a99aaab9 100644
--- a/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
+++ b/libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
@@ -21,6 +21,7 @@ import { WorkspaceShellContextSidebarComponent } from './components/workspace-sh
 import { WorkspaceShellHeaderComponent } from './components/workspace-shell-header/workspace-shell-header.component';
 import { WorkspaceShellImportOverlayComponent } from './components/workspace-shell-import-overlay/workspace-shell-import-overlay.component';
 import { WorkspaceShellRailComponent } from './components/workspace-shell-rail/workspace-shell-rail.component';
+import { TrafficLightsClearanceDirective } from './traffic-lights-clearance.directive';
 import { WorkspaceShellFacade } from './services/workspace-shell.facade';
 import { WorkspaceShellXtreamImportService } from './services/workspace-shell-xtream-import.service';
 import { WorkspaceShellCommandPaletteService } from './services/workspace-shell-command-palette.service';
@@ -42,6 +43,7 @@ import { LIVE_CATEGORIES_POPOVER } from '@iptvnator/portal/shared/util';
         PlaylistDropOverlayComponent,
         PlaylistDropZoneDirective,
         RouterOutlet,
+        TrafficLightsClearanceDirective,
         WorkspaceShellContextSidebarComponent,
         WorkspaceShellHeaderComponent,
         WorkspaceShellImportOverlayComponent,

From 259aebf25d9563c48a2ef066e61e2933c33d425a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 19:28:44 +0200
Subject: [PATCH 19/20] chore(deps-dev): bump sharp from 0.35.4 to 0.35.5
 (#1846)

Bumps [sharp](https://github.com/lovell/sharp) from 0.35.4 to 0.35.5.
- [Release notes](https://github.com/lovell/sharp/releases)
- [Commits](https://github.com/lovell/sharp/compare/v0.35.4...v0.35.5)

---
updated-dependencies:
- dependency-name: sharp
  dependency-version: 0.35.5
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 package.json   |   2 +-
 pnpm-lock.yaml | 253 +++++++++++++++++++++++++------------------------
 2 files changed, 132 insertions(+), 123 deletions(-)

diff --git a/package.json b/package.json
index 406ec03df..f7698f44c 100644
--- a/package.json
+++ b/package.json
@@ -257,7 +257,7 @@
         "parse-srcset": "1.0.2",
         "parse5": "8.0.1",
         "prettier": "^3.9.6",
-        "sharp": "0.35.4",
+        "sharp": "0.35.5",
         "tailwindcss": "^3.4.19",
         "ts-jest": "^29.4.12",
         "ts-node": "10.9.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 244eb6e6a..2da0209f9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -474,8 +474,8 @@ importers:
         specifier: ^3.9.6
         version: 3.9.6
       sharp:
-        specifier: 0.35.4
-        version: 0.35.4(@types/node@20.19.9)
+        specifier: 0.35.5
+        version: 0.35.5(@types/node@20.19.9)
       tailwindcss:
         specifier: ^3.4.19
         version: 3.4.19(tsx@4.23.13)(yaml@2.9.0)
@@ -2145,160 +2145,160 @@ packages:
     resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
     engines: {node: '>=18'}
 
-  '@img/sharp-darwin-arm64@0.35.4':
-    resolution: {integrity: sha512-Uhfl4V4lhP2nbUVF9+hyH1+luj86f1gUFeo8ALYxFoULoU+G87D43BfeMP8XHsk9boxAnCY/bf2EHwhA7MuGsA==}
+  '@img/sharp-darwin-arm64@0.35.5':
+    resolution: {integrity: sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==}
     engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-darwin-x64@0.35.4':
-    resolution: {integrity: sha512-hWniXY3bG5qKpkKrAwPe4y+VTPmf086YQAnkxWh7uA1YrlRouWGa0M0Mxj3ZjnXFkv7/TD1bTy9lGUK26vRvWw==}
+  '@img/sharp-darwin-x64@0.35.5':
+    resolution: {integrity: sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==}
     engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-freebsd-wasm32@0.35.4':
-    resolution: {integrity: sha512-lIsKw/BU+kjB4eZjxrYrZmwOJYi3Ajrv66iAlBmUPyKc3HpnloevB1g3wxGD9P/5BbQ1brBGl65VRRrCvQDEqA==}
+  '@img/sharp-freebsd-wasm32@0.35.5':
+    resolution: {integrity: sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==}
     engines: {node: '>=20.9.0'}
     os: [freebsd]
 
-  '@img/sharp-libvips-darwin-arm64@1.3.3':
-    resolution: {integrity: sha512-suTBPTDGrI9WodccaDdwZItTSaBYASlBk1NSfElSHrUfzu3szG6lvIF58+WiFvnfzuK8ZBFS5zE00PxqxnRiPg==}
+  '@img/sharp-libvips-darwin-arm64@1.3.4':
+    resolution: {integrity: sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==}
     cpu: [arm64]
     os: [darwin]
 
-  '@img/sharp-libvips-darwin-x64@1.3.3':
-    resolution: {integrity: sha512-FVJZ5mITMobmXIz/hPDTw0EintTW5H3WfrxwLqEqjiIihlu+hVRyGrFQ60xl0Lxn7Bt3zdpevPaQi0HEzqz9fw==}
+  '@img/sharp-libvips-darwin-x64@1.3.4':
+    resolution: {integrity: sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==}
     cpu: [x64]
     os: [darwin]
 
-  '@img/sharp-libvips-linux-arm64@1.3.3':
-    resolution: {integrity: sha512-0DaL0A6Xu6sQSQFwe4iVCrKWU2cCTItnRsYsCdxAMm9NF6twAA9BKnoqy4hqz4+azQ0JHuA26qiUKsf1XJ/v5A==}
+  '@img/sharp-libvips-linux-arm64@1.3.4':
+    resolution: {integrity: sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==}
     cpu: [arm64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linux-arm@1.3.3':
-    resolution: {integrity: sha512-3rbU4vqXXc3hY/OiXdl52xZvT0F1yEngWfvqudtPJg/KkyiaQw2DRsFrNzpmLvfavbwOq3qXn36GP8obHRULQA==}
+  '@img/sharp-libvips-linux-arm@1.3.4':
+    resolution: {integrity: sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==}
     cpu: [arm]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linux-ppc64@1.3.3':
-    resolution: {integrity: sha512-cdn1OvUBwsXhbC0zSzJnNzf5MZ/mTrobawDvNXBTxe8VtqKAm0sRuEY2Evzovb/w9JMk4TvRxqt1mekSuJz64w==}
+  '@img/sharp-libvips-linux-ppc64@1.3.4':
+    resolution: {integrity: sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==}
     cpu: [ppc64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linux-riscv64@1.3.3':
-    resolution: {integrity: sha512-HjPVx7yKz+0lqdhDlTw1tt90wamBoxhiXpvl1XZpJLiHH4RCJ5yDTqH+VlYPv2fwFs89JFw4c1IexYOcQUi4IQ==}
+  '@img/sharp-libvips-linux-riscv64@1.3.4':
+    resolution: {integrity: sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==}
     cpu: [riscv64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linux-s390x@1.3.3':
-    resolution: {integrity: sha512-neWLh+3yCNThxnfy3c4BbVBeGgt9aftno+XbT56iK28RgeDs3UOFWviLWlUu0bArYVYJaFDK+RRohbicUNCm8Q==}
+  '@img/sharp-libvips-linux-s390x@1.3.4':
+    resolution: {integrity: sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==}
     cpu: [s390x]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linux-x64@1.3.3':
-    resolution: {integrity: sha512-4vKmvAst9nrowcqquKFAyZJUDolUaIp8uRiN0mWFguJ1IplC9/pitXtlnnlU4aa/eJw3J7i67V+pwUL+wZGdsA==}
+  '@img/sharp-libvips-linux-x64@1.3.4':
+    resolution: {integrity: sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==}
     cpu: [x64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-libvips-linuxmusl-arm64@1.3.3':
-    resolution: {integrity: sha512-Y9kQaLMuNoB0bPYOOdcZMaseNrFpPodIWWMrx+CZyydf2xn68j9WYc6sWWRrDwNkzCQjKYfc68L7jKjGlHMibw==}
+  '@img/sharp-libvips-linuxmusl-arm64@1.3.4':
+    resolution: {integrity: sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==}
     cpu: [arm64]
     os: [linux]
     libc: [musl]
 
-  '@img/sharp-libvips-linuxmusl-x64@1.3.3':
-    resolution: {integrity: sha512-fj8Mv0HHfD1Rr+4I68+3agJynxDWtBFgicTbSOb9Bke6pIwzGcJ+RX/yHjmiEGFMCavY/dxvem7MyNaJF+wDiw==}
+  '@img/sharp-libvips-linuxmusl-x64@1.3.4':
+    resolution: {integrity: sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==}
     cpu: [x64]
     os: [linux]
     libc: [musl]
 
-  '@img/sharp-linux-arm64@0.35.4':
-    resolution: {integrity: sha512-De4jpEnAU8Hd5oT0j1G3uL4ZvTuipVMn7YC6vPaJhy6/7EwEae0SVAoBrUMYQbkLGDm85taVWwuPc1a44LTzCQ==}
+  '@img/sharp-linux-arm64@0.35.5':
+    resolution: {integrity: sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==}
     engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linux-arm@0.35.4':
-    resolution: {integrity: sha512-7OAS8gI0EReKGVN2HssHlM6umJgxF5VI3xN0p9FA91p/YO+ou5hiNghLdZ5BEHztwaaK5+bLKRf8x/o2L2nk9A==}
+  '@img/sharp-linux-arm@0.35.5':
+    resolution: {integrity: sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==}
     engines: {node: '>=20.9.0'}
     cpu: [arm]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linux-ppc64@0.35.4':
-    resolution: {integrity: sha512-2oYZJeIl4kCcMGk4ouZVjnkCtFrpQFlNEtJ6GbxzhHQchwH0NH/qEb9ykmOl29dqwMq+JhFdZn+1ak2FKhI9fQ==}
+  '@img/sharp-linux-ppc64@0.35.5':
+    resolution: {integrity: sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==}
     engines: {node: '>=20.9.0'}
     cpu: [ppc64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linux-riscv64@0.35.4':
-    resolution: {integrity: sha512-cPbNChoRURAWdebDIHSenxRpgEdy7JkPydSnUxRm9VvKD7m0/xVaR/8Fzlu81pk5nHEvHH87UZUA7cTtwnbJSA==}
+  '@img/sharp-linux-riscv64@0.35.5':
+    resolution: {integrity: sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==}
     engines: {node: '>=20.9.0'}
     cpu: [riscv64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linux-s390x@0.35.4':
-    resolution: {integrity: sha512-RY0JFY8Fd6RonCBtHz+DvadaPkXDSI1AUn6yWL9TipqkZ1vY8w8evqdgyDFnkm4/K1ve1TvZiaePP5oSd4+WVQ==}
+  '@img/sharp-linux-s390x@0.35.5':
+    resolution: {integrity: sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==}
     engines: {node: '>=20.9.0'}
     cpu: [s390x]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linux-x64@0.35.4':
-    resolution: {integrity: sha512-9qvvEAuk8k89TfWUoX2htWjbAMX8p+NxCppjpcg5k6xMsjhBQPTsoIh36h9Qde4WRuGpJeYnOjdosDn/cnv+OA==}
+  '@img/sharp-linux-x64@0.35.5':
+    resolution: {integrity: sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==}
     engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [linux]
     libc: [glibc]
 
-  '@img/sharp-linuxmusl-arm64@0.35.4':
-    resolution: {integrity: sha512-KB5jxpfWQTr0nc3xdHtWChdbifHrBGsd2SM62Eyxrl8afikm+f5qGBU75SJIZBT/S1MC8XyacdlXBMSWq6OURA==}
+  '@img/sharp-linuxmusl-arm64@0.35.5':
+    resolution: {integrity: sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==}
     engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [linux]
     libc: [musl]
 
-  '@img/sharp-linuxmusl-x64@0.35.4':
-    resolution: {integrity: sha512-f+eZJZIQNEEd26RPSW+76chwOf1XtA2Y/O+5ocVyLliHkeih3e+jhLVBdNTd2rS3IbNXK8+ug93Vf5ZXtF5Lxg==}
+  '@img/sharp-linuxmusl-x64@0.35.5':
+    resolution: {integrity: sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==}
     engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [linux]
     libc: [musl]
 
-  '@img/sharp-wasm32@0.35.4':
-    resolution: {integrity: sha512-zQnl4Kwp7Q6NHsENtU2T/00Zi+w3AQNwz3+UaTyVBy2FpXrzXzGjndpK61onhZjRtRpQXxCTeqw19bVyXOh7jA==}
+  '@img/sharp-wasm32@0.35.5':
+    resolution: {integrity: sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==}
     engines: {node: '>=20.9.0'}
 
-  '@img/sharp-webcontainers-wasm32@0.35.4':
-    resolution: {integrity: sha512-ESfNkywmCfPNyaZjxooddJQiQ+l/nTpGEOGthxiLnIHXC/CmcBixnfwUleX9mCz9ovrUUvKMap/pm8RYbzfwaA==}
+  '@img/sharp-webcontainers-wasm32@0.35.5':
+    resolution: {integrity: sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==}
     engines: {node: '>=20.9.0'}
     cpu: [wasm32]
 
-  '@img/sharp-win32-arm64@0.35.4':
-    resolution: {integrity: sha512-iNdlBX9gLVvqe2I3uIJSIKTq6wckP/DYxZtcqxm09x5Gi24DnFBmPAWZmr60ZyYMG0xlzo6goG3670ar+RXvRw==}
+  '@img/sharp-win32-arm64@0.35.5':
+    resolution: {integrity: sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==}
     engines: {node: '>=20.9.0'}
     cpu: [arm64]
     os: [win32]
 
-  '@img/sharp-win32-ia32@0.35.4':
-    resolution: {integrity: sha512-kqRsbaa5CS6KHlpxnN7WhE6vAAugXyZButpRdvDWetlv6Qv4N9WTcrWzF7tXfB9T7MsoadqdI8hmwLq6UlLvtw==}
+  '@img/sharp-win32-ia32@0.35.5':
+    resolution: {integrity: sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==}
     engines: {node: ^20.9.0}
     cpu: [ia32]
     os: [win32]
 
-  '@img/sharp-win32-x64@0.35.4':
-    resolution: {integrity: sha512-XtmnYhBcrORsJ4XJngyzr/EWP0hRZLAZRFaApdKuviyqF78+ylxh2y06ZmtULAMOnObJ3ucpN0AcwSWnMowTRg==}
+  '@img/sharp-win32-x64@0.35.5':
+    resolution: {integrity: sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==}
     engines: {node: '>=20.9.0'}
     cpu: [x64]
     os: [win32]
@@ -4682,6 +4682,11 @@ packages:
     engines: {node: '>=0.4.0'}
     hasBin: true
 
+  acorn@8.19.0:
+    resolution: {integrity: sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
   address@2.0.3:
     resolution: {integrity: sha512-XNAb/a6TCqou+TufU8/u11HCu9x1gYvOoxLwtlXgIqmkrYQADVv6ljyW2zwiPhHz9R1gItAWpuDrdJMmrOBFEA==}
     engines: {node: '>= 16.0.0'}
@@ -8854,13 +8859,14 @@ packages:
 
   shaka-player@5.2.12:
     resolution: {integrity: sha512-vEsuVDI3+oLh+yqpjXexQZlg2XMUBI0VrqatDuKWacPaxAud6Uph5uCowUPLhUgNG5XKWCpoM4l1r8qYzWH+zg==}
+    engines: {node: '>=18'}
 
   shallow-clone@3.0.1:
     resolution: {integrity: sha512-/6KqX+GVUdqPuPPd2LxDDxzX6CAbjJehAAOKlNpqqUpAqPM6HeL8f+o3a+JsyGjn2lv0WY8UsTgUJjU9Ok55NA==}
     engines: {node: '>=8'}
 
-  sharp@0.35.4:
-    resolution: {integrity: sha512-n++8XWcj+jCOr2IOl7h8LbKnGBDY4aPbmprMONBNFdn0ImXqpGVv5zliDs0V9HbmbCQLpbuo2ej9rAoOQTvMDA==}
+  sharp@0.35.5:
+    resolution: {integrity: sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==}
     engines: {node: '>=20.9.0'}
     peerDependencies:
       '@types/node': '*'
@@ -11798,108 +11804,108 @@ snapshots:
 
   '@img/colour@1.1.0': {}
 
-  '@img/sharp-darwin-arm64@0.35.4':
+  '@img/sharp-darwin-arm64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-darwin-arm64': 1.3.3
+      '@img/sharp-libvips-darwin-arm64': 1.3.4
     optional: true
 
-  '@img/sharp-darwin-x64@0.35.4':
+  '@img/sharp-darwin-x64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-darwin-x64': 1.3.3
+      '@img/sharp-libvips-darwin-x64': 1.3.4
     optional: true
 
-  '@img/sharp-freebsd-wasm32@0.35.4':
+  '@img/sharp-freebsd-wasm32@0.35.5':
     dependencies:
-      '@img/sharp-wasm32': 0.35.4
+      '@img/sharp-wasm32': 0.35.5
     optional: true
 
-  '@img/sharp-libvips-darwin-arm64@1.3.3':
+  '@img/sharp-libvips-darwin-arm64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-darwin-x64@1.3.3':
+  '@img/sharp-libvips-darwin-x64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-arm64@1.3.3':
+  '@img/sharp-libvips-linux-arm64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-arm@1.3.3':
+  '@img/sharp-libvips-linux-arm@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-ppc64@1.3.3':
+  '@img/sharp-libvips-linux-ppc64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-riscv64@1.3.3':
+  '@img/sharp-libvips-linux-riscv64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-s390x@1.3.3':
+  '@img/sharp-libvips-linux-s390x@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linux-x64@1.3.3':
+  '@img/sharp-libvips-linux-x64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linuxmusl-arm64@1.3.3':
+  '@img/sharp-libvips-linuxmusl-arm64@1.3.4':
     optional: true
 
-  '@img/sharp-libvips-linuxmusl-x64@1.3.3':
+  '@img/sharp-libvips-linuxmusl-x64@1.3.4':
     optional: true
 
-  '@img/sharp-linux-arm64@0.35.4':
+  '@img/sharp-linux-arm64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-arm64': 1.3.3
+      '@img/sharp-libvips-linux-arm64': 1.3.4
     optional: true
 
-  '@img/sharp-linux-arm@0.35.4':
+  '@img/sharp-linux-arm@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-arm': 1.3.3
+      '@img/sharp-libvips-linux-arm': 1.3.4
     optional: true
 
-  '@img/sharp-linux-ppc64@0.35.4':
+  '@img/sharp-linux-ppc64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-ppc64': 1.3.3
+      '@img/sharp-libvips-linux-ppc64': 1.3.4
     optional: true
 
-  '@img/sharp-linux-riscv64@0.35.4':
+  '@img/sharp-linux-riscv64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-riscv64': 1.3.3
+      '@img/sharp-libvips-linux-riscv64': 1.3.4
     optional: true
 
-  '@img/sharp-linux-s390x@0.35.4':
+  '@img/sharp-linux-s390x@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-s390x': 1.3.3
+      '@img/sharp-libvips-linux-s390x': 1.3.4
     optional: true
 
-  '@img/sharp-linux-x64@0.35.4':
+  '@img/sharp-linux-x64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linux-x64': 1.3.3
+      '@img/sharp-libvips-linux-x64': 1.3.4
     optional: true
 
-  '@img/sharp-linuxmusl-arm64@0.35.4':
+  '@img/sharp-linuxmusl-arm64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-arm64': 1.3.3
+      '@img/sharp-libvips-linuxmusl-arm64': 1.3.4
     optional: true
 
-  '@img/sharp-linuxmusl-x64@0.35.4':
+  '@img/sharp-linuxmusl-x64@0.35.5':
     optionalDependencies:
-      '@img/sharp-libvips-linuxmusl-x64': 1.3.3
+      '@img/sharp-libvips-linuxmusl-x64': 1.3.4
     optional: true
 
-  '@img/sharp-wasm32@0.35.4':
+  '@img/sharp-wasm32@0.35.5':
     dependencies:
       '@emnapi/runtime': 1.11.3
     optional: true
 
-  '@img/sharp-webcontainers-wasm32@0.35.4':
+  '@img/sharp-webcontainers-wasm32@0.35.5':
     dependencies:
-      '@img/sharp-wasm32': 0.35.4
+      '@img/sharp-wasm32': 0.35.5
     optional: true
 
-  '@img/sharp-win32-arm64@0.35.4':
+  '@img/sharp-win32-arm64@0.35.5':
     optional: true
 
-  '@img/sharp-win32-ia32@0.35.4':
+  '@img/sharp-win32-ia32@0.35.5':
     optional: true
 
-  '@img/sharp-win32-x64@0.35.4':
+  '@img/sharp-win32-x64@0.35.5':
     optional: true
 
   '@inquirer/ansi@2.0.8': {}
@@ -14144,6 +14150,9 @@ snapshots:
 
   acorn@8.18.0: {}
 
+  acorn@8.19.0:
+    optional: true
+
   address@2.0.3: {}
 
   aes-decrypter@3.1.3:
@@ -14444,7 +14453,7 @@ snapshots:
       yargs-parser: 22.0.0
       zod: 4.5.4
     optionalDependencies:
-      sharp: 0.35.4(@types/node@20.19.9)
+      sharp: 0.35.5(@types/node@20.19.9)
     transitivePeerDependencies:
       - '@azure/app-configuration'
       - '@azure/cosmos'
@@ -19564,37 +19573,37 @@ snapshots:
     dependencies:
       kind-of: 6.0.3
 
-  sharp@0.35.4(@types/node@20.19.9):
+  sharp@0.35.5(@types/node@20.19.9):
     dependencies:
       '@img/colour': 1.1.0
       detect-libc: 2.1.2
       semver: 7.8.5
     optionalDependencies:
-      '@img/sharp-darwin-arm64': 0.35.4
-      '@img/sharp-darwin-x64': 0.35.4
-      '@img/sharp-freebsd-wasm32': 0.35.4
-      '@img/sharp-libvips-darwin-arm64': 1.3.3
-      '@img/sharp-libvips-darwin-x64': 1.3.3
-      '@img/sharp-libvips-linux-arm': 1.3.3
-      '@img/sharp-libvips-linux-arm64': 1.3.3
-      '@img/sharp-libvips-linux-ppc64': 1.3.3
-      '@img/sharp-libvips-linux-riscv64': 1.3.3
-      '@img/sharp-libvips-linux-s390x': 1.3.3
-      '@img/sharp-libvips-linux-x64': 1.3.3
-      '@img/sharp-libvips-linuxmusl-arm64': 1.3.3
-      '@img/sharp-libvips-linuxmusl-x64': 1.3.3
-      '@img/sharp-linux-arm': 0.35.4
-      '@img/sharp-linux-arm64': 0.35.4
-      '@img/sharp-linux-ppc64': 0.35.4
-      '@img/sharp-linux-riscv64': 0.35.4
-      '@img/sharp-linux-s390x': 0.35.4
-      '@img/sharp-linux-x64': 0.35.4
-      '@img/sharp-linuxmusl-arm64': 0.35.4
-      '@img/sharp-linuxmusl-x64': 0.35.4
-      '@img/sharp-webcontainers-wasm32': 0.35.4
-      '@img/sharp-win32-arm64': 0.35.4
-      '@img/sharp-win32-ia32': 0.35.4
-      '@img/sharp-win32-x64': 0.35.4
+      '@img/sharp-darwin-arm64': 0.35.5
+      '@img/sharp-darwin-x64': 0.35.5
+      '@img/sharp-freebsd-wasm32': 0.35.5
+      '@img/sharp-libvips-darwin-arm64': 1.3.4
+      '@img/sharp-libvips-darwin-x64': 1.3.4
+      '@img/sharp-libvips-linux-arm': 1.3.4
+      '@img/sharp-libvips-linux-arm64': 1.3.4
+      '@img/sharp-libvips-linux-ppc64': 1.3.4
+      '@img/sharp-libvips-linux-riscv64': 1.3.4
+      '@img/sharp-libvips-linux-s390x': 1.3.4
+      '@img/sharp-libvips-linux-x64': 1.3.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.3.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.3.4
+      '@img/sharp-linux-arm': 0.35.5
+      '@img/sharp-linux-arm64': 0.35.5
+      '@img/sharp-linux-ppc64': 0.35.5
+      '@img/sharp-linux-riscv64': 0.35.5
+      '@img/sharp-linux-s390x': 0.35.5
+      '@img/sharp-linux-x64': 0.35.5
+      '@img/sharp-linuxmusl-arm64': 0.35.5
+      '@img/sharp-linuxmusl-x64': 0.35.5
+      '@img/sharp-webcontainers-wasm32': 0.35.5
+      '@img/sharp-win32-arm64': 0.35.5
+      '@img/sharp-win32-ia32': 0.35.5
+      '@img/sharp-win32-x64': 0.35.5
       '@types/node': 20.19.9
 
   shebang-command@2.0.0:
@@ -19950,7 +19959,7 @@ snapshots:
   terser@5.49.2:
     dependencies:
       '@jridgewell/source-map': 0.3.11
-      acorn: 8.18.0
+      acorn: 8.19.0
       commander: 2.20.3
       source-map-support: 0.5.21
     optional: true

From 335392afa9f37746d314ef990068860a69564a50 Mon Sep 17 00:00:00 2001
From: 4gray <4gray@users.noreply.github.com>
Date: Tue, 6 Oct 2026 22:48:19 +0200
Subject: [PATCH 20/20] perf(portal): make the portal Eager components OnPush
 (#1821)

* perf(portal): make the portal Eager components OnPush

Plan item C6 step 3 for libs/portal: the nine Eager components in
portal/shared/ui, portal/stalker/feature and portal/xtream/feature switch
to OnPush. Their templates read signals, signal inputs, async pipes and
template-event state; the plain fields they write outside events
(playback request ids, save throttles) are not rendered.

The already-OnPush live channel lists filled their favorites Maps in a
subscription and the Xtream list dropped programme previews after the EPG
mapping dialog, all without marking the view. They now call markForCheck
like the neighbouring handlers do, so a late favorites answer shows its
hearts without waiting for an unrelated check. A regression test for the
Xtream list fails without the call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(portal): let the favorites handler's markForCheck render the heart

Review follow-up (Greptile): the test forced detectChanges() after the
favorites arrived, so it passed without the handler's markForCheck(). It
now lets the fixture render on its own; removing the call fails it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: 4gray <fourgray@proton.me>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/architecture/zoneless-migration.md       | 24 ++++-----
 .../favorites-layout.component.ts             |  2 +-
 .../playlist-error-view.component.ts          |  2 +-
 .../search-form/search-form.component.ts      |  2 +-
 .../navigation/portal-rail-links.component.ts |  2 +-
 .../stalker-catalog-detail.component.ts       |  2 +-
 .../stalker-favorites-button.component.ts     |  2 +-
 .../stalker-live-stream-layout.component.ts   |  2 +
 .../stalker-series-view.component.ts          |  2 +-
 .../global-search-results.component.ts        |  2 +-
 .../portal-channels-list.component.spec.ts    | 50 +++++++++++++++++++
 .../portal-channels-list.component.ts         |  2 +
 .../serial-details.component.ts               |  2 +-
 13 files changed, 75 insertions(+), 21 deletions(-)

diff --git a/docs/architecture/zoneless-migration.md b/docs/architecture/zoneless-migration.md
index 08dddfcec..95bfd0670 100644
--- a/docs/architecture/zoneless-migration.md
+++ b/docs/architecture/zoneless-migration.md
@@ -149,15 +149,15 @@ picker), so each marks itself on the form's `events` through
 
 ### libs/portal (9)
 
-- [ ] `libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts`
-- [ ] `libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts`
-- [ ] `libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts`
-- [ ] `libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts`
-- [ ] `libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts`
-- [ ] `libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts`
-- [ ] `libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts`
-- [ ] `libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts`
-- [ ] `libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts`
+- [x] `libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts`
+- [x] `libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts`
+- [x] `libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts`
+- [x] `libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts`
+- [x] `libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts`
+- [x] `libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts`
+- [x] `libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts`
+- [x] `libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts`
+- [x] `libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts`
 
 Test-only files that set Eager are not listed; they do not ship. The guard
 skips every `*.spec.ts` / `*.test.ts` file with or without a suffix of one
@@ -179,9 +179,9 @@ the field a signal (or a `computed`), or writes it through one.
 | [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-item/playlist-item.component.ts` `checkPortalStatus` | plain `portalStatus` assigned after `await` in `ngOnInit` (PWA only: skipped when source health is supported) | playlist |
 | [ ] | `libs/playlist/shared/ui/src/lib/recent-playlists/playlist-info/playlist-info.component.ts` (EPG clear and EPG file pick handlers) | plain `playlist` reassigned after `await` | playlist |
 | [ ] | `libs/playlist/import/feature/src/lib/stalker-portal-import/stalker-portal-import.component.ts` (device-id derivation) | `form.patchValue` after `await`; template getters read `control.value`, which is not signal-backed | playlist |
-| [ ] | `libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts` (favorites load) | `favorites` Map filled in a `subscribe` without `markForCheck`; the component is OnPush already, so this is a latent bug today | portal |
-| [ ] | `libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts` (favorites load) | same pattern; the neighbouring `favoriteMarks.changes$` handler does call `markForCheck` | portal |
-| [ ] | same file, programme dialog `afterClosed` | deletes from `epgPrograms`/`currentProgramsProgress` after `await` without marking | portal |
+| [x] | `libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts` (favorites load) | `favorites` Map filled in a `subscribe` without `markForCheck`; the component is OnPush already, so this is a latent bug today | portal |
+| [x] | `libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts` (favorites load) | same pattern; the neighbouring `favoriteMarks.changes$` handler does call `markForCheck` | portal |
+| [x] | same file, programme dialog `afterClosed` | deletes from `epgPrograms`/`currentProgramsProgress` after `await` without marking | portal |
 | [x] | `apps/web/src/app/settings/settings-backup.facade.ts` (backup import) | `change` listener on a detached file input → `hydrateFromStore()`; section templates read `form().value.theme`/`coverSize`; each section now marks itself on its form's `events` (`markSectionForCheckOnFormEvents`), which `settings.component.form.spec.ts` guards without a forced render | apps/web |
 | [x] | `libs/ui/epg/src/lib/epg-guide/epg-guide.component.ts` (jump to now, keyboard focus) | `afterNextRender` registered from CDK/RxJS callbacks; zone.js followed them with a tick, zoneless schedules no render, so the guide opened at midnight. It now marks itself when it registers the hook. Found by `epg-guide.e2e.ts` on the zoneless build | flag |
 | [ ] | `libs/ui/remote-control/src/lib/remote-control/remote-control.component.ts` | plain `isLoading`/`error`/`status` written after `await` and from a 2 s `setInterval` | only if `apps/remote-control-web` goes zoneless |
diff --git a/libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts b/libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts
index 52c4e285d..ea7a5b251 100644
--- a/libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts
+++ b/libs/portal/shared/ui/src/lib/components/favorites-layout/favorites-layout.component.ts
@@ -56,7 +56,7 @@ export interface FavoriteLayoutItem {
         './favorites-layout.component.scss',
         '../../styles/portal-sidebar.scss',
     ],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         CategoryViewComponent,
         ContentCardComponent,
diff --git a/libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts b/libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts
index cae2b8f39..161840ee5 100644
--- a/libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts
+++ b/libs/portal/shared/ui/src/lib/components/playlist-error-view/playlist-error-view.component.ts
@@ -25,7 +25,7 @@ import { DialogService } from '@iptvnator/ui/components';
     selector: 'app-playlist-error-view',
     templateUrl: './playlist-error-view.component.html',
     styleUrls: ['./playlist-error-view.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [MatButtonModule, MatIconModule, RouterLink, TranslateModule],
 })
 export class PlaylistErrorViewComponent {
diff --git a/libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts b/libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts
index 5028d424d..30bffdd1f 100644
--- a/libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts
+++ b/libs/portal/shared/ui/src/lib/components/search-form/search-form.component.ts
@@ -39,7 +39,7 @@ export interface SearchFilter {
         TranslatePipe,
     ],
     templateUrl: './search-form.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             .search-container {
diff --git a/libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts b/libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts
index 2976a0cee..610770e80 100644
--- a/libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts
+++ b/libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts
@@ -22,7 +22,7 @@ import {
     selector: 'app-portal-rail-links',
     imports: [MatIcon, MatListModule, MatTooltip, RouterLink, RouterLinkActive],
     templateUrl: './portal-rail-links.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styleUrl: './portal-rail-links.component.scss',
 })
 export class PortalRailLinksComponent {
diff --git a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
index 488abdeeb..156cdf6ab 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-catalog-detail/stalker-catalog-detail.component.ts
@@ -60,7 +60,7 @@ import { createPlaybackSessionKey } from '@iptvnator/playback/util';
     selector: 'app-stalker-catalog-detail',
     imports: [StalkerSeriesViewComponent, VodDetailsComponent],
     templateUrl: './stalker-catalog-detail.component.html',
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     styles: [
         `
             :host {
diff --git a/libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts b/libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts
index efdc2bb9d..5d7ccccc6 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-favorites-button/stalker-favorites-button.component.ts
@@ -27,7 +27,7 @@ type FavoriteButtonItem = StalkerSelectedVodItem & {
     selector: 'app-favorites-button',
     templateUrl: './stalker-favorites-button.component.html',
     styleUrls: ['./stalker-favorites-button.component.scss'],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [AsyncPipe, DetailIconButtonComponent, MatIconModule, TranslateModule],
 })
 export class FavoritesButtonComponent {
diff --git a/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts b/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts
index f38b6b715..5005aa1c1 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-live-stream-layout/stalker-live-stream-layout.component.ts
@@ -679,6 +679,8 @@ export class StalkerLiveStreamLayoutComponent
                             );
                         }
                     });
+                    // OnPush: the Map changed outside any template event.
+                    this.cdr.markForCheck();
                 });
         }
 
diff --git a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
index a4fd531f4..2d8ab7b36 100644
--- a/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
+++ b/libs/portal/stalker/feature/src/lib/stalker-series-view/stalker-series-view.component.ts
@@ -155,7 +155,7 @@ interface StalkerSeriesPlaybackRequestContext {
         TranslatePipe,
         SeasonContainerComponent,
     ],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     providers: [
         StalkerSeriesTmdbSeasonsService,
         StalkerSeriesHeroPresenter,
diff --git a/libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts b/libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts
index 1b0185345..72d6f17a5 100644
--- a/libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts
+++ b/libs/portal/xtream/feature/src/lib/global-search-results/global-search-results.component.ts
@@ -6,7 +6,7 @@ import { SearchResultsComponent } from '../search-results/search-results.compone
     selector: 'app-global-search-results',
     imports: [SearchResultsComponent],
     providers: [XtreamStore],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     template: '<app-search-results/>',
 })
 export class GlobalSearchResultsComponent {}
diff --git a/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.spec.ts b/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.spec.ts
index 7afa25423..a05a42348 100644
--- a/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.spec.ts
+++ b/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.spec.ts
@@ -900,6 +900,56 @@ describe('PortalChannelsListComponent', () => {
         ).toBe('live:290');
     });
 
+    // OnPush: favorites resolve asynchronously (IPC or IndexedDB), outside
+    // any template event, so the heart must follow without a zone tick.
+    it('renders favorites that load after the first render', async () => {
+        const favorites$ = new Subject<FavoriteItem[]>();
+        favoritesService.getFavorites.mockReturnValue(favorites$);
+        selectedTypeContentLoading.set(false);
+        selectedChannels.set([{ title: 'Cartoon Network', xtream_id: 50 }]);
+        currentPlaylist.set({
+            id: 'playlist-1',
+            password: 'secret',
+            serverUrl: 'http://demo.example',
+            username: 'demo',
+        });
+        fixture.detectChanges();
+        await fixture.whenStable();
+        fixture.detectChanges();
+        const viewport = fixture.componentInstance.viewport();
+        Object.defineProperty(
+            viewport?.elementRef.nativeElement,
+            'clientHeight',
+            { configurable: true, value: 520 }
+        );
+        viewport?.checkViewportSize();
+        fixture.detectChanges();
+        await fixture.whenStable();
+        fixture.detectChanges();
+        const row = () =>
+            fixture.debugElement.query(By.directive(ChannelListItemComponent))
+                .componentInstance as ChannelListItemComponent;
+        expect(row().isFavorite()).toBe(false);
+
+        // From here the fixture renders on its own: a forced detectChanges()
+        // would hide a favorites handler that does not mark the view.
+        fixture.autoDetectChanges();
+        favorites$.next([
+            {
+                content_id: 1,
+                playlist_id: 'playlist-1',
+                type: 'live',
+                title: 'Cartoon Network',
+                category_id: 7,
+                xtream_id: 50,
+            },
+        ] satisfies FavoriteItem[]);
+        await fixture.whenStable();
+        await new Promise((resolve) => setTimeout(resolve));
+
+        expect(row().isFavorite()).toBe(true);
+    });
+
     it('scrolls the virtual list to the selected live channel', () => {
         const channels = Array.from({ length: 20 }, (_, index) => ({
             title: `Channel ${index + 1}`,
diff --git a/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts b/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts
index a8723a295..623fcb345 100644
--- a/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts
+++ b/libs/portal/xtream/feature/src/lib/portal-channels-list/portal-channels-list.component.ts
@@ -334,6 +334,7 @@ export class PortalChannelsListComponent implements AfterViewInit, OnDestroy {
                             true
                         );
                     });
+                    this.cdr.markForCheck();
                 });
             // A toggle in another list instance (the sidebar and the
             // fullscreen channel panel render this component side by side)
@@ -771,6 +772,7 @@ export class PortalChannelsListComponent implements AfterViewInit, OnDestroy {
                 this.epgQueueService.invalidate(streamId);
                 this.epgPrograms.delete(streamId);
                 this.currentProgramsProgress.delete(streamId);
+                this.cdr.markForCheck();
                 this.loadEpgForVisibleChannels(this.channelsToPreview());
             });
     }
diff --git a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
index c29a4e087..c35ead6ed 100644
--- a/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
+++ b/libs/portal/xtream/feature/src/lib/serial-details/serial-details.component.ts
@@ -87,7 +87,7 @@ import { SerialDetailsDownloadAdapterService } from './serial-details-download-a
         SerialDetailsMenuService,
         SerialDetailsDownloadAdapterService,
     ],
-    changeDetection: ChangeDetectionStrategy.Eager,
+    changeDetection: ChangeDetectionStrategy.OnPush,
     imports: [
         CastCrewRowComponent,
         DetailActionButtonComponent,