@livx.cc/native-kit 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -1,6 +1,6 @@
 import { AppwrapAdapter } from './appwrap-adapter';
 import { WebAdapter } from './web-adapter';
-import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Unsubscribe } from './types';
+import { Capability, Handshake, InvokeOptions, KIT_PROTOCOL, KitError, NativeKitAdapter, Platform, Unsubscribe } from './types';
 import { AppModule } from '../modules/app';
 import { BillingModule } from '../modules/billing/billing';
 import { BiometricsModule } from '../modules/biometrics';
@@ -26,6 +26,7 @@ import { ReviewsModule } from '../modules/reviews';
 import { ScannerModule } from '../modules/scanner';
 import { ScreenModule } from '../modules/screen';
 import { ShareModule } from '../modules/share';
+import { SpeechModule } from '../modules/speech';
 import { StorageModule } from '../modules/storage';
 import { ToastModule } from '../modules/toast';
 import { UiModule } from '../modules/ui';
@@ -93,6 +94,7 @@ export class NativeKit {
   public readonly media = new MediaModule(this);
   public readonly contacts = new ContactsModule(this);
   public readonly scanner = new ScannerModule(this);
+  public readonly speech = new SpeechModule(this);
   public readonly calendar = new CalendarModule(this);
   public readonly app = new AppModule(this);
   public readonly browser = new BrowserModule(this);

package/src/core/web-adapter.ts

@@ -40,6 +40,8 @@ export class WebAdapter implements NativeKitAdapter {
   private motionHandler: ((e: DeviceMotionEvent) => void) | null = null;
   /** Tear-down for an in-progress scanner.scan loop (stops the camera, removes the overlay). */
   private scanCancel: (() => void) | null = null;
+  /** Stop an in-progress speech.listen session (resolves it with the best transcript so far). */
+  private listenStop: (() => void) | null = null;
 
   detect(): boolean {
     return typeof window !== 'undefined';
@@ -79,6 +81,13 @@ export class WebAdapter implements NativeKitAdapter {
       media: (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
       // BarcodeDetector (Chrome/Android) decodes; needs a getUserMedia stream to feed it. Both → 'web'.
       scanner: typeof (window as any).BarcodeDetector !== 'undefined' && (navigator as any).mediaDevices?.getUserMedia ? 'web' : 'none',
+      // TTS: SpeechSynthesis API (broad support). STT: SpeechRecognition (Chrome/webkit only).
+      speech: typeof (window as any).speechSynthesis !== 'undefined' ? 'web' : 'none',
+      speechRecognition:
+        typeof (window as any).SpeechRecognition !== 'undefined' ||
+        typeof (window as any).webkitSpeechRecognition !== 'undefined'
+          ? 'web'
+          : 'none',
       app: 'web', // openUrl via window.open; openSettings unsupported
       browser: 'web', // new tab/window
       billing: 'none', // no IAP in a plain browser — wire a web checkout yourself
@@ -331,6 +340,19 @@ export class WebAdapter implements NativeKitAdapter {
         this.scanCancel?.();
         return undefined as T;
 
+      case 'speech.speak':
+        return this.speak(String(p.text ?? ''), p) as Promise<T>;
+      case 'speech.stop':
+        (window as any).speechSynthesis?.cancel?.();
+        return undefined as T;
+      case 'speech.voices':
+        return this.listVoices() as Promise<T>;
+      case 'speech.listen':
+        return this.listen(p) as Promise<T>;
+      case 'speech.stopListening':
+        this.listenStop?.();
+        return undefined as T;
+
       case 'photos.pick':
         return this.pickImageFile(false, !!p.dataUrl, p.maxSize) as Promise<T>;
       case 'camera.capture':
@@ -547,6 +569,88 @@ export class WebAdapter implements NativeKitAdapter {
     });
   }
 
+  // ── speech (Web Speech API) ─────────────────────────────────────────
+
+  /** Speak via SpeechSynthesis; resolve when the utterance ends (or rejects on synth error). */
+  private speak(text: string, opts: Record<string, any>): Promise<void> {
+    const synth = (window as any).speechSynthesis;
+    if (!synth) throw new KitError('UNSUPPORTED', 'SpeechSynthesis unavailable');
+    return new Promise((resolve, reject) => {
+      const u = new (window as any).SpeechSynthesisUtterance(text);
+      if (opts.lang) u.lang = opts.lang;
+      if (opts.rate != null) u.rate = opts.rate;
+      if (opts.pitch != null) u.pitch = opts.pitch;
+      if (opts.voice) {
+        const v = synth.getVoices().find((vc: any) => vc.voiceURI === opts.voice || vc.name === opts.voice);
+        if (v) u.voice = v;
+      }
+      u.onend = () => resolve();
+      u.onerror = (e: any) => reject(new KitError('NATIVE_ERROR', e?.error ?? 'speech synthesis failed'));
+      synth.speak(u);
+    });
+  }
+
+  /** List synthesizer voices, awaiting the async `voiceschanged` event when the list is empty. */
+  private listVoices(): Promise<Array<{ id: string; name: string; lang: string }>> {
+    const synth = (window as any).speechSynthesis;
+    if (!synth) throw new KitError('UNSUPPORTED', 'SpeechSynthesis unavailable');
+    const map = (vs: any[]) => vs.map((v) => ({ id: v.voiceURI ?? v.name, name: v.name, lang: v.lang }));
+    const ready = synth.getVoices();
+    if (ready.length) return Promise.resolve(map(ready));
+    // Chrome populates voices asynchronously — wait once for voiceschanged, with a short fallback.
+    return new Promise((resolve) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        resolve(map(synth.getVoices()));
+      };
+      synth.addEventListener?.('voiceschanged', done, { once: true });
+      setTimeout(done, 1000);
+    });
+  }
+
+  /** Capture the mic via SpeechRecognition; resolve the FINAL transcript, stream partials. */
+  private listen(opts: Record<string, any>): Promise<string> {
+    const Rec = (window as any).SpeechRecognition || (window as any).webkitSpeechRecognition;
+    if (!Rec) throw new KitError('UNSUPPORTED', 'SpeechRecognition unavailable (Chrome only)');
+    return new Promise((resolve, reject) => {
+      const rec = new Rec();
+      if (opts.lang) rec.lang = opts.lang;
+      rec.interimResults = !!opts.partial;
+      rec.continuous = false;
+      let best = '';
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        if (this.listenStop === stop) this.listenStop = null;
+        resolve(best);
+      };
+      const stop = () => { try { rec.stop(); } catch { /* already stopped */ } };
+      this.listenStop = stop;
+      rec.onresult = (e: any) => {
+        let interim = '';
+        let finalText = '';
+        for (let i = 0; i < e.results.length; i++) {
+          const t = e.results[i][0]?.transcript ?? '';
+          if (e.results[i].isFinal) finalText += t;
+          else interim += t;
+        }
+        best = (finalText || interim).trim();
+        if (opts.partial && interim) this.emit('speech.partial', { transcript: interim.trim() });
+      };
+      rec.onerror = (e: any) => {
+        if (settled) return;
+        settled = true;
+        if (this.listenStop === stop) this.listenStop = null;
+        reject(new KitError(e?.error === 'not-allowed' ? 'DENIED' : 'NATIVE_ERROR', e?.error ?? 'recognition failed'));
+      };
+      rec.onend = finish; // fires after stop() or natural end → resolve with best-so-far
+      rec.start();
+    });
+  }
+
   private pickImageFile(
     capture: boolean,
     wantDataUrl = false,

package/src/index.ts

@@ -37,6 +37,7 @@ export type { UpdateStatus, UpdatesOptions } from './modules/updates';
 export type { PickedContact } from './modules/contacts';
 export type { ScanFormat, ScanOptions, ScanResult, ScanCancelled } from './modules/scanner';
 export { isScanResult } from './modules/scanner';
+export type { SpeechVoice, SpeakOptions, ListenOptions, SpeechPartial } from './modules/speech';
 export type { CalendarEventOptions } from './modules/calendar';
 export type { BrowserOptions } from './modules/browser';
 export type { OAuthAuthorizeParams, OAuthResult } from './modules/oauth';

package/src/modules/speech.ts

@@ -0,0 +1,99 @@
+import type { NativeKit } from '../core/NativeKit';
+import type { Unsubscribe } from '../core/types';
+
+/** An installed synthesizer voice, as offered by {@link SpeechModule.voices}. */
+export interface SpeechVoice {
+  /** Platform voice identifier — pass back as {@link SpeakOptions.voice} to select it. */
+  id: string;
+  /** Human-readable name (e.g. 'Samantha'). */
+  name: string;
+  /** BCP-47 language tag the voice speaks (e.g. 'en-US'). */
+  lang: string;
+}
+
+export interface SpeakOptions {
+  /** BCP-47 language for the utterance (e.g. 'en-US'). Defaults to the system/voice language. */
+  lang?: string;
+  /** Speaking rate. ~0.5 slow … 1 normal … 2 fast (platforms clamp to their own range). */
+  rate?: number;
+  /** Voice pitch. ~0.5 low … 1 normal … 2 high. */
+  pitch?: number;
+  /** A {@link SpeechVoice.id} from {@link SpeechModule.voices} to speak with. */
+  voice?: string;
+}
+
+export interface ListenOptions {
+  /** BCP-47 language to recognize (e.g. 'en-US'). Defaults to the device locale. */
+  lang?: string;
+  /** Stream interim results via {@link SpeechModule.onPartial} while listening. Default false. */
+  partial?: boolean;
+}
+
+/** Payload of {@link SpeechModule.onPartial}: the best-so-far interim transcript. */
+export interface SpeechPartial {
+  /** Interim transcript text (not final — may change as recognition continues). */
+  transcript: string;
+}
+
+/**
+ * Voice I/O — text-to-speech (TTS) and speech-to-text (STT) — ONE API across platforms.
+ *
+ * TTS is permission-free: {@link speak} reads text aloud and resolves when the utterance finishes;
+ * {@link stop} cancels current/queued speech; {@link voices} lists installed synthesizer voices.
+ *
+ * STT carries microphone + speech-recognition permissions (the opt-in `speech` module stamps them).
+ * {@link listen} starts capture and resolves the FINAL transcript string; pass `{ partial: true }` to
+ * also stream interim results via {@link onPartial}. {@link stopListening} ends capture early and
+ * resolves the pending {@link listen} with the best transcript so far.
+ *
+ * Two HONEST capability flags — synthesis availability ≠ recognition availability:
+ *  - {@link capability} (TTS): native iOS `AVSpeechSynthesizer` / Android `TextToSpeech`; web `'web'`
+ *    when `speechSynthesis` exists, else `'none'`.
+ *  - {@link recognitionCapability} (STT): native iOS `SFSpeechRecognizer` / Android `SpeechRecognizer`;
+ *    web `'web'` when `SpeechRecognition`/`webkitSpeechRecognition` exists (Chrome) else `'none'` —
+ *    then {@link listen} throws `KitError('UNSUPPORTED')`. Branch on the flag, not try/catch.
+ */
+export class SpeechModule {
+  constructor(private kit: NativeKit) {}
+
+  /** TTS availability: 'native' on a shell · 'web' where speechSynthesis exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('speech');
+  }
+
+  /** STT availability: 'native' on a shell · 'web' where SpeechRecognition exists · else 'none'. */
+  get recognitionCapability() {
+    return this.kit.capability('speechRecognition');
+  }
+
+  /** Speak `text` aloud; resolves when the utterance finishes (or is stopped). */
+  speak(text: string, opts: SpeakOptions = {}): Promise<void> {
+    return this.kit.invoke('speech.speak', { text, ...opts });
+  }
+
+  /** Cancel the current/queued utterance immediately. */
+  stop(): Promise<void> {
+    return this.kit.invoke('speech.stop');
+  }
+
+  /** List installed synthesizer voices. */
+  voices(): Promise<SpeechVoice[]> {
+    return this.kit.invoke('speech.voices');
+  }
+
+  /** Start capturing the mic; resolves the FINAL transcript. With `{ partial:true }`, interim
+   *  results stream via {@link onPartial}. Throws `KitError('UNSUPPORTED')` where STT is absent. */
+  listen(opts: ListenOptions = {}): Promise<string> {
+    return this.kit.invoke('speech.listen', opts);
+  }
+
+  /** Stop capture early; the pending {@link listen} resolves with the best transcript so far. */
+  stopListening(): Promise<void> {
+    return this.kit.invoke('speech.stopListening');
+  }
+
+  /** Interim transcripts while listening (only when {@link listen} was called with `partial:true`). */
+  onPartial(cb: (p: SpeechPartial) => void): Unsubscribe {
+    return this.kit.on('speech.partial', (p) => cb(p as SpeechPartial));
+  }
+}