prismcast 1.10.2 → 1.11.0

package/dist/utils/delay.d.ts

@@ -1,33 +1,66 @@
+import type { Nullable } from "../types/index.ts";
 /**
- * A cancellable timeout that can be used with Promise.race. The promise resolves to false when the timeout fires, and cancel() clears the timer to prevent it
- * from holding an event loop reference after the race is won by another promise.
+ * A timeout expressed as an abort signal, paired with the disposal its consumer owes. The signal aborts with the caller's own error object as its reason, which
+ * is what the platform's AbortSignal.timeout() cannot express - it always aborts with a generic TimeoutError, forcing every consumer that needs to tell its own
+ * lapse apart from anyone else's to translate at the catch site. Carrying the reason instead means a caller can compare the rejection by reference or by type
+ * and get an exact answer.
  */
-export interface CancellableTimeout {
+export interface TimeoutSignal {
     cancel: () => void;
-    promise: Promise<false>;
+    signal: AbortSignal;
 }
 /**
- * Creates a cancellable timeout for use with Promise.race. Returns a promise that resolves to false after the specified delay, and a cancel function that clears
- * the timer so it does not hold an event loop reference after the race is won by another promise.
+ * Creates a timeout signal that aborts after the given duration, carrying the supplied error as its abort reason.
+ *
+ * The consumer owns the returned handle and must cancel() it once its wait settles. That discipline is what keeps a timer from being disposed at process exit
+ * instead of at settlement: on Windows, libuv disposing a still-pending timeout handle during natural exit can race pending socket cleanup and trip the
+ * UV_HANDLE_CLOSING assertion in libuv's async.c. Cancelling at settlement disposes the handle while the event loop is still healthy, which sidesteps the race
+ * regardless of how soon afterwards the process exits. The timer is also unref'd, so during its bounded pre-settlement window it never by itself holds open an
+ * otherwise-empty loop.
+ *
+ * The default error is built inside the timer callback so a wait that finishes in time allocates nothing.
  * @param ms - The timeout duration in milliseconds.
- * @returns An object with the timeout promise and a cancel function.
+ * @param reason - Optional error to abort with. Defaults to a generic Error naming the duration.
+ * @returns A handle exposing the timeout's signal and the cancel function that disposes its timer.
  */
-export declare function cancellableTimeout(ms: number): CancellableTimeout;
+export declare function timeoutSignal(ms: number, reason?: Error): TimeoutSignal;
 /**
- * Races a promise against a timeout. If the promise resolves before the timeout, its value is returned. If the timeout fires first, the provided error is thrown
- * (or a default Error if none is provided). The timer is always cleaned up via .finally() to prevent orphaned event loop references.
+ * Waits for a promise, bounded by a timeout that throws. If the promise settles first its outcome passes through unchanged; if the bound lapses first, the
+ * caller's exact error object is thrown, so a call site can identify its own lapse by reference or by instanceof rather than by parsing a message.
  *
- * This is the single implementation of the timeout-race-with-cleanup pattern. All code paths that need "promise with timeout" should use this rather than manually
- * constructing timer/promise/race/cleanup sequences.
- * @param promise - The promise to race against the timeout.
+ * This is the throw-shaped wait policy: reach for it when a lapse means the operation failed. The timer's full lifecycle lives here - created before the race
+ * and cancelled in the finally on every exit path - so no call site can forget the cleanup.
+ * @param promise - The promise to wait on.
  * @param timeoutMs - The timeout duration in milliseconds.
- * @param timeoutError - Optional error to throw on timeout. Defaults to a generic Error with the timeout duration.
+ * @param timeoutError - Optional error to throw on timeout. Defaults to a generic Error naming the duration.
  * @returns The resolved value of the promise.
+ * @throws The supplied error (or the default) when the bound lapses first, or the promise's own rejection when it settles first.
+ */
+export declare function waitWithTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutError?: Error): Promise<T>;
+/**
+ * Waits for a promise, bounded by a timeout that yields null. If the promise settles first its value is returned; if the bound lapses first the result is null,
+ * so the caller branches on a value rather than unwinding through a catch.
+ *
+ * This is the value-shaped wait policy: reach for it when a lapse is an ordinary outcome the caller already handles - a shutdown escalating from SIGTERM to
+ * SIGKILL, a tune that did not land, an interception that never arrived. A promise's own rejection still propagates, because a rejection is a failure rather
+ * than a lapse.
+ *
+ * The composition is deliberate. runWithAbort performs no race of its own; it composes the bounds into one signal, hands that signal to the factory, and maps
+ * an abort-time rejection to null. So the factory forwards the signal into waitWithSignal, and that forwarding is what makes the bound genuinely bind on a
+ * promise this code does not own - a factory that ignored its signal would leave a held promise waiting forever. The bound rides timeoutSignal rather than
+ * runWithAbort's own timeout option so every bound in the project flows through the one source that can carry a reason, owns its timer, and is controllable
+ * from a fake clock.
+ *
+ * One constraint belongs to the caller: a promise that can itself resolve null cannot be told apart from a lapse. Callers own that fit.
+ * @param promise - The promise to wait on.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @returns The resolved value of the promise, or null if the bound lapsed first.
  */
-export declare function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutError?: Error): Promise<T>;
+export declare function boundedWait<T>(promise: Promise<T>, timeoutMs: number): Promise<Nullable<T>>;
 /**
  * Creates a promise that resolves after the specified delay. Wraps node:timers/promises.setTimeout so the codebase has a single canonical "sleep" name.
  * @param ms - The delay duration in milliseconds.
  * @returns A promise that resolves after the specified delay.
  */
 export declare function delay(ms: number): Promise<void>;
+//# sourceMappingURL=delay.d.ts.map

package/dist/utils/delay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay.d.ts","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAE5B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAG,aAAa,CAQvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAWjH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAWjG;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrD"}

package/dist/utils/delay.js

@@ -1,36 +1,89 @@
 /* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * delay.ts: Async delay and timeout utilities for PrismCast.
+ * delay.ts: The project's wait policies. homebridge-plugin-utils owns the wait mechanisms - waitWithSignal races a held promise against an interrupt signal,
+ * and runWithAbort carries the return-null-on-abort policy - and this file names the policies built over them exactly once: timeoutSignal is the
+ * reason-carrying interrupt source, waitWithTimeout is the throw-shaped bounded wait, boundedWait is the value-shaped one, and delay is the named sleep. Any
+ * code path that needs "promise with a bound" consumes a policy here rather than re-rolling the timer, race, and cleanup sequence.
+ *
+ * Choosing between the two bounded waits is a question about semantics, not mechanism. A wait whose interruption is exceptional - the operation was supposed
+ * to finish and did not - throws through waitWithTimeout, so the failure travels as an error the caller can distinguish by identity or type. A wait whose
+ * lapse is an ordinary branch the caller was already going to take returns null through boundedWait, so the caller reads it as a value rather than unwinding
+ * through a catch it did not need.
+ *
+ * Each policy owns its timer's entire lifecycle: it creates the handle, races through the library, and cancels in a finally. Centralizing that ownership is
+ * what keeps a forgotten cleanup from leaking a timer at any call site, and it is what guarantees the handle is disposed at settlement while the event loop is
+ * still healthy (see the rationale on timeoutSignal).
  */
+import { runWithAbort, waitWithSignal } from "homebridge-plugin-utils";
 import { setTimeout as nodeSleep } from "node:timers/promises";
 /**
- * Creates a cancellable timeout for use with Promise.race. Returns a promise that resolves to false after the specified delay, and a cancel function that clears
- * the timer so it does not hold an event loop reference after the race is won by another promise.
+ * Creates a timeout signal that aborts after the given duration, carrying the supplied error as its abort reason.
+ *
+ * The consumer owns the returned handle and must cancel() it once its wait settles. That discipline is what keeps a timer from being disposed at process exit
+ * instead of at settlement: on Windows, libuv disposing a still-pending timeout handle during natural exit can race pending socket cleanup and trip the
+ * UV_HANDLE_CLOSING assertion in libuv's async.c. Cancelling at settlement disposes the handle while the event loop is still healthy, which sidesteps the race
+ * regardless of how soon afterwards the process exits. The timer is also unref'd, so during its bounded pre-settlement window it never by itself holds open an
+ * otherwise-empty loop.
+ *
+ * The default error is built inside the timer callback so a wait that finishes in time allocates nothing.
  * @param ms - The timeout duration in milliseconds.
- * @returns An object with the timeout promise and a cancel function.
+ * @param reason - Optional error to abort with. Defaults to a generic Error naming the duration.
+ * @returns A handle exposing the timeout's signal and the cancel function that disposes its timer.
  */
-export function cancellableTimeout(ms) {
-    const { promise, resolve } = Promise.withResolvers();
-    const timer = setTimeout(() => { resolve(false); }, ms);
-    return { cancel: () => { clearTimeout(timer); }, promise };
+export function timeoutSignal(ms, reason) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(reason ?? new Error("Operation timed out after " + String(ms) + "ms.")); }, ms);
+    timer.unref();
+    return { cancel: () => { clearTimeout(timer); }, signal: controller.signal };
 }
 /**
- * Races a promise against a timeout. If the promise resolves before the timeout, its value is returned. If the timeout fires first, the provided error is thrown
- * (or a default Error if none is provided). The timer is always cleaned up via .finally() to prevent orphaned event loop references.
+ * Waits for a promise, bounded by a timeout that throws. If the promise settles first its outcome passes through unchanged; if the bound lapses first, the
+ * caller's exact error object is thrown, so a call site can identify its own lapse by reference or by instanceof rather than by parsing a message.
  *
- * This is the single implementation of the timeout-race-with-cleanup pattern. All code paths that need "promise with timeout" should use this rather than manually
- * constructing timer/promise/race/cleanup sequences.
- * @param promise - The promise to race against the timeout.
+ * This is the throw-shaped wait policy: reach for it when a lapse means the operation failed. The timer's full lifecycle lives here - created before the race
+ * and cancelled in the finally on every exit path - so no call site can forget the cleanup.
+ * @param promise - The promise to wait on.
  * @param timeoutMs - The timeout duration in milliseconds.
- * @param timeoutError - Optional error to throw on timeout. Defaults to a generic Error with the timeout duration.
+ * @param timeoutError - Optional error to throw on timeout. Defaults to a generic Error naming the duration.
  * @returns The resolved value of the promise.
+ * @throws The supplied error (or the default) when the bound lapses first, or the promise's own rejection when it settles first.
+ */
+export async function waitWithTimeout(promise, timeoutMs, timeoutError) {
+    const timeout = timeoutSignal(timeoutMs, timeoutError);
+    try {
+        return await waitWithSignal(promise, timeout.signal);
+    }
+    finally {
+        timeout.cancel();
+    }
+}
+/**
+ * Waits for a promise, bounded by a timeout that yields null. If the promise settles first its value is returned; if the bound lapses first the result is null,
+ * so the caller branches on a value rather than unwinding through a catch.
+ *
+ * This is the value-shaped wait policy: reach for it when a lapse is an ordinary outcome the caller already handles - a shutdown escalating from SIGTERM to
+ * SIGKILL, a tune that did not land, an interception that never arrived. A promise's own rejection still propagates, because a rejection is a failure rather
+ * than a lapse.
+ *
+ * The composition is deliberate. runWithAbort performs no race of its own; it composes the bounds into one signal, hands that signal to the factory, and maps
+ * an abort-time rejection to null. So the factory forwards the signal into waitWithSignal, and that forwarding is what makes the bound genuinely bind on a
+ * promise this code does not own - a factory that ignored its signal would leave a held promise waiting forever. The bound rides timeoutSignal rather than
+ * runWithAbort's own timeout option so every bound in the project flows through the one source that can carry a reason, owns its timer, and is controllable
+ * from a fake clock.
+ *
+ * One constraint belongs to the caller: a promise that can itself resolve null cannot be told apart from a lapse. Callers own that fit.
+ * @param promise - The promise to wait on.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @returns The resolved value of the promise, or null if the bound lapsed first.
  */
-export async function raceWithTimeout(promise, timeoutMs, timeoutError) {
-    const { promise: timeoutPromise, reject: signalTimeout } = Promise.withResolvers();
-    const timer = setTimeout(() => {
-        signalTimeout(timeoutError ?? new Error("Operation timed out after " + String(timeoutMs) + "ms."));
-    }, timeoutMs);
-    return Promise.race([promise, timeoutPromise]).finally(() => { clearTimeout(timer); });
+export async function boundedWait(promise, timeoutMs) {
+    const timeout = timeoutSignal(timeoutMs);
+    try {
+        return await runWithAbort((signal) => waitWithSignal(promise, signal), { signal: timeout.signal });
+    }
+    finally {
+        timeout.cancel();
+    }
 }
 /**
  * Creates a promise that resolves after the specified delay. Wraps node:timers/promises.setTimeout so the codebase has a single canonical "sleep" name.

package/dist/utils/delay.js.map

@@ -1 +1 @@
-{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAY/D;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAE3C,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAS,CAAC;IAC5D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAExD,OAAO,EAAE,MAAM,EAAE,GAAS,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,OAAmB,EAAE,SAAiB,EAAE,YAAoB;IAEnG,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAS,CAAC;IAC1F,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAE5B,aAAa,CAAC,YAAY,IAAI,IAAI,KAAK,CAAC,4BAA4B,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACrG,CAAC,EAAE,SAAS,CAAC,CAAC;IAEd,OAAO,OAAO,CAAC,IAAI,CAAC,CAAE,OAAO,EAAE,cAAc,CAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU;IAEpC,MAAM,SAAS,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC"}
+{"version":3,"file":"delay.js","sourceRoot":"","sources":["../../src/utils/delay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EAAE,UAAU,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAc/D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU,EAAE,MAAc;IAEtD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,4BAA4B,GAAG,MAAM,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAElI,KAAK,CAAC,KAAK,EAAE,CAAC;IAEd,OAAO,EAAE,MAAM,EAAE,GAAS,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAI,OAAmB,EAAE,SAAiB,EAAE,YAAoB;IAEnG,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAEvD,IAAI,CAAC;QAEH,OAAO,MAAM,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,CAAC;YAAS,CAAC;QAET,OAAO,CAAC,MAAM,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,OAAmB,EAAE,SAAiB;IAEzE,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEzC,IAAI,CAAC;QAEH,OAAO,MAAM,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrG,CAAC;YAAS,CAAC;QAET,OAAO,CAAC,MAAM,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,EAAU;IAEpC,MAAM,SAAS,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC"}

package/dist/utils/errors.d.ts

@@ -9,7 +9,39 @@ export declare function formatError(error: unknown): string;
  * Checks whether an error indicates that the browser page or session has been closed or is otherwise unrecoverable. These errors should cause immediate abort of
  * any retry loops rather than continuing to retry an operation that will never succeed. Common unrecoverable errors include closed targets, closed sessions, and
  * detached frames (which occur when the page has been closed mid-operation).
+ *
+ * Matching ignores case. The same dead state reaches callers with different capitalization depending on which Puppeteer or CDP surface raised it, and a
+ * differently-capitalized closed target is the same closed target.
  * @param error - The error to check.
  * @returns True if the error indicates a closed or unrecoverable state.
  */
 export declare function isSessionClosedError(error: unknown): boolean;
+/**
+ * Checks whether an error means the DOM world an operation ran in ceased to exist. Two failure families union here: the page, target, or session is gone (what
+ * isSessionClosedError already covers), and the execution context or frame was torn down by a navigation or a teardown while the page itself may live on.
+ *
+ * The question this answers is about the world, not the work. An operation that failed this way reached no verdict on its own subject, so a caller deciding
+ * whether to discard cached state about that subject learns nothing from it and must keep the state.
+ *
+ * The context and frame wordings are matched as exact phrases rather than single words. A lone "destroyed" or "detached" turns up in errors that have nothing to
+ * do with page death - a DOM node detached from its document, an object destroyed by an unrelated teardown - and matching those would route ordinary failures
+ * into page-death handling. The phrases are the CDP error family; each one does not reach every call surface, since the evaluate wrapper rewrites the
+ * cannot-find-context wording into the context-destroyed one, but other Puppeteer surfaces still emit it directly.
+ *
+ * Composing isSessionClosedError formats the message twice on a call that matches neither family. That trade is deliberate: the session-closed patterns stay
+ * stated in exactly one place, and this runs only on an error path.
+ * @param error - The error to check.
+ * @returns True if the error indicates the page, execution context, or frame the operation ran in is gone.
+ */
+export declare function isPageDeathError(error: unknown): boolean;
+/**
+ * Checks whether an error is the stale-capture-mutex signal: Chrome's tabCapture extension rejects a second concurrent getStream() with "Cannot capture a tab with
+ * an active stream", and that rejection leaks puppeteer-stream's module-level mutex permanently, so the only recovery is a full process restart. This is the single
+ * home for that one literal - every site that must decide the process-exit escalation reads it from here. The predicate is deliberately narrow: session-closed-shaped
+ * rejections are common and benign, so widening it would exit the process on ordinary browser crashes. The related, broader capture-infrastructure classifier
+ * (isCaptureInfrastructureError in recovery.ts) matches this message too, but the process-exit decision this predicate gates stays its own distinct check.
+ * @param error - The error or message to check.
+ * @returns True if the error carries the stale-capture-mutex signature.
+ */
+export declare function isStaleCaptureMutexError(error: unknown): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAaxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE"}

package/dist/utils/errors.js

@@ -2,8 +2,8 @@
  *
  * errors.ts: Error formatting and handling utilities for PrismCast.
  */
-/* These utilities provide consistent error handling and formatting throughout the application. The formatError function extracts meaningful messages from various
- * error types, while isSessionClosedError helps identify unrecoverable browser state errors that should abort retry loops.
+/* These helpers group the error-handling primitives shared across the application: one normalizes arbitrary errors into log-ready text, the others classify
+ * browser-state failures so callers can abort a retry loop early, tell a dead page apart from a bad subject, or escalate an unrecoverable capture.
  */
 /**
  * Formats an error for logging by extracting the message if available, falling back to string conversion for non-Error objects. Trailing punctuation is stripped
@@ -29,12 +29,53 @@ export function formatError(error) {
  * Checks whether an error indicates that the browser page or session has been closed or is otherwise unrecoverable. These errors should cause immediate abort of
  * any retry loops rather than continuing to retry an operation that will never succeed. Common unrecoverable errors include closed targets, closed sessions, and
  * detached frames (which occur when the page has been closed mid-operation).
+ *
+ * Matching ignores case. The same dead state reaches callers with different capitalization depending on which Puppeteer or CDP surface raised it, and a
+ * differently-capitalized closed target is the same closed target.
  * @param error - The error to check.
  * @returns True if the error indicates a closed or unrecoverable state.
  */
 export function isSessionClosedError(error) {
-    const message = formatError(error);
-    const unrecoverablePatterns = ["Target closed", "Session closed", "detached Frame"];
+    const message = formatError(error).toLowerCase();
+    const unrecoverablePatterns = ["target closed", "session closed", "detached frame"];
     return unrecoverablePatterns.some((pattern) => message.includes(pattern));
 }
+/**
+ * Checks whether an error means the DOM world an operation ran in ceased to exist. Two failure families union here: the page, target, or session is gone (what
+ * isSessionClosedError already covers), and the execution context or frame was torn down by a navigation or a teardown while the page itself may live on.
+ *
+ * The question this answers is about the world, not the work. An operation that failed this way reached no verdict on its own subject, so a caller deciding
+ * whether to discard cached state about that subject learns nothing from it and must keep the state.
+ *
+ * The context and frame wordings are matched as exact phrases rather than single words. A lone "destroyed" or "detached" turns up in errors that have nothing to
+ * do with page death - a DOM node detached from its document, an object destroyed by an unrelated teardown - and matching those would route ordinary failures
+ * into page-death handling. The phrases are the CDP error family; each one does not reach every call surface, since the evaluate wrapper rewrites the
+ * cannot-find-context wording into the context-destroyed one, but other Puppeteer surfaces still emit it directly.
+ *
+ * Composing isSessionClosedError formats the message twice on a call that matches neither family. That trade is deliberate: the session-closed patterns stay
+ * stated in exactly one place, and this runs only on an error path.
+ * @param error - The error to check.
+ * @returns True if the error indicates the page, execution context, or frame the operation ran in is gone.
+ */
+export function isPageDeathError(error) {
+    if (isSessionClosedError(error)) {
+        return true;
+    }
+    const message = formatError(error).toLowerCase();
+    const contextDeathPatterns = ["cannot find context with specified id", "execution context is not available", "execution context was destroyed",
+        "frame got detached", "frame was detached"];
+    return contextDeathPatterns.some((pattern) => message.includes(pattern));
+}
+/**
+ * Checks whether an error is the stale-capture-mutex signal: Chrome's tabCapture extension rejects a second concurrent getStream() with "Cannot capture a tab with
+ * an active stream", and that rejection leaks puppeteer-stream's module-level mutex permanently, so the only recovery is a full process restart. This is the single
+ * home for that one literal - every site that must decide the process-exit escalation reads it from here. The predicate is deliberately narrow: session-closed-shaped
+ * rejections are common and benign, so widening it would exit the process on ordinary browser crashes. The related, broader capture-infrastructure classifier
+ * (isCaptureInfrastructureError in recovery.ts) matches this message too, but the process-exit decision this predicate gates stays its own distinct check.
+ * @param error - The error or message to check.
+ * @returns True if the error carries the stale-capture-mutex signature.
+ */
+export function isStaleCaptureMutexError(error) {
+    return formatError(error).includes("Cannot capture a tab with an active stream");
+}
 //# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IAExC,IAAI,OAAe,CAAC;IAEpB,IAAG,KAAK,YAAY,KAAK,EAAE,CAAC;QAE1B,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAG,KAAK,IAAI,CAAC,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAC,EAAE,CAAC;QAElF,OAAO,GAAI,KAA6B,CAAC,OAAO,CAAC;IACnD,CAAC;SAAM,CAAC;QAEN,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,uFAAuF;IACvF,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAEjD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAEnC,MAAM,qBAAqB,GAAG,CAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,CAAE,CAAC;IAEtF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IAExC,IAAI,OAAe,CAAC;IAEpB,IAAG,KAAK,YAAY,KAAK,EAAE,CAAC;QAE1B,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,CAAC;SAAM,IAAG,KAAK,IAAI,CAAC,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAC,EAAE,CAAC;QAElF,OAAO,GAAI,KAA6B,CAAC,OAAO,CAAC;IACnD,CAAC;SAAM,CAAC;QAEN,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,uFAAuF;IACvF,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAEjD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAEjD,MAAM,qBAAqB,GAAG,CAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,CAAE,CAAC;IAEtF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAE7C,IAAG,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAE/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IAEjD,MAAM,oBAAoB,GAAG,CAAE,uCAAuC,EAAE,oCAAoC,EAAE,iCAAiC;QAC7I,oBAAoB,EAAE,oBAAoB,CAAE,CAAC;IAE/C,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IAErD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,4CAA4C,CAAC,CAAC;AACnF,CAAC"}

package/dist/utils/evaluate.d.ts

@@ -49,3 +49,4 @@ export declare class EvaluateAbortError extends Error {
  * @throws Any error from the underlying evaluate call.
  */
 export declare function evaluateWithAbort<T, Args extends unknown[]>(context: Frame | Page, pageFunction: (...args: Args) => T, args?: Args, timeoutMs?: number): Promise<T>;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/utils/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/utils/evaluate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AA8BlD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI,CAG9F;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAGnE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAG3E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAGnF;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBAEjC,SAAS,EAAE,MAAM;CAM9B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;;CAQ5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,OAAO,EAAE,EAC/D,OAAO,EAAE,KAAK,GAAG,IAAI,EACrB,YAAY,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,EAClC,IAAI,CAAC,EAAE,IAAI,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC,CA2CZ"}

package/dist/utils/evaluate.js

@@ -1,6 +1,7 @@
+import { composeSignals, waitWithSignal } from "homebridge-plugin-utils";
 import { getStreamId } from "./streamContext.js";
-import { raceWithTimeout } from "./delay.js";
-/* This module provides a wrapper around Puppeteer's page.evaluate() and frame.evaluate() that adds two critical safety mechanisms:
+import { timeoutSignal } from "./delay.js";
+/* This module provides a wrapper around Puppeteer's page.evaluate() and frame.evaluate() that adds two safety mechanisms:
  *
  * 1. Abort signal: When a stream is terminated, its AbortController is triggered, immediately rejecting all pending evaluate calls for that stream. This prevents zombie
  *    CDP calls from hanging for 180 seconds (Puppeteer's default protocolTimeout) when the browser becomes unresponsive.
@@ -11,8 +12,12 @@ import { raceWithTimeout } from "./delay.js";
  * The wrapper automatically retrieves the abort signal from this module's local AbortController map using the stream context from AsyncLocalStorage. If no
  * stream context is available (e.g., during browser initialization), it falls back to timeout-only behavior.
  *
- * When aborting or timing out, the underlying CDP call is still pending in Puppeteer - we just stop waiting for it locally. We attach a no-op .catch() to the
- * evaluate promise to suppress unhandled rejection warnings when the CDP call eventually completes or times out.
+ * Both interrupts are one kind of thing - an abort signal - so they compose into a single signal and the wait is one race rather than a race of races. That
+ * composition is also what keeps the long-lived per-stream signal clean: the composed signal is built per call and registers its dependency internally, so no
+ * user-visible listener ever accumulates on the stream's own signal no matter how many evaluate calls a stream makes.
+ *
+ * When aborting or timing out, the underlying CDP call is still pending in Puppeteer - we just stop waiting for it locally. Waiting through waitWithSignal
+ * observes the evaluate promise on every path, which marks it handled so a CDP call that rejects after we have moved on raises no unhandled rejection.
  */
 // Default timeout for evaluate calls in milliseconds.
 const DEFAULT_EVALUATE_TIMEOUT = 15000;
@@ -85,9 +90,9 @@ export async function evaluateWithAbort(context, pageFunction, args, timeoutMs)
     const timeout = timeoutMs ?? DEFAULT_EVALUATE_TIMEOUT;
     // Get stream context to find the abort signal.
     const streamIdStr = getStreamId();
-    const signal = streamIdStr !== undefined ? getAbortSignal(streamIdStr) : undefined;
-    // Check if already aborted before starting.
-    if (signal?.aborted) {
+    const streamSignal = streamIdStr !== undefined ? getAbortSignal(streamIdStr) : undefined;
+    // Check if already aborted before starting, so a stream that is already gone never issues a CDP call at all.
+    if (streamSignal?.aborted) {
         throw new EvaluateAbortError();
     }
     // Start the evaluate call. We use 'as unknown as' to bypass TypeScript's strict function signature checking since Puppeteer's evaluate accepts various function
@@ -95,23 +100,24 @@ export async function evaluateWithAbort(context, pageFunction, args, timeoutMs)
     const evaluatePromise = args ?
         context.evaluate(pageFunction, ...args) :
         context.evaluate(pageFunction);
-    // Attach a no-op catch to suppress unhandled rejection warnings. When we abort or timeout, the underlying CDP call is still pending and will eventually resolve or
-    // reject. Without this, we'd get unhandled rejection warnings when the CDP call completes after we've moved on.
-    evaluatePromise.catch(() => { });
-    // Race evaluate against timeout using the shared utility. Timer cleanup is handled by raceWithTimeout's .finally().
-    const timeoutRace = raceWithTimeout(evaluatePromise, timeout, new EvaluateTimeoutError(timeout));
-    // If we have an abort signal, add a third racer that rejects when the abort fires.
-    if (signal) {
-        const { promise: abortPromise, reject: rejectAbort } = Promise.withResolvers();
-        // Check if already aborted (race condition protection).
-        if (signal.aborted) {
-            rejectAbort(new EvaluateAbortError());
-        }
-        else {
-            signal.addEventListener("abort", () => { rejectAbort(new EvaluateAbortError()); }, { once: true });
+    // Hold the timeout's reason in a local so the translation below can compare against it by reference. Composing the stream signal with the timeout signal
+    // yields one interrupt source whose reason names which side fired: our own timeoutReason, or - since lifecycle.ts aborts a stream with no argument - the
+    // platform's AbortError for a stream termination. Those two can never be confused, and an evaluate rejection is never the signal's reason at all, so it falls
+    // through verbatim. When there is no stream signal, composeSignals hands back the timeout signal unwrapped and the bound is the whole story.
+    const timeoutReason = new EvaluateTimeoutError(timeout);
+    const timeoutHandle = timeoutSignal(timeout, timeoutReason);
+    const signal = composeSignals(streamSignal, timeoutHandle.signal);
+    try {
+        return await waitWithSignal(evaluatePromise, signal);
+    }
+    catch (error) {
+        if ((error === signal.reason) && (error !== timeoutReason)) {
+            throw new EvaluateAbortError();
         }
-        return Promise.race([timeoutRace, abortPromise]);
+        throw error;
+    }
+    finally {
+        timeoutHandle.cancel();
     }
-    return timeoutRace;
 }
 //# sourceMappingURL=evaluate.js.map

package/dist/utils/evaluate.js.map

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

package/dist/utils/ffmpeg.context.d.ts

@@ -4,3 +4,4 @@ import type { FFmpegContext } from "./ffmpeg.ts";
  * @returns An FFmpegContext populated from the live process.
  */
 export declare function createDefaultFFmpegContext(): FFmpegContext;
+//# sourceMappingURL=ffmpeg.context.d.ts.map

package/dist/utils/ffmpeg.context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.context.d.ts","sourceRoot":"","sources":["../../src/utils/ffmpeg.context.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAuBjD;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,aAAa,CAU1D"}

package/dist/utils/ffmpeg.context.js.map

@@ -1 +1 @@
-{"version":3,"file":"ffmpeg.context.js","sourceRoot":"","sources":["../../src/utils/ffmpeg.context.ts"],"names":[],"mappings":"AAOA,OAAO,iBAAiB,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;;;;GAKG;AACH,KAAK,UAAU,iBAAiB,CAAC,WAAmB;IAElD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAW,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,CAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAE,EAAE,CAAC,CAAC;IAE7F,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IAExC,OAAO;QAEL,WAAW,EAAE,iBAAiB;QAC9B,MAAM,EAAE,UAAU;QAClB,OAAO;QACP,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,iBAAiB;KACzB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ffmpeg.context.js","sourceRoot":"","sources":["../../src/utils/ffmpeg.context.ts"],"names":[],"mappings":"AAQA,OAAO,iBAAiB,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C;;;;;GAKG;AACH,KAAK,UAAU,iBAAiB,CAAC,WAAmB;IAElD,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,EAAW,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,CAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAE,EAAE,CAAC,CAAC;IAE7F,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IAExC,OAAO;QAEL,WAAW,EAAE,iBAAiB;QAC9B,MAAM,EAAE,UAAU;QAClB,OAAO;QACP,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,iBAAiB;KACzB,CAAC;AACJ,CAAC"}

package/dist/utils/ffmpeg.d.ts

@@ -1,9 +1,9 @@
 import type { Readable, Writable } from "node:stream";
 import type { ChildProcess } from "node:child_process";
 /**
- * The runtime context resolveFFmpegPath consumes. Models the I/O boundary used by path resolution: filesystem existence checks, the user's home directory, the
- * detected platform, the spawn-based probe, and the bundled FFmpeg path from the ffmpeg-for-homebridge npm package. Production wires it through
- * createDefaultFFmpegContext (in ffmpeg.context.ts); tests pass a context literal.
+ * The runtime context probeFFmpegPath (and getBundledFFmpegPath) consume. Models the I/O boundary used by path resolution: filesystem existence checks, the
+ * user's home directory, the detected platform, the spawn-based probe, and the bundled FFmpeg path from the ffmpeg-for-homebridge npm package. Production wires
+ * it through createDefaultFFmpegContext (in ffmpeg.context.ts); tests pass a context literal.
  */
 export interface FFmpegContext {
     readonly bundledPath: string | undefined;
@@ -41,8 +41,8 @@ export declare function probeFFmpegPath(ctx?: FFmpegContext): Promise<string | u
 /**
  * Resolves the FFmpeg executable path against the production filesystem. Memoized via memoizeAsync: first call probes; subsequent calls return the cached
  * result. Used by production code paths (server startup, health checks, stream setup). Tests should use probeFFmpegPath against synthetic contexts instead -
- * this function intentionally has no parameters and no test seam so its caching contract is sealed. The memoization correctness (single-shot probe,
- * concurrent-caller dedup, sticky rejection) is exercised by memo.test.ts against the underlying primitive.
+ * this function intentionally takes no parameters, so tests have no way to substitute its dependencies and the caching contract stays sealed. The
+ * memoization correctness (single-shot probe, concurrent-caller dedup, sticky rejection) is exercised by memo.test.ts against the underlying primitive.
  *
  * Sticky-rejection caveat: memoizeAsync caches a probe rejection for the lifetime of the process - all future callers receive the same rejected promise
  * without re-probing. probeFFmpegPath today returns undefined for the "not found" case rather than throwing, so this branch never fires in practice. Future
@@ -61,6 +61,27 @@ export interface FFmpegProcess {
     stdin: Writable;
     stdout: Readable;
 }
+/**
+ * The outcome of classifying an FFmpeg process exit event. A discriminated union on outcome so callers can branch without inspecting an optional message field.
+ */
+export type FfmpegExitOutcome = {
+    outcome: "error";
+    message: string;
+} | {
+    outcome: "normal";
+};
+/**
+ * Classifies an FFmpeg process exit from its reported code and signal. Pure: the shuttingDown suppression happens in the caller before this function is ever
+ * invoked, so this function only ever classifies exits the caller actually wants judged. SIGTERM is graceful termination via kill() and always classifies as
+ * normal regardless of the exit code, because a killed process can still report whatever code it happened to be mid-exit with. A non-zero code is checked before
+ * signal presence, so a non-zero code accompanied by a signal still yields the code-based message; a truthy signal that is not SIGTERM (e.g. SIGKILL, SIGSEGV)
+ * only produces its own message when the code was null.
+ * @param code - The process exit code, or null if the process was terminated by a signal.
+ * @param signal - The signal that terminated the process, or null if it exited via a normal code.
+ * @param label - Descriptive label for the error message (e.g., "FFmpeg", "MPEG-TS remuxer").
+ * @returns The classified outcome: normal, or error with a formatted message.
+ */
+export declare function classifyFfmpegExit(code: number | null, signal: NodeJS.Signals | null, label: string): FfmpegExitOutcome;
 /**
  * Options for buildSpawnFFmpegArgs. Keeping the platform as an injected option (defaulting to process.platform) lets tests verify both the macOS and non-macOS
  * branches independently rather than re-asserting whatever branch the host happens to take.
@@ -116,8 +137,9 @@ export declare function spawnFFmpeg(ffmpegBin: string, audioBitrate: number, onE
 export declare function spawnMpegTsRemuxer(ffmpegBin: string, onError: (error: Error) => void, streamId?: string): FFmpegProcess;
 /**
  * Checks if FFmpeg is available on the system. Wraps the production-cached resolveFFmpegPath, so first call probes the filesystem and subsequent calls return
- * the memoized result. Tests should use probeFFmpegPath against synthetic contexts instead - this function delegates to the singleton resolver and has no test
- * seam.
+ * the memoized result. Tests should use probeFFmpegPath against synthetic contexts instead - this function delegates to the singleton resolver and offers no
+ * way for tests to substitute its dependencies.
  * @returns Promise resolving to true if FFmpeg is available, false otherwise.
  */
 export declare function isFFmpegAvailable(): Promise<boolean>;
+//# sourceMappingURL=ffmpeg.d.ts.map

package/dist/utils/ffmpeg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg.d.ts","sourceRoot":"","sources":["../../src/utils/ffmpeg.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAWvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAG5B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAGzC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAG3C,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAG/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAGnC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,aAA4C,GAAG,MAAM,GAAG,SAAS,CAQ1G;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,GAAG,GAAE,aAA4C,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA0DpH;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,mCAAkE,CAAC;AAIjG;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B,IAAI,EAAE,MAAM,IAAI,CAAC;IAGjB,OAAO,EAAE,YAAY,CAAC;IAGtB,KAAK,EAAE,QAAQ,CAAC;IAGhB,MAAM,EAAE,QAAQ,CAAC;CAClB;AAqBD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE9F;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAmBvH;AAoGD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAGjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,EAAE,CAkCrG;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAYjD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAUxJ;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAUvH;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAG1D"}