prismcast 1.8.0 → 1.9.0

package/dist/config/{providers.js → services.js}

@@ -1,6 +1,6 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * providers.ts: Provider group management for multi-provider channels.
+ * services.ts: Service group management for multi-service channels.
  */
 import { CHANNEL_IDENTITY_FIELDS, PREDEFINED_CHANNELS } from "../channels/index.js";
 import { DOMAIN_CONFIG, getDomainConfig } from "./sites.js";
@@ -8,24 +8,24 @@ import { LOG, extractDomain } from "../utils/index.js";
 import { getChannelEffectiveTags } from "./userChannels.js";
 import { getProfileForChannel } from "./profiles.js";
 import { getUserDomains } from "./userProfiles.js";
-/* Provider groups allow multiple streaming providers to offer the same content. For example, ESPN can be watched via ESPN.com (native) or Disney+.
+/* Service groups allow multiple streaming services to offer the same content. For example, ESPN can be watched via ESPN.com (native) or Disney+.
  *
  * All variant relationships — predefined and user-defined — are expressed via the canonicalKey field on Channel. The flattener sets canonicalKey on predefined
- * variant entries, the browse modal sets it on user variant entries, and the one-time migration stamps it on pre-existing user entries. buildProviderGroups
+ * variant entries, the browse modal sets it on user variant entries, and the one-time migration stamps it on pre-existing user entries. buildServiceGroups
  * scans all channels once and groups by canonicalKey. One field, one mechanism, one code path.
  *
- * User overrides: When a user defines a channel with the same key as a predefined channel, both versions appear in the provider dropdown. The user's custom version
+ * User overrides: When a user defines a channel with the same key as a predefined channel, both versions appear in the service dropdown. The user's custom version
  * is shown first (labeled "Custom") and is the default. The original predefined version uses a special key suffix (PREDEFINED_SUFFIX) to distinguish it from the
  * user's version. This allows users to switch between their custom definition and the original at any time.
  *
- * User selections are stored in channels.json (in the data directory) under the `providerSelections` key and persist across restarts.
+ * User selections are stored in channels.json (in the data directory) under the `serviceSelections` key and persist across restarts.
  */
 // Suffix appended to channel keys to reference the original predefined channel when a user has overridden it. For example, "espn:predefined" references the original
 // predefined ESPN channel when the user has created a custom "espn" entry.
 const PREDEFINED_SUFFIX = ":predefined";
 /**
  * Strips the :predefined suffix from a channel key if present, returning the base key. Synthetic keys like "pbs:predefined" are created when a user overrides a
- * predefined channel — the original predefined entry gets this suffix to coexist with the user's custom version in the provider dropdown. Functions that look up
+ * predefined channel — the original predefined entry gets this suffix to coexist with the user's custom version in the service dropdown. Functions that look up
  * channel data by key must strip the suffix to find the actual channel entry.
  * @param key - The channel key, possibly with :predefined suffix.
  * @returns The base key without the suffix.
@@ -33,43 +33,43 @@ const PREDEFINED_SUFFIX = ":predefined";
 function stripPredefinedSuffix(key) {
     return key.endsWith(PREDEFINED_SUFFIX) ? key.slice(0, -PREDEFINED_SUFFIX.length) : key;
 }
-// Module-level storage for provider groups, keyed by canonical channel key.
-const providerGroups = new Map();
+// Module-level storage for service groups, keyed by canonical channel key.
+const serviceGroups = new Map();
 // Reference to the channels map for inheritance resolution.
 let channelsRef = {};
-// User's provider selections, keyed by canonical channel key. Values are the selected provider key (e.g., "espn-disneyplus").
-let providerSelections = new Map();
-// Provider Tag System.
-// Module-level state for the provider filter. Empty array means "no filter" (all providers shown). Non-empty means only these tags are active.
-let enabledProviders = [];
-/**
- * Derives the provider tag for a channel from its URL domain, falling back to "direct" if no provider tag is configured. Checks the channel's explicit profile
- * first (for user-defined profiles with custom providerTag), then the URL domain via getDomainConfig().
+// User's service selections, keyed by canonical channel key. Values are the selected service key (e.g., "espn-disneyplus").
+let serviceSelections = new Map();
+// Service Tag System.
+// Module-level state for the service filter. Empty array means "no filter" (all services shown). Non-empty means only these tags are active.
+let enabledServices = [];
+/**
+ * Derives the service tag for a channel from its URL domain, falling back to "direct" if no service tag is configured. Checks the channel's explicit profile
+ * first (for user-defined profiles with custom serviceTag), then the URL domain via getDomainConfig().
  * @param channel - The channel to derive a tag for.
- * @returns The provider tag string.
+ * @returns The service tag string.
  */
-function resolveProviderTag(channel) {
-    // If the channel specifies a user-defined profile, use that profile's providerTag rather than deriving from the URL. This ensures channels with explicit profile
-    // assignments are grouped under the correct provider filter even when their URL domain has a different built-in providerTag.
+function resolveServiceTag(channel) {
+    // If the channel specifies a user-defined profile, use that profile's serviceTag rather than deriving from the URL. This ensures channels with explicit profile
+    // assignments are grouped under the correct service filter even when their URL domain has a different built-in serviceTag.
     if (channel.profile) {
-        const profileProvider = resolveUserProfileProvider(channel.profile);
-        if (profileProvider?.providerTag) {
-            return profileProvider.providerTag;
+        const profileService = resolveUserProfileService(channel.profile);
+        if (profileService?.serviceTag) {
+            return profileService.serviceTag;
         }
     }
     const config = getDomainConfig(channel.url);
-    return config?.providerTag ?? "direct";
+    return config?.serviceTag ?? "direct";
 }
 /**
- * Gets the provider tag for a channel key. For channels in a provider group, reads the pre-computed tag from the group variant entry (computed at group-building
- * time by buildProviderGroups). For standalone channels not in any group, derives the tag from the channel's URL domain. This function should not be called with
- * :predefined synthetic keys — those only exist inside provider groups and their tags are available via the group's variant entries.
+ * Gets the service tag for a channel key. For channels in a service group, reads the pre-computed tag from the group variant entry (computed at group-building
+ * time by buildServiceGroups). For standalone channels not in any group, derives the tag from the channel's URL domain. This function should not be called with
+ * :predefined synthetic keys — those only exist inside service groups and their tags are available via the group's variant entries.
  * @param key - The channel key.
- * @returns The provider tag string.
+ * @returns The service tag string.
  */
-export function getProviderTagForChannel(key) {
+export function getServiceTagForChannel(key) {
     const effectiveKey = stripPredefinedSuffix(key);
-    const group = providerGroups.get(effectiveKey);
+    const group = serviceGroups.get(effectiveKey);
     // For channels in a group, read the pre-computed tag from the variant entry.
     if (group) {
         const variant = group.variants.find((v) => (v.key === key) || (v.key === effectiveKey));
@@ -83,10 +83,10 @@ export function getProviderTagForChannel(key) {
     if (!channel) {
         return "direct";
     }
-    return resolveProviderTag(channel);
+    return resolveServiceTag(channel);
 }
 /**
- * Returns the auth domain for a channel key. Domain is the natural auth boundary — browser cookies and sessions scope to it. Multi-channel providers work correctly
+ * Returns the auth domain for a channel key. Domain is the natural auth boundary — browser cookies and sessions scope to it. Multi-channel services work correctly
  * because all their channels share one domain, and canonical channels work correctly because each has its own domain.
  * @param key - The channel key.
  * @returns The extracted domain from the channel's URL, or empty string if the channel or URL cannot be resolved.
@@ -101,12 +101,12 @@ export function getAuthDomainForChannel(key) {
     return extractDomain(channel.url);
 }
 /**
- * Returns all provider tags for a channel (canonical tag + all variant suffix tags). Used to determine which providers offer this channel.
+ * Returns all service tags for a channel (canonical tag + all variant suffix tags). Used to determine which services offer this channel.
  * @param canonicalKey - The canonical channel key.
- * @returns Array of provider tag strings.
+ * @returns Array of service tag strings.
  */
-export function getChannelProviderTags(canonicalKey) {
-    const group = providerGroups.get(canonicalKey);
+export function getChannelServiceTags(canonicalKey) {
+    const group = serviceGroups.get(canonicalKey);
     // For grouped channels, collect tags directly from the pre-computed variant entries.
     if (group) {
         const tags = new Set();
@@ -120,47 +120,47 @@ export function getChannelProviderTags(canonicalKey) {
         return [...tags];
     }
     // Standalone channel — derive tag from the channel directly.
-    return [getProviderTagForChannel(canonicalKey)];
+    return [getServiceTagForChannel(canonicalKey)];
 }
 /**
- * Scans all provider groups and collects unique provider tags with display names. Display names are derived from the provider field in DOMAIN_CONFIG entries that
- * have a providerTag.
+ * Scans all service groups and collects unique service tags with display names. Display names are derived from the service field in DOMAIN_CONFIG entries that
+ * have a serviceTag.
  * @returns Array of { displayName, domain, iconUrl, tag } objects sorted alphabetically by display name, with "direct" always first.
  */
-export function getAllProviderTags() {
+export function getAllServiceTags() {
     const tags = new Set();
-    // Scan all channels (not just grouped ones) to find all provider tags.
+    // Scan all channels (not just grouped ones) to find all service tags.
     const allKeys = new Set([...Object.keys(channelsRef), ...Object.keys(PREDEFINED_CHANNELS)]);
     for (const key of allKeys) {
-        // Skip variant keys — they are covered by getChannelProviderTags() on the canonical.
-        const group = providerGroups.get(key);
+        // Skip variant keys — they are covered by getChannelServiceTags() on the canonical.
+        const group = serviceGroups.get(key);
         if (group && (group.canonicalKey !== key)) {
             continue;
         }
-        const channelTags = getChannelProviderTags(key);
+        const channelTags = getChannelServiceTags(key);
         for (const tag of channelTags) {
             tags.add(tag);
         }
     }
-    // Scan user domain mappings for provider tags that may not appear in any channel yet (e.g., newly created profiles with no channels assigned).
+    // Scan user domain mappings for service tags that may not appear in any channel yet (e.g., newly created profiles with no channels assigned).
     const userDomains = getUserDomains();
     for (const config of Object.values(userDomains)) {
-        if (config.providerTag) {
-            tags.add(config.providerTag);
+        if (config.serviceTag) {
+            tags.add(config.serviceTag);
         }
     }
-    // Build tag metadata maps from DOMAIN_CONFIG entries. Collects display name, domain, and icon URL for each provider tag. First match wins for each tag.
+    // Build tag metadata maps from DOMAIN_CONFIG entries. Collects display name, domain, and icon URL for each service tag. First match wins for each tag.
     const tagMeta = new Map();
     tagMeta.set("direct", { displayName: "Channel Website" });
     for (const [domain, config] of Object.entries(DOMAIN_CONFIG)) {
-        if (config.providerTag && config.provider && !tagMeta.has(config.providerTag)) {
-            tagMeta.set(config.providerTag, { displayName: config.provider, domain, iconUrl: config.iconUrl });
+        if (config.serviceTag && config.service && !tagMeta.has(config.serviceTag)) {
+            tagMeta.set(config.serviceTag, { displayName: config.service, domain, iconUrl: config.iconUrl });
         }
     }
     // Scan user domain mappings for metadata not covered by built-in DOMAIN_CONFIG.
     for (const [domain, config] of Object.entries(userDomains)) {
-        if (config.providerTag && config.provider && !tagMeta.has(config.providerTag)) {
-            tagMeta.set(config.providerTag, { displayName: config.provider, domain, iconUrl: config.iconUrl });
+        if (config.serviceTag && config.service && !tagMeta.has(config.serviceTag)) {
+            tagMeta.set(config.serviceTag, { displayName: config.service, domain, iconUrl: config.iconUrl });
         }
     }
     // Build result with metadata.
@@ -182,47 +182,47 @@ export function getAllProviderTags() {
     return result;
 }
 /**
- * Gets the current enabled provider tags.
- * @returns Copy of the enabled providers array. Empty means no filter (all shown).
+ * Gets the current enabled service tags.
+ * @returns Copy of the enabled services array. Empty means no filter (all shown).
  */
-export function getEnabledProviders() {
-    return [...enabledProviders];
+export function getEnabledServices() {
+    return [...enabledServices];
 }
 /**
- * Sets the enabled provider tags. Empty array means "no filter" (all providers shown).
- * @param tags - The provider tags to enable.
+ * Sets the enabled service tags. Empty array means "no filter" (all services shown).
+ * @param tags - The service tags to enable.
  */
-export function setEnabledProviders(tags) {
-    enabledProviders = [...tags];
+export function setEnabledServices(tags) {
+    enabledServices = [...tags];
 }
 /**
- * Checks if a provider tag is currently enabled. Returns true if the tag is enabled, if no filter is active (empty set), or if the tag is "direct".
- * @param tag - The provider tag to check.
- * @returns True if the provider is available.
+ * Checks if a service tag is currently enabled. Returns true if the tag is enabled, if no filter is active (empty set), or if the tag is "direct".
+ * @param tag - The service tag to check.
+ * @returns True if the service is available.
  */
-export function isProviderTagEnabled(tag) {
-    // No filter active — all providers are enabled.
-    if (enabledProviders.length === 0) {
+export function isServiceTagEnabled(tag) {
+    // No filter active — all services are enabled.
+    if (enabledServices.length === 0) {
         return true;
     }
     // "direct" is always enabled.
     if (tag === "direct") {
         return true;
     }
-    return enabledProviders.includes(tag);
+    return enabledServices.includes(tag);
 }
 /**
- * Centralized availability check for the provider filter. Returns true if the channel has at least one variant whose provider tag is enabled.
+ * Centralized availability check for the service filter. Returns true if the channel has at least one variant whose service tag is enabled.
  * @param canonicalKey - The canonical channel key.
- * @returns True if the channel passes the provider filter.
+ * @returns True if the channel passes the service filter.
  */
-export function isChannelAvailableByProvider(canonicalKey) {
+export function isChannelAvailableByService(canonicalKey) {
     // No filter active — all channels are available.
-    if (enabledProviders.length === 0) {
+    if (enabledServices.length === 0) {
         return true;
     }
-    const tags = getChannelProviderTags(canonicalKey);
-    return tags.some((tag) => isProviderTagEnabled(tag));
+    const tags = getChannelServiceTags(canonicalKey);
+    return tags.some((tag) => isServiceTagEnabled(tag));
 }
 /**
  * Checks if a channel in the merged map is a user override of a predefined channel. This uses object reference comparison — getAllChannels() spreads
@@ -237,17 +237,22 @@ function isUserOverride(key, channels) {
     return Boolean(predefined) && (channels[key] !== predefined);
 }
 /**
- * Builds provider groups by scanning all channels and grouping by canonicalKey. Variant entries declare their canonical via the canonicalKey field (set by the
+ * Builds service groups by scanning all channels and grouping by canonicalKey. Variant entries declare their canonical via the canonicalKey field (set by the
  * flattener for predefined channels, by the browse modal for user channels, and by the one-time migration for pre-existing user entries). This is a single
  * pass over the merged channel map — one field, one mechanism for both predefined and user-defined variant relationships.
  *
  * User overrides of predefined channels (same key, different object reference) produce a two-entry group with "Custom" and the original predefined version,
- * even for single-provider channels that don't have canonicalKey-based variants.
+ * even for single-service channels that don't have canonicalKey-based variants.
+ *
+ * After building groups, validates stored service selections against the new variant structure and reverts any stale selections to the canonical default. This
+ * catches all staleness sources in one place: service key renames across versions, variant removal in code, user-deleted custom variants, and reverted
+ * predefined overrides.
  * @param channels - The merged channel map (predefined + user channels).
+ * @returns Canonical keys whose service selections were stale and reverted. Empty array if all selections are valid. The caller decides whether to persist.
  */
-export function buildProviderGroups(channels) {
+export function buildServiceGroups(channels) {
     channelsRef = channels;
-    providerGroups.clear();
+    serviceGroups.clear();
     // Pass 1: Collect variant keys grouped by their canonical key. Entries without canonicalKey are canonicals or standalone channels.
     const variantsByCanonical = new Map();
     for (const [key, channel] of Object.entries(channels)) {
@@ -270,34 +275,50 @@ export function buildProviderGroups(channels) {
             continue;
         }
         const variants = [];
-        // Handle user override of the canonical entry. The :predefined variant's tag is derived from the predefined channel (not the user override) so that provider
-        // filtering correctly reflects the predefined channel's provider, not the user's custom URL.
+        // Handle user override of the canonical entry. Two scenarios: (A) the user customized properties (station ID, tags, etc.) but the URL still matches a known
+        // service domain — no "Custom" variant needed, just the normal service label with a visual override indicator in the table; (B) the user set a genuinely
+        // non-standard URL — "Custom (domain)" is a real service variant and the :predefined entry gives access to the original service URL.
         if (isUserOverride(canonicalKey, channels)) {
             const predefined = PREDEFINED_CHANNELS[canonicalKey];
-            variants.push({ key: canonicalKey, label: "Custom (" + extractDomain(canonical.url) + ")", tag: resolveProviderTag(canonical) });
-            variants.push({ key: canonicalKey + PREDEFINED_SUFFIX, label: predefined.provider ?? getProviderDisplayName(predefined.url),
-                tag: resolveProviderTag(predefined) });
+            const userDomain = extractDomain(canonical.url);
+            const knownDomains = new Set([extractDomain(predefined.url)]);
+            for (const variantKey of variantKeys) {
+                knownDomains.add(extractDomain(channels[variantKey].url));
+            }
+            if (knownDomains.has(userDomain)) {
+                // Scenario A: property override on a known service. The canonical gets the same label as if it weren't overridden. The modified-dot indicator in the
+                // table renderer handles the visual distinction.
+                variants.push({ key: canonicalKey, label: getChannelServiceLabel(canonical), tag: resolveServiceTag(canonical) });
+            }
+            else {
+                // Scenario B: genuinely custom URL. "Custom (domain)" is a real service variant. The :predefined entry gives the user a path back to the original
+                // predefined service URL without permanently reverting their other customizations.
+                variants.push({ key: canonicalKey, label: "Custom (" + extractDomain(canonical.url) + ")", tag: resolveServiceTag(canonical) });
+                variants.push({ key: canonicalKey + PREDEFINED_SUFFIX, label: predefined.service ?? getServiceDisplayName(predefined.url),
+                    tag: resolveServiceTag(predefined) });
+            }
         }
         else {
-            variants.push({ key: canonicalKey, label: getChannelProviderLabel(canonical), tag: resolveProviderTag(canonical) });
+            variants.push({ key: canonicalKey, label: getChannelServiceLabel(canonical), tag: resolveServiceTag(canonical) });
         }
         variantKeys.sort();
         for (const variantKey of variantKeys) {
             const variant = channels[variantKey];
-            variants.push({ key: variantKey, label: getChannelProviderLabel(variant), tag: resolveProviderTag(variant) });
+            variants.push({ key: variantKey, label: getChannelServiceLabel(variant), tag: resolveServiceTag(variant) });
         }
         const group = { canonicalKey, variants };
         // Map canonical and all variant keys to this group for easy lookup.
-        providerGroups.set(canonicalKey, group);
+        serviceGroups.set(canonicalKey, group);
         for (const variantKey of variantKeys) {
-            providerGroups.set(variantKey, group);
+            serviceGroups.set(variantKey, group);
         }
-        LOG.debug("config:general", "Provider group '%s': variants=%s.", canonicalKey, variants.map((v) => v.key).join(", "));
+        LOG.debug("config:general", "Service group '%s': variants=%s.", canonicalKey, variants.map((v) => v.key).join(", "));
     }
-    // Pass 3: Create groups for user overrides of single-provider predefined channels. These don't have canonicalKey-based variants but the user's custom version
-    // should be toggleable against the predefined original.
+    // Pass 3: Create groups for user overrides of single-service predefined channels. Only Scenario B (genuinely custom URL) gets a service group — the user needs
+    // a dropdown to switch between their custom URL and the predefined service. Scenario A (property override on the same domain) skips group creation entirely
+    // because there is only one service and no dropdown is needed; the modified-dot indicator in the table renderer signals the override.
     for (const key of Object.keys(channels)) {
-        if (providerGroups.has(key)) {
+        if (serviceGroups.has(key)) {
             continue;
         }
         if (!isUserOverride(key, channels)) {
@@ -305,37 +326,99 @@ export function buildProviderGroups(channels) {
         }
         const userChannel = channels[key];
         const predefined = PREDEFINED_CHANNELS[key];
+        // Scenario A: URL domain matches the predefined service. No service group needed — renders as a single-service channel with a modified-dot indicator.
+        if (extractDomain(userChannel.url) === extractDomain(predefined.url)) {
+            continue;
+        }
+        // Scenario B: genuinely custom URL. Create a 2-entry group so the user can switch between their custom URL and the predefined service.
         const variants = [
-            { key, label: "Custom (" + extractDomain(userChannel.url) + ")", tag: resolveProviderTag(userChannel) },
-            { key: key + PREDEFINED_SUFFIX, label: predefined.provider ?? getProviderDisplayName(predefined.url), tag: resolveProviderTag(predefined) }
+            { key, label: "Custom (" + extractDomain(userChannel.url) + ")", tag: resolveServiceTag(userChannel) },
+            { key: key + PREDEFINED_SUFFIX, label: predefined.service ?? getServiceDisplayName(predefined.url), tag: resolveServiceTag(predefined) }
         ];
         const group = { canonicalKey: key, variants };
-        providerGroups.set(key, group);
-        LOG.debug("config:general", "Provider group '%s' (override): variants=%s.", key, variants.map((v) => v.key).join(", "));
+        serviceGroups.set(key, group);
+        LOG.debug("config:general", "Service group '%s' (override): variants=%s.", key, variants.map((v) => v.key).join(", "));
+    }
+    // Build the domain-to-predefined-channel reverse index. This enables the manual add form to show an inline hint when the entered URL matches a predefined
+    // channel. Scans only canonical entries in PREDEFINED_CHANNELS (variants share the canonical's URL domain and would produce duplicate results).
+    predefinedByDomain.clear();
+    for (const [key, channel] of Object.entries(PREDEFINED_CHANNELS)) {
+        if (channel.canonicalKey) {
+            continue;
+        }
+        const domain = extractDomain(channel.url);
+        const group = serviceGroups.get(key);
+        const entry = { canonicalKey: key, name: channel.name ?? key, serviceCount: group?.variants.length ?? 1 };
+        const existing = predefinedByDomain.get(domain);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            predefinedByDomain.set(domain, [entry]);
+        }
+    }
+    // Validate stored service selections against the rebuilt groups. Any selection whose variant key no longer exists in the group is stale and reverted to the
+    // canonical default. This handles all staleness sources: service key renames across versions, variant removal, user-deleted custom variants, and reverted
+    // predefined overrides. The caller decides whether to persist based on whether any keys were cleaned.
+    const staleKeys = [];
+    for (const [canonicalKey, selection] of serviceSelections) {
+        const group = serviceGroups.get(canonicalKey);
+        if (!group?.variants.some((v) => v.key === selection)) {
+            LOG.warn("Service selection '%s' for channel '%s' is no longer valid. Reverting to default.", selection, canonicalKey);
+            serviceSelections.delete(canonicalKey);
+            staleKeys.push(canonicalKey);
+        }
     }
+    return staleKeys;
 }
+// Reverse index mapping concise domains to predefined channel summaries. Built by buildServiceGroups() and queried by findPredefinedByDomain() and
+// getPredefinedDomainMap().
+const predefinedByDomain = new Map();
 /**
- * Resolves a URL to a friendly provider display name. Checks built-in DOMAIN_CONFIG first for a stable, well-known provider name, then falls back to
+ * Returns predefined channels whose canonical URL domain matches the given URL's domain. Used by the manual add form to show an inline hint when the user
+ * enters a URL that has predefined channels available. Returns an empty array when no predefined channels match.
+ * @param url - The URL to match against predefined channel domains.
+ * @returns Array of matching predefined channel summaries with canonical key, display name, and available service count.
+ */
+export function findPredefinedByDomain(url) {
+    try {
+        const domain = extractDomain(url);
+        return predefinedByDomain.get(domain) ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns the full domain-to-predefined-channel index for client-side embedding. Used by the channels panel to embed predefined match data so the manual add
+ * form can show inline hints without a server round-trip. The returned object is keyed by concise domain with arrays of channel summaries as values.
+ * @returns Record mapping domains to predefined channel summaries.
+ */
+export function getPredefinedDomainMap() {
+    return Object.fromEntries(predefinedByDomain);
+}
+/**
+ * Resolves a URL to a friendly service display name. Checks built-in DOMAIN_CONFIG first for a stable, well-known service name, then falls back to
  * getDomainConfig() which includes user domain mappings. This ordering prevents user domain overrides from corrupting display labels for predefined channel
- * variants — a user mapping a built-in domain to a custom profile should not rename every provider dropdown entry that uses that domain.
- * @param url - The URL to resolve a provider display name for.
- * @returns The provider display name, or the concise domain if no provider name is configured.
+ * variants — a user mapping a built-in domain to a custom profile should not rename every service dropdown entry that uses that domain.
+ * @param url - The URL to resolve a service display name for.
+ * @returns The service display name, or the concise domain if no service name is configured.
  */
-export function getProviderDisplayName(url) {
-    // Prefer built-in DOMAIN_CONFIG provider names for stable display. Check by full hostname first (for subdomain-specific entries like tv.youtube.com), then by
+export function getServiceDisplayName(url) {
+    // Prefer built-in DOMAIN_CONFIG service names for stable display. Check by full hostname first (for subdomain-specific entries like tv.youtube.com), then by
     // concise domain (e.g., disneyplus.com).
     try {
         const hostname = new URL(url).hostname;
         const builtinFull = DOMAIN_CONFIG[hostname];
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (builtinFull?.provider) {
-            return builtinFull.provider;
+        if (builtinFull?.service) {
+            return builtinFull.service;
         }
         const concise = extractDomain(url);
         const builtinConcise = DOMAIN_CONFIG[concise];
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (builtinConcise?.provider) {
-            return builtinConcise.provider;
+        if (builtinConcise?.service) {
+            return builtinConcise.service;
         }
     }
     catch {
@@ -343,61 +426,61 @@ export function getProviderDisplayName(url) {
     }
     // For domains not in DOMAIN_CONFIG, fall back to getDomainConfig() which includes user domain mappings.
     const config = getDomainConfig(url);
-    return config?.provider ?? extractDomain(url);
+    return config?.service ?? extractDomain(url);
 }
 /**
- * Resolves provider identity (tag and display name) for a user-defined profile by scanning its domain mappings. Returns the first matching domain config's
- * providerTag and provider name. This is the single source of truth for "profile key → provider identity" resolution, used by both tag and label lookups to avoid
+ * Resolves service identity (tag and display name) for a user-defined profile by scanning its domain mappings. Returns the first matching domain config's
+ * serviceTag and service name. This is the single source of truth for "profile key → service identity" resolution, used by both tag and label lookups to avoid
  * duplicating the domain scan logic.
  * @param profileKey - The user profile key to resolve.
- * @returns The provider identity from the profile's domain mappings, or undefined if no matching domain mapping exists.
+ * @returns The service identity from the profile's domain mappings, or undefined if no matching domain mapping exists.
  */
-function resolveUserProfileProvider(profileKey) {
+function resolveUserProfileService(profileKey) {
     const userDomains = getUserDomains();
     for (const config of Object.values(userDomains)) {
         if (config.profile === profileKey) {
-            return { provider: config.provider, providerTag: config.providerTag };
+            return { service: config.service, serviceTag: config.serviceTag };
         }
     }
     return undefined;
 }
 /**
- * Resolves the provider display label for a channel. Checks in order: explicit `provider` field on the channel, the channel's explicit profile resolved via
- * user domain mappings, then URL-based built-in display name. This ensures channels assigned to user-defined profiles show the profile's provider name rather
+ * Resolves the service display label for a channel. Checks in order: explicit `service` field on the channel, the channel's explicit profile resolved via
+ * user domain mappings, then URL-based built-in display name. This ensures channels assigned to user-defined profiles show the profile's service name rather
  * than the built-in name for the URL domain.
  * @param channel - The channel to resolve a label for.
- * @returns The provider display label.
+ * @returns The service display label.
  */
-export function getChannelProviderLabel(channel) {
-    if (channel.provider) {
-        return channel.provider;
+export function getChannelServiceLabel(channel) {
+    if (channel.service) {
+        return channel.service;
     }
-    // If the channel specifies a user-defined profile, use that profile's provider name from domain mappings.
+    // If the channel specifies a user-defined profile, use that profile's service name from domain mappings.
     if (channel.profile) {
-        const profileProvider = resolveUserProfileProvider(channel.profile);
-        if (profileProvider?.provider) {
-            return profileProvider.provider;
+        const profileService = resolveUserProfileService(channel.profile);
+        if (profileService?.service) {
+            return profileService.service;
         }
     }
-    return getProviderDisplayName(channel.url);
+    return getServiceDisplayName(channel.url);
 }
 // Valid sort field values for the channels table. Exported as the single source of truth for sort field validation, shared by the config POST handler and the
 // playlist endpoint's query parameter validation.
-export const VALID_SORT_FIELDS = new Set(["channelNumber", "channelSelector", "hdhrEnabled", "key", "name", "profile", "provider", "stationId", "tags"]);
+export const VALID_SORT_FIELDS = new Set(["channelNumber", "channelSelector", "hdhrEnabled", "key", "name", "profile", "service", "stationId", "tags"]);
 /**
  * Extracts a sortable string value from a channel for the specified sort field. Channel numbers are zero-padded to 6 digits for correct numeric ordering within a
- * string comparison. Provider values use the display label for human-meaningful sort order. This is the single source of truth for channel sort key extraction,
+ * string comparison. Service values use the display label for human-meaningful sort order. This is the single source of truth for channel sort key extraction,
  * shared by both the server-side table renderer and the M3U playlist generator.
- * @param channel - Fallback channel definition, used only when the selected provider variant cannot be resolved (e.g., key not in the merged channel map).
- * @param key - The canonical channel key. Used for key-based sorting and to resolve the selected provider variant internally.
+ * @param channel - Fallback channel definition, used only when the selected service variant cannot be resolved (e.g., key not in the merged channel map).
+ * @param key - The canonical channel key. Used for key-based sorting and to resolve the selected service variant internally.
  * @param field - The sort field to extract.
  * @returns A lowercase string suitable for comparison-based sorting.
  */
 export function getChannelSortKey(channel, key, field) {
-    // Resolve the selected provider variant so all sort keys reflect the user's provider selection. For URL-dependent fields (profile, provider), this is essential —
+    // Resolve the selected service variant so all sort keys reflect the user's service selection. For URL-dependent fields (profile, service), this is essential —
     // a canonical's URL may differ from the selected variant's (e.g., bbcnews canonical uses cox but the user selected the directv variant). For identity fields
     // (name, stationId, channelNumber), the flattener eagerly sets these on all entries, so the resolved channel has identical values regardless of variant.
-    const effective = getResolvedChannel(resolveProviderKey(key)) ?? channel;
+    const effective = getResolvedChannel(resolveServiceKey(key)) ?? channel;
     switch (field) {
         case "channelNumber": {
             const num = effective.channelNumber;
@@ -421,17 +504,17 @@ export function getChannelSortKey(channel, key, field) {
             if (effective.profile) {
                 return effective.profile.toLowerCase();
             }
-            // Auto-detected: check whether the profile resolves to a real provider or falls back to default. Only apply the ! prefix for non-default auto profiles so
+            // Auto-detected: check whether the profile resolves to a real service or falls back to default. Only apply the ! prefix for non-default auto profiles so
             // they sort between explicit profiles and empty profiles.
             const resolved = getProfileForChannel(effective);
             if (resolved.profileName === "default") {
                 return "";
             }
-            const label = getChannelProviderLabel(effective);
+            const label = getChannelServiceLabel(effective);
             return label ? ("!" + label.toLowerCase()) : "";
         }
-        case "provider": {
-            return getChannelProviderLabel(effective).toLowerCase();
+        case "service": {
+            return getChannelServiceLabel(effective).toLowerCase();
         }
         case "stationId": {
             const id = effective.stationId;
@@ -471,128 +554,112 @@ export function compareChannelSort(channelA, keyA, channelB, keyB, field, direct
     return nameA.localeCompare(nameB);
 }
 /**
- * Gets the provider group for a channel key. Works with both canonical and variant keys.
+ * Gets the service group for a channel key. Works with both canonical and variant keys.
  * @param key - Any channel key in the group.
- * @returns The provider group if the channel is part of a multi-provider group, undefined otherwise.
+ * @returns The service group if the channel is part of a multi-service group, undefined otherwise.
  */
-export function getProviderGroup(key) {
-    return providerGroups.get(key);
+export function getServiceGroup(key) {
+    return serviceGroups.get(key);
 }
 /**
- * Checks if a channel key is a non-canonical provider variant. Used to filter variants from channel listings.
+ * Checks if a channel key is a non-canonical service variant. Used to filter variants from channel listings.
  * @param key - The channel key to check.
- * @returns True if the key is a variant (not canonical) in a provider group.
+ * @returns True if the key is a variant (not canonical) in a service group.
  */
-export function isProviderVariant(key) {
-    const group = providerGroups.get(key);
+export function isServiceVariant(key) {
+    const group = serviceGroups.get(key);
     return (group !== undefined) && (group.canonicalKey !== key);
 }
 /**
- * Checks if a channel has multiple provider options. Used to determine whether to show a provider dropdown in the UI.
+ * Checks if a channel has multiple service options. Used to determine whether to show a service dropdown in the UI.
  * @param key - The channel key to check.
- * @returns True if the channel has more than one provider variant.
+ * @returns True if the channel has more than one service variant.
  */
-export function hasMultipleProviders(key) {
-    const group = providerGroups.get(key);
+export function hasMultipleServices(key) {
+    const group = serviceGroups.get(key);
     return (group !== undefined) && (group.variants.length > 1);
 }
 /**
  * Gets the canonical key for any channel key. For variant keys, returns the canonical key. For non-grouped or canonical keys, returns the input unchanged.
  * Handles the PREDEFINED_SUFFIX used when a user has overridden a predefined channel.
  * @param key - Any channel key.
- * @returns The canonical key for the channel's provider group, or the input key if not part of a group.
+ * @returns The canonical key for the channel's service group, or the input key if not part of a group.
  */
 export function getCanonicalKey(key) {
     // Strip predefined suffix if present before looking up the group.
     const baseKey = key.endsWith(PREDEFINED_SUFFIX) ? key.slice(0, -PREDEFINED_SUFFIX.length) : key;
-    const group = providerGroups.get(baseKey);
+    const group = serviceGroups.get(baseKey);
     return group?.canonicalKey ?? baseKey;
 }
 /**
- * Sets the user's provider selections. Called when loading from channels.json.
- * @param selections - Provider selections keyed by canonical channel key.
+ * Sets the user's service selections. Called when loading from channels.json.
+ * @param selections - Service selections keyed by canonical channel key.
  */
-export function setProviderSelections(selections) {
-    providerSelections = new Map(Object.entries(selections));
+export function setServiceSelections(selections) {
+    serviceSelections = new Map(Object.entries(selections));
 }
 /**
- * Gets all provider selections.
- * @returns Copy of the provider selections object.
+ * Gets all service selections.
+ * @returns Copy of the service selections object.
  */
-export function getProviderSelections() {
-    return Object.fromEntries(providerSelections);
+export function getServiceSelections() {
+    return Object.fromEntries(serviceSelections);
 }
 /**
- * Gets the provider selection for a specific channel.
+ * Gets the service selection for a specific channel.
  * @param canonicalKey - The canonical channel key.
- * @returns The selected provider key, or undefined if using the default.
+ * @returns The selected service key, or undefined if using the default.
  */
-export function getProviderSelection(canonicalKey) {
-    return providerSelections.get(canonicalKey);
+export function getServiceSelection(canonicalKey) {
+    return serviceSelections.get(canonicalKey);
 }
 /**
- * Sets the provider selection for a channel.
+ * Sets the service selection for a channel.
  * @param canonicalKey - The canonical channel key.
- * @param providerKey - The selected provider key.
+ * @param serviceKey - The selected service key.
  */
-export function setProviderSelection(canonicalKey, providerKey) {
+export function setServiceSelection(canonicalKey, serviceKey) {
     // If selecting the canonical (default), remove the selection instead of storing it.
-    if (providerKey === canonicalKey) {
-        providerSelections.delete(canonicalKey);
+    if (serviceKey === canonicalKey) {
+        serviceSelections.delete(canonicalKey);
     }
     else {
-        providerSelections.set(canonicalKey, providerKey);
+        serviceSelections.set(canonicalKey, serviceKey);
     }
 }
 /**
- * Resolves a canonical channel key to the actual channel key based on user selection. If the user has selected a specific provider for this channel, returns that
- * provider's key. Otherwise returns the canonical key (default provider). When the provider filter is active, falls back to the first enabled variant if the stored
- * selection's provider is filtered out.
+ * Resolves a canonical channel key to the actual channel key based on user selection. If the user has selected a specific service for this channel, returns that
+ * service's key. Otherwise returns the canonical key (default service). When the service filter is active, falls back to the first enabled variant if the stored
+ * selection's service is filtered out.
+ *
+ * This function is a pure resolver with no side effects. Stale selection cleanup is handled by buildServiceGroups(), which validates all stored selections
+ * against the rebuilt variant structure every time groups are rebuilt - both at startup and after runtime channel mutations.
  * @param canonicalKey - The canonical channel key.
- * @returns The resolved provider key to use for streaming.
+ * @returns The resolved service key to use for streaming.
  */
-export function resolveProviderKey(canonicalKey) {
-    const selection = providerSelections.get(canonicalKey);
-    // No selection stored — use the canonical key (default provider).
+export function resolveServiceKey(canonicalKey) {
+    const selection = serviceSelections.get(canonicalKey);
+    // No selection stored — use the canonical key (default service). If the canonical's service tag is filtered out, fall back to the first enabled variant.
     if (!selection) {
-        // If the canonical's provider tag is filtered out, find the first enabled variant.
-        if ((enabledProviders.length > 0) && !isProviderTagEnabled(getProviderTagForChannel(canonicalKey))) {
+        if ((enabledServices.length > 0) && !isServiceTagEnabled(getServiceTagForChannel(canonicalKey))) {
             return findFirstEnabledVariant(canonicalKey) ?? canonicalKey;
         }
         return canonicalKey;
     }
-    // Handle :predefined suffix — validate that the base key exists in PREDEFINED_CHANNELS.
-    if (selection.endsWith(PREDEFINED_SUFFIX)) {
-        const baseKey = selection.slice(0, -PREDEFINED_SUFFIX.length);
-        // Runtime check needed — TypeScript thinks Record indexing always returns a value, but the key may not exist.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (PREDEFINED_CHANNELS[baseKey]) {
-            return selection;
-        }
-        // Predefined channel was removed. Fall through to the invalid selection warning.
-        // Runtime check needed — TypeScript thinks Record indexing always returns a value, but the key may not exist.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    }
-    else if (channelsRef[selection]) {
-        // Normal selection — validate it exists in the merged channels. If its provider tag is filtered out, find the first enabled variant instead.
-        if ((enabledProviders.length > 0) && !isProviderTagEnabled(getProviderTagForChannel(selection))) {
-            return findFirstEnabledVariant(canonicalKey) ?? selection;
-        }
-        return selection;
+    // Valid selection — if its service tag is filtered out, fall back to the first enabled variant.
+    if ((enabledServices.length > 0) && !isServiceTagEnabled(getServiceTagForChannel(selection))) {
+        return findFirstEnabledVariant(canonicalKey) ?? selection;
     }
-    // Selection is invalid (provider removed). Clear it and log a warning.
-    LOG.warn("Provider selection '%s' for channel '%s' no longer exists. Using default.", selection, canonicalKey);
-    providerSelections.delete(canonicalKey);
-    return canonicalKey;
+    return selection;
 }
 /**
- * Finds the first enabled variant for a channel when the current selection's provider is filtered out. Iterates the group's variants and returns the first whose
- * provider tag is enabled.
+ * Finds the first enabled variant for a channel when the current selection's service is filtered out. Iterates the group's variants and returns the first whose
+ * service tag is enabled.
  * @param canonicalKey - The canonical channel key.
  * @returns The first enabled variant key, or undefined if none are enabled.
  */
 function findFirstEnabledVariant(canonicalKey) {
-    const group = providerGroups.get(canonicalKey);
+    const group = serviceGroups.get(canonicalKey);
     if (!group) {
         return undefined;
     }
@@ -600,21 +667,21 @@ function findFirstEnabledVariant(canonicalKey) {
         if (variant.key.endsWith(PREDEFINED_SUFFIX)) {
             continue;
         }
-        if (isProviderTagEnabled(variant.tag)) {
+        if (isServiceTagEnabled(variant.tag)) {
             return variant.key;
         }
     }
     return undefined;
 }
 /**
- * Applies variant inheritance: the variant contributes provider-specific fields (url, channelSelector, profile, etc.) while identity fields always come from the
- * canonical base. Identity fields describe what the channel IS — name, station ID, tags, channel number — and are independent of which provider serves it. The
+ * Applies variant inheritance: the variant contributes service-specific fields (url, channelSelector, profile, etc.) while identity fields always come from the
+ * canonical base. Identity fields describe what the channel IS — name, station ID, tags, channel number — and are independent of which service serves it. The
  * spread brings in all variant fields, then identity fields are unconditionally overwritten from the canonical. This ensures user overrides on the canonical
- * (e.g., renaming a channel or adding tags) propagate to all provider variants, rather than being masked by stale flattener-copied values on the variant.
- * The field list comes from CHANNEL_IDENTITY_FIELDS — the single source of truth for the identity/provider-specific separation.
- * @param variant - The variant channel definition (provider-specific fields).
+ * (e.g., renaming a channel or adding tags) propagate to all service variants, rather than being masked by stale flattener-copied values on the variant.
+ * The field list comes from CHANNEL_IDENTITY_FIELDS — the single source of truth for the identity/service-specific separation.
+ * @param variant - The variant channel definition (service-specific fields).
  * @param base - The canonical (base) channel with user overrides applied (identity fields).
- * @returns A new Channel with identity fields from the canonical and provider-specific fields from the variant.
+ * @returns A new Channel with identity fields from the canonical and service-specific fields from the variant.
  */
 function applyVariantInheritance(variant, base) {
     const result = { ...variant };
@@ -630,13 +697,13 @@ function copyField(target, source, key) {
     target[key] = source[key];
 }
 /**
- * Gets a channel with inheritance applied. For provider variants, this merges the variant's properties with inherited properties from the canonical entry
+ * Gets a channel with inheritance applied. For service variants, this merges the variant's properties with inherited properties from the canonical entry
  * using the live channel data (which includes user overrides). Use `resolvePredefinedVariant()` when you need resolution against pure predefined data.
  * @param key - The channel key (canonical or variant).
  * @returns The complete channel with inheritance applied, or undefined if the channel doesn't exist.
  */
 export function getResolvedChannel(key) {
-    // Handle predefined suffix — return the original predefined channel when user has overridden the canonical but selects the predefined provider.
+    // Handle predefined suffix — return the original predefined channel when user has overridden the canonical but selects the predefined service.
     if (key.endsWith(PREDEFINED_SUFFIX)) {
         const baseKey = key.slice(0, -PREDEFINED_SUFFIX.length);
         return PREDEFINED_CHANNELS[baseKey];
@@ -647,7 +714,7 @@ export function getResolvedChannel(key) {
     if (!channel) {
         return undefined;
     }
-    const group = providerGroups.get(key);
+    const group = serviceGroups.get(key);
     // If not part of a group or is the canonical entry, return as-is.
     if (!group || (group.canonicalKey === key)) {
         return channel;
@@ -664,7 +731,7 @@ export function getResolvedChannel(key) {
 }
 /**
  * Resolves a variant channel key against pure predefined data (ignoring user overrides). This is used for revert detection — when the user's edits match a
- * variant's predefined definition, the custom override can be removed and the provider selection switched to that variant. For canonical keys, returns the raw
+ * variant's predefined definition, the custom override can be removed and the service selection switched to that variant. For canonical keys, returns the raw
  * predefined channel. For variant keys, applies the same inheritance rules as `getResolvedChannel()` but against `PREDEFINED_CHANNELS` instead of `channelsRef`.
  * @param key - The channel key (canonical or variant).
  * @returns The channel with inheritance applied against predefined data, or undefined if the key has no predefined definition.
@@ -676,7 +743,7 @@ export function resolvePredefinedVariant(key) {
     if (!channel) {
         return undefined;
     }
-    const group = providerGroups.get(key);
+    const group = serviceGroups.get(key);
     // If not part of a group or is the canonical entry, return the predefined channel as-is.
     if (!group || (group.canonicalKey === key)) {
         return channel;
@@ -688,4 +755,4 @@ export function resolvePredefinedVariant(key) {
     }
     return applyVariantInheritance(channel, canonical);
 }
-//# sourceMappingURL=providers.js.map
+//# sourceMappingURL=services.js.map