import type { ChatMessage } from '../types';

/**
 * Transport-agnostic surface for surfacing "you have new messages" to the
 * user when they're not actively watching the chat.
 *
 * Two reference implementations ship with ui-tools:
 *   - `createBrowserNotifier` — Facebook-style document.title rotation +
 *     favicon badge, suitable for browser tabs.
 *   - `createNoopNotifier` — does nothing; default when no DOM is around
 *     and the safe pick inside Wails / Electron, where the host wires
 *     its own native dock-badge bridge instead.
 *
 * Hosts that want native badges (Wails dock, macOS notification dot)
 * implement this interface themselves and pass the instance into
 * `useChatUnreadNotifier({ notifier })`.
 */
export interface ChatNotifier {
  /**
   * Called whenever the unread count is non-zero AND the page is not
   * visible to the user. Implementations must be idempotent — they may
   * be called repeatedly with the same count.
   */
  setUnread(count: number, latest?: ChatMessage | null): void;

  /**
   * Called when the user is back (page visible, or dock opened) OR when
   * unread drops to zero. Implementations must fully restore any state
   * they mutated (title, favicon).
   */
  clear(): void;

  /**
   * Optional: release any resources (DOM listeners, cached canvases).
   * Called on hook unmount. Safe to omit.
   */
  dispose?(): void;
}