TX/artifacts/tx-os/src/lib/notification-sounds.ts

import type { NotificationSoundId } from "@workspace/api-client-react";
import {
  NOTIFICATION_SOUND_MANIFEST,
  SOUND_BY_ID,
} from "@/lib/notification-sound-manifest";

export const ALL_SOUND_IDS: ReadonlyArray<NotificationSoundId> =
  NOTIFICATION_SOUND_MANIFEST.map((s) => s.id);

/**
 * Custom DOM event the player dispatches when a play attempt is denied
 * because the user hasn't yet interacted with the page (browser autoplay
 * policy) or the AudioContext could not be resumed. The App listens for
 * this and shows a one-time toast hint. The event `detail` carries an
 * `isIos` flag so the toast can include iPad-specific guidance (raise
 * the *media* volume, since the iOS path now plays through the media
 * channel via HTMLAudioElement — see the iOS notes on `class
 * NotificationPlayer` below).
 */
export const AUTOPLAY_BLOCKED_EVENT = "txos:notification-autoplay-blocked";

export type AutoplayBlockedDetail = {
  isIos: boolean;
};

// iPad/iPhone/iPod detection used to surface a more actionable hint
// (e.g. "raise the media volume") AND to switch the playback engine to
// HTMLAudioElement, which is the only way to route notification chimes
// through the iOS *media* channel instead of the *ringer* channel.
// Modern iPadOS reports as Mac in `userAgent`, so we also check for
// Mac + multi-touch.
function detectIos(): boolean {
  if (typeof navigator === "undefined") return false;
  const ua = navigator.userAgent || "";
  if (/iPad|iPhone|iPod/.test(ua)) return true;
  // iPadOS 13+ desktop Safari masquerade.
  if (
    ua.includes("Macintosh") &&
    typeof navigator.maxTouchPoints === "number" &&
    navigator.maxTouchPoints > 1
  ) {
    return true;
  }
  return false;
}

type WindowWithWebkitAC = Window & {
  webkitAudioContext?: typeof AudioContext;
};

/**
 * NotificationPlayer
 * --------------------------------------------------------------------
 * Two playback engines, picked once per process based on `detectIos()`:
 *
 *   • Non-iOS (desktop, Android Chrome, Firefox, etc.):
 *     Web Audio API (`AudioContext` + decoded `AudioBuffer`s). Lower
 *     latency, can pre-decode in the background, and respects the
 *     user's expectation of "the sound the page plays."
 *
 *   • iOS (iPad / iPhone Safari + iPadOS-as-Mac masquerade):
 *     HTMLAudioElement (`new Audio(url)`). On iOS, Web Audio is routed
 *     through the *ringer* channel, which is silenced by the silent
 *     switch / Control Center mute and uses the *ringer* volume — even
 *     when the user has the *media* volume turned up (which is the
 *     volume that controls YouTube and other media). HTMLAudioElement
 *     plays through the media channel, identical to a `<video>` tag,
 *     so notifications stay audible whenever YouTube/Safari videos
 *     would also be audible.
 *
 * Both engines share the same throttling, autoplay-hint, vibration,
 * and test-only observability so callers (`socket`, settings preview)
 * see one uniform `play()` / `testPlay()` interface.
 */
class NotificationPlayer {
  // ---- Engine selection ----
  // Frozen at first use: detectIos() reads navigator, which is stable
  // for a session. Caching avoids repeated UA sniffing on every play.
  private isIosEngine: boolean | null = null;

  // ---- Web Audio (non-iOS) state ----
  private ctx: AudioContext | null = null;
  private buffers = new Map<NotificationSoundId, AudioBuffer>();
  private loading = new Map<NotificationSoundId, Promise<AudioBuffer | null>>();

  // ---- HTMLAudioElement (iOS) state ----
  // One element per sound id, reused across plays. iOS requires that
  // each element be `.play()`-ed at least once inside a user gesture
  // before it can be played later out-of-gesture; we satisfy that in
  // `unlock()` by playing-then-pausing every element silently.
  private htmlAudios = new Map<NotificationSoundId, HTMLAudioElement>();
  private htmlAudioUnlocked = new Set<NotificationSoundId>();

  // ---- Shared state ----
  private unlocked = false;
  private lastPlayAt = 0;
  private hintDispatched = false;

  private get useIos(): boolean {
    if (this.isIosEngine === null) this.isIosEngine = detectIos();
    return this.isIosEngine;
  }

  isUnlocked(): boolean {
    if (!this.unlocked) return false;
    if (this.useIos) {
      // On iOS, "unlocked" is set only once at least one
      // HTMLAudioElement has finished its silent priming play+pause
      // inside a gesture (see `unlock()` for why this matters for
      // hint suppression timing).
      return this.htmlAudioUnlocked.size > 0;
    }
    return this.ctx?.state === "running";
  }

  // ---- Web Audio helpers (non-iOS) ----

  /**
   * Lazily build the shared AudioContext. Returns `null` when the
   * Web Audio API is unavailable (very old browsers / SSR) so callers
   * can degrade gracefully.
   */
  private getContext(): AudioContext | null {
    if (this.ctx) return this.ctx;
    if (typeof window === "undefined") return null;
    const w = window as WindowWithWebkitAC;
    const Ctor = window.AudioContext ?? w.webkitAudioContext;
    if (!Ctor) return null;
    try {
      this.ctx = new Ctor();
    } catch {
      return null;
    }
    return this.ctx;
  }

  private async loadBuffer(
    soundId: NotificationSoundId,
  ): Promise<AudioBuffer | null> {
    const cached = this.buffers.get(soundId);
    if (cached) return cached;
    const inFlight = this.loading.get(soundId);
    if (inFlight) return inFlight;
    const ctx = this.getContext();
    const entry = SOUND_BY_ID.get(soundId);
    if (!ctx || !entry) return null;
    const promise = (async () => {
      try {
        const res = await fetch(entry.url, { credentials: "same-origin" });
        if (!res.ok) return null;
        const ab = await res.arrayBuffer();
        // Older WebKit only supports the callback form of decodeAudioData;
        // wrap so we always get a Promise.
        const buf = await new Promise<AudioBuffer>((resolve, reject) => {
          try {
            const maybe = ctx.decodeAudioData(
              ab,
              (b) => resolve(b),
              (e) => reject(e ?? new Error("decode failed")),
            );
            if (maybe && typeof (maybe as Promise<AudioBuffer>).then === "function") {
              (maybe as Promise<AudioBuffer>).then(resolve, reject);
            }
          } catch (e) {
            reject(e);
          }
        });
        this.buffers.set(soundId, buf);
        return buf;
      } catch {
        return null;
      } finally {
        this.loading.delete(soundId);
      }
    })();
    this.loading.set(soundId, promise);
    return promise;
  }

  // ---- HTMLAudioElement helpers (iOS) ----

  /**
   * Lazily build (or fetch the cached) HTMLAudioElement for a sound.
   * `preload="auto"` lets Safari start fetching the file early so the
   * first play after unlock has its data ready.
   */
  private getHtmlAudio(soundId: NotificationSoundId): HTMLAudioElement | null {
    if (typeof window === "undefined") return null;
    const cached = this.htmlAudios.get(soundId);
    if (cached) return cached;
    const entry = SOUND_BY_ID.get(soundId);
    if (!entry) return null;
    try {
      const el = new Audio(entry.url);
      el.preload = "auto";
      // `playsInline` is a video-only attribute on the type, but
      // setting it on an Audio element is harmless and silences a
      // theoretical fullscreen-takeover path on very old iOS.
      (el as HTMLAudioElement & { playsInline?: boolean }).playsInline = true;
      el.crossOrigin = "anonymous";
      this.htmlAudios.set(soundId, el);
      return el;
    } catch {
      return null;
    }
  }

  // ---- Public API ----

  /**
   * Browsers require a user gesture before audio can play. Call this
   * from inside a gesture handler (pointerdown/touchstart/keydown).
   *
   * On non-iOS we resume the AudioContext and play a 1-sample silent
   * buffer (iOS Safari's own trick, kept for any WebKit-derived
   * non-iOS browser still requiring it), then pre-decode all buffers.
   *
   * On iOS we instead play-then-pause every HTMLAudioElement silently
   * inside the gesture so each one is permanently allowed to play
   * later (e.g. when a socket event arrives outside any gesture).
   *
   * Safe to call repeatedly; both engines tolerate it.
   */
  unlock(): void {
    if (this.useIos) {
      // iOS path: walk every sound and prime its <audio> element. We
      // mute it for the priming play so the user doesn't hear a
      // burst of all 8 sounds at once. After the silent play resolves
      // we pause + restore volume + reset currentTime so the next
      // real play() starts from the beginning at full volume.
      //
      // We only flip `this.unlocked = true` once at least one element
      // has actually finished a successful priming play. Setting it
      // synchronously would cause the hint suppression path in
      // `playIos()` (which checks `!this.unlocked`) to swallow a
      // legitimate NotAllowedError from a play attempt that arrives
      // between the gesture and the moment the priming promise
      // settles.
      for (const entry of NOTIFICATION_SOUND_MANIFEST) {
        if (this.htmlAudioUnlocked.has(entry.id)) continue;
        const el = this.getHtmlAudio(entry.id);
        if (!el) continue;
        const originalVolume = el.volume;
        el.volume = 0;
        const markPrimed = () => {
          try {
            el.pause();
            el.currentTime = 0;
            el.volume = originalVolume;
            this.htmlAudioUnlocked.add(entry.id);
            this.unlocked = true;
          } catch {
            /* ignore */
          }
        };
        const p = el.play();
        if (p && typeof p.then === "function") {
          p.then(markPrimed).catch(() => {
            // Element couldn't start — likely no gesture yet, or the
            // user denied it. We'll try again on the next gesture.
            try {
              el.volume = originalVolume;
            } catch {
              /* ignore */
            }
          });
        } else {
          // Synchronous return (very old WebKit). Treat as success.
          markPrimed();
        }
      }
      return;
    }

    // Non-iOS Web Audio path (original behavior).
    const ctx = this.getContext();
    if (!ctx) return;

    // Always attempt resume() — even if `unlocked` is already true the
    // context may have been auto-suspended.
    if (ctx.state !== "running") {
      void ctx.resume().catch(() => {});
    }

    try {
      const silent = ctx.createBuffer(1, 1, 22050);
      const src = ctx.createBufferSource();
      src.buffer = silent;
      src.connect(ctx.destination);
      src.start(0);
    } catch {
      /* not fatal — resume() alone may still be enough */
    }

    if (this.unlocked) return;
    this.unlocked = true;

    for (const entry of NOTIFICATION_SOUND_MANIFEST) {
      void this.loadBuffer(entry.id);
    }
  }

  private dispatchHint() {
    if (this.hintDispatched) return;
    this.hintDispatched = true;
    if (typeof window !== "undefined") {
      const detail: AutoplayBlockedDetail = { isIos: this.useIos };
      window.dispatchEvent(
        new CustomEvent<AutoplayBlockedDetail>(AUTOPLAY_BLOCKED_EVENT, {
          detail,
        }),
      );
    }
    // Allow another hint after a generous cool-down so the user doesn't
    // get spammed if they ignore the first toast.
    setTimeout(() => {
      this.hintDispatched = false;
    }, 30_000);
  }

  /**
   * Play a notification chime by id. Safe to call before `unlock()` —
   * the play attempt will simply surface the autoplay-blocked hint
   * once instead of producing audio. Throttled to at most one chime
   * every 3 s to coalesce bursts.
   */
  play(
    soundId: NotificationSoundId,
    opts: { vibrate?: boolean; bypassThrottle?: boolean } = {},
  ): void {
    // Throttle: at most one sound every 3s to coalesce bursts of
    // notifications into a single chime. Settings "Test sound"
    // bypasses this so users can audition multiple sounds quickly.
    const now =
      typeof performance !== "undefined" ? performance.now() : Date.now();
    if (!opts.bypassThrottle) {
      if (now - this.lastPlayAt < 3000) return;
      this.lastPlayAt = now;
    }

    const entry = SOUND_BY_ID.get(soundId) ?? SOUND_BY_ID.get("ding");
    if (!entry) return;

    // Test-only observability: expose a counter + last sound so Playwright
    // can assert chime invocation. Gated on dev/test bundles so production
    // builds don't leak debug globals.
    if (typeof window !== "undefined" && import.meta.env.MODE !== "production") {
      const w = window as unknown as {
        __txosNotifPlayCount?: number;
        __txosNotifLastSound?: NotificationSoundId;
      };
      w.__txosNotifPlayCount = (w.__txosNotifPlayCount ?? 0) + 1;
      w.__txosNotifLastSound = entry.id;
    }

    if (this.useIos) {
      this.playIos(entry.id);
    } else {
      this.playWebAudio(entry.id);
    }

    if (opts.vibrate && typeof navigator !== "undefined" && navigator.vibrate) {
      try {
        navigator.vibrate([60, 40, 60]);
      } catch {
        /* ignore */
      }
    }
  }

  private playIos(soundId: NotificationSoundId): void {
    const el = this.getHtmlAudio(soundId);
    if (!el) {
      if (!this.unlocked) this.dispatchHint();
      return;
    }
    try {
      el.currentTime = 0;
    } catch {
      /* some browsers throw if not seekable yet — safe to ignore */
    }
    const p = el.play();
    if (p && typeof p.then === "function") {
      p.catch(() => {
        // Most common rejections: NotAllowedError (autoplay policy
        // before any gesture), or a transient AbortError from an
        // immediate currentTime reset on the next play. The hint
        // toast covers the autoplay case; the abort case is benign
        // and we don't want to spam the user.
        if (!this.unlocked) this.dispatchHint();
      });
    }
  }

  private playWebAudio(soundId: NotificationSoundId): void {
    const ctx = this.getContext();
    if (!ctx) {
      if (!this.unlocked) this.dispatchHint();
      return;
    }
    if (ctx.state !== "running") {
      void ctx.resume().catch(() => {});
    }
    void this.loadBuffer(soundId).then((buf) => {
      if (!buf) return;
      if (ctx.state !== "running") {
        this.dispatchHint();
        return;
      }
      try {
        const src = ctx.createBufferSource();
        src.buffer = buf;
        src.connect(ctx.destination);
        src.start(0);
      } catch {
        /* ignore one-off node errors */
      }
    });
  }

  /**
   * Force-play used by the "Test sound" button in settings. Bypasses
   * the 3-second throttle (so users can audition several sounds in a
   * row) and unlocks the audio first since this is always called from
   * inside a click handler.
   */
  testPlay(soundId: NotificationSoundId): void {
    this.unlock();
    this.play(soundId, { bypassThrottle: true });
  }
}

export const notificationPlayer = new NotificationPlayer();

// Test-only accessor so Playwright can assert the singleton player's
// AudioContext state after a user gesture (the actual production path
// on non-iOS, not a freshly constructed test ctx). Gated on dev/test
// bundles to avoid leaking internals into production. Returns the
// engine name on iOS (where there is no AudioContext) so tests can
// still distinguish "unlocked" from "not yet unlocked".
if (typeof window !== "undefined" && import.meta.env.MODE !== "production") {
  (window as unknown as {
    __txosNotifCtxState?: () => string | null;
  }).__txosNotifCtxState = () => {
    const p = notificationPlayer as unknown as {
      ctx: AudioContext | null;
      isIosEngine: boolean | null;
      unlocked: boolean;
    };
    if (p.isIosEngine) return p.unlocked ? "running" : "suspended";
    return p.ctx?.state ?? null;
  };
}