@editframe/elements 0.37.3-beta → 0.38.0

package/dist/elements/EFVideo.js

@@ -1,15 +1,15 @@
-import { updateAnimations } from "./updateAnimations.js";
-import { __decorate } from "../_virtual/_@oxc-project_runtime@0.95.0/helpers/decorate.js";
 import { TWMixin } from "../gui/TWMixin2.js";
 import { withSpanSync } from "../otel/tracingHelpers.js";
-import { PRIORITY_VIDEO, createFrameTaskWrapper } from "../preview/FrameController.js";
+import { PRIORITY_VIDEO } from "../preview/FrameController.js";
+import { updateAnimations } from "./updateAnimations.js";
+import { __decorate } from "../_virtual/_@oxc-project_runtime@0.95.0/helpers/decorate.js";
 import { EFMedia } from "./EFMedia.js";
 import { DelayedLoadingState } from "../DelayedLoadingState.js";
 import { MainVideoInputCache } from "./EFMedia/videoTasks/MainVideoInputCache.js";
 import { ScrubInputCache } from "./EFMedia/videoTasks/ScrubInputCache.js";
 import debug from "debug";
 import { css, html } from "lit";
-import { customElement, property, state } from "lit/decorators.js";
+import { customElement, state } from "lit/decorators.js";
 import { context, trace } from "@opentelemetry/api";
 import { createRef, ref } from "lit/directives/ref.js";
 
@@ -17,21 +17,44 @@ import { createRef, ref } from "lit/directives/ref.js";
 const mainVideoInputCache = new MainVideoInputCache();
 const scrubInputCache = new ScrubInputCache();
 const log = debug("ef:elements:EFVideo");
+var VideoSeekTask = class {
+	constructor() {
+		this.value = void 0;
+		this.task = void 0;
+		this.taskComplete = Promise.resolve(void 0);
+	}
+	#resolve;
+	begin() {
+		this.taskComplete = new Promise((resolve) => {
+			this.#resolve = resolve;
+		});
+	}
+	complete(sample) {
+		this.value = sample;
+		this.#resolve?.(sample);
+	}
+	abort() {
+		this.#resolve?.(void 0);
+	}
+};
 let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	static {
 		this.styles = [css`
       :host {
         display: block;
         position: relative;
+        object-fit: contain;
+        object-position: center;
       }
       canvas {
         overflow: hidden;
         position: static;
         width: 100%;
         height: 100%;
+        object-fit: inherit;
+        object-position: inherit;
         margin: 0;
         padding: 0;
-        overflow: hidden;
         border: none;
         outline: none;
         box-shadow: none;
@@ -85,9 +108,29 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	#cachedVideoSample = void 0;
 	#cachedVideoSampleTimeMs = void 0;
 	/**
+	* Quality upgrade intent tracking.
+	* Tracks what upgrade tasks were last submitted to avoid redundant scheduler calls.
+	*/
+	#upgradeState = null;
+	/**
+	* Standalone upgrade controller for elements without a timegroup.
+	*/
+	#standaloneUpgradeController = null;
+	/**
+	* Current rendition being displayed (for observability).
+	*/
+	#currentRenditionId = void 0;
+	/**
+	* Get the current rendition being displayed.
+	* @public
+	*/
+	get currentRenditionId() {
+		return this.#currentRenditionId;
+	}
+	/**
 	* Query readiness state for a given time.
 	* @implements FrameRenderable
-	* 
+	*
 	* Note: The timeMs parameter is the root timegroup's time. We check against
 	* this.currentSourceTimeMs since that's what we cache in prepareFrame.
 	*/
@@ -103,7 +146,7 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	/**
 	* Async preparation - seeks video and caches the sample.
 	* @implements FrameRenderable
-	* 
+	*
 	* Note: The timeMs parameter is the root timegroup's time. We ignore it and
 	* use this.currentSourceTimeMs instead, which accounts for:
 	* - Our position within the parent timegroup (ownCurrentTimeMs)
@@ -111,11 +154,13 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	*/
 	async prepareFrame(_timeMs, signal) {
 		signal.throwIfAborted();
+		this.unifiedVideoSeekTask.begin();
 		const sourceTimeMs = this.currentSourceTimeMs;
 		const mediaEngine = await this.getMediaEngine(signal);
 		if (!mediaEngine) {
 			this.#cachedVideoSample = void 0;
 			this.#cachedVideoSampleTimeMs = sourceTimeMs;
+			this.unifiedVideoSeekTask.complete(void 0);
 			return;
 		}
 		signal.throwIfAborted();
@@ -124,18 +169,23 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			signal.throwIfAborted();
 			this.#cachedVideoSample = videoSample;
 			this.#cachedVideoSampleTimeMs = sourceTimeMs;
+			this.unifiedVideoSeekTask.complete(videoSample);
 		} catch (error) {
-			if (error instanceof DOMException && error.name === "AbortError") throw error;
+			if (error instanceof DOMException && error.name === "AbortError") {
+				this.unifiedVideoSeekTask.abort();
+				throw error;
+			}
 			console.warn(`Video seek error at ${sourceTimeMs}ms:`, error);
 			this.#cachedVideoSample = void 0;
 			this.#cachedVideoSampleTimeMs = sourceTimeMs;
+			this.unifiedVideoSeekTask.complete(void 0);
 		}
 	}
 	/**
 	* Synchronous render - paints cached video sample to canvas.
 	* @implements FrameRenderable
-	* 
-	* Note: The timeMs parameter is the root timegroup's time. We use 
+	*
+	* Note: The timeMs parameter is the root timegroup's time. We use
 	* this.currentSourceTimeMs to match what prepareFrame cached.
 	*/
 	renderFrame(_timeMs) {
@@ -152,7 +202,7 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	}
 	/**
 	* Fetch video sample for a given time.
-	* 
+	*
 	* Uses a quality routing strategy:
 	* - In production rendering: always use main (full quality) track
 	* - In preview mode: try scrub track first for faster scrubbing, fall back to main
@@ -162,13 +212,24 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 		const mainRendition = mediaEngine.videoRendition;
 		if (mainRendition) {
 			const mainSegmentId = mediaEngine.computeSegmentId(desiredSeekTimeMs, mainRendition);
-			if (mainSegmentId !== void 0 && mediaEngine.isSegmentCached(mainSegmentId, mainRendition)) return this.#getMainVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
+			if (mainSegmentId !== void 0 && mediaEngine.isSegmentCached(mainSegmentId, mainRendition)) {
+				this.#currentRenditionId = "main";
+				return this.#getMainVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
+			}
+		}
+		if (this.isInProductionRenderingMode()) {
+			this.#currentRenditionId = "main";
+			return this.#getMainVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
 		}
-		if (this.isInProductionRenderingMode()) return this.#getMainVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
 		if (mediaEngine.getScrubVideoRendition?.()) {
 			const scrubSample = await this.#getScrubVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
-			if (scrubSample) return scrubSample;
+			if (scrubSample) {
+				this.#currentRenditionId = "scrub";
+				this.#maybeScheduleQualityUpgrade(mediaEngine, desiredSeekTimeMs);
+				return scrubSample;
+			}
 		}
+		this.#currentRenditionId = "main";
 		return this.#getMainVideoSampleForFrame(mediaEngine, desiredSeekTimeMs, signal);
 	}
 	/**
@@ -188,7 +249,11 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			let initSegment;
 			let mediaSegment;
 			try {
-				[initSegment, mediaSegment] = await Promise.all([mediaEngine.fetchInitSegment(scrubRenditionWithSrc, signal), mediaEngine.fetchMediaSegment(segmentId, scrubRenditionWithSrc, signal)]);
+				const initP = mediaEngine.fetchInitSegment(scrubRenditionWithSrc, signal);
+				const mediaP = mediaEngine.fetchMediaSegment(segmentId, scrubRenditionWithSrc, signal);
+				initP.catch(() => {});
+				mediaP.catch(() => {});
+				[initSegment, mediaSegment] = await Promise.all([initP, mediaP]);
 			} catch (error) {
 				if (error instanceof DOMException && error.name === "AbortError") throw error;
 				return;
@@ -225,7 +290,11 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			let initSegment;
 			let mediaSegment;
 			try {
-				[initSegment, mediaSegment] = await Promise.all([mediaEngine.fetchInitSegment(videoRendition, signal), mediaEngine.fetchMediaSegment(segmentId, videoRendition, signal)]);
+				const initP = mediaEngine.fetchInitSegment(videoRendition, signal);
+				const mediaP = mediaEngine.fetchMediaSegment(segmentId, videoRendition, signal);
+				initP.catch(() => {});
+				mediaP.catch(() => {});
+				[initSegment, mediaSegment] = await Promise.all([initP, mediaP]);
 			} catch (error) {
 				if (error instanceof DOMException && error.name === "AbortError") throw error;
 				if (error instanceof Error && (error.message.includes("401") || error.message.includes("UNAUTHORIZED") || error.message.includes("Failed to fetch") || error.message.includes("File not found") || error.message.includes("Media segment not found") || error.message.includes("Init segment not found") || error.message.includes("Track not found"))) return;
@@ -249,7 +318,7 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 		const videoTrack = await mainInput.getFirstVideoTrack();
 		if (!videoTrack) return;
 		signal.throwIfAborted();
-		return mainInput.seek(videoTrack.id, desiredSeekTimeMs);
+		return await mainInput.seek(videoTrack.id, desiredSeekTimeMs);
 	}
 	/**
 	* Delayed loading state manager for user feedback
@@ -258,21 +327,25 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	constructor() {
 		super();
 		this.canvasRef = createRef();
-		this.videoBufferDurationMs = 1e4;
-		this.maxVideoBufferFetches = 2;
-		this.enableVideoBuffering = true;
+		this.unifiedVideoSeekTask = new VideoSeekTask();
 		this.loadingState = {
 			isLoading: false,
 			operation: null,
 			message: ""
 		};
-		this.frameTask = createFrameTaskWrapper(this, { getTimeMs: () => this.desiredSeekTimeMs });
 		this.#delayedLoadingState = new DelayedLoadingState(250, (isLoading, message) => {
 			this.setLoadingState(isLoading, null, message);
 		});
 	}
 	updated(changedProperties) {
 		super.updated(changedProperties);
+		if (changedProperties.has("src") || changedProperties.has("fileId")) this.#invalidateUpgradeState("src-change");
+		if ([
+			"_trimStartMs",
+			"_trimEndMs",
+			"_sourceInMs",
+			"_sourceOutMs"
+		].some((prop) => changedProperties.has(prop))) this.#invalidateUpgradeState("bounds-change");
 	}
 	render() {
 		return html`
@@ -320,7 +393,6 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	}
 	/**
 	* Paint the current video frame to canvas
-	* Called by frameTask after seek is complete
 	*/
 	paint(seekToMs, parentSpan) {
 		const parentContext = parentSpan ? trace.setSpan(context.active(), parentSpan) : void 0;
@@ -356,14 +428,7 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			} catch (error) {
 				console.warn("Video pipeline error:", error);
 			}
-			if (!isProductionRendering) {
-				const isInRenderClone = !!this.closest(".ef-render-clone-container");
-				if (isInRenderClone) span.setAttribute("renderClone", true);
-				if (!isInRenderClone && (!this.rootTimegroup || this.rootTimegroup.currentTimeMs === 0 && this.desiredSeekTimeMs === 0)) {
-					span.setAttribute("skipped", "preview-initialization");
-					return;
-				}
-			} else {
+			if (!isProductionRendering) {} else {
 				if (!this.rootTimegroup) {
 					span.setAttribute("skipped", "no-root-timegroup");
 					return;
@@ -382,7 +447,7 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	*/
 	clearCanvas() {
 		if (!this.canvasElement) return;
-		const ctx = this.canvasElement.getContext("2d");
+		const ctx = this.canvasElement.getContext("2d", { willReadFrequently: true });
 		if (ctx) ctx.clearRect(0, 0, this.canvasElement.width, this.canvasElement.height);
 	}
 	/**
@@ -408,22 +473,26 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			}
 			const t1 = performance.now();
 			span.setAttribute("getCanvasMs", Math.round((t1 - t0) * 100) / 100);
-			const ctx = this.canvasElement.getContext("2d");
+			const ctx = this.canvasElement.getContext("2d", { willReadFrequently: true });
 			const t2 = performance.now();
 			span.setAttribute("getCtxMs", Math.round((t2 - t1) * 100) / 100);
 			if (!ctx) {
 				log("trace: displayFrame aborted - no canvas context");
 				throw new Error(`Frame display failed: Unable to get 2D canvas context at time ${seekToMs}ms. This may indicate a browser compatibility issue or canvas corruption.`);
 			}
+			const frameWidth = frame.displayWidth;
+			const frameHeight = frame.displayHeight;
 			let resized = false;
-			if (frame?.codedWidth && frame?.codedHeight) {
-				if (this.canvasElement.width !== frame.codedWidth || this.canvasElement.height !== frame.codedHeight) {
+			if (frameWidth && frameHeight) {
+				if (frameWidth > this.canvasElement.width || frameHeight > this.canvasElement.height) {
+					const newWidth = Math.max(this.canvasElement.width, frameWidth);
+					const newHeight = Math.max(this.canvasElement.height, frameHeight);
 					log("trace: updating canvas dimensions", {
-						width: frame.codedWidth,
-						height: frame.codedHeight
+						width: newWidth,
+						height: newHeight
 					});
-					this.canvasElement.width = frame.codedWidth;
-					this.canvasElement.height = frame.codedHeight;
+					this.canvasElement.width = newWidth;
+					this.canvasElement.height = newHeight;
 					resized = true;
 					const t3 = performance.now();
 					span.setAttribute("resizeMs", Math.round((t3 - t2) * 100) / 100);
@@ -462,78 +531,41 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 		return (this.rootTimegroup?.currentTimeMs || 0) >= renderStartTime;
 	}
 	/**
-	* Legacy getter for fragment index task
-	* Still used by EFCaptions - maps to frameTask
-	*/
-	get fragmentIndexTask() {
-		return this.frameTask;
-	}
-	#pendingFrameReadyTime = null;
-	#pendingFrameReadyPromise = null;
-	/**
-	* Helper method for tests: wait for the current frame to be ready
-	* This encapsulates the complexity of ensuring the video has updated
-	* and its frameTask has completed.
+	* Get a decoded VideoFrame at a specific source media timestamp.
+	* Returns a standard WebCodecs VideoFrame — caller MUST call .close() when done.
 	*
-	* @returns Promise that resolves when the frame is ready
-	*/
-	async waitForFrameReady() {
-		const currentTime = this.currentSourceTimeMs;
-		if (this.desiredSeekTimeMs !== currentTime) this.desiredSeekTimeMs = currentTime;
-		if (this.#pendingFrameReadyTime === currentTime && this.#pendingFrameReadyPromise) return this.#pendingFrameReadyPromise;
-		this.#pendingFrameReadyTime = currentTime;
-		this.#pendingFrameReadyPromise = this.#doWaitForFrameReady(currentTime);
-		try {
-			await this.#pendingFrameReadyPromise;
-		} finally {
-			if (this.#pendingFrameReadyTime === currentTime) {
-				this.#pendingFrameReadyTime = null;
-				this.#pendingFrameReadyPromise = null;
-			}
-		}
-	}
-	async #doWaitForFrameReady(_targetTimeMs) {
-		await this.updateComplete;
-		try {
-			await this.frameTask.run();
-		} catch (error) {
-			if (error instanceof DOMException && error.name === "AbortError" || error instanceof Error && (error.name === "AbortError" || error.message?.includes("signal is aborted") || error.message?.includes("The user aborted a request"))) return;
-			throw error;
-		}
-	}
-	/**
-	* Capture a video frame directly at a source media timestamp.
-	* Bypasses the frameTask system - designed for export/rendering.
-	* Does NOT paint to the element's internal canvas.
-	* 
-	* Uses the same routing logic as unified video system:
+	* Uses the same routing logic as the unified video system:
 	* - "auto": main track for production rendering, follows normal routing otherwise
 	* - "scrub": force low-res scrub track (for thumbnails)
 	* - "main": force full-quality main track
-	* 
+	*
 	* @param sourceTimeMs - Timestamp in source media coordinates (not timeline)
-	* @param options - Capture options including quality and abort signal
-	* @returns Frame data for serialization
+	* @param options - Quality and abort signal
+	* @returns VideoFrame that the caller must close()
 	* @public
 	*/
-	async captureFrameAtSourceTime(sourceTimeMs, options = {}) {
-		const { quality = "auto", signal } = options;
-		signal?.throwIfAborted();
+	async getVideoFrameAtSourceTime(sourceTimeMs, options = {}) {
+		const { quality = "auto", signal: providedSignal } = options;
+		const signal = providedSignal ?? new AbortController().signal;
+		signal.throwIfAborted();
 		const mediaEngine = await this.getMediaEngine(signal);
-		signal?.throwIfAborted();
+		signal.throwIfAborted();
 		if (!mediaEngine) throw new Error("No media engine available for frame capture");
 		const useMainTrack = quality === "main" || quality === "auto" && this.isInProductionRenderingMode();
 		let videoSample;
 		const { BufferedSeekingInput } = await import("./EFMedia/BufferedSeekingInput.js");
-		signal?.throwIfAborted();
+		signal.throwIfAborted();
 		if (useMainTrack) {
 			const videoRendition = mediaEngine.getVideoRendition?.() || mediaEngine.videoRendition;
 			if (!videoRendition) throw new Error("No video rendition available");
 			const segmentId = mediaEngine.computeSegmentId(sourceTimeMs, videoRendition);
 			if (segmentId === void 0) throw new Error(`Cannot compute segment ID for time ${sourceTimeMs}ms`);
 			const seekingInput = await mainVideoInputCache.getOrCreateInput(mediaEngine.src, segmentId, videoRendition.id, async () => {
-				const fetchSignal = signal ?? new AbortController().signal;
-				const [initSegment, mediaSegment] = await Promise.all([mediaEngine.fetchInitSegment(videoRendition, fetchSignal), mediaEngine.fetchMediaSegment(segmentId, videoRendition, fetchSignal)]);
+				const initP = mediaEngine.fetchInitSegment(videoRendition, signal);
+				const mediaP = mediaEngine.fetchMediaSegment(segmentId, videoRendition, signal);
+				initP.catch(() => {});
+				mediaP.catch(() => {});
+				const [initSegment, mediaSegment] = await Promise.all([initP, mediaP]);
 				if (!initSegment || !mediaSegment) return;
 				return new BufferedSeekingInput(await new Blob([initSegment, mediaSegment]).arrayBuffer(), {
 					videoBufferSize: EFMedia.VIDEO_SAMPLE_BUFFER_SIZE,
@@ -541,16 +573,16 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 					startTimeOffsetMs: videoRendition.startTimeOffsetMs
 				});
 			});
-			signal?.throwIfAborted();
+			signal.throwIfAborted();
 			if (!seekingInput) throw new Error(`Failed to fetch video segments for time ${sourceTimeMs}ms`);
 			const videoTrack = await seekingInput.getFirstVideoTrack();
-			signal?.throwIfAborted();
+			signal.throwIfAborted();
 			if (!videoTrack) throw new Error("No video track found in segment");
 			videoSample = await seekingInput.seek(videoTrack.id, sourceTimeMs);
-			signal?.throwIfAborted();
+			signal.throwIfAborted();
 		} else {
 			const scrubRendition = mediaEngine.getScrubVideoRendition?.();
-			if (!scrubRendition) return this.captureFrameAtSourceTime(sourceTimeMs, {
+			if (!scrubRendition) return this.getVideoFrameAtSourceTime(sourceTimeMs, {
 				quality: "main",
 				signal
 			});
@@ -561,8 +593,11 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			const segmentId = mediaEngine.computeSegmentId(sourceTimeMs, scrubRenditionWithSrc);
 			if (segmentId === void 0) throw new Error(`Cannot compute scrub segment ID for time ${sourceTimeMs}ms`);
 			const seekingInput = await scrubInputCache.getOrCreateInput(mediaEngine.src, segmentId, async () => {
-				const scrubFetchSignal = signal ?? new AbortController().signal;
-				const [initSegment, mediaSegment] = await Promise.all([mediaEngine.fetchInitSegment(scrubRenditionWithSrc, scrubFetchSignal), mediaEngine.fetchMediaSegment(segmentId, scrubRenditionWithSrc, scrubFetchSignal)]);
+				const initP = mediaEngine.fetchInitSegment(scrubRenditionWithSrc, signal);
+				const mediaP = mediaEngine.fetchMediaSegment(segmentId, scrubRenditionWithSrc, signal);
+				initP.catch(() => {});
+				mediaP.catch(() => {});
+				const [initSegment, mediaSegment] = await Promise.all([initP, mediaP]);
 				if (!initSegment || !mediaSegment) return;
 				return new BufferedSeekingInput(await new Blob([initSegment, mediaSegment]).arrayBuffer(), {
 					videoBufferSize: EFMedia.VIDEO_SAMPLE_BUFFER_SIZE,
@@ -570,41 +605,59 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 					startTimeOffsetMs: scrubRendition.startTimeOffsetMs
 				});
 			});
-			signal?.throwIfAborted();
-			if (!seekingInput) return this.captureFrameAtSourceTime(sourceTimeMs, {
+			signal.throwIfAborted();
+			if (!seekingInput) return this.getVideoFrameAtSourceTime(sourceTimeMs, {
 				quality: "main",
 				signal
 			});
 			const videoTrack = await seekingInput.getFirstVideoTrack();
-			signal?.throwIfAborted();
-			if (!videoTrack) return this.captureFrameAtSourceTime(sourceTimeMs, {
+			signal.throwIfAborted();
+			if (!videoTrack) return this.getVideoFrameAtSourceTime(sourceTimeMs, {
 				quality: "main",
 				signal
 			});
 			videoSample = await seekingInput.seek(videoTrack.id, sourceTimeMs);
-			signal?.throwIfAborted();
+			signal.throwIfAborted();
 		}
 		if (!videoSample) throw new Error(`No video sample found at ${sourceTimeMs}ms`);
-		const videoFrame = videoSample.toVideoFrame();
+		return videoSample.toVideoFrame();
+	}
+	/**
+	* Capture a video frame directly at a source media timestamp.
+	* Designed for export/rendering.
+	* Does NOT paint to the element's internal canvas.
+	*
+	* Uses the same routing logic as unified video system:
+	* - "auto": main track for production rendering, follows normal routing otherwise
+	* - "scrub": force low-res scrub track (for thumbnails)
+	* - "main": force full-quality main track
+	*
+	* @param sourceTimeMs - Timestamp in source media coordinates (not timeline)
+	* @param options - Capture options including quality and abort signal
+	* @returns Frame data for serialization
+	* @public
+	*/
+	async captureFrameAtSourceTime(sourceTimeMs, options = {}) {
+		const videoFrame = await this.getVideoFrameAtSourceTime(sourceTimeMs, options);
 		try {
-			signal?.throwIfAborted();
+			options.signal?.throwIfAborted();
 			const canvas = new OffscreenCanvas(videoFrame.codedWidth, videoFrame.codedHeight);
 			const ctx = canvas.getContext("2d");
 			if (!ctx) throw new Error("Failed to get 2d context from OffscreenCanvas");
 			ctx.drawImage(videoFrame, 0, 0);
-			signal?.throwIfAborted();
+			options.signal?.throwIfAborted();
 			const blob = await canvas.convertToBlob({
 				type: "image/jpeg",
 				quality: .92
 			});
-			signal?.throwIfAborted();
+			options.signal?.throwIfAborted();
 			const dataUrl = await new Promise((resolve, reject) => {
 				const reader = new FileReader();
 				reader.onload = () => resolve(reader.result);
 				reader.onerror = reject;
 				reader.readAsDataURL(blob);
 			});
-			signal?.throwIfAborted();
+			options.signal?.throwIfAborted();
 			return {
 				dataUrl,
 				width: videoFrame.codedWidth,
@@ -621,11 +674,12 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	*
 	* @param timestamps - Array of timestamps (in ms) that will be captured
 	* @param onProgress - Optional callback for loading progress
+	* @param signal - Optional AbortSignal for cancellation
 	* @returns Promise that resolves when all segments are cached
 	* @public
 	*/
-	async prefetchScrubSegments(timestamps, onProgress) {
-		const mediaEngine = await this.getMediaEngine();
+	async prefetchScrubSegments(timestamps, onProgress, signal) {
+		const mediaEngine = await this.getMediaEngine(signal);
 		if (!mediaEngine) {
 			log("prefetchScrubSegments: no media engine available");
 			return;
@@ -666,8 +720,9 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			bubbles: true,
 			composed: true
 		}));
+		const fetchSignal = signal ?? new AbortController().signal;
 		try {
-			await mediaEngine.fetchMediaSegment(firstSegmentId, scrubRenditionWithSrc);
+			await mediaEngine.fetchMediaSegment(firstSegmentId, scrubRenditionWithSrc, fetchSignal);
 			log(`prefetchScrubSegments: scrub track loaded`);
 		} catch (error) {
 			log(`prefetchScrubSegments: failed to load scrub track`, error);
@@ -687,57 +742,85 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 		log(`prefetchScrubSegments: complete`);
 	}
 	/**
-	* Pre-fetch main video segments for given timestamps.
-	* This ensures segments are cached for fast seeking during video export.
-	*
-	* @param timestamps - Array of timestamps (in ms) that will be captured
-	* @param onProgress - Optional callback for loading progress
-	* @returns Promise that resolves when all segments are cached
-	* @public
+	* Maybe schedule quality upgrade tasks for this element.
+	* Called when returning a scrub sample - checks if state has changed and submits tasks.
 	*/
-	async prefetchMainVideoSegments(timestamps, onProgress) {
-		const mediaEngine = await this.getMediaEngine();
-		if (!mediaEngine) {
-			log("prefetchMainVideoSegments: no media engine available");
-			return;
-		}
-		const videoRendition = mediaEngine.getVideoRendition?.() || mediaEngine.videoRendition;
-		if (!videoRendition) {
-			log("prefetchMainVideoSegments: no video rendition available");
-			return;
-		}
-		const segmentIds = /* @__PURE__ */ new Set();
-		for (const ts of timestamps) {
-			const segmentId = mediaEngine.computeSegmentId(ts, videoRendition);
-			if (segmentId !== void 0) segmentIds.add(segmentId);
-		}
-		if (segmentIds.size === 0) {
-			log("prefetchMainVideoSegments: no segments to prefetch");
-			return;
-		}
-		const uncachedSegmentIds = [];
-		for (const segmentId of segmentIds) if (!mediaEngine.isSegmentCached(segmentId, videoRendition)) uncachedSegmentIds.push(segmentId);
-		if (uncachedSegmentIds.length === 0) {
-			log("prefetchMainVideoSegments: all segments already cached");
-			onProgress?.(segmentIds.size, segmentIds.size);
-			return;
-		}
-		log(`prefetchMainVideoSegments: fetching ${uncachedSegmentIds.length} segments...`);
-		try {
-			await mediaEngine.fetchInitSegment(videoRendition);
-		} catch (error) {
-			log("prefetchMainVideoSegments: failed to fetch init segment", error);
-			return;
-		}
-		let loaded = segmentIds.size - uncachedSegmentIds.length;
-		for (const segmentId of uncachedSegmentIds) try {
-			await mediaEngine.fetchMediaSegment(segmentId, videoRendition);
-			loaded++;
-			onProgress?.(loaded, segmentIds.size);
-		} catch (error) {
-			log(`prefetchMainVideoSegments: failed to fetch segment ${segmentId}`, error);
+	#maybeScheduleQualityUpgrade(mediaEngine, sourceTimeMs) {
+		const mainRendition = mediaEngine.videoRendition;
+		if (!mainRendition) return;
+		const segmentId = mediaEngine.computeSegmentId(sourceTimeMs, mainRendition);
+		if (segmentId === void 0) return;
+		const startTimeMs = this.startTimeMs;
+		if (!(this.#upgradeState === null || this.#upgradeState.segmentId !== segmentId || this.#upgradeState.startTimeMs !== startTimeMs)) return;
+		const segments = this.#computeLookaheadSegments(mediaEngine, sourceTimeMs, mainRendition);
+		if (segments.length === 0) return;
+		const tasks = segments.map((seg) => ({
+			key: `${this.id}:${seg.segmentId}:${mainRendition.id}`,
+			fetch: async (signal) => {
+				await mediaEngine.fetchInitSegment(mainRendition, signal);
+				await mediaEngine.fetchMediaSegment(seg.segmentId, mainRendition, signal);
+			},
+			deadlineMs: seg.deadlineMs,
+			owner: this.id
+		}));
+		const scheduler = this.rootTimegroup?.qualityUpgradeScheduler;
+		if (scheduler) scheduler.replaceForOwner(this.id, tasks);
+		else this.#fetchStandalone(tasks);
+		this.#upgradeState = {
+			sourceTimeMs,
+			segmentId,
+			startTimeMs,
+			submittedKeys: new Set(tasks.map((t) => t.key))
+		};
+	}
+	/**
+	* Compute lookahead segments with deadlines in timeline space.
+	*/
+	#computeLookaheadSegments(mediaEngine, currentSourceTimeMs, rendition, maxLookahead = 5) {
+		const results = [];
+		const playheadMs = this.rootTimegroup?.currentTimeMs ?? 0;
+		const seen = /* @__PURE__ */ new Set();
+		let probeTimeMs = currentSourceTimeMs;
+		while (seen.size < maxLookahead) {
+			const segmentId = mediaEngine.computeSegmentId(probeTimeMs, rendition);
+			if (segmentId === void 0) break;
+			if (seen.has(segmentId)) break;
+			seen.add(segmentId);
+			if (!mediaEngine.isSegmentCached(segmentId, rendition)) {
+				const deadlineMs = playheadMs + (probeTimeMs - currentSourceTimeMs);
+				results.push({
+					segmentId,
+					deadlineMs
+				});
+			}
+			const thisDuration = rendition.segmentDurationsMs?.[segmentId - 1] ?? rendition.segmentDurationMs ?? 2e3;
+			probeTimeMs += thisDuration;
 		}
-		log(`prefetchMainVideoSegments: complete (${loaded}/${segmentIds.size} segments)`);
+		return results;
+	}
+	/**
+	* Standalone mode: fetch tasks sequentially without scheduler.
+	*/
+	#fetchStandalone(tasks) {
+		this.#standaloneUpgradeController?.abort();
+		this.#standaloneUpgradeController = new AbortController();
+		const signal = this.#standaloneUpgradeController.signal;
+		(async () => {
+			for (const task of tasks) {
+				if (signal.aborted) break;
+				try {
+					await task.fetch(signal);
+				} catch {}
+			}
+			if (!signal.aborted) this.playbackController?.runThrottledFrameTask();
+		})().catch(() => {});
+	}
+	/**
+	* Invalidate upgrade state and optionally cancel queued tasks.
+	*/
+	#invalidateUpgradeState(reason) {
+		if (reason === "src-change" || reason === "disconnect") this.rootTimegroup?.qualityUpgradeScheduler?.cancelForOwner(this.id);
+		this.#upgradeState = null;
 	}
 	/**
 	* Clean up resources when component is disconnected
@@ -745,6 +828,9 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 	disconnectedCallback() {
 		super.disconnectedCallback();
 		this.#delayedLoadingState.clearAllLoading();
+		this.#invalidateUpgradeState("disconnect");
+		this.#standaloneUpgradeController?.abort();
+		this.#standaloneUpgradeController = null;
 	}
 	didBecomeRoot() {
 		super.didBecomeRoot();
@@ -766,19 +852,20 @@ let EFVideo = class EFVideo$1 extends TWMixin(EFMedia) {
 			height: canvas.height
 		};
 	}
+	/**
+	* Render this video element to an MP4 using the direct video-to-video fast path.
+	* Bypasses DOM serialization — decodes frames directly and re-encodes to MP4.
+	* Respects trim, CSS filter, and opacity.
+	*
+	* @param options - Rendering options (fps, codec, bitrate, etc.)
+	* @returns Promise resolving to video buffer (if returnBuffer), or undefined
+	* @public
+	*/
+	async renderToVideo(options) {
+		const { renderVideoToVideo } = await import("../preview/renderVideoToVideo.js");
+		return renderVideoToVideo(this, options);
+	}
 };
-__decorate([property({
-	type: Number,
-	attribute: "video-buffer-duration"
-})], EFVideo.prototype, "videoBufferDurationMs", void 0);
-__decorate([property({
-	type: Number,
-	attribute: "max-video-buffer-fetches"
-})], EFVideo.prototype, "maxVideoBufferFetches", void 0);
-__decorate([property({
-	type: Boolean,
-	attribute: "enable-video-buffering"
-})], EFVideo.prototype, "enableVideoBuffering", void 0);
 __decorate([state()], EFVideo.prototype, "loadingState", void 0);
 EFVideo = __decorate([customElement("ef-video")], EFVideo);