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

package/dist/web-video-engine/engine.worker.js

@@ -26172,6 +26172,19 @@
                 return queued.timestampS;
             return this.reachable;
         }
+        async resizeOutput({ width, height }) {
+            await this.exclusive(async () => {
+                if (this.closed || this.outputWidth === undefined)
+                    return;
+                if (this.outputWidth === width && this.outputHeight === height)
+                    return;
+                this.quiesce();
+                this.outputWidth = width;
+                this.outputHeight = height;
+                this.exhausted = true;
+                this.epoch++;
+            });
+        }
         /** The frame at or before `targetS`, or null when nothing precedes it. */
         async frameAt(targetS) {
             const landed = await this.exclusive(() => this.land(targetS));
@@ -26701,6 +26714,25 @@
     function nativeResolution() {
         return { kind: "native" };
     }
+    /**
+     * Decode at the size the frame will actually occupy inside a box the consumer
+     * describes: native aspect fitted into boxWidth x boxHeight, times the clamped
+     * device pixel ratio. Letterboxing is why the box is two numbers and not one,
+     * since a portrait source in a landscape box paints far narrower than the box.
+     *
+     * This is the strategy for presentation "frames". There the consumer owns the
+     * compositor, so it is the only side that knows the box, and viewportResolution
+     * has nothing to read.
+     */
+    function displayBoxResolution(options) {
+        return {
+            kind: "displayBox",
+            boxWidth: options.boxWidth,
+            boxHeight: options.boxHeight,
+            devicePixelRatio: options.devicePixelRatio,
+            maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
+        };
+    }
     /** Runs the descriptor against a context to produce a target decode width. */
     function strategyWidth(strategy, ctx) {
         switch (strategy.kind) {
@@ -27120,6 +27152,9 @@
             ? sampleAtPresentationTime(sample, timeline.fromSourceTime(sample.timestamp))
             : null;
         return {
+            ...(source.resizeOutput
+                ? { resizeOutput: source.resizeOutput.bind(source) }
+                : {}),
             async frameAt(targetS) {
                 return wrap(await source.frameAt(timeline.toSourceTime(targetS)));
             },
@@ -27172,6 +27207,7 @@
         };
         return {
             decodePath: "sample",
+            resizeOutput: async () => undefined,
             // Pool-bound: every outstanding frame is a slot the sink cannot refill.
             playReadAhead: 1,
             track: handle.track,
@@ -27207,6 +27243,9 @@
     function sessionProvider(handle) {
         return {
             decodePath: "session",
+            ...(handle.session.resizeOutput
+                ? { resizeOutput: handle.session.resizeOutput.bind(handle.session) }
+                : {}),
             playReadAhead: PLAYBACK.READ_AHEAD_CANVAS,
             track: handle.track,
             keyframeProbe: handle.keyframeProbe,
@@ -27630,6 +27669,8 @@
     class CanvasSinkScrubCursor {
         provider;
         trackInfo;
+        outputGeneration = 0;
+        outputReads = new Set();
         disposeSource;
         /**
          * Forward-playback iterator. Lives only between attachPlay and detachPlay so
@@ -27669,6 +27710,41 @@
                 this.pendingSeekTargetS === null &&
                 !this.seekDraining);
         }
+        async resizeOutput({ width, height }) {
+            if (!this.provider.resizeOutput) {
+                throw new WebVideoEngineError(WebVideoEngineErrorCode.PresentationMismatch, "this decode source cannot resize frame output in place");
+            }
+            if (this.closed ||
+                (width === this.trackInfo.decodeWidth &&
+                    height === this.trackInfo.decodeHeight))
+                return false;
+            this.outputGeneration++;
+            this.pendingSeekTargetS = null;
+            const returning = this.iterator?.return();
+            this.iterator = null;
+            this.nextPending = 0;
+            this.lastEmittedFrame = null;
+            await Promise.allSettled([
+                ...this.outputReads,
+                ...(returning ? [returning] : []),
+            ]);
+            if (this.closed)
+                return false;
+            await this.provider.resizeOutput({ width, height });
+            if (this.closed)
+                return false;
+            this.trackInfo = {
+                ...this.trackInfo,
+                decodeWidth: width,
+                decodeHeight: height,
+            };
+            return true;
+        }
+        trackOutputRead(read) {
+            this.outputReads.add(read);
+            void read.then(() => this.outputReads.delete(read), () => this.outputReads.delete(read));
+            return read;
+        }
         async open() {
             // Seed the first paint via the same random-access path used for every
             // seek. Cheaper than a one-shot iterator just for the seed. Seed at the
@@ -27697,9 +27773,13 @@
         async seekToFrame(frame) {
             if (this.closed)
                 return null;
-            const decoded = await this.provider.getFrame(this.trackInfo.timeline.timeAt(frame.index));
-            if (this.closed || !decoded)
+            const outputGeneration = this.outputGeneration;
+            const decoded = await this.trackOutputRead(this.provider.getFrame(this.trackInfo.timeline.timeAt(frame.index)));
+            if (this.closed || outputGeneration !== this.outputGeneration || !decoded) {
+                if (decoded?.kind === "sample")
+                    decoded.sample.close();
                 return null;
+            }
             this.emitFrame(decoded);
             return this.lastEmittedFrame;
         }
@@ -27727,11 +27807,13 @@
         attachPlay(startS) {
             if (this.closed)
                 return;
-            void this.iterator?.return();
+            if (this.iterator)
+                void this.trackOutputRead(this.iterator.return());
             this.iterator = this.provider.frames(startS);
         }
         detachPlay() {
-            void this.iterator?.return();
+            if (this.iterator)
+                void this.trackOutputRead(this.iterator.return());
             this.iterator = null;
         }
         next() {
@@ -27776,6 +27858,7 @@
         }
         async close() {
             this.closed = true;
+            this.outputReads.clear();
             this.pendingSeekTargetS = null;
             this.currentState = ScrubCursorState.Closed;
             this.listeners.clear();
@@ -27809,11 +27892,14 @@
         async runSeek(t, keyOnly) {
             if (this.closed)
                 return;
+            const outputGeneration = this.outputGeneration;
             this.currentState = ScrubCursorState.Seeking;
-            const frame = await this.provider.getFrame(t);
-            if (this.closed)
-                return;
-            if (frame)
+            const frame = await this.trackOutputRead(this.provider.getFrame(t));
+            if (this.closed || outputGeneration !== this.outputGeneration) {
+                if (frame?.kind === "sample")
+                    frame.sample.close();
+            }
+            else if (frame)
                 this.emitFrame(frame, keyOnly);
             if (!this.closed)
                 this.currentState = ScrubCursorState.Idle;
@@ -27826,7 +27912,7 @@
             // otherwise we would race the iterator state.
             if (this.seekDraining)
                 return;
-            const next = (await iterator.next()).value ?? null;
+            const next = (await this.trackOutputRead(iterator.next())).value ?? null;
             if (this.closed || iterator !== this.iterator || !next) {
                 if (next?.kind === "sample")
                     next.sample.close();
@@ -27910,6 +27996,7 @@
         FrameTier["Preview"] = "preview";
     })(FrameTier || (FrameTier = {}));
     class FrameCache {
+        options;
         exact;
         preview;
         exactHits = 0;
@@ -27918,6 +28005,7 @@
         bucketMs;
         exactBudgetBytes;
         constructor(options) {
+            this.options = options;
             const exactWidth = Math.max(1, Math.round(options.exactWidth));
             const exactHeight = Math.max(1, Math.round(options.exactHeight));
             const aspect = exactWidth / exactHeight;
@@ -27937,6 +28025,13 @@
             this.exact = new TierStore(exactCapacity, exactWidth, exactHeight, FRAME_IDENTITY_KEY_GRID_MS);
             this.preview = new TierStore(Math.max(0, Math.floor(options.previewCapacity)), previewWidth, previewHeight, PREVIEW_KEY_GRID_MS);
         }
+        resized(width, height) {
+            return new FrameCache({
+                ...this.options,
+                exactWidth: width,
+                exactHeight: height,
+            });
+        }
         /**
          * Store a crisp full-resolution frame for the exact (scrub) tier under
          * `frame`, the timeline's name for it. `timestampMs` is the decoded
@@ -28663,6 +28758,9 @@
         cache;
         keyframeIndex;
         trackInfo;
+        outputGeneration = 0;
+        resizingOutput = false;
+        outputReads = new Set();
         exactTolMs;
         previewTolMs;
         now;
@@ -28777,6 +28875,47 @@
                 this.pendingSeekTargetS === null &&
                 !this.seekDraining);
         }
+        async resizeOutput({ width, height }) {
+            if (!this.provider.resizeOutput) {
+                throw new WebVideoEngineError(WebVideoEngineErrorCode.PresentationMismatch, "this decode source cannot resize frame output in place");
+            }
+            if (this.closed ||
+                (width === this.trackInfo.decodeWidth &&
+                    height === this.trackInfo.decodeHeight))
+                return false;
+            this.outputGeneration++;
+            this.resizingOutput = true;
+            this.pendingSeekTargetS = null;
+            const returning = this.iterator?.return();
+            this.iterator = null;
+            this.nextPending = 0;
+            this.abandonPrefetch();
+            this.lastEmittedFrame = null;
+            try {
+                await this.prefetchTask?.catch(() => undefined);
+                await Promise.allSettled([
+                    ...this.outputReads,
+                    ...(returning ? [returning] : []),
+                ]);
+                if (this.closed)
+                    return false;
+                await this.provider.resizeOutput({ width, height });
+                if (this.closed)
+                    return false;
+                this.trackInfo = {
+                    ...this.trackInfo,
+                    decodeWidth: width,
+                    decodeHeight: height,
+                };
+                const oldCache = this.cache;
+                this.cache = oldCache.resized(width, height);
+                oldCache.clear();
+                return true;
+            }
+            finally {
+                this.resizingOutput = false;
+            }
+        }
         async open() {
             // Seed at the track's real first timestamp, not a hardcoded 0: a trimmed
             // or offset clip's first frame is not at the origin, so getFrame(0) would
@@ -28996,7 +29135,9 @@
             this.enterMode(AccessMode.Playing);
             // Signal any running sweep to bail; the first pull awaits its teardown.
             this.abandonPrefetch();
-            void this.iterator?.return();
+            if (this.iterator) {
+                void this.trackOutputRead(this.iterator.return());
+            }
             this.iterator = this.provider.frames(startS);
             // Reset the in-flight latch for the new session. An old-iterator pull may
             // still be settling; its finally is iterator-identity-aware (see next()),
@@ -29008,7 +29149,9 @@
             this.nextInFlight = Promise.resolve();
         }
         detachPlay() {
-            void this.iterator?.return();
+            if (this.iterator) {
+                void this.trackOutputRead(this.iterator.return());
+            }
             this.iterator = null;
             // A pull in flight at detach never decrements, since its finally only
             // fires for the iterator it was issued against. Left stranded, the count
@@ -29056,8 +29199,9 @@
                 return null;
             this.enterMode(AccessMode.Stepping);
             this.abandonPrefetch();
+            const outputGeneration = this.outputGeneration;
             const decoded = await this.withDecodeWatchdog(this.provider.getFrame(this.trackInfo.timeline.timeAt(frame.index)));
-            if (this.closed || !decoded) {
+            if (this.closed || outputGeneration !== this.outputGeneration || !decoded) {
                 if (decoded?.kind === "sample")
                     decoded.sample.close();
                 return null;
@@ -29090,6 +29234,7 @@
         }
         async close() {
             this.closed = true;
+            this.outputReads.clear();
             this.abandonPrefetch();
             this.pendingSeekTargetS = null;
             this.currentState = ScrubCursorState.Closed;
@@ -29168,6 +29313,7 @@
             }
         }
         async runExactSeek(t) {
+            const outputGeneration = this.outputGeneration;
             this.exactSeeks += 1;
             const ms = t * 1000;
             const cached = this.cache.getForFrame(this.frameAtTime(t), ms, this.previewTolMs);
@@ -29188,7 +29334,7 @@
             const previewPaintedAt = painted && cached.tier === FrameTier.Preview ? this.now() : null;
             const startedAt = this.now();
             const frame = await this.withDecodeWatchdog(this.provider.getFrame(t));
-            if (this.closed || !frame) {
+            if (this.closed || outputGeneration !== this.outputGeneration || !frame) {
                 if (frame?.kind === "sample")
                     frame.sample.close();
                 return;
@@ -29255,13 +29401,14 @@
                 : null, targetMs);
         }
         async runKeySeek(t) {
+            const outputGeneration = this.outputGeneration;
             this.keySeeks += 1;
             // getFrame already anchors on the enclosing keyframe, so re-anchoring the
             // request collapses every target within a GOP onto that one frame. A
             // source carrying a single keyframe answers its whole timeline with the
             // first frame.
             const frame = await this.withDecodeWatchdog(this.provider.getFrame(t));
-            if (this.closed || !frame) {
+            if (this.closed || outputGeneration !== this.outputGeneration || !frame) {
                 if (frame?.kind === "sample")
                     frame.sample.close();
                 return;
@@ -29319,7 +29466,12 @@
          * decoder having a bad moment from one that will never answer again.
          */
         withDecodeWatchdog(decode) {
-            return this.watchdogged(decode, true);
+            return this.watchdogged(this.trackOutputRead(decode), true);
+        }
+        trackOutputRead(read) {
+            this.outputReads.add(read);
+            void read.then(() => this.outputReads.delete(read), () => this.outputReads.delete(read));
+            return read;
         }
         /**
          * The same watchdog over a container metadata read. Deliberately unbooked:
@@ -29447,6 +29599,11 @@
                         return;
                     }
                     this.provider = openFrameProvider(handle);
+                    this.outputReads.clear();
+                    await this.provider.resizeOutput?.({
+                        width: this.trackInfo.decodeWidth,
+                        height: this.trackInfo.decodeHeight,
+                    });
                     // Disposing the old input invalidated the old probe, so the index
                     // has to be rebuilt against the new one. It starts empty, and
                     // nothing else re-walks it: the source's keyframes are exactly
@@ -29527,6 +29684,8 @@
          * is never used twice at once, then runs under a captured generation token.
          */
         schedulePrefetch(aroundS) {
+            if (this.resizingOutput)
+                return;
             if (this.mode === AccessMode.Playing)
                 return;
             this.abandonPrefetch();
@@ -29639,7 +29798,7 @@
                 }
             }
             finally {
-                void iter.return();
+                void this.trackOutputRead(iter.return());
             }
         }
         /**
@@ -31373,6 +31532,17 @@ ${VERTEX_STAGE}
          * crosses the duration.
          */
         beginPlay(startS) {
+            const { timeline } = this.deps.cursor.track;
+            if (this.playSessionLive &&
+                this.deps.clock.playing &&
+                this.lastDeliveryS !== null &&
+                !this.paintedSincePlay &&
+                timeline.indexAtOrBefore(this.playAnchorS) ===
+                    timeline.indexAtOrBefore(startS)) {
+                return;
+            }
+            if (this.lastDeliveryS !== null)
+                this.endPlay();
             this.endedFired = false;
             this.playAnchorS = startS;
             // The realtime needles are per-session rates, not lifetime totals: a
@@ -31401,6 +31571,7 @@ ${VERTEX_STAGE}
             this.lastPresentTickS = null;
             this.resetCadenceTracking();
             this.clearPlayQueue();
+            this.clearStash();
             this.deps.cursor.attachPlay(startS);
             this.deps.cursor.next();
         }
@@ -31420,6 +31591,17 @@ ${VERTEX_STAGE}
             this.resetCadenceTracking();
             this.clearPlayQueue();
         }
+        holdOutput() {
+            this.stop();
+            this.clearStash();
+            this.clearPlayQueue();
+            this.deps.cursor.detachPlay();
+            this.lastDeliveryS = null;
+        }
+        releaseOutput() {
+            if (!this.disposed && this.sink)
+                this.start();
+        }
         /**
          * 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
@@ -31427,10 +31609,8 @@ ${VERTEX_STAGE}
          * 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) {
             if (!this.sink)
@@ -31440,7 +31620,12 @@ ${VERTEX_STAGE}
                 return false;
             const hitMs = Math.round(hit.timestampS * 1000);
             if (this.lastPaintedMs !== null) {
-                if (Math.abs(hitMs - this.lastPaintedMs) < this.deps.cacheSkipNearMs)
+                const { timeline } = this.deps.cursor.track;
+                const exactTarget = hit.quality === "exact" &&
+                    timeline.indexOfDecoded(hit.timestampS) ===
+                        timeline.indexAtOrBefore(timestampMs / 1000);
+                if (!exactTarget &&
+                    Math.abs(hitMs - this.lastPaintedMs) < this.deps.cacheSkipNearMs)
                     return false;
                 // And it has to be an improvement on what is showing, measured from
                 // where the user is pointing. The check above measures only distance
@@ -31456,10 +31641,30 @@ ${VERTEX_STAGE}
                     return false;
                 }
             }
+            return this.paintCached(hit);
+        }
+        /** 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) {
+            if (!this.sink)
+                return false;
+            const hit = this.deps.cursor.peekCached(timestampMs);
+            const { timeline } = this.deps.cursor.track;
+            if (!hit ||
+                hit.quality !== "exact" ||
+                timeline.indexOfDecoded(hit.timestampS) !==
+                    timeline.indexAtOrBefore(timestampMs / 1000)) {
+                return false;
+            }
+            return this.paintCached(hit);
+        }
+        paintCached(hit) {
+            if (!this.sink)
+                return false;
             // A cache hit is always a canvas blit, never a live sample, so there is
             // no close obligation here.
             const presented = this.sink.present(hit);
-            this.lastPaintedMs = hitMs;
+            this.lastPaintedMs = Math.round(hit.timestampS * 1000);
             this.lastPaintedQuality = hit.quality;
             // This is a full frame on the display canvas and the user sees the
             // picture change, so it is a paint. Reporting only decoded frames left
@@ -32340,6 +32545,45 @@ ${VERTEX_STAGE}
         return residency;
     }
 
+    function createPausableDeadline(timeoutMs, onExpire) {
+        let cancelled = false;
+        let remainingMs = timeoutMs;
+        let startedAtMs = performance.now();
+        let timer = null;
+        const expire = () => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            timer = null;
+            onExpire();
+        };
+        const arm = () => {
+            if (cancelled || timer !== null)
+                return;
+            startedAtMs = performance.now();
+            timer = setTimeout(expire, remainingMs);
+        };
+        arm();
+        return {
+            cancel() {
+                if (cancelled)
+                    return;
+                cancelled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                timer = null;
+            },
+            pause() {
+                if (cancelled || timer === null)
+                    return;
+                remainingMs = Math.max(0, remainingMs - (performance.now() - startedAtMs));
+                clearTimeout(timer);
+                timer = null;
+            },
+            resume: arm,
+        };
+    }
+
     function serializeEngineError(error) {
         return { code: error.code, message: error.message };
     }
@@ -32359,6 +32603,8 @@ ${VERTEX_STAGE}
      * the core never emits a competing time that would yank a settled playhead.
      */
     class EngineCore {
+        decodeStrategy = nativeResolution();
+        displayResize = null;
         emit;
         emitDiagnostics;
         emitPresentedFrame;
@@ -32417,6 +32663,8 @@ ${VERTEX_STAGE}
         lastHostFrame = null;
         /** Rejects an older refresh that completes after a newer one in one epoch. */
         lastHostPaintSeq = 0;
+        /** Main-thread visibility pauses only the wait for host presentation. */
+        presentationVisible = true;
         /** Mirrors WebVideoEngine's interactive-seek latch: true when a drag paused a
          *  playing engine, so endInteractiveSeek knows to resume. */
         resumeAfterInteractiveSeek = false;
@@ -32457,6 +32705,7 @@ ${VERTEX_STAGE}
                 this.abandonAwaitedSeek();
         }
         async load(config) {
+            this.decodeStrategy = config.decodeStrategy ?? nativeResolution();
             this.beginPresentationGeneration();
             this.presentation = config.presentation ?? "canvas";
             this.displayBox =
@@ -32541,11 +32790,163 @@ ${VERTEX_STAGE}
                 this.residency?.startWarming();
             return this.metadata;
         }
+        setDisplay(display) {
+            const cursor = this.cursor;
+            if (this.presentation !== "frames" ||
+                this.decodeStrategy.kind !== "displayBox" ||
+                !cursor?.resizeOutput) {
+                return Promise.reject(new WebVideoEngineError(WebVideoEngineErrorCode.PresentationMismatch, "display resizing requires frames presentation with a displayBox strategy"));
+            }
+            const resolved = resolveDecodeDimensions(displayBoxResolution(display), {
+                nativeWidth: cursor.track.width,
+                nativeHeight: cursor.track.height,
+                displayWidth: null,
+                devicePixelRatio: display.devicePixelRatio,
+            });
+            if (!this.displayResize &&
+                resolved.width === cursor.track.decodeWidth &&
+                resolved.height === cursor.track.decodeHeight) {
+                this.displayBox = {
+                    cssWidth: display.boxWidth,
+                    cssHeight: display.boxHeight,
+                    devicePixelRatio: display.devicePixelRatio,
+                };
+                return Promise.resolve(false);
+            }
+            let state = this.displayResize;
+            if (!state) {
+                let cancel = () => { };
+                const aborted = new Promise((resolve) => {
+                    cancel = resolve;
+                });
+                state = {
+                    tail: Promise.resolve(false),
+                    request: 0,
+                    navigation: 0,
+                    pendingNavigation: false,
+                    held: false,
+                    cancelled: false,
+                    cancel,
+                    aborted,
+                };
+                this.displayResize = state;
+            }
+            const active = state;
+            const request = ++active.request;
+            const previous = active.tail;
+            if (active.held)
+                this.abandonAwaitedSeek();
+            const run = (async () => {
+                await previous.catch((error) => {
+                    if (active.cancelled || !isResizeSuperseded(error))
+                        throw error;
+                });
+                if (active.cancelled)
+                    throw displayResizeAborted();
+                if (request !== active.request || active.pendingNavigation)
+                    throw displayResizeSuperseded();
+                const dimensions = resolved;
+                this.displayBox = {
+                    cssWidth: display.boxWidth,
+                    cssHeight: display.boxHeight,
+                    devicePixelRatio: display.devicePixelRatio,
+                };
+                if (dimensions.width === cursor.track.decodeWidth &&
+                    dimensions.height === cursor.track.decodeHeight)
+                    return false;
+                const target = this.lastHostFrame ??
+                    this.timeline().landingAt(this.timeline().indexAtOrBefore(this.clock.now()));
+                this.clock.pause();
+                this.clock.seek(target.mediaTimeS);
+                this.controller?.holdOutput();
+                active.held = true;
+                this.abandonAwaitedSeek();
+                this.beginPresentationGeneration();
+                const untilDisposed = (work) => Promise.race([
+                    work,
+                    active.aborted.then(() => {
+                        throw displayResizeAborted();
+                    }),
+                ]);
+                await untilDisposed(cursor.resizeOutput(dimensions));
+                if (request !== active.request || active.pendingNavigation)
+                    throw displayResizeSuperseded();
+                const wait = this.awaitSeekLanding(target.frame, false, true);
+                void wait.presented.catch(() => undefined);
+                const decoded = await untilDisposed(cursor.seekToFrame(target.frame));
+                if (request !== active.request || active.pendingNavigation) {
+                    this.controller?.holdOutput();
+                    this.abandonAwaitedSeek();
+                    throw displayResizeSuperseded();
+                }
+                if (!decoded)
+                    throw new WebVideoEngineError(WebVideoEngineErrorCode.DecoderStalled, "resized frame could not be decoded");
+                this.controller?.releaseOutput();
+                await untilDisposed(wait.presented);
+                if (request !== active.request || active.pendingNavigation)
+                    throw displayResizeSuperseded();
+                return true;
+            })();
+            const settled = run
+                .catch((error) => {
+                if (active.held) {
+                    this.abandonAwaitedSeek();
+                    this.controller?.holdOutput();
+                }
+                if (!isResizeSuperseded(error)) {
+                    this.playing = false;
+                    if (!active.cancelled)
+                        this.emitStatus(PlaybackStatus.Paused);
+                }
+                throw error;
+            })
+                .finally(() => {
+                if (active.tail !== settled)
+                    return;
+                this.displayResize = null;
+                this.controller?.releaseOutput();
+                if ((active.held || !this.clock.playing) &&
+                    !active.cancelled &&
+                    !active.pendingNavigation &&
+                    this.playing) {
+                    this.clock.play();
+                    this.controller?.beginPlay(this.clock.now());
+                    this.emitStatus(PlaybackStatus.Playing);
+                }
+            });
+            active.tail = settled;
+            return settled;
+        }
+        async afterDisplayResize(run, superseded) {
+            const state = this.displayResize;
+            const navigation = ++state.navigation;
+            state.pendingNavigation = true;
+            state.held = true;
+            this.controller?.holdOutput();
+            this.abandonAwaitedSeek();
+            this.beginPresentationGeneration();
+            while (this.displayResize === state)
+                await state.tail.catch((error) => {
+                    if (state.cancelled || !isResizeSuperseded(error))
+                        throw error;
+                });
+            if (state.cancelled)
+                throw displayResizeAborted();
+            if (navigation !== state.navigation)
+                return superseded;
+            if (this.playing)
+                this.clock.play();
+            return run();
+        }
         play() {
             if (!this.cursor || !this.controller)
                 return;
             if (this.decodeFailure)
                 return this.republishFailure();
+            if (this.displayResize) {
+                this.playing = true;
+                return;
+            }
             // Resume-from-end: a play after the clock crossed duration would tick
             // straight to Ended. Snap back to 0 first.
             const durS = this.durationMs / 1000;
@@ -32594,7 +32995,7 @@ ${VERTEX_STAGE}
                 }
             }
             this.controller?.endPlay();
-            if (wasPlaying)
+            if (wasPlaying && !this.displayResize)
                 this.abandonAwaitedSeek();
             if (this.decodeFailure)
                 return this.republishFailure();
@@ -32635,6 +33036,17 @@ ${VERTEX_STAGE}
          *  thread snapped the gesture and wrote it. Paints a cache preview, then
          *  walks the cursor. */
         scrub(frameIndex, intent = "gesture") {
+            if (this.displayResize) {
+                void this.afterDisplayResize(() => this.scrub(frameIndex, intent), undefined).catch((error) => {
+                    if (error instanceof WebVideoEngineError &&
+                        error.code === WebVideoEngineErrorCode.Aborted)
+                        return;
+                    this.handleTerminalFailure(error instanceof WebVideoEngineError
+                        ? error
+                        : new WebVideoEngineError(WebVideoEngineErrorCode.BackendCrashed, "display resize failed", error));
+                });
+                return;
+            }
             if (!this.cursor)
                 return;
             const target = this.timeline().landingAt(frameIndex);
@@ -32667,7 +33079,6 @@ ${VERTEX_STAGE}
             // crisp frame up, and then the wait is over before the walk restarts.
             if (!this.awaitedSeek)
                 this.closePlaySeekWait();
-            this.controller?.endPlay();
             this.controller?.beginPlay(tSec);
         }
         /** Closes the wait of a seek served by re-anchoring, at the crisp paint that
@@ -32689,6 +33100,8 @@ ${VERTEX_STAGE}
                 this.playSeekMaxMs = waitMs;
         }
         async commit(frameIndex) {
+            if (this.displayResize)
+                return this.afterDisplayResize(() => this.commit(frameIndex), null);
             if (!this.cursor)
                 return null;
             if (this.decodeFailure)
@@ -32698,7 +33111,9 @@ ${VERTEX_STAGE}
             this.lastStepLanded = null;
             const wait = this.awaitSeekLanding(target.frame, false, true);
             this.clock.seek(tSec);
-            this.controller?.tryPaintFromCache(tSec * 1000);
+            if (!this.controller?.presentExactFromCache(tSec * 1000)) {
+                this.controller?.tryPaintFromCache(tSec * 1000);
+            }
             // While playing, moving the playhead means re-anchoring the playback
             // walk, exactly as scrub does. Seeking the cursor instead leaves the walk
             // where it was, so playback carries on from the old position and the seek
@@ -32746,6 +33161,8 @@ ${VERTEX_STAGE}
             return landed;
         }
         async seekToKey(timeMs) {
+            if (this.displayResize)
+                return this.afterDisplayResize(() => this.seekToKey(timeMs), null);
             if (!this.cursor)
                 return null;
             if (this.decodeFailure)
@@ -32809,6 +33226,14 @@ ${VERTEX_STAGE}
          * other.
          */
         async step(direction) {
+            if (this.displayResize) {
+                return this.afterDisplayResize(async () => {
+                    const landed = await this.step(direction);
+                    if (this.playing)
+                        this.controller?.beginPlay(this.clock.now());
+                    return landed;
+                }, null);
+            }
             if (!this.cursor || !this.controller)
                 return null;
             const timeline = this.timeline();
@@ -32887,6 +33312,10 @@ ${VERTEX_STAGE}
             this.play();
         }
         async dispose() {
+            if (this.displayResize) {
+                this.displayResize.cancelled = true;
+                this.displayResize.cancel();
+            }
             this.playing = false;
             this.diagnosticsStop();
             // A capture still running is evidence someone asked for; keep it, marked
@@ -32957,7 +33386,7 @@ ${VERTEX_STAGE}
                 return { generation, presented: Promise.resolve(null) };
             }
             const presented = new Promise((resolve, reject) => {
-                const presentationTimer = setTimeout(() => {
+                const presentationDeadline = createPausableDeadline(HANG_RECOVERY.PRESENTATION_LATCH_TIMEOUT_MS, () => {
                     const awaited = this.awaitedSeek;
                     if (!awaited ||
                         awaited.generation !== generation ||
@@ -32970,20 +33399,33 @@ ${VERTEX_STAGE}
                         awaited.reject(error);
                     else
                         awaited.resolve(null);
-                }, HANG_RECOVERY.PRESENTATION_LATCH_TIMEOUT_MS);
+                });
                 const awaited = {
                     generation,
                     keyOnly,
-                    presentationTimer,
+                    presentationDeadline,
                     reject: (error) => reject(error),
                     rejectOnFailure,
                     resolve,
                     target,
                 };
                 this.awaitedSeek = awaited;
+                if (!this.presentationVisible)
+                    presentationDeadline.pause();
             });
             return { generation, presented };
         }
+        /** Main-thread document visibility; decoding/watchdogs remain active. */
+        setPresentationVisibility(visible) {
+            this.presentationVisible = visible;
+            const awaited = this.awaitedSeek;
+            if (!awaited)
+                return;
+            if (visible)
+                awaited.presentationDeadline.resume();
+            else
+                awaited.presentationDeadline.pause();
+        }
         isCurrentSeek(generation) {
             return generation === this.seekGeneration;
         }
@@ -32997,7 +33439,7 @@ ${VERTEX_STAGE}
             if (!awaited)
                 return;
             this.awaitedSeek = null;
-            clearTimeout(awaited.presentationTimer);
+            awaited.presentationDeadline.cancel();
             awaited.resolve(null);
         }
         /** Ends an impossible landing. Awaitable movement rejects with the engine's
@@ -33007,7 +33449,7 @@ ${VERTEX_STAGE}
             if (!awaited)
                 return;
             this.awaitedSeek = null;
-            clearTimeout(awaited.presentationTimer);
+            awaited.presentationDeadline.cancel();
             if (awaited.rejectOnFailure)
                 awaited.reject(error);
             else
@@ -33104,7 +33546,7 @@ ${VERTEX_STAGE}
             if (answeredSeek && this.awaitedSeek === answeredSeek) {
                 this.seekLanded = frameId;
                 this.awaitedSeek = null;
-                clearTimeout(answeredSeek.presentationTimer);
+                answeredSeek.presentationDeadline.cancel();
                 this.closePlaySeekWait();
                 // Paused paints normally never move the playhead, but the landing
                 // of an awaited seek is the one paint that says where the request
@@ -33486,6 +33928,17 @@ ${VERTEX_STAGE}
         const wanted = Math.round((windowMs / 1000) * DIAGNOSTICS.BROADCAST_HZ);
         return Math.min(DIAGNOSTICS.TRACE_SNAPSHOT_CAP, Math.max(1, wanted));
     }
+    function displayResizeAborted() {
+        return new WebVideoEngineError(WebVideoEngineErrorCode.Aborted, "display resize aborted by disposal");
+    }
+    function displayResizeSuperseded() {
+        return new WebVideoEngineError(WebVideoEngineErrorCode.Aborted, "display resize superseded");
+    }
+    function isResizeSuperseded(error) {
+        return (error instanceof WebVideoEngineError &&
+            error.code === WebVideoEngineErrorCode.Aborted &&
+            error.message === "display resize superseded");
+    }
 
     function toSerializedError(error) {
         if (error instanceof WebVideoEngineError)
@@ -33511,6 +33964,9 @@ ${VERTEX_STAGE}
             case "unbindCanvas":
                 engine.setCanvas(null);
                 return;
+            case "setPresentationVisibility":
+                engine.setPresentationVisibility(command.visible);
+                return;
             case "scrub":
                 engine.scrub(command.frameIndex, command.intent);
                 return;
@@ -33552,6 +34008,11 @@ ${VERTEX_STAGE}
                     engine.play();
                     return { type: "ack", requestId: command.requestId };
                 });
+            case "setDisplay":
+                return settle(post, command.requestId, async () => {
+                    const outputChanged = await engine.setDisplay(command.display);
+                    return { type: "ack", requestId: command.requestId, outputChanged };
+                });
             case "commit":
                 return settle(post, command.requestId, async () => {
                     const landing = await engine.commit(command.frameIndex);