/**
 * Shared type definitions for the Goon Plugin.
 *
 * These types define the canonical video object shape used across:
 * - chrome.storage.local (persistence layer)
 * - Popup scan logic (index.js)
 * - Viewer grid renderer (viewer.js)
 *
 * TypeScript project is configured (tsconfig.json) but source files
 * are currently .js. The JSDoc-style interface below documents the
 * contract; `tsc --noEmit` validates .js files against these types
 * when @type references are used.
 */

/**
 * Media delivery format of the video source.
 * - 'direct' : plain MP4/WebM blob served via HTTP(S)
 * - 'hls'    : HTTP Live Streaming manifest (.m3u8)
 */
export type MediaType = 'direct' | 'hls';

/**
 * A single video entry discovered by a tab scan.
 *
 * All fields except `url` are optional to preserve backward
 * compatibility with entries written by older extension versions.
 *
 * @example
 *   // Legacy entry (still valid)
 *   { url: "https://example.com/video.mp4" }
 *
 * @example
 *   // Full entry with HLS support
 *   {
 *     url: "https://example.com/playlist.m3u8",
 *     src: "https://example.com/playlist.m3u8",
 *     poster: "https://example.com/thumbnail.jpg",
 *     tab: "Video Tab",
 *     hlsManifest: "https://cdn.example.com/stream.m3u8",
 *     mediaType: "hls"
 *   }
 */
export interface VideoEntry {
  /** Primary video URL. May point to the source file or the HLS manifest. */
  url: string;

  /** Direct source URL extracted from the <video> element (data-* or src). */
  src?: string;

  /** Poster / thumbnail image URL. */
  poster?: string | null;

  /** Title of the browser tab where the video was found. */
  tab?: string;

  /**
   * URL to an HLS manifest (.m3u8).
   *
   * When present, the viewer loads Hls.js to play adaptive streams.
   * Backward compatible: older entries simply omit this field.
   */
  hlsManifest?: string;

  /**
   * Media delivery format.
   *
   * Defaults to 'direct' when omitted. Set to 'hls' when the video
   * is delivered via HTTP Live Streaming.
   *
   * Backward compatible: entries without this field are treated as
   * `mediaType === 'direct'`.
   */
  mediaType?: MediaType;
}