prismcast 1.10.2 → 1.11.0

package/dist/browser/video.js

@@ -2,9 +2,12 @@
  *
  * video.ts: Video context and playback handling for PrismCast.
  */
-import { EvaluateAbortError, LOG, delay, evaluateWithAbort, formatError, raceWithTimeout, startTimer } from "../utils/index.js";
-import { invalidateDirectUrl, resolveDirectUrl, selectChannel } from "./channelSelection.js";
+import { EvaluateAbortError, LOG, delay, evaluateWithAbort, extractDomain, formatError, startTimer, waitWithTimeout } from "../utils/index.js";
+import { getProvidersForDomain, invalidateDirectUrl, resolveDirectUrl, selectChannel } from "./channelSelection.js";
 import { CONFIG } from "../config/index.js";
+import { classifyBlockedPage } from "./blockedPage.js";
+import { markDomainAuthRequired } from "../config/health.js";
+import { startOverlayHandling } from "./consent.js";
 /* These functions manage the video element lifecycle for streaming capture. The key challenges we solve:
  *
  * 1. Video context resolution: Video elements may be in the main page or nested inside iframes. Some streaming sites (like those using Brightcove or JW Player
@@ -53,7 +56,7 @@ export function buildVideoSelectorType(profile) {
  * The one exception is checkVideoPresence(), which needs all video elements (count, max readyState) rather than selecting one. It uses the inline selection pattern
  * since its requirements differ from the standard single-element selection.
  *
- * - The selectorType parameter MUST be passed as the first argument to evaluateWithAbort
+ * - selectorType must be the first element of the args array passed to evaluateWithAbort.
  */
 /**
  * Injects the shared video selector helper into the browser context. Called in createPageWithCapture() (setup.ts) after page creation and before navigation. The
@@ -78,9 +81,11 @@ let fullscreenQueue = Promise.resolve();
  * Gets the current state of the video element for health monitoring. Returns null if no video element is found.
  * @param context - The frame or page containing the video element.
  * @param selectorType - The video selector type for finding the element.
+ * @param timeoutMs - How long to wait for the read before giving up. Omit for the evaluate wrapper's default bound; a caller that already has reason to suspect
+ *                    an unresponsive tab passes a shorter one, since it needs to tell a hung page from a live one rather than wait out a slow answer.
  * @returns The video state or null if no video found.
  */
-export async function getVideoState(context, selectorType) {
+export async function getVideoState(context, selectorType, timeoutMs) {
     return evaluateWithAbort(context, (type) => {
         const video = window.__prismcastSelectVideo?.(type) ?? null;
         if (!video) {
@@ -98,7 +103,7 @@ export async function getVideoState(context, selectorType) {
             videoWidth: video.videoWidth,
             volume: video.volume
         };
-    }, [selectorType]);
+    }, [selectorType], timeoutMs);
 }
 /**
  * Enforces volume settings on the video element. Sets muted to false and volume to 1. This is called periodically during health monitoring to counter sites that
@@ -116,13 +121,17 @@ export async function enforceVideoVolume(context, selectorType) {
     }, [selectorType]);
 }
 /**
- * Mutes all video elements on the page to suppress wrong-channel audio during tuning. When a page loads (e.g. Hulu's /live), a default livestream auto-plays before
- * channel selection can switch to the target channel. Since the capture pipeline is already running, this audio bleeds into the stream. Muting preemptively silences it.
- * This is best-effort: if no video elements exist yet, or the page is in a transitional state, the error is silently ignored. The unmute happens naturally when
- * ensurePlayback() calls startVideoPlayback() after tuning completes.
+ * Mutes every video element currently on the page, silencing audio that does not belong to the channel being established. A multi-channel page auto-plays a
+ * default livestream on load (Hulu's /live, for example), and with a capture pipeline already running that audio bleeds into the stream until channel selection
+ * reaches the requested channel; a page reloaded to re-establish a channel meets the same default again. Two moments call for it: where a tune begins, and where
+ * a re-establishment's playback initialization settles - the latter because playback establishment unmutes by a direct property write that an already-playing
+ * element keeps until something mutes it again.
+ *
+ * Best-effort: a page with no video elements yet, or one in a transitional state, swallows the failure rather than failing the caller. The unmute that matters
+ * happens naturally when startVideoPlayback() runs on the tuned channel.
  * @param page - The Puppeteer page object.
  */
-async function muteExistingVideos(page) {
+export async function muteExistingVideos(page) {
     try {
         await page.evaluate(() => {
             for (const video of Array.from(document.querySelectorAll("video"))) {
@@ -149,14 +158,21 @@ export async function suppressPageAudio(page) {
     // Override HTMLMediaElement.prototype.play to mute before playback. This runs before site JavaScript on all future navigations (including token refresh via
     // page.goto), matching the pattern established in precaching.ts. The override persists on the same page instance - a new page created by tab replacement won't
     // inherit it.
-    await page.evaluateOnNewDocument(() => {
-        // eslint-disable-next-line @typescript-eslint/unbound-method -- Prototype interception: originalPlay is captured here and invoked with .call(this) below.
-        const originalPlay = HTMLMediaElement.prototype.play;
-        HTMLMediaElement.prototype.play = async function () {
-            this.muted = true;
-            return originalPlay.call(this);
-        };
-    });
+    try {
+        await page.evaluateOnNewDocument(() => {
+            // eslint-disable-next-line @typescript-eslint/unbound-method -- Prototype interception: originalPlay is captured here and invoked with .call(this) below.
+            const originalPlay = HTMLMediaElement.prototype.play;
+            HTMLMediaElement.prototype.play = async function () {
+                this.muted = true;
+                return originalPlay.call(this);
+            };
+        });
+    }
+    catch {
+        // Best-effort, exactly like the immediate mute below. The page may be mid-navigation or tearing down as the stream switches to native delivery, and a failed
+        // override must not abort the switch it rides along with. Future navigations on this page then play unmuted until the next suppression pass runs, which is
+        // the cost the best-effort contract accepts.
+    }
     // Mute any videos that are already playing. The prototype override only affects future play() calls, so existing playback needs a direct mute.
     try {
         await page.evaluate(() => {
@@ -256,8 +272,8 @@ export async function startVideoPlayback(context, selectorType) {
 /**
  * Navigates a browser page to the specified URL with site-appropriate wait conditions. The navigation strategy depends on the site's player implementation:
  *
- * - waitForNetworkIdle=true: Wait for network activity to settle (no requests for 500ms). This ensures all JavaScript has loaded and the player is fully
- *   initialized. Used for sites with complex async initialization.
+ * - waitForNetworkIdle=true: Wait for network activity to settle, allowing up to 2 concurrent connections for 500ms. This ensures all JavaScript has loaded
+ *   and the player is fully initialized. Used for sites with complex async initialization.
  *
  * - waitForNetworkIdle=false: Return as soon as the page fires load event. Used for sites that have persistent connections or polling that would prevent
  *   networkidle from ever completing.
@@ -271,8 +287,8 @@ export async function startVideoPlayback(context, selectorType) {
 export async function navigateToPage(page, url, profile) {
     if (profile.waitForNetworkIdle) {
         try {
-            // Wait for network idle (no requests for 500ms). This ensures complex JavaScript players have fully initialized. The networkidle2 strategy allows up
-            // to 2 concurrent requests, which handles sites with persistent connections for analytics.
+            // Wait for network activity to settle. This ensures complex JavaScript players have fully initialized. The networkidle2 strategy allows up to 2
+            // concurrent requests, which handles sites with persistent connections for analytics.
             await page.goto(url, { timeout: CONFIG.streaming.navigationTimeout, waitUntil: "networkidle2" });
         }
         catch (error) {
@@ -293,6 +309,29 @@ export async function navigateToPage(page, url, profile) {
         await page.goto(url);
     }
 }
+/**
+ * Reloads the current page, mirroring navigateToPage's wait strategy. Two callers, one mechanism. An accepted embedded-player consent gate only creates the player
+ * iframe on a fresh load, so a reload re-renders the page with consent persisted and the video resolves on the second pass. A guide that never rendered is the
+ * other: the reload is what gives channel selection a fresh surface to read.
+ * @param page - The Puppeteer page object.
+ * @param profile - The site profile, whose waitForNetworkIdle flag selects the reload wait condition.
+ */
+async function reloadPage(page, profile) {
+    const waitUntil = profile.waitForNetworkIdle ? "networkidle2" : "load";
+    try {
+        await page.reload({ timeout: CONFIG.streaming.navigationTimeout, waitUntil });
+    }
+    catch (error) {
+        // A reload timeout is often non-fatal - the player may already be present even if some background requests never settled. Mirror navigateToPage: warn and
+        // continue on timeout, propagate other errors.
+        if (error && (error.name === "TimeoutError")) {
+            LOG.warn("Page reload timed out after %sms.", CONFIG.streaming.navigationTimeout);
+        }
+        else {
+            throw error;
+        }
+    }
+}
 /**
  * Finds the appropriate context (frame or page) containing the video element. Some streaming sites embed their video player in an iframe, which creates a
  * separate document context. We need to find this iframe and operate within it to access the video element.
@@ -316,7 +355,7 @@ export async function findVideoContext(page, profile) {
     await page.waitForSelector("iframe", { timeout: CONFIG.streaming.videoTimeout });
     // Poll for a video element to appear in any iframe. Complex embedded players (Brightcove, JW Player, etc.) load additional resources and scripts after the
     // iframe element appears, so the video may not be immediately available. We retry the search with brief pauses, using the configured delay as the overall
-    // timeout ceiling. This replaces a fixed delay with early exit - if the video appears quickly, we proceed immediately.
+    // timeout ceiling. Polling with early exit avoids waiting the full delay when the video appears quickly.
     const deadline = Date.now() + CONFIG.playback.iframeInitDelay;
     let iframeSearchComplete = false;
     let lastFrameCount = 0;
@@ -353,16 +392,18 @@ export async function findVideoContext(page, profile) {
             await delay(200);
         }
     }
-    // If no iframe contains a video, fall back to the main page. This is a potential issue for iframe-handling profiles since we expected the video to be in an
-    // iframe. Log a warning and verify the main page actually has a video element.
-    LOG.warn("No iframe contained video element. Falling back to main page context (searched %s frames).", Math.max(0, lastFrameCount - 1));
+    // No iframe contained a video, so fall back to the main page. This is a designed branch of the function's contract, not an error: it is reached transiently and
+    // recoverably whenever the embedded player has not loaded yet - most commonly on a consent-gated site's first pass, where the player iframe is withheld until the
+    // overlay handler accepts the consent and reloads. The authoritative failure signal, if the context genuinely has no playable video, is waitForVideoReady's
+    // timeout downstream; this fallback notice is therefore a DEBUG breadcrumb under browser:video rather than a WARN that would cry wolf on every gated tune.
+    LOG.debug("browser:video", "No iframe contained a video element; falling back to the main page context (searched %s frames).", Math.max(0, lastFrameCount - 1));
     // Check if the main page actually contains a video element.
     try {
         const mainPageHasVideo = await evaluateWithAbort(page, () => {
             return !!document.querySelector("video");
         });
         if (!mainPageHasVideo) {
-            LOG.warn("Main page fallback: no video element found in main page either.");
+            LOG.debug("browser:video", "Main page fallback: no video element found in the main page either.");
         }
     }
     catch (_error) {
@@ -384,12 +425,15 @@ export async function findVideoContext(page, profile) {
  * or playback issues.
  * @param context - The frame or page containing the video element.
  * @param profile - The site profile with video selection preferences.
+ * @param signal - Optional abort signal; when aborted the wait is abandoned without emitting the timeout warning, so the caller can supersede it after accepting an
+ * embedded-player consent gate that triggers a reload.
  */
-export async function waitForVideoReady(context, profile) {
+export async function waitForVideoReady(context, profile, signal) {
     // Use the per-domain video timeout if configured, otherwise fall back to the global default.
     const timeout = profile.videoTimeout ?? CONFIG.streaming.videoTimeout;
-    // First, wait for any video element to appear in the DOM. This catches cases where the video element is created dynamically by JavaScript.
-    await context.waitForSelector("video", { timeout });
+    // First, wait for any video element to appear in the DOM. This catches cases where the video element is created dynamically by JavaScript. The optional abort
+    // signal lets a caller abandon the wait cleanly - used when an embedded-player consent gate is accepted and the page is about to be reloaded.
+    await context.waitForSelector("video", { signal, timeout });
     // Scroll the video into view to satisfy Chrome's Intersection Observer autoplay policy. Chrome suppresses autoplay for offscreen videos, preventing them from
     // buffering and reaching readyState >= 3. Scrolling the video into the viewport unblocks autoplay. This is a no-op when the video is already visible.
     const postScrollState = await context.evaluate(() => {
@@ -412,17 +456,22 @@ export async function waitForVideoReady(context, profile) {
                 return Array.from(videos).some((v) => {
                     return v.readyState >= 3;
                 });
-            }, { timeout });
+            }, { signal, timeout });
         }
         else {
             // For standard sites with a single video, wait for that specific video to reach readyState >= 3.
             await context.waitForFunction(() => {
                 const video = document.querySelector("video");
                 return !!video && (video.readyState >= 3);
-            }, { timeout });
+            }, { signal, timeout });
         }
     }
     catch (error) {
+        // An aborted wait is not a genuine readiness failure - the caller deliberately abandoned it (for example, after accepting an embedded-player consent gate that
+        // triggers a reload). Rethrow without the misleading timeout diagnostics so it can be ignored upstream.
+        if (signal?.aborted) {
+            throw error;
+        }
         // Capture the video element's state at the moment of timeout to aid diagnosis.
         const timeoutState = await context.evaluate(() => {
             const videos = document.querySelectorAll("video");
@@ -484,7 +533,7 @@ export async function applyVideoStyles(context, selectorType, important = false)
  * This function uses Object.defineProperty to intercept property access, making it impossible for site JavaScript to change muted or volume values. The property
  * descriptors are set to configurable: true so the browser can still access the underlying values for playback.
  *
- * The function is idempotent - a __volumeLocked flag on the video element prevents applying the lock multiple times.
+ * The function is safe to call more than once - a __volumeLocked flag on the video element prevents applying the lock multiple times.
  * @param context - The frame or page containing the video element.
  * @param selectorType - The video selector type for finding the element.
  */
@@ -530,6 +579,9 @@ export async function lockVolumeProperties(context, selectorType) {
 /**
  * Triggers fullscreen mode using the appropriate method for the site. Different sites have different fullscreen implementations:
  *
+ * - Fullscreen button (fullscreenSelector): When configured, this is tried first by clicking the site's own fullscreen control, which uses the site's native
+ *   mechanism and is the most reliable approach when the button is present.
+ *
  * - Keyboard shortcuts (fullscreenKey): Many players use "f" as a keyboard shortcut for fullscreen. We send this keypress to activate the player's native
  *   fullscreen mode.
  *
@@ -537,7 +589,7 @@ export async function lockVolumeProperties(context, selectorType) {
  *   prompts or be blocked by CSP, but works on many sites.
  *
  * Note that we also apply CSS-based fullscreen styling separately (in applyVideoStyles), which provides a reliable fallback when native fullscreen methods fail.
- * @param page - The Puppeteer page object for keyboard input.
+ * @param page - The Puppeteer page object, used for keyboard input and for clicking the fullscreen button when fullscreenSelector is configured.
  * @param context - The frame or page containing the video element.
  * @param profile - The site profile indicating fullscreen method.
  * @param selectorType - The video selector type for finding the element.
@@ -651,8 +703,10 @@ async function isNativeFullscreenActive(context) {
  * dispatches real pointer events that Chrome recognizes as user gestures. The click may toggle play/pause on some players - the health monitor handles
  * re-starting playback if needed.
  *
- * Note: page.mouse.click() uses page-level coordinates, while getBoundingClientRect() in an iframe returns iframe-relative coordinates. This function works
- * correctly because all profiles with useRequestFullscreen are non-iframe (needsIframeHandling is false).
+ * Note: page.mouse.click() uses page-level coordinates, while getBoundingClientRect() inside an iframe returns iframe-relative coordinates. The iframe-embedded
+ * fullscreenApi profiles (the embeddedPlayer family) set both useRequestFullscreen and needsIframeHandling, so for those tunes the computed point can be offset
+ * from the real video position. That is tolerated here: the click exists only to register a trusted user gesture for transient activation, which any in-page
+ * click satisfies - it does not need to land precisely on the video - and a missed activation is recovered by the health monitor.
  * @param page - The Puppeteer page object.
  * @param context - The frame or page containing the video element.
  * @param selectorType - The video selector type for finding the element.
@@ -747,7 +801,8 @@ async function applyAggressiveFullscreen(context, selectorType) {
 export async function ensureFullscreen(page, context, profile, selectorType, skipNativeFullscreen) {
     const useNativeFullscreen = profile.useRequestFullscreen && !skipNativeFullscreen;
     // Inject a persistent stylesheet to hide site-specific overlay elements (e.g., player control bars, toolbars) that would otherwise appear in the captured stream.
-    // The style tag persists for the page lifetime and is idempotent - duplicate injections from recovery calls are harmless since CSS rules are deduplicated.
+    // The style tag persists for the page lifetime. Duplicate injections from recovery calls are harmless because the reapplied rules produce the same computed
+    // style, though each call does add another <style> tag to the DOM.
     if (profile.hideSelector) {
         const css = profile.hideSelector + " { display: none !important; }";
         await page.addStyleTag({ content: css }).catch(() => { });
@@ -761,7 +816,7 @@ export async function ensureFullscreen(page, context, profile, selectorType, ski
     const FULLSCREEN_QUEUE_TIMEOUT = 10000;
     fullscreenQueue = fullscreenQueue.then(async () => {
         try {
-            await raceWithTimeout(runFullscreenSequence(page, context, profile, selectorType, true), FULLSCREEN_QUEUE_TIMEOUT, new Error("Fullscreen queue entry timed out."));
+            await waitWithTimeout(runFullscreenSequence(page, context, profile, selectorType, true), FULLSCREEN_QUEUE_TIMEOUT, new Error("Fullscreen queue entry timed out."));
         }
         catch (error) {
             LOG.warn("Fullscreen queue entry failed: %s.", formatError(error));
@@ -879,7 +934,7 @@ async function runFullscreenSequence(page, context, profile, selectorType, useNa
 }
 /**
  * Ensures the video is playing with proper audio settings. This is the core playback function that handles both initial setup and recovery from stalls. It is
- * designed to be idempotent - safe to call multiple times without adverse effects.
+ * safe to call more than once without adverse effects.
  *
  * Recovery escalation levels (higher levels include all lower-level actions):
  *
@@ -934,62 +989,71 @@ export async function ensurePlayback(page, context, profile, options) {
         await lockVolumeProperties(context, selectorType);
     }
 }
+const defaultVideoTuneDeps = { classifyBlockedPage, getProvidersForDomain, selectChannel, startOverlayHandling };
 /**
- * Dismisses any stale overlay or modal 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.
+ * Diagnoses a failed tune by classifying the still-open page, which holds the evidence of why the tune failed. A confirmed provider authentication wall marks the
+ * domain needs-sign-in and replaces the generic failure with an actionable error; a wall on a domain with no registered provider is reported without marking (there
+ * is no channel-table row to point at, and an unmarked ad-hoc entry would have no clearing path); a consent overlay surfaces the standing detect-and-guide text;
+ * anything unrecognized - including a classification that outruns its own time budget - rethrows the original failure unchanged.
+ * @param page - The Puppeteer page object, still open at the point of failure.
+ * @param requestedUrl - The URL this tune navigated to; its registrable domain selects the provider and receives any needs-sign-in mark.
+ * @param originalError - The failure that triggered the diagnosis, rethrown as-is when the page classifies as unknown.
+ * @param deps - The injected tune collaborators used to resolve the provider and classify the blocked page.
+ * @returns Never resolves - every classification outcome throws.
  */
-async function dismissGuideOverlay(page) {
-    try {
-        await page.keyboard.press("Escape");
-        // Brief delay for the overlay dismiss animation to complete and the guide grid to re-render.
-        await delay(500);
-    }
-    catch (error) {
-        // Overlay dismissal is best-effort. The overlay may not exist, or the page may be in a state where keyboard input is ignored.
-        LOG.debug("browser:video", "Could not dismiss guide overlay: %s.", formatError(error));
+async function diagnoseBlockedTune(page, requestedUrl, originalError, deps) {
+    const domain = extractDomain(requestedUrl);
+    // Resolve the provider whose guide lives on this domain, when one is registered. Its declared auth wall indicators (when defined) sharpen the classification,
+    // and a provider match is what authorizes the needs-sign-in mark below.
+    const provider = deps.getProvidersForDomain(domain)[0];
+    // classifyBlockedPage is never-throwing and self-bounded, so the call needs no timeout wrapper and no fallback catch: a timed-out or unreadable page classifies
+    // unknown internally, and the original failure stands.
+    const classification = await deps.classifyBlockedPage(page, { indicators: provider?.authWallIndicators, requestedUrl });
+    switch (classification.kind) {
+        case "authWall": {
+            // A wall on a registered provider's domain is marked before the throw, so the stream setup layer reads the needs-sign-in state while composing the
+            // client-visible message for this very failure.
+            if (provider) {
+                markDomainAuthRequired(domain);
+                LOG.warn("The tune failed because %s is presenting an authentication wall (%s). Sign in from the channel table's login icon.", provider.label, classification.evidence);
+                throw new Error("Tune failed: " + provider.label + " is presenting an authentication wall (" + classification.evidence + "). Sign in from the channel " +
+                    "table's login icon.");
+            }
+            throw new Error("Tune failed: " + domain + " is presenting an authentication wall (" + classification.evidence + ").");
+        }
+        case "consentOverlay": {
+            // A consent or cookie prompt is blocking the page. Surface actionable guidance in place of the cryptic underlying failure - the viewer dismisses it once in
+            // setup or login mode and the choice persists.
+            throw new Error("This site is displaying a consent or cookie prompt that is blocking playback. Open it once in setup or login mode and dismiss the prompt - " +
+                "your choice is remembered.");
+        }
+        default: {
+            // Nothing recognizable on the page - the original failure is the most truthful report we have.
+            throw originalError;
+        }
     }
 }
-// Maximum duration in milliseconds for the dismiss modal poll. The poll checks for the modal element at regular intervals during the first few seconds of the
-// video wait. If the modal hasn't appeared within this window, it's not coming.
-const DISMISS_POLL_DURATION = 5000;
-// Interval in milliseconds between dismiss modal poll checks.
-const DISMISS_POLL_INTERVAL = 500;
 /**
- * Polls for an intermittent modal element and clicks it if found. Runs as a fire-and-forget background task alongside waitForVideoReady() to catch modals that
- * render after page load but before video starts playing. The first check is immediate (zero-wait), followed by up to DISMISS_POLL_DURATION of periodic rechecks.
- * Once the modal is found and clicked (or the poll window expires), the function resolves silently - it never throws.
+ * Runs a span of the tune under a phase-scoped overlay-handling poll. Creates the abort controller, launches the poll fire-and-forget for the given phase, hands the
+ * body an abort() it calls before diagnosing a blocked page (so the poll cannot keep clicking mid-classification), and always aborts the poll when the body settles.
+ * The video wait manages its own poll directly because it composes the poll with the embed-gate race and the paired reload; every other span of the tune uses this
+ * helper, which is why the phase is typed to exclude videoWait. The poll is launched through the injected deps, so every phase shares the single startOverlayHandling
+ * call the video wait already uses.
  * @param page - The Puppeteer page object.
- * @param selector - The CSS selector for the modal element to dismiss.
+ * @param profile - The resolved site profile.
+ * @param phase - The overlay phase covering this span (any phase but videoWait, whose choreography is bespoke).
+ * @param deps - The injected tune collaborators; the covering poll is launched through deps.startOverlayHandling.
+ * @param run - The span to run; receives an abort() that stops the covering poll immediately, for use before a blocked-page diagnosis.
+ * @returns The span's result.
  */
-async function dismissModalPoll(page, selector) {
-    const checks = Math.ceil(DISMISS_POLL_DURATION / DISMISS_POLL_INTERVAL);
-    for (let i = 0; i < checks; i++) {
-        // Delay between checks, but not before the first one - the first check is immediate.
-        if (i > 0) {
-            // eslint-disable-next-line no-await-in-loop
-            await delay(DISMISS_POLL_INTERVAL);
-        }
-        try {
-            // eslint-disable-next-line no-await-in-loop
-            const dismissed = await page.evaluate((sel) => {
-                const el = document.querySelector(sel);
-                if (el) {
-                    el.click();
-                    return true;
-                }
-                return false;
-            }, selector);
-            if (dismissed) {
-                LOG.debug("browser:video", "Dismissed modal via '%s'.", selector);
-                return;
-            }
-        }
-        catch {
-            // Page may have navigated or closed during the poll. Silently stop polling.
-            return;
-        }
+async function withOverlayGuard(page, profile, phase, deps, run) {
+    const controller = new AbortController();
+    void deps.startOverlayHandling(page, profile, { phase, signal: controller.signal });
+    try {
+        return await run(() => { controller.abort(); });
+    }
+    finally {
+        controller.abort();
     }
 }
 /**
@@ -998,66 +1062,154 @@ async function dismissModalPoll(page, selector) {
  * timeout, while channel selection and video setup run with their own internal time budgets (click retry loops, videoTimeout, etc.) without being killed by the
  * navigation timeout.
  *
- * For guideGrid channel selection failures, the function attempts a single retry after dismissing any stale overlay that may be covering the guide grid. This
- * handles the case where a failed click attempt left an overlay open, causing subsequent locateOnNowCell calls to fail.
+ * When channel selection fails because the guide surface itself never rendered, the function reloads the page and retries selection once. That failure class is
+ * transient - a rail whose lazy tiles never populated, an SPA shell that did not come up - and a reload is what cures it. A failure on a guide that did render,
+ * such as a channel name that is simply not in the lineup, gets no retry: reading the same rendered guide again would fail the same way, more slowly.
  *
  * @param page - The Puppeteer page object.
  * @param profile - The site profile containing all behavior flags.
  * @param options - Optional behaviors. See InitializePlaybackOptions.
+ * @param deps - Injected tune collaborators for testing; defaults to defaultVideoTuneDeps in production.
  * @returns The video context (frame or page) for subsequent monitoring, and a directTune flag when the channel was tuned via API interception.
  */
-export async function initializePlayback(page, profile, options = {}) {
+export async function initializePlayback(page, profile, options = {}, deps = defaultVideoTuneDeps) {
     const elapsed = startTimer();
-    const { persistResolution, skipChannelSelection = false } = options;
+    const { persistResolution, requestedUrl, skipChannelSelection = false } = options;
     // Mute any existing video elements to suppress wrong-channel audio during tuning. On SPA-based providers (Hulu, Fox, USA Network, etc.), a default livestream
     // auto-plays when the page loads. Since the capture pipeline is already running, this audio bleeds into the stream until channel selection completes and
     // ensurePlayback() unmutes the correct channel. For providers where no video exists yet, this is a harmless no-op.
     await muteExistingVideos(page);
-    // For multi-channel players (like usanetwork.com/live with multiple channels), select the desired channel from the UI. The selectChannel function checks the
-    // profile's channelSelection strategy and channelSelector to determine if/how to select a channel. Skipped when navigating directly to a cached watch URL,
-    // since the URL already targets the correct channel.
-    let directTune = false;
-    if (!skipChannelSelection) {
-        let channelResult = await selectChannel(page, profile, { persistResolution });
-        if (!channelResult.success) {
-            // For guideGrid strategy, a stale overlay from a previous failed click attempt may be covering the guide. Dismiss it and retry channel selection once.
-            if (profile.channelSelection.strategy === "guideGrid") {
-                LOG.warn("Guide grid channel selection failed: %s. Dismissing overlay and retrying.", channelResult.reason ?? "Unknown reason");
-                await dismissGuideOverlay(page);
-                channelResult = await selectChannel(page, profile, { persistResolution });
-            }
+    // The channel-selection walk, video-context resolution, and click-to-play run under a tuneSetup overlay poll, so a cookie banner or per-site modal that appears
+    // during those phases is dismissed rather than silently burning their budgets. The guard aborts the poll at the phase boundary (its finally) before the video
+    // wait launches its own poll, and each in-span failure aborts it explicitly before the blocked-page diagnosis so the poll cannot keep clicking mid-classification.
+    const setup = await withOverlayGuard(page, profile, "tuneSetup", deps, async (abortGuard) => {
+        // For multi-channel players (like usanetwork.com/live with multiple channels), select the desired channel from the UI. The selectChannel function checks the
+        // profile's channelSelection strategy and channelSelector to determine if/how to select a channel. Skipped when navigating directly to a cached watch URL,
+        // since the URL already targets the correct channel.
+        let directTune = false;
+        if (!skipChannelSelection) {
+            let channelResult = await deps.selectChannel(page, profile, { persistResolution });
             if (!channelResult.success) {
-                throw new Error("Channel selection failed: " + (channelResult.reason ?? "Unknown reason."));
+                /* The guide surface never rendered, so there was nothing for the strategy to read. That is the transient class - lazy tiles that never populated, an SPA
+                 * shell that did not come up, a stale overlay left across the grid - and a reload clears all of it at once, more thoroughly than dismissing anything
+                 * would. This is the one whole-selection retry in the system: providers own the cheap retries inside a single attempt, the coordinator owns this one.
+                 *
+                 * The budget it spends: the retry only fires after a selection has already failed, which for most providers costs up to videoTimeout and for Hulu - whose
+                 * grid strategy chains a list wait and a two-phase rows wait - closer to half a minute. The reload adds up to navigationTimeout, and a second selection
+                 * follows it. Hulu's worst case therefore runs past the 45-second establishment ceiling and is truncated by it, failing exactly as the un-retried attempt
+                 * was already going to fail. The ceiling is deliberately left where it is: the retry can never make a tune worse than the certain failure it replaces.
+                 */
+                if (channelResult.guideUnavailable === true) {
+                    LOG.warn("Channel selection failed because the guide did not render: %s. Reloading the page and retrying once.", channelResult.reason ?? "Unknown reason");
+                    await reloadPage(page, profile);
+                    // The reloaded page auto-plays its default channel again, and capture is live for the whole tune, so that audio would bleed into the recording until the
+                    // second selection lands. The re-establishment path mutes after its own reload for the same reason.
+                    await muteExistingVideos(page);
+                    channelResult = await deps.selectChannel(page, profile, { persistResolution });
+                }
+                if (!channelResult.success) {
+                    const selectionError = new Error("Channel selection failed: " + (channelResult.reason ?? "Unknown reason."));
+                    // With the requested URL in hand, diagnose the still-open page before failing - the selection may have failed because a sign-in wall or consent prompt is
+                    // where the guide should be. An unknown classification rethrows this same error, so the undiagnosed outcome is identical to the plain throw below.
+                    if (requestedUrl !== undefined) {
+                        // Stop the tuneSetup poll before probing the page, so it cannot keep clicking mid-classification; the guard's finally remains the safety net.
+                        abortGuard();
+                        await diagnoseBlockedTune(page, requestedUrl, selectionError, deps);
+                    }
+                    throw selectionError;
+                }
             }
+            directTune = channelResult.directTune ?? false;
+            LOG.debug("timing:tune", "Channel selection complete. (+%sms)", elapsed());
         }
-        directTune = channelResult.directTune ?? false;
-        LOG.debug("timing:tune", "Channel selection complete. (+%sms)", elapsed());
-    }
-    // Find the video context, which may be an iframe for embedded players. Some streaming sites embed their video player in an iframe, requiring us to search
-    // through frames to find the one containing the video element.
-    const context = await findVideoContext(page, profile);
-    LOG.debug("timing:tune", "Video context found. (+%sms)", elapsed());
-    // For clickToPlay sites, we need to click an element to start playback. These players require user interaction to begin playing, even with autoplay enabled. If
-    // clickSelector is set, we click that element (typically a play button overlay); otherwise we click the video element directly.
-    if (profile.clickToPlay) {
-        const clickTarget = profile.clickSelector ?? "video";
+        // Find the video context, which may be an iframe for embedded players. Some streaming sites embed their video player in an iframe, requiring us to search
+        // through frames to find the one containing the video element. For iframe-handling profiles this can reject with a raw selector timeout when the player iframe
+        // never appears, so with the requested URL in hand the failure routes through the blocked-page diagnosis; an unknown classification rethrows the original
+        // rejection unchanged.
+        let context;
         try {
-            // Wait for the click target to appear in the DOM. Play button overlays may be rendered after initial page load.
-            await context.waitForSelector(clickTarget, { timeout: CONFIG.streaming.videoTimeout });
-            await context.click(clickTarget);
-            LOG.debug("timing:tune", "Click-to-play complete. (+%sms)", elapsed());
+            context = await findVideoContext(page, profile);
+        }
+        catch (contextError) {
+            if (requestedUrl !== undefined) {
+                // Stop the tuneSetup poll before probing the page, so it cannot keep clicking mid-classification; the guard's finally remains the safety net.
+                abortGuard();
+                await diagnoseBlockedTune(page, requestedUrl, contextError, deps);
+            }
+            throw contextError;
         }
-        catch (clickError) {
-            LOG.warn("Could not click %s to initiate playback: %s.", clickTarget, formatError(clickError));
+        LOG.debug("timing:tune", "Video context found. (+%sms)", elapsed());
+        // For clickToPlay sites, we need to click an element to start playback. These players require user interaction to begin playing, even with autoplay enabled. If
+        // clickSelector is set, we click that element (typically a play button overlay); otherwise we click the video element directly.
+        if (profile.clickToPlay) {
+            const clickTarget = profile.clickSelector ?? "video";
+            try {
+                // Wait for the click target to appear in the DOM. Play button overlays may be rendered after initial page load.
+                await context.waitForSelector(clickTarget, { timeout: CONFIG.streaming.videoTimeout });
+                await context.click(clickTarget);
+                LOG.debug("timing:tune", "Click-to-play complete. (+%sms)", elapsed());
+            }
+            catch (clickError) {
+                LOG.warn("Could not click %s to initiate playback: %s.", clickTarget, formatError(clickError));
+            }
+        }
+        return { context, directTune };
+    });
+    let context = setup.context;
+    const directTune = setup.directTune;
+    // Wait for the video to become playable (readyState >= 3), while a fire-and-forget overlay-handling poll runs concurrently to reject cookie-consent banners,
+    // accept embedded-player consent gates, and dismiss the profile's per-site modal. The poll never blocks the wait. If it accepts an embed gate, the in-flight wait
+    // is abandoned and the page is reloaded once so the now-permitted player iframe is created and the video resolves on the second pass. If the wait fails with a
+    // consent prompt still blocking the page, an actionable detect-and-guide error replaces the cryptic selector timeout.
+    // Signals an embed-gate acceptance, so the video wait below can be raced against it. The gate resolves to "gate"; the video wait resolves to "video".
+    const embedGate = Promise.withResolvers();
+    // Stops the overlay poll once the wait settles, so it does not keep interacting with a page that is already done.
+    const overlayController = new AbortController();
+    // Abandons the in-flight video wait when an embed gate is accepted, so the superseded wait rejects silently instead of logging a misleading readiness timeout.
+    const waitController = new AbortController();
+    void deps.startOverlayHandling(page, profile, {
+        onEmbedGateAccepted: () => {
+            embedGate.resolve("gate");
+        },
+        phase: "videoWait",
+        signal: overlayController.signal
+    });
+    try {
+        // Race the video wait against an embed-gate acceptance. A present gate is accepted within a few seconds, so it reliably wins against the much longer video
+        // timeout; a plain successful tune resolves "video" with the overlay poll a cheap no-op. A genuine readiness timeout rejects the race and is handled below.
+        const outcome = await Promise.race([waitForVideoReady(context, profile, waitController.signal).then(() => "video"), embedGate.promise]);
+        if (outcome === "gate") {
+            // The site withheld the player iframe behind a consent gate that we accepted; consent now persists, so a single reload re-renders the page with the player
+            // present and the video resolves on the second pass. Abandon the now-superseded first wait so it does not log a spurious timeout as the page reloads.
+            LOG.debug("browser:consent", "Embedded-player consent gate accepted; reloading to resolve the player.");
+            waitController.abort();
+            await reloadPage(page, profile);
+            // The consent granted on the first pass persists, so the reload re-renders the page with the player iframe present and the video resolves. Context resolution
+            // and this second wait run under the postGateReload poll, so a cookie banner or per-site modal that re-renders after the reload is still cleared. That poll's
+            // policy forbids the embed-gate accept: a second acceptance would re-detect unrelated consent overlays elsewhere on the page (carousel video tiles on a site
+            // like france24), scroll one into view, and click it - yanking the main player offscreen and suppressing its autoplay. The phase makes that misfire
+            // structurally impossible while keeping cookie rejection and modal dismissal live. A consent overlay that genuinely persists past the reload falls through to
+            // the detect-and-guide path below.
+            context = await withOverlayGuard(page, profile, "postGateReload", deps, async () => {
+                const reloadedContext = await findVideoContext(page, profile);
+                await waitForVideoReady(reloadedContext, profile);
+                return reloadedContext;
+            });
         }
     }
-    // Wait for video to be ready (readyState >= 3). This ensures enough data is buffered for playback to begin smoothly. If a dismissSelector is configured, launch
-    // a background poll that checks for the modal during the first 5 seconds of the video wait. The poll is fire-and-forget - it never blocks the video wait. If the
-    // modal appears and is clicked, the video becomes unblocked and waitForVideoReady resolves normally.
-    if (profile.dismissSelector) {
-        void dismissModalPoll(page, profile.dismissSelector);
+    catch (videoError) {
+        // Playback never became ready. With the requested URL in hand, diagnose the still-open page - a sign-in wall or a still-blocking consent prompt found there
+        // replaces the cryptic selector timeout with an actionable error, and an unrecognized page rethrows this same rejection unchanged.
+        if (requestedUrl !== undefined) {
+            // Stop the overlay poll before probing the page, so it cannot keep clicking mid-classification. The finally below remains the safety net for every exit.
+            overlayController.abort();
+            await diagnoseBlockedTune(page, requestedUrl, videoError, deps);
+        }
+        throw videoError;
+    }
+    finally {
+        overlayController.abort();
     }
-    await waitForVideoReady(context, profile);
     LOG.debug("timing:tune", "Video ready. (+%sms)", elapsed());
     // Ensure playback is started, unmuted, and fullscreen. This applies CSS styling, triggers native fullscreen, and enforces volume settings.
     await ensurePlayback(page, context, profile);
@@ -1065,11 +1217,14 @@ export async function initializePlayback(page, profile, options = {}) {
     return { context, directTune };
 }
 /**
- * Tunes to a channel by navigating to the URL and initializing video playback. This is the single source of truth for channel initialization, used by both initial
- * stream setup and recovery. Having one authoritative function ensures consistent behavior and prevents code divergence between setup and recovery paths.
+ * Tunes to a channel by navigating to the URL and initializing video playback. This is the recovery path's tune: the playback monitor calls it to bring a stream
+ * back by navigating the page again. Initial stream setup and native re-establishment reach the same phases through establishChannelPlayback in streaming/setup.ts,
+ * which composes navigation and playback initialization with the per-path policy each of those callers carries. Both routes land in initializePlayback, so the
+ * channel selection, video detection, and playback steps a recovered stream runs are the steps a fresh one ran.
  *
  * The tuning process:
- * 0. Check cache: If a direct watch URL is cached, navigate to it and skip channel selection. On failure, invalidate and fall through.
+ * 0. Check cache: If a direct watch URL is cached, navigate to it and skip channel selection. On failure, fall through, and let the cache coordinator classify
+ *    the cause to decide whether the entry survives.
  * 1. Navigate: Load the target URL using site-appropriate wait conditions
  * 2. Select channel: For multi-channel players, click the desired channel in the UI
  * 3. Find video: Locate the video element (which may be in an iframe)
@@ -1083,12 +1238,13 @@ export async function initializePlayback(page, profile, options = {}) {
  * @param page - The Puppeteer page object.
  * @param url - The URL to navigate to.
  * @param profile - The site profile containing all behavior flags.
- * @returns The video context (frame or page) for subsequent monitoring.
+ * @returns The video context (frame or page) for subsequent monitoring, and a directTune flag when the channel was tuned via API interception.
  */
 export async function tuneToChannel(page, url, profile) {
     const tuneElapsed = startTimer();
-    // Check for a direct watch URL. If available, navigate directly to it and skip channel selection, avoiding guide page navigation entirely. On failure,
-    // invalidate the cache entry and fall through to the normal guide-based flow.
+    // Check for a direct watch URL. If available, navigate directly to it and skip channel selection, avoiding guide page navigation entirely. On failure, hand the
+    // cause to the cache coordinator - which keeps the entry when the failure describes a dead page rather than a bad URL - and fall through to the normal
+    // guide-based flow either way.
     const cachedUrl = await resolveDirectUrl(profile, page);
     if (cachedUrl) {
         try {
@@ -1100,15 +1256,17 @@ export async function tuneToChannel(page, url, profile) {
             return result;
         }
         catch (error) {
-            invalidateDirectUrl(profile);
+            invalidateDirectUrl(profile, error);
             LOG.warn("Cached direct URL failed for %s: %s. Falling back to guide navigation.", profile.channelSelector ?? "unknown", formatError(error));
         }
     }
     // Normal flow: navigate to the guide page URL and perform full channel selection.
     await navigateToPage(page, url, profile);
     LOG.debug("timing:tune", "Navigation complete. (+%sms)", tuneElapsed());
-    // Perform all post-navigation initialization: channel selection, video context resolution, click to play, video readiness, and fullscreen.
-    const result = await initializePlayback(page, profile);
+    // Perform all post-navigation initialization: channel selection, video context resolution, click to play, video readiness, and fullscreen. The guide URL rides
+    // along so a failed tune can diagnose the blocked page; the cached-direct attempt above deliberately does not pass it, since its failure is swallowed and retried
+    // through this authoritative path.
+    const result = await initializePlayback(page, profile, { requestedUrl: url });
     LOG.debug("timing:tune", "Tune complete. Total: %sms.", tuneElapsed());
     return result;
 }