@editframe/elements 0.19.2-beta.0 → 0.20.0-beta.0

package/src/elements/updateAnimations.browsertest.ts

@@ -1,4 +1,7 @@
+import { LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
 import { assert, beforeEach, describe, test } from "vitest";
+import { EFTemporal } from "./EFTemporal.js";
 import type { EFTimegroup } from "./EFTimegroup.js";
 import {
   type AnimatableElement,
@@ -7,19 +10,31 @@ import {
 
 import "./EFTimegroup.js";
 
-// Import the constant for tests that need to check animation precision
+// Create proper temporal test elements
+@customElement("test-temporal-element")
+class TestTemporalElement extends EFTemporal(LitElement) {
+  get intrinsicDurationMs() {
+    return this._durationMs;
+  }
+
+  private _durationMs = 1000;
+  setDuration(duration: number) {
+    this._durationMs = duration;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "test-temporal-element": TestTemporalElement;
+  }
+}
 
 beforeEach(() => {
   // Clean up DOM
   while (document.body.children.length) {
     document.body.children[0]?.remove();
   }
-  // Clean up localStorage
-  for (let i = 0; i < localStorage.length; i++) {
-    const key = localStorage.key(i);
-    if (typeof key !== "string") continue;
-    localStorage.removeItem(key);
-  }
+  window.localStorage.clear();
 });
 
 function createTestElement(
@@ -51,6 +66,10 @@ function createTestElement(
     value: props.parentTimegroup,
     writable: true,
   });
+  Object.defineProperty(element, "ownCurrentTimeMs", {
+    value: props.ownCurrentTimeMs ?? 0,
+    writable: true,
+  });
   document.body.appendChild(element);
   return element;
 }
@@ -214,6 +233,75 @@ describe("Timeline Element Synchronizer", () => {
       assert.equal(element.style.display, "");
     });
 
+    test("sequence elements remain coordinated at exact end boundary", () => {
+      // Create a root timegroup mock
+      const rootTimegroup = {
+        currentTimeMs: 3000,
+        durationMs: 3000,
+        startTimeMs: 0,
+        endTimeMs: 3000,
+        tagName: "EF-TIMEGROUP",
+      } as any;
+
+      // Create a child element in sequence that spans 2000-3000ms
+      const element = createTestElement({
+        startTimeMs: 2000,
+        endTimeMs: 3000,
+        durationMs: 1000,
+        ownCurrentTimeMs: 1000, // At exact end of its own duration
+        rootTimegroup: rootTimegroup,
+      });
+
+      // Create REAL animations using the Web Animations API
+      const animation1 = element.animate([{ opacity: 0 }, { opacity: 1 }], {
+        duration: 1000,
+        delay: 0,
+        iterations: 1,
+      });
+
+      const animation2 = element.animate(
+        [{ transform: "scale(1)" }, { transform: "scale(1.5)" }],
+        {
+          duration: 1000,
+          delay: 0,
+          iterations: 1,
+        },
+      );
+
+      // Start with animations running
+      animation1.play();
+      animation2.play();
+
+      // Verify we have real animations
+      const animations = element.getAnimations({ subtree: true });
+      assert.equal(animations.length, 2, "Should have 2 real animations");
+
+      updateAnimations(element);
+
+      // The element should be hidden due to exclusive end condition (3000 > 3000 = false)
+      assert.equal(
+        element.style.display,
+        "none",
+        "Element should be hidden at exact end boundary due to exclusive end",
+      );
+
+      // BUT animations should still be coordinated to prevent jarring visual jumps
+      // This is the fix we want: animations coordinated even when element is hidden at exact boundary
+      animations.forEach((animation, index) => {
+        assert.approximately(
+          animation.currentTime as number,
+          999,
+          1,
+          `Animation ${index + 1} should be coordinated at exact end boundary to prevent visual jumps`,
+        );
+        assert.equal(
+          animation.playState,
+          "paused",
+          `Animation ${index + 1} should be paused after coordination`,
+        );
+      });
+    });
+
     test("uses element currentTimeMs when no rootTimegroup", () => {
       const element = createTestElement({
         currentTimeMs: 500,
@@ -299,8 +387,6 @@ describe("Timeline Element Synchronizer", () => {
       });
       animation.play();
 
-      assert.equal(animation.playState, "running");
-
       updateAnimations(element);
 
       assert.equal(animation.playState, "paused");
@@ -367,9 +453,6 @@ describe("Timeline Element Synchronizer", () => {
       animation1.play();
       animation2.play();
 
-      assert.equal(animation1.playState, "running");
-      assert.equal(animation2.playState, "running");
-
       updateAnimations(element);
 
       // Both animations should be paused
@@ -415,6 +498,272 @@ describe("Timeline Element Synchronizer", () => {
 
       assert.equal(animation.playState, "paused");
     });
+
+    test("keeps completed animations available for scrubbing", async () => {
+      // Create a timegroup with 10s duration
+      const timegroup = document.createElement("ef-timegroup") as EFTimegroup;
+      timegroup.setAttribute("mode", "fixed");
+      timegroup.setAttribute("duration", "10000ms");
+      document.body.appendChild(timegroup);
+
+      // Create a child element with a 5s animation
+      const child = document.createElement("div");
+      timegroup.appendChild(child);
+
+      child.animate([{ opacity: 0 }, { opacity: 1 }], {
+        duration: 5000, // 5s animation
+        iterations: 1,
+        delay: 0,
+      });
+      timegroup.currentTime = 6;
+      await timegroup.seekTask.run();
+
+      // Animation should still be available even though timeline (6s) > animation duration (5s)
+      // This prevents animations from being removed, enabling scrubbing backwards
+      const animations = timegroup.getAnimations({ subtree: true });
+      assert.equal(
+        animations.length,
+        1,
+        "REGRESSION TEST: Animation should remain available for scrubbing. This would fail with Number.EPSILON due to insufficient precision offset.",
+      );
+    });
+  });
+
+  describe("child element animation coordination", () => {
+    test("coordinates animations on non-temporal child elements", async () => {
+      // Create root timegroup
+      const rootTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      rootTimegroup.currentTimeMs = 150; // Timeline at 150ms
+      document.body.appendChild(rootTimegroup);
+
+      // Create parent temporal element
+      const parentElement = document.createElement(
+        "test-temporal-element",
+      ) as TestTemporalElement;
+      parentElement.setDuration(300); // 300ms duration
+      parentElement.setAttribute("offset", "100ms"); // Start at 100ms in root timeline
+      rootTimegroup.appendChild(parentElement);
+
+      // Create a regular NON-temporal HTML element inside the temporal element
+      const nonTemporalDiv = document.createElement("div");
+      parentElement.appendChild(nonTemporalDiv);
+
+      // Wait for elements to be connected and updated
+      await rootTimegroup.updateComplete;
+      await parentElement.updateComplete;
+
+      // Create animation on the NON-temporal child element
+      const nonTemporalAnimation = nonTemporalDiv.animate(
+        [{ opacity: 0 }, { opacity: 1 }],
+        {
+          duration: 1000,
+        },
+      );
+      nonTemporalAnimation.play();
+
+      // Call updateAnimations on root timegroup
+      updateAnimations(rootTimegroup);
+
+      // Parent should be visible at current timeline position (150ms is between 100ms-400ms)
+      assert.notEqual(
+        parentElement.style.display,
+        "none",
+        "Parent should be visible at current timeline time",
+      );
+
+      // FIXED: Non-temporal child animation should be paused and coordinated
+      assert.equal(
+        nonTemporalAnimation.playState,
+        "paused",
+        "Non-temporal child element animation should be paused and coordinated with timeline",
+      );
+    });
+
+    test("coordinates animations on deeply nested non-temporal elements", async () => {
+      // Create root timegroup
+      const rootTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      rootTimegroup.currentTimeMs = 150; // Timeline at 150ms
+      document.body.appendChild(rootTimegroup);
+
+      // Create parent temporal element
+      const parentElement = document.createElement(
+        "test-temporal-element",
+      ) as TestTemporalElement;
+      parentElement.setDuration(300); // 300ms duration
+      parentElement.setAttribute("offset", "100ms"); // Start at 100ms in root timeline
+      rootTimegroup.appendChild(parentElement);
+
+      // Create nested non-temporal structure: temporal > div > div > span
+      const outerDiv = document.createElement("div");
+      const innerDiv = document.createElement("div");
+      const span = document.createElement("span");
+
+      parentElement.appendChild(outerDiv);
+      outerDiv.appendChild(innerDiv);
+      innerDiv.appendChild(span);
+
+      // Wait for elements to be connected and updated
+      await rootTimegroup.updateComplete;
+      await parentElement.updateComplete;
+
+      // Create animations on different levels of nesting
+      const outerAnimation = outerDiv.animate(
+        [{ transform: "scale(1)" }, { transform: "scale(1.1)" }],
+        {
+          duration: 800,
+        },
+      );
+      const innerAnimation = innerDiv.animate(
+        [{ opacity: 0.5 }, { opacity: 1 }],
+        {
+          duration: 1200,
+        },
+      );
+      const spanAnimation = span.animate(
+        [{ color: "red" }, { color: "blue" }],
+        {
+          duration: 600,
+        },
+      );
+
+      outerAnimation.play();
+      innerAnimation.play();
+      spanAnimation.play();
+
+      // Call updateAnimations on root timegroup
+      updateAnimations(rootTimegroup);
+
+      // All nested non-temporal animations should be coordinated
+      assert.equal(
+        outerAnimation.playState,
+        "paused",
+        "Outer div animation should be coordinated",
+      );
+      assert.equal(
+        innerAnimation.playState,
+        "paused",
+        "Inner div animation should be coordinated",
+      );
+      assert.equal(
+        spanAnimation.playState,
+        "paused",
+        "Span animation should be coordinated",
+      );
+    });
+
+    test("coordinates animations on child temporal elements when they are visible", async () => {
+      // Create root timegroup
+      const rootTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      rootTimegroup.currentTimeMs = 150; // Timeline at 150ms
+      document.body.appendChild(rootTimegroup);
+
+      // Create parent element (timegroup acts as parent)
+      const parentTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      parentTimegroup.setAttribute("duration", "1000ms");
+      rootTimegroup.appendChild(parentTimegroup);
+
+      // Create child temporal element that WILL be visible at timeline time 150ms
+      const childElement = document.createElement(
+        "test-temporal-element",
+      ) as TestTemporalElement;
+      childElement.setDuration(300); // 300ms duration (from 100ms to 400ms in root timeline)
+      childElement.setAttribute("offset", "100ms"); // Start at 100ms in root timeline
+      parentTimegroup.appendChild(childElement);
+
+      // Wait for elements to be connected and updated
+      await rootTimegroup.updateComplete;
+      await parentTimegroup.updateComplete;
+      await childElement.updateComplete;
+
+      // Create animation on child element
+      const childAnimation = childElement.animate(
+        [{ opacity: 0 }, { opacity: 1 }],
+        {
+          duration: 1000,
+        },
+      );
+      childAnimation.play();
+
+      // Call updateAnimations on parent timegroup - this should coordinate child animations too
+      updateAnimations(parentTimegroup);
+
+      // Child should be visible at current timeline position (150ms is between 100ms-400ms)
+      assert.notEqual(
+        childElement.style.display,
+        "none",
+        "Child should be visible at current timeline time",
+      );
+
+      // FIXED: Child animation should be paused and coordinated
+      assert.equal(
+        childAnimation.playState,
+        "paused",
+        "Child element animation should be paused and coordinated with timeline",
+      );
+    });
+
+    test("does not coordinate animations on child temporal elements when they are not visible", async () => {
+      // Create root timegroup
+      const rootTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      rootTimegroup.currentTimeMs = 100; // Timeline at 100ms
+      document.body.appendChild(rootTimegroup);
+
+      // Create parent element (timegroup acts as parent)
+      const parentTimegroup = document.createElement(
+        "ef-timegroup",
+      ) as EFTimegroup;
+      parentTimegroup.setAttribute("duration", "1000ms");
+      rootTimegroup.appendChild(parentTimegroup);
+
+      // Create child temporal element that will NOT be visible at timeline time 100ms
+      const childElement = document.createElement(
+        "test-temporal-element",
+      ) as TestTemporalElement;
+      childElement.setDuration(200); // 200ms duration
+      childElement.setAttribute("offset", "500ms"); // Start at 500ms in root timeline (way after current time)
+      parentTimegroup.appendChild(childElement);
+
+      // Wait for elements to be connected and updated
+      await rootTimegroup.updateComplete;
+      await parentTimegroup.updateComplete;
+      await childElement.updateComplete;
+
+      // Create animation on child element
+      const childAnimation = childElement.animate(
+        [{ opacity: 0 }, { opacity: 1 }],
+        {
+          duration: 1000,
+        },
+      );
+      childAnimation.play();
+
+      // Call updateAnimations on parent timegroup
+      updateAnimations(parentTimegroup);
+
+      // Child should be hidden (display: none)
+      assert.equal(
+        childElement.style.display,
+        "none",
+        "Child should be hidden when not in visible time range",
+      );
+
+      // Child animation should still be running (not coordinated since child is not visible)
+      assert.equal(
+        childAnimation.playState,
+        "paused",
+        "Child animation should remain running when child element is not visible",
+      );
+    });
   });
 
   describe("edge cases", () => {

package/src/elements/updateAnimations.ts

@@ -1,6 +1,5 @@
 import {
   deepGetTemporalElements,
-  isEFTemporal,
   type TemporalMixinInterface,
 } from "./EFTemporal.ts";
 
@@ -8,7 +7,7 @@ import {
 export type AnimatableElement = TemporalMixinInterface & HTMLElement;
 
 // Constants
-const ANIMATION_PRECISION_OFFSET = Number.EPSILON;
+const ANIMATION_PRECISION_OFFSET = 0.1; // Use 0.1ms to safely avoid completion threshold
 const DEFAULT_ANIMATION_ITERATIONS = 1;
 const PROGRESS_PROPERTY = "--ef-progress";
 const DURATION_PROPERTY = "--ef-duration";
@@ -39,8 +38,40 @@ export const evaluateTemporalState = (
       ? 1
       : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));
 
+  // Root timegroups should remain visible at exact end time, but other elements use exclusive end for clean transitions
+  const isRootTimegroup =
+    element.tagName.toLowerCase() === TIMEGROUP_TAGNAME &&
+    !(element as any).parentTimegroup;
+  const useInclusiveEnd = isRootTimegroup;
+
   const isVisible =
-    element.startTimeMs <= timelineTimeMs && element.endTimeMs > timelineTimeMs;
+    element.startTimeMs <= timelineTimeMs &&
+    (useInclusiveEnd
+      ? element.endTimeMs >= timelineTimeMs
+      : element.endTimeMs > timelineTimeMs);
+
+  return { progress, isVisible, timelineTimeMs };
+};
+
+/**
+ * Evaluates element visibility specifically for animation coordination
+ * Uses inclusive end boundaries to prevent animation jumps at exact boundaries
+ */
+export const evaluateTemporalStateForAnimation = (
+  element: AnimatableElement,
+): TemporalState => {
+  // Get timeline time from root timegroup, or use element's own time if it IS a timegroup
+  const timelineTimeMs = (element.rootTimegroup ?? element).currentTimeMs;
+
+  const progress =
+    element.durationMs <= 0
+      ? 1
+      : Math.max(0, Math.min(1, element.currentTimeMs / element.durationMs));
+
+  // For animation coordination, use inclusive end for ALL elements to prevent visual jumps
+  const isVisible =
+    element.startTimeMs <= timelineTimeMs &&
+    element.endTimeMs >= timelineTimeMs;
 
   return { progress, isVisible, timelineTimeMs };
 };
@@ -80,9 +111,11 @@ const updateVisualState = (
 };
 
 /**
- * Coordinates animations to match timeline
+ * Coordinates animations for a single element and its subtree, using the element as the time source
  */
-const coordinateAnimations = (element: AnimatableElement): void => {
+const coordinateAnimationsForSingleElement = (
+  element: AnimatableElement,
+): void => {
   const animations = element.getAnimations({ subtree: true });
 
   for (const animation of animations) {
@@ -96,17 +129,12 @@ const coordinateAnimations = (element: AnimatableElement): void => {
     }
 
     const target = effect.target;
-    if (!target || target.closest(TIMEGROUP_TAGNAME) !== element) {
-      continue;
-    }
-
-    const timeTarget = isEFTemporal(target)
-      ? target
-      : target.closest(TIMEGROUP_TAGNAME);
-    if (!timeTarget) {
+    if (!target) {
       continue;
     }
 
+    // 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 timing = effect.getTiming();
     const duration = Number(timing.duration) || 0;
     const delay = Number(timing.delay) || 0;
@@ -118,8 +146,8 @@ const coordinateAnimations = (element: AnimatableElement): void => {
       continue;
     }
 
-    // All timegroups are temporal, so always use ownCurrentTimeMs for local time coordination
-    const currentTime = timeTarget.ownCurrentTimeMs ?? 0;
+    // Use the element itself as the time source (it's guaranteed to be temporal)
+    const currentTime = element.ownCurrentTimeMs ?? 0;
 
     if (currentTime < delay) {
       animation.currentTime = 0;
@@ -130,12 +158,22 @@ const coordinateAnimations = (element: AnimatableElement): void => {
     const currentIteration = Math.floor(adjustedTime / duration);
     const currentIterationTime = adjustedTime % duration;
 
+    // Calculate the total animation timeline length (delay + duration * iterations)
+    const totalAnimationLength = delay + duration * iterations;
+
+    // CRITICAL: Always keep currentTime below totalAnimationLength to prevent completion
+    const maxSafeCurrentTime =
+      totalAnimationLength - ANIMATION_PRECISION_OFFSET;
+
     if (currentIteration >= iterations) {
-      animation.currentTime = duration - ANIMATION_PRECISION_OFFSET;
+      // Animation would be complete - clamp to just before completion
+      animation.currentTime = maxSafeCurrentTime;
     } else {
-      animation.currentTime =
+      // Animation in progress - clamp to safe value within current iteration
+      const proposedCurrentTime =
         Math.min(currentIterationTime, duration - ANIMATION_PRECISION_OFFSET) +
         delay;
+      animation.currentTime = Math.min(proposedCurrentTime, maxSafeCurrentTime);
     }
   }
 };
@@ -151,7 +189,18 @@ export const updateAnimations = (element: AnimatableElement): void => {
   });
   updateVisualState(element, temporalState);
 
-  if (temporalState.isVisible) {
-    coordinateAnimations(element);
+  // Coordinate animations - use animation-specific visibility to prevent jumps at exact boundaries
+  const animationState = evaluateTemporalStateForAnimation(element);
+  if (animationState.isVisible) {
+    coordinateAnimationsForSingleElement(element);
   }
+
+  // Coordinate animations for child elements using animation-specific visibility
+  deepGetTemporalElements(element).forEach((temporalElement) => {
+    const childAnimationState =
+      evaluateTemporalStateForAnimation(temporalElement);
+    if (childAnimationState.isVisible) {
+      coordinateAnimationsForSingleElement(temporalElement);
+    }
+  });
 };

package/src/gui/ContextMixin.browsertest.ts

@@ -4,7 +4,6 @@ import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 
 import { ContextMixin } from "./ContextMixin.js";
 
-// Required to test timeupdate event, we need a duration, and timegroups are a quick way to do that
 import "../elements/EFTimegroup.js";
 
 @customElement("test-context")
@@ -529,30 +528,6 @@ describe("ContextMixin", () => {
     });
   });
 
-  test("Time update event when the currentTimeMs changed", async () => {
-    const timegroup = document.createElement("ef-timegroup");
-    timegroup.mode = "fixed";
-    timegroup.duration = "10s";
-
-    const preview = document.createElement("test-context");
-    preview.append(timegroup);
-    document.body.append(preview);
-
-    type CurrentTimeEvent = CustomEvent<{ currentTimeMs: number }>;
-
-    // Expect the timeupdate event to be dispatched
-    const timeupdatePromise = new Promise<CurrentTimeEvent>((resolve) => {
-      preview.addEventListener(
-        "timeupdate",
-        (event: Event) => resolve(event as CurrentTimeEvent),
-        { once: true },
-      );
-    });
-    preview.currentTimeMs = 1000;
-    const event = await timeupdatePromise;
-    expect(event.detail.currentTimeMs).toBe(1000);
-  });
-
   describe("Reactivity", () => {
     test("should update durationMs when child tree changes", async () => {
       const element = document.createElement("test-context-reactivity");