@livx.cc/native-kit 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.23.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';
@@ -23,8 +23,10 @@ import { OAuthModule } from '../modules/oauth';
 import { PhotosModule } from '../modules/photos';
 import { PushModule } from '../modules/push';
 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';
@@ -91,6 +93,8 @@ export class NativeKit {
   public readonly health = new HealthModule(this);
   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

@@ -38,6 +38,10 @@ export class WebAdapter implements NativeKitAdapter {
   private listeners = new Map<string, Set<(payload: unknown) => void>>();
   private geoWatchId: number | null = null;
   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';
@@ -75,6 +79,15 @@ export class WebAdapter implements NativeKitAdapter {
       calendar: 'none',
       camera: 'web', // <input capture> — mobile browsers open the camera
       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
@@ -321,6 +334,25 @@ export class WebAdapter implements NativeKitAdapter {
       case 'calendar.createEvent':
         throw new KitError('UNSUPPORTED', 'No calendar access on web');
 
+      case 'scanner.scan':
+        return this.scanBarcode(p.formats, p.camera === 'front' ? 'user' : 'environment') as Promise<T>;
+      case 'scanner.cancel':
+        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':
@@ -447,6 +479,178 @@ export class WebAdapter implements NativeKitAdapter {
     this.listeners.get(event)?.forEach((cb) => cb(payload));
   }
 
+  /** Map our small format enum → BarcodeDetector `formats` strings. Omit/`'all'` = detector default. */
+  private toDetectorFormats(formats?: string | string[]): string[] | undefined {
+    const want = (Array.isArray(formats) ? formats : formats ? [formats] : []).filter((f) => f && f !== 'all');
+    if (!want.length) return undefined;
+    const map: Record<string, string> = { qr: 'qr_code', ean13: 'ean_13', code128: 'code_128' };
+    return want.map((f) => map[f] ?? f);
+  }
+
+  /** Reverse map a detector format string → our enum (best-effort). */
+  private fromDetectorFormat(f: string): 'qr' | 'ean13' | 'code128' | 'unknown' {
+    if (f === 'qr_code') return 'qr';
+    if (f === 'ean_13') return 'ean13';
+    if (f === 'code_128') return 'code128';
+    return 'unknown';
+  }
+
+  /**
+   * Open a full-screen camera overlay, run a BarcodeDetector loop, resolve the FIRST hit then tear
+   * down. Resolves `{ cancelled: true }` if the user taps the close button or `scanner.cancel` fires.
+   */
+  private scanBarcode(
+    formats: string | string[] | undefined,
+    facingMode: 'environment' | 'user'
+  ): Promise<{ value: string; format: string; bounds?: any } | { cancelled: true }> {
+    const Detector = (window as any).BarcodeDetector;
+    const getUserMedia = (navigator as any).mediaDevices?.getUserMedia?.bind((navigator as any).mediaDevices);
+    if (!Detector || !getUserMedia) throw new KitError('UNSUPPORTED', 'BarcodeDetector / camera unavailable in this browser');
+
+    return new Promise(async (resolve, reject) => {
+      let stream: MediaStream | null = null;
+      let raf = 0;
+      let done = false;
+      const wrap = document.createElement('div');
+      const video = document.createElement('video');
+
+      const teardown = () => {
+        if (done) return;
+        done = true;
+        cancelAnimationFrame(raf);
+        stream?.getTracks().forEach((t) => t.stop());
+        wrap.remove();
+        // Only clear if it's still OUR handler — a newer scan may have replaced it.
+        if (this.scanCancel === cancelHandler) this.scanCancel = null;
+      };
+      const cancelHandler = () => { teardown(); resolve({ cancelled: true }); };
+      this.scanCancel = cancelHandler;
+
+      try {
+        const detector = new Detector(this.toDetectorFormats(formats) ? { formats: this.toDetectorFormats(formats) } : undefined);
+        stream = await getUserMedia({ video: { facingMode } });
+        wrap.style.cssText = 'position:fixed;inset:0;background:#000;z-index:99999;display:flex;flex-direction:column';
+        video.setAttribute('playsinline', '');
+        video.muted = true;
+        video.style.cssText = 'flex:1;width:100%;height:100%;object-fit:cover';
+        (video as any).srcObject = stream;
+        const close = document.createElement('button');
+        close.textContent = 'Cancel';
+        close.style.cssText = 'position:absolute;top:max(12px,env(safe-area-inset-top));right:16px;z-index:1;background:rgba(0,0,0,.5);color:#fff;border:0;border-radius:18px;padding:8px 16px;font:15px system-ui';
+        close.onclick = () => { teardown(); resolve({ cancelled: true }); };
+        wrap.appendChild(video);
+        wrap.appendChild(close);
+        document.body.appendChild(wrap);
+        await video.play();
+
+        const tick = async () => {
+          if (done) return;
+          try {
+            const codes = await detector.detect(video);
+            if (codes?.length) {
+              const c = codes[0];
+              const b = c.boundingBox;
+              teardown();
+              resolve({
+                value: c.rawValue,
+                format: this.fromDetectorFormat(c.format),
+                bounds: b ? { x: b.x, y: b.y, width: b.width, height: b.height } : undefined,
+              });
+              return;
+            }
+          } catch { /* transient detect error — keep looping */ }
+          raf = requestAnimationFrame(tick);
+        };
+        raf = requestAnimationFrame(tick);
+      } catch (e: any) {
+        teardown();
+        reject(new KitError(e?.name === 'NotAllowedError' ? 'DENIED' : 'NATIVE_ERROR', e?.message ?? 'scan failed'));
+      }
+    });
+  }
+
+  // ── 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

@@ -35,6 +35,9 @@ export type { ActionOptions, AlertOptions, ConfirmOptions, SafeAreaInsets } from
 export type { MotionSample } from './modules/motion';
 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/scanner.ts

@@ -0,0 +1,63 @@
+import type { NativeKit } from '../core/NativeKit';
+
+/** Symbologies the scanner can decode. `'all'` (default) accepts every supported format. */
+export type ScanFormat = 'qr' | 'ean13' | 'code128' | 'all';
+
+/** A successfully decoded code. */
+export interface ScanResult {
+  /** Decoded payload (the string the barcode/QR encodes). */
+  value: string;
+  /** Detected symbology — one of {@link ScanFormat} minus `'all'`, or `'unknown'`. */
+  format: ScanFormat | 'unknown';
+  /** Bounding box of the code in the camera preview (CSS px), when the platform reports it. */
+  bounds?: { x: number; y: number; width: number; height: number };
+}
+
+/** Scan resolved without a code because the user dismissed the scanner. */
+export interface ScanCancelled {
+  cancelled: true;
+}
+
+export interface ScanOptions {
+  /** Symbology filter — a single format or a list. Omit / `'all'` = any supported code. */
+  formats?: ScanFormat | ScanFormat[];
+  /** Which camera to open. Default `'back'`. */
+  camera?: 'back' | 'front';
+}
+
+/** True when a {@link ScanResult.value} is present (not the cancelled shape). */
+export function isScanResult(r: ScanResult | ScanCancelled): r is ScanResult {
+  return (r as ScanCancelled).cancelled !== true;
+}
+
+/**
+ * Camera barcode / QR decoding — ONE API across platforms.
+ *
+ * {@link scan} opens a native full-screen capture UI, returns the FIRST decoded code, then
+ * auto-dismisses. If the user dismisses it first, it resolves to `{ cancelled: true }` (NOT a
+ * rejection) — branch with {@link isScanResult}. {@link cancel} dismisses an in-progress scan
+ * programmatically, which makes that same pending {@link scan} resolve `{ cancelled: true }`.
+ *
+ * Native (iOS `AVCaptureMetadataOutput`, Android ZXing capture Activity) reports
+ * `capability === 'native'`. Web maps to the `BarcodeDetector` API where present (Chrome/Android
+ * → `'web'`); where absent (Safari/Firefox today) it's `'none'` and {@link scan} throws
+ * `KitError('UNSUPPORTED')` — no heavy JS decoder fallback. Branch on {@link capability}.
+ */
+export class ScannerModule {
+  constructor(private kit: NativeKit) {}
+
+  /** 'native' on a shell · 'web' where BarcodeDetector exists · else 'none'. */
+  get capability() {
+    return this.kit.capability('scanner');
+  }
+
+  /** Open the scanner; resolve the first code, or `{ cancelled: true }` if dismissed. */
+  scan(opts: ScanOptions = {}): Promise<ScanResult | ScanCancelled> {
+    return this.kit.invoke('scanner.scan', opts);
+  }
+
+  /** Dismiss an in-progress {@link scan} (its promise then resolves `{ cancelled: true }`). */
+  cancel(): Promise<void> {
+    return this.kit.invoke('scanner.cancel');
+  }
+}

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));
+  }
+}