// Public types for the chat-audio subsystem.

export type ChatAudioEvent =
  | 'messageSent'
  | 'messageReceived'
  | 'streamStart'
  | 'error'
  | 'mention'
  | 'notification';

/** Map an event to a sound URL. `false` silences the event explicitly. */
export type ChatAudioSounds = Partial<Record<ChatAudioEvent, string | false>>;

export interface ChatAudioConfig {
  /** Map event → asset URL. Omit (or set `false`) to silence one event. */
  sounds?: ChatAudioSounds;
  /** Master volume 0..1. Persisted via the global prefs store. */
  volume?: number;
  /** Master mute. */
  muted?: boolean;
  /** Custom predicate — return `false` to suppress a play call. */
  shouldPlay?: (event: ChatAudioEvent) => boolean;
  /** Default-suppress when user prefers reduced motion. Default: true. */
  respectReducedMotion?: boolean;
  /** Default-suppress when user prefers reduced data. Default: true. */
  respectReducedData?: boolean;
  /** Mute when host page is hidden (`visibilityState === 'hidden'`). Default: true. */
  muteWhenHidden?: boolean;
}

export interface UseChatAudioReturn {
  /** Play a sound for an event. No-ops if the event has no URL or is muted. */
  play: (event: ChatAudioEvent) => void;
  /** Eagerly load an event's audio (called automatically on mount). */
  preload: (event: ChatAudioEvent) => void;
  /** Manually unlock — useful in stories/tests. */
  unlock: () => void;
  /** True after the first user gesture inside the chat root. */
  isUnlocked: boolean;
  /** Master mute (persistent). */
  muted: boolean;
  setMuted: (m: boolean) => void;
  /** Master volume 0..1 (persistent). */
  volume: number;
  setVolume: (v: number) => void;
  /** Per-event opt-out (persistent). */
  isEventEnabled: (event: ChatAudioEvent) => boolean;
  setEventEnabled: (event: ChatAudioEvent, enabled: boolean) => void;
}
