akarisub 1.1.2 → 1.1.4

package/dist/ts/akarisub.js

@@ -1,4 +1,6 @@
-import { classifyPerformanceWarnings, parsePreloadTrackSource } from './cue-events';
+import { GPURecovery } from './gpu-recovery';
+import { PreparedPresentation } from './prepared-presentation';
+import { classifyPerformanceWarnings, parsePreloadTrackSource, resolveCueTracking } from './cue-events';
 import { parseStreamingTrackOptions } from './streaming';
 import { normalizeFontFamilySource } from './font-subsets';
 import { computeCanvasSize, getVideoPosition, fixAlpha } from './utils';
@@ -6,7 +8,7 @@ import { canvas2dContextSettings, createSubtitleImageData, defaultVideoColorProf
 import { selectWasmBinary } from './wasm-capabilities';
 import { WebGPURenderer, isWebGPUSupported } from './webgpu-renderer';
 import { WebGL2Renderer, isWebGL2Supported } from './webgl2-renderer';
-import { compensatedMediaTime, compositorScheduleLeadMs, estimateRefreshIntervalMs, isStalePresentation, normalizeFrameTimeline, predictFrameDisplayTimeMs, presentedFrameIndex, presentationLeadSeconds, resolvePresentationMediaTime, selectRenderMediaTime, subtitleTimeForFrame, updateTimingCompensation } from './timing';
+import { compensatedMediaTime, estimateRefreshIntervalMs, isStalePresentation, normalizeFrameTimeline, predictFrameDisplayTimeMs, presentedFrameIndex, presentationLeadSeconds, resolvePresentationMediaTime, selectRenderMediaTime, subtitleTimeForFrame, updateTimingCompensation } from './timing';
 import { isVideoFrameLike, videoFrameCallbackMetadata } from './video-frame';
 import { getDefaultFontUrl, getMtWasmGlueUrl, getMtWasmUrl, getWasmGlueUrl, getWasmUrl } from './wasm';
 import { webYCbCrMap } from './utils';
@@ -45,7 +47,6 @@ const isLikelyWebKit = () => {
 export default class AkariSub extends EventTarget {
     static MAX_PENDING_DEMANDS = 3;
     static MAX_FONT_BYTES = 32 * 1024 * 1024;
-    static WEBGL_RESTORE_TIMEOUT_MS = 3000;
     static _hasAlphaBug = null;
     static _hasBitmapBug = null;
     _loaded;
@@ -53,6 +54,7 @@ export default class AkariSub extends EventTarget {
     _destroyedSignal;
     _resolveDestroyed;
     _pendingWorkerRejectors = new Set();
+    _pendingTrackReadyWaiters = new Map();
     _onDemandRender;
     _offscreenRender;
     _video;
@@ -85,12 +87,17 @@ export default class AkariSub extends EventTarget {
     _demandTimings = new Map();
     _adaptiveTiming;
     _frameTimeline;
-    _preparedFrames = new Map();
-    _stagedCanvases = new Set();
-    _stageFrameIndices = new Map();
-    _stageDisplayTimes = new Map();
-    _committedStage = null;
-    _scheduledPreparedFrame = null;
+    _presentationOwner;
+    get _presentation() {
+        return this._presentationOwner ??= new PreparedPresentation({
+            canvas: () => this._canvas,
+            release: stage => this._releaseGPUStage(stage),
+            committed: frame => this._gpuRecovery.commit(this._snapshotRenderedCanvas(frame.stage, frame.gpuStage === true)),
+            refreshInterval: () => estimateRefreshIntervalMs(this._refreshSamples ?? []),
+            now: () => performance.now(),
+            documentTime: () => Number(document.timeline?.currentTime)
+        });
+    }
     _predictedDisplayTimes = new Map();
     _displayClockOffsets = [];
     _displayGridAnchorMs;
@@ -102,8 +109,10 @@ export default class AkariSub extends EventTarget {
     _lastRefreshRafTime;
     _prepareQueue = [];
     _prepareRequests = new Map();
+    _lastRvfcMediaTime = null;
     _nextPrepareId = 1;
     _prepareForce = true;
+    _prepareFailureEpoch = -1;
     _timingCompensationSeconds = 0;
     _rvfcHandle = null;
     _rvfcGeneration = 0;
@@ -120,14 +129,46 @@ export default class AkariSub extends EventTarget {
     _boundHandleRVFC;
     _gpuRenderer = null;
     _rendererType = 'canvas2d';
-    _gpuRecovering = null;
-    _gpuRecoveryGeneration = 0;
-    _gpuRecoveryTimer = null;
+    _gpuRecoveryOwner;
+    get _gpuRecovery() {
+        return this._gpuRecoveryOwner ??= new GPURecovery({
+            current: () => this._gpuRenderer,
+            use: renderer => { this._gpuRenderer = renderer; },
+            begin: reason => {
+                this._emitPerformanceWarning({ kind: 'renderer-recovery', reason, rendererType: this._rendererType });
+                this._renderEpoch++;
+                this._pendingDemandTimes.length = 0;
+                this._demandTimings.clear();
+                this._clearPreparedFrames(false);
+                this._prepareForce = true;
+                this._showGPURecoveryFrame();
+            },
+            replay: async (renderer) => {
+                this._applyGpuColorManagement();
+                await this._restoreRetainedGPUFrame(renderer);
+            },
+            recovered: reason => {
+                this._activateBaseCanvas(this._currentExactFrameIndex());
+                this._setRendererType(this._rendererType, reason);
+                this._hideGPURecoveryFrame();
+                this._prepareForce = true;
+                this._syncVideoClock();
+            },
+            fallback: (reason, error) => {
+                console.warn(`[AkariSub] GPU recovery failed after ${reason}; falling back to Canvas2D.`, error);
+                this._adoptGPURecoveryCanvas();
+                this._setRendererType('canvas2d', reason);
+                void this.sendMessage('setAsyncRender', { value: false });
+                this._onCanvasFallback?.();
+                this._prepareForce = true;
+                this._syncVideoClock();
+            },
+            discard: snapshot => this._discardGPUSnapshot(snapshot)
+        });
+    }
     _recoveryCanvas = null;
     _recoveryCtx = null;
-    _lastGPUFrame = null;
     _gpuSnapshotPool = [];
-    _nextGPUSnapshotSequence = 1;
     _onCanvasFallback;
     _onCueEnter;
     _onCueExit;
@@ -139,8 +180,7 @@ export default class AkariSub extends EventTarget {
     _lastRenderWidth = 0;
     _lastRenderHeight = 0;
     _gpuBitmapImages = [];
-    /** Seconds added to video time when sampling the track. */
-    timeOffset;
+    _timeOffset;
     /** When true, the worker prints libass and renderer logs. */
     debug;
     /** Extra scale applied to the subtitle canvas before height limits. */
@@ -218,7 +258,7 @@ export default class AkariSub extends EventTarget {
         // ASS composition remains opt-in because it regresses several ordinary and
         // animation-heavy custom-canvas workloads despite helping dense overlays.
         this._offscreenRender = canTransferOffscreen && !canUseGPURenderer && wantsOffscreenRender;
-        this.timeOffset = options.timeOffset || 0;
+        this._timeOffset = options.timeOffset || 0;
         this._video = options.video;
         this._canvas = options.canvas;
         if (this._video && !this._canvas) {
@@ -313,6 +353,7 @@ export default class AkariSub extends EventTarget {
                 blockingFullTrackWarmup: options.blockingFullTrackWarmup ?? false,
                 fullTrackWarmupStep: options.fullTrackWarmupStep ?? 1,
                 adaptiveBlendLayouts: options.adaptiveBlendLayouts ?? false,
+                cueTracking: resolveCueTracking(options.cueTracking),
                 rawAssImageGpu,
                 onDemandRender: this._onDemandRender,
                 initialTime,
@@ -502,125 +543,33 @@ export default class AkariSub extends EventTarget {
             };
             return;
         }
-        renderer.onContextLost = () => this._beginWebGLRecovery(renderer);
+        renderer.onContextLost = () => this._gpuRecovery.waitForRestore(renderer);
         renderer.onContextRestored = (error) => {
             if (error) {
-                this._fallbackFromGPU(renderer, 'context-lost', error);
+                this._gpuRecovery.fail(renderer, error);
             }
             else {
-                void this._finishGPURecovery(renderer, 'context-lost');
+                void this._gpuRecovery.restore(renderer);
             }
         };
     }
     /** @internal */
-    _beginGPURecovery(renderer, reason) {
-        if (this._destroyed || this._gpuRenderer !== renderer || this._gpuRecovering)
-            return false;
-        this._gpuRecovering = renderer;
-        this._gpuRecoveryGeneration++;
-        this._emitPerformanceWarning({ kind: 'renderer-recovery', reason, rendererType: this._rendererType });
-        // GPU-backed prepared canvases cannot survive either kind of loss. Retire
-        // them without touching the retained CPU frame used by the recovery layer.
-        this._renderEpoch++;
-        this._pendingDemandTimes.length = 0;
-        this._demandTimings.clear();
-        this._clearPreparedFrames(false);
-        this._prepareForce = true;
-        this._showGPURecoveryFrame();
-        return true;
-    }
-    /** @internal */
     async _recoverWebGPU(renderer) {
-        if (!this._beginGPURecovery(renderer, 'device-lost'))
-            return;
-        const generation = this._gpuRecoveryGeneration;
-        let replacement = null;
-        try {
-            renderer.destroy();
-            replacement = new WebGPURenderer();
+        await this._gpuRecovery.replace(renderer, () => {
+            const replacement = new WebGPURenderer();
             this._bindGPURecovery(replacement);
-            await replacement.init();
-            if (this._destroyed || generation !== this._gpuRecoveryGeneration || !this._canvas) {
-                replacement.destroy();
+            return replacement;
+        }, async (replacement, isCurrent) => {
+            const gpu = replacement;
+            await gpu.init();
+            if (!isCurrent())
                 return;
-            }
-            await replacement.setCanvas(this._canvas, Math.max(1, this._canvas.width || this._lastRenderWidth || 1), Math.max(1, this._canvas.height || this._lastRenderHeight || 1));
-            if (!replacement.initialized)
+            if (!this._canvas)
+                throw new Error('Subtitle canvas is unavailable during GPU recovery');
+            await gpu.setCanvas(this._canvas, Math.max(1, this._canvas.width || this._lastRenderWidth || 1), Math.max(1, this._canvas.height || this._lastRenderHeight || 1));
+            if (!gpu.initialized)
                 throw new Error('Replacement WebGPU device was lost during initialization');
-            if (this._destroyed || generation !== this._gpuRecoveryGeneration) {
-                replacement.destroy();
-                return;
-            }
-            this._gpuRenderer = replacement;
-            await this._finishGPURecovery(replacement, 'device-lost');
-        }
-        catch (error) {
-            if (replacement && this._gpuRenderer !== replacement)
-                replacement.destroy();
-            this._fallbackFromGPU(renderer, 'device-lost', error);
-        }
-    }
-    /** @internal */
-    _beginWebGLRecovery(renderer) {
-        if (!this._beginGPURecovery(renderer, 'context-lost'))
-            return;
-        const generation = this._gpuRecoveryGeneration;
-        this._gpuRecoveryTimer = setTimeout(() => {
-            if (generation === this._gpuRecoveryGeneration) {
-                this._fallbackFromGPU(renderer, 'context-lost', new Error('Timed out waiting for WebGL2 context restoration'));
-            }
-        }, AkariSub.WEBGL_RESTORE_TIMEOUT_MS);
-    }
-    /** @internal */
-    async _finishGPURecovery(renderer, reason) {
-        if (this._destroyed || this._gpuRenderer !== renderer || this._gpuRecovering == null)
-            return;
-        try {
-            this._clearGPURecoveryTimer();
-            this._applyGpuColorManagement();
-            await this._restoreRetainedGPUFrame(renderer);
-            if (this._destroyed || this._gpuRenderer !== renderer)
-                return;
-            this._gpuRecovering = null;
-            this._setRendererType(this._rendererType, reason);
-            this._hideGPURecoveryFrame();
-            this._prepareForce = true;
-            this._syncVideoClock();
-        }
-        catch (error) {
-            this._fallbackFromGPU(renderer, reason, error);
-        }
-    }
-    /** @internal */
-    _fallbackFromGPU(renderer, reason, error) {
-        if (this._destroyed || this._gpuRecovering == null)
-            return;
-        if (this._gpuRenderer !== renderer && this._gpuRecovering !== renderer)
-            return;
-        console.warn(`[AkariSub] GPU recovery failed after ${reason}; falling back to Canvas2D.`, error);
-        this._clearGPURecoveryTimer();
-        try {
-            renderer.destroy();
-        }
-        catch {
-            // The failed device/context may already reject resource cleanup.
-        }
-        this._gpuRenderer = null;
-        this._gpuRecovering = null;
-        this._gpuRecoveryGeneration++;
-        this._adoptGPURecoveryCanvas();
-        this._setRendererType('canvas2d', reason);
-        void this.sendMessage('setAsyncRender', { value: false });
-        this._onCanvasFallback?.();
-        this._prepareForce = true;
-        this._syncVideoClock();
-    }
-    /** @internal */
-    _clearGPURecoveryTimer() {
-        if (this._gpuRecoveryTimer == null)
-            return;
-        clearTimeout(this._gpuRecoveryTimer);
-        this._gpuRecoveryTimer = null;
+        });
     }
     /** Active compositor: WebGPU, WebGL2, or Canvas2D. */
     get rendererType() {
@@ -666,7 +615,7 @@ export default class AkariSub extends EventTarget {
     _snapshotRenderImages(images, width, height) {
         if (!this._gpuSnapshotPool)
             return null;
-        const sequence = this._nextGPUSnapshotSequence++;
+        const sequence = this._gpuRecovery.sequence();
         const canRetainRaw = images.every((image) => image.image instanceof ArrayBuffer ||
             image.image instanceof Uint8Array ||
             image.image instanceof Uint8ClampedArray);
@@ -733,7 +682,7 @@ export default class AkariSub extends EventTarget {
             context.filter = 'none';
             context.clearRect(0, 0, canvas.width, canvas.height);
             context.drawImage(source, 0, 0);
-            return { canvas, sequence: this._nextGPUSnapshotSequence++, colorManaged };
+            return { canvas, sequence: this._gpuRecovery.sequence(), colorManaged };
         }
         catch {
             this._gpuSnapshotPool.push(canvas);
@@ -742,54 +691,19 @@ export default class AkariSub extends EventTarget {
     }
     /** @internal */
     _discardGPUSnapshot(snapshot) {
-        if (snapshot && 'canvas' in snapshot)
+        if (!this._destroyed && snapshot && 'canvas' in snapshot)
             this._gpuSnapshotPool.push(snapshot.canvas);
     }
     /** @internal */
-    _commitGPUSnapshot(snapshot) {
-        if (!snapshot)
-            return;
-        if (this._destroyed || (this._lastGPUFrame && snapshot.sequence < this._lastGPUFrame.sequence)) {
-            this._discardGPUSnapshot(snapshot);
-            return;
-        }
-        const previous = this._lastGPUFrame;
-        this._lastGPUFrame = snapshot;
-        if (previous && 'canvas' in previous)
-            this._gpuSnapshotPool.push(previous.canvas);
-    }
-    /** @internal */
     _materializeGPUSnapshot(snapshot) {
         if (!snapshot || 'canvas' in snapshot)
             return snapshot;
         const materialized = this._rasterizeGPUFrame(snapshot.images, snapshot.width, snapshot.height, snapshot.sequence);
-        if (materialized && this._lastGPUFrame === snapshot)
-            this._lastGPUFrame = materialized;
+        if (materialized)
+            this._gpuRecovery.materialize(snapshot, materialized);
         return materialized;
     }
     /** @internal */
-    _retainGPUFrameAfter(completion, snapshot) {
-        if (!snapshot)
-            return completion;
-        if (typeof completion === 'boolean') {
-            if (completion)
-                this._commitGPUSnapshot(snapshot);
-            else
-                this._discardGPUSnapshot(snapshot);
-            return completion;
-        }
-        return completion.then((painted) => {
-            if (painted)
-                this._commitGPUSnapshot(snapshot);
-            else
-                this._discardGPUSnapshot(snapshot);
-            return painted;
-        }, (error) => {
-            this._discardGPUSnapshot(snapshot);
-            throw error;
-        });
-    }
-    /** @internal */
     _currentCanvasFilter() {
         const target = this._videoColorProfile.matrix ?? this._videoColorSpace;
         if (!this._lastSubtitleColorSpace || !target)
@@ -797,10 +711,18 @@ export default class AkariSub extends EventTarget {
         return getColorSpaceFilterUrl(this._lastSubtitleColorSpace, target) ?? 'none';
     }
     /** @internal */
+    _requiresCanvasColorConversion() {
+        const target = this._videoColorProfile?.matrix ?? this._videoColorSpace;
+        return (!this._gpuRenderer &&
+            !!this._lastSubtitleColorSpace &&
+            !!target &&
+            this._lastSubtitleColorSpace !== target);
+    }
+    /** @internal */
     _showGPURecoveryFrame() {
         if (!this._canvasParent || !this._canvas)
             return;
-        const snapshot = this._materializeGPUSnapshot(this._lastGPUFrame);
+        const snapshot = this._materializeGPUSnapshot(this._gpuRecovery.snapshot);
         const width = snapshot?.canvas.width || this._canvas.width || this._lastRenderWidth || 1;
         const height = snapshot?.canvas.height || this._canvas.height || this._lastRenderHeight || 1;
         const canvas = this._recoveryCanvas ?? document.createElement('canvas');
@@ -854,7 +776,7 @@ export default class AkariSub extends EventTarget {
     }
     /** @internal */
     async _restoreRetainedGPUFrame(renderer) {
-        const snapshot = this._lastGPUFrame;
+        const snapshot = this._gpuRecovery.snapshot;
         let painted;
         if (!snapshot) {
             painted = renderer.clear();
@@ -885,7 +807,6 @@ export default class AkariSub extends EventTarget {
             throw new Error('The recovered GPU renderer rejected the retained subtitle frame');
         if (renderer instanceof WebGPURenderer)
             await renderer.submittedWorkDone();
-        this._activateBaseCanvas(this._currentExactFrameIndex());
     }
     /** @internal */
     _shouldUseHdr() {
@@ -1024,10 +945,18 @@ export default class AkariSub extends EventTarget {
             this._canvas.style.width = videoSize.width + 'px';
             this._canvas.style.height = videoSize.height + 'px';
         }
+        else if ((!width || !height) && this._videoFrameClock) {
+            const renderSize = computeCanvasSize(this._videoFrameClock.width, this._videoFrameClock.height, this.prescaleFactor, this.prescaleHeightLimit, this.maxRenderHeight);
+            width = renderSize.width;
+            height = renderSize.height;
+        }
         this._canvas.style.top = top + 'px';
         this._canvas.style.left = left + 'px';
-        for (const stage of this._stagedCanvases)
-            this._syncStagedCanvasLayout(stage);
+        this._presentation.layout(stage => this._syncStagedCanvasLayout(stage));
+        // Explicit resize calls can also supply fractional CSS/DPR dimensions.
+        // Keep canvas storage, GPU uploads and worker snapshots on the same size.
+        width = Math.max(0, Math.floor(width));
+        height = Math.max(0, Math.floor(height));
         if (width > 0 && height > 0 && (this._canvasctrl.width !== width || this._canvasctrl.height !== height)) {
             this._bumpRenderEpoch();
             this._canvasctrl.width = width;
@@ -1063,6 +992,7 @@ export default class AkariSub extends EventTarget {
             this._videoFrameClock = null;
             this._video = video;
             this._playstate = video.paused || video.ended;
+            this._lastRvfcMediaTime = null;
             if (this._onDemandRender) {
                 if (!this._destroyed && this._video === video) {
                     this._scheduleRVFC(video);
@@ -1153,6 +1083,7 @@ export default class AkariSub extends EventTarget {
     }
     /** Fetch and load an ASS/SSA track from `url`. */
     setTrackByUrl(url) {
+        this._supersedePendingTrackActivation();
         this._bumpRenderEpoch();
         this.sendMessage('setTrackByUrl', { url });
         this._reAttachOffscreen();
@@ -1161,6 +1092,7 @@ export default class AkariSub extends EventTarget {
     }
     /** Replace the current track with ASS/SSA text or bytes. */
     setTrack(content) {
+        this._supersedePendingTrackActivation();
         this._bumpRenderEpoch();
         this.sendMessage('setTrack', { content }, AkariSub._getSubtitleTransfers(content));
         this._reAttachOffscreen();
@@ -1173,6 +1105,7 @@ export default class AkariSub extends EventTarget {
      * materialized in the main thread.
      */
     setEncryptedTrack(content) {
+        this._supersedePendingTrackActivation();
         this._bumpRenderEpoch();
         this.sendMessage('setEncryptedTrack', { content }, AkariSub._getSubtitleTransfers(undefined, content));
         this._reAttachOffscreen();
@@ -1181,6 +1114,7 @@ export default class AkariSub extends EventTarget {
     }
     /** Unload the current track without destroying the renderer. */
     freeTrack() {
+        this._supersedePendingTrackActivation();
         this._sendMutatingMessage('freeTrack');
     }
     /**
@@ -1191,6 +1125,7 @@ export default class AkariSub extends EventTarget {
      */
     initStreamingTrack(options) {
         const parsed = parseStreamingTrackOptions(options);
+        this._supersedePendingTrackActivation();
         this._bumpRenderEpoch();
         this.sendMessage('initStreamingTrack', { options: parsed }, parsed.header ? AkariSub._getSubtitleTransfers(parsed.header) : undefined);
         this._reAttachOffscreen();
@@ -1265,8 +1200,9 @@ export default class AkariSub extends EventTarget {
         return { id: result.id };
     }
     /**
-     * Replace the visible track with a previously preloaded one. The last
-     * painted frame stays on screen until the new track's first frame is ready.
+     * Replace the visible track with a previously preloaded one. The returned
+     * promise waits for the matching readiness cycle; paused exact-timeline
+     * renderers also finish their configured frame-prefetch runway.
      */
     async activatePreloadedTrack(id = this._preloadedTrackId ?? -1) {
         const ready = this._workerReady ||
@@ -1277,22 +1213,38 @@ export default class AkariSub extends EventTarget {
             throw new Error('No preloaded track is ready');
         this._bumpRenderEpoch();
         const requestId = this._nextTrackRequestId++;
-        const result = await this._fetchFromWorker({
-            target: 'activatePreloadedTrack',
-            requestId,
-            id,
-            timeoutMs: null
-        });
-        if (!result.success || result.id == null) {
-            throw new Error(result.error || 'The preloaded track could not be activated');
+        const readiness = this._waitForTrackReady(requestId);
+        try {
+            const result = await this._fetchFromWorker({
+                target: 'activatePreloadedTrack',
+                requestId,
+                id,
+                timeoutMs: null
+            });
+            if (!result.success || result.id == null) {
+                throw new Error(result.error || 'The preloaded track could not be activated');
+            }
+            if (this._preloadedTrackId === result.id)
+                this._preloadedTrackId = null;
+            const requiresCanvasColorConversion = this._requiresCanvasColorConversion();
+            const reattachedOffscreen = !requiresCanvasColorConversion && this._offscreenRender && !!this._ctx;
+            if (!requiresCanvasColorConversion) {
+                this._reAttachOffscreen();
+                if (this._ctx)
+                    this._ctx.filter = 'none';
+            }
+            // The matching trackReady already synchronized the clock. Repeat it only
+            // when reattachment replaced the canvas that received that first render.
+            if (reattachedOffscreen)
+                this._syncVideoClock();
+            const readinessError = await readiness.promise;
+            if (readinessError)
+                throw readinessError;
+            return { id: result.id };
+        }
+        finally {
+            readiness.cancel();
         }
-        if (this._preloadedTrackId === result.id)
-            this._preloadedTrackId = null;
-        this._reAttachOffscreen();
-        if (this._ctx)
-            this._ctx.filter = 'none';
-        this._syncVideoClock();
-        return { id: result.id };
     }
     /** Tell the worker whether playback is paused. Ignored when a video element is attached. */
     setIsPaused(isPaused) {
@@ -1464,6 +1416,22 @@ export default class AkariSub extends EventTarget {
         this._primePreparedFrames(this._currentExactFrameMediaTime());
         this._dispatchNextPreparation();
     }
+    /** Subtitle time offset in seconds. Changing it discards prepared frames rendered with the previous offset. */
+    get timeOffset() {
+        return this._timeOffset;
+    }
+    set timeOffset(value) {
+        if (!Number.isFinite(value) || value === this._timeOffset)
+            return;
+        const previous = this._timeOffset;
+        this._timeOffset = value;
+        if (typeof previous !== 'number' || this._destroyed)
+            return;
+        this._bumpRenderEpoch();
+        this._syncVideoClock();
+        this._primePreparedFrames(this._currentExactFrameMediaTime());
+        this._dispatchNextPreparation();
+    }
     /** Number of events in the loaded track. */
     async getEventCount() {
         const data = await this._fetchFromWorker({ target: 'getEventCount' });
@@ -1565,12 +1533,11 @@ export default class AkariSub extends EventTarget {
             return true;
         if (metadata.width !== this._videoWidth || metadata.height !== this._videoHeight)
             return false;
-        const prepared = this._preparedFrames.get(frameIndex);
+        const prepared = this._presentation.take(frameIndex);
         if (!prepared)
             return false;
-        this._preparedFrames.delete(frameIndex);
         if (prepared.width !== this._canvasctrl.width || prepared.height !== this._canvasctrl.height) {
-            this._disposePreparedFrame(prepared);
+            this._presentation.dispose(prepared);
             this._prepareForce = true;
             return false;
         }
@@ -1588,7 +1555,7 @@ export default class AkariSub extends EventTarget {
         }
         const event = this._frameBufferReadyEvent;
         this._frameBufferReadyEvent = null;
-        this.dispatchEvent(new CustomEvent(event));
+        this.dispatchEvent(new CustomEvent(event.type, event.requestId == null ? undefined : { detail: { requestId: event.requestId } }));
     }
     /** @internal */
     _startRefreshSampling() {
@@ -1633,18 +1600,6 @@ export default class AkariSub extends EventTarget {
         this._gpuRenderer?.releaseCanvas(stage);
     }
     /** @internal */
-    _removeStagedCanvas(stage) {
-        for (const animation of stage.getAnimations())
-            animation.cancel();
-        this._releaseGPUStage(stage);
-        stage.remove();
-        if (this._committedStage === stage)
-            this._committedStage = null;
-        this._stagedCanvases.delete(stage);
-        this._stageFrameIndices.delete(stage);
-        this._stageDisplayTimes.delete(stage);
-    }
-    /** @internal */
     _currentExactFrameIndex() {
         if (!this._frameTimeline)
             return undefined;
@@ -1665,49 +1620,7 @@ export default class AkariSub extends EventTarget {
     }
     /** Make a freshly painted base canvas visible without discarding future prefetch. */
     _activateBaseCanvas(presentedIndex) {
-        if (!this._canvas)
-            return;
-        // A compositor-scheduled frame can become visible before its RVFC arrives.
-        // Never let an older demand response roll that already-visible frame back.
-        if (presentedIndex != null) {
-            const now = performance.now();
-            let visibleIndex = this._committedStage ? this._stageFrameIndices.get(this._committedStage) : undefined;
-            for (const stage of this._stagedCanvases) {
-                const boundary = this._stageDisplayTimes.get(stage);
-                const index = this._stageFrameIndices.get(stage);
-                if (boundary != null && boundary <= now && index != null && (visibleIndex == null || index > visibleIndex)) {
-                    visibleIndex = index;
-                }
-            }
-            if (visibleIndex != null && visibleIndex > presentedIndex)
-                return;
-        }
-        for (const animation of this._canvas.getAnimations())
-            animation.cancel();
-        this._canvas.style.opacity = '1';
-        const retainedStages = new Set();
-        for (const [index, frame] of [...this._preparedFrames]) {
-            const frameIndex = frame.index ?? index;
-            if (presentedIndex != null && frameIndex > presentedIndex && frame.stage) {
-                for (const animation of frame.animations ?? [])
-                    animation.cancel();
-                frame.animations = undefined;
-                frame.scheduled = false;
-                frame.committed = false;
-                frame.stage.style.opacity = '0';
-                retainedStages.add(frame.stage);
-                continue;
-            }
-            this._disposePreparedFrame(frame);
-            this._preparedFrames.delete(index);
-        }
-        this._scheduledPreparedFrame = null;
-        for (const stage of [...this._stagedCanvases]) {
-            if (!retainedStages.has(stage))
-                this._removeStagedCanvas(stage);
-        }
-        this._committedStage = null;
-        this._scheduleNextPreparedFrame();
+        this._presentation.activateBase(presentedIndex);
     }
     /** @internal */
     _activateBaseCanvasAfterGPUWork(renderEpoch = this._renderEpoch, presentedIndex) {
@@ -1734,22 +1647,6 @@ export default class AkariSub extends EventTarget {
         });
     }
     /** @internal */
-    _disposePreparedFrame(frame) {
-        if (this._scheduledPreparedFrame === frame)
-            this._scheduledPreparedFrame = null;
-        for (const animation of frame.animations ?? [])
-            animation.cancel();
-        frame.animations = undefined;
-        frame.scheduled = false;
-        frame.bitmap?.close();
-        frame.bitmap = undefined;
-        frame.gpuStage = false;
-        if (frame.stage) {
-            this._removeStagedCanvas(frame.stage);
-            frame.stage = undefined;
-        }
-    }
-    /** @internal */
     _stagePreparedFrame(index, frame, allowWebGPU = true) {
         if (!this._canvasParent || !frame.bitmap || this._destroyed)
             return;
@@ -1761,8 +1658,7 @@ export default class AkariSub extends EventTarget {
         frame.index = index;
         frame.stage = stage;
         frame.ready = false;
-        this._stagedCanvases.add(stage);
-        this._stageFrameIndices.set(stage, index);
+        this._presentation.register(stage, index);
         let rendered = false;
         const webgpuRenderer = allowWebGPU && this._rendererType === 'webgpu' && this._gpuRenderer instanceof WebGPURenderer
             ? this._gpuRenderer
@@ -1786,18 +1682,17 @@ export default class AkariSub extends EventTarget {
             // desynchronized:true can expose a newly appended but not-yet-painted layer.
             const context = stage.getContext('2d', this._canvas2dSettings());
             if (!context) {
-                this._removeStagedCanvas(stage);
+                this._presentation.remove(stage);
                 stage = document.createElement('canvas');
                 stage.width = frame.width;
                 stage.height = frame.height;
                 this._syncStagedCanvasLayout(stage);
                 stage.style.opacity = '0';
                 frame.stage = stage;
-                this._stagedCanvases.add(stage);
-                this._stageFrameIndices.set(stage, index);
+                this._presentation.register(stage, index);
                 const fallbackContext = stage.getContext('2d', this._canvas2dSettings());
                 if (!fallbackContext) {
-                    this._removeStagedCanvas(stage);
+                    this._presentation.remove(stage);
                     frame.stage = undefined;
                     return;
                 }
@@ -1824,157 +1719,7 @@ export default class AkariSub extends EventTarget {
             // promise is pending, rejecting it and starving prefetch forever.
             frame.ready = true;
         }
-        this._scheduleNextPreparedFrame();
-    }
-    /** @internal */
-    _scheduleNextPreparedFrame() {
-        if (this._scheduledPreparedFrame || this._destroyed)
-            return;
-        let next;
-        let nextTime = Number.POSITIVE_INFINITY;
-        const now = performance.now();
-        for (const frame of this._preparedFrames.values()) {
-            const target = frame.targetDisplayTime;
-            if (!frame.stage ||
-                frame.committed ||
-                frame.scheduled ||
-                !Number.isFinite(target) ||
-                target <= now ||
-                target >= nextTime) {
-                continue;
-            }
-            next = frame;
-            nextTime = target;
-        }
-        if (next?.ready)
-            this._schedulePreparedFrame(next, nextTime);
-    }
-    /** @internal */
-    _commitPreparedStage(frame) {
-        const stage = frame.stage;
-        if (!stage || !this._stagedCanvases.has(stage) || this._destroyed)
-            return;
-        if (!frame.committed) {
-            this._commitGPUSnapshot(this._snapshotRenderedCanvas(stage, frame.gpuStage === true));
-        }
-        for (const animation of frame.animations ?? [])
-            animation.cancel();
-        frame.animations = undefined;
-        frame.scheduled = false;
-        frame.committed = true;
-        if (this._scheduledPreparedFrame === frame)
-            this._scheduledPreparedFrame = null;
-        for (const animation of this._canvas.getAnimations())
-            animation.cancel();
-        this._canvas.style.opacity = '0';
-        stage.style.opacity = '1';
-        this._committedStage = stage;
-        const frameIndex = frame.index ?? this._stageFrameIndices.get(stage);
-        for (const candidate of [...this._stagedCanvases]) {
-            if (candidate === stage)
-                continue;
-            for (const animation of candidate.getAnimations())
-                animation.cancel();
-            const candidateIndex = this._stageFrameIndices.get(candidate);
-            const shouldRetire = frame.replaceAll || frameIndex == null || candidateIndex == null || candidateIndex < frameIndex;
-            if (shouldRetire) {
-                this._removeStagedCanvas(candidate);
-            }
-            else {
-                candidate.style.opacity = '0';
-            }
-        }
-        this._scheduleNextPreparedFrame();
-    }
-    /** @internal */
-    _schedulePreparedFrame(frame, targetDisplayTime) {
-        const stage = frame.stage;
-        frame.targetDisplayTime = targetDisplayTime;
-        if (!stage ||
-            !frame.ready ||
-            frame.scheduled ||
-            frame.committed ||
-            this._scheduledPreparedFrame ||
-            this._destroyed ||
-            targetDisplayTime <= performance.now()) {
-            return;
-        }
-        // Each swap independently hides every other layer. Do not form a single
-        // predecessor chain: removing one skipped prefetched frame would otherwise
-        // cancel the only animation capable of hiding its predecessor. Future and
-        // unscheduled stages are hidden too, but retained for their own later show.
-        const previousStages = [...this._stagedCanvases].filter((candidate) => candidate !== stage);
-        this._stageDisplayTimes.set(stage, targetDisplayTime);
-        const performanceTime = performance.now();
-        const compositorSwapTime = targetDisplayTime - compositorScheduleLeadMs(estimateRefreshIntervalMs(this._refreshSamples ?? []));
-        const documentTime = Number(document.timeline?.currentTime);
-        const hasDocumentTime = Number.isFinite(documentTime);
-        const sharedStartTime = hasDocumentTime ? documentTime + (compositorSwapTime - performanceTime) : undefined;
-        const animationOptions = {
-            delay: hasDocumentTime ? 0 : Math.max(0, compositorSwapTime - performanceTime),
-            // A near-zero positive interval keeps the swap compositor-scheduled while
-            // allowing its cleanup promise to run in the same refresh. A full 1 ms
-            // interval can survive until the next paint when animation composite order
-            // temporarily favors an older stage.
-            duration: 0.001,
-            easing: 'steps(1, jump-start)',
-            fill: 'forwards'
-        };
-        const hiddenLayers = [this._canvas, ...previousStages];
-        let showAnimation = null;
-        const hideAnimations = [];
-        try {
-            showAnimation = stage.animate([{ opacity: '0' }, { opacity: '1' }], animationOptions);
-            for (const layer of hiddenLayers) {
-                hideAnimations.push(layer.animate([{ opacity: '1' }, { opacity: '0' }], animationOptions));
-            }
-        }
-        catch {
-            showAnimation?.cancel();
-            for (const animation of hideAnimations)
-                animation.cancel();
-            return;
-        }
-        if (!showAnimation)
-            return;
-        if (sharedStartTime != null) {
-            showAnimation.startTime = sharedStartTime;
-            for (const animation of hideAnimations)
-                animation.startTime = sharedStartTime;
-        }
-        frame.scheduled = true;
-        this._scheduledPreparedFrame = frame;
-        const swapAnimations = [showAnimation, ...hideAnimations];
-        frame.animations = swapAnimations;
-        const releaseSwapAnimations = () => {
-            for (const animation of swapAnimations)
-                animation.cancel();
-            if (frame.animations === swapAnimations)
-                frame.animations = undefined;
-        };
-        // The show animation is the authoritative commit. Once it completes, make
-        // its state explicit, release this swap's fill animations, and remove all
-        // older layers. A later prefetched swap may already have its own independent
-        // hide animation on this stage; it is intentionally left untouched.
-        void showAnimation.finished.then(() => {
-            if (frame.animations !== swapAnimations)
-                return;
-            if (!frame.committed)
-                this._commitPreparedStage(frame);
-            releaseSwapAnimations();
-            if (this._scheduledPreparedFrame === frame)
-                this._scheduledPreparedFrame = null;
-            this._scheduleNextPreparedFrame();
-        }, () => {
-            if (frame.animations !== swapAnimations)
-                return;
-            releaseSwapAnimations();
-            if (this._scheduledPreparedFrame === frame)
-                this._scheduledPreparedFrame = null;
-            frame.scheduled = false;
-            if (!frame.committed)
-                this._scheduleNextPreparedFrame();
-        });
+        this._presentation.scheduleNext();
     }
     /** @internal */
     _recordPresentationClock(frameIndex, mediaTime, expectedDisplayTime) {
@@ -2009,70 +1754,14 @@ export default class AkariSub extends EventTarget {
         if (!Number.isFinite(targetDisplayTime))
             return;
         this._predictedDisplayTimes.set(frameIndex + 1, targetDisplayTime);
-        const prepared = this._preparedFrames.get(frameIndex + 1);
+        const prepared = this._presentation.get(frameIndex + 1);
         if (prepared)
             prepared.targetDisplayTime = targetDisplayTime;
-        this._scheduleNextPreparedFrame();
+        this._presentation.scheduleNext();
     }
     /** @internal */
     _clearPreparedFrames(preservePresentation = true) {
-        let preservedStage = preservePresentation ? this._committedStage : null;
-        if (preservePresentation) {
-            const now = performance.now();
-            let latestBoundary = preservedStage ? (this._stageDisplayTimes.get(preservedStage) ?? -Infinity) : -Infinity;
-            for (const stage of this._stagedCanvases) {
-                const boundary = this._stageDisplayTimes.get(stage);
-                if (boundary != null && boundary <= now && boundary >= latestBoundary) {
-                    preservedStage = stage;
-                    latestBoundary = boundary;
-                }
-            }
-        }
-        const preservedFrameIndex = preservedStage ? this._stageFrameIndices.get(preservedStage) : undefined;
-        const preservedDisplayTime = preservedStage ? this._stageDisplayTimes.get(preservedStage) : undefined;
-        this._scheduledPreparedFrame = null;
-        for (const frame of this._preparedFrames.values()) {
-            if (frame.stage === preservedStage) {
-                for (const animation of frame.animations ?? [])
-                    animation.cancel();
-                frame.animations = undefined;
-                frame.scheduled = false;
-                frame.bitmap?.close();
-                frame.bitmap = undefined;
-                continue;
-            }
-            this._disposePreparedFrame(frame);
-        }
-        this._preparedFrames.clear();
-        for (const stage of [...this._stagedCanvases]) {
-            if (stage !== preservedStage)
-                this._removeStagedCanvas(stage);
-        }
-        this._stagedCanvases.clear();
-        this._stageFrameIndices.clear();
-        this._stageDisplayTimes.clear();
-        for (const animation of this._canvas?.getAnimations?.() ?? [])
-            animation.cancel();
-        if (preservedStage?.isConnected) {
-            for (const animation of preservedStage.getAnimations())
-                animation.cancel();
-            preservedStage.style.opacity = '1';
-            this._stagedCanvases.add(preservedStage);
-            if (preservedFrameIndex != null)
-                this._stageFrameIndices.set(preservedStage, preservedFrameIndex);
-            if (preservedDisplayTime != null)
-                this._stageDisplayTimes.set(preservedStage, preservedDisplayTime);
-            if (this._canvas)
-                this._canvas.style.opacity = '0';
-            this._committedStage = preservedStage;
-        }
-        else {
-            if (preservedStage)
-                this._removeStagedCanvas(preservedStage);
-            this._committedStage = null;
-            if (this._canvas)
-                this._canvas.style.opacity = '1';
-        }
+        this._presentation.clear(preservePresentation);
         this._predictedDisplayTimes.clear();
         this._displayClockOffsets.length = 0;
         this._displayGridAnchorMs = undefined;
@@ -2085,26 +1774,16 @@ export default class AkariSub extends EventTarget {
     /** @internal */
     _primePreparedFrames(mediaTime) {
         const timeline = this._frameTimeline;
-        if (!timeline || timeline.length === 0 || this.framePrefetch <= 0 || this._destroyed) {
+        if (!timeline ||
+            timeline.length === 0 ||
+            this.framePrefetch <= 0 ||
+            this._destroyed ||
+            (this._prepareFailureEpoch ?? -1) >= 0 && this._prepareFailureEpoch === this._renderEpoch) {
             return;
         }
         const currentIndex = presentedFrameIndex(timeline, mediaTime);
         const lastIndex = Math.min(timeline.length - 1, currentIndex + this.framePrefetch);
-        for (const [index, frame] of this._preparedFrames) {
-            if (index < currentIndex || index > lastIndex) {
-                // A scheduled stage may already be the compositor's visible frame even
-                // when Chromium skips/delays its RVFC. Removing it here produces a blank
-                // refresh. Its successor's completed hide animation owns stage cleanup.
-                if ((frame.scheduled || frame.committed) && index < currentIndex) {
-                    frame.bitmap?.close();
-                    frame.bitmap = undefined;
-                }
-                else {
-                    this._disposePreparedFrame(frame);
-                }
-                this._preparedFrames.delete(index);
-            }
-        }
+        this._presentation.prune(currentIndex, lastIndex);
         const queued = this._prepareQueue.filter((index) => index > currentIndex && index <= lastIndex);
         this._prepareQueue.length = 0;
         this._prepareQueue.push(...queued);
@@ -2114,17 +1793,22 @@ export default class AkariSub extends EventTarget {
         for (const index of this._prepareQueue)
             requested.add(index);
         for (let index = currentIndex + 1; index <= lastIndex; index++) {
-            if (!this._preparedFrames.has(index) && !requested.has(index))
+            if (!this._presentation.has(index) && !requested.has(index))
                 this._prepareQueue.push(index);
         }
     }
     /** @internal */
     _dispatchNextPreparation() {
-        if (this.busy || !this._workerReady || !this._frameTimeline || this.framePrefetch <= 0)
+        if (this.busy ||
+            !this._workerReady ||
+            !this._frameTimeline ||
+            this.framePrefetch <= 0 ||
+            (this._prepareFailureEpoch ?? -1) >= 0 && this._prepareFailureEpoch === this._renderEpoch) {
             return;
+        }
         let index;
         while ((index = this._prepareQueue.shift()) != null) {
-            if (!this._preparedFrames.has(index))
+            if (!this._presentation.has(index))
                 break;
         }
         if (index == null)
@@ -2148,9 +1832,15 @@ export default class AkariSub extends EventTarget {
     _preparedFrame(data) {
         const request = this._prepareRequests.get(data.prepareId);
         this._prepareRequests.delete(data.prepareId);
+        const validEpoch = request != null && request.renderEpoch === this._renderEpoch && data.renderEpoch === this._renderEpoch;
+        if (data.failed && validEpoch) {
+            // A snapshot failure must not immediately enqueue the same frame again.
+            // Fall back to demand rendering for this epoch and let a later epoch retry.
+            this._prepareFailureEpoch = this._renderEpoch;
+            this._prepareQueue.length = 0;
+        }
         if (request?.presentation) {
             const presentation = request.presentation;
-            const validEpoch = request.renderEpoch === this._renderEpoch && data.renderEpoch === this._renderEpoch;
             const currentIndex = this._currentExactFrameIndex();
             const obsolete = currentIndex != null && request.index < currentIndex;
             if (data.bitmap && validEpoch && !obsolete) {
@@ -2185,9 +1875,6 @@ export default class AkariSub extends EventTarget {
             request.renderEpoch === this._renderEpoch &&
             data.renderEpoch === this._renderEpoch &&
             request.index >= currentIndex) {
-            const previous = this._preparedFrames.get(request.index);
-            if (previous)
-                this._disposePreparedFrame(previous);
             const prepared = {
                 width: data.width ?? this._canvasctrl.width,
                 height: data.height ?? this._canvasctrl.height,
@@ -2195,8 +1882,7 @@ export default class AkariSub extends EventTarget {
                 time: data.time
             };
             this._stagePreparedFrame(request.index, prepared);
-            this._preparedFrames.set(request.index, prepared);
-            this._scheduleNextPreparedFrame();
+            this._presentation.store(request.index, prepared);
         }
         else {
             data.bitmap?.close();
@@ -2209,35 +1895,12 @@ export default class AkariSub extends EventTarget {
     /** @internal */
     _presentPreparedFrame(frame, presentationId, expectedDisplayTime) {
         if (!this._activatePresentation(presentationId, frame.time)) {
-            // Scheduling happens on the display clock before RVFC validation. If a
-            // newer callback has already advanced the presentation watermark, this
-            // stage can still be the compositor's current frame. Never tear down a
-            // scheduled stage from a stale callback; the next atomic swap removes it.
-            if (frame.stage && (frame.scheduled || frame.committed || this._committedStage === frame.stage)) {
-                frame.bitmap?.close();
-                frame.bitmap = undefined;
-            }
-            else {
-                this._disposePreparedFrame(frame);
-            }
+            this._presentation.reject(frame);
             return;
         }
         const { bitmap, width, height, stage } = frame;
         if (stage) {
-            if (!frame.committed || this._committedStage !== stage) {
-                for (const animation of frame.animations ?? []) {
-                    try {
-                        animation.finish();
-                    }
-                    catch {
-                        animation.cancel();
-                    }
-                }
-                this._commitPreparedStage(frame);
-            }
-            this._stageDisplayTimes.set(stage, Number.isFinite(expectedDisplayTime) ? expectedDisplayTime : performance.now());
-            bitmap?.close();
-            frame.bitmap = undefined;
+            this._presentation.present(frame, expectedDisplayTime);
             return;
         }
         if (!bitmap)
@@ -2258,11 +1921,11 @@ export default class AkariSub extends EventTarget {
                     frame.replaceAll = true;
                     this._stagePreparedFrame(-1, frame, false);
                     if (frame.stage)
-                        this._commitPreparedStage(frame);
+                        this._presentation.commit(frame);
                     return;
                 }
                 const completion = this._activateBaseCanvasAfterGPUWork(this._renderEpoch, frame.index) ?? true;
-                void this._retainGPUFrameAfter(completion, snapshot);
+                void this._gpuRecovery.retainAfter(completion, snapshot);
                 return;
             }
             if (this._ctx) {
@@ -2300,6 +1963,7 @@ export default class AkariSub extends EventTarget {
     /** @internal */
     _bumpRenderEpoch() {
         this._renderEpoch++;
+        this._prepareFailureEpoch = -1;
         this._pendingDemandTimes.length = 0;
         this._demandTimings.clear();
         this._clearPreparedFrames();
@@ -2343,6 +2007,16 @@ export default class AkariSub extends EventTarget {
             }
             if (this._destroyed || this._video !== video || generation !== this._rvfcGeneration)
                 return;
+            if (this._playstate &&
+                !video.paused &&
+                !video.ended &&
+                !video.seeking &&
+                this._lastRvfcMediaTime != null &&
+                metadata.mediaTime > this._lastRvfcMediaTime) {
+                this._playstate = false;
+                this._syncVideoClock();
+            }
+            this._lastRvfcMediaTime = metadata.mediaTime;
             this._handleRVFC(now, metadata);
         });
     }
@@ -2384,14 +2058,12 @@ export default class AkariSub extends EventTarget {
         switch (event.type) {
             case 'play':
             case 'playing':
-            case 'canplay':
                 this._playstate = false;
                 break;
             case 'pause':
             case 'ended':
             case 'seeking':
             case 'waiting':
-            case 'stalled':
                 this._playstate = true;
                 break;
             case 'seeked':
@@ -2498,15 +2170,14 @@ export default class AkariSub extends EventTarget {
             const frameIndex = presentedFrameIndex(this._frameTimeline, mediaTime);
             if (frameIndex >= 0)
                 this._lastPresentedFrameIndex = frameIndex;
-            const prepared = this._preparedFrames.get(frameIndex);
+            const prepared = this._presentation.take(frameIndex);
             if (prepared) {
-                this._preparedFrames.delete(frameIndex);
                 if (prepared.width === this._canvasctrl.width && prepared.height === this._canvasctrl.height) {
                     this._presentPreparedFrame(prepared, presentationId, expectedDisplayTime);
                     presented = true;
                 }
                 else {
-                    this._disposePreparedFrame(prepared);
+                    this._presentation.dispose(prepared);
                     this._prepareForce = true;
                 }
             }
@@ -2730,6 +2401,7 @@ export default class AkariSub extends EventTarget {
                 const hasAlphaBug = AkariSub._hasAlphaBug ?? false;
                 const bufferCanvas = this._bufferCanvas;
                 const bufferCtx = this._bufferCtx;
+                const canWritePreblendedDirectly = data.preblended === true && ctx.filter === 'none';
                 for (let i = 0; i < imageCount; i++) {
                     const image = images[i];
                     if (image.image) {
@@ -2742,11 +2414,20 @@ export default class AkariSub extends EventTarget {
                                 ? new Uint8ClampedArray(rawImage.buffer, rawImage.byteOffset, rawImage.byteLength)
                                 : new Uint8ClampedArray(rawImage);
                         const fixedData = fixAlpha(rawData, hasAlphaBug);
+                        const imageData = createSubtitleImageData(fixedData, imgW, imgH);
+                        if (canWritePreblendedDirectly) {
+                            // renderBlendCollect guarantees these rectangles are already
+                            // source-over flattened and mutually disjoint. The render target
+                            // is cleared above, so a direct write preserves the same frame
+                            // while avoiding one upload and draw per plane.
+                            ctx.putImageData(imageData, image.x, image.y);
+                            continue;
+                        }
                         if (bufferCanvas.width !== imgW || bufferCanvas.height !== imgH) {
                             bufferCanvas.width = imgW;
                             bufferCanvas.height = imgH;
                         }
-                        bufferCtx.putImageData(createSubtitleImageData(fixedData, imgW, imgH), 0, 0);
+                        bufferCtx.putImageData(imageData, 0, 0);
                         ctx.drawImage(bufferCanvas, image.x, image.y);
                     }
                 }
@@ -2797,7 +2478,7 @@ export default class AkariSub extends EventTarget {
             }
             if (painted !== false) {
                 const completion = this._activateBaseCanvasAfterGPUWork(data.renderEpoch, presentedIndex) ?? true;
-                return this._retainGPUFrameAfter(completion, snapshot);
+                return this._gpuRecovery.retainAfter(completion, snapshot);
             }
             this._discardGPUSnapshot(snapshot);
             return false;
@@ -2842,7 +2523,7 @@ export default class AkariSub extends EventTarget {
             }
         }
         const completion = painted !== false ? (this._activateBaseCanvasAfterGPUWork(data.renderEpoch, presentedIndex) ?? true) : false;
-        const retainedCompletion = this._retainGPUFrameAfter(completion, snapshot);
+        const retainedCompletion = this._gpuRecovery.retainAfter(completion, snapshot);
         if (this.debug) {
             data.times.JSRenderTime = Date.now() - (data.times.JSRenderTime || 0) - (data.times.IPCTime || 0);
             let total = 0;
@@ -2863,7 +2544,7 @@ export default class AkariSub extends EventTarget {
             const currentTime = this._clockCurrentTime() ?? 0;
             const isPaused = this._isVideoPausedForWorker();
             const bufferExactFrames = isPaused && this._onDemandRender && !!this._frameTimeline?.length && this.framePrefetch > 0;
-            this._frameBufferReadyEvent = bufferExactFrames ? 'ready' : null;
+            this._frameBufferReadyEvent = bufferExactFrames ? { type: 'ready' } : null;
             this.setCurrentTime(isPaused, currentTime + this.timeOffset, this._videoPlaybackRateForWorker());
             if (!this._onDemandRender) {
                 this.dispatchEvent(new CustomEvent('ready'));
@@ -2892,20 +2573,39 @@ export default class AkariSub extends EventTarget {
         this.dispatchEvent(new CustomEvent('partial_ready'));
     }
     /** @internal */
-    _trackReady() {
+    _trackReady(data = {}) {
+        this._supersedePendingTrackActivation(data.requestId);
         const bufferExactFrames = this._workerReady &&
             this._isVideoPausedForWorker() &&
             this._onDemandRender &&
             !!this._frameTimeline?.length &&
             this.framePrefetch > 0;
-        this._frameBufferReadyEvent = bufferExactFrames ? 'trackReady' : null;
+        this._frameBufferReadyEvent = bufferExactFrames
+            ? { type: 'trackReady', requestId: data.requestId }
+            : null;
         this._syncVideoClock();
         if (bufferExactFrames) {
             this._primePreparedFrames(this._currentExactFrameMediaTime());
             this._dispatchNextPreparation();
             return;
         }
-        this.dispatchEvent(new CustomEvent('trackReady'));
+        this.dispatchEvent(new CustomEvent('trackReady', data.requestId == null ? undefined : { detail: { requestId: data.requestId } }));
+    }
+    /** @internal */
+    _supersedePendingTrackActivation(nextRequestId) {
+        const supersededRequestIds = new Set();
+        for (const [requestId, supersede] of [...(this._pendingTrackReadyWaiters ?? [])]) {
+            if (requestId === nextRequestId)
+                continue;
+            supersededRequestIds.add(requestId);
+            supersede(new Error('Track activation was superseded by a newer track change'));
+        }
+        const pending = this._frameBufferReadyEvent;
+        if (pending?.type === 'trackReady' &&
+            pending.requestId != null &&
+            supersededRequestIds.has(pending.requestId)) {
+            this._frameBufferReadyEvent = null;
+        }
     }
     /** Send a raw message to the worker. Prefer the typed methods above. */
     async sendMessage(target, data = {}, transferable) {
@@ -2944,6 +2644,15 @@ export default class AkariSub extends EventTarget {
                         reject(new Error('Error: Timeout while trying to fetch ' + target));
                     }, timeoutMs);
                 const handleMessage = (event) => {
+                    if (event.data.target === 'error') {
+                        const workerError = event.data.error;
+                        handleError(workerError instanceof Error
+                            ? workerError
+                            : new Error(typeof workerError === 'string'
+                                ? workerError
+                                : workerError?.message || 'Unknown worker error'));
+                        return;
+                    }
                     if (event.data.target === target &&
                         (workerMessage.requestId === undefined || event.data.requestId === workerMessage.requestId)) {
                         cleanup();
@@ -2982,6 +2691,45 @@ export default class AkariSub extends EventTarget {
         });
     }
     /** @internal */
+    _waitForTrackReady(requestId) {
+        let cancel = () => { };
+        const promise = new Promise((resolve) => {
+            let settled = false;
+            const cleanup = () => {
+                this.removeEventListener('trackReady', handleTrackReady);
+                this.removeEventListener('error', handleError);
+                this._pendingWorkerRejectors.delete(handleDestroyed);
+                if (this._pendingTrackReadyWaiters.get(requestId) === handleSuperseded) {
+                    this._pendingTrackReadyWaiters.delete(requestId);
+                }
+            };
+            const settle = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(error);
+            };
+            const handleTrackReady = (event) => {
+                if (event.detail?.requestId !== requestId)
+                    return;
+                settle(null);
+            };
+            const handleError = (event) => {
+                const errorEvent = event;
+                settle(errorEvent.error instanceof Error ? errorEvent.error : new Error(errorEvent.message || 'Renderer error'));
+            };
+            const handleDestroyed = (error) => settle(error);
+            const handleSuperseded = (error) => settle(error);
+            cancel = () => settle(null);
+            this.addEventListener('trackReady', handleTrackReady);
+            this.addEventListener('error', handleError);
+            this._pendingWorkerRejectors.add(handleDestroyed);
+            this._pendingTrackReadyWaiters.set(requestId, handleSuperseded);
+        });
+        return { promise, cancel: () => cancel() };
+    }
+    /** @internal */
     _cues(data) {
         for (const cue of data.exited) {
             this._onCueExit?.(cue);
@@ -3101,13 +2849,12 @@ export default class AkariSub extends EventTarget {
             cancelAnimationFrame(this._refreshRafHandle);
             this._refreshRafHandle = null;
         }
-        this._clearGPURecoveryTimer();
-        this._gpuRecoveryGeneration++;
-        this._gpuRecovering = null;
+        this._gpuRecovery.destroy();
         this._recoveryCanvas?.remove();
         this._recoveryCanvas = null;
         this._recoveryCtx = null;
         this._clearPreparedFrames(false);
+        this._presentation.destroy();
         if (this._video && this._canvasParent) {
             this._video.parentNode?.removeChild(this._canvasParent);
         }
@@ -3116,7 +2863,6 @@ export default class AkariSub extends EventTarget {
             this._gpuRenderer = null;
             this._rendererType = 'canvas2d';
         }
-        this._lastGPUFrame = null;
         this._gpuSnapshotPool.length = 0;
         this._destroyed = true;
         this._resolveDestroyed?.();