// Public types for the AudioPlayer v6.
// See packages/ui-tools/@dev/@refactoring6-audioplayer/04-implementation/api.md

export type WaveformMode = 'peaks' | 'live' | 'bars' | 'progress' | 'none';

export type WaveformConfig = {
  mode?: WaveformMode;
  peaks?: Float32Array;
  height?: number;
  barWidth?: number;
  barGap?: number;
  bgColor?: string;
  fgColor?: string;
  decodeOnMount?: boolean;
};

export type ReactiveCoverMode = false | 'subtle';
export type PlayerVariant = 'default' | 'compact' | 'auto';
export type PlayerErrorReason = 'network' | 'decode' | 'unsupported' | 'unknown';

export type PlayerProps = {
  src: string;
  peaks?: Float32Array;

  title?: string;
  artist?: string;
  album?: string;
  cover?: string;

  variant?: PlayerVariant;
  className?: string;

  waveform?: WaveformConfig;
  reactiveCover?: ReactiveCoverMode;

  autoplay?: boolean;
  loop?: boolean;
  initialVolume?: number;
  muted?: boolean;
  preload?: 'none' | 'metadata' | 'auto';
  exclusive?: boolean;

  onPrev?: () => void;
  onNext?: () => void;

  onPlay?: () => void;
  onPause?: () => void;
  onEnded?: () => void;
  onError?: (reason: PlayerErrorReason, e: unknown) => void;
  onTimeUpdate?: (currentTime: number, duration: number) => void;

  ariaLabel?: string;
  enableKeyboardShortcuts?: boolean;

  /** Focus the player container on mount so its keyboard scope is active
   *  immediately. Pair with `key={src}` upstream when the parent wants a
   *  fresh focus on every source change (file-browser inspector pattern). */
  autoFocus?: boolean;

  // When the user clicks on the waveform while paused, also start playback.
  // Default true — clicking on a time mark almost always means "play here".
  // Set false for embeds where stray clicks shouldn't trigger sound.
  seekStartsPlayback?: boolean;
};

export type PlayerStateKind =
  | 'idle'
  | 'loading'
  | 'decoding'
  | 'ready'
  | 'playing'
  | 'paused'
  | 'ended'
  | 'error';

export type PlayerState =
  | { kind: 'idle' | 'loading' }
  | { kind: 'decoding'; duration: number }
  | { kind: 'ready' | 'playing' | 'paused' | 'ended'; duration: number; peaks?: Float32Array }
  | { kind: 'error'; reason: PlayerErrorReason; duration: number };

export type PlayerControls = {
  play: () => Promise<void>;
  pause: () => void;
  toggle: () => Promise<void>;
  seek: (seconds: number) => void;
  seekTo: (ratio: number) => void;
  setVolume: (v: number) => void;
  toggleMute: () => void;
  toggleLoop: () => void;
};

export type PlayerHandle = {
  audio: HTMLAudioElement;
  play: () => Promise<void>;
  pause: () => void;
  seek: (seconds: number) => void;
  getCurrentTime: () => number;
  getDuration: () => number;
  /** Move keyboard focus to the player container so its hotkey scope
   *  (Space=play/pause, ←→=seek, ↑↓=volume, M=mute) becomes active. */
  focus: () => void;
};