even-toolkit 1.1.1 → 1.3.0

package/glasses/useGlasses.ts

@@ -7,6 +7,12 @@ import { bindKeyboard } from './keyboard';
 import { activateKeepAlive, deactivateKeepAlive } from './keep-alive';
 import type { SplashHandle } from './splash';
 
+/** Debug overlay — only shows if window.__glassesDebug is true */
+function showDebugOverlay(msg: string): void {
+  if (!(window as any).__glassesDebug) return;
+  // visible via __glassesDebug flag — no console output in production
+}
+
 export interface UseGlassesConfig<S> {
   getSnapshot: () => S;
   /** Convert snapshot to single text display (for 'text' mode) */
@@ -65,7 +71,7 @@ export function useGlasses<S>(config: UseGlassesConfig<S>): void {
       // Build display text from lines
       const data = configRef.current.toDisplayData(snapshot, nav);
       const text = data.lines.map(l => {
-        if (l.style === 'separator') return '\u2500'.repeat(44);
+        if (l.style === 'separator') return '\u2500'.repeat(28) + '\n';
         if (l.inverted) return `\u25B6 ${l.text}`;
         return `  ${l.text}`;
       }).join('\n');
@@ -144,15 +150,20 @@ export function useGlasses<S>(config: UseGlassesConfig<S>): void {
     };
 
     async function initBridge() {
+      showDebugOverlay('initBridge: starting...');
       try {
         await hub.init();
+        showDebugOverlay('initBridge: bridge ready');
+        // Expose bridge globally for STT GlassBridgeSource
+        (window as any).__evenBridge = hub;
         if (disposed) return;
 
         const splash = configRef.current.splash;
 
         if (splash) {
-          // Image-based splash: show canvas-rendered image, then wait minTime
+          showDebugOverlay('initBridge: showing splash...');
           await splash.show(hub);
+          showDebugOverlay('initBridge: splash shown');
           if (disposed) return;
 
           hub.onEvent((event) => {
@@ -170,7 +181,7 @@ export function useGlasses<S>(config: UseGlassesConfig<S>): void {
           // uses updateHomeText instead of rebuilding (avoids blink)
           lastHadImagesRef.current = !!configRef.current.homeImageTiles?.length;
         } else {
-          // Default text splash
+          showDebugOverlay('initBridge: no splash, showing text...');
           await hub.showTextPage(`\n\n      ${configRef.current.appName}`);
           if (disposed) return;
 
@@ -179,8 +190,9 @@ export function useGlasses<S>(config: UseGlassesConfig<S>): void {
             if (action) handleAction(action);
           });
         }
-      } catch {
+      } catch (err) {
         // SDK not available — app continues without glasses
+        showDebugOverlay('Bridge init failed: ' + (err instanceof Error ? err.message : String(err)));
       }
 
       // Start polling for state changes
@@ -207,8 +219,9 @@ export function useGlasses<S>(config: UseGlassesConfig<S>): void {
       unbindKeyboard();
       hub.dispose();
       hubRef.current = null;
+      (window as any).__evenBridge = null;
       deactivateKeepAlive();
     };
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "even-toolkit",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Design system & component library for Even Realities G2 smart glasses apps — 55+ web components, 191 pixel-art icons, glasses SDK bridge, and design tokens.",
   "type": "module",
   "main": "./dist/glasses/index.js",
@@ -318,14 +318,6 @@
       "types": "./dist/stt/audio/pcm-utils.d.ts",
       "import": "./dist/stt/audio/pcm-utils.js"
     },
-    "./stt/providers/web-speech": {
-      "types": "./dist/stt/providers/web-speech.d.ts",
-      "import": "./dist/stt/providers/web-speech.js"
-    },
-    "./stt/providers/whisper-local": {
-      "types": "./dist/stt/providers/whisper-local/provider.d.ts",
-      "import": "./dist/stt/providers/whisper-local/provider.js"
-    },
     "./stt/providers/whisper-api": {
       "types": "./dist/stt/providers/whisper-api.d.ts",
       "import": "./dist/stt/providers/whisper-api.js"
@@ -348,14 +340,13 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@evenrealities/even_hub_sdk": ">=0.0.7",
-    "@jappyjan/even-better-sdk": ">=0.0.10",
+    "@evenrealities/even_hub_sdk": ">=0.0.9",
+    "@jappyjan/even-better-sdk": ">=0.0.11",
     "class-variance-authority": ">=0.7.0",
     "clsx": ">=2.0.0",
     "react": ">=18.0.0",
     "react-router": ">=7.0.0",
-    "tailwind-merge": ">=2.0.0",
-    "@huggingface/transformers": ">=3.0.0"
+    "tailwind-merge": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -372,15 +363,11 @@
     },
     "class-variance-authority": {
       "optional": true
-    },
-    "@huggingface/transformers": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@evenrealities/even_hub_sdk": "^0.0.7",
-    "@huggingface/transformers": "^3.8.1",
-    "@jappyjan/even-better-sdk": "^0.0.10",
+    "@evenrealities/even_hub_sdk": "^0.0.9",
+"@jappyjan/even-better-sdk": "^0.0.11",
     "@types/react": "^19.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -408,6 +395,7 @@
     "url": "https://github.com/fabioglimb/even-toolkit/issues"
   },
   "dependencies": {
+    "react-is": "^19.2.4",
     "recharts": "^3.8.0"
   }
 }

package/stt/debug.ts

@@ -0,0 +1,38 @@
+/**
+ * STT Debug logging — enabled via window.__sttDebug = true
+ * or by calling enableSTTDebug() from the console.
+ *
+ * All logs are also stored in window.__sttLogs[] for inspection.
+ */
+
+const MAX_LOGS = 200;
+
+export function sttLog(...args: any[]): void {
+  const w = window as any;
+  if (!w.__sttLogs) w.__sttLogs = [];
+
+  const entry = {
+    t: new Date().toISOString().slice(11, 23),
+    msg: args.map(a => typeof a === 'object' ? JSON.stringify(a) : String(a)).join(' '),
+  };
+
+  w.__sttLogs.push(entry);
+  if (w.__sttLogs.length > MAX_LOGS) w.__sttLogs.shift();
+
+  if (w.__sttDebug) {
+    console.log(`[STT ${entry.t}]`, ...args);
+  }
+}
+
+/** Call from browser console: enableSTTDebug() */
+(window as any).enableSTTDebug = () => {
+  (window as any).__sttDebug = true;
+  console.log('[STT] Debug enabled. Logs:', (window as any).__sttLogs);
+};
+
+/** Call from browser console: getSTTLogs() */
+(window as any).getSTTLogs = () => {
+  return ((window as any).__sttLogs ?? [])
+    .map((e: any) => `${e.t} ${e.msg}`)
+    .join('\n');
+};

package/stt/engine.ts

@@ -8,17 +8,19 @@ import type {
 } from './types';
 import { createProvider } from './registry';
 import { MicrophoneSource } from './sources/microphone';
+import { GlassBridgeSource } from './sources/glass-bridge';
 import { resample } from './audio/resample';
 import { createVAD } from './audio/vad';
 import { createAudioBuffer } from './audio/buffer';
+import { sttLog } from './debug';
 
 /**
- * STTEngine orchestrates source -> processing -> provider.
+ * STTEngine — orchestrates audio source -> processing -> provider.
  *
- * For `web-speech` provider: skips audio source (it handles its own mic).
- * For other providers: starts audio source, pipes through optional resample
- * and VAD, buffers audio, and calls provider.transcribe() on speech end.
+ * Batch providers (whisper-api): record audio, then transcribe on stop.
+ * Streaming providers (deepgram): pipe audio in real-time via sendAudio.
  */
+
 export class STTEngine {
   private config: STTEngineConfig;
   private provider: STTProvider | null = null;
@@ -32,15 +34,16 @@ export class STTEngine {
   private providerUnsubs: Array<() => void> = [];
 
   private vad: ReturnType<typeof createVAD> | null = null;
-  private buffer: ReturnType<typeof createAudioBuffer> | null = null;
+  private chunkBuffer: ReturnType<typeof createAudioBuffer> | null = null;
   private targetSampleRate: number;
+  private stopped = false;
 
   constructor(config: STTEngineConfig) {
     this.config = config;
     this.targetSampleRate = config.sampleRate ?? 16000;
   }
 
-  // ── Event subscriptions ──
+  // -- Event subscriptions --
 
   onTranscript(cb: (t: STTTranscript) => void): () => void {
     this.transcriptListeners.push(cb);
@@ -67,25 +70,37 @@ export class STTEngine {
   }
 
   private emitTranscript(t: STTTranscript): void {
+    sttLog('transcript:', t.isFinal ? 'FINAL' : 'interim', `"${t.text}"`);
     for (const cb of this.transcriptListeners) cb(t);
   }
 
   private emitState(s: STTState): void {
+    sttLog('state ->', s);
     for (const cb of this.stateListeners) cb(s);
   }
 
   private emitError(e: STTError): void {
+    sttLog('ERROR:', e.code, e.message);
     for (const cb of this.errorListeners) cb(e);
   }
 
-  // ── Lifecycle ──
+  // -- Lifecycle --
 
   async start(): Promise<void> {
+    sttLog('engine.start()', 'provider:', this.config.provider, 'source:', this.config.source ?? 'auto');
+    this.stopped = false;
+
+    // Reuse existing provider if already initialized
+    if (this.provider) {
+      sttLog('engine: reusing provider');
+      return this.startAudioPipeline();
+    }
+
     this.emitState('loading');
 
     try {
-      // Create and init provider
       this.provider = await createProvider(this.config.provider);
+      sttLog('provider created:', this.provider.type, 'modes:', this.provider.supportedModes);
       this.subscribeProvider(this.provider);
 
       await this.provider.init({
@@ -98,36 +113,10 @@ export class STTEngine {
         vadSilenceMs: typeof this.config.vad === 'object' ? this.config.vad.silenceMs : undefined,
         sampleRate: this.targetSampleRate,
       });
-
-      // web-speech handles its own microphone
-      if (this.config.provider === 'web-speech') {
-        this.provider.start();
-        return;
-      }
-
-      // Set up audio source
-      this.source = this.resolveSource();
-      await this.source.start();
-
-      // Set up VAD if enabled
-      if (this.config.vad) {
-        const vadConfig = typeof this.config.vad === 'object' ? {
-          silenceThresholdMs: this.config.vad.silenceMs,
-          speechThresholdDb: this.config.vad.thresholdDb,
-        } : undefined;
-        this.vad = createVAD(vadConfig);
-      }
-
-      // Set up audio buffer for batch mode
-      this.buffer = createAudioBuffer({ sampleRate: this.targetSampleRate });
-
-      // Wire audio pipeline
-      this.sourceUnsub = this.source.onAudioData((pcm, sampleRate) => {
-        this.processAudio(pcm, sampleRate);
-      });
-
-      this.provider.start();
+      sttLog('provider.init() done');
+      await this.startAudioPipeline();
     } catch (err) {
+      sttLog('engine.start() FAILED:', err);
       const error: STTError = {
         code: 'unknown',
         message: err instanceof Error ? err.message : String(err),
@@ -136,29 +125,78 @@ export class STTEngine {
       this.emitError(error);
       this.emitState('error');
 
-      // Attempt fallback
       if (this.config.fallback) {
         await this.switchToFallback();
       }
     }
   }
 
+  /** Set up audio source + wire to provider. Reusable for restart. */
+  private async startAudioPipeline(): Promise<void> {
+    if (!this.provider) throw new Error('No provider');
+
+    // Streaming providers -- pipe audio via sendAudio
+    if ('sendAudio' in this.provider) {
+      this.source = this.resolveSource();
+      sttLog('streaming + sendAudio: source =', this.source.constructor.name);
+      await this.source.start();
+      const provider = this.provider;
+      this.sourceUnsub = this.source.onAudioData((pcm, sampleRate) => {
+        const samples = sampleRate !== this.targetSampleRate
+          ? resample(pcm, sampleRate, this.targetSampleRate)
+          : pcm;
+        (provider as any).sendAudio(samples);
+      });
+      this.emitState('listening');
+      this.provider.start();
+      sttLog('streaming provider started');
+      return;
+    }
+
+    // Batch providers: set up audio pipeline
+    this.source = this.resolveSource();
+    sttLog('audio source resolved:', this.source.constructor.name);
+    await this.source.start();
+
+    const vadConfig = typeof this.config.vad === 'object' ? {
+      silenceThresholdMs: this.config.vad.silenceMs ?? 2500,
+      speechThresholdDb: this.config.vad.thresholdDb,
+    } : { silenceThresholdMs: 2500 };
+    this.vad = createVAD(vadConfig);
+    this.chunkBuffer = createAudioBuffer({ sampleRate: this.targetSampleRate, maxSeconds: 120 });
+
+    this.sourceUnsub = this.source.onAudioData((pcm, sampleRate) => {
+      this.processAudio(pcm, sampleRate);
+    });
+
+    this.emitState('listening');
+    this.provider.start();
+    sttLog('engine listening');
+  }
+
   stop(): void {
-    this.provider?.stop();
+    if (this.stopped) return;
+    this.stopped = true;
+    sttLog('engine.stop()');
+
     this.sourceUnsub?.();
     this.sourceUnsub = null;
     this.source?.stop();
+    this.provider?.stop();
     this.vad?.reset();
-    this.buffer?.clear();
+
+    this.transcribeFullBuffer();
   }
 
   abort(): void {
+    this.stopped = true;
+    sttLog('engine.abort()');
     this.provider?.abort();
     this.sourceUnsub?.();
     this.sourceUnsub = null;
     this.source?.stop();
     this.vad?.reset();
-    this.buffer?.clear();
+    this.chunkBuffer?.clear();
   }
 
   dispose(): void {
@@ -174,75 +212,113 @@ export class STTEngine {
     this.errorListeners.length = 0;
   }
 
-  // ── Internal ──
+  // -- Internal --
 
   private resolveSource(): AudioSource {
     const src = this.config.source;
-    if (!src || src === 'microphone') {
-      return new MicrophoneSource();
+
+    // Explicit AudioSource object passed
+    if (src && typeof src === 'object') {
+      sttLog('resolveSource: using custom AudioSource object');
+      return src;
     }
+
+    // Explicit glass-bridge
     if (src === 'glass-bridge') {
-      throw new Error(
-        'glass-bridge source requires a GlassBridgeSource instance. ' +
-        'Pass an AudioSource object directly via config.source.'
-      );
+      sttLog('resolveSource: explicit glass-bridge');
+      return new GlassBridgeSource();
+    }
+
+    // Auto-detect: if glasses bridge is available, prefer it
+    if ((window as any).__evenBridge) {
+      sttLog('resolveSource: auto-detected __evenBridge -> using GlassBridgeSource');
+      return new GlassBridgeSource();
     }
-    // Custom AudioSource instance
+
+    // Explicit microphone or fallback
+    if (!src || src === 'microphone') {
+      sttLog('resolveSource: using MicrophoneSource (browser mic)');
+      return new MicrophoneSource();
+    }
+
     return src;
   }
 
   private processAudio(pcm: Float32Array, sampleRate: number): void {
-    // Resample if needed
-    let samples = sampleRate !== this.targetSampleRate
+    if (this.stopped) return;
+
+    const samples = sampleRate !== this.targetSampleRate
       ? resample(pcm, sampleRate, this.targetSampleRate)
       : pcm;
 
-    if (!this.buffer) return;
+    this.chunkBuffer?.append(samples);
 
-    // If VAD is enabled, check for speech boundaries
+    // VAD: detect speech end for auto-stop
     if (this.vad) {
       const result = this.vad.process(samples);
-
-      if (result.isSpeech || result.speechEnded) {
-        this.buffer.append(samples);
+      if (result.speechEnded && !this.config.continuous) {
+        sttLog('VAD: speech ended -> auto-stop');
+        this.stop();
       }
-
-      if (result.speechEnded) {
-        this.flushBuffer();
-      }
-    } else {
-      // No VAD: accumulate everything, provider handles streaming
-      this.buffer.append(samples);
     }
   }
 
-  private async flushBuffer(): Promise<void> {
-    if (!this.buffer || !this.provider) return;
+  /** On stop: transcribe the full recording buffer */
+  private async transcribeFullBuffer(): Promise<void> {
+    if (!this.provider?.transcribe || !this.chunkBuffer) {
+      this.emitState('idle');
+      return;
+    }
+
+    const audio = this.chunkBuffer.getAll();
+    this.chunkBuffer.clear();
+    this.chunkBuffer = null;
 
-    const audio = this.buffer.getAll();
-    this.buffer.clear();
+    if (audio.length < this.targetSampleRate * 0.3) {
+      sttLog('audio too short, skipping');
+      this.emitState('idle');
+      return;
+    }
 
-    if (audio.length === 0) return;
+    this.emitState('processing');
+    sttLog('transcribing full buffer:', (audio.length / this.targetSampleRate).toFixed(1), 's,', (audio.byteLength / 1024).toFixed(0), 'KB');
 
-    // If provider supports batch transcription
-    if (this.provider.transcribe) {
-      try {
-        const transcript = await this.provider.transcribe(audio, this.targetSampleRate);
-        this.emitTranscript(transcript);
-      } catch (err) {
-        this.emitError({
-          code: 'unknown',
-          message: err instanceof Error ? err.message : String(err),
-          provider: this.config.provider,
+    try {
+      const result = await this.provider.transcribe(audio, this.targetSampleRate);
+      const text = result.text.trim();
+      sttLog('final result:', `"${text}"`);
+
+      if (text) {
+        this.emitTranscript({
+          text,
+          isFinal: true,
+          confidence: result.confidence,
+          timestamp: Date.now(),
         });
       }
+    } catch (err) {
+      this.emitError({
+        code: 'unknown',
+        message: err instanceof Error ? err.message : String(err),
+        provider: this.config.provider,
+      });
     }
+
+    this.emitState('idle');
   }
 
   private subscribeProvider(provider: STTProvider): void {
+    const isStreaming = provider.supportedModes.includes('streaming');
+
     this.providerUnsubs.push(
-      provider.onTranscript((t) => this.emitTranscript(t)),
-      provider.onStateChange((s) => this.emitState(s)),
+      // Forward transcripts from streaming providers (deepgram emits them directly)
+      // Batch providers (whisper-api) are handled by transcribeFullBuffer — don't double-emit
+      provider.onTranscript((t) => {
+        if (isStreaming) this.emitTranscript(t);
+      }),
+      provider.onStateChange((s) => {
+        if (isStreaming) this.emitState(s);
+      }),
       provider.onError((e) => {
         this.emitError(e);
         if (this.config.fallback) {
@@ -254,21 +330,20 @@ export class STTEngine {
 
   private async switchToFallback(): Promise<void> {
     if (!this.config.fallback) return;
+    sttLog('switching to fallback provider:', this.config.fallback);
 
-    // Clean up current provider
     for (const unsub of this.providerUnsubs) unsub();
     this.providerUnsubs.length = 0;
     this.provider?.dispose();
     this.provider = null;
 
-    // Switch to fallback
     const fallbackType = this.config.fallback;
     this.config = { ...this.config, provider: fallbackType, fallback: undefined };
 
     try {
       await this.start();
     } catch {
-      // Fallback also failed — nothing more to do
+      // Fallback also failed
     }
   }
 }

package/stt/index.ts

@@ -8,3 +8,4 @@ export * from './audio/pcm-utils';
 export * from './audio/resample';
 export * from './audio/vad';
 export { createAudioBuffer } from './audio/buffer';
+export { sttLog } from './debug';

package/stt/providers/deepgram.ts

@@ -6,6 +6,7 @@ import type {
   STTTranscript,
   STTError,
 } from '../types';
+import { sttLog } from '../debug';
 
 interface DeepgramResult {
   channel?: {
@@ -38,7 +39,7 @@ export class DeepgramProvider implements STTProvider {
 
   async init(config: STTProviderConfig): Promise<void> {
     this.apiKey = config.apiKey ?? '';
-    this.language = config.language ?? 'en';
+    this.language = (config.language ?? 'en').split('-')[0]; // Deepgram wants 'en' not 'en-US'
     this.modelId = config.modelId ?? 'nova-2';
 
     if (!this.apiKey) {
@@ -67,7 +68,10 @@ export class DeepgramProvider implements STTProvider {
     this.ws = new WebSocket(url, ['token', this.apiKey]);
     this.ws.binaryType = 'arraybuffer';
 
+    sttLog('deepgram: connecting to', url.substring(0, 60) + '...');
+
     this.ws.onopen = () => {
+      sttLog('deepgram: connected');
       this.setState('listening');
     };
 
@@ -75,12 +79,16 @@ export class DeepgramProvider implements STTProvider {
       try {
         const data = JSON.parse(event.data as string) as DeepgramResult;
         const alt = data.channel?.alternatives?.[0];
-        if (!alt?.transcript) return;
+        const text = alt?.transcript ?? '';
+
+        if (!text) return;
+
+        sttLog('deepgram: got', data.is_final ? 'FINAL' : 'interim', `"${text}"`);
 
         const transcript: STTTranscript = {
-          text: alt.transcript,
+          text,
           isFinal: data.is_final ?? false,
-          confidence: alt.confidence ?? 0,
+          confidence: alt?.confidence ?? 0,
           timestamp: Date.now(),
         };
         this.emitTranscript(transcript);
@@ -89,7 +97,8 @@ export class DeepgramProvider implements STTProvider {
       }
     };
 
-    this.ws.onerror = () => {
+    this.ws.onerror = (event) => {
+      sttLog('deepgram: WebSocket error', event);
       const err: STTError = {
         code: 'network',
         message: 'Deepgram WebSocket error',
@@ -107,14 +116,22 @@ export class DeepgramProvider implements STTProvider {
     };
   }
 
-  /** Send raw audio data (PCM Int16 or Float32 as ArrayBuffer) to the Deepgram stream. */
+  /** Send audio data to the Deepgram stream. Converts Float32 to Int16 (linear16). */
   sendAudio(data: ArrayBuffer | Int16Array | Float32Array): void {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
 
-    if (data instanceof ArrayBuffer) {
-      this.ws.send(data);
-    } else {
+    if (data instanceof Float32Array) {
+      // Convert Float32 [-1, 1] to Int16 PCM (Deepgram expects linear16)
+      const int16 = new Int16Array(data.length);
+      for (let i = 0; i < data.length; i++) {
+        const s = Math.max(-1, Math.min(1, data[i]!));
+        int16[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+      }
+      this.ws.send(int16.buffer);
+    } else if (data instanceof Int16Array) {
       this.ws.send(data.buffer);
+    } else {
+      this.ws.send(data);
     }
   }