iptvnator/docs/superpowers/specs/2026-08-08-external-playback-launch-feedback-design.md

# External Playback Launch Feedback Design

## Goal

Make MPV and VLC recovery actions reversible and understandable. A target stays
available after an attempt, the diagnostic panel reports launch progress and
outcome, and the workspace dock remains the authoritative global view of the
external-player session.

## Current Problem

`WebPlayerViewComponent` records MPV or VLC as attempted before emitting the
fallback request. The recommendation policy then removes attempted targets, so
each button disappears even though IPTVnator only knows that the action was
requested. It does not yet know whether the external player started or played
the stream.

The external-player session already reports `launching`, `opened`, `playing`,
`error`, and `closed`, but the dock hides `error`, renders `opened` and
`playing` as the same “Opened” status, and exposes no dismiss action for an
external-player error.

## Considered Approaches

### 1. Keep actions and show only a local timed spinner

This is the smallest change, but the UI would guess when launching finished
and could disagree with the Electron session. It is rejected because the app
already has structured launch state.

### 2. Use only callbacks on every `PlaybackFallbackRequest` host

Every M3U, Xtream, Stalker, and shared host could make the launch promise the
only feedback source. This supplies an exact initial session ID, but by itself
still misses later `playing` and `error` session updates.

### 3. Correlate the owned launch result with the shared external session

This is the selected approach. The web-player component keeps source launch
ownership in its existing host output. Its credential-free tracker binds the
host's returned launch promise to the current fieldless intent token, and only
that exact result may supply the initial session ID. Later status changes come
from `PORTAL_EXTERNAL_PLAYBACK.activeSession` and must match that ID. This
prevents a delayed timed-out attempt from taking over a retry. No URL, headers,
DRM data, credentials, or raw diagnostic payload enters the ownership state.

## State Model

Each external target has component-local state:

- `idle`: no launch is in flight; a previous successful/closed attempt may
  still be represented by an attempt count;
- `launching`: the request is being handed off or Electron is spawning the
  player;
- `started`: Electron confirmed the process or existing player accepted the
  stream;
- `playing`: MPV/VLC position polling confirmed playback;
- `error`: the launch/session failed.

The state also contains an attempt count and, only after correlation, the exact
external session ID. It never contains the stream URL, headers, credentials,
engine messages, or error details. A fieldless `Symbol` intent plus the current
content-session generation rejects stale completions and timers.

Changing `playbackSessionKey` resets both targets. Destroying the component
invalidates the intent and clears its bounded launch timer. A later session
update is accepted only if it belongs to the correlated session ID.

## Recommendation Behaviour

External attempts no longer remove MPV or VLC from the ranked action list.
Inline engine attempts retain the current family-exclusion rules.

Within an otherwise unchanged policy result:

- an untried external target ranks ahead of an attempted sibling;
- fewer attempts rank ahead of more attempts;
- policy order remains the tie-breaker;
- the first surviving action remains primary and the total remains capped at
  three.

Labels describe the action, while adjacent status copy describes the outcome:

| State                   | Action label       | Status                |
| ----------------------- | ------------------ | --------------------- |
| `idle`, never attempted | Open in MPV/VLC    | none                  |
| `launching`             | Opening MPV/VLC…   | Opening player…       |
| `started`               | Open MPV/VLC again | Player started        |
| `playing`               | Open MPV/VLC again | Playing               |
| `error`                 | Try MPV/VLC again  | External player error |

Buttons remain mounted with stable recommendation keys, preserving layout and
focus. During a launch handshake, recovery actions expose `aria-busy` and
`aria-disabled`; activation handlers enforce the same single-flight guard, so
keyboard or programmatic activation cannot duplicate the request. A small
spinner replaces the external-action icon. State changes are announced through
concise `aria-live="polite"` status text.

Before a recovery action opens another external player, it closes the currently
tracked live external session through `PORTAL_EXTERNAL_PLAYBACK`. If the
session is still live and cannot be closed, the new attempt fails locally
instead of starting a second process. The coordinator applies the exact
confirmed close synchronously before emitting the replacement, so coalesced
Angular effects cannot leave stale Playing feedback. If diagnostic ownership
changes while closing, the unlaunched intent is cancelled without reporting a
launch error. MPV and VLC are available again after the handshake.

If no matching session arrives within a bounded timeout, the target transitions
to `error`. The timeout is feedback for a missing handoff, not evidence about
stream playback.

## Dock Behaviour

`ExternalPlaybackService.visibleSession` keeps error sessions visible until
the user dismisses them or another launch begins. The dock maps session states
without inference:

- `launching` → “Opening player…” with a spinner;
- `opened` → “Player started”;
- `playing` → “Playing”;
- `error` → the existing session error or a localized generic external-player
  failure;
- `closed` remains hidden by the global service.

The dock uses an `aria-live="polite"` status region and `aria-busy` while
launching. A live closable session shows “Close player”; an error shows
“Dismiss”. Dismiss only hides the terminal notification and never stores a
retry payload, so headers and credentials are not retained for a dock retry.

## Error And Privacy Boundaries

The diagnostic action shows only localized, app-owned launch-state copy. It
does not render rejected promise messages or external-player stderr. The dock
may continue to show the existing session error supplied by the Electron
boundary; it does not add new logging or persistence.

Recovery recommendations remain user-selected. There is no automatic retry,
automatic player switch, persistent history, telemetry, or learning.

## Testing

Unit and component coverage will prove:

- external attempts stay visible and rerank without weakening inline
  engine-family exclusion;
- one handshake at a time, duplicate activation rejection, stable DOM keys,
  spinner/labels, and `aria-busy`/`aria-disabled` feedback;
- exact session-ID correlation, stale update/timeout rejection, session-key
  reset, close-before-switch, and unclosable-session failure;
- dock `launching`, `opened`, `playing`, `error`, close, and dismiss states;
- `ExternalPlaybackService` keeps errors visible until dismissal.

Electron E2E will extend the deterministic recovery fixture to assert that the
buttons remain after an MPV attempt, VLC is promoted, the lower dock shows
launch feedback, and an error remains dismissible. Existing playback fixtures
and player stubs must be used; no real playlist, account, or external process is
required.

## Documentation And Release Note

Update the canonical playback recovery architecture in
`docs/architecture/embedded-inline-playback.md`, the shared-player summary in
`AGENTS.md` and `CLAUDE.md`, and add a user-facing `fix(playback)` note under
`.changes/`.

## Out Of Scope

- proving playback for sessions that do not expose position polling;
- retry from the dock;
- retaining playback headers or credentials after the original request;
- automatic failover between MPV and VLC;
- redesigning the diagnostic overlay or dock.