watchparty/client/src/global.d.ts

/**
 * 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;
}

// --- Google Cast Sender SDK (CDN global, see client/src/index.html) --------
// Minimal shape covering only what client/src/cast.ts actually calls - not
// the full Cast Application Framework API surface. Accessed only via
// `window.chrome`/`window.cast` there (never the bare identifiers), same
// reasoning as `window.Hls` above: neither is guaranteed to exist at all
// outside a Chromium-family browser, and a bare undeclared identifier read
// (unlike a property read off `window`) throws instead of yielding undefined.

interface CastMediaInfo {
  metadata?: { title?: string };
}

interface CastSession {
  loadMedia(request: unknown): Promise<void>;
  endSession(stopCasting: boolean): void;
}

interface CastContextEvent {
  castState?: string;
  sessionState?: string;
}

interface CastContext {
  setOptions(options: { receiverApplicationId: string; autoJoinPolicy: string }): void;
  requestSession(): Promise<void>;
  getCurrentSession(): CastSession | null;
  getCastState(): string;
  addEventListener(type: string, handler: (event: CastContextEvent) => void): void;
}

interface RemotePlayer {
  isPaused: boolean;
  currentTime: number;
  duration: number;
}

interface RemotePlayerController {
  playOrPause(): void;
  seek(): void;
  addEventListener(type: string, handler: () => void): void;
}

interface CastFramework {
  CastContext: { getInstance(): CastContext };
  CastContextEventType: { CAST_STATE_CHANGED: string; SESSION_STATE_CHANGED: string };
  CastState: { NO_DEVICES_AVAILABLE: string };
  SessionState: { SESSION_ENDED: string };
  RemotePlayer: new () => RemotePlayer;
  RemotePlayerController: new (player: RemotePlayer) => RemotePlayerController;
  RemotePlayerEventType: { IS_PAUSED_CHANGED: string; CURRENT_TIME_CHANGED: string };
}

interface Window {
  chrome?: {
    cast?: {
      isAvailable?: boolean;
      AutoJoinPolicy: { ORIGIN_SCOPED: string };
      media: {
        DEFAULT_MEDIA_RECEIVER_APP_ID: string;
        MediaInfo: new (contentId: string, contentType: string) => CastMediaInfo;
        LoadRequest: new (mediaInfo: CastMediaInfo) => unknown;
      };
    };
  };
  cast?: { framework: CastFramework };
  __onGCastApiAvailable?: (isAvailable: boolean) => void;
}