@editframe/elements 0.35.0-beta → 0.36.0-beta

package/dist/elements/EFTimegroup.js

@@ -8,7 +8,7 @@ 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 } from "../preview/FrameController.js";
+import { FrameController, PRIORITY_DEFAULT } from "../preview/FrameController.js";
 import { renderTemporalAudio } from "./renderTemporalAudio.js";
 import { EFTargetable } from "./TargetController.js";
 import { deepGetMediaElements } from "./EFMedia.js";
@@ -251,6 +251,65 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
     }
   `;
 	}
+	#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');
+	* tg.initializer = (instance) => {
+	*   // Runs once on prime timeline, once on each clone
+	*   instance.addFrameTask((info) => {
+	*     // Update content based on time
+	*   });
+	* };
+	* ```
+	* @public
+	*/
+	get initializer() {
+		return this.#initializer;
+	}
+	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);
@@ -293,6 +352,35 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		return this.#frameController;
 	}
 	/**
+	* Query timegroup's readiness state for a given time.
+	* Timegroups are always ready (no async preparation needed).
+	* @public
+	*/
+	getFrameState(_timeMs) {
+		return {
+			needsPreparation: false,
+			isReady: true,
+			priority: PRIORITY_DEFAULT
+		};
+	}
+	/**
+	* Async preparation phase (no-op for timegroups).
+	* Timegroups don't need preparation - they just coordinate child rendering.
+	* @public
+	*/
+	async prepareFrame(_timeMs, _signal) {}
+	/**
+	* Synchronous render phase - executes custom frame callbacks.
+	* Called by FrameController after all preparation is complete.
+	* Kicks off async frame callbacks without blocking (they run in background).
+	* @public
+	*/
+	renderFrame(_timeMs) {
+		if (this.#customFrameTasks.size > 0) this.#executeCustomFrameTasks().catch((error) => {
+			console.error("EFTimegroup custom frame task error:", error);
+		});
+	}
+	/**
 	* Get the effective FPS for this timegroup.
 	* During rendering, uses the render options FPS if available.
 	* Otherwise uses the configured fps property.
@@ -566,6 +654,9 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	}
 	connectedCallback() {
 		super.connectedCallback();
+		this.updateComplete.then(() => {
+			this.#runInitializer();
+		});
 		requestAnimationFrame(() => {
 			requestAnimationFrame(() => {
 				if (this.parentTimegroup) new TimegroupController(this.parentTimegroup, this);
@@ -689,15 +780,16 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	}
 	/**
 	* Runs the initializer function with validation for synchronous execution and time budget.
-	* @throws Error if no initializer is set
+	* Only runs once per instance. Safe to call multiple times - will skip if already run.
 	* @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;
+	#runInitializer() {
+		if (!this.initializer || this.#initializerHasRun) return;
+		this.#initializerHasRun = true;
 		const startTime = performance.now();
-		const result = this.initializer(cloneEl);
+		const result = this.initializer(this);
 		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.`);
@@ -742,9 +834,10 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 	* so we must manually copy them to the cloned elements.
 	* @internal
 	*/
-	#copyTextSegmentData(original, clone) {
+	async #copyTextSegmentData(original, clone) {
 		const originalSegments = original.querySelectorAll("ef-text-segment");
 		const cloneSegments = clone.querySelectorAll("ef-text-segment");
+		const updatePromises = [];
 		for (let i = 0; i < originalSegments.length && i < cloneSegments.length; i++) {
 			const origSeg = originalSegments[i];
 			const cloneSeg = cloneSegments[i];
@@ -753,7 +846,9 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 			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;
+			if (cloneSeg.updateComplete) updatePromises.push(cloneSeg.updateComplete);
 		}
+		await Promise.all(updatePromises);
 	}
 	/**
 	* Wait for all ef-captions elements to have their data loaded.
@@ -773,6 +868,29 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		if (waitPromises.length > 0) await Promise.all(waitPromises);
 	}
 	/**
+	* Copies initializers from original timegroup tree to cloned timegroup tree.
+	* Handles both the root timegroup and all nested timegroups recursively.
+	* @internal
+	*/
+	async #copyInitializersToClone(original, clone) {
+		const initializerPromises = [];
+		if (original.initializer) {
+			clone.initializer = original.initializer;
+			if (clone.initializerComplete) initializerPromises.push(clone.initializerComplete);
+		}
+		const originalNested = Array.from(original.querySelectorAll("ef-timegroup"));
+		const cloneNested = Array.from(clone.querySelectorAll("ef-timegroup"));
+		for (let i = 0; i < originalNested.length && i < cloneNested.length; i++) {
+			const origNested = originalNested[i];
+			const cloneNestedItem = cloneNested[i];
+			if (origNested.initializer) {
+				cloneNestedItem.initializer = origNested.initializer;
+				if (cloneNestedItem.initializerComplete) initializerPromises.push(cloneNestedItem.initializerComplete);
+			}
+		}
+		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).
@@ -813,8 +931,8 @@ let EFTimegroup = class EFTimegroup$1 extends EFTargetable(EFTemporal(TWMixin(Li
 		} else container.appendChild(cloneEl);
 		document.body.appendChild(container);
 		await cloneEl.updateComplete;
-		this.#copyTextSegmentData(this, cloneEl);
-		this.#runInitializer(cloneEl);
+		await this.#copyInitializersToClone(this, cloneEl);
+		await this.#copyTextSegmentData(this, 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");
@@ -822,6 +940,7 @@ 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.#copyTextSegmentData(this, actualClone);
 		const setupParentChildRelationships = (parent, root) => {
 			for (const child of parent.children) if (child.tagName === "EF-TIMEGROUP") {
 				const childTG = child;