prismcast 1.1.0 → 1.2.1

package/dist/config/sites.js

@@ -0,0 +1,350 @@
+import { extractDomain } from "../utils/index.js";
+/*
+ * Streaming sites implement their video players in wildly different ways. Some use standard HTML5 video with keyboard shortcuts, others embed players in iframes,
+ * and many have unique quirks like auto-muting or requiring specific fullscreen methods. Rather than scattering site-specific conditionals throughout the streaming
+ * code, we define "site profiles" that describe each site's behavior in a declarative way.
+ *
+ * The profile system has three components:
+ *
+ * 1. SITE_PROFILES: Named behavior configurations describing how to handle different player implementations. Profiles can inherit from other profiles using the
+ *    "extends" property, allowing us to define base profiles for common patterns (like "keyboardFullscreen" for sites using the f key) and then extend them with
+ *    site-specific variations.
+ *
+ * 2. DOMAIN_CONFIG: A mapping from domain patterns to site profiles and provider display names. When streaming a URL, we check if it matches any known domain and
+ *    use the corresponding profile. Provider display names give friendly labels (e.g., "Hulu" instead of "hulu.com") for the UI source column and provider
+ *    dropdowns. This is the primary mechanism for automatically selecting the right behavior and generating friendly display names.
+ *
+ * 3. Channel-level profile hints: Individual channel definitions can specify an explicit profile name, overriding URL-based detection. This is useful when a
+ *    channel's URL doesn't match the expected domain pattern, or when the same domain serves multiple channel types that need different handling.
+ *
+ * Profile resolution happens at stream startup and the resolved profile is passed through the entire streaming pipeline. The profile flags control:
+ * - How fullscreen is triggered (keyboard shortcut vs JavaScript API)
+ * - Whether to search for video elements in iframes
+ * - Which video element to select when multiple exist
+ * - Whether to wait for network activity to settle before playback
+ * - Whether to lock volume properties to prevent auto-muting
+ * - Whether the page is static content (no video element expected)
+ *
+ * When adding support for a new streaming site, first check if an existing profile matches its behavior. Only create a new profile if the site requires unique
+ * handling not covered by existing profiles.
+ */
+/*
+ * Each profile defines a set of behavior flags that control how we interact with the video player. Profiles are organized in an inheritance hierarchy based on
+ * behavior patterns rather than site ownership. This makes it easier to identify the right profile when adding new channels.
+ *
+ * Base profiles (no extends):
+ * - keyboardFullscreen: Sites using the f key for fullscreen toggle
+ * - fullscreenApi: Sites requiring the JavaScript requestFullscreen() API
+ * - staticPage: Non-video pages captured as static visual content
+ *
+ * Derived profiles (extends a base):
+ * - keyboardDynamic: Keyboard fullscreen + network idle wait (extends keyboardFullscreen)
+ * - keyboardMultiVideo: Keyboard fullscreen + multi-video selection (extends keyboardFullscreen)
+ * - keyboardIframe: Keyboard fullscreen + iframe handling (extends keyboardFullscreen)
+ * - keyboardDynamicMultiVideo: Keyboard + network idle + multi-video selection (extends keyboardDynamic)
+ * - clickToPlayKeyboard: Click to start playback + keyboard fullscreen (extends keyboardFullscreen)
+ * - brightcove: Brightcove players using API fullscreen + network idle wait (extends fullscreenApi)
+ * - clickToPlayApi: Click to start playback + API fullscreen (extends fullscreenApi)
+ * - disneyNow: DisneyNOW player with play button overlay + multi-video (extends clickToPlayApi)
+ * - embeddedPlayer: Iframe-based players using fullscreen API (extends fullscreenApi)
+ * - apiMultiVideo: API fullscreen + multi-video + tile-based channel selection (extends fullscreenApi)
+ * - huluLive: Hulu Live TV with guide grid channel selection + fullscreen button (extends fullscreenApi)
+ * - embeddedDynamicMultiVideo: Embedded + network idle + multi-video selection (extends embeddedPlayer)
+ * - embeddedVolumeLock: Embedded + volume property locking (extends embeddedPlayer)
+ * - youtubeTV: YouTube TV with non-virtualized EPG grid channel selection (extends fullscreenApi)
+ *
+ * Each profile includes a description field documenting its purpose. This is metadata only - it's stripped during profile resolution and exists purely for
+ * documentation.
+ */
+export const SITE_PROFILES = {
+    // Profile for multi-channel live TV pages that present a grid or shelf of live channel tiles requiring tile-based selection followed by a play button click. Uses
+    // the fullscreen API and multi-video selection to find the actively playing stream after channel selection. Does not use iframe handling or network idle wait
+    // because these sites serve video directly in the main page and have persistent connections that prevent network idle.
+    apiMultiVideo: {
+        category: "multiChannel",
+        channelSelection: { strategy: "tileClick" },
+        description: "Multi-channel sites with tile-based channel grid. Requires Channel Selector set to the CSS selector for the channel tile.",
+        extends: "fullscreenApi",
+        selectReadyVideo: true,
+        summary: "Multi-channel (tile selection, needs selector)"
+    },
+    // Profile for sites using the Brightcove player platform. Brightcove players require waiting for network activity to settle before the video player is fully
+    // initialized. The player dynamically loads its configuration and stream manifest, so waitForNetworkIdle ensures we don't try to interact with the player before
+    // it's ready. Uses the JavaScript fullscreen API rather than keyboard shortcuts because Brightcove intercepts keyboard events.
+    brightcove: {
+        category: "api",
+        description: "Brightcove player sites requiring network idle wait and API fullscreen.",
+        extends: "fullscreenApi",
+        summary: "Brightcove players (network wait)",
+        waitForNetworkIdle: true
+    },
+    // Profile for sites that require clicking to start playback. Some players don't autoplay and need user interaction to begin. Uses the JavaScript fullscreen API.
+    // Set clickSelector in the profile or channel definition to specify a play button element; otherwise clicks the video element directly.
+    clickToPlayApi: {
+        category: "api",
+        clickToPlay: true,
+        description: "Sites requiring a click to start playback, using the JavaScript fullscreen API. Use clickSelector for play button overlays.",
+        extends: "fullscreenApi",
+        summary: "Click-to-play (API fullscreen)"
+    },
+    // Profile for sites that require clicking to start playback, using keyboard 'f' for fullscreen. Use this when clickToPlayApi doesn't work for fullscreen but the
+    // site responds to the 'f' key. Set clickSelector in the profile or channel definition to specify a play button element.
+    clickToPlayKeyboard: {
+        category: "keyboard",
+        clickToPlay: true,
+        description: "Sites requiring a click to start playback, using the 'f' key for fullscreen. Use clickSelector for play button overlays.",
+        extends: "keyboardFullscreen",
+        summary: "Click-to-play ('f' key fullscreen)"
+    },
+    // Profile for DisneyNOW (disneynow.com) which has a play button overlay that must be clicked to start playback and multiple video elements on the page.
+    disneyNow: {
+        category: "api",
+        clickSelector: ".overlay__button button",
+        description: "DisneyNOW player with play button overlay and multiple video elements.",
+        extends: "clickToPlayApi",
+        selectReadyVideo: true,
+        summary: "DisneyNOW player"
+    },
+    // Profile for iframe-embedded players that also have multiple video elements (ads, placeholders, main content) and need network activity to settle. The
+    // selectReadyVideo flag ensures we find the video with actual content rather than an ad placeholder. Combines iframe handling with API-based fullscreen.
+    embeddedDynamicMultiVideo: {
+        category: "api",
+        description: "Iframe-embedded players with multiple video elements requiring network idle wait.",
+        extends: "embeddedPlayer",
+        selectReadyVideo: true,
+        summary: "Embedded multi-video (network wait)",
+        waitForNetworkIdle: true
+    },
+    // Intermediate profile for sites that both embed their player in an iframe AND require the JavaScript fullscreen API. Many modern players use this architecture
+    // to isolate ad content and use programmatic fullscreen rather than keyboard shortcuts. This profile combines iframe handling with API-based fullscreen.
+    embeddedPlayer: {
+        category: "api",
+        description: "Intermediate base profile for iframe-embedded players using fullscreen API.",
+        extends: "fullscreenApi",
+        needsIframeHandling: true,
+        summary: "Embedded iframe players"
+    },
+    // Profile for iframe-embedded players that aggressively mute audio after page load - likely to comply with autoplay policies or for accessibility reasons. Some
+    // sites set video.muted = true even after we unmute it. The lockVolumeProperties flag uses Object.defineProperty to override the muted and volume getters/setters,
+    // preventing the site from re-muting the video.
+    embeddedVolumeLock: {
+        category: "api",
+        description: "Iframe-embedded players that aggressively mute audio after page load.",
+        extends: "embeddedPlayer",
+        lockVolumeProperties: true,
+        summary: "Embedded players that auto-mute"
+    },
+    // Base profile for sites that require the JavaScript fullscreen API (element.requestFullscreen()) instead of keyboard shortcuts. Many modern players intercept
+    // keyboard events for their own controls, making the f key unreliable. Calling requestFullscreen() directly on the video element bypasses the player's keyboard
+    // handling and reliably enters fullscreen mode.
+    fullscreenApi: {
+        category: "api",
+        description: "Base profile for sites requiring the JavaScript fullscreen API.",
+        summary: "Sites needing JavaScript fullscreen",
+        useRequestFullscreen: true
+    },
+    // Profile for HBO Max live channels (play.hbomax.com). The HBO brand page contains a "Distribution Channels" rail showing all 5 live linear channels (HBO, HBO
+    // Hits, HBO Drama, HBO Comedy, HBO Movies) as tiles. The hboGrid strategy discovers the HBO tab URL from the homepage menu bar, navigates to it, then scrapes the
+    // channel rail for the watch URL matching the channelSelector name. Extends fullscreenApi for requestFullscreen() behavior inherited by the watch page.
+    hboMax: {
+        category: "multiChannel",
+        channelSelection: { strategy: "hboGrid" },
+        description: "HBO Max with live channel rail selection. Set Channel Selector to the channel name (e.g., HBO, HBO Hits).",
+        extends: "fullscreenApi",
+        summary: "HBO Max (live channels, needs selector)"
+    },
+    // Profile for Hulu Live TV which presents a guide grid of live channels. The channel list is revealed by clicking a tab (listSelector), then the desired channel
+    // is found by matching img.alt text. Uses the fullscreen API (inherited from fullscreenApi) plus a dedicated fullscreen button selector for the player's native
+    // maximize control. Requires selectReadyVideo because the page may have multiple video elements (ads, previews, main content). Uses waitForNetworkIdle because
+    // Hulu's SPA has heavy async initialization that often prevents the load event from firing within the retryOperation timeout; the graceful networkidle2 fallback
+    // in navigateToPage() allows execution to continue to channel selection even when background requests are still pending.
+    huluLive: {
+        category: "multiChannel",
+        channelSelection: { listSelector: "#CHANNELS", playSelector: "[data-testid=\"generic-tile-thumbnail\"]", strategy: "guideGrid" },
+        description: "Hulu Live TV with guide grid channel selection. Requires Channel Selector set to the channel name matching the guide grid image alt text.",
+        extends: "fullscreenApi",
+        fullscreenSelector: "[aria-label=\"Maximize\"]",
+        selectReadyVideo: true,
+        summary: "Hulu Live TV (guide grid, needs selector)",
+        waitForNetworkIdle: true
+    },
+    // Profile for sites that use keyboard fullscreen and also need time for network activity to settle before the player is fully initialized. These sites dynamically
+    // load their player and content. The waitForNetworkIdle flag ensures we don't try to interact with the player until all initial network requests have completed.
+    keyboardDynamic: {
+        category: "keyboard",
+        description: "Keyboard fullscreen sites requiring network idle wait for dynamic content loading.",
+        extends: "keyboardFullscreen",
+        summary: "Dynamic sites ('f' key fullscreen)",
+        waitForNetworkIdle: true
+    },
+    // Profile for multi-channel player pages that use keyboard fullscreen and need both network idle wait and multi-video selection. These pages present multiple
+    // channels to choose from, and the channelSelector property in the channel definition specifies which one to select. Extends keyboardDynamic to inherit network
+    // idle wait behavior. Uses thumbnailRow strategy for channel selection (find channel by thumbnail image URL, click adjacent show entry).
+    keyboardDynamicMultiVideo: {
+        category: "multiChannel",
+        channelSelection: { strategy: "thumbnailRow" },
+        description: "Multi-channel sites with thumbnail row layout. Requires Channel Selector set to the channel's thumbnail image URL.",
+        extends: "keyboardDynamic",
+        selectReadyVideo: true,
+        summary: "Multi-channel (thumbnail row, needs selector)"
+    },
+    // Base profile for sites that respond to the f key for fullscreen toggle. This is the most common fullscreen mechanism, following YouTube-style keyboard
+    // shortcuts. The f key is sent as a keyboard event to the page, triggering the player's built-in fullscreen toggle. This works with most standard video players.
+    keyboardFullscreen: {
+        category: "keyboard",
+        description: "Base profile for sites that respond to the f key for fullscreen toggle.",
+        fullscreenKey: "f",
+        summary: "Standard 'f' key fullscreen"
+    },
+    // Profile for sites using keyboard fullscreen with video players embedded in iframes. The video element is not directly in the main page DOM, so we need to search
+    // through all frames to find it. Once found, the player responds to the standard f key for fullscreen.
+    keyboardIframe: {
+        category: "keyboard",
+        description: "Keyboard fullscreen sites with video embedded in iframes.",
+        extends: "keyboardFullscreen",
+        needsIframeHandling: true,
+        summary: "Iframe players ('f' key fullscreen)"
+    },
+    // Profile for sites using keyboard fullscreen that load multiple video elements simultaneously - placeholder videos, ad videos, and the main content. We must find
+    // the video element that has actually loaded playable data (readyState >= 3) rather than just taking the first video element.
+    keyboardMultiVideo: {
+        category: "keyboard",
+        description: "Keyboard fullscreen sites with multiple video elements requiring ready-state selection.",
+        extends: "keyboardFullscreen",
+        selectReadyVideo: true,
+        summary: "Multi-video sites ('f' key fullscreen)"
+    },
+    // Profile for non-video pages that should be captured as static visual content. Examples include weather displays (weatherscan.net), maps (windy.com), and
+    // diagnostic pages. The noVideo flag tells the streaming code not to wait for a video element or set up playback monitoring - just capture whatever is displayed.
+    staticPage: {
+        category: "special",
+        description: "Base profile for non-video pages captured as static visual content.",
+        noVideo: true,
+        summary: "Static pages (no video)"
+    },
+    // Profile for YouTube TV (tv.youtube.com/live). The guide grid renders all ~256 channel rows in the DOM simultaneously (no virtualization), each containing a
+    // direct watch URL. The youtubeGrid strategy performs a single querySelector to find the target channel's watch link via aria-label, extracts the URL, and
+    // navigates directly — no scrolling, clicking, or timing workarounds needed. Uses selectReadyVideo because the watch page has ~36 video elements (live preview
+    // thumbnails from the guide) but only one active stream with readyState >= 3 and videoWidth > 0. Extends fullscreenApi because requestFullscreen() works
+    // directly on the active video element without gesture requirements.
+    youtubeTV: {
+        category: "multiChannel",
+        channelSelection: { strategy: "youtubeGrid" },
+        description: "YouTube TV with EPG grid channel selection. Use the guide name or a network name (e.g., NBC) for locals. PBS auto-resolves to major affiliates.",
+        extends: "fullscreenApi",
+        selectReadyVideo: true,
+        summary: "YouTube TV (guide grid, needs selector)"
+    }
+};
+/* This mapping associates domain keys with site profiles and provider display names. Most keys are concise second-level domains (e.g., "nbc.com", "foodnetwork.com")
+ * matching the output of extractDomain(). Keys can also be full hostnames (e.g., "tv.youtube.com") for subdomain-specific overrides — getDomainConfig() tries the
+ * full hostname first, then falls back to the concise domain, so "tv.youtube.com" takes precedence over "youtube.com" when the URL matches.
+ *
+ * Domains without a profile entry will use DEFAULT_SITE_PROFILE, which works for most standard video players. Domains without a provider entry will display the
+ * concise domain string (e.g., "hulu.com") in the UI.
+ */
+export const DOMAIN_CONFIG = {
+    "abc.com": { profile: "keyboardMultiVideo", provider: "ABC.com" },
+    "aetv.com": { profile: "fullscreenApi", provider: "A&E" },
+    "bet.com": { profile: "fullscreenApi", provider: "BET.com" },
+    "c-span.org": { profile: "brightcove", provider: "C-SPAN.org" },
+    "cbs.com": { profile: "keyboardIframe", provider: "CBS.com" },
+    "cnbc.com": { profile: "fullscreenApi", provider: "CNBC.com" },
+    "cnn.com": { profile: "fullscreenApi", provider: "CNN.com" },
+    "disneynow.com": { profile: "disneyNow", provider: "DisneyNOW" },
+    "disneyplus.com": { profile: "apiMultiVideo", provider: "Disney+ (Grid)" },
+    "espn.com": { profile: "keyboardMultiVideo", provider: "ESPN.com" },
+    "foodnetwork.com": { profile: "fullscreenApi", provider: "Food Network" },
+    "foxbusiness.com": { profile: "embeddedDynamicMultiVideo", provider: "Fox Business" },
+    "foxnews.com": { profile: "embeddedDynamicMultiVideo", provider: "Fox News" },
+    "foxsports.com": { profile: "fullscreenApi", provider: "Fox Sports" },
+    "france24.com": { profile: "embeddedVolumeLock", provider: "France 24" },
+    "fyi.tv": { profile: "fullscreenApi", provider: "FYI" },
+    "golfchannel.com": { profile: "fullscreenApi", provider: "Golf Channel" },
+    "hbomax.com": { profile: "hboMax", provider: "HBO Max" },
+    "history.com": { profile: "fullscreenApi", provider: "History.com" },
+    "hulu.com": { profile: "huluLive", provider: "Hulu (Grid)" },
+    "lakeshorepbs.org": { profile: "embeddedPlayer", provider: "Lakeshore PBS" },
+    "ms.now": { profile: "keyboardDynamic", provider: "MSNOW" },
+    "mylifetime.com": { profile: "fullscreenApi", provider: "Lifetime" },
+    "nationalgeographic.com": { profile: "keyboardDynamicMultiVideo", provider: "Nat Geo" },
+    "nba.com": { profile: "fullscreenApi", provider: "NBA.com" },
+    "nbc.com": { maxContinuousPlayback: 4, profile: "keyboardDynamic", provider: "NBC.com" },
+    "paramountplus.com": { profile: "fullscreenApi", provider: "Paramount+" },
+    "sling.com": { profile: "embeddedVolumeLock", provider: "Sling TV" },
+    "tbs.com": { profile: "fullscreenApi", provider: "TBS.com" },
+    "tntdrama.com": { profile: "fullscreenApi", provider: "TNT" },
+    "trutv.com": { profile: "fullscreenApi", provider: "truTV" },
+    "tv.youtube.com": { profile: "youtubeTV", provider: "YouTube TV" },
+    "usanetwork.com": { profile: "keyboardDynamicMultiVideo", provider: "USA Network (Grid)" },
+    "vh1.com": { profile: "fullscreenApi", provider: "VH1.com" },
+    "watchhallmarktv.com": { profile: "fullscreenApi", provider: "Hallmark" },
+    "weatherscan.net": { profile: "staticPage", provider: "Weatherscan" },
+    "windy.com": { profile: "staticPage", provider: "Windy" },
+    "wttw.com": { profile: "fullscreenApi", provider: "WTTW" },
+    "youtube.com": { profile: "keyboardDynamic", provider: "YouTube" }
+};
+/**
+ * Resolves a URL to its DOMAIN_CONFIG entry by trying the full hostname first for subdomain-specific overrides, then falling back to the concise domain (last two
+ * hostname parts). This allows entries like "tv.youtube.com" to override the base "youtube.com" entry when the URL matches the more-specific subdomain.
+ * @param url - The URL to resolve a domain configuration for.
+ * @returns The matching DomainConfig entry, or undefined if no match is found.
+ */
+export function getDomainConfig(url) {
+    try {
+        const hostname = new URL(url).hostname;
+        // Try the full hostname first for subdomain-specific overrides (e.g., "tv.youtube.com" before "youtube.com").
+        const hostnameMatch = DOMAIN_CONFIG[hostname];
+        if (hostnameMatch) {
+            return hostnameMatch;
+        }
+    }
+    catch {
+        // Invalid URL — fall through to concise domain lookup.
+    }
+    return DOMAIN_CONFIG[extractDomain(url)];
+}
+/* The default profile provides baseline behavior for sites not explicitly listed in the domain mapping or channel definitions. These settings work for most
+ * standard HTML5 video players that follow common conventions. Each flag is explicitly set to its default value for documentation purposes and to ensure
+ * predictable behavior - we don't rely on implicit defaults.
+ *
+ * Sites matching the default profile:
+ * - Use standard HTML5 video without iframe embedding
+ * - Have a single video element on the page
+ * - Don't require clicking to start playback
+ * - Don't auto-mute aggressively
+ * - Don't require waiting for network activity
+ * - Have video content (not static pages)
+ *
+ * Neither keyboard fullscreen nor API fullscreen is enabled by default because many sites work fine without explicit fullscreen triggering - the video is already
+ * displayed at full size in the viewport. Fullscreen is only needed when the player has visible controls or surrounding content that we want to hide.
+ */
+export const DEFAULT_SITE_PROFILE = {
+    // No channel selection - single-channel sites don't need it.
+    channelSelection: { strategy: "none" },
+    // No channel selector - this is only used for multi-channel player pages.
+    channelSelector: null,
+    // No click selector - when clickToPlay is true, click the video element by default.
+    clickSelector: null,
+    // Don't click to play - most sites start automatically or via other mechanisms.
+    clickToPlay: false,
+    // No fullscreen key - many players work without explicit fullscreen.
+    fullscreenKey: null,
+    // No fullscreen button selector - most sites don't have a dedicated fullscreen button we need to click.
+    fullscreenSelector: null,
+    // Don't lock volume properties - most sites don't aggressively mute.
+    lockVolumeProperties: false,
+    // No continuous playback limit - most sites allow indefinite streaming.
+    maxContinuousPlayback: null,
+    // Don't search iframes - assume video is in main page DOM.
+    needsIframeHandling: false,
+    // Expect video content - wait for video element.
+    noVideo: false,
+    // Use first video element - assume only one video exists.
+    selectReadyVideo: false,
+    // Don't use requestFullscreen() API.
+    useRequestFullscreen: false,
+    // Don't wait for network idle - assume player is ready on page load.
+    waitForNetworkIdle: false
+};
+//# sourceMappingURL=sites.js.map

package/dist/config/sites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites.js","sourceRoot":"","sources":["../../src/config/sites.ts"],"names":[],"mappings":"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"}

package/dist/config/userChannels.d.ts

@@ -14,6 +14,7 @@ export interface UserChannelsLoadResult {
     channels: UserChannelMap;
     parseError: boolean;
     parseErrorMessage?: string;
+    providerSelections: Record<string, string>;
 }
 /**
  * Returns the path to the user channels file.
@@ -32,12 +33,13 @@ export declare function hasChannelsParseError(): boolean;
 export declare function getChannelsParseErrorMessage(): string | undefined;
 /**
  * Loads user channels from the channels file. Returns an empty map if the file doesn't exist, and sets parseError if the file exists but contains invalid JSON.
- * @returns The loaded channels with parse status.
+ * The file can contain a special `providerSelections` key with user's provider preferences, which is extracted separately from channels.
+ * @returns The loaded channels with parse status and provider selections.
  */
 export declare function loadUserChannels(): Promise<UserChannelsLoadResult>;
 /**
  * Saves user channels to the channels file and updates the in-memory cache. Changes take effect immediately for new stream requests without requiring a server
- * restart. Creates the data directory if it doesn't exist.
+ * restart. Creates the data directory if it doesn't exist. Provider selections are also saved if any exist.
  * @param channels - The channels to save.
  * @throws If the file cannot be written.
  */
@@ -54,7 +56,7 @@ export declare function deleteUserChannel(key: string): Promise<void>;
  */
 export declare function resetUserChannels(): Promise<void>;
 /**
- * Initializes user channels by loading them from the file. This should be called once at server startup.
+ * Initializes user channels by loading them from the file. This should be called once at server startup. Also builds provider groups and loads provider selections.
  */
 export declare function initializeUserChannels(): Promise<void>;
 /**
@@ -68,6 +70,11 @@ export declare function initializeUserChannels(): Promise<void>;
  *
  * The enabled field reflects whether the channel is available for streaming. Predefined-only channels can be disabled via configuration; user and override
  * channels are always enabled.
+ *
+ * Provider variants (non-canonical keys in provider groups) are filtered out from this listing — they are accessed via the provider selection mechanism instead.
+ *
+ * IMPORTANT: This function preserves object references from PREDEFINED_CHANNELS and loadedUserChannels. The provider system (providers.ts) relies on this behavior
+ * to detect user overrides via reference comparison. Do not clone channel objects when building the listing.
  * @returns Sorted array of channel listing entries.
  */
 export declare function getChannelListing(): ChannelListingEntry[];
@@ -164,3 +171,8 @@ export interface ChannelsValidationResult {
  * @returns Validation result with errors if invalid.
  */
 export declare function validateImportedChannels(data: unknown, validProfiles: string[]): ChannelsValidationResult;
+/**
+ * Saves the current provider selections to the channels file. This triggers a full file save including all user channels.
+ * @throws If the file cannot be written.
+ */
+export declare function saveProviderSelections(): Promise<void>;

package/dist/config/userChannels.js

@@ -1,3 +1,4 @@
+import { buildProviderGroups, getProviderSelections, isProviderVariant, setProviderSelections } from "./providers.js";
 import { CONFIG } from "./index.js";
 import { LOG } from "../utils/index.js";
 import { PREDEFINED_CHANNELS } from "../channels/index.js";
@@ -5,10 +6,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 const { promises: fsPromises } = fs;
-/*
- * CHANNELS FILE PATH
- *
- * The channels file is stored in the same data directory as the config file (~/.prismcast).
+/* The channels file is stored in the same data directory as the config file (~/.prismcast).
  */
 const dataDir = path.join(os.homedir(), ".prismcast");
 const channelsFilePath = path.join(dataDir, "channels.json");
@@ -19,10 +17,7 @@ const channelsFilePath = path.join(dataDir, "channels.json");
 export function getUserChannelsFilePath() {
     return channelsFilePath;
 }
-/*
- * CHANNELS FILE OPERATIONS
- *
- * These functions handle reading and writing the channels file. All operations are async and handle errors gracefully.
+/* These functions handle reading and writing the channels file. All operations are async and handle errors gracefully.
  */
 // Module-level storage for loaded user channels. This is populated at startup and used by getAllChannels().
 let loadedUserChannels = {};
@@ -44,34 +39,54 @@ export function getChannelsParseErrorMessage() {
 }
 /**
  * Loads user channels from the channels file. Returns an empty map if the file doesn't exist, and sets parseError if the file exists but contains invalid JSON.
- * @returns The loaded channels with parse status.
+ * The file can contain a special `providerSelections` key with user's provider preferences, which is extracted separately from channels.
+ * @returns The loaded channels with parse status and provider selections.
  */
 export async function loadUserChannels() {
     try {
         const content = await fsPromises.readFile(channelsFilePath, "utf-8");
         try {
-            const channels = JSON.parse(content);
-            return { channels, parseError: false };
+            const parsed = JSON.parse(content);
+            // Extract providerSelections if present — it's not a channel, it's metadata.
+            const providerSelections = {};
+            const channels = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                if (key === "providerSelections") {
+                    // Copy provider selections if it's an object.
+                    if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
+                        for (const [selKey, selValue] of Object.entries(value)) {
+                            if (typeof selValue === "string") {
+                                providerSelections[selKey] = selValue;
+                            }
+                        }
+                    }
+                }
+                else if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
+                    // It's a channel definition.
+                    channels[key] = value;
+                }
+            }
+            return { channels, parseError: false, providerSelections };
         }
         catch (parseError) {
             const message = (parseError instanceof Error) ? parseError.message : String(parseError);
             LOG.warn("Invalid JSON in channels file %s: %s. Using predefined channels only.", channelsFilePath, message);
-            return { channels: {}, parseError: true, parseErrorMessage: message };
+            return { channels: {}, parseError: true, parseErrorMessage: message, providerSelections: {} };
         }
     }
     catch (error) {
         // File doesn't exist - this is normal, use predefined channels only.
         if (error.code === "ENOENT") {
-            return { channels: {}, parseError: false };
+            return { channels: {}, parseError: false, providerSelections: {} };
         }
         // Other read errors - log and use predefined channels.
         LOG.warn("Failed to read channels file %s: %s. Using predefined channels only.", channelsFilePath, (error instanceof Error) ? error.message : String(error));
-        return { channels: {}, parseError: false };
+        return { channels: {}, parseError: false, providerSelections: {} };
     }
 }
 /**
  * Saves user channels to the channels file and updates the in-memory cache. Changes take effect immediately for new stream requests without requiring a server
- * restart. Creates the data directory if it doesn't exist.
+ * restart. Creates the data directory if it doesn't exist. Provider selections are also saved if any exist.
  * @param channels - The channels to save.
  * @throws If the file cannot be written.
  */
@@ -84,11 +99,24 @@ export async function saveUserChannels(channels) {
     for (const key of sortedKeys) {
         sortedChannels[key] = channels[key];
     }
+    // Include provider selections if any exist.
+    const selections = getProviderSelections();
+    if (Object.keys(selections).length > 0) {
+        // Sort provider selections for consistent output.
+        const sortedSelections = {};
+        const selectionKeys = Object.keys(selections).sort();
+        for (const key of selectionKeys) {
+            sortedSelections[key] = selections[key];
+        }
+        sortedChannels.providerSelections = sortedSelections;
+    }
     // Write channels with pretty formatting for readability.
     const content = JSON.stringify(sortedChannels, null, 2);
     await fsPromises.writeFile(channelsFilePath, content + "\n", "utf-8");
     // Update in-memory cache so changes take effect immediately for new stream requests.
-    loadedUserChannels = { ...sortedChannels };
+    loadedUserChannels = { ...channels };
+    // Refresh provider groups so channelsRef reflects the new channel data. This ensures getResolvedChannel() returns correct data after modifications.
+    buildProviderGroups(getMergedChannelMap());
     // Clear any previous parse error since we're writing valid data.
     userChannelsParseError = false;
     userChannelsParseErrorMessage = undefined;
@@ -128,19 +156,21 @@ export async function resetUserChannels() {
         throw error;
     }
 }
-/*
- * CHANNEL INITIALIZATION
- *
- * User channels are loaded at server startup and stored in module-level state. This avoids repeated file reads during request handling.
+/* User channels are loaded at server startup and stored in module-level state. This avoids repeated file reads during request handling.
  */
 /**
- * Initializes user channels by loading them from the file. This should be called once at server startup.
+ * Initializes user channels by loading them from the file. This should be called once at server startup. Also builds provider groups and loads provider selections.
  */
 export async function initializeUserChannels() {
     const result = await loadUserChannels();
     loadedUserChannels = result.channels;
     userChannelsParseError = result.parseError;
     userChannelsParseErrorMessage = result.parseErrorMessage;
+    // Load provider selections from the file.
+    setProviderSelections(result.providerSelections);
+    // Build the merged channels map and then build provider groups.
+    const mergedChannels = getMergedChannelMap();
+    buildProviderGroups(mergedChannels);
     const userCount = Object.keys(loadedUserChannels).length;
     const predefinedCount = Object.keys(PREDEFINED_CHANNELS).length;
     const totalCount = userCount + predefinedCount;
@@ -151,10 +181,18 @@ export async function initializeUserChannels() {
         LOG.info("Loaded %d channels.", totalCount);
     }
 }
-/*
- * CHANNEL LISTING AND MERGING
- *
- * The getChannelListing() function is the single source of truth for merging predefined channels with user channels. It returns enriched entries with source
+/**
+ * Returns the merged channel map (predefined + user) without filtering by enabled status or provider variants. Used internally for building provider groups.
+ * @returns The complete merged channel map.
+ */
+function getMergedChannelMap() {
+    const result = { ...PREDEFINED_CHANNELS };
+    for (const [key, channel] of Object.entries(loadedUserChannels)) {
+        result[key] = channel;
+    }
+    return result;
+}
+/* The getChannelListing() function is the single source of truth for merging predefined channels with user channels. It returns enriched entries with source
  * classification and enabled status. All other channel retrieval functions that need merged data build on top of it.
  */
 /**
@@ -168,12 +206,21 @@ export async function initializeUserChannels() {
  *
  * The enabled field reflects whether the channel is available for streaming. Predefined-only channels can be disabled via configuration; user and override
  * channels are always enabled.
+ *
+ * Provider variants (non-canonical keys in provider groups) are filtered out from this listing — they are accessed via the provider selection mechanism instead.
+ *
+ * IMPORTANT: This function preserves object references from PREDEFINED_CHANNELS and loadedUserChannels. The provider system (providers.ts) relies on this behavior
+ * to detect user overrides via reference comparison. Do not clone channel objects when building the listing.
  * @returns Sorted array of channel listing entries.
  */
 export function getChannelListing() {
     const allKeys = new Set([...Object.keys(PREDEFINED_CHANNELS), ...Object.keys(loadedUserChannels)]);
     const listing = [];
     for (const key of allKeys) {
+        // Skip provider variants — they're accessed via provider selection, not as separate channels.
+        if (isProviderVariant(key)) {
+            continue;
+        }
         const isPredefined = key in PREDEFINED_CHANNELS;
         const isUser = key in loadedUserChannels;
         // Determine source classification. User channel data takes precedence on key conflicts.
@@ -243,10 +290,7 @@ export function isUserChannel(key) {
 export function isOverrideChannel(key) {
     return isPredefinedChannel(key) && isUserChannel(key);
 }
-/*
- * DISABLED PREDEFINED CHANNELS
- *
- * Users can disable predefined channels to exclude them from the playlist and block streaming. Disabled channels appear grayed out in the UI with an option to
+/* Users can disable predefined channels to exclude them from the playlist and block streaming. Disabled channels appear grayed out in the UI with an option to
  * re-enable. This is useful for users who don't want certain predefined channels cluttering their channel list.
  */
 /**
@@ -288,10 +332,7 @@ export function getPredefinedChannels() {
 export function isChannelAvailable(key) {
     return key in getAllChannels();
 }
-/*
- * CHANNEL VALIDATION
- *
- * These functions validate channel data before saving.
+/* These functions validate channel data before saving.
  */
 /**
  * Validates a channel key for format and uniqueness.
@@ -470,4 +511,15 @@ export function validateImportedChannels(data, validProfiles) {
     }
     return { channels, errors, valid: errors.length === 0 };
 }
+/* Provider selections are stored in the channels.json file alongside user channels. When a selection changes, we save the entire file (channels + selections)
+ * to persist the change.
+ */
+/**
+ * Saves the current provider selections to the channels file. This triggers a full file save including all user channels.
+ * @throws If the file cannot be written.
+ */
+export async function saveProviderSelections() {
+    // Simply save the user channels — the saveUserChannels function includes provider selections automatically.
+    await saveUserChannels(loadedUserChannels);
+}
 //# sourceMappingURL=userChannels.js.map