@editframe/elements 0.37.3-beta → 0.38.0

package/dist/elements/EFTimegroup.js

@@ -1,22 +1,21 @@
 import { quantizeToFrameTimeS } from "../utils/frameTime.js";
+import { getCloneFactory } from "./cloneFactoryRegistry.js";
 import { EF_RENDERING } from "../EF_RENDERING.js";
-import { evaluateAnimationVisibilityState, updateAnimations } from "./updateAnimations.js";
-import { parseTimeToMs } from "./parseTimeToMs.js";
-import { __decorate } from "../_virtual/_@oxc-project_runtime@0.95.0/helpers/decorate.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";
 import { isTracingEnabled, withSpan } from "../otel/tracingHelpers.js";
 import { FrameController, PRIORITY_DEFAULT } from "../preview/FrameController.js";
+import { QualityUpgradeScheduler } from "../preview/QualityUpgradeScheduler.js";
+import { updateAnimations } from "./updateAnimations.js";
+import { parseTimeToMs } from "./parseTimeToMs.js";
+import { __decorate } from "../_virtual/_@oxc-project_runtime@0.95.0/helpers/decorate.js";
+import { EFTemporal, flushStartTimeMsCache, registerIsTimegroupCalculatingDuration, resetTemporalCache, shallowGetTemporalElements, timegroupContext } from "./EFTemporal.js";
 import { renderTemporalAudio } from "./renderTemporalAudio.js";
 import { EFTargetable } from "./TargetController.js";
 import { deepGetMediaElements } from "./EFMedia.js";
 import { TimegroupController } from "./TimegroupController.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";
@@ -29,10 +28,9 @@ import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 
 //#region src/elements/EFTimegroup.ts
-var _EFTimegroup;
 const log = debug("ef:elements:EFTimegroup");
-const INITIALIZER_ERROR_THRESHOLD_MS = 100;
-const INITIALIZER_WARN_THRESHOLD_MS = 10;
+const INITIALIZER_ERROR_THRESHOLD_MS = 2e3;
+const INITIALIZER_WARN_THRESHOLD_MS = 100;
 let durationCache = /* @__PURE__ */ new WeakMap();
 const flushDurationCache = () => {
 	durationCache = /* @__PURE__ */ new WeakMap();
@@ -176,34 +174,14 @@ function evaluateSeekTarget(requestedTime, durationMs, fps) {
 	return Math.max(0, Math.min(quantizedTime, durationMs / 1e3));
 }
 let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(LitElement))) {
-	static {
-		_EFTimegroup = this;
-	}
 	constructor(..._args) {
 		super(..._args);
 		this._timeGroupContext = this;
 		this.efContext = this;
-		this.mode = "contain";
-		this.overlapMs = 0;
 		this.fps = 30;
 		this.autoInit = false;
 		this.workbench = false;
 		this.fit = "none";
-		this.frameTask = (() => {
-			const self = this;
-			const taskObj = {
-				run: () => {
-					self.#frameTaskAbortController?.abort();
-					self.#frameTaskAbortController = new AbortController();
-					const signal = self.#frameTaskAbortController.signal;
-					self.#frameTaskPromise = self.#runFrameTask(signal);
-					taskObj.taskComplete = self.#frameTaskPromise;
-					return self.#frameTaskPromise;
-				},
-				taskComplete: Promise.resolve()
-			};
-			return taskObj;
-		})();
 		this.seekTask = (() => {
 			const self = this;
 			const taskObj = {
@@ -251,25 +229,95 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
     }
   `;
 	}
+	#trackedChildren = /* @__PURE__ */ new Set();
+	shouldAutoReady() {
+		return false;
+	}
+	#childReadyStateHandler = () => {
+		this.#recomputeAggregateReadyState();
+	};
+	#childContentChangeHandler = (e) => {
+		const detail = e.detail;
+		this.emitContentChange(detail?.reason ?? "content");
+	};
+	#recomputeAggregateReadyState() {
+		const children = shallowGetTemporalElements(this);
+		if (children.length === 0) {
+			this.setContentReadyState("ready");
+			return;
+		}
+		let hasLoading = false;
+		let hasError = false;
+		let hasIdle = false;
+		for (const child of children) {
+			const state$1 = child.contentReadyState;
+			if (state$1 === "loading") hasLoading = true;
+			else if (state$1 === "error") hasError = true;
+			else if (state$1 === "idle") hasIdle = true;
+		}
+		if (hasError) this.setContentReadyState("error");
+		else if (hasLoading) this.setContentReadyState("loading");
+		else if (hasIdle) this.setContentReadyState("loading");
+		else this.setContentReadyState("ready");
+	}
+	#syncChildListeners() {
+		const currentChildren = new Set(shallowGetTemporalElements(this));
+		for (const child of this.#trackedChildren) if (!currentChildren.has(child)) {
+			child.removeEventListener("readystatechange", this.#childReadyStateHandler);
+			child.removeEventListener("contentchange", this.#childContentChangeHandler);
+		}
+		for (const child of currentChildren) if (!this.#trackedChildren.has(child)) {
+			child.addEventListener("readystatechange", this.#childReadyStateHandler);
+			child.addEventListener("contentchange", this.#childContentChangeHandler);
+		}
+		this.#trackedChildren = currentChildren;
+		this.#recomputeAggregateReadyState();
+	}
+	/** @public */
+	#mode = "contain";
+	get mode() {
+		return this.#mode;
+	}
+	set mode(value) {
+		if (this.#mode === value) return;
+		const old = this.#mode;
+		this.#mode = value;
+		this.requestUpdate("mode", old);
+		if (this.getAttribute("mode") !== value) this.setAttribute("mode", value);
+	}
+	/** @public */
+	#overlapMs = 0;
+	get overlapMs() {
+		return this.#overlapMs;
+	}
+	set overlapMs(value) {
+		if (this.#overlapMs === value) return;
+		const old = this.#overlapMs;
+		this.#overlapMs = value;
+		this.requestUpdate("overlapMs", old);
+		const attrVal = value > 0 ? `${value}ms` : null;
+		if (attrVal && this.getAttribute("overlap") !== attrVal) this.setAttribute("overlap", attrVal);
+		else if (!attrVal && this.hasAttribute("overlap")) this.removeAttribute("overlap");
+	}
 	#initializer;
 	/**
 	* Initializer function for setting up JavaScript behavior on this timegroup.
 	* This function is called ONCE per instance - on the prime timeline when first connected,
 	* and on each render clone when created.
-	* 
+	*
 	* Use this to register frame callbacks, set up event listeners, or initialize state.
 	* The same initializer code runs on both prime and clones, eliminating duplication.
-	* 
+	*
 	* CONSTRAINTS:
 	* - MUST be synchronous (no async/await, no Promise return)
 	* - MUST complete in <100ms (error thrown) or <10ms (warning logged)
 	* - Should only register callbacks and set up behavior, not do expensive work
-	* 
+	*
 	* TIMING:
 	* - If set before element connects to DOM: runs automatically after connectedCallback
 	* - If set after element is connected: runs immediately
 	* - Clones automatically copy and run the initializer when created
-	* 
+	*
 	* @example
 	* ```javascript
 	* const tg = document.querySelector('ef-timegroup');
@@ -287,29 +335,12 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	}
 	set initializer(fn) {
 		this.#initializer = fn;
-		if (fn && this.isConnected && !this.#initializerHasRun) this.#initializerComplete = this.updateComplete.then(() => {
-			this.#runInitializer();
-		});
 	}
 	/**
 	* Track if initializer has run on this instance to prevent double execution.
 	* @internal
 	*/
 	#initializerHasRun = false;
-	/**
-	* Promise that resolves when initializer completes.
-	* Used by createRenderClone to ensure frame tasks are registered before rendering.
-	* @internal
-	*/
-	#initializerComplete;
-	/**
-	* Public accessor for initializer completion promise.
-	* Allows createRenderClone to wait for initializer before rendering.
-	* @internal
-	*/
-	get initializerComplete() {
-		return this.#initializerComplete;
-	}
 	attributeChangedCallback(name, old, value) {
 		if (name === "mode" && value) this.mode = value;
 		if (name === "overlap" && value) this.overlapMs = parseTimeToMs(value);
@@ -352,6 +383,18 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		return this.#frameController;
 	}
 	/**
+	* Centralized quality upgrade scheduler for coordinating main-quality segment fetching.
+	* Lives alongside FrameController to manage background quality upgrades.
+	*/
+	#qualityUpgradeScheduler = new QualityUpgradeScheduler({ requestFrameRender: () => this.requestFrameRender() });
+	/**
+	* Get the quality upgrade scheduler for background segment fetching.
+	* @public
+	*/
+	get qualityUpgradeScheduler() {
+		return this.#qualityUpgradeScheduler;
+	}
+	/**
 	* Query timegroup's readiness state for a given time.
 	* Timegroups are always ready (no async preparation needed).
 	* @public
@@ -406,9 +449,28 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	incrementContentEpoch() {
 		this.#contentEpoch++;
 	}
+	/**
+	* Request a frame re-render at the current time.
+	*
+	* Use this when the source-to-timeline mapping has changed (e.g., sourcein/sourceout)
+	* but currentTimeMs hasn't. The FrameController only re-renders when currentTimeMs
+	* or durationMs change, so this provides a way for child elements to request a
+	* re-render when their internal state changes the visual output.
+	* @public
+	*/
+	requestFrameRender() {
+		this.#runThrottledFrameTask();
+	}
 	async #runThrottledFrameTask() {
 		if (this.playbackController) return this.playbackController.runThrottledFrameTask();
-		await this.frameTask.run();
+		try {
+			await this.#frameController.renderFrame(this.currentTimeMs, { onAnimationsUpdate: (root) => {
+				updateAnimations(root);
+			} });
+		} catch (error) {
+			if (error instanceof DOMException && error.name === "AbortError") return;
+			console.error("FrameController error:", error);
+		}
 	}
 	/** @public */
 	set currentTime(time) {
@@ -432,8 +494,10 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		this.#currentTime = seekTarget;
 		this.#userTimeMs = seekTarget * 1e3;
 		this.#seekInProgress = true;
-		this.seekTask.run().catch(() => {}).finally(() => {
+		Promise.resolve(this.seekTask.run()).catch(() => {}).finally(async () => {
 			this.#seekInProgress = false;
+			const { updateAnimations: updateAnimations$1 } = await import("./updateAnimations.js");
+			updateAnimations$1(this);
 			if (this.#pendingSeekTime !== void 0 && this.#pendingSeekTime !== seekTarget) {
 				const pendingTime = this.#pendingSeekTime;
 				this.#pendingSeekTime = void 0;
@@ -474,7 +538,7 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	*
 	* 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
@@ -486,12 +550,9 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		this.currentTimeMs = timeMs;
 		await this.seekTask.taskComplete;
 		if (this.playbackController) this.saveTimeToLocalStorage(this.currentTime);
-		await this.frameTask.taskComplete;
-		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;
-		}));
+		await this.#frameController.renderFrame(timeMs, { onAnimationsUpdate: (root) => {
+			updateAnimations(root);
+		} });
 	}
 	/**
 	* Optimized seek for render loops.
@@ -499,9 +560,9 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* - Skips waitForMediaDurations (already loaded at render setup)
 	* - Skips localStorage persistence
 	* - Uses FrameController for centralized element coordination
-	* 
+	*
 	* Still waits for all content to be ready (Lit updates, element preparation, rendering).
-	* 
+	*
 	* @param timeMs - Time in milliseconds to seek to
 	* @internal
 	*/
@@ -509,15 +570,21 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		const newTime = timeMs / 1e3;
 		this.#userTimeMs = timeMs;
 		this.#currentTime = newTime;
+		if (this.playbackController) this.playbackController.currentTime = newTime;
+		this._setLocalTimeMs(timeMs);
 		this.requestUpdate("currentTime");
 		await this.updateComplete;
 		const allLitElements = this.#getAllLitElementDescendants();
 		await Promise.all(allLitElements.map((el) => el.updateComplete));
+		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();
-		}));
+		if (textElements.length > 0) {
+			await Promise.all(textElements.map((el) => {
+				if ("whenSegmentsReady" in el && typeof el.whenSegmentsReady === "function") return el.whenSegmentsReady();
+				return Promise.resolve();
+			}));
+			this.offsetHeight;
+		}
 		await this.#frameController.renderFrame(timeMs, {
 			waitForLitUpdate: false,
 			onAnimationsUpdate: (root) => {
@@ -530,36 +597,21 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	/**
 	* Collects all LitElement descendants recursively.
 	* Used by seekForRender to ensure all reactive elements have updated.
-	* Optimized to filter by temporal visibility and skip hidden subtrees.
+	* Prunes subtrees of temporally-invisible elements — their Lit updates
+	* still fire via microtasks (OwnCurrentTimeController), so skipping
+	* the explicit await is safe.
 	*/
 	#getAllLitElementDescendants() {
 		const result = [];
 		const currentTimeMs = this.currentTimeMs;
-		let hiddenSubtreesSkipped = 0;
-		let temporallyFilteredOut = 0;
-		let totalLitElements = 0;
 		const walk = (el) => {
-			if (el instanceof HTMLElement && el.style.display === "none") {
-				hiddenSubtreesSkipped++;
-				return;
-			}
-			if (el instanceof HTMLElement) {
-				const style = getComputedStyle(el);
-				if (style.display === "none" || style.visibility === "hidden") {
-					hiddenSubtreesSkipped++;
-					return;
-				}
-			}
 			for (const child of el.children) {
-				if (child instanceof LitElement) {
-					totalLitElements++;
-					if ("startTimeMs" in child && "endTimeMs" in child) {
-						const startMs = child.startTimeMs ?? -Infinity;
-						const endMs = child.endTimeMs ?? Infinity;
-						if (currentTimeMs >= startMs && currentTimeMs <= endMs) result.push(child);
-						else temporallyFilteredOut++;
-					} else result.push(child);
+				if ("startTimeMs" in child && "endTimeMs" in child) {
+					const startMs = child.startTimeMs ?? -Infinity;
+					const endMs = child.endTimeMs ?? Infinity;
+					if (endMs > startMs && (currentTimeMs < startMs || currentTimeMs >= endMs)) continue;
 				}
+				if (child instanceof LitElement) result.push(child);
 				walk(child);
 			}
 		};
@@ -639,6 +691,8 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		flushSequenceDurationCache();
 		flushStartTimeMsCache();
 		this.requestUpdate();
+		this.#syncChildListeners();
+		this.emitContentChange("structure");
 	};
 	/** @internal */
 	loadTimeFromLocalStorage() {
@@ -654,8 +708,10 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	}
 	connectedCallback() {
 		super.connectedCallback();
+		if (this.canvasPreviewActive) return;
 		this.updateComplete.then(() => {
 			this.#runInitializer();
+			this.#syncChildListeners();
 		});
 		requestAnimationFrame(() => {
 			requestAnimationFrame(() => {
@@ -679,9 +735,7 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	#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;
-			}
+			if (event.property === "currentTimeMs" && typeof event.value === "number") this.#userTimeMs = event.value;
 		};
 		this.playbackController.addListener(this.#playbackListener);
 	}
@@ -703,79 +757,29 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	}
 	disconnectedCallback() {
 		super.disconnectedCallback();
+		if (this.canvasPreviewActive) return;
 		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();
+		for (const child of this.#trackedChildren) {
+			child.removeEventListener("readystatechange", this.#childReadyStateHandler);
+			child.removeEventListener("contentchange", this.#childContentChangeHandler);
 		}
+		this.#trackedChildren.clear();
+		this.#qualityUpgradeScheduler.dispose();
 	}
 	/**
 	* 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.
-	* 
+	*
+	* Uses dynamic import to only load render utilities in browser context.
+	*
 	* @param options - Rendering options (fps, codec, bitrate, filename, etc.)
 	* @returns Promise that resolves when video is downloaded
 	* @public
 	*/
 	async renderToVideo(options) {
+		const { renderTimegroupToVideo } = await import("../preview/renderTimegroupToVideo.js");
 		return renderTimegroupToVideo(this, options);
 	}
 	/**
@@ -808,7 +812,8 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		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;
+			const loadedData = origCap.captionsData ?? origCap.unifiedCaptionsDataTask?.value;
+			if (loadedData) cloneCap.captionsData = loadedData;
 		}
 	}
 	/**
@@ -873,10 +878,10 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* @internal
 	*/
 	async #copyInitializersToClone(original, clone) {
-		const initializerPromises = [];
 		if (original.initializer) {
 			clone.initializer = original.initializer;
-			if (clone.initializerComplete) initializerPromises.push(clone.initializerComplete);
+			await clone.updateComplete;
+			clone.#runInitializer();
 		}
 		const originalNested = Array.from(original.querySelectorAll("ef-timegroup"));
 		const cloneNested = Array.from(clone.querySelectorAll("ef-timegroup"));
@@ -885,29 +890,104 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			const cloneNestedItem = cloneNested[i];
 			if (origNested.initializer) {
 				cloneNestedItem.initializer = origNested.initializer;
-				if (cloneNestedItem.initializerComplete) initializerPromises.push(cloneNestedItem.initializerComplete);
+				await cloneNestedItem.updateComplete;
+				cloneNestedItem.#runInitializer();
 			}
 		}
-		if (initializerPromises.length > 0) await Promise.all(initializerPromises);
 	}
 	/**
 	* 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 factory = getCloneFactory(this);
+		if (factory) return this.#createRenderCloneFromFactory(factory);
+		return this.#createRenderCloneFromDOM();
+	}
+	/**
+	* Wait for all LitElement descendants to update and for text segments to be ready.
+	* This ensures the clone is fully initialized before rendering.
+	* @internal
+	*/
+	async #waitForDescendants(actualClone) {
+		const allLitElements = Array.from(actualClone.querySelectorAll("*")).filter((el) => el instanceof LitElement);
+		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();
+			}));
+			actualClone.offsetHeight;
+			await new Promise((resolve) => requestAnimationFrame(resolve));
+		}
+	}
+	/**
+	* Factory path: mount a fresh component tree (React, etc.) to produce
+	* a fully functional clone. The factory is responsible for rendering
+	* the component into the container and returning the root ef-timegroup.
+	*/
+	async #createRenderCloneFromFactory(factory) {
+		const width = this.offsetWidth || 1920;
+		const height = this.offsetHeight || 1080;
+		const container = document.createElement("div");
+		container.className = "ef-render-clone-container";
+		container.style.cssText = `
+      position: fixed;
+      left: -9999px;
+      top: 0;
+      width: ${width}px;
+      height: ${height}px;
+      pointer-events: none;
+      overflow: hidden;
+    `;
+		let renderTarget = container;
+		const originalConfig = this.closest("ef-configuration");
+		if (originalConfig) {
+			const configClone = originalConfig.cloneNode(false);
+			container.appendChild(configClone);
+			renderTarget = configClone;
+		}
+		document.body.appendChild(container);
+		const { timegroup: actualClone, cleanup: factoryCleanup } = factory(renderTarget);
+		if (!actualClone) throw new Error("Clone factory did not produce an ef-timegroup. Ensure the factory renders a component containing a Timegroup.");
+		actualClone.setAttribute("data-no-workbench", "true");
+		actualClone.setAttribute("data-no-playback-controller", "true");
+		actualClone.style.width = `${width}px`;
+		actualClone.style.height = `${height}px`;
+		actualClone.style.display = "block";
+		await customElements.whenDefined("ef-timegroup");
+		customElements.upgrade(container);
+		await actualClone.updateComplete;
+		await this.#waitForDescendants(actualClone);
+		await this.#finalizeRenderClone(actualClone);
+		return {
+			clone: actualClone,
+			container,
+			cleanup: () => {
+				container.remove();
+				factoryCleanup();
+			}
+		};
+	}
+	/**
+	* DOM path: deep clone the DOM tree and copy JavaScript properties.
+	* Used for vanilla HTML/JS timelines that don't have a factory registered.
+	*/
+	async #createRenderCloneFromDOM() {
 		const container = document.createElement("div");
 		container.className = "ef-render-clone-container";
 		container.style.cssText = `
@@ -921,6 +1001,14 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
     `;
 		const cloneEl = this.cloneNode(true);
 		cloneEl.removeAttribute("id");
+		for (const el of cloneEl.querySelectorAll("[id]")) el.removeAttribute("id");
+		cloneEl.setAttribute("data-no-workbench", "true");
+		cloneEl.setAttribute("data-no-playback-controller", "true");
+		const width = this.offsetWidth || 1920;
+		const height = this.offsetHeight || 1080;
+		cloneEl.style.width = `${width}px`;
+		cloneEl.style.height = `${height}px`;
+		cloneEl.style.display = "block";
 		this.#copyCaptionsData(this, cloneEl);
 		this.#copyTextContent(this, cloneEl);
 		const originalConfig = this.closest("ef-configuration");
@@ -940,7 +1028,30 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		actualClone = container.querySelector("ef-timegroup");
 		if (!actualClone) throw new Error("ef-timegroup element lost after upgrade");
 		await actualClone.updateComplete;
+		await this.#waitForDescendants(actualClone);
 		await this.#copyTextSegmentData(this, actualClone);
+		await this.#finalizeRenderClone(actualClone);
+		return {
+			clone: actualClone,
+			container,
+			cleanup: () => {
+				container.remove();
+				const reactRoot = actualClone._reactRoot;
+				if (reactRoot) queueMicrotask(() => {
+					reactRoot.unmount();
+				});
+			}
+		};
+	}
+	/**
+	* Shared finalization for both factory and DOM clone paths:
+	* - Set up parent-child temporal relationships
+	* - Lock root timegroup references
+	* - Wait for media durations and captions
+	* - Remove PlaybackController
+	* - Initial seek to frame 0
+	*/
+	async #finalizeRenderClone(actualClone) {
 		const setupParentChildRelationships = (parent, root) => {
 			for (const child of parent.children) if (child.tagName === "EF-TIMEGROUP") {
 				const childTG = child;
@@ -953,10 +1064,10 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 				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);
+			} else if (child instanceof Element) setupInContainer(child, parent, root);
 		};
-		const setupParentChildRelationshipsInContainer = (container$1, nearestParentTG, root) => {
-			for (const child of container$1.children) if (child.tagName === "EF-TIMEGROUP") {
+		const setupInContainer = (container, nearestParentTG, root) => {
+			for (const child of container.children) if (child.tagName === "EF-TIMEGROUP") {
 				const childTG = child;
 				childTG.parentTimegroup = nearestParentTG;
 				childTG.rootTimegroup = root;
@@ -967,7 +1078,7 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 				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);
+			} else if (child instanceof Element) setupInContainer(child, nearestParentTG, root);
 		};
 		actualClone.rootTimegroup = actualClone;
 		setupParentChildRelationships(actualClone, actualClone);
@@ -989,17 +1100,6 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			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() {
@@ -1020,54 +1120,6 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		const childTemporalsAsElements = this.childTemporals;
 		return evaluateDurationForMode(this, this.mode, childTemporalsAsElements);
 	}
-	/**
-	* 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;
-		});
-	}
-	/** @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);
-			signal?.throwIfAborted();
-			const visibleElements = this.#evaluateVisibleElementsForFrame();
-			if (isTracingEnabled()) span.setAttribute("visibleElementsCount", visibleElements.length);
-			const promiseStart = performance.now();
-			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()) {
-				span.setAttribute("actualInnerMs", innerEnd - innerStart);
-				span.setAttribute("promiseAwaitMs", promiseEnd - promiseStart);
-			}
-		});
-	}
 	#mediaDurationsPromise = void 0;
 	/** @internal */
 	async waitForMediaDurations(signal) {
@@ -1195,14 +1247,6 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	get childTemporals() {
 		return shallowGetTemporalElements(this);
 	}
-	get #contextProvider() {
-		let parent = this.parentNode;
-		while (parent) {
-			if (isContextMixin(parent)) return parent;
-			parent = parent.parentNode;
-		}
-		return null;
-	}
 	/**
 	* Returns true if the timegroup should be wrapped with a workbench.
 	*
@@ -1215,18 +1259,26 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* @internal
 	*/
 	shouldWrapWithWorkbench() {
+		if (this.canvasPreviewActive) return false;
 		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;
+		if (this.closest("test-context") !== null || this.hasAttribute("data-no-workbench")) return false;
+		if (EF_RENDERING?.() === true) return false;
+		if (typeof window !== "undefined") {
+			const params = new URLSearchParams(window.location.search);
+			if (params.get("noWorkbench") === "true" || params.get("no-workbench") === "true") return false;
+		}
 		return this.workbench;
 	}
 	/** @internal */
 	wrapWithWorkbench() {
 		const workbench = document.createElement("ef-workbench");
 		const parent = this.parentElement;
+		if (EF_RENDERING()) {
+			workbench.setAttribute("rendering", "");
+			workbench.rendering = true;
+		}
 		if (parent === document.body) {
 			workbench.style.position = "fixed";
 			workbench.style.top = "0";
@@ -1234,6 +1286,12 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			workbench.style.width = "100vw";
 			workbench.style.height = "100vh";
 			workbench.style.zIndex = "0";
+		} else {
+			workbench.style.position = "absolute";
+			workbench.style.top = "0";
+			workbench.style.left = "0";
+			workbench.style.width = "100%";
+			workbench.style.height = "100%";
 		}
 		parent?.append(workbench);
 		if (!this.hasAttribute("id")) this.setAttribute("id", "root-timegroup");
@@ -1246,8 +1304,8 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		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.width = `${rect.width}px`;
+		canvas.style.height = `${rect.height}px`;
 		canvas.style.display = "block";
 		canvas.append(this);
 		panZoom.append(canvas);
@@ -1262,9 +1320,6 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		filmstrip.setAttribute("target", this.id);
 		workbench.append(filmstrip);
 	}
-	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
@@ -1283,80 +1338,6 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	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) {
-		const renderedBuffer = await this.renderAudio(fromMs, toMs);
-		const playbackContext = new AudioContext();
-		const bufferSource = playbackContext.createBufferSource();
-		bufferSource.buffer = renderedBuffer;
-		bufferSource.connect(playbackContext.destination);
-		bufferSource.start(0);
-		return new Promise((resolve) => {
-			bufferSource.onended = () => {
-				playbackContext.close();
-				resolve();
-			};
-		});
-	}
-	async #loadMd5Sums() {
-		const efElements = this.#efElements;
-		const loaderTasks = [];
-		for (const el of efElements) {
-			const md5SumLoader = el.md5SumLoader;
-			if (md5SumLoader && typeof md5SumLoader.run === "function") {
-				md5SumLoader.run().catch(() => {});
-				if (md5SumLoader.taskComplete) loaderTasks.push(md5SumLoader.taskComplete);
-			}
-		}
-		await Promise.all(loaderTasks);
-		efElements.forEach((el) => {
-			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;
-	}
-	/** @internal */
-	#frameTaskPromise = Promise.resolve();
-	#frameTaskAbortController = null;
-	async #runFrameTask(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;
-		try {
-			signal.throwIfAborted();
-			if (this.isRootTimegroup) await withSpan("timegroup.frameTask", {
-				timegroupId: this.id || "unknown",
-				ownCurrentTimeMs: this.ownCurrentTimeMs,
-				currentTimeMs: this.currentTimeMs
-			}, void 0, async () => {
-				await this.#frameController.renderFrame(this.currentTimeMs, {
-					waitForLitUpdate: false,
-					onAnimationsUpdate: (root) => {
-						updateAnimations(root);
-					}
-				});
-				signal.throwIfAborted();
-				await this.#executeCustomFrameTasks();
-			});
-			else await this.#executeCustomFrameTasks();
-		} catch (error) {
-			if (error instanceof DOMException && error.name === "AbortError") return;
-			console.error("EFTimegroup frameTask error", error);
-		}
-	}
 	async #executeCustomFrameTasks() {
 		if (this.#customFrameTasks.size > 0) {
 			const percentComplete = this.durationMs > 0 ? this.ownCurrentTimeMs / this.durationMs : 0;
@@ -1462,7 +1443,7 @@ __decorate([property({
 	type: Number,
 	attribute: "currenttime"
 })], EFTimegroup.prototype, "currentTime", null);
-EFTimegroup = _EFTimegroup = __decorate([customElement("ef-timegroup")], EFTimegroup);
+EFTimegroup = __decorate([customElement("ef-timegroup")], EFTimegroup);
 
 //#endregion
 export { EFTimegroup, flushSequenceDurationCache, shallowGetTimegroups };