feat(playback): recommend recovery actions (#1374)

* docs(playback): design recovery recommendations

* docs(playback): plan recovery recommendations

* refactor(playback): extract diagnostic utilities

* feat(playback): define recovery recommendation contracts

* feat(playback): rank recovery recommendations

* feat(playback): track session recovery attempts

* feat(playback): identify content recovery sessions

* feat(ui): add ranked playback diagnostic panel

* feat(playback): switch temporarily to recommended players

* test(playback): cover temporary player recommendation

* test(playback): verify recommendation capability guards

* docs(playback): document recovery recommendations

* fix(playback): keep recovery keys credential-free

* fix(playback): remove derived tracking ownership

* fix(playback): preserve distinct recovery fallbacks

* fix(playback): reset resume for new sources

* fix(playback): preserve desktop recovery guidance

* docs(playback): clarify recovery policy exceptions

* fix(playback): reject stale progress updates

* fix(playback): keep protected recovery guidance neutral

* test(playback): cover stale progress output

* fix(playback): neutralize protected diagnostic copy

* fix(playback): harden runtime guidance ownership

* fix(playback): stabilize recovery application ownership

* fix(ci): classify playback util coverage

* fix(e2e): preserve playback fixture bytes

docs/architecture/player-controls-contract.md

@@ -7,8 +7,7 @@ Embedded MPV rendering and native-view bounds behavior remain documented in
 
 ## Current status
 
-The shared-controls foundation from PR #1148 now supports four runtime
-consumers and includes:
+The shared-controls foundation supports four runtime consumers and includes:
 
 - the `PlayerController` contract, default state, and capability presets;
 - the standalone `app-player-controls` presentation component and its
@@ -82,6 +81,25 @@ also includes a recording coordinator that correlates asynchronous snapshots
 with the active playback/session owner, serializes toggles, and cancels pending
 ownership when the session, playback, engine, or component changes.
 
+## Diagnostics And Recovery Ownership Boundary
+
+`PlayerController` remains a sibling of playback diagnostics and recovery
+recommendations. It owns engine-neutral playback state, capabilities, and
+commands for the shared controls; it does not classify errors, call
+`recommendPlaybackRecovery()`, rank actions, track recovery attempts, choose a
+temporary player, or own content-session policy.
+
+Those pure contracts and policies live in `@iptvnator/playback/util` (Nx
+project `playback-util`). `WebPlayerViewComponent` owns their in-memory,
+session-local application. No diagnostic or recommendation state or command is
+added to `PlayerController`.
+
+The only controls-layer participation is interaction gating. While the sibling
+diagnostic panel is visible, a web-player host disables shared surface and
+keyboard ownership and exits only its own DOM fullscreen so the recovery
+actions remain reachable. Clearing the diagnostic restores those paths; it
+does not make the controls contract an owner of the recovery lifecycle.
+
 ## Why this exists
 
 Historically each playback engine owned both media integration and controls UI.
@@ -306,7 +324,7 @@ playback diagnostic is visible: `WebPlayerViewComponent` passes
 components bind that value to `showControls` and
 `shortcutsEnabled`. If the active player shell owns DOM fullscreen, its host
 exits fullscreen before hiding the controls so the sibling diagnostic banner
-and its retry/fallback actions remain visible; fullscreen owned by another
+and its recovery actions remain visible; fullscreen owned by another
 element is left untouched. Retrying playback or clearing the diagnostic
 restores both interaction paths.