prismcast 1.10.2 → 1.11.0

package/dist/browser/tuning/hulu.js

@@ -1,16 +1,22 @@
 import { LOG, delay, evaluateWithAbort, formatError } from "../../utils/index.js";
-import { logAvailableChannels, normalizeChannelName, scrollAndClick } from "./shared.js";
+import { installOrReplaceOnNewDocument, logAvailableChannels, normalizeChannelName, scrollAndClick } from "./shared.js";
 import { CONFIG } from "../../config/index.js";
+import { createProviderChannelCache } from "./cache.js";
+import { searchVirtualizedGrid } from "./gridSearch.js";
 // 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();
+// automatic propagation of fresh programs and EAB data. Cleared on browser disconnect via clearHuluCache(). An affiliate projects into discovery output with its
+// network name as the channelSelector; every other channel projects with its display name.
+const huluCache = createProviderChannelCache((entry) => {
+    const result = { channelSelector: entry.affiliate ?? entry.displayName, name: entry.displayName };
+    if (entry.affiliate) {
+        result.affiliate = entry.affiliate;
+    }
+    return result;
+});
 // 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
@@ -18,12 +24,11 @@ const huluPagesWithListeners = new WeakSet();
 // 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: 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.
+ * Clears all Hulu caches: the unified channel cache along with its completeness mark, and the listing staging map. Called by clearChannelSelectionCaches() in the
+ * coordinator when the browser restarts, since cached state may be stale in a new browser session.
  */
 function clearHuluCache() {
-    huluChannelCache.clear();
-    huluFullyDiscovered = false;
+    huluCache.clear();
     huluListingStaging.clear();
 }
 /**
@@ -34,13 +39,13 @@ function clearHuluCache() {
  * @returns The actual cache key, or null if no match found.
  */
 function resolveHuluCacheKey(normalizedName) {
-    if (huluChannelCache.has(normalizedName)) {
+    if (huluCache.map.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()) {
+    for (const key of huluCache.map.keys()) {
         if (key.replace(/[^a-z0-9]/g, "") === stripped) {
             return key;
         }
@@ -49,13 +54,13 @@ function resolveHuluCacheKey(normalizedName) {
 }
 /**
  * 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.
+ * internal cache operations that use API-derived names should use huluCache.map.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;
+    return key ? huluCache.map.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,
@@ -69,7 +74,7 @@ function populateHuluChannelCache(items) {
         const info = item.channel_info;
         if (info?.name && info.id) {
             const normalized = normalizeChannelName(info.name);
-            const existing = huluChannelCache.get(normalized);
+            const existing = huluCache.map.get(normalized);
             const programs = huluListingStaging.get(info.id) ?? existing?.programs;
             if (existing) {
                 // Update in-place to preserve alias references and supplementary fields (rowNumber, affiliate).
@@ -80,12 +85,12 @@ function populateHuluChannelCache(items) {
                 }
             }
             else {
-                huluChannelCache.set(normalized, { displayName: info.name, programs, uuid: info.id });
+                huluCache.map.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);
+    LOG.debug("tuning:hulu", "Details API: %s items, %s unique channels. Channel cache size: %s.", items.length, channelsSeen.size, huluCache.map.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
@@ -102,28 +107,6 @@ function findCurrentEabFromPrograms(programs) {
     }
     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
  * unified channel cache with rowNumber and displayName as a side effect.
@@ -175,12 +158,12 @@ async function readRenderedChannels(page) {
         rendered.push({ displayName: ch.displayName, domIndex, name: ch.name, rowNumber: ch.rowNumber });
         // Cache the row number and display name for future direct-scroll lookups.
         if (ch.rowNumber >= 0) {
-            const existing = huluChannelCache.get(ch.name);
+            const existing = huluCache.map.get(ch.name);
             if (existing) {
                 existing.rowNumber = ch.rowNumber;
             }
             else {
-                huluChannelCache.set(ch.name, { displayName: ch.displayName, rowNumber: ch.rowNumber });
+                huluCache.map.set(ch.name, { displayName: ch.displayName, rowNumber: ch.rowNumber });
             }
         }
     }
@@ -395,7 +378,7 @@ async function clickOnNowCellAndPlay(page, clickTarget, playSelector, channelNam
     // Maximum number of on-now cell click attempts. The first click may not register if React hasn't finished hydrating the guide's event handlers.
     const MAX_CLICK_ATTEMPTS = 3;
     // Shorter timeout for the play button on non-final attempts. When a click registers, the play button appears in under 10ms - this timeout only determines how
-    // quickly we detect a missed click and retry. Keeping it low saves ~2s per failed attempt compared to the previous 3000ms value.
+    // quickly we detect a missed click and retry. Keeping it low lets a failed attempt fall through to the next one promptly rather than stalling on a dead wait.
     const RETRY_PLAY_TIMEOUT = 1000;
     // Delay between click retries. Gives React additional time to finish hydrating event handlers.
     const CLICK_RETRY_DELAY = 1500;
@@ -498,6 +481,9 @@ async function tryFastPathTune(page, entry, channelName) {
         const currentEab = findCurrentEabFromPrograms(entry.programs);
         if (currentEab) {
             const injected = await page.evaluate((u, e) => {
+                // The __prismcast* bridge functions are installed on window by the evaluateOnNewDocument fetch interceptor earlier in this module. The double cast reads
+                // them off window without committing to a global declaration, and the typeof === "function" guard below tolerates their absence when the interceptor was
+                // not installed (for example on a profile that does not use fetch interception). The same rationale applies to the other reads of these bridge functions.
                 const resolver = window["__prismcastResolveDirectTune"];
                 if (typeof resolver === "function") {
                     return resolver(u, e);
@@ -561,8 +547,8 @@ async function releaseHeldPlaylist(page) {
  * path (discoverHuluChannels) call this immediately after navigation so they share one source of truth for the profile-selector workaround.
  *
  * Selection policy: always the first profile. We do not expose a configurable name because the typical PrismCast deployment has a single primary profile, and an
- * operator who wants a different one can reorder profiles in Hulu's account settings. The selected profile name is captured in the audit log so the operator
- * always knows which one was picked.
+ * operator who wants a different one can reorder profiles in Hulu's account settings. The selected profile name is logged at INFO so the operator always
+ * knows which one was picked.
  *
  * The probe is cheap when no modal is present (one DOM evaluate) and best-effort when it is: any failure between detection and post-click navigation is logged
  * and returns silently. The downstream #CHANNELS-wait timeout becomes the failure signal of last resort, so the existing error path stays intact.
@@ -617,10 +603,12 @@ async function handleProfileSelectorIfPresent(page) {
  * virtualized list - only ~13 of ~124 rows exist in the DOM at any time, positioned absolutely within a tall spacer div. The virtualizer renders rows based on
  * the page scroll position (`document.documentElement.scrollTop`), so we scroll to bring the target channel into the DOM, then interact with it directly.
  *
- * Three mechanisms handle different channel types:
+ * Four mechanisms handle different channel types:
  * 1. Binary search with passive row number caching - primary mechanism for most channels (~800ms first time, ~200ms on cache hit)
  * 2. Position-based inference - handles local affiliates when searching by network name (e.g., "ABC" finds the local call sign at the right sort position)
  * 3. Linear scan fallback - safety net for raw call sign searches or any channel the binary search cannot find (~2.4 seconds)
+ * 4. Fast-path direct tune (tryFastPathTune) - after the channel is located, attempts a direct tune via unified cache injection or interceptor
+ *    self-resolution; a successful outcome returns success without reaching the on-now-cell click or play-button steps
  *
  * The selection process:
  * 1. Clear any "Who's Watching?" profile-selector modal that intercepts before guide interaction (see handleProfileSelectorIfPresent)
@@ -629,8 +617,9 @@ async function handleProfileSelectorIfPresent(page) {
  * 4. Check the unified cache for a row number direct-scroll shortcut
  * 5. Binary search: scroll to the midpoint row, read rendered channels (caching row numbers), check for exact match or infer local affiliate
  * 6. If binary search fails, linear scan from top to bottom as a universal fallback
- * 7. Click the on-now program cell (`.LiveGuideProgram--first`) in the target channel's row to open the playback overlay
- * 8. If playSelector is provided, wait for and click the play button to start live playback
+ * 7. Attempt a fast-path direct tune via tryFastPathTune; on success, return immediately, skipping steps 8 and 9
+ * 8. Click the on-now program cell (`.LiveGuideProgram--first`) in the target channel's row to open the playback overlay
+ * 9. If playSelector is provided, wait for and click the play button to start live playback
  * @param page - The Puppeteer page object.
  * @param profile - The resolved site profile with a non-null channelSelector (channel name) and channelSelection config.
  * @returns Result object with success status and optional failure reason.
@@ -684,13 +673,13 @@ async function guideGridStrategy(page, profile) {
         }
     }
     if (!rowsVisible) {
-        return { reason: "Channel grid rows did not render.", success: false };
+        return { guideUnavailable: true, reason: "Channel grid rows did not render.", success: false };
     }
     // Normalize the channel name to lowercase for case-insensitive matching against data-testid suffixes.
     const normalizedName = normalizeChannelName(channelName);
     const gridMeta = await readGridMeta(page);
     if (!gridMeta) {
-        return { reason: "Could not locate channel grid spacer element.", success: false };
+        return { guideUnavailable: true, reason: "Could not locate channel grid spacer element.", success: false };
     }
     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.
@@ -704,84 +693,71 @@ async function guideGridStrategy(page, profile) {
         // Read rendered channels to update the cache and confirm the channel is present.
         const rendered = await readRenderedChannels(page);
         if (rendered) {
-            const match = rendered.find((ch) => ch.name === normalizedName);
+            /* The entry this shortcut trusted may be filed under a key that is not the name its row renders under - an affiliate's network-name alias, or a key the
+             * fuzzy lookup resolved through - so entry identity is what recognizes the row the scroll landed on. The exact-name pass runs first and the identity pass
+             * only picks up what it leaves, so a row rendering under the requested name always wins over one that merely shares its entry.
+             */
+            const match = rendered.find((ch) => ch.name === normalizedName) ?? rendered.find((ch) => huluCache.map.get(ch.name) === cachedEntry);
             if (match) {
-                return await clickOnNowCellAndPlay(page, normalizedName, playSelector, channelName);
+                return await clickOnNowCellAndPlay(page, match.name, playSelector, channelName);
             }
         }
         // 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);
         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
-    // channel names to narrow the range. The search converges in ~3-4 iterations because the 13-row render window covers a large fraction of the remaining range.
-    let low = 0;
-    let high = totalRows - 1;
+    // The ~13-row render window covers a large fraction of whatever range is left after each step, so the search converges in ~3-4 iterations; ten is a bound on
+    // pathological virtualizer behavior rather than the normal exit.
     const maxIterations = 10;
-    let found = false;
-    for (let iteration = 0; iteration < maxIterations; iteration++) {
-        if (low > high) {
-            break;
-        }
-        const mid = Math.floor((low + high) / 2);
-        // eslint-disable-next-line no-await-in-loop
-        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)) {
-            continue;
-        }
-        // Check for an exact match first.
-        const exactMatch = rendered.find((ch) => ch.name === normalizedName);
-        if (exactMatch) {
-            found = true;
-            break;
-        }
-        // Determine binary search direction by comparing the target against the first and last rendered non-call-sign channel names. Call sign channels (W*/K*
-        // local affiliates) are excluded from direction comparison because they sort by hidden network name, not by their displayed call sign - using them for
-        // localeCompare would send the search the wrong way.
-        const nonCallSigns = rendered.filter((ch) => !CALL_SIGN_PATTERN.test(ch.name));
-        if (nonCallSigns.length === 0) {
-            // All rendered channels are call signs. Cannot determine direction. Move down and hope for better data.
-            low = mid + 1;
-            continue;
-        }
-        const first = nonCallSigns[0]?.name ?? "";
-        const last = nonCallSigns.at(-1)?.name ?? "";
-        if (normalizedName.localeCompare(first) < 0) {
-            // Target sorts before the first visible non-call-sign channel. Scroll up (toward lower row indices).
-            high = mid - 1;
-            continue;
-        }
-        if (normalizedName.localeCompare(last) > 0) {
-            // Target sorts after the last visible non-call-sign channel. Scroll down (toward higher row indices).
-            low = mid + 1;
-            continue;
-        }
-        // The target is alphabetically between the first and last rendered channels but was not found by exact data-testid match. This is the "missing" case - the
-        // channel may be a local affiliate whose call sign doesn't match the network name we're searching for. Try position-based inference.
-        const inferred = inferLocalAffiliate(rendered, normalizedName);
-        if (inferred) {
+    const outcome = await searchVirtualizedGrid({
+        // Call sign channels (W*/K* local affiliates) are excluded from the direction comparison because they sort by hidden network name, not by their displayed
+        // call sign - using them for localeCompare would send the search the wrong way.
+        isDirectionAnchor: (ch) => !CALL_SIGN_PATTERN.test(ch.name),
+        maxIterations,
+        nameOf: (ch) => ch.name,
+        onInRangeMiss: async (rendered) => {
+            // The target is alphabetically between the first and last rendered channels but was not found by exact data-testid match. This is the "missing" case - the
+            // channel may be a local affiliate whose call sign doesn't match the network name we're searching for. Try position-based inference.
+            const inferred = inferLocalAffiliate(rendered, normalizedName);
+            if (!inferred) {
+                return null;
+            }
             LOG.debug("tuning:hulu", "Inferred local affiliate %s for network name %s.", inferred, channelName);
-            clickTarget = inferred;
-            found = true;
             // 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 inferredEntry = huluChannelCache.get(inferred);
+            const inferredEntry = huluCache.map.get(inferred);
             if (inferredEntry) {
-                huluChannelCache.set(normalizedName, inferredEntry);
+                huluCache.map.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 };
+                    return { resolved: { success: true } };
                 }
             }
-        }
-        break;
+            return { found: inferred };
+        },
+        probe: async (rowIndex) => {
+            await scrollToGuideRow(page, gridDocTop, rowHeight, rowIndex);
+            // Read all rendered channels, populating the unified cache with row numbers as a side effect.
+            const rendered = await readRenderedChannels(page);
+            // The rows go back in DOM order untouched, because DOM order is this guide's visual order: Hulu files most local affiliates under their hidden network
+            // name, so sorting by the displayed name would scramble the very positions the affiliate inference reads.
+            return { found: rendered?.find((ch) => ch.name === normalizedName)?.name ?? null, rows: rendered };
+        },
+        targetName: normalizedName,
+        totalRows
+    });
+    // The inference hook tuned the channel itself through the fast path, which leaves the post-search fast-path retry, the playlist release, and the click path
+    // with nothing left to do.
+    if (outcome.kind === "resolved") {
+        return outcome.result;
+    }
+    let found = false;
+    if (outcome.kind === "found") {
+        // The name to click: the target's own on an exact match, the local affiliate's call sign where position inference identified one.
+        clickTarget = outcome.found;
+        found = true;
     }
     // If binary search did not find the channel (and position inference didn't identify a local affiliate), fall back to a linear scan through all channels. This
     // handles edge cases like raw call sign searches where localeCompare gives the wrong direction, or channels like "Lakeshore PBS" that sort by hidden network
@@ -806,7 +782,7 @@ async function guideGridStrategy(page, profile) {
     if (!found) {
         // 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()).toSorted();
+        const availableChannels = Array.from(huluCache.map.keys()).toSorted();
         if (availableChannels.length > 0) {
             logAvailableChannels({
                 availableChannels,
@@ -833,29 +809,6 @@ async function guideGridStrategy(page, profile) {
     // 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);
 }
-/**
- * Wraps guideGridStrategy with a single retry after dismissing any stale overlay that may be covering the guide grid. After a failed click attempt on the on-now
- * cell, the playback overlay or entity modal can remain open, obscuring the guide and preventing subsequent channel selection attempts from locating guide rows.
- * Pressing Escape closes most modal overlays in React-based SPAs.
- * @param page - The Puppeteer page object.
- * @param profile - The resolved site profile with a non-null channelSelector (channel name) and channelSelection config.
- * @returns Result object with success status and optional failure reason.
- */
-async function guideGridWithRetry(page, profile) {
-    let result = await guideGridStrategy(page, profile);
-    if (!result.success) {
-        LOG.warn("Guide grid channel selection failed: %s. Dismissing overlay and retrying.", result.reason ?? "Unknown reason");
-        try {
-            await page.keyboard.press("Escape");
-            await delay(500);
-        }
-        catch (error) {
-            LOG.debug("tuning:hulu", "Could not dismiss guide overlay: %s.", formatError(error));
-        }
-        result = await guideGridStrategy(page, profile);
-    }
-    return result;
-}
 /**
  * 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
@@ -886,19 +839,19 @@ function setupDetailsResponseInterception(page) {
                 const channelUuid = payload.slice(eqIdx + 1);
                 // 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()) {
+                for (const e of huluCache.map.values()) {
                     if (e.uuid === channelUuid) {
                         existingEntry = e;
                         break;
                     }
                 }
                 if (existingEntry) {
-                    huluChannelCache.set(name, existingEntry);
+                    huluCache.map.set(name, existingEntry);
                 }
                 else {
-                    huluChannelCache.set(name, { displayName: name, programs: huluListingStaging.get(channelUuid), uuid: channelUuid });
+                    huluCache.map.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);
+                LOG.debug("tuning:hulu", "Cached affiliate UUID from playlist: %s -> %s. Channel cache size: %s.", name, channelUuid, huluCache.map.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
@@ -941,7 +894,7 @@ function setupDetailsResponseInterception(page) {
                 }
                 // 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()) {
+                for (const entry of huluCache.map.values()) {
                     if (entry.uuid) {
                         const freshPrograms = huluListingStaging.get(entry.uuid);
                         if (freshPrograms) {
@@ -999,7 +952,7 @@ async function resolveHuluDirectUrl(channelSelector, page) {
     const seenEntries = new Set();
     const allCachedUuids = [];
     const allCurrentEabs = [];
-    for (const entry of huluChannelCache.values()) {
+    for (const entry of huluCache.map.values()) {
         if (!entry.uuid || seenEntries.has(entry)) {
             continue;
         }
@@ -1016,14 +969,21 @@ async function resolveHuluDirectUrl(channelSelector, page) {
      * 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.
+     * any page JavaScript, patching window.fetch so Hulu's module-scoped fetch reference captures the interceptor.
+     *
+     * The install goes through installOrReplaceOnNewDocument. Every tune resolves a direct URL first, so resolveHuluDirectUrl runs again on the same page when the
+     * monitor re-tunes it for recovery - and the UUID/EAB cache that drives this script's arguments can warm from empty (cold first tune) to
+     * populated (warm re-tune) in between. The script bakes those tokens in as evaluateOnNewDocument arguments, so re-installing each time is required to carry the
+     * CURRENT tokens; installOrReplaceOnNewDocument removes the prior script before adding the fresh one, keeping exactly one live interceptor with up-to-date
+     * arguments rather than an accumulating stack of competing window.fetch patches frozen at their respective install-time values. (Gating with installOncePerPage
+     * instead would freeze the cold first-tune's empty tokens and stall the warm recovery re-tune - the page would hold the playlist on a fast-path that the stale
+     * cold-mode script cannot complete, time out, and fall back to a full guide re-tune.)
      */
     try {
         // Always hold the playlist request. On warm cache, the interceptor swaps immediately. On cold cache (including affiliates), the guide grid strategy will either
         // inject UUID+EAB via the fast path (resolving the held playlist) or release the hold before falling through to the click path.
         const attemptDirectTune = true;
-        await page.evaluateOnNewDocument((initialUuid, initialEab, cachedUuids, cachedEabs, targetName, holdPlaylist) => {
+        await installOrReplaceOnNewDocument(page, "fetch-interceptor", async () => await page.evaluateOnNewDocument((initialUuid, initialEab, cachedUuids, cachedEabs, targetName, holdPlaylist) => {
             // evaluateOnNewDocument runs in every frame, including ad iframes. We only want to intercept fetches in the main frame - iframes don't make Hulu API
             // calls. The try/catch handles cross-origin iframes where accessing window.top throws a SecurityError.
             try {
@@ -1053,8 +1013,8 @@ async function resolveHuluDirectUrl(channelSelector, page) {
             console.log("[HULU-DIAG] Fetch interceptor installed (" + ((uuid && eab) ? "warm" : "cold") + ")." + (uuid ? " uuid=" + uuid + " eab=" + (eab || "pending") : ""));
             // Promise that resolves when both UUID and EAB are available for the playlist swap. On warm cache, resolves immediately (both injected at install time).
             // On cold cache, resolves when the in-page listing and details API response parsers have captured both values. The playlist handler awaits this Promise
-            // to hold the request until the target channel's data is ready. We use Promise.withResolvers() (Chrome 119+) for the deferred case so the resolver-extraction
-            // pattern matches inPageTimeout below rather than the older "new Promise(executor) + outer-scope variable" pattern.
+            // to hold the request until the target channel's data is ready. We use Promise.withResolvers() (Chrome 119+) for the deferred case so the resolver can be
+            // invoked later by the in-page API parsers as they capture UUID and EAB, matching the resolver-extraction pattern of inPageTimeout below.
             let directTuneResolve = null;
             let directTunePromise;
             if (uuid && eab) {
@@ -1089,8 +1049,9 @@ async function resolveHuluDirectUrl(channelSelector, page) {
             }
             // 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).
+            // swapped channel_id and content_eab_id. Returns true if the injection was accepted (the deferred resolver is still present), false once that resolver has
+            // been consumed - by self-resolution from API data or a prior injection (both via tryResolveDirectTune) or by __prismcastReleasePlaylist. The 8s playlist
+            // hold timeout wins the Promise.race below without clearing the resolver, so it does not by itself flip this to false.
             window["__prismcastResolveDirectTune"] = (u, e) => {
                 if (!directTuneResolve) {
                     return false;
@@ -1238,7 +1199,7 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                 }
                 return await originalFetch(input, Object.assign({}, init ?? {}, { body }));
             }
-            // Marked async to satisfy @typescript-eslint/promise-function-async since the function returns Promise<Response>.
+            // The fetch replacement is async because it awaits the underlying fetch and request-body reads while rewriting matching requests.
             window.fetch = async function (input, init) {
                 const url = (typeof input === "string") ? input : (input instanceof URL) ? input.href : input.url;
                 // Expand listing API requests to include all cached UUIDs. The mini-guide listing only sends ~10 channel UUIDs, but we have UUIDs from previous
@@ -1367,7 +1328,7 @@ async function resolveHuluDirectUrl(channelSelector, page) {
                 }
                 return originalFetch(input, init);
             };
-        }, cachedUuid ?? "", cachedEab ?? "", allCachedUuids, allCurrentEabs, normalizedName, attemptDirectTune);
+        }, cachedUuid ?? "", cachedEab ?? "", allCachedUuids, allCurrentEabs, normalizedName, attemptDirectTune));
     }
     catch (error) {
         LOG.debug("tuning:hulu", "Failed to install Hulu fetch interceptor: %s.", formatError(error));
@@ -1392,21 +1353,22 @@ async function resolveHuluDirectUrl(channelSelector, page) {
 function invalidateHuluDirectUrl(channelSelector) {
     const key = resolveHuluCacheKey(normalizeChannelName(channelSelector));
     if (key) {
-        huluChannelCache.delete(key);
+        huluCache.map.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
+ * virtualized guide grid. This function navigates to the Hulu live page itself. 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).
+ * @param page - The Puppeteer page object; this function navigates it to the Hulu live page.
  * @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();
+    const cached = huluCache.cached();
+    if (cached) {
+        return cached;
     }
     // 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
@@ -1495,15 +1457,15 @@ async function discoverHuluChannels(page) {
             // Alias the network name to the affiliate's cache entry so that resolveHuluDirectUrl can look up local affiliates by their channelSelector (e.g., "PBS")
             // without falling through to the guide grid. Without this alias, the first tune after precaching would always be cold for local affiliates because the
             // cache is keyed by call sign (e.g., "wttw") and findHuluChannelEntry("pbs") would find no match.
-            const affiliateEntry = huluChannelCache.get(callSign);
+            const affiliateEntry = huluCache.map.get(callSign);
             if (affiliateEntry) {
-                huluChannelCache.set(network, affiliateEntry);
+                huluCache.map.set(network, affiliateEntry);
             }
         }
     }
-    // Enrich unified cache entries with affiliate metadata so buildHuluDiscoveredChannels can derive proper affiliate labeling on subsequent getCachedChannels calls.
+    // Enrich unified cache entries with affiliate metadata so the cache's projection carries proper affiliate labeling on subsequent warm reads.
     for (const [callSign, network] of affiliateMap) {
-        const entry = huluChannelCache.get(callSign);
+        const entry = huluCache.map.get(callSign);
         if (entry) {
             entry.affiliate = network;
         }
@@ -1520,29 +1482,22 @@ async function discoverHuluChannels(page) {
     // 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;
+        // A full walk with affiliate position inference is what makes the cache comprehensive enough to serve warm reads. Anything short of it leaves the cache
+        // unmarked, so a later discovery call runs the walk again rather than reporting a lineup missing its affiliate labeling.
+        huluCache.markComplete();
     }
     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 huluProvider = {
     discoverChannels: discoverHuluChannels,
-    getCachedChannels: getHuluCachedChannels,
+    getCachedChannels: huluCache.cached,
     guideUrl: "https://www.hulu.com/live",
     handlesOwnNavigation: true,
     label: "Hulu",
-    // Profile for Hulu Live TV which presents a guide grid of live channels. The channel list is revealed by clicking a tab (listSelector), then the desired channel
-    // is found by matching img.alt text. Uses the fullscreen API (inherited from fullscreenApi) plus a dedicated fullscreen button selector for the player's native
+    // Profile for Hulu Live TV which presents a guide grid of live channels. The channel list is revealed by clicking the #CHANNELS tab (listSelector), then the
+    // target channel is located by matching its normalized name against the data-testid="live-guide-channel-kyber-{name}" attribute on the virtualized guide rows
+    // (binary search to scroll the target into the render window, with position-based affiliate inference). Uses the fullscreen API (inherited from fullscreenApi)
+    // plus a dedicated fullscreen button selector for the player's native
     // maximize control. Requires selectReadyVideo because the page may have multiple video elements (ads, previews, main content). Uses waitForNetworkIdle because
     // Hulu's SPA has heavy async initialization that often prevents the load event from firing within the retryOperation timeout; the graceful networkidle2 fallback
     // in navigateToPage() allows execution to continue to channel selection even when background requests are still pending.
@@ -1560,7 +1515,7 @@ export const huluProvider = {
     slug: "hulu",
     strategy: {
         clearCache: clearHuluCache,
-        execute: guideGridWithRetry,
+        execute: guideGridStrategy,
         invalidateDirectUrl: invalidateHuluDirectUrl,
         resolveDirectUrl: resolveHuluDirectUrl
     },