prismcast 1.9.0 → 1.10.0

package/dist/streaming/hlsSegments.js

@@ -1,8 +1,10 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * hlsSegments.ts: HLS segment storage functions for PrismCast.
+ * hlsSegments.ts: HLS segment storage functions for PrismCast. The wait-for-readiness helpers (waitForPlaylist, waitForInitSegment) route their timeout race
+ * through the Clock port (see utils/clock.ts) so tests can deterministically simulate "promise resolves before timeout" vs "timeout fires before promise"
+ * without depending on real timers - the race is exactly the pattern Node's synchronous mock.timers.tick cannot drive reliably.
  */
-import { LOG, raceWithTimeout } from "../utils/index.js";
+import { LOG, realClock } from "../utils/index.js";
 import { CONFIG } from "../config/index.js";
 import { getStream } from "./registry.js";
 /* This module provides functions for storing and retrieving HLS segments, playlists, and init segments. All data is stored in the stream registry's HLSState, which is
@@ -218,7 +220,7 @@ export function updatePlaylist(streamId, content) {
         stream.hls.signalPlaylistReady();
         // Cancel the deferred preroll timer now that real content is available. The timer may still be running for native streams where browser setup completed quickly
         // but the proxy's first poll cycle took longer than the preroll delay (PREROLL_DELAY_MS). Without this, the timer would fire after real content is already
-        // flowing, uselessly seeding preroll state. For streams where the timer already fired (preroll is active), this is a no-op — the timer handle is already null.
+        // flowing, uselessly seeding preroll state. For streams where the timer already fired (preroll is active), this is a no-op - the timer handle is already null.
         if (stream.hls.prerollTimer) {
             clearTimeout(stream.hls.prerollTimer);
             stream.hls.prerollTimer = null;
@@ -240,19 +242,21 @@ export function getPlaylist(streamId) {
  * Waits for the first playlist to be available for a stream.
  * @param streamId - The numeric stream ID.
  * @param timeout - Maximum time to wait in milliseconds.
+ * @param clock - Clock used for the timeout race. Defaults to realClock; tests inject a fake to drive the race deterministically.
  * @returns True if playlist is ready, false if timeout or stream not found.
  */
-export async function waitForPlaylist(streamId, timeout) {
-    return waitForReady(streamId, async (stream) => stream.hls.playlistReady, timeout);
+export async function waitForPlaylist(streamId, timeout, clock = realClock) {
+    return waitForReady(streamId, async (stream) => stream.hls.playlistReady, timeout, clock);
 }
 /**
  * Waits for the first init segment to be available for a stream. Used by MPEG-TS consumers to wait for codec configuration before starting their FFmpeg remuxer.
  * @param streamId - The numeric stream ID.
  * @param timeout - Maximum time to wait in milliseconds.
+ * @param clock - Clock used for the timeout race. Defaults to realClock; tests inject a fake to drive the race deterministically.
  * @returns True if init segment is ready, false if timeout or stream not found.
  */
-export async function waitForInitSegment(streamId, timeout) {
-    return waitForReady(streamId, async (stream) => stream.hls.initSegmentReady, timeout);
+export async function waitForInitSegment(streamId, timeout, clock = realClock) {
+    return waitForReady(streamId, async (stream) => stream.hls.initSegmentReady, timeout, clock);
 }
 // Internal Helpers.
 /**
@@ -261,13 +265,14 @@ export async function waitForInitSegment(streamId, timeout) {
  * @param streamId - The numeric stream ID.
  * @param getPromise - Accessor that extracts the readiness promise from the stream's HLS state.
  * @param timeout - Maximum time to wait in milliseconds.
+ * @param clock - Clock providing the timeout race; the public wrappers thread their own clock through.
  * @returns True if ready before timeout, false otherwise.
  */
-async function waitForReady(streamId, getPromise, timeout) {
+async function waitForReady(streamId, getPromise, timeout, clock) {
     const stream = getStream(streamId);
     if (!stream) {
         return false;
     }
-    return raceWithTimeout(getPromise(stream).then(() => true), timeout).catch(() => false);
+    return clock.raceWithTimeout(getPromise(stream).then(() => true), timeout).catch(() => false);
 }
 //# sourceMappingURL=hlsSegments.js.map

package/dist/streaming/hlsSegments.js.map

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

package/dist/streaming/monitor.d.ts

@@ -1,6 +1,16 @@
-import type { RecoveryMetrics, TabReplacementResult } from "./recovery.js";
+import type { RecoveryMetrics, TabReplacementResult } from "./recovery.ts";
 import type { Frame, Page } from "puppeteer-core";
-import type { Nullable, ResolvedSiteProfile } from "../types/index.js";
+import type { Nullable, ResolvedSiteProfile } from "../types/index.ts";
+/**
+ * Stream info passed to the monitor for status updates.
+ */
+export interface MonitorStreamInfo {
+    channelName: Nullable<string>;
+    numericStreamId: number;
+    serviceName: string;
+    serviceTag?: string;
+    startTime: Date;
+}
 /**
  * Monitors video playback health and attempts escalating recovery when issues are detected. This function runs on an interval, checking video state and triggering
  * increasingly aggressive recovery actions when playback stalls, pauses, or errors occur.
@@ -25,14 +35,4 @@ import type { Nullable, ResolvedSiteProfile } from "../types/index.js";
  *                           If null/undefined, tab replacement is not available and timeouts will eventually trip the circuit breaker.
  * @returns A cleanup function to stop the monitor.
  */
-/**
- * Stream info passed to the monitor for status updates.
- */
-export interface MonitorStreamInfo {
-    channelName: Nullable<string>;
-    numericStreamId: number;
-    serviceName: string;
-    serviceTag?: string;
-    startTime: Date;
-}
 export declare function monitorPlaybackHealth(page: Page, context: Frame | Page, profile: ResolvedSiteProfile, url: string, streamId: string, streamInfo: MonitorStreamInfo, onCircuitBreak: () => void, onTabReplacement?: () => Promise<Nullable<TabReplacementResult>>): () => RecoveryMetrics;

package/dist/streaming/monitor.js

@@ -12,6 +12,30 @@ import { getProviderBySlug } from "../browser/channelSelection.js";
 import { getShowName } from "./showInfo.js";
 import { refreshNativeManifest } from "../native/index.js";
 import { resizeAndMinimizeWindow } from "../browser/cdp.js";
+/**
+ * Monitors video playback health and attempts escalating recovery when issues are detected. This function runs on an interval, checking video state and triggering
+ * increasingly aggressive recovery actions when playback stalls, pauses, or errors occur.
+ *
+ * The monitor includes a circuit breaker that terminates the stream after a configurable number of consecutive failures within a time window. This prevents endless
+ * recovery attempts on fundamentally broken streams.
+ *
+ * Tab replacement recovery: When the browser tab becomes unresponsive (3+ consecutive evaluate timeouts), the monitor triggers tab replacement via the
+ * onTabReplacement callback. This closes the hung tab, creates a fresh one with new capture, and continues the stream. This is more reliable than page.goto-based
+ * recovery because a hung tab may not respond to navigation commands.
+ *
+ * The returned cleanup function should be called when the stream ends to stop monitoring and release resources.
+ *
+ * @param page - The Puppeteer page object.
+ * @param context - The frame or page containing the video element.
+ * @param profile - The site profile for behavior configuration.
+ * @param url - The URL of the stream, needed for page reload recovery.
+ * @param streamId - A concise identifier for the stream, used in log messages.
+ * @param streamInfo - Stream metadata for status updates.
+ * @param onCircuitBreak - Callback function called when circuit breaker trips.
+ * @param onTabReplacement - Optional callback for tab replacement recovery. When provided and 3+ consecutive timeouts occur, this is called to replace the hung tab.
+ *                           If null/undefined, tab replacement is not available and timeouts will eventually trip the circuit breaker.
+ * @returns A cleanup function to stop the monitor.
+ */
 export function monitorPlaybackHealth(page, context, profile, url, streamId, streamInfo, onCircuitBreak, onTabReplacement) {
     /* Monitor state. These track the video's behavior over time and control recovery decisions. Mutable variables are organized into typed state objects by subsystem
      * (recovery, segments, native health, resolution) to clarify ownership and interaction boundaries. Variables that don't belong to a specific subsystem remain as
@@ -56,29 +80,31 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // Last issue tracking for UI display. Stores what triggered recovery and when, so users can see stream history.
     let lastIssueType = null;
     let lastIssueTime = null;
-    // Recovery grace period. After a recovery action, we wait before checking for new issues to give the action time to take effect. L1 (play/unmute) is a quick
-    // action. L2 (source reload) and L3 (page reload) need more time for rebuffering/navigation.
-    const recoveryGracePeriods = [0, 3000, 10000, 10000]; // L0, L1, L2, L3 in milliseconds.
-    // Segment stall timeout. After L2/L3 recovery completes, if no new segments are produced within this timeout, the capture pipeline is considered dead and we
-    // escalate directly to tab replacement. This catches the case where recovery reports success but the MediaRecorder/FFmpeg pipeline has silently died.
-    const SEGMENT_STALL_TIMEOUT = 10000; // 10 seconds.
+    // Recovery grace periods in milliseconds, indexed by recovery level (L0 = no recovery, L1 = play/unmute, L2 = source reload, L3 = page reload). After a recovery
+    // action we wait this long before checking for new issues to give the action time to take effect. L1 is a quick action. L2 and L3 need more time for
+    // rebuffering or navigation to complete.
+    const recoveryGracePeriods = [0, 3_000, 10_000, 10_000];
+    // Segment stall timeout (10 seconds). After L2/L3 recovery completes, if no new segments are produced within this window, the capture pipeline is considered
+    // dead and we escalate directly to tab replacement. This catches the case where recovery reports success but the MediaRecorder/FFmpeg pipeline has silently died.
+    const SEGMENT_STALL_TIMEOUT = 10_000;
     // Tiny segment detection thresholds. Used for continuous segment size monitoring to detect dead capture pipelines. When video capture dies but audio continues,
     // segments contain only audio data. Audio is transcoded at a controlled bitrate (max 512Kbps), so audio-only segments are at most ~192KB for 3-second segments.
-    // The 500KB threshold catches both dead captures (18 bytes) and audio-only captures while staying well below the smallest video preset (480p/3Mbps ≈ 750KB/segment).
-    const TINY_SEGMENT_THRESHOLD = 512000; // 500KB - segments below this indicate dead or degraded capture.
-    const TINY_SEGMENT_COUNT_TRIGGER = 10; // Default trigger count: 10 consecutive tiny segments (~20 seconds with 2-second segments).
+    // The 500KB threshold catches both dead captures (18 bytes) and audio-only captures while staying well below the smallest video preset (480p/3Mbps ~ 750KB/segment).
+    // The default count trigger (10) requires roughly 20 seconds of consecutive tiny segments before action is taken, balancing responsiveness against false positives.
+    const TINY_SEGMENT_THRESHOLD = 512_000;
+    const TINY_SEGMENT_COUNT_TRIGGER = 10;
     // Resolve the service-specific tiny segment count threshold once at monitor startup. Services with extended static content (e.g., Xfinity commercial
     // placeholders) set a higher value to tolerate longer periods of small segments without false positive tab replacements. Dead capture pipelines (segments with
     // no video trafs) always use TINY_SEGMENT_COUNT_TRIGGER regardless of this setting.
     const providerModule = streamInfo.serviceTag ? getProviderBySlug(streamInfo.serviceTag) : undefined;
     const providerTinySegmentThreshold = providerModule?.tinySegmentThreshold ?? TINY_SEGMENT_COUNT_TRIGGER;
     // Segment staleness timeout. When no new segments have been produced for this duration, the capture pipeline is considered dead even though the video element may
-    // appear healthy. This catches the case where Chrome's MediaRecorder silently stops emitting data without raising an error — the input stream stays "open" but no
+    // appear healthy. This catches the case where Chrome's MediaRecorder silently stops emitting data without raising an error - the input stream stays "open" but no
     // data events fire. The 20-second threshold is 4x the maximum expected moof delivery interval (5 seconds) to avoid false positives during normal bursty delivery.
-    const SEGMENT_STALENESS_TIMEOUT = 20000; // 20 seconds.
+    const SEGMENT_STALENESS_TIMEOUT = 20_000;
     // Resolution degradation detection. When the video element's intrinsic resolution is significantly below the configured viewport, the service's ABR is delivering
-    // low-quality content. The threshold is expressed as a ratio — if either dimension is below this fraction of the viewport, the resolution is considered degraded.
-    // 50% catches clear ABR degradation (768×432 on 1080p = 40%) while allowing legitimate 720p content on 1080p (67% > 50%).
+    // low-quality content. The threshold is expressed as a ratio - if either dimension is below this fraction of the viewport, the resolution is considered degraded.
+    // 50% catches clear ABR degradation (768x432 on 1080p = 40%) while allowing legitimate 720p content on 1080p (67% > 50%).
     const RESOLUTION_RATIO_THRESHOLD = 0.5;
     // Grace period in milliseconds after stream start and after each recovery action. Gives ABR time to ramp up before flagging degradation.
     const RESOLUTION_GRACE_PERIOD = 30000;
@@ -95,7 +121,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // Pre-compute the selector type string for video element selection. This is passed to evaluate() calls.
     const selectorType = buildVideoSelectorType(profile);
     // Capture stream context for re-establishing on each interval tick. AsyncLocalStorage context is lost when entering setInterval callbacks. The show name
-    // resolver is lazy — it reads from the live show name cache at log time, so messages always reflect the current program even as shows change mid-stream.
+    // resolver is lazy - it reads from the live show name cache at log time, so messages always reflect the current program even as shows change mid-stream.
     const streamContext = {
         channelName: streamInfo.channelName ?? undefined,
         showNameResolver: () => getShowName(streamInfo.numericStreamId),
@@ -146,12 +172,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * Checks segment delivery health for native streams. Detects stalled streams by comparing the proxy's segment index and last segment timestamp against thresholds.
      * Recovery follows three escalation levels per the plan:
      *
-     * - L1: Re-fetch manifest (handled by the proxy's internal retry loop — consecutive failures up to the threshold)
+     * - L1: Re-fetch manifest (handled by the proxy's internal retry loop - consecutive failures up to the threshold)
      * - L2: Reload page for fresh tokens (same mechanism as proactive token refresh, but triggered by segment staleness)
      * - L3: Fall back to capture mode via tab replacement (stops native proxy, creates fresh page with capture pipeline)
      *
      * Note: The `recoveryState.inProgress` guard at the top of the interval callback prevents re-entry during async L2/L3 recovery. The native path does not need its
-     * own guard — it reuses the shared flag.
+     * own guard - it reuses the shared flag.
      *
      * @param entry - The stream registry entry for the native stream.
      */
@@ -212,7 +238,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             }
             const staleSec = Math.round(stalenessMs / 1000);
             LOG.debug("native:monitor", "Native stream stalled for %s. No new segments in %ss (threshold: %ss).", storeKey, staleSec, Math.round(stalenessThreshold / 1000));
-            // L2: At 4× target duration, attempt a page reload for fresh tokens. This recovers from auth expiry where the manifest URL is still valid but segment URLs
+            // L2: At 4x target duration, attempt a page reload for fresh tokens. This recovers from auth expiry where the manifest URL is still valid but segment URLs
             // are rejected. The proxy continues serving cached segments during the reload.
             if ((stalenessMs > (targetDuration * 4 * 1000)) && (nativeHealthState.recoveryAttempts === 0)) {
                 LOG.warn("Native stream stalled for %s. No new segments in %ss. Attempting recovery.", storeKey, staleSec);
@@ -222,7 +248,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 });
                 return;
             }
-            // L3: At 6× target duration (or if L2 was already attempted), fall back to capture mode via tab replacement.
+            // L3: At 6x target duration (or if L2 was already attempted), fall back to capture mode via tab replacement.
             if ((stalenessMs > (targetDuration * 6 * 1000)) || ((stalenessMs > (targetDuration * 4 * 1000)) && (nativeHealthState.recoveryAttempts > 0))) {
                 LOG.warn("Falling back to capture mode for %s: native streaming stalled after recovery attempt.", storeKey);
                 void runWithStreamContext(streamContext, async () => {
@@ -484,7 +510,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     }
     /**
      * Checks the page reload rate limit. Prunes expired timestamps, checks if the limit has been reached, and records the current timestamp if allowed. Callers are
-     * responsible for logging and handling the rate-limited case — consequences differ by context (circuit break, deferral, fallback to L2).
+     * responsible for logging and handling the rate-limited case - consequences differ by context (circuit break, deferral, fallback to L2).
      * @returns True if a page reload is allowed and the timestamp has been recorded, false if the rate limit has been reached.
      */
     function isPageReloadAllowed() {
@@ -510,7 +536,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      */
     function setRecoveryGracePeriod(level) {
         pendingReMinimize = true;
-        recoveryState.graceUntil = Date.now() + recoveryGracePeriods[level];
+        recoveryState.graceUntil = Date.now() + (recoveryGracePeriods[level] ?? 0);
     }
     /**
      * Handles tab replacement failure by checking the circuit breaker. If the breaker trips, terminates the stream. Returns the appropriate outcome for the caller.
@@ -520,7 +546,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     function handleTabReplacementFailure(context) {
         const cbResult = checkCircuitBreaker(circuitBreaker, Date.now());
         if (cbResult.shouldTrip) {
-            LOG.error("Recovery exhausted (%s) — terminating stream.", context);
+            LOG.error("Recovery exhausted (%s) - terminating stream.", context);
             clearInterval(interval);
             onCircuitBreak();
             return { outcome: "terminated" };
@@ -557,13 +583,13 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // Clear stale recovery metrics so the deferred-success check does not falsely log "Recovered" from leftover state set by recordRecoveryAttempt.
         metrics.currentRecoveryStartTime = null;
         metrics.currentRecoveryMethod = null;
-        LOG.warn("Tab replacement unsuccessful after retry — stream will be terminated.");
+        LOG.warn("Tab replacement unsuccessful after retry - stream will be terminated.");
         const failureOutcome = handleTabReplacementFailure(context);
         // If the circuit breaker did not trip but the old page is gone (handler destroyed it before createPageWithCapture failed), the stream is unrecoverable. The
-        // next monitor tick would silently clear the interval via currentPage.isClosed() with no termination log, no status emission, and no cleanup — creating a
+        // next monitor tick would silently clear the interval via currentPage.isClosed() with no termination log, no status emission, and no cleanup - creating a
         // zombie entry in the registry. Terminate explicitly instead.
         if ((failureOutcome.outcome === "failed") && currentPage.isClosed()) {
-            LOG.error("Tab replacement failed and the original page is no longer available — terminating stream.");
+            LOG.error("Tab replacement failed and the original page is no longer available - terminating stream.");
             clearInterval(interval);
             onCircuitBreak();
             return { outcome: "terminated" };
@@ -595,7 +621,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         recordRecoveryAttempt(metrics, RECOVERY_METHODS.tabReplacement);
         try {
             let result = await onTabReplacement();
-            // First attempt failed — retry once. See idempotency notes in the JSDoc above.
+            // First attempt failed - retry once. See idempotency notes in the JSDoc above.
             if (!result) {
                 LOG.debug("recovery:tab", "Tab replacement attempt 1/2 failed. Retrying...");
                 try {
@@ -612,7 +638,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             return handleExhaustedTabReplacement("tab replacement unsuccessful");
         }
         catch (error) {
-            // Unexpected error (not from onTabReplacement — those are caught internally by the handler in hls.ts and return null). Guard against registry corruption,
+            // Unexpected error (not from onTabReplacement - those are caught internally by the handler in hls.ts and return null). Guard against registry corruption,
             // getStream failures, or other unexpected errors.
             LOG.debug("recovery:tab", "Tab replacement attempt 1/2 failed: %s. Retrying...", formatError(error));
             try {
@@ -684,7 +710,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * Handles the case where no video element was found in the current context. Applies a grace period before triggering recovery: first failure waits, second failure
      * attempts frame re-search, third failure escalates to full page navigation. Distinguishes "no video element" from "video exists but not ready" (buffering).
      *
-     * Always exits the tick — no path falls through to subsequent health checks.
+     * Always exits the tick - no path falls through to subsequent health checks.
      * @param now - Current timestamp for timing calculations.
      */
     async function handleVideoNotFound(now) {
@@ -737,11 +763,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             return;
         }
         // After 3+ consecutive failures, escalate to full page navigation recovery.
-        LOG.warn("Video element not found — recovering via %s.", RECOVERY_METHODS.pageNavigation);
+        LOG.warn("Video element not found - recovering via %s.", RECOVERY_METHODS.pageNavigation);
         // Check circuit breaker for too many failures.
         const cbResult = checkCircuitBreaker(circuitBreaker, now);
         if (cbResult.shouldTrip) {
-            LOG.error("Recovery failed after %s attempts — terminating stream.", cbResult.totalCount);
+            LOG.error("Recovery failed after %s attempts - terminating stream.", cbResult.totalCount);
             clearInterval(interval);
             onCircuitBreak();
             return;
@@ -756,7 +782,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         recordRecoveryAttempt(metrics, RECOVERY_METHODS.pageNavigation);
         // Check page reload limit before attempting recovery.
         if (!isPageReloadAllowed()) {
-            LOG.error("Page navigation rate limit reached (%s in %s minutes) — cannot recover without video element.", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
+            LOG.error("Page navigation rate limit reached (%s in %s minutes) - cannot recover without video element.", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
             clearInterval(interval);
             onCircuitBreak();
             return;
@@ -806,14 +832,14 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             const entry = getStream(streamInfo.numericStreamId);
             const currentIndex = entry?.segmenter?.getSegmentIndex() ?? null;
             if ((currentIndex !== null) && (currentIndex > segmentState.preRecoveryIndex)) {
-                // Segments are flowing — recovery actually succeeded. Clear tracking state.
+                // Segments are flowing - recovery actually succeeded. Clear tracking state.
                 segmentState.preRecoveryIndex = null;
                 segmentState.waitStartTime = null;
                 segmentState.productionStalled = false;
             }
             else if ((now - segmentState.waitStartTime) > SEGMENT_STALL_TIMEOUT) {
                 // No new segments for SEGMENT_STALL_TIMEOUT after recovery grace period. The capture pipeline is dead.
-                LOG.warn("No segments produced for %ss after recovery — capture pipeline may have stalled.", SEGMENT_STALL_TIMEOUT / 1000);
+                LOG.warn("No segments produced for %ss after recovery - capture pipeline may have stalled.", SEGMENT_STALL_TIMEOUT / 1000);
                 segmentState.productionStalled = true;
             }
         }
@@ -834,7 +860,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 const effectiveThreshold = (hasVideo === false) ? TINY_SEGMENT_COUNT_TRIGGER : providerTinySegmentThreshold;
                 LOG.debug("recovery:tracks", "Below-threshold segment: %d bytes, hasVideo=%s, consecutive=%d, threshold=%d.", segmentSize, String(hasVideo), segmentState.consecutiveTinySegments, effectiveThreshold);
                 if (segmentState.consecutiveTinySegments >= effectiveThreshold) {
-                    LOG.warn("Detected %d consecutive undersized segments (%dKB) — capture pipeline may have stalled.", segmentState.consecutiveTinySegments, Math.round(segmentSize / 1024));
+                    LOG.warn("Detected %d consecutive undersized segments (%dKB) - capture pipeline may have stalled.", segmentState.consecutiveTinySegments, Math.round(segmentSize / 1024));
                     // Trigger tab replacement if available, otherwise let circuit breaker handle it via segmentState.productionStalled.
                     if (onTabReplacement && !recoveryState.inProgress) {
                         await executeTabReplacement("tiny segments");
@@ -859,7 +885,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         else if (sizeCheckEntry && (segmentState.lastCheckedIndex > 0) && !withinRecoveryGrace &&
             ((now - segmentState.lastSegmentAdvanceTime) > SEGMENT_STALENESS_TIMEOUT)) {
             /* Segment staleness detection. The segment index has not advanced for longer than SEGMENT_STALENESS_TIMEOUT. This catches the case where Chrome's
-             * MediaRecorder silently stops emitting data — the input Readable stream stays "open" (no end/error events) but no data events fire. The segmenter
+             * MediaRecorder silently stops emitting data - the input Readable stream stays "open" (no end/error events) but no data events fire. The segmenter
              * receives nothing, produces no new segments, and the playlist freezes at the last known sequence number. The video element on the page continues
              * playing normally (currentTime advances, no errors), so all video health checks pass. Without this check, the stale playlist persists indefinitely.
              *
@@ -867,7 +893,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
              * during stream startup before the first segment has been produced. The recovery grace guard prevents false triggering during legitimate pauses (e.g.,
              * after tab replacement while the new capture pipeline is initializing).
              */
-            LOG.warn("No new segments produced for %ss — capture pipeline may have stalled.", SEGMENT_STALENESS_TIMEOUT / 1000);
+            LOG.warn("No new segments produced for %ss - capture pipeline may have stalled.", SEGMENT_STALENESS_TIMEOUT / 1000);
             if (onTabReplacement && !recoveryState.inProgress) {
                 await executeTabReplacement("segment staleness");
                 return true;
@@ -912,7 +938,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             LOG.warn("Video resolution has been degraded for %ss (%s\u00d7%s in %s\u00d7%s viewport). Attempting recovery via %s.", String(degradedDuration), String(state.videoWidth), String(state.videoHeight), String(viewport.width), String(viewport.height), RECOVERY_METHODS.pageNavigation);
             recoveryState.inProgress = true;
             if (!isPageReloadAllowed()) {
-                LOG.warn("Resolution recovery deferred — page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
+                LOG.warn("Resolution recovery deferred - page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
                 // Defer by pushing grace end forward to avoid re-triggering every 2 seconds.
                 resolutionState.graceEnd = now + RESOLUTION_GRACE_PERIOD;
                 recoveryState.inProgress = false;
@@ -947,7 +973,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 resolutionState.graceEnd = now + RESOLUTION_GRACE_PERIOD;
                 return true;
             }
-            // Tab replacement not available — skip directly to acceptance.
+            // Tab replacement not available - skip directly to acceptance.
             resolutionState.recoveryAttempt = 2;
         }
         // Acceptance: resolution still degraded after both recovery attempts. Log once and stop retrying.
@@ -994,12 +1020,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         const elapsedHours = (elapsedMs / 3600000).toFixed(1);
         LOG.info("Proactive reload after %sh of continuous playback (site limit: %sh). Reloading page to prevent stream cutoff.", elapsedHours, String(profile.maxContinuousPlayback));
         recoveryState.inProgress = true;
-        // Check page reload rate limit. Proactive reload is best-effort maintenance — if the reload budget is exhausted from recent error recoveries, we gracefully
+        // Check page reload rate limit. Proactive reload is best-effort maintenance - if the reload budget is exhausted from recent error recoveries, we gracefully
         // yield. If the site eventually cuts the stream, normal error recovery handles it.
         if (!isPageReloadAllowed()) {
-            LOG.warn("Proactive reload deferred — page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
+            LOG.warn("Proactive reload deferred - page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
             // Set a grace period to prevent this deferral from re-triggering every 2 seconds while the rate limit remains in effect. We set recoveryState.graceUntil
-            // directly rather than calling setRecoveryGracePeriod() because no recovery action was performed — the window state is unchanged and pendingReMinimize
+            // directly rather than calling setRecoveryGracePeriod() because no recovery action was performed - the window state is unchanged and pendingReMinimize
             // should not be set.
             recoveryState.graceUntil = now + recoveryGracePeriods[3];
             recoveryState.inProgress = false;
@@ -1043,7 +1069,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // Segment production stall handling. When segments stopped flowing after L2/L3 recovery, the capture pipeline is dead and normal recovery won't help. Skip the
         // escalation ladder and go directly to tab replacement if available.
         if (segmentState.productionStalled && onTabReplacement) {
-            LOG.warn("Capture pipeline still stalled — escalating to %s.", RECOVERY_METHODS.tabReplacement);
+            LOG.warn("Capture pipeline still stalled - escalating to %s.", RECOVERY_METHODS.tabReplacement);
             await executeTabReplacement("capture pipeline stalled");
             return true;
         }
@@ -1051,7 +1077,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         const cbResult = checkCircuitBreaker(circuitBreaker, now);
         if (cbResult.shouldTrip) {
             const elapsedSeconds = circuitBreaker.firstFailureTime ? Math.round((now - circuitBreaker.firstFailureTime) / 1000) : 0;
-            LOG.error("Recovery failed after %s attempts in %ss — terminating stream.", cbResult.totalCount, elapsedSeconds);
+            LOG.error("Recovery failed after %s attempts in %ss - terminating stream.", cbResult.totalCount, elapsedSeconds);
             clearInterval(interval);
             onCircuitBreak();
             return true;
@@ -1084,11 +1110,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         lastIssueTime = now;
         // If a previous recovery was pending (L1 or L2 that didn't result in healthy playback), log that it was unsuccessful before starting the new attempt.
         if (metrics.currentRecoveryMethod !== null) {
-            LOG.warn("%s did not resolve the issue — escalating to %s.", capitalize(metrics.currentRecoveryMethod), recoveryMethod);
+            LOG.warn("%s did not resolve the issue - escalating to %s.", capitalize(metrics.currentRecoveryMethod), recoveryMethod);
         }
         else {
             const issueDesc = getIssueDescription(issueCategory);
-            LOG.warn("Playback %s — recovering via %s.", issueDesc, recoveryMethod);
+            LOG.warn("Playback %s - recovering via %s.", issueDesc, recoveryMethod);
         }
         recordRecoveryAttempt(metrics, recoveryMethod);
         // For L2/L3 recovery, record the current segment index so we can verify segments are flowing after recovery completes.
@@ -1107,21 +1133,21 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     recoveryState.sourceReloadAttempted = true;
                     markStreamDiscontinuity();
                 }
-                recoveryState.graceUntil = now + recoveryGracePeriods[recoveryState.escalationLevel];
+                recoveryState.graceUntil = now + (recoveryGracePeriods[recoveryState.escalationLevel] ?? 0);
                 resetResolutionState();
             }
             else {
                 // Level 3: Page navigation recovery.
                 // Safety check: If page navigation has failed twice consecutively, fall back to source reload.
                 if (consecutiveNavigationFailures >= 2) {
-                    LOG.warn("Page navigation has failed %s consecutive times — falling back to source reload.", consecutiveNavigationFailures);
+                    LOG.warn("Page navigation has failed %s consecutive times - falling back to source reload.", consecutiveNavigationFailures);
                     recoveryState.escalationLevel = 2;
                     consecutiveNavigationFailures = 0;
                     recoveryState.sourceReloadAttempted = false;
                 }
                 else {
                     if (!isPageReloadAllowed()) {
-                        LOG.warn("Page navigation rate limit reached (%s in %s minutes) — falling back to source reload.", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
+                        LOG.warn("Page navigation rate limit reached (%s in %s minutes) - falling back to source reload.", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
                         recoveryState.escalationLevel = 2;
                         recoveryState.sourceReloadAttempted = false;
                     }
@@ -1156,14 +1182,14 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     }
     /* Main monitoring interval. This runs every MONITOR_INTERVAL milliseconds to check video state and trigger recovery when needed.
      *
-     * IMPORTANT: Early returns must call emitStatusUpdate() before returning (except when the stream is terminating, e.g., page closed or circuit breaker tripped). This
+     * Every early return must call emitStatusUpdate() before returning (except when the stream is terminating, e.g., page closed or circuit breaker tripped). This
      * ensures SSE clients always have current status data (duration, memory, health) even during recovery, buffering, or video search periods. Without this, the
      * streamStatuses map becomes stale and new SSE connections receive outdated snapshots.
      *
-     * CHECK ORDER MATTERS: The recoveryState.inProgress check must come BEFORE the currentPage.isClosed() check. During tab replacement, the old page is intentionally
-     * closed while the handler creates a new page. If we check isClosed() first, we would terminate the interval while recovery is still in progress, causing status
-     * updates to stop permanently. The sequence is: (1) intervalCleared for explicit cleanup, (2) recoveryState.inProgress to continue during recovery, (3) isClosed()
-     * for unexpected page termination outside of recovery.
+     * Check ordering: the recoveryState.inProgress check must come before the currentPage.isClosed() check. During tab replacement, the old page is intentionally
+     * closed while the handler creates a new page; if we checked isClosed() first, we would terminate the interval while recovery is still in progress, causing
+     * status updates to stop permanently. The required sequence is: (1) intervalCleared for explicit cleanup, (2) recoveryState.inProgress to continue during
+     * recovery, (3) isClosed() for unexpected page termination outside of recovery.
      */
     const interval = setInterval(() => {
         // Stop monitoring if cleanup was requested.
@@ -1298,7 +1324,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     await resizeAndMinimizeWindow(currentPage);
                 }
                 /* Fullscreen reinforcement. Some streaming sites (notably Hulu) revert the video to a mini-player or PiP layout in response to browser state changes such as
-                 * window minimization or visibility events. Because the video continues playing normally in the smaller frame, no existing recovery condition is triggered — the
+                 * window minimization or visibility events. Because the video continues playing normally in the smaller frame, no existing recovery condition is triggered - the
                  * health monitor sees healthy, progressing playback while the captured frame shows a small video in the corner of the viewport. We verify that the video fills
                  * the viewport on every healthy tick and re-apply CSS fullscreen styling when it shrinks. The response is graduated: basic CSS first (sufficient for
                  * well-behaved sites like Hulu), escalating to !important priority only if basic styles don't hold by the next tick. The readyState guard prevents false
@@ -1411,7 +1437,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     lastIssueTime = Date.now();
                     // After 3 consecutive timeouts, attempt tab replacement if the callback is available.
                     if ((consecutiveTimeouts >= 3) && onTabReplacement) {
-                        LOG.warn("Tab unresponsive — recovering via %s.", RECOVERY_METHODS.tabReplacement);
+                        LOG.warn("Tab unresponsive - recovering via %s.", RECOVERY_METHODS.tabReplacement);
                         await executeTabReplacement("tab unresponsive");
                         return;
                     }