prismcast 1.4.1 → 1.5.0

package/dist/types/index.d.ts

@@ -1,406 +1,7 @@
-import type { Frame, Page } from "puppeteer-core";
-import type { RecoveryMetrics } from "../streaming/monitor.js";
-/**
- * A utility type that represents a value that can be null.
- * @typeParam T - The type that can be nullable.
- */
-export type Nullable<T> = T | null;
-/**
- * Browser-related configuration controlling Chrome launch behavior. Viewport dimensions are derived from the quality preset via getViewport() and are not stored in
- * this configuration object.
- */
-export interface BrowserConfig {
-    executablePath: Nullable<string>;
-    initTimeout: number;
-}
-/**
- * Filesystem paths for Chrome profile data and extension files.
- */
-export interface PathsConfig {
-    chromeDataDir: Nullable<string>;
-    chromeProfileName: string;
-    extensionDirName: string;
-    logFile: Nullable<string>;
-}
-/**
- * Playback monitoring and recovery timing configuration. These values control how quickly the system detects playback problems and how aggressively it attempts
- * recovery. The defaults balance responsiveness against false positives from temporary buffering.
- */
-export interface PlaybackConfig {
-    bufferingGracePeriod: number;
-    channelSelectorDelay: number;
-    channelSwitchDelay: number;
-    clickToPlayDelay: number;
-    iframeInitDelay: number;
-    maxPageReloads: number;
-    monitorInterval: number;
-    pageReloadWindow: number;
-    sourceReloadDelay: number;
-    stallCountThreshold: number;
-    stallThreshold: number;
-    sustainedPlaybackRequired: number;
-}
-/**
- * Recovery behavior configuration controlling retry logic, backoff timing, and circuit breaker thresholds. These settings determine how the system handles
- * failures and prevents runaway resource consumption from broken streams.
- */
-export interface RecoveryConfig {
-    backoffJitter: number;
-    circuitBreakerThreshold: number;
-    circuitBreakerWindow: number;
-    maxBackoffDelay: number;
-    stalePageCleanupInterval: number;
-    stalePageGracePeriod: number;
-}
-/**
- * HLS streaming configuration controlling segment generation and lifecycle.
- */
-export interface HLSConfig {
-    idleTimeout: number;
-    maxSegments: number;
-    segmentDuration: number;
-}
-/**
- * Channels configuration controlling which predefined channels are enabled.
- */
-export interface ChannelsConfig {
-    disabledPredefined: string[];
-    enabledProviders: string[];
-}
-/**
- * HDHomeRun emulation configuration. When enabled, PrismCast runs a separate HTTP server that emulates the HDHomeRun API, allowing Plex to discover and use
- * PrismCast as a virtual tuner for live TV and DVR recording. The emulated device appears in Plex's tuner setup and serves PrismCast's HLS streams directly.
- */
-export interface HdhrConfig {
-    deviceId: string;
-    enabled: boolean;
-    friendlyName: string;
-    port: number;
-}
-/**
- * Logging configuration controlling file-based logging behavior.
- */
-export interface LoggingConfig {
-    debugFilter: string;
-    httpLogLevel: "all" | "errors" | "filtered" | "none";
-    maxSize: number;
-}
-/**
- * HTTP server configuration controlling network binding.
- */
-export interface ServerConfig {
-    host: string;
-    port: number;
-}
-/**
- * Capture mode for media recording. Determines how video/audio is captured from the browser and processed for HLS output.
- * - "ffmpeg": Captures WebM (H264+Opus) and uses FFmpeg to transcode audio to AAC. More stable for long recordings.
- * - "native": Captures fMP4 (H264+AAC) directly from Chrome. No dependencies but may be unstable with long recordings.
- */
-export type CaptureMode = "ffmpeg" | "native";
-/**
- * Media streaming configuration controlling video capture quality, timeouts, and concurrency limits.
- */
-export interface StreamingConfig {
-    audioBitsPerSecond: number;
-    captureMode: CaptureMode;
-    frameRate: number;
-    maxConcurrentStreams: number;
-    maxNavigationRetries: number;
-    navigationTimeout: number;
-    qualityPreset: string;
-    videoBitsPerSecond: number;
-    videoTimeout: number;
-}
-/**
- * Root configuration object containing all application settings organized by functional area.
- */
-export interface Config {
-    browser: BrowserConfig;
-    channels: ChannelsConfig;
-    hdhr: HdhrConfig;
-    hls: HLSConfig;
-    logging: LoggingConfig;
-    paths: PathsConfig;
-    playback: PlaybackConfig;
-    recovery: RecoveryConfig;
-    server: ServerConfig;
-    streaming: StreamingConfig;
-}
-/**
- * UI category for profile grouping in dropdowns and reference documentation. Profiles are grouped by their fullscreen mechanism and special characteristics.
- * - "api": Profiles using the JavaScript fullscreen API (including embedded iframe and click-to-play variants).
- * - "keyboard": Profiles using keyboard shortcuts (typically the 'f' key) for fullscreen.
- * - "multiChannel": Multi-channel profiles requiring a channel selector for tile or thumbnail-based channel selection.
- * - "special": Special-purpose profiles like static page capture.
- */
-export type ProfileCategory = "api" | "keyboard" | "multiChannel" | "special";
-/**
- * Site profile definition with optional flags. All flags are optional because profiles can inherit from other profiles, and only the flags that differ from the
- * parent need to be specified. The DEFAULT_SITE_PROFILE provides baseline values for any flags not set through inheritance.
- */
-export interface SiteProfile {
-    category?: ProfileCategory;
-    channelSelection?: ChannelSelectionConfig;
-    channelSelector?: Nullable<string>;
-    clickSelector?: Nullable<string>;
-    clickToPlay?: boolean;
-    description?: string;
-    extends?: string;
-    summary?: string;
-    fullscreenKey?: Nullable<string>;
-    fullscreenSelector?: Nullable<string>;
-    hideSelector?: Nullable<string>;
-    lockVolumeProperties?: boolean;
-    needsIframeHandling?: boolean;
-    noVideo?: boolean;
-    selectReadyVideo?: boolean;
-    useRequestFullscreen?: boolean;
-    waitForNetworkIdle?: boolean;
-}
-/**
- * Fully-resolved site profile with all flags having concrete values. After resolving inheritance chains and applying defaults, every flag has a definite boolean
- * or string value. This interface is used by stream handling code that needs to check profile flags without worrying about undefined values.
- */
-export interface ResolvedSiteProfile {
-    channelSelection: ChannelSelectionConfig;
-    channelSelector: Nullable<string>;
-    clickSelector: Nullable<string>;
-    clickToPlay: boolean;
-    fullscreenKey: Nullable<string>;
-    fullscreenSelector: Nullable<string>;
-    hideSelector: Nullable<string>;
-    lockVolumeProperties: boolean;
-    maxContinuousPlayback: Nullable<number>;
-    needsIframeHandling: boolean;
-    noVideo: boolean;
-    selectReadyVideo: boolean;
-    useRequestFullscreen: boolean;
-    waitForNetworkIdle: boolean;
-}
-/**
- * Result of resolving a site profile. Includes both the resolved profile configuration and the name of the profile that was matched. The name indicates whether the
- * profile came from a channel hint, domain-based autodetection, or the default fallback.
- */
-export interface ProfileResolutionResult {
-    profile: ResolvedSiteProfile;
-    profileName: string;
-}
-/**
- * Channel definition mapping a short name to a streaming URL with optional configuration overrides.
- */
-export interface Channel {
-    channelNumber?: number;
-    channelSelector?: string;
-    name?: string;
-    profile?: string;
-    provider?: string;
-    stationId?: string;
-    url: string;
-}
-/**
- * Enriched channel entry returned by getChannelListing(). Wraps a Channel definition with source classification and enabled status metadata, providing the
- * single source of truth for merged channel data across the codebase.
- */
-export interface ChannelListingEntry {
-    availableByProvider: boolean;
-    channel: Channel;
-    enabled: boolean;
-    key: string;
-    source: "override" | "predefined" | "user";
-}
-/**
- * Map of channel short names to channel definitions. Channel names must be URL-safe strings (lowercase letters, numbers, hyphens) since they appear in stream
- * request URLs.
- */
-export type ChannelMap = Record<string, Channel>;
-/**
- * Represents a group of provider variants for the same content. Used by the UI to display provider selection dropdowns for multi-provider channels.
- */
-export interface ProviderGroup {
-    canonicalKey: string;
-    variants: {
-        key: string;
-        label: string;
-    }[];
-}
-/**
- * Information about an active streaming session. Created when a stream request is received and deleted when the stream ends.
- */
-export interface StreamInfo {
-    channelName: Nullable<string>;
-    id: number;
-    page: Page;
-    startTime: Date;
-    stopMonitor: Nullable<() => RecoveryMetrics>;
-    url: string;
-}
-/**
- * Snapshot of a video element's playback state. Collected by the playback health monitor to detect stalls, errors, and other problems.
- */
-export interface VideoState {
-    currentTime: number;
-    ended: boolean;
-    error: boolean;
-    muted: boolean;
-    networkState: number;
-    paused: boolean;
-    readyState: number;
-    time: number;
-    volume: number;
-}
-/**
- * Strategy for selecting a video element when multiple are present. "selectFirstVideo" takes the first video in DOM order; "selectReadyVideo" finds the video
- * with readyState >= 3, which typically identifies the actively playing main content rather than preloaded ads.
- */
-export type VideoSelectorType = "selectFirstVideo" | "selectReadyVideo";
-/**
- * Result of URL validation indicating whether the URL is safe to navigate to.
- */
-export interface UrlValidationResult {
-    reason?: string;
-    valid: boolean;
-}
-/**
- * Alias for UrlValidationResult maintained for backward compatibility with existing code.
- */
-export type UrlValidation = UrlValidationResult;
-/**
- * Health check response structure returned by the /health endpoint.
- */
-export interface HealthStatus {
-    browser: {
-        connected: boolean;
-        pageCount: number;
-    };
-    captureMode: string;
-    chrome: Nullable<string>;
-    clients: {
-        byType: {
-            count: number;
-            type: string;
-        }[];
-        total: number;
-    };
-    ffmpegAvailable: boolean;
-    memory: {
-        heapTotal: number;
-        heapUsed: number;
-        rss: number;
-        segmentBuffers: number;
-    };
-    message?: string;
-    status: "degraded" | "healthy" | "unhealthy";
-    streams: {
-        active: number;
-        limit: number;
-    };
-    timestamp: string;
-    uptime: number;
-    version: string;
-}
-/**
- * Information about a single active stream as returned by the /streams endpoint.
- */
-export interface StreamListItem {
-    channel: Nullable<string>;
-    duration: number;
-    id: number;
-    startTime: string;
-    url: string;
-}
-/**
- * Response structure for the /streams endpoint.
- */
-export interface StreamListResponse {
-    count: number;
-    limit: number;
-    streams: StreamListItem[];
-}
-/**
- * Available channel selection strategies. Each strategy implements a different approach to finding and selecting channels in a multi-channel player UI.
- *
- * - "foxGrid": Find channel by station code in a non-virtualized guide grid, click the channel logo button via DOM .click(). Used by Fox.com.
- * - "guideGrid": Find channel by exact-matching image alt text, click nearest clickable ancestor. Optionally clicks a tab to reveal the list first. Used by Hulu
- *   Live TV.
- * - "hboGrid": Discover the HBO tab page URL from the homepage menu bar, scrape the live channel tile rail for a matching channel name, and navigate to the watch
- *   URL. Caches the tab URL across tunes with stale-cache fallback. Used by HBO Max.
- * - "none": No channel selection needed (single-channel sites). This is the default.
- * - "slingGrid": Find channel by data-testid in a virtualized A-Z guide grid, scroll via binary search on .guide-cell scrollTop, click the on-now program
- *   cell. Used by Sling TV.
- * - "thumbnailRow": Find channel element using the profile's matchSelector (defaults to image URL matching), click adjacent element on the same row. Used by
- *   USA Network.
- * - "tileClick": Find channel element using the profile's matchSelector (defaults to image URL matching), click tile, then optionally click play button if
- *   playSelector is configured. Used by Disney+.
- * - "youtubeGrid": Find channel by aria-label in a non-virtualized EPG grid, extract the watch URL, and navigate directly. Used by YouTube TV.
- */
-export type ChannelSelectionStrategy = "foxGrid" | "guideGrid" | "hboGrid" | "none" | "slingGrid" | "thumbnailRow" | "tileClick" | "youtubeGrid";
-/**
- * Configuration for channel selection behavior within a site profile.
- */
-export interface ChannelSelectionConfig {
-    listSelector?: string;
-    matchSelector?: string;
-    playSelector?: string;
-    strategy: ChannelSelectionStrategy;
-}
-export interface ChannelSelectionProfile extends ResolvedSiteProfile {
-    channelSelector: string;
-}
-export declare function isChannelSelectionProfile(profile: ResolvedSiteProfile): profile is ChannelSelectionProfile;
-/**
- * Result of attempting to select a channel from a multi-channel player UI.
- */
-export interface ChannelSelectorResult {
-    reason?: string;
-    success: boolean;
-}
-/**
- * The strategy function signature. All strategies take the Puppeteer page and a narrowed profile with guaranteed non-null channelSelector.
- */
-export type ChannelStrategyHandler = (page: Page, profile: ChannelSelectionProfile) => Promise<ChannelSelectorResult>;
-/**
- * The complete contract for a channel selection strategy. Each provider file exports a single object implementing this interface. The coordinator accesses all
- * provider behavior through these hooks — no strategy-specific imports or hardcoded strategy name checks outside the registry.
- */
-export interface ChannelStrategyEntry {
-    /**
-     * Resets all module-level caches (row positions, discovered URLs, watch URLs). Called on browser restart when cached state may be stale.
-     */
-    clearCache?: () => void;
-    /**
-     * Selects the target channel in the provider's guide UI. Receives a Puppeteer page and a profile with a guaranteed non-null channelSelector. Must handle its
-     * own retry logic (e.g., overlay dismiss) and return a result indicating success or failure with a diagnostic reason.
-     */
-    execute: ChannelStrategyHandler;
-    /**
-     * Removes a cached watch URL after it failed to produce a working stream. Called by the coordinator when a cached direct navigation fails.
-     */
-    invalidateDirectUrl?: (channelSelector: string) => void;
-    /**
-     * Returns a watch URL for direct navigation, bypassing guide page loading. Implementations may perform async work such as fetching current asset IDs from
-     * provider APIs. The page parameter allows setting up response interception or accessing browser context when needed (e.g., cold cache setup).
-     */
-    resolveDirectUrl?: (channelSelector: string, page: Page) => Promise<Nullable<string>>;
-}
-/**
- * Coordinates for a click target, used when clicking channel selector elements.
- */
-export interface ClickTarget {
-    x: number;
-    y: number;
-}
-/**
- * Result of tuning to a channel, containing the video context needed for monitoring.
- */
-export interface TuneResult {
-    context: Frame | Page;
-}
-/**
- * Browser chrome dimensions (toolbars, borders) calculated by comparing window.outerHeight/Width to window.innerHeight/Width. Used to set window size such that
- * the viewport (content area) matches our target dimensions.
- */
-export interface UiSize {
-    height: number;
-    width: number;
-}
+export type { BrowserConfig, CaptureMode, ChannelsConfig, Config, HdhrConfig, HLSConfig, LoggingConfig, PathsConfig, PlaybackConfig, RecoveryConfig, ServerConfig, StreamingConfig } from "./config.js";
+export type { Channel, ChannelDelta, ChannelListingEntry, ChannelMap, ProviderGroup, StoredChannel, StoredChannelMap } from "./channels.js";
+export type { ChannelSelectionConfig, ChannelSelectionStrategy, DomainConfig, ProfileCategory, ProfileResolutionResult, ProfilesValidationResult, ProviderPack, ResolvedSiteProfile, SiteProfile, UserProfilesFile, UserProfilesLoadResult } from "./profiles.js";
+export type { ChannelSelectionProfile, ChannelSelectorResult, ChannelStrategyEntry, ChannelStrategyHandler, ClickTarget, DiscoveredChannel, ProviderModule, TuneResult, UiSize } from "./selection.js";
+export type { ChannelSortField, Nullable, SortDirection } from "./shared.js";
+export type { HealthStatus, StreamInfo, StreamListItem, StreamListResponse, UrlValidation, UrlValidationResult, VideoSelectorType, VideoState } from "./streaming.js";
+export { isChannelSelectionProfile } from "./selection.js";

package/dist/types/index.js

@@ -1,6 +1,2 @@
-// Type guard that proves channelSelector is a non-empty string. Matches the original !channelSelector truthiness check, which rejects both null and empty string.
-// Used by the coordinator before dispatching to strategy functions.
-export function isChannelSelectionProfile(profile) {
-    return (profile.channelSelector !== null) && (profile.channelSelector.length > 0);
-}
+export { isChannelSelectionProfile } from "./selection.js";
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAm1BA,kKAAkK;AAClK,oEAAoE;AACpE,MAAM,UAAU,yBAAyB,CAAC,OAA4B;IAEpE,OAAO,CAAC,OAAO,CAAC,eAAe,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/profiles.d.ts

@@ -0,0 +1,141 @@
+import type { ChannelMap } from "./channels.js";
+import type { Nullable } from "./shared.js";
+/**
+ * Available channel selection strategies. Each strategy implements a different approach to finding and selecting channels in a multi-channel player UI.
+ *
+ * - "directvGrid": Tune via webpack injection — captures __webpack_require__, extracts the Redux store from the React fiber tree, matches by channel name, and
+ *   dispatches playConsumable. Falls back to logo aria-label click when the interceptor fails. Used by DirecTV Stream.
+ * - "foxGrid": Find channel by station code in a non-virtualized guide grid, click the channel logo button via DOM .click(). Used by Fox.com.
+ * - "guideGrid": Find channel by exact-matching image alt text, click nearest clickable ancestor. Optionally clicks a tab to reveal the list first. Used by Hulu
+ *   Live TV.
+ * - "hboGrid": Discover the HBO tab page URL from the homepage menu bar, scrape the live channel tile rail for a matching channel name, and navigate to the watch
+ *   URL. Caches the tab URL across tunes with stale-cache fallback. Used by HBO Max.
+ * - "none": No channel selection needed (single-channel sites). This is the default.
+ * - "slingGrid": Find channel by data-testid in a virtualized A-Z guide grid, scroll via binary search on .guide-cell scrollTop, click the on-now program
+ *   cell. Used by Sling TV.
+ * - "thumbnailRow": Find channel element using the profile's matchSelector (defaults to image URL matching), click adjacent element on the same row. Used by
+ *   USA Network.
+ * - "tileClick": Find channel element using the profile's matchSelector (defaults to image URL matching), click tile, then optionally click play button if
+ *   playSelector is configured. Used by Disney+.
+ * - "youtubeGrid": Find channel by aria-label in a non-virtualized EPG grid, extract the watch URL, and navigate directly. Used by YouTube TV.
+ */
+export type ChannelSelectionStrategy = "directvGrid" | "foxGrid" | "guideGrid" | "hboGrid" | "none" | "slingGrid" | "thumbnailRow" | "tileClick" | "youtubeGrid";
+/**
+ * Configuration for channel selection behavior within a site profile.
+ */
+export interface ChannelSelectionConfig {
+    listSelector?: string;
+    matchSelector?: string;
+    playSelector?: string;
+    scrollSelector?: string;
+    scrollTarget?: string;
+    scrollToBottom?: boolean;
+    strategy: ChannelSelectionStrategy;
+}
+/**
+ * UI category for profile grouping in dropdowns and reference documentation. Profiles are grouped by their fullscreen mechanism and special characteristics.
+ * - "api": Profiles using the JavaScript fullscreen API (including embedded iframe and click-to-play variants).
+ * - "custom": User-defined profiles created via the profile builder wizard or imported from provider packs.
+ * - "keyboard": Profiles using keyboard shortcuts (typically the 'f' key) for fullscreen.
+ * - "multiChannel": Multi-channel profiles requiring a channel selector for tile or thumbnail-based channel selection.
+ * - "special": Special-purpose profiles like static page capture.
+ */
+export type ProfileCategory = "api" | "custom" | "keyboard" | "multiChannel" | "special";
+/**
+ * Site profile definition with optional flags. All flags are optional because profiles can inherit from other profiles, and only the flags that differ from the
+ * parent need to be specified. The DEFAULT_SITE_PROFILE provides baseline values for any flags not set through inheritance.
+ */
+export interface SiteProfile {
+    category?: ProfileCategory;
+    channelSelection?: ChannelSelectionConfig;
+    channelSelector?: Nullable<string>;
+    clickSelector?: Nullable<string>;
+    clickToPlay?: boolean;
+    description?: string;
+    extends?: string;
+    summary?: string;
+    fullscreenKey?: Nullable<string>;
+    fullscreenSelector?: Nullable<string>;
+    hideSelector?: Nullable<string>;
+    lockVolumeProperties?: boolean;
+    needsIframeHandling?: boolean;
+    noVideo?: boolean;
+    selectReadyVideo?: boolean;
+    useRequestFullscreen?: boolean;
+    waitForNetworkIdle?: boolean;
+}
+/**
+ * Fully-resolved site profile with all flags having concrete values. After resolving inheritance chains and applying defaults, every flag has a definite boolean
+ * or string value. This interface is used by stream handling code that needs to check profile flags without worrying about undefined values.
+ */
+export interface ResolvedSiteProfile {
+    channelSelection: ChannelSelectionConfig;
+    channelSelector: Nullable<string>;
+    clickSelector: Nullable<string>;
+    clickToPlay: boolean;
+    fullscreenKey: Nullable<string>;
+    fullscreenSelector: Nullable<string>;
+    hideSelector: Nullable<string>;
+    lockVolumeProperties: boolean;
+    maxContinuousPlayback: Nullable<number>;
+    needsIframeHandling: boolean;
+    noVideo: boolean;
+    selectReadyVideo: boolean;
+    useRequestFullscreen: boolean;
+    waitForNetworkIdle: boolean;
+}
+/**
+ * Result of resolving a site profile. Includes both the resolved profile configuration and the name of the profile that was matched. The name indicates whether the
+ * profile came from a channel hint, domain-based autodetection, or the default fallback.
+ */
+export interface ProfileResolutionResult {
+    profile: ResolvedSiteProfile;
+    profileName: string;
+}
+/**
+ * Domain-level configuration associating domain patterns with site profiles and provider display names. Each entry can specify a site profile for behavior
+ * configuration and/or a provider display name for friendly UI labels. Used by both built-in domain mappings in sites.ts and user-defined mappings in profiles.json.
+ */
+export interface DomainConfig {
+    loginUrl?: string;
+    maxContinuousPlayback?: number;
+    profile?: string;
+    provider?: string;
+    providerTag?: string;
+}
+/**
+ * Storage format for profiles.json. Contains user-defined site profiles and domain mappings that extend or override the built-in configurations.
+ */
+export interface UserProfilesFile {
+    domains?: Record<string, DomainConfig>;
+    profiles?: Record<string, SiteProfile>;
+}
+/**
+ * Result of loading user profiles from the profiles.json file.
+ */
+export interface UserProfilesLoadResult {
+    domains: Record<string, DomainConfig>;
+    parseError: boolean;
+    parseErrorMessage?: string;
+    profiles: Record<string, SiteProfile>;
+}
+/**
+ * Provider pack distribution format. Bundles a profile, domain mapping(s), and optionally channels for a streaming provider into a single JSON file. On import,
+ * its contents are split and written to profiles.json and channels.json.
+ */
+export interface ProviderPack {
+    channels?: ChannelMap;
+    domains?: Record<string, DomainConfig>;
+    name: string;
+    profiles: Record<string, SiteProfile>;
+    version: number;
+}
+/**
+ * Validation result for profile and domain imports.
+ */
+export interface ProfilesValidationResult {
+    domains: Record<string, DomainConfig>;
+    errors: string[];
+    profiles: Record<string, SiteProfile>;
+    valid: boolean;
+}

package/dist/types/profiles.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=profiles.js.map

package/dist/types/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/types/profiles.ts"],"names":[],"mappings":""}

package/dist/types/selection.d.ts

@@ -0,0 +1,101 @@
+import type { ChannelSelectionStrategy, ResolvedSiteProfile } from "./profiles.js";
+import type { Frame, Page } from "puppeteer-core";
+import type { Nullable } from "./shared.js";
+export interface ChannelSelectionProfile extends ResolvedSiteProfile {
+    channelSelector: string;
+}
+export declare function isChannelSelectionProfile(profile: ResolvedSiteProfile): profile is ChannelSelectionProfile;
+/**
+ * Result of attempting to select a channel from a multi-channel player UI.
+ */
+export interface ChannelSelectorResult {
+    directTune?: boolean;
+    reason?: string;
+    success: boolean;
+}
+/**
+ * The strategy function signature. All strategies take the Puppeteer page and a narrowed profile with guaranteed non-null channelSelector.
+ */
+export type ChannelStrategyHandler = (page: Page, profile: ChannelSelectionProfile) => Promise<ChannelSelectorResult>;
+/**
+ * The complete contract for a channel selection strategy. Each provider file exports a single object implementing this interface. The coordinator accesses all
+ * provider behavior through these hooks — no strategy-specific imports or hardcoded strategy name checks outside the registry.
+ */
+export interface ChannelStrategyEntry {
+    /**
+     * Resets all module-level caches (row positions, discovered URLs, watch URLs). Called on browser restart when cached state may be stale.
+     */
+    clearCache?: () => void;
+    /**
+     * Selects the target channel in the provider's guide UI. Receives a Puppeteer page and a profile with a guaranteed non-null channelSelector. Must handle its
+     * own retry logic (e.g., overlay dismiss) and return a result indicating success or failure with a diagnostic reason.
+     */
+    execute: ChannelStrategyHandler;
+    /**
+     * Removes a cached watch URL after it failed to produce a working stream. Called by the coordinator when a cached direct navigation fails.
+     */
+    invalidateDirectUrl?: (channelSelector: string) => void;
+    /**
+     * Returns a watch URL for direct navigation, bypassing guide page loading. Implementations may perform async work such as fetching current asset IDs from
+     * provider APIs. The page parameter allows setting up response interception or accessing browser context when needed (e.g., cold cache setup).
+     */
+    resolveDirectUrl?: (channelSelector: string, page: Page) => Promise<Nullable<string>>;
+}
+/**
+ * Standardized output shape for a channel discovered from a provider's guide. Produced by each provider's discoverChannels implementation and returned as
+ * a JSON array from the GET /providers/:slug/channels endpoint. Mirrors the shape of channel definitions in channels/index.ts so discovery output can be
+ * used directly to populate new entries.
+ */
+export interface DiscoveredChannel {
+    affiliate?: string;
+    channelSelector: string;
+    name: string;
+    tier?: string;
+}
+/**
+ * Unified provider contract that bundles identity metadata, tuning strategy, and channel discovery into a single registry entry. Each provider tuning file
+ * exports one ProviderModule. The coordinator builds its strategy dispatch lookup from provider modules at evaluation time. Generic strategies (thumbnailRow,
+ * tileClick) remain bare ChannelStrategyEntry objects — they are not providers.
+ */
+export interface ProviderModule {
+    /**
+     * Discovers all available channels from the provider's guide. The route handler navigates to guideUrl before calling this function unless handlesOwnNavigation
+     * is set. Returns a standardized DiscoveredChannel array.
+     */
+    discoverChannels: (page: Page) => Promise<DiscoveredChannel[]>;
+    /**
+     * Returns cached discovered channels if the provider has already fully enumerated its lineup from a previous tune or discovery call, or null if no enumeration
+     * has occurred. When non-null, the route handler can skip browser page creation entirely and return the cached result immediately.
+     */
+    getCachedChannels: () => Nullable<DiscoveredChannel[]>;
+    guideUrl: string;
+    handlesOwnNavigation?: boolean;
+    label: string;
+    slug: string;
+    strategy: ChannelStrategyEntry;
+    strategyName: ChannelSelectionStrategy;
+    validatePrecache?: (channels: DiscoveredChannel[]) => boolean;
+    validateTune?: (channelSelector: string) => boolean;
+}
+/**
+ * Coordinates for a click target, used when clicking channel selector elements.
+ */
+export interface ClickTarget {
+    x: number;
+    y: number;
+}
+/**
+ * Result of tuning to a channel, containing the video context needed for monitoring.
+ */
+export interface TuneResult {
+    context: Frame | Page;
+    directTune?: boolean;
+}
+/**
+ * Browser chrome dimensions (toolbars, borders) calculated by comparing window.outerHeight/Width to window.innerHeight/Width. Used to set window size such that
+ * the viewport (content area) matches our target dimensions.
+ */
+export interface UiSize {
+    height: number;
+    width: number;
+}