@adea-ai/audio 0.10.8

package/README.md

@@ -0,0 +1,4 @@
+# Audio package
+
+Owns the optional music controller and React bindings used by Agent HQ. Audio is
+lazy and non-blocking so scene loading does not depend on sound assets.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@adea-ai/audio",
+  "version": "0.10.8",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18"
+  },
+  "dependencies": {
+    "lucide-react": "^1.33.0",
+    "react": "19.2.8"
+  }
+}

package/src/config.ts

@@ -0,0 +1,9 @@
+/** Optional soundtrack hooks for Agent HQ. */
+export const AUDIO_BASE_URL = "/assets/audio";
+export const MUSIC_DIR = `${AUDIO_BASE_URL}/sounds/music`;
+
+export const MUSIC_FILES = {
+  silent: "",
+} as const;
+
+export type MusicId = keyof typeof MUSIC_FILES;

package/src/controller.ts

@@ -0,0 +1,165 @@
+import { MUSIC_DIR, MUSIC_FILES, type MusicId } from "./config";
+
+export type MusicOptions = {
+  /** 0..1 track gain (default 0.8). */
+  volume?: number;
+  /** Crossfade/fade duration in ms (default 500). */
+  fadeMs?: number;
+};
+
+const MUSIC_MUTE_KEY = "agent-hq:audio:music-muted";
+const LEGACY_MUTE_KEY = "agent-hq:audio:muted";
+const DEFAULT_MUSIC_VOLUME = 0.8;
+const FADE_STEP_MS = 30;
+
+function clampVolume(value: number): number {
+  return value <= 0 ? 0 : value > 1 ? 1 : value;
+}
+
+function readStorage(key: string): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, muted: boolean): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (muted) window.localStorage.setItem(key, "1");
+    else window.localStorage.removeItem(key);
+  } catch {
+    // Storage can be unavailable; the in-memory mute still applies.
+  }
+}
+
+function loadMusicMuted(): boolean {
+  return readStorage(MUSIC_MUTE_KEY) === "1" || readStorage(LEGACY_MUTE_KEY) === "1";
+}
+
+export class SoundController {
+  private musicElements = new Map<MusicId, HTMLAudioElement>();
+  private desiredMusic: MusicId | null = null;
+  private currentMusic: MusicId | null = null;
+  private activeFades = new Set<number>();
+  private _musicMuted: boolean;
+
+  constructor() {
+    this._musicMuted = loadMusicMuted();
+  }
+
+  get musicMuted(): boolean {
+    return this._musicMuted;
+  }
+
+  /** Retry queued playback after a user gesture. */
+  async unlock(): Promise<void> {
+    this.startDesiredMusic();
+  }
+
+  /** Start or switch to a looping soundtrack. */
+  playMusic(id: MusicId, options: MusicOptions = {}): void {
+    if (!MUSIC_FILES[id]) return;
+    this.desiredMusic = id;
+    this.prepareMusicElement(id);
+    if (!this.musicMuted) this.startMusic(id, options);
+  }
+
+  setMusicMuted(muted: boolean): void {
+    this._musicMuted = muted;
+    writeStorage(MUSIC_MUTE_KEY, muted);
+    for (const element of this.musicElements.values()) {
+      if (muted) element.pause();
+    }
+    if (!muted) this.startDesiredMusic();
+  }
+
+  toggleMusicMute(): boolean {
+    this.setMusicMuted(!this._musicMuted);
+    return this._musicMuted;
+  }
+
+  private prepareMusicElement(id: MusicId): void {
+    if (this.musicElements.has(id)) return;
+    const element = new Audio(`${MUSIC_DIR}/${MUSIC_FILES[id]}`);
+    element.loop = true;
+    // Defer the request until playback is allowed so audio never competes with
+    // the scene's first visual and physics assets.
+    element.preload = "none";
+    this.musicElements.set(id, element);
+  }
+
+  private startMusic(id: MusicId, options: MusicOptions = {}): void {
+    if (this.currentMusic === id) {
+      const active = this.musicElements.get(id);
+      if (active?.paused) void active.play().catch(() => undefined);
+      return;
+    }
+
+    const fadeMs = options.fadeMs ?? 500;
+    const target = clampVolume(options.volume ?? DEFAULT_MUSIC_VOLUME);
+    const previousId = this.currentMusic;
+    const previous = previousId ? (this.musicElements.get(previousId) ?? null) : null;
+    this.currentMusic = id;
+    const element = this.musicElements.get(id);
+    if (!element) return;
+    element.volume = 0;
+    element.currentTime = 0;
+    void element
+      .play()
+      .then(() => {
+        if (this.currentMusic !== id) {
+          element.pause();
+          return;
+        }
+        if (previous) {
+          this.fadeMusic(previous, 0, fadeMs, () => {
+            previous.pause();
+            previous.currentTime = 0;
+          });
+        }
+        this.fadeMusic(element, target, fadeMs);
+      })
+      .catch(() => {
+        // Autoplay is blocked before the first user gesture. Keep the desired
+        // track so unlock() can retry it later.
+        if (previous) this.currentMusic = previousId;
+        else this.currentMusic = null;
+      });
+  }
+
+  private startDesiredMusic(): void {
+    if (this.musicMuted || !this.desiredMusic) return;
+    const desired = this.desiredMusic;
+    if (this.currentMusic !== desired) {
+      this.startMusic(desired);
+      return;
+    }
+    const element = this.musicElements.get(desired);
+    if (element?.paused) void element.play().catch(() => undefined);
+  }
+
+  private fadeMusic(
+    element: HTMLAudioElement,
+    target: number,
+    durationMs: number,
+    onDone?: () => void
+  ): void {
+    const start = element.volume;
+    const startTime = performance.now();
+    const interval = window.setInterval(() => {
+      const progress = Math.min(1, (performance.now() - startTime) / Math.max(durationMs, 1));
+      element.volume = start + (target - start) * progress;
+      if (progress >= 1) {
+        window.clearInterval(interval);
+        this.activeFades.delete(interval);
+        onDone?.();
+      }
+    }, FADE_STEP_MS);
+    this.activeFades.add(interval);
+  }
+}
+
+export const soundController = new SoundController();

package/src/index.ts

@@ -0,0 +1,12 @@
+// Optional soundtrack hooks for Agent HQ.
+
+export { AUDIO_BASE_URL, MUSIC_FILES, type MusicId } from "./config";
+export { SoundController, soundController, type MusicOptions } from "./controller";
+export { musicForScene, sceneMusicTracks } from "./scene-music";
+export {
+  MusicToggle,
+  SoundProvider,
+  useSceneMusic,
+  useSound,
+  type SoundContextValue,
+} from "./react";

package/src/react.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { Music, Music2 } from "lucide-react";
+import { soundController, type MusicOptions } from "./controller";
+import { musicForScene } from "./scene-music";
+import type { MusicId } from "./config";
+
+export type SoundContextValue = {
+  controller: typeof soundController;
+  ready: boolean;
+  musicMuted: boolean;
+  toggleMusicMute: () => void;
+  playMusic: (id: MusicId, options?: MusicOptions) => void;
+};
+
+const SoundContext = createContext<SoundContextValue | null>(null);
+
+export function SoundProvider({ children }: { children: ReactNode }) {
+  const [musicMuted, setMusicMuted] = useState(false);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    queueMicrotask(() => {
+      if (mounted) setMusicMuted(soundController.musicMuted);
+    });
+
+    const onGesture = () => {
+      void soundController.unlock().then(() => {
+        if (mounted) setReady(true);
+      });
+    };
+    window.addEventListener("pointerdown", onGesture, { capture: true });
+    window.addEventListener("keydown", onGesture, { capture: true });
+    window.addEventListener("touchstart", onGesture, { capture: true });
+    if (new URLSearchParams(window.location.search).has("debug")) {
+      (window as unknown as { __agentHqSound?: typeof soundController }).__agentHqSound =
+        soundController;
+    }
+    return () => {
+      mounted = false;
+      window.removeEventListener("pointerdown", onGesture, { capture: true });
+      window.removeEventListener("keydown", onGesture, { capture: true });
+      window.removeEventListener("touchstart", onGesture, { capture: true });
+    };
+  }, []);
+
+  const value = useMemo<SoundContextValue>(
+    () => ({
+      controller: soundController,
+      ready,
+      musicMuted,
+      toggleMusicMute: () => setMusicMuted(soundController.toggleMusicMute()),
+      playMusic: (id, options) => soundController.playMusic(id, options),
+    }),
+    [musicMuted, ready]
+  );
+
+  return <SoundContext.Provider value={value}>{children}</SoundContext.Provider>;
+}
+
+export function useSound(): SoundContextValue {
+  const value = useContext(SoundContext);
+  if (!value) throw new Error("useSound must be used within <SoundProvider>");
+  return value;
+}
+
+export function useSceneMusic(sceneId: string | null | undefined): void {
+  useEffect(() => {
+    const timeout = window.setTimeout(() => {
+      soundController.playMusic(musicForScene(sceneId));
+    }, 1500);
+    return () => window.clearTimeout(timeout);
+  }, [sceneId]);
+}
+
+function MusicButton({ muted, onToggle }: { muted: boolean; onToggle: () => void }) {
+  return (
+    <button
+      type="button"
+      aria-label={muted ? "Unmute music" : "Mute music"}
+      aria-pressed={muted}
+      onClick={onToggle}
+      className={`inline-flex size-9 items-center justify-center rounded-lg border border-input bg-background transition-colors ${muted ? "text-muted-foreground hover:text-foreground" : "bg-primary text-primary-foreground"}`}
+    >
+      {muted ? (
+        <Music className="size-5" aria-hidden="true" />
+      ) : (
+        <Music2 className="size-5" aria-hidden="true" />
+      )}
+    </button>
+  );
+}
+
+export function MusicToggle() {
+  const { musicMuted, toggleMusicMute } = useSound();
+  return <MusicButton muted={musicMuted} onToggle={toggleMusicMute} />;
+}

package/src/scene-music.ts

@@ -0,0 +1,11 @@
+import type { MusicId } from "./config";
+
+/** Scene route id -> optional track. Deployments can add tracks without changing scene code. */
+export const sceneMusicTracks: Record<string, MusicId> = {
+  "hq-home": "silent",
+  "hq-work": "silent",
+};
+
+export function musicForScene(sceneId: string | null | undefined): MusicId {
+  return sceneMusicTracks[sceneId ?? ""] ?? "silent";
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}