prismcast 1.10.3 → 1.11.0

package/dist/browser/index.d.ts

@@ -3,6 +3,14 @@ import { clearLoginState, isLoginModeActive } from "./login.ts";
 import { getStream } from "puppeteer-stream";
 import type { Nullable } from "../types/index.ts";
 import type { ProcessInfo } from "../utils/index.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).
+ */
+export declare function setCaptureProbe(probe: CaptureProbe): void;
 /**
  * Returns true if graceful shutdown is in progress.
  */
@@ -12,7 +20,9 @@ export declare function isGracefulShutdown(): boolean;
  */
 export declare function setGracefulShutdown(value: boolean): void;
 export { clearLoginState, isLoginModeActive };
-export { type LoginStatus, endLoginMode, getLoginPage, getLoginStatus, startLoginMode } from "./login.ts";
+export type { LoginStatus } from "./login.ts";
+export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, startLoginMode } from "./login.ts";
+export { BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.ts";
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -24,8 +34,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.
  */
-export declare function registerManagedPage(page: Page): void;
+export declare function registerManagedPage(page: Page, options?: {
+    inFlightSetup?: 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
  * stale page cleanup from racing with intentional page closure.
@@ -47,9 +61,8 @@ export declare function ensureDataDirectory(): Promise<void>;
  * rely on an in-memory flag; the parent-child relationship in the OS process table IS the ownership proof, which means this function is safe to call from any
  * code path, including from a rejected-duplicate startup's exit handler.
  *
- * Why ownership matters. A duplicate PrismCast that the instance guard rejects must NOT signal Chrome that belongs to the legitimate holder. With PID-based
- * cleanup the only defense was an in-memory ownsChromeCleanup flag set at startup. With process-table discovery, the OS itself tells us who owns what: a Chrome
- * whose ppid is a live unrelated PID belongs to that parent, not to us.
+ * Why ownership matters. A duplicate PrismCast that the instance guard rejects must NOT signal Chrome that belongs to the legitimate holder. Process-table
+ * discovery lets the OS itself tell us who owns what: a Chrome whose ppid is a live unrelated PID belongs to that parent, not to us.
  * @param processes - The current process table snapshot.
  * @param profileDir - The Chrome user-data-dir to match against.
  * @param ownPid - The current process's PID (anything whose parent is us is ours to kill).
@@ -94,15 +107,27 @@ export declare function getExecutablePath(): string;
  */
 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:
+ * 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.
  *
- * - 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.
+ * 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.
+ */
+export declare function invalidateBrowser(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.
+ * @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.
  */
 export declare function getCurrentBrowser(): Promise<Browser>;
 /**
@@ -131,23 +156,14 @@ export declare function isBrowserConnected(): boolean;
  */
 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.
+ * 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.
  */
 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.
- *
- * Chrome termination uses Puppeteer's ChildProcess handle and its `exit` event for detection:
- *
- * - browserRef.close() sends CDP Browser.close and waits for WebSocket teardown, which hangs 3-5 seconds even after Chrome exits.
- * - browserRef.disconnect() drops the WebSocket instantly but orphans Chrome as a Node child process, creating a zombie that process.kill(pid, 0) cannot detect.
- * - Synchronous polling (Atomics.wait) blocks the event loop, preventing Node from processing SIGCHLD to reap the child - Chrome becomes a zombie regardless
- *   of how SIGTERM was sent.
- *
- * Instead, we send SIGTERM through the ChildProcess handle and listen for the `exit` event. This keeps the event loop running so Node can process SIGCHLD and
- * reap Chrome properly. The exit event fires only after the process is fully reaped - no zombies, no polling, no event loop blocking.
+ * Closes the browser and cleans up resources during full server shutdown. After this call the supervisor reports absent and any subsequent stream request launches
+ * a fresh browser. It retires the current instance from the lifecycle (so an in-flight launch is superseded and the metadata is cleared), then delegates the actual
+ * Chrome teardown to closeBrowserInstance. The graceful-shutdown flag is set so handleBrowserDisconnect, if it runs for any reason, stays quiet.
  */
 export declare function closeBrowser(): Promise<void>;
 /**
@@ -156,7 +172,7 @@ 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
+ * 2. Exclude pages associated with active streams, and pages whose stream setup is still in flight
  * 3. Apply a grace period before closing (to handle race conditions)
  * 4. Preserve at least one page to keep the browser alive
  */
@@ -190,3 +206,4 @@ export declare function stopBrowserRestartChecking(): void;
  */
 export declare function prepareExtension(): Promise<void>;
 export { getStream };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAuB,MAAM,YAAY,CAAC;AAIrF,OAAO,EAAoB,SAAS,EAAU,MAAM,kBAAkB,CAAC;AAOvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAyHrD,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAQxD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAGzD;AA+BD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAG5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAGxD;AAiCD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjH,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAMzF;;GAEG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4C7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAgB/F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAgBtD;AA0BD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAiBzD;AAkFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EACnH,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,EAAE,CA0BpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAgDtC;AA6DD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAgC1C;AASD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CA6GlD;AA6WD;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvF;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAG1D;AA4GD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,QAAQ,CAAC,MAAM,CAAC,CAGnD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAAC,OAAO,CAAC,CAGtD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAK5C;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA4D3D;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAkBvD;AA2ED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CA8BlD;AAyBD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkHvD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAQ3C;AA6ID;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAajD;AAcD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAqDtD;AAGD,OAAO,EAAE,SAAS,EAAE,CAAC"}