@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/SpeechRecognition/components/EngineBadge.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface EngineBadgeProps {
+  engineId: string;
+  className?: string;
+}
+
+const LABELS: Record<string, string> = {
+  webspeech: 'Web Speech',
+  http: 'Custom HTTP',
+  websocket: 'WebSocket',
+};
+
+export function EngineBadge({ engineId, className }: EngineBadgeProps): React.ReactElement {
+  const label = LABELS[engineId] ?? engineId;
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center rounded-full border border-border bg-muted/60 px-2 py-0.5 text-[10px] uppercase tracking-wide text-muted-foreground',
+        className,
+      )}
+    >
+      {label}
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/components/ErrorBanner.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import type * as React from 'react';
+
+import { AlertTriangle } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { RecognitionError } from '../types';
+
+const FRIENDLY: Record<RecognitionError['code'], string> = {
+  unsupported: 'Speech recognition isn\'t available in this browser.',
+  'permission-denied': 'Microphone access was denied. Allow it in your browser settings to dictate.',
+  'no-microphone': 'No microphone found.',
+  network: 'Network error talking to the speech service.',
+  aborted: 'Recognition was interrupted.',
+  'no-speech': 'No speech was detected. Try again.',
+  language: 'The requested language isn\'t supported by the engine.',
+  engine: 'The speech engine reported an error.',
+  unknown: 'Something went wrong with the microphone.',
+};
+
+export interface ErrorBannerProps {
+  error: RecognitionError | null;
+  className?: string;
+  onDismiss?: () => void;
+}
+
+export function ErrorBanner({ error, className, onDismiss }: ErrorBannerProps): React.ReactElement | null {
+  if (!error) return null;
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive',
+        className,
+      )}
+    >
+      <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+      <div className="flex-1">{FRIENDLY[error.code] ?? error.message}</div>
+      {onDismiss && (
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="text-destructive hover:underline"
+        >
+          Dismiss
+        </button>
+      )}
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/components/LanguagePicker.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface LanguageOption {
+  value: string;
+  label: string;
+}
+
+const DEFAULT_LANGUAGES: LanguageOption[] = [
+  { value: 'en-US', label: 'English (US)' },
+  { value: 'en-GB', label: 'English (UK)' },
+  { value: 'ru-RU', label: 'Русский' },
+  { value: 'ko-KR', label: '한국어' },
+  { value: 'ja-JP', label: '日本語' },
+  { value: 'zh-CN', label: '中文 (简体)' },
+  { value: 'es-ES', label: 'Español' },
+  { value: 'fr-FR', label: 'Français' },
+  { value: 'de-DE', label: 'Deutsch' },
+];
+
+export interface LanguagePickerProps {
+  value: string;
+  onChange: (value: string) => void;
+  options?: LanguageOption[];
+  className?: string;
+  disabled?: boolean;
+  ariaLabel?: string;
+}
+
+export function LanguagePicker({
+  value,
+  onChange,
+  options = DEFAULT_LANGUAGES,
+  className,
+  disabled,
+  ariaLabel = 'Recognition language',
+}: LanguagePickerProps): React.ReactElement {
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={cn(
+        'h-8 rounded-md border border-input bg-background px-2 text-xs text-foreground',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+    >
+      {options.map((o) => (
+        <option key={o.value} value={o.value}>
+          {o.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+export { DEFAULT_LANGUAGES };

package/src/tools/SpeechRecognition/components/MicMeter.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface MicMeterProps {
+  /** RMS level 0..1 (use the value returned by `useMicLevel`). */
+  level: number;
+  /** Number of bars rendered. @default 12 */
+  bars?: number;
+  /** Bar gap in px. @default 2 */
+  gap?: number;
+  /** Bar width in px. @default 3 */
+  barWidth?: number;
+  /** Container height in px. @default 24 */
+  height?: number;
+  className?: string;
+}
+
+/**
+ * Discrete-bar VU meter — small, dependency-free, no canvas. Each bar
+ * lights up when the current `level` exceeds its threshold. Centre bars
+ * are tallest so the meter reads like a classic mic level indicator.
+ */
+export function MicMeter({
+  level,
+  bars = 12,
+  gap = 2,
+  barWidth = 3,
+  height = 24,
+  className,
+}: MicMeterProps): React.ReactElement {
+  const clamped = Math.min(1, Math.max(0, level));
+  return (
+    <div
+      role="meter"
+      aria-valuemin={0}
+      aria-valuemax={1}
+      aria-valuenow={clamped}
+      className={cn('inline-flex items-center', className)}
+      style={{ gap, height }}
+    >
+      {Array.from({ length: bars }).map((_, i) => {
+        const ratio = (i + 1) / bars;
+        const active = clamped >= ratio - 0.5 / bars;
+        // taller in the middle, shorter at edges
+        const heightRatio = 1 - Math.abs(i - (bars - 1) / 2) / ((bars - 1) / 2 || 1);
+        const barH = Math.max(2, height * (0.35 + heightRatio * 0.65));
+        return (
+          <span
+            key={i}
+            className={cn(
+              'rounded-sm transition-colors',
+              active ? 'bg-primary' : 'bg-border',
+            )}
+            style={{ width: barWidth, height: barH }}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/components/PushToTalkHint.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface PushToTalkHintProps {
+  /** Same chord string passed to `usePushToTalk`. */
+  chord: string;
+  className?: string;
+}
+
+/**
+ * Renders "Hold ⌥ to talk" with the chord pretty-printed. Tiny helper
+ * meant to live next to a `DictationButton`.
+ */
+export function PushToTalkHint({ chord, className }: PushToTalkHintProps): React.ReactElement {
+  const formatted = chord
+    .split('+')
+    .map((p) => p.trim().toLowerCase())
+    .map((p) => {
+      switch (p) {
+        case 'mod':
+        case 'meta':
+          return '⌘';
+        case 'alt':
+          return '⌥';
+        case 'shift':
+          return '⇧';
+        case 'ctrl':
+          return '⌃';
+        default:
+          return p.length === 1 ? p.toUpperCase() : p;
+      }
+    })
+    .join('');
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1 text-[11px] text-muted-foreground',
+        className,
+      )}
+    >
+      Hold
+      <kbd className="rounded border border-border bg-muted px-1 py-0.5 font-mono text-[10px] text-foreground">
+        {formatted}
+      </kbd>
+      to talk
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/components/TranscriptView.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { Transcript } from '../types';
+
+export interface TranscriptViewProps {
+  transcript: Transcript;
+  /** Render the empty state when there is nothing yet. */
+  emptyState?: React.ReactNode;
+  /** Tone the interim text down so users can tell it's still "wet". */
+  dimInterim?: boolean;
+  className?: string;
+}
+
+/**
+ * Two-tone transcript: final segments in foreground, the trailing
+ * interim chunk dimmed so users see the model "thinking". Pure
+ * presentational — pair with `useSpeechRecognition().transcript`.
+ */
+export function TranscriptView({
+  transcript,
+  emptyState,
+  dimInterim = true,
+  className,
+}: TranscriptViewProps): React.ReactElement {
+  const { final, interim } = transcript;
+  if (!final && !interim) {
+    return (
+      <div className={cn('text-sm text-muted-foreground', className)}>
+        {emptyState ?? 'Press the mic to start dictating…'}
+      </div>
+    );
+  }
+  return (
+    <div className={cn('text-sm leading-relaxed', className)}>
+      <span className="text-foreground whitespace-pre-wrap">{final}</span>
+      {interim && (
+        <>
+          {' '}
+          <span
+            className={cn(
+              'whitespace-pre-wrap',
+              dimInterim ? 'text-muted-foreground' : 'text-foreground',
+            )}
+          >
+            {interim}
+          </span>
+        </>
+      )}
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/components/index.ts

@@ -0,0 +1,16 @@
+export { DictationButton } from './DictationButton';
+export type { DictationButtonProps } from './DictationButton';
+export { MicMeter } from './MicMeter';
+export type { MicMeterProps } from './MicMeter';
+export { TranscriptView } from './TranscriptView';
+export type { TranscriptViewProps } from './TranscriptView';
+export { LanguagePicker, DEFAULT_LANGUAGES } from './LanguagePicker';
+export type { LanguagePickerProps, LanguageOption } from './LanguagePicker';
+export { DevicePicker } from './DevicePicker';
+export type { DevicePickerProps } from './DevicePicker';
+export { EngineBadge } from './EngineBadge';
+export type { EngineBadgeProps } from './EngineBadge';
+export { ErrorBanner } from './ErrorBanner';
+export type { ErrorBannerProps } from './ErrorBanner';
+export { PushToTalkHint } from './PushToTalkHint';
+export type { PushToTalkHintProps } from './PushToTalkHint';

package/src/tools/SpeechRecognition/context/SpeechRecognitionProvider.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import type * as React from 'react';
+import { createContext, useContext, useMemo } from 'react';
+
+import type { UseSpeechRecognitionConfig, UseSpeechRecognitionReturn } from '../types';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+
+const Ctx = createContext<UseSpeechRecognitionReturn | null>(null);
+
+export interface SpeechRecognitionProviderProps extends UseSpeechRecognitionConfig {
+  children?: React.ReactNode;
+}
+
+/**
+ * Lifts a single `useSpeechRecognition` instance into a context so any
+ * descendant — composer slot, header badge, transcript overlay — can
+ * read the same status / transcript / level without each component
+ * spinning up its own engine. Mount it once per Chat (or per
+ * dictation-aware screen).
+ */
+export function SpeechRecognitionProvider({
+  children,
+  ...config
+}: SpeechRecognitionProviderProps): React.ReactElement {
+  const rec = useSpeechRecognition(config);
+  // Memo prevents context-value churn from leaking through to every
+  // useContext consumer when only one of {status, level, transcript}
+  // changes — React already triggers them via the inner state, the
+  // outer object identity should stay stable across renders.
+  const value = useMemo(() => rec, [rec]);
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useSpeechRecognitionContext(): UseSpeechRecognitionReturn {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error(
+      'useSpeechRecognitionContext must be used inside a <SpeechRecognitionProvider>.',
+    );
+  }
+  return ctx;
+}
+
+export function useSpeechRecognitionContextOptional(): UseSpeechRecognitionReturn | null {
+  return useContext(Ctx);
+}

package/src/tools/SpeechRecognition/context/index.ts

@@ -0,0 +1,6 @@
+export {
+  SpeechRecognitionProvider,
+  useSpeechRecognitionContext,
+  useSpeechRecognitionContextOptional,
+} from './SpeechRecognitionProvider';
+export type { SpeechRecognitionProviderProps } from './SpeechRecognitionProvider';

package/src/tools/SpeechRecognition/core/audio/defaults.ts

@@ -0,0 +1,24 @@
+/**
+ * Default earcons for speech sessions. We reuse two of the bundled
+ * Chat notification sounds rather than ship new MP3s — same lazy chunk
+ * already pays for them, and the tonal palette stays consistent across
+ * the chat + dictation UI.
+ *
+ *  - `start` → the chat "stream start" chime (calm low-key tone).
+ *  - `stop`  → the chat "sent" tick (2KB, very short — feels like
+ *              "captured" rather than a notification ping).
+ *    Previously used `notification.mp3` (30KB, long, loud) which was
+ *    too attention-grabbing for a self-initiated action.
+ *
+ * Loaded as `dataurl` by tsup (see `tsup.config.ts`), so consumers get
+ * working audio with zero asset setup.
+ */
+import start from '../../../Chat/core/audio/sounds/start.mp3';
+import sent from '../../../Chat/core/audio/sounds/sent.mp3';
+
+export type VoiceSoundEvent = 'start' | 'stop';
+
+export const DEFAULT_VOICE_SOUNDS: Record<VoiceSoundEvent, string> = {
+  start,
+  stop: sent,
+};

package/src/tools/SpeechRecognition/core/engine/external.ts

@@ -0,0 +1,222 @@
+/**
+ * External-controlled engine — for backends that own the entire
+ * record / decode / transcribe pipeline (Wails / Tauri / native
+ * sidecar). The frontend exposes "start" and "stop" verbs to the
+ * native layer, which then pushes a single `final` (or rolling
+ * `partial`s + `final`) back through events.
+ *
+ * Use this when:
+ *   - Audio capture lives outside the browser (cmdop_go OS-wide
+ *     hotkey, system audio device claims, etc.).
+ *   - Transcription runs on the backend (whisper.cpp, Vosk, custom
+ *     ONNX) and the browser never sees the raw audio.
+ *
+ * Compared to `createHttpEngine`/`createWebSocketEngine`:
+ *   - No `MediaRecorder` / `getUserMedia` involvement.
+ *   - `isSupported` defaults to `true` (the host knows whether the
+ *     native side is present — let it gate via `supported`).
+ *   - No `MediaStream` to expose, so the VU meter falls through to
+ *     the host's own level event (cmdop wires it via a separate hook).
+ */
+
+import { newSegmentId } from '../ids';
+import { sttLogger } from '../logger';
+import { createEngineBus } from './index';
+import type {
+  EngineStartOptions,
+  RecognitionEngine,
+  RecognitionError,
+  Unsub,
+} from '../../types';
+
+export interface ExternalEngineHandle {
+  /**
+   * Push an interim transcript fragment. Wrapped into a `partial`
+   * event with a generated segment id. Subsequent calls before
+   * `emitFinal` mutate the same interim segment.
+   */
+  emitPartial(text: string): void;
+  /**
+   * Push the final transcript. Closes the current segment; the engine
+   * emits `final` then transitions to `closed`.
+   */
+  emitFinal(text: string, confidence?: number): void;
+  /** Surface a backend error. Engine transitions to `closed`. */
+  emitError(err: RecognitionError): void;
+  /**
+   * Notify the engine that the native side actually started capturing.
+   * Flips status to `listening`. Call from a backend `recording`
+   * event. Optional — see `autoMarkListening`.
+   */
+  markListening(): void;
+}
+
+export interface ExternalEngineOptions {
+  /** Stable engine id for telemetry / UI badge. */
+  id?: string;
+  /**
+   * Whether the host believes the native side is available. Wire to
+   * a Wails ping / Tauri capability check. Defaults to `true`.
+   */
+  supported?: boolean;
+  /** Ask the backend to start capture. */
+  onStart: (opts: EngineStartOptions) => Promise<void> | void;
+  /** Ask the backend to stop capture (and finalise the buffer). */
+  onStop: () => Promise<void> | void;
+  /**
+   * Optional hard cancel — `onStop` may finalise, while `onAbort`
+   * discards. Falls back to `onStop` when omitted.
+   */
+  onAbort?: () => Promise<void> | void;
+  /**
+   * Subscribe to backend events. Called once per `start()`. The host
+   * wires its native event source (Wails `EventsOn`, Tauri
+   * `appWindow.listen`, …) and uses the supplied `handle` to push
+   * transcript fragments through the engine bus.
+   *
+   * Must return an unsubscribe function so the engine can detach on
+   * teardown.
+   */
+  subscribe: (handle: ExternalEngineHandle) => Unsub;
+  /**
+   * If `true` (default), the engine flips state to `listening` right
+   * after `onStart` resolves. Set `false` and call
+   * `handle.markListening()` explicitly when you want to wait for the
+   * native side to confirm the capture session opened.
+   */
+  autoMarkListening?: boolean;
+}
+
+/**
+ * Wraps a backend-driven STT pipeline into the standard
+ * `RecognitionEngine` shape so it works with `useSpeechRecognition`,
+ * `VoiceComposerSlot`, and every other piece of the SpeechRecognition
+ * tool.
+ *
+ * Example (cmdop Wails):
+ *
+ * ```ts
+ * import { EventsOn } from '@runtime';
+ * import * as VoiceService from '@bindings/desktop/services/voice/service';
+ *
+ * const engine = createExternalEngine({
+ *   id: 'wails-whisper',
+ *   onStart: () => VoiceService.StartRecordingForChat(),
+ *   onStop: () => VoiceService.StopRecordingForChat(),
+ *   subscribe: (handle) => {
+ *     const offText = EventsOn('voice:chat-text', (p) => {
+ *       if (p?.error) handle.emitError({ code: 'engine', message: p.error });
+ *       else if (p?.text) handle.emitFinal(p.text);
+ *       else handle.emitError({ code: 'no-speech', message: '' });
+ *     });
+ *     const offState = EventsOn('voice:state', (s) => {
+ *       if (s.state === 'recording' || s.state === 'streaming') {
+ *         handle.markListening();
+ *       }
+ *       if (s.partial) handle.emitPartial(s.partial);
+ *     });
+ *     return () => { offText(); offState(); };
+ *   },
+ * });
+ * ```
+ */
+export function createExternalEngine(
+  opts: ExternalEngineOptions,
+): RecognitionEngine {
+  const bus = createEngineBus();
+  let currentSegmentId: string | null = null;
+  let unsubscribe: Unsub | null = null;
+  let running = false;
+
+  function teardown(): void {
+    unsubscribe?.();
+    unsubscribe = null;
+    currentSegmentId = null;
+    running = false;
+  }
+
+  const handle: ExternalEngineHandle = {
+    emitPartial(text: string): void {
+      if (!running) return;
+      if (!currentSegmentId) currentSegmentId = newSegmentId();
+      bus.emit('partial', text, currentSegmentId);
+    },
+    emitFinal(text: string, confidence?: number): void {
+      if (!running) return;
+      const id = currentSegmentId ?? newSegmentId();
+      bus.emit('final', text, id, confidence);
+      // External engines almost always go idle right after their
+      // final — close the session so consumers' `onStop` fires
+      // without requiring a separate `stop()` call.
+      bus.emit('state', 'closed');
+      teardown();
+    },
+    emitError(err: RecognitionError): void {
+      bus.emit('error', err);
+      bus.emit('state', 'closed');
+      teardown();
+    },
+    markListening(): void {
+      if (!running) return;
+      bus.emit('state', 'listening');
+    },
+  };
+
+  return {
+    id: opts.id ?? 'external',
+    isSupported: opts.supported ?? true,
+    on(event, cb): Unsub {
+      return bus.on(event, cb);
+    },
+    async start(start: EngineStartOptions): Promise<void> {
+      if (running) return;
+      running = true;
+      bus.emit('state', 'connecting');
+      // Subscribe before the native side starts so we never miss the
+      // first event (some backends emit `recording` synchronously).
+      unsubscribe = opts.subscribe(handle);
+      try {
+        await opts.onStart(start);
+      } catch (cause) {
+        const err: RecognitionError = {
+          code: 'engine',
+          message: 'External engine failed to start.',
+          cause,
+        };
+        bus.emit('error', err);
+        bus.emit('state', 'closed');
+        teardown();
+        throw err;
+      }
+      if (opts.autoMarkListening !== false) {
+        bus.emit('state', 'listening');
+      }
+      start.signal?.addEventListener('abort', () => {
+        this.abort();
+      });
+    },
+    async stop(): Promise<void> {
+      if (!running) return;
+      bus.emit('state', 'closing');
+      try {
+        await opts.onStop();
+      } catch (cause) {
+        sttLogger.warn('[external] onStop threw', cause);
+      }
+      // Note: we DO NOT flip to `closed` here — most external engines
+      // need a roundtrip (transcribe + LLM rewrite) before the final
+      // text arrives. `emitFinal` / `emitError` are responsible for
+      // closing the session.
+    },
+    abort(): void {
+      if (!running) return;
+      bus.emit('state', 'closing');
+      const stopper = opts.onAbort ?? opts.onStop;
+      Promise.resolve(stopper()).catch((cause) => {
+        sttLogger.warn('[external] abort hook threw', cause);
+      });
+      bus.emit('state', 'closed');
+      teardown();
+    },
+  };
+}