supervision 0.2.0-next.1 → 0.2.0-next.2

package/dist/web-video-engine/frame-cache.d.ts

@@ -89,6 +89,7 @@ export interface FrameCacheOptions {
     readonly minExactSlots?: number;
 }
 export declare class FrameCache {
+    private readonly options;
     private readonly exact;
     private readonly preview;
     private exactHits;
@@ -97,6 +98,7 @@ export declare class FrameCache {
     private readonly bucketMs;
     private readonly exactBudgetBytes;
     constructor(options: FrameCacheOptions);
+    resized(width: number, height: number): FrameCache;
     /**
      * Store a crisp full-resolution frame for the exact (scrub) tier under
      * `frame`, the timeline's name for it. `timestampMs` is the decoded

package/dist/web-video-engine/pausable-deadline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A timeout whose budget advances only while its owner is visible. The owner
+ * still decides which work is eligible: this helper never pauses the work
+ * itself, nor any unrelated watchdog.
+ */
+export interface PausableDeadline {
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+}
+export declare function createPausableDeadline(timeoutMs: number, onExpire: () => void): PausableDeadline;

package/dist/web-video-engine/scrub-controller.d.ts

@@ -349,6 +349,8 @@ export declare class ScrubController {
      *  walk. Detaches the iterator and drops the read-ahead so paused ticks
      *  never paint a stale play frame. */
     endPlay(): void;
+    holdOutput(): void;
+    releaseOutput(): void;
     /**
      * Cache lookup helper used by the engine on scrub. Asks the cursor for a
      * cached frame near the target and, if it is far enough from what the canvas
@@ -356,12 +358,14 @@ export declare class ScrubController {
      * calls cursor.seekTo to land the full-res frame; the cursor's emit listener
      * stashes it for the next tick.
      *
-     * The skip-near-current check rejects hits whose timestamp falls within
-     * cacheSkipNearMs of the currently-displayed frame. This is the knob
-     * consumers tune to control single-frame-step UX: a higher value forces a
-     * fresh decode on tighter movements, a value of 0 always serves the cache.
+     * Nearby approximate hits respect cacheSkipNearMs. An exact hit for the
+     * requested frame can advance immediately, without waiting for a decode.
      */
     tryPaintFromCache(timestampMs: number): boolean;
+    /** A new commit needs its own presentation even when its exact pixels were
+     *  already shown by the preceding scrub. Approximate neighbors cannot answer it. */
+    presentExactFromCache(timestampMs: number): boolean;
+    private paintCached;
     private start;
     private runTick;
     private paint;

package/dist/web-video-engine/scrub-cursor.d.ts

@@ -1,4 +1,5 @@
 import type { CreateScrubCursorOptions } from "./create-scrub-cursor";
+import type { DecodeDimensions } from "./decode-resolution";
 import type { FrameCacheStats } from "./frame-cache";
 import type { FrameId, FrameTimeline } from "./frame-timeline";
 import type { GopStats } from "./keyframe-index";
@@ -283,6 +284,8 @@ export interface ScrubTrackInfo {
  *   - close is final; reusing a closed cursor is a programming error.
  */
 export interface ScrubCursor {
+    /** Drains old output and changes frame/cache size without reopening decode. */
+    resizeOutput?(dimensions: DecodeDimensions): Promise<boolean>;
     readonly state: ScrubCursorState;
     readonly track: ScrubTrackInfo;
     readonly isIdle: boolean;

package/dist/web-video-engine/video-engine.d.ts

@@ -1,4 +1,4 @@
-import type { DecodeResolutionStrategy } from "./decode-resolution";
+import type { DecodeResolutionStrategy, DisplayBoxResolutionOptions } from "./decode-resolution";
 import type { DiagnosticsSnapshot, EngineDiagnostics } from "./diagnostics";
 import { type FrameId, type FrameLanding } from "./frame-timeline";
 import type { SeekIntent } from "./scrub-cursor";
@@ -123,6 +123,9 @@ export declare class WebVideoEngine {
     private lastTrace;
     private traceArmed;
     private readonly pending;
+    private presentationVisible;
+    private listeningForPresentationVisibility;
+    private readonly onPresentationVisibilityChange;
     private nextRequestId;
     private metadata;
     /** The loaded source's frame table, held here so a gesture is resolved to a
@@ -156,6 +159,10 @@ export declare class WebVideoEngine {
      */
     bindCanvas: (el: HTMLCanvasElement | null) => void;
     play: () => Promise<void>;
+    /** Changes frames-mode display output without reopening the video. Resolves
+     * with true after worker delivery, or false for unchanged output dimensions.
+     * The host still acknowledges its actual presentation. */
+    setDisplay: (display: DisplayBoxResolutionOptions) => Promise<boolean>;
     pause: () => void;
     togglePlayback: () => void;
     /**
@@ -334,6 +341,9 @@ export declare class WebVideoEngine {
     private request;
     private post;
     private rejectAllPending;
+    private startPresentationVisibilityTracking;
+    private stopPresentationVisibilityTracking;
+    private syncPresentationVisibility;
     /**
      * The frame a target names.
      *
@@ -363,6 +373,7 @@ export type PresentedFrameHandler = (presented: PresentedFrame) => void;
  * getPlaybackState.
  */
 export interface WebVideoEngineHandle {
+    setDisplay(display: DisplayBoxResolutionOptions): Promise<boolean>;
     play(): Promise<void>;
     pause(): void;
     togglePlayback(): void;

package/dist/web-video-engine/worker-protocol.d.ts

@@ -1,6 +1,6 @@
 import type { FrameId, FrameLanding } from "./frame-timeline";
 import type { FrameQuality, SeekIntent } from "./scrub-cursor";
-import type { DecodeResolutionStrategy } from "./decode-resolution";
+import type { DecodeResolutionStrategy, DisplayBoxResolutionOptions } from "./decode-resolution";
 import type { DiagnosticsSnapshot, EngineDiagnostics } from "./diagnostics";
 import type { Rotation } from "./rotation";
 import type { EngineTrace } from "./trace-recorder";
@@ -79,6 +79,9 @@ export interface BindCanvasCommand {
 }
 export type FireAndForgetCommand = BindCanvasCommand | {
     readonly type: "unbindCanvas";
+} | {
+    readonly type: "setPresentationVisibility";
+    readonly visible: boolean;
 } | {
     readonly type: "scrub";
     readonly frameIndex: number;
@@ -109,6 +112,10 @@ export type FireAndForgetCommand = BindCanvasCommand | {
     readonly type: "traceDisarm";
 };
 export type AwaitableCommand = {
+    readonly type: "setDisplay";
+    readonly requestId: RequestId;
+    readonly display: DisplayBoxResolutionOptions;
+} | {
     readonly type: "load";
     readonly requestId: RequestId;
     readonly config: EngineLoadConfig;
@@ -200,6 +207,7 @@ export type ResponseEvent = {
     readonly type: "ack";
     readonly requestId: RequestId;
     readonly landing?: FrameLanding;
+    readonly outputChanged?: boolean;
 } | {
     readonly type: "stats";
     readonly requestId: RequestId;

package/node_modules/supervision-js-core/dist/detections/buffered-detection-timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buffered-detection-timeline.d.ts","sourceRoot":"","sources":["../../src/detections/buffered-detection-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAE3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAG1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAuDxD;;;;;GAKG;AACH,wBAAgB,yCAAyC,CACvD,QAAQ,EAAE,yBAAyB,GAClC,SAAS,cAAc,EAAE,CAI3B;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE;IACP,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC,GAAG,sBAAsB,GACzB,yBAAyB,CA+3B3B;AAED,wBAAgB,8BAA8B,IAAI,oBAAoB,CAWrE"}
+{"version":3,"file":"buffered-detection-timeline.d.ts","sourceRoot":"","sources":["../../src/detections/buffered-detection-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAE3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAG1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAuDxD;;;;;GAKG;AACH,wBAAgB,yCAAyC,CACvD,QAAQ,EAAE,yBAAyB,GAClC,SAAS,cAAc,EAAE,CAI3B;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE;IACP,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC,GAAG,sBAAsB,GACzB,yBAAyB,CA07B3B;AAED,wBAAgB,8BAA8B,IAAI,oBAAoB,CAWrE"}

package/node_modules/supervision-js-core/dist/index.js

@@ -615,6 +615,7 @@ function createBufferedDetectionTimeline(options) {
         duration: null,
         loop: false,
     };
+    let timelineFirstTimestamp = 0;
     let inFlight;
     let incrementalRefresh;
     /** Source version the gate last gave up on, or null while it still waits. */
@@ -754,14 +755,15 @@ function createBufferedDetectionTimeline(options) {
             state.bufferEndTime === null) {
             return;
         }
-        const laps = Math.round((getComparableMediaTime(mediaTime) - mediaTime) / duration);
+        const loopSpan = duration - timelineFirstTimestamp;
+        const laps = Math.round((getComparableMediaTime(mediaTime) - mediaTime) / loopSpan);
         if (laps === 0) {
             return;
         }
         state = {
             ...state,
-            bufferEndTime: state.bufferEndTime - laps * duration,
-            bufferStartTime: state.bufferStartTime - laps * duration,
+            bufferEndTime: state.bufferEndTime - laps * loopSpan,
+            bufferStartTime: state.bufferStartTime - laps * loopSpan,
         };
         notifyBufferChanged();
     };
@@ -864,21 +866,27 @@ function createBufferedDetectionTimeline(options) {
             if (destroyed || !isLoadingEnabled()) {
                 return;
             }
+            adoptFirstTimestamp(prepareOptions?.firstTimestamp);
+            const navigationMediaTime = getNavigationMediaTime(mediaTime);
             if (shouldWaitForPlaybackGate(prepareOptions)) {
-                await waitForPlaybackGate(mediaTime, prepareOptions);
+                await waitForPlaybackGate(navigationMediaTime, prepareOptions);
                 if (destroyed) {
                     return;
                 }
             }
-            await refreshBuffer(mediaTime);
-            anchorWindowToPlayhead(mediaTime);
+            await refreshBuffer(navigationMediaTime);
+            anchorWindowToPlayhead(navigationMediaTime);
         },
         needsBufferPrepare(mediaTime) {
+            const navigationMediaTime = getNavigationMediaTime(mediaTime);
             return (!destroyed &&
                 isLoadingEnabled() &&
-                (!isBuffered(mediaTime) || !inFlightCovers(mediaTime)));
+                (!isInsideBufferedRange(navigationMediaTime) ||
+                    !inFlightCovers(navigationMediaTime)));
         },
         needsPlaybackGateWait(mediaTime, prepareOptions) {
+            adoptFirstTimestamp(prepareOptions?.firstTimestamp);
+            const navigationMediaTime = getNavigationMediaTime(mediaTime);
             if (destroyed ||
                 !isLoadingEnabled() ||
                 !playbackGate?.enabled ||
@@ -888,28 +896,31 @@ function createBufferedDetectionTimeline(options) {
                 return false;
             }
             const availableRanges = options.source.getAvailableRanges();
-            return !createPlaybackGateCoveragePlan(mediaTime, prepareOptions).sourceRanges.every((range) => isRangeCovered(range, availableRanges));
+            return !createPlaybackGateCoveragePlan(navigationMediaTime, prepareOptions).sourceRanges.every((range) => isRangeCovered(range, availableRanges));
         },
         prefetch(mediaTime) {
             if (destroyed || !isLoadingEnabled()) {
                 return;
             }
-            anchorWindowToPlayhead(mediaTime);
-            supersedeLoadOutside(mediaTime);
-            if (!shouldPrefetch(mediaTime)) {
+            const navigationMediaTime = getNavigationMediaTime(mediaTime);
+            anchorWindowToPlayhead(navigationMediaTime);
+            supersedeLoadOutside(navigationMediaTime);
+            if (!shouldPrefetch(navigationMediaTime)) {
                 return;
             }
-            pendingPrefetch = { loadId, mediaTime };
+            pendingPrefetch = { loadId, mediaTime: navigationMediaTime };
             pumpPrefetchQueue();
         },
         selectFrame(mediaTime) {
-            if (!isBuffered(mediaTime)) {
+            const navigationMediaTime = getNavigationMediaTime(mediaTime);
+            if (!isInsideBufferedRange(navigationMediaTime)) {
                 return undefined;
             }
-            return selectDetectionFrame(buffer, getSourceMediaTime(mediaTime), options);
+            return selectDetectionFrame(buffer, getSourceMediaTime(navigationMediaTime), options);
         },
         setTimelineContext(context) {
             timelineContext = context;
+            adoptFirstTimestamp(context.firstTimestamp);
             bufferedSourceVersion = null;
             bufferedVersionRange = null;
         },
@@ -1045,12 +1056,12 @@ function createBufferedDetectionTimeline(options) {
     }
     function createPlaybackGateCoveragePlan(mediaTime, prepareOptions) {
         const requiredAheadSeconds = Math.max(0, playbackGate?.requiredAheadSeconds ?? 0);
-        const comparableMediaTime = getComparableMediaTime(mediaTime);
+        const comparableMediaTime = Math.max(timelineFirstTimestamp, getComparableMediaTime(mediaTime));
         const endTime = getRequiredCoverageEndTime({
             // A looping window counts past the end of media and wraps into the
             // replay, so clamping it to duration would ask for less than it needs.
             duration: isLoopingTimeline() ? null : prepareOptions?.duration,
-            firstTimestamp: prepareOptions?.firstTimestamp,
+            firstTimestamp: timelineFirstTimestamp,
             mediaTime: comparableMediaTime,
             requiredAheadSeconds,
         });
@@ -1137,21 +1148,23 @@ function createBufferedDetectionTimeline(options) {
      * a looping timeline. A plan is stated on the first lap and the window on the
      * playhead's, so across the loop point the two state the same edge a whole lap
      * apart; measured straight, that reads as a window a full lap stale and
-     * rebuilds it on every frame until the plan stops reaching behind zero.
+     * rebuilds it on every frame until the plan stops reaching behind the first
+     * playable timestamp.
      */
     function getWindowDrift(planTime, bufferTime) {
         const drift = Math.abs(planTime - bufferTime);
         if (!isLoopingTimeline() || timelineContext.duration === null) {
             return drift;
         }
-        const wrappedDrift = modulo(drift, timelineContext.duration);
-        return Math.min(wrappedDrift, timelineContext.duration - wrappedDrift);
+        const loopSpan = timelineContext.duration - timelineFirstTimestamp;
+        const wrappedDrift = modulo(drift, loopSpan);
+        return Math.min(wrappedDrift, loopSpan - wrappedDrift);
     }
     function createLoadPlan(requestedStartTime, requestedEndTime) {
         const startTime = Math.min(requestedStartTime, requestedEndTime);
         const endTime = Math.max(startTime, requestedEndTime);
         if (!isLoopingTimeline()) {
-            const clampedStartTime = Math.max(0, startTime);
+            const clampedStartTime = Math.max(timelineFirstTimestamp, startTime);
             const clampedEndTime = Math.max(clampedStartTime, endTime);
             return {
                 endTime: clampedEndTime,
@@ -1165,22 +1178,25 @@ function createBufferedDetectionTimeline(options) {
             };
         }
         const duration = timelineContext.duration ?? 0;
-        if (endTime - startTime >= duration) {
+        const loopSpan = duration - timelineFirstTimestamp;
+        if (endTime - startTime >= loopSpan) {
             return {
                 endTime: duration,
-                sourceRanges: [{ endTime: duration, startTime: 0 }],
-                startTime: 0,
+                sourceRanges: [
+                    { endTime: duration, startTime: timelineFirstTimestamp },
+                ],
+                startTime: timelineFirstTimestamp,
             };
         }
         // Both ends move by the same whole number of laps, so the window keeps its
         // span and its source ranges while its start reads on the media clock: a
         // window counted in the laps playback accumulated is one no host can hold
         // against a current time.
-        const laps = Math.floor(startTime / duration);
+        const laps = Math.floor((startTime - timelineFirstTimestamp) / loopSpan);
         return {
-            endTime: endTime - laps * duration,
-            sourceRanges: getLoopingSourceRanges(startTime, endTime, duration),
-            startTime: startTime - laps * duration,
+            endTime: endTime - laps * loopSpan,
+            sourceRanges: getLoopingSourceRanges(startTime, endTime, duration, timelineFirstTimestamp),
+            startTime: startTime - laps * loopSpan,
         };
     }
     function getBufferedSourceRanges() {
@@ -1192,7 +1208,7 @@ function createBufferedDetectionTimeline(options) {
     function isLoopingTimeline() {
         return (timelineContext.loop &&
             timelineContext.duration !== null &&
-            timelineContext.duration > 0);
+            timelineContext.duration > timelineFirstTimestamp);
     }
     function getComparableMediaTime(mediaTime) {
         if (!isLoopingTimeline() ||
@@ -1201,23 +1217,42 @@ function createBufferedDetectionTimeline(options) {
             timelineContext.duration === null) {
             return mediaTime;
         }
-        const duration = timelineContext.duration;
-        // The representative of mediaTime (mod duration) anchored at the window
+        const loopSpan = timelineContext.duration - timelineFirstTimestamp;
+        // The representative of mediaTime (mod the loop span) anchored at the window
         // start. The mapping must depend only on where the window sits, never on
         // how many laps playback has accumulated, or membership drifts away from
         // what the buffer actually holds. A time less than one lap past the
         // anchor never wraps, so ordinary forward playback cannot ratchet.
         return (state.bufferStartTime +
-            modulo(mediaTime - state.bufferStartTime, duration));
+            modulo(mediaTime - state.bufferStartTime, loopSpan));
     }
     function getSourceMediaTime(mediaTime) {
         if (!isLoopingTimeline() || timelineContext.duration === null) {
             return mediaTime;
         }
-        if (mediaTime >= 0 && mediaTime <= timelineContext.duration) {
+        if (mediaTime >= timelineFirstTimestamp &&
+            mediaTime <= timelineContext.duration) {
             return mediaTime;
         }
-        return modulo(mediaTime, timelineContext.duration);
+        const loopSpan = timelineContext.duration - timelineFirstTimestamp;
+        return (timelineFirstTimestamp +
+            modulo(mediaTime - timelineFirstTimestamp, loopSpan));
+    }
+    function getNavigationMediaTime(mediaTime) {
+        return Math.max(timelineFirstTimestamp, mediaTime);
+    }
+    function adoptFirstTimestamp(firstTimestamp) {
+        if (firstTimestamp === undefined ||
+            !Number.isFinite(firstTimestamp) ||
+            firstTimestamp === timelineFirstTimestamp) {
+            return;
+        }
+        timelineFirstTimestamp = firstTimestamp;
+        loadId += 1;
+        inFlight = undefined;
+        pendingPrefetch = undefined;
+        bufferedSourceVersion = null;
+        bufferedVersionRange = null;
     }
 }
 function createIdleDetectionBufferState() {
@@ -1248,13 +1283,14 @@ function getRequiredCoverageEndTime(options) {
     if (options.duration === null || options.duration === undefined) {
         return requestedEndTime;
     }
-    return Math.min(requestedEndTime, (options.firstTimestamp ?? 0) + Math.max(options.duration, 0));
+    return Math.min(requestedEndTime, Math.max(options.firstTimestamp ?? 0, options.duration));
 }
-function getLoopingSourceRanges(startTime, endTime, duration) {
-    const normalizedStartTime = modulo(startTime, duration);
-    const normalizedEndTime = modulo(endTime, duration);
-    const startCycle = Math.floor(startTime / duration);
-    const endCycle = Math.floor(endTime / duration);
+function getLoopingSourceRanges(startTime, endTime, duration, firstTimestamp = 0) {
+    const loopSpan = duration - firstTimestamp;
+    const normalizedStartTime = firstTimestamp + modulo(startTime - firstTimestamp, loopSpan);
+    const normalizedEndTime = firstTimestamp + modulo(endTime - firstTimestamp, loopSpan);
+    const startCycle = Math.floor((startTime - firstTimestamp) / loopSpan);
+    const endCycle = Math.floor((endTime - firstTimestamp) / loopSpan);
     if (startCycle === endCycle) {
         return [{ endTime: normalizedEndTime, startTime: normalizedStartTime }];
     }
@@ -1262,8 +1298,8 @@ function getLoopingSourceRanges(startTime, endTime, duration) {
     if (normalizedStartTime < duration) {
         ranges.push({ endTime: duration, startTime: normalizedStartTime });
     }
-    if (normalizedEndTime > 0) {
-        ranges.push({ endTime: normalizedEndTime, startTime: 0 });
+    if (normalizedEndTime > firstTimestamp) {
+        ranges.push({ endTime: normalizedEndTime, startTime: firstTimestamp });
     }
     return ranges;
 }