@editframe/elements 0.30.1-beta.0 → 0.31.0-beta.0

package/dist/elements/updateAnimations.js

@@ -1,4 +1,4 @@
-import { deepGetTemporalElements } from "./EFTemporal.js";
+import { deepGetTemporalElements, isEFTemporal } from "./EFTemporal.js";
 
 //#region src/elements/updateAnimations.ts
 const ANIMATION_PRECISION_OFFSET = .1;
@@ -8,144 +8,527 @@ const DURATION_PROPERTY = "--ef-duration";
 const TRANSITION_DURATION_PROPERTY = "--ef-transition-duration";
 const TRANSITION_OUT_START_PROPERTY = "--ef-transition-out-start";
 /**
-* Evaluates what the element's state should be based on the timeline
+* Tracks animations per element to prevent them from being lost when they complete.
+* Once an animation reaches 100% completion, it's removed from getAnimations(),
+* but we keep a reference to it so we can continue controlling it.
+*/
+const animationTracker = /* @__PURE__ */ new WeakMap();
+/**
+* Tracks whether DOM structure has changed for an element, requiring animation rediscovery.
+* For render clones (static DOM), this stays false after initial discovery.
+* For prime timeline (interactive), this is set to true when mutations occur.
+*/
+const domStructureChanged = /* @__PURE__ */ new WeakMap();
+/**
+* Tracks the last known animation count for an element to detect new animations.
+* Used as a lightweight check before calling expensive getAnimations().
+*/
+const lastAnimationCount = /* @__PURE__ */ new WeakMap();
+/**
+* Checks if an element is in a render clone (static DOM context).
+* Render clones are in containers with class "ef-render-clone-container".
+*/
+const isRenderClone = (element) => {
+	return element.closest(".ef-render-clone-container") !== null;
+};
+/**
+* Validates that an animation is still valid and controllable.
+* Animations become invalid when:
+* - They've been cancelled (idle state and not in getAnimations())
+* - Their effect is null (animation was removed)
+* - Their target is no longer in the DOM
+*/
+const isAnimationValid = (animation, currentAnimations) => {
+	if (animation.playState === "idle" && !currentAnimations.includes(animation)) return false;
+	const effect = animation.effect;
+	if (!effect) return false;
+	if (effect instanceof KeyframeEffect) {
+		const target = effect.target;
+		if (target && target instanceof Element) {
+			if (!target.isConnected) return false;
+		}
+	}
+	return true;
+};
+/**
+* Discovers and tracks animations on an element and its subtree.
+* This ensures we have references to animations even after they complete.
+*
+* Tracks animations per element where they exist, not just on the root element.
+* This allows us to find animations on any element in the subtree.
+*
+* OPTIMIZATION: For render clones (static DOM), discovery happens once at creation.
+* For prime timeline (interactive), discovery is responsive to DOM changes.
+*
+* Also cleans up invalid animations (cancelled, removed from DOM, etc.)
+*/
+const discoverAndTrackAnimations = (element) => {
+	const isClone = isRenderClone(element);
+	const hasTrackedAnimations = animationTracker.has(element);
+	const structureChanged = domStructureChanged.get(element) ?? true;
+	if (isClone && hasTrackedAnimations && !structureChanged) {
+		const rootTracked$1 = animationTracker.get(element);
+		const currentAnimations$1 = [];
+		const rootDirectAnimations = element.getAnimations();
+		for (const animation of rootTracked$1) if (isAnimationValid(animation, rootDirectAnimations)) currentAnimations$1.push(animation);
+		return {
+			tracked: rootTracked$1,
+			current: currentAnimations$1
+		};
+	}
+	const currentAnimations = element.getAnimations({ subtree: true });
+	if (isClone) domStructureChanged.set(element, false);
+	lastAnimationCount.set(element, currentAnimations.length);
+	for (const animation of currentAnimations) {
+		const effect = animation.effect;
+		const target = effect && effect instanceof KeyframeEffect ? effect.target : null;
+		if (target && target instanceof Element) {
+			let tracked = animationTracker.get(target);
+			if (!tracked) {
+				tracked = /* @__PURE__ */ new Set();
+				animationTracker.set(target, tracked);
+			}
+			tracked.add(animation);
+		}
+	}
+	let rootTracked = animationTracker.get(element);
+	if (!rootTracked) {
+		rootTracked = /* @__PURE__ */ new Set();
+		animationTracker.set(element, rootTracked);
+	}
+	for (const animation of currentAnimations) rootTracked.add(animation);
+	for (const animation of rootTracked) if (!isAnimationValid(animation, currentAnimations)) rootTracked.delete(animation);
+	const allTargets = /* @__PURE__ */ new Set();
+	for (const animation of currentAnimations) {
+		const effect = animation.effect;
+		const target = effect && effect instanceof KeyframeEffect ? effect.target : null;
+		if (target && target instanceof Element) allTargets.add(target);
+	}
+	const subtreeElements = element.querySelectorAll("*");
+	for (const el of subtreeElements) {
+		const tracked = animationTracker.get(el);
+		if (tracked) {
+			for (const animation of tracked) if (!isAnimationValid(animation, Array.from(el.getAnimations()))) tracked.delete(animation);
+			if (tracked.size === 0) animationTracker.delete(el);
+		}
+	}
+	return {
+		tracked: rootTracked,
+		current: currentAnimations
+	};
+};
+/**
+* Cleans up tracked animations when an element is disconnected.
+* This prevents memory leaks.
+*/
+const cleanupTrackedAnimations = (element) => {
+	animationTracker.delete(element);
+	domStructureChanged.delete(element);
+	lastAnimationCount.delete(element);
+};
+/**
+* Determines what phase an element is in relative to the timeline.
+*
+* WHY: Phase is the primary concept that drives all decisions. By explicitly
+* enumerating phases, we make the code's logic clear: phase determines visibility,
+* animation coordination, and visual state.
+*
+* Phases:
+* - before-start: Timeline is before element's start time
+* - active: Timeline is within element's active range (start to end, exclusive of end)
+* - at-end-boundary: Timeline is exactly at element's end time
+* - after-end: Timeline is after element's end time
+*
+* Note: We detect "at-end-boundary" by checking if timeline equals end time.
+* The boundary policy will then determine if this should be treated as visible/active
+* or not based on element characteristics.
+*/
+const determineElementPhase = (element, timelineTimeMs) => {
+	const endTimeMs = element.endTimeMs;
+	const startTimeMs = element.startTimeMs;
+	if (endTimeMs <= startTimeMs) return "active";
+	if (timelineTimeMs < startTimeMs) return "before-start";
+	const epsilon = .001;
+	const diff = timelineTimeMs - endTimeMs;
+	if (diff > epsilon) return "after-end";
+	if (Math.abs(diff) <= epsilon) return "at-end-boundary";
+	return "active";
+};
+/**
+* Visibility policy: determines when elements should be visible for display purposes.
+*
+* WHY: Root elements, elements aligned with composition end, and text segments
+* should remain visible at exact end time to prevent flicker and show final frames.
+* Other elements use exclusive end for clean transitions between elements.
+*/
+var VisibilityPolicy = class {
+	shouldIncludeEndBoundary(element) {
+		if (!element.parentTimegroup) return true;
+		if (element.endTimeMs === element.rootTimegroup?.endTimeMs) return true;
+		if (this.isTextSegment(element)) return true;
+		return false;
+	}
+	/**
+	* Checks if element is a text segment.
+	* Encapsulates the tag name check to hide implementation detail.
+	*/
+	isTextSegment(element) {
+		return element.tagName === "EF-TEXT-SEGMENT";
+	}
+};
+/**
+* Animation policy: determines when animations should be coordinated.
+*
+* WHY: When an animation reaches exactly the end time of an element, using exclusive
+* end would make the element invisible, causing the animation to be removed from the
+* DOM and creating a visual jump. By using inclusive end, we ensure animations remain
+* coordinated even at exact boundary times, providing smooth visual transitions.
+*/
+var AnimationPolicy = class {
+	shouldIncludeEndBoundary(_element) {
+		return true;
+	}
+};
+const visibilityPolicy = new VisibilityPolicy();
+const animationPolicy = new AnimationPolicy();
+/**
+* Determines if an element should be visible based on its phase and visibility policy.
+*/
+const shouldBeVisible = (phase, element) => {
+	if (phase === "before-start" || phase === "after-end") return false;
+	if (phase === "active") return true;
+	return visibilityPolicy.shouldIncludeEndBoundary(element);
+};
+/**
+* Determines if animations should be coordinated based on element phase and animation policy.
+*/
+const shouldCoordinateAnimations = (phase, element) => {
+	if (phase === "before-start" || phase === "after-end") return false;
+	if (phase === "active") return true;
+	return animationPolicy.shouldIncludeEndBoundary(element);
+};
+/**
+* Evaluates what the element's state should be based on the timeline.
+*
+* WHY: This function determines the complete temporal state including phase,
+* which becomes the primary driver for all subsequent decisions.
 */
 const evaluateTemporalState = (element) => {
 	const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;
 	const progress = element.durationMs <= 0 ? 1 : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));
-	const isRootElement = !element.parentTimegroup;
-	const isLastElementInComposition = element.endTimeMs === element.rootTimegroup?.endTimeMs;
-	const isTextSegment = element.tagName === "EF-TEXT-SEGMENT";
-	const useInclusiveEnd = isRootElement || isLastElementInComposition || isTextSegment;
+	const phase = determineElementPhase(element, timelineTimeMs);
 	return {
 		progress,
-		isVisible: element.startTimeMs <= timelineTimeMs && (useInclusiveEnd ? element.endTimeMs >= timelineTimeMs : element.endTimeMs > timelineTimeMs),
-		timelineTimeMs
+		isVisible: shouldBeVisible(phase, element),
+		timelineTimeMs,
+		phase
 	};
 };
 /**
-* Evaluates element visibility specifically for animation coordination
-* Uses inclusive end boundaries to prevent animation jumps at exact boundaries
+* Evaluates element visibility state specifically for animation coordination.
+* Uses inclusive end boundaries to prevent animation jumps at exact boundaries.
+*
+* This is exported for external use cases that need animation-specific visibility
+* evaluation without the full ElementUpdateContext.
 */
-const evaluateTemporalStateForAnimation = (element) => {
-	const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;
+const evaluateAnimationVisibilityState = (element) => {
+	const state = evaluateTemporalState(element);
+	const shouldCoordinate = shouldCoordinateAnimations(state.phase, element);
 	return {
-		progress: element.durationMs <= 0 ? 1 : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs)),
-		isVisible: element.startTimeMs <= timelineTimeMs && element.endTimeMs >= timelineTimeMs,
-		timelineTimeMs
+		...state,
+		isVisible: shouldCoordinate
 	};
 };
 /**
-* Updates the visual state (CSS + display) to match temporal state
+* Capability check: determines if an element supports stagger offset.
+* Encapsulates the knowledge of which element types support this feature.
 */
-const updateVisualState = (element, state) => {
-	element.style.setProperty(PROGRESS_PROPERTY, `${state.progress * 100}%`);
+const supportsStaggerOffset = (element) => {
+	return element.tagName === "EF-TEXT-SEGMENT";
+};
+/**
+* Calculates effective delay including stagger offset if applicable.
+*
+* Stagger offset allows elements (like text segments) to have their animations
+* start at different times while keeping their visibility timing unchanged.
+* This enables staggered animation effects within a single timegroup.
+*/
+const calculateEffectiveDelay = (delay, element) => {
+	if (supportsStaggerOffset(element)) {
+		const segment = element;
+		if (segment.staggerOffsetMs !== void 0 && segment.staggerOffsetMs !== null) return delay + segment.staggerOffsetMs;
+		let cssValue = element.style.getPropertyValue("--ef-stagger-offset").trim();
+		if (!cssValue) cssValue = window.getComputedStyle(element).getPropertyValue("--ef-stagger-offset").trim();
+		if (cssValue) {
+			const match = cssValue.match(/(\d+(?:\.\d+)?)\s*ms?/);
+			if (match) {
+				const staggerOffset = parseFloat(match[1]);
+				if (!isNaN(staggerOffset)) return delay + staggerOffset;
+			} else {
+				const numValue = parseFloat(cssValue);
+				if (!isNaN(numValue)) return delay + numValue;
+			}
+		}
+	}
+	return delay;
+};
+/**
+* Calculates maximum safe animation time to prevent completion.
+*
+* WHY: Once an animation reaches "finished" state, it can no longer be manually controlled
+* via currentTime. By clamping to just before completion (using ANIMATION_PRECISION_OFFSET),
+* we ensure the animation remains in a controllable state, allowing us to synchronize it
+* with the timeline even when it would naturally be complete.
+*/
+const calculateMaxSafeAnimationTime = (duration, iterations) => {
+	return duration * iterations - ANIMATION_PRECISION_OFFSET;
+};
+/**
+* Determines if the current iteration should be reversed based on direction
+*/
+const shouldReverseIteration = (direction, currentIteration) => {
+	return direction === "reverse" || direction === "alternate" && currentIteration % 2 === 1 || direction === "alternate-reverse" && currentIteration % 2 === 0;
+};
+/**
+* Applies direction to iteration time (reverses if needed)
+*/
+const applyDirectionToIterationTime = (currentIterationTime, duration, direction, currentIteration) => {
+	if (shouldReverseIteration(direction, currentIteration)) return duration - currentIterationTime;
+	return currentIterationTime;
+};
+/**
+* Maps element time to animation time for normal direction.
+* Uses cumulative time throughout the animation.
+* Note: elementTime should already be adjusted (elementTime - effectiveDelay).
+*/
+const mapNormalDirectionTime = (elementTime, duration, maxSafeTime) => {
+	const currentIteration = Math.floor(elementTime / duration);
+	const iterationTime = elementTime % duration;
+	const cumulativeTime = currentIteration * duration + iterationTime;
+	return Math.min(cumulativeTime, maxSafeTime);
+};
+/**
+* Maps element time to animation time for reverse direction.
+* Uses cumulative time with reversed iterations.
+* Note: elementTime should already be adjusted (elementTime - effectiveDelay).
+*/
+const mapReverseDirectionTime = (elementTime, duration, maxSafeTime) => {
+	const currentIteration = Math.floor(elementTime / duration);
+	const reversedIterationTime = duration - elementTime % duration;
+	const cumulativeTime = currentIteration * duration + reversedIterationTime;
+	return Math.min(cumulativeTime, maxSafeTime);
+};
+/**
+* Maps element time to animation time for alternate/alternate-reverse directions.
+*
+* WHY SPECIAL HANDLING: Alternate directions oscillate between forward and reverse iterations.
+* Without delay, we use iteration time (0 to duration) because the animation naturally
+* resets each iteration. However, with delay, iteration 0 needs to account for the delay
+* offset (using ownCurrentTimeMs), and later iterations need cumulative time to properly
+* track progress across multiple iterations. This complexity requires a dedicated mapper
+* rather than trying to handle it in the general case.
+*/
+const mapAlternateDirectionTime = (elementTime, effectiveDelay, duration, direction, maxSafeTime) => {
+	const adjustedTime = elementTime - effectiveDelay;
+	if (effectiveDelay > 0) {
+		if (Math.floor(adjustedTime / duration) === 0) return Math.min(elementTime, maxSafeTime);
+		return Math.min(adjustedTime, maxSafeTime);
+	}
+	const currentIteration = Math.floor(elementTime / duration);
+	const iterationTime = applyDirectionToIterationTime(elementTime % duration, duration, direction, currentIteration);
+	return Math.min(iterationTime, maxSafeTime);
+};
+/**
+* Maps element time to animation time based on direction.
+*
+* WHY: This function explicitly transforms element time to animation time, making
+* the time mapping concept clear. Different directions require different transformations
+* to achieve the desired visual effect.
+*/
+const mapElementTimeToAnimationTime = (elementTime, timing, effectiveDelay) => {
+	const { duration, iterations, direction } = timing;
+	const maxSafeTime = calculateMaxSafeAnimationTime(duration, iterations);
+	const adjustedTime = elementTime - effectiveDelay;
+	if (direction === "reverse") return mapReverseDirectionTime(adjustedTime, duration, maxSafeTime);
+	if (direction === "alternate" || direction === "alternate-reverse") return mapAlternateDirectionTime(elementTime, effectiveDelay, duration, direction, maxSafeTime);
+	return mapNormalDirectionTime(adjustedTime, duration, maxSafeTime);
+};
+/**
+* Determines the animation time for a completed animation based on direction.
+*/
+const getCompletedAnimationTime = (timing, maxSafeTime) => {
+	const { direction, iterations, duration } = timing;
+	if (direction === "alternate" || direction === "alternate-reverse") {
+		const finalIteration = iterations - 1;
+		if (direction === "alternate" && finalIteration % 2 === 1 || direction === "alternate-reverse" && finalIteration % 2 === 0) return Math.min(duration - ANIMATION_PRECISION_OFFSET, maxSafeTime);
+	}
+	return maxSafeTime;
+};
+/**
+* Validates that animation effect is a KeyframeEffect with a target
+*/
+const validateAnimationEffect = (effect) => {
+	return effect !== null && effect instanceof KeyframeEffect && effect.target !== null;
+};
+/**
+* Extracts timing information from an animation effect.
+* Duration and delay from getTiming() are already in milliseconds.
+* We use getTiming().delay directly from the animation object.
+*/
+const extractAnimationTiming = (effect) => {
+	const timing = effect.getTiming();
+	return {
+		duration: Number(timing.duration) || 0,
+		delay: Number(timing.delay) || 0,
+		iterations: Number(timing.iterations) || DEFAULT_ANIMATION_ITERATIONS,
+		direction: timing.direction || "normal"
+	};
+};
+/**
+* Prepares animation for manual control by ensuring it's paused
+*/
+const prepareAnimation = (animation) => {
+	if (animation.playState === "finished") animation.cancel();
+	else if (animation.playState === "running") animation.pause();
+};
+/**
+* Maps element time to animation currentTime and sets it on the animation.
+*
+* WHY: This function explicitly performs the time mapping transformation,
+* making it clear that we're transforming element time to animation time.
+*/
+const mapAndSetAnimationTime = (animation, element, timing, effectiveDelay) => {
+	const elementTime = element.ownCurrentTimeMs ?? 0;
+	if (animation.playState === "running") animation.pause();
+	const adjustedTime = elementTime - effectiveDelay;
+	if (adjustedTime < 0) {
+		if (timing.delay > 0) animation.currentTime = elementTime;
+		else animation.currentTime = 0;
+		return;
+	}
+	const { duration, iterations } = timing;
+	const currentIteration = Math.floor(adjustedTime / duration);
+	if (currentIteration >= iterations) {
+		const completedAnimationTime = getCompletedAnimationTime(timing, calculateMaxSafeAnimationTime(duration, iterations));
+		if (timing.delay > 0) animation.currentTime = effectiveDelay + completedAnimationTime;
+		else animation.currentTime = completedAnimationTime;
+	} else {
+		const animationTime = mapElementTimeToAnimationTime(elementTime, timing, effectiveDelay);
+		const { direction, delay } = timing;
+		if (delay > 0) if ((direction === "alternate" || direction === "alternate-reverse") && effectiveDelay > 0 && currentIteration === 0) animation.currentTime = elementTime;
+		else animation.currentTime = effectiveDelay + animationTime;
+		else animation.currentTime = animationTime;
+	}
+};
+/**
+* Synchronizes a single animation with the timeline using the element as the time source.
+*
+* For animations in this element's subtree, always use this element as the time source.
+* This handles both animations directly on the temporal element and on its non-temporal children.
+*/
+const synchronizeAnimation = (animation, element) => {
+	const effect = animation.effect;
+	if (!validateAnimationEffect(effect)) return;
+	const timing = extractAnimationTiming(effect);
+	if (timing.duration <= 0) {
+		animation.currentTime = 0;
+		return;
+	}
+	const target = effect.target;
+	let timeSource = element;
+	if (target && target instanceof HTMLElement) {
+		const nearestTimegroup = target.closest("ef-timegroup");
+		if (nearestTimegroup && isEFTemporal(nearestTimegroup)) timeSource = nearestTimegroup;
+	}
+	let staggerElement = timeSource;
+	if (target && target instanceof HTMLElement) {
+		const targetAsAnimatable = target;
+		if (supportsStaggerOffset(targetAsAnimatable)) staggerElement = targetAsAnimatable;
+		else {
+			const parentSegment = target.closest("ef-text-segment");
+			if (parentSegment && supportsStaggerOffset(parentSegment)) staggerElement = parentSegment;
+		}
+	}
+	const effectiveDelay = calculateEffectiveDelay(timing.delay, staggerElement);
+	mapAndSetAnimationTime(animation, timeSource, timing, effectiveDelay);
+};
+/**
+* Coordinates animations for a single element and its subtree, using the element as the time source.
+*
+* Uses tracked animations to ensure we can control animations even after they complete.
+* Both CSS animations (created via the 'animation' property) and WAAPI animations are included.
+*
+* CRITICAL: CSS animations are created asynchronously when classes are added. This function
+* discovers new animations on each call and tracks them in memory. Once animations complete,
+* they're removed from getAnimations(), but we keep references to them so we can continue
+* controlling them.
+*/
+const coordinateElementAnimations = (element) => {
+	const { tracked: trackedAnimations, current: currentAnimations } = discoverAndTrackAnimations(element);
+	for (const animation of trackedAnimations) {
+		if (!isAnimationValid(animation, currentAnimations)) continue;
+		prepareAnimation(animation);
+		synchronizeAnimation(animation, element);
+	}
+};
+/**
+* Applies visual state (CSS + display) to match temporal state.
+*
+* WHY: This function applies visual state based on the element's phase and state.
+* Phase determines what should be visible, and this function applies that decision.
+*/
+const applyVisualState = (element, state) => {
+	element.style.setProperty(PROGRESS_PROPERTY, `${state.progress}`);
 	if (!state.isVisible) {
-		if (element.style.display !== "none") element.style.display = "none";
+		element.style.setProperty("display", "none");
 		return;
 	}
-	if (element.style.display === "none") element.style.display = "";
+	element.style.removeProperty("display");
 	element.style.setProperty(DURATION_PROPERTY, `${element.durationMs}ms`);
 	element.style.setProperty(TRANSITION_DURATION_PROPERTY, `${element.parentTimegroup?.overlapMs ?? 0}ms`);
 	element.style.setProperty(TRANSITION_OUT_START_PROPERTY, `${element.durationMs - (element.parentTimegroup?.overlapMs ?? 0)}ms`);
 };
 /**
-* Coordinates animations for a single element and its subtree, using the element as the time source
+* Applies animation coordination if the element phase requires it.
+*
+* WHY: Animation coordination is driven by phase. If the element is in a phase
+* where animations should be coordinated, we coordinate them.
 */
-const coordinateAnimationsForSingleElement = (element) => {
-	const animations = element.getAnimations({ subtree: true });
-	for (const animation of animations) {
-		if (animation.playState === "finished") {
-			animation.cancel();
-			animation.play();
-			animation.pause();
-		} else if (animation.playState === "running") animation.pause();
-		const effect = animation.effect;
-		if (!(effect && effect instanceof KeyframeEffect)) continue;
-		const target = effect.target;
-		if (!target) continue;
-		const timing = effect.getTiming();
-		const duration = Number(timing.duration) || 0;
-		let delay = Number(timing.delay) || 0;
-		if (target instanceof HTMLElement) {
-			const animationDelays = window.getComputedStyle(target).animationDelay.split(", ").map((s) => s.trim());
-			const parseDelay = (delayStr) => {
-				if (delayStr === "0s" || delayStr === "0ms") return 0;
-				const delayMatch = delayStr.match(/^([\d.]+)(s|ms)$/);
-				if (delayMatch?.[1] && delayMatch[2]) {
-					const value = Number.parseFloat(delayMatch[1]);
-					return delayMatch[2] === "s" ? value * 1e3 : value;
-				}
-				return 0;
-			};
-			if (animationDelays.length === 1 && animationDelays[0]) {
-				const parsedDelay = parseDelay(animationDelays[0]);
-				if (parsedDelay > 0) delay = parsedDelay;
-				else if ((animationDelays[0] === "0s" || animationDelays[0] === "0ms") && delay === 0) delay = 0;
-			} else if (animationDelays.length > 1) {
-				const animationIndex = Array.from(target.getAnimations()).indexOf(animation);
-				if (animationIndex >= 0 && animationIndex < animationDelays.length && animationDelays[animationIndex]) {
-					const parsedDelay = parseDelay(animationDelays[animationIndex]);
-					if (parsedDelay > 0) delay = parsedDelay;
-				}
-			}
-		}
-		const iterations = Number(timing.iterations) || DEFAULT_ANIMATION_ITERATIONS;
-		if (duration <= 0) {
-			animation.currentTime = 0;
-			continue;
-		}
-		const currentTime = element.ownCurrentTimeMs ?? 0;
-		let effectiveDelay = delay;
-		if (element.tagName === "EF-TEXT-SEGMENT" && element.staggerOffsetMs !== void 0) {
-			const staggerOffsetMs = element.staggerOffsetMs;
-			effectiveDelay = delay + staggerOffsetMs;
-		}
-		if (currentTime < effectiveDelay) {
-			animation.currentTime = 0;
-			continue;
-		}
-		const adjustedTime = currentTime - effectiveDelay;
-		const currentIteration = Math.floor(adjustedTime / duration);
-		let currentIterationTime = adjustedTime % duration;
-		const direction = timing.direction || "normal";
-		const isAlternate = direction === "alternate" || direction === "alternate-reverse";
-		if (direction === "reverse" || direction === "alternate" && currentIteration % 2 === 1 || direction === "alternate-reverse" && currentIteration % 2 === 0) currentIterationTime = duration - currentIterationTime;
-		if (currentIteration >= iterations) {
-			const maxSafeAnimationTime = duration * iterations - ANIMATION_PRECISION_OFFSET;
-			if (isAlternate) {
-				const finalIteration = iterations - 1;
-				if (direction === "alternate" && finalIteration % 2 === 1 || direction === "alternate-reverse" && finalIteration % 2 === 0) animation.currentTime = Math.min(duration - ANIMATION_PRECISION_OFFSET, maxSafeAnimationTime);
-				else animation.currentTime = maxSafeAnimationTime;
-			} else animation.currentTime = maxSafeAnimationTime;
-		} else if (isAlternate) if (effectiveDelay > 0) if (currentIteration === 0) animation.currentTime = currentTime;
-		else {
-			const maxSafeAnimationTime = duration * iterations - ANIMATION_PRECISION_OFFSET;
-			animation.currentTime = Math.min(adjustedTime, maxSafeAnimationTime);
-		}
-		else animation.currentTime = currentIterationTime;
-		else {
-			const timeWithinAnimation = currentIteration * duration + currentIterationTime;
-			const maxSafeAnimationTime = duration * iterations - ANIMATION_PRECISION_OFFSET;
-			animation.currentTime = Math.min(timeWithinAnimation, maxSafeAnimationTime);
-		}
-	}
+const applyAnimationCoordination = (element, phase) => {
+	if (shouldCoordinateAnimations(phase, element)) coordinateElementAnimations(element);
+};
+/**
+* Evaluates the complete state for an element update.
+* This separates evaluation (what should the state be?) from application (apply that state).
+*/
+const evaluateElementState = (element) => {
+	return {
+		element,
+		state: evaluateTemporalState(element)
+	};
 };
 /**
-* Main function: synchronizes DOM element with timeline
+* Main function: synchronizes DOM element with timeline.
+*
+* Orchestrates clear flow: Phase → Policy → Time Mapping → State Application
+*
+* WHY: This function makes the conceptual flow explicit:
+* 1. Determine phase (what phase is the element in?)
+* 2. Apply policies (should it be visible/coordinated based on phase?)
+* 3. Map time for animations (transform element time to animation time)
+* 4. Apply visual state (update CSS and display based on phase and policies)
 */
 const updateAnimations = (element) => {
-	const temporalState = evaluateTemporalState(element);
-	deepGetTemporalElements(element).forEach((temporalElement) => {
-		updateVisualState(temporalElement, evaluateTemporalState(temporalElement));
-	});
-	updateVisualState(element, temporalState);
-	if (evaluateTemporalStateForAnimation(element).isVisible) coordinateAnimationsForSingleElement(element);
-	deepGetTemporalElements(element).forEach((temporalElement) => {
-		if (evaluateTemporalStateForAnimation(temporalElement).isVisible) coordinateAnimationsForSingleElement(temporalElement);
+	const rootContext = evaluateElementState(element);
+	const childContexts = deepGetTemporalElements(element).map((temporalElement) => evaluateElementState(temporalElement));
+	applyVisualState(rootContext.element, rootContext.state);
+	applyAnimationCoordination(rootContext.element, rootContext.state.phase);
+	childContexts.forEach((context) => {
+		applyVisualState(context.element, context.state);
+		applyAnimationCoordination(context.element, context.state.phase);
 	});
 };
 
 //#endregion
-export { evaluateTemporalStateForAnimation, updateAnimations };
+export { cleanupTrackedAnimations, evaluateAnimationVisibilityState, updateAnimations };
 //# sourceMappingURL=updateAnimations.js.map