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

package/src/elements/EFVideo.ts

@@ -1,10 +1,27 @@
+import { VideoAsset } from "@editframe/assets/EncodedAsset.js";
 import { Task } from "@lit/task";
-import { css, html } from "lit";
-import { customElement } from "lit/decorators.js";
+import debug from "debug";
+import { css, html, type PropertyValueMap } from "lit";
+import { customElement, state } from "lit/decorators.js";
 import { createRef, ref } from "lit/directives/ref.js";
-
+import { DelayedLoadingState } from "../DelayedLoadingState.js";
 import { TWMixin } from "../gui/TWMixin.js";
+import { type CacheStats, ScrubTrackManager } from "../ScrubTrackManager.js";
 import { EFMedia } from "./EFMedia.js";
+import { printTaskStatus } from "./printTaskStatus.ts";
+
+// EF_FRAMEGEN is a global instance created in EF_FRAMEGEN.ts
+declare global {
+  var EF_FRAMEGEN: import("../EF_FRAMEGEN.js").EFFramegen;
+}
+
+const log = debug("ef:elements:EFVideo");
+
+interface LoadingState {
+  isLoading: boolean;
+  operation: "scrub-segment" | "video-segment" | "seeking" | "decoding" | null;
+  message: string;
+}
 
 @customElement("ef-video")
 export class EFVideo extends TWMixin(EFMedia) {
@@ -15,6 +32,7 @@ export class EFVideo extends TWMixin(EFMedia) {
     css`
       :host {
         display: block;
+        position: relative;
       }
       canvas {
         all: inherit;
@@ -29,12 +47,105 @@ export class EFVideo extends TWMixin(EFMedia) {
         outline: none;
         box-shadow: none;
       }
+      .loading-overlay {
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        background: rgba(0, 0, 0, 0.6);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 10;
+        backdrop-filter: blur(2px);
+      }
+      .loading-content {
+        background: rgba(0, 0, 0, 0.8);
+        border-radius: 8px;
+        padding: 16px 24px;
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        color: white;
+        font-size: 14px;
+        font-weight: 500;
+      }
+      .loading-spinner {
+        width: 20px;
+        height: 20px;
+        border: 2px solid rgba(255, 255, 255, 0.2);
+        border-left: 2px solid #fff;
+        border-radius: 50%;
+        animation: spin 1s linear infinite;
+      }
+      @keyframes spin {
+        0% { transform: rotate(0deg); }
+        100% { transform: rotate(360deg); }
+      }
+      .loading-message {
+        font-size: 12px;
+        opacity: 0.8;
+      }
     `,
   ];
   canvasRef = createRef<HTMLCanvasElement>();
+
+  /**
+   * Scrub track manager for fast timeline navigation
+   */
+  scrubTrackManager?: ScrubTrackManager;
+
+  /**
+   * Track last seek time for fast seeking detection
+   */
+  private lastSeekTimeMs = 0;
+
+  /**
+   * Delayed loading state manager for user feedback
+   */
+  private delayedLoadingState: DelayedLoadingState;
+
+  /**
+   * Loading state for user feedback
+   */
+  @state()
+  loadingState = {
+    isLoading: false,
+    operation: null as LoadingState["operation"],
+    message: "",
+  };
+
+  constructor() {
+    super();
+
+    // Initialize delayed loading state with callback to update UI
+    this.delayedLoadingState = new DelayedLoadingState(
+      250,
+      (isLoading, message) => {
+        this.setLoadingState(isLoading, null, message);
+      },
+    );
+  }
+
   render() {
     return html`
       <canvas ${ref(this.canvasRef)}></canvas>
+      ${
+        this.loadingState.isLoading
+          ? html`
+        <div class="loading-overlay">
+          <div class="loading-content">
+            <div class="loading-spinner"></div>
+            <div>
+              <div>Loading Video...</div>
+              <div class="loading-message">${this.loadingState.message}</div>
+            </div>
+          </div>
+        </div>
+      `
+          : ""
+      }
     `;
   }
 
@@ -46,85 +157,653 @@ export class EFVideo extends TWMixin(EFMedia) {
   // If frames are fed in out of order, the decoder may crash.
   #decoderLock = false;
 
+  // Track if decoder needs reset due to errors
+  #decoderNeedsReset = false;
+
   frameTask = new Task(this, {
-    args: () =>
-      [
-        this.trackFragmentIndexLoader.status,
-        this.initSegmentsLoader.status,
-        this.seekTask.status,
-        this.fetchSeekTask.status,
-        this.videoAssetTask.status,
-        this.paintTask.status,
-      ] as const,
-    task: async () => {
-      await this.trackFragmentIndexLoader.taskComplete;
-      await this.initSegmentsLoader.taskComplete;
+    args: () => [this.desiredSeekTimeMs] as const,
+    onError: (error) => {
+      console.error("frameTask error", error);
+    },
+    task: async ([_desiredSeekTimeMs], { signal }) => {
       await this.seekTask.taskComplete;
-      await this.fetchSeekTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
+      await this.fragmentIndexTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
+      await this.mediaSegmentsTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
       await this.videoAssetTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
       await this.paintTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
+    },
+  });
+
+  get frameTaskStatus() {
+    return {
+      desiredSeekTimeMs: this.desiredSeekTimeMs,
+      fragmentIndexTask: printTaskStatus(this.fragmentIndexTask.status),
+      seekTask: printTaskStatus(this.seekTask.status),
+      mediaSegmentsTask: printTaskStatus(this.mediaSegmentsTask.status),
+      assetSegmentLoader: printTaskStatus(this.assetSegmentLoader.status),
+      assetSegmentKeysTask: printTaskStatus(this.assetSegmentKeysTask.status),
+      assetInitSegmentsTask: printTaskStatus(this.assetInitSegmentsTask.status),
+      videoAssetTask: printTaskStatus(this.videoAssetTask.status),
+      paintTask: printTaskStatus(this.paintTask.status),
+      frameTask: printTaskStatus(this.frameTask.status),
+    };
+  }
+
+  #lastVideoAsset: any = null;
+
+  protected updated(
+    changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>,
+  ): void {
+    super.updated(changedProperties);
+
+    const currentVideoAsset = this.videoAssetTask.value;
+    if (currentVideoAsset !== this.#lastVideoAsset) {
+      // Track video asset changes for reference, but don't reset decoder
+      // Decoder resets should only happen due to actual decoder errors, not normal asset transitions
+      this.#lastVideoAsset = currentVideoAsset;
+    }
+
+    // Initialize scrub track manager for JIT transcode mode
+    this.initializeScrubTrackManager();
+  }
+
+  /**
+   * Initialize scrub track manager if needed
+   */
+  private async initializeScrubTrackManager(): Promise<void> {
+    const mode = this.effectiveMode;
+
+    // Only initialize for JIT transcode mode with valid src
+    if (mode === "jit-transcode" && this.src && !this.scrubTrackManager) {
+      const jitClient = this.jitClientTask.value;
+      if (jitClient) {
+        try {
+          this.scrubTrackManager = new ScrubTrackManager(this.src, jitClient, {
+            onLoadingStateChange: (isLoading: boolean, message?: string) => {
+              if (isLoading) {
+                // Only show loading for user-visible operations (non-background)
+                this.startDelayedLoading(
+                  "scrub-segment",
+                  message || "Loading scrub track...",
+                );
+              } else {
+                this.clearDelayedLoading("scrub-segment");
+              }
+            },
+          });
+
+          await this.scrubTrackManager.initialize();
+        } catch (error) {
+          console.warn("Failed to initialize scrub track manager:", error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Start a delayed loading operation for testing
+   */
+  startDelayedLoading(
+    operationId: string,
+    message: string,
+    options: { background?: boolean } = {},
+  ): void {
+    this.delayedLoadingState.startLoading(operationId, message, options);
+  }
+
+  /**
+   * Clear a delayed loading operation for testing
+   */
+  clearDelayedLoading(operationId: string): void {
+    this.delayedLoadingState.clearLoading(operationId);
+  }
+
+  /**
+   * Set loading state for user feedback
+   */
+  private setLoadingState(
+    isLoading: boolean,
+    operation: LoadingState["operation"] = null,
+    message = "",
+  ): void {
+    this.loadingState = {
+      isLoading,
+      operation,
+      message,
+    };
+  }
+
+  videoAssetTask = new Task(this, {
+    autoRun: true,
+    args: () => [this.effectiveMode, this.mediaSegmentsTask.value] as const,
+    onError: (error) => {
+      console.error("videoAsset task error", error);
+    },
+    task: async ([mode, _files], { signal: _signal }) => {
+      await this.mediaSegmentsTask.taskComplete;
+      if (_signal.aborted) {
+        return undefined;
+      }
+
+      await this.fragmentIndexTask.taskComplete;
+      if (_signal.aborted) {
+        return undefined;
+      }
+
+      // Get fresh values
+      const files = this.mediaSegmentsTask.value;
+      const fragmentIndex = this.fragmentIndexTask.value;
+
+      if (!files) {
+        log("trace: videoAsset task aborted - no files");
+        throw new Error(
+          `Video asset creation failed: No media segment files available. This indicates a problem with media segment loading for source: "${this.src}"`,
+        );
+      }
+
+      const computedVideoTrackId = Object.values(fragmentIndex ?? {}).find(
+        (track) => track.type === "video",
+      )?.track;
+
+      if (computedVideoTrackId === undefined) {
+        log("trace: videoAsset task aborted - no video track");
+        throw new Error(
+          `Video asset creation failed: No video track found in media segments. Source may not contain video content: "${this.src}"`,
+        );
+      }
+
+      const videoFile = files[computedVideoTrackId];
+      if (!videoFile) {
+        log("trace: videoAsset task aborted - no video file");
+        throw new Error(
+          `Video asset creation failed: Video file not available for track ${computedVideoTrackId}. Media segment loading may have failed for source: "${this.src}"`,
+        );
+      }
+
+      // Cleanup existing asset
+      const existingAsset = this.videoAssetTask.value;
+      if (existingAsset) {
+        for (const frame of existingAsset?.decodedFrames || []) {
+          frame.close();
+        }
+        const decoder = existingAsset?.videoDecoder;
+        if (decoder && decoder.state !== "closed") {
+          decoder.close();
+        }
+      }
+
+      if (_signal.aborted) {
+        return undefined;
+      }
+
+      log("trace: creating video asset", { mode });
+
+      // Get start time offset from fragment index (timing correction for FFmpeg processing)
+      const videoTrackFragmentIndex = Object.values(fragmentIndex ?? {}).find(
+        (track) => track.type === "video",
+      );
+      const startTimeOffsetMs = Number(
+        (videoTrackFragmentIndex?.startTimeOffsetMs ?? 0).toFixed(5),
+      );
+
+      // Single branching point for creation method
+      if (mode === "jit-transcode") {
+        const result = await VideoAsset.createFromCompleteMP4(
+          `jit-segment-${computedVideoTrackId}`,
+          videoFile,
+          { startTimeOffsetMs },
+        );
+        return result;
+      }
+      const result = await VideoAsset.createFromReadableStream(
+        "video.mp4",
+        videoFile.stream(),
+        videoFile,
+        { startTimeOffsetMs },
+      );
+      return result;
     },
   });
 
   paintTask = new Task(this, {
-    args: () => [this.videoAssetTask.value, this.desiredSeekTimeMs] as const,
-    task: async (
-      [videoAsset, seekToMs],
-      {
-        signal:
-          _signal /** Aborting seeks is counter-productive. It is better to drop seeks. */,
-      },
-    ) => {
+    args: () => [this.desiredSeekTimeMs] as const,
+    onError: (error) => {
+      console.error("paintTask error", error);
+    },
+    task: async ([_seekToMs], { signal }) => {
+      // Check if we're in production rendering mode vs preview mode
+      const isProductionRendering = this.isInProductionRenderingMode();
+
+      // EF_FRAMEGEN-aware rendering mode detection
+      if (!isProductionRendering) {
+        // Preview mode: skip rendering during initialization to prevent artifacts
+        if (
+          !this.rootTimegroup ||
+          (this.rootTimegroup.currentTimeMs === 0 &&
+            this.desiredSeekTimeMs === 0)
+        ) {
+          return; // Skip initialization frame in preview mode
+        }
+        // Preview mode: proceed with rendering
+      } else {
+        // Production rendering mode: only render when EF_FRAMEGEN has explicitly started frame rendering
+        // This prevents initialization frames before the actual render sequence begins
+        if (!this.rootTimegroup) {
+          return;
+        }
+
+        if (!this.isFrameRenderingActive()) {
+          return; // Wait for EF_FRAMEGEN to start frame sequence
+        }
+
+        // Production mode: EF_FRAMEGEN has started frame sequence, proceed with rendering
+      }
+
+      if (signal.aborted) {
+        return;
+      }
+
+      // CRITICAL: For segment transitions, ensure we wait for the correct mediaSegmentsTask
+      // This prevents using stale VideoAssets from previous segments
+
+      await this.mediaSegmentsTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
+
+      // CRITICAL: Always await fresh videoAsset just before using it
+      // This prevents race conditions where old VideoAssets with closed decoders are used
+      await this.videoAssetTask.taskComplete;
+      if (signal.aborted) {
+        return;
+      }
+
+      // Get fresh values after await - ensures we use current VideoAsset
+      const videoAsset = this.videoAssetTask.value;
+      const currentSeekToMs = this.desiredSeekTimeMs; // Use current seek time, not captured
+
       if (!videoAsset) {
+        log("trace: paintTask aborted - no video asset");
+        throw new Error(
+          `Frame rendering failed: No video asset available. This may indicate a problem with video loading or an invalid source: "${this.src}"`,
+        );
+      }
+
+      // Check if decoder needs reset due to previous errors
+      if (this.#decoderNeedsReset) {
+        try {
+          // Reset the video decoder
+          if (videoAsset?.videoDecoder) {
+            videoAsset.configureDecoder();
+          } else {
+            console.warn("No video decoder available for reset");
+          }
+
+          // Clear the flag after successful reset
+          this.#decoderNeedsReset = false;
+        } catch (resetError) {
+          console.error("reset error", resetError);
+          // Keep the flag set if reset fails
+          throw new Error(
+            `Frame rendering failed: Unable to reset video decoder after previous error. Decoder state: ${resetError instanceof Error ? resetError.message : "Unknown error"}. Try refreshing the page or reloading the video.`,
+          );
+        }
+      }
+      if (signal.aborted) {
         return;
       }
+
       if (this.#decoderLock) {
         return;
       }
+
       try {
         this.#decoderLock = true;
-        const frame = await videoAsset.seekToTime(seekToMs / 1000);
 
-        if (!this.canvasElement) {
-          return;
+        // Validate VideoAsset is still current and decoder is in valid state
+        const currentVideoAsset = this.videoAssetTask.value;
+        if (videoAsset !== currentVideoAsset) {
+          return; // Skip render with stale videoAsset
         }
-        const ctx = this.canvasElement.getContext("2d");
-        if (!(frame && ctx)) {
-          return;
+
+        // Check decoder state before using it
+        const decoderState = videoAsset?.videoDecoder?.state;
+        if (decoderState === "closed") {
+          return; // Skip render with closed decoder
         }
 
-        if (frame?.codedWidth && frame?.codedHeight) {
-          if (
-            this.canvasElement.width !== frame.codedWidth ||
-            this.canvasElement.height !== frame.codedHeight
-          ) {
-            this.canvasElement.width = frame.codedWidth;
-            this.canvasElement.height = frame.codedHeight;
+        // Try scrub track first for JIT transcode mode
+        if (this.effectiveMode === "jit-transcode" && this.scrubTrackManager) {
+          const shouldUseScrub =
+            this.scrubTrackManager.shouldUseScrubTrack(currentSeekToMs);
+          const isFastSeeking = this.scrubTrackManager.isFastSeeking(
+            this.lastSeekTimeMs,
+            currentSeekToMs,
+          );
+
+          if (false || shouldUseScrub || isFastSeeking) {
+            try {
+              // Use delayed loading instead of immediate loading
+              this.startDelayedLoading(
+                "scrub-segment-load",
+                "Loading scrub segment...",
+              );
+
+              const scrubFrame =
+                await this.scrubTrackManager.getScrubFrame(currentSeekToMs);
+
+              if (scrubFrame && this.canvasElement) {
+                this.scrubTrackManager.recordCacheMiss();
+                this.lastSeekTimeMs = currentSeekToMs;
+
+                // Clear loading and display scrub frame
+                this.clearDelayedLoading("scrub-segment-load");
+                return this.displayFrame(scrubFrame, currentSeekToMs);
+              }
+
+              // Scrub frame was null/failed - fall back to normal video
+              console.warn(
+                "Scrub track returned null frame, falling back to normal video",
+              );
+              this.clearDelayedLoading("scrub-segment-load");
+              this.startDelayedLoading(
+                "video-segment-fallback",
+                "Loading high quality video...",
+              );
+            } catch (error) {
+              this.clearDelayedLoading("scrub-segment-load");
+              console.warn(
+                "Scrub track failed, falling back to normal video:",
+                error,
+              );
+
+              // Show loading for normal video fallback
+              this.startDelayedLoading(
+                "video-segment-fallback",
+                "Loading high quality video...",
+              );
+            }
+          } else {
+            // Cache hit for normal video - scrub track manager exists, record the hit
+            this.scrubTrackManager?.recordCacheHit();
           }
         }
 
-        if (frame.format === null) {
-          console.warn("Frame format is null", frame);
-          return seekToMs;
+        // Normal video rendering path (for all cases where scrub track isn't used)
+        // Check if we need to show loading for normal video operations
+        const shouldShowLoading =
+          !this.delayedLoadingState.isLoading &&
+          (this.effectiveMode !== "asset" || !videoAsset);
+
+        if (shouldShowLoading) {
+          this.startDelayedLoading("video-segment", "Loading video segment...");
         }
-        ctx.drawImage(
-          frame,
-          0,
-          0,
-          this.canvasElement.width,
-          this.canvasElement.height,
+
+        // Render normal video - pass fresh VideoAsset reference
+        this.lastSeekTimeMs = currentSeekToMs;
+        const result = await this.renderNormalVideo(
+          videoAsset,
+          currentSeekToMs,
         );
 
-        return seekToMs;
+        // Clear loading state after normal video renders
+        this.clearDelayedLoading("video-segment");
+        this.clearDelayedLoading("video-segment-fallback");
+
+        return result;
       } catch (error) {
-        console.trace("Unexpected error while seeking video", error);
-        // As a practical matter, we should probably just re-create the VideoAsset if decoding fails.
-        // The decoder is probably in an invalid state anyway.
+        // Clear all loading states on error
+        this.clearDelayedLoading("scrub-segment-load");
+        this.clearDelayedLoading("video-segment");
+        this.clearDelayedLoading("video-segment-fallback");
+
+        // Handle errors with proper error propagation
+        if (error instanceof Error) {
+          if (
+            error.name === "DataError" &&
+            error.message.includes("key frame is required")
+          ) {
+            console.warn(
+              "Decoder reset during VideoAsset due to key frame requirement",
+            );
+            this.#decoderNeedsReset = true;
+
+            if (this.effectiveMode === "jit-transcode") {
+              this.requestUpdate();
+            }
+            throw error;
+          }
+          if (error.name === "AbortError") {
+            // AbortError is expected behavior when tasks are cancelled
+            throw new Error(
+              "Frame rendering cancelled: Operation was aborted, likely due to a new seek request or component unmounting.",
+            );
+          }
+          if (
+            error.message.includes("VideoAsset decoder closed") ||
+            error.message.includes("recreation in progress")
+          ) {
+            // This is now expected behavior during VideoAsset transitions - don't treat as error
+            return; // Gracefully abort instead of throwing
+          }
+          if (
+            error.name === "InvalidStateError" &&
+            error.message.includes("closed codec")
+          ) {
+            // Expected during VideoAsset recreation - gracefully abort
+            return; // Gracefully abort instead of throwing
+          }
+          console.warn("Decoder reset during VideoAsset recreation", error);
+          this.#decoderNeedsReset = true;
+          throw error;
+        }
+
+        // For non-Error objects, still provide descriptive error
+        throw new Error(
+          `Frame rendering failed: Unknown error during video rendering at ${currentSeekToMs}ms. Error: ${String(error)}`,
+        );
       } finally {
         this.#decoderLock = false;
       }
     },
   });
+
+  /**
+   * Render normal video using existing logic
+   */
+  private async renderNormalVideo(
+    videoAsset: VideoAsset,
+    seekToMs: number,
+  ): Promise<number> {
+    let targetSeekTimeSeconds = seekToMs / 1000;
+
+    try {
+      // Validate VideoAsset is still current before seeking
+      const currentVideoAsset = this.videoAssetTask.value;
+      if (videoAsset !== currentVideoAsset) {
+        throw new Error(
+          "VideoAsset decoder closed during seek - recreation in progress",
+        );
+      }
+
+      // Check decoder state immediately before seeking
+      const decoderState = videoAsset?.videoDecoder?.state;
+      if (decoderState === "closed") {
+        throw new Error(
+          "VideoAsset decoder closed during seek - recreation in progress",
+        );
+      }
+      if (this.effectiveMode === "jit-transcode") {
+        targetSeekTimeSeconds %= 2;
+      }
+
+      const frame = await videoAsset.seekToTime(targetSeekTimeSeconds);
+
+      if (frame) {
+        // Final validation that VideoAsset is still current before displaying
+        const finalVideoAsset = this.videoAssetTask.value;
+        if (videoAsset !== finalVideoAsset) {
+          frame.close(); // Clean up the frame
+          throw new Error(
+            "VideoAsset decoder closed during seek - recreation in progress",
+          );
+        }
+
+        // Read fresh time right before displaying - final safeguard against stale values
+        const finalSeekToMs = this.desiredSeekTimeMs;
+        return this.displayFrame(frame, finalSeekToMs);
+      }
+
+      log("trace: no frame returned from seekToTime");
+      throw new Error(
+        `Frame rendering failed: No frame available at time ${seekToMs}ms (${targetSeekTimeSeconds}s). This may indicate seeking beyond video duration, corrupted video data, or an incompatible video format.`,
+      );
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        (error.message.includes("VideoAsset decoder closed") ||
+          error.message.includes("recreation in progress"))
+      ) {
+        // This is the expected narrow timing window race condition during VideoAsset transitions
+        throw error; // Re-throw to let paintTask handle it gracefully
+      }
+
+      // Re-throw other unexpected errors
+      throw error;
+    }
+  }
+
+  /**
+   * Display a video frame on the canvas
+   */
+  private displayFrame(frame: VideoFrame, seekToMs: number): number {
+    log("trace: displayFrame start", { seekToMs, frameFormat: frame.format });
+    if (!this.canvasElement) {
+      log("trace: displayFrame aborted - no canvas element");
+      throw new Error(
+        `Frame display failed: Canvas element is not available at time ${seekToMs}ms. The video component may not be properly initialized.`,
+      );
+    }
+
+    const ctx = this.canvasElement.getContext("2d");
+    if (!ctx) {
+      log("trace: displayFrame aborted - no canvas context");
+      throw new Error(
+        `Frame display failed: Unable to get 2D canvas context at time ${seekToMs}ms. This may indicate a browser compatibility issue or canvas corruption.`,
+      );
+    }
+
+    if (frame?.codedWidth && frame?.codedHeight) {
+      if (
+        this.canvasElement.width !== frame.codedWidth ||
+        this.canvasElement.height !== frame.codedHeight
+      ) {
+        log("trace: updating canvas dimensions", {
+          width: frame.codedWidth,
+          height: frame.codedHeight,
+        });
+        this.canvasElement.width = frame.codedWidth;
+        this.canvasElement.height = frame.codedHeight;
+      }
+    }
+
+    if (frame.format === null) {
+      log("trace: displayFrame aborted - null frame format");
+      throw new Error(
+        `Frame display failed: Video frame has null format at time ${seekToMs}ms. This indicates corrupted or incompatible video data.`,
+      );
+    }
+
+    log("trace: drawing frame to canvas");
+    ctx.drawImage(
+      frame,
+      0,
+      0,
+      this.canvasElement.width,
+      this.canvasElement.height,
+    );
+    log("trace: frame drawn to canvas", { seekToMs });
+
+    return seekToMs;
+  }
+
+  /**
+   * Check if we're in production rendering mode (EF_FRAMEGEN active) vs preview mode
+   */
+  private isInProductionRenderingMode(): boolean {
+    // Check if EF_RENDERING function exists and returns true (production rendering)
+    if (typeof window.EF_RENDERING === "function") {
+      return window.EF_RENDERING();
+    }
+
+    // Check if workbench is in rendering mode
+    const workbench = document.querySelector("ef-workbench") as any;
+    if (workbench?.rendering) {
+      return true;
+    }
+
+    // Check if EF_FRAMEGEN exists and has render options (indicates active rendering)
+    if (window.EF_FRAMEGEN?.renderOptions) {
+      return true;
+    }
+
+    // Default to preview mode
+    return false;
+  }
+
+  /**
+   * Check if EF_FRAMEGEN has explicitly started frame rendering (not just initialization)
+   */
+  private isFrameRenderingActive(): boolean {
+    if (!window.EF_FRAMEGEN?.renderOptions) {
+      return false;
+    }
+
+    // In production mode, only render when EF_FRAMEGEN has actually begun frame sequence
+    // Check if we're past the initialization phase by looking for explicit frame control
+    const renderOptions = window.EF_FRAMEGEN.renderOptions;
+    const renderStartTime = renderOptions.encoderOptions.fromMs;
+    const currentTime = this.rootTimegroup?.currentTimeMs || 0;
+
+    // We're in active frame rendering if:
+    // 1. currentTime >= renderStartTime (includes the starting frame)
+    return currentTime >= renderStartTime;
+  }
+
+  /**
+   * Get scrub track performance statistics
+   */
+  getScrubTrackStats(): CacheStats | null {
+    return this.scrubTrackManager?.getCacheStats() || null;
+  }
+
+  /**
+   * Clean up resources when component is disconnected
+   */
+  disconnectedCallback(): void {
+    super.disconnectedCallback();
+
+    // Clean up scrub track manager
+    this.scrubTrackManager?.cleanup();
+
+    // Clean up delayed loading state
+    this.delayedLoadingState.clearAllLoading();
+  }
 }
 
 declare global {