prismcast 1.12.0 → 1.12.1

package/dist/browser/index.js

@@ -1,20 +1,22 @@
-import { LOG, boundedWait, evaluateWithAbort, formatError, isProcessRunning, listProcesses, realClock, startTimer } from "../utils/index.js";
+import { LOG, boundedWait, evaluateWithAbort, formatError, isProcessRunning, listProcesses, realClock, setChromeUserAgent, startTimer } from "../utils/index.js";
 import { clearLoginState, isLoginModeActive, setBrowserAccessors } from "./login.js";
-import { getAllStreams, getStreamCount } from "../streaming/registry.js";
+import { getAllStreams, getStreamCount, hasActiveCaptureStreams, isCaptureIdentity } from "../streaming/registry.js";
+import { getCachedTabId, installStrayOpenTabReaper, onTabActivation } from "./tabSelection.js";
 import { getChromeDataDir, getDataDir, getExtensionDir } from "../config/paths.js";
-import { getExtensionPage, getStream, launch } from "puppeteer-stream";
+import { getExtensionPage, launch } from "puppeteer-stream";
 import { getGpuCapabilities, setGpuCapabilities } from "./display.js";
-import { minimizeWindow, unminimizeWindow, withCDPSession } from "./cdp.js";
+import { minimizeWindow, readWindowPlacement, reaffirmCaptureSurface, unminimizeWindow, withCDPSession } from "./cdp.js";
 import { CONFIG } from "../config/index.js";
+import { EXTENSION_READY_EXPRESSION } from "./tabCapture.js";
 import { clearChannelSelectionCaches } from "./channelSelection.js";
 import { createBrowserSupervisor } from "./browserSupervisor.js";
+import { createWindowVisibilitySync } from "./windowSync.js";
 import { emitSystemStatusChanged } from "../streaming/statusEmitter.js";
 import { evaluateStalePages } from "./pageStaleness.js";
 import fs from "node:fs";
 import { getPresetViewport } from "../config/presets.js";
 import path from "node:path";
 import { launch as puppeteerLaunch } from "puppeteer-core";
-import { setChromeUserAgent } from "../utils/index.js";
 import { startPrecaching } from "./precaching.js";
 import { terminateStream } from "../streaming/lifecycle.js";
 const { promises: fsPromises } = fs;
@@ -78,8 +80,10 @@ const supervisor = createBrowserSupervisor({ close: closeBrowserInstance, launch
     policy: buildRelaunchPolicy });
 /**
  * Observes supervisor lifecycle transitions purely for operator-visible signals; it never affects the transition (the supervisor treats it as best-effort, so a
- * throwing logger cannot corrupt the lifecycle). It raises the loud degraded alarm when the relaunch governor trips, an info notice when capture readiness is
- * restored after a degraded period, and emits the SSE system status whenever a ready browser is published.
+ * throwing logger cannot corrupt the lifecycle). It raises the loud degraded alarm when the relaunch governor trips, the capture-impairment alarm when a published
+ * browser is marked as unable to start captures, an info notice when capture readiness is restored after a degraded period, and emits the SSE system status
+ * whenever a ready browser is published. It reports rather than acts: the caller holding a verdict is what drives any recovery from it, because a restart begun
+ * from inside this observer would re-enter the supervisor while the transition that notified it is still on the stack.
  * @param next - The state being entered.
  * @param previous - The state being left.
  */
@@ -96,13 +100,20 @@ function onSupervisorStateChange(next, previous) {
         // silent; only a recovery from trialing/degraded is worth an operator notice.
         LOG.info("The browser capture system has recovered and is serving captures again.");
     }
+    else if ((next.kind === "ready") && (next.impairment !== null) && ((previous.kind !== "ready") || (previous.impairment === null))) {
+        // The published browser has been marked as unable to start captures. The transition carrying the mark happens once per instance, so the alarm fires once per
+        // instance too, and it says what an operator watching a stalled tune needs: the running captures are unaffected, new requests back off, and the cure arrives
+        // on its own once the registry empties.
+        LOG.error("The browser can no longer start captures (%s). Its running captures continue, new stream requests receive a 503 back-off, and it will relaunch as " +
+            "soon as no stream is active.", next.impairment.reason);
+    }
     // The browser's connectivity is part of the SSE system status, so emit when a ready browser is published. Readiness-loss emits are owned by handleBrowserDisconnect
     // (genuine disconnect) and the shutdown path; emitSystemStatusChanged dedupes, so a redundant emit is a cheap no-op.
     if (next.kind === "ready") {
         void emitCurrentSystemStatus();
     }
 }
-/* The capture-readiness probe (capability tier of the launch gate). Null until streaming/setup.ts injects the real getStream probe at module load, which the import
+/* The capture-readiness probe (capability tier of the launch gate). Null until streaming/setup.ts injects the real capture probe at module load, which the import
  * order guarantees runs before any launch: app.ts imports the streaming layer, whose module bodies evaluate during import resolution, before startServer's warm-up.
  * launchReadyBrowser refuses to publish a browser if it is somehow still null (see the call site), rather than serving an unverified one.
  */
@@ -110,8 +121,7 @@ let captureProbe = null;
 /**
  * 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 function setCaptureProbe(probe) {
     captureProbe = probe;
@@ -132,6 +142,15 @@ const BROWSER_RESTART_CHECK_INTERVAL = 30000;
 // Timer handle for the quiet period countdown. When set, the browser has exceeded BROWSER_MAX_AGE and we are waiting for BROWSER_RESTART_QUIET_PERIOD to
 // elapse with zero active streams. Cancelled if a stream starts during the quiet period.
 let restartQuietTimer = null;
+/**
+ * Cancels the scheduled-restart quiet period if one is pending, so the countdown it was running cannot fire against a browser it no longer describes.
+ */
+function cancelRestartQuietTimer() {
+    if (restartQuietTimer) {
+        clearTimeout(restartQuietTimer);
+        restartQuietTimer = null;
+    }
+}
 // Interval handle for the periodic restart eligibility check.
 let restartCheckInterval = null;
 // Flag indicating that the browser is being closed intentionally via closeBrowser(). When true, the disconnect handler skips error logging and stream termination
@@ -166,23 +185,205 @@ const managedPageIds = new Set();
 // Map from page ID to timestamp when a page was first observed as potentially stale (not associated with an active stream). Pages must remain in this state for
 // the configured grace period before being closed. This prevents race conditions where pages are briefly untracked during initialization or cleanup transitions.
 const potentiallyStalePages = new Map();
-/* Set of IDs for pages that stream setup created and whose ownership the stream registry does not yet record. Setup writes the registry's page reference only once
- * it completes, which on a slow tune is long enough for the cleanup walk to see the page as unowned and close it out from under the setup driving it; membership
- * here exempts the page from staleness for exactly that window. An entry leaves the set when unregisterManagedPage releases the page as setup tears it down, when
- * the cleanup walk sees the registry record the ownership the mark stood in for, and when clearPageTracking wipes the collections at the end of a browser session.
+/* Set of IDs for pages an operation owns for its whole duration while nothing the cleanup walk reads records that ownership. Stream setup is one such owner: it
+ * writes the registry's page reference only once it completes, which on a slow tune is long enough for the walk to see the page as unowned and close it out from
+ * under the setup driving it. A channel discovery walk is another: its page is never a stream page, so no registry entry will ever speak for it, and the walk's
+ * own cleanup is what releases it. Membership here exempts the page from staleness for exactly the window its owner holds it. An entry leaves the set when
+ * unregisterManagedPage releases the page as its owner finishes, when the cleanup walk sees the registry record the ownership the mark stood in for, and when
+ * clearPageTracking wipes the collections at the end of a browser session.
+ */
+const inFlightPageIds = new Set();
+/* The pages that live in a window of their own rather than the shared one. A CDP window command acts on the window of the page whose session carries it, so
+ * which page a command travels on decides which window moves...and a page in its own window would move that one. Membership here is what keeps such a page
+ * out of every site that reaches for a convenient page to command the shared window through.
+ *
+ * Keyed on the page and never cleared. The fact is intrinsic to how the page was created rather than a phase of its life, an entry dies with the page that
+ * holds it, and the picker below already declines a closed page - so unregistration, teardown order, and clearPageTracking have nothing to maintain here.
+ */
+const ownWindowPages = new WeakSet();
+/**
+ * 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 function isCarrierPage(page) {
+    return !!page && !page.isClosed() && !ownWindowPages.has(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.
  */
-const inFlightSetupPageIds = new Set();
+export function pickCarrierPage(pages) {
+    return pages.find(isCarrierPage) ?? null;
+}
+/* Which window Chrome's own tables call the shared one, keyed on the browser that owns it. The value belongs to CDP's window table and is never comparable with
+ * the capture extension's chrome.windows ids: those are two independent tables, and this is the only place a value from the CDP side is held.
+ *
+ * Keyed on the browser and never cleared, for the reason the own-window mark above is: the identity is a fact about how that browser was created, an entry dies
+ * with the browser holding it, and a relaunch records its own. An id that outlived its browser is exactly what would place a capture tab in the wrong window
+ * while every check agreed, so there is deliberately no way to write one a live browser did not report.
+ */
+const sharedWindowIds = new WeakMap();
+/* The window each page was found in, cached for the page's life in the tabIds idiom of tabSelection.ts. The lookup below attaches a CDP session the shared helper
+ * does not detach, so reading a candidate fresh on every tune would leave a session behind on each launch-era page every time. A page a user drags into another
+ * window keeps the window it was first read in; a stale entry costs a carrier that has since moved out of the shared window, which the placement confirmation
+ * catches and answers with the plain create rather than with a tab in the wrong place.
+ */
+const pageWindowIds = new WeakMap();
+// The URL prefix the capture extension's own pages carry. The resolver reads it to prefer a plain-origin carrier, since an open evaluated on the extension's
+// options page is territory nothing has measured.
+const EXTENSION_PAGE_PREFIX = "chrome-extension://";
+/**
+ * Reads the window a page sits in, answering from the cache once the page has been read.
+ * @param page - The page to locate.
+ * @returns The window's CDP id, or undefined when the window cannot be read at all - a closed page, a target that yields no window, or a CDP failure.
+ */
+async function readPageWindow(page) {
+    const cached = pageWindowIds.get(page);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const windowId = await withCDPSession(page, async (_session, id) => id);
+    if (windowId !== undefined) {
+        pageWindowIds.set(page, windowId);
+    }
+    return windowId;
+}
+/**
+ * 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 async function noteSharedWindow(browser, page) {
+    const windowId = await readPageWindow(page);
+    if (windowId === undefined) {
+        LOG.debug("browser:lifecycle", "The shared browser window could not be identified, so capture tabs will open wherever Chrome places them.");
+        return;
+    }
+    sharedWindowIds.set(browser, windowId);
+}
+/**
+ * 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 async function resolveSharedWindowCarrier(browser) {
+    const sharedWindowId = sharedWindowIds.get(browser);
+    const candidates = (await browser.pages()).filter(isCarrierPage);
+    for (const page of [...candidates.filter((candidate) => !candidate.url().startsWith(EXTENSION_PAGE_PREFIX)),
+        ...candidates.filter((candidate) => candidate.url().startsWith(EXTENSION_PAGE_PREFIX))]) {
+        if (sharedWindowId === undefined) {
+            return page;
+        }
+        // eslint-disable-next-line no-await-in-loop -- A candidate is only asked for its window once the candidates ahead of it have failed to qualify.
+        if ((await readPageWindow(page)) === sharedWindowId) {
+            return page;
+        }
+    }
+    return null;
+}
+/**
+ * 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 async function confirmSharedWindowPlacement(page) {
+    const sharedWindowId = sharedWindowIds.get(page.browser());
+    if (sharedWindowId === undefined) {
+        return true;
+    }
+    return (await readPageWindow(page)) === sharedWindowId;
+}
 // Login mode management. State and functions live in login.ts; re-exported here so existing consumers don't need import path changes. clearLoginState,
 // isLoginModeActive, and setBrowserAccessors are imported above; the first two for internal use, setBrowserAccessors for one-time initialization below.
 export { clearLoginState, isLoginModeActive };
 export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, startLoginMode } from "./login.js";
 // Re-export the supervisor's acquire() rejection classes through the browser surface so the stream-setup layer can map them to a 503 back-off without reaching into
-// the supervisor module directly. Both signal a transient "retry me" condition: BrowserUnavailableError while the relaunch governor is cooling, BrowserSupersededError
-// when a launch was abandoned mid-flight by a readiness-loss.
-export { BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.js";
-// Inject browser accessors into the login module. This breaks the circular dependency (login needs getBrowserInstance/minimizeBrowserWindow, index needs login
-// functions) using the same setter/getter pattern as setChromeUserAgent in chromeFetch.ts. Function declarations are hoisted, so both accessors are available here.
-setBrowserAccessors({ getBrowserInstance, minimizeBrowserWindow });
+// the supervisor module directly. Each signals a transient "retry me" condition: BrowserUnavailableError while the relaunch governor is cooling,
+// BrowserSupersededError when a launch was abandoned mid-flight by a readiness-loss, and BrowserCaptureImpairedError when the published browser can no longer start
+// captures and is waiting for its streams to end. The purpose and impairment types cross the same boundary, so a caller declares what it needs the browser for and
+// reads the mark without importing the supervisor.
+export { BrowserCaptureImpairedError, BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.js";
+/* The one window-presentation executor for the process lifetime. Its collaborators all live in this module: the registry predicate that says whether capture is
+ * reading the compositor, login mode's own flag, the shutdown gate, the two CDP primitives, and a page resolver built on the supervisor.
+ *
+ * The resolver prefers the page its caller handed over, borrows any page the browser already has open when there is none, and creates a temporary page only when
+ * the browser has nothing open at all. A temporary page is the only resolution that carries a dispose, so the executor releases what the resolver created and
+ * leaves a borrowed page alone. Both the preference and the borrow go through the shared carrier rule, because a command travels on a page's own session and
+ * so acts on that page's window: a page living in a window of its own would move that window instead of the shared one, whether it arrived as the caller's
+ * preference or as the first page the browser happened to report.
+ *
+ * The instance stays private to this module and every caller reaches it through the exported function just below. That split is what makes the symbol safe to
+ * reference at module-evaluation time: a function declaration is hoisted, so the setBrowserAccessors call further down - and any sibling module whose own body
+ * evaluates while this module is still evaluating, precaching.ts among them - resolves it whatever the declaration order turns out to be. A bare exported const
+ * would leave those readers in the temporal dead zone, which no placement inside this file can fix for a reader in another file.
+ */
+const windowVisibilitySync = createWindowVisibilitySync({
+    hasActiveCaptureStreams,
+    isLoginModeActive,
+    isShuttingDown: isGracefulShutdown,
+    minimize: minimizeWindow,
+    resolvePage: async (preferred) => {
+        const browser = supervisor.current();
+        if (!browser?.connected) {
+            return null;
+        }
+        if (isCarrierPage(preferred)) {
+            return { dispose: null, page: preferred };
+        }
+        const borrowed = pickCarrierPage(await browser.pages());
+        if (borrowed) {
+            return { dispose: null, page: borrowed };
+        }
+        // A page that exists only to carry a CDP command never needs its tab selected.
+        const temporary = await browser.newPage({ background: true });
+        // Registered so stale page cleanup recognizes the page as ours for the moment it exists.
+        registerManagedPage(temporary);
+        return {
+            dispose: async () => {
+                unregisterManagedPage(temporary);
+                try {
+                    await temporary.close();
+                }
+                catch (error) {
+                    // The browser may already have taken the page with it. Nothing downstream depends on the close succeeding.
+                    LOG.debug("browser:lifecycle", "Could not close the temporary window-sync page: %s.", formatError(error));
+                }
+            },
+            page: temporary
+        };
+    },
+    unminimize: unminimizeWindow
+});
+/**
+ * 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 async function syncWindowVisibility(page) {
+    return windowVisibilitySync(page);
+}
+// Inject browser accessors into the login module. This breaks the circular dependency (login needs getBrowserInstance and the window sync, index needs login
+// functions) using the same setter/getter pattern as setChromeUserAgent in chromeFetch.ts. Both accessors are hoisted function declarations, so this call reads
+// them at module evaluation time regardless of where they sit in the file.
+setBrowserAccessors({ getBrowserInstance, syncWindowVisibility });
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -203,6 +404,12 @@ export async function emitCurrentSystemStatus() {
     const memUsage = process.memoryUsage();
     const status = {
         browser: {
+            /* Read at compose time, beside the connectivity read below rather than as a snapshot taken before the page-count await. This function is called un-awaited
+             * from many sites, so two calls can be in flight around the instant a mark lands; a pre-mark snapshot settling after the mark's own emit would broadcast
+             * false over the cached true and the dedupe would honor it. Reading here makes every emit describe the state at the moment consumers receive it, so the
+             * later of two racing emits is also the truer one.
+             */
+            captureImpaired: supervisor.captureImpairment() !== null,
             connected: !!browser && browser.connected,
             pageCount
         },
@@ -225,8 +432,9 @@ export async function emitCurrentSystemStatus() {
  * 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 function registerManagedPage(page, options = {}) {
     // Generate a unique ID for this page.
@@ -235,9 +443,9 @@ export function registerManagedPage(page, options = {}) {
     pageToId.set(page, pageId);
     // Track the ID as managed.
     managedPageIds.add(pageId);
-    // Exempt the page from staleness for as long as its stream setup is in flight.
-    if (options.inFlightSetup) {
-        inFlightSetupPageIds.add(pageId);
+    // Exempt the page from staleness for as long as the operation that owns it is in flight.
+    if (options.inFlight) {
+        inFlightPageIds.add(pageId);
     }
 }
 /**
@@ -251,8 +459,8 @@ export function unregisterManagedPage(page) {
         managedPageIds.delete(pageId);
         // Also remove from potentially stale tracking since we're intentionally closing it.
         potentiallyStalePages.delete(pageId);
-        // Release any in-flight setup mark. The page is leaving our management, so the exemption it carried has nothing left to protect.
-        inFlightSetupPageIds.delete(pageId);
+        // Release any in-flight mark. The page is leaving our management, so the exemption it carried has nothing left to protect.
+        inFlightPageIds.delete(pageId);
         // Note: We don't delete from pageToId because WeakMap handles cleanup automatically when the Page is garbage collected.
     }
 }
@@ -274,7 +482,7 @@ function getManagedPageId(page) {
 function clearPageTracking() {
     managedPageIds.clear();
     potentiallyStalePages.clear();
-    inFlightSetupPageIds.clear();
+    inFlightPageIds.clear();
 }
 /**
  * Ensures the data directory exists, creating it if necessary. This should be called during application startup before any operations that depend on the data
@@ -580,6 +788,9 @@ export function getExecutablePath() {
  * the full rationale.
  */
 const PUPPETEER_STREAM_EXTENSION_ID = "jjndjgheafjngoipoacpjgeicjeomjli";
+// Chrome's documented value for disabling the device-scale-factor part of a metrics override, leaving the display's own density in effect. Naming it keeps the
+// sentinel from reading as a literal density of zero.
+const NATIVE_DENSITY = 0;
 /**
  * Assembles the configuration options for launching Chrome with Puppeteer. These options are critical for reliable streaming:
  *
@@ -590,7 +801,6 @@ const PUPPETEER_STREAM_EXTENSION_ID = "jjndjgheafjngoipoacpjgeicjeomjli";
  * @returns Puppeteer launch options.
  */
 export function buildLaunchOptions() {
-    const viewport = getPresetViewport(CONFIG);
     return {
         /* Chrome command-line arguments. Each flag serves a specific purpose for reliable streaming:
          *
@@ -602,7 +812,7 @@ export function buildLaunchOptions() {
          *   is a defensive duplicate: if a future puppeteer-stream release drops the flag again in favor of granting activeTab via a synthetic keystroke,
          *   CDP-synthesized keystrokes do not satisfy chrome.commands under automation (the renderer sees the event but the browser-process accelerator dispatcher
          *   does not), so capture would be denied at the API level (see github.com/Flam3rboy/puppeteer-stream/issues/206) without this fallback in place. Confirm
-         *   whether this duplicate is still warranted whenever the pinned puppeteer-stream version changes.
+         *   whether this duplicate is still warranted whenever the locked puppeteer-stream version changes.
          *
          * --autoplay-policy=no-user-gesture-required: Allows video and audio to play without requiring a user click first. Essential for automated streaming
          *   since we cannot simulate genuine user interaction for autoplay policy purposes.
@@ -645,18 +855,30 @@ export function buildLaunchOptions() {
             "--hide-scrollbars",
             "--no-first-run"
         ],
-        /* The configured quality preset is the capture surface. Puppeteer holds this viewport for the browser's lifetime and applies it as a device-metrics override
-         * to every page the browser creates - capture pages, probe pages, discovery pages, and the capture extension's own page - so no individual page-creation site
-         * has to ask for it. Tab capture reads the compositor's emulated surface rather than the OS window, which is what lets capture run at the preset's resolution
-         * whatever size the display is or the window happens to be. A device scale factor of 1 keeps a 1:1 render-to-encode mapping...the surface is rastered at
-         * exactly the pixel count the encoder consumes, so nothing is scaled on the way out. puppeteer-stream reads this same option and derives Chrome's window and
-         * ozone screen dimension flags from it, so the preset's dimensions enter the launch in exactly one place.
+        /* No launch-wide viewport, stated as an explicit null because an omitted option is not the same thing: Puppeteer reads an absent defaultViewport as its own
+         * 800x600 default and applies that override to every page it creates, while a null leaves each page carrying no override at all. Two consequences follow, and
+         * both are the point. A page renders at whatever surface PrismCast declares on it and nothing else - the capture surface on a capture page, the preset-sized
+         * layout on the discovery and capture-probe pages - so no page inherits an emulation it never asked for. And puppeteer-stream derives Chrome's --window-size
+         * and --ozone-override-screen-size flags from a sized default, where a --window-size flag stops Chrome restoring the placement it persisted in the profile, so
+         * with no default the window's size and placement are Chrome's and the user's.
+         *
+         * The return type names the null so the key cannot be dropped as dead configuration without a compile error, since its absence is silently a viewport rather
+         * than none.
          */
-        defaultViewport: { deviceScaleFactor: 1, height: viewport.height, width: viewport.width },
+        defaultViewport: null,
         // Path to the Chrome executable, either from environment variable or autodetected.
         executablePath: getExecutablePath(),
-        // Run Chrome in headed (visible) mode, not headless. The puppeteer-stream extension requires a visible browser window to capture the screen. We minimize
-        // the window after launch to reduce GPU usage while still allowing capture.
+        /* PrismCast owns process signals, so the launcher's own listeners are off. Left on, the puppeteer launcher installs handlers for SIGHUP, SIGINT, and SIGTERM
+         * on the node process and, on SIGTERM or SIGHUP, ends Chrome's entire process group with SIGKILL - and on SIGINT it kills the group and then exits the process
+         * outright. Either way it races the shutdown handlers in app.ts and preempts closeBrowserInstance's SIGTERM ladder below, so Chrome gets no shutdown at all
+         * and forfeits whatever it had pending: a window placement inside its save debounce, its session state. With the listeners off, a signal reaches PrismCast's
+         * own handler, the graceful path runs, and Chrome exits through the ladder with its pending writes committed.
+         */
+        handleSIGHUP: false,
+        handleSIGINT: false,
+        handleSIGTERM: false,
+        // Run Chrome in headed (visible) mode, not headless. The puppeteer-stream extension captures the compositor's output for a real window, which a headless
+        // browser does not have. The window is on screen while any capture stream runs or a login session is active, and minimized otherwise.
         headless: false,
         /* Prevent Puppeteer from adding certain default arguments that would interfere with streaming:
          *
@@ -692,6 +914,212 @@ export function buildLaunchOptions() {
         userDataDir: getChromeDataDir(CONFIG)
     };
 }
+/**
+ * Declares a device-metrics override on a page: the configured quality preset's dimensions at the density the caller names. Every surface this module declares is
+ * built here, so the preset reaches a page's emulation through exactly one read and one command.
+ * @param page - The page to declare the surface on.
+ * @param deviceScaleFactor - The pixel density to declare. NATIVE_DENSITY leaves the display's own density in effect.
+ * @returns The dimensions declared on the page.
+ */
+async function declareSurface(page, deviceScaleFactor) {
+    const viewport = getPresetViewport(CONFIG);
+    await page.setViewport({ deviceScaleFactor, height: viewport.height, width: viewport.width });
+    return { height: viewport.height, width: viewport.width };
+}
+/**
+ * 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 async function emulateCaptureSurface(page) {
+    const reportedDensity = await evaluateWithAbort(page, () => window.devicePixelRatio);
+    // A reading that is not a positive finite number is no measurement at all, and the compositor still needs an explicit density...1 is the density of an
+    // unscaled display, which is the safest thing to declare when the page cannot say.
+    const densityIsUsable = Number.isFinite(reportedDensity) && (reportedDensity > 0);
+    const deviceScaleFactor = densityIsUsable ? reportedDensity : 1;
+    if (!densityIsUsable) {
+        LOG.warn("The capture page reported a pixel density of %s. Emulating the capture surface at a density of %d instead.", reportedDensity, deviceScaleFactor);
+    }
+    const surface = await declareSurface(page, deviceScaleFactor);
+    LOG.debug("browser:lifecycle", "Emulated the capture surface at %dx%d with a pixel density of %s.", surface.width, surface.height, deviceScaleFactor);
+    return surface;
+}
+/**
+ * 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 async function emulateLayoutSurface(page) {
+    return declareSurface(page, NATIVE_DENSITY);
+}
+/**
+ * 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 function mirrorPlacement(placement) {
+    const { height, left, top, width } = placement;
+    return (placement.windowState === "maximized") ? { height, left, top, width, windowState: "maximized" } : { height, left, top, width };
+}
+/**
+ * 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 it is the active tab of a window that is not minimized, and 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, and a virtualized grid re-renders as the walk scrolls it - yet it is never captured, so it has no claim on the shared window's
+ * presentation and no business moving the user's selection. Its own window resolves both: the page is the active tab there 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 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 async function createDiscoveryPage(browser) {
+    const carrier = pickCarrierPage(await browser.pages());
+    const placement = carrier ? await readWindowPlacement(carrier) : null;
+    // The mark is set with nothing awaited between the creation and it, so no page read can observe this page as a candidate to carry a shared-window command.
+    const page = await browser.newPage({ background: true, type: "window", windowBounds: placement ? mirrorPlacement(placement) : undefined });
+    ownWindowPages.add(page);
+    LOG.debug("browser:lifecycle", "Opened the discovery page in a window of its own, %s.", placement ? "mirroring the shared window's placement" : "with no shared window to read a placement from");
+    return page;
+}
+/* The follow-up re-issue schedule a tab activation runs, expressed as offsets in milliseconds from the activation's own invocation rather than as gaps between
+ * shots. Chrome switches an activated tab's capture to the window's fitted presentation only after the focus event has fired, so the immediate re-issue that
+ * event triggers lands too early to stick (measured 2026-08-30: a selected capture tab's recording stayed fitted for upwards of forty seconds, until the
+ * monitor's periodic re-affirmation healed it completely with the tab still selected). These offsets bracket the switch so one shot lands just past it, the last
+ * rung allowing for platforms slower than the one measured. Every shot beyond the one that sticks is a no-op by reaffirmCaptureSurface's own contract, and the
+ * monitor's periodic re-affirmation remains the backstop bounding anything the whole ladder misses.
+ */
+const ACTIVATION_REAFFIRM_LADDER_MS = [250, 750, 1500, 3000];
+/* The heal enrolled for each capture page, which is the trigger the selection primitive's activation report fires. Keying on the page rather than on a tab id is
+ * what makes the enrollment expire on its own: an entry lives exactly as long as the page it heals. The callback held here is the very instance that page's focus
+ * binding invokes, so the two triggers share one generation counter and an activation arriving through either route supersedes an in-flight ladder rather than
+ * running a second one beside it.
+ */
+const activationHeals = new WeakMap();
+/**
+ * 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.
+ *
+ * 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 realClock.
+ * @returns The callback, which never rejects. Its promise settles once the ladder is spent, which the page-side listener does not wait on.
+ */
+export function makeFocusReaffirmCallback(page, reaffirm, clock = realClock) {
+    // The generation this closure hands out. It only ever increments: an invocation claims the next one and owns the rung schedule until a later invocation claims
+    // a higher one.
+    let generation = 0;
+    // One rung's re-issue. The offset it was scheduled at is carried on the debug line, so a swallowed failure says which shot spoke; the immediate shot reports zero.
+    const fireShot = async (offsetMs) => {
+        try {
+            await reaffirm(page);
+        }
+        catch (error) {
+            LOG.debug("browser:lifecycle", "Could not re-affirm the capture surface after a tab activation (+%sms): %s.", offsetMs, formatError(error));
+        }
+    };
+    return async () => {
+        const mine = ++generation;
+        await fireShot(0);
+        let previousOffsetMs = 0;
+        for (const offsetMs of ACTIVATION_REAFFIRM_LADDER_MS) {
+            // eslint-disable-next-line no-await-in-loop -- The pacing is the point: each rung waits out the distance left to its own offset before anything else runs.
+            await clock.sleep(offsetMs - previousOffsetMs);
+            // A newer activation owns the schedule, and it carries its own rungs timed from its own moment, so this ladder has nothing left to contribute.
+            if (generation !== mine) {
+                return;
+            }
+            // eslint-disable-next-line no-await-in-loop -- Sequential by design: a rung's re-issue settles before the wait toward the next rung begins.
+            await fireShot(offsetMs);
+            previousOffsetMs = offsetMs;
+        }
+    };
+}
+// The production collaborators.
+const defaultActivationHealDeps = { clock: realClock, reaffirm: reaffirmCaptureSurface };
+/**
+ * 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 async function installActivationHeal(page, deps = defaultActivationHealDeps) {
+    const callback = makeFocusReaffirmCallback(page, deps.reaffirm, deps.clock);
+    // Enrolled ahead of the binding, so the report-side trigger is live from the first moment either trigger could be. An exposeFunction that fails takes the page
+    // down with it, and the entry goes when the page does.
+    activationHeals.set(page, callback);
+    await page.exposeFunction("__prismcastReaffirmSurface", callback);
+    await page.evaluateOnNewDocument(() => {
+        window.addEventListener("focus", () => {
+            void window.__prismcastReaffirmSurface?.();
+        });
+    });
+}
+/**
+ * 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 function healActivatedCaptureTab(tabId, deps = { getAllStreams, getCachedTabId }) {
+    for (const entry of deps.getAllStreams()) {
+        // The mode is read through the registry's own published predicate rather than off the entry, keeping this layer's knowledge of a stream's shape to what the
+        // registry chooses to publish. A stream's page is nullable, because an entry is registered before its setup has produced one, so the narrowing comes ahead
+        // of the lookup that needs a page to ask about.
+        if (!isCaptureIdentity(entry) || (entry.page === null)) {
+            continue;
+        }
+        if (deps.getCachedTabId(entry.page) !== tabId) {
+            continue;
+        }
+        // A page whose install point has not run yet has nothing enrolled to fire, and the monitor's periodic re-affirmation is what covers it in the meantime.
+        void activationHeals.get(entry.page)?.();
+    }
+}
+/* The extension-side trigger, subscribed once for the life of the process. Every activation PrismCast performs goes through the selection primitive and is
+ * reported by it, which is the only way an activation of a captured page can be known at all; the page's own focus listener covers the one activation the
+ * primitive does not perform, a user's click that focuses the window. A browser relaunch changes neither module, so nothing here is re-subscribed.
+ */
+onTabActivation((tabId) => {
+    healActivatedCaptureTab(tabId);
+});
 /**
  * Custom launch function that modifies Chrome arguments when running as a packaged executable. The packaged version cannot load extensions from node_modules
  * (which is bundled inside the executable), so we point the extension paths to our extracted extension files in the data directory.
@@ -736,28 +1164,8 @@ function formatGpuSuffix(gpu) {
     return " (software rendering)";
 }
 /**
- * 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 function getUndersizedDisplayBounds(bounds, captureSurface) {
-    if ((bounds?.windowState !== "normal") || (bounds.width === undefined) || (bounds.height === undefined)) {
-        return null;
-    }
-    if ((bounds.width >= captureSurface.width) && (bounds.height >= captureSurface.height)) {
-        return null;
-    }
-    return { height: bounds.height, width: bounds.width };
-}
-/**
- * Probes the browser's GPU hardware-encoding capabilities and reports how the display compares to the configured capture surface. The GPU half queries CDP
- * SystemInfo.getInfo for renderer identity and H.264/HEVC/AV1 hardware encoding support, falling back to a MediaRecorder capability probe where the CDP data is
- * incomplete, and caches the result for codec selection to read. The display half is advisory: every page renders at the configured preset, so a display too
- * small to show a whole frame changes nothing about capture and is worth stating once.
+ * Probes the browser's GPU hardware-encoding capabilities. It queries CDP SystemInfo.getInfo for renderer identity and H.264/HEVC/AV1 hardware encoding support,
+ * falls back to a MediaRecorder capability probe where the CDP data is incomplete, and caches the result for codec selection to read.
  *
  * The probe runs against an existing page where one is open, and a temporary page otherwise.
  * @param browser - The browser instance to use for detection.
@@ -765,17 +1173,16 @@ export function getUndersizedDisplayBounds(bounds, captureSurface) {
 async function detectBrowserCapabilities(browser) {
     let tempPage = null;
     try {
-        // Try to use an existing page first to avoid window activation issues on macOS.
-        const existingPages = await browser.pages();
-        let targetPage = existingPages.find((p) => !p.isClosed()) ?? null;
+        // Try to use an existing page first to avoid window activation issues on macOS. The pick goes through the shared carrier rule, because the restore below
+        // acts on the window of whichever page carries it and a page living in its own window would restore that one instead of the shared one.
+        let targetPage = pickCarrierPage(await browser.pages());
         if (!targetPage) {
-            tempPage = await browser.newPage();
+            // A probe page never needs its tab selected either.
+            tempPage = await browser.newPage({ background: true });
             targetPage = tempPage;
         }
         /* Restore the window to its normal state before probing. Chrome restores window state from the persistent user data directory, so after a scheduled browser
-         * restart the window can come up minimized, and a minimized window reports its bounds as the shrunken presentation rather than the size the OS granted it -
-         * which would make the display advisory below fire against a size no display ever imposed. It also keeps the GPU probe's environment representative of the
-         * one capture runs in.
+         * restart the window can come up minimized, and the GPU probe wants an environment representative of the one capture runs in.
          */
         await unminimizeWindow(targetPage);
         // Detect GPU capabilities via CDP SystemInfo.getInfo. This is the authoritative source for GPU identity and hardware encoding capabilities - it runs at the
@@ -850,19 +1257,6 @@ async function detectBrowserCapabilities(browser) {
         catch (gpuError) {
             LOG.debug("browser:lifecycle", "GPU detection failed: %s.", String(gpuError));
         }
-        /* Report a display that cannot show a whole frame. The bounds come from the browser rather than from the page, because an emulated page reports the emulated
-         * size for screen.* and window.* alike, which would make the comparison circular - Browser.getWindowBounds is window state the page's emulation cannot reach.
-         */
-        const bounds = await withCDPSession(targetPage, async (session, windowId) => {
-            const result = await session.send("Browser.getWindowBounds", { windowId });
-            return result.bounds;
-        });
-        const captureSurface = getPresetViewport(CONFIG);
-        const granted = getUndersizedDisplayBounds(bounds, captureSurface);
-        if (granted) {
-            LOG.info("The display is smaller than the configured %s\u00d7%s capture surface (the browser window was granted %s\u00d7%s). Capture is unaffected: every " +
-                "page renders at the configured preset regardless of display or window size.", captureSurface.width, captureSurface.height, granted.width, granted.height);
-        }
     }
     catch (error) {
         LOG.warn("Browser capability detection failed: %s. Hardware encoding capabilities are unknown for this session.", formatError(error));
@@ -881,10 +1275,11 @@ async function detectBrowserCapabilities(browser) {
 }
 /**
  * Relinquishes the current browser's capture readiness and tears down everything that depended on it. This is the single source of truth for "the published browser
- * is no longer usable" - shared by the disconnect handler (the browser crashed) and by invalidateBrowser (the browser is alive but capture-dead). It drops the
+ * is no longer usable", and the disconnect handler is its one caller: the browser is gone, so nothing that depended on it can be salvaged. It drops the
  * supervisor's readiness first (which supersedes any launch in flight, clears the governor's health anchor, and transitions the lifecycle to absent so the next
  * request relaunches through the gate and governor), clears the adapter-held metadata and caches, ends login mode, terminates every active stream (they were
- * capturing on the now-unusable browser), and emits status. Callers log the specific cause; the alive-but-dead caller additionally closes the Chrome instance.
+ * capturing on the now-unusable browser), and emits status. The caller logs the specific cause. A browser that is still connected but can no longer start captures
+ * takes the far gentler noteBrowserCaptureImpaired path instead, which keeps its running captures.
  * @param streamTerminationReason - The reason recorded against each terminated stream, for the stream-end logs.
  */
 function relinquishBrowserReadiness(streamTerminationReason) {
@@ -895,10 +1290,7 @@ function relinquishBrowserReadiness(streamTerminationReason) {
     currentChromeVersion = null;
     setChromeUserAgent(null);
     // Cancel any pending scheduled-restart quiet timer since the browser this readiness applied to is gone.
-    if (restartQuietTimer) {
-        clearTimeout(restartQuietTimer);
-        restartQuietTimer = null;
-    }
+    cancelRestartQuietTimer();
     // Clear all channel selection caches. Cached state (guide row positions, discovered page URLs) belongs to the old browser session.
     clearChannelSelectionCaches();
     // End login mode if it was active. We use clearLoginState() rather than endLoginMode() because the browser may already be gone and we do not want to attempt any
@@ -933,43 +1325,40 @@ function handleBrowserDisconnect() {
     relinquishBrowserReadiness("browser disconnect");
 }
 /**
- * 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.
+ * Records that a still-connected browser can no longer start captures - a mid-life capture death that no "disconnected" event would surface - and schedules 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 for the registry to empty. Exported for the streaming layer to call once its probe or its wedge has produced the verdict.
  *
- * 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 async function invalidateBrowser(browser, reason) {
-    // Only invalidate if this is still the published browser. If it was already superseded (a disconnect plus relaunch raced the caller's probe), there is nothing to
-    // do - the readiness loss was handled, and tearing down the current browser would wrongly disrupt a healthy, freshly-relaunched one.
-    if (supervisor.current() !== browser) {
+ * 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.
+ */
+export function noteBrowserCaptureImpaired(browser, reason) {
+    // A false answer means the verdict landed on nothing: the instance was superseded by a disconnect and relaunch while the caller was confirming it, or the browser
+    // already carries a mark whose alarm and status emit have already fired. Either way there is no new state to act on.
+    if (!supervisor.noteCaptureImpaired(browser, reason)) {
         return;
     }
-    LOG.error("The browser is connected but can no longer capture (%s). Invalidating it for a governed relaunch.", reason);
-    relinquishBrowserReadiness("capture system failure");
-    // Readiness was relinquished first, because that is what supersedes an in-flight launch; publishing the teardown synchronously, before any await, then keeps the
-    // launch window shut for the whole drain so nothing spawns a second Chrome against the profile lock this one still holds.
-    const teardown = closeBrowserInstance(browser);
-    supervisor.noteTeardownBegun(teardown, BROWSER_TEARDOWN_DRAIN_BOUND_MS);
-    await teardown;
+    restartBrowserIfImpairedAndIdle();
 }
 /**
  * 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 async function getCurrentBrowser() {
-    return supervisor.acquire();
+export async function getCurrentBrowser(purpose) {
+    return supervisor.acquire(purpose);
 }
 /**
  * The supervisor's `launch` port: spawns Chrome, runs the readiness gate, performs post-launch initialization (display detection, version/UA capture, precaching),
@@ -993,21 +1382,31 @@ async function launchReadyBrowser() {
         // Readiness gate, handshake tier (cheap, on-suspicion). Poll for the puppeteer-stream extension to finish initializing - it injects a START_RECORDING function
         // into its options page context, so its presence is the extension's own readiness signal. We poll rather than fixed-delay so the browser is ready as soon as the
         // extension loads (typically 200-500ms). On failure this THROWS rather than warning-and-proceeding: an unregistered extension means chrome.tabs is undefined and
-        // every getStream() would hang, so the instance is not capture-ready and must not be published. We reclassify the raw waitForFunction timeout into a
+        // every capture acquisition would hang, so the instance is not capture-ready and must not be published. We reclassify the raw waitForFunction timeout into a
         // capture-infrastructure error carrying "timed out" so the setup layer maps it to a 503 back-off (the same as the capability-tier probe failure), rather than a
         // 500 the client would not back off from - an unregistered extension is a capture-infrastructure fault, and a fresh relaunch usually clears it.
         try {
             const extensionPage = await getExtensionPage(browser);
-            await extensionPage.waitForFunction("typeof START_RECORDING === 'function'", { timeout: CONFIG.browser.initTimeout });
+            await extensionPage.waitForFunction(EXTENSION_READY_EXPRESSION, { timeout: CONFIG.browser.initTimeout });
         }
         catch (handshakeError) {
             throw new Error("The capture extension handshake timed out after " + String(CONFIG.browser.initTimeout) + " ms.", { cause: handshakeError });
         }
         LOG.debug("timing:browser", "Extension initialized. (+%sms)", browserElapsed());
-        // Readiness gate, capability tier (the authoritative arbiter). Run the injected capture probe - a real getStream against a throwaway page on THIS instance - so
-        // "ready" means "really captured," not merely "the extension handshake responded." This predicate must run at every (re)launch:
-        // it exercises the exact getStream path that hangs when the extension is unregistered. A probe failure throws, so the supervisor counts the launch failure and the
-        // browser is never published; the unrecoverable stale-mutex case exits the process from inside the probe, since a Chrome restart cannot fix a leaked module mutex.
+        /* The tab the window rests on. It is created once and selected by construction because nothing asks otherwise, so whatever the window shows when nothing has
+         * asked for a tab is a blank page rather than the capture extension's own options page - which the library opens selected at launch. It is left unmanaged, as
+         * stale page cleanup judges only the pages stream setup and discovery create; it carries no correctness duty, so it needs no re-validation, and a user
+         * closing it costs nothing.
+         *
+         * It is also the page the shared window's identity is read from. This tab is in that window by construction, and reading it here - before the capture probe,
+         * the capability detection, or any stream - is what lets every later capture tab be anchored to the window rather than placed by Chrome.
+         */
+        const restingTab = await browser.newPage();
+        await noteSharedWindow(browser, restingTab);
+        // Readiness gate, capability tier (the authoritative arbiter). Run the injected capture probe - a real capture acquisition against a throwaway page on THIS
+        // instance - so "ready" means "really captured," not merely "the extension handshake responded." This predicate must run at every (re)launch:
+        // it exercises the exact acquisition path that fails when the extension is unregistered. A probe failure throws, so the supervisor counts the launch failure
+        // and the browser is never published.
         //
         // If the probe is not wired (the injection point left unset by a refactor - impossible in the normal import order, which always wires it before any launch),
         // we reject the launch rather than publish a handshake-only browser: serving an unverified browser would be the "proceed and hope" path this design
@@ -1034,6 +1433,11 @@ async function launchReadyBrowser() {
         // Start background precaching of selected service channel lineups. Fire-and-forget - the setTimeout inside startPrecaching() defers the work until after this
         // launch settles and the supervisor has published the ready browser, so its getCurrentBrowser() resolves immediately rather than re-entering this launch.
         startPrecaching();
+        /* The reaper belongs to the browser instance the supervisor is about to publish: puppeteer drops a closed browser's listeners along with the instance, and
+         * a relaunch comes back through this same path and installs its own. It goes in ahead of the disconnect handler so that handler stays the last step before
+         * publication, for the reason its own comment gives.
+         */
+        installStrayOpenTabReaper(browser);
         // Arm the disconnect handler only now, as the very last step before the supervisor publishes this browser as ready. It is deliberately NOT armed earlier: during
         // the gate/init window above, a Chrome crash surfaces as a thrown init step (CDP and waitForFunction reject on a dead browser), which the supervisor counts as a
         // launch failure and feeds to the governor - keeping the relaunch loop bounded even if Chrome dies repeatedly during init. Arming the handler earlier would let
@@ -1069,6 +1473,15 @@ export function getChromeVersion() {
 export function getBrowserInstance() {
     return supervisor.current();
 }
+/**
+ * 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 function getCaptureImpairment() {
+    return supervisor.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.
@@ -1077,54 +1490,6 @@ export function isBrowserConnected() {
     const browser = supervisor.current();
     return !!browser && browser.connected;
 }
-/**
- * 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 async function minimizeBrowserWindow() {
-    // Guard against calling this when no browser is running.
-    const browser = supervisor.current();
-    if (!browser?.connected) {
-        return;
-    }
-    let tempPage = null;
-    try {
-        // Try to use an existing page first. Creating a new page can cause the window to restore/activate on macOS, which defeats the purpose of minimizing.
-        const existingPages = await browser.pages();
-        let targetPage = existingPages.find((p) => !p.isClosed()) ?? null;
-        // If no existing pages, we must create a temporary one. This is less ideal but necessary to get a CDP session target.
-        if (!targetPage) {
-            tempPage = await browser.newPage();
-            // Register the temp page so stale cleanup knows it's ours.
-            registerManagedPage(tempPage);
-            targetPage = tempPage;
-        }
-        // Delegate to the CDP helper for the window-state change, so every minimize in the codebase issues the same command sequence.
-        await minimizeWindow(targetPage);
-        // Clean up the temporary page if we created one.
-        if (tempPage) {
-            unregisterManagedPage(tempPage);
-            await tempPage.close();
-        }
-    }
-    catch (error) {
-        // If we created a temp page, make sure to unregister it even on error.
-        if (tempPage) {
-            unregisterManagedPage(tempPage);
-            try {
-                await tempPage.close();
-            }
-            catch (_closeError) {
-                // Ignore close errors during error handling.
-            }
-        }
-        // Minimizing is not critical - log a warning but don't fail the operation.
-        LOG.debug("browser:lifecycle", "Could not minimize the browser window: %s.", formatError(error));
-    }
-}
 /**
  * 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.
@@ -1241,8 +1606,8 @@ export async function closeBrowser() {
  *
  * 4. Minimum page preservation: We always keep at least one page open to prevent Chrome from exiting.
  *
- * 5. In-flight setup exemption: Pages whose stream setup is still running (tracked in inFlightSetupPageIds) are never considered stale. The registry records a
- *    stream's page only once setup completes, so without this a slow tune would have its own page closed out from under it.
+ * 5. In-flight exemption: Pages an operation still holds (tracked in inFlightPageIds) are never considered stale. The registry records a stream's page only once
+ *    setup completes, and a discovery page reaches the registry at no point at all, so without this a slow tune or a running walk would lose its own page.
  *
  * The safeguards are expressed as rules in browser/pageStaleness.ts, which decides from a snapshot what to close, track, forget, and unmark. This function is the
  * I/O shell around that decision: it reads Chrome's page list, applies the decision to the tracking collections, and performs the closes.
@@ -1253,7 +1618,7 @@ export async function closeBrowser() {
  *
  * 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
  */
@@ -1292,7 +1657,7 @@ export async function cleanupStalePages() {
             }
         }
         // The staleness judgment - clocks, exemptions, the dead-entry sweep, and the preserve-one budget - belongs to the pure core; this function only carries it out.
-        const actions = evaluateStalePages({ activePageIds, gracePeriodMs: CONFIG.recovery.stalePageGracePeriod, inFlightSetupPageIds, now, pageIds,
+        const actions = evaluateStalePages({ activePageIds, gracePeriodMs: CONFIG.recovery.stalePageGracePeriod, inFlightPageIds, now, pageIds,
             staleFirstSeen: potentiallyStalePages });
         // Bring the tracking collections in line with the decision before any close runs, so a close that fails cannot leave the bookkeeping half-applied.
         for (const pageId of actions.forgetTrackedIds) {
@@ -1302,7 +1667,7 @@ export async function cleanupStalePages() {
             potentiallyStalePages.set(pageId, now);
         }
         for (const pageId of actions.clearInFlightIds) {
-            inFlightSetupPageIds.delete(pageId);
+            inFlightPageIds.delete(pageId);
         }
         let closedCount = 0;
         for (const pageId of actions.closeIds) {
@@ -1350,15 +1715,39 @@ export function stopStalePageCleanup() {
         stalePageCleanupInterval = null;
     }
 }
-/* Opportunistic browser restart functions. The check runs on a 30-second interval and, when the browser exceeds BROWSER_MAX_AGE with zero active streams, starts
- * a quiet period timer. The quiet timer is cancelled if a stream starts, ensuring active viewers are never disrupted. When the timer expires, the browser is
- * closed and immediately re-launched.
+/* Browser restart functions. One routine performs the restart; what differs is the cause that reaches it.
+ *
+ * The maintenance cause is opportunistic and age-driven: the check runs on a 30-second interval and, when the browser exceeds BROWSER_MAX_AGE with zero active
+ * streams, starts a quiet period timer. The quiet timer is cancelled if a stream starts, ensuring active viewers are never disrupted. When the timer expires, the
+ * browser is closed and immediately re-launched.
+ *
+ * The impairment cause is a repair rather than hygiene: a browser that can no longer start captures is unusable for new tunes no matter how young it is, so age and
+ * the quiet period do not apply to it. It relaunches the moment the registry empties, which the mark itself, every stream end, and the periodic tick each check
+ * for.
  */
 /**
- * Checks whether the browser qualifies for an opportunistic restart. Called periodically by the restart check interval. The check skips when any of these
- * conditions hold: graceful shutdown in progress, login mode active, browser not ready, browser age below threshold. On every eligible tick it also drives the
- * supervisor's health-gated governor reset. If active streams exist, any pending quiet timer is cancelled (streams started during the quiet period reset the
- * countdown). Otherwise a quiet timer is started if one is not already running.
+ * 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 of them ends.
+ */
+export function restartBrowserIfImpairedAndIdle() {
+    if (supervisor.captureImpairment() === null) {
+        return;
+    }
+    // A marked browser's restart belongs to this path, so a maintenance quiet period pending from before the mark is retired the first time any trigger observes the
+    // mark - whether or not the registry is idle yet - rather than being left to fire against the browser the relaunch will have replaced.
+    cancelRestartQuietTimer();
+    if (getStreamCount() > 0) {
+        return;
+    }
+    void executeBrowserRestart("impairment");
+}
+/**
+ * Checks whether the browser qualifies for a restart. Called periodically by the restart check interval. The check skips when any of these conditions hold:
+ * graceful shutdown in progress, login mode active, browser not ready. A marked browser is handed to the impairment path and the tick ends there. Otherwise the
+ * tick drives the supervisor's health-gated governor reset and applies the maintenance rules: skip below the age threshold, cancel any pending quiet timer while
+ * active streams exist (streams started during the quiet period reset the countdown), and otherwise start a quiet timer if one is not already running.
  */
 function checkBrowserRestart() {
     // Skip if the server is shutting down or login mode is active.
@@ -1372,6 +1761,15 @@ function checkBrowserRestart() {
     if (!browser?.connected || (launchTime === null)) {
         return;
     }
+    /* A marked browser waits for idleness rather than for age, so the maintenance rules below have nothing to say about it. It is not evidence of sustained health
+     * either - the governor's reset waits for the fresh browser - so this tick neither feeds the health hold nor logs the recovery notice for it. The stream-end
+     * trigger normally restarts it well before this tick runs; the tick is the backstop for a trigger that could not act, a login session active at the time above
+     * all. The quiet period this tick would otherwise cancel below is retired inside the call, so the early return leaves no timer unobserved.
+     */
+    if (supervisor.captureImpairment() !== null) {
+        restartBrowserIfImpairedAndIdle();
+        return;
+    }
     // Health-gated governor reset. On every eligible tick, tell the supervisor the browser is still ready; once it has been continuously ready for the policy's
     // hold, this resets the relaunch governor to its normal state and returns true, so we log the recovery exactly once.
     if (supervisor.noteSustainedHealth()) {
@@ -1386,26 +1784,28 @@ function checkBrowserRestart() {
     if (getStreamCount() > 0) {
         if (restartQuietTimer) {
             LOG.debug("browser:lifecycle", "Browser restart quiet period cancelled - streams are active.");
-            clearTimeout(restartQuietTimer);
-            restartQuietTimer = null;
         }
+        cancelRestartQuietTimer();
         return;
     }
     // No active streams and the browser is old enough. Start the quiet timer if one is not already running.
     if (!restartQuietTimer) {
         LOG.debug("browser:lifecycle", "Browser uptime exceeds threshold. Quiet period started - restart will proceed if no streams start within %s minutes.", Math.round(BROWSER_RESTART_QUIET_PERIOD / 60000));
         restartQuietTimer = setTimeout(() => {
-            void executeBrowserRestart();
+            void executeBrowserRestart("maintenance");
         }, BROWSER_RESTART_QUIET_PERIOD);
     }
 }
 /**
- * Executes the opportunistic browser restart after the quiet period has elapsed. Performs a final guard check before proceeding, then closes the browser and
- * immediately re-launches a fresh instance.
+ * Executes a browser restart: a final guard check, then the current instance is retired and torn down and a fresh one is launched in its place. Every cause shares
+ * that whole sequence; only the log line that announces the restart differs, since only the cause knows why the browser is being replaced.
+ * @param cause - Why the restart is running, for the announcement.
  */
-async function executeBrowserRestart() {
-    // Clear the timer handle.
-    restartQuietTimer = null;
+async function executeBrowserRestart(cause) {
+    // Retire any pending quiet period. For a maintenance restart this is the timer that just fired, and clearing a fired handle costs nothing. For an impairment
+    // restart it may be a countdown started before the mark, which has to go: the browser it was measured against is about to be replaced, and letting it fire would
+    // restart the fresh instance a second time.
+    cancelRestartQuietTimer();
     // Final guard: re-check all preconditions. Conditions may have changed during the quiet period (e.g., a stream started just before the timer fired, login mode
     // was activated, or the browser disconnected on its own). Reading current()/currentLaunchTime() together keeps the ready-state check and the age source consistent.
     const browser = supervisor.current();
@@ -1417,7 +1817,12 @@ async function executeBrowserRestart() {
     const age = realClock.now() - launchTime;
     const hours = Math.floor(age / 3600000);
     const minutes = Math.floor((age % 3600000) / 60000);
-    LOG.info("Restarting browser for scheduled maintenance (uptime: %sh %sm).", hours, minutes);
+    if (cause === "impairment") {
+        LOG.info("Restarting the browser because it can no longer start captures (uptime: %sh %sm).", hours, minutes);
+    }
+    else {
+        LOG.info("Restarting browser for scheduled maintenance (uptime: %sh %sm).", hours, minutes);
+    }
     try {
         // Retire the current instance from the lifecycle, tear it down, then acquire a fresh one through the supervisor. We do NOT touch the graceful-shutdown flag (the
         // server is not shutting down): closeBrowserInstance removes the disconnect listener, which is what makes this intentional teardown quiet. acquire() publishes
@@ -1430,6 +1835,12 @@ async function executeBrowserRestart() {
         const teardown = closeBrowserInstance(browser);
         supervisor.noteTeardownBegun(teardown, BROWSER_TEARDOWN_DRAIN_BOUND_MS);
         await teardown;
+        /* The relaunch ends the browser session the channel-selection caches describe (guide row positions, discovered page URLs, watch URLs), exactly as the
+         * disconnect path ends it, so they are cleared here for the same reason. The clear waits for the process to be gone rather than running beside the teardown,
+         * because a page of the retiring session can still deliver a response event while Chrome drains - the Comcast channelmap listener writes its caches from
+         * exactly such an event - and a clear issued ahead of the drain would be undone by it.
+         */
+        clearChannelSelectionCaches();
         // The preconditions were checked before the teardown, but a shutdown can begin during the seconds it takes, and relaunching then would spawn Chrome into a
         // dying process. Re-check on the far side of the await, for the same reason the guard above re-checks on the far side of the quiet period.
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the shutdown path sets this while the teardown is awaited; TS cannot see that.
@@ -1437,10 +1848,12 @@ async function executeBrowserRestart() {
             LOG.debug("browser:lifecycle", "Browser restart relaunch declined because shutdown began while the previous instance was closing.");
             return;
         }
-        // Launch a fresh browser instance so it is ready for the next stream request.
-        await getCurrentBrowser();
-        // Minimize the new window to reduce GPU usage and desktop clutter.
-        await minimizeBrowserWindow();
+        // Launch a fresh browser instance so it is ready for the next stream request. The relaunch needs nothing but the browser itself, and the instance it replaces
+        // may be refusing captures, so it acquires for a page.
+        await getCurrentBrowser("page");
+        // Bring the fresh window into agreement with the policy. A scheduled restart only runs against an idle registry, so this settles it minimized; a stream
+        // arriving while the relaunch is in flight triggers its own sync during establishment.
+        await syncWindowVisibility();
         LOG.info("Browser restart complete. Fresh instance is ready.");
     }
     catch (error) {
@@ -1463,10 +1876,7 @@ export function stopBrowserRestartChecking() {
         clearInterval(restartCheckInterval);
         restartCheckInterval = null;
     }
-    if (restartQuietTimer) {
-        clearTimeout(restartQuietTimer);
-        restartQuietTimer = null;
-    }
+    cancelRestartQuietTimer();
 }
 /* When running as a packaged executable (created by the `pkg` tool), the application is bundled into a single binary. Node modules like puppeteer-stream are
  * included in the bundle, but Chrome cannot load extensions from within the packaged binary - it needs actual files on the filesystem.
@@ -1523,6 +1933,9 @@ export async function prepareExtension() {
         throw error;
     }
 }
-// Re-export getStream from puppeteer-stream for use by the streaming module. This keeps all puppeteer-stream imports centralized in the browser module.
-export { getStream };
+/* Re-export the capture acquisition for the streaming module. The browser directory owns every conversation with puppeteer-stream - index.ts launches it and
+ * tabCapture.ts speaks its extension's protocol - so no other layer imports the library, and the streaming layer asks this module for a capture the same way it
+ * asks it for a browser.
+ */
+export { acquireCaptureStream } from "./tabCapture.js";
 //# sourceMappingURL=index.js.map