@amazon/vinyl 4.0.1-next.20261017024550 → 4.1.0

package/dist/types/current/playback/createStallMonitor.d.ts

@@ -3,8 +3,8 @@ import type { ReadonlyPlaybackController } from './ReadonlyPlaybackController';
 import { StallEndedReason } from './ReadonlyPlaybackController';
 export interface StallMonitorOptions {
     /**
-     * Seconds the play head must be frozen (no `timeUpdate`) while playing before a stall is
-     * reported. Default: 1
+     * Seconds the play head must be frozen (`currentTime` not advancing) while playing before a
+     * stall is reported. Default: 1
      */
     readonly stallThreshold?: number;
     /**
@@ -13,7 +13,7 @@ export interface StallMonitorOptions {
     readonly pollInterval?: number;
 }
 export interface StallEndedInfo {
-    /** Time of the last `timeUpdate` observed before the play head froze. */
+    /** Time of the last progress observed before the play head froze. */
     readonly started: Timestamp;
     /** Time the stall ended. */
     readonly ended: Timestamp;
@@ -30,14 +30,19 @@ export interface StallMonitorCallbacks {
 }
 /**
  * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
- * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ * (`currentTime` not advancing) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ *
+ * Progress is observed both from `timeUpdate` events and by reading `currentTime` on each poll. A
+ * late `timeUpdate` alone is not a stall: when the main thread is busy (a long task, a GC pause) or
+ * event delivery is delayed, the play head keeps advancing while no `timeUpdate` reaches script,
+ * and the poll sees that advance rather than reporting a freeze.
  *
  * Detection only runs once playback has actually been observed (a `playing` event) and is
  * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
  * reported during initial loading or while awaiting a seek. A detected stall ends when the play
  * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
- * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
- * freeze, so it reflects the full frozen time rather than only the time past the threshold.
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last observed progress before
+ * the freeze, so it reflects the full frozen time rather than only the time past the threshold.
  *
  * Returns a function that stops the monitor.
  */

package/dist/types/current/playback/createStallMonitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createStallMonitor.d.ts","sourceRoot":"","sources":["../../../../src/playback/createStallMonitor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAEhC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CACpC;AAED,MAAM,WAAW,qBAAqB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAA;IACnC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACxD;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,0BAA0B,EACtC,SAAS,EAAE,qBAAqB,EAChC,OAAO,GAAE,mBAAwB,GAClC,MAAM,IAAI,CA+EZ"}
+{"version":3,"file":"createStallMonitor.d.ts","sourceRoot":"","sources":["../../../../src/playback/createStallMonitor.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAEhC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CACpC;AAED,MAAM,WAAW,qBAAqB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAA;IACnC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAA;CACxD;AASD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAC9B,UAAU,EAAE,0BAA0B,EACtC,SAAS,EAAE,qBAAqB,EAChC,OAAO,GAAE,mBAAwB,GAClC,MAAM,IAAI,CA8FZ"}

package/dist/types/current/playback/createStallMonitor.js

@@ -12,24 +12,29 @@ import { StallEndedReason } from './ReadonlyPlaybackController';
 const PROGRESS_EPSILON = 1e-6;
 /**
  * Watches a {@link ReadonlyPlaybackController} for stalls while playing: the play head freezing
- * (no `timeUpdate`) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ * (`currentTime` not advancing) for longer than {@link StallMonitorOptions.stallThreshold} seconds.
+ *
+ * Progress is observed both from `timeUpdate` events and by reading `currentTime` on each poll. A
+ * late `timeUpdate` alone is not a stall: when the main thread is busy (a long task, a GC pause) or
+ * event delivery is delayed, the play head keeps advancing while no `timeUpdate` reaches script,
+ * and the poll sees that advance rather than reporting a freeze.
  *
  * Detection only runs once playback has actually been observed (a `playing` event) and is
  * suspended on `pause`/`seeking`/`emptied` until playback is observed again — so a stall is never
  * reported during initial loading or while awaiting a seek. A detected stall ends when the play
  * head advances again (`playing`) or playback stops for another reason (`pause`/`seeking`/
- * `emptied`); {@link StallEndedInfo.duration} is measured from the last `timeUpdate` before the
- * freeze, so it reflects the full frozen time rather than only the time past the threshold.
+ * `emptied`); {@link StallEndedInfo.duration} is measured from the last observed progress before
+ * the freeze, so it reflects the full frozen time rather than only the time past the threshold.
  *
  * Returns a function that stops the monitor.
  */
 export function createStallMonitor(controller, callbacks, options = {}) {
     const stallThresholdMs = (options.stallThreshold ?? 1) * 1000;
     const pollIntervalMs = (options.pollInterval ?? 0.25) * 1000;
-    // Only detect once playback has been observed; gates out initial load and post-seek buffering.
-    let observedPlaying = false;
-    // Wall-clock time of the last `timeUpdate` — the reference start of any freeze.
+    // Wall-clock time of the last observed progress — the reference start of any freeze.
     let lastProgressAt = Date.now();
+    // Play head position at the last observed progress.
+    let lastProgressPosition = controller.currentTime;
     let inStall = false;
     let pollId = null;
     const { add, dispose } = createDisposer();
@@ -52,11 +57,26 @@ export function createStallMonitor(controller, callbacks, options = {}) {
         pollId = null;
     };
     add(stopPoll);
+    const markProgress = () => {
+        lastProgressAt = Date.now();
+        lastProgressPosition = controller.currentTime;
+    };
     const startPoll = () => {
         if (pollId != null)
             return;
+        // Polls only while playback is observed — started on `playing`, stopped by `suspend` —
+        // which gates out initial load and post-seek buffering.
         pollId = setInterval(() => {
-            if (inStall || !observedPlaying)
+            // The play head advanced without a `timeUpdate` reaching us yet (e.g. a long task
+            // delayed it past this poll): that's progress, not a freeze.
+            if (controller.currentTime - lastProgressPosition >
+                PROGRESS_EPSILON) {
+                if (inStall)
+                    endStall(StallEndedReason.PLAYING);
+                markProgress();
+                return;
+            }
+            if (inStall)
                 return;
             if (Date.now() - lastProgressAt >= stallThresholdMs) {
                 inStall = true;
@@ -68,7 +88,6 @@ export function createStallMonitor(controller, callbacks, options = {}) {
     // playback is observed again.
     const suspend = (reason) => {
         endStall(reason);
-        observedPlaying = false;
         stopPoll();
     };
     add(controller.on('playing', () => {
@@ -78,8 +97,7 @@ export function createStallMonitor(controller, callbacks, options = {}) {
         // Whether resuming or freshly starting, the play head is advancing again, so restart the
         // freeze clock. Without this the poll could immediately re-detect a stall from the stale
         // pre-freeze timestamp before the first post-resume `timeUpdate` resets it.
-        lastProgressAt = Date.now();
-        observedPlaying = true;
+        markProgress();
         startPoll();
     }));
     add(controller.on('timeUpdate', ({ previous, current }) => {
@@ -90,7 +108,7 @@ export function createStallMonitor(controller, callbacks, options = {}) {
         // The play head advanced: close any open stall, then reset the freeze clock.
         if (inStall)
             endStall(StallEndedReason.PLAYING);
-        lastProgressAt = Date.now();
+        markProgress();
     }));
     add(controller.on('pause', () => suspend(StallEndedReason.PAUSE)));
     add(controller.on('seeking', () => suspend(StallEndedReason.SEEKING)));