iptvnator/docs/architecture/download-manager.md

# Download Manager Architecture

The download manager is a desktop-only feature that layers a curated queue,
progress tracking, storage configuration, and playback controls on top of the
existing Xtream (`libs/portal/xtream`) + Stalker (`libs/portal/stalker`) portal
views. Backend work is handled in the Electron process while the Angular
renderer exposes the global `/workspace/downloads` page, source-scoped route
variants, contextual buttons, and theme-aware styling.

## Xtream archive downloads

The desktop Xtream Live TV programme dialog offers **Download programme (TS)**
for completed, available catch-up programmes in both timeline and list views.
The host captures the playlist, channel and original programme timestamps before
resolving the existing timeshift URL (including the panel timezone). A channel
change while the dialog is open invalidates its action. Downloading does not
select the programme or change playback. Collection views retain archive URL
copying; archive downloads are initially exposed through Xtream Live TV only.
M3U, Stalker and PWA archive downloads, HLS assembly and recording future broadcasts
are outside this feature.

`EpgArchiveDownloadService` submits the resolved URL and the playlist's playback
header allowlist to the existing desktop queue. Pending submission suppression
is per programme identity, so slow resolution does not discard a different
programme's request. HLS URLs are refused explicitly;
the backend also checks the response type and every 188-byte MPEG-TS packet.
No transcoder or media helper is required. The file always uses `.ts`.

The `catchup` download type stores `programme_start` and JSON metadata containing
channel name, start/stop Unix seconds and the known archive expiry. Its unique
identity is `(playlist_id, xtream_id, programme_start)`; movies and episodes keep
their existing identity. `download-schema.ts` widens the SQLite CHECK in a
transaction after older additive migrations, preserving row IDs, files, headers,
resume state and metadata. It also replaces the former global unique index with
separate catch-up and non-catch-up indexes.

Only ended programmes can be enqueued. Known expiry is checked on enqueue,
retry, resume, missing-file recovery and when the queued transfer starts.
Pause keeps its owned partial file, but **resume/retry restarts from byte zero**,
without Range, If-Range, or automatic reconnect append. The queue explains this.
Before truncating, `download-catchup-output.ts` rejects symlinks and hardlinks,
opens without truncation (with O_NOFOLLOW where available), checks descriptor
identity against lstat, then truncates and writes through that same descriptor.
An absent partial is created exclusively, so a replaced path cannot redirect writes.
The task retains that descriptor's device/inode identity through promotion:
`download-catchup-finalize.ts` verifies the source and published file, rejects a
replaced partial, and copies from the verified descriptor on filesystems without
hardlinks. Existing destination files are never overwritten. Cleanup atomically
moves the public pathname into a private temporary directory before checking its
identity and removing it. A captured replacement is restored with no-clobber
linking; if restoration is unavailable or the original pathname is occupied,
the file is retained in `.iptvnator-cleanup-*/entry` and its recovery location
is logged. Cleanup never recursively deletes a nonempty quarantine. This closes
the predictable-path check/unlink window; it does not isolate files from
same-user processes that deliberately enter the private temporary directory.
Active failure and cancellation use the same captured transfer identity; a
partial that was never safely opened is preserved instead of being deleted.
`download_archive_finalizations` is a write-ahead SQLite journal keyed by download
ID (cascade-deleted with the download). It records the path, size, source identity
and expected final identity **before hardlink promotion**, or before the first
byte is written to an exclusively created copy destination. Thus even a completed
unknown-length file has durable proof before the completion-status write. Startup
requires that proof and a matching regular file, identity and size to recover an
archive; termination before promotion leaves the verified partial paused. An
owned incomplete copy is removed by journal identity before the source resumes. The
journal also makes startup partial cleanup identity-aware. A journaled partial
whose identity changed is preserved and detached from the failed row; Retry
reserves a fresh path instead of adopting or truncating it. The journal remains with
completed archives until they are removed. An explicitly restarted transfer
carries the journaled source identity to output opening and checks
it against the opened descriptor. Only then does it replace the previous proof,
before truncation or writes, replacing the old finalization proof with a
transfer-phase journal containing the newly opened identity. That identity
survives pause, failure and restart without claiming the file is complete. A
rejected replacement is detached from the failed row without deletion, so Retry
reserves a new path. Retained catch-up paths without any durable proof are also
preserved and redirected to a fresh reservation. On a final-path collision,
archives never relocate a retained partial: only a verified owned partial is
discarded before reserving a new filename, because archive retries restart at zero. The transfer proof is upgraded to finalization proof only
after validated EOF. Process-local proof allows immediate
recovery after a transient completion DB error without waiting for a restart.
Fallback copying observes pause/cancel between bounded 64 KiB reads/writes and
before publication completes. Interruption removes only the owned copy and
leaves the source for the runtime pause/cancel handler. Once publication identity
and size pass the final check, the task synchronously enters completion commit
before awaited partial cleanup and the SQLite completion write. Pause/cancel then
return false without setting flags; a command is never accepted and subsequently
overwritten by completion. Remove rejects this committing row before partial
cleanup or deletion, and Clear completed skips it, preserving the cascading
journal until completion finishes. Remove waits for an accepted active archive
cancellation to settle before reading/deleting its row; queued archives are
canceled first, and a concurrent new runtime attempt blocks removal. A settled
archive still marked downloading after a failed status write also retries
journal cleanup before row deletion. Remove/Clear preserve a final file whose
journaled device/inode/creation-time identity and full size prove completed promotion, even when completion
status writes failed and its stored status is stale. Repeat submissions, Retry
and Resume restore such a journal-proven completion in place before any new
transfer or ownership reset, before expiry, provider DNS and new-folder checks
that apply only to another remote transfer; retained cleanup failures keep their
journal. Remove, Clear completed and missing-file
re-download and repeated programme submissions use journal-backed private
capture for archive partial cleanup;
unknown or replaced entries are preserved. Ownership reads device/inode as BigInt and journals decimal strings without
losing 64-bit Windows file references, alongside a positive file creation timestamp, so inode reuse after unlink cannot
bless a new entry; proofs lacking creation time remain untrusted. Fresh
reservations capture this identity from their exclusive creation descriptor and
commit it together with the downloads row path/name in one SQLite transaction
before the HTTP wait. A committed reservation is therefore recoverable even if
the process exits before transfer setup. Existing partials without matching expected
ownership are never truncated, including before the first response. Before capture, a synchronous SQLite
write records `partialCleanupPath` (or `finalCleanupPath` for failed promotion)
in the existing ownership proof. Active cancellation/failure, promotion and
startup recovery use the same journal-backed cleanup as manual actions. Cancel,
failure and removal of an unfinished attempt also clean its journaled final target;
removing a completed row preserves its media. Retry cleans an incomplete owned
final before reserving a destination. A failed
unlink or replacement restoration keeps that durable pointer and blocks journal
deletion/replacement. Later cleanup retries no-clobber restoration of captured
foreign entries; an occupied public path or unsupported hardlinks preserves both
the capture and its journal for recovery. Even after a foreign entry is restored,
its private recovery copy is never automatically unlinked: another process could
remove the public link first. Remove/Clear return a structured recovery path and open a persistent, localized
dialog with the full path, Copy recovery path and manual recovery instructions.
Copy keeps the dialog open, including on clipboard failure; Close dismisses it.
After the user recovers it and explicitly removes that private copy, cleanup may release the
journal. Ordinary owned-file cleanup remains automatic. Remove/Clear, Retry/Resume and fresh
reservations retry identity-verified cleanup, including after restart and on
filesystems without hardlinks. Cleanup remains synchronous after the
runtime guard, so a completion transition cannot interleave with unlink.
Missing archive re-downloads claim a fresh reservation instead of inheriting the
completed file's identity.
If the initial reservation journal write fails, persistence is retried once
before journal-backed cleanup. If SQLite remains unavailable, the empty
reservation stays at its public path; no unjournaled entry is relocated. An
empty fallback-copy target whose final proof cannot commit is likewise preserved.
A kill between exclusive reservation/copy-file creation and its identity journal
commit, or persistent SQLite failure before that commit, can leave an unowned
**empty** destination: no bytes are written before the commit.
Recovery preserves that file rather than guessing ownership; Retry uses a
numbered free destination. SQLite and filesystem creation cannot commit
atomically, and portable rename cannot guarantee no-clobber publication on the
filesystems that need this fallback. This bounded orphan is preferred to deleting
or overwriting an unrelated file.
Cancellation of queued/paused archives uses the same journal-backed cleanup as
Remove; unproven or replaced entries, including symlinks, are preserved.
A retained archive cannot use the VOD byte-count completion shortcut. Transfers
have a 30-second idle timeout and a total deadline of twice programme duration
plus ten minutes, capped at 24 hours. Transfers also stop at the smallest of a
100 Mbit/s budget for the programme duration plus one minute, 64 GiB, and
half of the initial available space after subtracting a 1 GiB reserve (reserving a second
copy for filesystems without hardlinks). The retained partial is safely truncated
through its verified descriptor before computing this budget, so Resume/Retry
can reuse its released space. Known Content-Length values above
that budget are rejected before writing; unknown-length responses are counted
before forwarding chunks. Free space is rechecked every 16 MiB to account for
other disk activity, and copy headroom is checked again against the final byte
count after the output stream closes, including short tails below that interval. These safety limits apply to TS archives only. Failure never promotes the partial to the
library, and errors omit credential-bearing URLs.

Completion means clean HTTP EOF, matching Content-Length when supplied, and
valid nonempty TS packet framing. **It does not verify media duration or the
provider's programme boundaries.** A provider can return a shorter valid clip
with clean EOF; this version cannot identify that without demuxing duration.
Unknown-length responses show indeterminate progress until EOF.

Completed archive cards appear under All with programme title, channel and
broadcast date. Clicking a card plays the local file through the download action;
it does not navigate to a movie or series detail route. Files and metadata remain
available after restart and after the source archive expires.

## Backend responsibilities

- **Queue control (`apps/electron-backend/src/app/events/database/download-runtime.ts`)**
  `DownloadTask` mirrors a row of the shared `downloads` table (type `Download` in `libs/shared/database/src/lib/schema.ts`) plus transient cancel/pause/progress helpers (shared task types live in `download-task.ts`). Request validation and row creation live in `download-requests.ts`, retry/resume flows in `download-resume-requests.ts`, removal/terminal cleanup in
  `download-removal-requests.ts`, while `downloads.events.ts` stays focused on IPC registration. `enqueueDownload()` pushes the task onto `downloadQueue` and triggers `processQueue()`. `processQueue()` keeps one active download, updates the row to `downloading`, and calls `startDownload()`. The byte transfer itself lives in `download-transfer.ts`, finalization and retained-partial persistence in `download-finalize.ts` (ordinary file promotion in `download-file-finalize.ts`, archive completion in
  `download-catchup-completion.ts`, proven completion recovery in `download-catchup-recover-completion.ts`, target reservation in `download-runtime-reservation.ts`), cancellation/pause persistence in `download-runtime-persistence.ts`, and the renderer update broadcast in `download-broadcast.ts`.
- **Range-aware transfer (`download-transfer.ts`)**
  The transfer streams the response through the backend's validated Axios redirect helper instead of `electron-dl`, and always requests `Accept-Encoding: identity`: Range offsets, totals, and the persisted `.part` must describe the same representation, and Axios's transparent gzip/brotli decoding would put decoded bytes on disk while every counter speaks encoded bytes. Headers (user agent, referer, origin) are persisted in `request_headers` and re-applied through the same allowlist when read back on retry/resume. Fresh Xtream movie and series-episode downloads propagate the playlist's configured headers, using its User-Agent when present and otherwise sharing the provider-compatible `XTREAM_CLIENT_USER_AGENT` used by Xtream API requests and stream probes. Retry, resume, and missing-file recovery resolve the owning playlist type and add that fallback to legacy Xtream rows without a stored User-Agent; known Stalker rows are left unchanged. Download rows deliberately outlive individually deleted playlists, so a headerless legacy row whose source no longer exists receives the same IPTV-player fallback because its original provider type cannot be recovered. Active pause/cancel operations abort the current request with `AbortController`; pause keeps the partial file and cancel removes it. Resume checks the existing `.part` size (rejecting anything that is not a regular file, so a symlink planted while paused is never followed). The first response's strong `ETag` (or `Last-Modified`) is persisted in `resume_validator`; a partial carrying that validator resumes with `Range: bytes=<offset>-` plus `If-Range`, so the server itself proves the entity is unchanged. A retained partial **without** a validator resumes through overlap verification instead (`download-overlap.ts`): the `Range` request rewinds by up to 256 KiB (`OVERLAP_VERIFICATION_BYTES`) and a transform stream compares that replayed window byte-for-byte against the partial's tail before anything is appended — a self-made validator for the many Xtream panels that send neither header. A mismatching overlap truncates the `.part` and restarts the transfer from byte zero (`OverlapMismatchError`); a partial smaller than the overlap window is verified in full from byte zero over a plain request and appended to — never rewritten in place, so a reconnect that dies early can only grow the file. Success requires the verifier to have consumed its ENTIRE window: a response that ends inside the overlap is an ordinary retained interruption when the stream died early, but a response that delivered its complete AUTHORITATIVE total inside the window — whether it then closed cleanly or reset — proves the remote entity shrank and restarts from scratch; the old suffix is never finalized as a completed file. An HTTP 416 answer to a resume request is classified by `classifyRangeNotSatisfiable()`: it COMPLETES only an exact-EOF request with identity proof (`If-Range`-backed, or the EOF probe that follows a fully verified overlap replay) whose stated `bytes */N` equals the partial — a bare length match on a rewound request proves nothing about whose bytes are on disk; it RESTARTS only when a STATED total proves the entity shrank — the total sits below a rewound request's first byte, or at it (the rewound range beginning exactly at the new EOF), or below the partial at an exact-EOF request; every length-less, ambiguous, or contradictory 416 RETAINS the partial, and none of these paths ever reaches generic cleanup. A validator promoted by a complete overlap match survives mid-append failures too: the promotion also runs on the error path, and retained-failure and pause persistence write `resume_validator` from the task, so later attempts resume via `If-Range` instead of replaying the window — without this, a server whose per-connection cap barely exceeds the window would stall out on sub-threshold progress. A verify-append attempt promotes the response's `ETag`/`Last-Modified` onto the row only after the complete overlap matched; until then the retained bytes are unproven and blessing them with a validator would let the next resume `If-Range`-append onto a foreign prefix. The response's TOTAL stays equally uncommitted (task and row) until the overlap matched — a persisted total equal to the unverified partial's size would let the completed-partial shortcut finalize unproven bytes after a pause, crash, or retained failure. Retained-interruption persistence keeps the live task in sync with the row (a stale falsified total would make the next reconnect's resume-offset guard reject the partial). Overlap replay re-counts bytes from the rewound offset, so reported progress is floored at the partial's retained size whenever the transfer appends — a response that ends inside the overlap can never move displayed progress backwards. A `206 Partial Content` answer must start at the requested offset (`Content-Range` is verified) before bytes are appended; any other 2xx answer — the server ignoring `Range`, or `If-Range` detecting that the remote file changed — restarts the transfer from byte zero over the same `.part` instead of failing the download.
- **Destination collision policy**
  Existing destination files are never overwritten, inspected, or deleted.
  Before starting a new transfer, the backend atomically reserves a free
  numbered `.part` path while leaving the final destination path absent. The
  selected final `filePath` and `fileName` are persisted before transfer
  begins. When a retained download's recorded destination got occupied while
  it was paused or failed (for example by a file the user created), the
  retained `.part` is renamed aside and finalized to the next free numbered
  destination (`Movie (1).mp4`) instead of resolving the collision by size or
  `unlink()`. Completion creates the final `filePath` from the `.part` without
  overwriting an existing file; cancel and non-recoverable transfer failures
  remove the `.part`, while finalization failures, completed-partial failures,
  and allowlisted network interruptions after bytes reached disk deliberately
  retain it (the row keeps `filePath` so a later retry can finish without
  re-downloading); pause and restart recovery keep partials. A retry resumes
  through If-Range when a validator was stored and through overlap
  verification otherwise.
  Re-downloading such a failed row from a detail page
  (`DOWNLOADS_START`) deletes the retained `.part` before the row is reset.
- **Derived file readiness and recovery**
  `DOWNLOADS_GET_LIST` and `DOWNLOADS_GET` inspect completed destinations on
  every read. Only regular, non-symbolic-link files are reported as available;
  missing paths, directories, symlinks, and inspection errors are reported as
  missing without changing the persisted `completed` transfer status.
  `DOWNLOADS_REDOWNLOAD_MISSING` accepts only the managed row id, rechecks the
  file, and returns a recovered result without network access when it has
  reappeared. Otherwise it conditionally claims the completed row, preserves
  its owned destination, re-applies the stored header allowlist and URL safety
  policy, and enqueues a fresh transfer without overwriting an existing file.
- **IPC surface**  
  The backend exposes `DOWNLOADS_*` handlers for list retrieval,
  start/pause/resume/cancel/retry/missing-file recovery/remove operations,
  folder selection/reveal, and the `DOWNLOADS_UPDATE_EVENT` emitter that the
  renderer listens to in order to refresh its signal store.

## Renderer architecture

- **Downloads service** (`libs/services/src/lib/downloads.service.ts`)
  `DownloadsService.downloads` is the renderer's authoritative **global** list.
  `loadDownloads()` therefore always invokes the Electron list IPC without its
  legacy optional playlist scope. Route scope, category, and search must never
  replace or narrow that signal. Loads are serialized: at most one list IPC is
  active, and callers arriving during it coalesce behind one trailing refresh.
  Each response therefore commits in request order. A caller assigned to the
  trailing refresh resolves after that refresh settles even when later
  broadcasts queue the following refresh, preventing both stale continuation
  and starvation during frequent progress updates.
  `hasLoadedDownloads` records that the latest attempt completed, including an
  error, while
  `hasAuthoritativeDownloadList` becomes true after a successful request,
  remains true while a later refresh is in flight, and clears only if the
  latest request fails. Series download actions require both loaded and
  authoritative state so a failed refresh cannot restart rows missing from a
  stale or empty renderer snapshot. Before each fresh download or resume the
  service asks the main process for an authorized folder and calls the
  corresponding IPC command. The `onDownloadsUpdate` broadcast triggers a new
  global load.
- **Series season queueing**
  `SeasonDownloadCoordinator` owns synchronous, per-identity pending
  reservations and submits an individual episode or selected-season snapshot
  through `DownloadsService.startDownload()`. Season batches are sequential
  and best-effort: one candidate failing does not stop later candidates. After
  added or stable duplicate submissions, one authoritative list refresh closes
  the pending-to-queued/downloaded handoff, and the coordinator returns
  `added`, `skipped`, and `failed` counts. Xtream and Stalker adapters own
  provider URL, request header, and metadata preparation; the coordinator owns
  only provider-neutral orchestration. When a reserved candidate matches a
  completed-missing row, the coordinator performs one authoritative preflight
  refresh before any provider preparation. If another list request is active,
  the preflight joins the single trailing refresh; later download-update
  broadcasts cannot delay that assigned refresh. Restored files therefore
  become stable skips without requiring a Stalker URL/network request. Both
  providers use normalized `episode.id` as the canonical
  episode `xtreamId`; Stalker `originalCmd` and `originalId` participate only
  in URL resolution. Provider adapters preserve numeric season zero, including
  a fallback season key of `"0"`, so Specials keep distinct `S00` coordinates.
  The exact `(playlistId, contentType, xtreamId)` identity is authoritative.
  Complete `(playlistId, seriesXtreamId, seasonNumber, episodeNumber)`
  coordinates are a legacy episode-compatibility fallback. Stalker also stores
  an `episode_identity_scope` for regular `/series`, embedded VOD `series[]`,
  and lazy Ministra VOD `is_series` origins. A known different scope is a
  different episode owner; an older coordinate row without a provable scope
  fails closed instead of being migrated across modes. Exact canonical legacy
  rows remain authoritative. Other ambiguous or conflicting matches resolve to
  the same explicit renderer conflict state rather than masquerading as a
  missing row, so both the episode action and season count fail closed.
  SQLite `null` and optional `undefined` coordinates both mean that a canonical
  legacy row is incomplete, matching the backend resolver. Renderer-pending,
  queued, downloading, and paused episodes are skipped, as are completed rows
  whose file is available or whose availability is still unknown. Failed,
  canceled, completed-missing, and unambiguous row-less episodes are eligible;
  a completed-missing row is restarted as a fresh download. Before resetting
  such a completed row, `DOWNLOADS_START` asynchronously rechecks its retained
  path in the main process. A restored file returns stable
  `reason: 'already-downloaded'` without mutation; active matches return
  `reason: 'already-in-progress'`. The recheck has a one-second caller deadline
  that starts before shared-slot acquisition; timeout or probe failure leaves
  the row untouched and returns a failed submission, allowing the sequential
  season loop to continue. Completed-file list callers have the same deadline
  and report a timeout as missing for that snapshot. The underlying filesystem
  operation remains coalesced and charged against the four-probe cap until it
  actually settles, so later callers get independent bounded waits without
  duplicating stalled native work. Only `ENOENT` and `ENOTDIR` are authoritative
  absence; permission, I/O, and other probe errors remain unknown, so
  `DOWNLOADS_START` leaves the completed row and file path untouched. Before a
  completed-missing, failed, or canceled row clears its path, the same start IPC
  asynchronously removes any retained `.part`. Cleanup coalesces same-path work
  and allows at most four underlying unlinks. A one-second admission deadline
  rejects queued work before it can mutate the filesystem; once an unlink
  starts, the request awaits its authoritative result so no late side effect can
  race a retry. Permission and I/O failures keep the row's ownership intact,
  while `ENOENT` and `ENOTDIR` safely proceed. The coordinator counts both stable
  duplicate reasons as skipped. There is no batch IPC,
  parallel transfer, or queue reordering: destination authorization, persisted
  header handling, and the backend's one-active-transfer FIFO semantics remain
  unchanged.
- **Pure manager model**
  (`download-manager.viewmodel.ts` and `download-library.viewmodel.ts`)
  derives the current route scope, search/category filtering, queue partitions,
  stable ordering, counts, and tracked byte total without mutating service
  state. `queued`, `downloading`, and `paused` rows form the active surface;
  `failed` and `canceled` rows form the attention surface. A `completed` row
  whose derived file availability is missing also enters attention with a
  dedicated recovery reason; only available completed rows enter the offline
  library. Completed episodes with a valid
  `seriesXtreamId` are grouped by `(playlistId, seriesXtreamId)`, ordered by
  season and episode, and represented by one poster card. Episodes without a
  usable series id remain standalone cards so they never disappear.
- **Downloads workspace** (`libs/portal/downloads/feature`)
  keeps orchestration in `DownloadsComponent`, async mutations in the
  component-scoped `DownloadManagerActionsService`, source-route resolution in
  `DownloadLibraryNavigationService`, and rendering in the presentational
  `DownloadQueueComponent`, `DownloadLibraryComponent`, and
  `DownloadedSeriesDialogComponent`. Presentational children emit typed
  `DownloadItemAction` values and do not inject the download service, router,
  dialogs, or snackbars.
  The fixed header and filter row sit above one vertical scroll owner. The
  queue and library sections share one heading treatment (the dashboard-rail
  title style with an `.app-count-badge` item count) so same-level sections
  read alike; the queue's bordered panel wraps only the row list. Queue rows
  expose exactly one visible primary action — pause, resume, or retry — while
  cancel, copy-URL, and remove live in the row's overflow menu, so two
  adjacent destructive icons never compete. Completed movies
  and grouped series reuse the portal's canonical content grid as compact
  poster cards borrowed from the dashboard-rail card language: a type badge
  and an always-visible ⋮ trigger sit on the artwork, the title and series
  facts sit below it, and Play / Show in folder / Copy URL / Remove live in
  that overflow menu. File size is not repeated on the card; it belongs to the
  focused offline detail. Both completed
  cards and their loading skeleton consume the global
  `--cover-grid-min-width` / `--cover-gap` tokens, so the Small, Medium, and
  Large cover preference behaves like it does elsewhere in the app. All
  surfaces use the existing `--app-*` and Material system tokens. Ready cards
  do not repeat an Offline badge; source provenance is available at the top of
  their overflow menus. The global
  workspace download shortcut displays the service's active count, while the
  page badge and filter counts reflect the current route scope.
- **Honest interactions**
  Every asynchronous item command owns a pending id until the IPC result
  settles, preventing duplicate dispatch without optimistically changing a
  status. Service failures surface through the established snackbar path.
  Removing a completed entry explicitly says the finalized media file remains
  on disk. Removing a paused, failed, or canceled entry says retained partial
  data is deleted. “Clear finished” communicates both outcomes and preserves
  playlist scope when the page is opened under a source route. VOD and episode
  detail views continue to render a paused download as an active Resume button
  (`DownloadsService.isPaused()` / `resumeDownloadByContent()`). Artwork and
  titles on every completed card — movie, grouped series, and standalone
  episode alike — open the focused offline detail for that download; the
  explicit Play command in the poster's overflow menu still starts the local
  file directly. A legacy standalone episode without a usable series id
  resolves to a single-episode offline detail built from its own row.
  Missing completed rows show `File missing` under Needs attention with
  `Download again`; Play and Show in folder are withheld. A file-action race
  that returns `File not found` refreshes the authoritative list and returns
  the user from focused details to the manager.

## Focused offline details

- Ready movies and grouped series open a local-focused detail view rather than
  a provider catalog page. A movie exposes local Play and Show in folder. A
  series projects only completed episode rows whose finalized files are still
  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 an exact category/item route for Xtream. For
  Stalker it accepts a matching recently-viewed snapshot only when its raw
  movie/regular-series/VOD-series markers agree with the download type, so
  overlapping movie and series ids cannot select the wrong item. An exact
  numeric category stored in the download snapshot wins over the recent
  collection's virtual `vod`/`series` category. Without a matching recent
  shape, only a movie with that exact numeric category can form a
  metadata-only target; episodes and legacy movies without one leave the
  handoff unavailable. The normal provider detail opens in one-shot
  `provider-only` presentation: provider content and playback remain available
  when that host resolves them, while local, Offline, and download actions are
  hidden.
- A completed row that is no longer locally available is never rendered as a
  ready offline detail. Direct or stale detail URLs return to the manager; if
  navigation fails, the detail shell shows the missing-file error with Back and
  Retry. Invalid or removed download ids render a focused not-found state.
- Movie and episode downloads capture a versioned, display-only metadata
  snapshot at start time from the already-rendered Xtream or Stalker detail,
  including any TMDB fields already present. The snapshot keeps provider
  identity/category separately from presentation metadata and lets the offline
  view render even when the source portal is unavailable.
- A grouped series selects its newest valid parent snapshot, then fills only
  missing parent metadata from older valid member snapshots. Newer values,
  per-episode metadata, language, and freshness identity remain authoritative.
  Each episode row still uses its own stored episode metadata.
- Legacy rows and sparse, stale, or wrong-language snapshots are backfilled
  when focused details open: row metadata supplies a safe local fallback,
  provider data is merged when it can be resolved, and opt-in TMDB enrichment
  uses the same app language and merge rules as provider details. Successful
  refreshes persist to the representative row; transient failures keep safe
  improvements without falsely marking the snapshot fresh, and concurrent
  refreshes are request-ordered so only the latest generation may write.
- Snapshot artwork accepts only safe HTTP(S) image URLs. Renderer normalization
  and main-process persistence independently reject credential-shaped path and
  query keys, including `username`, so provider credentials cannot be cached in
  offline metadata.

## Global API surface

- **Preload + types**  
  `apps/electron-backend/src/app/api/main.preload.ts` wires every download IPC command plus the `onDownloadsUpdate` listener to `window.electron`. The shared `ElectronBridgeApi` contract in `libs/shared/interfaces/src/lib/electron-api.interface.ts` owns the download and playback-position method types; `global.d.ts` and `apps/web/src/typings.d.ts` reference that contract instead of redeclaring the bridge.

## Routing and navigation

- The global workspace is `/workspace/downloads`. Source-scoped variants are
  available under both portal flavors:
  `/workspace/xtreams/:id/downloads` and
  `/workspace/stalker/:id/downloads`. All three routes render the same global
  store; the `:id` routes derive a view-only playlist scope.
- Each scope exposes the same focused child route:
  `/workspace/downloads/:downloadId`,
  `/workspace/xtreams/:id/downloads/:downloadId`, and
  `/workspace/stalker/:id/downloads/:downloadId`. The workspace shell treats
  all three as focused content: route search is disabled and the context panel
  is `none`, so provider categories are not shown beside a local-only item.
- The manager persists its selected All/Movies/Series/In progress filter in
  the current route query with `replaceUrl`. Opening a focused item then keeps
  that exact scoped URL as its validated return target, so Back restores the
  manager's scope, search query, filter, and browser-history position.
- Downloads navigation is data-driven: `libs/portal/shared/util/src/lib/navigation/portal-rail-links.ts` emits a `downloads` section link (`path: [...root, 'downloads']`) for both portals, so they reuse the same download page.

## Queuing, persistence, and UX notes

- Every download row writes to the shared `downloads` table with statuses (`queued`, `downloading`, `paused`, `completed`, `failed`, `canceled`) plus metadata such as `bytesDownloaded`, `totalBytes`, `errorMessage`, `requestHeaders`, `resumeValidator`, the offline-detail metadata snapshot, and Xtream identifiers. Downloads are locally owned records rather than playlist children: deleting a source retains its rows and local files, keeps them visible in the global library, and disables provider handoff until that source exists again. Startup rebuilds older tables that still carry the playlist foreign key, while additive columns use the idempotent column migrations.
- Download-list and focused-detail reads verify completed files with asynchronous `lstat` probes in the main process. One shared probe queue permits at most four filesystem calls at once and coalesces only in-flight checks for the same path; it does not cache completed results, so external file deletion is visible on the next refresh without letting frequent progress broadcasts block Electron's main thread.
- On startup, `download-recovery.ts` converts stale `downloading` rows with a non-empty `.part` file to `paused`, converts stale `queued` rows to `paused` while keeping any retained `.part` (a resumed download waiting behind an active one persists as `queued` with its partial), and marks stale `downloading` rows without recoverable partial bytes as `failed`.
- Queue cancellation removes a queued task or records an active cancellation request and aborts the request when available. Pausing follows the same abort path but persists `paused` and keeps the `.part`. Retries reuse the same database entry: a failed row with a retained `filePath` resumes its `.part` through HTTP Range, otherwise the retry starts from zero. Resume appends to the existing `.part` through HTTP Range with `If-Range` validation when a validator is stored, and through 256 KiB overlap verification when none is.
- A `.part` that cannot be deleted (locked, permission denied) never loses its database path: cancel persists `canceled` while retaining `filePath` for later cleanup, and `DOWNLOADS_REMOVE` keeps the row and answers `success: false` (surfaced as a snackbar) so retrying the remove re-attempts the deletion once the lock is released.
- Resume claims the row atomically (`paused` → `queued` as a conditional update) and the runtime queue rejects duplicate ids, so two rapid Resume clicks racing the status refresh can never produce two transfers for the same download.
- A response that ends cleanly before the advertised representation size (for example a proxy that caps each response) is never committed as completed: the transfer fails with `Transfer ended before the advertised size` while retaining the `.part` and `filePath`, so a retry continues via Range from where it stopped.
- An allowlisted network failure retains ANY nonempty `.part`: since overlap verification owns resume correctness, the next attempt can safely prove, resume, or restart over whatever was retained — deleting bytes is the only unrecoverable outcome, so retention needs no total, validator, or range evidence. A total the bytes on disk have falsified is persisted as unknown, never as the falsified value. The failed row exposes a stable `DOWNLOAD_NETWORK_INTERRUPTED (<code>)` message without a URL; Retry continues through the same resume validation. Only non-network errors, empty fresh failures, and a partial that shrank mid-attempt keep the generic failure path.
- The runtime reconnects interrupted transfers on its own (`download-reconnect.ts`, wrapping the transfer in `startDownload`): a recoverable interruption or clean short response triggers an automatic reconnect after a 1 s delay, because servers that cap each connection at N bytes or seconds — common Xtream anti-download throttling — would otherwise demand a manual Retry click per ~130 MB slice. The loop is structurally bounded: an attempt must end at least 64 KiB past the previous attempt to reset the stall budget, and three consecutive attempts without that progress surface the last interruption as the ordinary retained failure. Restarts are an EXPLICIT signal, never byte inference: the transfer layer increments `task.transferRestarts` whenever it rewrites the `.part` from byte zero (overlap mismatch, shrunk entity, HTTP 416, or a server that ignored `Range`), and the loop opens a fresh progress epoch on that signal — clean stall budget, no baseline — because a rebuilt file that happens to land near the previous attempt's byte count is indistinguishable from a stall by byte comparison alone. Only two restarts are tolerated per transfer, or an always-restarting server would reset the budget forever; an unsignalled byte regression is an ordinary stall. Cancel and pause are re-checked around every reconnect. A reconnect attempt that fails before any response (for example `ECONNREFUSED` against a rebooting panel) is converted into the same retained interruption instead of falling into the generic partial-deleting failure path, so an automatic reconnect can never destroy a multi-gigabyte partial the user did not touch. Total handling separates authority from information: the response's own total is the ONLY thing that authorizes completion. An indeterminate range's advertised end (`bytes X-Y/*` → Y+1) flags short delivery, and an indeterminate range that ends cleanly at Y stays incomplete too — reaching Y proves only that the selected range was delivered, so the transfer reconnects from the new offset instead of finalizing; only a response with no range and no total keeps the clean-EOF completion contract of unknown-length HTTP. A reset after the final byte of an AUTHORITATIVE total (overlap proven, totals in agreement) completes the transfer instead of resuming at EOF into a 416-truncate loop; a total carried forward from an earlier response is informational only — it can flag a short transfer, is dropped once the bytes on disk falsify it OR once an indeterminate range can even REACH it (strictly-below guard — settled to unknown on every exit path, clean deliveries and mid-stream pauses included, keeping row and live task consistent), and never authorizes finalization. A verified replay of an indeterminate range that appends nothing arms a one-shot EOF probe: the next attempt requests the byte after the partial outright, so a compliant `416` with `bytes */N` can confirm completion — the ordinary rewound request can never observe it; a probe answered with more data is retired unappended (no overlap proof at that offset) and ordinary rewound verification resumes; a 416 WITHOUT a confirming length answered to ANY request starting at the partial's exact end — the EOF probe and every validator-backed resume alike — is inconclusive, since a request at the entity's true end always collects one and the length is optional: the partial is retained rather than restarted, and only a stated total BELOW the partial proves the entity shrank. Only a fresh or restarted transfer drops the carried total entirely, since it described a discarded file. When no total was ever known, a retained failure persists `totalBytes` as null rather than fabricating one from the byte count — a fabricated total equal to the partial's size would let Retry's completed-partial shortcut finalize an unverified partial without a request; only a finalization failure after a COMPLETE transfer records its byte count as the total, which is what lets its Retry finalize the proven partial directly.
- Retained `filePath`s recorded in the database stay usable after the user switches download folders — resume/retry of a retained row does not re-require the folder to be the current selection. Fresh downloads still authorize against the currently selected folder.
- Startup recovery recognizes a finalization that crashed between creating the final file and committing the row (`downloading` row, no partial, final file present with the recorded size) and marks it `completed` instead of failing it and orphaning the file.
- Pause/resume is covered end to end by `apps/electron-backend-e2e/src/downloads.e2e.ts`: a throttled Range-capable mock server verifies the paused `.part` on disk, the `Range`/`If-Range` resume request, and byte-exact assembly of the final file. Automatic reconnects are covered by `apps/electron-backend-e2e/src/download-reliability.e2e.ts`: a validator-carrying interrupting server must complete without a manual Retry via `Range`/`If-Range`, and a validator-less interrupting server must complete through the rewound overlap-verification `Range` request.
- The OS downloads path is always authorized. A custom folder becomes
  authorized only after native folder selection, and the main process persists
  that selection under Electron `userData`. Renderer settings may display the
  path, but they are not trusted as authorization.
- The manager's search and All/Movies/Series/In progress filters affect visible
  queue and library entities only. The tracked-byte summary deliberately
  ignores search/category filtering while honoring route scope, so hiding a
  card never makes its disk footprint appear to vanish.

## Live-TV recordings

Recordings made with the embedded MPV player live beside downloads, not inside
them: a recording has no source URL to re-fetch, no byte totals, and no
retry/resume semantics, so it gets its own `recordings` SQLite table (no
unique index — re-recording a channel is normal; `playlist_id` carries no FK
so recordings survive source deletion, with `playlist_name` stored as a
display snapshot via `playlistDisplayLabel`).

- **Lifecycle tracking** is owned by `EmbeddedMpvRecordingTracker`
  (`apps/electron-backend/src/app/services/embedded-mpv-recording-tracker.ts`):
  explicit start/stop hooks in `EmbeddedMpvNativeService` plus a
  session-snapshot observer. The stop hook is a _request_, not an outcome —
  `addon.stopRecording()` only dispatches (async mpv property set, or a
  command written to the frame-copy helper), so finalization always waits for
  the snapshot reporting the recording inactive; statting or unlinking
  earlier would report a short recording as failed and could delete bytes mpv
  is still flushing. macOS native-view clears `recordingActive` _before_
  dispatching the async property set and restores it if that request is
  rejected, so an inactive snapshot must additionally survive a 1.5 s settle
  window (three poll cycles) before it counts as an acknowledgement; a revived
  recording cancels the pending finalization. A 10 s bound finalizes anyway if
  the acknowledgement never arrives. None of this timing is load-bearing for
  stop enrichment — that path does not wait for finalization at all. The same observer covers the stop paths that never call
  `stopRecording()` at all (stream-replacement auto-stop, frame-copy helper
  crash, session error/close). A synthetic error/closed snapshot arrives
  while teardown may still be flushing (the frame-copy helper exits up to
  ~2 s after `disposeSession()`), so it defers finalization behind a 2.5 s
  flush window instead of statting immediately — the row stays `recording`
  (startup-repairable) through the window, and an already-armed stop settle
  timer keeps its `completed` verdict. Statuses: `recording` → `completed` (acknowledged
  stop, `fs.stat` size) / `interrupted` (implicit stop with a playable partial
  — MPEG-TS is streamable) / `failed` (start error or absent/empty file). Only
  a recording that never went active has its empty pre-reserved file unlinked;
  once mpv owned the file, the bytes are left alone. Rows carry `owner_pid`,
  so startup repair (`recording-recovery.ts`, `reconcileStaleRecordings`)
  resolves what a hard kill left in `recording` while skipping rows another
  live instance still owns (`IPTVNATOR_ALLOW_MULTIPLE_INSTANCES`) and rows
  the tracker itself is still tracking (`activeRowIds()`) — the renderer is
  interactive before this pass runs, so a recording started during bootstrap
  carries this process's own pid and only the tracker's ledger proves it
  live. Bare pid liveness is not ownership: the holder must also look like
  an IPTVnator/Electron process (`ps`/`tasklist` name, best-effort) and must
  not provably have started after the recording did (`ps -o etime=` /
  PowerShell `StartTime`) — a pid frees only when its previous owner dies,
  so a recycled pid's holder is always younger than the recording, even
  when it landed on another Electron app; unreadable evidence stays
  conservative and keeps the skip. Repair changes broadcast one
  `RECORDINGS_UPDATE_EVENT` because the renderer may already hold the
  pre-repair list. Both repair and tracker finalization stat through a
  bounded async probe (3 s deadline; only `ENOENT`/`ENOTDIR` proves
  absence): repair leaves an unjudgeable row in `recording` for a later
  startup, finalization keeps the requested status with an unknown size —
  a recording directory on a dead network mount must neither block the
  main thread/queue nor brand a likely-good file `failed`. Repair probes
  its whole batch concurrently, so `main.ts` awaits roughly one deadline,
  not one per row. List decoration likewise preserves an inconclusive
  probe: `ElectronRecordingItem.fileAvailability` adds `'unknown'`, and
  consumers gate on `=== 'missing'` so only proven absence reaches Needs
  attention or hides file actions. The focused
  recording detail route is guarded by the `supportsRecordings` capability
  (redirect to the manager) since `RecordingsService` never becomes
  authoritative in the PWA. Tracker finalization is bound to the exact open entry, never the
  reusable session id: a stop → immediate restart on the same session leaves
  the old entry to its own settle timer, and replacing the map entry arms
  that timer if no stop was ever observed, so neither row can be finalized
  by the other's lifecycle.
- **Metadata is captured at recording start** (EPG is time-sensitive and
  Xtream/Stalker EPG never reaches SQLite): each live host — M3U player,
  Xtream live layout, Stalker ITV layout, unified live tab — assembles a
  `RecordingStartMetadata` (channel name/logo, playlist id + display-label
  snapshot, source type, EPG key, current program) that flows
  `WebPlayerViewComponent → EmbeddedMpvPlayerComponent →
EmbeddedMpvControlsAdapter → EmbeddedMpvRecordingStartOptions.metadata`.
  `EmbeddedMpvPlayerComponent` watches the session snapshot for the
  active→inactive recording edge and emits `recordingStopped` — one owner for
  every trigger, including a Stop clicked in the download manager, which
  talks to the main process directly and never reaches the player's own
  toggle. The event carries the EPG key captured while the recording was
  active, because a channel switch auto-stops the recording and the host's own
  state already describes the new channel by the time the stop is handled;
  each host enriches only when that key still matches its current channel.
  The EPG key is not unique for M3U items (a `tvgId`, or the display-name
  fallback, can be shared by several list entries), so hosts with M3U
  selections additionally set `RecordingStartMetadata.sourceItemKey` (the
  unified tab's `item.uid`, the M3U player's `channel.id`) — captured and
  carried through the stop event the same way, and compared before
  enriching, so switching between two same-keyed items cannot attach the
  second item's schedule to the first item's recording. The host answers with **stop enrichment**: it filters its in-memory
  program list to the programs overlapping `[startedAt, endedAt]`
  (`filterRecordingProgramsOverlap` in `@iptvnator/shared/interfaces`) and
  sends them through `RECORDINGS_UPDATE_PROGRAMS`, keyed by the unique
  target path — that is how a recording spanning a program boundary lists
  every covered show. The handler is deliberately independent of finalization: it
  looks the row up in **any** status (the newest for that path — `openSync
('wx')` keeps a reserved path exclusive while its recording owns it) and
  `finalize()` never touches `programs_json`, so the two writes commit in
  either order. The only wait is the tracker's queue drain, which guarantees
  the row's INSERT exists — no deadline, and therefore no way for a one-shot
  enrichment to be dropped by a clock. A recording stopped while no player is mounted on that
  channel keeps its start snapshot.
- **IPC surface** (`recordings.events.ts`): `RECORDINGS_GET_LIST/GET/STOP/
REMOVE/UPDATE_PROGRAMS/REVEAL_FILE/PLAY_FILE` plus the dedicated
  `RECORDINGS_UPDATE_EVENT` bare ping (not shared with downloads, so
  recording transitions do not force availability-probed download refetches).
  Active rows are decorated with a live `fs.stat` size — `file_size_bytes` is
  only persisted at finalization, so the manager's growing size comes from
  there. Recording totals also feed the manager-wide All chip and the header's
  active badge, so a page listing only recordings never reads "All 0".
  Reveal/play are gated by `isManagedRecordingFile` — the path must exist in
  the recordings table, mirroring `isManagedDownloadFile`, so the
  renderer-supplied recording directory stays a write-location preference
  rather than a shell-access grant. `RECORDINGS_STOP` resolves the row's
  `session_id` and stops through `EmbeddedMpvNativeService`, so the manager
  can stop a recording without knowing about MPV sessions — but only for rows
  this process owns: session ids restart per process, so dispatching a
  foreign row's id would stop an unrelated local recording. Remove keeps
  finished files on disk (same contract as downloads) and cleans up a failed
  row's leftover reservation only while no other row claims that path — a
  retry within the same timestamp second reuses the freed name. Renderer gate: a separate
  `supportsRecordings` capability allowlist — deliberately NOT folded into
  `supportsDownloads`, which would strip older builds of the whole manager.
- **UI**: `RecordingsService` mirrors `DownloadsService` (one global list,
  coalesced refreshes via `DownloadListLoadState`, refetch on ping). The
  manager adds a `recording` filter chip; `recording-manager.viewmodel.ts`
  partitions rows into a "Recording now" queue section (pulsing REC chip with
  elapsed time and live file size — never a percentage, the length is
  unknown; the size comes from a bounded, in-flight-coalesced `stat` with a
  1 s deadline so a recording directory on a dead network filesystem
  degrades to "no size" instead of wedging every list load), a recordings-only Needs attention list (Remove only: a broadcast
  cannot be re-recorded), and a "Recordings" library section of 16:9
  channel-logo cards (`recording-queue.component.*`,
  `recording-library.component.*`). Card titles use the captured program
  title, falling back to channel + start time. The focused detail
  (`recording-detail/`, route `/workspace/downloads/recording/:recordingId`,
  context panel and route search hidden via `workspace-shell-route.utils.ts`)
  shows the recorded time range, covered programs when a recording spans ≥2
  shows, file path, and Play/Reveal/Stop/Remove; a missing file degrades to
  Back + Remove.

Keeping the backend queue, IPC handlers, shared schema, and renderer signals
synchronized minimizes drift between platform rules and the UI. Future work
might cover queue reordering, bulk pause/cancel actions, disk-free space
telemetry, playback analytics, or frame-copy screenshot posters for
recordings.