@umicat/platform-sdk 0.1.0

package/dist/voice/VoiceModule.js

@@ -0,0 +1,234 @@
+const VOICE_EVENT = 'umicat:voice';
+/**
+ * Voice input — device/platform speech-to-text with a live mic level for
+ * waveform UIs. Access via `umicat.voice`. Never throws from `start()`; it
+ * resolves `null` when unsupported or the mic is denied.
+ */
+export class VoiceModule {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Does this host declare the native voice capability (WebView bridge path)? */
+    hasHostVoice() {
+        return !!this.transport.capabilities?.includes('voice') && typeof this.transport.on === 'function';
+    }
+    /** True if voice input works here — either the native host bridge or the
+     *  browser's own SpeechRecognition + mic. Check before showing a mic button. */
+    supported() {
+        if (this.hasHostVoice())
+            return true;
+        return webVoiceSupported();
+    }
+    /**
+     * Start a voice session. Resolves to a {@link VoiceSession}, or `null` if
+     * unsupported / the mic was denied (callers fall back to typing).
+     */
+    async start(lang, cb) {
+        if (this.hasHostVoice())
+            return this.startHostVoice(lang, cb);
+        return startWebVoice(lang, cb);
+    }
+    /** Native path: drive the platform recognizer through the host bridge. */
+    async startHostVoice(lang, cb) {
+        const transport = this.transport;
+        let level = 0;
+        let finalText = '';
+        let ended = false;
+        let cancelled = false;
+        const finish = () => {
+            if (ended)
+                return;
+            ended = true;
+            off();
+            if (!cancelled) {
+                const t = finalText.trim();
+                if (t)
+                    cb.onFinal(t);
+            }
+            cb.onEnd();
+        };
+        // Subscribe BEFORE start so no early event is missed (single session, so
+        // no sessionId filtering needed).
+        const off = transport.on(VOICE_EVENT, (payload) => {
+            const e = payload;
+            switch (e.event) {
+                case 'partial':
+                    cb.onPartial?.(e.text ?? '');
+                    break;
+                case 'final':
+                    finalText = e.text ?? finalText;
+                    break;
+                case 'level':
+                    if (typeof e.level === 'number')
+                        level = e.level;
+                    break;
+                case 'error':
+                    if (!cancelled)
+                        cb.onError?.(e.code ?? 'error');
+                    finish();
+                    break;
+                case 'end':
+                    finish();
+                    break;
+            }
+        });
+        try {
+            const params = { lang };
+            await transport.call('voice.start', params);
+        }
+        catch {
+            off();
+            cb.onError?.('start');
+            return null;
+        }
+        return {
+            level: () => level,
+            // Native emits 'final' then 'end' → finish() delivers onFinal.
+            stop: () => { transport.call('voice.stop').catch(() => { }); },
+            cancel: () => {
+                cancelled = true;
+                transport.call('voice.cancel').catch(() => { });
+                finish();
+            },
+        };
+    }
+}
+/** True if the BROWSER can do speech-to-text (its own recognition) AND give us the mic. */
+export function webVoiceSupported() {
+    if (typeof window === 'undefined')
+        return false;
+    const w = window;
+    const hasSR = !!(w.SpeechRecognition || w.webkitSpeechRecognition);
+    const hasMic = !!(navigator.mediaDevices && typeof navigator.mediaDevices.getUserMedia === 'function');
+    const secure = window.isSecureContext !== false; // getUserMedia needs a secure context (https)
+    return hasSR && hasMic && secure;
+}
+/** Browser path: the device's own SpeechRecognition + a Web Audio level meter. */
+async function startWebVoice(lang, cb) {
+    const w = window;
+    const SRClass = w.SpeechRecognition || w.webkitSpeechRecognition;
+    if (!SRClass || !navigator.mediaDevices?.getUserMedia)
+        return null;
+    // 1) Mic stream + analyser for the live waveform.
+    let stream;
+    try {
+        stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    }
+    catch {
+        cb.onError?.('not-allowed'); // denied / no mic
+        return null;
+    }
+    const AC = window.AudioContext || w.webkitAudioContext;
+    const ctx = new AC();
+    const source = ctx.createMediaStreamSource(stream);
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 512;
+    source.connect(analyser);
+    const buf = new Uint8Array(analyser.fftSize);
+    // 2) Speech recognition (the browser's own).
+    const rec = new SRClass();
+    rec.lang = lang;
+    rec.interimResults = true;
+    rec.continuous = false;
+    rec.maxAlternatives = 1;
+    let finalText = '';
+    let cancelled = false;
+    let ended = false;
+    const cleanup = () => {
+        try {
+            rec.onresult = null;
+            rec.onerror = null;
+        }
+        catch { /* ignore */ }
+        try {
+            stream.getTracks().forEach((t) => t.stop());
+        }
+        catch { /* ignore */ }
+        try {
+            source.disconnect();
+            analyser.disconnect();
+        }
+        catch { /* ignore */ }
+        try {
+            void ctx.close();
+        }
+        catch { /* ignore */ }
+    };
+    rec.onresult = (ev) => {
+        let interim = '';
+        for (let i = ev.resultIndex; i < ev.results.length; i++) {
+            const r = ev.results[i];
+            if (r.isFinal)
+                finalText += r[0].transcript;
+            else
+                interim += r[0].transcript;
+        }
+        if (interim)
+            cb.onPartial?.(interim);
+    };
+    rec.onerror = (ev) => { if (!cancelled)
+        cb.onError?.(ev.error || 'error'); };
+    rec.onend = () => {
+        if (ended)
+            return;
+        ended = true;
+        cleanup();
+        if (!cancelled) {
+            const t = finalText.trim();
+            if (t)
+                cb.onFinal(t);
+        }
+        cb.onEnd();
+    };
+    try {
+        rec.start();
+    }
+    catch {
+        cleanup();
+        cb.onError?.('start');
+        return null;
+    }
+    return {
+        level() {
+            try {
+                analyser.getByteTimeDomainData(buf);
+                let sum = 0;
+                for (let i = 0; i < buf.length; i++) {
+                    const x = (buf[i] - 128) / 128;
+                    sum += x * x;
+                }
+                return Math.min(1, Math.sqrt(sum / buf.length) * 3.2); // speech is quiet → scale up
+            }
+            catch {
+                return 0;
+            }
+        },
+        stop() {
+            try {
+                rec.stop();
+            }
+            catch {
+                if (!ended) {
+                    ended = true;
+                    cleanup();
+                    const t = finalText.trim();
+                    if (t)
+                        cb.onFinal(t);
+                    cb.onEnd();
+                }
+            }
+        },
+        cancel() {
+            cancelled = true;
+            try {
+                rec.abort();
+            }
+            catch { /* ignore */ }
+            if (!ended) {
+                ended = true;
+                cleanup();
+                cb.onEnd();
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@umicat/platform-sdk",
+  "version": "0.1.0",
+  "description": "Umicat's platform layer, independent of any rendering engine: identity, cloud saves, shared game data, multiplayer, runtime AI, voice and scripted dialogue. Consumed by @umicat/phaser-sdk and @umicat/three-sdk alike.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test scripts/*.test.mjs"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "colyseus.js": "^0.16.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "umicat-platform-sdk"
+  }
+}