@kids-games/core 0.1.0

package/dist/voice/player.js

@@ -0,0 +1,224 @@
+"use client";
+import { PERSONAS } from "./personas";
+/**
+ * AudioPlayer — plays pre-generated .mp3 files from public/audio/.
+ * No runtime API calls. All audio is static files served by the app.
+ */
+export class AudioPlayer {
+    audioElement = null;
+    audioContext = null;
+    muted = false;
+    volume = 1.0;
+    cancelFlag = false;
+    audioBasePath;
+    storagePrefix;
+    unlocked = false;
+    cachedVoices = [];
+    constructor(storagePrefix, audioBasePath) {
+        this.storagePrefix = storagePrefix;
+        this.audioBasePath = audioBasePath;
+        if (typeof window !== "undefined") {
+            this.muted = localStorage.getItem(`${storagePrefix}-muted`) === "true";
+            const savedVolume = localStorage.getItem(`${storagePrefix}-volume`);
+            if (savedVolume)
+                this.volume = parseFloat(savedVolume);
+            // Pre-cache voices for Chrome (fires async) and other browsers
+            if (window.speechSynthesis) {
+                this.cachedVoices = window.speechSynthesis.getVoices();
+                window.speechSynthesis.addEventListener("voiceschanged", () => {
+                    this.cachedVoices = window.speechSynthesis.getVoices();
+                });
+            }
+        }
+    }
+    /** Must be called from a user interaction to unlock audio on mobile browsers */
+    unlock() {
+        if (this.unlocked)
+            return;
+        try {
+            // Create and resume AudioContext to unlock Web Audio
+            const ctx = this.getAudioContext();
+            if (ctx.state === "suspended") {
+                ctx.resume();
+            }
+            // Create a silent audio element to unlock HTMLAudioElement playback
+            const el = this.getAudioElement();
+            el.src = "data:audio/mp3;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAAAAAAAAAAAAAA//tQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWGluZwAAAA8AAAACAAABhgC7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7//////////////////////////////////////////////////////////////////8AAAAATGF2YzU4LjEzAAAAAAAAAAAAAAAAJAAAAAAAAAAAAYYoRwMHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+            el.play().catch(() => { });
+            el.pause();
+            this.unlocked = true;
+        }
+        catch {
+            // Silently fail — will retry on next interaction
+        }
+    }
+    getAudioElement() {
+        if (!this.audioElement) {
+            this.audioElement = new Audio();
+            this.audioElement.preload = "auto";
+        }
+        return this.audioElement;
+    }
+    getAudioContext() {
+        if (!this.audioContext) {
+            this.audioContext = new (window.AudioContext ||
+                window.webkitAudioContext)();
+        }
+        if (this.audioContext.state === "suspended") {
+            this.audioContext.resume();
+        }
+        return this.audioContext;
+    }
+    /** Get the Web Audio context for SFX synthesis */
+    getContext() {
+        return this.getAudioContext();
+    }
+    /**
+     * Play a pre-generated phrase by ID.
+     * Resolves to the audio file at: {audioBasePath}/{personaId}/{phraseId}.mp3
+     */
+    async playPhrase(phraseId, personaId) {
+        if (this.muted)
+            return;
+        this.cancelFlag = false;
+        const url = `${this.audioBasePath}/${personaId}/${phraseId}.mp3`;
+        return this.playAudioFile(url);
+    }
+    /**
+     * Play a sequence of phrases with pauses between them.
+     * Useful for Letter Land's "A... ah... Apple" pattern.
+     */
+    async playSequence(phrases, pauseMs = 400) {
+        this.cancelFlag = false;
+        for (let i = 0; i < phrases.length; i++) {
+            if (this.cancelFlag || this.muted)
+                break;
+            await this.playPhrase(phrases[i].id, phrases[i].persona);
+            if (i < phrases.length - 1 && !this.cancelFlag) {
+                await this.pause(pauseMs);
+            }
+        }
+    }
+    /** Play an audio file by URL */
+    playAudioFile(url) {
+        return new Promise((resolve) => {
+            if (this.muted || typeof window === "undefined") {
+                resolve();
+                return;
+            }
+            const audio = this.getAudioElement();
+            // Cancel any in-progress playback
+            audio.pause();
+            audio.currentTime = 0;
+            audio.src = url;
+            audio.volume = this.volume;
+            const cleanup = () => {
+                audio.removeEventListener("ended", onEnd);
+                audio.removeEventListener("error", onError);
+            };
+            const onEnd = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = () => {
+                cleanup();
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn(`[kids-audio] Failed to play: ${url}`);
+                }
+                resolve();
+            };
+            audio.addEventListener("ended", onEnd);
+            audio.addEventListener("error", onError);
+            audio.play().catch(() => {
+                cleanup();
+                resolve();
+            });
+        });
+    }
+    /** Fallback: speak text using Web Speech API with persona voice settings */
+    async speakDynamic(text, personaId) {
+        if (this.muted || typeof window === "undefined" || !window.speechSynthesis) {
+            return;
+        }
+        const persona = PERSONAS[personaId];
+        return new Promise((resolve) => {
+            window.speechSynthesis.cancel();
+            const utterance = new SpeechSynthesisUtterance(text);
+            utterance.rate = persona.fallback.rate;
+            utterance.pitch = persona.fallback.pitch;
+            utterance.volume = this.volume;
+            // Use cached voices (handles Chrome's async voice loading)
+            const voices = this.cachedVoices.length > 0
+                ? this.cachedVoices
+                : window.speechSynthesis.getVoices();
+            if (persona.fallback.preferFemale) {
+                const preferred = voices.find((v) => v.lang.startsWith("en") && v.name.includes("Female")) ||
+                    voices.find((v) => v.lang.startsWith("en"));
+                if (preferred)
+                    utterance.voice = preferred;
+            }
+            else {
+                const preferred = voices.find((v) => v.lang.startsWith("en"));
+                if (preferred)
+                    utterance.voice = preferred;
+            }
+            utterance.onend = () => resolve();
+            utterance.onerror = () => resolve();
+            window.speechSynthesis.speak(utterance);
+        });
+    }
+    /** Cancel any in-progress audio playback */
+    cancel() {
+        this.cancelFlag = true;
+        // Stop audio element
+        if (this.audioElement) {
+            this.audioElement.pause();
+            this.audioElement.currentTime = 0;
+        }
+        // Stop speech synthesis (for speakDynamic fallback)
+        if (typeof window !== "undefined" && window.speechSynthesis) {
+            window.speechSynthesis.cancel();
+        }
+    }
+    /** Set muted state */
+    setMuted(muted) {
+        this.muted = muted;
+        if (typeof window !== "undefined") {
+            localStorage.setItem(`${this.storagePrefix}-muted`, String(muted));
+        }
+        if (muted) {
+            this.cancel();
+        }
+    }
+    /** Get muted state */
+    isMuted() {
+        return this.muted;
+    }
+    /** Set volume (0.0 to 1.0) */
+    setVolume(vol) {
+        this.volume = Math.max(0, Math.min(1, vol));
+        if (typeof window !== "undefined") {
+            localStorage.setItem(`${this.storagePrefix}-volume`, String(this.volume));
+        }
+        if (this.audioElement) {
+            this.audioElement.volume = this.volume;
+        }
+    }
+    /** Get volume */
+    getVolume() {
+        return this.volume;
+    }
+    pause(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /** Clean up resources */
+    destroy() {
+        this.cancel();
+        if (this.audioContext) {
+            this.audioContext.close();
+            this.audioContext = null;
+        }
+        this.audioElement = null;
+    }
+}
+//# sourceMappingURL=player.js.map

package/dist/voice/player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.js","sourceRoot":"","sources":["../../voice/player.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;GAGG;AACH,MAAM,OAAO,WAAW;IACd,YAAY,GAA4B,IAAI,CAAC;IAC7C,YAAY,GAAwB,IAAI,CAAC;IACzC,KAAK,GAAG,KAAK,CAAC;IACd,MAAM,GAAG,GAAG,CAAC;IACb,UAAU,GAAG,KAAK,CAAC;IACnB,aAAa,CAAS;IACtB,aAAa,CAAS;IACtB,QAAQ,GAAG,KAAK,CAAC;IACjB,YAAY,GAA2B,EAAE,CAAC;IAElD,YAAY,aAAqB,EAAE,aAAqB;QACtD,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QAEnC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,aAAa,QAAQ,CAAC,KAAK,MAAM,CAAC;YACvE,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,aAAa,SAAS,CAAC,CAAC;YACpE,IAAI,WAAW;gBAAE,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;YAEvD,+DAA+D;YAC/D,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;gBAC3B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;gBACvD,MAAM,CAAC,eAAe,CAAC,gBAAgB,CAAC,eAAe,EAAE,GAAG,EAAE;oBAC5D,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;gBACzD,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,gFAAgF;IAChF,MAAM;QACJ,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC;YACH,qDAAqD;YACrD,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YACnC,IAAI,GAAG,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;gBAC9B,GAAG,CAAC,MAAM,EAAE,CAAC;YACf,CAAC;YACD,oEAAoE;YACpE,MAAM,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAClC,EAAE,CAAC,GAAG,GAAG,wXAAwX,CAAC;YAClY,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YAC1B,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;IACH,CAAC;IAEO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,IAAI,KAAK,EAAE,CAAC;YAChC,IAAI,CAAC,YAAY,CAAC,OAAO,GAAG,MAAM,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,IAAI,CACtB,MAAM,CAAC,YAAY;gBAClB,MAAiE,CAAC,kBAAkB,CACtF,EAAE,CAAC;QACN,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC5C,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,kDAAkD;IAClD,UAAU;QACR,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,QAAgB,EAAE,SAAoB;QACrD,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QAExB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,aAAa,IAAI,SAAS,IAAI,QAAQ,MAAM,CAAC;QACjE,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAChB,OAAkD,EAClD,OAAO,GAAG,GAAG;QAEb,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK;gBAAE,MAAM;YACzC,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACzD,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC/C,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,gCAAgC;IACxB,aAAa,CAAC,GAAW;QAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;gBAChD,OAAO,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;YAErC,kCAAkC;YAClC,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;YAEtB,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;YAChB,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAE3B,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;gBAC1C,KAAK,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC9C,CAAC,CAAC;YAEF,MAAM,KAAK,GAAG,GAAG,EAAE;gBACjB,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,OAAO,EAAE,CAAC;gBACV,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;oBAC1C,OAAO,CAAC,IAAI,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;gBACtD,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YAEF,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACvC,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACtB,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,YAAY,CAAC,IAAY,EAAE,SAAoB;QACnD,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YAC3E,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;YAEhC,MAAM,SAAS,GAAG,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAC;YACrD,SAAS,CAAC,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YACvC,SAAS,CAAC,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;YACzC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YAE/B,2DAA2D;YAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;gBACzC,CAAC,CAAC,IAAI,CAAC,YAAY;gBACnB,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;gBAClC,MAAM,SAAS,GACb,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;oBACxE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9C,IAAI,SAAS;oBAAE,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC;YAC7C,CAAC;iBAAM,CAAC;gBACN,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9D,IAAI,SAAS;oBAAE,SAAS,CAAC,KAAK,GAAG,SAAS,CAAC;YAC7C,CAAC;YAED,SAAS,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;YAClC,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4CAA4C;IAC5C,MAAM;QACJ,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QAEvB,qBAAqB;QACrB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC,YAAY,CAAC,WAAW,GAAG,CAAC,CAAC;QACpC,CAAC;QAED,oDAAoD;QACpD,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YAC5D,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,QAAQ,CAAC,KAAc;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,aAAa,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,8BAA8B;IAC9B,SAAS,CAAC,GAAW;QACnB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC5C,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,aAAa,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QACzC,CAAC;IACH,CAAC;IAED,iBAAiB;IACjB,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,yBAAyB;IACzB,OAAO;QACL,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/voice/provider.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from "react";
+import { AudioPlayer } from "./player";
+import type { PersonaId, AudioProviderConfig } from "./types";
+export interface KidsAudioContextType {
+    /** Play a pre-generated phrase by ID */
+    playPhrase: (phraseId: string, personaId: PersonaId) => Promise<void>;
+    /** Play a sequence of phrases with pauses */
+    playSequence: (phrases: Array<{
+        id: string;
+        persona: PersonaId;
+    }>, pauseMs?: number) => Promise<void>;
+    /** Fallback: speak dynamic text via Web Speech API */
+    speakDynamic: (text: string, personaId: PersonaId) => Promise<void>;
+    /** Cancel all audio playback */
+    cancel: () => void;
+    /** Current mute state */
+    muted: boolean;
+    /** Toggle or set mute */
+    setMuted: (muted: boolean) => void;
+    /** Toggle mute */
+    toggleMute: () => void;
+    /** Current volume (0-1) */
+    volume: number;
+    /** Set volume (0-1) */
+    setVolume: (vol: number) => void;
+    /** Get the underlying AudioPlayer (for SFX access) */
+    player: AudioPlayer | null;
+}
+export declare const KidsAudioContext: import("react").Context<KidsAudioContextType>;
+interface KidsAudioProviderProps extends AudioProviderConfig {
+    children: ReactNode;
+}
+export declare function KidsAudioProvider({ children, storagePrefix, audioBasePath, }: KidsAudioProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/dist/voice/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../voice/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAoB,MAAM,SAAS,CAAC;AAGhF,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,6CAA6C;IAC7C,YAAY,EAAE,CACZ,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,CAAA;KAAE,CAAC,EAClD,OAAO,CAAC,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,sDAAsD;IACtD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,gCAAgC;IAChC,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,yBAAyB;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,yBAAyB;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,kBAAkB;IAClB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,sDAAsD;IACtD,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B;AAED,eAAO,MAAM,gBAAgB,+CAW3B,CAAC;AAEH,UAAU,sBAAuB,SAAQ,mBAAmB;IAC1D,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,aAAa,EACb,aAAa,GACd,EAAE,sBAAsB,2CA+FxB"}

package/dist/voice/provider.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useEffect, useRef, useState, } from "react";
+import { AudioPlayer } from "./player";
+export const KidsAudioContext = createContext({
+    playPhrase: async () => { },
+    playSequence: async () => { },
+    speakDynamic: async () => { },
+    cancel: () => { },
+    muted: false,
+    setMuted: () => { },
+    toggleMute: () => { },
+    volume: 1,
+    setVolume: () => { },
+    player: null,
+});
+export function KidsAudioProvider({ children, storagePrefix, audioBasePath, }) {
+    const playerRef = useRef(null);
+    const [muted, setMutedState] = useState(false);
+    const [volume, setVolumeState] = useState(1);
+    // Initialize player
+    useEffect(() => {
+        const player = new AudioPlayer(storagePrefix, audioBasePath);
+        playerRef.current = player;
+        setMutedState(player.isMuted());
+        setVolumeState(player.getVolume());
+        return () => {
+            player.destroy();
+            playerRef.current = null;
+        };
+    }, [storagePrefix, audioBasePath]);
+    // Unlock audio on first user interaction
+    useEffect(() => {
+        const handleInteraction = () => {
+            playerRef.current?.unlock();
+        };
+        document.addEventListener("pointerdown", handleInteraction, { once: true });
+        document.addEventListener("keydown", handleInteraction, { once: true });
+        return () => {
+            document.removeEventListener("pointerdown", handleInteraction);
+            document.removeEventListener("keydown", handleInteraction);
+        };
+    }, []);
+    const playPhrase = useCallback(async (phraseId, personaId) => {
+        await playerRef.current?.playPhrase(phraseId, personaId);
+    }, []);
+    const playSequence = useCallback(async (phrases, pauseMs) => {
+        await playerRef.current?.playSequence(phrases, pauseMs);
+    }, []);
+    const speakDynamic = useCallback(async (text, personaId) => {
+        await playerRef.current?.speakDynamic(text, personaId);
+    }, []);
+    const cancel = useCallback(() => {
+        playerRef.current?.cancel();
+    }, []);
+    const setMuted = useCallback((value) => {
+        playerRef.current?.setMuted(value);
+        setMutedState(value);
+    }, []);
+    const toggleMute = useCallback(() => {
+        const next = !playerRef.current?.isMuted();
+        playerRef.current?.setMuted(next);
+        setMutedState(next);
+    }, []);
+    const setVolume = useCallback((vol) => {
+        playerRef.current?.setVolume(vol);
+        setVolumeState(vol);
+    }, []);
+    return (_jsx(KidsAudioContext.Provider, { value: {
+            playPhrase,
+            playSequence,
+            speakDynamic,
+            cancel,
+            muted,
+            setMuted,
+            toggleMute,
+            volume,
+            setVolume,
+            player: playerRef.current,
+        }, children: children }));
+}
+//# sourceMappingURL=provider.js.map

package/dist/voice/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../voice/provider.tsx"],"names":[],"mappings":"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"}

package/dist/voice/types.d.ts

@@ -0,0 +1,52 @@
+/** OpenAI TTS voice identifiers */
+export type OpenAIVoice = "shimmer" | "nova" | "fable" | "echo" | "alloy" | "onyx";
+/** Persona identifiers */
+export type PersonaId = "sunny" | "bloop" | "maple" | "fizz" | "pip";
+/** Persona definition */
+export interface Persona {
+    id: PersonaId;
+    name: string;
+    role: string;
+    description: string;
+    openaiVoice: OpenAIVoice;
+    speed: number;
+    /** Fallback settings for Web Speech API */
+    fallback: {
+        rate: number;
+        pitch: number;
+        preferFemale: boolean;
+    };
+    celebrationPhrases: string[];
+    encouragementPhrases: string[];
+    tryAgainPhrases: string[];
+}
+/** A single line in a game's voice script */
+export interface VoiceScriptLine {
+    id: string;
+    text: string;
+    persona: PersonaId;
+    trigger: string;
+}
+/** A game's complete voice script */
+export interface VoiceScript {
+    game: string;
+    personas: PersonaId[];
+    lines: VoiceScriptLine[];
+}
+/** Audio playback state */
+export interface AudioState {
+    muted: boolean;
+    volume: number;
+    currentPersona: PersonaId | null;
+    isPlaying: boolean;
+}
+/** Configuration for the audio provider */
+export interface AudioProviderConfig {
+    /** localStorage key prefix for this game (e.g., "count-along") */
+    storagePrefix: string;
+    /** Base path for audio files (e.g., "/audio" or "/count-along/audio") */
+    audioBasePath: string;
+}
+/** Celebration intensity levels */
+export type CelebrationLevel = "small" | "medium" | "big";
+//# sourceMappingURL=types.d.ts.map

package/dist/voice/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../voice/types.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAEnF,0BAA0B;AAC1B,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAErE,yBAAyB;AACzB,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,2BAA2B;AAC3B,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC"}

package/dist/voice/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/voice/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../voice/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kids-games/core",
+  "version": "0.1.0",
+  "description": "Shared framework for Kids Corner games — voice personas, audio playback, celebrations, UI components, and design tokens",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mattatencio/kids-games-core"
+  },
+  "exports": {
+    "./voice": {
+      "types": "./dist/voice/index.d.ts",
+      "import": "./dist/voice/index.js"
+    },
+    "./sfx": {
+      "types": "./dist/sfx/index.d.ts",
+      "import": "./dist/sfx/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./celebrations": {
+      "types": "./dist/celebrations/index.d.ts",
+      "import": "./dist/celebrations/index.js"
+    },
+    "./tokens": {
+      "types": "./dist/tokens/index.d.ts",
+      "import": "./dist/tokens/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "generate-audio": "tsx scripts/generate-audio.ts"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "openai": "^4.80.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "@types/react": "^19.0.0"
+  }
+}