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

package/dist/transcoding/types/index.d.ts

@@ -74,6 +74,7 @@ interface MediaEngine {
     audioBufferDurationMs: number;
     maxVideoBufferFetches: number;
     maxAudioBufferFetches: number;
+    bufferThresholdMs: number;
   };
   /**
    * Extract thumbnail canvases at multiple timestamps efficiently

package/package.json

@@ -1,15 +1,11 @@
 {
   "name": "@editframe/elements",
-  "version": "0.25.0-beta.0",
+  "version": "0.26.0-beta.0",
   "description": "",
-  "exports": {
-    ".": "./dist/index.js",
-    "./package.json": "./package.json"
-  },
   "type": "module",
   "scripts": {
     "typecheck": "tsc --noEmit --emitDeclarationOnly false",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/build-css.js",
     "build:watch": "tsdown --watch",
     "typedoc": "typedoc --json ./types.json --plugin typedoc-plugin-zod --excludeExternals ./src && jq -c . ./types.json > ./types.tmp.json && mv ./types.tmp.json ./types.json"
   },
@@ -17,7 +13,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@bramus/style-observer": "^1.3.0",
-    "@editframe/assets": "0.25.0-beta.0",
+    "@editframe/assets": "0.26.0-beta.0",
     "@lit/context": "^1.1.6",
     "@lit/task": "^1.0.3",
     "@opentelemetry/api": "^1.9.0",
@@ -36,9 +32,35 @@
     "@types/dom-webcodecs": "^0.1.11",
     "@types/node": "^20.14.13",
     "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.38",
+    "tailwindcss": "^3.4.3",
     "typescript": "^5.5.4"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts"
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json",
+    "./styles.css": "./dist/style.css",
+    "./types.json": "./types.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        }
+      },
+      "./package.json": "./package.json",
+      "./styles.css": "./dist/style.css",
+      "./types.json": "./types.json"
+    }
+  }
 }

package/scripts/build-css.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import autoprefixer from "autoprefixer";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import postcss from "postcss";
+import tailwindcss from "tailwindcss";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const srcDir = join(__dirname, "..", "src");
+const distDir = join(__dirname, "..", "dist");
+
+// Ensure dist directory exists
+mkdirSync(distDir, { recursive: true });
+
+// Read source CSS
+const cssPath = join(srcDir, "elements.css");
+const css = readFileSync(cssPath, "utf-8");
+
+// Process through PostCSS
+console.log("Processing CSS through Tailwind and PostCSS...");
+
+postcss([
+  tailwindcss({
+    content: [join(srcDir, "**/*.ts")],
+  }),
+  autoprefixer(),
+])
+  .process(css, { from: cssPath, to: join(distDir, "style.css") })
+  .then((result) => {
+    writeFileSync(join(distDir, "style.css"), result.css);
+    if (result.map) {
+      writeFileSync(join(distDir, "style.css.map"), result.map.toString());
+    }
+    console.log("✅ CSS processed and written to dist/style.css");
+  })
+  .catch((error) => {
+    console.error("❌ CSS processing failed:", error);
+    process.exit(1);
+  });

package/src/elements/EFMedia/AssetMediaEngine.ts

@@ -346,6 +346,7 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
       audioBufferDurationMs: 2000,
       maxVideoBufferFetches: 1,
       maxAudioBufferFetches: 1,
+      bufferThresholdMs: 30000, // Timeline-aware buffering threshold
     };
   }
 

package/src/elements/EFMedia/BaseMediaEngine.ts

@@ -482,4 +482,24 @@ export abstract class BaseMediaEngine {
     segmentId: number,
     rendition: VideoRendition,
   ): number[];
+
+  /**
+   * Get buffer configuration for this media engine
+   * Can be overridden by subclasses to provide custom buffer settings
+   */
+  getBufferConfig(): {
+    videoBufferDurationMs: number;
+    audioBufferDurationMs: number;
+    maxVideoBufferFetches: number;
+    maxAudioBufferFetches: number;
+    bufferThresholdMs: number;
+  } {
+    return {
+      videoBufferDurationMs: 10000, // 10 seconds
+      audioBufferDurationMs: 10000, // 10 seconds
+      maxVideoBufferFetches: 3,
+      maxAudioBufferFetches: 3,
+      bufferThresholdMs: 30000, // 30 seconds - timeline-aware buffering threshold
+    };
+  }
 }

package/src/elements/EFMedia/JitMediaEngine.browsertest.ts

@@ -155,4 +155,72 @@ describe("JitMediaEngine", () => {
         "http://localhost:63315/api/v1/transcode/{rendition}/{segmentId}.m4s?url=http%3A%2F%2Fweb%3A3000%2Fhead-moov-480p.mp4",
     });
   });
+
+  test("calculatePlayheadDistance utility function", async ({ expect }) => {
+    const { calculatePlayheadDistance } = await import(
+      "./shared/BufferUtils.js"
+    );
+
+    // Element is currently active (playhead within element bounds)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 0, endTimeMs: 2000 },
+        1000, // playhead at 1s
+      ),
+    ).toBe(0);
+
+    // Element hasn't started yet (playhead before element)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        0, // playhead at 0s
+      ),
+    ).toBe(2000);
+
+    // Element already finished (playhead after element)
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 0, endTimeMs: 2000 },
+        5000, // playhead at 5s
+      ),
+    ).toBe(3000);
+
+    // Playhead at element start boundary
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        2000, // playhead exactly at start
+      ),
+    ).toBe(0);
+
+    // Playhead at element end boundary
+    expect(
+      calculatePlayheadDistance(
+        { startTimeMs: 2000, endTimeMs: 4000 },
+        4000, // playhead exactly at end
+      ),
+    ).toBe(0);
+  });
+
+  test("buffer config includes timeline threshold", async ({ expect }) => {
+    const configuration = document.createElement("ef-configuration");
+    const apiHost = `${window.location.protocol}//${window.location.host}`;
+    configuration.setAttribute("api-host", apiHost);
+    configuration.apiHost = apiHost;
+    configuration.signingURL = "";
+
+    const video = document.createElement("ef-video");
+    video.src = "http://web:3000/head-moov-480p.mp4";
+    configuration.appendChild(video);
+    document.body.appendChild(configuration);
+
+    // Wait for media engine to initialize
+    const mediaEngine = await video.mediaEngineTask.taskComplete;
+
+    // Check that buffer config includes the threshold
+    const bufferConfig = mediaEngine.getBufferConfig();
+    expect(bufferConfig.bufferThresholdMs).toBe(30000);
+
+    configuration.remove();
+  });
 });

package/src/elements/EFMedia/JitMediaEngine.ts

@@ -206,6 +206,7 @@ export class JitMediaEngine extends BaseMediaEngine implements MediaEngine {
       audioBufferDurationMs: 8000,
       maxVideoBufferFetches: 3,
       maxAudioBufferFetches: 3,
+      bufferThresholdMs: 30000, // Timeline-aware buffering threshold
     };
   }
 

package/src/elements/EFMedia/audioTasks/makeAudioBufferTask.ts

@@ -62,8 +62,19 @@ export const makeAudioBufferTask = (host: EFMedia): AudioBufferTask => {
         bufferDurationMs,
         maxParallelFetches,
         enableBuffering: host.enableAudioBuffering,
+        bufferThresholdMs: engineConfig.bufferThresholdMs,
       };
 
+      // Timeline context for priority-based buffering
+      const timelineContext =
+        host.rootTimegroup?.currentTimeMs !== undefined
+          ? {
+              elementStartMs: host.startTimeMs,
+              elementEndMs: host.endTimeMs,
+              playheadMs: host.rootTimegroup.currentTimeMs,
+            }
+          : undefined;
+
       return manageMediaBuffer<AudioRendition>(
         seekTimeMs,
         currentConfig,
@@ -99,6 +110,7 @@ export const makeAudioBufferTask = (host: EFMedia): AudioBufferTask => {
           },
           logError: console.error,
         },
+        timelineContext,
       );
     },
   });

package/src/elements/EFMedia/shared/BufferUtils.ts

@@ -21,6 +21,7 @@ export interface MediaBufferConfig {
   maxParallelFetches: number;
   enableBuffering: boolean;
   enableContinuousBuffering?: boolean;
+  bufferThresholdMs?: number; // Timeline-aware buffering threshold (default: 30000ms)
 }
 
 /**
@@ -189,6 +190,26 @@ export const getUnrequestedSegments = (
   return segmentIds.filter((id) => !bufferState.requestedSegments.has(id));
 };
 
+/**
+ * Calculate distance from element to playhead position
+ * Returns 0 if element is currently active, otherwise returns distance in milliseconds
+ */
+export const calculatePlayheadDistance = (
+  element: { startTimeMs: number; endTimeMs: number },
+  playheadMs: number,
+): number => {
+  // Element hasn't started yet
+  if (playheadMs < element.startTimeMs) {
+    return element.startTimeMs - playheadMs;
+  }
+  // Element already finished
+  if (playheadMs > element.endTimeMs) {
+    return playheadMs - element.endTimeMs;
+  }
+  // Element is currently active
+  return 0;
+};
+
 /**
  * Core media buffering orchestration logic - prefetch only, no data storage
  * Integrates with BaseMediaEngine's existing caching and request deduplication
@@ -202,11 +223,32 @@ export const manageMediaBuffer = async <
   durationMs: number,
   signal: AbortSignal,
   deps: MediaBufferDependencies<T>,
+  timelineContext?: {
+    elementStartMs: number;
+    elementEndMs: number;
+    playheadMs: number;
+  },
 ): Promise<MediaBufferState> => {
   if (!config.enableBuffering) {
     return currentState;
   }
 
+  // Timeline-aware buffering: skip if element is too far from playhead
+  if (timelineContext && config.bufferThresholdMs !== undefined) {
+    const distance = calculatePlayheadDistance(
+      {
+        startTimeMs: timelineContext.elementStartMs,
+        endTimeMs: timelineContext.elementEndMs,
+      },
+      timelineContext.playheadMs,
+    );
+
+    if (distance > config.bufferThresholdMs) {
+      // Element is too far from playhead, skip buffering
+      return currentState;
+    }
+  }
+
   const rendition = await deps.getRendition();
   if (!rendition) {
     // Cannot buffer without a rendition

package/src/elements/EFMedia/videoTasks/makeVideoBufferTask.ts

@@ -57,8 +57,19 @@ export const makeVideoBufferTask = (host: EFVideo): VideoBufferTask => {
         bufferDurationMs,
         maxParallelFetches,
         enableBuffering: host.enableVideoBuffering,
+        bufferThresholdMs: engineConfig.bufferThresholdMs,
       };
 
+      // Timeline context for priority-based buffering
+      const timelineContext =
+        host.rootTimegroup?.currentTimeMs !== undefined
+          ? {
+              elementStartMs: host.startTimeMs,
+              elementEndMs: host.endTimeMs,
+              playheadMs: host.rootTimegroup.currentTimeMs,
+            }
+          : undefined;
+
       return manageMediaBuffer<VideoRendition>(
         seekTimeMs,
         currentConfig,
@@ -91,6 +102,7 @@ export const makeVideoBufferTask = (host: EFVideo): VideoBufferTask => {
           },
           logError: console.error,
         },
+        timelineContext,
       );
     },
   });

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);
           },
         );