feat(xtream): resume the latest series episode (#1187)

Dashboard Continue Watching now carries the exact saved season/episode into
Xtream series details and starts it at the persisted offset. Successful
external MPV/VLC launches persist the launched episode and retarget the
series CTA to "Play episode N". Recent-history rows keyed by an episode id
resolve their parent series before navigation.

Includes maintainer follow-ups: no zero-offset resume on failed position
loads, seriesXtreamId-gated resume targets for legacy rows, and patch
coverage raised from 76.7% to 93.9%.

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

docs/architecture/embedded-inline-playback.md

@@ -176,6 +176,13 @@ When a detail view starts playback:
 The detail or collection/search host owns inline state. `PlayerService` is not
 an owner of embedded UI playback state.
 
+After a successful external episode launch, the detail host immediately
+persists that episode as the latest playback-position entry, preserving an
+existing resume offset or using zero for a newly opened episode. MPV/VLC
+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.
+
 ## Series Quick Start CTA
 
 Xtream and Stalker series detail views share the quick-start decision helper in
@@ -189,6 +196,9 @@ Current contract:
   `S01E02 · Episode title`
 - if an episode is in progress, resume the latest updated in-progress episode
   with its saved offset
+- if the newest episode entry is a successful external-player launch marker
+  with no meaningful progress yet, target it with `Play episode N` instead of
+  falling back to the first episode
 - if no episode is in progress, play the first unwatched episode in season order
 - if watched episodes end at a season boundary, play the first episode of the
   next loaded season

docs/architecture/portal-detail-navigation.md

@@ -23,6 +23,12 @@ Related:
 - Dashboard `Global Favorites` and `Recently Watched` widgets hand off Xtream and
   Stalker movies/series into the matching global collection route with detail
   pre-opened.
+- Dashboard Continue Watching handoffs for Xtream series may additionally carry
+  a one-shot season/episode resume target. The collection-owned Xtream detail
+  consumes it after its episode positions load and starts that exact episode;
+  opening the series from the collection grid itself remains detail-only. If the
+  positions load fails, the target stays unconsumed and the handoff degrades to
+  detail-only rather than starting the episode at offset zero.
 - Do not force both portals into the same browse/detail behavior unless the full
   portal detail architecture is being changed.
 
@@ -73,6 +79,14 @@ Dashboard behavior to preserve:
   Xtream movie/series items into `/workspace/global-favorites` or
   `/workspace/global-recent` with collection detail pre-opened from navigation
   state.
+- When an Xtream series recent has a saved episode position, the dashboard hero
+  and Continue Watching card should include that exact series/episode target in
+  the navigation state. It is a one-shot playback request and must not leak into
+  normal favorites, search, category, or collection-grid navigation. Only
+  position rows that name their parent `seriesXtreamId` produce a target:
+  episode-keyed recents make `item.xtream_id` an episode id, so legacy rows
+  without the pointer stay detail-only instead of promoting the episode id to a
+  series id.
 - Back from the collection detail should return to the dashboard handoff state,
   not switch the active playlist.
 

docs/architecture/workspace-dashboard.md

@@ -97,6 +97,11 @@ Render rules:
        hero and cards can show progress, remaining time, and series season/
        episode badges. Series lookup uses keyed maps for both direct episode ids
        and series ids; card renders must not scan the full playback-position map.
+       Dashboard-originated Xtream series clicks also carry that exact episode
+       target through the global-recent inline-detail handoff. Once the series
+       metadata and playback positions load, the detail player consumes the
+       target once and resumes the saved episode. Opening the same item normally
+       from the global recent grid remains a detail-only action.
     3. `liveOnFavoritesCardsEnriched` — maps favorited live channels first,
        falling back to recently watched live channels when no live favorites
        exist. M3U cards carry an `epg_lookup_key` using the app-wide XMLTV
@@ -174,9 +179,12 @@ The welcome state is rendered via the existing
    rails have data.
 5. Navigation from a rail card must deep-link into the appropriate workspace
    route without switching the active playlist in the header switcher.
-6. `Recently Used Sources` reflects recent source usage across all provider
+6. Xtream series hero/Continue Watching clicks with a saved episode position
+   must resume that exact episode while preserving the collection-owned detail
+   and Back behavior. Do not apply autoplay to ordinary collection-grid clicks.
+7. `Recently Used Sources` reflects recent source usage across all provider
    types, not just recent imports.
-7. The live rail title key must match the rendered source: favorites use
+8. The live rail title key must match the rendered source: favorites use
    `WORKSPACE.DASHBOARD.LIVE_FAVORITES`; recently watched fallback uses
    `WORKSPACE.DASHBOARD.LIVE_RECENT`.