docs: Add JSDoc examples to core utilities and expand README with SSR, TypeScript, advanced examples, and troubleshooting.

Author: alphainfinitus

README.md

@@ -187,6 +187,180 @@ insertTextAtCursor(inputRef, 'hello', currentValue, setValue)
 
 > **Note:** The Web Speech API requires HTTPS in production (except localhost).
 
+---
+
+## SSR / Next.js
+
+This package is SSR-safe. The Web Speech API is only accessed on the client.
+
+### Next.js App Router
+
+```tsx
+'use client'
+
+import { useSpeechInput } from '@syntropy-labs/react-web-speech'
+
+export function VoiceButton() {
+  const { isListening, toggle, isSupported } = useSpeechInput()
+  
+  if (!isSupported) return null
+  
+  return (
+    <button onClick={toggle}>
+      {isListening ? 'Stop' : 'Speak'}
+    </button>
+  )
+}
+```
+
+### Next.js Pages Router
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const VoiceInput = dynamic(
+  () => import('../components/VoiceInput'),
+  { ssr: false }
+)
+```
+
+---
+
+## TypeScript
+
+All types are exported:
+
+```tsx
+import type {
+  UseSpeechInputOptions,
+  UseSpeechInputReturn,
+  UseSpeechInputWithCursorOptions,
+  UseSpeechInputWithCursorReturn,
+  SpeechError,
+  SpeechErrorType,
+  MicPermissionState,
+  CursorPosition,
+  BrowserCapabilities,
+} from '@syntropy-labs/react-web-speech'
+```
+
+---
+
+## Advanced Examples
+
+### Voice-controlled Form
+
+```tsx
+import { useState, useRef } from 'react'
+import { useSpeechInputWithCursor } from '@syntropy-labs/react-web-speech'
+
+function VoiceForm() {
+  const [formData, setFormData] = useState({ name: '', email: '' })
+  const [activeField, setActiveField] = useState<'name' | 'email'>('name')
+  const inputRefs = {
+    name: useRef<HTMLInputElement>(null),
+    email: useRef<HTMLInputElement>(null),
+  }
+
+  const { toggle, isListening } = useSpeechInputWithCursor({
+    inputRef: inputRefs[activeField],
+    value: formData[activeField],
+    onChange: (value) => setFormData({ ...formData, [activeField]: value }),
+  })
+
+  return (
+    <form>
+      <input
+        ref={inputRefs.name}
+        value={formData.name}
+        onFocus={() => setActiveField('name')}
+        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+        placeholder="Name"
+      />
+      <input
+        ref={inputRefs.email}
+        value={formData.email}
+        onFocus={() => setActiveField('email')}
+        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+        placeholder="Email"
+      />
+      <button type="button" onClick={toggle}>
+        {isListening ? '🔴 Stop' : '🎙️ Speak'}
+      </button>
+    </form>
+  )
+}
+```
+
+### Real-time Transcript Display
+
+```tsx
+import { useSpeechInput } from '@syntropy-labs/react-web-speech'
+
+function LiveTranscript() {
+  const { transcript, interimTranscript, isListening, toggle } = useSpeechInput({
+    interimResults: true,
+    continuous: true,
+  })
+
+  return (
+    <div>
+      <button onClick={toggle}>{isListening ? 'Stop' : 'Start'}</button>
+      <p>
+        {transcript}
+        <span style={{ opacity: 0.5 }}>{interimTranscript}</span>
+      </p>
+    </div>
+  )
+}
+```
+
+---
+
+## Troubleshooting
+
+### "Permission denied" error
+
+The user has denied microphone access. They need to:
+1. Click the 🔒 icon in the browser address bar
+2. Reset microphone permissions
+3. Refresh the page
+
+### "Network error"
+
+The Web Speech API requires an internet connection. Chrome sends audio to Google's servers for processing.
+
+### Recognition stops immediately
+
+Some browsers stop recognition after detecting silence. Solutions:
+- Use `continuous: true` for longer sessions
+- Increase `silenceTimeout` (or set to `0` to disable)
+
+### Works in development but not production
+
+The Web Speech API requires HTTPS. Make sure your production site uses SSL.
+
+### Duplicate React error with yarn link
+
+When testing locally with `yarn link`, add React aliases to your Vite config:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import path from 'path'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      react: path.resolve('./node_modules/react'),
+      'react-dom': path.resolve('./node_modules/react-dom'),
+    },
+  },
+})
+```
+
+---
+
 ## Why This Package?
 
 Existing React speech-to-text packages lack critical production-ready features:
@@ -226,3 +400,4 @@ yarn build
 
 MIT © [SyntropyLabs](https://github.com/SyntropyLabs)
 
+

src/core/browser.ts

@@ -6,10 +6,17 @@ import type { BrowserCapabilities, SpeechRecognitionInstance } from '../types'
 let cachedCapabilities: BrowserCapabilities | null = null
 
 /**
- * Detect browser capabilities for Web Speech API
- * Results are cached for performance
+ * Detect browser capabilities for Web Speech API.
+ * Results are cached for performance.
  *
  * @returns Browser capabilities object
+ * @example
+ * ```ts
+ * const caps = detectBrowserCapabilities()
+ * if (!caps.isSupported) {
+ *   console.log('Speech API not supported')
+ * }
+ * ```
  */
 export function detectBrowserCapabilities(): BrowserCapabilities {
   // Return cached result if available
@@ -78,8 +85,16 @@ export function clearCapabilitiesCache(): void {
 }
 
 /**
- * Check if the current browser has known issues with Speech API
+ * Check if the current browser has known issues with Speech API.
+ *
  * @returns Warning message if issues exist, null otherwise
+ * @example
+ * ```ts
+ * const warning = getBrowserCompatibilityWarning()
+ * if (warning) {
+ *   console.warn(warning)
+ * }
+ * ```
  */
 export function getBrowserCompatibilityWarning(): string | null {
   const { browserName, isSupported } = detectBrowserCapabilities()

src/core/permissions.ts

@@ -2,10 +2,17 @@ import type { MicPermissionState } from '../types'
 import { detectBrowserCapabilities } from './browser'
 
 /**
- * Get the current microphone permission state
- * Uses Permissions API when available, falls back to 'prompt'
+ * Get the current microphone permission state.
+ * Uses Permissions API when available, falls back to 'prompt'.
  *
  * @returns Promise resolving to permission state
+ * @example
+ * ```ts
+ * const state = await getMicPermissionState()
+ * if (state === 'denied') {
+ *   alert('Please enable microphone access')
+ * }
+ * ```
  */
 export async function getMicPermissionState(): Promise<MicPermissionState> {
   const { isSupported, supportsPermissionsAPI } = detectBrowserCapabilities()
@@ -73,10 +80,17 @@ export function subscribeToPermissionChanges(
 }
 
 /**
- * Request microphone permission by attempting to access the device
- * This triggers the browser's permission prompt
+ * Request microphone permission by attempting to access the device.
+ * This triggers the browser's permission prompt.
  *
  * @returns Promise resolving to the new permission state
+ * @example
+ * ```ts
+ * const state = await requestMicPermission()
+ * if (state === 'granted') {
+ *   console.log('Microphone access granted!')
+ * }
+ * ```
  */
 export async function requestMicPermission(): Promise<MicPermissionState> {
   const { isSupported } = detectBrowserCapabilities()

src/core/recognition.ts

@@ -37,11 +37,24 @@ const ERROR_MESSAGES: Record<SpeechErrorType, string> = {
 }
 
 /**
- * Create a configured SpeechRecognition instance
+ * Create a configured SpeechRecognition instance.
  *
  * @param options - Recognition configuration options
- * @param callbacks - Event callbacks
+ * @param callbacks - Event callbacks for recognition events
  * @returns Configured recognition instance, or null if not supported
+ * @example
+ * ```ts
+ * const recognition = createRecognitionInstance(
+ *   { lang: 'en-US', continuous: false },
+ *   {
+ *     onResult: (text, isFinal) => console.log(text),
+ *     onError: (err) => console.error(err),
+ *     onStart: () => console.log('Started'),
+ *     onEnd: () => console.log('Ended'),
+ *   }
+ * )
+ * recognition?.start()
+ * ```
  */
 export function createRecognitionInstance(
   options: RecognitionOptions,