@editframe/elements 0.17.6-beta.0 → 0.18.3-beta.0

package/src/elements/EFMedia/services/AudioElementFactory.browsertest.ts

@@ -0,0 +1,325 @@
+import { afterEach, beforeEach, describe, vi } from "vitest";
+import { assetMSWHandlers } from "../../../../test/useAssetMSW.js";
+import { test as baseTest } from "../../../../test/useMSW.js";
+import { AudioElementFactory } from "./AudioElementFactory.js";
+import { MediaSourceService } from "./MediaSourceService.js";
+
+const test = baseTest.extend({
+  setupAssetHandlers: [
+    async ({ worker }, use) => {
+      worker.use(...assetMSWHandlers);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+
+describe("AudioElementFactory", () => {
+  let factory: AudioElementFactory;
+  let mediaSourceService: MediaSourceService;
+  let audioContext1: AudioContext;
+  let audioContext2: AudioContext;
+
+  beforeEach(() => {
+    // Clean up any existing elements
+    while (document.body.children.length) {
+      document.body.children[0]?.remove();
+    }
+
+    factory = new AudioElementFactory();
+    mediaSourceService = new MediaSourceService();
+    audioContext1 = new AudioContext();
+    audioContext2 = new AudioContext();
+  });
+
+  afterEach(async () => {
+    factory.clearCache();
+    mediaSourceService.cleanup();
+    // Close AudioContexts safely
+    if (audioContext1.state !== "closed") await audioContext1.close();
+    if (audioContext2.state !== "closed") await audioContext2.close();
+    vi.clearAllMocks();
+  });
+
+  describe("MediaElementSource Creation", () => {
+    test("should create MediaElementAudioSourceNode when MediaSource is ready", async ({
+      expect,
+    }) => {
+      // Mock a successful MediaSource
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(
+        document.createElement("audio"),
+      );
+
+      const source = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      expect(source).toBeDefined();
+      expect(source).toBeInstanceOf(MediaElementAudioSourceNode);
+      expect(mediaSourceService.ensureInitialized).toHaveBeenCalledOnce();
+    });
+
+    test("should throw error when audio element not available", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(null);
+
+      await expect(
+        factory.createMediaElementSource(audioContext1, mediaSourceService),
+      ).rejects.toThrow("Audio element not available from MediaSourceService");
+    });
+
+    test("should propagate MediaSourceService initialization errors", async ({
+      expect,
+    }) => {
+      const initError = new Error("MediaSource initialization failed");
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockRejectedValue(
+        initError,
+      );
+
+      await expect(
+        factory.createMediaElementSource(audioContext1, mediaSourceService),
+      ).rejects.toThrow("MediaSource initialization failed");
+    });
+  });
+
+  describe("Caching Behavior", () => {
+    test("should cache MediaElementSource per AudioContext", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(
+        document.createElement("audio"),
+      );
+
+      const source1 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+      const source2 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      expect(source1).toBe(source2);
+      expect(mediaSourceService.ensureInitialized).toHaveBeenCalledOnce();
+    });
+
+    test("should create separate sources for different AudioContexts", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+
+      // Mock different audio elements for each call
+      const audio1 = document.createElement("audio");
+      const audio2 = document.createElement("audio");
+      vi.spyOn(mediaSourceService, "getAudioElement")
+        .mockReturnValueOnce(audio1)
+        .mockReturnValueOnce(audio2);
+
+      const source1 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+      const source2 = await factory.createMediaElementSource(
+        audioContext2,
+        mediaSourceService,
+      );
+
+      expect(source1).not.toBe(source2);
+      expect(mediaSourceService.ensureInitialized).toHaveBeenCalledTimes(2);
+    });
+
+    test("should respect hasCachedSource method", async ({ expect }) => {
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(
+        document.createElement("audio"),
+      );
+
+      await factory.createMediaElementSource(audioContext1, mediaSourceService);
+
+      expect(factory.hasCachedSource(audioContext1)).toBe(true);
+      expect(factory.hasCachedSource(audioContext2)).toBe(false);
+    });
+
+    test("should not use cache when AudioContext is closed", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      // Mock different audio elements to avoid "already connected" error
+      const audio1 = document.createElement("audio");
+      const audio2 = document.createElement("audio");
+      vi.spyOn(mediaSourceService, "getAudioElement")
+        .mockReturnValueOnce(audio1)
+        .mockReturnValueOnce(audio2);
+
+      const source1 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      // Close the AudioContext
+      await audioContext1.close();
+
+      // Should create new source since context is closed
+      const source2 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      expect(source1).not.toBe(source2);
+      expect(mediaSourceService.ensureInitialized).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("Cleanup and Lifecycle", () => {
+    test("should clear all cached sources", async ({ expect }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      // Mock different audio elements for each AudioContext
+      const audio1 = document.createElement("audio");
+      const audio2 = document.createElement("audio");
+      vi.spyOn(mediaSourceService, "getAudioElement")
+        .mockReturnValueOnce(audio1)
+        .mockReturnValueOnce(audio2);
+
+      await factory.createMediaElementSource(audioContext1, mediaSourceService);
+      await factory.createMediaElementSource(audioContext2, mediaSourceService);
+
+      // Due to browser limitation, only the most recent AudioContext should remain cached
+      // (audioContext1 gets disconnected when audioContext2 is created)
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+      expect(factory.hasCachedSource(audioContext2)).toBe(true);
+
+      factory.clearCache();
+
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+      expect(factory.hasCachedSource(audioContext2)).toBe(false);
+    });
+
+    test("should automatically clean up cache when AudioContext state changes", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(
+        document.createElement("audio"),
+      );
+
+      await factory.createMediaElementSource(audioContext1, mediaSourceService);
+      expect(factory.hasCachedSource(audioContext1)).toBe(true);
+
+      // Simulate AudioContext state change to closed
+      await audioContext1.close();
+
+      // Trigger state change event manually since we're in test environment
+      audioContext1.dispatchEvent(new Event("statechange"));
+
+      // Wait a tick for event processing
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+    });
+
+    test("should handle multiple cleanup calls gracefully", ({ expect }) => {
+      expect(() => {
+        factory.clearCache();
+        factory.clearCache();
+        factory.clearCache();
+      }).not.toThrow();
+    });
+  });
+
+  describe("Integration with MediaSourceService", () => {
+    test("should call ensureInitialized before creating source", async ({
+      expect,
+    }) => {
+      const ensureInitSpy = vi
+        .spyOn(mediaSourceService, "ensureInitialized")
+        .mockResolvedValue();
+      const getAudioElementSpy = vi
+        .spyOn(mediaSourceService, "getAudioElement")
+        .mockReturnValue(document.createElement("audio"));
+
+      await factory.createMediaElementSource(audioContext1, mediaSourceService);
+
+      expect(ensureInitSpy).toHaveBeenCalled();
+      expect(getAudioElementSpy).toHaveBeenCalled();
+      // Both should be called, order verified by implementation logic
+    });
+
+    test("should handle MediaSourceService reinitialization", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+
+      const audio1 = document.createElement("audio");
+      const audio2 = document.createElement("audio");
+      vi.spyOn(mediaSourceService, "getAudioElement")
+        .mockReturnValueOnce(audio1)
+        .mockReturnValueOnce(audio2);
+
+      const source1 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      // Clear cache to simulate reinitialization
+      factory.clearCache();
+
+      const source2 = await factory.createMediaElementSource(
+        audioContext1,
+        mediaSourceService,
+      );
+
+      expect(source1).not.toBe(source2);
+      expect(mediaSourceService.ensureInitialized).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("Error Handling", () => {
+    test("should handle MediaSourceService timeout gracefully", async ({
+      expect,
+    }) => {
+      const timeoutError = new Error(
+        "MediaSource failed to open within timeout",
+      );
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockRejectedValue(
+        timeoutError,
+      );
+
+      await expect(
+        factory.createMediaElementSource(audioContext1, mediaSourceService),
+      ).rejects.toThrow("MediaSource failed to open within timeout");
+
+      // Should not have cached anything on error
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+    });
+
+    test("should handle createMediaElementSource browser errors", async ({
+      expect,
+    }) => {
+      vi.spyOn(mediaSourceService, "ensureInitialized").mockResolvedValue();
+      vi.spyOn(mediaSourceService, "getAudioElement").mockReturnValue(
+        document.createElement("audio"),
+      );
+
+      // Mock createMediaElementSource to throw
+      const createSourceError = new Error("HTMLMediaElement already connected");
+      vi.spyOn(audioContext1, "createMediaElementSource").mockImplementation(
+        () => {
+          throw createSourceError;
+        },
+      );
+
+      await expect(
+        factory.createMediaElementSource(audioContext1, mediaSourceService),
+      ).rejects.toThrow("HTMLMediaElement already connected");
+
+      expect(factory.hasCachedSource(audioContext1)).toBe(false);
+    });
+  });
+});

package/src/elements/EFMedia/services/AudioElementFactory.ts

@@ -0,0 +1,119 @@
+import type { MediaSourceService } from "./MediaSourceService.js";
+
+/**
+ * Factory for creating and caching MediaElementAudioSourceNode instances
+ * Handles the complex lifecycle and caching logic previously embedded in EFMedia
+ */
+export class AudioElementFactory {
+  private cache = new WeakMap<AudioContext, MediaElementAudioSourceNode>();
+  private currentSource: MediaElementAudioSourceNode | null = null;
+  private currentAudioContext: AudioContext | null = null;
+
+  /**
+   * Create or retrieve cached MediaElementAudioSourceNode for the given AudioContext
+   */
+  async createMediaElementSource(
+    audioContext: AudioContext,
+    mediaSourceService: MediaSourceService,
+  ): Promise<MediaElementAudioSourceNode> {
+    // Check if we already have a cached source for this AudioContext
+    const cached = this.cache.get(audioContext);
+    if (
+      cached &&
+      audioContext.state !== "closed" &&
+      this.currentAudioContext === audioContext
+    ) {
+      return cached;
+    }
+
+    // Disconnect previous MediaElementSource BEFORE any operations if switching AudioContexts
+    // HTML audio elements can only be connected to one MediaElementSourceNode at a time
+    if (this.currentSource && this.currentAudioContext !== audioContext) {
+      this.currentSource.disconnect();
+      if (this.currentAudioContext) {
+        this.cache.delete(this.currentAudioContext);
+      }
+      // Clear current tracking immediately
+      this.currentSource = null;
+      this.currentAudioContext = null;
+    }
+
+    // Ensure MediaSource is initialized
+    await mediaSourceService.ensureInitialized();
+
+    const audioElement = mediaSourceService.getAudioElement();
+    if (!audioElement) {
+      throw new Error("Audio element not available from MediaSourceService");
+    }
+
+    // Create MediaElementAudioSourceNode
+    let mediaElementSource: MediaElementAudioSourceNode;
+    try {
+      mediaElementSource = audioContext.createMediaElementSource(audioElement);
+    } catch (error) {
+      // If still connected to another source, force clear and retry once
+      if (
+        error instanceof Error &&
+        error.message.includes("already connected")
+      ) {
+        // Clear all caches and try to disconnect any lingering connections
+        this.clearCache();
+        try {
+          mediaElementSource =
+            audioContext.createMediaElementSource(audioElement);
+        } catch (retryError) {
+          console.warn(
+            "AudioElementFactory: Failed to create MediaElementSource even after clearing cache:",
+            retryError,
+          );
+          throw retryError;
+        }
+      } else {
+        throw error;
+      }
+    }
+
+    // Update current tracking
+    this.currentSource = mediaElementSource;
+    this.currentAudioContext = audioContext;
+
+    // Cache the source for this AudioContext
+    this.cache.set(audioContext, mediaElementSource);
+
+    // Clean up cache and tracking when AudioContext is closed
+    const cleanup = () => {
+      if (audioContext.state === "closed") {
+        this.cache.delete(audioContext);
+        if (this.currentAudioContext === audioContext) {
+          this.currentSource = null;
+          this.currentAudioContext = null;
+        }
+        audioContext.removeEventListener("statechange", cleanup);
+      }
+    };
+    audioContext.addEventListener("statechange", cleanup);
+
+    return mediaElementSource;
+  }
+
+  /**
+   * Clear all cached sources (useful for testing or cleanup)
+   */
+  clearCache(): void {
+    // Disconnect current source if it exists
+    if (this.currentSource) {
+      this.currentSource.disconnect();
+    }
+
+    this.cache = new WeakMap();
+    this.currentSource = null;
+    this.currentAudioContext = null;
+  }
+
+  /**
+   * Check if we have a cached source for the given AudioContext
+   */
+  hasCachedSource(audioContext: AudioContext): boolean {
+    return this.cache.has(audioContext) && audioContext.state !== "closed";
+  }
+}

package/src/elements/EFMedia/services/MediaSourceService.browsertest.ts

@@ -0,0 +1,257 @@
+import { afterEach, beforeEach, describe, vi } from "vitest";
+import { assetMSWHandlers } from "../../../../test/useAssetMSW.js";
+import { test as baseTest } from "../../../../test/useMSW.js";
+import { MediaSourceService } from "./MediaSourceService.js";
+
+const test = baseTest.extend({
+  setupAssetHandlers: [
+    async ({ worker }, use) => {
+      worker.use(...assetMSWHandlers);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+
+describe("MediaSourceService", () => {
+  let service: MediaSourceService;
+
+  beforeEach(() => {
+    // Clean up any existing elements
+    while (document.body.children.length) {
+      document.body.children[0]?.remove();
+    }
+  });
+
+  afterEach(() => {
+    service?.cleanup();
+    vi.clearAllMocks();
+  });
+
+  describe("Initialization", () => {
+    test("should create service without initializing MediaSource", ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      expect(service).toBeDefined();
+      expect(service.isReady()).toBe(false);
+      expect(service.getAudioElement()).toBeNull();
+    });
+
+    test("should initialize MediaSource when ensureInitialized is called", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      try {
+        await service.ensureInitialized();
+
+        // If initialization succeeds (real browser), verify behavior
+        expect(service.isReady()).toBe(true);
+        expect(service.getAudioElement()).toBeDefined();
+        expect(service.getAudioElement()).toBeInstanceOf(HTMLAudioElement);
+      } catch (error) {
+        // If MediaSource doesn't work in test environment, verify error handling
+        expect(error).toBeDefined();
+        expect(service.isReady()).toBe(false);
+      }
+    });
+
+    test("should not reinitialize if already ready", async ({ expect }) => {
+      service = new MediaSourceService();
+
+      await service.ensureInitialized();
+      const firstElement = service.getAudioElement();
+
+      await service.ensureInitialized();
+      const secondElement = service.getAudioElement();
+
+      expect(firstElement).toBe(secondElement);
+    });
+
+    test("should call onReady callback when initialized", async ({
+      expect,
+    }) => {
+      const onReady = vi.fn();
+      service = new MediaSourceService({ onReady });
+
+      await service.ensureInitialized();
+
+      expect(onReady).toHaveBeenCalledOnce();
+    });
+
+    test("should call onError callback on initialization failure", async ({
+      expect,
+    }) => {
+      const onError = vi.fn();
+      // Use default timeout but expect failures in test environment
+      service = new MediaSourceService({ onError });
+
+      try {
+        await service.ensureInitialized();
+      } catch (error) {
+        // MediaSource may not work in test environment - that's expected
+        expect(error).toBeDefined();
+      }
+
+      // onError might have been called during MediaSource creation
+      if (onError.mock.calls.length > 0) {
+        expect(onError).toHaveBeenCalled();
+      }
+    });
+  });
+
+  describe("Audio Element Management", () => {
+    test("should return null audio element when not initialized", ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      expect(service.getAudioElement()).toBeNull();
+    });
+
+    test("should return audio element after initialization (when possible)", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      try {
+        await service.ensureInitialized();
+        const audioElement = service.getAudioElement();
+
+        if (service.isReady()) {
+          expect(audioElement).toBeDefined();
+          expect(audioElement).toBeInstanceOf(HTMLAudioElement);
+        }
+      } catch (_error) {
+        // MediaSource might not work in test environment
+        expect(service.getAudioElement()).toBeNull();
+      }
+    });
+
+    test("should handle cleanup and reinitialization cycle", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      try {
+        await service.ensureInitialized();
+        service.cleanup();
+
+        expect(service.isReady()).toBe(false);
+        expect(service.getAudioElement()).toBeNull();
+
+        // Try to reinitialize
+        await service.ensureInitialized();
+        // Should either work or fail consistently
+        expect(typeof service.isReady()).toBe("boolean");
+      } catch (_error) {
+        // Expected in test environment - verify cleanup still works
+        expect(service.isReady()).toBe(false);
+      }
+    });
+  });
+
+  describe("Segment Feeding", () => {
+    test("should auto-initialize when feeding segments", async ({ expect }) => {
+      service = new MediaSourceService();
+      const segmentData = new ArrayBuffer(1024);
+
+      expect(service.isReady()).toBe(false);
+
+      await service.feedSegment(segmentData);
+
+      expect(service.isReady()).toBe(true);
+    });
+
+    test("should handle segment feeding when already initialized", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+      await service.ensureInitialized();
+
+      const segmentData = new ArrayBuffer(1024);
+
+      // Should not throw
+      await expect(service.feedSegment(segmentData)).resolves.not.toThrow();
+    });
+  });
+
+  describe("Time Management", () => {
+    test("should handle time setting when not initialized", ({ expect }) => {
+      service = new MediaSourceService();
+
+      // Should not throw
+      expect(() => service.setCurrentTime(1000)).not.toThrow();
+    });
+
+    test("should set time on audio element when initialized", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+      await service.ensureInitialized();
+
+      const audioElement = service.getAudioElement();
+      const setCurrentTimeSpy = vi.spyOn(audioElement!, "currentTime", "set");
+
+      service.setCurrentTime(2000);
+
+      expect(setCurrentTimeSpy).toHaveBeenCalledWith(2);
+    });
+  });
+
+  describe("Cleanup", () => {
+    test("should handle cleanup when not initialized", ({ expect }) => {
+      service = new MediaSourceService();
+
+      expect(() => service.cleanup()).not.toThrow();
+      expect(service.isReady()).toBe(false);
+    });
+
+    test("should cleanup initialized MediaSource", async ({ expect }) => {
+      service = new MediaSourceService();
+      await service.ensureInitialized();
+
+      expect(service.isReady()).toBe(true);
+
+      service.cleanup();
+
+      expect(service.isReady()).toBe(false);
+      expect(service.getAudioElement()).toBeNull();
+    });
+
+    test("should allow reinitialization after cleanup", async ({ expect }) => {
+      service = new MediaSourceService();
+
+      await service.ensureInitialized();
+      service.cleanup();
+      await service.ensureInitialized();
+
+      expect(service.isReady()).toBe(true);
+      expect(service.getAudioElement()).toBeDefined();
+    });
+  });
+
+  describe("Buffered Ranges", () => {
+    test("should return null buffered ranges when not initialized", ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+
+      expect(service.getBuffered()).toBeNull();
+    });
+
+    test("should return buffered ranges when initialized", async ({
+      expect,
+    }) => {
+      service = new MediaSourceService();
+      await service.ensureInitialized();
+
+      const buffered = service.getBuffered();
+
+      // May be null or TimeRanges depending on state
+      expect(buffered === null || buffered instanceof TimeRanges).toBe(true);
+    });
+  });
+});