prismcast 1.10.2 → 1.11.0

package/dist/browser/manifestInterceptor.js

@@ -1,295 +1,293 @@
-import { LOG, chromeFetch, startTimer } from "../utils/index.js";
-import { classifyHlsPlaylist } from "../native/probe.js";
-/* This module installs a Chrome DevTools Protocol (CDP) listener on the Network domain to capture HLS manifest URLs as the browser's video player fetches them. The
- * listener is shared by two consumers:
+import { LOG, extractPathname, startTimer } from "../utils/index.js";
+import { observeHlsPlaylists } from "./hlsPlaylistObserver.js";
+/* This module hosts two consumer-facing state machines built on top of the HLS playlist observer (hlsPlaylistObserver.ts), which in turn rides on the tab-wide
+ * network observer (tabNetworkObserver.ts). The layering:
  *
- * - Native HLS streaming: captures the playlist URL during stream startup and hands the CDP session off to the proxy for subsequent token-refresh tunes. See
- *   installManifestInterceptor() and the consumers in src/native/. This consumer accepts both master and media playlists; the probe normalizes either kind into a
- *   MediaFeed so downstream code does not branch on which kind arrived.
- * - Tune verification: confirms that the channel a strategy clicked actually loaded by matching the resulting manifest URL against an expected predicate (e.g.,
- *   call sign in the path). See awaitMatchingManifest() and the consumer in src/browser/tuning/fox.ts. This consumer expects master playlists only because tune
- *   verification is a multi-channel concept that does not apply to direct-tune media-only sources.
+ *   tabNetworkObserver  -> tab-wide CDP transport (OOPIF-aware via auto-attach + flatten)
+ *   hlsPlaylistObserver -> HLS filter + body fetch + classify + per-URL dedup + wire-arrival sequencing
+ *   manifestInterceptor -> selection: the channel-selection epoch, playlist membership, the liveness override, finalize semantics, predicate match
  *
- * Both APIs share the underlying CDP observer that filters .m3u8 URLs, fetches the body, and asks classifyHlsPlaylist() for the playlist kind; the kind is
- * forwarded to consumers so each can apply its own kind-specific filter without re-reading the body. Classification lives in exactly one place
- * (src/native/probe.ts) so the master/media decision cannot drift between the interceptor's transport-layer gate and the probe's resolution-layer dispatch.
- * We use a direct fetch rather than CDP's Network.getResponseBody because Chrome's network cache can evict response bodies before we read them, causing
- * spurious "No data found for resource" failures.
+ * This module hosts the following consumer-facing state machines built on top of the HLS playlist observer:
  *
- * For multi-channel sites, the video player may load manifests for channels other than the one requested. installManifestInterceptor tracks both the first and
- * latest master manifest URLs to handle two distinct tuning patterns. The pattern is selected by the directTune flag passed to finalize():
+ * - installManifestInterceptor(): the long-lived capture used by native HLS setup. Accepts both master and media playlists, tracks the first and latest URL per
+ *   kind, and resolves with the playlist appropriate for the tune type when finalize() is called. A direct tune (single-channel site navigated by URL) takes the
+ *   first qualifying capture, master preferred. A guide tune (multi-channel site) judges the captures through three signals - a channel-selection epoch stamped
+ *   when selection begins, playlist membership of a media playlist within the latest master's declared children, and media liveness - so the tuned channel's
+ *   playlist is chosen even when a page-load default channel was captured first. See selectInterceptedManifest for the full rule.
+ * - awaitMatchingManifest(): the short-lived verification used after a guide-click tune. Accepts master playlists only and resolves with the first URL whose
+ *   path satisfies a caller-supplied predicate. Media playlists are skipped at the consumer level because tune verification is a multi-channel concept that
+ *   does not apply to direct-tune media-only sources.
  *
- * - Direct tunes (directTune=true): the navigated URL itself selects the channel, so the first manifest captured is the correct one - the player loaded it for
- *   the navigated URL. Background prefetches for other channels may arrive later but should be ignored. The first manifest wins.
- * - Guide tunes (directTune=false): page navigation loads a default channel's manifest, then a tuning strategy (guide-grid click, JS bridge call, webpack
- *   injection, etc.) triggers a new manifest fetch for the requested channel. The latest manifest wins.
- *
- * awaitMatchingManifest takes a different approach: it resolves with the first master manifest whose URL satisfies the caller-supplied predicate. The CDP session
- * is torn down automatically on resolution. This is the verification path - the caller has already triggered the tune and now wants confirmation that the
- * resulting manifest belongs to the expected channel.
+ * Race safety, URL filtering, body fetching, classification, and wire-arrival sequencing all live below this module - we receive a stream of recognized HLS
+ * playlists with their kind, per-kind facts, and arrival ordinal, and apply selection policy. Public callers do not hold CDP session references; the underlying
+ * HLS observer disposes its tab network observer deterministically when finalize, timeout, predicate match, or explicit dispose fires.
  */
-// Default timeout for the long-lived interception used by native HLS.
-const INTERCEPTION_TIMEOUT = 15000;
-// Brief delay after finalize() is called to allow any in-flight manifest response to arrive. Applied only for guide-based tunes (directTune=false) where the
-// channel switch may trigger a manifest fetch that arrives milliseconds after the click handler returns. Direct tunes skip this delay and resolve immediately.
-const FINALIZE_SETTLE_DELAY = 1500;
+// Brief delay after finalize() is called to allow any in-flight manifest response to arrive. Applied for guide-based tunes (directTune=false), where the channel
+// switch may trigger a manifest fetch that arrives milliseconds after the click handler returns, and for direct tunes that have not yet captured a master
+// manifest. A direct tune skips this delay and resolves immediately only once a master manifest has already arrived. Exported so a caller sizing its own
+// interception window (streaming/setup.ts) can include the settle window the window must outlive.
+export const FINALIZE_SETTLE_DELAY = 1500;
 // Default timeout for awaitMatchingManifest. Tune verification is a short-lived check after a click, so the budget is tighter than the native interception path.
 const VERIFICATION_TIMEOUT = 8000;
-// Timeout for the per-response manifest body fetch. The body is fed to classifyHlsPlaylist() to determine whether it is a master playlist; if Chrome's network
-// cache evicts the body or the CDN serves a slow response, we abandon and treat the response as non-master.
-const MANIFEST_BODY_FETCH_TIMEOUT = 5000;
 /**
- * Selects the playlist URL appropriate for a given resolution mode from the per-kind first/latest state captured by the manifest observer. Master URLs always
- * outrank media URLs when both kinds were observed because masters declare richer metadata (variant bandwidth, resolution, separate audio renditions). Within
- * the chosen kind, direct tunes pick the first URL and guide tunes pick the latest URL. Returns null when no qualifying URL is available.
- *
- * Pure function exported for unit testing; the closure inside installManifestInterceptor() consumes it through the same shape.
+ * Reports whether a media playlist is a verified NON-member of a master's declared children, comparing by pathname only. Membership is URL-identity policy, not
+ * manifest-format knowledge, which is why it lives here rather than in probe. Pathname-only because post-redirect response URLs diverge from a master's declared
+ * child URIs at the host far more often than at the path. The judgment is member-conservative: a media URL that cannot be parsed, an empty declared child list, or
+ * an empty effective set after dropping unparseable children all read as MEMBER (the master wins, degrading to the categorical rule, never a new failure). Only a
+ * parseable media pathname absent from a non-empty set of parseable child pathnames is a verified non-member.
  *
- * @param state - The captured-URL state at resolution time.
- * @returns The selected URL, or null when no URL matches the resolution mode.
+ * @param mediaUrl - The candidate media playlist URL.
+ * @param childUrls - The master's declared child playlist URLs.
+ * @returns True only when the media pathname is proven absent from a non-empty effective set of child pathnames.
  */
-export function selectInterceptedManifest(state) {
-    if (state.directTune) {
-        return state.firstMasterUrl ?? state.firstMediaUrl;
+function isVerifiedNonMemberOfMaster(mediaUrl, childUrls) {
+    const mediaPathname = extractPathname(mediaUrl);
+    // A media URL we cannot parse cannot be proven foreign, so it reads as a member and the master wins.
+    if (mediaPathname === null) {
+        return false;
+    }
+    // Normalize the declared children to pathnames, dropping any that cannot be parsed. An empty declared list or a list that parses to nothing yields an empty
+    // effective set: with no children to compare against, membership cannot be disproven, so the master wins.
+    const childPathnames = childUrls.map((child) => extractPathname(child)).filter((pathname) => pathname !== null);
+    if (childPathnames.length === 0) {
+        return false;
     }
-    return state.latestMasterUrl ?? state.latestMediaUrl;
+    return !childPathnames.includes(mediaPathname);
 }
 /**
- * Installs a CDP Network.responseReceived listener that calls onPlaylist() for every recognized HLS playlist URL observed. The listener filters to .m3u8 URLs,
- * fetches the body, and asks classifyHlsPlaylist() for the playlist kind; recognized kinds (master, media) fire the callback with the kind label, while
- * unrecognized bodies are skipped. Consumers apply their own kind-specific filtering on top of the callback - installManifestInterceptor accepts both kinds
- * with master priority, while awaitMatchingManifest accepts master only.
+ * Selects the playlist appropriate for a given resolution mode from the captured state, reporting the URL together with the kind selection decided.
  *
- * Returns null when the page is closed or the CDP session cannot be created. The caller is responsible for calling dispose() to clean up.
- * @param page - The Puppeteer page to monitor.
- * @param onPlaylist - Callback invoked for each verified HLS playlist URL together with its kind.
- * @param logCategory - Debug log category for this observer's lifecycle messages.
- * @returns The observer handle, or null if installation failed.
+ * Direct tunes take the earliest qualifying capture (firstMasterUrl before firstMediaUrl), master preferred, with the kind tagged by the slot that supplied the
+ * URL. The epoch never participates on the direct branch: a direct tune navigates by URL and its first capture answers.
+ *
+ * Guide tunes apply a three-signal rule over the latest captures:
+ *
+ *   1. No master captured: the media fallback (latestMedia's URL) or null. Liveness gates only the override of a master, never the sole available feed, so a VOD
+ *      media playlist still answers when it is all that arrived.
+ *   2. Epoch declared and the master post-epoch (latestMaster.ordinal > markOrdinal): the master, categorically. A master observed after channel selection began
+ *      answers the click. An absent epoch (mark never called) also leaves the master the winner, because without a click there is no fresher truth to prefer.
+ *   3. Override to the media only when every clause holds: an epoch exists (rule 2 falling through means the master is pre-epoch), latestMedia is live, the media
+ *      is post-epoch (latestMedia.ordinal > markOrdinal - which structurally postdates the pre-epoch master, so no separate ordering clause is needed), and the
+ *      media is a verified non-member of the master's children. Otherwise the master wins.
+ *
+ * Membership is member-conservative (see isVerifiedNonMemberOfMaster): anything short of a proven foreign pathname keeps the master, so the override engages only
+ * where a media playlist is demonstrably not one of the master's own children. Pure selection policy exported so the rule is testable in isolation from the
+ * network plumbing; the closure inside installManifestInterceptor() consumes it through the same shape.
+ *
+ * @param state - The captured state at resolution time.
+ * @returns The selected playlist, or null when no URL matches the resolution mode.
  */
-async function startManifestObserver(page, onPlaylist, logCategory) {
-    if (page.isClosed()) {
+export function selectInterceptedManifest(state) {
+    if (state.directTune) {
+        if (state.firstMasterUrl !== null) {
+            return { kind: "master", url: state.firstMasterUrl };
+        }
+        if (state.firstMediaUrl !== null) {
+            return { kind: "media", url: state.firstMediaUrl };
+        }
         return null;
     }
-    let cdpSession;
-    try {
-        cdpSession = await page.createCDPSession();
-    }
-    catch (error) {
-        LOG.debug(logCategory, "Failed to create CDP session: %s.", String(error));
-        return null;
+    const { latestMaster, latestMedia, markOrdinal } = state;
+    // Rule 1: no master captured. The media fallback answers regardless of liveness.
+    if (latestMaster === null) {
+        return (latestMedia === null) ? null : { kind: "media", url: latestMedia.url };
     }
-    try {
-        await cdpSession.send("Network.enable");
+    // Rule 2: a master observed after channel selection began answers the click categorically; an absent epoch keeps the master too.
+    if ((markOrdinal !== null) && (latestMaster.ordinal > markOrdinal)) {
+        return { kind: "master", url: latestMaster.url };
     }
-    catch (error) {
-        LOG.debug(logCategory, "Failed to enable Network domain: %s.", String(error));
-        return null;
+    // Rule 3: override to a live, post-epoch, verified non-member media; otherwise the master wins.
+    if ((markOrdinal !== null) && (latestMedia !== null) && latestMedia.live && (latestMedia.ordinal > markOrdinal) &&
+        isVerifiedNonMemberOfMaster(latestMedia.url, latestMaster.childUrls)) {
+        return { kind: "media", url: latestMedia.url };
     }
-    LOG.debug(logCategory, "CDP manifest observer installed.");
-    let disposed = false;
-    // Listen for completed responses. We use Network.responseReceived to capture .m3u8 URLs, then fetch the manifest body directly from Node.js to verify it is
-    // a master manifest. This avoids CDP's Network.getResponseBody which is unreliable - Chrome's network cache can evict response bodies before we read them.
-    const onResponseReceived = async (params) => {
-        if (disposed) {
-            return;
-        }
-        const url = params.response.url;
-        // Filter for .m3u8 URLs. Strip query parameters before checking the extension.
-        const urlPath = url.split("?")[0] ?? "";
-        if (!urlPath.endsWith(".m3u8")) {
-            return;
-        }
-        LOG.debug(logCategory, "Observed .m3u8 response: %s.", url.slice(0, 120));
-        // Fetch the manifest body directly to inspect whether this is a master manifest. The URL contains embedded CDN auth tokens, so no cookies or special
-        // headers are needed beyond the Chrome User-Agent injected by chromeFetch().
-        try {
-            const response = await chromeFetch(url, { signal: AbortSignal.timeout(MANIFEST_BODY_FETCH_TIMEOUT) });
-            if (!response.ok) {
-                LOG.debug(logCategory, "Manifest fetch returned HTTP %s for %s.", response.status, url.slice(0, 120));
-                return;
-            }
-            const body = await response.text();
-            // Delegate the master/media decision to the canonical classifier. Recognized kinds (master, media) are forwarded to the callback together with the kind
-            // label; consumers apply their own filter. Both consumers of onPlaylist maintain their own resolved-flag guard, so a callback that arrives after dispose
-            // is harmless - the downstream resolve is idempotent.
-            const kind = classifyHlsPlaylist(body);
-            if (kind === "unknown") {
-                LOG.debug(logCategory, "Skipping .m3u8 classified as unknown (no recognizable HLS directives).");
-                return;
-            }
-            onPlaylist(url, kind);
-        }
-        catch (error) {
-            LOG.debug(logCategory, "Could not fetch .m3u8 body: %s.", String(error));
-        }
-    };
-    // Wrap the async handler to avoid no-misused-promises - EventEmitter.on() does not handle returned promises.
-    const wrappedHandler = (...args) => { void onResponseReceived(...args); };
-    cdpSession.on("Network.responseReceived", wrappedHandler);
-    const dispose = (keepSession) => {
-        if (disposed) {
-            return;
-        }
-        disposed = true;
-        cdpSession.off("Network.responseReceived", wrappedHandler);
-        if (!keepSession) {
-            removeManifestInterceptor(cdpSession);
-        }
-    };
-    return { cdpSession, dispose };
+    return { kind: "master", url: latestMaster.url };
 }
 /**
- * Installs a long-lived CDP listener that tracks observed HLS playlist URLs on the given page. Both master and media playlists are accepted; the listener tracks
- * first/latest URLs separately per kind so master-based and media-only sites both work without separate code paths. Master playlists take precedence over media
- * playlists when both have arrived during the interception window because masters carry richer metadata (variant bandwidth, resolution, separate audio
- * renditions) that improves the resulting MediaFeed. The returned handle provides a finalize(directTune) callback - when called, the interceptor resolves with
- * whichever URL is appropriate for the tune type:
+ * Installs a long-lived HLS playlist observer that tracks observed playlists on the given page. Both master and media playlists are accepted; the first and latest
+ * URL per kind are tracked separately, guarded by wire-arrival order, so master-based and media-only sites both work without separate code paths. The returned
+ * handle provides a finalize(directTune) callback and a markChannelSelectionStart() epoch stamp; when finalize is called the observer resolves through
+ * selectInterceptedManifest with the playlist appropriate for the tune type:
+ *
+ * - directTune=true: resolves immediately if a master manifest has already arrived (or after the settle delay when only a media-only manifest, or nothing, has
+ *   arrived so far) with the first manifest captured. Used by sites where the navigated URL itself selects the channel and the player loads its manifest before
+ *   the click handler returns. Master-first URL preferred over media-first.
+ * - directTune=false: resolves after the settle delay through the guide-tune rule (channel-selection epoch, playlist membership, liveness), so the tuned
+ *   channel's playlist wins over a page-load default channel captured first. Used by guide-based sites where the channel-switch click triggers a new manifest
+ *   fetch that may arrive milliseconds after the click handler returns.
  *
- * - directTune=true: resolves immediately (or after the settle delay if no manifest has arrived yet) with the first manifest captured. Used by sites where the
- *   navigated URL itself selects the channel and the player loads its manifest before the click handler returns. Master-first URL preferred over media-first.
- * - directTune=false: resolves after the settle delay with the latest manifest captured. Used by guide-based sites where the channel-switch click triggers a new
- *   manifest fetch that may arrive milliseconds after the click handler returns. Master-latest URL preferred over media-latest.
+ * On timeout (finalize never called), the observer resolves epoch-free through the same guide-tune rule with no epoch declared, so the categorical
+ * master-preferred outcome holds and a direct tune the timeout may be guarding is never exposed to the epoch rule. The underlying HLS observer is disposed
+ * automatically on resolution; callers do not hold CDP session references.
  *
- * On timeout (finalize never called), the listener resolves with the latest captured URL using the same master-priority rule, or null if none arrived. The CDP
- * session is preserved in the result and ownership transfers to the caller; callers must call removeManifestInterceptor() when done.
- * @param page - The Puppeteer page to monitor.
- * @param timeout - Maximum time in milliseconds to wait for a manifest. Acts as a safety net if finalize() is never called.
- * @returns The interceptor handle, or null if the CDP session could not be created.
+ * @param page - The puppeteer page to monitor.
+ * @param timeout - Maximum time in milliseconds to wait for a manifest. Required: every caller sizes its interception window consciously to outlive the phases it
+ *   observes, so no production caller relies on a shared default. Acts as a safety net if finalize() is never called.
+ * @param observeFactory - The HLS playlist observer factory (default observeHlsPlaylists); injectable so the selection state machine can run without a live browser.
+ * @returns The interceptor handle, or null if the observer could not be installed.
  */
-export async function installManifestInterceptor(page, timeout = INTERCEPTION_TIMEOUT) {
+export async function installManifestInterceptor(page, timeout, observeFactory = observeHlsPlaylists) {
     const elapsed = startTimer();
-    // Track first/latest URLs separately per playlist kind. Master URLs take precedence at selection time because masters carry richer metadata. For direct
-    // tunes, the first URL of the higher-priority kind wins; for guide tunes, the latest URL of the higher-priority kind wins. Without separate per-kind
-    // tracking, a master-based site whose player happens to also load a media playlist for a different channel would risk picking the wrong one.
-    let firstMasterUrl = null;
-    let latestMasterUrl = null;
-    let firstMediaUrl = null;
-    let latestMediaUrl = null;
+    // Track the first and latest observation per kind, plus the epoch fence. Slot updates are guarded by wire-arrival order, not delivery order: the first slot
+    // holds the lowest-ordinal arrival and the latest facts hold the highest, so a body fetch that resolves out of order still records arrival truth. Under
+    // in-order delivery this is byte-for-byte the earliest/most-recent behavior. manifestCount stays purely diagnostic for the log lines.
+    let firstMaster = null;
+    let firstMedia = null;
+    let latestMaster = null;
+    let latestMedia = null;
+    let markOrdinal = null;
     let resolved = false;
     let manifestCount = 0;
     const { promise, resolve } = Promise.withResolvers();
-    const observer = await startManifestObserver(page, (url, kind) => {
-        manifestCount++;
-        if (kind === "master") {
-            firstMasterUrl ??= url;
-            latestMasterUrl = url;
-        }
-        else if (kind === "media") {
-            firstMediaUrl ??= url;
-            latestMediaUrl = url;
+    const observer = await observeFactory(page, {
+        logCategory: "native:intercept",
+        onPlaylist: (playlist) => {
+            manifestCount++;
+            if (playlist.kind === "master") {
+                // First slot: the lowest ordinal wins, so a late delivery of an even-earlier arrival corrects it.
+                if ((firstMaster === null) || (playlist.sequence < firstMaster.ordinal)) {
+                    firstMaster = { ordinal: playlist.sequence, url: playlist.url };
+                }
+                // Latest slot: the highest ordinal wins, so a late delivery of a lower arrival never displaces it.
+                if ((latestMaster === null) || (playlist.sequence > latestMaster.ordinal)) {
+                    latestMaster = { childUrls: playlist.childUrls, ordinal: playlist.sequence, url: playlist.url };
+                }
+            }
+            else {
+                if ((firstMedia === null) || (playlist.sequence < firstMedia.ordinal)) {
+                    firstMedia = { ordinal: playlist.sequence, url: playlist.url };
+                }
+                if ((latestMedia === null) || (playlist.sequence > latestMedia.ordinal)) {
+                    latestMedia = { live: playlist.live, ordinal: playlist.sequence, url: playlist.url };
+                }
+            }
+            LOG.debug("native:intercept", "%s playlist captured (#%s, seq %s) in %sms: %s.", playlist.kind, manifestCount, playlist.sequence, elapsed(), playlist.url.slice(0, 120));
         }
-        LOG.debug("native:intercept", "%s playlist captured (#%s) in %sms: %s.", kind, manifestCount, elapsed(), url.slice(0, 120));
-    }, "native:intercept");
+    });
     if (!observer) {
         return null;
     }
-    // Selects the URL appropriate for the resolution mode by delegating to the pure selectInterceptedManifest() helper. Closure variables are passed by value so
-    // the helper does not depend on shared mutable state.
-    const selectUrl = (directTune) => selectInterceptedManifest({
+    // Builds the selection state from the closure locals. epochFree forces markOrdinal to null so the timeout path resolves without the epoch rule, which must
+    // never engage on a path a direct tune can reach.
+    const buildState = (directTune, epochFree) => ({
         directTune,
-        firstMasterUrl,
-        firstMediaUrl,
-        latestMasterUrl,
-        latestMediaUrl
+        firstMasterUrl: firstMaster?.url ?? null,
+        firstMediaUrl: firstMedia?.url ?? null,
+        latestMaster,
+        latestMedia,
+        markOrdinal: epochFree ? null : markOrdinal
     });
-    // Timeout guard. If finalize() is never called (defensive), resolve with whatever we have after the timeout.
-    const timer = setTimeout(() => {
+    // Centralized resolution helper. Used by the timeout, finalize, and dispose paths to settle the promise exactly once and tear down the observer regardless of
+    // which path won. The selection honors the direct-vs-guide semantics and, for guide tunes, the epoch/membership/liveness rule via selectInterceptedManifest.
+    const settle = (options) => {
+        const { directTune, epochFree = false, reason } = options;
         if (resolved) {
             return;
         }
         resolved = true;
-        // The timeout path mirrors the latest-URL semantics of a guide tune; if no finalize() ever arrived we err on the side of the most recent capture.
-        const selected = selectUrl(false);
-        if (selected) {
-            LOG.debug("native:intercept", "Manifest interception timed out after %sms. Resolving with latest URL (%s captured).", elapsed(), manifestCount);
-            observer.dispose(true);
-            resolve({ cdpSession: observer.cdpSession, masterManifestUrl: selected });
+        clearTimeout(timer);
+        const selection = selectInterceptedManifest(buildState(directTune, epochFree));
+        if (selection) {
+            LOG.debug("native:intercept", "Interception %s in %sms with %s capture(s). Using %s %s: %s.", reason, elapsed(), manifestCount, directTune ? "first" : "latest", selection.kind, selection.url.slice(0, 120));
+            observer.dispose();
+            resolve({ manifestUrl: selection.url, selectedKind: selection.kind });
         }
         else {
-            LOG.debug("native:intercept", "Manifest interception timed out after %sms. No HLS playlist captured.", elapsed());
-            observer.dispose(false);
+            LOG.debug("native:intercept", "Interception %s in %sms but no HLS playlist was captured.", reason, elapsed());
+            observer.dispose();
             resolve(null);
         }
-    }, timeout);
+    };
+    // Timeout guard. If finalize() is never called (defensive), settle epoch-free after the timeout: the timeout cannot know the tune kind, and the epoch rule must
+    // never engage on a path a direct tune can reach, so it resolves with the categorical master-preferred outcome. With the interception budget sized by the
+    // caller to outlive the tune (streaming/setup.ts), this path is last-resort defense rather than a routine finish.
+    const timer = setTimeout(() => { settle({ directTune: false, epochFree: true, reason: "timed out" }); }, timeout);
     // Finalize function exposed on the returned handle. Called by the stream setup code after channel selection is complete. The resolution strategy depends on
     // two factors: whether a qualifying manifest has already been captured, and whether the tune is direct or guide-based.
     //
-    // - Manifest captured + direct tune: resolve immediately (A&E, most TVE sites - manifest arrived during page load).
+    // - Master manifest captured + direct tune: settle immediately (A&E, most TVE sites - manifest arrived during page load).
     // - Manifest captured + guide tune: wait FINALIZE_SETTLE_DELAY (Fox guide, Hulu - a newer manifest from the channel switch may still arrive).
     // - No manifest captured + either: wait FINALIZE_SETTLE_DELAY (Fox Sports - manifest fetch starts after video element appears, hasn't arrived yet).
     const finalize = (directTune) => {
         if (resolved) {
             return;
         }
-        // Helper that resolves the promise with the current state. The selectUrl helper applies the master-first priority and the directTune first/latest semantics.
-        const resolveNow = () => {
-            if (resolved) {
-                return;
-            }
-            resolved = true;
-            clearTimeout(timer);
-            const selectedUrl = selectUrl(directTune);
-            if (selectedUrl) {
-                LOG.debug("native:intercept", "Interception finalized in %sms with %s playlist capture(s). Using %s: %s.", elapsed(), manifestCount, directTune ? "first" : "latest", selectedUrl.slice(0, 120));
-                observer.dispose(true);
-                resolve({ cdpSession: observer.cdpSession, masterManifestUrl: selectedUrl });
-            }
-            else {
-                LOG.debug("native:intercept", "Interception finalized in %sms but no HLS playlist was captured.", elapsed());
-                observer.dispose(false);
-                resolve(null);
-            }
-        };
-        // For direct tunes, resolve immediately if a master URL has already arrived. We do not short-circuit on a media-only first URL because a master may still
-        // be in flight - waiting the settle delay gives master priority a chance to take effect. Once the settle elapses we resolve with whichever URL ranks
-        // highest under selectUrl.
-        if (directTune && firstMasterUrl) {
-            resolveNow();
+        // For direct tunes, settle immediately if a master URL has already arrived. We do not short-circuit on a media-only first URL because a master may still
+        // be in flight - waiting the settle delay gives the master-first preference a chance to take effect.
+        if (directTune && (firstMaster !== null)) {
+            settle({ directTune: true, reason: "finalized" });
         }
         else {
-            setTimeout(resolveNow, FINALIZE_SETTLE_DELAY);
+            setTimeout(() => { settle({ directTune, reason: "finalized" }); }, FINALIZE_SETTLE_DELAY);
+        }
+    };
+    // Stamps the observation epoch at which channel selection begins by fencing the observer's current wire sequence. Observations after the stamp answer the
+    // click; guide-tune selection prefers a master observed after this point. Callable again - the latest stamp wins - and a no-op once the interception has
+    // resolved, matching the finalize and dispose guard idiom.
+    const markChannelSelectionStart = () => {
+        if (resolved) {
+            return;
+        }
+        markOrdinal = observer.currentSequence();
+        LOG.debug("native:intercept", "Channel selection epoch stamped at wire sequence %s.", markOrdinal);
+    };
+    // Explicit dispose path for "using" syntax or caller-driven cancellation. Safe to call more than once. Resolves the promise with null if it has not already
+    // settled, so callers awaiting the promise are never left hanging on a disposed observer.
+    const dispose = () => {
+        if (resolved) {
+            return;
         }
+        resolved = true;
+        clearTimeout(timer);
+        LOG.debug("native:intercept", "Interception disposed in %sms with %s capture(s) and no resolution selected.", elapsed(), manifestCount);
+        observer.dispose();
+        resolve(null);
     };
-    return { finalize, promise };
+    return { dispose, finalize, markChannelSelectionStart, promise, [Symbol.dispose]: dispose };
 }
 /**
- * Awaits the first master HLS manifest URL whose URL satisfies the supplied predicate. Used by tune-verification paths where the caller has just clicked or
+ * Awaits the first master HLS manifest whose URL satisfies the supplied predicate. Used by tune-verification paths where the caller has just clicked or
  * navigated to a target channel and wants to confirm the resulting stream belongs to that channel rather than to whatever default the page was previously
  * showing.
  *
- * Resolves with the matching URL on success. Resolves with null if no matching manifest arrives within the timeout. The CDP session is torn down automatically
- * in both cases - the verification path does not hand off the session to a downstream consumer.
- * @param page - The Puppeteer page to monitor.
+ * Resolves with the matching URL on success. Resolves with null if no matching manifest arrives within the timeout. The underlying observer is torn down
+ * automatically in both cases - the verification path does not hand off a session to a downstream consumer.
+ *
+ * @param page - The puppeteer page to monitor.
  * @param predicate - Test applied to each verified master manifest URL. Return true to accept the URL and resolve.
  * @param timeout - Maximum time in milliseconds to wait for a matching manifest.
+ * @param observeFactory - The HLS playlist observer factory (default observeHlsPlaylists); injectable so the verification state machine can run without a live browser.
  * @returns The matching URL, or null on timeout.
  */
-export async function awaitMatchingManifest(page, predicate, timeout = VERIFICATION_TIMEOUT) {
+export async function awaitMatchingManifest(page, predicate, timeout = VERIFICATION_TIMEOUT, observeFactory = observeHlsPlaylists) {
     const elapsed = startTimer();
     let resolved = false;
     const { promise, resolve } = Promise.withResolvers();
     // Tune verification is a multi-channel concept that only applies to master playlists - direct-tune media-only sources do not run a guide-click verification
     // step because the page navigation itself selects the channel. We reject media playlists at the consumer level rather than asking the observer to filter so
     // the observer keeps a single canonical contract (forward all recognized HLS playlists with their kind).
-    const observer = await startManifestObserver(page, (url, kind) => {
-        if (resolved) {
-            return;
-        }
-        if (kind !== "master") {
-            LOG.debug("native:intercept", "Tune verification ignoring non-master playlist (%s).", kind);
-            return;
-        }
-        if (predicate(url)) {
-            resolved = true;
-            LOG.debug("native:intercept", "Matching manifest found in %sms: %s.", elapsed(), url.slice(0, 120));
-            observer?.dispose(false);
-            clearTimeout(timer);
-            resolve(url);
-        }
-        else {
-            LOG.debug("native:intercept", "Master manifest did not match predicate: %s.", url.slice(0, 120));
+    const observer = await observeFactory(page, {
+        logCategory: "native:intercept",
+        onPlaylist: (playlist) => {
+            if (resolved) {
+                return;
+            }
+            if (playlist.kind !== "master") {
+                LOG.debug("native:intercept", "Tune verification ignoring non-master playlist (%s).", playlist.kind);
+                return;
+            }
+            if (predicate(playlist.url)) {
+                resolved = true;
+                LOG.debug("native:intercept", "Matching manifest found in %sms: %s.", elapsed(), playlist.url.slice(0, 120));
+                observer?.dispose();
+                clearTimeout(timer);
+                resolve(playlist.url);
+            }
+            else {
+                LOG.debug("native:intercept", "Master manifest did not match predicate: %s.", playlist.url.slice(0, 120));
+            }
         }
-    }, "native:intercept");
+    });
     if (!observer) {
         return null;
     }
@@ -299,25 +297,9 @@ export async function awaitMatchingManifest(page, predicate, timeout = VERIFICAT
         }
         resolved = true;
         LOG.debug("native:intercept", "Awaiting matching manifest timed out after %sms.", elapsed());
-        observer.dispose(false);
+        observer.dispose();
         resolve(null);
     }, timeout);
     return promise;
 }
-/**
- * Removes the Network domain listener and detaches the CDP session. Safe to call multiple times or on an already-detached session. Public so that native HLS
- * consumers (which receive the CDP session through ManifestInterceptionResult) can clean up after token-refresh handoffs and proxy shutdown.
- * @param cdpSession - The CDP session to clean up.
- */
-export function removeManifestInterceptor(cdpSession) {
-    try {
-        cdpSession.removeAllListeners("Network.responseReceived");
-        void cdpSession.send("Network.disable").catch(() => { });
-        void cdpSession.detach().catch(() => { });
-    }
-    catch (_error) {
-        // Ignore errors during cleanup - the session may already be detached.
-    }
-    LOG.debug("native:intercept", "CDP manifest interceptor removed.");
-}
 //# sourceMappingURL=manifestInterceptor.js.map