@bnhf/prismcast 1.3.4-2026.2.19

package/dist/browser/channelSelection.js

@@ -0,0 +1,202 @@
+import { LOG, delay } from "../utils/index.js";
+import { CHANNELS } from "../channels/index.js";
+import { CONFIG } from "../config/index.js";
+import { foxStrategy } from "./tuning/fox.js";
+import { hboStrategy } from "./tuning/hbo.js";
+import { huluStrategy } from "./tuning/hulu.js";
+import { isChannelSelectionProfile } from "../types/index.js";
+import { slingStrategy } from "./tuning/sling.js";
+import { thumbnailRowStrategy } from "./tuning/thumbnailRow.js";
+import { tileClickStrategy } from "./tuning/tileClick.js";
+import { yttvStrategy } from "./tuning/youtubeTv.js";
+/* Multi-channel streaming sites (like USA Network) present multiple channels on a single page, with a program guide for each channel. Users must select which
+ * channel they want to watch by clicking on a show in the guide. This module coordinates the dispatch to per-provider strategy functions in the tuning/ directory.
+ *
+ * Each strategy is a self-contained file under tuning/ that exports a single ChannelStrategyEntry object. The coordinator handles pre-dispatch concerns (image
+ * polling, no-op checks) and post-dispatch logging. Strategy files may import scrollAndClick() and normalizeChannelName() from this coordinator — the circular
+ * import is safe because all cross-module calls happen inside async functions long after module evaluation completes.
+ */
+/* Adding a new channel selection provider:
+ *
+ * 1. Create a new file in tuning/ implementing the strategy function with the ChannelStrategyHandler signature.
+ * 2. Export a single ChannelStrategyEntry object from the file. Set the hooks your provider needs:
+ *    - execute (required): The strategy function that selects the channel in the provider's guide UI.
+ *    - clearCache: If your strategy caches state (row positions, URLs), provide a function that clears it.
+ *    - resolveDirectUrl / invalidateDirectUrl: If your strategy discovers stable watch URLs that can be reused across tunes, provide cache lookup and invalidation.
+ *    - usesImageSlug: Set to true if channelSelector is an image URL slug requiring load polling before dispatch.
+ * 3. Import the entry here and add it to the strategies registry with the strategy name as the key.
+ * 4. Add the strategy name to the ChannelSelectionStrategy union type in types/index.ts.
+ * 5. Add a site profile entry in config/sites.ts that references the new strategy name.
+ *
+ * The coordinator handles all cross-cutting concerns (dispatch, cache clearing, direct URL resolution, image polling) through the ChannelStrategyEntry interface.
+ * Strategy files may import scrollAndClick(), normalizeChannelName(), and logAvailableChannels() from this module for shared utilities.
+ */
+// Strategy dispatch registry. Maps strategy names from ChannelSelectionStrategy to their implementation entry. Adding a new provider requires a single entry here
+// — all cross-cutting concerns (cache clearing, direct URL resolution, image polling) are driven by the entry's hooks.
+const strategies = {
+    foxGrid: foxStrategy,
+    guideGrid: huluStrategy,
+    hboGrid: hboStrategy,
+    slingGrid: slingStrategy,
+    thumbnailRow: thumbnailRowStrategy,
+    tileClick: tileClickStrategy,
+    youtubeGrid: yttvStrategy
+};
+/**
+ * Returns a direct watch URL for the channel specified in the profile, if one can be resolved. Looks up the strategy entry's resolveDirectUrl hook and calls it
+ * with the channelSelector and page. Returns null if the strategy has no resolver, the profile has no channelSelector, or the resolver returns null.
+ * @param profile - The resolved site profile.
+ * @param page - The Puppeteer page object, passed through to the strategy's resolver for response interception setup or API calls.
+ * @returns The direct watch URL or null.
+ */
+export async function resolveDirectUrl(profile, page) {
+    const { channelSelection, channelSelector } = profile;
+    if (!channelSelector) {
+        return null;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    return await strategies[channelSelection.strategy]?.resolveDirectUrl?.(channelSelector, page) ?? null;
+}
+/**
+ * Invalidates the cached direct watch URL for the channel specified in the profile. Looks up the strategy entry's invalidateDirectUrl hook and calls it with
+ * the channelSelector. No-op if the strategy has no invalidator or the profile has no channelSelector.
+ * @param profile - The resolved site profile.
+ */
+export function invalidateDirectUrl(profile) {
+    const { channelSelection, channelSelector } = profile;
+    if (!channelSelector) {
+        return;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    strategies[channelSelection.strategy]?.invalidateDirectUrl?.(channelSelector);
+}
+/**
+ * Clears all channel selection caches. Called by handleBrowserDisconnect() in browser/index.ts when the browser restarts, since cached state (guide row positions,
+ * discovered page URLs, watch URLs) may be stale in a new browser session.
+ */
+export function clearChannelSelectionCaches() {
+    for (const entry of Object.values(strategies)) {
+        entry.clearCache?.();
+    }
+}
+/**
+ * Clicks at the specified coordinates after a brief settle delay. The delay allows scroll animations and lazy-loaded content to finish before the click fires.
+ * Callers are responsible for scrolling the target element into view (typically via scrollIntoView inside a page.evaluate call) before invoking this function.
+ * Exported for use by tuning strategy files (thumbnailRow, tileClick, hulu).
+ * @param page - The Puppeteer page object.
+ * @param target - The x/y coordinates to click.
+ * @returns True if the click was executed.
+ */
+export async function scrollAndClick(page, target) {
+    // Brief delay after scrolling for any animations or lazy-loaded content to settle.
+    await delay(200);
+    // Click the target coordinates to switch to the channel.
+    await page.mouse.click(target.x, target.y);
+    return true;
+}
+// Normalizes a channel name for case-insensitive, whitespace-tolerant comparison. Trims leading and trailing whitespace, collapses internal whitespace sequences
+// (including non-breaking spaces, tabs, and other Unicode whitespace matched by \s) into a single regular space, and lowercases. This handles data-testid values
+// with trailing spaces (e.g., "WLS "), double spaces, or non-breaking space characters that would otherwise cause exact match failures.
+// Exported for use by tuning strategy files (hulu, sling).
+export function normalizeChannelName(name) {
+    return name.trim().replace(/\s+/g, " ").toLowerCase();
+}
+/**
+ * Logs available channel names from a provider's guide grid when channel selection fails. Produces an actionable log message listing channel names that users can
+ * use as `channelSelector` values in user-defined channels. When `presetSuffix` is provided, channels already covered by built-in preset definitions are filtered
+ * out so users see only channels that require manual configuration. When omitted (small channel sets like Fox or HBO), all channels are logged unfiltered.
+ * @param options - Diagnostic dump configuration.
+ * @param options.additionalKnownNames - Extra names to exclude from the filtered list (e.g., CHANNEL_ALTERNATES values for YTTV).
+ * @param options.availableChannels - Sorted list of channel names discovered in the guide grid.
+ * @param options.channelName - The channelSelector value that failed to match, for the log message.
+ * @param options.guideUrl - The URL of the provider's guide page, included in the log message so users know what to set as the channel URL.
+ * @param options.presetSuffix - Key suffix to filter preset channels (e.g., "-yttv", "-hulu"). Omit for small unfiltered channel sets.
+ * @param options.providerName - Human-readable provider name for the log message (e.g., "YouTube TV", "Hulu").
+ */
+export function logAvailableChannels(options) {
+    const { additionalKnownNames, availableChannels, channelName, guideUrl, presetSuffix, providerName } = options;
+    if (availableChannels.length === 0) {
+        return;
+    }
+    let filteredChannels;
+    let countLabel;
+    if (presetSuffix) {
+        // Collect all channelSelector values from preset channels with this suffix, lowercased for case-insensitive comparison.
+        const knownSelectors = Object.entries(CHANNELS)
+            .filter(([key]) => key.endsWith(presetSuffix))
+            .map(([, ch]) => (ch.channelSelector ?? "").toLowerCase())
+            .filter((s) => s.length > 0);
+        // Include additional known names (e.g., CHANNEL_ALTERNATES values for YTTV) so those are also filtered out.
+        if (additionalKnownNames) {
+            for (const name of additionalKnownNames) {
+                knownSelectors.push(name.toLowerCase());
+            }
+        }
+        // Filter to channels not matched by any known selector. A channel is "covered" if a preset would find it via exact match (with parenthetical suffix stripped)
+        // or prefix+digit match. This mirrors the strategy's own matching tiers so users see only channels that genuinely need manual configuration.
+        filteredChannels = availableChannels.filter((name) => {
+            const lower = name.toLowerCase();
+            const stripped = lower.replace(/ \(.*\)$/, "");
+            return !knownSelectors.some((sel) => {
+                return (stripped === sel) ||
+                    (lower.startsWith(sel + " ") && (lower.length > sel.length + 1) && (lower.charCodeAt(sel.length + 1) >= 48) && (lower.charCodeAt(sel.length + 1) <= 57));
+            });
+        });
+        countLabel = "uncovered (" + String(filteredChannels.length) + " of " + String(availableChannels.length) + ")";
+    }
+    else {
+        // No preset suffix — log all available channels unfiltered. Used for small channel sets (Fox, HBO) where the full list is actionable without filtering.
+        filteredChannels = availableChannels;
+        countLabel = String(filteredChannels.length);
+    }
+    if (filteredChannels.length === 0) {
+        return;
+    }
+    LOG.warn("Channel \"%s\" not found in %s guide. Create a user-defined channel with one of the names below as the Channel Selector and %s as the URL. " +
+        "Available channels (%s): %s.", channelName, providerName, guideUrl, countLabel, filteredChannels.join(", "));
+}
+/**
+ * Selects a channel from a multi-channel player UI using the strategy specified in the profile. This is the main entry point for channel selection, called by
+ * tuneToChannel() after page navigation.
+ *
+ * The function handles:
+ * - Polling for channel slug image readiness before strategy dispatch (when entry.usesImageSlug is true)
+ * - Strategy dispatch based on profile.channelSelection.strategy
+ * - No-op for single-channel sites (strategy "none" or no channelSelector)
+ * - Logging of selection attempts and results
+ * @param page - The Puppeteer page object.
+ * @param profile - The resolved site profile containing channelSelection config and channelSelector slug.
+ * @returns Result object with success status and optional failure reason.
+ */
+export async function selectChannel(page, profile) {
+    const { channelSelection } = profile;
+    // No channel selection needed if strategy is "none" or no channelSelector is specified.
+    if ((channelSelection.strategy === "none") || !isChannelSelectionProfile(profile)) {
+        return { success: true };
+    }
+    // Look up the strategy entry before image polling so we can check entry.usesImageSlug.
+    const entry = strategies[channelSelection.strategy];
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!entry) {
+        LOG.warn("Unknown channel selection strategy: %s.", channelSelection.strategy);
+        return { reason: "Unknown channel selection strategy.", success: false };
+    }
+    // Poll for the channel slug image to appear and fully load. We check both src match and load completion (img.complete + naturalWidth) to ensure the image is
+    // actually rendered before proceeding. This prevents race conditions where the img element exists with the correct src but the browser hasn't finished fetching
+    // and rendering it, which can cause layout instability and click failures. Only run for strategies that use an image URL slug as their channelSelector
+    // (thumbnailRow, tileClick). Strategies using channel names or station codes skip this.
+    if (entry.usesImageSlug) {
+        try {
+            await page.waitForFunction((slug) => {
+                return Array.from(document.querySelectorAll("img")).some((img) => img.src && img.src.includes(slug) && img.complete && (img.naturalWidth > 0));
+            }, { timeout: CONFIG.playback.channelSelectorDelay }, profile.channelSelector);
+        }
+        catch {
+            // Timeout — the image hasn't loaded yet. Proceed anyway and let the strategy evaluate and report not-found naturally.
+        }
+    }
+    // Dispatch to the appropriate strategy via the registry.
+    const result = await entry.execute(page, profile);
+    return result;
+}
+//# sourceMappingURL=channelSelection.js.map

package/dist/browser/channelSelection.js.map

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

package/dist/browser/display.d.ts

@@ -0,0 +1,34 @@
+import type { Nullable } from "../types/index.js";
+/**
+ * Sets the maximum supported viewport dimensions. Called by browser initialization after detecting the display size and accounting for browser chrome.
+ * @param width - Maximum viewport width in pixels.
+ * @param height - Maximum viewport height in pixels.
+ */
+export declare function setMaxSupportedViewport(width: number, height: number): void;
+/**
+ * Returns the maximum supported viewport dimensions, or null if display detection has not yet completed. Callers should fall back to the configured preset when null
+ * is returned.
+ * @returns The maximum supported viewport dimensions, or null before detection.
+ */
+export declare function getMaxSupportedViewport(): Nullable<{
+    height: number;
+    width: number;
+}>;
+/**
+ * Sets the browser chrome dimensions. Called by browser initialization after measuring the difference between outer and inner window dimensions.
+ * @param width - Chrome width in pixels (typically 0 or small for window borders).
+ * @param height - Chrome height in pixels (title bar + toolbar).
+ */
+export declare function setBrowserChrome(width: number, height: number): void;
+/**
+ * Returns the cached browser chrome dimensions, or null if display detection has not yet completed.
+ * @returns The browser chrome dimensions, or null before detection.
+ */
+export declare function getBrowserChrome(): Nullable<{
+    height: number;
+    width: number;
+}>;
+/**
+ * Clears the cached display dimensions. Called when browser restarts to force re-detection.
+ */
+export declare function clearDisplayCache(): void;

package/dist/browser/display.js

@@ -0,0 +1,54 @@
+/* This module provides a simple cache for display-related dimensions detected during browser initialization. Two sets of values are cached:
+ *
+ * 1. Maximum supported viewport: The largest viewport that fits on the display after accounting for browser chrome. Used by the preset system to determine if the
+ *    configured preset needs to be degraded.
+ *
+ * 2. Browser chrome dimensions: The height and width of browser UI elements (title bar, toolbar, borders). Used when resizing the browser window to calculate the
+ *    total window size needed for a given viewport size.
+ *
+ * This module is intentionally minimal with no imports from other project modules to avoid circular dependencies. The browser module detects dimensions and calls
+ * the setters. Other modules call the getters to access cached values.
+ */
+// Cached maximum supported viewport dimensions. Null before browser initialization completes display detection.
+let maxSupportedViewport = null;
+// Cached browser chrome dimensions (title bar, toolbar, borders). Null before browser initialization completes display detection.
+let browserChrome = null;
+/**
+ * Sets the maximum supported viewport dimensions. Called by browser initialization after detecting the display size and accounting for browser chrome.
+ * @param width - Maximum viewport width in pixels.
+ * @param height - Maximum viewport height in pixels.
+ */
+export function setMaxSupportedViewport(width, height) {
+    maxSupportedViewport = { height, width };
+}
+/**
+ * Returns the maximum supported viewport dimensions, or null if display detection has not yet completed. Callers should fall back to the configured preset when null
+ * is returned.
+ * @returns The maximum supported viewport dimensions, or null before detection.
+ */
+export function getMaxSupportedViewport() {
+    return maxSupportedViewport;
+}
+/**
+ * Sets the browser chrome dimensions. Called by browser initialization after measuring the difference between outer and inner window dimensions.
+ * @param width - Chrome width in pixels (typically 0 or small for window borders).
+ * @param height - Chrome height in pixels (title bar + toolbar).
+ */
+export function setBrowserChrome(width, height) {
+    browserChrome = { height, width };
+}
+/**
+ * Returns the cached browser chrome dimensions, or null if display detection has not yet completed.
+ * @returns The browser chrome dimensions, or null before detection.
+ */
+export function getBrowserChrome() {
+    return browserChrome;
+}
+/**
+ * Clears the cached display dimensions. Called when browser restarts to force re-detection.
+ */
+export function clearDisplayCache() {
+    browserChrome = null;
+    maxSupportedViewport = null;
+}
+//# sourceMappingURL=display.js.map

package/dist/browser/display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.js","sourceRoot":"","sources":["../../src/browser/display.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAEH,gHAAgH;AAChH,IAAI,oBAAoB,GAAgD,IAAI,CAAC;AAE7E,kIAAkI;AAClI,IAAI,aAAa,GAAgD,IAAI,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,MAAc;IAEnE,oBAAoB,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IAErC,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,MAAc;IAE5D,aAAa,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAE9B,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAE/B,aAAa,GAAG,IAAI,CAAC;IACrB,oBAAoB,GAAG,IAAI,CAAC;AAC9B,CAAC"}

package/dist/browser/index.d.ts

@@ -0,0 +1,205 @@
+import type { Browser, LaunchOptions, Page } from "puppeteer-core";
+import { getStream } from "puppeteer-stream";
+import type { Nullable } from "../types/index.js";
+/**
+ * Returns true if graceful shutdown is in progress.
+ */
+export declare function isGracefulShutdown(): boolean;
+/**
+ * Sets the graceful shutdown flag. Call this at the start of shutdown, before terminating streams, so that page close errors are suppressed.
+ */
+export declare function setGracefulShutdown(value: boolean): void;
+/**
+ * Login status information returned by getLoginStatus().
+ */
+export interface LoginStatus {
+    active: boolean;
+    startTime: Nullable<number>;
+    url: Nullable<string>;
+}
+/**
+ * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
+ */
+export declare function emitCurrentSystemStatus(): Promise<void>;
+/**
+ * Registers a page as managed by PrismCast. This should be called immediately after creating a page via browser.newPage(). Registered pages are tracked for stale
+ * page cleanup, while unregistered pages (manually opened, site popups, etc.) are left alone.
+ *
+ * Each registered page receives a unique ID that persists for the page's lifetime. This ID is used for comparison and staleness tracking, avoiding potential
+ * issues with Page object reference identity.
+ * @param page - The Puppeteer Page to register.
+ */
+export declare function registerManagedPage(page: Page): void;
+/**
+ * Unregisters a page from PrismCast's management. This should be called when a page is being closed intentionally (during stream cleanup). Unregistering prevents the
+ * stale page cleanup from racing with intentional page closure.
+ * @param page - The Puppeteer Page to unregister.
+ */
+export declare function unregisterManagedPage(page: Page): void;
+/**
+ * Gets the current data directory path. This is where Chrome profile data and extension files are stored.
+ * @returns The data directory path.
+ */
+export declare function getDataDir(): string;
+/**
+ * Ensures the data directory exists, creating it if necessary. This should be called during application startup before any operations that depend on the data
+ * directory (like browser launch or extension preparation).
+ *
+ * The data directory (~/.prismcast) stores:
+ * - Chrome profile data (cookies, local storage, session state)
+ * - Extension files (when running as a packaged executable)
+ */
+export declare function ensureDataDirectory(): Promise<void>;
+/**
+ * Ensures a clean slate for browser launch by terminating any stale Chrome processes and removing orphaned profile lock files. Chrome locks its profile directory
+ * while running, and if a previous instance crashed without releasing the lock, we cannot launch a new browser with the same profile. This function uses pkill to
+ * find and terminate any Chrome processes whose command line contains our profile directory path, then polls pgrep to verify the processes have actually exited.
+ * After process cleanup, it removes stale lock files (SingletonLock, SingletonCookie, SingletonSocket) and DevToolsActivePort from the profile directory.
+ *
+ * The termination strategy escalates from SIGTERM to SIGKILL. SIGTERM is sent first, giving Chrome up to 5 seconds to flush its profile databases (LevelDB,
+ * extension state, session storage) and exit cleanly. If Chrome does not exit, SIGKILL is sent as a fallback. This escalation is critical when called from the
+ * process exit handler — Chrome may be running normally (e.g., after a capture probe timeout), and an immediate SIGKILL would corrupt its profile databases,
+ * poisoning the Docker volume for subsequent container restarts.
+ *
+ * The file cleanup is essential for Docker deployments. Container restarts destroy Chrome processes without giving them a chance to release profile locks, but the
+ * lock files persist in the mounted volume. Without removing them, Chrome cannot start in the new container, causing a crash loop.
+ *
+ * This is called at startup before launching the browser and after closeBrowser() during shutdown. It's safe to call even when no stale processes or files exist.
+ */
+export declare function killStaleChrome(): void;
+/**
+ * Locates the Google Chrome executable on the system. The CHROME_BIN environment variable takes precedence, allowing operators to specify a non-standard
+ * installation. Otherwise, we search common installation paths across macOS, Linux, and Windows.
+ *
+ * @returns Path to the Chrome executable.
+ * @throws If no Chrome installation is found.
+ */
+export declare function getExecutablePath(): string;
+/**
+ * Assembles the configuration options for launching Chrome with Puppeteer. These options are critical for reliable streaming:
+ *
+ * - Chrome flags configure the browser for unattended video playback without user interaction
+ * - Ignored default args prevent Puppeteer from disabling features we need (extensions, audio, component updates)
+ * - A persistent user data directory retains cookies and login state across restarts
+ * - Pipe mode provides a faster, more reliable connection than WebSocket
+ * @returns Puppeteer launch options.
+ */
+export declare function buildLaunchOptions(): LaunchOptions;
+/**
+ * Provides access to the shared browser instance, launching one if needed. The browser is a shared resource used by all streaming sessions. This function handles:
+ *
+ * - Returning the existing browser if it's still connected
+ * - Launching a new browser if none exists or the previous one disconnected
+ * - Serializing concurrent callers so only one launch occurs at a time
+ * - Waiting for the puppeteer-stream extension to initialize
+ * - Setting up disconnect handlers for crash recovery
+ * @returns The browser instance.
+ * @throws If the browser cannot be launched.
+ */
+export declare function getCurrentBrowser(): Promise<Browser>;
+/**
+ * Returns the Chrome version string captured when the browser launched, or null if the browser is not connected.
+ * @returns The Chrome version string (e.g., "Chrome/144.0.7559.110") or null.
+ */
+export declare function getChromeVersion(): Nullable<string>;
+/**
+ * Checks if the browser is currently connected and usable. This is a synchronous check that can be used before attempting browser operations.
+ * @returns True if the browser is connected and ready for use, false otherwise.
+ */
+export declare function isBrowserConnected(): boolean;
+/**
+ * Resizes the browser window to the effective viewport and minimizes it. This function combines viewport sizing with minimization to ensure the window is
+ * properly sized before being minimized. The resize uses the effective viewport from getEffectiveViewport(), which accounts for display size constraints and
+ * preset degradation.
+ *
+ * To avoid issues with creating temporary pages (which can cause the window to restore on macOS), we prefer using an existing page if one is available. Only if
+ * no pages exist do we create a temporary page.
+ */
+export declare function minimizeBrowserWindow(): Promise<void>;
+/**
+ * Gets all open browser pages (tabs). This is used by the health check endpoint to report page count and by stale page cleanup to find orphaned pages.
+ * @returns Array of pages, or empty array if the browser is not connected.
+ */
+export declare function getBrowserPages(): Promise<Page[]>;
+/**
+ * Closes the browser and cleans up resources. This is called during graceful shutdown to ensure Chrome exits cleanly. After this call, the browser reference is
+ * cleared and any subsequent stream requests will launch a fresh browser.
+ *
+ * The function uses a two-stage approach to ensure Chrome actually exits:
+ * 1. Try browser.close() with a 5-second timeout (DevTools Protocol graceful close)
+ * 2. Run killStaleChrome() to catch anything Stage 1 missed, using SIGTERM→SIGKILL escalation to give Chrome a chance to flush its profile databases
+ */
+export declare function closeBrowser(): Promise<void>;
+/**
+ * Starts login mode by opening a new browser tab with the specified URL and un-minimizing the browser window. The user can then authenticate with their TV
+ * provider in the visible browser.
+ *
+ * Login mode blocks new stream requests until it ends (via endLoginMode, tab close detection, or timeout).
+ * @param url - The URL to navigate to for authentication.
+ * @returns Object indicating success or failure with optional error message.
+ */
+export declare function startLoginMode(url: string): Promise<{
+    error?: string;
+    success: boolean;
+}>;
+/**
+ * Ends login mode by closing the login tab (if still open) and re-minimizing the browser window. This function is idempotent - it's safe to call multiple times
+ * or when login mode is not active.
+ *
+ * Called by:
+ * - User clicking "Done" in the web UI (POST /auth/done)
+ * - Tab close detection (user closes the tab manually)
+ * - 15-minute timeout
+ * - Browser disconnect handler (cleanup)
+ */
+export declare function endLoginMode(): Promise<void>;
+/**
+ * Returns whether login mode is currently active. Used by the stream handler to block new stream requests during login.
+ * @returns True if login mode is active, false otherwise.
+ */
+export declare function isLoginModeActive(): boolean;
+/**
+ * Returns the current login status including whether active, the URL being used, and when login started. Used by the /auth/status API endpoint.
+ * @returns Login status object.
+ */
+export declare function getLoginStatus(): LoginStatus;
+/**
+ * Cleans up browser pages that are not associated with active streams. This function runs periodically to catch any pages that were not properly closed during
+ * stream termination.
+ *
+ * The cleanup uses a multi-stage filtering process:
+ * 1. Only consider pages we created (in managedPageIds)
+ * 2. Exclude pages associated with active streams
+ * 3. Apply a grace period before closing (to handle race conditions)
+ * 4. Preserve at least one page to keep the browser alive
+ */
+export declare function cleanupStalePages(): Promise<void>;
+/**
+ * Starts the periodic stale page cleanup interval. This should be called once during server startup, after the browser is initialized. The interval runs
+ * indefinitely until stopStalePageCleanup() is called (typically during graceful shutdown).
+ */
+export declare function startStalePageCleanup(): void;
+/**
+ * Stops the stale page cleanup interval. This should be called during graceful shutdown to prevent the cleanup from running after we've started shutting down
+ * the browser and streams.
+ */
+export declare function stopStalePageCleanup(): void;
+/**
+ * Starts the periodic browser restart eligibility check. This should be called once during server startup, after the browser is initialized. The interval runs
+ * indefinitely until stopBrowserRestartChecking() is called (typically during graceful shutdown).
+ */
+export declare function startBrowserRestartChecking(): void;
+/**
+ * Stops the browser restart checking interval and cancels any pending quiet timer. This should be called during graceful shutdown to prevent a restart from
+ * racing with server shutdown.
+ */
+export declare function stopBrowserRestartChecking(): void;
+/**
+ * Extracts the Puppeteer Stream extension files when running as a packaged executable. This copies the extension files from within the packaged binary to the
+ * filesystem where Chrome can load them.
+ *
+ * When running from source (not packaged), this function does nothing - puppeteer-stream can load the extension directly from node_modules.
+ * @throws If extension extraction fails.
+ */
+export declare function prepareExtension(): Promise<void>;
+export { getStream };