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

package/src/elements/EFTimegroup.browsertest.ts

@@ -420,13 +420,57 @@ describe("setting currentTime", () => {
     await timegroup.waitForMediaDurations();
 
     timegroup.currentTime = 5_000; // 5000 seconds, should clamp to 10s
-    await timegroup.seekTask.taskComplete;
+    await timegroup.seekTask.run();
 
     const storedValue = localStorage.getItem(timegroup.storageKey);
     assert.equal(storedValue, "10"); // Should store 10 (clamped from 5000 to duration)
     timegroup.remove();
   });
 
+  test("root timegroup remains visible when currentTime equals duration exactly", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup id="end-time-test" mode="fixed" duration="10s"></ef-timegroup>`,
+    );
+    await timegroup.waitForMediaDurations();
+
+    // Set currentTime to exactly the duration
+    timegroup.currentTime = 10; // 10 seconds
+    await timegroup.seekTask.taskComplete;
+    await timegroup.frameTask.taskComplete;
+
+    // The root timegroup should still be visible at the exact end time
+    assert.notEqual(
+      timegroup.style.display,
+      "none",
+      "Root timegroup should be visible at exact end time",
+    );
+  });
+
+  test("root timegroup becomes hidden only after currentTime exceeds duration", async () => {
+    const timegroup = renderTimegroup(
+      html`<ef-timegroup id="beyond-end-test" mode="fixed" duration="10s"></ef-timegroup>`,
+    );
+    await timegroup.waitForMediaDurations();
+
+    // Set currentTime beyond the duration (should be clamped to duration)
+    timegroup.currentTime = 15; // 15 seconds, should clamp to 10s
+    await timegroup.seekTask.taskComplete;
+    await timegroup.frameTask.taskComplete;
+
+    // Even when clamped, it should still be visible at the end
+    assert.notEqual(
+      timegroup.style.display,
+      "none",
+      "Root timegroup should be visible even when time is clamped to duration",
+    );
+    // Verify that the time was actually clamped
+    assert.equal(
+      timegroup.currentTime,
+      10,
+      "Time should be clamped to duration",
+    );
+  });
+
   test("does not persist in localStorage if the timegroup has no id", async () => {
     const timegroup = renderTimegroup(
       html`<ef-timegroup mode="fixed" duration="10s"></ef-timegroup>`,
@@ -572,19 +616,23 @@ describe("Dynamic content updates", () => {
       const frameTaskB = timegroup.querySelector("test-frame-task-b")!;
       const frameTaskC = timegroup.querySelector("test-frame-task-c")!;
 
-      assert.equal(frameTaskA.frameTaskCount, 0);
+      // following the initial update, the first frame tasks have run once.
+      await timegroup.updateComplete;
+
+      assert.equal(frameTaskA.frameTaskCount, 1);
       assert.equal(frameTaskB.frameTaskCount, 0);
-      assert.equal(frameTaskC.frameTaskCount, 0);
+      assert.equal(frameTaskC.frameTaskCount, 1);
 
+      // Then we run them manually.
       await timegroup.frameTask.run();
 
       // At timeline time 0ms:
       // - frameTaskA (0-1000ms) should run
       // - frameTaskB (1000-2000ms) should NOT run
       // - frameTaskC (0-1000ms) should run (inherits root positioning)
-      assert.equal(frameTaskA.frameTaskCount, 1);
+      assert.equal(frameTaskA.frameTaskCount, 2);
       assert.equal(frameTaskB.frameTaskCount, 0); // Not visible at time 0
-      assert.equal(frameTaskC.frameTaskCount, 1); // Nested in B but inherits root positioning
+      assert.equal(frameTaskC.frameTaskCount, 2); // Nested in B but inherits root positioning
     });
   });
 
@@ -599,9 +647,10 @@ describe("Dynamic content updates", () => {
       );
       const nonRootTimegroup = timegroup.querySelector("ef-timegroup")!;
       const frameTaskA = timegroup.querySelector("test-frame-task-a")!;
-      assert.equal(frameTaskA.frameTaskCount, 0);
+      await timegroup.updateComplete;
+      assert.equal(frameTaskA.frameTaskCount, 1);
       await nonRootTimegroup.seekTask.run();
-      assert.equal(frameTaskA.frameTaskCount, 0);
+      assert.equal(frameTaskA.frameTaskCount, 1);
     });
 
     test("waits for media durations", async () => {

package/src/elements/EFTimegroup.ts

@@ -1,7 +1,7 @@
 import { provide } from "@lit/context";
 import { Task, TaskStatus } from "@lit/task";
 import debug from "debug";
-import { css, html, LitElement } from "lit";
+import { css, html, LitElement, type PropertyValues } from "lit";
 import { customElement, property } from "lit/decorators.js";
 
 import { EF_INTERACTIVE } from "../EF_INTERACTIVE.js";
@@ -17,7 +17,10 @@ import {
   timegroupContext,
 } from "./EFTemporal.js";
 import { TimegroupController } from "./TimegroupController.js";
-import { evaluateTemporalState, updateAnimations } from "./updateAnimations.ts";
+import {
+  evaluateTemporalStateForAnimation,
+  updateAnimations,
+} from "./updateAnimations.ts";
 
 const log = debug("ef:elements:EFTimegroup");
 
@@ -104,6 +107,46 @@ export class EFTimegroup extends EFTemporal(LitElement) {
 
   #processingPendingSeek = false;
 
+  #frameTaskInProgress = false;
+
+  #pendingFrameTaskRun = false;
+
+  #processingPendingFrameTask = false;
+
+  /**
+   * Throttles frameTask execution to ensure only one runs at a time while preserving the last request
+   */
+  private async runThrottledFrameTask(): Promise<void> {
+    if (this.#frameTaskInProgress) {
+      this.#pendingFrameTaskRun = true;
+      // Wait for the current frame task to complete
+      while (this.#frameTaskInProgress) {
+        await this.frameTask.taskComplete;
+      }
+      return;
+    }
+
+    this.#frameTaskInProgress = true;
+
+    try {
+      await this.frameTask.run();
+    } finally {
+      this.#frameTaskInProgress = false;
+
+      if (this.#pendingFrameTaskRun && !this.#processingPendingFrameTask) {
+        this.#pendingFrameTaskRun = false;
+        this.#processingPendingFrameTask = true;
+        try {
+          await this.runThrottledFrameTask();
+        } finally {
+          this.#processingPendingFrameTask = false;
+        }
+      } else {
+        this.#pendingFrameTaskRun = false;
+      }
+    }
+  }
+
   @property({ type: Number, attribute: "currenttime" })
   set currentTime(time: number) {
     time = Math.max(0, time);
@@ -127,7 +170,6 @@ export class EFTimegroup extends EFTemporal(LitElement) {
     }
 
     this.#currentTime = time;
-    // This will be set to false in the seekTask
     this.#seekInProgress = true;
 
     this.seekTask.run().finally(() => {
@@ -232,6 +274,15 @@ export class EFTimegroup extends EFTemporal(LitElement) {
     }
   }
 
+  #previousDurationMs = 0;
+
+  protected updated(_changedProperties: PropertyValues): void {
+    if (this.#previousDurationMs !== this.durationMs) {
+      this.#previousDurationMs = this.durationMs;
+      this.runThrottledFrameTask();
+    }
+  }
+
   disconnectedCallback() {
     super.disconnectedCallback();
     this.#resizeObserver?.disconnect();
@@ -333,7 +384,14 @@ export class EFTimegroup extends EFTemporal(LitElement) {
       const startTimeMs = (temporal as any).startTimeMs as number;
       const endTimeMs = (temporal as any).endTimeMs as number;
       const elementStartsBeforeEnd = startTimeMs <= timelineTimeMs + epsilon;
-      const elementEndsAfterStart = endTimeMs > timelineTimeMs; // Exclusive end for clean transitions
+      // Root timegroups should remain visible at exact end time, but other elements use exclusive end for clean transitions
+      const isRootTimegroup =
+        temporal.tagName.toLowerCase() === "ef-timegroup" &&
+        !(temporal as any).parentTimegroup;
+      const useInclusiveEnd = isRootTimegroup;
+      const elementEndsAfterStart = useInclusiveEnd
+        ? endTimeMs >= timelineTimeMs
+        : endTimeMs > timelineTimeMs;
       return elementStartsBeforeEnd && elementEndsAfterStart;
     });
 
@@ -366,15 +424,14 @@ export class EFTimegroup extends EFTemporal(LitElement) {
     const temporalElements = deepGetElementsWithFrameTasks(this);
 
     // Filter to only include temporally visible elements for frame processing
+    // Use animation-friendly visibility to prevent animation jumps at exact boundaries
     const visibleElements = temporalElements.filter((element) => {
-      const temporalState = evaluateTemporalState(element);
-      return temporalState.isVisible;
+      const animationState = evaluateTemporalStateForAnimation(element);
+      return animationState.isVisible;
     });
 
     await Promise.all(
-      visibleElements.map((element) => {
-        return element.frameTask.run();
-      }),
+      visibleElements.map((element) => element.frameTask.run()),
     );
   }
 
@@ -679,9 +736,11 @@ export class EFTimegroup extends EFTemporal(LitElement) {
         0,
         Math.min(targetTime ?? 0, this.durationMs / 1000),
       );
+      // Apply the clamped time back to currentTime
+      this.#currentTime = newTime;
       this.requestUpdate("currentTime");
-      await this.frameTask.run();
-      this.#saveTimeToLocalStorage(newTime);
+      await this.runThrottledFrameTask();
+      this.#saveTimeToLocalStorage(this.#currentTime);
       // This has to be set false here so any following seeks are not treated as pending
       this.#seekInProgress = false;
       return newTime;

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,17 +10,31 @@ import {
 
 import "./EFTimegroup.js";
 
+// 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(
@@ -49,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;
 }
@@ -212,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,
@@ -297,8 +387,6 @@ describe("Timeline Element Synchronizer", () => {
       });
       animation.play();
 
-      assert.equal(animation.playState, "running");
-
       updateAnimations(element);
 
       assert.equal(animation.playState, "paused");
@@ -365,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
@@ -444,6 +529,243 @@ describe("Timeline Element Synchronizer", () => {
     });
   });
 
+  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", () => {
     test("handles zero duration gracefully", () => {
       const element = createTestElement({