/**
 * Ambient declarations for things esbuild/the browser provide that aren't
 * npm packages - see client/build.mjs's `.html`-as-text loader, and
 * client/index.html's CDN <script> tags for hls.js/socket.io (both used
 * as plain globals, not imported - keeping the "pin an exact CDN version,
 * no bundler-managed copy" choice this app made from the start).
 */

/** Each component's own .html template, imported as a raw string - see
 *  any view's own .ts file for the pattern (`import html from './Foo.html'`). */
declare module '*.html' {
  const content: string;
  export default content;
}

/** Imported purely for esbuild's CSS bundling side effect (see any view's
 *  own `import './Foo.css'`) - there's nothing to type, the import itself
 *  is the whole point. */
declare module '*.css';

// --- socket.io-client (CDN global, see client/index.html) -------------------
// Minimal shape covering only what this app actually calls - not the full
// socket.io-client API surface.

interface AppClientSocket {
  on(event: string, handler: (...args: unknown[]) => void): void;
  emit(event: string, payload?: unknown): void;
  disconnect(): void;
}

declare function io(): AppClientSocket;

// --- hls.js (CDN global, see client/index.html) -----------------------------
// Same idea - only the surface client/src/views/player and musicBar
// actually use.

interface HlsErrorData {
  fatal: boolean;
  [key: string]: unknown;
}

interface HlsInstance {
  on(event: string, handler: (event: string, data: HlsErrorData) => void): void;
  loadSource(url: string): void;
  attachMedia(media: HTMLMediaElement): void;
  destroy(): void;
}

/** Only the loading-timeout knobs Player.ts/musicBar actually override -
 *  see their own HLS_CONFIG comment for why the defaults are too tight
 *  for this app's real transcode latency. */
interface HlsConfig {
  manifestLoadingTimeOut?: number;
  manifestLoadingMaxRetry?: number;
  levelLoadingTimeOut?: number;
  fragLoadingTimeOut?: number;
}

interface HlsStatic {
  new (config?: HlsConfig): HlsInstance;
  isSupported(): boolean;
  Events: { MANIFEST_PARSED: string; ERROR: string };
}

declare const Hls: HlsStatic | undefined;

interface Window {
  Hls?: HlsStatic;
}