From 7987f976928e36f9d33a59e1711f207aed100999 Mon Sep 17 00:00:00 2001 From: 4gray Date: Fri, 31 Jul 2026 17:32:10 +0200 Subject: [PATCH] docs(downloads): clarify stalker provider fallback --- .changes/downloads-manager-mvp.md | 4 +-- CLAUDE.md | 12 ++++---- docs/architecture/download-manager.md | 11 ++++--- docs/architecture/portal-detail-navigation.md | 30 +++++++++++-------- docs/architecture/stalker-portal.md | 15 ++++++---- 5 files changed, 43 insertions(+), 29 deletions(-) diff --git a/.changes/downloads-manager-mvp.md b/.changes/downloads-manager-mvp.md index 6d0b75ca8..c6b89e963 100644 --- a/.changes/downloads-manager-mvp.md +++ b/.changes/downloads-manager-mvp.md @@ -5,5 +5,5 @@ area: downloads Downloads now open movies and series in focused offline details with saved metadata and optional TMDB enrichment. Series show only episodes available -locally, while View in portal opens the complete online catalog and provider -playback. +locally, while View in portal can return to the source portal for provider +playback when the source item can be recovered. diff --git a/CLAUDE.md b/CLAUDE.md index 9630dac95..f8b5c8d5d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -916,11 +916,13 @@ engine` (restart required) or fields. Legacy, sparse, stale, or wrong-language snapshots are safely backfilled from row/provider metadata and optional TMDB enrichment when the focused detail opens. -- `View in portal` resolves an exact source target and opens the provider's - normal detail in one-shot `provider-only` presentation. Provider playback and - the complete catalog remain available, while Offline/local/download actions - are hidden. This applies to Xtream movies/series and regular, embedded - `series[]`, and Ministra `is_series=1` Stalker flows. +- `View in portal` resolves a concrete Xtream category/item route. Stalker + preserves regular, embedded `series[]`, or Ministra `is_series=1` mode only + when a matching recently-viewed snapshot supplies that raw shape; otherwise + it navigates with an identity/title-derived regular VOD or series fallback + that is not existence-checked first. The normal detail uses one-shot + `provider-only` presentation: it exposes provider content/playback it can + resolve while hiding Offline/local/download actions. - If a finalized file disappears while a focused detail is open, the authoritative download list refreshes and returns to the manager. A failed redirect leaves an actionable missing-file state with Back and Retry. diff --git a/docs/architecture/download-manager.md b/docs/architecture/download-manager.md index 78117c502..29bd15974 100644 --- a/docs/architecture/download-manager.md +++ b/docs/architecture/download-manager.md @@ -114,10 +114,13 @@ variants, contextual buttons, and theme-aware styling. available, grouped into seasons; every episode Play and Show in folder action targets that row's local file. The provider's other seasons and episodes are deliberately absent from this view. -- `View in portal` resolves the exact Xtream or Stalker source item before the - action becomes available. It then leaves the offline view and opens the - provider's normal detail host in explicit `provider-only` presentation: the - complete online catalog and provider playback remain available, while local, +- `View in portal` resolves an exact category/item route for Xtream. For + Stalker it preserves the raw mode and item shape when a matching + recently-viewed snapshot is available; otherwise it builds a regular VOD or + series target from the persisted identity and title without first proving + that the provider still serves it. The handoff opens the normal provider + detail host in explicit `provider-only` presentation: provider content and + playback remain available when that host resolves them, while local, Offline, and download actions are hidden. Regular provider navigation does not inherit this one-shot presentation state. - A completed row that is no longer locally available is never rendered as a diff --git a/docs/architecture/portal-detail-navigation.md b/docs/architecture/portal-detail-navigation.md index 863781a95..e65feafe7 100644 --- a/docs/architecture/portal-detail-navigation.md +++ b/docs/architecture/portal-detail-navigation.md @@ -34,10 +34,11 @@ Related: context panel, play only finalized local files, and show only locally available episodes for a series. - `View in portal` is the explicit bridge from a focused offline detail to the - source catalog. It resolves an exact provider target and passes the one-shot - `detailPresentation: 'provider-only'` navigation state. The destination keeps - provider playback and the complete provider episode catalog, but hides - Offline/local/download presentation. + source catalog. Xtream resolves a concrete category/item route; Stalker uses + the best stored item shape or an identity/title-derived fallback. Both pass + the one-shot `detailPresentation: 'provider-only'` navigation state. The + destination keeps provider playback and whatever catalog the normal provider + host can resolve, but hides Offline/local/download presentation. - Do not force both portals into the same browse/detail behavior unless the full portal detail architecture is being changed. @@ -159,15 +160,18 @@ Behavior to preserve: Download handoff behavior: -- `View in portal` preserves Stalker's inline/store-state architecture. The - download target carries `openStalkerItem` into the normal VOD or series - category host instead of inventing a canonical item route. -- The provider-only marker follows the exact selected item through regular - series, embedded VOD `series[]`, and lazy Ministra VOD `is_series=1` flows. - All provider seasons/episodes and provider playback remain available, while - the shared VOD or series UI suppresses local Offline and download controls. - Consuming the marker is identity-scoped so a later ordinary item open returns - to normal provider presentation. +- `View in portal` preserves Stalker's inline/store-state architecture. A + matching recently-viewed snapshot is carried as `openStalkerItem` into the + normal category host, preserving regular series, embedded VOD `series[]`, or + lazy Ministra VOD `is_series=1` shape when that raw snapshot exists. +- When no matching snapshot exists, a movie download falls back to a regular + VOD item and an episode download to a regular-series item derived from the + persisted provider identity and title. This fallback is not existence-checked + before navigation and cannot reconstruct embedded or `is_series=1` mode. +- The provider-only marker is scoped to the resulting selected item. Its normal + provider host supplies the seasons, episodes, and playback it can resolve, + while the shared VOD or series UI suppresses local Offline and download + controls. A later ordinary item open returns to normal provider presentation. ## Decision Rule For Future Changes diff --git a/docs/architecture/stalker-portal.md b/docs/architecture/stalker-portal.md index 90ff6ae91..4f96eb2fa 100644 --- a/docs/architecture/stalker-portal.md +++ b/docs/architecture/stalker-portal.md @@ -368,11 +368,16 @@ The VOD-series contract is cross-surface: provider category in a versioned offline snapshot. The focused Download Manager detail uses only locally available episode rows; it does not reuse the provider season resource as an offline availability list. -- `View in portal` hands the stored Stalker identity back to the normal - category/inline detail host with identity-scoped provider-only presentation. - All three series modes retain their complete provider seasons, episodes, and - provider playback, while Offline/local/download controls stay hidden for - that handoff. A normal Stalker item open remains unchanged. +- `View in portal` first looks for a matching recently-viewed Stalker snapshot. + When found, it hands the raw shape to the normal category/inline detail host, + so regular series, embedded `series[]`, and lazy `is_series=1` mode are + preserved with identity-scoped provider-only presentation. +- Without that matching snapshot, the episode download supplies only persisted + identity/title metadata and falls back to a regular-series item. The fallback + is not existence-checked before navigation and cannot reconstruct embedded or + `is_series=1` mode. In either path, the provider host renders whatever + seasons, episodes, and playback it can resolve while Offline/local/download + controls stay hidden. A normal Stalker item open remains unchanged. Core decision logic and normalization are centralized in: