prismcast 1.10.2 → 1.11.0

package/dist/streaming/pretune.js

@@ -2,18 +2,20 @@
  *
  * pretune.ts: Predictive channel pretuning from Channels DVR schedule.
  */
-import { LOG, delay, formatError } from "../utils/index.js";
+import { LOG, formatError } from "../utils/index.js";
+import { clearAllPretuneSafetyTimers, forgetPretuneSafetyTimer, setPretuneSafetyTimer } from "./pretuneTimers.js";
 import { fetchFromDvr, getDeviceMappings, getDvrHost } from "./showInfo.js";
 import { getChannelStreamId, terminateStream } from "./lifecycle.js";
 import { initializeStream, validateChannel } from "./hls.js";
 import { emitCurrentSystemStatus } from "../browser/index.js";
 import { getStream } from "./registry.js";
+import { realClock } from "../utils/clock.js";
 /* This module polls the Channels DVR schedule API to discover upcoming recordings and pretunes channels 30 seconds before they start. When the DVR requests the
  * stream, it's already live with buffered segments - achieving near-instant tuning instead of 3-7 second cold starts.
  *
  * The polling loop runs every 60 seconds, checking for jobs starting within a 5-minute scheduling horizon. For each eligible job (PrismCast channel as the DVR's
- * preferred source), a precise setTimeout is scheduled for 30 seconds before the recording start time. When the timer fires, the module validates the channel,
- * checks for conflicts, and calls initializeStream() with the preTuned flag. A safety timeout tears down unclaimed streams 90 seconds after the scheduled start.
+ * preferred source), a precise setTimeout is scheduled for 30 seconds before the recording start time. When the timer fires, the module checks for conflicts,
+ * validates the channel, and calls initializeStream() with the preTuned flag. A safety timeout tears down unclaimed streams 90 seconds after the scheduled start.
  *
  * Key design decisions:
  * - Only pretune when a PrismCast guide number is the FIRST entry in the job's channels array (DVR's preferred source).
@@ -35,27 +37,26 @@ const SAFETY_TIMEOUT_MS = 90000;
 const MAX_RETRIES = 5;
 // Delay between retry attempts (5 seconds).
 const RETRY_DELAY_MS = 5000;
+const defaultPretuneDeps = { clock: realClock, fetchFromDvr, getDeviceMappings, getDvrHost, initializeStream };
 // State.
 // Interval handle for periodic job polling.
 let pollInterval = null;
 // Active pretune timers keyed by job ID. Used to avoid duplicate scheduling and to clear timers when jobs disappear.
 const activeTimers = new Map();
-// Safety timers keyed by stream ID. Used to tear down unclaimed pretuned streams after the scheduled start time.
-const safetyTimers = new Map();
 // Public API.
 /**
  * Starts the pretune polling loop. Should be called on server startup after show info polling is initialized.
  */
-export function startPretunePolling() {
+export function startPretunePolling(deps = defaultPretuneDeps) {
     if (pollInterval) {
         return;
     }
     // Run the first poll after a short delay to allow the persisted DVR host to load.
     setTimeout(() => {
-        void pollForUpcomingJobs();
+        void pollForUpcomingJobs(deps);
     }, 5000);
     pollInterval = setInterval(() => {
-        void pollForUpcomingJobs();
+        void pollForUpcomingJobs(deps);
     }, POLL_INTERVAL_MS);
 }
 /**
@@ -71,22 +72,19 @@ export function stopPretunePolling() {
         clearTimeout(timer);
     }
     activeTimers.clear();
-    // Clear all safety timers.
-    for (const timer of safetyTimers.values()) {
-        clearTimeout(timer);
-    }
-    safetyTimers.clear();
+    // Clear all safety timers via their owning registry.
+    clearAllPretuneSafetyTimers();
 }
 // Internal Functions.
 /**
  * Polls the Channels DVR API for upcoming scheduled recordings and schedules pretune timers for eligible jobs.
  */
-async function pollForUpcomingJobs() {
-    const host = getDvrHost();
+async function pollForUpcomingJobs(deps) {
+    const host = deps.getDvrHost();
     if (!host) {
         return;
     }
-    const jobs = await fetchFromDvr(host, "/api/v1/jobs");
+    const jobs = await deps.fetchFromDvr(host, "/api/v1/jobs");
     if (jobs.length === 0) {
         return;
     }
@@ -95,7 +93,7 @@ async function pollForUpcomingJobs() {
     // Track which job IDs we see this poll cycle so we can clear timers for removed jobs.
     const seenJobIds = new Set();
     // Get the device mappings once for resolving guide numbers. The cache ensures this is fast on repeated calls.
-    const mappings = await getDeviceMappings(host);
+    const mappings = await deps.getDeviceMappings(host);
     if (mappings.size === 0) {
         return;
     }
@@ -129,7 +127,7 @@ async function pollForUpcomingJobs() {
         LOG.debug("streaming:pretune", "Scheduling pretune for '%s' (%s) in %ds.", job.name, channelId, Math.round(effectiveDelay / 1000));
         const timer = setTimeout(() => {
             activeTimers.delete(job.id);
-            void pretuneChannel(channelId, job.name, startMs);
+            void pretuneChannel(channelId, job.name, startMs, deps);
         }, effectiveDelay);
         activeTimers.set(job.id, timer);
     }
@@ -158,13 +156,13 @@ function resolveGuideNumber(mappings, guideNumber) {
     return undefined;
 }
 /**
- * Pretunes a channel ahead of a scheduled recording. Validates the channel, checks for conflicts, initializes the stream with the preTuned flag, and sets up a
+ * Pretunes a channel ahead of a scheduled recording. Checks for conflicts, validates the channel, initializes the stream with the preTuned flag, and sets up a
  * safety timeout for unclaimed streams. Retries on failure up to MAX_RETRIES times within the pretune window.
  * @param channelId - The PrismCast channel key (e.g., "cnn").
  * @param jobName - The program title for logging (e.g., "Anderson Cooper 360").
  * @param startTimeMs - The recording start time in milliseconds.
  */
-async function pretuneChannel(channelId, jobName, startTimeMs) {
+async function pretuneChannel(channelId, jobName, startTimeMs, deps) {
     // Check if the channel is already streaming.
     const existingStreamId = getChannelStreamId(channelId);
     if (existingStreamId !== undefined) {
@@ -182,7 +180,7 @@ async function pretuneChannel(channelId, jobName, startTimeMs) {
         attempts++;
         try {
             // eslint-disable-next-line no-await-in-loop
-            const streamId = await initializeStream({
+            const streamId = await deps.initializeStream({
                 channel: validation.channel,
                 channelName: channelId,
                 clientAddress: null,
@@ -195,7 +193,7 @@ async function pretuneChannel(channelId, jobName, startTimeMs) {
                 // Set a safety timeout to tear down the stream if no real client connects within 90 seconds of the scheduled start.
                 const safetyDelay = Math.max(0, (startTimeMs + SAFETY_TIMEOUT_MS) - Date.now());
                 const safetyTimer = setTimeout(() => {
-                    safetyTimers.delete(streamId);
+                    forgetPretuneSafetyTimer(streamId);
                     const stream = getStream(streamId);
                     if (stream?.preTuned) {
                         LOG.info("No client connected for pretuned %s. Ending stream.", displayName);
@@ -203,7 +201,7 @@ async function pretuneChannel(channelId, jobName, startTimeMs) {
                         void emitCurrentSystemStatus();
                     }
                 }, safetyDelay);
-                safetyTimers.set(streamId, safetyTimer);
+                setPretuneSafetyTimer(streamId, safetyTimer);
                 return;
             }
         }
@@ -218,7 +216,7 @@ async function pretuneChannel(channelId, jobName, startTimeMs) {
         // Brief delay before retry.
         if (attempts < MAX_RETRIES) {
             // eslint-disable-next-line no-await-in-loop
-            await delay(RETRY_DELAY_MS);
+            await deps.clock.sleep(RETRY_DELAY_MS);
         }
     }
     LOG.warn("All %d pretune attempts failed for %s.", MAX_RETRIES, displayName);

package/dist/streaming/pretune.js.map

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

package/dist/streaming/pretuneTimers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Records the pending safety timer for a pretuned stream, replacing any existing entry for that stream ID. Called by pretune.ts when it schedules the reaper.
+ * @param streamId - The numeric stream ID the timer guards.
+ * @param timer - The timer handle to track.
+ */
+export declare function setPretuneSafetyTimer(streamId: number, timer: ReturnType<typeof setTimeout>): void;
+/**
+ * Forgets a safety timer entry without cancelling it. Called from inside the timer's own callback after it has fired, where clearing the (already-elapsed) timer
+ * would be redundant; we only need to drop the bookkeeping entry.
+ * @param streamId - The numeric stream ID whose entry to drop.
+ */
+export declare function forgetPretuneSafetyTimer(streamId: number): void;
+/**
+ * Cancels and forgets the pending safety timer for a pretuned stream. Called by terminateStream() when a pretuned stream is claimed and torn down through the normal
+ * lifecycle, so the safety timeout - which exists only to reap streams that were never claimed - does not linger in the Map until it fires harmlessly against an
+ * already-gone stream. Safe to call for any stream ID; streams without a pending safety timer are a no-op.
+ * @param streamId - The numeric stream ID whose safety timer to clear.
+ */
+export declare function clearPretuneSafetyTimer(streamId: number): void;
+/**
+ * Cancels and forgets every pending safety timer. Called by stopPretunePolling() on server shutdown so no reaper survives the polling loop.
+ */
+export declare function clearAllPretuneSafetyTimers(): void;
+//# sourceMappingURL=pretuneTimers.d.ts.map

package/dist/streaming/pretuneTimers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pretuneTimers.d.ts","sourceRoot":"","sources":["../../src/streaming/pretuneTimers.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAS9D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAQlD"}

package/dist/streaming/pretuneTimers.js

@@ -0,0 +1,56 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * pretuneTimers.ts: Ownership of the pretune safety-timer registry.
+ *
+ * A pretuned stream is started ahead of its scheduled time and reaped by a per-stream safety timer if no real client ever claims it. That timer must be cancelled
+ * when the stream IS claimed and terminated through the normal lifecycle, so terminateStream() (lifecycle.ts) needs to clear it. This registry lives in its own
+ * leaf module - importing nothing from the streaming graph - so lifecycle.ts can clear a timer without importing pretune.ts. pretune.ts imports lifecycle.ts (for
+ * terminateStream) and hls.ts (for initializeStream/validateChannel), so a direct lifecycle->pretune edge would close a hls -> lifecycle -> pretune -> hls import
+ * cycle. Keeping the timer state here is the single source of truth for the registry and keeps the dependency edges acyclic.
+ */
+// Safety timers keyed by stream ID. Used to tear down unclaimed pretuned streams after the scheduled start time. Owned here so both the producer (pretune.ts, which
+// schedules them) and the consumer (lifecycle.ts, which clears them on normal termination) reference one registry without a cyclic import.
+const safetyTimers = new Map();
+/**
+ * Records the pending safety timer for a pretuned stream, replacing any existing entry for that stream ID. Called by pretune.ts when it schedules the reaper.
+ * @param streamId - The numeric stream ID the timer guards.
+ * @param timer - The timer handle to track.
+ */
+export function setPretuneSafetyTimer(streamId, timer) {
+    // Cancel any prior reaper for this stream before tracking the new one, so the registry holds at most one live timer per stream and an overwritten handle can never
+    // survive to fire against the same stream later. In practice a stream is pretuned once, so this is a no-op; it keeps the registry holding at most one live timer
+    // per stream even if a stream is ever re-registered.
+    clearPretuneSafetyTimer(streamId);
+    safetyTimers.set(streamId, timer);
+}
+/**
+ * Forgets a safety timer entry without cancelling it. Called from inside the timer's own callback after it has fired, where clearing the (already-elapsed) timer
+ * would be redundant; we only need to drop the bookkeeping entry.
+ * @param streamId - The numeric stream ID whose entry to drop.
+ */
+export function forgetPretuneSafetyTimer(streamId) {
+    safetyTimers.delete(streamId);
+}
+/**
+ * Cancels and forgets the pending safety timer for a pretuned stream. Called by terminateStream() when a pretuned stream is claimed and torn down through the normal
+ * lifecycle, so the safety timeout - which exists only to reap streams that were never claimed - does not linger in the Map until it fires harmlessly against an
+ * already-gone stream. Safe to call for any stream ID; streams without a pending safety timer are a no-op.
+ * @param streamId - The numeric stream ID whose safety timer to clear.
+ */
+export function clearPretuneSafetyTimer(streamId) {
+    const timer = safetyTimers.get(streamId);
+    if (timer) {
+        clearTimeout(timer);
+        safetyTimers.delete(streamId);
+    }
+}
+/**
+ * Cancels and forgets every pending safety timer. Called by stopPretunePolling() on server shutdown so no reaper survives the polling loop.
+ */
+export function clearAllPretuneSafetyTimers() {
+    for (const timer of safetyTimers.values()) {
+        clearTimeout(timer);
+    }
+    safetyTimers.clear();
+}
+//# sourceMappingURL=pretuneTimers.js.map

package/dist/streaming/pretuneTimers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pretuneTimers.js","sourceRoot":"","sources":["../../src/streaming/pretuneTimers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,oKAAoK;AACpK,2IAA2I;AAC3I,MAAM,YAAY,GAAG,IAAI,GAAG,EAAyC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB,EAAE,KAAoC;IAE1F,mKAAmK;IACnK,iKAAiK;IACjK,qDAAqD;IACrD,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAElC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IAEvD,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IAEtD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEzC,IAAG,KAAK,EAAE,CAAC;QAET,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B;IAEzC,KAAI,MAAM,KAAK,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;QAEzC,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;IAED,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC"}

package/dist/streaming/recovery.d.ts

@@ -1,5 +1,6 @@
 import type { Frame, Page } from "puppeteer-core";
 import type { Nullable, VideoState } from "../types/index.ts";
+import type { StreamHealthStatus } from "./statusEmitter.ts";
 /**
  * Recovery metrics tracked throughout the stream's lifetime. Returned when the monitor stops for inclusion in termination logs.
  */
@@ -16,6 +17,18 @@ export interface RecoveryMetrics {
     tabReplacementSuccesses: number;
     totalRecoveryTimeMs: number;
 }
+/**
+ * Handle returned by monitorPlaybackHealth. The playback monitor is a self-contained resource node: it owns a polling interval and exposes its accumulated recovery
+ * metrics for reading, separately from stopping. The metrics counters are live throughout the monitor's lifetime and remain valid after disposal (the interval is
+ * cleared but the counter object is retained), so the termination prologue reads getMetrics() while the stream is still live, then dispose() stops the interval -
+ * the same read-then-dispose shape as the capture session's segmenter stats and the native proxy's getStats(). Implements both dispose() (project convention) and
+ * TC39 Symbol.dispose so the monitor composes uniformly with the other capture-mode resources.
+ */
+export interface MonitorHandle extends Disposable {
+    readonly dispose: () => void;
+    readonly getMetrics: () => RecoveryMetrics;
+    readonly [Symbol.dispose]: () => void;
+}
 export declare const RECOVERY_METHODS: {
     readonly pageNavigation: "page navigation";
     readonly playUnmute: "play/unmute";
@@ -78,13 +91,51 @@ export declare function recordRecoverySuccess(metrics: RecoveryMetrics, method:
  */
 export declare function formatRecoveryMetricsSummary(metrics: RecoveryMetrics): string;
 /**
- * Circuit breaker state for tracking failures within a time window. The circuit breaker prevents endless recovery attempts on fundamentally broken streams by
- * terminating after a threshold of failures within a configured window.
+ * State for failure accrual within a sliding time window. This is the single failure-counting primitive in PrismCast: the per-stream circuit breaker below and the
+ * browser relaunch governor (browser/launchGovernor.ts) both judge "have there been too many failures recently?" through it, differing only in the policy bounds they
+ * pass and what they do when the window trips. The state is a plain record the caller owns and persists across calls; the bounds are supplied per call so one primitive
+ * serves consumers with different tolerances without hard-coding any single config value.
  */
-export interface CircuitBreakerState {
+export interface FailureWindowState {
     firstFailureTime: Nullable<number>;
     totalFailureCount: number;
 }
+/**
+ * Policy bounds for a failure window: how long the window lasts and how many failures within it constitute a trip.
+ */
+export interface FailureWindowOptions {
+    readonly threshold: number;
+    readonly windowMs: number;
+}
+/**
+ * Result of recording one failure against a window.
+ */
+export interface FailureWindowResult {
+    readonly totalCount: number;
+    readonly tripped: boolean;
+    readonly withinWindow: boolean;
+}
+/**
+ * Records a failure against a sliding window and reports whether the window has tripped. Deterministic over (state, now, options): given the same inputs it always
+ * mutates the supplied state the same way and returns the same decision plus diagnostics, with no reliance on the wall clock or any module-level state. When a
+ * failure arrives after the window has lapsed, the window restarts from it (count resets to 1) so accrual reflects only the recent window. This is the single
+ * source of truth for failure accrual; consumers differ only in the bounds they pass and what a trip means to them.
+ * @param state - The failure-window state to update.
+ * @param now - The current timestamp in milliseconds.
+ * @param options - The window duration and trip threshold.
+ * @returns The trip decision and diagnostics.
+ */
+export declare function recordFailure(state: FailureWindowState, now: number, options: FailureWindowOptions): FailureWindowResult;
+/**
+ * Resets a failure window to its empty state. Called when sustained health is achieved (the stream recovered; the browser is durably ready).
+ * @param state - The failure-window state to reset.
+ */
+export declare function resetFailureWindow(state: FailureWindowState): void;
+/**
+ * The per-stream circuit breaker's state is a failure window. The alias keeps the breaker's vocabulary at its call sites while there is exactly one underlying state
+ * type and one accrual implementation.
+ */
+export type CircuitBreakerState = FailureWindowState;
 /**
  * Result from checking circuit breaker state.
  */
@@ -94,8 +145,9 @@ export interface CircuitBreakerResult {
     withinWindow: boolean;
 }
 /**
- * Records a failure and checks whether the circuit breaker should trip. This is the single entry point for circuit breaker decisions across every recovery
- * path - any code that wants to count a failure goes through this function. Updates the state in place and returns the trip decision along with diagnostic info.
+ * Records a failure and checks whether the per-stream circuit breaker should trip. This is the single entry point for circuit breaker decisions across every
+ * recovery path - any code that wants to count a stream failure goes through this function. It is the stream-scoped policy binding of recordFailure: the window and
+ * threshold come from CONFIG.recovery, and a trip means "terminate the stream."
  * @param state - The circuit breaker state to update.
  * @param now - The current timestamp.
  * @returns Result indicating whether the circuit breaker should trip and diagnostic info.
@@ -135,3 +187,85 @@ export declare function formatIssueType(state: VideoState, isStalled: boolean, i
  * @returns The issue category for recovery path selection.
  */
 export declare function getIssueCategory(state: VideoState, isStalled: boolean, isBuffering: boolean): "paused" | "buffering" | "other";
+/**
+ * Classifies whether an error originates in Chrome's capture infrastructure (the extension, the capture lock, or stream initialization) rather than in a specific
+ * site or stream. This is the single source of truth for that judgment: the stream-setup path uses it to decide a 503 back-off, and the browser supervisor uses it
+ * to decide whether a setup failure is evidence the browser may no longer be capture-ready. It is layered with, not exclusive of, the narrower isStaleCaptureMutexError
+ * predicate (utils/errors.ts), which matches only the stale-mutex string: a stale-mutex error is also a capture-infrastructure error (so this matches it too), but the
+ * process-exit decision that the stale-mutex case alone warrants stays a distinct check at that predicate's own call sites.
+ * @param error - The error or message to classify.
+ * @returns True when the message carries a capture-infrastructure signature.
+ */
+export declare function isCaptureInfrastructureError(error: unknown): boolean;
+/**
+ * Derives the reported health status for a capture stream from its recovery and playback state. This is the single source of truth for the health precedence
+ * ladder the monitor emits over SSE: an error state - or a page-reload-level escalation (>= 3), which is equally severe - reports "error"; an active escalation
+ * (levels 1-2) reports "recovering"; buffering within the grace window reports "buffering"; consecutive stalls that have not yet crossed the recovery trigger
+ * report "stalled"; otherwise "healthy". Deterministic and side-effect free over its inputs, so the precedence lives in exactly one place and is directly testable.
+ * @param inputs - The recovery escalation level, error flag, buffering flag, and consecutive stall count read from the monitor's state.
+ * @returns The stream health status to report.
+ */
+export declare function deriveStreamHealth(inputs: {
+    escalationLevel: number;
+    hasError: boolean;
+    isBuffering: boolean;
+    stallCount: number;
+}): StreamHealthStatus;
+/**
+ * Decides whether the monitor should trigger a recovery action this tick. This is the single source of truth for the recovery-trigger condition: recovery never
+ * fires inside the post-recovery grace window; otherwise it fires on an error, an ended stream, a persistent pause (paused past the stall-count hysteresis while
+ * outside the buffering grace window), a persistent stall (not progressing past the same hysteresis while outside the buffering grace window), or a stalled
+ * capture pipeline. The buffering grace window filters transient rebuffer pauses so they do not escalate. Deterministic and side-effect free over its inputs.
+ * @param inputs - The grace-window flags, playback state flags, pause/stall counts, the stall-count threshold, and the production-stalled flag from the monitor.
+ * @returns True when a recovery action is warranted.
+ */
+export declare function shouldTriggerRecovery(inputs: {
+    hasEnded: boolean;
+    hasError: boolean;
+    isPaused: boolean;
+    isProgressing: boolean;
+    pauseCount: number;
+    productionStalled: boolean;
+    stallCount: number;
+    stallCountThreshold: number;
+    withinBufferingGrace: boolean;
+    withinRecoveryGrace: boolean;
+}): boolean;
+/**
+ * Computes the recovery escalation level to enter for a fresh recovery episode. This is the single source of truth for the issue-aware escalation ladder: a
+ * paused stream from a clean slate tries L1 (play/unmute) first, since it resolves paused playback roughly half the time; a first attempt for a buffering or
+ * other issue - or a pause that L1 did not fix - escalates to L2 (source reload); and once a source reload has already been attempted, it escalates to L3 (page
+ * navigation). The distinct L3-to-L2 fallback under a navigation rate limit is a separate concern owned by the recovery executor, not this ladder.
+ * @param inputs - The current escalation level, the classified issue category, and whether a source reload has already been attempted this episode.
+ * @returns The escalation level (1, 2, or 3) to enter.
+ */
+export declare function computeNextRecoveryLevel(inputs: {
+    currentEscalationLevel: number;
+    issueCategory: "buffering" | "other" | "paused";
+    sourceReloadAttempted: boolean;
+}): number;
+/**
+ * The health classification and recovery escalation warranted by a native stream's segment-delivery metrics.
+ */
+export interface NativeSegmentHealthDecision {
+    readonly action: "l2" | "l3" | "none";
+    readonly health: StreamHealthStatus;
+    readonly issueType: Nullable<string>;
+}
+/**
+ * Classifies a native (proxied HLS) stream's health from its segment-delivery metrics and decides the recovery escalation, if any. This is the single source of
+ * truth for the native staleness ladder: active fetch errors report "recovering" without escalating from here (the proxy retries internally); otherwise, once at
+ * least one segment has been produced, staleness beyond 2x the target duration reports "stalled", with escalation to an L2 page reload at 4x on the first attempt
+ * and, once that reload has not resolved the stall, an L3 capture fallback. Below the staleness threshold the stream is healthy. Pure and total; the
+ * caller owns the segment-advance bookkeeping, issue-timestamp recording, logging, and firing of the returned action.
+ * @param inputs - Consecutive fetch errors, the last-segment timestamp, prior recovery attempts, staleness in milliseconds, and the target duration in milliseconds.
+ * @returns The health status, the warranted escalation action, and the issue label to record.
+ */
+export declare function classifyNativeSegmentHealth(inputs: {
+    consecutiveErrors: number;
+    lastSegmentTime: number;
+    recoveryAttempts: number;
+    stalenessMs: number;
+    targetDurationMs: number;
+}): NativeSegmentHealthDecision;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/streaming/recovery.d.ts.map

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