prismcast 1.4.1 → 1.5.0

package/dist/browser/tuning/hulu.js

@@ -1,34 +1,132 @@
 import { LOG, delay, evaluateWithAbort, formatError } from "../../utils/index.js";
 import { logAvailableChannels, normalizeChannelName, scrollAndClick } from "../channelSelection.js";
 import { CONFIG } from "../../config/index.js";
-// Guide grid row number cache. Maps lowercased, trimmed channel names from data-testid attributes to their row numbers (from sr-only text). Populated passively
-// during binary search iterations and used for direct-scroll optimization on subsequent tunes. Session-scoped — cleared when the browser restarts.
-const guideRowCache = new Map();
-// Hulu channel UUID cache. Maps normalized channel names (from guide.hulu.com/guide/details API responses) to channel UUIDs used in the playlist API's channel_id
-// field. Populated server-side by intercepting details API responses during page load. Session-scoped — cleared when the browser restarts via clearHuluCache().
-const huluUuidCache = new Map();
-// Hulu channel EAB cache. Maps channel UUIDs to their program schedules (from guide.hulu.com/guide/listing API responses). Each entry is an array of programs with
-// EAB IDs and airing times. Used to supply the correct content_eab_id when swapping channel_id in the playlist API request — the server requires a valid EAB for
-// the target channel. Session-scoped — cleared when the browser restarts via clearHuluCache().
-const huluEabCache = new Map();
+// Unified channel cache for Hulu. Maps normalized channel names to their combined entry. Aliases (e.g., "abc" → same entry as "wls") share object references for
+// automatic propagation of fresh programs and EAB data. Cleared on browser disconnect via clearHuluCache().
+const huluChannelCache = new Map();
+// Transient staging map for listing API response data. Maps channel UUIDs to their program schedules. Populated from listing API responses (which arrive before
+// details responses due to the interceptor's listingCapturedPromise hold). Read by populateHuluChannelCache when the details response arrives, joining UUID-keyed
+// programs with name-keyed entries. Also used to propagate fresh programs to existing cache entries when a new listing response arrives.
+const huluListingStaging = new Map();
+// Tracks whether a full discovery walk (with affiliate position inference) has completed. When true, buildHuluDiscoveredChannels can return comprehensive results
+// including proper affiliate labeling. When false, getCachedChannels returns null to force a fresh discovery walk.
+let huluFullyDiscovered = false;
 // Tracks pages with details API response listeners to avoid duplicate registration. Mirrors the pagesWithListeners pattern in sling.ts.
 const huluPagesWithListeners = new WeakSet();
 // The Hulu live page URL. The evaluateOnNewDocument fetch interceptor swaps channel_id and content_eab_id in the playlist API request, making the app play the
-// target channel through its own pipeline without guide grid interaction. On warm cache, UUID and EAB are injected at install time. On cold cache (non-affiliate),
-// the interceptor captures them from listing and details API responses during page load, holding the playlist request until both are resolved.
+// target channel through its own pipeline without guide grid interaction. On warm cache, UUID and EAB are injected at install time. On cold cache, the guide
+// grid's Channels tab click triggers full API expansion, and the interceptor captures UUID+EAB from those expanded responses.
 const HULU_LIVE_URL = "https://www.hulu.com/live";
 /**
- * Clears all Hulu caches: guide row cache, channel UUID cache, and EAB program cache. Called by clearChannelSelectionCaches() in the coordinator when the
+ * Clears all Hulu caches: the unified channel cache, listing staging map, and discovery flag. Called by clearChannelSelectionCaches() in the coordinator when the
  * browser restarts, since cached state may be stale in a new browser session.
  */
 function clearHuluCache() {
-    guideRowCache.clear();
-    huluEabCache.clear();
-    huluUuidCache.clear();
+    huluChannelCache.clear();
+    huluFullyDiscovered = false;
+    huluListingStaging.clear();
+}
+/**
+ * Resolves the actual cache key for a normalized channel name, with a fuzzy fallback that strips all non-alphanumeric characters to handle formatting mismatches
+ * between channelSelector values and Hulu's API naming (e.g., "C-SPAN3" vs "C-SPAN 3", "HBO2" vs "HBO 2"). Used by findHuluChannelEntry (lookup) and
+ * invalidateHuluDirectUrl (deletion) to ensure both paths handle the same set of name variants.
+ * @param normalizedName - The normalized (lowercased, whitespace-collapsed) channel name to resolve.
+ * @returns The actual cache key, or null if no match found.
+ */
+function resolveHuluCacheKey(normalizedName) {
+    if (huluChannelCache.has(normalizedName)) {
+        return normalizedName;
+    }
+    // Fuzzy fallback: strip all non-alphanumeric characters and compare. Handles formatting differences in spaces, hyphens, ampersands, and other punctuation
+    // between channelSelector definitions and Hulu's Details API channel_info.name values.
+    const stripped = normalizedName.replace(/[^a-z0-9]/g, "");
+    for (const key of huluChannelCache.keys()) {
+        if (key.replace(/[^a-z0-9]/g, "") === stripped) {
+            return key;
+        }
+    }
+    return null;
+}
+/**
+ * Looks up a channel in the unified cache by normalized name, with fuzzy fallback via resolveHuluCacheKey. Only used for lookups keyed by channelSelector —
+ * internal cache operations that use API-derived names should use huluChannelCache.get() directly.
+ * @param normalizedName - The normalized (lowercased, whitespace-collapsed) channel name to look up.
+ * @returns The matching cache entry, or null if no match found.
+ */
+function findHuluChannelEntry(normalizedName) {
+    const key = resolveHuluCacheKey(normalizedName);
+    return key ? huluChannelCache.get(key) ?? null : null;
+}
+/**
+ * Populates the unified channel cache from a details API response. For each item with channel_info, creates or updates the entry keyed by normalized name,
+ * joining the details data (name, UUID) with programs from the listing staging map. Updates existing entries in-place to preserve alias references and
+ * supplementary fields (rowNumber, affiliate) that may have been set by guide grid operations.
+ * @param items - Array of details response items containing channel_info with name and id.
+ */
+function populateHuluChannelCache(items) {
+    const channelsSeen = new Set();
+    for (const item of items) {
+        const info = item.channel_info;
+        if (info?.name && info.id) {
+            const normalized = normalizeChannelName(info.name);
+            const existing = huluChannelCache.get(normalized);
+            const programs = huluListingStaging.get(info.id) ?? existing?.programs;
+            if (existing) {
+                // Update in-place to preserve alias references and supplementary fields (rowNumber, affiliate).
+                existing.displayName = info.name;
+                existing.uuid = info.id;
+                if (programs) {
+                    existing.programs = programs;
+                }
+            }
+            else {
+                huluChannelCache.set(normalized, { displayName: info.name, programs, uuid: info.id });
+            }
+            channelsSeen.add(info.name);
+        }
+    }
+    LOG.debug("tuning:hulu", "Details API: %s items, %s unique channels. Channel cache size: %s.", items.length, channelsSeen.size, huluChannelCache.size);
+}
+/**
+ * Finds the currently-airing EAB from a program schedule array. Searches the programs for one whose airing window brackets the current time. Returns null if the
+ * array is empty or no program is currently airing (stale data or program boundary gap).
+ * @param programs - Array of programs with EAB IDs and airing times.
+ * @returns The currently-airing EAB string, or null if no match.
+ */
+function findCurrentEabFromPrograms(programs) {
+    const now = Date.now();
+    for (const program of programs) {
+        if ((now >= new Date(program.airingStart).getTime()) && (now < new Date(program.airingEnd).getTime())) {
+            return program.eab;
+        }
+    }
+    return null;
+}
+/**
+ * Derives a DiscoveredChannel array from the unified channel cache, deduplicating alias entries via Set reference equality. Affiliates produce entries with the
+ * network name as channelSelector; non-affiliates use their display name. Used by getCachedChannels and discoverHuluChannels when returning from warm cache.
+ * @returns Sorted array of discovered channels.
+ */
+function buildHuluDiscoveredChannels() {
+    const channels = [];
+    const seen = new Set();
+    for (const entry of huluChannelCache.values()) {
+        if (seen.has(entry)) {
+            continue;
+        }
+        seen.add(entry);
+        const result = { channelSelector: entry.affiliate ?? entry.displayName, name: entry.displayName };
+        if (entry.affiliate) {
+            result.affiliate = entry.affiliate;
+        }
+        channels.push(result);
+    }
+    channels.sort((a, b) => a.name.localeCompare(b.name));
+    return channels;
 }
 /**
  * Reads all rendered channel containers from the guide grid, extracting their names from data-testid attributes and row numbers from sr-only text. Populates the
- * row number cache as a side effect.
+ * unified channel cache with rowNumber and displayName as a side effect.
  * @param page - The Puppeteer page object.
  * @returns Array of rendered channels in DOM order, or null if no channels are rendered.
  */
@@ -43,38 +141,104 @@ async function readRenderedChannels(page) {
         for (const el of Array.from(containers)) {
             const testid = el.getAttribute("data-testid") ?? "";
             const name = testid.slice(prefix.length).trim().replace(/\s+/g, " ").toLowerCase();
-            // Extract row number from sr-only text. Format: "{Name} Details, row {N} of {Total}. ..."
+            // Extract the original-cased display name and row number from sr-only text. Format: "{Name} Details, row {N} of {Total}. ..." The data-testid attribute
+            // is lowercased by Hulu's app, so the sr-only text is the only source of original casing (e.g., "CNN" vs "cnn", "A&E" vs "a&e").
+            let displayName = name;
             let rowNumber = -1;
             const btn = el.querySelector("[data-testid=\"live-guide-channel-button\"]");
             if (btn) {
                 const srOnly = btn.querySelector(".sr-only, [class*=\"sr-only\"]");
                 if (srOnly) {
-                    const match = /row (\d+) of/.exec(srOnly.textContent);
-                    if (match) {
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                    const text = srOnly.textContent ?? "";
+                    const nameMatch = /^(.+?) Details, row/.exec(text);
+                    if (nameMatch) {
+                        displayName = nameMatch[1].trim();
+                    }
+                    const rowMatch = /row (\d+) of/.exec(text);
+                    if (rowMatch) {
                         // Row numbers in sr-only text are 1-based. Convert to 0-based for scroll offset calculation.
-                        rowNumber = parseInt(match[1], 10) - 1;
+                        rowNumber = parseInt(rowMatch[1], 10) - 1;
                     }
                 }
             }
-            results.push({ name, rowNumber });
+            results.push({ displayName, name, rowNumber });
         }
         return results;
     });
     if (!channels) {
         return null;
     }
-    // Assign DOM indices and populate the row number cache.
+    // Assign DOM indices and populate the unified channel cache with row numbers and display names.
     const rendered = [];
     for (let i = 0; i < channels.length; i++) {
         const ch = channels[i];
-        rendered.push({ domIndex: i, name: ch.name, rowNumber: ch.rowNumber });
-        // Cache the row number for future direct-scroll lookups.
+        rendered.push({ displayName: ch.displayName, domIndex: i, name: ch.name, rowNumber: ch.rowNumber });
+        // Cache the row number and display name for future direct-scroll lookups.
         if (ch.rowNumber >= 0) {
-            guideRowCache.set(ch.name, ch.rowNumber);
+            const existing = huluChannelCache.get(ch.name);
+            if (existing) {
+                existing.rowNumber = ch.rowNumber;
+            }
+            else {
+                huluChannelCache.set(ch.name, { displayName: ch.displayName, rowNumber: ch.rowNumber });
+            }
         }
     }
     return rendered;
 }
+/**
+ * Reads grid metadata from the Hulu live guide by walking up from a rendered row element to find the spacer and viewport divs. Measures the actual row height
+ * from the first rendered row's bounding rect rather than assuming a hardcoded pixel value. The spacer div is the direct parent of all absolutely-positioned
+ * rows, and its height equals totalRows * rowHeight. The viewport div is the spacer's parent (overflow: hidden). We calculate gridDocTop as the viewport's
+ * document-level offset, so that scrolling to gridDocTop + (rowIndex * rowHeight) places that row at the top of the browser viewport. Shared by both
+ * guideGridStrategy and discoverHuluChannels.
+ * @param page - The Puppeteer page object.
+ * @returns Grid metadata or null if the grid structure is not found.
+ */
+async function readGridMeta(page) {
+    return await page.evaluate(() => {
+        const row = document.querySelector("[data-testid=\"live-guide-row\"]");
+        if (!row) {
+            return null;
+        }
+        // Measure the actual row height from the rendered element rather than assuming a hardcoded value.
+        const rowHeight = row.getBoundingClientRect().height;
+        if (rowHeight <= 0) {
+            return null;
+        }
+        // The spacer div is the parent of all row elements.
+        const spacer = row.parentElement;
+        if (!spacer) {
+            return null;
+        }
+        const spacerHeight = spacer.offsetHeight;
+        if (spacerHeight < rowHeight) {
+            return null;
+        }
+        // The viewport div is the spacer's parent. Its position relative to the document determines our scroll offset.
+        const viewport = spacer.parentElement;
+        if (!viewport) {
+            return null;
+        }
+        const gridDocTop = viewport.getBoundingClientRect().top + document.documentElement.scrollTop;
+        return { gridDocTop, rowHeight, totalRows: Math.round(spacerHeight / rowHeight) };
+    });
+}
+/**
+ * Scrolls the Hulu live guide to the specified row index and waits for the virtualizer to render. The scroll target is calculated from the grid's document-level
+ * offset and the dynamically measured row height. Shared by guideGridStrategy (binary search) and discoverHuluChannels (linear scan).
+ * @param page - The Puppeteer page object.
+ * @param gridDocTop - The grid viewport's document-level top offset (from readGridMeta).
+ * @param rowHeight - The measured row height in pixels (from readGridMeta).
+ * @param rowIndex - The zero-based row index to scroll to.
+ */
+async function scrollToGuideRow(page, gridDocTop, rowHeight, rowIndex) {
+    await page.evaluate((scrollTo) => {
+        document.documentElement.scrollTop = scrollTo;
+    }, gridDocTop + (rowIndex * rowHeight));
+    await delay(200);
+}
 /**
  * Locates the on-now program cell for the channel at the given data-testid name (lowercased, trimmed), scrolls it into view, and returns its center coordinates
  * for a subsequent page.mouse.click(). We return coordinates rather than clicking inside the evaluate because page.mouse.click() generates the full pointer event
@@ -315,26 +479,60 @@ async function clickOnNowCellAndPlay(page, clickTarget, playSelector, channelNam
     return { reason: "Play button did not appear after " + String(MAX_CLICK_ATTEMPTS) + " on-now cell click attempts for " + channelName + ".", success: false };
 }
 /**
- * Attempts to tune to a channel via the fast path: injects UUID and EAB into the in-page fetch interceptor, which swaps the held playlist request to the target
- * channel. Called after binary search identifies a local affiliate whose UUID and EAB are available in the server-side caches. On success, dismisses the guide
- * overlay so the video player is visible for capture, then returns true. On failure (interceptor's directTunePromise already resolved due to timeout), returns
- * false so the caller can fall through to the click-based path.
+ * Attempts a fast-path tune by either injecting UUID+EAB from the unified cache into the in-page interceptor, or detecting that the interceptor has already
+ * self-resolved from in-page API data. Two resolution mechanisms handle different channel types:
+ *
+ * 1. Server-side injection: finds the currently-airing EAB from the entry's program schedule and calls __prismcastResolveDirectTune to inject both values into the
+ *    held playlist request. Primary mechanism for local affiliates whose call signs don't match the channelSelector network name — the interceptor can't
+ *    self-resolve by name for these, so external injection is the only path.
+ * 2. Self-resolution detection: queries __prismcastIsDirectTuneResolved to check if the interceptor already captured UUID+EAB from the expanded
+ *    Details+Listing API responses and resolved the playlist autonomously. Primary mechanism for non-affiliate channels on cold cache, where the interceptor's
+ *    in-page name matching succeeds before the guide grid completes binary search.
+ *
+ * On success, dismisses the guide overlay so the video player is visible for capture.
  * @param page - The Puppeteer page object.
- * @param channelUuid - The channel UUID to inject into the interceptor.
- * @param currentEab - The currently-airing EAB to inject into the interceptor.
+ * @param entry - The unified cache entry for the target channel, or null if not yet available.
  * @param channelName - The original channel name for logging.
- * @returns True if the injection succeeded, false if the interceptor's Promise had already resolved.
+ * @returns True if the tune was resolved (via injection or self-resolution), false otherwise.
  */
-async function tryFastPathTune(page, channelUuid, currentEab, channelName) {
-    const injected = await page.evaluate((u, e) => {
-        const resolver = window.__prismcastResolveDirectTune;
-        if (typeof resolver === "function") {
-            return resolver(u, e);
+async function tryFastPathTune(page, entry, channelName) {
+    let resolved = false;
+    let resolveDetail = "";
+    // Phase 1: If UUID and programs are available from the unified cache, attempt to inject the UUID along with the current EAB into the in-page interceptor. This
+    // is the primary mechanism for local affiliates (where the interceptor can't self-resolve by name) and a secondary mechanism for exact-match channels.
+    if (entry?.uuid && entry.programs) {
+        const currentEab = findCurrentEabFromPrograms(entry.programs);
+        if (currentEab) {
+            const injected = await page.evaluate((u, e) => {
+                const resolver = window.__prismcastResolveDirectTune;
+                if (typeof resolver === "function") {
+                    return resolver(u, e);
+                }
+                return false;
+            }, entry.uuid, currentEab);
+            if (injected) {
+                resolved = true;
+                resolveDetail = "uuid=" + entry.uuid;
+            }
         }
-        return false;
-    }, channelUuid, currentEab);
-    if (!injected) {
-        LOG.debug("tuning:hulu", "Fast-path injection failed for %s (interceptor Promise already resolved).", channelName);
+    }
+    // Phase 2: If injection didn't succeed, check if the interceptor self-resolved from in-page API data. This happens on cold cache for non-affiliate channels
+    // whose names match the Details API response (e.g., "CNN International", "ESPN"). The interceptor captures UUID+EAB from the expanded Details+Listing
+    // responses triggered by the Channels tab click and resolves the held playlist autonomously, making the guide grid click redundant.
+    if (!resolved) {
+        const selfResolved = await page.evaluate(() => {
+            const checker = window.__prismcastIsDirectTuneResolved;
+            if (typeof checker === "function") {
+                return checker();
+            }
+            return false;
+        });
+        if (selfResolved) {
+            resolved = true;
+            resolveDetail = "interceptor self-resolved from API data";
+        }
+    }
+    if (!resolved) {
         return false;
     }
     // Dismiss the guide overlay so the video player is visible for capture. The guide was opened for binary search and is still covering the player.
@@ -345,13 +543,13 @@ async function tryFastPathTune(page, channelUuid, currentEab, channelName) {
     catch (error) {
         LOG.debug("tuning:hulu", "Could not dismiss guide after fast-path tune: %s.", formatError(error));
     }
-    LOG.debug("tuning:hulu", "Direct tune via fetch interception for inferred affiliate %s (uuid=%s).", channelName, channelUuid);
+    LOG.debug("tuning:hulu", "Direct tune via fetch interception for %s (%s).", channelName, resolveDetail);
     return true;
 }
 /**
- * Releases the held playlist request in the in-page fetch interceptor, reverting to the click-based flow. Called when the fast-path injection can't proceed
- * (UUID or EAB not in server-side caches) or wasn't attempted. Sets holdActive to false in the interceptor so subsequent playlist requests from the play button
- * click follow the affiliate capture path ([HULU-CACHE]).
+ * Releases the held playlist request in the in-page fetch interceptor, reverting to the click-based flow. Called when tryFastPathTune returns false (neither
+ * server-side injection nor interceptor self-resolution succeeded). Sets holdActive to false in the interceptor so subsequent playlist requests from the play
+ * button click follow the affiliate capture path ([HULU-CACHE]).
  * @param page - The Puppeteer page object.
  */
 async function releaseHeldPlaylist(page) {
@@ -376,7 +574,7 @@ async function releaseHeldPlaylist(page) {
  * The selection process:
  * 1. If listSelector is provided, click the tab/button to reveal the channel list (e.g., a "Channels" tab)
  * 2. Wait for the channel grid rows to render in the DOM
- * 3. Check the row number cache for a direct-scroll shortcut
+ * 3. Check the unified cache for a row number direct-scroll shortcut
  * 4. Binary search: scroll to the midpoint row, read rendered channels (caching row numbers), check for exact match or infer local affiliate
  * 5. If binary search fails, linear scan from top to bottom as a universal fallback
  * 6. Click the on-now program cell (`.LiveGuideProgram--first`) in the target channel's row to open the playback overlay
@@ -433,53 +631,21 @@ async function guideGridStrategy(page, profile) {
     if (!rowsVisible) {
         return { reason: "Channel grid rows did not render.", success: false };
     }
-    // Each row in the virtualized grid is exactly 112px tall. The total number of channels is derived from the spacer div's height.
-    const ROW_HEIGHT = 112;
     // Normalize the channel name to lowercase for case-insensitive matching against data-testid suffixes.
     const normalizedName = normalizeChannelName(channelName);
-    // Read grid metadata by walking up from a rendered row to find the spacer and viewport divs. The spacer div is the direct parent of all absolutely-positioned
-    // rows, and its height equals totalRows * ROW_HEIGHT. The viewport div is the spacer's parent (overflow: hidden). We calculate gridDocTop as the viewport's
-    // document-level offset, so that scrolling to gridDocTop + (rowIndex * ROW_HEIGHT) places that row at the top of the browser viewport.
-    const gridMeta = await page.evaluate((rowHeight) => {
-        const row = document.querySelector("[data-testid=\"live-guide-row\"]");
-        if (!row) {
-            return null;
-        }
-        // The spacer div is the parent of all row elements.
-        const spacer = row.parentElement;
-        if (!spacer) {
-            return null;
-        }
-        const spacerHeight = spacer.offsetHeight;
-        if (spacerHeight < rowHeight) {
-            return null;
-        }
-        // The viewport div is the spacer's parent. Its position relative to the document determines our scroll offset.
-        const viewport = spacer.parentElement;
-        if (!viewport) {
-            return null;
-        }
-        const gridDocTop = viewport.getBoundingClientRect().top + document.documentElement.scrollTop;
-        return { gridDocTop, totalRows: Math.round(spacerHeight / rowHeight) };
-    }, ROW_HEIGHT);
+    const gridMeta = await readGridMeta(page);
     if (!gridMeta) {
         return { reason: "Could not locate channel grid spacer element.", success: false };
     }
-    const { gridDocTop, totalRows } = gridMeta;
-    // Helper: scroll to a specific row index and wait for the virtualizer to render.
-    const scrollToRow = async (rowIndex) => {
-        await page.evaluate((scrollTo) => {
-            document.documentElement.scrollTop = scrollTo;
-        }, gridDocTop + (rowIndex * ROW_HEIGHT));
-        await delay(200);
-    };
+    const { gridDocTop, rowHeight, totalRows } = gridMeta;
     // The name of the channel to click. This starts as the normalized target name but may be replaced by a local affiliate call sign via position inference.
     let clickTarget = normalizedName;
-    // Check the row number cache for a direct-scroll shortcut. If we've seen this channel before, we can skip binary search entirely and scroll directly to it.
-    const cachedRow = guideRowCache.get(normalizedName);
-    if (cachedRow !== undefined) {
-        LOG.debug("tuning:hulu", "Guide cache hit for %s at row %s.", channelName, cachedRow);
-        await scrollToRow(cachedRow);
+    // Check the unified cache for a row number direct-scroll shortcut. If we've seen this channel before, we can skip binary search entirely and scroll directly
+    // to it. Uses fuzzy lookup to handle channelSelector/API name formatting mismatches.
+    const cachedEntry = findHuluChannelEntry(normalizedName);
+    if (cachedEntry?.rowNumber !== undefined) {
+        LOG.debug("tuning:hulu", "Guide cache hit for %s at row %s.", channelName, cachedEntry.rowNumber);
+        await scrollToGuideRow(page, gridDocTop, rowHeight, cachedEntry.rowNumber);
         // Read rendered channels to update the cache and confirm the channel is present.
         const rendered = await readRenderedChannels(page);
         if (rendered) {
@@ -488,9 +654,9 @@ async function guideGridStrategy(page, profile) {
                 return await clickOnNowCellAndPlay(page, normalizedName, playSelector, channelName);
             }
         }
-        // Cache hit but channel not found at expected position. The guide may have changed. Clear this entry and fall through to binary search.
+        // Cache hit but channel not found at expected position. The guide may have changed. Clear the row number and fall through to binary search.
         LOG.debug("tuning:hulu", "Guide cache miss for %s. Falling back to binary search.", channelName);
-        guideRowCache.delete(normalizedName);
+        cachedEntry.rowNumber = undefined;
     }
     // Binary search through the virtualized channel list. On each iteration we scroll to the midpoint of the current range, wait for the virtualizer to render,
     // then check if the target channel is among the ~13 rendered rows. If not, we compare the target name alphabetically against the first and last rendered
@@ -505,8 +671,8 @@ async function guideGridStrategy(page, profile) {
         }
         const mid = Math.floor((low + high) / 2);
         // eslint-disable-next-line no-await-in-loop
-        await scrollToRow(mid);
-        // Read all rendered channels, populating the row number cache as a side effect.
+        await scrollToGuideRow(page, gridDocTop, rowHeight, mid);
+        // Read all rendered channels, populating the unified cache with row numbers as a side effect.
         // eslint-disable-next-line no-await-in-loop
         const rendered = await readRenderedChannels(page);
         if (!rendered || (rendered.length === 0)) {
@@ -546,28 +712,17 @@ async function guideGridStrategy(page, profile) {
             LOG.debug("tuning:hulu", "Inferred local affiliate %s for network name %s.", inferred, channelName);
             clickTarget = inferred;
             found = true;
-            // Cache the network name → affiliate's row number so subsequent tunes for the same network name become direct scrolls.
-            const inferredRow = guideRowCache.get(inferred);
-            if (inferredRow !== undefined) {
-                guideRowCache.set(normalizedName, inferredRow);
-            }
-            // Cross-reference the UUID cache so the network name can resolve to a warm-cache direct tune on subsequent requests. The details API returns the local
-            // call sign as channel_info.name, so the UUID cache is keyed by call sign. The user's channelSelector uses the network name (e.g., "ABC"). Without this
+            // Cross-reference the unified cache so the network name resolves to a warm-cache direct tune on subsequent requests. The details API returns the local
+            // call sign as channel_info.name, so the cache is keyed by call sign. The user's channelSelector uses the network name (e.g., "ABC"). Without this
             // cross-reference, local affiliates would always fall through to cold-cache guide grid tunes because the names never match.
-            const inferredUuid = huluUuidCache.get(inferred);
-            if (inferredUuid) {
-                huluUuidCache.set(normalizedName, inferredUuid);
-                LOG.debug("tuning:hulu", "Cross-referenced UUID cache: %s -> %s (from inferred affiliate %s).", channelName, inferredUuid, inferred);
-                // Fast path: inject UUID+EAB into the in-page interceptor to tune via fetch interception instead of clicking. The server-side caches are populated
-                // from details and listing API responses during page load, which typically complete before binary search finishes (~600ms). If both UUID and EAB are
-                // available, the interceptor swaps the held playlist request to the target channel — no on-now cell click or play button interaction needed.
-                const currentEab = findCurrentEab(inferredUuid);
-                if (currentEab) {
-                    // eslint-disable-next-line no-await-in-loop
-                    const fastPathSuccess = await tryFastPathTune(page, inferredUuid, currentEab, channelName);
-                    if (fastPathSuccess) {
-                        return { success: true };
-                    }
+            const inferredEntry = huluChannelCache.get(inferred);
+            if (inferredEntry) {
+                huluChannelCache.set(normalizedName, inferredEntry);
+                LOG.debug("tuning:hulu", "Cross-referenced cache: %s -> %s (from inferred affiliate %s).", channelName, inferredEntry.uuid ?? "no-uuid", inferred);
+                // eslint-disable-next-line no-await-in-loop
+                const fastPathSuccess = await tryFastPathTune(page, inferredEntry, channelName);
+                if (fastPathSuccess) {
+                    return { success: true };
                 }
             }
         }
@@ -580,7 +735,7 @@ async function guideGridStrategy(page, profile) {
         LOG.debug("tuning:hulu", "Binary search did not find %s. Starting linear scan fallback.", channelName);
         for (let row = 0; row < totalRows; row += 10) {
             // eslint-disable-next-line no-await-in-loop
-            await scrollToRow(row);
+            await scrollToGuideRow(page, gridDocTop, rowHeight, row);
             // eslint-disable-next-line no-await-in-loop
             const rendered = await readRenderedChannels(page);
             if (!rendered) {
@@ -594,9 +749,9 @@ async function guideGridStrategy(page, profile) {
         }
     }
     if (!found) {
-        // Log available channels from the guide row cache to help users identify the correct channelSelector value. The cache accumulates all channel names encountered
-        // during binary search and linear scan, so it contains most or all channels even though the virtualized grid only renders ~13 at a time.
-        const availableChannels = Array.from(guideRowCache.keys()).sort();
+        // Log available channels from the unified cache to help users identify the correct channelSelector value. The cache accumulates all channel names
+        // encountered during binary search and linear scan, so it contains most or all channels even though the virtualized grid only renders ~13 at a time.
+        const availableChannels = Array.from(huluChannelCache.keys()).sort();
         if (availableChannels.length > 0) {
             logAvailableChannels({
                 availableChannels,
@@ -608,8 +763,17 @@ async function guideGridStrategy(page, profile) {
         }
         return { reason: "Could not find channel " + channelName + " in guide grid.", success: false };
     }
-    // Release the held playlist before falling through to the click path. This is a safety net — the inference block releases the hold in all its sub-paths, but
-    // exact-match and linear-scan paths may reach here without having released. The release is a no-op if the hold was already released or was never active.
+    // Fast path: attempt direct tune via unified cache injection or interceptor self-resolution detection. The Channels tab click (before binary search)
+    // triggers full Details+Listing API responses. For non-affiliates, the in-page interceptor may have already self-resolved from those responses (capturing
+    // UUID+EAB and swapping the playlist autonomously). For channels where the interceptor hasn't self-resolved, the unified cache provides UUID+EAB for
+    // injection. Either path avoids the redundant on-now cell click. Note: for affiliates, the inference block above may have already called tryFastPathTune with
+    // the same entry — that call is redundant here but harmless (~10ms), and avoiding it with a flag would create a fragile coupling to the inference block.
+    const fastPathSuccess = await tryFastPathTune(page, findHuluChannelEntry(normalizedName), channelName);
+    if (fastPathSuccess) {
+        return { success: true };
+    }
+    // Release the held playlist before falling through to the click path. Neither tryFastPathTune nor the inference block calls releaseHeldPlaylist — they either
+    // inject successfully (resolving the held playlist directly) or return false without side effects. The release is a no-op if the hold was already resolved.
     await releaseHeldPlaylist(page);
     // Click the on-now program cell and wait for the play button, with click retries to handle React hydration timing.
     return await clickOnNowCellAndPlay(page, clickTarget, playSelector, channelName);
@@ -638,11 +802,11 @@ async function guideGridWithRetry(page, profile) {
     return result;
 }
 /**
- * Sets up server-side response interception on the page to capture channel UUID mappings from Hulu's guide details API and EAB schedules from the listing API.
- * As the live page loads, Hulu fetches program details from guide.hulu.com/guide/details in batches. Each response item includes channel_info with the
- * channel's UUID and display name. We intercept these responses to populate the huluUuidCache, enabling instant UUID resolution on subsequent tunes. The
- * in-page interceptor in resolveHuluDirectUrl() expands details request bodies with additional EABs so these responses cover all ~123 channels. Also bridges
- * in-page console signals (HULU-DIAG and HULU-CACHE) to the Node.js LOG. Uses a WeakSet to prevent duplicate listener registration.
+ * Sets up server-side response interception on the page to capture channel data from Hulu's guide APIs. As the live page loads, Hulu fetches program details from
+ * guide.hulu.com/guide/details in batches and program schedules from guide.hulu.com/guide/listing. We intercept both responses to populate the unified channel
+ * cache: listing data goes into the staging map (UUID → programs), then details data triggers populateHuluChannelCache which joins name → UUID with staged
+ * programs. Also bridges in-page console signals (HULU-DIAG, HULU-CACHE, HULU-FAIL) to the Node.js LOG. Uses a WeakSet to prevent duplicate listener
+ * registration.
  * @param page - The Puppeteer page object.
  */
 function setupDetailsResponseInterception(page) {
@@ -658,45 +822,56 @@ function setupDetailsResponseInterception(page) {
             LOG.debug("tuning:hulu", text);
         }
         // Affiliate UUID capture: the in-page interceptor emits "[HULU-CACHE] targetName=channelUuid" when it observes a playlist passthrough for an affiliate guide
-        // grid tune. Cache the UUID under the channelSelector key so subsequent tunes resolve via warm direct tuning instead of the guide grid.
+        // grid tune. Find the existing entry by UUID and create an alias under the channelSelector key so subsequent tunes resolve via warm direct tuning.
         if (text.startsWith("[HULU-CACHE] ")) {
             const payload = text.slice("[HULU-CACHE] ".length);
             const eqIdx = payload.indexOf("=");
             if (eqIdx > 0) {
                 const name = payload.slice(0, eqIdx);
                 const channelUuid = payload.slice(eqIdx + 1);
-                huluUuidCache.set(name, channelUuid);
-                LOG.debug("tuning:hulu", "Cached affiliate UUID from playlist: %s -> %s. UUID cache size: %s.", name, channelUuid, huluUuidCache.size);
+                // Find the existing entry by UUID to create an alias (shared object reference). If no entry exists yet, create a new one with programs from staging.
+                let existingEntry = null;
+                for (const e of huluChannelCache.values()) {
+                    if (e.uuid === channelUuid) {
+                        existingEntry = e;
+                        break;
+                    }
+                }
+                if (existingEntry) {
+                    huluChannelCache.set(name, existingEntry);
+                }
+                else {
+                    huluChannelCache.set(name, { displayName: name, programs: huluListingStaging.get(channelUuid), uuid: channelUuid });
+                }
+                LOG.debug("tuning:hulu", "Cached affiliate UUID from playlist: %s -> %s. Channel cache size: %s.", name, channelUuid, huluChannelCache.size);
             }
         }
+        // Direct tune failure: the interceptor's hold period expired without resolving UUID+EAB for the target channel. The 503 response prevents Hulu from playing
+        // the wrong channel. The guide grid binary search runs as the fallback. Since all cold tunes go through the guide grid (triggering full API expansion), this
+        // path should rarely be reached — it provides defense-in-depth against silent false positives.
+        if (text.startsWith("[HULU-FAIL]")) {
+            LOG.warn(text);
+        }
     });
     page.on("response", (response) => {
         const url = response.url();
         if (response.status() !== 200) {
             return;
         }
-        // Details API: capture channel UUID mappings for the persistent cache.
+        // Details API: populate the unified channel cache by joining name → UUID from this response with programs from the listing staging map.
         if (url.includes("guide.hulu.com/guide/details")) {
             void response.json().then((data) => {
                 if (!Array.isArray(data.items)) {
                     return;
                 }
-                const channelsSeen = new Set();
-                for (const item of data.items) {
-                    const info = item.channel_info;
-                    if (info?.name && info.id) {
-                        huluUuidCache.set(normalizeChannelName(info.name), info.id);
-                        channelsSeen.add(info.name);
-                    }
-                }
-                LOG.debug("tuning:hulu", "Details API: %s items, %s unique channels. UUID cache size: %s.", data.items.length, channelsSeen.size, huluUuidCache.size);
+                populateHuluChannelCache(data.items);
             }).catch(() => {
                 // CORS preflight responses (OPTIONS) return empty bodies that fail JSON parsing. This is expected and harmless.
             });
             return;
         }
-        // Listing API: capture program schedules (EABs with airing times) for each channel. The app fires listing requests on every page load covering all ~130
-        // channels with ~8 hours of programs. We cache the full schedule per channel UUID so resolveHuluDirectUrl can find the currently-airing EAB at tune time.
+        // Listing API: capture program schedules (EABs with airing times) into the staging map, then propagate fresh programs to existing unified cache entries. The
+        // app fires listing requests on every page load covering all ~130 channels with ~8 hours of programs.
         if (url.includes("guide.hulu.com/guide/listing")) {
             void response.json().then((data) => {
                 if (!Array.isArray(data.channels)) {
@@ -705,93 +880,89 @@ function setupDetailsResponseInterception(page) {
                 let programCount = 0;
                 for (const channel of data.channels) {
                     if (channel.id && Array.isArray(channel.programs) && (channel.programs.length > 0)) {
-                        huluEabCache.set(channel.id, channel.programs);
+                        huluListingStaging.set(channel.id, channel.programs);
                         programCount += channel.programs.length;
                     }
                 }
-                LOG.debug("tuning:hulu", "Listing API: %s channels, %s programs. EAB cache size: %s.", data.channels.length, programCount, huluEabCache.size);
+                // Propagate fresh programs to existing unified cache entries. Aliases share object references, so updating one entry automatically propagates to all
+                // aliases for the same channel.
+                for (const entry of huluChannelCache.values()) {
+                    if (entry.uuid) {
+                        const freshPrograms = huluListingStaging.get(entry.uuid);
+                        if (freshPrograms) {
+                            entry.programs = freshPrograms;
+                        }
+                    }
+                }
+                LOG.debug("tuning:hulu", "Listing API: %s channels, %s programs. Staging size: %s.", data.channels.length, programCount, huluListingStaging.size);
             }).catch(() => {
                 // CORS preflight responses (OPTIONS) return empty bodies that fail JSON parsing. This is expected and harmless.
             });
         }
     });
 }
-/**
- * Finds the currently-airing EAB for a channel from the EAB cache. Searches the cached program schedule for the given channel UUID and returns the EAB of the
- * program whose airing window brackets the current time. Returns null if the channel has no cached programs or if no program is currently airing (stale cache
- * or program boundary gap).
- * @param channelUuid - The channel UUID to look up in the EAB cache.
- * @returns The currently-airing EAB string, or null if no match.
- */
-function findCurrentEab(channelUuid) {
-    const programs = huluEabCache.get(channelUuid);
-    if (!programs) {
-        return null;
-    }
-    const now = Date.now();
-    for (const program of programs) {
-        if ((now >= new Date(program.airingStart).getTime()) && (now < new Date(program.airingEnd).getTime())) {
-            return program.eab;
-        }
-    }
-    return null;
-}
 /**
  * Resolves a direct URL for Hulu channel tuning and installs a fetch interceptor that handles both warm and cold tunes. On warm cache (UUID and EAB known from
- * previous API responses), the interceptor has both values at install time and swaps the first playlist request immediately. On cold cache, the interceptor
- * captures the target channel's UUID from the details API response and EAB from the listing API response, holding the playlist request until both are resolved
- * (with an 8-second timeout). On all tunes, the interceptor also expands listing and details API requests to populate the full UUID cache (~123 channels) for
- * future warm tunes. Returns null only for known local affiliate network names on cold cache (ABC, CBS, NBC, Fox, PBS, CW) — their channel_info.name in the
- * details API uses call signs that don't match the channelSelector, so the guide grid handles them via position-based inference.
+ * previous API responses), the interceptor has both values at install time and swaps the first playlist request immediately. On cold cache (no UUID), returns
+ * null so the guide grid runs — the Channels tab click triggers full Details+Listing API expansion for all ~123 channels, and the interceptor captures UUID+EAB
+ * from those expanded responses to resolve the held playlist. Without the Channels tab click, the initial page load only provides data for ~10 visible channels.
+ * On all tunes, the interceptor also expands listing and details API requests to populate the full cache for future warm tunes.
  * @param channelSelector - The channel selector string (e.g., "Fox", "CNN", "ESPN").
  * @param page - The Puppeteer page for evaluateOnNewDocument installation and response interception setup.
- * @returns The Hulu live URL for direct tuning, or null for local affiliate networks on cold cache or interceptor installation failure.
+ * @returns The Hulu live URL for direct tuning, or null on cold cache (no UUID) or interceptor installation failure.
  */
 async function resolveHuluDirectUrl(channelSelector, page) {
     const normalizedName = normalizeChannelName(channelSelector);
-    const cachedUuid = huluUuidCache.get(normalizedName) ?? null;
-    // Set up server-side response listeners to populate the UUID and EAB caches. Must be set up before navigation so we capture details and listing API responses
+    const cachedEntry = findHuluChannelEntry(normalizedName);
+    const cachedUuid = cachedEntry?.uuid ?? null;
+    // Set up server-side response listeners to populate the unified channel cache. Must be set up before navigation so we capture details and listing API responses
     // during both the guide grid flow (cold cache) and the intercepted page load (warm cache).
     setupDetailsResponseInterception(page);
-    // Look up the currently-airing EAB for the target channel (if UUID is known). On warm cache (both UUID and EAB available), the interceptor has both at install
-    // time and swaps immediately. On cold cache or stale EAB, the interceptor captures the values from API responses during page load, holding the playlist until
-    // both are resolved. The guide grid only runs for local affiliate network names (NETWORK_NAMES_WITH_AFFILIATES) whose names don't match the details API.
-    const cachedEab = cachedUuid ? findCurrentEab(cachedUuid) : null;
+    // Look up the currently-airing EAB for the target channel (if UUID and programs are known). On warm cache (both UUID and EAB available), the interceptor has
+    // both at install time and swaps immediately. On cold cache (no UUID), we return null below so the guide grid runs — the Channels tab click triggers full API
+    // expansion.
+    const cachedEab = (cachedEntry?.programs) ? findCurrentEabFromPrograms(cachedEntry.programs) : null;
     const isWarmCache = Boolean(cachedUuid && cachedEab);
     if (isWarmCache) {
         LOG.debug("tuning:hulu", "resolveHuluDirectUrl: warm cache for %s (uuid=%s, eab=%s).", channelSelector, cachedUuid, cachedEab);
     }
     else if (!cachedUuid) {
-        // On cold cache, local affiliate network names fall through to the guide grid because their channel_info.name uses call signs that the interceptor
-        // can't match. All other channels attempt cold direct tuning — the interceptor captures UUID+EAB from API responses during page load.
+        // On cold cache, all channels fall through to the guide grid — the Channels tab click triggers full Details+Listing API expansion for all ~123 channels.
+        // The affiliate/non-affiliate distinction is diagnostic only (both return null). Affiliates use position-based inference; non-affiliates use exact match.
         if (NETWORK_NAMES_WITH_AFFILIATES.has(normalizedName)) {
             LOG.debug("tuning:hulu", "resolveHuluDirectUrl: cold cache for %s (local affiliate). Falling through to guide grid.", channelSelector);
         }
         else {
-            LOG.debug("tuning:hulu", "resolveHuluDirectUrl: cold cache for %s. Attempting cold direct tune via API interception.", channelSelector);
+            LOG.debug("tuning:hulu", "resolveHuluDirectUrl: cold cache for %s. Falling through to guide grid for full API expansion.", channelSelector);
         }
     }
     else {
         LOG.debug("tuning:hulu", "resolveHuluDirectUrl: UUID cached for %s but no current EAB. Attempting direct tune via API interception.", channelSelector);
     }
-    // Collect all unique UUIDs from the cache for listing API request expansion. On warm tunes, this keeps EAB schedules fresh for all known channels. On cold
-    // tunes after the first, this expands the listing request beyond the mini-guide's ~10 UUIDs. Empty on the very first cold tune (no cached data yet).
-    const allCachedUuids = [...new Set(huluUuidCache.values())];
-    // Collect one current EAB per cached channel for details API request expansion. On warm tunes, this fills the UUID cache completely. On cold tunes after the
-    // first, this supplements the in-page listing-derived EABs. Empty on the very first cold tune — the interceptor builds EABs dynamically from the listing API
-    // response instead.
+    // Collect all unique UUIDs and current EABs from the unified cache for API request expansion. On warm tunes, this keeps EAB schedules fresh for all known
+    // channels. On cold tunes after the first, this expands requests beyond the mini-guide's ~10 channels. Empty on the very first cold tune.
+    const seenEntries = new Set();
+    const allCachedUuids = [];
     const allCurrentEabs = [];
-    for (const channelUuid of huluEabCache.keys()) {
-        const currentEab = findCurrentEab(channelUuid);
-        if (currentEab) {
-            allCurrentEabs.push(currentEab);
+    for (const entry of huluChannelCache.values()) {
+        if (!entry.uuid || seenEntries.has(entry)) {
+            continue;
+        }
+        seenEntries.add(entry);
+        allCachedUuids.push(entry.uuid);
+        if (entry.programs) {
+            const currentEab = findCurrentEabFromPrograms(entry.programs);
+            if (currentEab) {
+                allCurrentEabs.push(currentEab);
+            }
         }
     }
     /* Install the fetch interceptor before navigation on both warm and cold tunes. On warm tunes, it swaps channel_id and content_eab_id in playlist requests
-     * immediately. On cold non-affiliate tunes, it holds the playlist request and swaps after capturing both values from listing and details API responses. On all
-     * tunes, it captures listing API responses to build an in-page EAB map and expands subsequent details API requests, populating the UUID cache to ~123 channels
-     * on a single page load. The script runs via evaluateOnNewDocument — it executes before any page JavaScript, patching window.fetch so Hulu's module-scoped
-     * fetch reference captures the interceptor. Each stream gets its own page via createPageWithCapture(), so there's no persistence concern.
+     * immediately. On cold tunes, the guide grid's Channels tab click triggers full API expansion, and the interceptor holds the playlist request until both
+     * UUID and EAB are captured from those responses. On all tunes, it captures listing API responses to build an in-page EAB map and expands subsequent
+     * details API requests, populating the UUID cache to ~123 channels on a single page load. The script runs via evaluateOnNewDocument — it executes before
+     * any page JavaScript, patching window.fetch so Hulu's module-scoped fetch reference captures the interceptor. Each stream gets its own page via
+     * createPageWithCapture(), so there's no persistence concern.
      */
     try {
         // Always hold the playlist request. On warm cache, the interceptor swaps immediately. On cold cache (including affiliates), the guide grid strategy will either
@@ -832,18 +1003,23 @@ async function resolveHuluDirectUrl(channelSelector, page) {
             const directTunePromise = (uuid && eab) ?
                 Promise.resolve() :
                 new Promise((resolve) => { directTuneResolve = resolve; });
+            // Tracks whether the direct tune has been successfully resolved (UUID+EAB available and playlist swap in progress). Set by tryResolveDirectTune when both
+            // values are captured from API responses or injected externally. Warm cache starts resolved. Used by __prismcastIsDirectTuneResolved to let the guide grid
+            // strategy detect that the interceptor already handled the tune autonomously, avoiding a redundant on-now cell click.
+            let directTuneResolved = Boolean(uuid && eab);
             // Checks whether both UUID and EAB are now known and resolves directTunePromise if so. Called after each successful capture from listing or details API
             // responses. Order-independent — handles both "listing first, details second" and "details first, listing second" sequences.
             function tryResolveDirectTune() {
                 if (uuid && eab && directTuneResolve) {
+                    directTuneResolved = true;
                     directTuneResolve();
                     directTuneResolve = null;
                 }
             }
-            // Injection endpoint for the guide grid strategy's fast-path affiliate tune. After binary search identifies the local affiliate and the server-side caches
-            // provide the UUID and EAB, the strategy calls this function via page.evaluate to feed both values into the interceptor. The held playlist request then
-            // resumes with the swapped channel_id and content_eab_id. Returns true if the injection was accepted (directTunePromise not yet resolved), false if the
-            // Promise already resolved (8s timeout expired or a previous injection).
+            // Injection endpoint for the guide grid strategy's fast-path tune. After binary search identifies the target channel and the unified cache provides the
+            // UUID and EAB, the strategy calls this function via page.evaluate to feed both values into the interceptor. The held playlist request then resumes with the
+            // swapped channel_id and content_eab_id. Returns true if the injection was accepted (directTunePromise not yet resolved), false if the Promise already
+            // resolved (self-resolution from API data, 8s timeout, or a previous injection).
             window.__prismcastResolveDirectTune = (u, e) => {
                 if (!directTuneResolve) {
                     return false;
@@ -853,7 +1029,7 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                 tryResolveDirectTune();
                 return true;
             };
-            // Release endpoint for the guide grid strategy's click-path fallback. When the fast-path injection can't proceed (UUID or EAB not in server-side caches),
+            // Release endpoint for the guide grid strategy's click-path fallback. When the fast-path injection can't proceed (UUID or EAB not in unified cache),
             // the strategy calls this to unblock the held playlist request and revert to the click-based flow. Sets holdActive to false so the playlist handler follows
             // the affiliate capture path ([HULU-CACHE]) on subsequent requests from the play button click.
             window.__prismcastReleasePlaylist = () => {
@@ -863,6 +1039,10 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                     directTuneResolve = null;
                 }
             };
+            // Query endpoint for the guide grid strategy to check if the interceptor has already resolved the direct tune. Returns true if the playlist was swapped
+            // (self-resolution from API data, external injection, or warm cache). The guide grid checks this after finding the target channel — if the interceptor
+            // already handled the tune, the on-now cell click is redundant and can be skipped.
+            window.__prismcastIsDirectTuneResolved = () => directTuneResolved;
             // In-page EAB map built dynamically from listing API responses. On the first cold tune, cachedEabs is empty (no pre-computed data from Node.js), so this
             // map is the sole source of expansion data for details API requests. Populated asynchronously when the first listing response arrives.
             const capturedCurrentEabs = new Map();
@@ -875,7 +1055,7 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                 listingCapturedResolve = resolve;
             });
             // Fire-and-forget: parses a listing API response to build the in-page EAB map. For each channel, finds the currently-airing program by comparing airing
-            // times against the current time, mirroring the server-side findCurrentEab() logic. Called on all listing return paths (expanded and passthrough).
+            // times against the current time, mirroring the server-side findCurrentEabFromPrograms() logic. Called on all listing return paths (expanded and passthrough).
             function captureListingData(response) {
                 try {
                     void response.clone().json().then((data) => {
@@ -1062,8 +1242,9 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                 if (url.includes("play.hulu.com") && url.includes("playlist")) {
                     // Wait for UUID and EAB to be available. On warm cache, directTunePromise resolved immediately at creation time. On cold cache with holdActive
                     // enabled, this holds the playlist request until either: (1) the guide grid strategy injects UUID+EAB via __prismcastResolveDirectTune (fast path), or
-                    // (2) the in-page listing/details parsers capture both values (cold non-affiliate), or (3) the 8-second timeout expires (safety net). When holdActive
-                    // is false (set by __prismcastReleasePlaylist after fast-path failure), the playlist passes through with affiliate UUID capture for the click fallback.
+                    // (2) the in-page listing/details parsers capture both values from the guide grid's Channels tab expansion, or (3) the 8-second timeout expires and the
+                    // interceptor returns a 503 (safety net). When holdActive is false (set by __prismcastReleasePlaylist after fast-path failure), the playlist passes
+                    // through with affiliate UUID capture for the click fallback.
                     if (holdActive) {
                         await Promise.race([directTunePromise, new Promise((resolve) => { setTimeout(resolve, 8000); })]);
                     }
@@ -1093,8 +1274,8 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                             return originalFetch(input, init);
                         }
                         // eslint-disable-next-line no-console
-                        console.log("[HULU-DIAG] Playlist passthrough: no uuid/eab resolved for " + targetName + " (uuid=" + uuid + ", eab=" + (eab ? "yes" : "no") + ").");
-                        return originalFetch(input, init);
+                        console.log("[HULU-FAIL] Direct tune failed for " + targetName + ": uuid/eab not resolved within hold period.");
+                        return new Response("", { status: 503 });
                     }
                     const bodyText = await getBodyText(input, init);
                     if (bodyText) {
@@ -1124,27 +1305,172 @@ async function resolveHuluDirectUrl(channelSelector, page) {
         LOG.debug("tuning:hulu", "Failed to install Hulu fetch interceptor: %s.", formatError(error));
         return null;
     }
-    // For known local affiliate network names on cold cache, skip cold direct tuning — the channel_info.name in the details API uses the local call sign
-    // rather than the network name, so the in-page interceptor can't match by name. The guide grid handles these via position-based inference and
-    // cross-references the UUID for warm tunes on subsequent requests.
-    if (!cachedUuid && NETWORK_NAMES_WITH_AFFILIATES.has(normalizedName)) {
+    // On cold cache (no UUID), fall through to the guide grid. The initial page load only provides Details API data for ~10 visible channels — the guide grid's
+    // Channels tab click triggers full expansion for all ~123 channels, and the interceptor captures UUID+EAB from those expanded responses to resolve the held
+    // playlist. Affiliates additionally need position-based inference because their channel_info.name uses call signs rather than network names.
+    if (!cachedUuid) {
         return null;
     }
     LOG.debug("tuning:hulu", "Fetch interceptor installed. Returning URL: %s.", HULU_LIVE_URL);
     return HULU_LIVE_URL;
 }
 /**
- * Invalidates the cached channel UUID for the given channel selector. Called when a cached direct URL fails to produce a working stream, so the next tune
- * attempts the cold cache path (details API extraction) or falls back to the guide grid.
+ * Invalidates the cached entry for the given channel selector. Called when a cached direct URL fails to produce a working stream, so the next tune attempts the
+ * cold cache path (details API extraction) or falls back to the guide grid. Uses resolveHuluCacheKey for fuzzy name matching so invalidation works even when the
+ * channelSelector format doesn't exactly match the API-derived key. Deletes the specific key without affecting entries that share the same object reference
+ * via aliasing.
  * @param channelSelector - The channel selector string to invalidate.
  */
 function invalidateHuluDirectUrl(channelSelector) {
-    huluUuidCache.delete(normalizeChannelName(channelSelector));
+    const key = resolveHuluCacheKey(normalizeChannelName(channelSelector));
+    if (key) {
+        huluChannelCache.delete(key);
+    }
+}
+/**
+ * Discovers all channels from Hulu Live TV by clicking the Channels tab to trigger full API expansion and performing a complete linear scan through the
+ * virtualized guide grid. The route has already navigated to the Hulu live page. Detects local affiliates using the same CALL_SIGN_PATTERN and position-based
+ * inference logic as the tuning strategy. Affiliates get the network name as their selector; non-affiliates get their display name. Enriches unified cache
+ * entries with affiliate metadata for subsequent getCachedChannels derivation.
+ * @param page - The Puppeteer page object, already on the Hulu live page (navigated by the route handler).
+ * @returns Array of discovered channels with affiliate detection and selector mapping.
+ */
+async function discoverHuluChannels(page) {
+    // Return from the unified cache if a full discovery walk (with affiliate inference) has already completed.
+    if (huluFullyDiscovered && (huluChannelCache.size > 0)) {
+        return buildHuluDiscoveredChannels();
+    }
+    // Set up response interception BEFORE navigation so we capture the initial details and listing API responses during page load. These responses populate the
+    // unified channel cache with UUID, programs, and display names for all ~130 channels — warming the tuning cache as a side effect of discovery. The same
+    // setupDetailsResponseInterception function used by the tuning path ensures a single code path for all API response processing.
+    setupDetailsResponseInterception(page);
+    try {
+        await page.goto(HULU_LIVE_URL, { timeout: CONFIG.streaming.navigationTimeout, waitUntil: "networkidle2" });
+    }
+    catch {
+        return [];
+    }
+    // Click the Channels tab to reveal the channel list and trigger full API expansion. Matches the tuning path's retry logic — if guide rows don't appear after
+    // the first tab click, retry once with a longer delay in case the first click fired during a transitional state before the guide was fully interactive.
+    const listSelector = "#CHANNELS";
+    try {
+        await page.waitForSelector(listSelector, { timeout: CONFIG.streaming.videoTimeout, visible: true });
+        await page.$eval(listSelector, (el) => { el.click(); });
+        await delay(300);
+    }
+    catch {
+        return [];
+    }
+    let rowsVisible = false;
+    for (let guideAttempt = 0; guideAttempt < 2; guideAttempt++) {
+        try {
+            const rowTimeout = (guideAttempt === 0) ? 5000 : CONFIG.streaming.videoTimeout;
+            // eslint-disable-next-line no-await-in-loop
+            await page.waitForSelector("[data-testid=\"live-guide-row\"]", { timeout: rowTimeout, visible: true });
+            rowsVisible = true;
+            break;
+        }
+        catch {
+            // Rows not visible yet. On first failure, retry the tab click in case the guide wasn't fully interactive.
+            if (guideAttempt === 0) {
+                try {
+                    // eslint-disable-next-line no-await-in-loop
+                    await page.$eval(listSelector, (el) => { el.click(); });
+                    // eslint-disable-next-line no-await-in-loop
+                    await delay(500);
+                }
+                catch {
+                    // Retry click failed. Fall through to final wait attempt.
+                }
+            }
+        }
+    }
+    if (!rowsVisible) {
+        return [];
+    }
+    // Read grid metadata to determine total rows and scroll offset. Reuses the shared readGridMeta helper.
+    const gridMeta = await readGridMeta(page);
+    if (!gridMeta) {
+        return [];
+    }
+    const { gridDocTop, rowHeight, totalRows } = gridMeta;
+    // Linear scan through the entire guide grid to collect all channels. Step by 10 rows (~the virtualizer render window) to cover the full list.
+    const allChannels = [];
+    const seenNames = new Set();
+    for (let row = 0; row < totalRows; row += 10) {
+        // eslint-disable-next-line no-await-in-loop
+        await scrollToGuideRow(page, gridDocTop, rowHeight, row);
+        // eslint-disable-next-line no-await-in-loop
+        const rendered = await readRenderedChannels(page);
+        if (!rendered) {
+            continue;
+        }
+        for (const ch of rendered) {
+            if (!seenNames.has(ch.name)) {
+                seenNames.add(ch.name);
+                allChannels.push(ch);
+            }
+        }
+    }
+    // Reassign sequential domIndex values across the full accumulated list so that inferLocalAffiliate's position-based logic works correctly. The original
+    // domIndex values are from individual scroll windows (0-12) and are not meaningful across the full channel list.
+    const indexedChannels = allChannels.map((ch, i) => ({ ...ch, domIndex: i }));
+    // Build a callSign → networkName map by reusing inferLocalAffiliate for each broadcast network. This is the same position-based inference the tuning strategy
+    // uses during binary search — a call sign channel occupies the alphabetical position where its network name would sort.
+    const affiliateMap = new Map();
+    for (const network of NETWORK_NAMES_WITH_AFFILIATES) {
+        const callSign = inferLocalAffiliate(indexedChannels, network);
+        if (callSign) {
+            affiliateMap.set(callSign, network.toUpperCase());
+        }
+    }
+    // Enrich unified cache entries with affiliate metadata so buildHuluDiscoveredChannels can derive proper affiliate labeling on subsequent getCachedChannels calls.
+    for (const [callSign, network] of affiliateMap) {
+        const entry = huluChannelCache.get(callSign);
+        if (entry) {
+            entry.affiliate = network;
+        }
+    }
+    // Build discovery results from the walk data. The unified cache may have incomplete entries on cold start (no API data), so we build from the walk results
+    // directly to ensure all channels are included.
+    const discovered = indexedChannels.map((ch) => {
+        const network = affiliateMap.get(ch.name);
+        if (network) {
+            return { affiliate: network, channelSelector: network, name: ch.displayName };
+        }
+        return { channelSelector: ch.displayName, name: ch.displayName };
+    });
+    // Do not cache empty results — leave the flag false so subsequent calls retry the full walk. Empty results can indicate no Hulu + Live TV subscription.
+    if (discovered.length > 0) {
+        discovered.sort((a, b) => a.name.localeCompare(b.name));
+        huluFullyDiscovered = true;
+    }
+    return discovered;
+}
+/**
+ * Returns cached discovered channels from the unified channel cache, or null if a full discovery walk (with affiliate position inference) has not yet completed.
+ * Derives the result on the fly from unified cache entries, deduplicating aliases via Set reference equality.
+ * @returns Sorted array of discovered channels or null.
+ */
+function getHuluCachedChannels() {
+    if (!huluFullyDiscovered || (huluChannelCache.size === 0)) {
+        return null;
+    }
+    return buildHuluDiscoveredChannels();
 }
-export const huluStrategy = {
-    clearCache: clearHuluCache,
-    execute: guideGridWithRetry,
-    invalidateDirectUrl: invalidateHuluDirectUrl,
-    resolveDirectUrl: resolveHuluDirectUrl
+export const huluProvider = {
+    discoverChannels: discoverHuluChannels,
+    getCachedChannels: getHuluCachedChannels,
+    guideUrl: "https://www.hulu.com/live",
+    handlesOwnNavigation: true,
+    label: "Hulu",
+    slug: "hulu",
+    strategy: {
+        clearCache: clearHuluCache,
+        execute: guideGridWithRetry,
+        invalidateDirectUrl: invalidateHuluDirectUrl,
+        resolveDirectUrl: resolveHuluDirectUrl
+    },
+    strategyName: "guideGrid"
 };
 //# sourceMappingURL=hulu.js.map