import { LitElement } from "lit";

//#region src/preview/FrameController.d.ts
/**
 * State returned by elements describing their readiness for a given time.
 */
interface FrameState {
  /**
   * Whether async preparation is needed before rendering.
   * Examples: video needs to seek, captions need to load data.
   */
  needsPreparation: boolean;
  /**
   * Whether the element is ready to render synchronously.
   * True when all async work is complete and renderFrame() can be called.
   */
  isReady: boolean;
  /**
   * Rendering priority hint. Lower numbers render first.
   * Used to order render calls for elements with dependencies.
   *
   * Standard priorities:
   * - PRIORITY_VIDEO (1): Video elements
   * - PRIORITY_CAPTIONS (2): Caption overlays
   * - PRIORITY_AUDIO (3): Audio elements
   * - PRIORITY_WAVEFORM (4): Audio visualizers (depend on audio)
   * - PRIORITY_IMAGE (5): Static images
   * - PRIORITY_DEFAULT (100): Fallback for custom elements
   */
  priority: number;
}
/**
 * Interface that elements implement to participate in centralized frame rendering.
 * Elements keep their rendering logic local but expose a standardized interface.
 */
interface FrameRenderable {
  /**
   * Query the element's readiness state for a given time.
   * Must be synchronous and cheap to call.
   */
  getFrameState(timeMs: number): FrameState;
  /**
   * Async preparation phase. Called when getFrameState().needsPreparation is true.
   * Performs any async work needed before rendering (seeking, loading, etc.).
   *
   * @param timeMs - The time to prepare for
   * @param signal - Abort signal for cancellation
   */
  prepareFrame(timeMs: number, signal: AbortSignal): Promise<void>;
  /**
   * Synchronous render phase. Called after all preparation is complete.
   * Performs the actual rendering (paint to canvas, update DOM, etc.).
   *
   * @param timeMs - The time to render
   */
  renderFrame(timeMs: number): void;
}
/**
 * Per-phase timing data returned by FrameController.renderFrame().
 * All values are in milliseconds.
 */
interface RenderFrameTiming {
  queryMs: number;
  prepareMs: number;
  renderMs: number;
  animsMs: number;
}
/**
 * Options for FrameController.renderFrame()
 */
interface RenderFrameOptions {
  /**
   * Whether to wait for Lit updateComplete before querying elements.
   * Default: true
   */
  waitForLitUpdate?: boolean;
  /**
   * Callback to update CSS animations after frame rendering completes.
   * Called with the root element after all elements have rendered.
   * This centralizes animation synchronization in one place.
   */
  onAnimationsUpdate?: (rootElement: Element) => void;
}
/**
 * Central controller for frame rendering.
 * Lives at the root timegroup and orchestrates all element rendering.
 */
declare class FrameController {
  #private;
  constructor(rootElement: LitElement & {
    currentTimeMs: number;
  });
  /**
   * Cancel any in-progress render operation and mark the last frame stale.
   *
   * Use this when a user-initiated seek or time change invalidates the current
   * render and a fresh render is needed immediately.
   *
   * Do NOT call this from quality-upgrade callbacks — use markLastFrameStale()
   * instead to avoid aborting an in-progress scrub seek.
   */
  abort(): void;
  /**
   * Mark the last rendered frame stale WITHOUT aborting any in-progress render.
   *
   * Use this for quality-upgrade re-renders: the goal is to show a
   * higher-quality frame at the same time, but aborting the current render
   * would cancel an in-progress scrub seek. If quality-upgrade calls fire
   * faster than scrub seeks can complete, every seek would be aborted before
   * returning a sample — infinite loop, canvas stuck on first frame.
   *
   * With only the stale marker, the current render continues uninterrupted. When
   * it finishes, the queued re-render fires and can upgrade to main quality.
   *
   * Do NOT call abort() from quality-upgrade callbacks — use this method instead.
   */
  markLastFrameStale(): void;
  /**
   * Render a frame at the specified time.
   *
   * This is the main entry point for frame rendering. It:
   * 1. Cancels any previous in-progress render
   * 2. Queries all visible FrameRenderable elements
   * 3. Runs preparation in parallel for elements that need it
   * 4. Runs render in priority order
   *
   * @param timeMs - The time in milliseconds to render
   * @param options - Optional configuration
   */
  renderFrame(timeMs: number, options?: RenderFrameOptions): Promise<RenderFrameTiming | null>;
  /**
   * Check if a render is currently in progress.
   */
  get isRendering(): boolean;
}
//#endregion
export { FrameController, FrameRenderable, FrameState, RenderFrameOptions };
//# sourceMappingURL=FrameController.d.ts.map