prismcast 1.12.0 → 1.13.0

package/dist/browser/tabCapture.d.ts

@@ -0,0 +1,97 @@
+import { getExtensionPage, wss } from "puppeteer-stream";
+import type { Clock } from "homebridge-plugin-utils";
+import type { Page } from "puppeteer-core";
+import type { Readable } from "node:stream";
+import { withTabSelected } from "./tabSelection.ts";
+export declare const EXTENSION_READY_EXPRESSION = "typeof START_RECORDING === 'function'";
+export declare const ACTIVE_TAB_GRANT_PENDING_MESSAGE = "has not been invoked for the current page";
+export declare const EXTENSION_NOT_READY_MESSAGE = "The capture extension is not ready on this browser.";
+export declare const ACTIVE_TAB_GRANT_POLL_MS = 50;
+export declare const ACTIVE_TAB_GRANT_CEILING_MS = 1000;
+export declare const CAPTURE_FRAME_SIZE_MS = 20;
+export declare const CAPTURE_STREAM_HIGH_WATER_MARK: number;
+/**
+ * The dimension and frame-rate bounds a capture track is held to. Chrome reads these as tabCapture's mandatory media constraints, which is what holds the encoder
+ * to the surface the page was emulated at rather than to whatever the window happens to be showing.
+ */
+export interface CaptureVideoConstraints {
+    readonly mandatory: {
+        readonly maxFrameRate: number;
+        readonly maxHeight: number;
+        readonly maxWidth: number;
+        readonly minFrameRate: number;
+        readonly minHeight: number;
+        readonly minWidth: number;
+    };
+}
+/**
+ * What a caller asks a capture for. videoConstraints is required rather than optional because every caller supplies one and it is the only thing tying the
+ * encoder to the emulated surface; a capture acquired without it would silently compose whatever the window was presenting.
+ */
+export interface CaptureStreamOptions {
+    readonly audio: boolean;
+    readonly audioBitsPerSecond?: number;
+    readonly mimeType: string;
+    readonly video: boolean;
+    readonly videoBitsPerSecond?: number;
+    readonly videoConstraints: CaptureVideoConstraints;
+}
+/**
+ * The settings object the extension's START_RECORDING receives, mirroring the RecordingOptions type in the extension's own source field for field.
+ *
+ * One divergence is deliberate. The extension annotates audioBitsPerSecond, videoBitsPerSecond, and bitsPerSecond as required numbers, but it hands all three
+ * straight to MediaRecorder, where an absent value selects the recorder's own default - and the readiness probe passes none of them and captures perfectly well.
+ * So this type declares what the protocol tolerates rather than what the extension's annotation over-claims, and the settings-shape test asserts the field NAMES
+ * against the extension's source so a genuine protocol change still fails loudly.
+ */
+export interface ExtensionRecordingSettings {
+    audio: boolean;
+    audioBitsPerSecond?: number;
+    audioConstraints?: CaptureVideoConstraints;
+    bitsPerSecond?: number;
+    delay?: number;
+    frameSize: number;
+    index: number;
+    mimeType: string;
+    tabId: number;
+    video: boolean;
+    videoBitsPerSecond?: number;
+    videoConstraints?: CaptureVideoConstraints;
+}
+/**
+ * A live capture: the readable stream of recorder chunks, plus the two members that let an owner end it and know when the ending is complete.
+ */
+export interface CaptureStream extends Readable {
+    stop(): Promise<void>;
+    readonly stopped: Promise<void>;
+}
+/**
+ * The collaborators this module talks through, injected so a test can drive the whole acquisition without a browser or a listening socket: the two library values
+ * and the tab-selection primitive whose hold the acquisition runs inside.
+ */
+export interface TabCaptureDeps {
+    readonly getExtensionPage: typeof getExtensionPage;
+    readonly withTabSelected: typeof withTabSelected;
+    readonly wss: typeof wss;
+}
+/**
+ * Per-call context for an acquisition: the clock its waits run on and the collaborators it talks through.
+ */
+export interface AcquireCaptureStreamContext {
+    readonly clock?: Clock;
+    readonly deps?: TabCaptureDeps;
+}
+export declare const defaultTabCaptureDeps: TabCaptureDeps;
+/**
+ * Acquires a tab capture for a page: one started recording, its chunks arriving as a readable stream, and the two controls that end it.
+ *
+ * Exactly one start is made. A start Chrome refuses with "Could not start video source" is logged once with the window's reported state and the selected tab, so
+ * the refusal explains itself, and then fails the acquisition unchanged; whether that refusal is the browser's fault and what should follow are the
+ * establishment's to decide from its capture probe. Every other rejection fails the acquisition the same way, with no log of its own.
+ * @param page - The page to capture.
+ * @param options - What the capture is asked for.
+ * @param context - The clock and collaborators. Defaults to the production collaborators on the real clock.
+ * @returns The started capture.
+ * @throws When the extension is not ready, its tab cannot be selected, or the start fails.
+ */
+export declare function acquireCaptureStream(page: Page, options: CaptureStreamOptions, context?: AcquireCaptureStreamContext): Promise<CaptureStream>;

package/dist/browser/tabCapture.js

@@ -0,0 +1,314 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * tabCapture.ts: PrismCast's own conversation with the capture extension.
+ *
+ * Starting a tab capture is four steps against the browser: select the page's tab through the capture extension and hold it, send the keyboard command that grants
+ * the extension its activeTab permission for that tab, hand the extension a settings object it turns into a MediaRecorder feeding a WebSocket, and give the tab
+ * that was selected before back. Every piece those steps need - the extension's options page, the WebSocket server, the browser launch - is exported by
+ * puppeteer-stream, so PrismCast speaks the protocol itself rather than through a convenience wrapper, and three things follow from that.
+ *
+ * There is one capture lock in this process, and streaming/setup.ts owns it. A wrapper that carries a lock of its own would serialize the same work twice, and a
+ * rejection escaping such a lock's unguarded section leaves it held for the life of the process - a condition no Chrome restart can clear, because the state is
+ * in Node rather than in the browser. Owning the start means the only serialization is the one whose deadline, abort signal, and wedge policy the caller already
+ * controls.
+ *
+ * A rejected start is reported rather than judged. Chrome answers a start it cannot serve with "Could not start video source", and the whole response here is one
+ * warning carrying the window and selected-tab state that explains it, read while that tab is still selected, with the rejection travelling to the caller
+ * unchanged. What such a refusal says about the browser is the establishment's question, settled by its capture probe, so this layer holds no retry policy of its
+ * own. The activeTab grant is the one wait that does belong here: rather than sleeping a fixed interval after the keyboard command and hoping the grant landed,
+ * the start is attempted and Chrome's own "has not been invoked for the current page" answer drives a short poll, so a grant that lands immediately costs nothing.
+ *
+ * The coupling this module takes on is the extension's protocol, and it is asserted rather than trusted: tabCapture.test.ts fingerprints the three library files
+ * this module was written against and derives the settings-object shape from the extension's own source, so a dependency bump that changes either fails the
+ * suite with instructions rather than failing a capture in the field.
+ */
+import { LOG, formatError, pollUntil, startTimer } from "../utils/index.js";
+import { getExtensionPage, wss } from "puppeteer-stream";
+import { CAPTURE_SOURCE_UNAVAILABLE_MESSAGE } from "../types/index.js";
+import { PassThrough } from "node:stream";
+import { readWindowState } from "./cdp.js";
+import { systemClock } from "homebridge-plugin-utils";
+import { withTabSelected } from "./tabSelection.js";
+// Constants.
+// The extension's readiness predicate, stated once. The launch gate waits on it before publishing a browser, and the acquisition asserts it before preparing an
+// attempt, so both ask the same question of the same page.
+export const EXTENSION_READY_EXPRESSION = "typeof START_RECORDING === 'function'";
+// Chrome's rejection text when the extension's activeTab grant has not landed for the page yet. The keyboard command that grants it is asynchronous, so this
+// answer means "ask again shortly" rather than "this cannot work".
+export const ACTIVE_TAB_GRANT_PENDING_MESSAGE = "has not been invoked for the current page";
+// The failure when a browser is serving without a loaded capture extension. The launch gate establishes readiness before a browser is published, so reaching
+// this means the extension went away underneath a published browser.
+export const EXTENSION_NOT_READY_MESSAGE = "The capture extension is not ready on this browser.";
+// The cadence between start attempts while Chrome is still reporting the activeTab grant pending, and the ceiling on that wait. A grant that lands with the
+// keyboard command costs one attempt and no wait at all; the ceiling bounds the case where it never lands, so the caller sees Chrome's own message rather than
+// a hang. One attempt is a handful of CDP round trips - the selection re-assert, the five key events, the start - taken inside a selection held across the whole
+// poll, so the ceiling is sized to afford several of them rather than to a multiple of the cadence alone.
+export const ACTIVE_TAB_GRANT_POLL_MS = 50;
+export const ACTIVE_TAB_GRANT_CEILING_MS = 1000;
+// The recorder's timeslice in milliseconds - how often the extension's MediaRecorder hands a chunk to its socket. A browser-side recorder setting rather than a
+// wait of ours, at the value the capture pipeline was tuned against.
+export const CAPTURE_FRAME_SIZE_MS = 20;
+// The capture stream's buffer ceiling. Chrome delivers bursty multi-megabyte chunks on keyframes, so the buffer is sized to absorb a burst without the socket's
+// writes backing up into the recorder.
+export const CAPTURE_STREAM_HIGH_WATER_MARK = 8 * 1024 * 1024;
+/**
+ * A start Chrome refused, carrying the state that explains the refusal. The state is read while the capture's tab is still selected, which is the only moment it
+ * describes the conditions the start actually ran under. Chrome's own refusal text is the message, so the capture-infrastructure classifier and the
+ * establishment's refusal test both keep matching on it.
+ *
+ * Module-private on purpose: the judgment "this is a capture-infrastructure failure" belongs to one mechanism, the pattern list in streaming/recovery.ts, which
+ * reads the message. This class is the internal typed carrier for the diagnostics that travel alongside it, not a second way to ask the same question.
+ */
+class CaptureStartRefusedError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.diagnostics = diagnostics;
+        this.name = "CaptureStartRefusedError";
+    }
+}
+// The production collaborators.
+export const defaultTabCaptureDeps = { getExtensionPage, withTabSelected, wss };
+// The socket index each capture publishes under. It only ever moves forward, so no two captures in this process - including two attempts of the same
+// acquisition - can be confused for one another on the shared server.
+let nextCaptureIndex = 0;
+// Acquisition.
+/**
+ * Normalizes anything thrown into an Error. Puppeteer delivers a page-side exception that is not an Error object as the primitive itself, and the extension
+ * rejects its capture-start with a bare string, so a rethrow that assumed an Error would strip the only diagnostic there was.
+ * @param error - The thrown value.
+ * @returns The value itself when it is already an Error, otherwise an Error carrying its formatted text.
+ */
+function toError(error) {
+    return (error instanceof Error) ? error : new Error(formatError(error));
+}
+/**
+ * Prepares one start attempt: a fresh socket index, a fresh stream, and a connection handler registered on the server BEFORE the extension is invoked. The
+ * ordering is required, not tidy - START_RECORDING opens its socket before it asks Chrome for the capture, so a handler registered afterwards would miss the
+ * connection, and a start that goes on to fail still connects a socket for its index.
+ * @param server - The WebSocket server the extension connects back to.
+ * @returns The prepared attempt.
+ */
+function prepareAttempt(server) {
+    const index = nextCaptureIndex++;
+    const stream = new PassThrough({ highWaterMark: CAPTURE_STREAM_HIGH_WATER_MARK });
+    // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- Standard pattern for signal promises.
+    const stopped = Promise.withResolvers();
+    const attempt = {
+        index,
+        onConnection: (socket, request) => {
+            // The extension names the capture it is connecting for in the query string. Any other index belongs to another capture's handler.
+            if (new URL(request.url ?? "/", "http://localhost").searchParams.get("index") !== String(index)) {
+                return;
+            }
+            attempt.socket = socket;
+            socket.on("message", (data) => {
+                if (!stream.destroyed && !stream.writableEnded) {
+                    stream.write(data);
+                }
+            });
+            socket.on("close", () => {
+                if (!stream.destroyed && !stream.writableEnded) {
+                    stream.end();
+                }
+                // The extension closes its socket only after the recorder stopped and its pending sends drained, so this close is the completion signal an owner waits
+                // on before closing the page out from under it.
+                stopped.resolve();
+                server.off("connection", attempt.onConnection);
+            });
+        },
+        socket: null,
+        stopped,
+        stream
+    };
+    server.on("connection", attempt.onConnection);
+    return attempt;
+}
+/**
+ * Discards an attempt that did not start: its listener comes off the server, its socket is closed if the extension managed to open one, its stream is destroyed,
+ * and its completion signal settles. Nothing of a failed attempt outlives this call, which is what lets the next attempt begin from a clean server.
+ * @param server - The WebSocket server the attempt registered on.
+ * @param attempt - The attempt to discard.
+ */
+function discardAttempt(server, attempt) {
+    server.off("connection", attempt.onConnection);
+    attempt.socket?.close();
+    attempt.stream.destroy();
+    attempt.stopped.resolve();
+}
+/**
+ * Sends the keyboard command the extension's manifest binds, which is the extension's documented way of being invoked and grants it activeTab permission for the
+ * selected tab. On current Chrome the allowlist flag the launch passes already grants what this grants - a capture with no command ever sent succeeded, measured
+ * 2026-08-30 - so this is kept as the documented path rather than as the thing that makes capture work, and it is only ever aimed at the tab the hold selected.
+ * @param page - The page the capture is being acquired for.
+ */
+async function grantActiveTab(page) {
+    const modifier = (process.platform === "darwin") ? "Meta" : "Control";
+    await page.keyboard.down(modifier);
+    await page.keyboard.down("Shift");
+    await page.keyboard.press("KeyY");
+    await page.keyboard.up("Shift");
+    await page.keyboard.up(modifier);
+}
+/**
+ * Runs one START_RECORDING evaluate against the extension for a prepared attempt.
+ * @param extension - The extension's options page.
+ * @param attempt - The prepared attempt whose index and stream the recording feeds.
+ * @param options - What the caller asked the capture for.
+ * @param tabId - The tab Chrome will capture.
+ */
+async function startRecording(extension, attempt, options, tabId) {
+    const settings = {
+        audio: options.audio,
+        audioBitsPerSecond: options.audioBitsPerSecond,
+        frameSize: CAPTURE_FRAME_SIZE_MS,
+        index: attempt.index,
+        mimeType: options.mimeType,
+        tabId,
+        video: options.video,
+        videoBitsPerSecond: options.videoBitsPerSecond,
+        videoConstraints: options.videoConstraints
+    };
+    await extension.evaluate((recording) => START_RECORDING(recording), settings);
+}
+/**
+ * Attempts one start, waiting out an activeTab grant that has not landed yet. The keyboard command that grants the permission is asynchronous, so rather than
+ * sleeping a fixed interval and hoping, this attempts the start and reads Chrome's own answer: "has not been invoked for the current page" means ask again on
+ * the cadence, anything else is this attempt's verdict. A grant already in place costs exactly one attempt and no wait.
+ *
+ * The whole poll runs inside ONE tab selection. Chrome records whichever tab is selected, so the selection has to hold across every attempt, and taking it once
+ * means the user's tab is handed back once rather than flickering per attempt. Each attempt re-asserts the selection before it acts, so a login page opening or a
+ * user's click between attempts is corrected rather than recorded.
+ *
+ * Each poll iteration prepares a wholly fresh attempt and discards it before the next, so no listener, socket, or index is ever reused across a refusal.
+ * @param page - The page to capture.
+ * @param options - What the caller asked the capture for.
+ * @param collaborators - The extension page, the socket server, the clock the cadence runs on, and the deps the selection is taken through.
+ * @param collaborators.clock - The clock driving the grant cadence.
+ * @param collaborators.deps - The injected collaborators, read for the tab-selection primitive.
+ * @param collaborators.extension - The extension's options page.
+ * @param collaborators.server - The WebSocket server the extension connects back to.
+ * @returns The attempt that started.
+ * @throws The last grant-pending rejection when the ceiling lapses, or the attempt's own rejection for any other failure.
+ */
+async function acquireOnce(page, options, collaborators) {
+    const { clock, deps, extension, server } = collaborators;
+    return deps.withTabSelected(page, async (selected) => {
+        const runAttempt = async () => {
+            const attempt = prepareAttempt(server);
+            try {
+                await selected.reassert();
+                await grantActiveTab(page);
+                await startRecording(extension, attempt, options, selected.id);
+                return { attempt, kind: "started" };
+            }
+            catch (error) {
+                discardAttempt(server, attempt);
+                if (formatError(error).includes(ACTIVE_TAB_GRANT_PENDING_MESSAGE)) {
+                    return { error, kind: "grant-pending" };
+                }
+                /* Every other rejection is this attempt's verdict, and the window state that explains it is only truthful while the capture's tab is still selected -
+                 * which is here, inside the hold, rather than after it has been handed back. The read is best-effort by construction, so a diagnostic can never replace
+                 * the failure it describes.
+                 */
+                const windowState = await readWindowState(page);
+                throw new CaptureStartRefusedError(formatError(error), { activeTab: selected.url, windowState });
+            }
+        };
+        const outcome = await pollUntil({ cadenceMs: ACTIVE_TAB_GRANT_POLL_MS, ceilingMs: ACTIVE_TAB_GRANT_CEILING_MS, clock, read: runAttempt,
+            until: (result) => result.kind === "started" });
+        if (outcome.value.kind === "grant-pending") {
+            throw toError(outcome.value.error);
+        }
+        return outcome.value.attempt;
+    });
+}
+/**
+ * Attaches the two capture-control members to a started attempt's stream, producing the CaptureStream its owner holds.
+ * @param attempt - The attempt that started.
+ * @param extension - The extension's options page, which STOP_RECORDING is evaluated against.
+ * @param server - The WebSocket server the attempt registered on.
+ * @returns The owner-facing capture stream.
+ */
+function attachCaptureControls(attempt, extension, server) {
+    let stopping = false;
+    const requestStop = async () => {
+        // The stop request has to reach a browser that is still listening. When it is already gone the recording is gone with it, so this is the one path where
+        // asking is pointless rather than merely best-effort.
+        if (!extension.isClosed() && extension.browser().connected) {
+            try {
+                await extension.evaluate((index) => STOP_RECORDING(index), attempt.index);
+            }
+            catch (error) {
+                LOG.debug("browser:lifecycle", "The capture extension did not accept the stop request: %s.", formatError(error));
+            }
+        }
+        server.off("connection", attempt.onConnection);
+        // A capture whose socket never connected has no close event coming, so its completion signal settles here rather than waiting for one that cannot arrive.
+        if (!attempt.socket) {
+            attempt.stopped.resolve();
+        }
+    };
+    /* stop() is deliberately not async: every call has to hand back the SAME promise object, because the completion an owner waits on is the capture's, not this
+     * call's. The request itself goes out once, guarded by the flag, and its own failures are swallowed inside requestStop so this promise never rejects.
+     */
+    const stop = () => {
+        if (!stopping) {
+            stopping = true;
+            void requestStop();
+        }
+        return attempt.stopped.promise;
+    };
+    return Object.assign(attempt.stream, { stop, stopped: attempt.stopped.promise });
+}
+/**
+ * Acquires a tab capture for a page: one started recording, its chunks arriving as a readable stream, and the two controls that end it.
+ *
+ * Exactly one start is made. A start Chrome refuses with "Could not start video source" is logged once with the window's reported state and the selected tab, so
+ * the refusal explains itself, and then fails the acquisition unchanged; whether that refusal is the browser's fault and what should follow are the
+ * establishment's to decide from its capture probe. Every other rejection fails the acquisition the same way, with no log of its own.
+ * @param page - The page to capture.
+ * @param options - What the capture is asked for.
+ * @param context - The clock and collaborators. Defaults to the production collaborators on the real clock.
+ * @returns The started capture.
+ * @throws When the extension is not ready, its tab cannot be selected, or the start fails.
+ */
+export async function acquireCaptureStream(page, options, context = {}) {
+    const { clock = systemClock, deps = defaultTabCaptureDeps } = context;
+    const acquisitionElapsed = startTimer(clock);
+    const extension = await deps.getExtensionPage(page.browser());
+    const server = await deps.wss;
+    /* The launch gate already established the extension's readiness before this browser was published, so this asks once rather than retrying: reaching it means
+     * the extension went away underneath a published browser, which is a fault to report rather than a condition to wait out. It reads the same statement of the
+     * predicate the gate waits on.
+     */
+    const ready = await extension.evaluate(EXTENSION_READY_EXPRESSION);
+    if (ready !== true) {
+        throw new Error(EXTENSION_NOT_READY_MESSAGE);
+    }
+    try {
+        const started = await acquireOnce(page, options, { clock, deps, extension, server });
+        const stream = attachCaptureControls(started, extension, server);
+        /* Both close paths end the recording. The owner's disposer destroys the stream, which emits close; a page that dies takes its capture with it and fires
+         * the page's own close. Registering here rather than inside the socket handler means a capture whose socket never connected still stops cleanly.
+         */
+        page.once("close", () => { void stream.stop(); });
+        stream.once("close", () => { void stream.stop(); });
+        LOG.debug("timing:startup", "Capture acquired in %dms.", acquisitionElapsed());
+        return stream;
+    }
+    catch (error) {
+        /* Chrome's refusal earns a line of its own, because the state it was read under is recoverable nowhere else: the window's reported state and the tab the
+         * start was aimed at were gathered inside the hold, while that tab was still the selected one, and by the time this rejection reaches any other layer the
+         * selection is back where the user left it. A refusal that arrives without that state is one no selection was live for, so its fields are simply absent.
+         * The line reports and nothing more - the acquisition draws no conclusion about the browser from a single refusal.
+         */
+        if (formatError(error).includes(CAPTURE_SOURCE_UNAVAILABLE_MESSAGE)) {
+            const diagnostics = (error instanceof CaptureStartRefusedError) ? error.diagnostics : { activeTab: null, windowState: null };
+            LOG.warn("Chrome refused to start the tab capture.", { activeTab: diagnostics.activeTab, elapsedMs: acquisitionElapsed(), windowState: diagnostics.windowState });
+        }
+        // The failure is already an Error: acquireOnce normalizes every rejection at the one boundary where a page-side value enters, so it travels unchanged.
+        throw error;
+    }
+}
+//# sourceMappingURL=tabCapture.js.map

package/dist/browser/tabCapture.js.map

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

package/dist/browser/tabNetworkObserver.d.ts

@@ -46,4 +46,3 @@ export interface TabNetworkObserver extends Disposable {
  * @returns The observer handle, or null if installation failed.
  */
 export declare function observeTabResponses(page: Page, options: TabNetworkObserverOptions): Promise<Nullable<TabNetworkObserver>>;
-//# sourceMappingURL=tabNetworkObserver.d.ts.map

package/dist/browser/tabSelection.d.ts

@@ -0,0 +1,117 @@
+import type { Browser, Page } from "puppeteer-core";
+import type { Clock } from "homebridge-plugin-utils";
+import type { Nullable } from "../types/index.ts";
+import { getExtensionPage } from "puppeteer-stream";
+export declare const TAB_NOT_FOUND_MESSAGE = "The capture extension could not find the page's tab.";
+export declare const TAB_NOT_SELECTED_MESSAGE = "The capture extension did not select the page's tab.";
+/**
+ * The library value this module talks to, injected so a test can drive a whole hold without a browser.
+ */
+export interface TabSelectionDeps {
+    readonly getExtensionPage: typeof getExtensionPage;
+}
+/**
+ * The collaborators an open runs through: the window topology, and the library lookup this module already talks to.
+ *
+ * A sibling of TabSelectionDeps rather than an extension of it, because TabSelectionDeps has to stay satisfiable by its own default for the three consumers that
+ * take it that way. The two topology functions answer questions about CDP's window table, which this module structurally cannot ask - it speaks to the capture
+ * extension and to nothing else - so they carry no default at all and arrive from a call site that can see both modules.
+ */
+export interface SharedWindowTabDeps {
+    readonly confirmPlacement: (page: Page) => Promise<boolean>;
+    readonly getExtensionPage?: typeof getExtensionPage;
+    readonly resolveCarrier: (browser: Browser) => Promise<Nullable<Page>>;
+}
+/**
+ * Per-call context for an open: how long the whole turn may take, the clock that ceiling runs on, and the collaborators it runs through.
+ */
+export interface OpenSharedWindowTabContext {
+    readonly ceilingMs?: number;
+    readonly clock?: Clock;
+    readonly deps: SharedWindowTabDeps;
+}
+/**
+ * The selected tab handed to a hold's body: what it is, and the way to be sure of it again at a moment of the body's own choosing.
+ */
+export interface SelectedTab {
+    readonly id: number;
+    readonly reassert: () => Promise<void>;
+    readonly url: Nullable<string>;
+    readonly windowId: number;
+}
+/**
+ * Per-call context for a hold: how long the selection may be held, the clock that bound runs on, and the collaborators it talks through.
+ */
+export interface WithTabSelectedContext {
+    readonly ceilingMs?: number;
+    readonly clock?: Clock;
+    readonly deps?: TabSelectionDeps;
+}
+export declare const defaultTabSelectionDeps: TabSelectionDeps;
+/**
+ * Subscribes to the activation report: every tab this module activates through the extension, announced by id as soon as the update resolves.
+ *
+ * A captured page cannot hear its own activation, so the module performing the activation is the one place the fact exists to be announced at all. The report
+ * carries the id and stops there, which is what keeps this module's vocabulary to tabs and windows no matter what a subscriber goes on to do with one.
+ * @param listener - Called with the id of each tab this module activates.
+ * @returns The closure that ends the subscription. A subscriber that has gone away without calling it stays in the set for the life of the process.
+ */
+export declare function onTabActivation(listener: (tabId: number) => void): () => void;
+/**
+ * The tab id a page was identified as, when it has one.
+ *
+ * The report names a tab and a subscriber holds pages, so this is the bridge between them. The answer is only ever an id a completed identification cached, which
+ * means a page this module has never selected reads undefined - the right answer for it, because no activation of ours can have named it.
+ * @param page - The page to look up.
+ * @returns The cached tab id, or undefined when this page has not been identified.
+ */
+export declare function getCachedTabId(page: Page): number | undefined;
+/**
+ * Runs a body with a page's tab selected in its window, and hands back the tab that was selected before it afterwards.
+ *
+ * Holds are serialized: this queues onto the chain, and the hold that follows begins when this one has given the selection back - not when this caller has
+ * finished reading its result, which is what lets a body that outlives its ceiling keep running without holding the selection or the queue.
+ * @param page - The page whose tab the body needs selected.
+ * @param body - The work to run while the tab is selected. It receives the selected tab.
+ * @param context - The ceiling, clock, and collaborators. Defaults to the capture start's own deadline on the system clock with the production collaborators.
+ * @returns Whatever the body resolves with, even when the hold's ceiling lapsed first.
+ * @throws The body's own rejection, or a selection failure of this module's own.
+ */
+export declare function withTabSelected<T>(page: Page, body: (tab: SelectedTab) => Promise<T>, context?: WithTabSelectedContext): Promise<T>;
+/**
+ * Opens a page as a tab of the shared browser window, and hands the selection straight back to the tab that had it.
+ *
+ * The open belongs here because the open IS a selection change. Chrome picks the window for a plain background page and skips a minimized one, so a capture tab
+ * created while the shared window rests minimized beside a discovery window takes root in the discovery window instead and keeps that window alive long past the
+ * walk it was opened for. The one anchor Chrome honors in every window state is the opener relationship: a window.open evaluated on a page of the shared window
+ * opens its tab in that window, minimized or not, and restores the window on the way in (measured 2026-08-31, both window states).
+ *
+ * Running it as a turn on this module's executor closes two races rather than one. chrome.tabCapture records whichever tab is selected and page creation runs
+ * outside the capture lock, so a bare open could land between a concurrent stream's re-assert and its recording start and put a blank tab on that stream's
+ * recording; and two overlapping opens on one page silently lose all but the first, because a page carries a single transient activation. Serialized turns make
+ * both unrepresentable rather than unlikely.
+ *
+ * Two id spaces meet at this call and are never compared. The window identity a placement is confirmed against belongs to CDP's table, and this module never sees
+ * it - it arrives as an injected answer of true or false. Every id this module reads or writes itself, the tab that was selected and the tab that gets it back,
+ * is the capture extension's.
+ *
+ * Three side effects belong to somebody else. The tab arrives selected, which is why the selection goes back inside this same turn. The open restores a minimized
+ * window, which the window-visibility policy settles afterwards. And the give-back's activation report re-affirms whichever tab regains the selection, so when
+ * that is another stream's capture page its composition wobbles for about a second until the re-affirm ladder lands - the same self-healing wobble a capture
+ * start already causes once, now possible a second time at page creation.
+ * @param browser - The browser to open the tab in.
+ * @param context - The turn's ceiling, the clock it runs on, and the collaborators it runs through.
+ * @returns The opened page, or a page created the plain way when the anchor could not be had.
+ */
+export declare function openSharedWindowTab(browser: Browser, context: OpenSharedWindowTabContext): Promise<Page>;
+/**
+ * Installs the listener that closes the tabs abandoned opens leave behind, for the life of the browser it is given.
+ *
+ * A turn's evaluate keeps running inside Chrome after the turn's own wait has ended, so a carrier that was merely slow can land its tab long after the turn
+ * scanned for one and created its page the plain way. Nothing registered that tab, so nothing judges it and nothing closes it. The browser's own target events
+ * are what make it findable: a page target whose URL carries the open marker, and whose nonce no pass is waiting for, is one nobody asked for. Both target
+ * events are read because a window.open target is created at about:blank and takes its URL on the change that follows, which leaves the judgment a function of
+ * the target's URL and this module's own state and nothing else.
+ * @param browser - The browser whose targets to watch.
+ */
+export declare function installStrayOpenTabReaper(browser: Browser): void;