prismcast 1.3.1 → 1.3.2

package/dist/browser/tuning/youtubeTv.js

@@ -3,6 +3,11 @@ import { CONFIG } from "../../config/index.js";
 import { logAvailableChannels } from "../channelSelection.js";
 // Base URL for YouTube TV watch page navigation.
 const YOUTUBE_TV_BASE_URL = "https://tv.youtube.com";
+// Module-level cache for watch URLs discovered during channel selection. On the first tune to any YTTV channel, the strategy performs a bulk scrape of all ~256
+// channels in the non-virtualized EPG grid, populating this cache with every channel's watch URL keyed by its lowercased guide name (e.g., "cnn", "nbc 5", "wgn").
+// Subsequent tunes to any YTTV channel resolve via findWatchUrl() in resolveDirectUrl, skipping guide navigation entirely. Cleared on browser disconnect via
+// clearYttvCache().
+const yttvWatchUrlCache = new Map();
 // Known alternate channel names for affiliates that vary by market. CW appears as "WGN" in some markets. PBS affiliates appear under local call letters (e.g.,
 // WTTW, KQED) or branded names (e.g., "Cascade PBS", "Lakeshore PBS") rather than "PBS", so we list the major market call letters and branded names to cover most
 // users. Each alternate is tried after the primary name fails both exact and prefix+digit matching. Users in smaller markets override via custom channel entries with
@@ -15,20 +20,85 @@ const CHANNEL_ALTERNATES = {
     ]
 };
 /**
- * YouTube TV grid strategy: finds a channel in the non-virtualized EPG grid at tv.youtube.com/live by querying the aria-label attribute on thumbnail endpoint
- * elements. All ~256 channel rows are present in the DOM simultaneously, so a single querySelector locates the target channel. The strategy extracts the watch
- * URL from the matching anchor element and navigates directly — no scrolling, clicking, or timing workarounds needed.
+ * Looks up a watch URL in the cache using the same three-tier matching logic as the guide grid DOM query. The tiers are tried in order for each name in the
+ * candidate list (primary channelSelector first, then any CHANNEL_ALTERNATES):
+ *
+ * 1. Exact match: cache key equals the lowercased name (e.g., "cnn" matches "cnn").
+ * 2. Prefix+digit: cache key starts with the name followed by a space and a digit. Catches local affiliates displayed as "{Network} {Number}" (e.g., "nbc 5",
+ *    "abc 7") while excluding unrelated channels (e.g., "nbc sports chicago").
+ * 3. Parenthetical suffix: cache key starts with the name followed by " (". Catches timezone/region variants like "magnolia network (pacific)".
+ *
+ * When a non-exact match succeeds, the result is also cached under the primary channelSelector key for O(1) lookup on subsequent calls. This function doubles as
+ * the resolveDirectUrl hook — after the first tune populates the cache via bulk scrape, every subsequent YTTV tune resolves here without loading the guide page.
+ * @param channelName - The channelSelector value (e.g., "CNN", "NBC", "CW").
+ * @returns The full watch URL or null if no match is found.
+ */
+function findWatchUrl(channelName) {
+    const lower = channelName.toLowerCase();
+    // Build the candidate list: primary name first, then any known alternates for markets where the affiliate uses a different name. The eslint disable is needed
+    // because TypeScript's Record indexing doesn't capture that the key may not exist at runtime.
+    const alternates = CHANNEL_ALTERNATES[lower];
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const namesToTry = alternates ? [lower, ...alternates.map((a) => a.toLowerCase())] : [lower];
+    for (const name of namesToTry) {
+        // Tier 1: Exact match.
+        const exact = yttvWatchUrlCache.get(name);
+        if (exact) {
+            // Cache under the primary channelSelector key if we matched via an alternate name, so subsequent lookups are O(1).
+            if (name !== lower) {
+                yttvWatchUrlCache.set(lower, exact);
+            }
+            return exact;
+        }
+        // Tier 2: Prefix+digit match for local affiliates. Iterate all cache entries to find one whose key starts with "{name} " followed by a digit, matching the
+        // "{Network} {Number}" pattern (e.g., "nbc 5", "abc 7") while excluding unrelated channels (e.g., "nbc sports chicago").
+        for (const [key, url] of yttvWatchUrlCache) {
+            if (key.startsWith(name + " ") && (key.length > name.length + 1) && (key.charCodeAt(name.length + 1) >= 48) && (key.charCodeAt(name.length + 1) <= 57)) {
+                yttvWatchUrlCache.set(lower, url);
+                return url;
+            }
+        }
+        // Tier 3: Parenthetical suffix match for timezone/region variants. Find a cache entry whose key starts with "{name} (" to catch channels like
+        // "magnolia network (pacific)" or "the filipino channel (pacific)".
+        for (const [key, url] of yttvWatchUrlCache) {
+            if (key.startsWith(name + " (")) {
+                yttvWatchUrlCache.set(lower, url);
+                return url;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Invalidates the cached YouTube TV watch URL for the given channel selector. Called when a cached URL fails to produce a working stream. Deletes the
+ * channelSelector key — the bulk-scraped guide-name entries are left intact and will be refreshed on the next strategy run when the guide page is reloaded.
+ * @param channelSelector - The channel selector string to invalidate.
+ */
+function invalidateYttvDirectUrl(channelSelector) {
+    yttvWatchUrlCache.delete(channelSelector.toLowerCase());
+}
+/**
+ * Clears all cached YouTube TV watch URLs. Called by clearChannelSelectionCaches() in the coordinator when the browser restarts.
+ */
+function clearYttvCache() {
+    yttvWatchUrlCache.clear();
+}
+/**
+ * YouTube TV grid strategy: scrapes all watch URLs from the non-virtualized EPG grid at tv.youtube.com/live in a single pass, populating the module-level cache so
+ * that subsequent tunes to any YTTV channel resolve via findWatchUrl() without loading the guide page. All ~256 channel rows are present in the DOM simultaneously,
+ * so one querySelectorAll captures every channel's name and watch URL.
  *
  * The selection process:
  * 1. Wait for ytu-epg-row elements to confirm the guide grid has loaded.
- * 2. Find the target channel using a case-insensitive aria-label CSS selector.
- * 3. Extract the href attribute and validate it starts with "watch/" (not "live" or "browse/").
- * 4. Navigate to the full watch URL via page.goto().
+ * 2. Bulk scrape all channels: extract aria-label names and watch/ hrefs from every thumbnail endpoint.
+ * 3. Populate the watch URL cache with all discovered channels.
+ * 4. Look up the target channel using tiered matching (exact, prefix+digit, parenthetical, alternates) against the cache.
+ * 5. Navigate to the matched watch URL via page.goto().
  * @param page - The Puppeteer page object.
  * @param profile - The resolved site profile with a non-null channelSelector (channel name, e.g., "CNN", "ESPN", "NBC").
  * @returns Result object with success status and optional failure reason.
  */
-export async function youtubeGridStrategy(page, profile) {
+async function youtubeGridStrategy(page, profile) {
     const channelName = profile.channelSelector;
     // Wait for the EPG grid to render. All ~256 rows load simultaneously (no virtualization), so once any row exists, all channels are queryable.
     try {
@@ -37,99 +107,52 @@ export async function youtubeGridStrategy(page, profile) {
     catch {
         return { reason: "YouTube TV guide grid did not load.", success: false };
     }
-    // Build the list of names to try: the primary name first, then any known alternates for markets where the affiliate uses a different name. The eslint disable is
-    // needed because TypeScript's Record indexing doesn't capture that the key may not exist at runtime.
-    const alternates = CHANNEL_ALTERNATES[channelName.toLowerCase()];
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    const namesToTry = alternates ? [channelName, ...alternates] : [channelName];
-    // Find the watch URL for the target channel. For each name in the list, we try three matching tiers:
-    //
-    // 1. Exact match: aria-label="watch {Name}" (case-insensitive).
-    // 2. Prefix+digit: aria-label starts with "watch {Name} " followed by a digit. This catches local affiliates displayed as "{Network} {Number}" (e.g., "NBC 5",
-    //    "ABC 7", "FOX 32") while excluding unrelated channels (e.g., "NBC Sports Chicago").
-    // 3. Parenthetical suffix: aria-label starts with "watch {Name} (" to match timezone/region variants like "Magnolia Network (Pacific)" or
-    //    "The Filipino Channel (Pacific)".
-    const watchPath = await evaluateWithAbort(page, (names) => {
-        // Helper to extract and validate a watch URL from an anchor element. Returns the href if it points to a streamable watch page, null otherwise.
-        const extractWatchHref = (anchor) => {
-            if (!anchor) {
-                return null;
-            }
-            const href = anchor.getAttribute("href");
-            // Validate the href points to a streamable watch page. Channels with "live" or "browse/" hrefs are premium add-ons or info pages that cannot be streamed.
-            if (!href?.startsWith("watch/")) {
-                return null;
-            }
-            return href;
-        };
-        // Try each name in order. The primary channel name is tried first, followed by any known alternates.
-        for (const name of names) {
-            // Tier 1: Exact match. The CSS "i" flag enables case-insensitive matching to handle variations in capitalization between the channel selector and the guide.
-            const exactSelector = "ytu-endpoint.tenx-thumb[aria-label=\"watch " + name + "\" i] a";
-            const exactResult = extractWatchHref(document.querySelector(exactSelector));
-            if (exactResult) {
-                return exactResult;
+    // Bulk scrape all channels from the grid in a single evaluate round-trip. For each thumbnail endpoint with a valid watch/ href, extract the channel name (from
+    // the aria-label, stripping the "watch " prefix) and the watch path. Channels with "live" or "browse/" hrefs are premium add-ons or info pages and are excluded.
+    const allChannels = await evaluateWithAbort(page, () => {
+        const results = [];
+        for (const thumb of Array.from(document.querySelectorAll("ytu-endpoint.tenx-thumb[aria-label]"))) {
+            const label = thumb.getAttribute("aria-label") ?? "";
+            if (!label.startsWith("watch ")) {
+                continue;
             }
-            // Tier 2: Prefix + digit match for local affiliates. Find all thumbnails whose aria-label starts with "watch {Name} " and filter to those where the next
-            // character is a digit, matching the "{Network} {Number}" pattern (e.g., "NBC 5", "ABC 7") while excluding unrelated channels (e.g., "NBC Sports Chicago").
-            const prefixSelector = "ytu-endpoint.tenx-thumb[aria-label^=\"watch " + name + " \" i] a";
-            const candidates = document.querySelectorAll(prefixSelector);
-            const prefix = "watch " + name + " ";
-            for (const candidate of Array.from(candidates)) {
-                const parent = candidate.closest("ytu-endpoint.tenx-thumb");
-                const label = parent?.getAttribute("aria-label") ?? "";
-                const suffix = label.slice(prefix.length);
-                // Accept only if the remainder starts with a digit — this is the local affiliate channel number.
-                if ((suffix.length > 0) && (suffix.charCodeAt(0) >= 48) && (suffix.charCodeAt(0) <= 57)) {
-                    return extractWatchHref(candidate);
-                }
-            }
-            // Tier 3: Parenthetical suffix match for timezone/region variants. Channels like "Magnolia Network (Pacific)" or "The Filipino Channel (Pacific)" have the
-            // base name followed by a space and a parenthetical. The CSS selector matches aria-labels starting with "watch {Name} (" to catch these variants.
-            const parenSelector = "ytu-endpoint.tenx-thumb[aria-label^=\"watch " + name + " (\" i] a";
-            const parenResult = extractWatchHref(document.querySelector(parenSelector));
-            if (parenResult) {
-                return parenResult;
+            const anchor = thumb.querySelector("a");
+            const href = anchor?.getAttribute("href") ?? "";
+            // Only include channels with streamable watch URLs. Channels with "live" or "browse/" hrefs are premium add-ons or info pages.
+            if (href.startsWith("watch/")) {
+                results.push({ name: label.slice(6), watchPath: href });
             }
         }
-        return null;
-    }, [namesToTry]);
-    if (!watchPath) {
-        // Channel not found. Query all available channel names from the guide grid and log them as a diagnostic to help users identify their market's channel names
-        // and create user-defined channels with the correct channelSelector value.
-        try {
-            const availableChannels = await evaluateWithAbort(page, () => {
-                return Array.from(document.querySelectorAll("ytu-endpoint.tenx-thumb[aria-label]"))
-                    .map((el) => {
-                    const label = el.getAttribute("aria-label") ?? "";
-                    return label.startsWith("watch ") ? label.slice(6) : "";
-                })
-                    .filter((name) => name.length > 0)
-                    .sort();
-            }, []);
-            // Build additional known names from CHANNEL_ALTERNATES values so they are also filtered out of the diagnostic list.
-            const additionalKnownNames = [];
-            for (const alts of Object.values(CHANNEL_ALTERNATES)) {
-                for (const alt of alts) {
-                    additionalKnownNames.push(alt);
-                }
+        return results;
+    }, []);
+    // Populate the watch URL cache with all discovered channels. This makes every subsequent YTTV tune a cache hit via resolveDirectUrl, skipping guide navigation
+    // entirely. Cache keys are lowercased guide names (e.g., "cnn", "nbc 5", "wgn"). The tiered matching in findWatchUrl() handles channelSelector-to-guide-name
+    // resolution (e.g., "NBC" finds "nbc 5" via prefix+digit matching, "CW" finds "wgn" via CHANNEL_ALTERNATES).
+    for (const ch of allChannels) {
+        yttvWatchUrlCache.set(ch.name.toLowerCase(), YOUTUBE_TV_BASE_URL + "/" + ch.watchPath);
+    }
+    LOG.debug("tuning:yttv", "Cached %s YouTube TV watch URLs.", yttvWatchUrlCache.size);
+    // Look up the target channel using tiered matching against the populated cache.
+    const watchUrl = findWatchUrl(channelName);
+    if (!watchUrl) {
+        // Channel not found. Log available channels as a diagnostic to help users identify their market's channel names and create user-defined channels with the
+        // correct channelSelector value. Build additional known names from CHANNEL_ALTERNATES values so they are also filtered out of the diagnostic list.
+        const additionalKnownNames = [];
+        for (const alts of Object.values(CHANNEL_ALTERNATES)) {
+            for (const alt of alts) {
+                additionalKnownNames.push(alt);
             }
-            logAvailableChannels({
-                additionalKnownNames,
-                availableChannels,
-                channelName,
-                guideUrl: "https://tv.youtube.com/live",
-                presetSuffix: "-yttv",
-                providerName: "YouTube TV"
-            });
-        }
-        catch {
-            // Diagnostic dump is best-effort. Don't let it mask the real channel selection failure.
         }
+        logAvailableChannels({
+            additionalKnownNames,
+            availableChannels: allChannels.map((ch) => ch.name).sort(),
+            channelName,
+            guideUrl: "https://tv.youtube.com/live",
+            presetSuffix: "-yttv",
+            providerName: "YouTube TV"
+        });
         return { reason: "Channel \"" + channelName + "\" not found in YouTube TV guide.", success: false };
     }
-    // Navigate directly to the watch URL. This auto-starts playback without any click interaction needed.
-    const watchUrl = YOUTUBE_TV_BASE_URL + "/" + watchPath;
     LOG.debug("tuning:yttv", "Navigating to YouTube TV watch URL for %s.", channelName);
     try {
         await page.goto(watchUrl, { timeout: CONFIG.streaming.navigationTimeout, waitUntil: "load" });
@@ -139,4 +162,21 @@ export async function youtubeGridStrategy(page, profile) {
     }
     return { success: true };
 }
+/**
+ * Async wrapper around findWatchUrl for the ChannelStrategyEntry.resolveDirectUrl contract. The page parameter is unused because YTTV watch URLs are resolved
+ * purely from the in-memory cache populated during the first guide page scrape.
+ * @param channelSelector - The channel selector string (e.g., "CNN", "ESPN", "NBC").
+ * @param _page - Unused. Present to satisfy the async resolveDirectUrl signature.
+ * @returns The cached watch URL or null.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/require-await
+async function resolveYttvDirectUrl(channelSelector, _page) {
+    return findWatchUrl(channelSelector);
+}
+export const yttvStrategy = {
+    clearCache: clearYttvCache,
+    execute: youtubeGridStrategy,
+    invalidateDirectUrl: invalidateYttvDirectUrl,
+    resolveDirectUrl: resolveYttvDirectUrl
+};
 //# sourceMappingURL=youtubeTv.js.map

package/dist/browser/tuning/youtubeTv.js.map

@@ -1 +1 @@
-{"version":3,"file":"youtubeTv.js","sourceRoot":"","sources":["../../../src/browser/tuning/youtubeTv.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"youtubeTv.js","sourceRoot":"","sources":["../../../src/browser/tuning/youtubeTv.ts"],"names":[],"mappings":"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"}

package/dist/browser/video.d.ts

@@ -144,8 +144,9 @@ export declare function waitForVideoReady(context: Frame | Page, profile: Resolv
  * - cursor: none - Hides the mouse cursor for cleaner capture
  * @param context - The frame or page containing the video element.
  * @param selectorType - The video selector type for finding the element.
+ * @param important - When true, applies styles with !important priority to override site JavaScript that actively fights style changes.
  */
-export declare function applyVideoStyles(context: Frame | Page, selectorType: VideoSelectorType): Promise<void>;
+export declare function applyVideoStyles(context: Frame | Page, selectorType: VideoSelectorType, important?: boolean): Promise<void>;
 /**
  * Locks the volume properties on the video element to prevent the site's JavaScript from muting our stream. Some sites (like France24) aggressively mute videos
  * or lower volume in response to various events. They may reset volume on play, on focus, on visibility change, or on a timer.
@@ -174,22 +175,52 @@ export declare function lockVolumeProperties(context: Frame | Page, selectorType
  * @param selectorType - The video selector type for finding the element.
  */
 export declare function triggerFullscreen(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, selectorType: VideoSelectorType): Promise<void>;
+/**
+ * Verifies that the video element is filling the viewport, indicating that fullscreen styling was successfully applied. This function checks the video element's
+ * bounding rectangle against the viewport dimensions to determine if the video appears fullscreen.
+ *
+ * The verification allows for some tolerance because:
+ * - The video may have letterboxing/pillarboxing due to aspect ratio differences
+ * - Some browsers report slightly smaller dimensions due to scrollbars or UI chrome
+ * - CSS rounding may cause small discrepancies
+ *
+ * We require the video to fill at least 85% of the viewport in at least one dimension (the constraining dimension for aspect ratio) and at least 50% in the
+ * other dimension to catch obviously broken cases.
+ * @param context - The frame or page containing the video element.
+ * @param selectorType - The video selector type for finding the element.
+ * @returns True if the video appears to be fullscreen, false if it does not, or null if the check could not be performed (e.g. context destroyed).
+ */
+export declare function verifyFullscreen(context: Frame | Page, selectorType: VideoSelectorType): Promise<Nullable<boolean>>;
 /**
  * Ensures the video is displayed fullscreen with verification and retry logic. This function orchestrates the fullscreen process:
  *
  * 1. Initial attempt: Apply CSS styles and trigger fullscreen API
- * 2. Verify: Check if video is filling the viewport
- * 3. Simple retry: If verification fails, wait and retry the same approach (timing issues are common)
- * 4. Escalate: If simple retries fail, apply aggressive fullscreen techniques
+ * 2. Verify: Check video dimensions and, for fullscreenApi profiles, confirm document.fullscreenElement is set
+ * 3. Simple retry: If verification fails, click the video for user activation and retry (the Fullscreen API requires a recent user gesture)
+ * 4. Escalate: If simple retries fail, apply aggressive fullscreen techniques with a final Fullscreen API re-trigger
  *
- * The retry approach handles the common case where fullscreen fails due to timing - the page may still be initializing when we first attempt. Escalation to
- * aggressive techniques is a last resort that may break site functionality but ensures video fills the viewport.
+ * The retry approach handles both timing issues (page still initializing) and user activation issues (requestFullscreen requires a recent user gesture).
+ * On retry, clicking the video provides fresh activation so the subsequent requestFullscreen() call can succeed. Escalation to aggressive techniques is a
+ * last resort that may break site functionality but ensures video fills the viewport.
  * @param page - The Puppeteer page object for keyboard input.
  * @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.
+ * @param skipNativeFullscreen - When true, skips Fullscreen API-specific actions (click-for-activation, native fullscreen verification, API retries). CSS styling
+ *   and keyboard shortcuts still run. Used during monitor recovery where user activation is unavailable and click-for-activation can interfere with playback.
+ */
+export declare function ensureFullscreen(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, selectorType: VideoSelectorType, skipNativeFullscreen?: boolean): Promise<void>;
+/**
+ * Options for ensurePlayback() that control recovery behavior.
  */
-export declare function ensureFullscreen(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, selectorType: VideoSelectorType): Promise<void>;
+interface EnsurePlaybackOptions {
+    /** The escalation level (1-2). Level 1 is basic play/unmute recovery. Level 2 adds video source reload. Defaults to 1. */
+    recoveryLevel?: number;
+    /** When true, skips native Fullscreen API actions (click-for-activation, API verification, API retries) during the fullscreen step. CSS styling and keyboard
+     * shortcuts still run. Used by the monitor during recovery where user activation is unavailable and click-for-activation can toggle playback state. The
+     * monitor's own lightweight fullscreen maintenance loop handles ongoing CSS reapplication independently. Defaults to false. */
+    skipNativeFullscreen?: boolean;
+}
 /**
  * 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.
@@ -199,8 +230,8 @@ export declare function ensureFullscreen(page: Page, context: Frame | Page, prof
  * LEVEL 1 - Basic recovery (default):
  * - Set muted=false and volume=1
  * - Call play() if video is paused
- * - Ensure fullscreen with verification and retry (applies CSS, triggers fullscreen API/keyboard, verifies video fills viewport, escalates to aggressive
- *   techniques if needed)
+ * - Ensure fullscreen with CSS styling, keyboard shortcuts, and dimension verification. When skipNativeFullscreen is set, Fullscreen API-specific actions are
+ *   skipped because user activation is unavailable and click-for-activation can interfere with playback recovery.
  * - Lock volume properties if profile requires it
  *
  * LEVEL 2 - Reload video source:
@@ -214,9 +245,9 @@ export declare function ensureFullscreen(page: Page, context: Frame | Page, prof
  * @param page - The Puppeteer page object.
  * @param context - The frame or page containing the video element.
  * @param profile - The site profile containing all behavior flags.
- * @param recoveryLevel - The escalation level (1-2). Defaults to 1.
+ * @param options - Optional recovery configuration. Omit for initial tune (full fullscreen behavior, level 1).
  */
-export declare function ensurePlayback(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, recoveryLevel?: number): Promise<void>;
+export declare function ensurePlayback(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, options?: EnsurePlaybackOptions): Promise<void>;
 /**
  * Performs all post-navigation channel initialization: selects the channel, finds the video context, clicks to play if needed, waits for video readiness, and
  * ensures playback with fullscreen styling. This function is separated from navigateToPage() so that retryOperation() in setup.ts can wrap only navigation with a
@@ -228,14 +259,17 @@ export declare function ensurePlayback(page: Page, context: Frame | Page, profil
  *
  * @param page - The Puppeteer page object.
  * @param profile - The site profile containing all behavior flags.
+ * @param skipChannelSelection - When true, skip the channel selection phase entirely. Used when navigating directly to a cached watch URL that already targets
+ *   the correct channel — only video detection, playback, and fullscreen setup are needed.
  * @returns The video context (frame or page) for subsequent monitoring.
  */
-export declare function initializePlayback(page: Page, profile: ResolvedSiteProfile): Promise<TuneResult>;
+export declare function initializePlayback(page: Page, profile: ResolvedSiteProfile, skipChannelSelection?: boolean): Promise<TuneResult>;
 /**
  * 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.
  *
  * 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.
  * 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)
@@ -252,3 +286,4 @@ export declare function initializePlayback(page: Page, profile: ResolvedSiteProf
  * @returns The video context (frame or page) for subsequent monitoring.
  */
 export declare function tuneToChannel(page: Page, url: string, profile: ResolvedSiteProfile): Promise<TuneResult>;
+export {};