@editframe/elements 0.37.3-beta → 0.38.0

package/dist/preview/FrameController.js.map

@@ -1 +1 @@
-{"version":3,"file":"FrameController.js","names":["#rootElement","#abortController","#renderInProgress","#pendingRenderTime","#queryVisibleElements","result: FrameRenderable[]","#getChildrenIncludingSlotted","assignedElements: Element[]","frameTaskPromise: Promise<void>","taskObj: FrameTask"],"sources":["../../src/preview/FrameController.ts"],"sourcesContent":["/**\n * FrameController: Centralized frame rendering control\n *\n * Replaces the distributed Lit Task hierarchy with a single control loop\n * that queries elements and coordinates rendering directly.\n *\n * Benefits over the previous Task-based system:\n * - Single abort controller instead of distributed abort handling\n * - Clear prepare → render phases\n * - All coordination visible in one place\n * - No Lit Task reactivity overhead\n */\n\nimport type { LitElement } from \"lit\";\n\n// ============================================================================\n// Priority Constants\n// ============================================================================\n// Lower numbers render first. Elements with dependencies should have higher\n// priority numbers than their dependencies.\n//\n// Example: Waveform depends on audio analysis data, so it renders after audio.\n// ============================================================================\n\n/**\n * Priority for video elements.\n * Video renders first as other elements may depend on video frames being ready.\n */\nexport const PRIORITY_VIDEO = 1;\n\n/**\n * Priority for captions elements.\n * Captions render after video so they can overlay correctly.\n */\nexport const PRIORITY_CAPTIONS = 2;\n\n/**\n * Priority for audio elements.\n * Audio renders after captions (no visual dependency, but keeps consistent ordering).\n */\nexport const PRIORITY_AUDIO = 3;\n\n/**\n * Priority for waveform elements.\n * Waveform renders after audio because it depends on audio analysis data.\n */\nexport const PRIORITY_WAVEFORM = 4;\n\n/**\n * Priority for image elements.\n * Images render with low priority as they're typically static.\n */\nexport const PRIORITY_IMAGE = 5;\n\n/**\n * Default priority for elements that don't specify one.\n * High number ensures custom elements render after standard elements.\n */\nexport const PRIORITY_DEFAULT = 100;\n\n/**\n * State returned by elements describing their readiness for a given time.\n */\nexport interface FrameState {\n  /**\n   * Whether async preparation is needed before rendering.\n   * Examples: video needs to seek, captions need to load data.\n   */\n  needsPreparation: boolean;\n\n  /**\n   * Whether the element is ready to render synchronously.\n   * True when all async work is complete and renderFrame() can be called.\n   */\n  isReady: boolean;\n\n  /**\n   * Rendering priority hint. Lower numbers render first.\n   * Used to order render calls for elements with dependencies.\n   * \n   * Standard priorities:\n   * - PRIORITY_VIDEO (1): Video elements\n   * - PRIORITY_CAPTIONS (2): Caption overlays\n   * - PRIORITY_AUDIO (3): Audio elements\n   * - PRIORITY_WAVEFORM (4): Audio visualizers (depend on audio)\n   * - PRIORITY_IMAGE (5): Static images\n   * - PRIORITY_DEFAULT (100): Fallback for custom elements\n   */\n  priority: number;\n}\n\n/**\n * Interface that elements implement to participate in centralized frame rendering.\n * Elements keep their rendering logic local but expose a standardized interface.\n */\nexport interface FrameRenderable {\n  /**\n   * Query the element's readiness state for a given time.\n   * Must be synchronous and cheap to call.\n   */\n  getFrameState(timeMs: number): FrameState;\n\n  /**\n   * Async preparation phase. Called when getFrameState().needsPreparation is true.\n   * Performs any async work needed before rendering (seeking, loading, etc.).\n   *\n   * @param timeMs - The time to prepare for\n   * @param signal - Abort signal for cancellation\n   */\n  prepareFrame(timeMs: number, signal: AbortSignal): Promise<void>;\n\n  /**\n   * Synchronous render phase. Called after all preparation is complete.\n   * Performs the actual rendering (paint to canvas, update DOM, etc.).\n   *\n   * @param timeMs - The time to render\n   */\n  renderFrame(timeMs: number): void;\n}\n\n/**\n * Type guard to check if an element implements FrameRenderable.\n */\nexport function isFrameRenderable(element: unknown): element is FrameRenderable {\n  return (\n    typeof element === \"object\" &&\n    element !== null &&\n    \"getFrameState\" in element &&\n    \"prepareFrame\" in element &&\n    \"renderFrame\" in element &&\n    typeof (element as FrameRenderable).getFrameState === \"function\" &&\n    typeof (element as FrameRenderable).prepareFrame === \"function\" &&\n    typeof (element as FrameRenderable).renderFrame === \"function\"\n  );\n}\n\n/**\n * Options for FrameController.renderFrame()\n */\nexport interface RenderFrameOptions {\n  /**\n   * Whether to wait for Lit updateComplete before querying elements.\n   * Default: true\n   */\n  waitForLitUpdate?: boolean;\n\n  /**\n   * Callback to update CSS animations after frame rendering completes.\n   * Called with the root element after all elements have rendered.\n   * This centralizes animation synchronization in one place.\n   */\n  onAnimationsUpdate?: (rootElement: Element) => void;\n}\n\n/**\n * Central controller for frame rendering.\n * Lives at the root timegroup and orchestrates all element rendering.\n */\nexport class FrameController {\n  #rootElement: LitElement & { currentTimeMs: number };\n  #abortController: AbortController | null = null;\n  #renderInProgress = false;\n  #pendingRenderTime: number | null = null;\n\n  constructor(rootElement: LitElement & { currentTimeMs: number }) {\n    this.#rootElement = rootElement;\n  }\n\n  /**\n   * Cancel any in-progress render operation.\n   */\n  abort(): void {\n    this.#abortController?.abort();\n    this.#abortController = null;\n  }\n\n  /**\n   * Render a frame at the specified time.\n   *\n   * This is the main entry point for frame rendering. It:\n   * 1. Cancels any previous in-progress render\n   * 2. Queries all visible FrameRenderable elements\n   * 3. Runs preparation in parallel for elements that need it\n   * 4. Runs render in priority order\n   *\n   * @param timeMs - The time in milliseconds to render\n   * @param options - Optional configuration\n   */\n  async renderFrame(\n    timeMs: number,\n    options: RenderFrameOptions = {}\n  ): Promise<void> {\n    const { waitForLitUpdate = true, onAnimationsUpdate } = options;\n\n    // If a render is in progress, queue this one\n    if (this.#renderInProgress) {\n      this.#pendingRenderTime = timeMs;\n      return;\n    }\n\n    // Cancel any previous render operation\n    this.#abortController?.abort();\n    this.#abortController = new AbortController();\n    const signal = this.#abortController.signal;\n\n    this.#renderInProgress = true;\n\n    try {\n      // Wait for Lit to propagate time changes to children\n      if (waitForLitUpdate) {\n        await this.#rootElement.updateComplete;\n        signal.throwIfAborted();\n      }\n\n      // Query all visible elements that implement FrameRenderable\n      // Pass the timeMs parameter to use for visibility checks (root element's time may be stale)\n      const elements = this.#queryVisibleElements(timeMs);\n      signal.throwIfAborted();\n\n      // Phase 1: Parallel preparation\n      const elementsNeedingPreparation = elements.filter(\n        (el) => el.getFrameState(timeMs).needsPreparation\n      );\n\n      if (elementsNeedingPreparation.length > 0) {\n        await Promise.all(\n          elementsNeedingPreparation.map((el) => el.prepareFrame(timeMs, signal))\n        );\n        signal.throwIfAborted();\n      }\n\n      // Phase 2: Sequential render by priority\n      const sortedElements = [...elements].sort(\n        (a, b) => a.getFrameState(timeMs).priority - b.getFrameState(timeMs).priority\n      );\n\n      for (const element of sortedElements) {\n        signal.throwIfAborted();\n        element.renderFrame(timeMs);\n      }\n\n      // Phase 3: Update CSS animations (centralized)\n      if (onAnimationsUpdate) {\n        onAnimationsUpdate(this.#rootElement);\n      }\n    } finally {\n      this.#renderInProgress = false;\n\n      // Process any queued render\n      if (this.#pendingRenderTime !== null) {\n        const pendingTime = this.#pendingRenderTime;\n        this.#pendingRenderTime = null;\n        // Don't await - fire and forget to avoid recursive waiting\n        this.renderFrame(pendingTime, options).catch(() => {\n          // Silently ignore errors from queued renders (likely aborted)\n        });\n      }\n    }\n  }\n\n  /**\n   * Query all visible FrameRenderable elements in the tree.\n   * Uses temporal visibility to filter out elements not visible at current time.\n   * \n   * IMPORTANT: For temporal elements, we use temporal visibility (startTimeMs/endTimeMs)\n   * instead of CSS visibility. This is because updateAnimations sets display:none on\n   * elements outside their time range, but that CSS state is from the PREVIOUS frame.\n   * When seeking, we need to evaluate visibility based on the NEW time, not stale CSS.\n   * \n   * @param timeMs - The time to use for visibility checks. This should be the target\n   *                 render time, not read from root element (which may be stale).\n   */\n  #queryVisibleElements(timeMs: number): FrameRenderable[] {\n    const result: FrameRenderable[] = [];\n    const currentTimeMs = timeMs;\n\n    const walk = (element: Element): void => {\n      // For temporal elements (ef-timegroup, ef-video, etc.), use temporal visibility\n      // instead of CSS visibility. CSS display:none may be stale from previous frame.\n      const isTemporal = \"startTimeMs\" in element && \"endTimeMs\" in element;\n      \n      if (isTemporal) {\n        // Temporal element: check time-based visibility\n        // Use exclusive end (< not <=) to avoid overlap at boundaries\n        const startMs = (element as { startTimeMs?: number }).startTimeMs ?? -Infinity;\n        const endMs = (element as { endTimeMs?: number }).endTimeMs ?? Infinity;\n        const isTemporallyVisible = currentTimeMs >= startMs && currentTimeMs < endMs;\n        \n        if (!isTemporallyVisible) {\n          // Skip this element AND its children (children's times are relative to parent)\n          return;\n        }\n        \n        // Element is temporally visible - include if it implements FrameRenderable\n        if (isFrameRenderable(element)) {\n          result.push(element);\n        }\n      } else {\n        // Non-temporal element: use CSS visibility\n        if (element instanceof HTMLElement) {\n          // Fast path: check inline display style\n          if (element.style.display === \"none\") {\n            return;\n          }\n          // Slow path: check computed style\n          const style = getComputedStyle(element);\n          if (style.display === \"none\" || style.visibility === \"hidden\") {\n            return;\n          }\n        }\n\n        // Check if this element implements FrameRenderable\n        if (isFrameRenderable(element)) {\n          result.push(element);\n        }\n      }\n\n      // Walk children - handle both regular children and slotted content\n      const children = this.#getChildrenIncludingSlotted(element);\n      for (const child of children) {\n        walk(child);\n      }\n    };\n\n    walk(this.#rootElement);\n    return result;\n  }\n\n  /**\n   * Gets all child elements including slotted content for shadow DOM elements.\n   * For elements with shadow DOM that contain slots, this returns the assigned\n   * elements (slotted content) instead of just the shadow DOM children.\n   */\n  #getChildrenIncludingSlotted(element: Element): Element[] {\n    // If element has shadowRoot with slots, get assigned elements\n    if (element.shadowRoot) {\n      const slots = element.shadowRoot.querySelectorAll('slot');\n      if (slots.length > 0) {\n        const assignedElements: Element[] = [];\n        for (const slot of slots) {\n          assignedElements.push(...slot.assignedElements());\n        }\n        // Also include shadow DOM children that aren't slots (for mixed content)\n        for (const child of element.shadowRoot.children) {\n          if (child.tagName !== 'SLOT') {\n            assignedElements.push(child);\n          }\n        }\n        return assignedElements;\n      }\n    }\n    \n    // Fallback to regular children\n    return Array.from(element.children);\n  }\n\n  /**\n   * Check if a render is currently in progress.\n   */\n  get isRendering(): boolean {\n    return this.#renderInProgress;\n  }\n}\n\n/**\n * Default frame state for elements that don't need special handling.\n * Use this for simple elements that are always ready.\n */\nexport const DEFAULT_FRAME_STATE: FrameState = {\n  needsPreparation: false,\n  isReady: true,\n  priority: PRIORITY_DEFAULT,\n};\n\n/**\n * Helper to create a FrameRenderable mixin for elements.\n * Provides default implementations that can be overridden.\n */\nexport function createFrameRenderableMixin<T extends { new (...args: any[]): HTMLElement }>(\n  Base: T\n) {\n  return class FrameRenderableMixin extends Base implements FrameRenderable {\n    getFrameState(_timeMs: number): FrameState {\n      return DEFAULT_FRAME_STATE;\n    }\n\n    async prepareFrame(_timeMs: number, _signal: AbortSignal): Promise<void> {\n      // Default: no preparation needed\n    }\n\n    renderFrame(_timeMs: number): void {\n      // Default: no explicit render needed\n    }\n  };\n}\n\n// ============================================================================\n// Shared Frame Task Wrapper\n// ============================================================================\n// Creates a backwards-compatible frameTask object from a FrameRenderable element.\n// This eliminates duplicate boilerplate code across all temporal elements.\n// ============================================================================\n\n/**\n * Interface for the legacy frameTask object.\n * Used for backwards compatibility with code expecting the old Task-like API.\n */\nexport interface FrameTask {\n  /**\n   * Run the frame task (prepare + render).\n   * @returns Promise that resolves when the task completes\n   */\n  run(): Promise<void>;\n\n  /**\n   * Promise that resolves when the current task completes.\n   */\n  taskComplete: Promise<void>;\n}\n\n/**\n * Options for creating a frame task wrapper.\n */\nexport interface FrameTaskWrapperOptions {\n  /**\n   * Function to get the current time in milliseconds.\n   * Default uses element's ownCurrentTimeMs if available, otherwise 0.\n   */\n  getTimeMs?: () => number;\n}\n\n/**\n * Create a backwards-compatible frameTask wrapper for a FrameRenderable element.\n * \n * This factory function creates a frameTask object that:\n * - Manages its own AbortController for cancellation\n * - Calls prepareFrame() then renderFrame() in sequence\n * - Silently ignores AbortErrors (expected during cancellation)\n * - Provides taskComplete promise for awaiting completion\n * \n * @param element - The element implementing FrameRenderable\n * @param options - Optional configuration\n * @returns A frameTask object compatible with legacy code\n * \n * @example\n * ```typescript\n * class MyElement extends LitElement implements FrameRenderable {\n *   frameTask = createFrameTaskWrapper(this, {\n *     getTimeMs: () => this.currentSourceTimeMs,\n *   });\n * \n *   getFrameState(timeMs: number): FrameState { ... }\n *   async prepareFrame(timeMs: number, signal: AbortSignal): Promise<void> { ... }\n *   renderFrame(timeMs: number): void { ... }\n * }\n * ```\n */\nexport function createFrameTaskWrapper(\n  element: FrameRenderable & { ownCurrentTimeMs?: number; desiredSeekTimeMs?: number },\n  options: FrameTaskWrapperOptions = {}\n): FrameTask {\n  let frameTaskPromise: Promise<void> = Promise.resolve();\n\n  const getTimeMs = options.getTimeMs ?? (() => {\n    // Try desiredSeekTimeMs first (video), then ownCurrentTimeMs, then 0\n    if (\"desiredSeekTimeMs\" in element && typeof element.desiredSeekTimeMs === \"number\") {\n      return element.desiredSeekTimeMs;\n    }\n    if (\"ownCurrentTimeMs\" in element && typeof element.ownCurrentTimeMs === \"number\") {\n      return element.ownCurrentTimeMs;\n    }\n    return 0;\n  });\n\n  const taskObj: FrameTask = {\n    run: () => {\n      const abortController = new AbortController();\n      const timeMs = getTimeMs();\n      \n      frameTaskPromise = (async () => {\n        try {\n          await element.prepareFrame(timeMs, abortController.signal);\n          element.renderFrame(timeMs);\n        } catch (error) {\n          // Silently ignore AbortErrors - expected when task is cancelled\n          if (error instanceof DOMException && error.name === \"AbortError\") {\n            return;\n          }\n          throw error;\n        }\n      })();\n      \n      taskObj.taskComplete = frameTaskPromise;\n      return frameTaskPromise;\n    },\n    taskComplete: Promise.resolve(),\n  };\n  return taskObj;\n}\n"],"mappings":"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"}
+{"version":3,"file":"FrameController.js","names":["#rootElement","#abortController","#lastRenderedTimeMs","#renderInProgress","#pendingRenderTime","#queryVisibleElements","#frameCount","#totalQueryMs","#totalPrepareMs","#totalRenderMs","#totalAnimsMs","result: FrameRenderable[]","#getChildrenIncludingSlotted","assignedElements: Element[]"],"sources":["../../src/preview/FrameController.ts"],"sourcesContent":["/**\n * FrameController: Centralized frame rendering control\n *\n * Replaces the distributed Lit Task hierarchy with a single control loop\n * that queries elements and coordinates rendering directly.\n *\n * Benefits over the previous Task-based system:\n * - Single abort controller instead of distributed abort handling\n * - Clear prepare → render phases\n * - All coordination visible in one place\n * - No Lit Task reactivity overhead\n */\n\nimport type { LitElement } from \"lit\";\n\n// ============================================================================\n// Priority Constants\n// ============================================================================\n// Lower numbers render first. Elements with dependencies should have higher\n// priority numbers than their dependencies.\n//\n// Example: Waveform depends on audio analysis data, so it renders after audio.\n// ============================================================================\n\n/**\n * Priority for video elements.\n * Video renders first as other elements may depend on video frames being ready.\n */\nexport const PRIORITY_VIDEO = 1;\n\n/**\n * Priority for captions elements.\n * Captions render after video so they can overlay correctly.\n */\nexport const PRIORITY_CAPTIONS = 2;\n\n/**\n * Priority for audio elements.\n * Audio renders after captions (no visual dependency, but keeps consistent ordering).\n */\nexport const PRIORITY_AUDIO = 3;\n\n/**\n * Priority for waveform elements.\n * Waveform renders after audio because it depends on audio analysis data.\n */\nexport const PRIORITY_WAVEFORM = 4;\n\n/**\n * Priority for image elements.\n * Images render with low priority as they're typically static.\n */\nexport const PRIORITY_IMAGE = 5;\n\n/**\n * Default priority for elements that don't specify one.\n * High number ensures custom elements render after standard elements.\n */\nexport const PRIORITY_DEFAULT = 100;\n\n/**\n * State returned by elements describing their readiness for a given time.\n */\nexport interface FrameState {\n  /**\n   * Whether async preparation is needed before rendering.\n   * Examples: video needs to seek, captions need to load data.\n   */\n  needsPreparation: boolean;\n\n  /**\n   * Whether the element is ready to render synchronously.\n   * True when all async work is complete and renderFrame() can be called.\n   */\n  isReady: boolean;\n\n  /**\n   * Rendering priority hint. Lower numbers render first.\n   * Used to order render calls for elements with dependencies.\n   *\n   * Standard priorities:\n   * - PRIORITY_VIDEO (1): Video elements\n   * - PRIORITY_CAPTIONS (2): Caption overlays\n   * - PRIORITY_AUDIO (3): Audio elements\n   * - PRIORITY_WAVEFORM (4): Audio visualizers (depend on audio)\n   * - PRIORITY_IMAGE (5): Static images\n   * - PRIORITY_DEFAULT (100): Fallback for custom elements\n   */\n  priority: number;\n}\n\n/**\n * Interface that elements implement to participate in centralized frame rendering.\n * Elements keep their rendering logic local but expose a standardized interface.\n */\nexport interface FrameRenderable {\n  /**\n   * Query the element's readiness state for a given time.\n   * Must be synchronous and cheap to call.\n   */\n  getFrameState(timeMs: number): FrameState;\n\n  /**\n   * Async preparation phase. Called when getFrameState().needsPreparation is true.\n   * Performs any async work needed before rendering (seeking, loading, etc.).\n   *\n   * @param timeMs - The time to prepare for\n   * @param signal - Abort signal for cancellation\n   */\n  prepareFrame(timeMs: number, signal: AbortSignal): Promise<void>;\n\n  /**\n   * Synchronous render phase. Called after all preparation is complete.\n   * Performs the actual rendering (paint to canvas, update DOM, etc.).\n   *\n   * @param timeMs - The time to render\n   */\n  renderFrame(timeMs: number): void;\n}\n\n/**\n * Type guard to check if an element implements FrameRenderable.\n */\nexport function isFrameRenderable(\n  element: unknown,\n): element is FrameRenderable {\n  return (\n    typeof element === \"object\" &&\n    element !== null &&\n    \"getFrameState\" in element &&\n    \"prepareFrame\" in element &&\n    \"renderFrame\" in element &&\n    typeof (element as FrameRenderable).getFrameState === \"function\" &&\n    typeof (element as FrameRenderable).prepareFrame === \"function\" &&\n    typeof (element as FrameRenderable).renderFrame === \"function\"\n  );\n}\n\n/**\n * Options for FrameController.renderFrame()\n */\nexport interface RenderFrameOptions {\n  /**\n   * Whether to wait for Lit updateComplete before querying elements.\n   * Default: true\n   */\n  waitForLitUpdate?: boolean;\n\n  /**\n   * Callback to update CSS animations after frame rendering completes.\n   * Called with the root element after all elements have rendered.\n   * This centralizes animation synchronization in one place.\n   */\n  onAnimationsUpdate?: (rootElement: Element) => void;\n}\n\n/**\n * Central controller for frame rendering.\n * Lives at the root timegroup and orchestrates all element rendering.\n */\nexport class FrameController {\n  #rootElement: LitElement & { currentTimeMs: number };\n  #abortController: AbortController | null = null;\n  #renderInProgress = false;\n  #pendingRenderTime: number | null = null;\n  #frameCount = 0;\n  #totalQueryMs = 0;\n  #totalPrepareMs = 0;\n  #totalRenderMs = 0;\n  #totalAnimsMs = 0;\n\n  /**\n   * Last successfully rendered time. Used for deduplication when multiple\n   * callers (e.g., PlaybackController RAF loop and canvas render loop)\n   * both try to render the same frame within one animation frame.\n   */\n  #lastRenderedTimeMs: number = -1;\n\n  constructor(rootElement: LitElement & { currentTimeMs: number }) {\n    this.#rootElement = rootElement;\n  }\n\n  /**\n   * Cancel any in-progress render operation and reset deduplication state.\n   */\n  abort(): void {\n    this.#abortController?.abort();\n    this.#abortController = null;\n    // Reset deduplication state so next render goes through even if same time\n    this.#lastRenderedTimeMs = -1;\n  }\n\n  /**\n   * Render a frame at the specified time.\n   *\n   * This is the main entry point for frame rendering. It:\n   * 1. Cancels any previous in-progress render\n   * 2. Queries all visible FrameRenderable elements\n   * 3. Runs preparation in parallel for elements that need it\n   * 4. Runs render in priority order\n   *\n   * @param timeMs - The time in milliseconds to render\n   * @param options - Optional configuration\n   */\n  async renderFrame(\n    timeMs: number,\n    options: RenderFrameOptions = {},\n  ): Promise<void> {\n    const { waitForLitUpdate = true, onAnimationsUpdate } = options;\n\n    // Deduplicate: skip if we just rendered this exact time.\n    // This prevents double-rendering when multiple RAF loops (e.g., PlaybackController\n    // and canvas render loop) both call renderFrame() for the same frame.\n    if (timeMs === this.#lastRenderedTimeMs) {\n      return;\n    }\n\n    // If a render is in progress, queue this one\n    if (this.#renderInProgress) {\n      this.#pendingRenderTime = timeMs;\n      return;\n    }\n\n    // Cancel any previous render operation\n    this.#abortController?.abort();\n    this.#abortController = new AbortController();\n    const signal = this.#abortController.signal;\n\n    this.#renderInProgress = true;\n\n    try {\n      if (waitForLitUpdate) {\n        await this.#rootElement.updateComplete;\n        signal.throwIfAborted();\n      }\n\n      const tQuery = performance.now();\n      const elements = this.#queryVisibleElements(timeMs);\n      const queryMs = performance.now() - tQuery;\n      signal.throwIfAborted();\n\n      const tPrepare = performance.now();\n      const elementsNeedingPreparation = elements.filter(\n        (el) => el.getFrameState(timeMs).needsPreparation,\n      );\n\n      if (elementsNeedingPreparation.length > 0) {\n        await Promise.all(\n          elementsNeedingPreparation.map((el) =>\n            el.prepareFrame(timeMs, signal),\n          ),\n        );\n        signal.throwIfAborted();\n      }\n      const prepareMs = performance.now() - tPrepare;\n\n      const tRender = performance.now();\n      const sortedElements = [...elements].sort(\n        (a, b) =>\n          a.getFrameState(timeMs).priority - b.getFrameState(timeMs).priority,\n      );\n\n      for (const element of sortedElements) {\n        signal.throwIfAborted();\n        element.renderFrame(timeMs);\n      }\n      const renderMs = performance.now() - tRender;\n\n      const tAnims = performance.now();\n      if (onAnimationsUpdate) {\n        onAnimationsUpdate(this.#rootElement);\n      }\n      const animsMs = performance.now() - tAnims;\n\n      this.#frameCount++;\n      this.#totalQueryMs += queryMs;\n      this.#totalPrepareMs += prepareMs;\n      this.#totalRenderMs += renderMs;\n      this.#totalAnimsMs += animsMs;\n\n      if (this.#frameCount % 60 === 0) {\n        this.#frameCount = 0;\n        this.#totalQueryMs = 0;\n        this.#totalPrepareMs = 0;\n        this.#totalRenderMs = 0;\n        this.#totalAnimsMs = 0;\n      }\n\n      this.#lastRenderedTimeMs = timeMs;\n    } finally {\n      this.#renderInProgress = false;\n\n      // Process any queued render\n      if (this.#pendingRenderTime !== null) {\n        const pendingTime = this.#pendingRenderTime;\n        this.#pendingRenderTime = null;\n        // Don't await - fire and forget to avoid recursive waiting\n        this.renderFrame(pendingTime, options).catch(() => {\n          // Silently ignore errors from queued renders (likely aborted)\n        });\n      }\n    }\n  }\n\n  /**\n   * Query all visible FrameRenderable elements in the tree.\n   * Uses temporal visibility to filter out elements not visible at current time.\n   *\n   * IMPORTANT: For temporal elements, we use temporal visibility (startTimeMs/endTimeMs)\n   * instead of CSS visibility. This is because updateAnimations sets display:none on\n   * elements outside their time range, but that CSS state is from the PREVIOUS frame.\n   * When seeking, we need to evaluate visibility based on the NEW time, not stale CSS.\n   *\n   * @param timeMs - The time to use for visibility checks. This should be the target\n   *                 render time, not read from root element (which may be stale).\n   */\n  #queryVisibleElements(timeMs: number): FrameRenderable[] {\n    const result: FrameRenderable[] = [];\n    const currentTimeMs = timeMs;\n\n    const walk = (element: Element): void => {\n      // For temporal elements (ef-timegroup, ef-video, etc.), use temporal visibility\n      // instead of CSS visibility. CSS display:none may be stale from previous frame.\n      const isTemporal = \"startTimeMs\" in element && \"endTimeMs\" in element;\n\n      if (isTemporal) {\n        // Temporal element: check time-based visibility\n        // Use exclusive end (< not <=) to avoid overlap at boundaries\n        const startMs =\n          (element as { startTimeMs?: number }).startTimeMs ?? -Infinity;\n        const endMs = (element as { endTimeMs?: number }).endTimeMs ?? Infinity;\n        const isTemporallyVisible =\n          currentTimeMs >= startMs && currentTimeMs < endMs;\n\n        if (!isTemporallyVisible) {\n          // Skip this element AND its children (children's times are relative to parent)\n          return;\n        }\n\n        // Element is temporally visible - include if it implements FrameRenderable\n        if (isFrameRenderable(element)) {\n          result.push(element);\n        }\n      } else {\n        // Non-temporal element: only check inline display style (fast path).\n        // Skip getComputedStyle — it forces synchronous style recalc and is\n        // unnecessary because FrameRenderable elements are always temporal.\n        // We only walk non-temporal elements to reach temporal children.\n        if (\n          element instanceof HTMLElement &&\n          element.style.display === \"none\"\n        ) {\n          return;\n        }\n\n        if (isFrameRenderable(element)) {\n          result.push(element);\n        }\n      }\n\n      // Walk children - handle both regular children and slotted content\n      const children = this.#getChildrenIncludingSlotted(element);\n      for (const child of children) {\n        walk(child);\n      }\n    };\n\n    walk(this.#rootElement);\n    return result;\n  }\n\n  /**\n   * Gets all child elements including slotted content for shadow DOM elements.\n   * For elements with shadow DOM that contain slots, this returns the assigned\n   * elements (slotted content) instead of just the shadow DOM children.\n   */\n  #getChildrenIncludingSlotted(element: Element): Iterable<Element> {\n    // If element has shadowRoot with slots, get assigned elements\n    if (element.shadowRoot) {\n      const slots = element.shadowRoot.querySelectorAll(\"slot\");\n      if (slots.length > 0) {\n        const assignedElements: Element[] = [];\n        for (const slot of slots) {\n          assignedElements.push(...slot.assignedElements());\n        }\n        // Also include shadow DOM children that aren't slots (for mixed content)\n        for (const child of element.shadowRoot.children) {\n          if (child.tagName !== \"SLOT\") {\n            assignedElements.push(child);\n          }\n        }\n        return assignedElements;\n      }\n    }\n\n    // Return HTMLCollection directly (iterable, no allocation)\n    return element.children;\n  }\n\n  /**\n   * Check if a render is currently in progress.\n   */\n  get isRendering(): boolean {\n    return this.#renderInProgress;\n  }\n}\n\n/**\n * Default frame state for elements that don't need special handling.\n * Use this for simple elements that are always ready.\n */\nexport const DEFAULT_FRAME_STATE: FrameState = {\n  needsPreparation: false,\n  isReady: true,\n  priority: PRIORITY_DEFAULT,\n};\n\n/**\n * Helper to create a FrameRenderable mixin for elements.\n * Provides default implementations that can be overridden.\n */\nexport function createFrameRenderableMixin<\n  T extends { new (...args: any[]): HTMLElement },\n>(Base: T) {\n  return class FrameRenderableMixin extends Base implements FrameRenderable {\n    getFrameState(_timeMs: number): FrameState {\n      return DEFAULT_FRAME_STATE;\n    }\n\n    async prepareFrame(_timeMs: number, _signal: AbortSignal): Promise<void> {\n      // Default: no preparation needed\n    }\n\n    renderFrame(_timeMs: number): void {\n      // Default: no explicit render needed\n    }\n  };\n}\n"],"mappings":"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"}

package/dist/preview/QualityUpgradeScheduler.d.ts

@@ -0,0 +1,76 @@
+//#region src/preview/QualityUpgradeScheduler.d.ts
+/**
+ * QualityUpgradeScheduler: Centralized deadline-ordered work queue
+ *
+ * Coordinates main-quality segment fetching across multiple video elements.
+ * Generic scheduler that doesn't understand media concepts (segments, renditions, etc.)
+ * - only processes { key, deadlineMs, fetch, owner } tuples.
+ *
+ * Design principles:
+ * - Deadline-based ordering: always process nearest deadline first
+ * - Ground-truth cache validation: check cache before starting any fetch
+ * - In-flight fetches never cancelled: they populate shared cache
+ * - Event-driven: elements submit tasks only on state changes, not every frame
+ */
+interface UpgradeTask {
+  /** Opaque dedup key (e.g. "${owner}:${segmentId}:${renditionId}") */
+  key: string;
+  /** Fetch function that populates the cache */
+  fetch: (signal: AbortSignal) => Promise<void>;
+  /** Timeline time when this segment will be needed */
+  deadlineMs: number;
+  /** Element ID, for bulk operations */
+  owner: string;
+}
+interface UpgradeTaskStatus {
+  key: string;
+  owner: string;
+  deadlineMs: number;
+  status: "queued" | "active" | "completed" | "failed";
+  error?: string;
+}
+interface OwnerProgress {
+  queued: number;
+  active: number;
+  completed: number;
+  failed: number;
+}
+declare class QualityUpgradeScheduler {
+  #private;
+  constructor(options: {
+    requestFrameRender: () => void;
+    maxConcurrent?: number;
+    isCached?: (key: string) => boolean;
+  });
+  /**
+   * Add tasks without affecting existing ones (additive).
+   * Used for lookahead extension during playback.
+   */
+  enqueue(tasks: UpgradeTask[]): void;
+  /**
+   * Replace all queued tasks for an owner.
+   * Used on seeks, trim changes, timeline position changes where old deadlines are stale.
+   * Does NOT cancel in-flight tasks (they populate shared cache).
+   */
+  replaceForOwner(owner: string, tasks: UpgradeTask[]): void;
+  /**
+   * Cancel all tasks for an owner.
+   * Removes queued tasks. Does NOT abort in-flight fetches.
+   */
+  cancelForOwner(owner: string): void;
+  /**
+   * Get snapshot of current queue state for debugging.
+   */
+  getQueueSnapshot(): UpgradeTaskStatus[];
+  /**
+   * Get progress for a specific owner.
+   */
+  getOwnerProgress(owner: string): OwnerProgress;
+  /**
+   * Dispose the scheduler - abort all in-flight work.
+   */
+  dispose(): void;
+}
+//#endregion
+export { QualityUpgradeScheduler };
+//# sourceMappingURL=QualityUpgradeScheduler.d.ts.map

package/dist/preview/QualityUpgradeScheduler.js

@@ -0,0 +1,158 @@
+//#region src/preview/QualityUpgradeScheduler.ts
+var QualityUpgradeScheduler = class {
+	#maxConcurrent;
+	#queue = [];
+	#activeTasks = /* @__PURE__ */ new Map();
+	#completedTasks = /* @__PURE__ */ new Map();
+	#abortController;
+	#requestFrameRender;
+	#isCached;
+	constructor(options) {
+		this.#requestFrameRender = options.requestFrameRender;
+		this.#maxConcurrent = options.maxConcurrent ?? 4;
+		this.#isCached = options.isCached;
+		this.#abortController = new AbortController();
+	}
+	/**
+	* Add tasks without affecting existing ones (additive).
+	* Used for lookahead extension during playback.
+	*/
+	enqueue(tasks) {
+		if (this.#abortController.signal.aborted) return;
+		for (const task of tasks) {
+			if (this.#queue.some((t) => t.key === task.key) || this.#activeTasks.has(task.key) || this.#completedTasks.has(task.key)) continue;
+			this.#queue.push(task);
+		}
+		this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);
+		this.#processQueue();
+	}
+	/**
+	* Replace all queued tasks for an owner.
+	* Used on seeks, trim changes, timeline position changes where old deadlines are stale.
+	* Does NOT cancel in-flight tasks (they populate shared cache).
+	*/
+	replaceForOwner(owner, tasks) {
+		if (this.#abortController.signal.aborted) return;
+		this.#queue = this.#queue.filter((t) => t.owner !== owner);
+		for (const task of tasks) {
+			if (this.#activeTasks.has(task.key) || this.#completedTasks.has(task.key)) continue;
+			this.#queue.push(task);
+		}
+		this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);
+		this.#processQueue();
+	}
+	/**
+	* Cancel all tasks for an owner.
+	* Removes queued tasks. Does NOT abort in-flight fetches.
+	*/
+	cancelForOwner(owner) {
+		this.#queue = this.#queue.filter((t) => t.owner !== owner);
+		for (const [key, task] of this.#completedTasks.entries()) if (task.owner === owner) this.#completedTasks.delete(key);
+	}
+	/**
+	* Process the queue - start tasks up to maxConcurrent limit.
+	*/
+	#processQueue() {
+		if (this.#abortController.signal.aborted) return;
+		while (this.#activeTasks.size < this.#maxConcurrent && this.#queue.length > 0) {
+			const task = this.#queue.shift();
+			if (!task) break;
+			if (this.#isCached?.(task.key)) {
+				this.#completedTasks.set(task.key, {
+					key: task.key,
+					owner: task.owner,
+					status: "completed"
+				});
+				continue;
+			}
+			this.#startTask(task);
+		}
+	}
+	/**
+	* Start a single task.
+	*/
+	#startTask(task) {
+		const promise = task.fetch(this.#abortController.signal).then(() => {
+			this.#activeTasks.delete(task.key);
+			this.#completedTasks.set(task.key, {
+				key: task.key,
+				owner: task.owner,
+				status: "completed"
+			});
+			this.#requestFrameRender();
+			this.#processQueue();
+		}).catch((error) => {
+			this.#activeTasks.delete(task.key);
+			if (!(error instanceof DOMException && error.name === "AbortError")) this.#completedTasks.set(task.key, {
+				key: task.key,
+				owner: task.owner,
+				status: "failed",
+				error: error instanceof Error ? error.message : String(error)
+			});
+			this.#processQueue();
+		});
+		this.#activeTasks.set(task.key, {
+			task,
+			startedAt: performance.now(),
+			promise
+		});
+	}
+	/**
+	* Get snapshot of current queue state for debugging.
+	*/
+	getQueueSnapshot() {
+		const results = [];
+		for (const task of this.#queue) results.push({
+			key: task.key,
+			owner: task.owner,
+			deadlineMs: task.deadlineMs,
+			status: "queued"
+		});
+		for (const [key, activeTask] of this.#activeTasks.entries()) results.push({
+			key,
+			owner: activeTask.task.owner,
+			deadlineMs: activeTask.task.deadlineMs,
+			status: "active"
+		});
+		for (const [key, completed] of this.#completedTasks.entries()) results.push({
+			key,
+			owner: completed.owner,
+			deadlineMs: 0,
+			status: completed.status,
+			error: completed.error
+		});
+		return results;
+	}
+	/**
+	* Get progress for a specific owner.
+	*/
+	getOwnerProgress(owner) {
+		const queued = this.#queue.filter((t) => t.owner === owner).length;
+		let active = 0;
+		for (const activeTask of this.#activeTasks.values()) if (activeTask.task.owner === owner) active++;
+		let completed = 0;
+		let failed = 0;
+		for (const task of this.#completedTasks.values()) if (task.owner === owner) if (task.status === "completed") completed++;
+		else failed++;
+		return {
+			queued,
+			active,
+			completed,
+			failed
+		};
+	}
+	/**
+	* Dispose the scheduler - abort all in-flight work.
+	*/
+	dispose() {
+		for (const activeTask of this.#activeTasks.values()) activeTask.promise.catch(() => {});
+		this.#abortController.abort();
+		this.#queue = [];
+		this.#activeTasks.clear();
+		this.#completedTasks.clear();
+	}
+};
+
+//#endregion
+export { QualityUpgradeScheduler };
+//# sourceMappingURL=QualityUpgradeScheduler.js.map

package/dist/preview/QualityUpgradeScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QualityUpgradeScheduler.js","names":["#requestFrameRender","#maxConcurrent","#isCached","#abortController","#queue","#activeTasks","#completedTasks","#processQueue","#startTask","results: UpgradeTaskStatus[]"],"sources":["../../src/preview/QualityUpgradeScheduler.ts"],"sourcesContent":["/**\n * QualityUpgradeScheduler: Centralized deadline-ordered work queue\n *\n * Coordinates main-quality segment fetching across multiple video elements.\n * Generic scheduler that doesn't understand media concepts (segments, renditions, etc.)\n * - only processes { key, deadlineMs, fetch, owner } tuples.\n *\n * Design principles:\n * - Deadline-based ordering: always process nearest deadline first\n * - Ground-truth cache validation: check cache before starting any fetch\n * - In-flight fetches never cancelled: they populate shared cache\n * - Event-driven: elements submit tasks only on state changes, not every frame\n */\n\nexport interface UpgradeTask {\n  /** Opaque dedup key (e.g. \"${owner}:${segmentId}:${renditionId}\") */\n  key: string;\n  /** Fetch function that populates the cache */\n  fetch: (signal: AbortSignal) => Promise<void>;\n  /** Timeline time when this segment will be needed */\n  deadlineMs: number;\n  /** Element ID, for bulk operations */\n  owner: string;\n}\n\nexport interface UpgradeTaskStatus {\n  key: string;\n  owner: string;\n  deadlineMs: number;\n  status: \"queued\" | \"active\" | \"completed\" | \"failed\";\n  error?: string;\n}\n\nexport interface OwnerProgress {\n  queued: number;\n  active: number;\n  completed: number;\n  failed: number;\n}\n\ninterface ActiveTask {\n  task: UpgradeTask;\n  startedAt: number;\n  promise: Promise<void>;\n}\n\ninterface CompletedTask {\n  key: string;\n  owner: string;\n  status: \"completed\" | \"failed\";\n  error?: string;\n}\n\nexport class QualityUpgradeScheduler {\n  #maxConcurrent: number;\n  #queue: UpgradeTask[] = [];\n  #activeTasks = new Map<string, ActiveTask>();\n  #completedTasks = new Map<string, CompletedTask>();\n  #abortController: AbortController;\n  #requestFrameRender: () => void;\n  #isCached?: (key: string) => boolean;\n\n  constructor(options: {\n    requestFrameRender: () => void;\n    maxConcurrent?: number;\n    isCached?: (key: string) => boolean;\n  }) {\n    this.#requestFrameRender = options.requestFrameRender;\n    this.#maxConcurrent = options.maxConcurrent ?? 4;\n    this.#isCached = options.isCached;\n    this.#abortController = new AbortController();\n  }\n\n  /**\n   * Add tasks without affecting existing ones (additive).\n   * Used for lookahead extension during playback.\n   */\n  enqueue(tasks: UpgradeTask[]): void {\n    if (this.#abortController.signal.aborted) return;\n\n    for (const task of tasks) {\n      // Skip if already queued, active, or completed\n      if (\n        this.#queue.some((t) => t.key === task.key) ||\n        this.#activeTasks.has(task.key) ||\n        this.#completedTasks.has(task.key)\n      ) {\n        continue;\n      }\n\n      this.#queue.push(task);\n    }\n\n    // Sort queue by deadline (ascending)\n    this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);\n\n    // Start processing if we have capacity\n    this.#processQueue();\n  }\n\n  /**\n   * Replace all queued tasks for an owner.\n   * Used on seeks, trim changes, timeline position changes where old deadlines are stale.\n   * Does NOT cancel in-flight tasks (they populate shared cache).\n   */\n  replaceForOwner(owner: string, tasks: UpgradeTask[]): void {\n    if (this.#abortController.signal.aborted) return;\n\n    // Remove queued (not active) tasks for this owner\n    this.#queue = this.#queue.filter((t) => t.owner !== owner);\n\n    // Add new tasks\n    for (const task of tasks) {\n      // Skip if already active or completed\n      if (\n        this.#activeTasks.has(task.key) ||\n        this.#completedTasks.has(task.key)\n      ) {\n        continue;\n      }\n\n      this.#queue.push(task);\n    }\n\n    // Sort queue by deadline (ascending)\n    this.#queue.sort((a, b) => a.deadlineMs - b.deadlineMs);\n\n    // Start processing if we have capacity\n    this.#processQueue();\n  }\n\n  /**\n   * Cancel all tasks for an owner.\n   * Removes queued tasks. Does NOT abort in-flight fetches.\n   */\n  cancelForOwner(owner: string): void {\n    // Remove from queue\n    this.#queue = this.#queue.filter((t) => t.owner !== owner);\n\n    // Remove from completed tracking (allows resubmission)\n    for (const [key, task] of this.#completedTasks.entries()) {\n      if (task.owner === owner) {\n        this.#completedTasks.delete(key);\n      }\n    }\n\n    // Note: we do NOT cancel active tasks - they populate the shared cache\n  }\n\n  /**\n   * Process the queue - start tasks up to maxConcurrent limit.\n   */\n  #processQueue(): void {\n    if (this.#abortController.signal.aborted) return;\n\n    while (\n      this.#activeTasks.size < this.#maxConcurrent &&\n      this.#queue.length > 0\n    ) {\n      const task = this.#queue.shift();\n      if (!task) break;\n\n      // Ground-truth cache check before starting\n      if (this.#isCached?.(task.key)) {\n        // Already cached from another path, mark as completed and continue\n        this.#completedTasks.set(task.key, {\n          key: task.key,\n          owner: task.owner,\n          status: \"completed\",\n        });\n        continue;\n      }\n\n      // Start the task\n      this.#startTask(task);\n    }\n  }\n\n  /**\n   * Start a single task.\n   */\n  #startTask(task: UpgradeTask): void {\n    const promise = task\n      .fetch(this.#abortController.signal)\n      .then(() => {\n        // Success\n        this.#activeTasks.delete(task.key);\n        this.#completedTasks.set(task.key, {\n          key: task.key,\n          owner: task.owner,\n          status: \"completed\",\n        });\n\n        // Trigger re-render so upgraded quality gets displayed\n        this.#requestFrameRender();\n\n        // Start next task if available\n        this.#processQueue();\n      })\n      .catch((error) => {\n        // Failure\n        this.#activeTasks.delete(task.key);\n\n        // Don't track AbortError as failure (intentional cancellation)\n        const isAbortError =\n          error instanceof DOMException && error.name === \"AbortError\";\n\n        if (!isAbortError) {\n          this.#completedTasks.set(task.key, {\n            key: task.key,\n            owner: task.owner,\n            status: \"failed\",\n            error: error instanceof Error ? error.message : String(error),\n          });\n        }\n\n        // Continue processing queue even after failure\n        this.#processQueue();\n      });\n\n    this.#activeTasks.set(task.key, {\n      task,\n      startedAt: performance.now(),\n      promise,\n    });\n  }\n\n  /**\n   * Get snapshot of current queue state for debugging.\n   */\n  getQueueSnapshot(): UpgradeTaskStatus[] {\n    const results: UpgradeTaskStatus[] = [];\n\n    // Queued tasks\n    for (const task of this.#queue) {\n      results.push({\n        key: task.key,\n        owner: task.owner,\n        deadlineMs: task.deadlineMs,\n        status: \"queued\",\n      });\n    }\n\n    // Active tasks\n    for (const [key, activeTask] of this.#activeTasks.entries()) {\n      results.push({\n        key,\n        owner: activeTask.task.owner,\n        deadlineMs: activeTask.task.deadlineMs,\n        status: \"active\",\n      });\n    }\n\n    // Completed tasks\n    for (const [key, completed] of this.#completedTasks.entries()) {\n      results.push({\n        key,\n        owner: completed.owner,\n        deadlineMs: 0, // No longer relevant\n        status: completed.status as \"completed\" | \"failed\",\n        error: completed.error,\n      });\n    }\n\n    return results;\n  }\n\n  /**\n   * Get progress for a specific owner.\n   */\n  getOwnerProgress(owner: string): OwnerProgress {\n    const queued = this.#queue.filter((t) => t.owner === owner).length;\n\n    let active = 0;\n    for (const activeTask of this.#activeTasks.values()) {\n      if (activeTask.task.owner === owner) {\n        active++;\n      }\n    }\n\n    let completed = 0;\n    let failed = 0;\n    for (const task of this.#completedTasks.values()) {\n      if (task.owner === owner) {\n        if (task.status === \"completed\") {\n          completed++;\n        } else {\n          failed++;\n        }\n      }\n    }\n\n    return { queued, active, completed, failed };\n  }\n\n  /**\n   * Dispose the scheduler - abort all in-flight work.\n   */\n  dispose(): void {\n    // Suppress in-flight task rejections before aborting to avoid unhandled\n    // rejection events from the synchronous abort signal firing.\n    for (const activeTask of this.#activeTasks.values()) {\n      activeTask.promise.catch(() => {});\n    }\n    this.#abortController.abort();\n    this.#queue = [];\n    this.#activeTasks.clear();\n    this.#completedTasks.clear();\n  }\n}\n"],"mappings":"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"}

package/dist/preview/RenderContext.d.ts

@@ -1 +1,119 @@
-import "../elements/EFVideo.js";
+import { EFVideo } from "../elements/EFVideo.js";
+
+//#region src/preview/RenderContext.d.ts
+
+/**
+ * Result of capturing a video frame.
+ */
+interface CapturedFrame {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+/**
+ * Options for creating a RenderContext.
+ */
+interface RenderContextOptions {
+  /** Maximum number of canvas dataURLs to cache (default: 50) */
+  maxCanvasCacheSize?: number;
+  /** Maximum number of video frame dataURLs to cache (default: 100) */
+  maxVideoFrameCacheSize?: number;
+}
+/**
+ * RenderContext provides scoped caching for render operations.
+ *
+ * Create at the start of a render, dispose when complete:
+ * ```typescript
+ * const context = new RenderContext();
+ * try {
+ *   // ... render operations
+ * } finally {
+ *   context.dispose();
+ * }
+ * ```
+ */
+declare class RenderContext {
+  #private;
+  constructor(options?: RenderContextOptions);
+  /**
+   * Check if the context has been disposed.
+   */
+  get disposed(): boolean;
+  /**
+   * Get cache metrics for monitoring.
+   */
+  get metrics(): {
+    canvasCacheHits: number;
+    canvasCacheMisses: number;
+    videoFrameCacheHits: number;
+    videoFrameCacheMisses: number;
+  };
+  /**
+   * Get a cached dataURL for a static element.
+   * Returns undefined if not cached or element doesn't support caching.
+   */
+  getCachedCanvasDataUrl(element: Element): string | undefined;
+  /**
+   * Cache a dataURL for a static element.
+   * Does nothing if the element doesn't support caching.
+   */
+  setCachedCanvasDataUrl(element: Element, dataUrl: string): void;
+  /**
+   * Get a cached video frame.
+   * Returns undefined if not cached.
+   */
+  getCachedVideoFrame(videoElement: Element, sourceTimeMs: number): CapturedFrame | undefined;
+  /**
+   * Cache a video frame.
+   */
+  setCachedVideoFrame(videoElement: Element, sourceTimeMs: number, frame: CapturedFrame): void;
+  /**
+   * Convenience method to get or capture a video frame.
+   * Checks cache first, then captures if not cached.
+   *
+   * @param video - The ef-video element
+   * @param sourceTimeMs - Source media timestamp
+   * @param options - Capture options including quality and signal
+   * @returns The captured frame data
+   */
+  getOrCaptureVideoFrame(video: EFVideo, sourceTimeMs: number, options?: {
+    quality?: "auto" | "scrub" | "main";
+    signal?: AbortSignal;
+  }): Promise<CapturedFrame>;
+  /**
+   * Get cached document styles.
+   * Returns undefined if not cached.
+   */
+  getCachedDocumentStyles(): string | undefined;
+  /**
+   * Cache document styles.
+   */
+  setCachedDocumentStyles(styles: string): void;
+  /**
+   * Dispose the context and clear all caches.
+   * Should be called when rendering is complete.
+   */
+  dispose(): void;
+  /**
+   * Symbol.dispose implementation for use with the `using` keyword.
+   *
+   * @example
+   * ```typescript
+   * using context = new RenderContext();
+   * // ... render operations
+   * // context is automatically disposed when scope exits
+   * ```
+   */
+  [Symbol.dispose](): void;
+  /**
+   * Get the current size of the canvas cache.
+   */
+  get canvasCacheSize(): number;
+  /**
+   * Get the current size of the video frame cache.
+   */
+  get videoFrameCacheSize(): number;
+}
+//#endregion
+export { RenderContext };
+//# sourceMappingURL=RenderContext.d.ts.map

package/dist/preview/RenderContext.js

@@ -33,7 +33,7 @@ function getElementUniqueId(element) {
 }
 /**
 * RenderContext provides scoped caching for render operations.
-* 
+*
 * Create at the start of a render, dispose when complete:
 * ```typescript
 * const context = new RenderContext();
@@ -49,6 +49,8 @@ var RenderContext = class {
 	#canvasCache;
 	/** Cache for video frames by source timestamp */
 	#videoFrameCache;
+	/** Cache for document styles (computed once per render session) */
+	#documentStylesCache = null;
 	/** Whether this context has been disposed */
 	#disposed = false;
 	/** Metrics for monitoring cache effectiveness */
@@ -138,7 +140,7 @@ var RenderContext = class {
 	/**
 	* Convenience method to get or capture a video frame.
 	* Checks cache first, then captures if not cached.
-	* 
+	*
 	* @param video - The ef-video element
 	* @param sourceTimeMs - Source media timestamp
 	* @param options - Capture options including quality and signal
@@ -152,6 +154,21 @@ var RenderContext = class {
 		return frame;
 	}
 	/**
+	* Get cached document styles.
+	* Returns undefined if not cached.
+	*/
+	getCachedDocumentStyles() {
+		if (this.#disposed) return void 0;
+		return this.#documentStylesCache ?? void 0;
+	}
+	/**
+	* Cache document styles.
+	*/
+	setCachedDocumentStyles(styles) {
+		if (this.#disposed) return;
+		this.#documentStylesCache = styles;
+	}
+	/**
 	* Dispose the context and clear all caches.
 	* Should be called when rendering is complete.
 	*/
@@ -159,11 +176,12 @@ var RenderContext = class {
 		if (this.#disposed) return;
 		this.#canvasCache.clear();
 		this.#videoFrameCache.clear();
+		this.#documentStylesCache = null;
 		this.#disposed = true;
 	}
 	/**
 	* Symbol.dispose implementation for use with the `using` keyword.
-	* 
+	*
 	* @example
 	* ```typescript
 	* using context = new RenderContext();

package/dist/preview/RenderContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderContext.js","names":["#canvasCache","#videoFrameCache","#disposed","#metrics","#getCanvasCacheKey","#getVideoFrameCacheKey"],"sources":["../../src/preview/RenderContext.ts"],"sourcesContent":["/**\n * RenderContext manages scoped caches for the rendering pipeline.\n * \n * Used during foreignObject serialization to cache:\n * - Video frames by source timestamp (useful for freeze frames, slow-mo)\n * - Static element canvases by element identity + renderVersion\n * \n * The context should be created at the start of a render operation\n * and disposed when the render completes (success or failure).\n */\n\nimport { LRUCache } from \"../utils/LRUCache.js\";\nimport type { EFVideo } from \"../elements/EFVideo.js\";\n\n/**\n * Check if an element has a renderVersion property.\n */\nfunction hasRenderVersion(element: Element): element is Element & { renderVersion: number } {\n  return \"renderVersion\" in element && typeof (element as any).renderVersion === \"number\";\n}\n\n/**\n * Module-level counter for generating unique element IDs.\n * This ensures uniqueness across all RenderContext instances.\n */\nlet nextElementId = 1;\n\n/**\n * WeakMap to store unique IDs for elements.\n * Using WeakMap ensures we don't prevent garbage collection of elements.\n * The ID is stable for the lifetime of the element.\n */\nconst elementUniqueIds = new WeakMap<Element, number>();\n\n/**\n * Get or create a unique ID for an element.\n * This guarantees uniqueness even for elements with the same id attribute\n * or no id attribute at all.\n */\nfunction getElementUniqueId(element: Element): number {\n  let id = elementUniqueIds.get(element);\n  if (id === undefined) {\n    id = nextElementId++;\n    elementUniqueIds.set(element, id);\n  }\n  return id;\n}\n\n/**\n * Result of capturing a video frame.\n */\nexport interface CapturedFrame {\n  dataUrl: string;\n  width: number;\n  height: number;\n}\n\n/**\n * Options for creating a RenderContext.\n */\nexport interface RenderContextOptions {\n  /** Maximum number of canvas dataURLs to cache (default: 50) */\n  maxCanvasCacheSize?: number;\n  /** Maximum number of video frame dataURLs to cache (default: 100) */\n  maxVideoFrameCacheSize?: number;\n}\n\n/**\n * RenderContext provides scoped caching for render operations.\n * \n * Create at the start of a render, dispose when complete:\n * ```typescript\n * const context = new RenderContext();\n * try {\n *   // ... render operations\n * } finally {\n *   context.dispose();\n * }\n * ```\n */\nexport class RenderContext {\n  /** Cache for static element canvases (ef-image, ef-waveform) */\n  #canvasCache: LRUCache<string, string>;\n  \n  /** Cache for video frames by source timestamp */\n  #videoFrameCache: LRUCache<string, CapturedFrame>;\n  \n  /** Whether this context has been disposed */\n  #disposed = false;\n  \n  /** Metrics for monitoring cache effectiveness */\n  #metrics = {\n    canvasCacheHits: 0,\n    canvasCacheMisses: 0,\n    videoFrameCacheHits: 0,\n    videoFrameCacheMisses: 0,\n  };\n\n  constructor(options: RenderContextOptions = {}) {\n    const { maxCanvasCacheSize = 50, maxVideoFrameCacheSize = 100 } = options;\n    this.#canvasCache = new LRUCache(maxCanvasCacheSize);\n    this.#videoFrameCache = new LRUCache(maxVideoFrameCacheSize);\n  }\n\n  /**\n   * Check if the context has been disposed.\n   */\n  get disposed(): boolean {\n    return this.#disposed;\n  }\n\n  /**\n   * Get cache metrics for monitoring.\n   */\n  get metrics() {\n    return { ...this.#metrics };\n  }\n\n  // ============================================================================\n  // Static Element Cache (ef-image, ef-waveform)\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a static element.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple elements have the same id attribute.\n   * Returns null if the element doesn't support caching (no renderVersion).\n   */\n  #getCanvasCacheKey(element: Element): string | null {\n    if (!hasRenderVersion(element)) {\n      return null;\n    }\n    // Use unique element ID + render version for guaranteed uniqueness\n    const uniqueId = getElementUniqueId(element);\n    return `canvas:${uniqueId}:${element.renderVersion}`;\n  }\n\n  /**\n   * Get a cached dataURL for a static element.\n   * Returns undefined if not cached or element doesn't support caching.\n   */\n  getCachedCanvasDataUrl(element: Element): string | undefined {\n    if (this.#disposed) return undefined;\n    \n    const key = this.#getCanvasCacheKey(element);\n    if (!key) return undefined;\n    \n    const cached = this.#canvasCache.get(key);\n    if (cached) {\n      this.#metrics.canvasCacheHits++;\n    } else {\n      this.#metrics.canvasCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a dataURL for a static element.\n   * Does nothing if the element doesn't support caching.\n   */\n  setCachedCanvasDataUrl(element: Element, dataUrl: string): void {\n    if (this.#disposed) return;\n    \n    const key = this.#getCanvasCacheKey(element);\n    if (key) {\n      this.#canvasCache.set(key, dataUrl);\n    }\n  }\n\n  // ============================================================================\n  // Video Frame Cache\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a video frame.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple videos have the same id attribute.\n   */\n  #getVideoFrameCacheKey(videoElement: Element, sourceTimeMs: number): string {\n    const uniqueId = getElementUniqueId(videoElement);\n    // Round to nearest ms to avoid floating point issues\n    const roundedTime = Math.round(sourceTimeMs);\n    return `video:${uniqueId}:${roundedTime}`;\n  }\n\n  /**\n   * Get a cached video frame.\n   * Returns undefined if not cached.\n   */\n  getCachedVideoFrame(videoElement: Element, sourceTimeMs: number): CapturedFrame | undefined {\n    if (this.#disposed) return undefined;\n    \n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    const cached = this.#videoFrameCache.get(key);\n    if (cached) {\n      this.#metrics.videoFrameCacheHits++;\n    } else {\n      this.#metrics.videoFrameCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a video frame.\n   */\n  setCachedVideoFrame(videoElement: Element, sourceTimeMs: number, frame: CapturedFrame): void {\n    if (this.#disposed) return;\n    \n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    this.#videoFrameCache.set(key, frame);\n  }\n\n  /**\n   * Convenience method to get or capture a video frame.\n   * Checks cache first, then captures if not cached.\n   * \n   * @param video - The ef-video element\n   * @param sourceTimeMs - Source media timestamp\n   * @param options - Capture options including quality and signal\n   * @returns The captured frame data\n   */\n  async getOrCaptureVideoFrame(\n    video: EFVideo,\n    sourceTimeMs: number,\n    options: {\n      quality?: \"auto\" | \"scrub\" | \"main\";\n      signal?: AbortSignal;\n    } = {}\n  ): Promise<CapturedFrame> {\n    // Check cache first\n    const cached = this.getCachedVideoFrame(video, sourceTimeMs);\n    if (cached) {\n      return cached;\n    }\n\n    // Capture frame using direct API\n    const frame = await video.captureFrameAtSourceTime(sourceTimeMs, options);\n    \n    // Cache for future use\n    this.setCachedVideoFrame(video, sourceTimeMs, frame);\n    \n    return frame;\n  }\n\n  // ============================================================================\n  // Cleanup\n  // ============================================================================\n\n  /**\n   * Dispose the context and clear all caches.\n   * Should be called when rendering is complete.\n   */\n  dispose(): void {\n    if (this.#disposed) return;\n    \n    this.#canvasCache.clear();\n    this.#videoFrameCache.clear();\n    this.#disposed = true;\n  }\n\n  /**\n   * Symbol.dispose implementation for use with the `using` keyword.\n   * \n   * @example\n   * ```typescript\n   * using context = new RenderContext();\n   * // ... render operations\n   * // context is automatically disposed when scope exits\n   * ```\n   */\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n\n  /**\n   * Get the current size of the canvas cache.\n   */\n  get canvasCacheSize(): number {\n    return this.#canvasCache.size;\n  }\n\n  /**\n   * Get the current size of the video frame cache.\n   */\n  get videoFrameCacheSize(): number {\n    return this.#videoFrameCache.size;\n  }\n}\n"],"mappings":";;;;;;AAiBA,SAAS,iBAAiB,SAAkE;AAC1F,QAAO,mBAAmB,WAAW,OAAQ,QAAgB,kBAAkB;;;;;;AAOjF,IAAI,gBAAgB;;;;;;AAOpB,MAAM,mCAAmB,IAAI,SAA0B;;;;;;AAOvD,SAAS,mBAAmB,SAA0B;CACpD,IAAI,KAAK,iBAAiB,IAAI,QAAQ;AACtC,KAAI,OAAO,QAAW;AACpB,OAAK;AACL,mBAAiB,IAAI,SAAS,GAAG;;AAEnC,QAAO;;;;;;;;;;;;;;;AAmCT,IAAa,gBAAb,MAA2B;;CAEzB;;CAGA;;CAGA,YAAY;;CAGZ,WAAW;EACT,iBAAiB;EACjB,mBAAmB;EACnB,qBAAqB;EACrB,uBAAuB;EACxB;CAED,YAAY,UAAgC,EAAE,EAAE;EAC9C,MAAM,EAAE,qBAAqB,IAAI,yBAAyB,QAAQ;AAClE,QAAKA,cAAe,IAAI,SAAS,mBAAmB;AACpD,QAAKC,kBAAmB,IAAI,SAAS,uBAAuB;;;;;CAM9D,IAAI,WAAoB;AACtB,SAAO,MAAKC;;;;;CAMd,IAAI,UAAU;AACZ,SAAO,EAAE,GAAG,MAAKC,SAAU;;;;;;;;CAa7B,mBAAmB,SAAiC;AAClD,MAAI,CAAC,iBAAiB,QAAQ,CAC5B,QAAO;AAIT,SAAO,UADU,mBAAmB,QAAQ,CAClB,GAAG,QAAQ;;;;;;CAOvC,uBAAuB,SAAsC;AAC3D,MAAI,MAAKD,SAAW,QAAO;EAE3B,MAAM,MAAM,MAAKE,kBAAmB,QAAQ;AAC5C,MAAI,CAAC,IAAK,QAAO;EAEjB,MAAM,SAAS,MAAKJ,YAAa,IAAI,IAAI;AACzC,MAAI,OACF,OAAKG,QAAS;MAEd,OAAKA,QAAS;AAEhB,SAAO;;;;;;CAOT,uBAAuB,SAAkB,SAAuB;AAC9D,MAAI,MAAKD,SAAW;EAEpB,MAAM,MAAM,MAAKE,kBAAmB,QAAQ;AAC5C,MAAI,IACF,OAAKJ,YAAa,IAAI,KAAK,QAAQ;;;;;;;CAavC,uBAAuB,cAAuB,cAA8B;AAI1E,SAAO,SAHU,mBAAmB,aAAa,CAGxB,GADL,KAAK,MAAM,aAAa;;;;;;CAQ9C,oBAAoB,cAAuB,cAAiD;AAC1F,MAAI,MAAKE,SAAW,QAAO;EAE3B,MAAM,MAAM,MAAKG,sBAAuB,cAAc,aAAa;EACnE,MAAM,SAAS,MAAKJ,gBAAiB,IAAI,IAAI;AAC7C,MAAI,OACF,OAAKE,QAAS;MAEd,OAAKA,QAAS;AAEhB,SAAO;;;;;CAMT,oBAAoB,cAAuB,cAAsB,OAA4B;AAC3F,MAAI,MAAKD,SAAW;EAEpB,MAAM,MAAM,MAAKG,sBAAuB,cAAc,aAAa;AACnE,QAAKJ,gBAAiB,IAAI,KAAK,MAAM;;;;;;;;;;;CAYvC,MAAM,uBACJ,OACA,cACA,UAGI,EAAE,EACkB;EAExB,MAAM,SAAS,KAAK,oBAAoB,OAAO,aAAa;AAC5D,MAAI,OACF,QAAO;EAIT,MAAM,QAAQ,MAAM,MAAM,yBAAyB,cAAc,QAAQ;AAGzE,OAAK,oBAAoB,OAAO,cAAc,MAAM;AAEpD,SAAO;;;;;;CAWT,UAAgB;AACd,MAAI,MAAKC,SAAW;AAEpB,QAAKF,YAAa,OAAO;AACzB,QAAKC,gBAAiB,OAAO;AAC7B,QAAKC,WAAY;;;;;;;;;;;;CAanB,CAAC,OAAO,WAAiB;AACvB,OAAK,SAAS;;;;;CAMhB,IAAI,kBAA0B;AAC5B,SAAO,MAAKF,YAAa;;;;;CAM3B,IAAI,sBAA8B;AAChC,SAAO,MAAKC,gBAAiB"}
+{"version":3,"file":"RenderContext.js","names":["#canvasCache","#videoFrameCache","#disposed","#metrics","#getCanvasCacheKey","#getVideoFrameCacheKey","#documentStylesCache"],"sources":["../../src/preview/RenderContext.ts"],"sourcesContent":["/**\n * RenderContext manages scoped caches for the rendering pipeline.\n *\n * Used during foreignObject serialization to cache:\n * - Video frames by source timestamp (useful for freeze frames, slow-mo)\n * - Static element canvases by element identity + renderVersion\n *\n * The context should be created at the start of a render operation\n * and disposed when the render completes (success or failure).\n */\n\nimport { LRUCache } from \"../utils/LRUCache.js\";\nimport type { EFVideo } from \"../elements/EFVideo.js\";\n\n/**\n * Check if an element has a renderVersion property.\n */\nfunction hasRenderVersion(\n  element: Element,\n): element is Element & { renderVersion: number } {\n  return (\n    \"renderVersion\" in element &&\n    typeof (element as any).renderVersion === \"number\"\n  );\n}\n\n/**\n * Module-level counter for generating unique element IDs.\n * This ensures uniqueness across all RenderContext instances.\n */\nlet nextElementId = 1;\n\n/**\n * WeakMap to store unique IDs for elements.\n * Using WeakMap ensures we don't prevent garbage collection of elements.\n * The ID is stable for the lifetime of the element.\n */\nconst elementUniqueIds = new WeakMap<Element, number>();\n\n/**\n * Get or create a unique ID for an element.\n * This guarantees uniqueness even for elements with the same id attribute\n * or no id attribute at all.\n */\nfunction getElementUniqueId(element: Element): number {\n  let id = elementUniqueIds.get(element);\n  if (id === undefined) {\n    id = nextElementId++;\n    elementUniqueIds.set(element, id);\n  }\n  return id;\n}\n\n/**\n * Result of capturing a video frame.\n */\nexport interface CapturedFrame {\n  dataUrl: string;\n  width: number;\n  height: number;\n}\n\n/**\n * Options for creating a RenderContext.\n */\nexport interface RenderContextOptions {\n  /** Maximum number of canvas dataURLs to cache (default: 50) */\n  maxCanvasCacheSize?: number;\n  /** Maximum number of video frame dataURLs to cache (default: 100) */\n  maxVideoFrameCacheSize?: number;\n}\n\n/**\n * RenderContext provides scoped caching for render operations.\n *\n * Create at the start of a render, dispose when complete:\n * ```typescript\n * const context = new RenderContext();\n * try {\n *   // ... render operations\n * } finally {\n *   context.dispose();\n * }\n * ```\n */\nexport class RenderContext {\n  /** Cache for static element canvases (ef-image, ef-waveform) */\n  #canvasCache: LRUCache<string, string>;\n\n  /** Cache for video frames by source timestamp */\n  #videoFrameCache: LRUCache<string, CapturedFrame>;\n\n  /** Cache for document styles (computed once per render session) */\n  #documentStylesCache: string | null = null;\n\n  /** Whether this context has been disposed */\n  #disposed = false;\n\n  /** Metrics for monitoring cache effectiveness */\n  #metrics = {\n    canvasCacheHits: 0,\n    canvasCacheMisses: 0,\n    videoFrameCacheHits: 0,\n    videoFrameCacheMisses: 0,\n  };\n\n  constructor(options: RenderContextOptions = {}) {\n    const { maxCanvasCacheSize = 50, maxVideoFrameCacheSize = 100 } = options;\n    this.#canvasCache = new LRUCache(maxCanvasCacheSize);\n    this.#videoFrameCache = new LRUCache(maxVideoFrameCacheSize);\n  }\n\n  /**\n   * Check if the context has been disposed.\n   */\n  get disposed(): boolean {\n    return this.#disposed;\n  }\n\n  /**\n   * Get cache metrics for monitoring.\n   */\n  get metrics() {\n    return { ...this.#metrics };\n  }\n\n  // ============================================================================\n  // Static Element Cache (ef-image, ef-waveform)\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a static element.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple elements have the same id attribute.\n   * Returns null if the element doesn't support caching (no renderVersion).\n   */\n  #getCanvasCacheKey(element: Element): string | null {\n    if (!hasRenderVersion(element)) {\n      return null;\n    }\n    // Use unique element ID + render version for guaranteed uniqueness\n    const uniqueId = getElementUniqueId(element);\n    return `canvas:${uniqueId}:${element.renderVersion}`;\n  }\n\n  /**\n   * Get a cached dataURL for a static element.\n   * Returns undefined if not cached or element doesn't support caching.\n   */\n  getCachedCanvasDataUrl(element: Element): string | undefined {\n    if (this.#disposed) return undefined;\n\n    const key = this.#getCanvasCacheKey(element);\n    if (!key) return undefined;\n\n    const cached = this.#canvasCache.get(key);\n    if (cached) {\n      this.#metrics.canvasCacheHits++;\n    } else {\n      this.#metrics.canvasCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a dataURL for a static element.\n   * Does nothing if the element doesn't support caching.\n   */\n  setCachedCanvasDataUrl(element: Element, dataUrl: string): void {\n    if (this.#disposed) return;\n\n    const key = this.#getCanvasCacheKey(element);\n    if (key) {\n      this.#canvasCache.set(key, dataUrl);\n    }\n  }\n\n  // ============================================================================\n  // Video Frame Cache\n  // ============================================================================\n\n  /**\n   * Generate a cache key for a video frame.\n   * Uses a unique element ID (via WeakMap) to ensure uniqueness even if\n   * multiple videos have the same id attribute.\n   */\n  #getVideoFrameCacheKey(videoElement: Element, sourceTimeMs: number): string {\n    const uniqueId = getElementUniqueId(videoElement);\n    // Round to nearest ms to avoid floating point issues\n    const roundedTime = Math.round(sourceTimeMs);\n    return `video:${uniqueId}:${roundedTime}`;\n  }\n\n  /**\n   * Get a cached video frame.\n   * Returns undefined if not cached.\n   */\n  getCachedVideoFrame(\n    videoElement: Element,\n    sourceTimeMs: number,\n  ): CapturedFrame | undefined {\n    if (this.#disposed) return undefined;\n\n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    const cached = this.#videoFrameCache.get(key);\n    if (cached) {\n      this.#metrics.videoFrameCacheHits++;\n    } else {\n      this.#metrics.videoFrameCacheMisses++;\n    }\n    return cached;\n  }\n\n  /**\n   * Cache a video frame.\n   */\n  setCachedVideoFrame(\n    videoElement: Element,\n    sourceTimeMs: number,\n    frame: CapturedFrame,\n  ): void {\n    if (this.#disposed) return;\n\n    const key = this.#getVideoFrameCacheKey(videoElement, sourceTimeMs);\n    this.#videoFrameCache.set(key, frame);\n  }\n\n  /**\n   * Convenience method to get or capture a video frame.\n   * Checks cache first, then captures if not cached.\n   *\n   * @param video - The ef-video element\n   * @param sourceTimeMs - Source media timestamp\n   * @param options - Capture options including quality and signal\n   * @returns The captured frame data\n   */\n  async getOrCaptureVideoFrame(\n    video: EFVideo,\n    sourceTimeMs: number,\n    options: {\n      quality?: \"auto\" | \"scrub\" | \"main\";\n      signal?: AbortSignal;\n    } = {},\n  ): Promise<CapturedFrame> {\n    // Check cache first\n    const cached = this.getCachedVideoFrame(video, sourceTimeMs);\n    if (cached) {\n      return cached;\n    }\n\n    // Capture frame using direct API\n    const frame = await video.captureFrameAtSourceTime(sourceTimeMs, options);\n\n    // Cache for future use\n    this.setCachedVideoFrame(video, sourceTimeMs, frame);\n\n    return frame;\n  }\n\n  // ============================================================================\n  // Document Styles Cache\n  // ============================================================================\n\n  /**\n   * Get cached document styles.\n   * Returns undefined if not cached.\n   */\n  getCachedDocumentStyles(): string | undefined {\n    if (this.#disposed) return undefined;\n    return this.#documentStylesCache ?? undefined;\n  }\n\n  /**\n   * Cache document styles.\n   */\n  setCachedDocumentStyles(styles: string): void {\n    if (this.#disposed) return;\n    this.#documentStylesCache = styles;\n  }\n\n  // ============================================================================\n  // Cleanup\n  // ============================================================================\n\n  /**\n   * Dispose the context and clear all caches.\n   * Should be called when rendering is complete.\n   */\n  dispose(): void {\n    if (this.#disposed) return;\n\n    this.#canvasCache.clear();\n    this.#videoFrameCache.clear();\n    this.#documentStylesCache = null;\n    this.#disposed = true;\n  }\n\n  /**\n   * Symbol.dispose implementation for use with the `using` keyword.\n   *\n   * @example\n   * ```typescript\n   * using context = new RenderContext();\n   * // ... render operations\n   * // context is automatically disposed when scope exits\n   * ```\n   */\n  [Symbol.dispose](): void {\n    this.dispose();\n  }\n\n  /**\n   * Get the current size of the canvas cache.\n   */\n  get canvasCacheSize(): number {\n    return this.#canvasCache.size;\n  }\n\n  /**\n   * Get the current size of the video frame cache.\n   */\n  get videoFrameCacheSize(): number {\n    return this.#videoFrameCache.size;\n  }\n}\n"],"mappings":"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"}

package/dist/preview/RenderProfiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"RenderProfiler.js","names":["parts: string[]"],"sources":["../../src/preview/RenderProfiler.ts"],"sourcesContent":["/**\n * Profiling utility for render operations.\n * Centralizes timing accumulation and logging to keep business logic clean.\n */\n\n/** Interval between profiling log outputs (ms) */\nconst DEFAULT_LOG_INTERVAL_MS = 2000;\n\n/** Interval for periodic frame logging (every N frames) */\nconst DEFAULT_FRAME_LOG_INTERVAL = 60;\n\n/**\n * Phases tracked during rendering.\n */\nexport interface RenderTimings {\n  setup: number;\n  draw: number;\n  downsample: number;\n  canvasEncode: number;\n  inline: number;\n  serialize: number;\n  base64: number;\n  imageLoad: number;\n  restore: number;\n}\n\n/**\n * Profiler for render operations.\n * Accumulates timing data and provides structured logging.\n */\nexport class RenderProfiler {\n  private _renderCount = 0;\n  private _lastLogTime = 0;\n  private _timingLoggedAt = 0;\n  \n  private _timings: RenderTimings = {\n    setup: 0,\n    draw: 0,\n    downsample: 0,\n    canvasEncode: 0,\n    inline: 0,\n    serialize: 0,\n    base64: 0,\n    imageLoad: 0,\n    restore: 0,\n  };\n\n  /**\n   * Reset all timing data.\n   */\n  reset(): void {\n    this._renderCount = 0;\n    this._lastLogTime = 0;\n    this._timingLoggedAt = 0;\n    \n    for (const key of Object.keys(this._timings) as (keyof RenderTimings)[]) {\n      this._timings[key] = 0;\n    }\n  }\n\n  /**\n   * Get current render count.\n   */\n  get renderCount(): number {\n    return this._renderCount;\n  }\n\n  /**\n   * Increment render count.\n   */\n  incrementRenderCount(): void {\n    this._renderCount++;\n  }\n\n  /**\n   * Add time to a specific phase.\n   */\n  addTime(phase: keyof RenderTimings, ms: number): void {\n    this._timings[phase] += ms;\n  }\n\n  /**\n   * Time a synchronous operation and add to the specified phase.\n   */\n  time<T>(phase: keyof RenderTimings, fn: () => T): T {\n    const start = performance.now();\n    const result = fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Time an async operation and add to the specified phase.\n   */\n  async timeAsync<T>(phase: keyof RenderTimings, fn: () => Promise<T>): Promise<T> {\n    const start = performance.now();\n    const result = await fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Check if enough time has passed since last log (for time-based logging).\n   */\n  shouldLogByTime(intervalMs: number = DEFAULT_LOG_INTERVAL_MS): boolean {\n    const now = performance.now();\n    if (now - this._lastLogTime > intervalMs) {\n      this._lastLogTime = now;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if enough frames have passed since last log (for frame-based logging).\n   */\n  shouldLogByFrameCount(interval: number = DEFAULT_FRAME_LOG_INTERVAL): boolean {\n    if (this._renderCount - this._timingLoggedAt >= interval) {\n      this._timingLoggedAt = this._renderCount;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if this is an early render (for initial debug logging).\n   */\n  isEarlyRender(threshold: number = 2): boolean {\n    return this._renderCount < threshold;\n  }\n\n  /**\n   * Get timing summary string.\n   */\n  summary(): string {\n    const t = this._timings;\n    const parts: string[] = [];\n    \n    if (t.setup > 0) parts.push(`setup=${t.setup.toFixed(0)}ms`);\n    if (t.draw > 0) parts.push(`draw=${t.draw.toFixed(0)}ms`);\n    if (t.downsample > 0) parts.push(`downsample=${t.downsample.toFixed(0)}ms`);\n    if (t.canvasEncode > 0) parts.push(`canvasEncode=${t.canvasEncode.toFixed(0)}ms`);\n    if (t.inline > 0) parts.push(`inline=${t.inline.toFixed(0)}ms`);\n    if (t.serialize > 0) parts.push(`serialize=${t.serialize.toFixed(0)}ms`);\n    if (t.base64 > 0) parts.push(`base64=${t.base64.toFixed(0)}ms`);\n    if (t.imageLoad > 0) parts.push(`imageLoad=${t.imageLoad.toFixed(0)}ms`);\n    if (t.restore > 0) parts.push(`restore=${t.restore.toFixed(0)}ms`);\n    \n    return parts.join(', ');\n  }\n\n  /**\n   * Get raw timings object.\n   */\n  getTimings(): Readonly<RenderTimings> {\n    return { ...this._timings };\n  }\n}\n\n/**\n * Default shared profiler instance.\n * Can be replaced with a custom instance for testing.\n */\nexport const defaultProfiler = new RenderProfiler();\n"],"mappings":";;;;;;AAMA,MAAM,0BAA0B;;AAGhC,MAAM,6BAA6B;;;;;AAqBnC,IAAa,iBAAb,MAA4B;;sBACH;sBACA;yBACG;kBAEQ;GAChC,OAAO;GACP,MAAM;GACN,YAAY;GACZ,cAAc;GACd,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,SAAS;GACV;;;;;CAKD,QAAc;AACZ,OAAK,eAAe;AACpB,OAAK,eAAe;AACpB,OAAK,kBAAkB;AAEvB,OAAK,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS,CAC1C,MAAK,SAAS,OAAO;;;;;CAOzB,IAAI,cAAsB;AACxB,SAAO,KAAK;;;;;CAMd,uBAA6B;AAC3B,OAAK;;;;;CAMP,QAAQ,OAA4B,IAAkB;AACpD,OAAK,SAAS,UAAU;;;;;CAM1B,KAAQ,OAA4B,IAAgB;EAClD,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,IAAI;AACnB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,MAAM,UAAa,OAA4B,IAAkC;EAC/E,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,MAAM,IAAI;AACzB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,gBAAgB,aAAqB,yBAAkC;EACrE,MAAM,MAAM,YAAY,KAAK;AAC7B,MAAI,MAAM,KAAK,eAAe,YAAY;AACxC,QAAK,eAAe;AACpB,UAAO;;AAET,SAAO;;;;;CAMT,sBAAsB,WAAmB,4BAAqC;AAC5E,MAAI,KAAK,eAAe,KAAK,mBAAmB,UAAU;AACxD,QAAK,kBAAkB,KAAK;AAC5B,UAAO;;AAET,SAAO;;;;;CAMT,cAAc,YAAoB,GAAY;AAC5C,SAAO,KAAK,eAAe;;;;;CAM7B,UAAkB;EAChB,MAAM,IAAI,KAAK;EACf,MAAMA,QAAkB,EAAE;AAE1B,MAAI,EAAE,QAAQ,EAAG,OAAM,KAAK,SAAS,EAAE,MAAM,QAAQ,EAAE,CAAC,IAAI;AAC5D,MAAI,EAAE,OAAO,EAAG,OAAM,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAAC,IAAI;AACzD,MAAI,EAAE,aAAa,EAAG,OAAM,KAAK,cAAc,EAAE,WAAW,QAAQ,EAAE,CAAC,IAAI;AAC3E,MAAI,EAAE,eAAe,EAAG,OAAM,KAAK,gBAAgB,EAAE,aAAa,QAAQ,EAAE,CAAC,IAAI;AACjF,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,UAAU,EAAG,OAAM,KAAK,WAAW,EAAE,QAAQ,QAAQ,EAAE,CAAC,IAAI;AAElE,SAAO,MAAM,KAAK,KAAK;;;;;CAMzB,aAAsC;AACpC,SAAO,EAAE,GAAG,KAAK,UAAU;;;;;;;AAQ/B,MAAa,kBAAkB,IAAI,gBAAgB"}
+{"version":3,"file":"RenderProfiler.js","names":["parts: string[]"],"sources":["../../src/preview/RenderProfiler.ts"],"sourcesContent":["/**\n * Profiling utility for render operations.\n * Centralizes timing accumulation and logging to keep business logic clean.\n */\n\n/** Interval between profiling log outputs (ms) */\nconst DEFAULT_LOG_INTERVAL_MS = 2000;\n\n/** Interval for periodic frame logging (every N frames) */\nconst DEFAULT_FRAME_LOG_INTERVAL = 60;\n\n/**\n * Phases tracked during rendering.\n */\nexport interface RenderTimings {\n  setup: number;\n  draw: number;\n  downsample: number;\n  canvasEncode: number;\n  inline: number;\n  serialize: number;\n  base64: number;\n  imageLoad: number;\n  restore: number;\n}\n\n/**\n * Profiler for render operations.\n * Accumulates timing data and provides structured logging.\n */\nexport class RenderProfiler {\n  private _renderCount = 0;\n  private _lastLogTime = 0;\n  private _timingLoggedAt = 0;\n\n  private _timings: RenderTimings = {\n    setup: 0,\n    draw: 0,\n    downsample: 0,\n    canvasEncode: 0,\n    inline: 0,\n    serialize: 0,\n    base64: 0,\n    imageLoad: 0,\n    restore: 0,\n  };\n\n  /**\n   * Reset all timing data.\n   */\n  reset(): void {\n    this._renderCount = 0;\n    this._lastLogTime = 0;\n    this._timingLoggedAt = 0;\n\n    for (const key of Object.keys(this._timings) as (keyof RenderTimings)[]) {\n      this._timings[key] = 0;\n    }\n  }\n\n  /**\n   * Get current render count.\n   */\n  get renderCount(): number {\n    return this._renderCount;\n  }\n\n  /**\n   * Increment render count.\n   */\n  incrementRenderCount(): void {\n    this._renderCount++;\n  }\n\n  /**\n   * Add time to a specific phase.\n   */\n  addTime(phase: keyof RenderTimings, ms: number): void {\n    this._timings[phase] += ms;\n  }\n\n  /**\n   * Time a synchronous operation and add to the specified phase.\n   */\n  time<T>(phase: keyof RenderTimings, fn: () => T): T {\n    const start = performance.now();\n    const result = fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Time an async operation and add to the specified phase.\n   */\n  async timeAsync<T>(\n    phase: keyof RenderTimings,\n    fn: () => Promise<T>,\n  ): Promise<T> {\n    const start = performance.now();\n    const result = await fn();\n    this._timings[phase] += performance.now() - start;\n    return result;\n  }\n\n  /**\n   * Check if enough time has passed since last log (for time-based logging).\n   */\n  shouldLogByTime(intervalMs: number = DEFAULT_LOG_INTERVAL_MS): boolean {\n    const now = performance.now();\n    if (now - this._lastLogTime > intervalMs) {\n      this._lastLogTime = now;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if enough frames have passed since last log (for frame-based logging).\n   */\n  shouldLogByFrameCount(\n    interval: number = DEFAULT_FRAME_LOG_INTERVAL,\n  ): boolean {\n    if (this._renderCount - this._timingLoggedAt >= interval) {\n      this._timingLoggedAt = this._renderCount;\n      return true;\n    }\n    return false;\n  }\n\n  /**\n   * Check if this is an early render (for initial debug logging).\n   */\n  isEarlyRender(threshold: number = 2): boolean {\n    return this._renderCount < threshold;\n  }\n\n  /**\n   * Get timing summary string.\n   */\n  summary(): string {\n    const t = this._timings;\n    const parts: string[] = [];\n\n    if (t.setup > 0) parts.push(`setup=${t.setup.toFixed(0)}ms`);\n    if (t.draw > 0) parts.push(`draw=${t.draw.toFixed(0)}ms`);\n    if (t.downsample > 0) parts.push(`downsample=${t.downsample.toFixed(0)}ms`);\n    if (t.canvasEncode > 0)\n      parts.push(`canvasEncode=${t.canvasEncode.toFixed(0)}ms`);\n    if (t.inline > 0) parts.push(`inline=${t.inline.toFixed(0)}ms`);\n    if (t.serialize > 0) parts.push(`serialize=${t.serialize.toFixed(0)}ms`);\n    if (t.base64 > 0) parts.push(`base64=${t.base64.toFixed(0)}ms`);\n    if (t.imageLoad > 0) parts.push(`imageLoad=${t.imageLoad.toFixed(0)}ms`);\n    if (t.restore > 0) parts.push(`restore=${t.restore.toFixed(0)}ms`);\n\n    return parts.join(\", \");\n  }\n\n  /**\n   * Get raw timings object.\n   */\n  getTimings(): Readonly<RenderTimings> {\n    return { ...this._timings };\n  }\n}\n\n/**\n * Default shared profiler instance.\n * Can be replaced with a custom instance for testing.\n */\nexport const defaultProfiler = new RenderProfiler();\n"],"mappings":";;;;;;AAMA,MAAM,0BAA0B;;AAGhC,MAAM,6BAA6B;;;;;AAqBnC,IAAa,iBAAb,MAA4B;;sBACH;sBACA;yBACG;kBAEQ;GAChC,OAAO;GACP,MAAM;GACN,YAAY;GACZ,cAAc;GACd,QAAQ;GACR,WAAW;GACX,QAAQ;GACR,WAAW;GACX,SAAS;GACV;;;;;CAKD,QAAc;AACZ,OAAK,eAAe;AACpB,OAAK,eAAe;AACpB,OAAK,kBAAkB;AAEvB,OAAK,MAAM,OAAO,OAAO,KAAK,KAAK,SAAS,CAC1C,MAAK,SAAS,OAAO;;;;;CAOzB,IAAI,cAAsB;AACxB,SAAO,KAAK;;;;;CAMd,uBAA6B;AAC3B,OAAK;;;;;CAMP,QAAQ,OAA4B,IAAkB;AACpD,OAAK,SAAS,UAAU;;;;;CAM1B,KAAQ,OAA4B,IAAgB;EAClD,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,IAAI;AACnB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,MAAM,UACJ,OACA,IACY;EACZ,MAAM,QAAQ,YAAY,KAAK;EAC/B,MAAM,SAAS,MAAM,IAAI;AACzB,OAAK,SAAS,UAAU,YAAY,KAAK,GAAG;AAC5C,SAAO;;;;;CAMT,gBAAgB,aAAqB,yBAAkC;EACrE,MAAM,MAAM,YAAY,KAAK;AAC7B,MAAI,MAAM,KAAK,eAAe,YAAY;AACxC,QAAK,eAAe;AACpB,UAAO;;AAET,SAAO;;;;;CAMT,sBACE,WAAmB,4BACV;AACT,MAAI,KAAK,eAAe,KAAK,mBAAmB,UAAU;AACxD,QAAK,kBAAkB,KAAK;AAC5B,UAAO;;AAET,SAAO;;;;;CAMT,cAAc,YAAoB,GAAY;AAC5C,SAAO,KAAK,eAAe;;;;;CAM7B,UAAkB;EAChB,MAAM,IAAI,KAAK;EACf,MAAMA,QAAkB,EAAE;AAE1B,MAAI,EAAE,QAAQ,EAAG,OAAM,KAAK,SAAS,EAAE,MAAM,QAAQ,EAAE,CAAC,IAAI;AAC5D,MAAI,EAAE,OAAO,EAAG,OAAM,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,CAAC,IAAI;AACzD,MAAI,EAAE,aAAa,EAAG,OAAM,KAAK,cAAc,EAAE,WAAW,QAAQ,EAAE,CAAC,IAAI;AAC3E,MAAI,EAAE,eAAe,EACnB,OAAM,KAAK,gBAAgB,EAAE,aAAa,QAAQ,EAAE,CAAC,IAAI;AAC3D,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,SAAS,EAAG,OAAM,KAAK,UAAU,EAAE,OAAO,QAAQ,EAAE,CAAC,IAAI;AAC/D,MAAI,EAAE,YAAY,EAAG,OAAM,KAAK,aAAa,EAAE,UAAU,QAAQ,EAAE,CAAC,IAAI;AACxE,MAAI,EAAE,UAAU,EAAG,OAAM,KAAK,WAAW,EAAE,QAAQ,QAAQ,EAAE,CAAC,IAAI;AAElE,SAAO,MAAM,KAAK,KAAK;;;;;CAMzB,aAAsC;AACpC,SAAO,EAAE,GAAG,KAAK,UAAU;;;;;;;AAQ/B,MAAa,kBAAkB,IAAI,gBAAgB"}