prismcast 1.12.0 → 1.13.0

package/dist/browser/hlsPlaylistObserver.js

@@ -2,9 +2,10 @@
  *
  * hlsPlaylistObserver.ts: HLS-aware observer layered on top of the tab-wide network observer.
  */
-import { LOG, chromeFetch } from "../utils/index.js";
+import { LOG, chromeFetch, timeoutSignal } from "../utils/index.js";
 import { classifyHlsPlaylist, extractChildPlaylistUrls, isLiveMediaPlaylist } from "../native/probe.js";
 import { observeTabResponses } from "./tabNetworkObserver.js";
+import { systemClock } from "homebridge-plugin-utils";
 /* This module is the HLS-aware layer on top of tabNetworkObserver. Its job is to deliver every recognized HLS playlist (URL + kind) observed anywhere in the tab
  * to a single callback. It encapsulates:
  *
@@ -37,15 +38,15 @@ const MANIFEST_BODY_FETCH_TIMEOUT = 5000;
  * Returns null when the underlying tab network observer could not be installed (page closed, root CDP session creation failed).
  *
  * @param page - The puppeteer page to observe.
- * @param options - Observer options including the playlist callback and the debug log category.
+ * @param options - Observer options: the playlist callback, the debug log category, and the clock the body fetch's bound arms on.
  * @returns The observer handle, or null if installation failed.
  */
 export async function observeHlsPlaylists(page, options) {
-    const { logCategory, onPlaylist } = options;
+    const { clock = systemClock, logCategory, onPlaylist } = options;
     let disposed = false;
     // Wire-arrival sequence counter. Each eligible unique URL is assigned the next ordinal synchronously at the dedup gate - before its body fetch begins - so the
     // ordinal reflects the order responses arrived on the wire rather than the order their independent, racing body fetches happen to resolve. Sequences start at 1,
-    // so a currentSequence() of 0 means nothing has been observed yet and an epoch fenced at 0 reads every later observation as post-epoch. The honest bound: the
+    // so a currentSequence() of 0 means nothing has been observed yet and an epoch fenced at 0 reads every later observation as post-epoch. The bound: the
     // ordinal reflects CDP-event arrival order at the client, and Chrome does not guarantee cross-session event ordering for OOPIF targets, so the fence approximates
     // wire order within event-delivery latency - a residual window of milliseconds, in place of the seconds-wide body-fetch race a delivery-time ordering would carry.
     let sequenceCounter = 0;
@@ -72,11 +73,12 @@ export async function observeHlsPlaylists(page, options) {
         }
         seenUrls.add(url);
         // Assign the wire-arrival ordinal synchronously, immediately past the dedup gate and before the first await, so it reflects the order this response arrived
-        // rather than the order its body fetch resolves against every other in-flight fetch. The local rides through the fetch and is delivered on the observation.
+        // rather than the order its body fetch resolves against every other in-flight fetch. The local is carried across the fetch and is delivered on the observation.
         const sequence = ++sequenceCounter;
         LOG.debug(logCategory, "Observed .m3u8 response (seq %s): %s.", sequence, url.slice(0, 120));
+        const bound = timeoutSignal(MANIFEST_BODY_FETCH_TIMEOUT, { clock });
         try {
-            const response = await chromeFetch(url, { signal: AbortSignal.timeout(MANIFEST_BODY_FETCH_TIMEOUT) });
+            const response = await chromeFetch(url, { signal: bound.signal });
             if (!response.ok) {
                 LOG.debug(logCategory, "Manifest fetch returned HTTP %s for %s.", response.status, url.slice(0, 120));
                 return;
@@ -108,6 +110,9 @@ export async function observeHlsPlaylists(page, options) {
         catch (error) {
             LOG.debug(logCategory, "Could not fetch .m3u8 body: %s.", String(error));
         }
+        finally {
+            bound.cancel();
+        }
     };
     const tabObserver = await observeTabResponses(page, {
         onResponse: (response) => { void handleResponse(response.url); }

package/dist/browser/hlsPlaylistObserver.js.map

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

package/dist/browser/index.d.ts

@@ -1,16 +1,27 @@
 import type { Browser, LaunchOptions, Page } from "puppeteer-core";
+import type { BrowserPurpose, CaptureImpairment } from "./browserSupervisor.ts";
 import { clearLoginState, isLoginModeActive } from "./login.ts";
-import { getStream } from "puppeteer-stream";
+import { getAllStreams } from "../streaming/registry.ts";
+import { getCachedTabId } from "./tabSelection.ts";
+import type { Clock } from "homebridge-plugin-utils";
 import type { Nullable } from "../types/index.ts";
 import type { ProcessInfo } from "../utils/index.ts";
+import type { WindowPlacement } from "./cdp.ts";
 type CaptureProbe = (browser: Browser) => Promise<void>;
 /**
  * Injects the capture-readiness probe used as the capability tier of the launch gate. Called once from streaming/setup.ts at module load (which always precedes any
  * launch, since the streaming layer is imported during server startup). Separating the wiring from the call keeps browser/index.ts free of a streaming-layer import.
- * @param probe - The probe to run against a freshly-launched browser; it resolves when the browser can capture and rejects otherwise (or exits the process for the
- *   unrecoverable stale-mutex case).
+ * @param probe - The probe to run against a freshly-launched browser; it resolves when the browser can capture and rejects when it cannot.
  */
 export declare function setCaptureProbe(probe: CaptureProbe): void;
+type StreamTerminator = (streamId: number, channelName: string, reason: string) => void;
+/**
+ * Injects the authoritative stream terminator used when browser readiness is lost. Called once from streaming/lifecycle.ts at module load. Separating the wiring
+ * from the call keeps browser/index.ts free of a streaming-layer import.
+ * @param terminator - The function that tears down one stream and all of the resources it owns.
+ */
+export declare function setStreamTerminator(terminator: StreamTerminator): void;
+export type BrowserRestartCause = "impairment" | "maintenance";
 /**
  * Returns true if graceful shutdown is in progress.
  */
@@ -19,10 +30,63 @@ 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;
+/**
+ * Reports whether a page may carry a CDP command aimed at the shared window: it exists, it is still open, and it does not live in a window of its own. The
+ * parameter accepts the absent case so every caller narrows through this one test rather than guarding beside it.
+ * @param page - The candidate page, which may be absent.
+ * @returns True when the page can carry a shared-window command.
+ */
+export declare function isCarrierPage(page: Nullable<Page>): page is Page;
+/**
+ * Picks the page a shared-window command should travel on from the pages a browser has open, taking the first that qualifies.
+ * @param pages - The candidate pages, in the order the browser reports them.
+ * @returns The page to carry the command, or null when none of them qualifies.
+ */
+export declare function pickCarrierPage(pages: readonly Page[]): Nullable<Page>;
+/**
+ * Records which window the shared one is, reading it from a page that sits in it.
+ *
+ * This is the one way an identity is written. The launch path calls it once the launch-era pages exist, so every browser this process publishes carries the
+ * answer before anything asks for a capture tab, and a probe running against a browser of its own calls the same function rather than reaching for the map.
+ * @param browser - The browser whose shared window is being recorded.
+ * @param page - A page that sits in that window.
+ */
+export declare function noteSharedWindow(browser: Browser, page: Page): Promise<void>;
+/**
+ * Picks the page an opener-anchored tab should be opened from: one the browser has open, living in the shared window rather than a window of its own, and
+ * confirmed to sit in the window this process recorded.
+ *
+ * A plain-origin page is preferred over the capture extension's own options page, which is the carrier of last resort. The options page is recognized by the URL
+ * prefix its own pages carry rather than through the library's resolver, whose wait for a missing extension would spend thirty seconds inside a caller's turn.
+ * When no identity was ever recorded the confirmation has nothing to test against, and the first qualifying page is the answer: an anchor to some window of the
+ * browser's is still better than letting Chrome choose one.
+ * @param browser - The browser to resolve a carrier in.
+ * @returns The page to evaluate the open on, or null when none of the browser's pages qualifies.
+ */
+export declare function resolveSharedWindowCarrier(browser: Browser): Promise<Nullable<Page>>;
+/**
+ * Reports whether a page ended up in the shared window.
+ *
+ * Advisory when no identity was ever recorded: there is nothing to contradict the placement with, so the answer is true and the caller proceeds. A window that
+ * cannot be READ is the opposite answer, though, and deliberately so - the shared lookup reports undefined for a closed page, an empty response, and a CDP
+ * failure alike, and reading any of those as a confirmation would confirm a wrong-window tab in exactly the case this check exists for.
+ * @param page - The page to test.
+ * @returns True when the page sits in the recorded window, or when no window was ever recorded.
+ */
+export declare function confirmSharedWindowPlacement(page: Page): Promise<boolean>;
 export { clearLoginState, isLoginModeActive };
 export type { LoginStatus } from "./login.ts";
 export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, startLoginMode } from "./login.ts";
-export { BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.ts";
+export { BrowserCaptureImpairedError, BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.ts";
+export type { BrowserPurpose, CaptureImpairment } from "./browserSupervisor.ts";
+/**
+ * Brings the shared browser window into agreement with the visibility policy. This is the one entry point every layer uses - streaming, recovery, login,
+ * precaching, and startup all call it and none of them decide window state themselves.
+ * @param page - The page whose CDP session should carry the command, when the caller has one in hand. The executor falls back to any open page, or a temporary
+ * one, when it is omitted or the page has closed.
+ * @returns A promise that resolves once a pass that began at or after this call has completed.
+ */
+export declare function syncWindowVisibility(page?: Page): Promise<void>;
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -34,11 +98,12 @@ export declare function emitCurrentSystemStatus(): Promise<void>;
  * 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.
- * @param options - Registration options. Set inFlightSetup when stream setup owns the page but has not yet recorded that ownership in the stream registry, so the
- *   stale page cleanup never closes a page whose stream is still being established.
+ * @param options - Registration options. Set inFlight when an operation owns the page for its duration but nothing the stale page cleanup reads records that
+ *   ownership - a stream setup that has not yet written its page into the registry, or a discovery walk whose page belongs to no stream at all - so the cleanup
+ *   never closes a page out from under the operation driving it.
  */
 export declare function registerManagedPage(page: Page, options?: {
-    inFlightSetup?: boolean;
+    inFlight?: boolean;
 }): 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
@@ -118,51 +183,160 @@ export declare function getExecutablePath(): string;
  * - Pipe mode provides a faster, more reliable connection than WebSocket
  * @returns Puppeteer launch options.
  */
-export declare function buildLaunchOptions(): LaunchOptions;
-/**
- * Decides whether the window bounds the browser granted prove the display cannot show a whole captured frame, returning those bounds when they do and null
- * otherwise. Bounds the browser could not report, and bounds read while the window carried a state other than normal, describe a transient condition rather than
- * the display...treating either as evidence would let a CDP hiccup or an unfinished window transition pose as a small display, so both yield null. Beyond that,
- * either dimension falling below the capture surface is enough: a frame that does not fit the window in one axis is already a frame the screen cannot show whole.
- * @param bounds - The window bounds the browser reported, or undefined when the read did not complete.
- * @param captureSurface - The dimensions every page renders at, derived from the configured quality preset.
- * @returns The granted window dimensions when the display falls short of the capture surface, null otherwise.
- */
-export declare function getUndersizedDisplayBounds(bounds: {
-    height?: number;
-    width?: number;
-    windowState?: string;
-} | undefined, captureSurface: {
+export declare function buildLaunchOptions(): LaunchOptions & {
+    defaultViewport: null;
+};
+/**
+ * Emulates the capture surface on a page that is about to be captured: the configured quality preset's dimensions, declared at the pixel density the display
+ * actually has. Chrome composes an active tab's capture from the window presentation unless the page's device-metrics override declares a density explicitly
+ * and that density matches the display's real one, so the density is read from the page itself - a page carrying no declared density reports the display's own -
+ * and declared back before capture acquires the page. The declared dimensions are returned so the caller holds its capture constraints to the surface that was
+ * emulated rather than reading the preset a second time.
+ * @param page - The page to emulate the capture surface on.
+ * @returns The dimensions declared on the page.
+ */
+export declare function emulateCaptureSurface(page: Page): Promise<{
     height: number;
     width: number;
-}): Nullable<{
+}>;
+/**
+ * Emulates the layout surface on a page that is laid out but never captured: the configured quality preset's dimensions at the display's own density. The guide
+ * walks were written against that layout and the launch-gate capture probe acquires against it, so declaring it is what keeps both on the surface they were
+ * validated on. The density stays the display's, because nothing reads this page's pixels.
+ * @param page - The page to emulate the layout surface on.
+ * @returns The dimensions declared on the page.
+ */
+export declare function emulateLayoutSurface(page: Page): Promise<{
     height: number;
     width: number;
 }>;
 /**
- * Invalidates a specific browser that is still connected but can no longer capture - a mid-life capture death that no "disconnected" event would surface. This is the
- * single recovery action generalized to the alive-but-incapable case: relinquish readiness and terminate the browser's streams (exactly as a disconnect does),
- * then additionally close the still-running Chrome so a leaked process is not left behind. The lifecycle is already absent after relinquish, so the next request
- * relaunches a fresh, gate-verified browser through the supervisor. Exported for the streaming layer's passive mid-life detector to call once its probe confirms the
- * browser cannot capture. noteReadinessLost stays internal: callers signal intent through this function, never the supervisor directly.
+ * Derives the creation bounds for a window that should open exactly where an existing window rests. The four numbers always travel, so the new window lands on
+ * the same frame. The state travels only when it is "maximized", because that is the one state Chrome saves alongside the frame and a maximized window mirrored
+ * as a normal one would drop it. Every other state is left off deliberately: a fullscreen window's frame is its whole screen and a normal window at that frame
+ * is the right stand-in for it, and a minimized window reports the frame it will return to, which is a placement worth inheriting without the minimization.
+ * @param placement - The placement of the window to mirror.
+ * @returns The bounds to create the new window with.
+ */
+export declare function mirrorPlacement(placement: WindowPlacement): {
+    height: number;
+    left: number;
+    top: number;
+    width: number;
+    windowState?: "maximized";
+};
+/**
+ * Opens a page for a channel guide discovery walk in a browser window of its own, and marks it as belonging to that window.
+ *
+ * A document renders only while Chrome presents it: the active tab of a window the desktop is showing, or a page Chrome counts as captured. The shared window
+ * rests minimized whenever nothing is capturing and no sign-in holds it on screen, with its selected tab belonging to the user. A guide walk needs its page to
+ * render - an observer-driven channel rail fills its tiles from rendering updates, a virtualized grid re-renders as the walk scrolls it, and every wait the walk
+ * makes polls on the page's animation frames - yet it is never captured, so it has no claim on the shared window's presentation and no business moving the
+ * user's selection. A window of its own resolves the tab half: the page is that window's active tab from the moment it exists. The window is created in the
+ * background, so Chrome shows it inactive and moves no focus (measured 2026-08-31), and such a window's document is one Chrome does not present on its own: it
+ * reports itself hidden and unfocused and delivers no animation frame beyond a document load's first ones (measured 2026-09-13). Focus emulation resolves the
+ * presentation half, for the page's whole life - Puppeteer's own emulateFocusedPage carries the mechanism, on the page's own session.
+ *
+ * The window opens at the shared window's own placement, so the window placement Chrome persists for the profile never changes - readWindowPlacement carries
+ * the reasoning. The caller declares the layout surface on the page and owns its registration, and closing the page closes the window with it.
+ * @param browser - The browser to open the window in.
+ * @returns The page, as the active tab of its own window.
+ */
+export declare function createDiscoveryPage(browser: Browser): Promise<Page>;
+/**
+ * Builds the callback the page's focus binding invokes: an immediate re-issue, then a ladder of follow-ups at ACTIVATION_REAFFIRM_LADDER_MS's offsets from this
+ * invocation. The ladder is what makes the heal land, because the compositor's switch outlasts the focus event announcing it - the immediate shot alone cannot
+ * reach the far side of the switch, so later shots have to.
  *
- * The caller passes the exact instance it verified, and we invalidate only if it is still the published browser. The detector's probe runs in the background for
- * seconds, during which the verified browser could have disconnected and been replaced by a fresh relaunch; without this identity guard we would tear down that
- * new, healthy browser on the strength of a probe against the old, dead one.
- * @param browser - The specific browser instance the caller verified as unable to capture.
- * @param reason - A short description of why the browser is being invalidated, for the alarm log.
+ * Invocations supersede rather than accumulate. A generation counter makes the newest invocation the owner of the rung schedule: the duplicate focus events a
+ * single activation fires collapse into one schedule a few milliseconds newer than the first, while an activation that genuinely arrives later - a second
+ * stream's tab give-back landing on this page, another click - gets a full bracket timed from its own moment instead of inheriting the tail of an in-flight one.
+ * The counter lives in this closure, so a callback supersedes only the ladders it started itself and two streams' pages cannot reach each other's schedules.
+ *
+ * Nothing cancels a superseded ladder, because nothing has to: it returns at its next generation check, a shot against a page mid-teardown rejects into the
+ * swallow below, and a shot that never settles leaves its ladder awaiting a promise nobody holds. The counter needs no reset for the same reason - a newer
+ * invocation is itself the invalidation - and the schedule holds no timers, only awaited sleeps.
+ *
+ * A rejection is swallowed into a debug line because a focus event races page teardown by nature - the tab a user just selected can be the one a terminating
+ * stream is closing - and the periodic re-affirmation corrects anything a lost re-issue leaves behind.
+ * @param page - The capture page this callback re-affirms.
+ * @param reaffirm - The re-issue to invoke. A parameter rather than a direct call so the callback's behavior can be driven on its own: what it does with the page
+ *                   it was built for, what schedule it keeps, and what it does with a rejection, is the whole of its contract.
+ * @param clock - The time source the ladder's waits run on. Defaults to the system clock.
+ * @returns The callback, which never rejects. Its promise settles once the ladder is spent, which the page-side listener does not wait on.
+ */
+export declare function makeFocusReaffirmCallback(page: Page, reaffirm: (page: Page) => Promise<void>, clock?: Clock): () => Promise<void>;
+/**
+ * The collaborators a page's heal is built from: the time source its ladder's waits run on, and the re-issue each of its shots performs. Injected as a default
+ * parameter in the shape CreatePageWithCaptureDeps, TabCaptureDeps, FullscreenDeps, and PrecachingDeps already use, so a test drives the enrolled callback through
+ * the install point itself rather than around it. The port holds no state, and production call sites pass nothing.
+ */
+export interface ActivationHealDeps {
+    readonly clock: Clock;
+    readonly reaffirm: (page: Page) => Promise<void>;
+}
+/**
+ * Installs the tab-activation heal on a capture page. Chrome composes the capture of a selected tab from the window's fitted presentation, so the instant a
+ * capture tab becomes the selected one that capture starts recording a clipped view of itself; the re-issue ladder this installs moves the composition back to
+ * the emulated surface about a second later.
+ *
+ * The heal has two triggers and one ladder between them. The exposed binding is fired by a focus listener inside the page, which covers the activation that
+ * arrives with a user's click focusing the browser window. The enrollment in activationHeals is fired by the selection primitive's activation report, which
+ * covers every activation PrismCast performs for itself - the give-back returning a user to a capture tab, the selection step, a re-assert - and a captured page
+ * hears none of those: capture holds it visible and the extension's update moves no operating-system focus, so no page event fires at all (measured 2026-08-30).
+ * Both triggers hold the same callback instance, which is what lets them share its generation counter instead of running two schedules against one page.
+ *
+ * The listener is registered through evaluateOnNewDocument so it survives the page's navigations, exactly as the shared video-selector helper does, and the
+ * binding survives them on Puppeteer's own terms.
+ * @param page - The capture page to install the heal on.
+ * @param deps - The clock and the re-issue the ladder runs on. Defaults to the production pair.
+ */
+export declare function installActivationHeal(page: Page, deps?: ActivationHealDeps): Promise<void>;
+/**
+ * Heals the capture page showing in a tab the selection primitive has just activated.
+ *
+ * The report names a tab and what needs healing is a page, so the match walks the registry for a capture-mode stream whose page was identified as that tab. A
+ * report matching nothing is the ordinary case rather than a failure - a give-back returning the selection to the user's own tab, a native stream that composes
+ * no capture at all, a page registered before its setup reached the install point - and every one of them is a quiet no-op.
+ * @param tabId - The tab the selection primitive activated.
+ * @param deps - The registry read and the page-to-tab lookup the match runs through. Defaults to the production pair.
+ */
+export declare function healActivatedCaptureTab(tabId: number, deps?: {
+    readonly getAllStreams: typeof getAllStreams;
+    readonly getCachedTabId: typeof getCachedTabId;
+}): void;
+/**
+ * Records that a still-connected browser can no longer start captures - a mid-life capture death that no "disconnected" event would surface - and runs the
+ * relaunch that cures it. This is the single recovery action for a browser that is alive and still serving: the mark lives on the supervisor's ready state, so its
+ * running captures continue untouched, new stream requests are refused at acquire() with a 503 back-off, the recovery ladder stops offering tab replacement, and
+ * the relaunch waits until nothing depends on the browser. Exported for the streaming layer to call once its probe or its wedge has produced the verdict.
+ *
+ * The returned promise settles once the relaunch this mark triggered has settled, which is what a caller that means to use the fresh browser awaits: the teardown
+ * holds the supervisor in its draining state, where acquire() rejects rather than joins, so acquiring any earlier draws that rejection instead of the new
+ * instance. A caller with nothing waiting on the outcome voids it and the relaunch proceeds on its own.
+ *
+ * The restart trigger uses this function's return value rather than the supervisor's transition observer, deliberately. The observer runs inside transition(), so a
+ * restart begun there would call noteReadinessLost re-entrantly while the marking transition's notification is still on the stack. The observer stays a reporter -
+ * the alarm and the status emit - and the caller that holds the verdict acts on it once the transition has completed.
+ * @param browser - The specific browser instance the caller verified as unable to start captures.
+ * @param reason - A short description of the evidence behind the verdict, carried in the alarm log and the impairment record.
+ * @returns A promise settling once the relaunch this mark triggered has settled, or at once when the verdict landed on nothing.
  */
-export declare function invalidateBrowser(browser: Browser, reason: string): Promise<void>;
+export declare function noteBrowserCaptureImpaired(browser: Browser, reason: string): Promise<void>;
 /**
  * Provides access to the capture-ready browser, launching one if needed. This is the single gated entry point for all browser access: it delegates to the
  * supervisor's acquire(), which returns the ready browser, joins an in-flight launch (single-flight, so concurrent callers never contend on Chrome's profile lock),
  * lazily launches when absent, or - while the relaunch governor is cooling after repeated failures - rejects fast with a BrowserUnavailableError WITHOUT spawning
  * Chrome (the loop bound). The launch it drives runs the readiness gate, so a returned browser is verified capture-ready, not merely connected.
+ *
+ * The purpose is what the caller intends to do with the browser, and it is the gate on a marked one: a "capture" caller is refused, because that is precisely the
+ * operation the browser can no longer perform, while a "page" caller - precaching, the startup warm-up, the relaunch itself - is served as usual.
+ * @param purpose - Whether the caller goes on to start a capture or only needs a page to open.
  * @returns The capture-ready browser instance.
- * @throws BrowserUnavailableError while the governor is cooling, BrowserSupersededError if an in-flight launch was abandoned by a readiness-loss, or the underlying
- *   launch error when a launch attempt fails.
+ * @throws BrowserUnavailableError while the governor is cooling, BrowserCaptureImpairedError when a capture purpose meets a browser that can no longer start
+ *   captures, BrowserSupersededError if an in-flight launch was abandoned by a readiness-loss, or the underlying launch error when a launch attempt fails.
  */
-export declare function getCurrentBrowser(): Promise<Browser>;
+export declare function getCurrentBrowser(purpose: BrowserPurpose): 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.
@@ -174,19 +348,18 @@ export declare function getChromeVersion(): Nullable<string>;
  * @returns The browser instance, or null if not running.
  */
 export declare function getBrowserInstance(): Nullable<Browser>;
+/**
+ * Returns the impairment recorded on the published browser, or null when nothing is published or the published browser can still start captures. Like
+ * getBrowserInstance this does not launch, so callers that only need to know whether captures can be started - the recovery ladder, the status composition, the
+ * health endpoint - read it without touching the lifecycle.
+ * @returns The impairment record, or null.
+ */
+export declare function getCaptureImpairment(): Nullable<CaptureImpairment>;
 /**
  * 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;
-/**
- * Minimizes the browser window. The window's presentation state is all this touches - the surface pages render at is emulated from the configured preset and is
- * unaffected by whether the window is on screen.
- *
- * 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.
  * @returns Array of pages, or empty array if the browser is not connected.
@@ -204,29 +377,70 @@ export declare function closeBrowser(): Promise<void>;
  *
  * The cleanup uses a multi-stage filtering process:
  * 1. Only consider pages we created (in managedPageIds)
- * 2. Exclude pages associated with active streams, and pages whose stream setup is still in flight
+ * 2. Exclude pages associated with active streams, and pages an operation still holds in flight
  * 3. Apply a grace period before closing (to handle race conditions)
  * 4. Preserve at least one page to keep the browser alive
+ * @param now - The instant the sweep judges staleness against, read from the interval's own clock so the staleness clocks this sweep starts and the ones it
+ * later reads are stamped on one time source.
  */
-export declare function cleanupStalePages(): Promise<void>;
+export declare function cleanupStalePages(now: number): 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).
+ * Starts the periodic stale page cleanup. This should be called once during server startup, after the browser is initialized. The sweep runs indefinitely until
+ * stopStalePageCleanup() is called (typically during graceful shutdown). A second start while one is running changes nothing.
+ * @param clock - The clock the sweep's interval arms on and whose reading each sweep judges staleness against, so the cadence and the judgment share one time
+ * source. Defaults to the system clock.
  */
-export declare function startStalePageCleanup(): void;
+export declare function startStalePageCleanup(clock?: Clock): 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.
+ * Stops the periodic stale page cleanup. This should be called during graceful shutdown to prevent the sweep from running after we've started shutting down the
+ * browser and streams. Disposing the registry drains the interval, and a stop with nothing running is a no-op.
  */
 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).
+ * The registry facts a restart's idleness decision is made from. One shape, read by readRestartFacts and judged by isBrowserIdleForRestart, so the decision stays
+ * a pure function of stated facts rather than of whatever each guard happened to read.
+ */
+interface RestartFacts {
+    readonly establishedStreams: boolean;
+    readonly inFlightPages: number;
+    readonly streamCount: number;
+}
+/**
+ * Decides whether the browser may be torn down for the given cause, from facts read at the call. Each cause asks a different question of the same registry, so
+ * the decision is stated once here rather than spelled out at each guard.
+ *
+ * Maintenance is opportunistic housekeeping, so it waits for an empty registry outright: a pending entry is a tune in progress, and replacing the browser under
+ * one would fail it for nothing better than a fresher instance. Impairment is a repair the tunes themselves are waiting on, so it asks the narrower question of
+ * what a teardown would actually destroy - a stream established on this browser, whose entry holds its page, or a page an operation still holds in flight. A tune
+ * refused a capture start holds neither while it waits for the relaunch, so the very pending entry that maintenance would defer to is not a reason to leave an
+ * unusable browser in place. A tune that has acquired the browser but not yet opened its page falls outside every dependency source for the same reason and
+ * deliberately so: it holds nothing a relaunch would destroy, neither a page nor a capture, and its own capture start would meet the impaired browser in any
+ * case, so the relaunch may run under it.
+ * @param cause - Why the restart wants to run.
+ * @param facts - The registry facts read at the call.
+ * @returns True when the browser may be torn down for this cause.
+ */
+export declare function isBrowserIdleForRestart(cause: BrowserRestartCause, facts: RestartFacts): boolean;
+/**
+ * Relaunches a browser that can no longer start captures, as soon as nothing depends on it. Every trigger routes here - the mark itself, each stream termination,
+ * and the periodic restart check as the backstop for a moment when the other two could not act (login mode above all) - so the decision lives in one place rather
+ * than being re-derived by each. Idleness rather than age is the condition, because the mark makes the browser useless for new tunes immediately while its running
+ * captures are still worth finishing, so the earliest safe moment is exactly the moment the last thing depending on this browser lets go of it.
+ *
+ * The returned promise settles once the relaunch has settled, for the caller that goes on to acquire the fresh browser; a trigger with nothing waiting on the
+ * outcome voids it. An early return resolves at once, because there is nothing for such a caller to wait for.
+ * @returns A promise settling once the relaunch has settled, or at once when no relaunch runs.
+ */
+export declare function restartBrowserIfImpairedAndIdle(): Promise<void>;
+/**
+ * Starts the periodic browser restart eligibility check. This should be called once during server startup, after the browser is initialized. The check runs
+ * indefinitely until stopBrowserRestartChecking() is called (typically during graceful shutdown). A second start while one is running changes nothing.
+ * @param clock - The clock the check's interval and the quiet period it arms both run on. Defaults to the system clock.
  */
-export declare function startBrowserRestartChecking(): void;
+export declare function startBrowserRestartChecking(clock?: Clock): 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.
+ * Stops the periodic browser restart eligibility check. This should be called during graceful shutdown to prevent a restart from racing with server shutdown.
+ * Disposing the registry drains the check and any pending quiet period together, and a stop with nothing running is a no-op.
  */
 export declare function stopBrowserRestartChecking(): void;
 /**
@@ -237,5 +451,5 @@ export declare function stopBrowserRestartChecking(): void;
  * @throws If extension extraction fails.
  */
 export declare function prepareExtension(): Promise<void>;
-export { getStream };
-//# sourceMappingURL=index.d.ts.map
+export { acquireCaptureStream } from "./tabCapture.ts";
+export type { CaptureStream, CaptureStreamOptions } from "./tabCapture.ts";