{"owner":"4gray","repo":"iptvnator","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n> The process sections below (Plan Mode, Documentation After Changes, Regression Prevention, Agent Bootstrap, Electron CDP Debugging) are mirrored in `AGENTS.md`, which is the canonical copy for agent workflows. When updating one, keep the other in sync.\n\n## Plan Mode\n\n- When Claude Code is in Plan Mode and produces a final ``, it must also save that finalized plan as a Markdown file in the repo-root `.plans/` directory.\n- Save only finalized plans. Do not write interim exploration, question turns, or draft revisions to `.plans/`.\n- Use the filename pattern `YYYY-MM-DD-short-topic.md` such as `.plans/2026-03-12-channel-filtering.md`.\n- If the intended filename already exists, append a numeric suffix such as `-2`, `-3`, and so on.\n\n## Documentation After Changes\n\n- After implementing a meaningful change, Claude Code must assess whether canonical repo docs need updates before considering the task complete.\n- Meaningful changes include new or changed user-visible behavior, architecture or data-flow changes, non-obvious maintenance workflows, new setup/debugging steps, and new subsystem contracts or boundaries.\n- Skip doc updates for trivial refactors with unchanged behavior, formatting-only edits, and isolated test-only changes.\n- Prefer updating an existing authoritative doc before creating a new one:\n 1. `README.md` for top-level developer or user workflows\n 2. `docs/architecture/` for architecture, ownership, and behavior contracts\n 3. the nearest module `README.md` for local usage or behavior\n- Keep this file (`CLAUDE.md`) itself up to date. It is a living document: whenever a change touches something it describes — monorepo structure (new/moved/renamed apps or libs), routes, database schema/tables, stores and their features, key components, commands, environment behavior, or coding conventions — update the affected `CLAUDE.md` sections as part of the same task, and keep the mirrored process sections in `AGENTS.md` in sync.\n- When adding a new feature area, check whether the Architecture or Key Features sections of `CLAUDE.md` describe the surrounding area; if they do, reflect the addition there instead of leaving the description stale.\n- Do not let `CLAUDE.md` drift: a stale path or route in this file poisons the context of every future agent session. If you notice an outdated claim while working, fix it (or flag it in the final summary) even if it is unrelated to the current task.\n- Repo docs are canonical even when they were originally drafted by an LLM.\n- Final task summaries should state whether docs were updated and which doc changed.\n\n## Release Notes For User-Visible Changes\n\n- Any change a user could notice — new behavior, changed behavior, bug fix, performance win, breaking change — must add one note file under `.changes/` in the same PR. Format, field table, and writing rules: `.changes/README.md`.\n- Name it `-.md`; `area` matches the conventional-commit scope. There is no version field — the release version is chosen at release time.\n- Write the body for a user, not a reviewer: \"the player now remembers volume between episodes\", not \"hoist volume state into the session\". Max 400 characters; depth belongs in the release blog post.\n- `type: internal` records invisible maintenance. Internal notes stay collapsed in `CHANGELOG.md`, are omitted from the blog scaffold, and are removed from the authored public GitHub body by `extract-changelog-section.mjs --public`; GitHub's generated commit list remains separate, so an internal-only release can have an empty authored body.\n- Skip the note for test-only changes, docs, CI/workflow plumbing, and pure refactors with no behavior change. When skipping on a PR that touches `apps/**` or `libs/**`, apply the `no-release-note` label.\n- CI enforces this: the \"Release note gate\" job in `.github/workflows/ci.yml` fails PRs that change runtime code without an added `.changes/*.md` or the label (policy in `tools/release/check-release-note-gate.mjs`; tests/e2e/website/mock-server/docs paths are auto-exempt).\n- The `release-notes` skill covers writing notes; the `release-cut` skill covers the full release sequence.\n- Validate before finishing: `pnpm run release:notes:validate`.\n- Pushes to `master` and `v*` can publish Docker images. A `v*` tag build creates a draft GitHub release.\n- Publishing the GitHub release verifies its Snap assets and automatically uploads them to `edge`; installed-Snap smoke and candidate/stable promotion remain manual.\n- Release-post screenshots come only from the release capture script running against the mock servers. Never add a screenshot taken from a real playlist or account to `apps/website/public/blog/**` — real streams, logos, and metadata are copyrighted, and credentials must never reach a published image.\n- Final task summaries should state whether a release note was added or why it was skipped.\n\n## Regression Prevention And Test Updates\n\n- Before the final summary for any feature, behavior change, bug fix, data-flow change, Electron IPC/database change, or user-visible UI workflow change, Claude Code must complete a test impact pass. Identify the affected projects and decide whether unit, integration, E2E, build, lint, or manual/CDP verification is required.\n- Bug fixes must normally include regression coverage that fails on the old behavior and passes with the fix. If automated coverage is not practical, document why in the final summary and include the strongest manual validation performed.\n- Feature work and behavior changes must update existing tests when assertions, fixtures, mocks, routes, or E2E flows are now stale, incomplete, or missing. Prefer extending the closest existing spec or E2E file before adding a new suite.\n- Default validation ladder:\n 1. Run targeted unit tests for directly affected projects with `pnpm nx test ` or existing scripts such as `pnpm run test:frontend`, `pnpm run test:backend`, or `pnpm run test:unit:ci` when the scope is broader.\n 2. Run affected E2E coverage when changing user-visible workflows, routing, persistence, playback, portals, settings, import flows, or Electron-only behavior.\n 3. Use `pnpm nx show projects --withTarget test` and `pnpm nx show projects --withTarget e2e` when project ownership or available validation targets are unclear.\n 4. Prefer specific atomized E2E targets before broad suites when they cover the changed behavior, for example `pnpm nx run web-e2e:e2e-ci--src/xtream.e2e.ts` or `pnpm nx run electron-backend-e2e:e2e-ci--src/search.e2e.ts`.\n- Electron-specific changes affecting IPC, SQLite, packaged runtime, external players, native file access, or Electron-only routes require Electron E2E coverage where available, or CDP/manual verification with `agent-browser` and the tracing flags documented below.\n- Final task summaries must list tests added or updated, validation commands run with results, and any skipped validation with the reason. For docs-only changes, state that unit/E2E validation was not required and verify the changed Markdown instead.\n\n## Project Overview\n\nIPTVnator is a cross-platform IPTV player application built with Angular and Electron, supporting M3U/M3U8 playlists, Xtream Codes API, and Stalker portals.\n\n**Dual Environment Support**: The application is designed to work in both Electron and as a Progressive Web App (PWA). The architecture uses a factory pattern to inject environment-specific services at runtime, ensuring the same codebase works in both contexts.\n\n## Development Commands\n\n### Agent Bootstrap\n\n```bash\npnpm install --frozen-lockfile\npnpm nx show projects\n```\n\n- Run the install step in a fresh worktree before relying on Nx discovery, lint, test, or build commands. Without `node_modules`, local Nx modules are unavailable.\n- Use scoped path aliases from `tsconfig.base.json` such as `@iptvnator/services`, `@iptvnator/shared/interfaces`, and `@iptvnator/ui/components`.\n- Do not add new imports from legacy bare aliases such as `services`, `shared-interfaces`, `components`, `m3u-state`, or `database`.\n- Every Nx project should keep `scope:*`, `domain:*`, and `type:*` tags in `project.json`.\n- See `docs/architecture/nx-workspace-boundaries.md` for the current Nx tag and alias policy.\n- Keep `nx` and every official `@nx/*` package on the same exact version; run\n `pnpm run deps:nx:validate` after dependency updates.\n- Vite `7.3.6`, resolved through Angular's build tooling, is patched with\n bounded transform prefilters and the upstream precise matchers in\n `patches/vite@7.3.6.patch`. Keep the patch until supported Angular tooling\n resolves a Vite version containing the fix, and run `pnpm run deps:vite:test`\n after related dependency updates.\n- A directory holding files consumed by other projects must be an Nx project.\n Nx builds its graph from TypeScript imports only, so a relative SCSS `@use`\n across project roots creates no edge and the imported file lands in no task\n hash — edits then return a cache hit instead of rebuilding. Shared partials\n live in `libs/ui/styles` (project `ui-styles`), and each consumer declares\n `\"implicitDependencies\": [\"ui-styles\"]`. Run `pnpm run styles:inputs:validate`\n after adding a cross-project stylesheet import.\n- Update Nx with `pnpm nx migrate nx@ --skipInstall`, regenerate the\n lockfile, run generated migrations when present, and validate before opening\n a PR. Major updates are always manual. Replace incomplete Dependabot security\n PRs with a coordinated update instead of editing the bot branch.\n- Repository-specific skills live under `.codex/skills/`.\n- Frontmatter descriptions are trigger-only and begin with `Use when`; keep\n each skill at or below 500 words.\n- Run `pnpm run skills:validate` after editing a committed skill or a literal\n path it documents.\n- Keep `.codex` and `.claude` copies of `release-notes` and `release-cut`\n byte-identical.\n\n### Building and Serving\n\n```bash\n# Serve the Angular web app only (development mode, baseHref=\"/\")\npnpm run serve:frontend\n# or\nnx serve web\n\n# Serve with PWA configuration (optimized, baseHref=\"/\")\npnpm run serve:frontend:pwa\n# or\nnx serve web --configuration=pwa\n\n# Serve the Electron app (starts both frontend and backend)\npnpm run serve:backend\n# or\nnx serve electron-backend\n\n# Build frontend for Electron (baseHref=\"./\")\npnpm run build:frontend\n# or\nnx build web\n\n# Build frontend for PWA deployment (baseHref=\"/\")\npnpm run build:frontend:pwa\n# or\nnx build web --configuration=pwa\n\n# Build backend (Electron)\npnpm run build:backend\n# or\nnx build electron-backend\n\n# Package the app (creates distributable without installers)\npnpm run package:app\n# or\nnx run electron-backend:package\n\n# Create installers/executables\npnpm run make:app\n# or\nnx run electron-backend:make\n```\n\n### Electron CDP Debugging\n\n- Start Electron in dev mode with: `nx serve electron-backend`\n- Package-script equivalent: `pnpm run serve:backend`\n- The workspace is configured to always launch Electron with: `--remote-debugging-port=9222`\n- Use CDP clients (Chrome DevTools Protocol tools) against: `127.0.0.1:9222`\n- When the task is Electron automation/debugging, use the `electron` skill\n- Do not auto-open DevTools during normal CDP automation. In development, DevTools is opt-in via `ELECTRON_OPEN_DEVTOOLS=1`.\n- If DevTools is open, `agent-browser --cdp 9222 ...` may attach to the DevTools page instead of the IPTVnator window (symptoms: `tab list` shows `about:blank`, empty snapshots, black screenshots). Inspect targets with `curl http://127.0.0.1:9222/json/list` and connect directly to the app page's `webSocketDebuggerUrl`.\n- The app holds a single-instance lock (`acquireSingleInstanceLock` in `apps/electron-backend/src/app/services/single-instance.ts`): a second launch against the same `userData` quits immediately and focuses the running window. To attach a second CDP-enabled instance to the same profile, set `IPTVNATOR_ALLOW_MULTIPLE_INSTANCES=1` — knowing that only one of the two processes will own the renderer's IndexedDB, so settings written by the other are lost. Before focusing, the guard forwards the second launch's argv to `onSecondInstance`, which is how a playlist path handed to an already-running app reaches the open queue.\n\nFor startup tracing or white-screen debugging:\n\n```bash\nIPTVNATOR_TRACE_STARTUP=1 nx serve electron-backend\n```\n\nUseful narrower flags:\n\n- `IPTVNATOR_TRACE_IPC=1` traces renderer `window.electron.*` bridge calls\n- `IPTVNATOR_TRACE_DB=1` traces DB worker requests and DB progress events\n- `IPTVNATOR_TRACE_SQL=1` traces SQLite statements in both main and worker connections\n- `IPTVNATOR_TRACE_WINDOW=1` traces BrowserWindow navigation/load lifecycle\n- `IPTVNATOR_TRACE_PLAYER=1` traces external-player activity and bounded Embedded MPV runtime-probe stderr\n- `IPTVNATOR_TRACE_RENDERER_CONSOLE=1` mirrors renderer console logs into the Electron terminal\n- `IPTVNATOR_PERF_CAPTURE=1` enables development/test-only, redacted M3U and Xtream preload IPC request/completion markers plus count-only M3U acquire/parse/normalize, Xtream main network/JSON-transform/success-response-ready/cancel-dispatch, and renderer store phase capture; renderer wrappers emit only while the benchmark installs its Symbol hook, benchmark tooling sets the flag explicitly, and production launches must leave it unset\n- `IPTVNATOR_PERF_WORKER_PROFILING=1` enables development/test-only, request-scoped worker receive/work/response-post timestamps, thread CPU, event-loop utilization/delay, count-only playlist serialization/SQLite write/read/deserialization plus Xtream category/content/cache-clear/delete/in-source-search phase events, profiling-only worker cancel-receipt acknowledgements, valid-sample-counted isolate peak memory, and the database worker's idle-only one-shot post-GC heap probe; overlapping database requests are explicitly invalidated instead of misattributed, the performance benchmark sets the flag automatically, and production launches must leave it unset\n\nSettings, portal request/response, and trace payloads must use\n`@iptvnator/shared/logging` or the redacting portal logger before reaching\n`console.*`; never log raw credentials while debugging.\n\nIf the Nx daemon gets into a bad state before rerunning Electron:\n\n```bash\npnpm nx reset\n```\n\nUse global `agent-browser` (preferred):\n\n```bash\n# Verify CDP targets\nagent-browser --cdp 9222 tab list\n\n# Switch to the app tab and inspect interactive elements\nagent-browser --cdp 9222 tab 1\nagent-browser --cdp 9222 snapshot -i -c -d 4\n\n# Capture debug artifacts\nagent-browser --cdp 9222 screenshot /tmp/iptvnator-cdp.png\nagent-browser --cdp 9222 trace start /tmp/iptvnator.trace.zip\nagent-browser --cdp 9222 wait 1500\nagent-browser --cdp 9222 trace stop /tmp/iptvnator.trace.zip\n```\n\nIf `agent-browser` is not in PATH, use:\n\n```bash\nnpx --yes agent-browser --cdp 9222 tab list\n```\n\n### Testing\n\n```bash\n# Run frontend tests\npnpm run test:frontend\n# or\npnpm nx test web\n\n# Run backend tests\npnpm run test:backend\n# or\npnpm nx test electron-backend\n\n# Run targeted E2E tests (Playwright)\npnpm nx run web-e2e:e2e-ci--src/xtream.e2e.ts\npnpm nx run electron-backend-e2e:e2e-ci--src/search.e2e.ts\n\n# Run broad E2E suites only when the impact justifies it\npnpm nx e2e web-e2e\npnpm nx e2e electron-backend-e2e\n\n# Run tests with coverage when needed\npnpm nx test web --configuration=ci\n```\n\nBefore finishing behavior changes or bug fixes, follow `Regression Prevention And Test Updates` above and report the test impact decision in the final summary.\n\n### Linting\n\n```bash\n# Lint all projects (CI runs this on master; PRs lint affected projects)\npnpm run lint\n\n# Lint a single project\nnx lint web\nnx lint electron-backend\n```\n\nCI lints affected projects on PRs (`nx affected`) and every project on master\npushes (`.github/workflows/ci.yml`). This enforces the\nNx module-boundary tags, the legacy bare-alias ban, and a `max-lines` ESLint\nrule. The limits and their rationale live in one place,\n`tools/eslint/max-lines-config.mjs`, which both `eslint.config.mjs` and the\nbaseline generator import so the enforced rule and the generated list cannot\ndrift:\n\n- **Production TypeScript: hard maximum 400 lines.**\n- **Tests: 1200.** `**/*.spec.ts`, `**/*.e2e.ts` and everything under\n `apps/*-e2e/**` — a spec is a flat list of independent cases, so splitting one\n at the production limit yields arbitrary `-2.spec.ts` files, and length there\n signals coverage rather than the design debt the production limit catches.\n- **Blank lines and comments are not counted** (`skipBlankLines`,\n `skipComments`), so a docblock is never the reason a file must be split.\n\nPre-existing oversized files are baselined in\n`tools/eslint/max-lines-baseline.mjs`; regenerate the baseline with\n`node tools/eslint/generate-max-lines-baseline.mjs` after splitting a file. The\ngenerator decides who belongs on the list by running ESLint's own `max-lines`\nrule, not by counting lines itself — a private reimplementation would silently\ndisagree with the rule and produce a baseline that turns CI red while looking\ncorrect. Never add new files to the baseline — the list must only shrink. A new\nfile that genuinely cannot be split (for example a function serialized into\nanother process) instead carries its own file-wide\n`/* eslint-disable max-lines -- */`; the generator skips those files, so\na justified exemption never lands in the baseline. If such a directive later\nbecomes unnecessary, ESLint reports it as an unused disable directive — remove\nit rather than leaving a stale justification behind.\n\nProject `lint` targets that shell out to eslint must quote the glob, e.g.\n`eslint \"apps//**/*.ts\"`. An unquoted `**` is expanded by the POSIX\nshell on Linux and macOS (which has no `globstar`, so it matches only a\nshallow subset of files) while Windows passes the literal pattern to ESLint,\nwhich expands it recursively — the two hosts then lint different file sets.\nThe target still reports success either way, so a broken glob hides missing\ncoverage instead of failing. After changing such a target, compare the linted\nfile count against `find -name '*.ts' | wc -l`.\n\n## Architecture\n\n### Monorepo Structure (Nx Workspace)\n\nThis is an Nx monorepo with the following structure:\n\n- **apps/web** - Angular application (frontend, shared by Electron and PWA)\n- **apps/electron-backend** - Electron main process\n- **apps/web-backend** - HTTP backend for the self-hosted PWA (`/parse`, `/parse-xml`, `/xtream`, `/stalker` CORS proxy endpoints). At startup it raises Node's happy-eyeballs per-attempt connection timeout to 2500 ms (`network-family-autoselection.ts`) so dual-stack provider hostnames fall back to IPv4 behind IPv6-less VPN/Docker networks; an explicit `--network-family-autoselection-attempt-timeout` passed via `NODE_OPTIONS`/CLI always wins. Outbound provider failures are logged hostname-only with the underlying Node error codes and return the primary code in the error body (`provider-error.ts`) — the proxied URL query carries credentials and must never be logged. Every proxied request carries the same timeout as its Electron counterpart (Xtream 30 s, Stalker 15 s / 30 s for `create_link`, playlist and XMLTV 30 s). The shared per-host circuit breaker (`host-guard.ts`, injected via `WebBackendAppOptions.hostGuard`) covers `/xtream` and `/stalker` only — playlist/XMLTV downloads keep the timeout but no breaker, matching Electron. A fast-fail keeps the route's normal failure shape (HTTP 200 with a `{message, status}` body), `skipConnectionGuard=true` carries the Stalker discovery exemption through the proxy, and `POST /connectivity-guard/reset` is the PWA's counterpart to the `CONNECTIVITY_GUARD_RESET` IPC\n- **apps/remote-control-web** - Mobile remote-control web app served by the Electron backend\n- **apps/web-e2e** - Playwright E2E tests against the web app\n- **apps/electron-backend-e2e** - Playwright E2E tests against the Electron app\n- **apps/stalker-mock-server** - Mock Stalker/Ministra portal for dev and E2E\n- **apps/xtream-mock-server** - Mock Xtream Codes API for dev and E2E\n- **apps/website** - Astro + Tailwind landing page and blog\n- **libs/** - Shared libraries:\n - **epg/data-access** - EPG services, runtime bridge, program normalization\n - **m3u-state** - NgRx state management for M3U playlists\n - **playlist/import/feature** - Playlist import flows (file/URL/text upload, Xtream and Stalker import dialogs)\n - **playlist/m3u/feature-player** - M3U video player page and `/workspace/playlists/:id` routes\n - **playlist/shared/{ui,util}** - Shared playlist UI and utilities\n - **portal/xtream/{data-access,feature}** - XtreamStore, services, data sources; routed Xtream components\n - **portal/stalker/{data-access,feature}** - StalkerStore and routed Stalker components\n - **portal/catalog/feature** - Portal catalog UI\n - **portal/downloads/feature** - Download manager UI\n - **portal/shared/{data-access,ui,util}** - Cross-portal shared code: stateful collection services and VOD multi-source discovery/resolve/ranking live in `data-access`; reusable views live in `ui`; `util` is for pure contracts/helpers\n - **services** - Abstract DataService contract and shared app services (incl. the TMDB metadata enrichment module in `lib/tmdb/`)\n - **shared/interfaces** - TypeScript interfaces and types (incl. `ElectronBridgeApi`)\n - **shared/logging** - Dependency-free structured redaction for diagnostic logs\n - **shared/host-health** - Per-host circuit breaker for portal requests (`HostConnectivityGuard`), shared by the Electron main process and the web backend; transport-free, the owning app supplies the clock and owns the instance\n - **shared/database** - Canonical Drizzle schema and DB connection (used by the Electron backend)\n - **shared/m3u-utils** - M3U playlist utilities\n - **shared/marketing-fixtures** - Provider-neutral fictional movie metadata shared by the Xtream and Stalker marketing mocks\n - **shared/testing** - Shared test helpers\n - **ui/components** - Reusable UI components (incl. channel list)\n - **ui/epg** - EPG UI (timeline ribbon, multi-EPG, progress panel, program dialogs)\n - **ui/playback** - Player UI (video/audio players)\n - **ui/pipes** - Angular pipes\n - **ui/remote-control** - Remote-control UI pieces\n - **ui/shared-portals** - Shared portal types (`LiveEpgPanelSummary`)\n - **ui/styles** - Shared styles/theme\n - **workspace/{shell,dashboard}** - Workspace shell (layout/navigation) and dashboard\n\n### Frontend Architecture (Angular)\n\n**State Management**: Uses NgRx for playlist state management:\n\n- Store configuration in `apps/web/src/app/app.config.ts`\n- Playlist state, actions, effects, and reducers in `libs/m3u-state/`\n- Entity adapter pattern for managing playlists collection\n- Router store integration for route-based state\n\n**XtreamStore Architecture** (Signal Store with Feature Composition):\n\nThe Xtream Codes module uses NgRx Signal Store with a layered architecture:\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ PRESENTATION LAYER │\n│ Components use XtreamStore (facade) │\n└─────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ FACADE LAYER │\n│ XtreamStore │\n│ (Composes feature stores, unified API) │\n└─────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ withPortal · withContent · withSelection · withSearch · withEpg │\n│ withPlayer · withFavorites · withRecentItems │\n│ withPlaybackPositions │\n└─────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ DATA SOURCE LAYER │\n│ IXtreamDataSource │\n│ ┌───────────────────┬───────────────────┐ │\n│ ▼ ▼ │\n│ ElectronDataSource PwaDataSource │\n│ (DB-first + API) (API-only) │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nFile structure:\n\n```\nlibs/portal/xtream/\n├── data-access/src/lib/\n│ ├── stores/\n│ │ ├── features/\n│ │ │ ├── with-portal.feature.ts # Playlist & portal status\n│ │ │ ├── with-content.feature.ts # Categories & streams\n│ │ │ ├── with-selection.feature.ts # UI selection & infinite-scroll window\n│ │ │ ├── with-search.feature.ts # Search functionality\n│ │ │ ├── with-epg.feature.ts # EPG data\n│ │ │ ├── with-player.feature.ts # Stream URLs & player\n│ │ │ ├── with-playback-positions.feature.ts # Resume/playback positions\n│ │ │ └── index.ts\n│ │ ├── xtream.store.ts # Facade composing all features\n│ │ └── index.ts\n│ ├── services/\n│ │ ├── xtream-api.service.ts # Xtream Codes API calls\n│ │ ├── xtream-url.service.ts # Stream URL construction\n│ │ ├── favorites.service.ts # Favorites persistence\n│ │ ├── epg-queue.service.ts # EPG fetch queueing\n│ │ ├── xtream-xmltv-fallback.service.ts # XMLTV fallback EPG\n│ │ └── index.ts\n│ ├── data-sources/\n│ │ ├── xtream-data-source.interface.ts # Abstract interface + types\n│ │ ├── electron-xtream-data-source.ts # DB-first implementation\n│ │ ├── pwa-xtream-data-source.ts # API-only implementation\n│ │ └── index.ts # provideXtreamDataSource() factory\n│ ├── with-favorites.feature.ts # Favorites feature\n│ └── with-recent-items.ts # Recently viewed feature\n└── feature/src/lib/ # Routed components\n ├── xtream-feature.routes.ts # createXtreamRoutes(): /workspace/xtreams/:id tree\n ├── live-stream-layout/, vod-details/, serial-details/, ...\n └── global-search-results/ # Global search (Electron-only route)\n```\n\nKey patterns:\n\n- **Feature stores**: Each `with*.feature.ts` uses `signalStoreFeature()` for focused functionality\n- **Facade pattern**: `XtreamStore` composes all features, maintaining backward compatibility\n- **Data source abstraction**: `IXtreamDataSource` has SQLite-backed and\n API/in-memory implementations\n- **Factory injection**: `provideXtreamDataSource()` selects\n `ElectronXtreamDataSource` only when\n `RuntimeCapabilitiesService.supportsXtreamSqliteDataSource`; otherwise it\n selects `PwaXtreamDataSource`\n- **Catalog lazy loading**: catalog grids scroll infinitely instead of paging.\n `withSelection` keeps a `visibleCount` render window over the in-memory\n catalog plus bounded per-selection scroll snapshots for detail/tab\n round-trips; the shared `InfiniteScrollDirective`\n (`libs/portal/shared/ui`) measures container overflow to auto-fill tall\n viewports (terminating on lack of container growth, not on a load count)\n and fires `loadMore` near the bottom. The search layout routes its results\n container through the same directive (`nearEnd*` inputs). Stalker feeds the\n same contract from server-paged appends: portal pages accumulate into one\n deduplicated list, `hasMoreContent` derives from accumulated length vs\n `total_items`, a failed append keeps loaded pages and offers a tail retry,\n and the facade maps page 0 to the skeleton and later pages to the tail\n spinner. No paginator remains anywhere in the app\n\nXtream data strategies by runtime capability:\n\n| Capability | Strategy |\n| --------------------------------- | -------------------------------------------------------- |\n| **Complete Xtream SQLite bridge** | DB-first: check DB → fetch API if missing → cache to DB |\n| **Bridge unavailable** | API-only: fetch from API and keep session data in memory |\n\n**M3U Playlist Module Architecture**:\n\nThe M3U playlist module handles traditional M3U/M3U8 playlists with support for 90,000+ channels.\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ VIDEO PLAYER PAGE │\n│ libs/playlist/m3u/feature-player/src/lib/video-player/ │\n├─────────────────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌───────────────────────────────────────────────┐│\n│ │ Sidebar │ │ Video Player (ArtPlayer/Video.js) ││\n│ │ ┌─────────┐ │ │ ││\n│ │ │Channel │ │ ├───────────────────────────────────────────────┤│\n│ │ │List │ │ │ EPG timeline ribbon (app-epg-timeline) ││\n│ │ │Container│ │ │ horizontal, under the player ││\n│ │ └─────────┘ │ └───────────────────────────────────────────────┘│\n│ └─────────────┘ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\nThe live EPG panel is a horizontal **timeline ribbon** under the player (`app-epg-timeline`, `libs/ui/epg/src/lib/epg-timeline/`), not a right-side drawer (reworked in PR #1102). See `docs/architecture/m3u-playlist-module.md` for the timeline's controllers and scroll behavior.\n\n**Radio Channel Layout** (when `channel.radio === 'true'`):\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ ┌─────────────┐ ┌────────────────────────────────────────────────┐│\n│ │ Sidebar │ │ Blurred backdrop (station logo) ││\n│ │ │ │ ┌──────────┐ ││\n│ │ │ │ │ Artwork │ ← cinematic hero layout ││\n│ │ │ │ └──────────┘ ││\n│ │ │ │ Station Name ││\n│ │ │ │ [LIVE] badge ││\n│ │ │ │ ⏮ ▶/⏸ ⏭ ← transport controls ││\n│ │ │ │ 🔊 ━━━━━━━━━ ← volume slider ││\n│ │ │ │ (no EPG panel) ││\n│ └─────────────┘ └────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────────────┘\n```\n\nKey radio behavior:\n\n- Detection: `channel.radio === 'true'` (string from M3U `radio` attribute)\n- The audio player always renders inline — `shouldShowInlinePlayer` is bypassed for radio\n- EPG panel is conditionally hidden in the template when radio is active\n- Volume is shared with video player via `localStorage` key `'volume'`\n- Keyboard: ArrowUp/Down adjusts volume by 5%, M toggles mute\n- Component: `libs/ui/playback/src/lib/audio-player/audio-player.component.ts`\n\n**M3U Movie Recognition** (VOD detail instead of the EPG zone): an M3U entry\nrecognized as a movie FILE swaps the player + EPG area for the portals'\ntwo-state VOD detail shell fed by TMDB, watch-first (activation still plays\nimmediately; Esc reveals the Browse hero). Detection is synchronous URL-shape\nheuristics — movie container extension (`mkv`/`mp4`/…, never `ts`/`m3u8`/`mpd`)\nor an Xtream-style `/movie|movies|vod/` path segment; radio, DASH, `/series/`\npaths and episode-marker names (`S01E02`, \"2 серия\") fail toward the live\nlayout (`isLikelyM3uMovie` in `libs/shared/m3u-utils`). Gated on TMDB\nenrichment being enabled AND `Settings.m3uVodDetails` (default on; checkbox in\nSettings → Metadata (TMDB)). Host: `m3u-vod-detail/` in\n`libs/playlist/m3u/feature-player` (shell + `PortalInlinePlayerComponent`,\nparent's `embeddedPlayback()` with `isLive: false`); external MPV/VLC users\nkeep Browse. See \"Movie Recognition (VOD Detail View)\" in\n`docs/architecture/m3u-playlist-module.md`.\n\nChannel List Component Structure (parent coordinator pattern):\n\n```\nlibs/ui/components/src/lib/channel-list-container/\n├── channel-list-container.component.ts # Parent - shared state coordinator\n├── all-channels-view/ # Virtual scroll + debounced search\n├── groups-view/ # Expansion panels + infinite scroll\n├── favorites-view/ # CDK drag-drop reordering\n├── recent-view/ # Recently viewed channels\n└── channel-list-item/ # Individual channel display\n```\n\nKey patterns:\n\n- **EnrichedChannel**: Pre-computed EPG data attached to channels for performance\n- **Parent coordinator**: Manages shared signals (`channelEpgMap`, `progressTick`, `favoriteIds`)\n- **Virtual scrolling**: CDK virtual scroll for 90,000+ channel lists\n- **Infinite scroll**: IntersectionObserver in groups view loads 50 items at a time\n- **Global progress tick**: Single 30s interval instead of per-item intervals\n\nState management via NgRx (`libs/m3u-state/`):\n\n- `PlaylistActions`: loadPlaylists, addPlaylist, removePlaylist, parsePlaylist\n- `ChannelActions`: setChannels, setActiveChannel, setAdjacentChannelAsActive\n- `EpgActions`: setActiveEpgProgram, setCurrentEpgProgram, setEpgAvailableFlag\n- `FavoritesActions`: updateFavorites, setFavorites, hydrateFavorites\n\nSee `docs/architecture/m3u-playlist-module.md` for complete documentation.\n\n**Routing**: Lazy-loaded routes in `apps/web/src/app/app.routes.ts`. All user-facing routes are nested under the workspace shell (`/workspace/...`); `/` redirects into the workspace.\n\n- Dashboard: `/workspace/dashboard`; sources overview: `/workspace/sources`\n- M3U player: `/workspace/playlists/:id` (children: `favorites`, `recent`, `:view`) — routes in `libs/playlist/m3u/feature-player`\n- Xtream Codes: `/workspace/xtreams/:id` (children: `live`, `vod`, `series`, `search`, `actor/:personId`, `recently-added`, `favorites`, `recent`, `downloads`) — `libs/portal/xtream/feature/src/lib/xtream-feature.routes.ts`\n- Stalker portal: `/workspace/stalker/:id` (children: `itv`, `vod`, `radio`, `series`, `favorites`, `recent`, `search`, `actor/:personId`, `downloads`) — `libs/portal/stalker/feature/src/lib/stalker-feature.routes.ts`\n- Global collections: `/workspace/global-favorites`, `/workspace/global-recent`\n- Global search: `/workspace/search` (Electron-only; a guard redirects the PWA to `/workspace/sources`)\n- Downloads: `/workspace/downloads` with focused\n `/workspace/downloads/:downloadId`; source-scoped equivalents are\n `/workspace/xtreams/:id/downloads/:downloadId` and\n `/workspace/stalker/:id/downloads/:downloadId`. Focused download details hide\n the workspace context panel.\n- Settings: `/workspace/settings/:section` — one page per section (`general`, `playback`, `epg`, `dashboard`, `remote-control`, `tmdb`, `backup`, `reset`, `about`); `/workspace/settings` redirects to `general`, unknown or capability-gated sections redirect there too, and `/settings` redirects into the workspace. The shared form lives on the parent `SettingsComponent`, so edits survive section switches; a floating unsaved-changes bar (Save/Discard) replaces the old always-visible footer Save button. Leaving the settings AREA with a dirty form triggers `settingsUnsavedChangesGuard` (canDeactivate) and a save/discard/stay dialog — section switches deliberately bypass it, and a failed save cancels the navigation. Non-router exits are covered too: `SettingsUnloadGuardService` (provided by `SettingsComponent`) arms a `beforeunload` handler while the form is dirty (native leave prompt in the PWA) and arms an Electron main-process close guard (`window-close-guard.service.ts`) for the whole settings mount — mount-long on purpose, since arming on the first edit would race the close it protects against. The guard intercepts window close/app quit before `beforeunload` fires and completes the original intent only after the renderer confirms through the same dialog (a pristine form auto-confirms); Electron reloads are cancelled and re-triggered the same way, a failed save always keeps the window open, and installing an app update suspends the whole guard so the updater's quit passes unchallenged — every install entry point (settings About section and the global update notification panel) must go through the root `AppUpdateInstallService`, which owns that suspend/restore choreography\n\n**Service Architecture** (Factory Pattern):\n\n- Abstract `DataService` class in `libs/services/src/lib/data.service.ts` defines the contract\n- Two environment-specific implementations:\n - `ElectronService` (`apps/web/src/app/services/electron.service.ts`) - Uses IPC to communicate with Electron backend\n - `PwaService` (`apps/web/src/app/services/pwa.service.ts`) - Uses HTTP API and IndexedDB for standalone web version\n- Factory function `DataFactory()` in `apps/web/src/app/app.config.ts` determines which implementation to inject:\n ```typescript\n if (window.electron) {\n return inject(ElectronService);\n }\n return inject(PwaService);\n ```\n\n**Data Storage (Environment-Specific)**:\n\n- **Electron**: SQLite database via Drizzle ORM (`better-sqlite3` driver)\n - Location: `~/.iptvnator/databases/iptvnator.db`\n - Full-featured relational database with foreign keys and indexes\n - Canonical schema and connection live in `libs/shared/database`\n- **PWA (Web)**: IndexedDB via `ngx-indexed-db`\n - Browser-based NoSQL storage\n - Same schema structure but implemented in IndexedDB\n - Limited by browser storage quotas\n\n**TypeScript File Size Rule**:\n\nKeep production TypeScript files under **300 lines**. Hard maximum is\n**350–400 lines**, and CI enforces the 400. Blank lines and comments do not\ncount toward it, so documenting a file never costs you headroom. Tests\n(`**/*.spec.ts`, `**/*.e2e.ts`, `apps/*-e2e/**`) are held to 1200 instead — the\nguidance below is about production code.\n\n- When creating new files, design them to stay within this limit from the start.\n- When adding a feature to an existing file that would push it past 350 lines, **refactor first**: extract helpers, sub-services, or feature modules before adding the new code.\n- When you notice a file already exceeds 350 lines, **proactively suggest a refactoring** (or perform it if the change is straightforward) — even if the immediate task is small.\n\nTypical split strategies:\n\n- Angular components: extract child components, move logic to a dedicated service or store feature\n- Signal store features: split into smaller `with*` feature functions in separate files\n- Services: split by responsibility (e.g. separate API, transformation, and state concerns)\n- Utility files: group by domain and export from a barrel `index.ts`\n\nThis rule exists to keep the codebase navigable and reviewable. A 150-line file is always preferable to a 500-line file.\n\n---\n\n**Angular Coding Standards**:\n\nThis project uses modern Angular signal-based APIs and patterns. **ALWAYS** use the following:\n\n- **Component Queries**: Use `viewChild()`, `viewChildren()`, `contentChild()`, `contentChildren()` instead of `@ViewChild`, `@ViewChildren`, `@ContentChild`, `@ContentChildren` decorators\n\n ```typescript\n // ✅ Correct - Signal-based\n readonly menu = viewChild.required('menuRef');\n readonly items = viewChildren('item');\n\n // ❌ Incorrect - Old decorator syntax\n @ViewChild('menuRef') menu!: MatMenu;\n @ViewChildren('item') items!: QueryList;\n ```\n\n **Important**: When using signals in templates with properties that expect non-signal values, unwrap the signal by calling it:\n\n ```html\n \n \n\n \n \n ```\n\n- **Component Inputs/Outputs**: Use `input()` and `output()` functions instead of `@Input()` and `@Output()` decorators\n\n ```typescript\n // ✅ Correct - Signal-based\n readonly title = input.required();\n readonly size = input(10); // with default value\n readonly clicked = output();\n\n // ❌ Incorrect - Old decorator syntax\n @Input({ required: true }) title!: string;\n @Input() size = 10;\n @Output() clicked = new EventEmitter();\n ```\n\n- **Reactive State**: Use signal primitives for reactive state management\n\n ```typescript\n // ✅ Use signal(), computed(), effect(), linkedSignal()\n readonly count = signal(0);\n readonly doubled = computed(() => this.count() * 2);\n\n constructor() {\n effect(() => {\n console.log('Count changed:', this.count());\n });\n }\n ```\n\n- **Host Bindings**: Use `@HostBinding()` and `@HostListener()` decorators (these don't have signal equivalents yet)\n\n ```typescript\n @HostBinding('class.active') get isActive() { return this.active(); }\n @HostListener('click') onClick() { /* ... */ }\n ```\n\n- **Control Flow**: Use `@if`, `@for`, `@switch` instead of `*ngIf`, `*ngFor`, `*ngSwitch`\n\n ```typescript\n // ✅ Correct - Modern syntax\n @if (isLoggedIn()) {\n

Welcome!

\n }\n\n @for (item of items(); track item.id) {\n
  • {{ item.name }}
    • \n }\n\n // ❌ Incorrect - Old syntax\n

    Welcome!

    \n
  • {{ item.name }}
    • \n ```\n\n### Backend Architecture (Electron)\n\n**Main Entry**: `apps/electron-backend/src/main.ts`\n\n- Bootstraps Electron app and initializes database\n- Registers event handlers for IPC communication\n- Holds a single-instance lock (`app/services/single-instance.ts`), requested after the `userData` override so E2E runs with their own data dir keep independent locks. A second launch quits and focuses the running window; concurrent instances would otherwise share a Chromium profile whose IndexedDB only one of them can lock, silently breaking renderer-side settings persistence. `IPTVNATOR_ALLOW_MULTIPLE_INSTANCES=1` opts out for local debugging. The guard also forwards that launch's argv and working directory, so `iptvnator playlist.m3u` against a running app opens the playlist instead of being discarded.\n\n**Database**:\n\n- **ORM**: Drizzle ORM with `better-sqlite3` (local SQLite file)\n- **Location**: `~/.iptvnator/databases/iptvnator.db` (avoids spaces in path)\n- **Schema** (`libs/shared/database/src/lib/schema.ts` — canonical; `apps/electron-backend/src/app/database/schema.ts` is a backwards-compat re-export shim):\n - `playlists` - Playlist metadata (M3U, Xtream, Stalker)\n - `categories` - Content categories (live, movies, series)\n - `content` - Streams/VOD/series items. Besides the catalog fields it carries what a detail view learned and handed back: `backdrop_url`, plus the TMDB identity (`tmdb_id`, `release_year`, `original_title`) that lets an activity row repeat the detail view's lookup instead of rebuilding a weaker one from the display title\n - `favorites` - User favorites\n - `recentlyViewed` - Watch history\n - `epgChannels`, `epgPrograms` - Persisted EPG data\n - `epgChannelMappings` (`epg_channel_mappings`) - Manual EPG channel mappings (defined in `epg-mapping.schema.ts`, re-exported by `schema.ts`)\n - `playbackPositions` - Resume positions\n - `downloads` - Download manager state\n - `appState` - Key-value app state (also tracks one-off data migrations)\n - `tmdbMetadata` - TMDB enrichment cache (details payloads + search match resolutions, keyed by media type/lookup key/language)\n - `vodSourcePins` (`vod_source_pins`) - VOD multi-source per-movie preferred playlist, keyed by a portal-agnostic match key (defined in `vod-source-pins.schema.ts`, re-exported by `schema.ts`)\n- **Connection**: `libs/shared/database/src/lib/connection.ts`\n - `createTables()` auto-creates tables on init (`CREATE TABLE IF NOT EXISTS`)\n - Provides full read-write access for `electron-backend` and a read-only mode\n - A root `drizzle.config.ts` configures Drizzle Kit tooling (points at the schema via the compat shim)\n\n**IPC Communication**:\n\n- **Preload script**: `apps/electron-backend/src/app/api/main.preload.ts`\n - Exposes `window.electron` API via `contextBridge`\n - All IPC channels defined here (playlist operations, EPG, database CRUD, external players, etc.)\n - The canonical TypeScript contract is `ElectronBridgeApi` in `libs/shared/interfaces/src/lib/electron-api.interface.ts`; `global.d.ts`, `apps/web/src/typings.d.ts`, and `main.preload.ts` must reference this shared type instead of maintaining separate method lists.\n- **Event handlers**: `apps/electron-backend/src/app/events/`\n - `database.events.ts` - Database CRUD operations\n - `playlist.events.ts` - Playlist import/update\n - `playlist-open.events.ts` - Playlist files handed over by the OS (argv, file association, macOS `open-file`); the queue itself lives in `services/playlist-open-request.ts`\n - `epg.events.ts` - EPG IPC registration; freshness/fetch orchestration lives in `epg-fetch.service.ts`, manual channel-mapping resolution and CRUD in `epg-mapping.service.ts`, worker lifecycle in `epg-worker.service.ts`, DB lookups in `epg-query.service.ts`\n - `xtream.events.ts` - Xtream Codes API\n - `stalker.events.ts` - Stalker portal API\n - `connectivity-guard.events.ts` - `CONNECTIVITY_GUARD_RESET`: forgets the connection failures recorded for a portal host. Both portal handlers above run every request through the per-host circuit breaker (rules in `@iptvnator/shared/host-health`, process-wide instance in `util/host-connectivity-guard.ts`; the web backend runs the same breaker over its proxy routes) — after 2 consecutive connection-level failures (no HTTP response; `ETIMEDOUT`/`ENOTFOUND`/`ECONNREFUSED`/… but never `ECONNRESET`) requests to that endpoint fail immediately for 30 s. The key is `URL.origin`, not `URL.host`, which would give `http://panel` and `https://panel` one shared record and let a dead TLS listener fast-fail the working HTTP one instead of hanging the full 30 s/15 s axios timeout again, with one half-open trial request afterwards. Any HTTP response (4xx and 5xx included) clears the record. The refusal is a real `Error` whose wording is a renderer contract (`buildHostConnectivityFastFailMessage` in `libs/shared/interfaces`): it must carry no `HTTP Error `, no timeout wording and none of the auth phrases, or Stalker endpoint discovery misclassifies it and lazy portal repair fires against a host just declared dead. Discovery probes are exempt via the `skipConnectionGuard` payload flag (bypass + no failure counting, but successes still clear the record). Every user-driven retry/refresh that issues portal requests must reset BEFORE its first request, or the affordance fast-fails and looks broken; automatic and first-load paths deliberately do not reset. Current senders: Xtream content-gate Retry, Stalker catalog append retry (`retryContentPage`), Stalker search-page retry, `StalkerItvCacheService.refresh()` (Live TV refresh), both account-info dialogs' Retry, the destructive Xtream refresh (`XtreamRefreshFlowService`, before it deletes the cached catalog — one flow shared by both entry points, `PlaylistRefreshActionService.refreshXtream()` and `RecentPlaylistsComponent.refreshXtreamPlaylist()`, which supply only a progress reporter), `StalkerPortalDiscoveryService.discover()`, and `PortalStatusService` on `skipCache`. Kill switch: `IPTVNATOR_DISABLE_CONNECTIVITY_GUARD=1`. Contract: `docs/architecture/host-connectivity-guard.md`\n - `player.events.ts` - External player IPC registration; MPV/VLC lifecycle logic lives in `mpv-session.service.ts`, `vlc-session.service.ts`, and shared `external-player-*` helpers\n - `settings.events.ts` - App settings\n - `electron.events.ts` - App version, etc.\n\n**Workers** (`apps/electron-backend/src/app/workers/`):\n\n- EPG parsing: `epg-parser.worker.ts`; main-process worker lifecycle is coordinated from `apps/electron-backend/src/app/events/epg-worker.service.ts`\n- Non-EPG SQLite work: `database.worker.ts` (see `docs/architecture/sqlite-db-worker.md`)\n- Playlist refresh: `playlist-refresh.worker.ts`; explicit cancellation is main-process-owned and terminates the one-shot worker before acknowledging `PLAYLIST_CANCEL_REFRESH` (see `docs/architecture/m3u-playlist-module.md`)\n\n### Key Features\n\n**Playlist Support**:\n\n- M3U/M3U8 files (local or URL)\n- Xtream Codes API (`username`, `password`, `serverUrl`)\n- Stalker portal (`macAddress`, `url`)\n\n**Stalker playback links**: `create_link` runs only when the catalog row sets\n`use_http_tmp_link` or `use_load_balancing`; otherwise the static `cmd` plays\ndirectly. One helper decides\n(`resolveStalkerStaticPlaybackUrl` in\n`libs/portal/stalker/data-access/.../stalker-link-semantics.utils.ts`), applied\nby `fetchStalkerPlaybackLink()` for ITV/VOD/radio and by\n`StreamResolverService` for Favorites/Recently Viewed. It falls back to\n`create_link` for anything it cannot resolve alone: no row to read flags from,\na relative/query-only command (the VOD `has_files` rewrite), a non-HTTP scheme,\nor a loopback host; an episode (`series` set) always mints, since the parameter\nselects the episode server-side. Temporary links live ~5 s, so no resolved URL\nis persisted or replayed — favorites and recently-viewed store the `cmd`,\nplayback positions store ids, and the main-process context map stores headers\nkeyed by origin+path. Downloads are the one exception (they must retry a URL).\n`forced_storage`/`play_token` are deliberately unwired. Contract:\n`docs/architecture/stalker-portal.md` (\"Playback Link Resolution\").\n\n**Opening a playlist from the OS** (Electron only): a `.m3u`/`.m3u8` path passed\non the command line, opened through a file association, or delivered by macOS'\n`open-file` event is normalized to an absolute path in the main process\n(`services/playlist-open-request.ts`) and queued there. The renderer\n(`apps/web/src/app/services/playlist-open-request.service.ts`) subscribes to the\n`OPEN_FILE` push **before** calling `announcePlaylistOpenListener`, which is\nwhat makes the main process flush. `OPEN_FILE` is the only way out of the\nqueue, and a request stays there until the renderer confirms receipt via\n`acknowledgePlaylistOpenRequest` — `webContents.send()` returns before the\nlistener runs, and a reload or dead render process keeps the `WebContents`\nalive, so a successful push is not proof of delivery. Anything unacknowledged\nis replayed to the next renderer that announces itself. The renderer\nimports them on a single promise chain so a burst arrives in a deterministic\norder. `addPlaylist$` in `libs/m3u-state` uses `concatMap` (not `switchMap`)\nfor the same reason: each action carries a different playlist, so a newer add\nmust never cancel an older one's write, EPG fetch and navigation. The import\nitself reuses the normal file path\n(`updatePlaylistFromFilePath` → `PlaylistActions.addPlaylist`), so persistence,\nplaylist-scoped EPG, and the navigation to the new playlist all behave exactly\nlike a dialog import.\n\nThe OS-level registration that makes those paths reachable is\n`fileAssociations` in `electron-builder.json` — one entry per extension, each\nwith its own `mimeType`. Electron Builder derives all three platform\nregistrations from it: macOS `CFBundleDocumentTypes` (which is what makes\n`open-file` fire from Finder), the NSIS registry entries, and, on Linux, the\ndesktop entry's `MimeType` plus `/usr/share/mime/packages/iptvnator.xml` for\ndeb/rpm/pacman. Two traps: it assigns the derived `MimeType` _after_ spreading\n`linux.desktop.entry`, so declaring `MimeType` there is silently overwritten and\nmust not be used; and it appends `%U` to `Exec`, so Linux file managers hand\nover percent-encoded `file://` URIs rather than paths —\n`createPlaylistOpenRequest` decodes them before the extension check. `%U` is\nalso the _plural_ exec code, so a multi-file selection arrives as one launch\nwith one argument per file; `extractPlaylistOpenRequestsFromArgv` returns all\nof them and `enqueueAll` queues the batch, because stopping at the first match\nwould silently drop the rest of the selection. Adding an exec code to\n`linux.executableArgs` would suppress the `%U` but also pass that code to the\napp as a real argument, so it is not an option.\n\n**Video Players**:\n\n- Built-in web players: HTML5+hls.js, Video.js, and ArtPlayer\n- mpegts.js `1.8.1` errors from all three built-in players cross one\n version-locked structured evidence boundary in `libs/playback/util`. It\n retains only exact public type/detail pairs, pair-derived stage/failure,\n terminal disposition, and a\n validated HTTP 4xx/5xx status; raw messages and arbitrary `info` never reach\n stored or rendered diagnostics. HTTP/network failures avoid false decoder\n recommendations, while exact format, codec, truncated-stream, and\n MediaSource failures retain actionable recovery guidance. This diagnostic\n layer remains separate from the shared `PlayerController` controls contract.\n- Browser playback diagnostics and recovery policy live in\n `libs/playback/util` and are exported by `@iptvnator/playback/util`.\n Public engine errors cross allowlisted sanitizers into a\n `PlaybackDiagnostic`; `recommendPlaybackRecovery(context)` then ranks at\n most three actions, and `WebPlayerViewComponent` executes only the action\n the user selects. The policy is a sibling of `PlayerController`; shared\n controls only gate interaction while the diagnostic panel is visible.\n `WebPlayerViewComponent` owns a host-derived content-session key that is\n stable for the mounted logical selection, attempted target IDs, the temporary\n player override, and VOD handoff position. Its `PlaybackBinding` is exactly\n `{ generation, target }`, while every source/target/reload application uses a\n fieldless opaque `Symbol` token. Diagnostic storage uses a separate fieldless\n intent `Symbol`, and source applications advance a third fieldless revision\n `Symbol` that clears only the VOD handoff position; target-only switches and\n Retry leave that revision stable. None of these ownership primitives contains\n URLs, headers, DRM material, or credentials. The application effect\n synchronizes the content session before tracking intent, so clearing a\n temporary player override cannot schedule a duplicate application or header\n handoff. Every application start clears both the diagnostic owner and backing\n signal before asynchronous header setup; a current false result or rejection\n leaves them clear, and a stale completion cannot erase a newer owned\n diagnostic. Each\n rendered web or Embedded MPV application captures its nullable binding, the\n application and source-revision tokens, and live/VOD flag; a time update\n changes resume state only while that exact capture still owns the current\n application. A recommended built-in\n player temporarily\n outranks the host override and saved player for that mounted content session,\n never mutates `Settings.player`, and resumes finite VOD position on a\n best-effort basis; live playback returns to the live edge. Retry and\n alternative sources preserve attempts, while a different content-session key\n or component teardown resets them. Recovery recommendations never\n auto-switch, persist history, learn across sessions, or emit telemetry.\n The policy projects attempted inline target IDs through the validated\n canonical source/target capabilities and excludes every attempted engine\n family, so HTML5 and ArtPlayer are not separate hls.js recoveries. Network\n and generic unknown evidence fail closed to Retry/alternative source; the\n exact Shaka browser-unsupported preflight marker is the sole unknown-code\n exception. PWA capability suppresses managed MPV/VLC, and ClearKey/KODIPROP\n DRM suppresses external targets because its payload is not transferable. Raw\n engine messages, arbitrary data, and credentials never enter recommendation\n evidence or ownership state. MPV/VLC actions remain mounted after an attempt\n and expose credential-free per-target launching/started/playing/error state;\n only an exact Electron `playing` update is labelled Playing. One handshake is\n allowed at a time. The renderer claims the credential-free content identity\n before awaiting Electron, so primary Play is disabled and a launching or\n closable-error alternative remains owned before the controller commits it.\n Every route action that can start the same external playback, including\n Restart and the provider-source shortcut, observes that local pre-IPC guard.\n The Xtream VOD diagnostic-fallback handler records the same route-scoped\n destination and pending generation before invoking MPV/VLC, so route reuse\n cannot orphan that process outside the next route's close-before-play path.\n Its fieldless intent is bound to the exact session returned\n by the source owner's launch promise, so a late timed-out attempt cannot take\n over a retry; later global updates must match that ID. A replacement waits for\n confirmed teardown of the tracked external process, applies the old exact\n close before launch, and cancels an unlaunched handoff if diagnostic ownership\n changes. Process teardown has bounded graceful and forced confirmation\n windows, and reusable MPV bounds the IPC command that precedes them; if any\n stage cannot reach a confirmed exit, the exact session stays live and the\n replacement fails closed instead of overlapping it. A process-wide teardown\n gate starts before any potentially slow teardown preparation, including VLC\n position flush and a reused player's protocol quit, and rejects every\n MPV/VLC spawn until that exact child reports exit. If bounded\n teardown fails while a fresh launch is still pending, that launch IPC rejects\n and the exact session remains a closable error instead of hanging forever.\n If a pre-content reuse failure has no still-live displaced session to restore,\n the replacement error keeps its attached closer so Stop can retry the orphaned\n child teardown. A terminal error without a closer is never restorable.\n A failed close is single-flight only while its promise is pending: Stop can\n retry the same exact child after a bounded confirmation failure. Reuse maps\n the child to its current content session, so a stale older closer becomes a\n no-op instead of terminating a newer `loadfile`/VLC enqueue handoff.\n A duplicate close for an already closed session returns its terminal snapshot\n without re-entering the saved closer, and a late process error cannot revive\n that terminal session. Reused MPV commands are bound to the socket captured\n for that exact child, so a later process cannot inherit a stale protocol quit.\n Stop observed before a pending MPV content command or VLC enqueue command\n prevents that command from dispatching. A source handoff fails closed while\n a live session has no closer (`canClose: false`); renderer Dismiss is not\n teardown confirmation. That denied handoff advances neither the multi-source\n switch token nor the playback generation, so it cannot cancel the sole launch\n already in flight.\n VLC rechecks the gate at each concrete spawn after port allocation or reuse\n work; if a post-start fallback is blocked there, the opened session becomes\n an error rather than retaining a false started status. A failed RC-port\n allocation never claims reuse ownership, so the fallback VLC child retains\n its exact one-shot closer.\n Reuse failures before a content command restore the globally displaced\n renderer session, not the reusable process's prior owner, and only while the\n exact displaced-session ID is still active; after\n `loadfile`/VLC `clear` is dispatched,\n the replacement owns the process and remains a closable error instead of\n restoring stale content metadata. Stop during an in-flight MPV or VLC reuse\n command, including during failed-command teardown or the subsequent VLC\n fallback port-allocation wait, settles that exact close without falling\n through to a fresh spawn;\n a stopped VLC spawn error that reports only `close` also settles its original\n launch IPC with the exact closed session;\n a fresh fallback retires the old child's exit under its prior session so it\n cannot close the replacement. Source handoffs recheck ownership after launch\n and accept only `opened`/`playing`; a stale returned session is closed exactly\n and a Stop-returned `closed` session is never committed. If that exact stale\n close fails, its credential-free destination owner is retained for the next\n close attempt. Retained destination ownership is scoped to the initiating\n playlist/VOD route key, so route reuse cannot expose Stop for the previous\n movie's external session. Play/Resume capture that route key before awaiting\n close and cancel if navigation changes it; a late diagnostic fallback closes\n its exact returned session instead of adopting it on the new route. They\n supersede an older source resolution before awaiting the shared\n close-before-replacement path, and accepting a diagnostic fallback retires\n the same older resolution before opening MPV/VLC. They publish the route-source\n badge, caption evidence, and position only after start succeeds.\n Closable errors still participate in every replacement close and keep Stop as\n the global dock's only teardown affordance; Dismiss is reserved for terminal\n errors that have no closer. The shared `isLiveExternalPlayerSession` predicate\n keeps M3U and series ownership while\n such an error can still be stopped; consumers must not treat every `error`\n status as terminal.\n If the local handshake times out after an exact Electron session is known,\n that ID remains\n correlated so a later exact update can recover the UI. The global dock mirrors\n those statuses, keeps closable errors visible until Stop confirms teardown and\n terminal errors visible until dismissal, and intentionally has no retry because\n it does not own the original launch headers or credentials.\n- DASH + ClearKey (M3U module): `.mpd` channels play through a lazily loaded\n Shaka Player source engine inside the HTML5 and ArtPlayer components (no new\n player in settings). ClearKey keys come from `#KODIPROP:inputstream.adaptive.*`\n lines, post-processed into `Channel.drm` by `extractDrmFromRaw()` in\n `libs/shared/m3u-utils` (hooked in `createPlaylistObject()`, covering all\n import paths). DASH channels always play inline: `isDashChannel()` bypasses\n the external-player setting (radio precedent) and routes Video.js/MPV/VLC/\n embedded-MPV users to the HTML5 player via `playerOverride` (ArtPlayer keeps\n ArtPlayer). Unsupported license types (Widevine/PlayReady — out of scope,\n need the castLabs Electron fork) surface a DRM playback diagnostic instead\n of crashing. ClearKey EME works in stock Electron. Engine:\n `libs/ui/playback/src/lib/shaka-engine/`. Its DOM-free Shaka `5.2.4`\n diagnostic boundary lives in `libs/playback/util`; it version-locks public\n severity/category/code evidence, ignores\n recoverable error events, treats rejected loads as terminal lifecycle\n outcomes, preserves exact public DASH text-parser category/code evidence with\n unknown stage/failure, and never retains or renders raw messages or\n `error.data`. A failed browser-support preflight stays generic-unknown but\n carries the exact app-owned\n `PlaybackRuntimeSupport.ShakaBrowserUnsupported` marker, preserving managed\n external fallback only for clear transferable DASH; PWA capability and\n KODIPROP DRM still suppress it. Details in\n `docs/architecture/m3u-playlist-module.md` (\"DASH + ClearKey Playback\").\n- External players: MPV, VLC (via IPC to Electron backend)\n- Display sleep during playback: `PlaybackKeepAwakeService`\n (`apps/web/src/app/services/playback-keep-awake.service.ts`) watches every\n `