prismcast 1.5.2 → 1.6.0

package/dist/streaming/monitor.js

@@ -2,10 +2,14 @@ import { EvaluateTimeoutError, LOG, formatError, getAbortSignal, isSessionClosed
 import { RECOVERY_METHODS, capitalize, checkCircuitBreaker, createRecoveryMetrics, formatIssueType, formatRecoveryDuration, getIssueCategory, getIssueDescription, getRecoveryMethod, recordRecoveryAttempt, recordRecoverySuccess, resetCircuitBreaker } from "./recovery.js";
 import { applyVideoStyles, buildVideoSelectorType, checkVideoPresence, enforceVideoVolume, ensurePlayback, findVideoContext, getVideoState, tuneToChannel, validateVideoElement, verifyFullscreen } from "../browser/video.js";
 import { getChannelLogo, getShowName } from "./showInfo.js";
-import { getLastSegmentSize, getStream, getStreamMemoryUsage } from "./registry.js";
+import { getLastSegmentHasVideo, getLastSegmentSize, getStream, getStreamMemoryUsage } from "./registry.js";
 import { CONFIG } from "../config/index.js";
+import { clearProbeCache } from "../native/probe.js";
 import { emitStreamHealthChanged } from "./statusEmitter.js";
 import { getClientSummary } from "./clients.js";
+import { getEffectiveViewport } from "../config/presets.js";
+import { getProviderBySlug } from "../browser/channelSelection.js";
+import { refreshNativeManifest } from "../native/index.js";
 import { resizeAndMinimizeWindow } from "../browser/cdp.js";
 export function monitorPlaybackHealth(page, context, profile, url, streamId, streamInfo, onCircuitBreak, onTabReplacement) {
     /* Monitor state variables. These track the video's behavior over time and control recovery decisions.
@@ -90,11 +94,22 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // 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; // Trigger recovery after 10 consecutive tiny segments (~20 seconds with 2-second segments).
+    const TINY_SEGMENT_COUNT_TRIGGER = 10; // Default trigger count: 10 consecutive tiny segments (~20 seconds with 2-second segments).
+    // Resolve the provider-specific tiny segment count threshold once at monitor startup. Providers 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.providerTag ? getProviderBySlug(streamInfo.providerTag) : 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
     // 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.
+    // Resolution degradation detection. When the video element's intrinsic resolution is significantly below the configured viewport, the provider'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%).
+    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;
     // Fixed margin in milliseconds before the maxContinuousPlayback limit at which a proactive reload is triggered. Two minutes provides enough time for page
     // navigation and video reinitialization to complete before the site enforces its cutoff.
     const PROACTIVE_RELOAD_MARGIN_MS = 120000;
@@ -107,6 +122,232 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     const selectorType = buildVideoSelectorType(profile);
     // Capture stream context for re-establishing on each interval tick. AsyncLocalStorage context is lost when entering setInterval callbacks.
     const streamContext = { channelName: streamInfo.channelName ?? undefined, streamId, url };
+    // Native stream health state. These variables are only used when the stream is in native mode. They track segment delivery health to detect stalled streams
+    // where the provider's manifest stops advancing or segments stop arriving. Native recovery uses the shared `recoveryInProgress` flag rather than a separate flag,
+    // since the interval callback already checks `recoveryInProgress` before dispatching to either the native or capture-mode health check path.
+    let nativeLastCheckedSegmentIndex = 0;
+    let nativeLastSegmentAdvanceTime = Date.now();
+    let nativeHealthIssueType = null;
+    let nativeHealthIssueTime = null;
+    let nativeRecoveryAttempts = 0;
+    // Resolution degradation monitoring. Separate from the existing recovery escalation (L1-L4) which handles broken playback. Resolution degradation is a quality
+    // issue — the stream works but at lower-than-expected resolution. Uses its own tracking and two-step escalation: page reload, then tab replacement.
+    let resolutionGraceEnd = Date.now() + RESOLUTION_GRACE_PERIOD;
+    let resolutionRecoveryAttempt = 0;
+    /**
+     * 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)
+     * - 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 `recoveryInProgress` 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.
+     *
+     * @param entry - The stream registry entry for the native stream.
+     */
+    function checkNativeStreamHealth(entry) {
+        const proxy = entry.nativeProxy;
+        if (!proxy) {
+            emitStatusUpdate();
+            return;
+        }
+        const now = Date.now();
+        const currentSegmentIndex = proxy.getSegmentIndex();
+        const lastSegmentTime = proxy.getLastSegmentTime();
+        const targetDuration = proxy.getTargetDuration();
+        const consecutiveErrors = proxy.getConsecutiveErrors();
+        const storeKey = entry.info.storeKey;
+        // Fast path: if the proxy hit its error threshold and stopped itself, trigger L3 fallback immediately. This avoids waiting for the staleness threshold when hard
+        // errors (HTTP 403, network failures) have already been detected by the proxy's internal retry loop.
+        if (proxy.hasErrored()) {
+            LOG.debug("native:monitor", "Native proxy errored for %s. Initiating capture fallback.", storeKey);
+            nativeHealthIssueType = "proxy error";
+            nativeHealthIssueTime = now;
+            void runWithStreamContext(streamContext, async () => {
+                await executeNativeL3Fallback(entry);
+            });
+            return;
+        }
+        // Check if new segments have been produced since the last tick.
+        if (currentSegmentIndex > nativeLastCheckedSegmentIndex) {
+            nativeLastCheckedSegmentIndex = currentSegmentIndex;
+            nativeLastSegmentAdvanceTime = now;
+            // Clear any previous issue tracking when segments are flowing.
+            if (nativeHealthIssueType) {
+                nativeHealthIssueType = null;
+                nativeHealthIssueTime = null;
+                nativeRecoveryAttempts = 0;
+                LOG.debug("native:monitor", "Native stream healthy for %s. Segments advancing (index %s).", storeKey, currentSegmentIndex);
+            }
+        }
+        // Calculate staleness: time since the last new segment was produced.
+        const stalenessMs = now - nativeLastSegmentAdvanceTime;
+        const stalenessThreshold = targetDuration * 2 * 1000;
+        // Classify health based on segment delivery metrics.
+        let nativeHealth = "healthy";
+        if (consecutiveErrors > 0) {
+            nativeHealth = "recovering";
+            if (!nativeHealthIssueType) {
+                nativeHealthIssueType = "fetch errors";
+                nativeHealthIssueTime = now;
+            }
+            LOG.debug("native:monitor", "Native stream recovering for %s. Consecutive errors: %s.", storeKey, consecutiveErrors);
+        }
+        else if ((stalenessMs > stalenessThreshold) && (lastSegmentTime > 0)) {
+            // Only flag staleness after at least one segment has been produced (lastSegmentTime > 0) and the staleness exceeds the threshold.
+            nativeHealth = "stalled";
+            if (!nativeHealthIssueType) {
+                nativeHealthIssueType = "segment stall";
+                nativeHealthIssueTime = now;
+            }
+            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
+            // are rejected. The proxy continues serving cached segments during the reload.
+            if ((stalenessMs > (targetDuration * 4 * 1000)) && (nativeRecoveryAttempts === 0)) {
+                LOG.warn("Native stream stalled for %s. No new segments in %ss. Attempting recovery.", storeKey, staleSec);
+                nativeRecoveryAttempts++;
+                void runWithStreamContext(streamContext, async () => {
+                    await executeNativeL2Recovery(entry);
+                });
+                return;
+            }
+            // L3: At 6× 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)) && (nativeRecoveryAttempts > 0))) {
+                LOG.warn("Falling back to capture mode for %s: native streaming stalled after recovery attempt.", storeKey);
+                void runWithStreamContext(streamContext, async () => {
+                    await executeNativeL3Fallback(entry);
+                });
+                return;
+            }
+        }
+        emitNativeStatus(entry, nativeHealth);
+    }
+    /**
+     * Emits a status update with native-specific health classification. Populates meaningful fields (health, issue tracking, memory, clients) and zeroes video-specific
+     * fields that are not applicable to native streams.
+     *
+     * @param entry - The stream registry entry.
+     * @param health - The health status to report.
+     */
+    function emitNativeStatus(entry, health) {
+        if (intervalCleared) {
+            return;
+        }
+        const now = Date.now();
+        const memoryBytes = getStreamMemoryUsage(entry).total;
+        const channelKey = entry.info.storeKey;
+        const clientSummary = getClientSummary(streamInfo.numericStreamId);
+        const escalation = (health === "stalled") ? 1 : ((health === "recovering") ? 2 : 0);
+        const status = {
+            bufferingDuration: null,
+            channel: streamInfo.channelName,
+            clientCount: clientSummary.total,
+            clients: clientSummary.clients,
+            currentTime: 0,
+            duration: Math.round((now - streamInfo.startTime.getTime()) / 1000),
+            escalationLevel: escalation,
+            health,
+            id: streamInfo.numericStreamId,
+            lastIssueTime: nativeHealthIssueTime,
+            lastIssueType: nativeHealthIssueType,
+            lastRecoveryTime: null,
+            logoUrl: channelKey ? (getChannelLogo(channelKey) ?? "") : "",
+            memoryBytes,
+            networkState: 0,
+            pageReloadsInWindow: 0,
+            providerName: streamInfo.providerName,
+            readyState: 0,
+            recoveryAttempts: nativeRecoveryAttempts,
+            showName: getShowName(streamInfo.numericStreamId),
+            startTime: streamInfo.startTime.toISOString(),
+            streamingMode: entry.streamingMode,
+            url
+        };
+        emitStreamHealthChanged(status);
+    }
+    /**
+     * L2 recovery for native streams: reloads the page to get fresh authentication tokens and re-intercepts the manifest. Delegates to the shared refreshNativeManifest
+     * helper in the coordinator module, which handles interceptor installation, navigation, probing, isStopped() guards, and proxy updates.
+     *
+     * @param entry - The stream registry entry.
+     */
+    async function executeNativeL2Recovery(entry) {
+        const proxy = entry.nativeProxy;
+        if (!proxy || proxy.isStopped()) {
+            return;
+        }
+        recoveryInProgress = true;
+        LOG.debug("native:monitor", "Starting L2 recovery (page reload) for %s.", entry.info.storeKey);
+        try {
+            const success = await refreshNativeManifest({
+                channelName: entry.info.storeKey,
+                page: currentPage,
+                proxy,
+                streamIdStr: streamId,
+                url
+            });
+            if (success) {
+                // Reset staleness tracking so the monitor gives the refreshed stream time to produce segments.
+                nativeLastSegmentAdvanceTime = Date.now();
+            }
+        }
+        finally {
+            recoveryInProgress = false;
+        }
+    }
+    /**
+     * L3 recovery for native streams: falls back to capture mode via tab replacement. Stops the native proxy, creates a fresh page with capture pipeline, and switches
+     * the stream to capture mode. The existing tab replacement infrastructure handles page creation, capture initialization, segmenter creation, and registry updates.
+     *
+     * If the proxy's onError fires concurrently (from the poll loop hitting its failure threshold), terminateStream runs before this async function gets a chance to
+     * execute. By the time L3 runs, the stream is already terminated and executeTabReplacement returns null, which we handle as a failed outcome.
+     *
+     * @param entry - The stream registry entry.
+     */
+    async function executeNativeL3Fallback(entry) {
+        if (!onTabReplacement) {
+            LOG.warn("Capture fallback not available for %s: no tab replacement handler.", entry.info.storeKey);
+            onCircuitBreak();
+            return;
+        }
+        LOG.debug("native:monitor", "Starting L3 fallback (capture mode) for %s.", entry.info.storeKey);
+        // Stop the native proxy before tab replacement closes the page. The proxy may still be polling and would encounter errors when the page navigates away.
+        if (entry.nativeProxy) {
+            entry.nativeProxy.stop();
+            entry.nativeProxy = null;
+        }
+        // Use the existing tab replacement infrastructure. It sets recoveryInProgress = true internally and clears it in finalizeTabReplacement. It creates a new page
+        // with capture, navigates, sets up playback, creates a segmenter, and updates the registry entry (page, rawCaptureStream, ffmpegProcess, segmenter).
+        const outcome = await executeTabReplacement("native fallback to capture");
+        if (outcome.outcome === "success") {
+            // Tab replacement succeeded. Update the registry to reflect capture mode. The tab replacement handler already set page, rawCaptureStream, ffmpegProcess,
+            // and segmenter on the registry entry. We just need to update the streaming mode and clear audio state.
+            entry.streamingMode = "capture";
+            // Clear separate audio state from the native proxy. Without this, hasAudio remains true and the HLS handler continues serving the master playlist (referencing
+            // video.m3u8 and audio.m3u8) instead of the capture segmenter's variant playlist. Clients that cached the master playlist structure would request stale audio
+            // and video variant playlists pointing to segments that are no longer being updated.
+            entry.hls.hasAudio = false;
+            entry.hls.audioPlaylist = "";
+            entry.hls.audioSegments.clear();
+            entry.hls.videoPlaylist = "";
+            // Clear the probe cache so subsequent tunes to this channel don't re-attempt native streaming.
+            clearProbeCache(entry.info.storeKey);
+            LOG.info("Switched to capture mode for %s: native streaming failed.", entry.info.storeKey);
+            // The monitor's next tick will see streamingMode === "capture" and run the normal video element monitoring path. The state reset from
+            // applyTabReplacementSuccess (called by executeTabReplacement) already initialized all capture-mode monitor variables.
+        }
+        else if (outcome.outcome === "terminated") {
+            // Circuit breaker tripped during tab replacement. Stream is being terminated.
+            LOG.warn("Capture fallback failed for %s: circuit breaker tripped.", entry.info.storeKey);
+        }
+        else {
+            // Tab replacement failed but stream wasn't terminated. The circuit breaker will handle it on the next failure.
+            LOG.warn("Capture fallback failed for %s: tab replacement unsuccessful.", entry.info.storeKey);
+        }
+    }
     // Helper to mark a discontinuity in the HLS playlist after recovery events that disrupt the video source. The segmenter flushes its current fragment buffer and sets
     // a pending discontinuity flag so the next segment boundary includes an #EXT-X-DISCONTINUITY tag. This tells HLS clients to flush their decoder state.
     const markStreamDiscontinuity = () => {
@@ -143,6 +384,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * Emits a status update for this stream.
      */
     function emitStatusUpdate() {
+        // Do not emit after the monitor has been stopped. An in-flight async tick can resume from an await after terminateStream() has called stopMonitor() and
+        // emitStreamRemoved(). Without this guard, the emitStreamHealthChanged() call below would re-add the dead stream to the streamStatuses Map, creating a zombie
+        // entry that persists in SSE snapshots indefinitely.
+        if (intervalCleared) {
+            return;
+        }
         const now = Date.now();
         // Get current memory usage from the stream's HLS segment buffers.
         const entry = getStream(streamInfo.numericStreamId);
@@ -173,6 +420,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             recoveryAttempts: totalRecoveryAttempts,
             showName: getShowName(streamInfo.numericStreamId),
             startTime: streamInfo.startTime.toISOString(),
+            streamingMode: entry?.streamingMode ?? "capture",
             url
         };
         emitStreamHealthChanged(status);
@@ -209,6 +457,27 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         videoNotFoundCount = 0;
         stallCount = 0;
     }
+    /**
+     * Resets resolution monitoring state. Called when resolution reaches expected levels or after any recovery action that restarts ABR negotiation.
+     */
+    function resetResolutionState() {
+        resolutionGraceEnd = Date.now() + RESOLUTION_GRACE_PERIOD;
+        resolutionRecoveryAttempt = 0;
+    }
+    /**
+     * 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).
+     * @returns True if a page reload is allowed and the timestamp has been recorded, false if the rate limit has been reached.
+     */
+    function isPageReloadAllowed() {
+        const reloadWindow = Date.now() - CONFIG.playback.pageReloadWindow;
+        pageReloadTimestamps = pageReloadTimestamps.filter((ts) => ts > reloadWindow);
+        if (pageReloadTimestamps.length >= CONFIG.playback.maxPageReloads) {
+            return false;
+        }
+        pageReloadTimestamps.push(Date.now());
+        return true;
+    }
     /**
      * Resets escalation level and related flags. Called after successful recovery to allow the stream to start from level 0 on future issues.
      */
@@ -256,6 +525,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         resetRecoveryCounters();
         resetEscalationState();
         resetSegmentMonitoringState();
+        resetResolutionState();
         setRecoveryGracePeriod(3);
         resetCircuitBreaker(circuitBreaker);
     }
@@ -423,6 +693,13 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             emitStatusUpdate();
             return;
         }
+        // For native streaming mode, monitor segment delivery health instead of video element state. We check the registry on each tick rather than caching the mode at
+        // startup because the streaming mode is set after the monitor starts (native streaming is attempted after setupStream returns).
+        const nativeEntry = getStream(streamInfo.numericStreamId);
+        if (nativeEntry?.streamingMode === "native") {
+            checkNativeStreamHealth(nativeEntry);
+            return;
+        }
         // Re-establish stream context for this interval tick. AsyncLocalStorage context is lost when entering setInterval callbacks.
         runWithStreamContext(streamContext, async () => {
             try {
@@ -556,15 +833,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     recoveryInProgress = true;
                     recordRecoveryAttempt(metrics, RECOVERY_METHODS.pageNavigation);
                     // Check page reload limit before attempting recovery.
-                    const reloadWindow = now - CONFIG.playback.pageReloadWindow;
-                    pageReloadTimestamps = pageReloadTimestamps.filter((ts) => ts > reloadWindow);
-                    if (pageReloadTimestamps.length >= CONFIG.playback.maxPageReloads) {
+                    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));
                         clearInterval(interval);
                         onCircuitBreak();
                         return;
                     }
-                    pageReloadTimestamps.push(now);
                     // Use the unified recovery function with validation.
                     const recoveryResult = await performPageNavigationRecovery();
                     // Page navigation disrupted the video stream. Mark a discontinuity regardless of navigation success so HLS clients resynchronize their decoders.
@@ -583,6 +857,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                         resetRecoveryCounters();
                         resetEscalationState();
                         resetSegmentMonitoringState();
+                        resetResolutionState();
                     }
                     else {
                         consecutiveNavigationFailures++;
@@ -661,8 +936,14 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     if (segmentSize < TINY_SEGMENT_THRESHOLD) {
                         consecutiveTinySegments++;
                         wasInTinySegmentState = true;
-                        if (consecutiveTinySegments >= TINY_SEGMENT_COUNT_TRIGGER) {
-                            LOG.warn("Detected %d consecutive tiny segments (%d bytes) — capture pipeline is not responding.", consecutiveTinySegments, segmentSize);
+                        // Check track composition to determine the effective threshold. Dead capture pipelines produce audio-only segments (hasVideo=false) and always use the
+                        // default count for fast detection. Segments with video trafs present (hasVideo=true or null) use the provider-specific threshold, which may be higher
+                        // for providers with extended static content (e.g., Xfinity commercial placeholders lasting several minutes).
+                        const hasVideo = getLastSegmentHasVideo(sizeCheckEntry);
+                        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), consecutiveTinySegments, effectiveThreshold);
+                        if (consecutiveTinySegments >= effectiveThreshold) {
+                            LOG.warn("Detected %d consecutive tiny segments (%d bytes, hasVideo=%s) — capture pipeline is not responding.", consecutiveTinySegments, segmentSize, String(hasVideo));
                             // Trigger tab replacement if available, otherwise let circuit breaker handle it via segmentProductionStalled. Return unconditionally after tab
                             // replacement (matching stalled-capture and unresponsive-tab triggers) to avoid falling through the rest of the tick with stale pre-replacement state.
                             if (onTabReplacement && !recoveryInProgress) {
@@ -679,7 +960,8 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                         // Valid segment size. Check for spontaneous recovery from tiny segment state. We don't mark discontinuity here - only tab replacement marks discontinuity.
                         // Self-healing may be transient and not require decoder reset.
                         if (wasInTinySegmentState) {
-                            LOG.debug("recovery:segments", "Segment production self-healed (%d bytes).", segmentSize);
+                            const hasVideo = getLastSegmentHasVideo(sizeCheckEntry);
+                            LOG.debug("recovery:segments", "Segment production self-healed (%d bytes, hasVideo=%s).", segmentSize, String(hasVideo));
                         }
                         // Reset tiny segment tracking.
                         consecutiveTinySegments = 0;
@@ -743,6 +1025,78 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                         fullscreenReapplyCount = 0;
                     }
                 }
+                /* Resolution degradation detection. When a provider's ABR delivers content at a resolution significantly below the configured viewport, the captured frame
+                 * shows a small video in the top-left corner of a larger viewport. This is distinct from fullscreen issues (which the fullscreen reinforcement above handles) —
+                 * the video CSS fills the viewport, but the intrinsic media resolution is low. We monitor video.videoWidth/videoHeight and compare against the effective viewport
+                 * dimensions. The check is gated by healthy playback, outside recovery grace, and non-zero intrinsic dimensions. The 30-second grace period after stream start
+                 * and each recovery allows ABR time to ramp up quality. After two unsuccessful recovery attempts (page reload + tab replacement), the system accepts the
+                 * resolution to avoid infinite loops on legitimately low-resolution content.
+                 */
+                if (isProgressing && !state.paused && !state.error && !state.ended && !withinRecoveryGrace && (state.videoWidth > 0) && (state.videoHeight > 0)) {
+                    const viewport = getEffectiveViewport(CONFIG);
+                    const widthRatio = state.videoWidth / viewport.width;
+                    const heightRatio = state.videoHeight / viewport.height;
+                    const isDegraded = (widthRatio < RESOLUTION_RATIO_THRESHOLD) || (heightRatio < RESOLUTION_RATIO_THRESHOLD);
+                    if (isDegraded) {
+                        LOG.debug("recovery:resolution", "Video resolution: %s\u00d7%s (viewport: %s\u00d7%s, ratio: %s%%\u00d7%s%%).", String(state.videoWidth), String(state.videoHeight), String(viewport.width), String(viewport.height), String(Math.round(widthRatio * 100)), String(Math.round(heightRatio * 100)));
+                    }
+                    // Escalation step 1: page reload. Forces the provider's ABR to restart quality negotiation.
+                    if (isDegraded && (now >= resolutionGraceEnd) && (resolutionRecoveryAttempt === 0)) {
+                        LOG.warn("Video resolution degraded (%s\u00d7%s in %s\u00d7%s viewport). Recovering via %s.", String(state.videoWidth), String(state.videoHeight), String(viewport.width), String(viewport.height), RECOVERY_METHODS.pageNavigation);
+                        recoveryInProgress = true;
+                        // Check page reload rate limit before attempting.
+                        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));
+                            // Defer by pushing grace end forward to avoid re-triggering every 2 seconds.
+                            resolutionGraceEnd = now + RESOLUTION_GRACE_PERIOD;
+                            recoveryInProgress = false;
+                            emitStatusUpdate();
+                            return;
+                        }
+                        pendingReMinimize = true;
+                        const recoveryResult = await performPageNavigationRecovery();
+                        markStreamDiscontinuity();
+                        resolutionRecoveryAttempt = 1;
+                        resolutionGraceEnd = now + RESOLUTION_GRACE_PERIOD;
+                        if (recoveryResult.success && recoveryResult.newContext) {
+                            currentContext = recoveryResult.newContext;
+                            lastPageNavigationTime = Date.now();
+                            LOG.info("Resolution recovery: page reload completed. Waiting for ABR ramp-up.");
+                        }
+                        else {
+                            LOG.warn("Resolution recovery: page reload unsuccessful.");
+                        }
+                        recoveryInProgress = false;
+                        emitStatusUpdate();
+                        return;
+                    }
+                    // Escalation step 2: tab replacement. Creates a fresh page with new capture pipeline and network connections.
+                    if (isDegraded && (now >= resolutionGraceEnd) && (resolutionRecoveryAttempt === 1)) {
+                        if (onTabReplacement) {
+                            LOG.warn("Video resolution still degraded (%s\u00d7%s) after page reload. Recovering via %s.", String(state.videoWidth), String(state.videoHeight), RECOVERY_METHODS.tabReplacement);
+                            const outcome = await executeTabReplacement("resolution degraded");
+                            resolutionRecoveryAttempt = 2;
+                            resolutionGraceEnd = now + RESOLUTION_GRACE_PERIOD;
+                            if (outcome.outcome === "terminated") {
+                                return;
+                            }
+                            return;
+                        }
+                        // Tab replacement not available — skip directly to acceptance.
+                        resolutionRecoveryAttempt = 2;
+                    }
+                    // Acceptance: resolution still degraded after both recovery attempts. Log once and stop retrying.
+                    if (isDegraded && (now >= resolutionGraceEnd) && (resolutionRecoveryAttempt === 2)) {
+                        LOG.warn("Video resolution remains degraded (%s\u00d7%s in %s\u00d7%s viewport) after recovery attempts. Accepting current resolution.", String(state.videoWidth), String(state.videoHeight), String(viewport.width), String(viewport.height));
+                        resolutionRecoveryAttempt = 3;
+                    }
+                    // Resolution is good: clear tracking state so future degradation starts fresh.
+                    if (!isDegraded && (resolutionRecoveryAttempt > 0)) {
+                        LOG.info("Video resolution restored (%s\u00d7%s).", String(state.videoWidth), String(state.videoHeight));
+                        resolutionRecoveryAttempt = 0;
+                        resolutionGraceEnd = 0;
+                    }
+                }
                 /* Stall counter management. We increment stallCount when the video is not progressing and not within buffering grace. We reset to 0 when progression resumes.
                  * This hysteresis prevents reacting to single-frame hiccups.
                  */
@@ -811,9 +1165,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                         recoveryInProgress = true;
                         // Check page reload rate limit before attempting. 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.
-                        const reloadWindow = now - CONFIG.playback.pageReloadWindow;
-                        pageReloadTimestamps = pageReloadTimestamps.filter((ts) => ts > reloadWindow);
-                        if (pageReloadTimestamps.length >= CONFIG.playback.maxPageReloads) {
+                        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));
                             // Set a grace period to prevent this deferral from re-triggering every 2 seconds while the rate limit remains in effect. The 10-second L3 grace
                             // period spaces out re-checks, and the rate-limit window (default 15 minutes) will eventually expire old timestamps to allow the proactive reload. We
@@ -824,7 +1176,6 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                             emitStatusUpdate();
                             return;
                         }
-                        pageReloadTimestamps.push(now);
                         const recoveryResult = await performPageNavigationRecovery();
                         // Page navigation disrupted the video stream. Mark a discontinuity so HLS clients resynchronize their decoders.
                         markStreamDiscontinuity();
@@ -835,6 +1186,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                             LOG.info("Proactive reload completed successfully.");
                             resetRecoveryCounters();
                             resetSegmentMonitoringState();
+                            resetResolutionState();
                         }
                         else {
                             LOG.warn("Proactive reload unsuccessful. Will retry after recovery grace period.");
@@ -936,6 +1288,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                             }
                             // Set grace period to give this recovery level time to take effect before the next check.
                             recoveryGraceUntil = now + recoveryGracePeriods[escalationLevel];
+                            resetResolutionState();
                         }
                         else {
                             /* Level 3: Page navigation recovery. This is the most aggressive recovery - we navigate to the URL again and reinitialize everything.
@@ -950,20 +1303,14 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                                 sourceReloadAttempted = false;
                             }
                             else {
-                                // Check page reload limit to prevent excessive navigations. We allow MAX_PAGE_RELOADS within PAGE_RELOAD_WINDOW.
-                                const reloadWindow = now - CONFIG.playback.pageReloadWindow;
-                                // Prune old timestamps outside the window.
-                                pageReloadTimestamps = pageReloadTimestamps.filter((ts) => {
-                                    return ts > reloadWindow;
-                                });
-                                if (pageReloadTimestamps.length >= CONFIG.playback.maxPageReloads) {
+                                // Check page reload limit to prevent excessive navigations.
+                                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));
                                     escalationLevel = 2;
                                     // Reset source reload tracking so the fallback L2 gets a fair chance.
                                     sourceReloadAttempted = false;
                                 }
                                 else {
-                                    pageReloadTimestamps.push(now);
                                     // Use the unified recovery function with validation.
                                     const recoveryResult = await performPageNavigationRecovery();
                                     // Page navigation disrupted the video stream. Mark a discontinuity regardless of navigation success so HLS clients resynchronize their decoders.
@@ -982,6 +1329,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                                         resetRecoveryCounters();
                                         resetEscalationState();
                                         resetSegmentMonitoringState();
+                                        resetResolutionState();
                                     }
                                     else {
                                         consecutiveNavigationFailures++;