References

type SoundRole =
  // Interaction (4)
  | "interaction.tap"
  | "interaction.subtle"
  | "interaction.toggle"
  | "interaction.confirm"
  // Overlay (4)
  | "overlay.open"
  | "overlay.close"
  | "overlay.expand"
  | "overlay.collapse"
  // Navigation (3)
  | "navigation.forward"
  | "navigation.backward"
  | "navigation.tab"
  // Notification (4)
  | "notification.info"
  | "notification.success"
  | "notification.warning"
  | "notification.error"
  // Hero (2)
  | "hero.complete"
  | "hero.milestone";

type SoundPackName =
  | "soft"
  | "aero"
  | "arcade"
  | "organic"
  | "glass"
  | "industrial"
  | "minimal"
  | "retro"
  | "crisp";

interface SensoryUIProviderProps {
  children: React.ReactNode;
  config?: Partial<SensoryUIConfig>;
}

interface SensoryUIConfig {
  enabled: boolean;          // Default: true
  volume: number;            // Default: 0.35 (range: 0–1)
  theme: SoundPackName;      // Default: "aero"
  categories: {
    interaction: boolean;    // Default: true
    navigation: boolean;     // Default: true
    notification: boolean;   // Default: true
    overlay: boolean;        // Default: true
    hero: boolean;           // Default: false
  };
  overrides: Record<string, string>;  // URL or base64 data URI
  reducedMotion: "inherit" | "force-off" | "force-on";  // Default: "inherit"
}

interface PartSoundProps {
  sound?: SoundRole | false;   // Default: part-specific (see below)
  volume?: number;             // Default: 1 (per-component multiplier)
}

interface OpenCloseSoundProps {
  sound?: SoundRole | false;      // Default: "overlay.open"
  closeSound?: SoundRole | false; // Default: "overlay.close"
  volume?: number;                // Default: 1
}

interface OpenSoundProps {
  openSound?: SoundRole | false;  // Default: see below
  closeSound?: SoundRole | false; // Default: see below
  volume?: number;                // Default: 1
}

interface ExpandCollapseSoundProps {
  expandSound?: SoundRole | false;    // Default: "overlay.expand"
  collapseSound?: SoundRole | false;  // Default: "overlay.collapse"
  volume?: number;                    // Default: 1
}

import { useSensoryUI } from "@/components/ui/sensory-ui/config/provider";

const { playSound, enabled } = useSensoryUI();
await playSound("interaction.tap", { volume: 0.5 });

import { usePlaySound } from "@/components/ui/sensory-ui/config/use-play-sound";

function CustomComponent() {
  const { play, enabled } = usePlaySound({
    sound: "notification.success",
    volume: 0.5,
  });

  return <button onClick={play}>Play sound</button>;
}

function playSound(
  role: SoundRole,
  options?: PlaySoundOptions
): Promise<SoundPlayback | null>;

interface PlaySoundOptions {
  volume?: number;        // Per-call volume multiplier (0–1, default 1)
  playbackRate?: number;  // Playback speed (default 1, buffer sources only)
  onEnd?: () => void;     // Called when playback ends
}

interface SoundPlayback {
  stop: () => void;    // Cancel playback
}

import { resolveRole } from "@/components/ui/sensory-ui/config/config";

function resolveRole(
  role: SoundRole,
  config: SensoryUIConfig
): SoundSource | null;

import { playSound } from "@/components/ui/sensory-ui/config/engine";

function playSound(
  source: SoundSource,
  options?: PlaySoundOptions
): Promise<SoundPlayback>;