@editframe/elements 0.25.1-beta.0 → 0.26.0-beta.0

package/src/elements/EFTemporal.ts

@@ -256,10 +256,18 @@ export const deepGetElementsWithFrameTasks = (
 };
 
 let temporalCache: Map<Element, TemporalMixinInterface[]>;
+let temporalCacheResetScheduled = false;
 export const resetTemporalCache = () => {
   temporalCache = new Map();
-  if (typeof requestAnimationFrame !== "undefined") {
-    requestAnimationFrame(resetTemporalCache);
+  if (
+    typeof requestAnimationFrame !== "undefined" &&
+    !temporalCacheResetScheduled
+  ) {
+    temporalCacheResetScheduled = true;
+    requestAnimationFrame(() => {
+      temporalCacheResetScheduled = false;
+      resetTemporalCache();
+    });
   }
 };
 resetTemporalCache();
@@ -303,10 +311,18 @@ export class OwnCurrentTimeController implements ReactiveController {
 type Constructor<T = {}> = new (...args: any[]) => T;
 
 let startTimeMsCache = new WeakMap<Element, number>();
+let startTimeMsCacheResetScheduled = false;
 const resetStartTimeMsCache = () => {
   startTimeMsCache = new WeakMap();
-  if (typeof requestAnimationFrame !== "undefined") {
-    requestAnimationFrame(resetStartTimeMsCache);
+  if (
+    typeof requestAnimationFrame !== "undefined" &&
+    !startTimeMsCacheResetScheduled
+  ) {
+    startTimeMsCacheResetScheduled = true;
+    requestAnimationFrame(() => {
+      startTimeMsCacheResetScheduled = false;
+      resetStartTimeMsCache();
+    });
   }
 };
 resetStartTimeMsCache();

package/src/elements/EFTimegroup.browsertest.ts

@@ -669,4 +669,202 @@ describe("Dynamic content updates", () => {
       assert.equal(media.mediaEngineTaskCount, 1);
     });
   });
+
+  describe("custom frame tasks", () => {
+    test("executes registered callback on frame update", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let callbackExecuted = false;
+      const callback = () => {
+        callbackExecuted = true;
+      };
+
+      timegroup.addFrameTask(callback);
+      await timegroup.seek(1000);
+
+      assert.equal(callbackExecuted, true);
+    }, 1000);
+
+    test("callback receives correct timing information", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5000ms"></ef-timegroup>`,
+      );
+
+      let receivedInfo: any = null;
+      const callback = (info: any) => {
+        receivedInfo = info;
+      };
+
+      timegroup.addFrameTask(callback);
+      await timegroup.seek(2000);
+
+      assert.equal(receivedInfo.ownCurrentTimeMs, 2000);
+      assert.equal(receivedInfo.currentTimeMs, 2000);
+      assert.equal(receivedInfo.durationMs, 5000);
+      assert.equal(receivedInfo.percentComplete, 0.4);
+      assert.equal(receivedInfo.element, timegroup);
+    }, 1000);
+
+    test("executes multiple callbacks in parallel", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let callback1Executed = false;
+      let callback2Executed = false;
+      let callback3Executed = false;
+
+      timegroup.addFrameTask(() => {
+        callback1Executed = true;
+      });
+      timegroup.addFrameTask(() => {
+        callback2Executed = true;
+      });
+      timegroup.addFrameTask(() => {
+        callback3Executed = true;
+      });
+
+      await timegroup.seek(1000);
+
+      assert.equal(callback1Executed, true);
+      assert.equal(callback2Executed, true);
+      assert.equal(callback3Executed, true);
+    }, 1000);
+
+    test("async callbacks block frame pipeline", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let asyncCallbackCompleted = false;
+      const executionOrder: string[] = [];
+
+      const asyncCallback = async () => {
+        executionOrder.push("async-start");
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        asyncCallbackCompleted = true;
+        executionOrder.push("async-end");
+      };
+
+      timegroup.addFrameTask(asyncCallback);
+
+      const seekPromise = timegroup.seek(1000);
+      executionOrder.push("seek-called");
+
+      await seekPromise;
+      executionOrder.push("seek-complete");
+
+      assert.equal(asyncCallbackCompleted, true);
+      assert.deepEqual(executionOrder, [
+        "seek-called",
+        "async-start",
+        "async-end",
+        "seek-complete",
+      ]);
+    }, 1000);
+
+    test("cleanup function removes callback", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let callbackExecutionCount = 0;
+      const cleanup = timegroup.addFrameTask(() => {
+        callbackExecutionCount++;
+      });
+
+      await timegroup.seek(1000);
+      assert.equal(callbackExecutionCount, 1);
+
+      cleanup();
+      await timegroup.seek(2000);
+      assert.equal(callbackExecutionCount, 1);
+    }, 1000);
+
+    test("removeFrameTask removes callback", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let callbackExecutionCount = 0;
+      const callback = () => {
+        callbackExecutionCount++;
+      };
+
+      timegroup.addFrameTask(callback);
+      await timegroup.seek(1000);
+      assert.equal(callbackExecutionCount, 1);
+
+      timegroup.removeFrameTask(callback);
+      await timegroup.seek(2000);
+      assert.equal(callbackExecutionCount, 1);
+    }, 1000);
+
+    test("addFrameTask throws error for non-function", () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      assert.throws(() => {
+        timegroup.addFrameTask("not a function" as any);
+      }, "Frame task callback must be a function");
+    }, 1000);
+
+    test("custom frame tasks persist after disconnect and reconnect", async () => {
+      const container = document.createElement("div");
+      document.body.appendChild(container);
+
+      const timegroup = document.createElement("ef-timegroup") as EFTimegroup;
+      timegroup.setAttribute("mode", "fixed");
+      timegroup.setAttribute("duration", "5s");
+      container.appendChild(timegroup);
+
+      let callbackWorkedAfterReconnect = false;
+      const callback = () => {
+        callbackWorkedAfterReconnect = true;
+      };
+
+      timegroup.addFrameTask(callback);
+
+      // Disconnect and reconnect
+      container.removeChild(timegroup);
+      callbackWorkedAfterReconnect = false; // Reset after disconnect
+      container.appendChild(timegroup);
+
+      // Callback should still work after reconnect
+      await timegroup.seek(2000);
+      assert.equal(
+        callbackWorkedAfterReconnect,
+        true,
+        "Callback should still work after reconnect",
+      );
+
+      container.remove();
+    }, 1000);
+
+    test("sync and async callbacks execute together", async () => {
+      const timegroup = renderTimegroup(
+        html`<ef-timegroup mode="fixed" duration="5s"></ef-timegroup>`,
+      );
+
+      let syncExecuted = false;
+      let asyncExecuted = false;
+
+      timegroup.addFrameTask(() => {
+        syncExecuted = true;
+      });
+
+      timegroup.addFrameTask(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        asyncExecuted = true;
+      });
+
+      await timegroup.seek(1000);
+
+      assert.equal(syncExecuted, true);
+      assert.equal(asyncExecuted, true);
+    }, 1000);
+  });
 });

package/src/elements/EFTimegroup.ts

@@ -34,6 +34,15 @@ declare global {
 
 const log = debug("ef:elements:EFTimegroup");
 
+// Custom frame task callback type
+export type FrameTaskCallback = (info: {
+  ownCurrentTimeMs: number;
+  currentTimeMs: number;
+  durationMs: number;
+  percentComplete: number;
+  element: EFTimegroup;
+}) => void | Promise<void>;
+
 // Cache for sequence mode duration calculations to avoid O(n) recalculation
 let sequenceDurationCache: WeakMap<EFTimegroup, number> = new WeakMap();
 
@@ -125,6 +134,7 @@ export class EFTimegroup extends EFTargetable(EFTemporal(TWMixin(LitElement))) {
   #seekInProgress = false;
   #pendingSeekTime: number | undefined;
   #processingPendingSeek = false;
+  #customFrameTasks: Set<FrameTaskCallback> = new Set();
 
   /**
    * Get the effective FPS for this timegroup.
@@ -276,6 +286,33 @@ export class EFTimegroup extends EFTargetable(EFTemporal(TWMixin(LitElement))) {
     return !this.parentTimegroup;
   }
 
+  /**
+   * Register a custom frame task callback that will be executed during frame rendering.
+   * The callback receives timing information and can be async or sync.
+   * Multiple callbacks can be registered and will execute in parallel.
+   *
+   * @param callback - Function to execute on each frame
+   * @returns A cleanup function that removes the callback when called
+   */
+  addFrameTask(callback: FrameTaskCallback): () => void {
+    if (typeof callback !== "function") {
+      throw new Error("Frame task callback must be a function");
+    }
+    this.#customFrameTasks.add(callback);
+    return () => {
+      this.#customFrameTasks.delete(callback);
+    };
+  }
+
+  /**
+   * Remove a previously registered custom frame task callback.
+   *
+   * @param callback - The callback function to remove
+   */
+  removeFrameTask(callback: FrameTaskCallback): void {
+    this.#customFrameTasks.delete(callback);
+  }
+
   saveTimeToLocalStorage(time: number) {
     try {
       if (this.id && this.isConnected && !Number.isNaN(time)) {
@@ -759,6 +796,26 @@ export class EFTimegroup extends EFTargetable(EFTemporal(TWMixin(LitElement))) {
           undefined,
           async () => {
             await this.waitForFrameTasks();
+
+            // Execute custom frame tasks
+            if (this.#customFrameTasks.size > 0) {
+              const percentComplete =
+                this.durationMs > 0 ? ownCurrentTimeMs / this.durationMs : 0;
+              const frameInfo = {
+                ownCurrentTimeMs,
+                currentTimeMs,
+                durationMs: this.durationMs,
+                percentComplete,
+                element: this,
+              };
+
+              await Promise.all(
+                Array.from(this.#customFrameTasks).map((callback) =>
+                  Promise.resolve(callback(frameInfo)),
+                ),
+              );
+            }
+
             updateAnimations(this);
           },
         );