prismcast 1.6.0 → 1.8.0

package/dist/config/userChannels.js

@@ -1,8 +1,13 @@
-import { LOG, containsNonPrintable, sanitizeString } from "../utils/index.js";
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * userChannels.ts: User channel file management for PrismCast.
+ */
+import { CHANNEL_IDENTITY_FIELDS, PREDEFINED_CHANNELS, PREDEFINED_TAGS } from "../channels/index.js";
+import { LOG, containsNonPrintable, sanitizeString, stringifySorted } from "../utils/index.js";
 import { buildProviderGroups, getAllProviderTags, getProviderSelections, getResolvedChannel, isChannelAvailableByProvider, isProviderVariant, resolveProviderKey, setEnabledProviders, setProviderSelections } from "./providers.js";
 import { getChannelsFilePath, getDataDir } from "./paths.js";
+import { loadUserConfig, saveUserConfig } from "./userConfig.js";
 import { CONFIG } from "./index.js";
-import { PREDEFINED_CHANNELS } from "../channels/index.js";
 import fs from "node:fs";
 const { promises: fsPromises } = fs;
 /* The channels file path is resolved via the centralized paths module (config/paths.ts). The data directory is initialized at startup before channel loading.
@@ -21,6 +26,8 @@ export function getUserChannelsFilePath() {
 let loadedUserChannels = {};
 let userChannelsParseError = false;
 let userChannelsParseErrorMessage;
+// Module-level tag registry state. Tracks user-created tags and user-deleted predefined tags. The runtime vocabulary is computed by getActiveTagVocabulary().
+let loadedTagRegistry = { deletedTags: [], tags: [] };
 /**
  * Returns whether the user channels file had a parse error.
  * @returns True if the channels file exists but contains invalid JSON.
@@ -37,16 +44,17 @@ 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.
- * 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.
+ * The file can contain metadata keys (`providerSelections`, `tagRegistry`) which are extracted separately from channel data.
+ * @returns The loaded channels with parse status, provider selections, and tag registry.
  */
 export async function loadUserChannels() {
     try {
         const content = await fsPromises.readFile(getChannelsFilePath(), "utf-8");
         try {
             const parsed = JSON.parse(content);
-            // Extract providerSelections if present — it's not a channel, it's metadata.
+            // Extract metadata keys (providerSelections, tagRegistry) — these are not channels, they're organizational state stored alongside channel data.
             const providerSelections = {};
+            const tagRegistry = { deletedTags: [], tags: [] };
             const channels = {};
             for (const [key, value] of Object.entries(parsed)) {
                 if (key === "providerSelections") {
@@ -59,66 +67,114 @@ export async function loadUserChannels() {
                         }
                     }
                 }
+                else if (key === "tagRegistry") {
+                    // Extract tag registry with defensive validation. Each field must be a string array — non-string elements are silently dropped.
+                    if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
+                        const raw = value;
+                        if (Array.isArray(raw.tags)) {
+                            tagRegistry.tags = raw.tags.filter((t) => typeof t === "string").sort();
+                        }
+                        if (Array.isArray(raw.deletedTags)) {
+                            tagRegistry.deletedTags = raw.deletedTags.filter((t) => typeof t === "string").sort();
+                        }
+                    }
+                }
                 else if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
                     // It's a channel definition or delta override.
                     channels[key] = value;
                 }
             }
-            return { channels, parseError: false, providerSelections };
+            return { channels, parseError: false, providerSelections, tagRegistry };
         }
         catch (parseError) {
             const message = (parseError instanceof Error) ? parseError.message : String(parseError);
             LOG.warn("Invalid JSON in channels file %s: %s. Using predefined channels only.", getChannelsFilePath(), message);
-            return { channels: {}, parseError: true, parseErrorMessage: message, providerSelections: {} };
+            return { channels: {}, parseError: true, parseErrorMessage: message, providerSelections: {}, tagRegistry: { deletedTags: [], tags: [] } };
         }
     }
     catch (error) {
         // File doesn't exist - this is normal, use predefined channels only.
         if (error.code === "ENOENT") {
-            return { channels: {}, parseError: false, providerSelections: {} };
+            return { channels: {}, parseError: false, providerSelections: {}, tagRegistry: { deletedTags: [], tags: [] } };
         }
         // Other read errors - log and use predefined channels.
         LOG.warn("Failed to read channels file %s: %s. Using predefined channels only.", getChannelsFilePath(), (error instanceof Error) ? error.message : String(error));
-        return { channels: {}, parseError: false, providerSelections: {} };
+        return { channels: {}, parseError: false, providerSelections: {}, tagRegistry: { deletedTags: [], tags: [] } };
     }
 }
 /**
  * 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. Provider selections are also saved if any exist. Empty deltas (no overridden fields) for predefined
- * channel keys are stripped before saving to avoid storing no-op entries.
+ * restart. Creates the data directory if it doesn't exist. Metadata keys (provider selections, tag registry) are also saved if they have content. No-op deltas
+ * for predefined channel keys are normalized before saving: fields that match the predefined value or null-clear a field the predefined doesn't have are
+ * stripped. If the delta becomes empty after normalization, the entry is removed entirely. This ensures that any code path that writes deltas (inline edit,
+ * auto-number, browse modal, full edit) produces clean channels.json output without each handler needing to optimize its own delta.
  * @param channels - The channels to save (full definitions or delta overrides).
  * @throws If the file cannot be written.
  */
 export async function saveUserChannels(channels) {
     // Ensure data directory exists.
     await fsPromises.mkdir(getDataDir(), { recursive: true });
-    // Strip empty deltas for predefined keys — an empty delta means no changes were made.
+    // Normalize predefined channel deltas by stripping no-op fields. A delta field is a no-op if: (1) its value is null and the predefined doesn't have the
+    // field (clearing a nonexistent field), (2) its value is undefined, or (3) its value matches the predefined's value exactly (redundant copy). After stripping,
+    // deltas with no remaining fields are removed entirely.
     const filtered = {};
     for (const [key, stored] of Object.entries(channels)) {
-        if ((key in PREDEFINED_CHANNELS) && (Object.keys(stored).length === 0)) {
-            continue;
+        if (key in PREDEFINED_CHANNELS) {
+            const predefined = PREDEFINED_CHANNELS[key];
+            const cleaned = {};
+            let hasFields = false;
+            for (const [field, value] of Object.entries(stored)) {
+                // Skip non-delta fields (like canonicalKey) that aren't in the allowlist.
+                if (!DELTA_ALLOWED_FIELDS.has(field)) {
+                    continue;
+                }
+                // Skip undefined values — they have no effect.
+                if (value === undefined) {
+                    continue;
+                }
+                // Skip null values when the predefined doesn't have the field — clearing a nonexistent field is a no-op.
+                if ((value === null) && !(field in predefined)) {
+                    continue;
+                }
+                // Skip values that match the predefined exactly — redundant copies. Array fields (like tags) use JSON.stringify for comparison since reference equality
+                // always fails for arrays. Tags arrays are always sorted and lowercase, making JSON.stringify deterministic.
+                if (value !== null) {
+                    const predefinedValue = predefined[field];
+                    if (Array.isArray(value) ? (JSON.stringify(value) === JSON.stringify(predefinedValue)) : (predefinedValue === value)) {
+                        continue;
+                    }
+                }
+                cleaned[field] = value;
+                hasFields = true;
+            }
+            // Preserve non-delta fields (like canonicalKey) that were on the stored entry.
+            for (const [field, value] of Object.entries(stored)) {
+                if (!DELTA_ALLOWED_FIELDS.has(field) && (value !== undefined)) {
+                    cleaned[field] = value;
+                    hasFields = true;
+                }
+            }
+            if (hasFields) {
+                filtered[key] = cleaned;
+            }
+        }
+        else {
+            // User channels: strip null fields. Null is a delta convention for predefined channels ("clear this field") and has no meaning on full Channel definitions —
+            // the Channel type uses T | undefined, never T | null. This allows callers to uniformly use null for "empty/clear" without needing to know the storage convention.
+            filtered[key] = Object.fromEntries(Object.entries(stored).filter(([, v]) => v !== null));
         }
-        filtered[key] = stored;
-    }
-    // Sort channels by key for consistent output.
-    const sortedChannels = {};
-    const sortedKeys = Object.keys(filtered).sort();
-    for (const key of sortedKeys) {
-        sortedChannels[key] = filtered[key];
     }
-    // Include provider selections if any exist.
+    // Include metadata keys (provider selections, tag registry) if they have content.
     const selections = getProviderSelections();
+    const output = { ...filtered };
     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;
+        output.providerSelections = selections;
     }
-    // Write channels with pretty formatting for readability.
-    const content = JSON.stringify(sortedChannels, null, 2);
+    if ((loadedTagRegistry.tags.length > 0) || (loadedTagRegistry.deletedTags.length > 0)) {
+        output.tagRegistry = loadedTagRegistry;
+    }
+    // Write channels with pretty formatting and sorted keys for consistent, diff-friendly output.
+    const content = stringifySorted(output);
     await fsPromises.writeFile(getChannelsFilePath(), content + "\n", "utf-8");
     // Update in-memory cache so changes take effect immediately for new stream requests.
     loadedUserChannels = { ...filtered };
@@ -170,14 +226,102 @@ export async function resetUserChannels() {
  */
 export async function initializeUserChannels() {
     const result = await loadUserChannels();
+    // Silent migration: rename "foxcom" provider references to "foxone." Migrates provider selections (channels.json) and user channel variant keys. The
+    // provider filter (config.json) is handled separately below since it's already loaded into CONFIG at this point.
+    let channelsMigrated = false;
+    for (const [canonicalKey, selectedVariant] of Object.entries(result.providerSelections)) {
+        if (selectedVariant.endsWith("-foxcom")) {
+            result.providerSelections[canonicalKey] = selectedVariant.slice(0, -6) + "foxone";
+            channelsMigrated = true;
+        }
+    }
+    for (const key of Object.keys(result.channels)) {
+        if (key.endsWith("-foxcom")) {
+            result.channels[key.slice(0, -6) + "foxone"] = result.channels[key];
+            Reflect.deleteProperty(result.channels, key);
+            channelsMigrated = true;
+        }
+    }
+    // Load provider selections before saving so that saveUserChannels (which persists both channels and selections) captures the migrated values.
+    setProviderSelections(result.providerSelections);
+    if (channelsMigrated) {
+        await saveUserChannels(result.channels);
+        LOG.info("Migrated Fox provider references from foxcom to foxone.");
+    }
     loadedUserChannels = result.channels;
+    loadedTagRegistry = result.tagRegistry;
     userChannelsParseError = result.parseError;
     userChannelsParseErrorMessage = result.parseErrorMessage;
-    // Load provider selections from the file.
-    setProviderSelections(result.providerSelections);
     // Load enabled providers from the configuration, validating that each tag is recognized. Invalid tags (e.g., from hand-edited config.json typos) are stripped
     // silently after logging a warning. Validation must happen after buildProviderGroups() because getAllProviderTags() depends on the groups being built.
-    const configuredProviders = CONFIG.channels.enabledProviders;
+    let configuredProviders = CONFIG.channels.enabledProviders;
+    // Silent migration: rename "foxcom" to "foxone" in the provider filter if present. Persisted to config.json immediately so the stale value doesn't remain.
+    if (configuredProviders.includes("foxcom")) {
+        configuredProviders = configuredProviders.map((tag) => (tag === "foxcom") ? "foxone" : tag);
+        CONFIG.channels.enabledProviders = configuredProviders;
+        const configResult = await loadUserConfig();
+        if (configResult.config.channels?.enabledProviders) {
+            configResult.config.channels.enabledProviders = configuredProviders;
+            await saveUserConfig(configResult.config);
+        }
+        LOG.info("Migrated provider filter from foxcom to foxone.");
+    }
+    // Upgrade inference for setupCompleted: existing users who already have providers or channels configured should not see the first-run setup wizard. If the
+    // flag is not set in the config file and evidence of prior configuration exists, infer true and persist.
+    if (!CONFIG.channels.setupCompleted) {
+        const hasProviders = configuredProviders.length > 0;
+        const hasUserChannels = Object.keys(loadedUserChannels).length > 0;
+        if (hasProviders || hasUserChannels) {
+            CONFIG.channels.setupCompleted = true;
+            const configResult = await loadUserConfig();
+            configResult.config.channels ??= {};
+            configResult.config.channels.setupCompleted = true;
+            await saveUserConfig(configResult.config);
+        }
+    }
+    // One-time migration: stamp canonicalKey on existing user channel variant entries that were created before explicit variant relationships were introduced.
+    // These entries have hyphenated keys where the prefix is a known predefined canonical (e.g., "espn-hulu" where "espn" exists). The heuristic runs once —
+    // new entries get canonicalKey written at creation time by the browse modal.
+    let canonicalKeyMigrated = false;
+    for (const [key, channel] of Object.entries(result.channels)) {
+        // Skip entries that already have canonicalKey.
+        if (channel.canonicalKey) {
+            continue;
+        }
+        const hyphenIndex = key.indexOf("-");
+        if (hyphenIndex === -1) {
+            continue;
+        }
+        const prefix = key.substring(0, hyphenIndex);
+        // Only stamp canonicalKey if the prefix exists as a predefined channel. This matches the old buildProviderGroups heuristic exactly.
+        if (prefix in PREDEFINED_CHANNELS) {
+            channel.canonicalKey = prefix;
+            canonicalKeyMigrated = true;
+        }
+    }
+    if (canonicalKeyMigrated) {
+        await saveUserChannels(result.channels);
+        LOG.info("Migrated user channel variant entries with explicit canonical key declarations.");
+    }
+    // One-time migration: strip identity fields from user channel variant entries. Identity fields (name, stationId, tags, etc.) are resolved from the canonical
+    // at runtime via applyVariantInheritance, so storing them on variants is redundant. Older versions wrote these fields on variant creation. This migration
+    // cleans them up so channels.json only contains provider-specific fields on variant entries.
+    let variantFieldsMigrated = false;
+    for (const channel of Object.values(result.channels)) {
+        if (!channel.canonicalKey) {
+            continue;
+        }
+        for (const field of CHANNEL_IDENTITY_FIELDS) {
+            if (field in channel) {
+                Reflect.deleteProperty(channel, field);
+                variantFieldsMigrated = true;
+            }
+        }
+    }
+    if (variantFieldsMigrated) {
+        await saveUserChannels(result.channels);
+        LOG.info("Stripped redundant identity fields from user channel variant entries.");
+    }
     // Build the merged channels map and then build provider groups.
     const mergedChannels = getMergedChannelMap();
     buildProviderGroups(mergedChannels);
@@ -215,7 +359,11 @@ export async function initializeUserChannels() {
 }
 // Fields that users are allowed to override via delta. This allowlist prevents hand-edited channels.json from overriding fields like provider that are
 // intentionally not user-editable. Matches the fields in the ChannelDelta interface.
-const DELTA_ALLOWED_FIELDS = new Set(["channelNumber", "channelSelector", "name", "profile", "stationId", "tvgShift", "url"]);
+// User-editable fields for predefined channel delta overrides. Derived from CHANNEL_IDENTITY_FIELDS (identity fields like name, stationId, tags) plus the
+// provider-specific fields exposed in the edit form (channelSelector, profile, url). This derivation ensures that adding a new identity field to
+// CHANNEL_IDENTITY_FIELDS automatically includes it in the delta allowlist.
+const PROVIDER_SPECIFIC_EDITABLE_FIELDS = ["channelSelector", "profile", "url"];
+const DELTA_ALLOWED_FIELDS = new Set([...CHANNEL_IDENTITY_FIELDS, ...PROVIDER_SPECIFIC_EDITABLE_FIELDS]);
 /**
  * Resolves a stored channel entry (full definition or delta) into a fully resolved Channel. For user-defined channels with no predefined equivalent, the stored
  * entry is returned as-is (it must be a full Channel). For overrides of predefined channels, the predefined definition is used as a base and only allowlisted
@@ -232,7 +380,9 @@ export function resolveStoredChannel(key, stored) {
     if (!predefined) {
         return stored;
     }
-    // Start with a copy of the predefined definition, then overlay allowlisted non-null delta fields.
+    // Start with a copy of the predefined definition, then overlay allowlisted non-null delta fields. The spread creates a shallow copy — reference-type fields
+    // (like tags) share the same array instance as PREDEFINED_CHANNELS. The defensive copy below ensures the returned Channel is fully independent so callers can
+    // safely modify it without corrupting the predefined source of truth.
     const resolved = { ...predefined };
     for (const [field, value] of Object.entries(stored)) {
         if (!DELTA_ALLOWED_FIELDS.has(field)) {
@@ -247,6 +397,9 @@ export function resolveStoredChannel(key, stored) {
             resolved[field] = value;
         }
     }
+    // Defensive copy of reference-type fields to break shared references with PREDEFINED_CHANNELS. The delta overlay above may have replaced tags entirely (if
+    // the delta included a tags array), but when no delta is present for tags, the spread leaves the predefined's array reference on the resolved object.
+    resolved.tags &&= resolved.tags.slice();
     return resolved;
 }
 /**
@@ -326,8 +479,8 @@ export function getChannelListing() {
     return listing;
 }
 /**
- * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded unless they
- * have a user override. Built on top of getChannelListing() to ensure a single merging code path.
+ * Returns all available channels (predefined + user), with user channels taking precedence on key conflicts. Disabled predefined channels are excluded. Built on
+ * top of getChannelListing() to ensure a single merging code path.
  * @returns The merged channel map with disabled predefined channels filtered out.
  */
 export function getAllChannels() {
@@ -346,6 +499,85 @@ export function getAllChannels() {
 export function getUserChannels() {
     return { ...loadedUserChannels };
 }
+// Tag Registry.
+/**
+ * Returns the current tag registry state.
+ * @returns A copy of the tag registry with user-created tags and deleted predefined tags.
+ */
+export function getTagRegistry() {
+    return { deletedTags: [...loadedTagRegistry.deletedTags], tags: [...loadedTagRegistry.tags] };
+}
+/**
+ * Updates the tag registry state in memory. Call saveUserChannels() after to persist the change.
+ * @param registry - The new tag registry state.
+ */
+export function setTagRegistry(registry) {
+    loadedTagRegistry = { deletedTags: registry.deletedTags.sort(), tags: registry.tags.sort() };
+}
+/**
+ * Returns the active tag vocabulary: predefined tags minus user-deleted tags, plus user-created tags, sorted alphabetically. This is the single source of truth
+ * for which tags are visible, assignable, and queryable throughout the system. Tags not in this list are invisible to the UI and rejected by the ?tag= query
+ * parameter, even if they exist on channel definitions (vocabulary-as-lens model).
+ * @returns Sorted array of active tag strings.
+ */
+export function getActiveTagVocabulary() {
+    const deleted = new Set(loadedTagRegistry.deletedTags);
+    const active = PREDEFINED_TAGS.filter((tag) => !deleted.has(tag));
+    // Merge user tags, deduplicate (in case a user tag matches a non-deleted predefined tag), and sort.
+    const combined = new Set([...active, ...loadedTagRegistry.tags]);
+    return [...combined].sort();
+}
+/**
+ * Returns a channel's effective tags — the intersection of the channel's assigned tags with the active vocabulary. Tags that exist on the channel but are not in
+ * the active vocabulary are filtered out, ensuring only assignable and queryable tags are visible in the UI and playlist responses.
+ * @param channel - The channel to get effective tags for.
+ * @returns Sorted array of effective tag strings, or empty array if the channel has no tags or none are in the active vocabulary.
+ */
+export function getChannelEffectiveTags(channel) {
+    if (!channel.tags || (channel.tags.length === 0)) {
+        return [];
+    }
+    const vocabulary = new Set(getActiveTagVocabulary());
+    return channel.tags.filter((tag) => vocabulary.has(tag));
+}
+/**
+ * Applies a tag transformation across channels and persists the result. This is the single source of truth for batch tag mutations — delete, rename, and bulk
+ * toggle all route through this function. The caller provides a filter (which channels to transform) and a transform (how to modify each channel's tags). This
+ * function handles loading stored channel data, applying the transform, and saving. Delta normalization in saveUserChannels() handles predefined channel
+ * delta computation automatically — callers do not need to reason about deltas vs. full definitions.
+ * @param filter - Predicate selecting which listing entries to transform. Receives each ChannelListingEntry from getChannelListing().
+ * @param transform - Pure function mapping a channel's current resolved tags to its new tags. Receives the channel's current tags array (may be empty, ordering
+ *   not guaranteed). Must return the desired tags array (may be empty to clear all tags). The returned array is sorted before storage.
+ * @returns Object with the affected channel keys and success status. On parse error, returns an error message and empty affected keys.
+ */
+export async function transformChannelTags(filter, transform) {
+    const result = await loadUserChannels();
+    if (result.parseError) {
+        return { affectedKeys: [], error: "Cannot update tags: channels file contains invalid JSON." };
+    }
+    const affectedKeys = [];
+    for (const entry of getChannelListing()) {
+        if (!filter(entry)) {
+            continue;
+        }
+        const currentTags = entry.channel.tags ?? [];
+        const newTags = transform(currentTags).sort();
+        // Skip channels where the transform produced no change.
+        if (JSON.stringify(newTags) === JSON.stringify(currentTags.slice().sort())) {
+            continue;
+        }
+        // Set the new tags on the stored entry. Callers use null uniformly for "clear/empty" — saveUserChannels() handles the storage conventions: delta normalization
+        // for predefined channels (comparing against raw definitions), null-stripping for user channels (null has no meaning on full Channel definitions).
+        const existing = result.channels[entry.key] ?? {};
+        existing.tags = (newTags.length > 0) ? newTags : null;
+        result.channels[entry.key] = existing;
+        affectedKeys.push(entry.key);
+    }
+    if (affectedKeys.length > 0) {
+        await saveUserChannels(result.channels);
+    }
+    return { affectedKeys };
+}
 /**
  * Returns the predefined channel definition for a key.
  * @param key - The channel key to look up.
@@ -362,6 +594,78 @@ export function getPredefinedChannel(key) {
 export function isPredefinedChannel(key) {
     return key in PREDEFINED_CHANNELS;
 }
+/**
+ * Returns the East canonical key for a Pacific channel. Pacific canonicals are auto-generated by generatePacificDefinitions with a "p" suffix (e.g., "disneyp"
+ * from "disney"). When a Pacific canonical's logo or other brand-level metadata is unavailable, the East counterpart provides a fallback. Returns undefined
+ * when the key is not a Pacific canonical (doesn't end with "p" or the base key isn't predefined).
+ * @param key - The channel key to check.
+ * @returns The East canonical key if this is a Pacific channel, undefined otherwise.
+ */
+export function getEastCanonicalKey(key) {
+    if (!key.endsWith("p")) {
+        return undefined;
+    }
+    const eastKey = key.slice(0, -1);
+    return isPredefinedChannel(eastKey) ? eastKey : undefined;
+}
+// Logo cache. Logo URLs are fetched from the Channels DVR API and cached by Gracenote station ID. The cache is populated in two tiers by showInfo.ts: first from
+// the DVR's /devices endpoint (covers all channels in the M3U playlist), then via TMS station name search for any remaining channels. The cache refreshes every
+// 24 hours and updates on individual channel add/edit operations.
+// Logo cache keyed by Gracenote station ID. Populated by showInfo.ts via setChannelLogos() and setChannelLogo().
+const logoCache = new Map();
+/**
+ * Bulk-populates the logo cache from a stationId-to-URL map. Called by showInfo.ts after fetching logo data from the DVR. Existing entries are overwritten with
+ * fresh data to pick up any logo URL changes (e.g., network rebrands).
+ * @param logos - Map of Gracenote station ID to logo URL.
+ */
+export function setChannelLogos(logos) {
+    for (const [stationId, url] of logos) {
+        logoCache.set(stationId, url);
+    }
+}
+/**
+ * Sets a single logo cache entry. Called by showInfo.ts after a TMS station name search for a single channel (tier 2 population or channel add/edit).
+ * @param stationId - The Gracenote station ID.
+ * @param url - The logo URL.
+ */
+export function setChannelLogo(stationId, url) {
+    logoCache.set(stationId, url);
+}
+/**
+ * Clears the logo cache. Called on shutdown to release memory.
+ */
+export function clearChannelLogos() {
+    logoCache.clear();
+}
+/**
+ * Resolves a channel key to its effective Gracenote station ID. Pacific channels (e.g., "bravop") resolve to their east counterpart's station ID since
+ * they share the same brand logo. User channel overrides that change the stationId are reflected. Returns undefined if the channel has no stationId.
+ * @param channelKey - The channel key to resolve (e.g., "amc", "bravop").
+ * @returns The Gracenote station ID, or undefined.
+ */
+export function getChannelStationId(channelKey) {
+    // Pacific channels are regional feeds of the same brand as their east counterparts, so we resolve to the east variant's station ID for logo purposes.
+    const effectiveKey = getEastCanonicalKey(channelKey) ?? channelKey;
+    // User channels take precedence - resolveStoredChannel merges deltas with the predefined base, so overrides that change the stationId are reflected here.
+    return (effectiveKey in loadedUserChannels) ?
+        resolveStoredChannel(effectiveKey, loadedUserChannels[effectiveKey]).stationId :
+        // 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
+        PREDEFINED_CHANNELS[effectiveKey]?.stationId;
+}
+/**
+ * Returns the logo URL for a channel from the cache. Pacific channels (e.g., "bravop") are resolved to their east counterpart automatically. The cache is
+ * populated by showInfo.ts from the Channels DVR API - this function only reads from it.
+ * @param channelKey - The channel key to look up (e.g., "amc", "bravop"). Pacific keys resolve to their east variant internally.
+ * @returns The logo URL if cached, undefined otherwise.
+ */
+export function getChannelLogo(channelKey) {
+    const stationId = getChannelStationId(channelKey);
+    if (!stationId) {
+        return undefined;
+    }
+    return logoCache.get(stationId);
+}
 /**
  * Checks if a channel key exists in the user channels.
  * @param key - The channel key to check.
@@ -374,19 +678,15 @@ export function isUserChannel(key) {
  * re-enable. This is useful for users who don't want certain predefined channels cluttering their channel list.
  */
 /**
- * Checks if a predefined channel is disabled.
+ * Checks if a predefined channel is disabled. The disabled state is determined solely by the disabledPredefined list in config — the user's explicit visibility
+ * intent. Property overrides (HDHR toggle, name change, tag edits) stored as deltas in channels.json are orthogonal and do not affect the enabled/disabled state.
  * @param key - The channel key to check.
  * @returns True if the channel is predefined and disabled.
  */
 export function isPredefinedChannelDisabled(key) {
-    // Only predefined channels can be disabled via this mechanism.
     if (!isPredefinedChannel(key)) {
         return false;
     }
-    // If a user channel overrides this predefined channel, the predefined channel's disabled state is irrelevant.
-    if (isUserChannel(key)) {
-        return false;
-    }
     return CONFIG.channels.disabledPredefined.includes(key);
 }
 /**
@@ -512,6 +812,28 @@ export function validateChannelKey(key, isNew) {
     }
     return undefined;
 }
+/**
+ * Validates a channel number for range and uniqueness. Returns an error message if invalid, undefined if valid. Empty string means no channel number (valid).
+ * This is the single source of truth for channel number validation, shared by the full edit handler and the inline-edit handler.
+ * @param value - The channel number as a string (from form input or inline edit). Empty means "no number."
+ * @param excludeKey - The channel key being edited, excluded from the duplicate check.
+ * @returns Error message if invalid, undefined if valid.
+ */
+export function validateChannelNumber(value, excludeKey) {
+    if (!value) {
+        return undefined;
+    }
+    const num = parseInt(value, 10);
+    if (Number.isNaN(num) || (num < 1) || (num > 99999)) {
+        return "Channel number must be between 1 and 99999.";
+    }
+    for (const entry of getChannelListing()) {
+        if ((entry.channel.channelNumber === num) && (entry.key !== excludeKey)) {
+            return "Channel number " + String(num) + " is already used by '" + entry.key + "'.";
+        }
+    }
+    return undefined;
+}
 /**
  * Validates a channel URL.
  * @param url - The URL to validate.
@@ -686,4 +1008,12 @@ export async function saveProviderSelections() {
     // Simply save the user channels — the saveUserChannels function includes provider selections automatically.
     await saveUserChannels(loadedUserChannels);
 }
+/**
+ * Saves the current tag registry to the channels file. This triggers a full file save including all user channels.
+ * @throws If the file cannot be written.
+ */
+export async function saveTagRegistry() {
+    // Simply save the user channels — the saveUserChannels function includes the tag registry automatically.
+    await saveUserChannels(loadedUserChannels);
+}
 //# sourceMappingURL=userChannels.js.map