@speechos/react 1.0.10 → 1.0.11

package/dist/context.d.cts

@@ -6,8 +6,7 @@
  */
 import React, { type ReactNode } from "react";
 import { type SpeechOSCoreConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn, type CommandDefinition, type CommandResult } from "@speechos/core";
-import type { FormDetectorInterface } from "@speechos/client";
-import type { TextInputHandlerInterface } from "@speechos/client";
+import type { FormDetectorInterface, TextInputHandlerInterface, ReadAloudConfig } from "@speechos/client";
 /**
  * Context value exposed by SpeechOSProvider
  */
@@ -19,8 +18,8 @@ export interface SpeechOSContextValue {
     stopDictation: () => Promise<string>;
     edit: (text: string) => Promise<string>;
     stopEdit: () => Promise<string>;
-    command: (commands: CommandDefinition[]) => Promise<CommandResult | null>;
-    stopCommand: () => Promise<CommandResult | null>;
+    command: (commands: CommandDefinition[]) => Promise<CommandResult[]>;
+    stopCommand: () => Promise<CommandResult[]>;
     cancel: () => Promise<void>;
     on: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => UnsubscribeFn;
     off: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => void;
@@ -55,6 +54,13 @@ export interface SpeechOSReactConfig extends SpeechOSCoreConfig {
      * Default: false
      */
     useExternalSettings?: boolean;
+    /**
+     * Read-aloud behavior for selected text.
+     * - true (default): enable with defaults
+     * - false: disable read-aloud
+     * - ReadAloudConfig: customize behavior
+     */
+    readAloud?: boolean | ReadAloudConfig;
 }
 /**
  * Props for SpeechOSProvider

package/dist/context.d.ts

@@ -6,8 +6,7 @@
  */
 import React, { type ReactNode } from "react";
 import { type SpeechOSCoreConfig, type SpeechOSState, type SpeechOSEventMap, type UnsubscribeFn, type CommandDefinition, type CommandResult } from "@speechos/core";
-import type { FormDetectorInterface } from "@speechos/client";
-import type { TextInputHandlerInterface } from "@speechos/client";
+import type { FormDetectorInterface, TextInputHandlerInterface, ReadAloudConfig } from "@speechos/client";
 /**
  * Context value exposed by SpeechOSProvider
  */
@@ -19,8 +18,8 @@ export interface SpeechOSContextValue {
     stopDictation: () => Promise<string>;
     edit: (text: string) => Promise<string>;
     stopEdit: () => Promise<string>;
-    command: (commands: CommandDefinition[]) => Promise<CommandResult | null>;
-    stopCommand: () => Promise<CommandResult | null>;
+    command: (commands: CommandDefinition[]) => Promise<CommandResult[]>;
+    stopCommand: () => Promise<CommandResult[]>;
     cancel: () => Promise<void>;
     on: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => UnsubscribeFn;
     off: <K extends keyof SpeechOSEventMap>(event: K, callback: (payload: SpeechOSEventMap[K]) => void) => void;
@@ -55,6 +54,13 @@ export interface SpeechOSReactConfig extends SpeechOSCoreConfig {
      * Default: false
      */
     useExternalSettings?: boolean;
+    /**
+     * Read-aloud behavior for selected text.
+     * - true (default): enable with defaults
+     * - false: disable read-aloud
+     * - ReadAloudConfig: customize behavior
+     */
+    readAloud?: boolean | ReadAloudConfig;
 }
 /**
  * Props for SpeechOSProvider

package/dist/hooks/index.d.cts

@@ -9,4 +9,5 @@ export { useSpeechOSEvents } from "./useSpeechOSEvents.js";
 export { useDictation, type UseDictationResult } from "./useDictation.js";
 export { useEdit, type UseEditResult } from "./useEdit.js";
 export { useCommand, type UseCommandResult } from "./useCommand.js";
+export { useTTS, type UseTTSResult, type SpeakOptions } from "./useTTS.js";
 export { useSpeechOSWidget, type UseSpeechOSWidgetResult } from "./useSpeechOSWidget.js";

package/dist/hooks/index.d.ts

@@ -9,4 +9,5 @@ export { useSpeechOSEvents } from "./useSpeechOSEvents.js";
 export { useDictation, type UseDictationResult } from "./useDictation.js";
 export { useEdit, type UseEditResult } from "./useEdit.js";
 export { useCommand, type UseCommandResult } from "./useCommand.js";
+export { useTTS, type UseTTSResult, type SpeakOptions } from "./useTTS.js";
 export { useSpeechOSWidget, type UseSpeechOSWidgetResult } from "./useSpeechOSWidget.js";

package/dist/hooks/useCommand.d.cts

@@ -10,24 +10,25 @@ import type { CommandDefinition, CommandResult } from "@speechos/core";
 export interface UseCommandResult {
     /** Start command listening - begins recording */
     start: (commands: CommandDefinition[]) => Promise<void>;
-    /** Stop command listening - ends recording and returns matched command */
-    stop: () => Promise<CommandResult | null>;
+    /** Stop command listening - ends recording and returns matched commands */
+    stop: () => Promise<CommandResult[]>;
     /** Whether currently listening for commands */
     isListening: boolean;
     /** Whether processing the command */
     isProcessing: boolean;
-    /** The matched command result (null if no match or not yet processed) */
-    result: CommandResult | null;
+    /** The matched command results (empty array if no matches or not yet processed) */
+    results: CommandResult[];
     /** Any error that occurred */
     error: string | null;
-    /** Clear the result and error state */
+    /** Clear the results and error state */
     clear: () => void;
 }
 /**
  * Simplified hook for voice command workflows
  *
  * Provides an easy-to-use interface for voice command matching
- * with automatic state management.
+ * with automatic state management. Supports matching multiple
+ * commands from a single voice input.
  *
  * @example
  * ```tsx
@@ -42,7 +43,7 @@ export interface UseCommandResult {
  * ];
  *
  * function VoiceCommands() {
- *   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+ *   const { start, stop, isListening, isProcessing, results, error } = useCommand();
  *
  *   const handleCommand = async () => {
  *     await start(commands);
@@ -50,9 +51,9 @@ export interface UseCommandResult {
  *
  *   const handleStop = async () => {
  *     const matched = await stop();
- *     if (matched) {
- *       console.log('Matched command:', matched.name, matched.arguments);
- *     }
+ *     matched.forEach(cmd => {
+ *       console.log('Matched command:', cmd.name, cmd.arguments);
+ *     });
  *   };
  *
  *   return (
@@ -61,7 +62,11 @@ export interface UseCommandResult {
  *         {isListening ? 'Execute' : 'Say Command'}
  *       </button>
  *       {isProcessing && <span>Processing...</span>}
- *       {result && <p>Command: {result.name}</p>}
+ *       {results.length > 0 && (
+ *         <div>
+ *           {results.map((cmd, i) => <p key={i}>Command: {cmd.name}</p>)}
+ *         </div>
+ *       )}
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
  *     </div>
  *   );

package/dist/hooks/useCommand.d.ts

@@ -10,24 +10,25 @@ import type { CommandDefinition, CommandResult } from "@speechos/core";
 export interface UseCommandResult {
     /** Start command listening - begins recording */
     start: (commands: CommandDefinition[]) => Promise<void>;
-    /** Stop command listening - ends recording and returns matched command */
-    stop: () => Promise<CommandResult | null>;
+    /** Stop command listening - ends recording and returns matched commands */
+    stop: () => Promise<CommandResult[]>;
     /** Whether currently listening for commands */
     isListening: boolean;
     /** Whether processing the command */
     isProcessing: boolean;
-    /** The matched command result (null if no match or not yet processed) */
-    result: CommandResult | null;
+    /** The matched command results (empty array if no matches or not yet processed) */
+    results: CommandResult[];
     /** Any error that occurred */
     error: string | null;
-    /** Clear the result and error state */
+    /** Clear the results and error state */
     clear: () => void;
 }
 /**
  * Simplified hook for voice command workflows
  *
  * Provides an easy-to-use interface for voice command matching
- * with automatic state management.
+ * with automatic state management. Supports matching multiple
+ * commands from a single voice input.
  *
  * @example
  * ```tsx
@@ -42,7 +43,7 @@ export interface UseCommandResult {
  * ];
  *
  * function VoiceCommands() {
- *   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+ *   const { start, stop, isListening, isProcessing, results, error } = useCommand();
  *
  *   const handleCommand = async () => {
  *     await start(commands);
@@ -50,9 +51,9 @@ export interface UseCommandResult {
  *
  *   const handleStop = async () => {
  *     const matched = await stop();
- *     if (matched) {
- *       console.log('Matched command:', matched.name, matched.arguments);
- *     }
+ *     matched.forEach(cmd => {
+ *       console.log('Matched command:', cmd.name, cmd.arguments);
+ *     });
  *   };
  *
  *   return (
@@ -61,7 +62,11 @@ export interface UseCommandResult {
  *         {isListening ? 'Execute' : 'Say Command'}
  *       </button>
  *       {isProcessing && <span>Processing...</span>}
- *       {result && <p>Command: {result.name}</p>}
+ *       {results.length > 0 && (
+ *         <div>
+ *           {results.map((cmd, i) => <p key={i}>Command: {cmd.name}</p>)}
+ *         </div>
+ *       )}
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
  *     </div>
  *   );

package/dist/hooks/useTTS.d.cts

@@ -0,0 +1,59 @@
+/**
+ * useTTS - React hook for text-to-speech
+ *
+ * Provides a simple interface for TTS synthesis and playback.
+ */
+import { type TTSOptions, type TTSResult } from "@speechos/core";
+/**
+ * Return type for useTTS hook
+ */
+export interface UseTTSResult {
+    /** Synthesize text and play audio immediately */
+    speak: (text: string, options?: SpeakOptions) => Promise<void>;
+    /** Synthesize text and return audio bytes */
+    synthesize: (text: string, options?: TTSOptions) => Promise<TTSResult>;
+    /** Stop current playback */
+    stop: () => void;
+    /** Whether currently synthesizing (HTTP request in progress) */
+    isSynthesizing: boolean;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** The last synthesized audio result (from synthesize()) */
+    audioResult: TTSResult | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear error and audio result state */
+    clear: () => void;
+}
+/**
+ * Options for speaking text (extends TTSOptions with playback options)
+ */
+export interface SpeakOptions extends TTSOptions {
+    /** Output audio device ID (if supported by browser) */
+    audioDeviceId?: string;
+}
+/**
+ * React hook for text-to-speech
+ *
+ * Provides an easy-to-use interface for TTS synthesis and playback
+ * with automatic state management.
+ *
+ * @example
+ * ```tsx
+ * function TTSButton() {
+ *   const { speak, stop, isSynthesizing, isPlaying, error } = useTTS();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => speak('Hello!')}>
+ *         {isSynthesizing ? 'Loading...' : isPlaying ? 'Stop' : 'Speak'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns TTS controls and state
+ */
+export declare function useTTS(): UseTTSResult;

package/dist/hooks/useTTS.d.ts

@@ -0,0 +1,59 @@
+/**
+ * useTTS - React hook for text-to-speech
+ *
+ * Provides a simple interface for TTS synthesis and playback.
+ */
+import { type TTSOptions, type TTSResult } from "@speechos/core";
+/**
+ * Return type for useTTS hook
+ */
+export interface UseTTSResult {
+    /** Synthesize text and play audio immediately */
+    speak: (text: string, options?: SpeakOptions) => Promise<void>;
+    /** Synthesize text and return audio bytes */
+    synthesize: (text: string, options?: TTSOptions) => Promise<TTSResult>;
+    /** Stop current playback */
+    stop: () => void;
+    /** Whether currently synthesizing (HTTP request in progress) */
+    isSynthesizing: boolean;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** The last synthesized audio result (from synthesize()) */
+    audioResult: TTSResult | null;
+    /** Any error that occurred */
+    error: string | null;
+    /** Clear error and audio result state */
+    clear: () => void;
+}
+/**
+ * Options for speaking text (extends TTSOptions with playback options)
+ */
+export interface SpeakOptions extends TTSOptions {
+    /** Output audio device ID (if supported by browser) */
+    audioDeviceId?: string;
+}
+/**
+ * React hook for text-to-speech
+ *
+ * Provides an easy-to-use interface for TTS synthesis and playback
+ * with automatic state management.
+ *
+ * @example
+ * ```tsx
+ * function TTSButton() {
+ *   const { speak, stop, isSynthesizing, isPlaying, error } = useTTS();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => speak('Hello!')}>
+ *         {isSynthesizing ? 'Loading...' : isPlaying ? 'Stop' : 'Speak'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @returns TTS controls and state
+ */
+export declare function useTTS(): UseTTSResult;

package/dist/index.cjs

@@ -339,7 +339,8 @@ function useEdit() {
 * Simplified hook for voice command workflows
 *
 * Provides an easy-to-use interface for voice command matching
-* with automatic state management.
+* with automatic state management. Supports matching multiple
+* commands from a single voice input.
 *
 * @example
 * ```tsx
@@ -354,7 +355,7 @@ function useEdit() {
 * ];
 *
 * function VoiceCommands() {
-*   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+*   const { start, stop, isListening, isProcessing, results, error } = useCommand();
 *
 *   const handleCommand = async () => {
 *     await start(commands);
@@ -362,9 +363,9 @@ function useEdit() {
 *
 *   const handleStop = async () => {
 *     const matched = await stop();
-*     if (matched) {
-*       console.log('Matched command:', matched.name, matched.arguments);
-*     }
+*     matched.forEach(cmd => {
+*       console.log('Matched command:', cmd.name, cmd.arguments);
+*     });
 *   };
 *
 *   return (
@@ -373,7 +374,11 @@ function useEdit() {
 *         {isListening ? 'Execute' : 'Say Command'}
 *       </button>
 *       {isProcessing && <span>Processing...</span>}
-*       {result && <p>Command: {result.name}</p>}
+*       {results.length > 0 && (
+*         <div>
+*           {results.map((cmd, i) => <p key={i}>Command: {cmd.name}</p>)}
+*         </div>
+*       )}
 *       {error && <p style={{ color: 'red' }}>{error}</p>}
 *     </div>
 *   );
@@ -384,7 +389,7 @@ function useEdit() {
 */
 function useCommand() {
 	const { state: state$2, command, stopCommand } = useSpeechOSContext();
-	const [result, setResult] = (0, react.useState)(null);
+	const [results, setResults] = (0, react.useState)([]);
 	const [error, setError] = (0, react.useState)(null);
 	const isListening = state$2.recordingState === "recording" && state$2.activeAction === "command";
 	const isProcessing = state$2.recordingState === "processing";
@@ -399,10 +404,10 @@ function useCommand() {
 	}, [command]);
 	const stop = (0, react.useCallback)(async () => {
 		try {
-			const commandResult = await stopCommand();
-			setResult(commandResult);
+			const commandResults = await stopCommand();
+			setResults(commandResults);
 			setError(null);
-			return commandResult;
+			return commandResults;
 		} catch (err) {
 			const message = err instanceof Error ? err.message : "Failed to process command";
 			setError(message);
@@ -410,7 +415,7 @@ function useCommand() {
 		}
 	}, [stopCommand]);
 	const clear = (0, react.useCallback)(() => {
-		setResult(null);
+		setResults([]);
 		setError(null);
 	}, []);
 	return {
@@ -418,7 +423,124 @@ function useCommand() {
 		stop,
 		isListening,
 		isProcessing,
-		result,
+		results,
+		error,
+		clear
+	};
+}
+
+//#endregion
+//#region src/hooks/useTTS.ts
+let clientTTS = null;
+async function getClientTTS() {
+	if (clientTTS) return clientTTS;
+	try {
+		const client = await import("@speechos/client");
+		clientTTS = client.tts;
+		return clientTTS;
+	} catch {
+		return null;
+	}
+}
+/**
+* React hook for text-to-speech
+*
+* Provides an easy-to-use interface for TTS synthesis and playback
+* with automatic state management.
+*
+* @example
+* ```tsx
+* function TTSButton() {
+*   const { speak, stop, isSynthesizing, isPlaying, error } = useTTS();
+*
+*   return (
+*     <div>
+*       <button onClick={() => speak('Hello!')}>
+*         {isSynthesizing ? 'Loading...' : isPlaying ? 'Stop' : 'Speak'}
+*       </button>
+*       {error && <p style={{ color: 'red' }}>{error}</p>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns TTS controls and state
+*/
+function useTTS() {
+	const [isSynthesizing, setIsSynthesizing] = (0, react.useState)(false);
+	const [isPlaying, setIsPlaying] = (0, react.useState)(false);
+	const [audioResult, setAudioResult] = (0, react.useState)(null);
+	const [error, setError] = (0, react.useState)(null);
+	(0, react.useEffect)(() => {
+		const unsubStart = __speechos_core.events.on("tts:playback:start", () => {
+			setIsPlaying(true);
+		});
+		const unsubComplete = __speechos_core.events.on("tts:playback:complete", () => {
+			setIsPlaying(false);
+		});
+		const unsubStop = __speechos_core.events.on("tts:playback:stop", () => {
+			setIsPlaying(false);
+		});
+		const unsubError = __speechos_core.events.on("tts:error", ({ message, phase }) => {
+			if (phase === "playback") setIsPlaying(false);
+			setError(message);
+		});
+		return () => {
+			unsubStart();
+			unsubComplete();
+			unsubStop();
+			unsubError();
+		};
+	}, []);
+	const speak = (0, react.useCallback)(async (text, options) => {
+		setError(null);
+		setIsSynthesizing(true);
+		try {
+			const client = await getClientTTS();
+			if (client) await client.speak(text, options);
+			else {
+				await __speechos_core.tts.synthesize(text, options);
+				console.warn("[useTTS] @speechos/client not available, audio not played");
+			}
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "TTS failed";
+			setError(message);
+			throw err;
+		} finally {
+			setIsSynthesizing(false);
+		}
+	}, []);
+	const synthesize = (0, react.useCallback)(async (text, options) => {
+		setError(null);
+		setIsSynthesizing(true);
+		try {
+			const result = await __speechos_core.tts.synthesize(text, options);
+			setAudioResult(result);
+			return result;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Synthesis failed";
+			setError(message);
+			throw err;
+		} finally {
+			setIsSynthesizing(false);
+		}
+	}, []);
+	const stop = (0, react.useCallback)(async () => {
+		const client = await getClientTTS();
+		if (client) client.stop();
+		setIsPlaying(false);
+	}, []);
+	const clear = (0, react.useCallback)(() => {
+		setAudioResult(null);
+		setError(null);
+	}, []);
+	return {
+		speak,
+		synthesize,
+		stop,
+		isSynthesizing,
+		isPlaying,
+		audioResult,
 		error,
 		clear
 	};
@@ -599,4 +721,5 @@ exports.useSpeechOS = useSpeechOS;
 exports.useSpeechOSContext = useSpeechOSContext;
 exports.useSpeechOSEvents = useSpeechOSEvents;
 exports.useSpeechOSState = useSpeechOSState;
-exports.useSpeechOSWidget = useSpeechOSWidget;
+exports.useSpeechOSWidget = useSpeechOSWidget;
+exports.useTTS = useTTS;

package/dist/index.d.cts

@@ -37,8 +37,8 @@
  *
  */
 export { SpeechOSProvider, SpeechOSContext, useSpeechOSContext, type SpeechOSContextValue, type SpeechOSProviderProps, type SpeechOSReactConfig, } from "./context.js";
-export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useCommand, useSpeechOSWidget, type UseDictationResult, type UseEditResult, type UseCommandResult, type UseSpeechOSWidgetResult, } from "./hooks/index.js";
+export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useCommand, useTTS, useSpeechOSWidget, type UseDictationResult, type UseEditResult, type UseCommandResult, type UseTTSResult, type SpeakOptions, type UseSpeechOSWidgetResult, } from "./hooks/index.js";
 export { SpeechOSWidget, type SpeechOSWidgetProps, } from "./components/index.js";
-export type { SpeechOSCoreConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, CommandArgument, CommandDefinition, CommandResult, } from "@speechos/core";
+export type { SpeechOSCoreConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, CommandArgument, CommandDefinition, CommandResult, TTSOptions, TTSResult, } from "@speechos/core";
 export type { SpeechOSCoreConfig as SpeechOSConfig } from "@speechos/core";
 export declare const VERSION = "0.1.0";

package/dist/index.d.ts

@@ -37,8 +37,8 @@
  *
  */
 export { SpeechOSProvider, SpeechOSContext, useSpeechOSContext, type SpeechOSContextValue, type SpeechOSProviderProps, type SpeechOSReactConfig, } from "./context.js";
-export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useCommand, useSpeechOSWidget, type UseDictationResult, type UseEditResult, type UseCommandResult, type UseSpeechOSWidgetResult, } from "./hooks/index.js";
+export { useSpeechOS, useSpeechOSState, useSpeechOSEvents, useDictation, useEdit, useCommand, useTTS, useSpeechOSWidget, type UseDictationResult, type UseEditResult, type UseCommandResult, type UseTTSResult, type SpeakOptions, type UseSpeechOSWidgetResult, } from "./hooks/index.js";
 export { SpeechOSWidget, type SpeechOSWidgetProps, } from "./components/index.js";
-export type { SpeechOSCoreConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, CommandArgument, CommandDefinition, CommandResult, } from "@speechos/core";
+export type { SpeechOSCoreConfig, SpeechOSState, SpeechOSAction, SpeechOSEventMap, RecordingState, UnsubscribeFn, CommandArgument, CommandDefinition, CommandResult, TTSOptions, TTSResult, } from "@speechos/core";
 export type { SpeechOSCoreConfig as SpeechOSConfig } from "@speechos/core";
 export declare const VERSION = "0.1.0";

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { events, speechOS, state } from "@speechos/core";
+import { events, speechOS, state, tts } from "@speechos/core";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/context.tsx
@@ -316,7 +316,8 @@ function useEdit() {
 * Simplified hook for voice command workflows
 *
 * Provides an easy-to-use interface for voice command matching
-* with automatic state management.
+* with automatic state management. Supports matching multiple
+* commands from a single voice input.
 *
 * @example
 * ```tsx
@@ -331,7 +332,7 @@ function useEdit() {
 * ];
 *
 * function VoiceCommands() {
-*   const { start, stop, isListening, isProcessing, result, error } = useCommand();
+*   const { start, stop, isListening, isProcessing, results, error } = useCommand();
 *
 *   const handleCommand = async () => {
 *     await start(commands);
@@ -339,9 +340,9 @@ function useEdit() {
 *
 *   const handleStop = async () => {
 *     const matched = await stop();
-*     if (matched) {
-*       console.log('Matched command:', matched.name, matched.arguments);
-*     }
+*     matched.forEach(cmd => {
+*       console.log('Matched command:', cmd.name, cmd.arguments);
+*     });
 *   };
 *
 *   return (
@@ -350,7 +351,11 @@ function useEdit() {
 *         {isListening ? 'Execute' : 'Say Command'}
 *       </button>
 *       {isProcessing && <span>Processing...</span>}
-*       {result && <p>Command: {result.name}</p>}
+*       {results.length > 0 && (
+*         <div>
+*           {results.map((cmd, i) => <p key={i}>Command: {cmd.name}</p>)}
+*         </div>
+*       )}
 *       {error && <p style={{ color: 'red' }}>{error}</p>}
 *     </div>
 *   );
@@ -361,7 +366,7 @@ function useEdit() {
 */
 function useCommand() {
 	const { state: state$1, command, stopCommand } = useSpeechOSContext();
-	const [result, setResult] = useState(null);
+	const [results, setResults] = useState([]);
 	const [error, setError] = useState(null);
 	const isListening = state$1.recordingState === "recording" && state$1.activeAction === "command";
 	const isProcessing = state$1.recordingState === "processing";
@@ -376,10 +381,10 @@ function useCommand() {
 	}, [command]);
 	const stop = useCallback(async () => {
 		try {
-			const commandResult = await stopCommand();
-			setResult(commandResult);
+			const commandResults = await stopCommand();
+			setResults(commandResults);
 			setError(null);
-			return commandResult;
+			return commandResults;
 		} catch (err) {
 			const message = err instanceof Error ? err.message : "Failed to process command";
 			setError(message);
@@ -387,7 +392,7 @@ function useCommand() {
 		}
 	}, [stopCommand]);
 	const clear = useCallback(() => {
-		setResult(null);
+		setResults([]);
 		setError(null);
 	}, []);
 	return {
@@ -395,7 +400,124 @@ function useCommand() {
 		stop,
 		isListening,
 		isProcessing,
-		result,
+		results,
+		error,
+		clear
+	};
+}
+
+//#endregion
+//#region src/hooks/useTTS.ts
+let clientTTS = null;
+async function getClientTTS() {
+	if (clientTTS) return clientTTS;
+	try {
+		const client = await import("@speechos/client");
+		clientTTS = client.tts;
+		return clientTTS;
+	} catch {
+		return null;
+	}
+}
+/**
+* React hook for text-to-speech
+*
+* Provides an easy-to-use interface for TTS synthesis and playback
+* with automatic state management.
+*
+* @example
+* ```tsx
+* function TTSButton() {
+*   const { speak, stop, isSynthesizing, isPlaying, error } = useTTS();
+*
+*   return (
+*     <div>
+*       <button onClick={() => speak('Hello!')}>
+*         {isSynthesizing ? 'Loading...' : isPlaying ? 'Stop' : 'Speak'}
+*       </button>
+*       {error && <p style={{ color: 'red' }}>{error}</p>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns TTS controls and state
+*/
+function useTTS() {
+	const [isSynthesizing, setIsSynthesizing] = useState(false);
+	const [isPlaying, setIsPlaying] = useState(false);
+	const [audioResult, setAudioResult] = useState(null);
+	const [error, setError] = useState(null);
+	useEffect(() => {
+		const unsubStart = events.on("tts:playback:start", () => {
+			setIsPlaying(true);
+		});
+		const unsubComplete = events.on("tts:playback:complete", () => {
+			setIsPlaying(false);
+		});
+		const unsubStop = events.on("tts:playback:stop", () => {
+			setIsPlaying(false);
+		});
+		const unsubError = events.on("tts:error", ({ message, phase }) => {
+			if (phase === "playback") setIsPlaying(false);
+			setError(message);
+		});
+		return () => {
+			unsubStart();
+			unsubComplete();
+			unsubStop();
+			unsubError();
+		};
+	}, []);
+	const speak = useCallback(async (text, options) => {
+		setError(null);
+		setIsSynthesizing(true);
+		try {
+			const client = await getClientTTS();
+			if (client) await client.speak(text, options);
+			else {
+				await tts.synthesize(text, options);
+				console.warn("[useTTS] @speechos/client not available, audio not played");
+			}
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "TTS failed";
+			setError(message);
+			throw err;
+		} finally {
+			setIsSynthesizing(false);
+		}
+	}, []);
+	const synthesize = useCallback(async (text, options) => {
+		setError(null);
+		setIsSynthesizing(true);
+		try {
+			const result = await tts.synthesize(text, options);
+			setAudioResult(result);
+			return result;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : "Synthesis failed";
+			setError(message);
+			throw err;
+		} finally {
+			setIsSynthesizing(false);
+		}
+	}, []);
+	const stop = useCallback(async () => {
+		const client = await getClientTTS();
+		if (client) client.stop();
+		setIsPlaying(false);
+	}, []);
+	const clear = useCallback(() => {
+		setAudioResult(null);
+		setError(null);
+	}, []);
+	return {
+		speak,
+		synthesize,
+		stop,
+		isSynthesizing,
+		isPlaying,
+		audioResult,
 		error,
 		clear
 	};
@@ -565,4 +687,4 @@ function SpeechOSWidget({ apiKey, userId, host, zIndex, debug, onTranscription,
 const VERSION = "0.1.0";
 
 //#endregion
-export { SpeechOSContext, SpeechOSProvider, SpeechOSWidget, VERSION, useCommand, useDictation, useEdit, useSpeechOS, useSpeechOSContext, useSpeechOSEvents, useSpeechOSState, useSpeechOSWidget };
+export { SpeechOSContext, SpeechOSProvider, SpeechOSWidget, VERSION, useCommand, useDictation, useEdit, useSpeechOS, useSpeechOSContext, useSpeechOSEvents, useSpeechOSState, useSpeechOSWidget, useTTS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speechos/react",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "React hooks and components for SpeechOS voice integration",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -48,8 +48,8 @@
   "author": "SpeechOS",
   "license": "MIT",
   "peerDependencies": {
-    "@speechos/client": "^0.2.11",
-    "@speechos/core": "^0.2.10",
+    "@speechos/client": "^0.2.12",
+    "@speechos/core": "^0.2.11",
     "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
@@ -69,6 +69,6 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@speechos/core": "^0.2.10"
+    "@speechos/core": "^0.2.11"
   }
 }