@zakkster/lite-audio 1.0.0

package/Audio.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @zakkster/lite-audio - Zero-GC reactive Web Audio engine.
+ * Peers: @zakkster/lite-signal, @zakkster/lite-audio-pool.
+ */
+
+/**
+ * lite-signal's callable signal shape. A signal is a getter function that
+ * doubles as an object with .peek() and (for writable signals) .set().
+ * lite-audio exposes read-only signals to consumers; internal writes go
+ * through explicit setter methods on the engine.
+ */
+export interface ReadSignal<T> {
+    (): T;
+    peek(): T;
+}
+export interface WriteSignal<T> extends ReadSignal<T> {
+    set(value: T): void;
+}
+
+export type LoadState = 'idle' | 'loading' | 'ready' | 'error';
+export type CtxState = 'suspended' | 'running' | 'interrupted' | 'closed';
+
+export interface SoundConfig {
+    /** Source URL list, ordered by preference. First supported extension wins. */
+    src: string[];
+    /** Bus to route this sound to. Defaults to 'sfx'. Must exist in `opts.buses`. */
+    bus?: string;
+    /** Default volume for this sound (playOpts fallback). */
+    volume?: number;
+    /** Default pitch variation range for playOpts (e.g. 0.1 = plus/minus 10%). */
+    pitchVar?: number;
+}
+
+export interface LiteAudioOptions {
+    /**
+     * User-facing bus names. Do not include 'master' - it is always the top
+     * of the graph and is controlled via setMuted() / muted().
+     */
+    buses?: string[];
+
+    /** Voices per bus pool. Defaults to 32. */
+    poolCapacity?: number;
+
+    /**
+     * Maximum number of distinct sounds that can be queued for play before
+     * unlock. Same-sound repeats collapse to latest-per-sound; new distinct
+     * sounds past the limit are silently dropped.
+     */
+    queueLimit?: number;
+
+    /** localStorage key for master mute. Defaults to 'lite_audio_muted' (manager parity). */
+    mutedStorageKey?: string;
+
+    /** Injectable for tests. Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+
+    /** Injectable for tests. Defaults to globalThis.window. */
+    window?: any;
+
+    /** Injectable for tests. Defaults to globalThis.document. */
+    document?: any;
+}
+
+export class LiteAudio {
+    constructor(opts?: LiteAudioOptions);
+
+    /** Wire to an AudioContext. Creates one if none passed. Idempotent per-instance. */
+    init(ctx?: AudioContext): Promise<void>;
+
+    /**
+     * Fetch, decode, and register sounds. Resolves after every sound has
+     * settled (loaded or errored). Pools are built once per touched bus at
+     * the end. Safe to call multiple times to add more sounds.
+     */
+    defineSounds(config: Record<string, SoundConfig>): Promise<void>;
+
+    /**
+     * Positional hot path: no options object. Returns a bus-tagged voice handle,
+     * or -1 on any skip (unknown sound, not-yet-loaded, or context locked).
+     * Locked-context plays are queued and flushed on the first user gesture (D3).
+     *
+     * The handle is `busIndex * 2^32 + poolHandle`: a plain number, exact well
+     * inside 2^53, opaque to callers. The bus tag is what makes a handle name one
+     * voice engine-wide - every bus's pool counts generations from zero on its own,
+     * so the raw pool handles collide across buses by construction.
+     */
+    play(soundId: string, volume?: number, pan?: number, pitch?: number): number;
+
+    /**
+     * Sugar layer over play(): options object with pitchVar resolution.
+     * Not the hot path - a frame loop should call play() positionally.
+     */
+    playOpts(soundId: string, opts?: {
+        volume?: number;
+        pan?: number;
+        pitch?: number;
+        pitchVar?: number;
+    }): number;
+
+    /** Stop a specific voice by handle. Stale handles are silent no-ops. */
+    stop(handle: number): void;
+
+    /** Is this exact voice still sounding? False if stolen, stopped, or played out. */
+    isPlaying(handle: number): boolean;
+
+    /** Name of the bus that issued this handle, or null. */
+    busOf(handle: number): string | null;
+
+    /** Voices sounding on a bus, or across every bus when called with no argument. */
+    activeCount(busName?: string): number;
+
+    /** Stop every voice on a named bus. */
+    stopBus(busName: string): void;
+
+    /** Stop every voice across every bus. */
+    stopAll(): void;
+
+    // ---------- Bus + master controls --------------------------------------
+    setBusVolume(busName: string, volume: number): void;
+    setBusMuted(busName: string, muted: boolean): void;
+    setMuted(state: boolean): void;
+
+    // ---------- Reactive readables -----------------------------------------
+    /** Current AudioContext state signal. */
+    ctxState(): ReadSignal<CtxState>;
+    /** Whether the context has been unlocked by a user gesture. */
+    unlocked(): ReadSignal<boolean>;
+    /** Master mute signal (persisted to localStorage). */
+    muted(): ReadSignal<boolean>;
+    /** Per-sound load state signal. Undefined if the sound is not registered. */
+    loadState(soundId: string): ReadSignal<LoadState> | undefined;
+    /** Per-bus volume signal. Undefined for unknown bus name. */
+    busVolume(busName: string): ReadSignal<number> | undefined;
+    /** Per-bus mute signal. Undefined for unknown bus name. */
+    busMuted(busName: string): ReadSignal<boolean> | undefined;
+    /** Direct access to a bus's GainNode for advanced effect insertion. */
+    busNode(busName: string): GainNode | undefined;
+    /** Direct access to the master GainNode. */
+    masterNode(): GainNode | null;
+
+    /**
+     * Stop every voice, tear down pools and buses, dispose signal effects,
+     * detach DOM listeners, release references. Idempotent. Does not close
+     * the AudioContext - the app owns that.
+     */
+    destroy(): void;
+}
+
+export default LiteAudio;

package/Audio.js

@@ -0,0 +1,671 @@
+/** @zakkster/lite-audio - Zero-GC reactive Web Audio engine */
+
+import { signal, effect, batch, dispose } from '@zakkster/lite-signal';
+import { AudioPool } from '@zakkster/lite-audio-pool';
+
+/**
+ * Persistence key: byte-identical to lite-audio-manager so a game migrating
+ * from the manager to lite-audio does not lose the player's saved mute
+ * preference. Do not rename without a migration path.
+ */
+const MUTED_STORAGE_KEY = 'lite_audio_muted';
+
+/**
+ * Time constants held under lite-audio's roof. FADE_SECONDS is our default
+ * for non-emergency stops - short enough to feel instant, long enough to
+ * avoid clicks. RAMP_TC is the setTargetAtTime time constant for bus writes
+ * (D1): 10ms means the mixer settles ~63% within 10ms and effectively fully
+ * within 30ms, imperceptible to a listener but click-free.
+ */
+const FADE_SECONDS = 0.02;
+const RAMP_TC = 0.01;
+
+/**
+ * Handle namespace. A pool handle is a full uint32 - [gen:24][channel:8] - with no
+ * spare bits, and every bus runs its own pool counting generations from zero. So the
+ * first play on EVERY bus returns the same uint32 (channel 0, generation 0), and a
+ * handle alone cannot say which bus issued it. The engine therefore tags the bus
+ * above the pool's 32 bits: handle = busIndex * 2^32 + poolHandle.
+ *
+ * Handles stay plain numbers, exact to 2^53, which leaves room for 2^21 buses. The
+ * low half round-trips through ToUint32 for free (h >>> 0), so decoding costs one
+ * shift and one divide, and stop() becomes an O(1) lookup instead of a broadcast
+ * across every pool hoping the generation check rejects the wrong ones.
+ */
+const BUS_STRIDE = 4294967296;   // 2^32
+
+/**
+ * The unlock queue is bounded to bound worst-case memory: if a spammy loop
+ * calls play() a thousand times before the first user gesture, we do not
+ * want that to become a thousand-voice burst on unlock. Latest-per-sound
+ * so the most recent intent wins.
+ */
+const DEFAULT_QUEUE_LIMIT = 32;
+
+/**
+ * DOM events wired at capture phase to intercept the very first user gesture
+ * on iOS/Safari, exact set the manager uses. Do not add 'click' - some pages
+ * dispatch synthetic clicks that would falsely resume the context.
+ */
+const UNLOCK_EVENTS = ['touchstart', 'touchend', 'mousedown', 'keydown'];
+
+/**
+ * Storage-safe read (SSR / Workers / sandboxed iframes / Safari private mode).
+ * @param {string} key
+ * @param {any} fallback
+ */
+function readStorage(key, fallback) {
+    try {
+        if (typeof localStorage === 'undefined') return fallback;
+        const v = localStorage.getItem(key);
+        return v === null ? fallback : v;
+    } catch { return fallback; }
+}
+
+function writeStorage(key, value) {
+    try {
+        if (typeof localStorage === 'undefined') return;
+        localStorage.setItem(key, String(value));
+    } catch { /* Safari private mode / storage disabled */ }
+}
+
+// ---------- Loader ---------------------------------------------------------
+
+/**
+ * Format-fallback probe. Given a list of URLs like ['a.webm', 'b.mp3'], picks
+ * the first one whose extension the runtime claims to support via a
+ * throwaway <audio>.canPlayType('audio/<ext>') check. In Node or environments
+ * without <audio>, all URLs are considered supported and the first wins.
+ */
+function pickSupportedSrc(srcs) {
+    if (!Array.isArray(srcs) || srcs.length === 0) return null;
+    if (typeof document === 'undefined' || typeof Audio === 'undefined') return srcs[0];
+    let probe;
+    try { probe = new Audio(); } catch { return srcs[0]; }
+    for (const url of srcs) {
+        const ext = extensionOf(url);
+        const mime = ext ? MIME_BY_EXT[ext] : null;
+        if (!mime) continue;
+        const verdict = probe.canPlayType(mime);
+        if (verdict === 'probably' || verdict === 'maybe') return url;
+    }
+    return srcs[0];   // fall back to first if nothing matched, best-effort
+}
+
+const MIME_BY_EXT = {
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    opus: 'audio/ogg; codecs=opus',
+    wav: 'audio/wav',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    webm: 'audio/webm',
+    flac: 'audio/flac',
+};
+
+function extensionOf(url) {
+    const m = /\.([a-z0-9]{2,5})(\?|#|$)/i.exec(url);
+    return m ? m[1].toLowerCase() : null;
+}
+
+// ---------- Engine ---------------------------------------------------------
+
+/**
+ * lite-audio v1.0.0 engine. SFX layer over @zakkster/lite-audio-pool, one
+ * pool per bus. Signals drive continuous state (bus volumes, master mute,
+ * context state, load state); one-shots stay imperative through play().
+ *
+ * The typical lifecycle:
+ *   const audio = new LiteAudio({ buses: ['sfx', 'ui'] });
+ *   await audio.init(new AudioContext());
+ *   await audio.defineSounds({ laser: { src: ['/laser.mp3'], bus: 'sfx' } });
+ *   const h = audio.play('laser', 1, 0, 1);
+ *   audio.stop(h);
+ *   audio.destroy();
+ *
+ * Everything past init() is safe to call before unlock: play() enqueues,
+ * defineSounds() starts fetching, bus volumes accept writes. The unlock
+ * gesture flushes the queue and starts the audible clock.
+ */
+export class LiteAudio {
+    /**
+     * @param {Object} [opts]
+     * @param {string[]} [opts.buses=['sfx','ui','voice']] - Bus names. 'master' is implicit.
+     * @param {number} [opts.poolCapacity=32] - Voices per bus pool.
+     * @param {number} [opts.queueLimit=32] - Bound on pre-unlock play queue.
+     * @param {string} [opts.mutedStorageKey='lite_audio_muted'] - localStorage key.
+     * @param {Function} [opts.fetch] - Injectable for tests. Defaults to globalThis.fetch.
+     * @param {Object} [opts.window] - Injectable for tests. Defaults to globalThis.window.
+     * @param {Object} [opts.document] - Injectable for tests. Defaults to globalThis.document.
+     */
+    constructor(opts = {}) {
+        this._busNames = opts.buses || ['sfx', 'ui', 'voice'];
+        this._poolCapacity = opts.poolCapacity ?? 32;
+        this._queueLimit = opts.queueLimit ?? DEFAULT_QUEUE_LIMIT;
+        this._mutedKey = opts.mutedStorageKey ?? MUTED_STORAGE_KEY;
+        this._fetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+        this._window = opts.window ?? (typeof window !== 'undefined' ? window : null);
+        this._document = opts.document ?? (typeof document !== 'undefined' ? document : null);
+
+        // Read persisted mute BEFORE constructing the master signal so the
+        // very first emitted value already carries the user's preference.
+        const initialMuted = readStorage(this._mutedKey, 'false') === 'true';
+
+        // Public signals (readable via getter methods). Callable getters +
+        // .set/.peek; effects can depend on these directly.
+        this._sMuted = signal(initialMuted);
+        this._sUnlocked = signal(false);
+        this._sCtxState = signal('suspended');
+
+        // Per-bus state, populated in init(). Each entry:
+        //   { index, gain, volume:signal, muted:signal, pool, effectHandle }
+        this._buses = new Map();
+
+        // Index -> bus record, so a handle's bus tag resolves in O(1).
+        this._busList = [];
+
+        // Per-sound state, populated by defineSounds():
+        //   { srcs:[], busName, buffer, spriteId, loadState:signal, volume, pitchVar }
+        this._sounds = new Map();
+
+        // Reverse index: bus name -> array of soundIds routed to that bus.
+        // Rebuilt after every defineSounds so pools know their sprite map.
+        this._soundsByBus = new Map();
+
+        // Pre-unlock play queue. Map key is soundId (latest-per-sound wins).
+        // Bounded by _queueLimit.
+        this._pendingPlays = new Map();
+
+        // Effect handles kept so destroy() can dispose them cleanly.
+        this._effectHandles = [];
+
+        // Unlock/lifecycle AbortControllers - same shape as the manager.
+        this._unlockAbort = null;
+        this._lifecycleAbort = null;
+
+        this._ctx = null;
+        this._master = null;
+        this._destroyed = false;
+        this._initialized = false;
+    }
+
+    // ---------- Lifecycle --------------------------------------------------
+
+    /**
+     * Wire the engine to an AudioContext. Idempotent per-instance; a second
+     * call with a different context throws (destroy first). If no context is
+     * passed, one is created from globalThis.AudioContext.
+     *
+     * After init() the master and bus GainNodes exist and their bus->volume
+     * effects are wired. The unlock listeners are attached only if a window
+     * is available (test environments can skip by omitting `window`).
+     */
+    async init(ctx) {
+        if (this._destroyed) throw new Error('LiteAudio: destroyed');
+        if (this._initialized) {
+            if (ctx && ctx !== this._ctx) throw new Error('LiteAudio: already bound to a different context');
+            return;
+        }
+
+        this._ctx = ctx || new (globalThis.AudioContext || globalThis.webkitAudioContext)();
+        this._sCtxState.set(this._ctx.state);
+        if (this._ctx.state === 'running') this._sUnlocked.set(true);
+
+        // Master GainNode is the top of the bus tree; user buses feed into it,
+        // and the master's own gain reflects the master mute signal.
+        this._master = this._ctx.createGain();
+        this._master.connect(this._ctx.destination);
+
+        // Master mute effect: writes to master gain via setTargetAtTime for
+        // click-free transitions. Also persists to storage on write.
+        const masterEffect = effect(() => {
+            const muted = this._sMuted();
+            const target = muted ? 0 : 1;
+            const t = this._ctx.currentTime;
+            this._master.gain.setTargetAtTime(target, t, RAMP_TC);
+            writeStorage(this._mutedKey, muted);
+        });
+        this._effectHandles.push(masterEffect);
+
+        // Build each user bus: GainNode -> master, plus a per-bus volume+muted
+        // effect that writes to gain via setTargetAtTime.
+        for (const name of this._busNames) {
+            if (name === 'master') continue;    // reserved name; use master directly
+            const gain = this._ctx.createGain();
+            gain.connect(this._master);
+            const sVol = signal(1);
+            const sMut = signal(false);
+            const busEffect = effect(() => {
+                const v = sVol();
+                const m = sMut();
+                const target = m ? 0 : v;
+                gain.gain.setTargetAtTime(target, this._ctx.currentTime, RAMP_TC);
+            });
+            this._effectHandles.push(busEffect);
+            const busRec = {
+                index: this._busList.length,
+                gain, volume: sVol, muted: sMut, effect: busEffect, pool: null,
+            };
+            this._buses.set(name, busRec);
+            this._busList.push(busRec);
+        }
+
+        // Ctx state effect: mirror external state changes into our signal so
+        // downstream effects (auto-suspend, HUD, etc.) can react.
+        if (typeof this._ctx.addEventListener === 'function') {
+            const onStatechange = () => this._sCtxState.set(this._ctx.state);
+            this._ctx.addEventListener('statechange', onStatechange);
+            this._statechangeHandler = onStatechange;
+        }
+
+        // Wire unlock and visibility handlers, if we have a DOM.
+        if (this._window) this._setupUnlock();
+        if (this._document) this._setupVisibilityResume();
+
+        this._initialized = true;
+    }
+
+    /**
+     * Attach unlock listeners at capture phase (D3, verbatim port from the
+     * manager's semantics). The first qualifying gesture fires a silent buffer
+     * pulse, calls ctx.resume(), sets the unlocked signal, and flushes any
+     * play() calls the caller queued while locked.
+     */
+    _setupUnlock() {
+        this._unlockAbort = new AbortController();
+
+        const unlock = async () => {
+            if (this._sUnlocked.peek()) return;
+            const ctx = this._ctx;
+            if (!ctx) return;
+
+            if (ctx.state === 'suspended' || ctx.state === 'interrupted') {
+                // Silent buffer pulse: forces the hardware pipeline open on
+                // iOS Safari, which otherwise treats a resume() alone as a
+                // no-op the first time.
+                try {
+                    const buf = ctx.createBuffer(1, 1, 22050);
+                    const src = ctx.createBufferSource();
+                    src.buffer = buf;
+                    src.connect(ctx.destination);
+                    src.start(0);
+                } catch { /* some mock contexts may not implement createBuffer fully */ }
+
+                try {
+                    await ctx.resume();
+                } catch { /* resume rejected - keep trying on next gesture */ return; }
+            }
+            // Post-resume: if we made it here without an error, unlock succeeded.
+            batch(() => {
+                this._sUnlocked.set(true);
+                this._sCtxState.set(ctx.state);
+            });
+            this._unlockAbort.abort();
+            this._flushQueue();
+        };
+
+        for (const evt of UNLOCK_EVENTS) {
+            this._window.addEventListener(evt, unlock, {
+                capture: true,
+                signal: this._unlockAbort.signal,
+            });
+        }
+    }
+
+    _setupVisibilityResume() {
+        this._lifecycleAbort = new AbortController();
+        this._document.addEventListener('visibilitychange', () => {
+            if (!this._document.hidden && this._ctx?.state === 'suspended') {
+                this._ctx.resume().catch(() => {});
+            }
+        }, { signal: this._lifecycleAbort.signal });
+    }
+
+    // ---------- Loader -----------------------------------------------------
+
+    /**
+     * Fetch and decode a set of sounds. Sound configs have shape:
+     *   { src: [url, ...], bus?: string, volume?: number, pitchVar?: number }
+     *
+     * Returns a promise that resolves when every sound has settled (loaded or
+     * errored). Load state per sound is tracked in a signal readable via
+     * loadState(soundId).
+     *
+     * Pools are built (or rebuilt) after all sounds in this batch settle, so
+     * a bus's sprite map covers everything currently loaded for it.
+     */
+    async defineSounds(config) {
+        if (this._destroyed) throw new Error('LiteAudio: destroyed');
+        if (!this._initialized) throw new Error('LiteAudio: init() before defineSounds()');
+        if (!config) return;
+
+        const busesTouched = new Set();
+        const loadPromises = [];
+
+        for (const [soundId, cfg] of Object.entries(config)) {
+            if (this._sounds.has(soundId)) continue;                // idempotent
+
+            const busName = cfg.bus || 'sfx';
+            if (!this._buses.has(busName)) {
+                throw new Error(`LiteAudio: sound "${soundId}" routed to unknown bus "${busName}"`);
+            }
+
+            const sState = signal('idle');
+            const record = {
+                soundId,
+                srcs: cfg.src || [],
+                busName,
+                volume: cfg.volume ?? 1,
+                pitchVar: cfg.pitchVar ?? 0,
+                buffer: null,
+                loadState: sState,
+            };
+            this._sounds.set(soundId, record);
+            busesTouched.add(busName);
+
+            loadPromises.push(this._loadOne(record));
+        }
+
+        await Promise.all(loadPromises);
+
+        // Rebuild sound-by-bus reverse index for the buses we touched.
+        for (const busName of busesTouched) {
+            const ids = [];
+            for (const [id, rec] of this._sounds) {
+                if (rec.busName === busName && rec.loadState.peek() === 'ready') ids.push(id);
+            }
+            this._soundsByBus.set(busName, ids);
+        }
+
+        // Build/rebuild the pool for each touched bus. Rebuilding tears down
+        // the previous pool cleanly (its destroy() disconnects nodes), which
+        // is why the pool's destroy() had to be fixed to actually disconnect
+        // - see lite-audio-pool CHANGELOG 1.1.0.
+        for (const busName of busesTouched) {
+            const busRec = this._buses.get(busName);
+            if (busRec.pool) { busRec.pool.destroy(); busRec.pool = null; }
+
+            const ids = this._soundsByBus.get(busName) || [];
+            if (ids.length === 0) continue;                          // nothing loaded
+
+            const spriteMap = {};
+            for (const id of ids) {
+                const rec = this._sounds.get(id);
+                spriteMap[id] = { start: 0, duration: rec.buffer.duration };
+            }
+            // Pool's default buffer is a dummy - every play passes an explicit
+            // per-play buffer, which is why we asked the pool to grow that arg
+            // in v1.1.0. spriteMap only needs to name what CAN be played.
+            const dummyBuffer = ids.length > 0 ? this._sounds.get(ids[0]).buffer : null;
+            busRec.pool = new AudioPool(
+                this._ctx, dummyBuffer, spriteMap, this._poolCapacity, busRec.gain
+            );
+        }
+
+        // Flush the queue in case sounds arrived after the user gesture:
+        // plays that were queued because the sound was still loading can now
+        // fire. flushQueue is a no-op if unlock is not yet in.
+        this._flushQueue();
+    }
+
+    async _loadOne(record) {
+        const url = pickSupportedSrc(record.srcs);
+        if (!url) { record.loadState.set('error'); return; }
+        if (!this._fetch) { record.loadState.set('error'); return; }
+
+        record.loadState.set('loading');
+        try {
+            const resp = await this._fetch(url);
+            if (!resp || !resp.ok) throw new Error(`fetch failed: ${resp?.status ?? '?'}`);
+            const bytes = await resp.arrayBuffer();
+            const buf = await this._ctx.decodeAudioData(bytes);
+            record.buffer = buf;
+            record.loadState.set('ready');
+        } catch {
+            record.loadState.set('error');
+        }
+    }
+
+    // ---------- Playback ---------------------------------------------------
+
+    /**
+     * Positional hot path (D5). Returns the pool's generation-stamped handle,
+     * or -1 on any skip (unknown sound, not-ready sound, context locked).
+     * When locked, the call is enqueued (bounded, latest-per-sound) instead
+     * of dropped - the queue is flushed on unlock.
+     */
+    play(soundId, volume = 1, pan = 0, pitch = 1) {
+        if (this._destroyed) return -1;
+        const rec = this._sounds.get(soundId);
+        if (!rec) return -1;
+
+        // If not unlocked yet, queue the intent and return -1. The caller can
+        // observe unlocked() and re-decide, but a good game just fires - the
+        // queue turns pre-gesture plays into post-gesture plays automatically.
+        if (!this._sUnlocked.peek() || rec.loadState.peek() !== 'ready') {
+            this._enqueue(soundId, volume, pan, pitch);
+            return -1;
+        }
+
+        const busRec = this._buses.get(rec.busName);
+        if (!busRec || !busRec.pool) return -1;
+
+        // Per-play buffer override (pool v1.1.0): the pool is constructed
+        // with a dummy default buffer; we always pass the sound's own buffer.
+        const poolHandle = busRec.pool.play(soundId, volume, pan, pitch, rec.buffer);
+        if (poolHandle < 0) return -1;
+        return busRec.index * BUS_STRIDE + poolHandle;
+    }
+
+    /**
+     * Sugar over play(): options object + pitchVar resolution. Not the hot
+     * path - a frame loop should call the positional play() directly.
+     */
+    playOpts(soundId, opts = {}) {
+        const rec = this._sounds.get(soundId);
+        const vol = opts.volume ?? rec?.volume ?? 1;
+        const pan = opts.pan ?? 0;
+        let pitch = opts.pitch ?? 1;
+        const pv = opts.pitchVar ?? rec?.pitchVar ?? 0;
+        if (opts.pitch == null && pv > 0) {
+            pitch = 1 + (Math.random() * 2 - 1) * pv;
+        }
+        return this.play(soundId, vol, pan, pitch);
+    }
+
+    /**
+     * Stop a specific play by its pool handle. Because pool handles are
+     * generation-stamped, a stale handle from a stolen voice is a silent
+     * no-op - the guarantee we shipped in pool v1.1.0.
+     * @param {number} handle
+     */
+    stop(handle) {
+        if (this._destroyed || handle < 0) return;
+        const busRec = this._busList[(handle / BUS_STRIDE) | 0];
+        if (!busRec || !busRec.pool) return;
+        busRec.pool.stop(handle >>> 0);
+    }
+
+    /**
+     * Is this exact voice still sounding? False once its channel was stolen,
+     * stopped, or played out - and false for a handle the named bus never issued.
+     * @param {number} handle
+     * @returns {boolean}
+     */
+    isPlaying(handle) {
+        if (this._destroyed || handle < 0) return false;
+        const busRec = this._busList[(handle / BUS_STRIDE) | 0];
+        if (!busRec || !busRec.pool) return false;
+        return busRec.pool.isPlaying(handle >>> 0);
+    }
+
+    /**
+     * Which bus issued this handle, or null. Useful for HUDs and for asserting in
+     * tests that a voice landed where its sound was routed.
+     * @param {number} handle
+     * @returns {string|null}
+     */
+    busOf(handle) {
+        if (handle < 0) return null;
+        const index = (handle / BUS_STRIDE) | 0;
+        for (const [name, busRec] of this._buses) {
+            if (busRec.index === index) return name;
+        }
+        return null;
+    }
+
+    /**
+     * Voices currently sounding on a bus, or across every bus when called with no
+     * argument. Allocation-free; safe to call every frame.
+     * @param {string} [busName]
+     * @returns {number}
+     */
+    activeCount(busName) {
+        if (this._destroyed) return 0;
+        if (busName !== undefined) {
+            const busRec = this._buses.get(busName);
+            return busRec?.pool ? busRec.pool.activeCount() : 0;
+        }
+        let n = 0;
+        for (let i = 0; i < this._busList.length; i++) {
+            const pool = this._busList[i].pool;
+            if (pool) n += pool.activeCount();
+        }
+        return n;
+    }
+
+    /** Stop every voice on a named bus. */
+    stopBus(busName) {
+        if (this._destroyed) return;
+        const busRec = this._buses.get(busName);
+        if (busRec?.pool) busRec.pool.stopAll();
+    }
+
+    /** Stop every voice across every bus. */
+    stopAll() {
+        if (this._destroyed) return;
+        for (const [, busRec] of this._buses) {
+            if (busRec.pool) busRec.pool.stopAll();
+        }
+    }
+
+    // ---------- Bus controls -----------------------------------------------
+
+    setBusVolume(busName, volume) {
+        const busRec = this._buses.get(busName);
+        if (busRec) busRec.volume.set(volume);
+    }
+
+    setBusMuted(busName, muted) {
+        const busRec = this._buses.get(busName);
+        if (busRec) busRec.muted.set(!!muted);
+    }
+
+    setMuted(state) { this._sMuted.set(!!state); }
+
+    // ---------- Signal getters ---------------------------------------------
+
+    /** Reactive readable: current context state ('suspended'|'running'|...). */
+    ctxState() { return this._sCtxState; }
+
+    /** Reactive readable: whether the context has been unlocked. */
+    unlocked() { return this._sUnlocked; }
+
+    /** Reactive readable: master mute state. */
+    muted() { return this._sMuted; }
+
+    /** Reactive readable: load state for a specific sound. */
+    loadState(soundId) { return this._sounds.get(soundId)?.loadState; }
+
+    /** Reactive readable: bus volume signal. */
+    busVolume(busName) { return this._buses.get(busName)?.volume; }
+
+    /** Reactive readable: bus mute signal. */
+    busMuted(busName) { return this._buses.get(busName)?.muted; }
+
+    /** Direct access to a bus's GainNode for effect insertion (advanced). */
+    busNode(busName) { return this._buses.get(busName)?.gain; }
+
+    /** Direct access to the master GainNode (advanced). */
+    masterNode() { return this._master; }
+
+    // ---------- Unlock queue -----------------------------------------------
+
+    _enqueue(soundId, volume, pan, pitch) {
+        // Latest-per-sound: if the same sound was already queued, overwrite
+        // the intent. Bounded: if we would exceed queueLimit with a NEW key,
+        // silently drop the newcomer - the game can rebuild it on unlock,
+        // and this is a paper-cut fallback, not the happy path.
+        if (this._pendingPlays.has(soundId)) {
+            this._pendingPlays.set(soundId, [soundId, volume, pan, pitch]);
+            return;
+        }
+        if (this._pendingPlays.size >= this._queueLimit) return;
+        this._pendingPlays.set(soundId, [soundId, volume, pan, pitch]);
+    }
+
+    _flushQueue() {
+        if (!this._sUnlocked.peek()) return;
+        if (this._pendingPlays.size === 0) return;
+
+        // Snapshot - play() may re-queue if a sound is still not ready.
+        const items = [...this._pendingPlays.values()];
+        this._pendingPlays.clear();
+        for (const [id, v, p, pi] of items) {
+            const rec = this._sounds.get(id);
+            if (!rec) continue;
+            if (rec.loadState.peek() !== 'ready') {
+                // Sound not ready yet: put it back for the next flush.
+                this._enqueue(id, v, p, pi);
+                continue;
+            }
+            this.play(id, v, p, pi);
+        }
+    }
+
+    // ---------- Teardown ---------------------------------------------------
+
+    /**
+     * Stop everything, tear down the audio graph, remove listeners, dispose
+     * effects, and release references. Idempotent - a second destroy() is
+     * safe. The AudioContext itself is not closed (the app owns it).
+     */
+    destroy() {
+        if (this._destroyed) return;
+        this._destroyed = true;
+
+        this._unlockAbort?.abort();
+        this._lifecycleAbort?.abort();
+
+        if (this._statechangeHandler && this._ctx?.removeEventListener) {
+            this._ctx.removeEventListener('statechange', this._statechangeHandler);
+        }
+
+        // stopAll first so voice fade-outs schedule against a still-live graph.
+        for (const [, busRec] of this._buses) {
+            if (busRec.pool) { try { busRec.pool.destroy(); } catch {} busRec.pool = null; }
+        }
+
+        for (const h of this._effectHandles) {
+            try { dispose(h); } catch {}
+        }
+        this._effectHandles.length = 0;
+
+        // Disconnect bus and master gains.
+        for (const [, busRec] of this._buses) {
+            try { busRec.gain.disconnect(); } catch {}
+        }
+        try { this._master?.disconnect(); } catch {}
+
+        this._buses.clear();
+        this._busList.length = 0;
+        this._sounds.clear();
+        this._soundsByBus.clear();
+        this._pendingPlays.clear();
+        this._master = null;
+        this._ctx = null;
+    }
+}
+
+export default LiteAudio;

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 1.0.0
+
+Initial release. Ships the SFX layer of the lite-audio stack: signal-driven
+buses over one `AudioPool` per bus, iOS/mobile unlock ported verbatim from
+`lite-audio-manager`, plus a bounded pre-unlock play queue.
+
+### Included (roadmap D1 / D3 / D4 / D5 / D6 / D7 / D8)
+
+- **Signal-driven control surface (D1).** Bus volumes, mutes, master mute,
+  context state, per-sound load state are all `lite-signal` signals. Each bus
+  gets one `effect()` that writes the effective target
+  (`muted ? 0 : volume`) through `setTargetAtTime(target, currentTime, 0.01)`
+  — click-free by construction, no manual ramp code in userland.
+- **Unlock ported verbatim (D3).** Silent-buffer pulse + `ctx.resume()` on the
+  first `touchstart` / `touchend` / `mousedown` / `keydown`, capture-phase,
+  behind an `AbortController` — same event set and same attach shape as the
+  manager. Handles `'interrupted'` state (iOS phone-call scenario) as
+  equivalent to `'suspended'`. Added: `ctxState()` and `unlocked()` as signals
+  the rest of the app can subscribe to.
+- **Bounded pre-unlock play queue (D3 extension).** `play()` before unlock
+  returns `-1` and enqueues the intent. Same-sound repeats collapse to
+  latest-per-sound; new distinct sounds past `queueLimit` are silently dropped.
+  Flushed on unlock. The manager's silent-drop behavior was the #1 mobile-game
+  paper cut Howler could not fix from the outside; lite-audio fixes it from
+  the inside.
+- **Reactive loader (D4).** `defineSounds(config)` fetches + decodes each
+  sound; a `loadState(id)` signal per sound transitions
+  `'idle' -> 'loading' -> 'ready' | 'error'` observably. Format fallback via
+  `canPlayType` probe over the `src` array. Fetch is injectable for tests.
+- **Positional hot path (D5).** `play(soundId, volume, pan, pitch)` — no
+  options object per call. `playOpts(id, {...})` sugar layer above handles
+  `pitchVar` random-pitch resolution.
+- **Bus-tagged voice handles (D5/D6).** `play()` returns
+  `busIndex * 2^32 + poolHandle`. The tag is not decoration: every bus runs its
+  own `AudioPool`, and every pool counts channels and generations from zero, so
+  the first play on *each* bus returns the identical raw handle
+  (`0x00000000` - channel 0, generation 0). A handle alone cannot say which bus
+  issued it, and the pool's generation check cannot help, because it is a
+  recycle counter, not a namespace. With the tag, `stop()` resolves the owning
+  pool in O(1) and cannot reach across a bus boundary. Handles stay plain
+  numbers, exact well inside 2^53, opaque to callers.
+- **Fades delegated to pool (D6).** `stop(handle)` routes to the handle's own
+  bus; the generation check inside that pool means a stale handle after a steal
+  is a silent no-op, never a wrong-voice hit.
+- **`isPlaying(handle)`, `busOf(handle)`, `activeCount(busName?)`.** Liveness of
+  one voice, the bus that issued a handle, and the live voice count per bus or
+  engine-wide. Allocation-free; `activeCount()` is safe to call every frame.
+- **Master mute persistence (D7).** localStorage key `'lite_audio_muted'` -
+  byte-identical to `lite-audio-manager` so a game migrating between the two
+  keeps the player's saved preference intact.
+- **Mock-ctx test harness (D8).** `test/mock-ctx.js` records every
+  `AudioParam` scheduled event into an `.events` array, runs a real state
+  machine covering all four `AudioContextState` values, and mocks
+  `decodeAudioData` + `fetch` with length-hint payloads so different mock
+  URLs decode to different-sized buffers deterministically. Foundation for
+  every later lite-audio session.
+
+### Deliberately deferred (roadmap D10)
+
+- **Music streaming layer.** `MediaElementAudioSourceNode`, crossfades,
+  reactive `position()` / `duration()`, `playExclusive` / `playUnique` -
+  ships in **v1.1.0** (roadmap session A2).
+- **Ducking, mix snapshots, per-bus meters, auto-suspend.** Ships in
+  **v1.2.0** (roadmap session A3).
+- **`./compat` shim.** `AudioManager`-shaped adapter over `LiteAudio` for
+  drop-in migration, plus full parity certification. Ships in **v2.0.0**
+  (roadmap session A4).
+- **3D spatial (PannerNode/HRTF), AudioWorklet custom DSP, convolution
+  reverb.** Post-2.0.
+
+### Demo
+
+- New `demo/index.html`: single-file, four scenes, no asset folder - every sound
+  is synthesized in an `OfflineAudioContext`, encoded to WAV, and served to the
+  engine as a `blob:` URL, so the real fetch + decode path runs.
+  **unlock** - the context lifecycle as an SVG state machine driven by
+  `ctxState()`, plus the pre-unlock queue: fire plays while locked and watch
+  latest-per-sound collapse and the `queueLimit` drop, then dispatch the gesture
+  and hear the flush. The engine takes a *fake window* through `opts.window`, so
+  the demo owns the gesture instead of racing it - the one-shot feature becomes
+  replayable. **loader** - `loadState()` per sound, with one asset behind 2.6s of
+  injected fetch latency and one pointed at a 404, so `loading` and `error` are
+  states you can actually watch. **mixer** - bus faders and mutes as signals,
+  with a gain scope plotting the real `GainNode.value` against the signal target:
+  the 10ms `setTargetAtTime` bend is the click you do not hear. **voices** - the
+  per-bus pools, and the twin-handle trap: two buses hand back the same raw
+  handle, and only the bus tag keeps `stop()` from killing both.
+
+### Test coverage
+
+38 tests across 10 suites, all green. Gate items from the roadmap:
+
+- Unlock state machine including `'interrupted'` — 6 tests
+- Loader fallback + error - 5 tests
+- Bus effect writes as `setTargetAtTime` on the mock ctx - 4 tests
+- Steal + declick schedule shape (delegated) - 1 test
+- Generation no-op on stale handles (delegated) - covered in 2 playback tests
+- Unlock queue flush (latest-per-sound, bounded) - 3 tests
+- Zero-GC hot path shape - 1 test
+- Master mute persistence — 3 tests
+- Playback delegation to pool — 6 tests
+- destroy() idempotency + listener detachment - 3 tests
+
+- Handle namespace across buses - 6 tests (`test/BusHandles.test.js`)
+
+### Peer dependency pins
+
+- `@zakkster/lite-signal` `^1.3.0`
+- `@zakkster/lite-audio-pool` `^1.1.0`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @zakkster/lite-audio
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-audio.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-audio)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-audio?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-audio)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-audio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-audio)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-audio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-audio)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+
+
+Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles,
+unlock queue, one `AudioPool` per bus. The SFX layer of a growing audio stack
+that eventually deprecates the Howler wrapper it replaces.
+
+- Zero deps of its own; two peers: `@zakkster/lite-signal` and
+  `@zakkster/lite-audio-pool`
+- ~7.5 KB minified, ~2.7 KB gzipped
+- No Howler, no HTML5 Audio fallback, no MP3 decoder shim — just the Web Audio
+  API surface the modern web has had since 2018, wired precisely
+- Ports the iOS/mobile unlock semantics of `lite-audio-manager` verbatim, plus a
+  bounded pre-unlock play queue the manager could not offer from Howler's outside
+
+**Status:** v1.0.0 covers SFX. The music streaming layer
+(`MediaElementAudioSourceNode`, crossfades, exclusive/unique) is the v1.1.0
+milestone; ducking, snapshots, and auto-suspend are v1.2.0; a Howler-shim
+compat subpath and full parity certification against `lite-audio-manager` are
+v2.0.0.
+
+## Install
+
+```bash
+npm i @zakkster/lite-audio @zakkster/lite-signal @zakkster/lite-audio-pool
+```
+
+## Quick start
+
+```js
+import { LiteAudio } from '@zakkster/lite-audio';
+
+const audio = new LiteAudio({ buses: ['sfx', 'ui', 'voice'] });
+await audio.init();                       // creates an AudioContext internally
+
+await audio.defineSounds({
+    laser: { src: ['/laser.opus', '/laser.mp3'], bus: 'sfx' },
+    hit:   { src: ['/hit.wav'],                  bus: 'sfx', pitchVar: 0.15 },
+    click: { src: ['/click.mp3'],                bus: 'ui' },
+});
+
+// Fires immediately when unlocked; queued (bounded, latest-per-sound) and
+// flushed on the first touchstart / mousedown / keydown otherwise. No polling,
+// no "waiting for unlock" ceremony in the caller.
+const handle = audio.play('laser', 0.8, 0.0, 1.0);
+audio.stop(handle);
+
+// Reactive state - subscribe with lite-signal's effect() for UI hookup.
+audio.unlocked();                         // ReadSignal<boolean>
+audio.loadState('laser');                 // ReadSignal<'idle'|'loading'|'ready'|'error'>
+audio.busVolume('sfx');                   // ReadSignal<number>
+
+audio.setBusVolume('sfx', 0.5);           // schedules setTargetAtTime, click-free
+audio.setMuted(true);                     // master mute, persists to localStorage
+
+audio.destroy();                          // idempotent, disconnects the graph
+```
+
+## Why not Howler?
+
+Howler.js is a good general-purpose audio library. It handles decoding, HTML5
+Audio fallback for browsers that predate reliable Web Audio, format detection
+across MP3/OGG/WAV/M4A, streaming, spatial audio, and a lot more. If you are
+shipping cross-platform audio to a broad web audience without wanting to think
+about any of that, use Howler.
+
+lite-audio deliberately does not do most of those things. It targets the narrow
+slice where the ecosystem has moved on:
+
+- **Web Audio is universal.** Every browser we care about (2018+) has decode +
+  scheduling. HTML5 Audio fallback is dead weight for a modern game.
+- **Signals over events.** Continuous state — bus volumes, mute, load status,
+  context state — belongs in a reactive graph, not a bag of event listeners.
+  `effect(() => busGain.setTargetAtTime(...))` is one line; the equivalent
+  Howler pattern is a handful of `on('volumechange')` handlers plus manual
+  ramps.
+- **Handles that survive stealing.** Voice-stealing is the norm in games. The
+  underlying `AudioPool` returns generation-stamped handles; a `stop(handle)`
+  after the channel has been stolen is a silent no-op instead of a wrong-voice
+  hit. Howler has no direct equivalent — `Howl.stop(id)` on an id that has
+  been reused is a real bug we ran into.
+- **Zero-GC hot path.** No per-play closure, no options-object allocation on
+  the positional `play(id, vol, pan, pitch)` path. The pool underneath has
+  been benchmarked to ~14M plays/sec with ~0 B retained per play.
+
+lite-audio is ~7.5 KB minified against Howler's ~35 KB. That size difference is
+real budget you get back for shaders, netcode, or another 100 sounds.
+
+## Architecture in one paragraph
+
+**Signals are the control surface; AudioParams are the sink.** Continuous state
+(bus volumes, mute, per-sound load state, ctx state) lives in `lite-signal`
+signals. One `effect()` per bus writes the effective target through
+`setTargetAtTime(target, ctx.currentTime, 0.01)` — click-free by construction.
+One-shot triggers (`play`) stay imperative — a sound firing is an event, not
+state. Voices come from a per-bus `AudioPool`, addressed by
+bus-tagged handles (`busIndex * 2^32 | (gen << 8) | channel`); a stale
+`stop(handle)` after a steal is a silent no-op. Unlock is ported from
+`lite-audio-manager` verbatim (silent-buffer pulse + `resume()` + capture-phase
+listeners behind an `AbortController`), plus a bounded pre-unlock play queue
+so a call fired before the first user gesture does not vanish.
+
+## Signal readouts (the whole reactive surface)
+
+| Signal | Read via | Notes |
+| --- | --- | --- |
+| Context state | `audio.ctxState()` | `'suspended' \| 'running' \| 'interrupted' \| 'closed'` |
+| Unlock status | `audio.unlocked()` | `true` once the first gesture succeeded |
+| Master mute | `audio.muted()` | Persisted to `localStorage['lite_audio_muted']` |
+| Bus volume | `audio.busVolume(name)` | 0..1 (or higher; not clamped) |
+| Bus mute | `audio.busMuted(name)` | Independent of master mute |
+| Load state | `audio.loadState(id)` | `'idle' \| 'loading' \| 'ready' \| 'error'` |
+
+All readable via `signal()` (calling), `signal.peek()` (untracked read), or
+inside a `computed()` / `effect()`.
+
+## Options reference
+
+```js
+new LiteAudio({
+    buses:            ['sfx', 'ui', 'voice'],   // user-facing buses
+    poolCapacity:     32,                        // voices per bus pool
+    queueLimit:       32,                        // bound on pre-unlock queue
+    mutedStorageKey:  'lite_audio_muted',        // manager parity default
+    fetch:            globalThis.fetch,          // injectable for tests
+    window:           globalThis.window,         // ditto
+    document:         globalThis.document,       // ditto
+});
+```
+
+## Migration from lite-audio-manager
+
+The persistence key (`lite_audio_muted`), unlock event set (`touchstart`,
+`touchend`, `mousedown`, `keydown`), capture-phase attachment, and silent-buffer
+unlock pulse are byte-identical to the manager. A migration should keep the
+player's saved mute preference intact on first launch.
+
+A `./compat` subpath re-exporting an `AudioManager`-shaped adapter over
+`LiteAudio` is planned for **v2.0.0**; the migration guide will be the release
+notes for that.
+
+## Testing
+
+```bash
+npm test
+```
+
+32 tests across 9 suites, covering unlock state machine (including
+`'interrupted'`), loader fallback + error, bus signal writes as
+`setTargetAtTime` on a mock AudioContext, pool delegation (steal, generation
+no-op on stale handles, stopBus scope), unlock queue flush semantics
+(latest-per-sound, bounded), and destroy idempotency + listener detachment.
+
+The mock harness (`test/mock-ctx.js`) records every `AudioParam` scheduled
+event into an inspectable `.events` array, runs a real context state machine
+(all four states — `suspended`, `running`, `interrupted`, `closed`), and
+mocks `fetch` + `decodeAudioData` with length-hint payloads so tests can
+distinguish sounds deterministically. This harness is the D8 foundation the
+next roadmap sessions will reuse for the music layer, ducking, and parity
+certification.
+
+## License
+
+MIT. Copyright Zahary Shinikchiev.

package/llms.txt

@@ -0,0 +1,106 @@
+# @zakkster/lite-audio
+> Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles, unlock queue, per-bus AudioPool. SFX layer over @zakkster/lite-audio-pool.
+
+## Install
+npm i @zakkster/lite-audio @zakkster/lite-signal @zakkster/lite-audio-pool
+
+## Import
+import { LiteAudio } from '@zakkster/lite-audio';
+
+## Key Facts
+- Zero deps of its own; two peers: @zakkster/lite-signal (^1.3), @zakkster/lite-audio-pool (^1.1)
+- Signal-driven control surface: bus volumes, master mute, ctx state, per-sound load state are all reactive
+- Bus writes go through setTargetAtTime for click-free transitions (10 ms time constant)
+- Pre-unlock play() calls are queued (bounded, latest-per-sound), flushed on first user gesture
+- iOS/Safari unlock: silent-buffer pulse + resume() on touchstart/touchend/mousedown/keydown (capture phase, exact set the manager uses)
+- Handles 'interrupted' state (iOS phone-call scenario) the same as 'suspended'
+- Master mute persists to localStorage under 'lite_audio_muted' (byte-identical to lite-audio-manager for migration)
+- One AudioPool per bus (pool v1.1.0+ output param + per-play buffer override)
+- Positional hot path: play(soundId, volume, pan, pitch) - no options object per call
+- Handles are bus-tagged: busIndex * 2^32 + poolHandle. Pool handles collide across buses (every pool starts at channel 0 / generation 0), so the tag is what makes stop() name one voice
+- v1.0.0 covers SFX only; music streaming layer (MediaElementAudioSourceNode) lands in v1.1.0
+
+## Quick Start
+```js
+import { LiteAudio } from '@zakkster/lite-audio';
+
+const audio = new LiteAudio({ buses: ['sfx', 'ui', 'voice'] });
+await audio.init();                       // creates AudioContext
+await audio.defineSounds({
+    laser: { src: ['/laser.opus', '/laser.mp3'], bus: 'sfx' },
+    hit:   { src: ['/hit.wav'], bus: 'sfx', pitchVar: 0.15 },
+    click: { src: ['/click.mp3'], bus: 'ui' },
+});
+
+// Fires immediately if unlocked; queued and flushed on first gesture otherwise.
+const h = audio.play('laser', 0.8, 0.0, 1.0);
+audio.stop(h);
+audio.isPlaying(h);                       // false once stolen, stopped, or played out
+
+// Reactive readouts
+audio.unlocked();                         // ReadSignal<boolean>
+audio.ctxState();                         // ReadSignal<'suspended'|'running'|'interrupted'|'closed'>
+audio.loadState('laser');                 // ReadSignal<'idle'|'loading'|'ready'|'error'>
+audio.busVolume('sfx');                   // ReadSignal<number>
+
+// Writes
+audio.setBusVolume('sfx', 0.5);
+audio.setBusMuted('ui', true);
+audio.setMuted(true);                     // master, persists to localStorage
+
+audio.destroy();                          // idempotent
+```
+
+## Export: LiteAudio (class)
+
+### Constructor
+```
+new LiteAudio(opts?)
+```
+- `opts.buses?: string[]` - defaults ['sfx', 'ui', 'voice']. 'master' is implicit.
+- `opts.poolCapacity?: number` - defaults 32.
+- `opts.queueLimit?: number` - defaults 32.
+- `opts.mutedStorageKey?: string` - defaults 'lite_audio_muted'.
+- `opts.fetch?, opts.window?, opts.document?` - test injectables.
+
+### async init(ctx?): Promise<void>
+Wires the engine to an AudioContext. Creates one via globalThis.AudioContext if none passed. Sets up master gain, bus gains, master-mute effect, per-bus volume+mute effects, statechange listener, unlock listeners.
+
+### async defineSounds(config): Promise<void>
+Fetches and decodes every sound in the config. Config shape:
+```
+{ [soundId]: { src: string[], bus?: string, volume?: number, pitchVar?: number } }
+```
+Resolves after every sound has settled. Load state per sound is a reactive signal readable via loadState(soundId). Pools are built (or rebuilt) once per touched bus at the end.
+
+### play(soundId, volume?, pan?, pitch?): number
+Positional hot path. Returns a handle >= 0 on success, -1 on any skip (unknown sound, not-yet-ready sound, context locked). Locked plays are queued (latest-per-sound, bounded by queueLimit) and flushed on unlock.
+
+### playOpts(soundId, opts?): number
+Sugar over play() with pitchVar resolution: `pitch = 1 + (rand*2-1)*pitchVar`.
+
+### stop(handle): void
+Stops a specific play. Stale handles (channel stolen or already ended) are silent no-ops. The handle carries its bus, so stop() resolves the owning pool in O(1) and can never reach across a bus boundary.
+
+### isPlaying(handle): boolean, busOf(handle): string|null, activeCount(busName?): number
+Liveness of one voice, the bus that issued a handle, and the live voice count per bus or engine-wide.
+
+### stopBus(busName): void, stopAll(): void
+Bus- and engine-wide stops.
+
+### setBusVolume(name, v), setBusMuted(name, m), setMuted(state)
+Signal setters. Every write schedules a setTargetAtTime on the affected GainNode with a 10 ms time constant.
+
+### Reactive readables
+`ctxState() : ReadSignal<CtxState>`
+`unlocked() : ReadSignal<boolean>`
+`muted() : ReadSignal<boolean>`
+`loadState(id) : ReadSignal<LoadState> | undefined`
+`busVolume(name), busMuted(name) : ReadSignal | undefined`
+`busNode(name) : GainNode | undefined`
+`masterNode() : GainNode | null`
+
+### destroy(): void
+Stops every voice, tears down pools (which disconnect their nodes), disposes signal effects, aborts unlock/lifecycle controllers, releases references. Idempotent. Does not close the AudioContext.
+
+See Audio.js source for full inline documentation.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@zakkster/lite-audio",
+  "version": "1.0.0",
+  "description": "Zero-GC reactive Web Audio engine. Signal-driven buses, ABA-safe voice handles, unlock queue. SFX layer over @zakkster/lite-audio-pool.",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./Audio.js",
+  "module": "./Audio.js",
+  "types": "./Audio.d.ts",
+  "exports": {
+    ".": {
+      "types": "./Audio.d.ts",
+      "import": "./Audio.js",
+      "node": "./Audio.js",
+      "default": "./Audio.js"
+    }
+  },
+  "files": [
+    "Audio.js",
+    "Audio.d.ts",
+    "llms.txt",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "audio",
+    "webaudio",
+    "sound",
+    "reactive",
+    "signals",
+    "zero-gc",
+    "game-audio",
+    "sfx",
+    "voice-stealing",
+    "unlock",
+    "ios-unlock"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-audio#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-audio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-audio/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "peerDependencies": {
+    "@zakkster/lite-signal": "^1.3.0",
+    "@zakkster/lite-audio-pool": "^1.1.0"
+  },
+  "devDependencies": {
+    "@zakkster/lite-signal": "^1.3.0",
+    "@zakkster/lite-audio-pool": "^1.1.0"
+  }
+}