prismcast 1.10.2 → 1.11.0

package/dist/browser/manifestInterceptor.d.ts

@@ -1,77 +1,130 @@
-import type { CDPSession, Page } from "puppeteer-core";
 import type { Nullable } from "../types/index.ts";
+import type { Page } from "puppeteer-core";
+import type { RecognizedHlsPlaylistKind } from "../native/probe.ts";
+import { observeHlsPlaylists } from "./hlsPlaylistObserver.ts";
+export declare const FINALIZE_SETTLE_DELAY = 1500;
 /**
- * Captured-URL state used by selectInterceptedManifest() to choose the playlist URL appropriate for a given resolution mode. Modeled as a plain record so the
- * selection logic is testable in isolation from the CDP listener that maintains the underlying state.
+ * A master playlist observation reduced to the facts selection needs: the declared child playlist URLs (for membership judgment), the wire-arrival ordinal, and
+ * the URL. Modeled as a record so a URL can never exist without its ordinal - the null-consistency question separate parallel locals would raise is
+ * unrepresentable.
+ */
+export interface InterceptedMasterFact {
+    readonly childUrls: readonly string[];
+    readonly ordinal: number;
+    readonly url: string;
+}
+/**
+ * A media playlist observation reduced to the facts selection needs: its liveness, the wire-arrival ordinal, and the URL. Modeled as a record so a URL can never
+ * exist without its ordinal.
+ */
+export interface InterceptedMediaFact {
+    readonly live: boolean;
+    readonly ordinal: number;
+    readonly url: string;
+}
+/**
+ * Captured state used by selectInterceptedManifest() to choose the playlist appropriate for a given resolution mode. Modeled as a plain record so the selection
+ * logic is testable in isolation from the network plumbing that maintains the underlying state. Every judgment - including the pathname normalization membership
+ * relies on - lives in the selection function; this record carries only facts.
  */
 export interface InterceptedManifestState {
-    directTune: boolean;
-    firstMasterUrl: Nullable<string>;
-    firstMediaUrl: Nullable<string>;
-    latestMasterUrl: Nullable<string>;
-    latestMediaUrl: Nullable<string>;
+    readonly directTune: boolean;
+    readonly firstMasterUrl: Nullable<string>;
+    readonly firstMediaUrl: Nullable<string>;
+    readonly latestMaster: Nullable<InterceptedMasterFact>;
+    readonly latestMedia: Nullable<InterceptedMediaFact>;
+    readonly markOrdinal: Nullable<number>;
+}
+/**
+ * The outcome of selectInterceptedManifest(): the chosen URL and the kind selection decided it is. The kind is reported alongside the URL so no caller re-derives
+ * it by comparing URLs, which would be fragile when the same URL could sit in both the master and media records.
+ */
+export interface SelectedManifest {
+    readonly kind: RecognizedHlsPlaylistKind;
+    readonly url: string;
 }
 /**
- * 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.
+ * Selects the playlist appropriate for a given resolution mode from the captured state, reporting the URL together with the kind selection decided.
+ *
+ * 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.
  *
- * Pure function exported for unit testing; the closure inside installManifestInterceptor() consumes it through the same shape.
+ * 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-URL state at resolution time.
- * @returns The selected URL, or null when no URL matches the resolution mode.
+ * @param state - The captured state at resolution time.
+ * @returns The selected playlist, or null when no URL matches the resolution mode.
  */
-export declare function selectInterceptedManifest(state: InterceptedManifestState): Nullable<string>;
+export declare function selectInterceptedManifest(state: InterceptedManifestState): Nullable<SelectedManifest>;
 /**
- * Result of manifest interception containing the CDP session for reuse during token refresh and the playlist URL the probe will consume. The URL may be either
- * a master or a media playlist; the probe normalizes both kinds into a MediaFeed so downstream code does not branch.
+ * Result of manifest interception. The URL may be either a master or a media playlist; selectedKind reports which selection chose, and the probe normalizes both
+ * kinds into a MediaFeed so downstream code does not branch on which kind originally arrived. The underlying observer and its CDP sessions are owned and disposed
+ * internally - callers do not hold session references.
  */
 export interface ManifestInterceptionResult {
-    cdpSession: CDPSession;
-    masterManifestUrl: string;
+    readonly manifestUrl: string;
+    readonly selectedKind: RecognizedHlsPlaylistKind;
 }
 /**
- * Handle returned by installManifestInterceptor. Provides the interception promise and a finalize function to signal that channel selection is complete.
+ * Handle returned by installManifestInterceptor. Provides the interception promise, a finalize function to signal that channel selection is complete, an epoch
+ * stamp marking when channel selection begins, and an explicit dispose path. Implements TC39 Symbol.dispose so callers may use the "using" keyword for
+ * scope-bound cleanup, including on thrown errors.
  */
-export interface ManifestInterceptorHandle {
-    finalize: (directTune: boolean) => void;
-    promise: Promise<Nullable<ManifestInterceptionResult>>;
+export interface ManifestInterceptorHandle extends Disposable {
+    readonly dispose: () => void;
+    readonly finalize: (directTune: boolean) => void;
+    readonly markChannelSelectionStart: () => void;
+    readonly promise: Promise<Nullable<ManifestInterceptionResult>>;
+    readonly [Symbol.dispose]: () => void;
 }
 /**
- * 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 (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.
+ * - 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.
  *
- * 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.
+ * 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.
+ *
+ * @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 declare function installManifestInterceptor(page: Page, timeout?: number): Promise<Nullable<ManifestInterceptorHandle>>;
+export declare function installManifestInterceptor(page: Page, timeout: number, observeFactory?: typeof observeHlsPlaylists): Promise<Nullable<ManifestInterceptorHandle>>;
 /**
- * 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 declare function awaitMatchingManifest(page: Page, predicate: (url: string) => boolean, timeout?: number): Promise<Nullable<string>>;
-/**
- * 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 declare function removeManifestInterceptor(cdpSession: CDPSession): void;
+export declare function awaitMatchingManifest(page: Page, predicate: (url: string) => boolean, timeout?: number, observeFactory?: typeof observeHlsPlaylists): Promise<Nullable<string>>;
+//# sourceMappingURL=manifestInterceptor.d.ts.map

package/dist/browser/manifestInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestInterceptor.d.ts","sourceRoot":"","sources":["../../src/browser/manifestInterceptor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AA6B/D,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAK1C;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IAIpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAGtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IAGnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAGvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IAGvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAG7B,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAG1C,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAGzC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAGvD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IAIrD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAG/B,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IAGzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAmCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,wBAAwB,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAuCrG;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IAIzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAG7B,QAAQ,CAAC,YAAY,EAAE,yBAAyB,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,UAAU;IAI3D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;IAM7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,IAAI,CAAC;IAKjD,QAAQ,CAAC,yBAAyB,EAAE,MAAM,IAAI,CAAC;IAI/C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAGhE,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACvC;AA6BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAC1E,cAAc,GAAE,OAAO,mBAAyC,GAAG,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC,CAoKhH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACzF,OAAO,GAAE,MAA6B,EAAE,cAAc,GAAE,OAAO,mBAAyC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CA8DrI"}