prismcast 1.5.2 → 1.7.0

package/dist/browser/index.js

@@ -1,17 +1,18 @@
-import { LOG, evaluateWithAbort, formatError, startTimer } from "../utils/index.js";
+import { getGpuCapabilities, setBrowserChrome, setGpuCapabilities, setMaxSupportedViewport } from "./display.js";
+import { LOG, cancellableTimeout, clearPidFile, evaluateWithAbort, formatError, isProcessRunning, readPidFile, startTimer, writePidFile } from "../utils/index.js";
+import { clearLoginState, isLoginModeActive, setBrowserAccessors } from "./login.js";
 import { getAllStreams, getStreamCount } from "../streaming/registry.js";
-import { getChromeDataDir, getDataDir, getExtensionDir } from "../config/paths.js";
+import { getChromeDataDir, getChromePidFilePath, getDataDir, getExtensionDir } from "../config/paths.js";
 import { getEffectivePreset, getPresetViewport } from "../config/presets.js";
 import { getExtensionPage, getStream, launch } from "puppeteer-stream";
 import { resizeAndMinimizeWindow, unminimizeWindow } from "./cdp.js";
-import { setBrowserChrome, setMaxSupportedViewport } from "./display.js";
 import { CONFIG } from "../config/index.js";
 import { clearChannelSelectionCaches } from "./channelSelection.js";
 import { emitSystemStatusChanged } from "../streaming/statusEmitter.js";
-import { execSync } from "node:child_process";
 import fs from "node:fs";
 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;
@@ -24,11 +25,18 @@ const { promises: fsPromises } = fs;
  * - dataDir: The filesystem location for persistent data (Chrome profile, extension files). Resolved via config/paths.ts, which is created on startup if it doesn't
  *   exist.
  *
- * Stream tracking and ID generation have been moved to streaming/registry.ts for unified stream management across all output types (direct WebM, HLS, etc.).
+ * Stream tracking and ID generation have been moved to streaming/registry.ts for unified stream management across all output types (HLS, MPEG-TS, etc.).
  */
 // The shared browser instance used by all streaming sessions. Created on first stream request or during warmup. Set to null when the browser is not running or
 // has disconnected.
 let currentBrowser = null;
+// The PID of the Chrome process launched by Puppeteer. Tracked in memory for fast access and persisted to a PID file on disk so that orphaned Chrome processes
+// can be cleaned up after a crash or container restart without relying on Unix-only tools like pkill/pgrep.
+let chromePid = null;
+// Tracks whether this process has taken ownership of Chrome cleanup by running killStaleChrome() during startup. The exit handler checks this flag to avoid
+// killing Chrome that belongs to another running PrismCast instance — e.g., when a duplicate instance is rejected by the instance guard and exits before
+// killStaleChrome() runs in the startup sequence.
+let ownsChromeCleanup = false;
 // The Chrome version string (e.g., "Chrome/144.0.7559.110") captured when the browser launches. Cleared when the browser disconnects. Used by the
 // health endpoint to report the active Chrome version.
 let currentChromeVersion = null;
@@ -89,27 +97,13 @@ 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();
-/* Login mode allows users to authenticate with TV providers directly from the PrismCast web UI. When login mode is active:
- *
- * - A dedicated login tab is open in the browser showing the channel's URL
- * - The browser window is un-minimized so the user can interact with it
- * - New stream requests are blocked to prevent interference with the login process
- * - A 15-minute timeout automatically ends login mode if the user forgets
- *
- * The login page is NOT registered as a managed page to exclude it from stale page cleanup. We manage its lifecycle explicitly through startLoginMode/endLoginMode.
- */
-// Whether login mode is currently active.
-let loginModeActive = false;
-// The browser page (tab) used for login. Set when login starts, cleared when login ends.
-let loginPage = null;
-// The URL being used for login. Stored for status reporting.
-let loginUrl = null;
-// Timestamp when login mode started. Used for status reporting and timeout calculation.
-let loginStartTime = null;
-// Timeout handle for auto-ending login mode after 15 minutes.
-let loginTimeoutHandle = null;
-// Login timeout duration (15 minutes).
-const LOGIN_TIMEOUT_MS = 15 * 60 * 1000;
+// 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, startLoginMode } from "./login.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 });
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -191,7 +185,7 @@ function getManagedPageId(page) {
 export async function ensureDataDirectory() {
     try {
         await fsPromises.mkdir(getDataDir(), { recursive: true });
-        LOG.debug("browser", "Data directory ready: %s.", getDataDir());
+        LOG.debug("browser:lifecycle", "Data directory ready: %s.", getDataDir());
     }
     catch (error) {
         LOG.error("Failed to create data directory %s: %s.", getDataDir(), formatError(error));
@@ -212,78 +206,124 @@ export async function ensureDataDirectory() {
  * - Extension initialization: The puppeteer-stream extension needs time after browser launch to inject its recording APIs. We wait for this initialization before
  *   attempting to capture streams.
  */
+/**
+ * Persists the Chrome process PID to both the module-level variable (fast, in-memory) and a PID file on disk (survives crashes). The PID file allows the next
+ * startup to find and terminate orphaned Chrome processes even if the Node process crashed without cleanup.
+ * @param pid - The Chrome process ID to save.
+ */
+function saveChromePid(pid) {
+    chromePid = pid;
+    writePidFile(getChromePidFilePath(), pid, "Chrome", LOG);
+}
+/**
+ * Loads the Chrome PID from the module-level variable (fast path) or falls back to reading the PID file on disk (crash recovery path). Returns null if no PID
+ * is available — either first run or the PID file was already cleaned up.
+ * @returns The Chrome process ID, or null if unavailable.
+ */
+function loadChromePid() {
+    return chromePid ?? readPidFile(getChromePidFilePath(), "Chrome", LOG);
+}
+/**
+ * Clears the Chrome PID from both the module-level variable and the PID file on disk. Called after successful process cleanup to prevent stale PID reuse.
+ */
+function clearChromePid() {
+    chromePid = null;
+    clearPidFile(getChromePidFilePath(), "Chrome", LOG);
+}
+/**
+ * Synchronous sleep using Atomics.wait(). This is a cross-platform replacement for execSync("sleep N") that works on all platforms without shelling out.
+ * Required because killStaleChrome() runs in the synchronous process.on("exit") handler where async operations are not available.
+ * @param ms - Duration to sleep in milliseconds.
+ */
+function syncSleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 /**
  * Ensures a clean slate for browser launch by terminating any stale Chrome processes and removing orphaned profile lock files. Chrome locks its profile directory
- * while running, and if a previous instance crashed without releasing the lock, we cannot launch a new browser with the same profile. This function uses pkill to
- * find and terminate any Chrome processes whose command line contains our profile directory path, then polls pgrep to verify the processes have actually exited.
- * After process cleanup, it removes stale lock files (SingletonLock, SingletonCookie, SingletonSocket) and DevToolsActivePort from the profile directory.
+ * while running, and if a previous instance crashed without releasing the lock, we cannot launch a new browser with the same profile. This function uses the
+ * saved Chrome PID to find and terminate the process via process.kill(), then polls for exit using signal 0. This approach is fully cross-platform — it does not
+ * rely on Unix-only tools like pkill or pgrep.
  *
  * The termination strategy escalates from SIGTERM to SIGKILL. SIGTERM is sent first, giving Chrome up to 5 seconds to flush its profile databases (LevelDB,
  * extension state, session storage) and exit cleanly. If Chrome does not exit, SIGKILL is sent as a fallback. This escalation is critical when called from the
  * process exit handler — Chrome may be running normally (e.g., after a capture probe timeout), and an immediate SIGKILL would corrupt its profile databases,
  * poisoning the Docker volume for subsequent container restarts.
  *
- * The file cleanup is essential for Docker deployments. Container restarts destroy Chrome processes without giving them a chance to release profile locks, but the
- * lock files persist in the mounted volume. Without removing them, Chrome cannot start in the new container, causing a crash loop.
+ * If no PID is available (first run or clean shutdown where the PID file was already removed), process killing is skipped entirely and only lock file cleanup
+ * runs. When a PID file does exist but the process is gone (Docker restart with a mounted volume — the PID belongs to the previous container's PID namespace),
+ * process.kill() throws ESRCH, which is caught gracefully.
  *
- * This is called at startup before launching the browser and after closeBrowser() during shutdown. It's safe to call even when no stale processes or files exist.
+ * This is called at startup before launching the browser and from the process exit handler as a crash recovery fallback. It's safe to call even when no stale
+ * processes or files exist.
  */
 export function killStaleChrome() {
-    // Build the profile directory path that would appear in Chrome's command-line arguments.
     const profileDir = getChromeDataDir(CONFIG);
+    const pid = loadChromePid();
     const POLL_INTERVAL_MS = 200;
-    try {
-        // Send SIGTERM first to give Chrome a chance to flush its profile databases (LevelDB, extension state, session storage) before exiting. This is critical
-        // when called from the process exit handler — Chrome may be running normally (e.g., after a capture probe timeout) and SIGKILL would corrupt its profile
-        // databases, poisoning the Docker volume for subsequent restarts.
-        execSync(["pkill -f \"", profileDir, "\""].join(""));
-        LOG.debug("browser", "Sent SIGTERM to Chrome instances using %s.", profileDir);
-        // Wait up to 5 seconds for Chrome to flush its databases and exit after SIGTERM. Containerized environments with software rendering and shared CPU may
-        // need the full window.
-        const TERM_WAIT_MS = 5000;
-        if (!waitForChromeExit(profileDir, TERM_WAIT_MS, POLL_INTERVAL_MS)) {
-            // SIGTERM didn't work. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not respond to SIGTERM.
-            LOG.debug("browser", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
-            try {
-                execSync(["pkill -9 -f \"", profileDir, "\""].join(""));
-            }
-            catch (_error) {
-                // No matching processes — Chrome may have exited between the pgrep check and the pkill.
+    if (pid !== null) {
+        try {
+            // Send SIGTERM first to give Chrome a chance to flush its profile databases (LevelDB, extension state, session storage) before exiting. This is critical
+            // when called from the process exit handler — Chrome may be running normally (e.g., after a capture probe timeout) and SIGKILL would corrupt its profile
+            // databases, poisoning the Docker volume for subsequent restarts.
+            process.kill(pid, "SIGTERM");
+            LOG.debug("browser:lifecycle", "Sent SIGTERM to Chrome process %d.", pid);
+            // Wait up to 5 seconds for Chrome to flush its databases and exit after SIGTERM. Containerized environments with software rendering and shared CPU may
+            // need the full window.
+            const TERM_WAIT_MS = 5000;
+            if (!waitForChromeExit(pid, TERM_WAIT_MS, POLL_INTERVAL_MS)) {
+                // SIGTERM didn't work. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not respond to SIGTERM.
+                LOG.debug("browser:lifecycle", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
+                try {
+                    process.kill(pid, "SIGKILL");
+                }
+                catch (_error) {
+                    // ESRCH — Chrome exited between the poll check and the kill call.
+                }
+                const KILL_WAIT_MS = 2000;
+                if (!waitForChromeExit(pid, KILL_WAIT_MS, POLL_INTERVAL_MS)) {
+                    LOG.warn("Chrome process %d did not exit after %dms of signal escalation. Proceeding anyway.", pid, TERM_WAIT_MS + KILL_WAIT_MS);
+                }
             }
-            const KILL_WAIT_MS = 2000;
-            if (!waitForChromeExit(profileDir, KILL_WAIT_MS, POLL_INTERVAL_MS)) {
-                LOG.warn("Chrome processes did not exit after %sms of signal escalation. Proceeding anyway.", TERM_WAIT_MS + KILL_WAIT_MS);
+        }
+        catch (error) {
+            // ESRCH means the process does not exist — expected when there are no stale processes from a clean shutdown, or in Docker where the PID belongs to a
+            // previous container's PID namespace.
+            if (error.code !== "ESRCH") {
+                LOG.warn("Failed to signal Chrome process %d: %s.", pid, formatError(error));
             }
         }
-    }
-    catch (_error) {
-        // When pkill finds no matching processes, it returns a non-zero exit code. This is expected when there are no stale processes from a clean shutdown.
+        clearChromePid();
     }
     // Remove stale lock and port files left behind by an unclean Chrome exit.
     cleanStaleProfileFiles(profileDir);
+    // Mark this process as owning Chrome cleanup. The exit handler checks this flag to avoid killing Chrome that belongs to another running instance.
+    ownsChromeCleanup = true;
+}
+/**
+ * Returns whether this process has taken ownership of Chrome cleanup by running killStaleChrome() during startup. Used by the exit handler to avoid killing
+ * Chrome that belongs to another running PrismCast instance.
+ * @returns True if killStaleChrome() has run in this process.
+ */
+export function canCleanupChrome() {
+    return ownsChromeCleanup;
 }
 /**
- * Polls pgrep until no Chrome processes matching the profile directory remain, or the timeout expires. pgrep returns exit code 0 when matching processes exist
- * and non-zero when none remain.
- * @param profileDir - The Chrome profile directory path to match against process command lines.
+ * Polls until the Chrome process with the given PID has exited, or the timeout expires. Uses process.kill(pid, 0) to check process existence — throws ESRCH
+ * when the process is gone. Between polls, sleeps synchronously using Atomics.wait() for cross-platform compatibility.
+ * @param pid - The Chrome process ID to wait for.
  * @param timeoutMs - Maximum time to wait in milliseconds.
- * @param pollIntervalMs - Time between pgrep checks in milliseconds.
- * @returns True if all matching processes exited within the timeout, false otherwise.
+ * @param pollIntervalMs - Time between existence checks in milliseconds.
+ * @returns True if the process exited within the timeout, false otherwise.
  */
-function waitForChromeExit(profileDir, timeoutMs, pollIntervalMs) {
+function waitForChromeExit(pid, timeoutMs, pollIntervalMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        try {
-            execSync(["pgrep -f \"", profileDir, "\""].join(""), { stdio: "ignore" });
-            // Processes still exist. Wait and check again.
-            execSync(["sleep ", String(pollIntervalMs / 1000)].join(""));
-        }
-        catch (_error) {
-            // pgrep returned non-zero — no matching processes remain.
+        if (!isProcessRunning(pid)) {
             return true;
         }
+        syncSleep(pollIntervalMs);
     }
-    return false;
+    return !isProcessRunning(pid);
 }
 /**
  * Removes stale Chrome profile lock files and the DevTools port file. Chrome writes these while running and removes them on clean shutdown, but an unclean exit
@@ -300,7 +340,7 @@ function cleanStaleProfileFiles(profileDir) {
         const filePath = path.join(profileDir, file);
         try {
             fs.unlinkSync(filePath);
-            LOG.debug("browser", "Removed stale profile file: %s.", file);
+            LOG.debug("browser:lifecycle", "Removed stale profile file: %s.", file);
         }
         catch (error) {
             // ENOENT means the file doesn't exist, which is the expected case after a clean shutdown. Any other error (permissions, filesystem issues) is worth
@@ -469,6 +509,28 @@ async function launchWithCustomArgs(opts) {
  * use by the preset system when determining effective viewport.
  * @param browser - The browser instance to use for detection.
  */
+/**
+ * Formats the GPU capabilities into a human-readable suffix for the "Chrome ready" log line. The renderer string is already cleaned (ANGLE wrapper and Metal
+ * prefix stripped) at detection time, so this function uses it directly and appends hardware-accelerated codec names in brackets when available.
+ * @param gpu - The detected GPU capabilities.
+ * @returns A formatted string like " (GPU: Apple M1 [H264, HEVC])" or " (software rendering)".
+ */
+function formatGpuSuffix(gpu) {
+    const codecs = [
+        gpu.av1HardwareEncoding && "AV1",
+        gpu.h264HardwareEncoding && "H264",
+        gpu.hevcHardwareEncoding && "HEVC"
+    ].filter(Boolean);
+    if (codecs.length > 0) {
+        return " (GPU: " + gpu.renderer + " [" + codecs.join(", ") + "])";
+    }
+    // No hardware encoding available. A GPU may be present for rendering but lack hardware encoding — show the GPU name without codecs if we have a non-trivial
+    // renderer string, otherwise label as software rendering.
+    if (gpu.renderer && (gpu.renderer !== "unknown")) {
+        return " (GPU: " + gpu.renderer + ")";
+    }
+    return " (software rendering)";
+}
 async function detectDisplayDimensions(browser) {
     let tempPage = null;
     let usingTempPage = false;
@@ -481,24 +543,123 @@ async function detectDisplayDimensions(browser) {
             usingTempPage = true;
             targetPage = tempPage;
         }
-        // Measure display dimensions and browser chrome via JavaScript.
-        const dimensions = await evaluateWithAbort(targetPage, () => {
-            return {
-                // Available screen dimensions (excludes taskbar, dock, menu bar).
-                availHeight: screen.availHeight,
-                availWidth: screen.availWidth,
-                // Browser chrome dimensions (title bar, toolbar, borders).
-                chromeHeight: window.outerHeight - window.innerHeight,
-                chromeWidth: window.outerWidth - window.innerWidth
-            };
-        });
+        // Ensure the window is in normal state before measuring. Chrome restores window state from the persistent user data directory, so after a scheduled browser
+        // restart the window may launch minimized. A minimized window reports outerWidth/outerHeight as 0 while innerWidth/innerHeight retains the viewport dimensions,
+        // producing negative chrome measurements that poison all subsequent window sizing.
+        await unminimizeWindow(targetPage);
+        // Measure display dimensions and browser chrome via JavaScript. The measurement is retried if chrome dimensions are negative, which indicates the macOS window
+        // manager has not yet finished the minimize-to-normal state transition (the animation is asynchronous relative to the CDP command).
+        let dimensions;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            // eslint-disable-next-line no-await-in-loop
+            dimensions = await evaluateWithAbort(targetPage, () => {
+                return {
+                    // Available screen dimensions (excludes taskbar, dock, menu bar).
+                    availHeight: screen.availHeight,
+                    availWidth: screen.availWidth,
+                    // Browser chrome dimensions (title bar, toolbar, borders).
+                    chromeHeight: window.outerHeight - window.innerHeight,
+                    chromeWidth: window.outerWidth - window.innerWidth
+                };
+            });
+            if ((dimensions.chromeWidth >= 0) && (dimensions.chromeHeight >= 0)) {
+                break;
+            }
+            // Chrome dimensions are negative — the window manager is still transitioning. Wait briefly and remeasure.
+            if (attempt < 2) {
+                LOG.debug("browser:lifecycle", "Display detection measured negative chrome dimensions (%s\u00d7%s, attempt %s). Retrying after window state settles.", dimensions.chromeWidth, dimensions.chromeHeight, attempt + 1);
+                // eslint-disable-next-line no-await-in-loop
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }
+        // If all attempts produced negative chrome dimensions, skip caching to avoid poisoning window sizing. The preset system will use the configured preset without
+        // degradation, and resizeAndMinimizeWindow will fall back to measuring chrome dimensions via page.evaluate() on each call.
+        if (!dimensions) {
+            return;
+        }
+        if ((dimensions.chromeWidth < 0) || (dimensions.chromeHeight < 0)) {
+            LOG.warn("Display detection produced invalid chrome dimensions after 3 attempts (%s\u00d7%s). Window sizing may be incorrect.", dimensions.chromeWidth, dimensions.chromeHeight);
+            return;
+        }
         // Calculate maximum viewport: available screen space minus browser chrome.
         const maxWidth = dimensions.availWidth - dimensions.chromeWidth;
         const maxHeight = dimensions.availHeight - dimensions.chromeHeight;
         // Cache the results for use by the preset system and window sizing.
         setBrowserChrome(dimensions.chromeWidth, dimensions.chromeHeight);
         setMaxSupportedViewport(maxWidth, maxHeight);
-        LOG.debug("browser", "Display detection complete: screen %s\u00d7%s, chrome %s\u00d7%s, max viewport %s\u00d7%s.", dimensions.availWidth, dimensions.availHeight, dimensions.chromeWidth, dimensions.chromeHeight, maxWidth, maxHeight);
+        LOG.debug("browser:lifecycle", "Display detection complete: screen %s\u00d7%s, chrome %s\u00d7%s, max viewport %s\u00d7%s.", dimensions.availWidth, dimensions.availHeight, dimensions.chromeWidth, dimensions.chromeHeight, maxWidth, maxHeight);
+        // Detect GPU capabilities via CDP SystemInfo.getInfo. This is the authoritative source for GPU identity and hardware encoding capabilities — it runs at the
+        // browser level (no page context or secure context required) and returns the actual list of hardware-accelerated video encoding profiles.
+        try {
+            const cdpSession = await browser.target().createCDPSession();
+            try {
+                const sysInfo = await cdpSession.send("SystemInfo.getInfo");
+                // Extract the GPU renderer from the primary device. The WebGL unmasked renderer provides a richer string (includes ANGLE backend info), so we query
+                // that as well and prefer it when available.
+                const deviceName = (sysInfo.gpu.devices.length > 0) ? sysInfo.gpu.devices[0].deviceString : "unknown";
+                // Get the unmasked WebGL renderer for a more descriptive GPU identity string.
+                const webglRenderer = await evaluateWithAbort(targetPage, () => {
+                    const canvas = document.createElement("canvas");
+                    const gl = canvas.getContext("webgl");
+                    if (!gl) {
+                        return "unknown";
+                    }
+                    const ext = gl.getExtension("WEBGL_debug_renderer_info");
+                    return ext ? String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)) : String(gl.getParameter(gl.RENDERER));
+                });
+                // Extract the meaningful GPU name. ANGLE wraps the actual GPU identity: "ANGLE (Vendor, GPU Name, API Version)". The GPU name is the second
+                // comma-separated field. For non-ANGLE renderers, use the device string from CDP.
+                let renderer = webglRenderer;
+                const angleMatch = /^ANGLE \([^,]+, ([^,]+)/.exec(webglRenderer);
+                if (angleMatch) {
+                    renderer = angleMatch[1].trim();
+                    // Strip the "ANGLE Metal Renderer: " prefix that macOS adds.
+                    const metalPrefix = "ANGLE Metal Renderer: ";
+                    if (renderer.startsWith(metalPrefix)) {
+                        renderer = renderer.slice(metalPrefix.length);
+                    }
+                }
+                else if ((webglRenderer === "WebKit WebGL") || (webglRenderer === "unknown")) {
+                    renderer = deviceName;
+                }
+                // Determine hardware encoding capability. Two paths:
+                // 1. featureStatus.video_encode === "enabled" — authoritative Chrome-level flag indicating the platform's hardware encoding framework is active
+                //    (VideoToolbox on macOS, VA-API on Linux, DXVA on Windows). When enabled, H.264 hardware encoding is always available.
+                // 2. videoEncoding profile array — lists specific hardware-accelerated codec profiles (e.g., "H264 Main", "HEVC Main"). Populated on Linux/Windows
+                //    via VA-API/DXVA but empty on macOS where VideoToolbox doesn't enumerate through this interface.
+                const videoEncodeEnabled = sysInfo.gpu.featureStatus?.video_encode === "enabled";
+                const h264FromProfiles = sysInfo.gpu.videoEncoding.some((e) => e.profile.startsWith("H264"));
+                const hevcFromProfiles = sysInfo.gpu.videoEncoding.some((e) => e.profile.startsWith("HEVC"));
+                const av1FromProfiles = sysInfo.gpu.videoEncoding.some((e) => e.profile.startsWith("AV1"));
+                // H.264 hardware encoding is available when either the feature flag or the profile list confirms it.
+                const h264Hardware = videoEncodeEnabled || h264FromProfiles;
+                // HEVC and AV1 hardware encoding: check the profile list first (authoritative on Linux/Windows). On macOS (empty profile list), probe via MediaRecorder
+                // in the page context — MediaRecorder.isTypeSupported works in non-secure contexts unlike VideoEncoder.
+                let hevcHardware = hevcFromProfiles;
+                let av1Hardware = av1FromProfiles;
+                if (videoEncodeEnabled && (!hevcHardware || !av1Hardware)) {
+                    const [hevcSupported, av1Supported] = await evaluateWithAbort(targetPage, () => {
+                        if (typeof MediaRecorder === "undefined") {
+                            return [false, false];
+                        }
+                        return [
+                            MediaRecorder.isTypeSupported("video/mp4;codecs=hvc1.1.6.L93.B0"),
+                            MediaRecorder.isTypeSupported("video/mp4;codecs=av01.0.08M.08")
+                        ];
+                    });
+                    hevcHardware ||= hevcSupported;
+                    av1Hardware ||= av1Supported;
+                }
+                setGpuCapabilities({ av1HardwareEncoding: av1Hardware, h264HardwareEncoding: h264Hardware, hevcHardwareEncoding: hevcHardware, renderer });
+                LOG.debug("browser:lifecycle", "GPU detection: device=%s, renderer=%s, H.264=%s, HEVC=%s, AV1=%s, video_encode=%s, encoding profiles=%s.", deviceName, renderer, h264Hardware, hevcHardware, av1Hardware, sysInfo.gpu.featureStatus?.video_encode ?? "unknown", sysInfo.gpu.videoEncoding.map((e) => e.profile).join(", ") || "none");
+            }
+            finally {
+                void cdpSession.detach().catch(() => { });
+            }
+        }
+        catch (gpuError) {
+            LOG.debug("browser:lifecycle", "GPU detection failed: %s.", String(gpuError));
+        }
         // Check if the configured preset needs to be degraded and warn the user.
         const presetResult = getEffectivePreset(CONFIG);
         if (presetResult.degraded && presetResult.maxViewport) {
@@ -533,10 +694,12 @@ async function detectDisplayDimensions(browser) {
  * This ensures streams fail gracefully rather than hanging indefinitely trying to use closed pages.
  */
 function handleBrowserDisconnect() {
-    // Clear the browser reference, launch timestamp, and cached version so getCurrentBrowser() will launch a new instance on the next call.
+    // Clear the browser reference, launch timestamp, cached version, user agent, and stale PID so getCurrentBrowser() will launch a new instance on the next call.
     currentBrowser = null;
     browserLaunchTime = null;
+    chromePid = null;
     currentChromeVersion = null;
+    setChromeUserAgent(null);
     // Cancel any pending restart quiet timer since the browser is already gone.
     if (restartQuietTimer) {
         clearTimeout(restartQuietTimer);
@@ -544,20 +707,10 @@ function handleBrowserDisconnect() {
     }
     // Clear all channel selection caches. Cached state (guide row positions, discovered page URLs) may be stale in a new browser session.
     clearChannelSelectionCaches();
-    // Clear login state if login mode was active. We clear directly rather than calling endLoginMode() because the browser is already gone and we don't want to
-    // attempt any browser operations.
-    if (loginModeActive) {
-        if (loginTimeoutHandle) {
-            clearTimeout(loginTimeoutHandle);
-            loginTimeoutHandle = null;
-        }
-        loginModeActive = false;
-        loginPage = null;
-        loginUrl = null;
-        loginStartTime = null;
-        if (!gracefulShutdownInProgress) {
-            LOG.info("Login mode ended due to browser disconnect.");
-        }
+    // Clear login state if login mode was active. We use clearLoginState() rather than endLoginMode() because the browser is already gone and we don't want to
+    // attempt any browser operations (page close, window minimize).
+    if (clearLoginState() && !gracefulShutdownInProgress) {
+        LOG.info("Login mode ended due to browser disconnect.");
     }
     // Only log the error for unexpected disconnects. During graceful shutdown, closeBrowser() set the flag and this disconnect is intentional.
     if (!gracefulShutdownInProgress) {
@@ -619,6 +772,15 @@ async function launchBrowser() {
         // The launch function from puppeteer-stream wraps standard Puppeteer launch to inject the streaming extension. We pass our custom launch function that
         // handles packaged executable extension paths.
         currentBrowser = await launch({ launch: launchWithCustomArgs }, options);
+        // Persist the Chrome PID for cross-platform process cleanup. The PID file survives Node crashes, allowing the next startup to find and terminate orphaned
+        // Chrome processes without relying on Unix-only tools like pkill/pgrep.
+        const launchedPid = currentBrowser.process()?.pid;
+        if (launchedPid) {
+            saveChromePid(launchedPid);
+        }
+        else {
+            LOG.warn("Chrome process PID is unavailable. Orphaned process cleanup after a crash will be limited to lock file removal.");
+        }
         // Register a handler for browser disconnection. This ensures we clean up properly if the browser crashes or is closed unexpectedly.
         currentBrowser.on("disconnected", handleBrowserDisconnect);
         LOG.debug("timing:browser", "Chrome process spawned. (+%sms)", browserElapsed());
@@ -640,11 +802,15 @@ async function launchBrowser() {
         await detectDisplayDimensions(currentBrowser);
         LOG.debug("timing:browser", "Display detection complete. (+%sms)", browserElapsed());
         // Log the Chrome version for diagnostic reference. This helps correlate browser behavior changes (tab unresponsiveness, memory pressure, capture issues)
-        // with specific Chrome releases.
+        // with specific Chrome releases. We also capture the User-Agent string so that server-side fetch() calls to provider CDNs can match Chrome's identity.
         const chromeVersion = await currentBrowser.version();
+        const userAgent = await currentBrowser.userAgent();
         browserLaunchTime = Date.now();
         currentChromeVersion = chromeVersion;
-        LOG.info("Chrome ready: %s.", chromeVersion);
+        setChromeUserAgent(userAgent);
+        const gpu = getGpuCapabilities();
+        const gpuSuffix = gpu ? formatGpuSuffix(gpu) : "";
+        LOG.info("Chrome ready: %s%s.", chromeVersion, gpuSuffix);
         LOG.debug("timing:browser", "Browser ready. Total: %sms.", browserElapsed());
         // Emit system status update for SSE subscribers.
         await emitCurrentSystemStatus();
@@ -654,10 +820,11 @@ async function launchBrowser() {
     }
     catch (error) {
         LOG.error("Failed to launch browser: %s.", formatError(error));
-        // Clear the browser reference, launch timestamp, and cached version on failure so the next call will attempt to launch again.
+        // Clear the browser reference, launch timestamp, cached version, and user agent on failure so the next call will attempt to launch again.
         currentBrowser = null;
         browserLaunchTime = null;
         currentChromeVersion = null;
+        setChromeUserAgent(null);
         throw error;
     }
     return currentBrowser;
@@ -669,6 +836,14 @@ async function launchBrowser() {
 export function getChromeVersion() {
     return currentChromeVersion;
 }
+/**
+ * Returns the current browser instance, or null if not launched. Unlike getCurrentBrowser(), this does not lazily launch. Used by modules that need to check
+ * browser state without triggering a launch (e.g., login mode checking connectivity before opening a tab).
+ * @returns The browser instance, or null if not running.
+ */
+export function getBrowserInstance() {
+    return currentBrowser;
+}
 /**
  * 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.
@@ -724,7 +899,7 @@ export async function minimizeBrowserWindow() {
             }
         }
         // Resizing/minimizing is not critical - log a warning but don't fail the operation.
-        LOG.debug("browser", "Could not resize and minimize browser window: %s.", formatError(error));
+        LOG.debug("browser:lifecycle", "Could not resize and minimize browser window: %s.", formatError(error));
     }
 }
 /**
@@ -748,179 +923,64 @@ export async function getBrowserPages() {
  * Closes the browser and cleans up resources. This is called during graceful shutdown to ensure Chrome exits cleanly. After this call, the browser reference is
  * cleared and any subsequent stream requests will launch a fresh browser.
  *
- * The function uses a two-stage approach to ensure Chrome actually exits:
- * 1. Try browser.close() with a 5-second timeout (DevTools Protocol graceful close)
- * 2. Run killStaleChrome() to catch anything Stage 1 missed, using SIGTERM→SIGKILL escalation to give Chrome a chance to flush its profile databases
+ * 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.
  */
 export async function closeBrowser() {
     // Ensure the flag is set so the disconnect handler knows this is intentional. Normally set earlier by app.ts shutdown(), but set here as a fallback for direct
     // calls to closeBrowser().
     setGracefulShutdown(true);
     const browserRef = currentBrowser;
-    // Clear the reference, launch timestamp, and cached version early to prevent any new operations from using it.
+    // Clear the reference, launch timestamp, cached version, and user agent early to prevent any new operations from using it.
     currentBrowser = null;
     browserLaunchTime = null;
     currentChromeVersion = null;
+    setChromeUserAgent(null);
     if (!browserRef) {
         return;
     }
-    // Stage 1: Try graceful close with a timeout. We use Promise.race to avoid hanging indefinitely if Chrome is unresponsive.
-    if (browserRef.connected) {
-        try {
-            await Promise.race([
-                browserRef.close(),
-                new Promise((_, reject) => setTimeout(() => { reject(new Error("Browser close timed out")); }, 5000))
-            ]);
-        }
-        catch (error) {
-            const message = formatError(error);
-            if (message.includes("timed out")) {
-                LOG.warn("Browser did not close within 5 seconds. Forcing termination.");
-            }
-            else {
-                LOG.debug("browser", "Browser close error: %s.", message);
-            }
-        }
-    }
-    // Stage 2: Catch anything Stage 1 missed. If Chrome didn't respond to the DevTools close command (broken WebSocket, hung process), killStaleChrome()
-    // sends SIGTERM first to give Chrome a chance to flush its profile databases, then escalates to SIGKILL if needed.
-    killStaleChrome();
-}
-/* These functions manage the login mode workflow, allowing users to authenticate with TV providers through the browser. The workflow is:
- *
- * 1. User clicks "Login" on a channel in the web UI
- * 2. startLoginMode() opens a new tab with the channel's URL and un-minimizes the browser
- * 3. User completes authentication in the visible browser window
- * 4. User clicks "Done" in the web UI, or closes the tab, or the 15-minute timeout fires
- * 5. endLoginMode() closes the login tab (if still open) and re-minimizes the browser
- *
- * During login mode, new stream requests are blocked to prevent the browser from navigating away or creating conflicting tabs.
- */
-/**
- * Starts login mode by opening a new browser tab with the specified URL and un-minimizing the browser window. The user can then authenticate with their TV
- * provider in the visible browser.
- *
- * Login mode blocks new stream requests until it ends (via endLoginMode, tab close detection, or timeout).
- * @param url - The URL to navigate to for authentication.
- * @returns Object indicating success or failure with optional error message.
- */
-export async function startLoginMode(url) {
-    // Check if login mode is already active.
-    if (loginModeActive) {
-        return { error: "Login is already in progress.", success: false };
-    }
-    // Ensure browser is available.
-    if (!currentBrowser?.connected) {
-        return { error: "Browser is not connected.", success: false };
-    }
-    try {
-        // Create a new page for login. We intentionally do NOT register it as a managed page so stale page cleanup ignores it.
-        loginPage = await currentBrowser.newPage();
-        // Set up handler for tab close detection. If the user closes the tab manually, we should end login mode automatically.
-        loginPage.on("close", () => {
-            // Only auto-end if this is still the active login page.
-            if (loginModeActive && loginPage) {
-                LOG.info("Login tab was closed. Ending login mode.");
-                // Use void to handle the promise without awaiting (we're in an event handler).
-                void endLoginMode();
-            }
+    // Send SIGTERM through Puppeteer's ChildProcess handle and wait for the `exit` event. The ChildProcess handle is only available when Puppeteer launched
+    // Chrome (not when connecting to an existing browser), but PrismCast always launches Chrome directly.
+    const chromeProcess = browserRef.process();
+    if (chromeProcess?.pid && !chromeProcess.killed) {
+        const TERM_WAIT_MS = 5000;
+        const KILL_WAIT_MS = 2000;
+        // Listen for the exit event before sending the signal. The event fires after the OS reaps the process, so there is no zombie window. Resolves to true so
+        // Promise.race can distinguish exit from timeout.
+        const exitPromise = new Promise((resolve) => {
+            chromeProcess.on("exit", () => { resolve(true); });
         });
-        // Navigate to the login URL.
-        await loginPage.goto(url, { waitUntil: "domcontentloaded" });
-        // Un-minimize the browser window so the user can see and interact with it.
-        await unminimizeWindow(loginPage);
-        // Set login state.
-        loginModeActive = true;
-        loginUrl = url;
-        loginStartTime = Date.now();
-        // Set up the 15-minute timeout.
-        loginTimeoutHandle = setTimeout(() => {
-            LOG.warn("Login mode timed out after 15 minutes. Ending login mode.");
-            void endLoginMode();
-        }, LOGIN_TIMEOUT_MS);
-        LOG.info("Login mode started for %s.", url);
-        return { success: true };
-    }
-    catch (error) {
-        // Clean up on failure.
-        if (loginPage && !loginPage.isClosed()) {
-            try {
-                await loginPage.close();
-            }
-            catch (_closeError) {
-                // Ignore close errors.
-            }
-        }
-        loginPage = null;
-        return { error: formatError(error), success: false };
-    }
-}
-/**
- * Ends login mode by closing the login tab (if still open) and re-minimizing the browser window. This function is idempotent - it's safe to call multiple times
- * or when login mode is not active.
- *
- * Called by:
- * - User clicking "Done" in the web UI (POST /auth/done)
- * - Tab close detection (user closes the tab manually)
- * - 15-minute timeout
- * - Browser disconnect handler (cleanup)
- */
-export async function endLoginMode() {
-    // Clear the timeout if it hasn't fired yet.
-    if (loginTimeoutHandle) {
-        clearTimeout(loginTimeoutHandle);
-        loginTimeoutHandle = null;
-    }
-    // Close the login page if it's still open.
-    if (loginPage && !loginPage.isClosed()) {
-        try {
-            await loginPage.close();
-        }
-        catch (_error) {
-            // Ignore close errors - the page may have already been closed.
+        chromeProcess.kill("SIGTERM");
+        LOG.debug("browser:lifecycle", "Sent SIGTERM to Chrome process %d.", chromeProcess.pid);
+        // Wait for Chrome to exit after SIGTERM, with a timeout. If Chrome doesn't exit in time, escalate to SIGKILL.
+        const termTimeout = cancellableTimeout(TERM_WAIT_MS);
+        const exitedAfterTerm = await Promise.race([exitPromise, termTimeout.promise]);
+        termTimeout.cancel();
+        if (!exitedAfterTerm) {
+            // SIGTERM didn't work within the timeout. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not
+            // respond to SIGTERM.
+            LOG.debug("browser:lifecycle", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
+            chromeProcess.kill("SIGKILL");
+            const killTimeout = cancellableTimeout(KILL_WAIT_MS);
+            await Promise.race([exitPromise, killTimeout.promise]);
+            killTimeout.cancel();
         }
     }
-    // Clear login state.
-    const wasActive = loginModeActive;
-    loginModeActive = false;
-    loginPage = null;
-    loginUrl = null;
-    loginStartTime = null;
-    // Re-minimize the browser window.
-    if (wasActive && currentBrowser?.connected) {
-        await minimizeBrowserWindow();
-    }
-    if (wasActive) {
-        LOG.info("Login mode ended.");
-    }
-}
-/**
- * Returns whether login mode is currently active. Used by the stream handler to block new stream requests during login.
- * @returns True if login mode is active, false otherwise.
- */
-export function isLoginModeActive() {
-    return loginModeActive;
-}
-/**
- * Returns the current login status including whether active, the URL being used, and when login started. Used by the /auth/status API endpoint.
- * @returns Login status object.
- */
-export function getLoginStatus() {
-    return {
-        active: loginModeActive,
-        startTime: loginStartTime,
-        url: loginUrl
-    };
-}
-/**
- * Returns the active login page if login mode is currently active. Used by the profile test flow to evaluate CSS selectors against the live page DOM.
- * @returns The login page, or null if login mode is not active.
- */
-export function getLoginPage() {
-    if (!loginModeActive) {
-        return null;
+    // Disconnect the Puppeteer WebSocket after Chrome has exited. This cleans up Puppeteer's internal state (event listeners, pending CDP calls) without
+    // waiting for the WebSocket close handshake to complete on a dead connection.
+    if (browserRef.connected) {
+        void browserRef.disconnect();
     }
-    return loginPage;
+    // Clear the PID file and remove stale Chrome profile lock files.
+    clearChromePid();
+    cleanStaleProfileFiles(getChromeDataDir(CONFIG));
 }
 /* Over time, browser pages (tabs) may accumulate if cleanup fails during stream termination. This can happen due to race conditions, errors during cleanup, or
  * edge cases in stream lifecycle management. Each orphaned page consumes memory and may continue running JavaScript, so we periodically clean them up.
@@ -962,9 +1022,11 @@ export async function cleanupStalePages() {
         // Build a set of page IDs for pages currently in use by active streams.
         const activePageIds = new Set();
         for (const streamInfo of getAllStreams()) {
-            const pageId = getManagedPageId(streamInfo.page);
-            if (pageId) {
-                activePageIds.add(pageId);
+            if (streamInfo.page) {
+                const pageId = getManagedPageId(streamInfo.page);
+                if (pageId) {
+                    activePageIds.add(pageId);
+                }
             }
         }
         const now = Date.now();
@@ -1029,12 +1091,12 @@ export async function cleanupStalePages() {
         }
         // Log only if we actually closed something, to avoid log spam from idle cleanup runs.
         if (closedCount > 0) {
-            LOG.debug("browser", "Cleaned up %s stale page(s).", closedCount);
+            LOG.debug("browser:lifecycle", "Cleaned up %s stale page(s).", closedCount);
         }
     }
     catch (error) {
         // Cleanup failure is not critical - log a warning and try again next interval.
-        LOG.debug("browser", "Stale page cleanup failed: %s.", formatError(error));
+        LOG.debug("browser:lifecycle", "Stale page cleanup failed: %s.", formatError(error));
     }
 }
 /**
@@ -1065,7 +1127,7 @@ export function stopStalePageCleanup() {
  */
 function checkBrowserRestart() {
     // Skip if the server is shutting down, login mode is active, or the browser is not connected.
-    if (gracefulShutdownInProgress || loginModeActive || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
+    if (gracefulShutdownInProgress || isLoginModeActive() || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
         return;
     }
     // Skip if the browser has not exceeded the maximum age.
@@ -1076,7 +1138,7 @@ function checkBrowserRestart() {
     // If there are active streams, cancel any pending quiet timer and return. Streams that start during the quiet period reset the countdown.
     if (getStreamCount() > 0) {
         if (restartQuietTimer) {
-            LOG.debug("browser", "Browser restart quiet period cancelled — streams are active.");
+            LOG.debug("browser:lifecycle", "Browser restart quiet period cancelled — streams are active.");
             clearTimeout(restartQuietTimer);
             restartQuietTimer = null;
         }
@@ -1084,7 +1146,7 @@ function checkBrowserRestart() {
     }
     // No active streams and the browser is old enough. Start the quiet timer if one is not already running.
     if (!restartQuietTimer) {
-        LOG.debug("browser", "Browser uptime exceeds threshold. Quiet period started — restart will proceed if no streams start within %s minutes.", Math.round(BROWSER_RESTART_QUIET_PERIOD / 60000));
+        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();
         }, BROWSER_RESTART_QUIET_PERIOD);
@@ -1099,8 +1161,8 @@ async function executeBrowserRestart() {
     restartQuietTimer = null;
     // 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).
-    if (gracefulShutdownInProgress || loginModeActive || (getStreamCount() > 0) || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
-        LOG.debug("browser", "Browser restart aborted — preconditions no longer met.");
+    if (gracefulShutdownInProgress || isLoginModeActive() || (getStreamCount() > 0) || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
+        LOG.debug("browser:lifecycle", "Browser restart aborted — preconditions no longer met.");
         return;
     }
     const age = Date.now() - browserLaunchTime;
@@ -1108,7 +1170,7 @@ async function executeBrowserRestart() {
     const minutes = Math.floor((age % 3600000) / 60000);
     LOG.info("Restarting browser for scheduled maintenance (uptime: %sh %sm).", hours, minutes);
     try {
-        // closeBrowser() sets gracefulShutdownInProgress = true internally and performs multi-stage graceful close.
+        // closeBrowser() sets gracefulShutdownInProgress = true internally and performs SIGTERM-based Chrome termination.
         await closeBrowser();
         // Reset the flag since the server is NOT shutting down — only the browser is restarting.
         setGracefulShutdown(false);
@@ -1193,7 +1255,7 @@ export async function prepareExtension() {
                 throw error;
             }
         }
-        LOG.debug("browser", "Extension files prepared successfully.");
+        LOG.debug("browser:lifecycle", "Extension files prepared successfully.");
     }
     catch (error) {
         LOG.error("Extension preparation failed: %s.", formatError(error));