@editframe/elements 0.20.3-beta.0 → 0.21.0-beta.0

package/src/elements/EFMedia/AssetIdMediaEngine.test.ts

@@ -122,14 +122,16 @@ describe("AssetIdMediaEngine", () => {
 
     it("should return correct audio rendition", () => {
       const audioRendition = engine.audioRendition;
-      expect(audioRendition.trackId).toBe(1);
-      expect(audioRendition.src).toBe(mockAssetId);
+      expect(audioRendition).toBeDefined();
+      expect(audioRendition!.trackId).toBe(1);
+      expect(audioRendition!.src).toBe(mockAssetId);
     });
 
     it("should return correct video rendition", () => {
       const videoRendition = engine.videoRendition;
-      expect(videoRendition.trackId).toBe(2);
-      expect(videoRendition.src).toBe(mockAssetId);
+      expect(videoRendition).toBeDefined();
+      expect(videoRendition!.trackId).toBe(2);
+      expect(videoRendition!.src).toBe(mockAssetId);
     });
   });
 

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

@@ -57,8 +57,9 @@ describe("AssetMediaEngine", () => {
     expect,
   }) => {
     const audioRendition = mediaEngine.audioRendition;
-    expect(audioRendition.trackId).toBe(2);
-    expect(audioRendition.src).toBe(host.src);
+    expect(audioRendition).toBeDefined();
+    expect(audioRendition!.trackId).toBe(2);
+    expect(audioRendition!.src).toBe(host.src);
   });
 
   test("returns video rendition with correct properties", ({
@@ -67,9 +68,10 @@ describe("AssetMediaEngine", () => {
     expect,
   }) => {
     const videoRendition = mediaEngine.videoRendition;
-    expect(videoRendition.trackId).toBe(1);
-    expect(videoRendition.src).toBe(host.src);
-    expect(videoRendition.startTimeOffsetMs).toBeCloseTo(66.6, 0);
+    expect(videoRendition).toBeDefined();
+    expect(videoRendition!.trackId).toBe(1);
+    expect(videoRendition!.src).toBe(host.src);
+    expect(videoRendition!.startTimeOffsetMs).toBeCloseTo(66.6, 0);
   });
 
   test("provides templates for asset endpoints", ({ mediaEngine, expect }) => {
@@ -100,39 +102,39 @@ describe("AssetMediaEngine", () => {
 
   describe("bars n tone segment id computation", () => {
     test("computes 0ms is 0", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(0, mediaEngine.getVideoRendition()),
-      ).toBe(0);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(0, videoRendition!)).toBe(0);
     });
 
     test("computes 2000 is 1", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(2000, mediaEngine.getVideoRendition()),
-      ).toBe(1);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(2000, videoRendition!)).toBe(1);
     });
 
     test("computes 4000 is 2", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(4000, mediaEngine.getVideoRendition()),
-      ).toBe(2);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(4000, videoRendition!)).toBe(2);
     });
 
     test("computes 6000 is 3", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(6000, mediaEngine.getVideoRendition()),
-      ).toBe(3);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(6000, videoRendition!)).toBe(3);
     });
 
     test("computes 8000 is 4", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(8000, mediaEngine.getVideoRendition()),
-      ).toBe(4);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(8000, videoRendition!)).toBe(4);
     });
 
     test("computes 7975 is  3", ({ expect, mediaEngine }) => {
-      expect(
-        mediaEngine.computeSegmentId(7975, mediaEngine.getVideoRendition()),
-      ).toBe(3);
+      const videoRendition = mediaEngine.getVideoRendition();
+      expect(videoRendition).toBeDefined();
+      expect(mediaEngine.computeSegmentId(7975, videoRendition!)).toBe(3);
     });
   });
 });

package/src/elements/EFMedia/AssetMediaEngine.ts

@@ -1,5 +1,6 @@
 import type { TrackFragmentIndex } from "@editframe/assets";
 
+import { withSpan } from "../../otel/tracingHelpers.js";
 import type {
   AudioRendition,
   InitSegmentPaths,
@@ -54,16 +55,28 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
   }
 
   get videoRendition() {
+    const videoTrack = this.videoTrackIndex;
+
+    if (!videoTrack || videoTrack.track === undefined) {
+      return undefined;
+    }
+
     return {
-      trackId: this.videoTrackIndex?.track,
+      trackId: videoTrack.track,
       src: this.src,
-      startTimeOffsetMs: this.videoTrackIndex?.startTimeOffsetMs,
+      startTimeOffsetMs: videoTrack.startTimeOffsetMs,
     };
   }
 
   get audioRendition() {
+    const audioTrack = this.audioTrackIndex;
+
+    if (!audioTrack || audioTrack.track === undefined) {
+      return undefined;
+    }
+
     return {
-      trackId: this.audioTrackIndex?.track,
+      trackId: audioTrack.track,
       src: this.src,
     };
   }
@@ -109,23 +122,36 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
     rendition: { trackId: number | undefined; src: string },
     signal: AbortSignal,
   ) {
-    if (!rendition.trackId) {
-      throw new Error(
-        "[fetchInitSegment] Track ID is required for asset metadata",
-      );
-    }
-    const url = this.buildInitSegmentUrl(rendition.trackId);
-    const initSegment = this.data[rendition.trackId]?.initSegment;
-    if (!initSegment) {
-      throw new Error("Init segment not found");
-    }
-
-    // Use unified fetch method with Range headers
-    const headers = {
-      Range: `bytes=${initSegment.offset}-${initSegment.offset + initSegment.size - 1}`,
-    };
-
-    return this.fetchMediaWithHeaders(url, headers, signal);
+    return withSpan(
+      "assetEngine.fetchInitSegment",
+      {
+        trackId: rendition.trackId || -1,
+        src: rendition.src,
+      },
+      undefined,
+      async (span) => {
+        if (!rendition.trackId) {
+          throw new Error(
+            "[fetchInitSegment] Track ID is required for asset metadata",
+          );
+        }
+        const url = this.buildInitSegmentUrl(rendition.trackId);
+        const initSegment = this.data[rendition.trackId]?.initSegment;
+        if (!initSegment) {
+          throw new Error("Init segment not found");
+        }
+
+        span.setAttribute("offset", initSegment.offset);
+        span.setAttribute("size", initSegment.size);
+
+        // Use unified fetch method with Range headers
+        const headers = {
+          Range: `bytes=${initSegment.offset}-${initSegment.offset + initSegment.size - 1}`,
+        };
+
+        return this.fetchMediaWithHeaders(url, headers, signal);
+      },
+    );
   }
 
   async fetchMediaSegment(
@@ -133,26 +159,40 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
     rendition: { trackId: number | undefined; src: string },
     signal?: AbortSignal,
   ) {
-    if (!rendition.trackId) {
-      throw new Error(
-        "[fetchMediaSegment] Track ID is required for asset metadata",
-      );
-    }
-    if (segmentId === undefined) {
-      throw new Error("Segment ID is not available");
-    }
-    const url = this.buildMediaSegmentUrl(rendition.trackId, segmentId);
-    const mediaSegment = this.data[rendition.trackId]?.segments[segmentId];
-    if (!mediaSegment) {
-      throw new Error("Media segment not found");
-    }
-
-    // Use unified fetch method with Range headers
-    const headers = {
-      Range: `bytes=${mediaSegment.offset}-${mediaSegment.offset + mediaSegment.size - 1}`,
-    };
-
-    return this.fetchMediaWithHeaders(url, headers, signal);
+    return withSpan(
+      "assetEngine.fetchMediaSegment",
+      {
+        segmentId,
+        trackId: rendition.trackId || -1,
+        src: rendition.src,
+      },
+      undefined,
+      async (span) => {
+        if (!rendition.trackId) {
+          throw new Error(
+            "[fetchMediaSegment] Track ID is required for asset metadata",
+          );
+        }
+        if (segmentId === undefined) {
+          throw new Error("Segment ID is not available");
+        }
+        const url = this.buildMediaSegmentUrl(rendition.trackId, segmentId);
+        const mediaSegment = this.data[rendition.trackId]?.segments[segmentId];
+        if (!mediaSegment) {
+          throw new Error("Media segment not found");
+        }
+
+        span.setAttribute("offset", mediaSegment.offset);
+        span.setAttribute("size", mediaSegment.size);
+
+        // Use unified fetch method with Range headers
+        const headers = {
+          Range: `bytes=${mediaSegment.offset}-${mediaSegment.offset + mediaSegment.size - 1}`,
+        };
+
+        return this.fetchMediaWithHeaders(url, headers, signal);
+      },
+    );
   }
 
   /**
@@ -322,9 +362,7 @@ export class AssetMediaEngine extends BaseMediaEngine implements MediaEngine {
       // This is because Asset segments are independent timeline fragments
 
       if (!rendition.trackId) {
-        throw new Error(
-          "[convertToSegmentRelativeTimestamps] Track ID is required for asset metadata",
-        );
+        throw new Error("Track ID is required for asset metadata");
       }
       // For AssetMediaEngine, we need to calculate the actual segment start time
       // using the precise segment boundaries from the track fragment index

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

@@ -34,6 +34,100 @@ class TestMediaEngine extends BaseMediaEngine {
   }
 }
 
+// Test implementation for video-only assets
+// @ts-expect-error missing implementations
+class VideoOnlyMediaEngine extends BaseMediaEngine {
+  fetchMediaSegment = vi.fn();
+  public host: EFMedia;
+
+  constructor(host: EFMedia) {
+    super(host);
+    this.host = host;
+  }
+
+  get videoRendition() {
+    return {
+      trackId: 1,
+      src: "test-video.mp4",
+      segmentDurationMs: 2000,
+    };
+  }
+
+  get audioRendition() {
+    return undefined; // Video-only asset
+  }
+}
+
+// Test implementation for audio-only assets
+// @ts-expect-error missing implementations
+class AudioOnlyMediaEngine extends BaseMediaEngine {
+  fetchMediaSegment = vi.fn();
+  public host: EFMedia;
+
+  constructor(host: EFMedia) {
+    super(host);
+    this.host = host;
+  }
+
+  get videoRendition() {
+    return undefined; // Audio-only asset
+  }
+
+  get audioRendition() {
+    return {
+      trackId: 1,
+      src: "test-audio.mp4",
+      segmentDurationMs: 1000,
+    };
+  }
+}
+
+describe("BaseMediaEngine API Contract", () => {
+  test("getAudioRendition returns audio rendition when available", ({
+    expect,
+  }) => {
+    const host = document.createElement("ef-video") as EFMedia;
+    const engine = new TestMediaEngine(host);
+
+    const result = engine.getAudioRendition();
+    expect(result).toBeDefined();
+    expect(result?.trackId).toBe(2);
+    expect(result?.src).toBe("test-audio.mp4");
+  });
+
+  test("getAudioRendition returns undefined for video-only assets", ({
+    expect,
+  }) => {
+    const host = document.createElement("ef-video") as EFMedia;
+    const engine = new VideoOnlyMediaEngine(host);
+
+    const result = engine.getAudioRendition();
+    expect(result).toBeUndefined();
+  });
+
+  test("getVideoRendition returns video rendition when available", ({
+    expect,
+  }) => {
+    const host = document.createElement("ef-video") as EFMedia;
+    const engine = new TestMediaEngine(host);
+
+    const result = engine.getVideoRendition();
+    expect(result).toBeDefined();
+    expect(result?.trackId).toBe(1);
+    expect(result?.src).toBe("test-video.mp4");
+  });
+
+  test("getVideoRendition returns undefined for audio-only assets", ({
+    expect,
+  }) => {
+    const host = document.createElement("ef-audio") as EFMedia;
+    const engine = new AudioOnlyMediaEngine(host);
+
+    const result = engine.getVideoRendition();
+    expect(result).toBeUndefined();
+  });
+});
+
 describe("BaseMediaEngine deduplication", () => {
   test("should fetch segment successfully", async ({ expect }) => {
     const host = document.createElement("ef-video") as EFMedia;

package/src/elements/EFMedia/BaseMediaEngine.ts

@@ -1,3 +1,4 @@
+import { withSpan } from "../../otel/tracingHelpers.js";
 import { RequestDeduplicator } from "../../transcoding/cache/RequestDeduplicator.js";
 import type {
   AudioRendition,
@@ -23,17 +24,19 @@ export abstract class BaseMediaEngine {
   abstract get videoRendition(): VideoRendition | undefined;
   abstract get audioRendition(): AudioRendition | undefined;
 
-  getVideoRendition(): VideoRendition {
-    if (!this.videoRendition) {
-      throw new Error("No video rendition available");
-    }
+  /**
+   * Get video rendition if available. Returns undefined for audio-only assets.
+   * Callers should handle undefined gracefully.
+   */
+  getVideoRendition(): VideoRendition | undefined {
     return this.videoRendition;
   }
 
-  getAudioRendition(): AudioRendition {
-    if (!this.audioRendition) {
-      throw new Error("No audio rendition available");
-    }
+  /**
+   * Get audio rendition if available. Returns undefined for video-only assets.
+   * Callers should handle undefined gracefully.
+   */
+  getAudioRendition(): AudioRendition | undefined {
     return this.audioRendition;
   }
 
@@ -59,65 +62,122 @@ export abstract class BaseMediaEngine {
       signal?: AbortSignal;
     },
   ): Promise<any> {
-    const { responseType, headers, signal } = options;
-
-    // Create cache key that includes URL and headers for proper isolation
-    // Note: We don't include signal in cache key as it would prevent proper deduplication
-    const cacheKey = headers ? `${url}:${JSON.stringify(headers)}` : url;
-
-    // Check cache first
-    const cached = mediaCache.get(cacheKey);
-    if (cached) {
-      // If we have a cached promise, we need to handle the caller's abort signal
-      // without affecting the underlying request that other instances might be using
-      if (signal) {
-        return this.handleAbortForCachedRequest(cached, signal);
-      }
-      return cached;
-    }
-
-    // Use global deduplicator to prevent concurrent requests for the same resource
-    // Note: We do NOT pass the signal to the deduplicator - each caller manages their own abort
-    const promise = globalRequestDeduplicator.executeRequest(
-      cacheKey,
-      async () => {
-        try {
-          // Make the fetch request WITHOUT the signal - let each caller handle their own abort
-          // This prevents one instance's abort from affecting other instances using the shared cache
-          const response = await this.host.fetch(url, { headers });
-
-          if (responseType === "json") {
-            return response.json();
+    return withSpan(
+      "mediaEngine.fetchWithCache",
+      {
+        url: url.length > 100 ? `${url.substring(0, 100)}...` : url,
+        responseType: options.responseType,
+        hasHeaders: !!options.headers,
+      },
+      undefined,
+      async (span) => {
+        const t0 = performance.now();
+        const { responseType, headers, signal } = options;
+
+        // Create cache key that includes URL and headers for proper isolation
+        // Note: We don't include signal in cache key as it would prevent proper deduplication
+        const cacheKey = headers ? `${url}:${JSON.stringify(headers)}` : url;
+
+        // Check cache first
+        const t1 = performance.now();
+        const cached = mediaCache.get(cacheKey);
+        const t2 = performance.now();
+        span.setAttribute("cacheLookupMs", Math.round((t2 - t1) * 1000) / 1000);
+
+        if (cached) {
+          span.setAttribute("cacheHit", true);
+          // If we have a cached promise, we need to handle the caller's abort signal
+          // without affecting the underlying request that other instances might be using
+          if (signal) {
+            const t3 = performance.now();
+            const result = await this.handleAbortForCachedRequest(
+              cached,
+              signal,
+            );
+            const t4 = performance.now();
+            span.setAttribute(
+              "handleAbortMs",
+              Math.round((t4 - t3) * 100) / 100,
+            );
+            span.setAttribute(
+              "totalCacheHitMs",
+              Math.round((t4 - t0) * 100) / 100,
+            );
+            return result;
           }
-          return response.arrayBuffer();
-        } catch (error) {
-          // If the request was aborted, don't cache the error
+          span.setAttribute(
+            "totalCacheHitMs",
+            Math.round((t2 - t0) * 100) / 100,
+          );
+          return cached;
+        }
+
+        span.setAttribute("cacheHit", false);
+
+        // Use global deduplicator to prevent concurrent requests for the same resource
+        // Note: We do NOT pass the signal to the deduplicator - each caller manages their own abort
+        const promise = globalRequestDeduplicator.executeRequest(
+          cacheKey,
+          async () => {
+            const fetchStart = performance.now();
+            try {
+              // Make the fetch request WITHOUT the signal - let each caller handle their own abort
+              // This prevents one instance's abort from affecting other instances using the shared cache
+              const response = await this.host.fetch(url, { headers });
+              const fetchEnd = performance.now();
+              span.setAttribute("fetchMs", fetchEnd - fetchStart);
+
+              if (responseType === "json") {
+                return response.json();
+              }
+              const buffer = await response.arrayBuffer();
+              span.setAttribute("sizeBytes", buffer.byteLength);
+              return buffer;
+            } catch (error) {
+              // If the request was aborted, don't cache the error
+              if (
+                error instanceof DOMException &&
+                error.name === "AbortError"
+              ) {
+                // Remove from cache so other requests can retry
+                mediaCache.delete(cacheKey);
+              }
+              throw error;
+            }
+          },
+        );
+
+        // Cache the promise (not the result) to handle concurrent requests
+        mediaCache.set(cacheKey, promise);
+
+        // Handle the case where the promise might be aborted
+        promise.catch((error) => {
+          // If the request was aborted, remove it from cache to prevent corrupted data
           if (error instanceof DOMException && error.name === "AbortError") {
-            // Remove from cache so other requests can retry
             mediaCache.delete(cacheKey);
           }
-          throw error;
+        });
+
+        // If the caller has a signal, handle abort logic without affecting the underlying request
+        if (signal) {
+          const result = await this.handleAbortForCachedRequest(
+            promise,
+            signal,
+          );
+          const tEnd = performance.now();
+          span.setAttribute(
+            "totalFetchMs",
+            Math.round((tEnd - t0) * 100) / 100,
+          );
+          return result;
         }
+
+        const result = await promise;
+        const tEnd = performance.now();
+        span.setAttribute("totalFetchMs", Math.round((tEnd - t0) * 100) / 100);
+        return result;
       },
     );
-
-    // Cache the promise (not the result) to handle concurrent requests
-    mediaCache.set(cacheKey, promise);
-
-    // Handle the case where the promise might be aborted
-    promise.catch((error) => {
-      // If the request was aborted, remove it from cache to prevent corrupted data
-      if (error instanceof DOMException && error.name === "AbortError") {
-        mediaCache.delete(cacheKey);
-      }
-    });
-
-    // If the caller has a signal, handle abort logic without affecting the underlying request
-    if (signal) {
-      return this.handleAbortForCachedRequest(promise, signal);
-    }
-
-    return promise;
   }
 
   /**