@editframe/elements 0.30.2-beta.0 → 0.31.0-beta.1

package/dist/elements/EFTimegroup.js

@@ -1,8 +1,9 @@
 import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
+import { quantizeToFrameTimeS } from "../utils/frameTime.js";
 import { EF_RENDERING } from "../EF_RENDERING.js";
 import { parseTimeToMs } from "./parseTimeToMs.js";
 import { __decorate } from "../_virtual/_@oxc-project_runtime@0.94.0/helpers/decorate.js";
-import { EFTemporal, deepGetElementsWithFrameTasks, flushStartTimeMsCache, resetTemporalCache, shallowGetTemporalElements, timegroupContext } from "./EFTemporal.js";
+import { EFTemporal, deepGetElementsWithFrameTasks, flushStartTimeMsCache, registerIsTimegroupCalculatingDuration, resetTemporalCache, shallowGetTemporalElements, timegroupContext } from "./EFTemporal.js";
 import { efContext } from "../gui/efContext.js";
 import { isContextMixin } from "../gui/ContextMixin.js";
 import { TWMixin } from "../gui/TWMixin2.js";
@@ -12,6 +13,16 @@ import { EFTargetable } from "./TargetController.js";
 import { deepGetMediaElements } from "./EFMedia.js";
 import { TimegroupController } from "./TimegroupController.js";
 import { evaluateAnimationVisibilityState, updateAnimations } from "./updateAnimations.js";
+import { getContainerInfoFromElement } from "./ContainerInfo.js";
+import { getPositionInfoFromElement } from "./ElementPositionInfo.js";
+import { captureFromClone, captureTimegroupAtTime } from "../preview/renderTimegroupToCanvas.js";
+import { renderTimegroupToVideo } from "../preview/renderTimegroupToVideo.js";
+import "../canvas/EFCanvas.js";
+import "../gui/hierarchy/EFHierarchy.js";
+import "../gui/EFFilmstrip.js";
+import "../gui/EFFitScale.js";
+import "../gui/EFWorkbench.js";
+import "./EFPanZoom.js";
 import { provide } from "@lit/context";
 import { Task, TaskStatus } from "@lit/task";
 import debug from "debug";
@@ -21,15 +32,150 @@ import { customElement, property } from "lit/decorators.js";
 //#region src/elements/EFTimegroup.ts
 var _EFTimegroup;
 const log = debug("ef:elements:EFTimegroup");
-let sequenceDurationCache = /* @__PURE__ */ new WeakMap();
-const flushSequenceDurationCache = () => {
-	sequenceDurationCache = /* @__PURE__ */ new WeakMap();
+const INITIALIZER_ERROR_THRESHOLD_MS = 100;
+const INITIALIZER_WARN_THRESHOLD_MS = 10;
+let durationCache = /* @__PURE__ */ new WeakMap();
+const flushDurationCache = () => {
+	durationCache = /* @__PURE__ */ new WeakMap();
 };
+const flushSequenceDurationCache = flushDurationCache;
+const durationCalculationInProgress = /* @__PURE__ */ new WeakSet();
+const isTimegroupCalculatingDuration = (timegroup) => {
+	return timegroup !== void 0 && durationCalculationInProgress.has(timegroup);
+};
+registerIsTimegroupCalculatingDuration(isTimegroupCalculatingDuration);
+/**
+* Determines if a timegroup has its own duration based on its mode.
+* This is the semantic rule: which modes produce independent durations.
+*/
+function hasOwnDurationForMode(mode, hasExplicitDuration) {
+	return mode === "contain" || mode === "sequence" || mode === "fixed" && hasExplicitDuration;
+}
+/**
+* Determines if a child temporal element should participate in parent duration calculation.
+*
+* Semantic rule: Fit-mode children inherit from parent, so they don't contribute to parent's
+* duration calculation (to avoid circular dependencies). Children without own duration
+* also don't contribute.
+*/
+function shouldParticipateInDurationCalculation(child) {
+	if (child instanceof EFTimegroup && child.mode === "fit") return false;
+	if (!child.hasOwnDuration) return false;
+	return true;
+}
+/**
+* Evaluates duration for "fit" mode: inherits from parent.
+* Semantic rule: fit mode always matches parent duration, or 0 if no parent.
+*/
+function evaluateFitDuration(parentTimegroup) {
+	if (!parentTimegroup) return 0;
+	return parentTimegroup.durationMs;
+}
+/**
+* Evaluates duration for "sequence" mode: sum of children minus overlaps.
+* Semantic rule: sequence mode sums child durations, subtracting overlap between consecutive items.
+* Fit-mode children are excluded to avoid circular dependencies.
+*/
+function evaluateSequenceDuration(timegroup, childTemporals, overlapMs) {
+	const cachedDuration = durationCache.get(timegroup);
+	if (cachedDuration !== void 0) return cachedDuration;
+	let duration = 0;
+	let participatingIndex = 0;
+	childTemporals.forEach((child) => {
+		if (!shouldParticipateInDurationCalculation(child)) return;
+		if (child instanceof EFTimegroup && durationCalculationInProgress.has(child)) return;
+		if (child instanceof EFTimegroup) {
+			let ancestor = child.parentNode;
+			let shouldSkip = false;
+			while (ancestor) {
+				if (ancestor === timegroup) break;
+				if (ancestor instanceof EFTimegroup && durationCalculationInProgress.has(ancestor)) {
+					shouldSkip = true;
+					break;
+				}
+				ancestor = ancestor.parentNode;
+			}
+			if (shouldSkip) return;
+		}
+		if (participatingIndex > 0) duration -= overlapMs;
+		duration += child.durationMs;
+		participatingIndex++;
+	});
+	duration = Math.max(0, duration);
+	durationCache.set(timegroup, duration);
+	return duration;
+}
+/**
+* Evaluates duration for "contain" mode: maximum of children.
+* Semantic rule: contain mode takes the maximum child duration.
+* Fit-mode children and children without own duration are excluded.
+*/
+function evaluateContainDuration(timegroup, childTemporals) {
+	const cachedDuration = durationCache.get(timegroup);
+	if (cachedDuration !== void 0) return cachedDuration;
+	let maxDuration = 0;
+	for (const child of childTemporals) {
+		if (!shouldParticipateInDurationCalculation(child)) continue;
+		if (child instanceof EFTimegroup && durationCalculationInProgress.has(child)) continue;
+		if (child instanceof EFTimegroup) {
+			let ancestor = child.parentNode;
+			let shouldSkip = false;
+			while (ancestor) {
+				if (ancestor === timegroup) break;
+				if (ancestor instanceof EFTimegroup && durationCalculationInProgress.has(ancestor)) {
+					shouldSkip = true;
+					break;
+				}
+				ancestor = ancestor.parentNode;
+			}
+			if (shouldSkip) continue;
+		}
+		maxDuration = Math.max(maxDuration, child.durationMs);
+	}
+	const duration = Math.max(0, maxDuration);
+	durationCache.set(timegroup, duration);
+	return duration;
+}
+/**
+* Evaluates duration based on timegroup mode.
+* This is the semantic evaluation function - it determines what duration should be.
+*
+* Note: Fixed mode is handled inline in the getter because it needs to call super.durationMs
+* which requires the class context. The other modes are extracted for clarity.
+*/
+function evaluateDurationForMode(timegroup, mode, childTemporals) {
+	switch (mode) {
+		case "fit": return evaluateFitDuration(timegroup.parentTimegroup);
+		case "sequence":
+			durationCalculationInProgress.add(timegroup);
+			try {
+				return evaluateSequenceDuration(timegroup, childTemporals, timegroup.overlapMs);
+			} finally {
+				durationCalculationInProgress.delete(timegroup);
+			}
+		case "contain":
+			durationCalculationInProgress.add(timegroup);
+			try {
+				return evaluateContainDuration(timegroup, childTemporals);
+			} finally {
+				durationCalculationInProgress.delete(timegroup);
+			}
+		default: throw new Error(`Invalid time mode: ${mode}`);
+	}
+}
 const shallowGetTimegroups = (element, groups = []) => {
 	for (const child of Array.from(element.children)) if (child instanceof EFTimegroup) groups.push(child);
 	else shallowGetTimegroups(child, groups);
 	return groups;
 };
+/**
+* Evaluates the target time for a seek operation.
+* Applies quantization and clamping to determine the valid seek target.
+*/
+function evaluateSeekTarget(requestedTime, durationMs, fps) {
+	const quantizedTime = quantizeToFrameTimeS(requestedTime, fps);
+	return Math.max(0, Math.min(quantizedTime, durationMs / 1e3));
+}
 let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(LitElement))) {
 	static {
 		_EFTimegroup = this;
@@ -41,47 +187,83 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		this.mode = "contain";
 		this.overlapMs = 0;
 		this.fps = 30;
+		this.autoInit = false;
+		this.workbench = false;
 		this.fit = "none";
-		this.mediaDurationsPromise = void 0;
 		this.frameTask = new Task(this, {
-			autoRun: false,
+			autoRun: EF_INTERACTIVE,
 			args: () => [this.ownCurrentTimeMs, this.currentTimeMs],
-			task: async ([ownCurrentTimeMs, currentTimeMs]) => {
-				if (this.isRootTimegroup) await withSpan("timegroup.frameTask", {
+			onError: (error) => {
+				this.frameTask.taskComplete.catch(() => {});
+				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;
+				console.error("EFTimegroup frameTask error", error);
+			},
+			task: async ([ownCurrentTimeMs, currentTimeMs], { signal }) => {
+				const now = Date.now();
+				if (now - this.#timegroupFrameTaskLastReset > _EFTimegroup.TIMEGROUP_FRAME_TASK_RESET_MS) {
+					this.#timegroupFrameTaskCount = 0;
+					this.#timegroupFrameTaskLastReset = now;
+				}
+				this.#timegroupFrameTaskCount++;
+				if (this.#timegroupFrameTaskCount > _EFTimegroup.TIMEGROUP_FRAME_TASK_THRESHOLD) return;
+				signal?.throwIfAborted();
+				if (this.isRootTimegroup) return withSpan("timegroup.frameTask", {
 					timegroupId: this.id || "unknown",
 					ownCurrentTimeMs,
 					currentTimeMs
 				}, void 0, async () => {
-					await this.waitForFrameTasks();
+					await this.waitForFrameTasks(signal);
+					signal?.throwIfAborted();
 					await this.#executeCustomFrameTasks();
+					signal?.throwIfAborted();
 					updateAnimations(this);
 				});
-				else await this.#executeCustomFrameTasks();
+				else return this.#executeCustomFrameTasks();
 			}
 		});
 		this.seekTask = new Task(this, {
 			autoRun: false,
 			args: () => [this.#pendingSeekTime ?? this.#currentTime],
 			onComplete: () => {},
-			task: async ([targetTime]) => {
-				if (this.playbackController) {
-					await this.playbackController.seekTask.taskComplete;
+			task: async ([targetTime], { signal }) => {
+				signal?.throwIfAborted();
+				if (this.playbackController) return this.playbackController.seekTask.taskComplete.then(() => {
+					signal?.throwIfAborted();
 					return this.currentTime;
-				}
+				});
 				if (!this.isRootTimegroup) return;
 				return withSpan("timegroup.seekTask", {
 					timegroupId: this.id || "unknown",
 					targetTime: targetTime ?? 0,
 					durationMs: this.durationMs
 				}, void 0, async (span) => {
-					await this.waitForMediaDurations();
-					const newTime = Math.max(0, Math.min(targetTime ?? 0, this.durationMs / 1e3));
+					try {
+						await Promise.race([this.waitForMediaDurations(signal), new Promise((_, reject) => {
+							if (signal?.aborted) {
+								reject(new DOMException("Aborted", "AbortError"));
+								return;
+							}
+							const timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error("waitForMediaDurations timeout")), 1e4);
+							signal?.addEventListener("abort", () => {
+								clearTimeout(timeoutId);
+								reject(new DOMException("Aborted", "AbortError"));
+							});
+						})]);
+					} catch (error) {
+						if (error instanceof DOMException && error.name === "AbortError") throw error;
+					}
+					signal?.throwIfAborted();
+					const newTime = evaluateSeekTarget(targetTime ?? 0, this.durationMs, this.effectiveFps);
 					if (isTracingEnabled()) span.setAttribute("newTime", newTime);
 					this.#currentTime = newTime;
 					this.requestUpdate("currentTime");
-					await this.runThrottledFrameTask();
-					this.saveTimeToLocalStorage(this.#currentTime);
+					await this.updateComplete;
+					signal?.throwIfAborted();
+					await this.#runThrottledFrameTask();
+					signal?.throwIfAborted();
+					if (!this.#restoringFromLocalStorage) this.saveTimeToLocalStorage(this.#currentTime);
 					this.#seekInProgress = false;
+					if (this.#restoringFromLocalStorage) this.#restoringFromLocalStorage = false;
 					return newTime;
 				});
 			}
@@ -94,7 +276,9 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			"overlap",
 			"currenttime",
 			"fit",
-			"fps"
+			"fps",
+			"auto-init",
+			"workbench"
 		];
 	}
 	static {
@@ -118,59 +302,87 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	attributeChangedCallback(name, old, value) {
 		if (name === "mode" && value) this.mode = value;
 		if (name === "overlap" && value) this.overlapMs = parseTimeToMs(value);
+		if (name === "auto-init") this.autoInit = value !== null;
 		if (name === "fps" && value) this.fps = Number.parseFloat(value);
+		if (name === "workbench") this.workbench = value !== null;
 		super.attributeChangedCallback(name, old, value);
 	}
 	#resizeObserver;
+	/** Content epoch - increments when visual content changes (used by thumbnail cache) */
+	#contentEpoch = 0;
 	#currentTime = void 0;
+	#userTimeMs = 0;
 	#seekInProgress = false;
 	#pendingSeekTime;
 	#processingPendingSeek = false;
+	#restoringFromLocalStorage = false;
+	/** @internal */
+	isRestoringFromLocalStorage() {
+		return this.#restoringFromLocalStorage;
+	}
+	/** @internal - Used by PlaybackController to set restoration state */
+	setRestoringFromLocalStorage(value) {
+		this.#restoringFromLocalStorage = value;
+	}
 	#customFrameTasks = /* @__PURE__ */ new Set();
+	#onFrameCallback = null;
+	#onFrameCleanup = null;
+	#playbackListener = null;
 	/**
 	* Get the effective FPS for this timegroup.
 	* During rendering, uses the render options FPS if available.
 	* Otherwise uses the configured fps property.
+	* @public
 	*/
 	get effectiveFps() {
 		if (typeof window !== "undefined" && window.EF_FRAMEGEN?.renderOptions) return window.EF_FRAMEGEN.renderOptions.encoderOptions.video.framerate;
 		return this.fps;
 	}
 	/**
-	* Quantize a time value to the nearest frame boundary based on effectiveFps.
-	* @param timeSeconds - Time in seconds
-	* @returns Time quantized to frame boundaries in seconds
+	* Get the current content epoch (used by thumbnail cache).
+	* The epoch increments whenever visual content changes.
+	* @public
 	*/
-	quantizeToFrameTime(timeSeconds) {
-		const fps = this.effectiveFps;
-		if (!fps || fps <= 0) return timeSeconds;
-		const frameDurationS = 1 / fps;
-		return Math.round(timeSeconds / frameDurationS) * frameDurationS;
+	get contentEpoch() {
+		return this.#contentEpoch;
 	}
-	async runThrottledFrameTask() {
+	/**
+	* Increment content epoch (called when visual content changes).
+	* This invalidates cached thumbnails by changing their cache keys.
+	* @public
+	*/
+	incrementContentEpoch() {
+		this.#contentEpoch++;
+	}
+	async #runThrottledFrameTask() {
 		if (this.playbackController) return this.playbackController.runThrottledFrameTask();
 		await this.frameTask.run();
 	}
+	/** @public */
 	set currentTime(time) {
-		time = this.quantizeToFrameTime(time);
+		const seekTarget = evaluateSeekTarget(time, this.durationMs, this.effectiveFps);
 		if (this.playbackController) {
-			this.playbackController.currentTime = time;
+			this.playbackController.currentTime = seekTarget;
+			this.#userTimeMs = seekTarget * 1e3;
 			return;
 		}
-		time = Math.max(0, Math.min(this.durationMs / 1e3, time));
 		if (!this.isRootTimegroup) return;
-		if (Number.isNaN(time)) return;
-		if (time === this.#currentTime && !this.#processingPendingSeek) return;
-		if (this.#pendingSeekTime === time) return;
+		if (Number.isNaN(seekTarget)) return;
+		if (seekTarget === this.#currentTime && !this.#processingPendingSeek && !this.#restoringFromLocalStorage) return;
+		if (this.#pendingSeekTime === seekTarget) return;
+		if (this.#restoringFromLocalStorage && seekTarget !== this.#currentTime) {}
 		if (this.#seekInProgress) {
-			this.#pendingSeekTime = time;
-			this.#currentTime = time;
+			this.#pendingSeekTime = seekTarget;
+			this.#currentTime = seekTarget;
+			this.#userTimeMs = seekTarget * 1e3;
 			return;
 		}
-		this.#currentTime = time;
+		this.#currentTime = seekTarget;
+		this.#userTimeMs = seekTarget * 1e3;
 		this.#seekInProgress = true;
-		this.seekTask.run().finally(() => {
-			if (this.#pendingSeekTime !== void 0 && this.#pendingSeekTime !== time) {
+		this.seekTask.run().catch(() => {}).finally(() => {
+			this.#seekInProgress = false;
+			if (this.#pendingSeekTime !== void 0 && this.#pendingSeekTime !== seekTarget) {
 				const pendingTime = this.#pendingSeekTime;
 				this.#pendingSeekTime = void 0;
 				this.#processingPendingSeek = true;
@@ -182,49 +394,141 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			} else this.#pendingSeekTime = void 0;
 		});
 	}
+	/** @public */
 	get currentTime() {
 		if (this.playbackController) return this.playbackController.currentTime;
 		return this.#currentTime ?? 0;
 	}
+	/** @public */
 	set currentTimeMs(ms) {
 		this.currentTime = ms / 1e3;
 	}
+	/** @public */
 	get currentTimeMs() {
 		return this.currentTime * 1e3;
 	}
 	/**
+	* The time the user last requested via seek/scrub.
+	* Preview systems should use this instead of currentTimeMs to avoid
+	* seeing intermediate times during batch operations (thumbnails, export).
+	* @public
+	*/
+	get userTimeMs() {
+		return this.#userTimeMs;
+	}
+	/**
 	* Seek to a specific time and wait for all frames to be ready.
 	* This is the recommended way to seek in tests and programmatic control.
 	*
+	* Combines seeking (Purpose 3) with frame rendering (Purpose 4) to ensure
+	* all visible elements are ready after the seek completes.
+	* 
+	* Updates both the source time AND userTimeMs (what the preview displays).
+	*
 	* @param timeMs - Time in milliseconds to seek to
 	* @returns Promise that resolves when the seek is complete and all visible children are ready
+	* @public
 	*/
 	async seek(timeMs) {
+		this.#userTimeMs = timeMs;
 		this.currentTimeMs = timeMs;
 		await this.seekTask.taskComplete;
 		if (this.playbackController) this.saveTimeToLocalStorage(this.currentTime);
 		await this.frameTask.taskComplete;
-		const visibleElements = deepGetElementsWithFrameTasks(this).filter((element) => {
-			return evaluateAnimationVisibilityState(element).isVisible;
-		});
+		const visibleElements = this.#evaluateVisibleElementsForFrame();
 		await Promise.all(visibleElements.map(async (element) => {
 			if ("waitForFrameReady" in element && typeof element.waitForFrameReady === "function") await element.waitForFrameReady();
 			else await element.updateComplete;
 		}));
 	}
 	/**
+	* Optimized seek for render loops.
+	* Unlike `seek()`, this:
+	* - Skips waitForMediaDurations (already loaded at render setup)
+	* - Skips localStorage persistence
+	* - Consolidates awaits to reduce event loop yields
+	* 
+	* Still waits for all content to be ready (Lit updates, frame tasks, video frames).
+	* 
+	* @param timeMs - Time in milliseconds to seek to
+	* @internal
+	*/
+	async seekForRender(timeMs) {
+		const newTime = timeMs / 1e3;
+		this.#userTimeMs = timeMs;
+		this.#currentTime = newTime;
+		this.requestUpdate("currentTime");
+		await this.updateComplete;
+		const allLitElements = this.#getAllLitElementDescendants();
+		await Promise.all(allLitElements.map((el) => el.updateComplete));
+		const textElements = allLitElements.filter((el) => el.tagName === "EF-TEXT");
+		if (textElements.length > 0) await Promise.all(textElements.map((el) => {
+			if ("whenSegmentsReady" in el && typeof el.whenSegmentsReady === "function") return el.whenSegmentsReady();
+			return Promise.resolve();
+		}));
+		await new Promise((resolve) => requestAnimationFrame(resolve));
+		const visibleElements = this.#evaluateVisibleElementsForFrame();
+		await Promise.all([this.frameTask.run(), ...visibleElements.map((element) => {
+			if ("waitForFrameReady" in element && typeof element.waitForFrameReady === "function") return element.waitForFrameReady();
+			else return element.updateComplete;
+		})]);
+		this.offsetWidth;
+	}
+	/**
+	* Collects all LitElement descendants recursively.
+	* Used by seekForRender to ensure all reactive elements have updated.
+	*/
+	#getAllLitElementDescendants() {
+		const result = [];
+		const walk = (el) => {
+			for (const child of el.children) {
+				if (child instanceof LitElement) result.push(child);
+				walk(child);
+			}
+		};
+		walk(this);
+		return result;
+	}
+	/**
 	* Determines if this is a root timegroup (no parent timegroups)
+	* @public
 	*/
 	get isRootTimegroup() {
 		return !this.parentTimegroup;
 	}
 	/**
+	* Property-based frame task callback for React integration.
+	* When set, automatically registers the callback as a frame task.
+	* Setting a new value automatically cleans up the previous callback.
+	* Set to null or undefined to remove the callback.
+	*
+	* @example
+	* // React usage:
+	* <Timegroup onFrame={({ ownCurrentTimeMs, percentComplete }) => {
+	*   // Per-frame updates
+	* }} />
+	*
+	* @public
+	*/
+	get onFrame() {
+		return this.#onFrameCallback;
+	}
+	set onFrame(callback) {
+		if (this.#onFrameCleanup) {
+			this.#onFrameCleanup();
+			this.#onFrameCleanup = null;
+		}
+		this.#onFrameCallback = callback ?? null;
+		if (callback) this.#onFrameCleanup = this.addFrameTask(callback);
+	}
+	/**
 	* Register a custom frame task callback that will be executed during frame rendering.
 	* The callback receives timing information and can be async or sync.
 	* Multiple callbacks can be registered and will execute in parallel.
 	*
 	* @param callback - Function to execute on each frame
 	* @returns A cleanup function that removes the callback when called
+	* @public
 	*/
 	addFrameTask(callback) {
 		if (typeof callback !== "function") throw new Error("Frame task callback must be a function");
@@ -237,10 +541,12 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* Remove a previously registered custom frame task callback.
 	*
 	* @param callback - The callback function to remove
+	* @public
 	*/
 	removeFrameTask(callback) {
 		this.#customFrameTasks.delete(callback);
 	}
+	/** @internal */
 	saveTimeToLocalStorage(time) {
 		try {
 			if (this.id && this.isConnected && !Number.isNaN(time)) localStorage.setItem(this.storageKey, time.toString());
@@ -257,130 +563,397 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		flushStartTimeMsCache();
 		this.requestUpdate();
 	};
+	/** @internal */
 	loadTimeFromLocalStorage() {
 		if (this.id) try {
 			const storedValue = localStorage.getItem(this.storageKey);
 			if (storedValue === null) return;
-			return Number.parseFloat(storedValue);
+			const parsedValue = Number.parseFloat(storedValue);
+			if (Number.isNaN(parsedValue) || !Number.isFinite(parsedValue)) return;
+			return parsedValue;
 		} catch (error) {
 			log("Failed to load time from localStorage", error);
 		}
 	}
 	connectedCallback() {
 		super.connectedCallback();
-		if (!this.playbackController) this.waitForMediaDurations().then(async () => {
-			let didLoadFromStorage = false;
-			if (this.id) {
-				const maybeLoadedTime = this.loadTimeFromLocalStorage();
-				if (maybeLoadedTime !== void 0) {
-					this.currentTime = maybeLoadedTime;
-					didLoadFromStorage = true;
-				}
-			}
-			if (EF_INTERACTIVE && this.seekTask.status === TaskStatus.INITIAL) this.seekTask.run();
-			else if (didLoadFromStorage) await this.seekTask.run();
+		requestAnimationFrame(() => {
+			requestAnimationFrame(() => {
+				if (this.parentTimegroup) new TimegroupController(this.parentTimegroup, this);
+				if (this.shouldWrapWithWorkbench()) this.wrapWithWorkbench();
+			});
 		});
-		if (this.parentTimegroup) new TimegroupController(this.parentTimegroup, this);
-		if (this.shouldWrapWithWorkbench()) this.wrapWithWorkbench();
+	}
+	/**
+	* Called when this timegroup becomes a root (no parent timegroup).
+	* Sets up the playback listener after PlaybackController is created.
+	* @internal
+	*/
+	didBecomeRoot() {
+		super.didBecomeRoot();
+		this.#setupPlaybackListener();
+	}
+	/**
+	* Setup listener on playbackController to sync userTimeMs during playback.
+	*/
+	#setupPlaybackListener() {
+		if (this.#playbackListener || !this.playbackController) return;
+		this.#playbackListener = (event) => {
+			if (event.property === "currentTimeMs" && typeof event.value === "number") {
+				if (this.playing) this.#userTimeMs = event.value;
+			}
+		};
+		this.playbackController.addListener(this.#playbackListener);
+	}
+	/**
+	* Remove playback listener on disconnect.
+	*/
+	#removePlaybackListener() {
+		if (this.#playbackListener && this.playbackController) this.playbackController.removeListener(this.#playbackListener);
+		this.#playbackListener = null;
 	}
 	#previousDurationMs = 0;
 	updated(changedProperties) {
 		super.updated(changedProperties);
-		if (changedProperties.has("mode") || changedProperties.has("overlapMs")) sequenceDurationCache.delete(this);
+		if (changedProperties.has("mode") || changedProperties.has("overlapMs")) durationCache.delete(this);
 		if (this.#previousDurationMs !== this.durationMs) {
 			this.#previousDurationMs = this.durationMs;
-			this.runThrottledFrameTask();
+			this.#runThrottledFrameTask();
 		}
 	}
 	disconnectedCallback() {
 		super.disconnectedCallback();
 		this.#resizeObserver?.disconnect();
+		this.#removePlaybackListener();
+	}
+	/**
+	* Capture the timegroup at a specific timestamp as a canvas.
+	* Does NOT modify currentTimeMs - captures are rendered independently.
+	* 
+	* @param options - Capture options including timeMs, scale, contentReadyMode
+	* @returns Promise resolving to an HTMLCanvasElement with the captured frame
+	* @public
+	*/
+	async captureAtTime(options) {
+		return captureTimegroupAtTime(this, options);
+	}
+	/**
+	* Capture multiple timestamps as canvas thumbnails in a single batch.
+	* 
+	* CLONE-TIMELINE ARCHITECTURE:
+	* Creates a single render clone and reuses it across all captures.
+	* Prime-timeline is NEVER seeked - user can continue previewing/editing during capture.
+	* 
+	* @param timestamps - Array of timestamps (in milliseconds) to capture
+	* @param options - Capture options (scale, contentReadyMode, blockingTimeoutMs)
+	* @returns Promise resolving to array of HTMLCanvasElements
+	* @public
+	*/
+	async captureBatch(timestamps, options = {}) {
+		if (timestamps.length === 0) return [];
+		const { scale = .25, contentReadyMode = "immediate", blockingTimeoutMs = 5e3 } = options;
+		const batchStartTime = performance.now();
+		const cloneStartTime = performance.now();
+		const { clone: renderClone, container: renderContainer, cleanup: cleanupRenderClone } = await this.createRenderClone();
+		const cloneTime = performance.now() - cloneStartTime;
+		const prefetchStartTime = performance.now();
+		const videoElements = renderClone.querySelectorAll("ef-video");
+		if (videoElements.length > 0) await Promise.all(Array.from(videoElements).map((video) => video.prefetchScrubSegments(timestamps)));
+		const prefetchTime = performance.now() - prefetchStartTime;
+		const canvases = [];
+		let totalSeekTime = 0;
+		let totalCaptureTime = 0;
+		try {
+			for (let i = 0; i < timestamps.length; i++) {
+				const timeMs = timestamps[i];
+				const seekStart = performance.now();
+				await renderClone.seekForRender(timeMs);
+				totalSeekTime += performance.now() - seekStart;
+				const captureStart = performance.now();
+				const canvas = await captureFromClone(renderClone, renderContainer, {
+					scale,
+					contentReadyMode,
+					blockingTimeoutMs,
+					originalTimegroup: this
+				});
+				totalCaptureTime += performance.now() - captureStart;
+				canvases.push(canvas);
+			}
+			return canvases;
+		} finally {
+			const totalTime = performance.now() - batchStartTime;
+			console.log(`[captureBatch] ${timestamps.length} frames: clone=${cloneTime.toFixed(0)}ms, prefetch=${prefetchTime.toFixed(0)}ms, seek=${totalSeekTime.toFixed(0)}ms, capture=${totalCaptureTime.toFixed(0)}ms, total=${totalTime.toFixed(0)}ms`);
+			cleanupRenderClone();
+		}
+	}
+	/**
+	* Render the timegroup to an MP4 video file and trigger download.
+	* Captures each frame at the specified fps, encodes using WebCodecs via
+	* MediaBunny, and downloads the resulting video.
+	* 
+	* @param options - Rendering options (fps, codec, bitrate, filename, etc.)
+	* @returns Promise that resolves when video is downloaded
+	* @public
+	*/
+	async renderToVideo(options) {
+		return renderTimegroupToVideo(this, options);
+	}
+	/**
+	* Runs the initializer function with validation for synchronous execution and time budget.
+	* @throws Error if no initializer is set
+	* @throws Error if initializer returns a Promise (async not allowed)
+	* @throws Error if initializer takes more than INITIALIZER_ERROR_THRESHOLD_MS
+	* @internal
+	*/
+	#runInitializer(cloneEl) {
+		if (!this.initializer) return;
+		const startTime = performance.now();
+		const result = this.initializer(cloneEl);
+		const elapsed = performance.now() - startTime;
+		if (result !== void 0 && result !== null && typeof result.then === "function") throw new Error("Timeline initializer must be synchronous. Do not return a Promise from the initializer function.");
+		if (elapsed > INITIALIZER_ERROR_THRESHOLD_MS) throw new Error(`Timeline initializer took ${elapsed.toFixed(1)}ms, exceeding the ${INITIALIZER_ERROR_THRESHOLD_MS}ms limit. Initializers must be fast - move expensive work outside the initializer.`);
+		if (elapsed > INITIALIZER_WARN_THRESHOLD_MS) console.warn(`[ef-timegroup] Initializer took ${elapsed.toFixed(1)}ms, exceeding ${INITIALIZER_WARN_THRESHOLD_MS}ms. Consider optimizing for better render performance.`);
 	}
+	/**
+	* Copy captionsData property from original to clone.
+	* cloneNode() only copies attributes, not JavaScript properties.
+	* captionsData is often set via JS (e.g., captionsEl.captionsData = {...}),
+	* so we must manually copy it to the cloned elements.
+	* @internal
+	*/
+	#copyCaptionsData(original, clone) {
+		const originalCaptions = original.querySelectorAll("ef-captions");
+		const cloneCaptions = clone.querySelectorAll("ef-captions");
+		for (let i = 0; i < originalCaptions.length && i < cloneCaptions.length; i++) {
+			const origCap = originalCaptions[i];
+			const cloneCap = cloneCaptions[i];
+			if (origCap.captionsData) cloneCap.captionsData = origCap.captionsData;
+		}
+	}
+	/**
+	* Copy ef-text _textContent property from original to cloned elements.
+	* This MUST be called BEFORE elements upgrade (before updateComplete)
+	* because splitText() runs in connectedCallback and will clear segments
+	* if _textContent is null/empty.
+	* @internal
+	*/
+	#copyTextContent(original, clone) {
+		const originalTexts = original.querySelectorAll("ef-text");
+		const cloneTexts = clone.querySelectorAll("ef-text");
+		for (let i = 0; i < originalTexts.length && i < cloneTexts.length; i++) {
+			const origText = originalTexts[i];
+			const cloneText = cloneTexts[i];
+			if (origText._textContent !== void 0) cloneText._textContent = origText._textContent;
+			if (origText._templateElement !== void 0) cloneText._templateElement = origText._templateElement;
+		}
+	}
+	/**
+	* Copy ef-text-segment properties from original to cloned elements.
+	* segmentText and other properties are set via JS, not attributes,
+	* so we must manually copy them to the cloned elements.
+	* @internal
+	*/
+	#copyTextSegmentData(original, clone) {
+		const originalSegments = original.querySelectorAll("ef-text-segment");
+		const cloneSegments = clone.querySelectorAll("ef-text-segment");
+		for (let i = 0; i < originalSegments.length && i < cloneSegments.length; i++) {
+			const origSeg = originalSegments[i];
+			const cloneSeg = cloneSegments[i];
+			if (origSeg.segmentText !== void 0) cloneSeg.segmentText = origSeg.segmentText;
+			if (origSeg.segmentIndex !== void 0) cloneSeg.segmentIndex = origSeg.segmentIndex;
+			if (origSeg.staggerOffsetMs !== void 0) cloneSeg.staggerOffsetMs = origSeg.staggerOffsetMs;
+			if (origSeg.segmentStartMs !== void 0) cloneSeg.segmentStartMs = origSeg.segmentStartMs;
+			if (origSeg.segmentEndMs !== void 0) cloneSeg.segmentEndMs = origSeg.segmentEndMs;
+		}
+	}
+	/**
+	* Wait for all ef-captions elements to have their data loaded.
+	* This is needed because EFCaptions is not an EFMedia, so waitForMediaDurations doesn't cover it.
+	* Used by createRenderClone to ensure captions are ready before rendering.
+	* @internal
+	*/
+	async #waitForCaptionsData(root) {
+		const captionsElements = root.querySelectorAll("ef-captions");
+		if (captionsElements.length === 0) return;
+		const waitPromises = [];
+		for (const el of captionsElements) {
+			const task = el.unifiedCaptionsDataTask;
+			if (!task) continue;
+			if (task.status === TaskStatus.COMPLETE || task.status === TaskStatus.ERROR) continue;
+			if (task.status === TaskStatus.INITIAL) task.run().catch(() => {});
+			if (task.taskComplete) waitPromises.push(task.taskComplete);
+		}
+		if (waitPromises.length > 0) await Promise.all(waitPromises);
+	}
+	/**
+	* Create an independent clone of this timegroup for rendering.
+	* The clone is a fully functional ef-timegroup with its own animations
+	* and time state, isolated from the original (Prime-timeline).
+	* 
+	* OPTIONAL: An initializer can be set via `timegroup.initializer = (tg) => { ... }`
+	* to re-run JavaScript setup (frame callbacks, React components) on each clone.
+	* 
+	* This enables:
+	* - Rendering without affecting user's preview position
+	* - Concurrent renders with different clones
+	* - Re-running JavaScript setup on each clone (if initializer is provided)
+	* 
+	* @returns Promise resolving to clone, container, and cleanup function
+	* @throws Error if initializer is async or takes too long
+	* @public
+	*/
+	async createRenderClone() {
+		const container = document.createElement("div");
+		container.className = "ef-render-clone-container";
+		container.style.cssText = `
+      position: fixed;
+      left: -9999px;
+      top: 0;
+      width: ${this.offsetWidth || 1920}px;
+      height: ${this.offsetHeight || 1080}px;
+      pointer-events: none;
+      overflow: hidden;
+    `;
+		const cloneEl = this.cloneNode(true);
+		cloneEl.removeAttribute("id");
+		this.#copyCaptionsData(this, cloneEl);
+		this.#copyTextContent(this, cloneEl);
+		const originalConfig = this.closest("ef-configuration");
+		if (originalConfig) {
+			const configClone = originalConfig.cloneNode(false);
+			configClone.appendChild(cloneEl);
+			container.appendChild(configClone);
+		} else container.appendChild(cloneEl);
+		document.body.appendChild(container);
+		await cloneEl.updateComplete;
+		this.#copyTextSegmentData(this, cloneEl);
+		this.#runInitializer(cloneEl);
+		let actualClone = container.querySelector("ef-timegroup");
+		if (!actualClone) throw new Error("No ef-timegroup found after initializer. Ensure your initializer renders a Timegroup (React) or does not remove the cloned element (vanilla JS).");
+		await customElements.whenDefined("ef-timegroup");
+		customElements.upgrade(container);
+		actualClone = container.querySelector("ef-timegroup");
+		if (!actualClone) throw new Error("ef-timegroup element lost after upgrade");
+		await actualClone.updateComplete;
+		const setupParentChildRelationships = (parent, root) => {
+			for (const child of parent.children) if (child.tagName === "EF-TIMEGROUP") {
+				const childTG = child;
+				childTG.parentTimegroup = parent;
+				childTG.rootTimegroup = root;
+				childTG.lockRootTimegroup();
+				setupParentChildRelationships(childTG, root);
+			} else if ("parentTimegroup" in child && "rootTimegroup" in child) {
+				const temporal = child;
+				temporal.parentTimegroup = parent;
+				temporal.rootTimegroup = root;
+				if ("lockRootTimegroup" in temporal && typeof temporal.lockRootTimegroup === "function") temporal.lockRootTimegroup();
+			} else if (child instanceof Element) setupParentChildRelationshipsInContainer(child, parent, root);
+		};
+		const setupParentChildRelationshipsInContainer = (container$1, nearestParentTG, root) => {
+			for (const child of container$1.children) if (child.tagName === "EF-TIMEGROUP") {
+				const childTG = child;
+				childTG.parentTimegroup = nearestParentTG;
+				childTG.rootTimegroup = root;
+				childTG.lockRootTimegroup();
+				setupParentChildRelationships(childTG, root);
+			} else if ("parentTimegroup" in child && "rootTimegroup" in child) {
+				const temporal = child;
+				temporal.parentTimegroup = nearestParentTG;
+				temporal.rootTimegroup = root;
+				if ("lockRootTimegroup" in temporal && typeof temporal.lockRootTimegroup === "function") temporal.lockRootTimegroup();
+			} else if (child instanceof Element) setupParentChildRelationshipsInContainer(child, nearestParentTG, root);
+		};
+		actualClone.rootTimegroup = actualClone;
+		setupParentChildRelationships(actualClone, actualClone);
+		await actualClone.updateComplete;
+		actualClone.rootTimegroup = actualClone;
+		actualClone.lockRootTimegroup();
+		const finalizeRootTimegroup = (el) => {
+			if ("rootTimegroup" in el && "lockRootTimegroup" in el) {
+				el.rootTimegroup = actualClone;
+				el.lockRootTimegroup();
+			}
+			for (const child of el.children) finalizeRootTimegroup(child);
+		};
+		finalizeRootTimegroup(actualClone);
+		await actualClone.waitForMediaDurations();
+		await this.#waitForCaptionsData(actualClone);
+		if (actualClone.playbackController) {
+			actualClone.playbackController.remove();
+			actualClone.playbackController = void 0;
+		}
+		await actualClone.seek(0);
+		return {
+			clone: actualClone,
+			container,
+			cleanup: () => {
+				container.remove();
+				const reactRoot = actualClone._reactRoot;
+				if (reactRoot) queueMicrotask(() => {
+					reactRoot.unmount();
+				});
+			}
+		};
+	}
+	/** @internal */
 	get storageKey() {
 		if (!this.id) throw new Error("Timegroup must have an id to use localStorage.");
 		return `ef-timegroup-${this.id}`;
 	}
+	/** @internal */
 	get intrinsicDurationMs() {
 		if (this.hasExplicitDuration) return this.explicitDurationMs;
 	}
+	/** @internal */
 	get hasOwnDuration() {
-		return this.mode === "contain" || this.mode === "sequence" || this.mode === "fixed" && this.hasExplicitDuration;
+		return hasOwnDurationForMode(this.mode, this.hasExplicitDuration);
 	}
+	/** @public */
 	get durationMs() {
-		switch (this.mode) {
-			case "fit":
-				if (!this.parentTimegroup) return 0;
-				return this.parentTimegroup.durationMs;
-			case "fixed": return super.durationMs;
-			case "sequence": {
-				const cachedDuration = sequenceDurationCache.get(this);
-				if (cachedDuration !== void 0) return cachedDuration;
-				let duration = 0;
-				this.childTemporals.forEach((child, index) => {
-					if (child instanceof _EFTimegroup && child.mode === "fit") return;
-					if (index > 0) duration -= this.overlapMs;
-					duration += child.durationMs;
-				});
-				sequenceDurationCache.set(this, duration);
-				return duration;
-			}
-			case "contain": {
-				let maxDuration = 0;
-				for (const child of this.childTemporals) {
-					if (child instanceof _EFTimegroup && child.mode === "fit") continue;
-					if (!child.hasOwnDuration) continue;
-					maxDuration = Math.max(maxDuration, child.durationMs);
-				}
-				return maxDuration;
-			}
-			default: throw new Error(`Invalid time mode: ${this.mode}`);
-		}
+		if (this.mode === "fixed") return super.durationMs;
+		const childTemporalsAsElements = this.childTemporals;
+		return evaluateDurationForMode(this, this.mode, childTemporalsAsElements);
 	}
-	async getPendingFrameTasks(signal) {
-		await this.waitForNestedUpdates(signal);
-		signal?.throwIfAborted();
-		const temporals = deepGetElementsWithFrameTasks(this);
-		const timelineTimeMs = (this.#pendingSeekTime ?? this.#currentTime ?? 0) * 1e3;
-		const frameTasks = temporals.filter((temporal) => {
-			if (!("startTimeMs" in temporal) || !("endTimeMs" in temporal)) return true;
-			const epsilon = .001;
-			const startTimeMs = temporal.startTimeMs;
-			const endTimeMs = temporal.endTimeMs;
-			const elementStartsBeforeEnd = startTimeMs <= timelineTimeMs + epsilon;
-			const elementEndsAfterStart = temporal.tagName.toLowerCase() === "ef-timegroup" && !temporal.parentTimegroup ? endTimeMs >= timelineTimeMs : endTimeMs > timelineTimeMs;
-			return elementStartsBeforeEnd && elementEndsAfterStart;
-		}).map((temporal) => temporal.frameTask);
-		frameTasks.forEach((task) => {
-			task.run();
+	/**
+	* Evaluates which elements should be rendered in the current frame.
+	* Filters to only include temporally visible elements for frame processing.
+	* Uses animation-friendly visibility to prevent animation jumps at exact boundaries.
+	*/
+	#evaluateVisibleElementsForFrame() {
+		return deepGetElementsWithFrameTasks(this).filter((element) => {
+			return evaluateAnimationVisibilityState(element).isVisible;
 		});
-		return frameTasks.filter((task) => task.status < TaskStatus.COMPLETE);
-	}
-	async waitForNestedUpdates(signal) {
-		const limit = 10;
-		let steps = 0;
-		let isComplete = true;
-		while (true) {
-			steps++;
-			if (steps > limit) throw new Error("Reached update depth limit.");
-			isComplete = await this.updateComplete;
-			signal?.throwIfAborted();
-			if (isComplete) break;
-		}
 	}
-	async waitForFrameTasks() {
+	/** @internal */
+	async waitForFrameTasks(signal) {
 		return await withSpan("timegroup.waitForFrameTasks", {
 			timegroupId: this.id || "unknown",
 			mode: this.mode
 		}, void 0, async (span) => {
+			signal?.throwIfAborted();
 			const innerStart = performance.now();
 			const temporalElements = deepGetElementsWithFrameTasks(this);
 			if (isTracingEnabled()) span.setAttribute("temporalElementsCount", temporalElements.length);
-			const visibleElements = temporalElements.filter((element) => {
-				return evaluateAnimationVisibilityState(element).isVisible;
-			});
+			signal?.throwIfAborted();
+			const visibleElements = this.#evaluateVisibleElementsForFrame();
 			if (isTracingEnabled()) span.setAttribute("visibleElementsCount", visibleElements.length);
 			const promiseStart = performance.now();
-			await Promise.all(visibleElements.map((element) => element.frameTask.run()));
+			await Promise.all(visibleElements.map(async (element) => {
+				signal?.throwIfAborted();
+				try {
+					if ("waitForFrameReady" in element && typeof element.waitForFrameReady === "function") await element.waitForFrameReady();
+					else {
+						await element.updateComplete;
+						await element.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"))) {
+						signal?.throwIfAborted();
+						return;
+					}
+					throw error;
+				}
+			}));
 			const promiseEnd = performance.now();
 			const innerEnd = performance.now();
 			if (isTracingEnabled()) {
@@ -389,9 +962,21 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			}
 		});
 	}
-	async waitForMediaDurations() {
-		if (!this.mediaDurationsPromise) this.mediaDurationsPromise = this.#waitForMediaDurations();
-		return this.mediaDurationsPromise;
+	#mediaDurationsPromise = void 0;
+	/** @internal */
+	async waitForMediaDurations(signal) {
+		signal?.throwIfAborted();
+		if (!this.#mediaDurationsPromise) this.#mediaDurationsPromise = this.#waitForMediaDurations(signal).catch((err) => {
+			if (err instanceof DOMException && err.name === "AbortError") {
+				this.#mediaDurationsPromise = void 0;
+				throw err;
+			}
+			console.error(`[EFTimegroup] waitForMediaDurations failed for ${this.id || "unnamed"}:`, err);
+			this.#mediaDurationsPromise = void 0;
+			throw err;
+		});
+		if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+		return this.#mediaDurationsPromise;
 	}
 	/**
 	* Wait for all media elements to load their initial segments.
@@ -399,25 +984,96 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* that caused issues with constructing audio data. We had negative durations
 	* in calculations and it was not clear why.
 	*/
-	async #waitForMediaDurations() {
+	async #waitForMediaDurations(signal) {
 		return withSpan("timegroup.waitForMediaDurations", {
 			timegroupId: this.id || "unknown",
 			mode: this.mode
 		}, void 0, async (span) => {
-			await this.updateComplete;
+			signal?.throwIfAborted();
+			await new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new DOMException("Aborted", "AbortError"));
+					return;
+				}
+				const abortHandler = () => {
+					clearTimeout(timeoutId);
+					cancelAnimationFrame(rafId2);
+					cancelAnimationFrame(rafId1);
+					reject(new DOMException("Aborted", "AbortError"));
+				};
+				signal?.addEventListener("abort", abortHandler, { once: true });
+				let rafId1;
+				let rafId2;
+				let timeoutId;
+				rafId1 = requestAnimationFrame(() => {
+					if (signal?.aborted) {
+						reject(new DOMException("Aborted", "AbortError"));
+						return;
+					}
+					rafId2 = requestAnimationFrame(() => {
+						if (signal?.aborted) {
+							reject(new DOMException("Aborted", "AbortError"));
+							return;
+						}
+						timeoutId = setTimeout(() => {
+							signal?.removeEventListener("abort", abortHandler);
+							resolve();
+						}, 10);
+					});
+				});
+			});
+			signal?.throwIfAborted();
 			const mediaElements = deepGetMediaElements(this);
 			if (isTracingEnabled()) span.setAttribute("mediaElementsCount", mediaElements.length);
-			await Promise.all(mediaElements.map((m) => m.mediaEngineTask.value ? Promise.resolve() : m.mediaEngineTask.run()));
+			signal?.throwIfAborted();
+			const mediaLoadStart = Date.now();
+			const MEDIA_LOAD_TIMEOUT_MS = 3e4;
+			const loadPromises = mediaElements.map(async (m, index) => {
+				signal?.throwIfAborted();
+				const elementStart = Date.now();
+				try {
+					const status = m.mediaEngineTask.status;
+					if (status === TaskStatus.COMPLETE || status === TaskStatus.ERROR) return;
+					if (status === TaskStatus.INITIAL) m.mediaEngineTask.run().catch(() => {});
+					const timeoutPromise = new Promise((_, reject) => {
+						if (signal?.aborted) {
+							reject(new DOMException("Aborted", "AbortError"));
+							return;
+						}
+						const timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Media element ${index} load timeout after ${MEDIA_LOAD_TIMEOUT_MS}ms`)), MEDIA_LOAD_TIMEOUT_MS);
+						signal?.addEventListener("abort", () => {
+							clearTimeout(timeoutId);
+							reject(new DOMException("Aborted", "AbortError"));
+						}, { once: true });
+					});
+					const taskPromise = m.mediaEngineTask.taskComplete;
+					taskPromise.catch(() => {});
+					await Promise.race([taskPromise, timeoutPromise]);
+				} catch (error) {
+					if (error instanceof DOMException && error.name === "AbortError") throw error;
+					if (isTracingEnabled()) {
+						const elementElapsed = Date.now() - elementStart;
+						console.error(`[EFTimegroup] Media element ${index} failed after ${elementElapsed}ms:`, error);
+					}
+				}
+			});
+			const results = await Promise.allSettled(loadPromises);
+			if (results.some((r) => r.status === "rejected" && r.reason instanceof DOMException && r.reason.name === "AbortError")) throw new DOMException("Aborted", "AbortError");
+			const failures = results.filter((r) => r.status === "rejected");
+			if (failures.length > 0 && isTracingEnabled()) {
+				const mediaLoadElapsed = Date.now() - mediaLoadStart;
+				console.warn(`[EFTimegroup] ${failures.length} media elements failed to load in ${mediaLoadElapsed}ms:`, failures.map((r) => r.status === "rejected" ? r.reason : null));
+			}
 			flushStartTimeMsCache();
 			flushSequenceDurationCache();
-			this.requestUpdate("currentTime");
-			await this.updateComplete;
+			setTimeout(() => this.requestUpdate("currentTime"), 0);
 		});
 	}
+	/** @internal */
 	get childTemporals() {
 		return shallowGetTemporalElements(this);
 	}
-	get contextProvider() {
+	get #contextProvider() {
 		let parent = this.parentNode;
 		while (parent) {
 			if (isContextMixin(parent)) return parent;
@@ -430,34 +1086,59 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	*
 	* A timegroup should be wrapped with a workbench if:
 	* - It's being rendered (EF_RENDERING), OR
-	* - It's in interactive mode (EF_INTERACTIVE) with the dev workbench flag set
+	* - The workbench property is set to true
 	*
 	* If the timegroup is already wrapped in a context provider like ef-preview,
 	* it should NOT be wrapped in a workbench.
+	* @internal
 	*/
 	shouldWrapWithWorkbench() {
-		if (EF_RENDERING?.() === true) return this.closest("ef-timegroup") === this && this.closest("ef-preview") === null && this.closest("ef-workbench") === null && this.closest("test-context") === null;
-		if (!globalThis.EF_DEV_WORKBENCH) return false;
-		return EF_INTERACTIVE && this.closest("ef-timegroup") === this && this.closest("ef-preview") === null && this.closest("ef-workbench") === null && this.closest("test-context") === null;
+		if (!this.isRootTimegroup) return false;
+		if (this.closest("ef-canvas") !== null) return false;
+		if (this.closest("ef-preview") !== null || this.closest("ef-workbench") !== null || this.closest("ef-preview-context") !== null) return false;
+		if (this.closest("test-context") !== null) return false;
+		if (this.closest(".ef-render-clone-container") !== null) return false;
+		if (EF_RENDERING?.() === true) return true;
+		return this.workbench;
 	}
+	/** @internal */
 	wrapWithWorkbench() {
 		const workbench = document.createElement("ef-workbench");
 		this.parentElement?.append(workbench);
-		if (!this.hasAttribute("id")) this.setAttribute("id", "root-this");
-		this.setAttribute("slot", "canvas");
-		workbench.append(this);
+		if (!this.hasAttribute("id")) this.setAttribute("id", "root-timegroup");
+		const panZoom = document.createElement("ef-pan-zoom");
+		panZoom.id = "workbench-panzoom";
+		panZoom.setAttribute("slot", "canvas");
+		panZoom.setAttribute("auto-fit", "");
+		panZoom.style.width = "100%";
+		panZoom.style.height = "100%";
+		const rect = this.getBoundingClientRect();
+		const canvas = document.createElement("ef-canvas");
+		canvas.id = "workbench-canvas";
+		canvas.style.width = `${Math.max(rect.width, 1920)}px`;
+		canvas.style.height = `${Math.max(rect.height, 1080)}px`;
+		canvas.style.display = "block";
+		canvas.append(this);
+		panZoom.append(canvas);
+		workbench.append(panZoom);
+		const hierarchy = document.createElement("ef-hierarchy");
+		hierarchy.setAttribute("slot", "hierarchy");
+		hierarchy.setAttribute("target", "workbench-canvas");
+		hierarchy.setAttribute("header", "Scenes");
+		workbench.append(hierarchy);
 		const filmstrip = document.createElement("ef-filmstrip");
 		filmstrip.setAttribute("slot", "timeline");
 		filmstrip.setAttribute("target", this.id);
 		workbench.append(filmstrip);
 	}
-	get efElements() {
+	get #efElements() {
 		return Array.from(this.querySelectorAll("ef-audio, ef-video, ef-image, ef-captions, ef-waveform"));
 	}
 	/**
 	* Returns media elements for playback audio rendering
 	* For standalone media, returns [this]; for timegroups, returns all descendants
 	* Used by PlaybackController for audio-driven playback
+	* @internal
 	*/
 	getMediaElements() {
 		return deepGetMediaElements(this);
@@ -466,15 +1147,16 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* Render audio buffer for playback
 	* Called by PlaybackController during live playback
 	* Delegates to shared renderTemporalAudio utility for consistent behavior
+	* @internal
 	*/
-	async renderAudio(fromMs, toMs) {
-		return renderTemporalAudio(this, fromMs, toMs);
+	async renderAudio(fromMs, toMs, signal) {
+		return renderTemporalAudio(this, fromMs, toMs, signal);
 	}
 	/**
 	* TEMPORARY TEST METHOD: Renders audio and immediately plays it back
 	* Usage: timegroup.testPlayAudio(0, 5000) // Play first 5 seconds
 	*/
-	async testPlayAudio(fromMs, toMs) {
+	async #testPlayAudio(fromMs, toMs) {
 		const renderedBuffer = await this.renderAudio(fromMs, toMs);
 		const playbackContext = new AudioContext();
 		const bufferSource = playbackContext.createBufferSource();
@@ -488,13 +1170,13 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			};
 		});
 	}
-	async loadMd5Sums() {
-		const efElements = this.efElements;
+	async #loadMd5Sums() {
+		const efElements = this.#efElements;
 		const loaderTasks = [];
 		for (const el of efElements) {
 			const md5SumLoader = el.md5SumLoader;
 			if (md5SumLoader instanceof Task) {
-				md5SumLoader.run();
+				md5SumLoader.run().catch(() => {});
 				loaderTasks.push(md5SumLoader.taskComplete);
 			}
 		}
@@ -503,6 +1185,14 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			if ("productionSrc" in el && el.productionSrc instanceof Function) el.setAttribute("src", el.productionSrc());
 		});
 	}
+	#timegroupFrameTaskCount = 0;
+	#timegroupFrameTaskLastReset = Date.now();
+	static {
+		this.TIMEGROUP_FRAME_TASK_THRESHOLD = 100;
+	}
+	static {
+		this.TIMEGROUP_FRAME_TASK_RESET_MS = 1e3;
+	}
 	async #executeCustomFrameTasks() {
 		if (this.#customFrameTasks.size > 0) {
 			const percentComplete = this.durationMs > 0 ? this.ownCurrentTimeMs / this.durationMs : 0;
@@ -516,10 +1206,41 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			await Promise.all(Array.from(this.#customFrameTasks).map((callback) => Promise.resolve(callback(frameInfo))));
 		}
 	}
+	/**
+	* Get container information for this timegroup.
+	* Timegroups are always containers and can contain children.
+	* Display mode is determined from computed styles.
+	*
+	* @public
+	*/
+	getContainerInfo() {
+		return {
+			...getContainerInfoFromElement(this),
+			isContainer: true,
+			canContainChildren: true
+		};
+	}
+	/**
+	* Get position information for this timegroup.
+	* Returns computed bounds, transform, and rotation.
+	*
+	* @public
+	*/
+	getPositionInfo() {
+		return getPositionInfoFromElement(this);
+	}
 };
 __decorate([provide({ context: timegroupContext })], EFTimegroup.prototype, "_timeGroupContext", void 0);
 __decorate([provide({ context: efContext })], EFTimegroup.prototype, "efContext", void 0);
 __decorate([property({ type: Number })], EFTimegroup.prototype, "fps", void 0);
+__decorate([property({
+	type: Boolean,
+	attribute: "auto-init"
+})], EFTimegroup.prototype, "autoInit", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], EFTimegroup.prototype, "workbench", void 0);
 __decorate([property({ type: String })], EFTimegroup.prototype, "fit", void 0);
 __decorate([property({
 	type: Number,