@untemps/react-vocal 2.0.0-beta.14 → 2.0.0-beta.16

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [2.0.0-beta.16](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.15...v2.0.0-beta.16) (2026-05-24)
+
+
+### Features
+
+* Export useCommands and fix README result callback examples ([#158](https://github.com/untemps/react-vocal/issues/158)) ([990636a](https://github.com/untemps/react-vocal/commit/990636a3d7b3a7981629b0172318ae9bc739abf8))
+
+# [2.0.0-beta.15](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.14...v2.0.0-beta.15) (2026-05-24)
+
+
+### chore
+
+* Migrate codebase to TypeScript ([#156](https://github.com/untemps/react-vocal/issues/156)) ([86c6e49](https://github.com/untemps/react-vocal/commit/86c6e49a82f599b60356afb91f34b59f63710a44))
+
+
+### BREAKING CHANGES
+
+* minimum supported Node.js version bumped from `^20.19.0 || >=22.12.0` to `>=22`, aligning with the underlying @untemps/vocal 2.x direct dependency
+
 # [2.0.0-beta.14](https://github.com/untemps/react-vocal/compare/v2.0.0-beta.13...v2.0.0-beta.14) (2026-05-24)
 
 

package/README.md

@@ -23,10 +23,12 @@ far (see [caniuse](https://caniuse.com/#search=SpeechRecognition)). If the API i
 won't display anything.
 
 This component intends to catch a speech result as soon as possible. This can be a good fit for vocal commands or search
-field filling. For now on it does not support continuous speech (see [Roadmap](#roadmap) below).  
-That means either a result is caught and returned or timeout is reached and the recognition is discarded.  
-The `stop` function returned by children-as-function mechanism allows to prematurely discard the recognition before
-timeout elapses.
+field filling. It also supports a continuous mode (`continuous` prop) for real-time transcription and always-on voice
+command use cases — see the `Vocal` component API table for details.
+
+In single-shot mode (the default), either a result is caught and returned or the timeout is reached and the recognition
+is discarded. The `stop` function returned by children-as-function mechanism allows to prematurely discard the
+recognition before the timeout elapses.
 
 ### Special cases
 
@@ -54,6 +56,21 @@ yarn add fuse.js
 
 Without fuse.js, phrase commands fall back to case-insensitive exact matching. Single-word commands always use exact matching and never require fuse.js.
 
+## TypeScript
+
+`@untemps/react-vocal` is written in TypeScript and ships full type declarations. The public surface is typed end-to-end:
+
+- `Vocal` component props (`VocalProps`, `OnResultCallback`)
+- `useVocal` hook signature, action tuple (`UseVocalActions`, `UseVocalReturn`)
+- `useCommands` shapes (`CommandCallback`, `CommandsMap`, `TriggerCommand`)
+- `isSupported` function (re-exported from `@untemps/vocal`)
+
+```typescript
+import Vocal, { useVocal, isSupported, type VocalProps, type CommandsMap } from '@untemps/react-vocal'
+```
+
+TypeScript is listed as an optional peer dependency (`>=6.0.0`) — install it only if your project uses TS.
+
 ## Usage
 
 ### `Vocal` component
@@ -267,10 +284,10 @@ const App = () => {
 		setResult('')
 	}
 
-	const _onVocalResult = (result) => {
+	const _onVocalResult = (_event, bestAlternative) => {
 		setIsListening(false)
 
-		setResult(result)
+		setResult(bestAlternative)
 	}
 
 	const _onVocalError = (e) => {
@@ -344,6 +361,57 @@ const [, { start }] = useVocal('en-US')
 start({ signal: controller.signal })
 ```
 
+### `useCommands` hook
+
+The `useCommands` hook is the same command-matching primitive used internally by the `Vocal` component. Export it directly when you build a custom UI on top of `useVocal` and want to reuse the matching logic instead of re-implementing it.
+
+#### Basic usage
+
+```javascript
+import { useVocal, useCommands } from '@untemps/react-vocal'
+
+const App = () => {
+	const commands = {
+		rouge: () => setBorderColor('red'),
+		bleu: () => setBorderColor('blue'),
+	}
+	const triggerCommand = useCommands(commands)
+
+	const [, { start, subscribe }] = useVocal('fr-FR')
+
+	const _onResult = (_event, bestAlternative) => {
+		triggerCommand(bestAlternative)
+	}
+
+	const _onClick = () => {
+		subscribe('result', _onResult)
+		start()
+	}
+
+	return <button onClick={_onClick}>Listen</button>
+}
+```
+
+#### Signature
+
+```
+useCommands(commands, precision)
+```
+
+| Args      | Type   | Default | Description                                                                                              |
+| --------- | ------ | ------- | -------------------------------------------------------------------------------------------------------- |
+| commands  | object | null    | A `{ key: callback }` map. Keys are lowercased internally. Callbacks receive `(rawInput, commandKey)`.   |
+| precision | number | 0.4     | Fuse.js score threshold for **phrase** command keys only (lower = stricter). Single-word keys use exact lookup. |
+
+#### Return value
+
+`useCommands` returns a `triggerCommand(rawInput)` function. Passing a transcript runs it against the commands map and invokes the matching callback if any, returning its result. Returns `null` when no command matches.
+
+Matching rules:
+
+- **Single-word keys** (e.g. `rouge`, `submit`): exact case-insensitive lookup, with each word of the input tried individually so a key fires even when embedded in a phrase (`je veux du rouge` triggers `rouge`).
+- **Phrase keys** (e.g. `change the background color`): Fuse.js fuzzy matching against the joined transcript, gated by `precision`. fuse.js is loaded lazily; if it's not installed, the hook falls back to substring matching.
+
 ### Browser support flag
 
 #### Basic usage
@@ -401,4 +469,3 @@ Contributions are warmly welcomed:
 ## Roadmap
 
 -   Add a connector management to plug external speech-to-text services in
--   Support continuous speech

package/dist/index.cjs

@@ -1,7 +1,7 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports),s=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},c=(n,r,a)=>(a=n==null?{}:e(i(n)),s(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let l=require(`react`);l=c(l,1);var u=()=>!!navigator.permissions,d=()=>!!navigator.mediaDevices,f=async(e,t,{signal:n}={})=>{if(!u()||!d())throw new DOMException(`Navigator API: permissions or Navigator API: mediaDevices not supported`,`NOT_SUPPORTED_ERR`);if(n?.throwIfAborted(),(await navigator.permissions.query({name:e})).state===`denied`)throw new DOMException(`Permission denied`,`NOT_ALLOWED_ERR`);n?.throwIfAborted();let r=navigator.mediaDevices.getUserMedia(t);if(!n)return r;let i,a=new Promise((e,t)=>{i=()=>t(n.reason),n.addEventListener(`abort`,i,{once:!0})});return Promise.race([r,a]).finally(()=>{n.removeEventListener(`abort`,i)})},p={AUDIO_END:`audioend`,AUDIO_START:`audiostart`,END:`end`,ERROR:`error`,NO_MATCH:`nomatch`,RESULT:`result`,SOUND_END:`soundend`,SOUND_START:`soundstart`,SPEECH_END:`speechend`,SPEECH_START:`speechstart`,START:`start`},m=1e3,h=new Set([`not-allowed`,`service-not-allowed`,`audio-capture`]),g={grammars:null,lang:`en-US`,continuous:!1,interimResults:!1,maxAlternatives:1},_=()=>{if(!(typeof window>`u`))return window.SpeechRecognition??window.webkitSpeechRecognition??window.mozSpeechRecognition??window.msSpeechRecognition},v=()=>window.SpeechGrammarList??window.webkitSpeechGrammarList??window.mozSpeechGrammarList??window.msSpeechGrammarList,y=e=>e.reduce((e,t)=>(t.confidence??0)>(e.confidence??0)?t:e),b=e=>{let t=e.slice();return Object.defineProperty(t,`isFinal`,{value:!0}),Object.defineProperty(t,`item`,{value:e=>t[e]}),t},x=e=>{let t=e.slice();return Object.defineProperty(t,`item`,{value:e=>t[e]}),t},S=e=>Object.values(p).includes(e),C=e=>`Unknown event type "${e}". Valid types are: ${Object.values(p).join(`, `)}.`,w=()=>!!_()&&!!u()&&!!d(),T=e=>{let t=_();if(!t)throw new DOMException(`SpeechRecognition not supported`,`NOT_SUPPORTED_ERR`);let n=new t,r={},i=!1,a=!1,o=0,s=null,c=!1,l=[],u={...g,...e??{}};if(n.lang=u.lang,n.continuous=u.continuous,n.interimResults=u.interimResults,n.maxAlternatives=u.maxAlternatives,u.grammars)n.grammars=u.grammars;else{let e=v();n.grammars=e?new e:null}let d=()=>{s!==null&&(clearTimeout(s),s=null),c=!1},w=()=>!!n&&!a&&n.continuous,T=()=>{s=null;try{n.start(),o=Date.now()}catch{c=!1,i=!1}},E=()=>{let e=l;if(l=[],e.length===0||!r[p.RESULT]?.length)return;let t=e.map(e=>y(Array.from(e)).transcript).join(` `).trim(),n=Object.assign(new Event(p.RESULT),{resultIndex:0,results:x(e)});[...r[p.RESULT]].forEach(({callback:e})=>{e(n,t,[t])})},D=[[p.END,e=>{if(w()){let t=Math.max(0,m-(Date.now()-o));c=!0,s=setTimeout(T,t),e.stopImmediatePropagation();return}E(),i=!1}],[p.START,e=>{c&&(e.stopImmediatePropagation(),queueMicrotask(()=>{c=!1}))}],[p.ERROR,e=>{h.has(e.error)&&(a=!0,d(),i=!1)}],[p.RESULT,e=>{if(!u.continuous)return;let t=e,n=t.results?.[t.resultIndex];n?.isFinal&&l.push(b(Array.from(n)))}]];D.forEach(([e,t])=>n.addEventListener(e,t));let O=async({signal:e}={})=>{if(n)try{let t=await f(`microphone`,{audio:!0},{signal:e});if(e?.aborted||!n)return;if(!t)throw Error(`Unable to retrieve the stream from media device`);a=!1,l=[],n.start(),i=!0,o=Date.now()}catch(e){if(e instanceof Error&&e.name===`AbortError`)return;throw e}},k=()=>{n&&(a=!0,d(),n.stop(),i=!1)},A=()=>{n&&(a=!0,d(),l=[],n.abort(),i=!1)},j=(e,t)=>{if(!S(e))throw Error(C(e));if(!n)return;let i=n=>{if(c&&(e===p.END||e===p.START))return;if(e!==p.RESULT){t(n);return}let r=n;if(!(r.results?.length>0)||r.resultIndex>=r.results.length){t(n);return}let i=r.results[r.resultIndex];if(u.continuous&&i.isFinal)return;let a=Array.from(i);t(n,y(a).transcript,a.map(e=>e.transcript))};n.addEventListener(e,i),r[e]||(r[e]=[]),r[e].push({callback:t,handler:i})},M=(e,t)=>{if(!S(e))throw Error(C(e));if(!(!n||!r[e]))if(t!==void 0){let i=r[e].findIndex(e=>e.callback===t);i!==-1&&(n.removeEventListener(e,r[e][i].handler),r[e].splice(i,1),r[e].length===0&&delete r[e])}else r[e].forEach(({handler:t})=>n.removeEventListener(e,t)),delete r[e]};return{get isRecording(){return i},start:O,stop:k,abort:A,on:j,off:M,cleanup:()=>{k(),Object.keys(r).forEach(e=>M(e)),D.forEach(([e,t])=>n?.removeEventListener(e,t)),n=null}}},E=e=>typeof e==`function`,D=(e=`en-US`,t=null,n=1,r=!1,i=null)=>{let a=(0,l.useRef)(null),[o,s]=(0,l.useState)(!1),c=(0,l.useMemo)(()=>w(),[]);return(0,l.useEffect)(()=>{if(c){let o=i||T({lang:e,grammars:t,maxAlternatives:n,continuous:r});a.current=o;let c=()=>s(!0),l=()=>s(!1);return o.on(`start`,c),o.on(`end`,l),o.on(`error`,l),()=>{o.off(`start`,c),o.off(`end`,l),o.off(`error`,l),o.abort(),o.cleanup(),s(!1)}}},[e,t,n,r,i,c]),[a,{start:(0,l.useCallback)(e=>{if(a.current)return s(!0),a.current.start(e)},[]),stop:(0,l.useCallback)(()=>{a.current&&a.current.stop()},[]),abort:(0,l.useCallback)(()=>{a.current&&a.current.abort()},[]),subscribe:(0,l.useCallback)((e,t)=>{a.current&&a.current.on(e,t)},[]),unsubscribe:(0,l.useCallback)((e,t)=>{a.current&&a.current.off(e,t)},[]),clean:(0,l.useCallback)(()=>{a.current&&a.current.cleanup()},[]),isRecording:o}]},O=(e,t=0)=>{let n=(0,l.useRef)(-1),r=(0,l.useCallback)(()=>{clearTimeout(n.current),n.current=-1},[]),i=(0,l.useCallback)(()=>{r(),n.current=setTimeout(e,t)},[e,t,r]);return(0,l.useEffect)(()=>r,[r]),[i,r]},k=(e,t=.4)=>{let n=(0,l.useMemo)(()=>e?Object.entries(e).reduce((e,[t,n])=>({...e,[t.toLowerCase()]:n}),{}):{},[e]),r=(0,l.useMemo)(()=>Object.keys(n),[n]),i=(0,l.useMemo)(()=>r.some(e=>e.includes(` `)),[r]),a=(0,l.useRef)(null);return(0,l.useEffect)(()=>{if(!i){a.current=null;return}let e=!1;return import(`fuse.js`).then(t=>{e||(a.current=new(t.default??t)(r,{includeScore:!0,ignoreLocation:!0}))}).catch(()=>{e||process.env.NODE_ENV!==`production`&&console.warn(`[react-vocal] fuse.js is not installed. Phrase command keys will fall back to exact matching. Install fuse.js to enable fuzzy matching: npm install fuse.js`)}),()=>{e=!0}},[i,r]),e=>{if(!r.length)return null;if(!i){let t=e.trim().split(/\s+/),r=t.length>1?t:[e.trim()];for(let e of r){let t=e.toLowerCase();if(t in n)return n[t]?.(e,t)}return null}let o=a.current;if(o){let r=o.search(e).filter(e=>e.score<t);if(r?.length){let t=r[0].item.toLowerCase();return n[t]?.(e,t)}}else{let t=e.toLowerCase(),i=r.find(e=>t.includes(e)||e.includes(t));if(i)return n[i]?.(e,i)}return null}},A=o((e=>{var t=Symbol.for(`react.transitional.element`),n=Symbol.for(`react.fragment`);function r(e,n,r){var i=null;if(r!==void 0&&(i=``+r),n.key!==void 0&&(i=``+n.key),`key`in n)for(var a in r={},n)a!==`key`&&(r[a]=n[a]);else r=n;return n=r.ref,{$$typeof:t,type:e,key:i,ref:n===void 0?null:n,props:r}}e.Fragment=n,e.jsx=r,e.jsxs=r})),j=o((e=>{process.env.NODE_ENV!==`production`&&(function(){function t(e){if(e==null)return null;if(typeof e==`function`)return e.$$typeof===O?null:e.displayName||e.name||null;if(typeof e==`string`)return e;switch(e){case _:return`Fragment`;case y:return`Profiler`;case v:return`StrictMode`;case C:return`Suspense`;case w:return`SuspenseList`;case D:return`Activity`}if(typeof e==`object`)switch(typeof e.tag==`number`&&console.error(`Received an unexpected object in getComponentNameFromType(). This is likely a bug in React. Please file an issue.`),e.$$typeof){case g:return`Portal`;case x:return e.displayName||`Context`;case b:return(e._context.displayName||`Context`)+`.Consumer`;case S:var n=e.render;return e=e.displayName,e||=(e=n.displayName||n.name||``,e===``?`ForwardRef`:`ForwardRef(`+e+`)`),e;case T:return n=e.displayName||null,n===null?t(e.type)||`Memo`:n;case E:n=e._payload,e=e._init;try{return t(e(n))}catch{}}return null}function n(e){return``+e}function r(e){try{n(e);var t=!1}catch{t=!0}if(t){t=console;var r=t.error,i=typeof Symbol==`function`&&Symbol.toStringTag&&e[Symbol.toStringTag]||e.constructor.name||`Object`;return r.call(t,`The provided key is an unsupported type %s. This value must be coerced to a string before using it here.`,i),n(e)}}function i(e){if(e===_)return`<>`;if(typeof e==`object`&&e&&e.$$typeof===E)return`<...>`;try{var n=t(e);return n?`<`+n+`>`:`<...>`}catch{return`<...>`}}function a(){var e=k.A;return e===null?null:e.getOwner()}function o(){return Error(`react-stack-top-frame`)}function s(e){if(A.call(e,`key`)){var t=Object.getOwnPropertyDescriptor(e,`key`).get;if(t&&t.isReactWarning)return!1}return e.key!==void 0}function c(e,t){function n(){N||(N=!0,console.error("%s: `key` is not a prop. Trying to access it will result in `undefined` being returned. If you need to access the same value within the child component, you should pass it as a different prop. (https://react.dev/link/special-props)",t))}n.isReactWarning=!0,Object.defineProperty(e,`key`,{get:n,configurable:!0})}function l(){var e=t(this.type);return P[e]||(P[e]=!0,console.error(`Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release.`)),e=this.props.ref,e===void 0?null:e}function u(e,t,n,r,i,a){var o=n.ref;return e={$$typeof:h,type:e,key:t,props:n,_owner:r},(o===void 0?null:o)===null?Object.defineProperty(e,`ref`,{enumerable:!1,value:null}):Object.defineProperty(e,`ref`,{enumerable:!1,get:l}),e._store={},Object.defineProperty(e._store,`validated`,{configurable:!1,enumerable:!1,writable:!0,value:0}),Object.defineProperty(e,`_debugInfo`,{configurable:!1,enumerable:!1,writable:!0,value:null}),Object.defineProperty(e,`_debugStack`,{configurable:!1,enumerable:!1,writable:!0,value:i}),Object.defineProperty(e,`_debugTask`,{configurable:!1,enumerable:!1,writable:!0,value:a}),Object.freeze&&(Object.freeze(e.props),Object.freeze(e)),e}function d(e,n,i,o,l,d){var p=n.children;if(p!==void 0)if(o)if(j(p)){for(o=0;o<p.length;o++)f(p[o]);Object.freeze&&Object.freeze(p)}else console.error(`React.jsx: Static children should always be an array. You are likely explicitly calling React.jsxs or React.jsxDEV. Use the Babel transform instead.`);else f(p);if(A.call(n,`key`)){p=t(e);var m=Object.keys(n).filter(function(e){return e!==`key`});o=0<m.length?`{key: someKey, `+m.join(`: ..., `)+`: ...}`:`{key: someKey}`,L[p+o]||(m=0<m.length?`{`+m.join(`: ..., `)+`: ...}`:`{}`,console.error(`A props object containing a "key" prop is being spread into JSX:
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports);let t=require(`react`);var n=()=>!!navigator.permissions,r=()=>!!navigator.mediaDevices,i=async(e,t,{signal:i}={})=>{if(!n()||!r())throw new DOMException(`Navigator API: permissions or Navigator API: mediaDevices not supported`,`NOT_SUPPORTED_ERR`);if(i?.throwIfAborted(),(await navigator.permissions.query({name:e})).state===`denied`)throw new DOMException(`Permission denied`,`NOT_ALLOWED_ERR`);i?.throwIfAborted();let a=navigator.mediaDevices.getUserMedia(t);if(!i)return a;let o,s=new Promise((e,t)=>{o=()=>t(i.reason),i.addEventListener(`abort`,o,{once:!0})});return Promise.race([a,s]).finally(()=>{i.removeEventListener(`abort`,o)})},a={AUDIO_END:`audioend`,AUDIO_START:`audiostart`,END:`end`,ERROR:`error`,NO_MATCH:`nomatch`,RESULT:`result`,SOUND_END:`soundend`,SOUND_START:`soundstart`,SPEECH_END:`speechend`,SPEECH_START:`speechstart`,START:`start`},o=1e3,s=new Set([`not-allowed`,`service-not-allowed`,`audio-capture`]),c={grammars:null,lang:`en-US`,continuous:!1,interimResults:!1,maxAlternatives:1},l=()=>{if(!(typeof window>`u`))return window.SpeechRecognition??window.webkitSpeechRecognition??window.mozSpeechRecognition??window.msSpeechRecognition},u=()=>window.SpeechGrammarList??window.webkitSpeechGrammarList??window.mozSpeechGrammarList??window.msSpeechGrammarList,d=e=>e.reduce((e,t)=>(t.confidence??0)>(e.confidence??0)?t:e),f=e=>{let t=e.slice();return Object.defineProperty(t,`isFinal`,{value:!0}),Object.defineProperty(t,`item`,{value:e=>t[e]}),t},p=e=>{let t=e.slice();return Object.defineProperty(t,`item`,{value:e=>t[e]}),t},m=e=>Object.values(a).includes(e),h=e=>`Unknown event type "${e}". Valid types are: ${Object.values(a).join(`, `)}.`,g=()=>!!l()&&!!n()&&!!r(),_=e=>{let t=l();if(!t)throw new DOMException(`SpeechRecognition not supported`,`NOT_SUPPORTED_ERR`);let n=new t,r={},g=!1,_=!1,v=0,y=null,b=!1,x=[],S={...c,...e??{}};if(n.lang=S.lang,n.continuous=S.continuous,n.interimResults=S.interimResults,n.maxAlternatives=S.maxAlternatives,S.grammars)n.grammars=S.grammars;else{let e=u();n.grammars=e?new e:null}let C=()=>{y!==null&&(clearTimeout(y),y=null),b=!1},w=()=>!!n&&!_&&n.continuous,T=()=>{y=null;try{n.start(),v=Date.now()}catch{b=!1,g=!1}},E=()=>{let e=x;if(x=[],e.length===0||!r[a.RESULT]?.length)return;let t=e.map(e=>d(Array.from(e)).transcript).join(` `).trim(),n=Object.assign(new Event(a.RESULT),{resultIndex:0,results:p(e)});[...r[a.RESULT]].forEach(({callback:e})=>{e(n,t,[t])})},D=[[a.END,e=>{if(w()){let t=Math.max(0,o-(Date.now()-v));b=!0,y=setTimeout(T,t),e.stopImmediatePropagation();return}E(),g=!1}],[a.START,e=>{b&&(e.stopImmediatePropagation(),queueMicrotask(()=>{b=!1}))}],[a.ERROR,e=>{s.has(e.error)&&(_=!0,C(),g=!1)}],[a.RESULT,e=>{if(!S.continuous)return;let t=e,n=t.results?.[t.resultIndex];n?.isFinal&&x.push(f(Array.from(n)))}]];D.forEach(([e,t])=>n.addEventListener(e,t));let O=async({signal:e}={})=>{if(n)try{let t=await i(`microphone`,{audio:!0},{signal:e});if(e?.aborted||!n)return;if(!t)throw Error(`Unable to retrieve the stream from media device`);_=!1,x=[],n.start(),g=!0,v=Date.now()}catch(e){if(e instanceof Error&&e.name===`AbortError`)return;throw e}},k=()=>{n&&(_=!0,C(),n.stop(),g=!1)},A=()=>{n&&(_=!0,C(),x=[],n.abort(),g=!1)},j=(e,t)=>{if(!m(e))throw Error(h(e));if(!n)return;let i=n=>{if(b&&(e===a.END||e===a.START))return;if(e!==a.RESULT){t(n);return}let r=n;if(!(r.results?.length>0)||r.resultIndex>=r.results.length){t(n);return}let i=r.results[r.resultIndex];if(S.continuous&&i.isFinal)return;let o=Array.from(i);t(n,d(o).transcript,o.map(e=>e.transcript))};n.addEventListener(e,i),r[e]||(r[e]=[]),r[e].push({callback:t,handler:i})},M=(e,t)=>{if(!m(e))throw Error(h(e));if(!(!n||!r[e]))if(t!==void 0){let i=r[e].findIndex(e=>e.callback===t);i!==-1&&(n.removeEventListener(e,r[e][i].handler),r[e].splice(i,1),r[e].length===0&&delete r[e])}else r[e].forEach(({handler:t})=>n.removeEventListener(e,t)),delete r[e]};return{get isRecording(){return g},start:O,stop:k,abort:A,on:j,off:M,cleanup:()=>{k(),Object.keys(r).forEach(e=>M(e)),D.forEach(([e,t])=>n?.removeEventListener(e,t)),n=null}}},v=e=>typeof e==`function`,y=(e=`en-US`,n=null,r=1,i=!1,a=null)=>{let o=(0,t.useRef)(null),[s,c]=(0,t.useState)(!1),l=(0,t.useMemo)(()=>g(),[]);return(0,t.useEffect)(()=>{if(l){let t=a||_({lang:e,grammars:n,maxAlternatives:r,continuous:i});o.current=t;let s=()=>c(!0),l=()=>c(!1);return t.on(`start`,s),t.on(`end`,l),t.on(`error`,l),()=>{t.off(`start`,s),t.off(`end`,l),t.off(`error`,l),t.abort(),t.cleanup(),c(!1)}}},[e,n,r,i,a,l]),[o,{start:(0,t.useCallback)(e=>{if(o.current)return c(!0),o.current.start(e)},[]),stop:(0,t.useCallback)(()=>{o.current&&o.current.stop()},[]),abort:(0,t.useCallback)(()=>{o.current&&o.current.abort()},[]),subscribe:(0,t.useCallback)((e,t)=>{o.current&&o.current.on(e,t)},[]),unsubscribe:(0,t.useCallback)((e,t)=>{o.current&&o.current.off(e,t)},[]),clean:(0,t.useCallback)(()=>{o.current&&o.current.cleanup()},[]),isRecording:s}]},b=(e,n=0)=>{let r=(0,t.useRef)(-1),i=(0,t.useCallback)(()=>{clearTimeout(r.current),r.current=-1},[]),a=(0,t.useCallback)(()=>{i(),r.current=setTimeout(e,n)},[e,n,i]);return(0,t.useEffect)(()=>i,[i]),[a,i]},x=(e,n=.4)=>{let r=(0,t.useMemo)(()=>e?Object.entries(e).reduce((e,[t,n])=>({...e,[t.toLowerCase()]:n}),{}):{},[e]),i=(0,t.useMemo)(()=>Object.keys(r),[r]),a=(0,t.useMemo)(()=>i.some(e=>e.includes(` `)),[i]),o=(0,t.useRef)(null);return(0,t.useEffect)(()=>{if(!a){o.current=null;return}let e=!1;return import(`fuse.js`).then(t=>{e||(o.current=new(t.default??t)(i,{includeScore:!0,ignoreLocation:!0}))}).catch(()=>{e||process.env.NODE_ENV!==`production`&&console.warn(`[react-vocal] fuse.js is not installed. Phrase command keys will fall back to exact matching. Install fuse.js to enable fuzzy matching: npm install fuse.js`)}),()=>{e=!0}},[a,i]),e=>{if(!i.length)return null;if(!a){let t=e.trim().split(/\s+/),n=t.length>1?t:[e.trim()];for(let e of n){let t=e.toLowerCase();if(t in r)return r[t]?.(e,t)}return null}let t=o.current;if(t){let i=t.search(e).filter(e=>(e.score??1)<n);if(i?.length){let t=i[0].item.toLowerCase();return r[t]?.(e,t)}}else{let t=e.toLowerCase(),n=i.find(e=>t.includes(e)||e.includes(t));if(n)return r[n]?.(e,n)}return null}},S=e((e=>{var t=Symbol.for(`react.transitional.element`),n=Symbol.for(`react.fragment`);function r(e,n,r){var i=null;if(r!==void 0&&(i=``+r),n.key!==void 0&&(i=``+n.key),`key`in n)for(var a in r={},n)a!==`key`&&(r[a]=n[a]);else r=n;return n=r.ref,{$$typeof:t,type:e,key:i,ref:n===void 0?null:n,props:r}}e.Fragment=n,e.jsx=r,e.jsxs=r})),C=e((e=>{process.env.NODE_ENV!==`production`&&(function(){function t(e){if(e==null)return null;if(typeof e==`function`)return e.$$typeof===O?null:e.displayName||e.name||null;if(typeof e==`string`)return e;switch(e){case _:return`Fragment`;case y:return`Profiler`;case v:return`StrictMode`;case C:return`Suspense`;case w:return`SuspenseList`;case D:return`Activity`}if(typeof e==`object`)switch(typeof e.tag==`number`&&console.error(`Received an unexpected object in getComponentNameFromType(). This is likely a bug in React. Please file an issue.`),e.$$typeof){case g:return`Portal`;case x:return e.displayName||`Context`;case b:return(e._context.displayName||`Context`)+`.Consumer`;case S:var n=e.render;return e=e.displayName,e||=(e=n.displayName||n.name||``,e===``?`ForwardRef`:`ForwardRef(`+e+`)`),e;case T:return n=e.displayName||null,n===null?t(e.type)||`Memo`:n;case E:n=e._payload,e=e._init;try{return t(e(n))}catch{}}return null}function n(e){return``+e}function r(e){try{n(e);var t=!1}catch{t=!0}if(t){t=console;var r=t.error,i=typeof Symbol==`function`&&Symbol.toStringTag&&e[Symbol.toStringTag]||e.constructor.name||`Object`;return r.call(t,`The provided key is an unsupported type %s. This value must be coerced to a string before using it here.`,i),n(e)}}function i(e){if(e===_)return`<>`;if(typeof e==`object`&&e&&e.$$typeof===E)return`<...>`;try{var n=t(e);return n?`<`+n+`>`:`<...>`}catch{return`<...>`}}function a(){var e=k.A;return e===null?null:e.getOwner()}function o(){return Error(`react-stack-top-frame`)}function s(e){if(A.call(e,`key`)){var t=Object.getOwnPropertyDescriptor(e,`key`).get;if(t&&t.isReactWarning)return!1}return e.key!==void 0}function c(e,t){function n(){N||(N=!0,console.error("%s: `key` is not a prop. Trying to access it will result in `undefined` being returned. If you need to access the same value within the child component, you should pass it as a different prop. (https://react.dev/link/special-props)",t))}n.isReactWarning=!0,Object.defineProperty(e,`key`,{get:n,configurable:!0})}function l(){var e=t(this.type);return P[e]||(P[e]=!0,console.error(`Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release.`)),e=this.props.ref,e===void 0?null:e}function u(e,t,n,r,i,a){var o=n.ref;return e={$$typeof:h,type:e,key:t,props:n,_owner:r},(o===void 0?null:o)===null?Object.defineProperty(e,`ref`,{enumerable:!1,value:null}):Object.defineProperty(e,`ref`,{enumerable:!1,get:l}),e._store={},Object.defineProperty(e._store,`validated`,{configurable:!1,enumerable:!1,writable:!0,value:0}),Object.defineProperty(e,`_debugInfo`,{configurable:!1,enumerable:!1,writable:!0,value:null}),Object.defineProperty(e,`_debugStack`,{configurable:!1,enumerable:!1,writable:!0,value:i}),Object.defineProperty(e,`_debugTask`,{configurable:!1,enumerable:!1,writable:!0,value:a}),Object.freeze&&(Object.freeze(e.props),Object.freeze(e)),e}function d(e,n,i,o,l,d){var p=n.children;if(p!==void 0)if(o)if(j(p)){for(o=0;o<p.length;o++)f(p[o]);Object.freeze&&Object.freeze(p)}else console.error(`React.jsx: Static children should always be an array. You are likely explicitly calling React.jsxs or React.jsxDEV. Use the Babel transform instead.`);else f(p);if(A.call(n,`key`)){p=t(e);var m=Object.keys(n).filter(function(e){return e!==`key`});o=0<m.length?`{key: someKey, `+m.join(`: ..., `)+`: ...}`:`{key: someKey}`,L[p+o]||(m=0<m.length?`{`+m.join(`: ..., `)+`: ...}`:`{}`,console.error(`A props object containing a "key" prop is being spread into JSX:
   let props = %s;
   <%s {...props} />
 React keys must be passed directly to JSX without using spread:
   let props = %s;
-  <%s key={someKey} {...props} />`,o,p,m,p),L[p+o]=!0)}if(p=null,i!==void 0&&(r(i),p=``+i),s(n)&&(r(n.key),p=``+n.key),`key`in n)for(var h in i={},n)h!==`key`&&(i[h]=n[h]);else i=n;return p&&c(i,typeof e==`function`?e.displayName||e.name||`Unknown`:e),u(e,p,i,a(),l,d)}function f(e){p(e)?e._store&&(e._store.validated=1):typeof e==`object`&&e&&e.$$typeof===E&&(e._payload.status===`fulfilled`?p(e._payload.value)&&e._payload.value._store&&(e._payload.value._store.validated=1):e._store&&(e._store.validated=1))}function p(e){return typeof e==`object`&&!!e&&e.$$typeof===h}var m=require(`react`),h=Symbol.for(`react.transitional.element`),g=Symbol.for(`react.portal`),_=Symbol.for(`react.fragment`),v=Symbol.for(`react.strict_mode`),y=Symbol.for(`react.profiler`),b=Symbol.for(`react.consumer`),x=Symbol.for(`react.context`),S=Symbol.for(`react.forward_ref`),C=Symbol.for(`react.suspense`),w=Symbol.for(`react.suspense_list`),T=Symbol.for(`react.memo`),E=Symbol.for(`react.lazy`),D=Symbol.for(`react.activity`),O=Symbol.for(`react.client.reference`),k=m.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,A=Object.prototype.hasOwnProperty,j=Array.isArray,M=console.createTask?console.createTask:function(){return null};m={react_stack_bottom_frame:function(e){return e()}};var N,P={},F=m.react_stack_bottom_frame.bind(m,o)(),I=M(i(o)),L={};e.Fragment=_,e.jsx=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!1,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)},e.jsxs=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!0,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)}})()})),M=o(((e,t)=>{process.env.NODE_ENV===`production`?t.exports=A():t.exports=j()}))(),N=({color:e=`black`,activeColor:t=`red`,isActive:n=!1})=>(0,M.jsx)(`svg`,{"data-testid":`__icon-root__`,xmlns:`http://www.w3.org/2000/svg`,width:`100%`,height:`100%`,viewBox:`0 0 24 24`,"aria-hidden":`true`,children:(0,M.jsxs)(`g`,{children:[(0,M.jsx)(`path`,{"data-testid":`__icon-path__`,fill:e,d:`M12 14c1.66 0 2.99-1.34 2.99-3L15 5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm5.3-3c0 3-2.54 5.1-5.3 5.1S6.7 14 6.7 11H5c0 3.41 2.72 6.23 6 6.72V21h2v-3.28c3.28-.48 6-3.3 6-6.72h-1.7z`}),n&&(0,M.jsx)(`circle`,{"data-testid":`__icon-active__`,fill:t,cx:`16`,cy:`4`,r:`4`})]})}),P=(e,t)=>{for(let n of e)for(let e of n)if(t(e.transcript??``)!==null)return},F=({children:e,commands:t=null,lang:n=`en-US`,grammars:r=null,timeout:i=3e3,silenceTimeout:a=null,precision:o=.4,maxAlternatives:s=1,continuous:c=!1,ariaLabel:u=`start recognition`,style:d=null,className:f=null,outlineStyle:p=`2px solid`,onStart:m=null,onEnd:h=null,onSpeechStart:g=null,onSpeechEnd:_=null,onResult:v=null,onError:y=null,onNoMatch:b=null,signal:x=null,__rsInstance:S})=>{let C=(0,l.useRef)(null),T=(0,l.useMemo)(()=>w(),[]),[,{start:A,stop:j,subscribe:F,unsubscribe:I,isRecording:L}]=D(n,r,s,c,S),R=k(t,o),z=(0,l.useRef)({});z.current={onStart:m,onEnd:h,onSpeechStart:g,onSpeechEnd:_,onResult:v,onError:y,onNoMatch:b};let B=(0,l.useRef)(c);B.current=c;let V=(0,l.useRef)(R);V.current=R;let H=(0,l.useRef)(null),U=(0,l.useRef)(null),W=(0,l.useRef)(!1),G=(0,l.useRef)(a);G.current=a;let ee=(0,l.useCallback)(()=>U.current?.(),[]),[K,q]=O(ee,i),[te,J]=O(ee,a??0),Y=(0,l.useCallback)(()=>{try{j()}catch(e){z.current.onError?.(e),H.current?.()}},[j]),ne=(0,l.useCallback)(e=>{K(),z.current.onStart?.(e)},[K]),re=(0,l.useCallback)(e=>{q(),z.current.onSpeechStart?.(e)},[q]),ie=(0,l.useCallback)(e=>{K(),B.current&&G.current>0&&te(),z.current.onSpeechEnd?.(e)},[K,te]),ae=(0,l.useCallback)((e,t)=>{q(),B.current||(P(e?.results??[],V.current),Y()),z.current.onResult?.(t,e)},[q,Y]),X=(0,l.useCallback)(e=>{Y(),z.current.onError?.(e)},[Y]),oe=(0,l.useCallback)(e=>{q(),Y(),z.current.onNoMatch?.(e)},[q,Y]),Z=(0,l.useCallback)(e=>{if(!W.current){W.current=!0,q(),J();try{Y(),H.current?.()}finally{W.current=!1,z.current.onEnd?.(e)}}},[q,J,Y]);U.current=Z;let Q=(0,l.useMemo)(()=>({start:ne,end:Z,speechstart:re,speechend:ie,result:ae,error:X,nomatch:oe}),[ne,Z,re,ie,ae,X,oe]);H.current=()=>Object.entries(Q).forEach(([e,t])=>I?.(e,t));let $=(0,l.useCallback)(()=>{try{J(),Object.entries(Q).forEach(([e,t])=>F(e,t)),A({signal:x})?.catch?.(X)}catch(e){X(e)}},[Q,F,A,J,X,x]),se=(0,l.useCallback)(()=>{!f&&p&&(C.current.style.outline=p)},[f,p]),ce=(0,l.useCallback)(()=>{!f&&p&&(C.current.style.outline=`none`)},[f,p]);return T?E(e)?e($,Y,L):(0,l.isValidElement)(e)?(0,l.cloneElement)(e,{...!L&&{onClick:$}}):(0,M.jsx)(`button`,{"data-testid":`__vocal-root__`,ref:C,"aria-label":u,"aria-pressed":L,style:f?null:{width:24,height:24,backgroundColor:`transparent`,border:`none`,padding:0,cursor:!c&&L?`default`:`pointer`,...d},className:f,onFocus:se,onBlur:ce,onClick:L?Y:$,children:(0,M.jsx)(N,{isActive:L,color:`#aaa`})}):null};exports.default=F,exports.isSupported=w,exports.useVocal=D;
+  <%s key={someKey} {...props} />`,o,p,m,p),L[p+o]=!0)}if(p=null,i!==void 0&&(r(i),p=``+i),s(n)&&(r(n.key),p=``+n.key),`key`in n)for(var h in i={},n)h!==`key`&&(i[h]=n[h]);else i=n;return p&&c(i,typeof e==`function`?e.displayName||e.name||`Unknown`:e),u(e,p,i,a(),l,d)}function f(e){p(e)?e._store&&(e._store.validated=1):typeof e==`object`&&e&&e.$$typeof===E&&(e._payload.status===`fulfilled`?p(e._payload.value)&&e._payload.value._store&&(e._payload.value._store.validated=1):e._store&&(e._store.validated=1))}function p(e){return typeof e==`object`&&!!e&&e.$$typeof===h}var m=require(`react`),h=Symbol.for(`react.transitional.element`),g=Symbol.for(`react.portal`),_=Symbol.for(`react.fragment`),v=Symbol.for(`react.strict_mode`),y=Symbol.for(`react.profiler`),b=Symbol.for(`react.consumer`),x=Symbol.for(`react.context`),S=Symbol.for(`react.forward_ref`),C=Symbol.for(`react.suspense`),w=Symbol.for(`react.suspense_list`),T=Symbol.for(`react.memo`),E=Symbol.for(`react.lazy`),D=Symbol.for(`react.activity`),O=Symbol.for(`react.client.reference`),k=m.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,A=Object.prototype.hasOwnProperty,j=Array.isArray,M=console.createTask?console.createTask:function(){return null};m={react_stack_bottom_frame:function(e){return e()}};var N,P={},F=m.react_stack_bottom_frame.bind(m,o)(),I=M(i(o)),L={};e.Fragment=_,e.jsx=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!1,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)},e.jsxs=function(e,t,n){var r=1e4>k.recentlyCreatedOwnerStacks++;return d(e,t,n,!0,r?Error(`react-stack-top-frame`):F,r?M(i(e)):I)}})()})),w=e(((e,t)=>{process.env.NODE_ENV===`production`?t.exports=S():t.exports=C()}))(),T=({color:e=`black`,activeColor:t=`red`,isActive:n=!1})=>(0,w.jsx)(`svg`,{"data-testid":`__icon-root__`,xmlns:`http://www.w3.org/2000/svg`,width:`100%`,height:`100%`,viewBox:`0 0 24 24`,"aria-hidden":`true`,children:(0,w.jsxs)(`g`,{children:[(0,w.jsx)(`path`,{"data-testid":`__icon-path__`,fill:e,d:`M12 14c1.66 0 2.99-1.34 2.99-3L15 5c0-1.66-1.34-3-3-3S9 3.34 9 5v6c0 1.66 1.34 3 3 3zm5.3-3c0 3-2.54 5.1-5.3 5.1S6.7 14 6.7 11H5c0 3.41 2.72 6.23 6 6.72V21h2v-3.28c3.28-.48 6-3.3 6-6.72h-1.7z`}),n&&(0,w.jsx)(`circle`,{"data-testid":`__icon-active__`,fill:t,cx:`16`,cy:`4`,r:`4`})]})}),E=(e,t)=>{for(let n of e)for(let e of n)if(t(e.transcript??``)!==null)return},D=({children:e,commands:n=null,lang:r=`en-US`,grammars:i=null,timeout:a=3e3,silenceTimeout:o=null,precision:s=.4,maxAlternatives:c=1,continuous:l=!1,ariaLabel:u=`start recognition`,style:d=null,className:f=null,outlineStyle:p=`2px solid`,onStart:m=null,onEnd:h=null,onSpeechStart:_=null,onSpeechEnd:S=null,onResult:C=null,onError:D=null,onNoMatch:O=null,signal:k=null,__rsInstance:A=null})=>{let j=(0,t.useRef)(null),M=(0,t.useMemo)(()=>g(),[]),[,{start:N,stop:P,subscribe:F,unsubscribe:I,isRecording:L}]=y(r,i,c,l,A),ee=x(n,s),R=(0,t.useRef)({onStart:null,onEnd:null,onSpeechStart:null,onSpeechEnd:null,onResult:null,onError:null,onNoMatch:null});R.current={onStart:m,onEnd:h,onSpeechStart:_,onSpeechEnd:S,onResult:C,onError:D,onNoMatch:O};let z=(0,t.useRef)(l);z.current=l;let B=(0,t.useRef)(ee);B.current=ee;let V=(0,t.useRef)(null),H=(0,t.useRef)(null),U=(0,t.useRef)(!1),W=(0,t.useRef)(o);W.current=o;let G=(0,t.useCallback)(()=>H.current?.(),[]),[K,q]=b(G,a),[te,J]=b(G,o??0),Y=(0,t.useCallback)(()=>{try{P()}catch(e){R.current.onError?.(e),V.current?.()}},[P]),ne=(0,t.useCallback)(e=>{K(),R.current.onStart?.(e)},[K]),re=(0,t.useCallback)(e=>{q(),R.current.onSpeechStart?.(e)},[q]),ie=(0,t.useCallback)(e=>{K(),z.current&&(W.current??0)>0&&te(),R.current.onSpeechEnd?.(e)},[K,te]),ae=(0,t.useCallback)((e,t)=>{q(),z.current||(E(e.results===void 0?[]:Array.from(e.results,e=>Array.from(e)),B.current),Y()),R.current.onResult?.(t,e)},[q,Y]),X=(0,t.useCallback)(e=>{Y(),R.current.onError?.(e)},[Y]),oe=(0,t.useCallback)(e=>{q(),Y(),R.current.onNoMatch?.(e)},[q,Y]),Z=(0,t.useCallback)(e=>{if(!U.current){U.current=!0,q(),J();try{Y(),V.current?.()}finally{U.current=!1,R.current.onEnd?.(e)}}},[q,J,Y]);H.current=Z;let Q=(0,t.useMemo)(()=>({start:ne,end:Z,speechstart:re,speechend:ie,result:ae,error:X,nomatch:oe}),[ne,Z,re,ie,ae,X,oe]);V.current=()=>Object.entries(Q).forEach(([e,t])=>I?.(e,t));let $=(0,t.useCallback)(()=>{try{J(),Object.entries(Q).forEach(([e,t])=>F(e,t)),N({signal:k??void 0})?.catch?.(X)}catch(e){X(e)}},[Q,F,N,J,X,k]),se=(0,t.useCallback)(()=>{!f&&p&&j.current&&(j.current.style.outline=p)},[f,p]),ce=(0,t.useCallback)(()=>{!f&&p&&j.current&&(j.current.style.outline=`none`)},[f,p]);return M?v(e)?e($,Y,L):(0,t.isValidElement)(e)?(0,t.cloneElement)(e,{...!L&&{onClick:$}}):(0,w.jsx)(`button`,{"data-testid":`__vocal-root__`,ref:j,"aria-label":u,"aria-pressed":L,style:f?void 0:{width:24,height:24,backgroundColor:`transparent`,border:`none`,padding:0,cursor:!l&&L?`default`:`pointer`,...d??{}},className:f??void 0,onFocus:se,onBlur:ce,onClick:L?Y:$,children:(0,w.jsx)(T,{isActive:L,color:`#aaa`})}):null};exports.default=D,exports.isSupported=g,exports.useCommands=x,exports.useVocal=y;
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { CSSProperties } from 'react';
+import { EventHandlerFor } from '@untemps/vocal';
+import { EventType } from '@untemps/vocal';
+import { GenericEventHandler } from '@untemps/vocal';
+import { isSupported } from '@untemps/vocal';
+import { JSX } from 'react/jsx-runtime';
+import { ReactElement } from 'react';
+import { ReactNode } from 'react';
+import { RefObject } from 'react';
+import { VocalInstance } from '@untemps/vocal';
+
+export declare type CommandCallback = (rawInput: string, commandKey: string) => unknown;
+
+export declare type CommandsMap = Record<string, CommandCallback>;
+
+export { isSupported }
+
+export declare type OnResultCallback = (bestAlternative: string, event: SpeechRecognitionEvent | Event) => void;
+
+export declare type TriggerCommand = (rawInput: string) => unknown;
+
+export declare const useCommands: (commands?: CommandsMap | null, precision?: number) => TriggerCommand;
+
+export declare const useVocal: (lang?: string, grammars?: SpeechGrammarList | null, maxAlternatives?: number, continuous?: boolean, __rsInstance?: VocalInstance | null) => UseVocalReturn;
+
+export declare interface UseVocalActions {
+    start: (options?: {
+        signal?: AbortSignal;
+    }) => Promise<void> | undefined;
+    stop: () => void;
+    abort: () => void;
+    subscribe: {
+        <T extends EventType>(eventType: T, handler: EventHandlerFor<T>): void;
+        (eventType: string, handler: GenericEventHandler): void;
+    };
+    unsubscribe: {
+        <T extends EventType>(eventType: T, handler?: EventHandlerFor<T>): void;
+        (eventType: string, handler?: GenericEventHandler): void;
+    };
+    clean: () => void;
+    isRecording: boolean;
+}
+
+export declare type UseVocalReturn = [RefObject<VocalInstance | null>, UseVocalActions];
+
+declare const Vocal: ({ children, commands, lang, grammars, timeout, silenceTimeout, precision, maxAlternatives, continuous, ariaLabel, style, className, outlineStyle, onStart, onEnd, onSpeechStart, onSpeechEnd, onResult, onError, onNoMatch, signal, __rsInstance, }: VocalProps) => JSX.Element | null;
+export default Vocal;
+
+export declare interface VocalProps {
+    children?: ReactNode | ((start: () => void, stop: () => void, isStarted: boolean) => ReactElement | null);
+    commands?: CommandsMap | null;
+    lang?: string;
+    grammars?: SpeechGrammarList | null;
+    timeout?: number;
+    silenceTimeout?: number | null;
+    precision?: number;
+    maxAlternatives?: number;
+    continuous?: boolean;
+    ariaLabel?: string;
+    style?: CSSProperties | null;
+    className?: string | null;
+    outlineStyle?: string | null;
+    onStart?: ((event: Event) => void) | null;
+    onEnd?: ((event?: Event) => void) | null;
+    onSpeechStart?: ((event: Event) => void) | null;
+    onSpeechEnd?: ((event: Event) => void) | null;
+    onResult?: OnResultCallback | null;
+    onError?: ((error: unknown) => void) | null;
+    onNoMatch?: ((event: Event) => void) | null;
+    signal?: AbortSignal | null;
+    /**
+     * Internal/testing escape hatch. Injects a custom vocal instance. Not part of the
+     * stable public API — see issue #136 for the redesign of this surface.
+     */
+    __rsInstance?: VocalInstance | null;
+}
+
+export { }

package/dist/index.es.js

@@ -245,7 +245,7 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		}
 		let r = c.current;
 		if (r) {
-			let i = r.search(e).filter((e) => e.score < t);
+			let i = r.search(e).filter((e) => (e.score ?? 1) < t);
 			if (i?.length) {
 				let t = i[0].item.toLowerCase();
 				return n[t]?.(e, t);
@@ -451,9 +451,17 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 	})] })
 }), N = (e, t) => {
 	for (let n of e) for (let e of n) if (t(e.transcript ?? "") !== null) return;
-}, P = ({ children: r, commands: o = null, lang: s = "en-US", grammars: c = null, timeout: l = 3e3, silenceTimeout: u = null, precision: d = .4, maxAlternatives: f = 1, continuous: p = !1, ariaLabel: m = "start recognition", style: h = null, className: g = null, outlineStyle: _ = "2px solid", onStart: v = null, onEnd: y = null, onSpeechStart: b = null, onSpeechEnd: x = null, onResult: S = null, onError: w = null, onNoMatch: k = null, signal: A = null, __rsInstance: P }) => {
-	let F = a(null), I = i(() => C(), []), [, { start: L, stop: R, subscribe: ee, unsubscribe: te, isRecording: z }] = E(s, c, f, p, P), B = O(o, d), V = a({});
-	V.current = {
+}, P = ({ children: r, commands: o = null, lang: s = "en-US", grammars: c = null, timeout: l = 3e3, silenceTimeout: u = null, precision: d = .4, maxAlternatives: f = 1, continuous: p = !1, ariaLabel: m = "start recognition", style: h = null, className: g = null, outlineStyle: _ = "2px solid", onStart: v = null, onEnd: y = null, onSpeechStart: b = null, onSpeechEnd: x = null, onResult: S = null, onError: w = null, onNoMatch: k = null, signal: A = null, __rsInstance: P = null }) => {
+	let F = a(null), I = i(() => C(), []), [, { start: L, stop: R, subscribe: ee, unsubscribe: te, isRecording: z }] = E(s, c, f, p, P), ne = O(o, d), B = a({
+		onStart: null,
+		onEnd: null,
+		onSpeechStart: null,
+		onSpeechEnd: null,
+		onResult: null,
+		onError: null,
+		onNoMatch: null
+	});
+	B.current = {
 		onStart: v,
 		onEnd: y,
 		onSpeechStart: b,
@@ -462,37 +470,37 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		onError: w,
 		onNoMatch: k
 	};
-	let H = a(p);
-	H.current = p;
-	let U = a(B);
-	U.current = B;
-	let W = a(null), ne = a(null), G = a(!1), re = a(u);
+	let V = a(p);
+	V.current = p;
+	let H = a(ne);
+	H.current = ne;
+	let U = a(null), W = a(null), G = a(!1), re = a(u);
 	re.current = u;
-	let ie = n(() => ne.current?.(), []), [K, q] = D(ie, l), [ae, J] = D(ie, u ?? 0), Y = n(() => {
+	let ie = n(() => W.current?.(), []), [K, q] = D(ie, l), [ae, J] = D(ie, u ?? 0), Y = n(() => {
 		try {
 			R();
 		} catch (e) {
-			V.current.onError?.(e), W.current?.();
+			B.current.onError?.(e), U.current?.();
 		}
 	}, [R]), oe = n((e) => {
-		K(), V.current.onStart?.(e);
+		K(), B.current.onStart?.(e);
 	}, [K]), se = n((e) => {
-		q(), V.current.onSpeechStart?.(e);
+		q(), B.current.onSpeechStart?.(e);
 	}, [q]), ce = n((e) => {
-		K(), H.current && re.current > 0 && ae(), V.current.onSpeechEnd?.(e);
+		K(), V.current && (re.current ?? 0) > 0 && ae(), B.current.onSpeechEnd?.(e);
 	}, [K, ae]), le = n((e, t) => {
-		q(), H.current || (N(e?.results ?? [], U.current), Y()), V.current.onResult?.(t, e);
+		q(), V.current || (N(e.results === void 0 ? [] : Array.from(e.results, (e) => Array.from(e)), H.current), Y()), B.current.onResult?.(t, e);
 	}, [q, Y]), X = n((e) => {
-		Y(), V.current.onError?.(e);
+		Y(), B.current.onError?.(e);
 	}, [Y]), ue = n((e) => {
-		q(), Y(), V.current.onNoMatch?.(e);
+		q(), Y(), B.current.onNoMatch?.(e);
 	}, [q, Y]), Z = n((e) => {
 		if (!G.current) {
 			G.current = !0, q(), J();
 			try {
-				Y(), W.current?.();
+				Y(), U.current?.();
 			} finally {
-				G.current = !1, V.current.onEnd?.(e);
+				G.current = !1, B.current.onEnd?.(e);
 			}
 		}
 	}, [
@@ -500,7 +508,7 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		J,
 		Y
 	]);
-	ne.current = Z;
+	W.current = Z;
 	let Q = i(() => ({
 		start: oe,
 		end: Z,
@@ -518,10 +526,10 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		X,
 		ue
 	]);
-	W.current = () => Object.entries(Q).forEach(([e, t]) => te?.(e, t));
+	U.current = () => Object.entries(Q).forEach(([e, t]) => te?.(e, t));
 	let $ = n(() => {
 		try {
-			J(), Object.entries(Q).forEach(([e, t]) => ee(e, t)), L({ signal: A })?.catch?.(X);
+			J(), Object.entries(Q).forEach(([e, t]) => ee(e, t)), L({ signal: A ?? void 0 })?.catch?.(X);
 		} catch (e) {
 			X(e);
 		}
@@ -533,25 +541,25 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 		X,
 		A
 	]), de = n(() => {
-		!g && _ && (F.current.style.outline = _);
+		!g && _ && F.current && (F.current.style.outline = _);
 	}, [g, _]), fe = n(() => {
-		!g && _ && (F.current.style.outline = "none");
+		!g && _ && F.current && (F.current.style.outline = "none");
 	}, [g, _]);
 	return I ? T(r) ? r($, Y, z) : t(r) ? e(r, { ...!z && { onClick: $ } }) : /* @__PURE__ */ (0, j.jsx)("button", {
 		"data-testid": "__vocal-root__",
 		ref: F,
 		"aria-label": m,
 		"aria-pressed": z,
-		style: g ? null : {
+		style: g ? void 0 : {
 			width: 24,
 			height: 24,
 			backgroundColor: "transparent",
 			border: "none",
 			padding: 0,
 			cursor: !p && z ? "default" : "pointer",
-			...h
+			...h ?? {}
 		},
-		className: g,
+		className: g ?? void 0,
 		onFocus: de,
 		onBlur: fe,
 		onClick: z ? Y : $,
@@ -562,6 +570,6 @@ var s = (e, t) => () => (t || (e((t = { exports: {} }).exports, t), e = null), t
 	}) : null;
 };
 //#endregion
-export { P as default, C as isSupported, E as useVocal };
+export { P as default, C as isSupported, O as useCommands, E as useVocal };
 
 //# sourceMappingURL=index.es.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@untemps/react-vocal",
-	"version": "2.0.0-beta.14",
+	"version": "2.0.0-beta.16",
 	"author": "Vincent Le Badezet <v.lebadezet@untemps.net>",
 	"repository": "git@github.com:untemps/react-vocal.git",
 	"license": "MIT",
@@ -21,54 +21,71 @@
 		"access": "public"
 	},
 	"files": [
-		"dist/index.cjs",
-		"dist/index.es.js",
+		"dist/*.cjs",
+		"dist/*.es.js",
+		"dist/*.d.ts",
 		"CHANGELOG.md"
 	],
 	"type": "module",
 	"main": "dist/index.cjs",
 	"module": "dist/index.es.js",
+	"types": "dist/index.d.ts",
 	"sideEffects": false,
 	"exports": {
 		".": {
+			"types": "./dist/index.d.ts",
 			"import": "./dist/index.es.js",
 			"require": "./dist/index.cjs",
 			"default": "./dist/index.es.js"
 		}
 	},
 	"engines": {
-		"node": "^20.19.0 || >=22.12.0"
+		"node": ">=22"
 	},
 	"devDependencies": {
 		"@commitlint/cli": "^20.5.3",
-		"fuse.js": "^7.3.0",
 		"@commitlint/config-conventional": "^20.5.3",
+		"@eslint/js": "^10.0.1",
+		"@microsoft/api-extractor": "^7.58.7",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
 		"@semantic-release/github": "^12.0.6",
 		"@testing-library/dom": "^10.4.1",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@testing-library/react": "^16.3.2",
+		"@types/react": "^19.2.15",
+		"@types/react-dom": "^19.2.3",
 		"@untemps/utils": "^3.2.0",
 		"@vitejs/plugin-react": "^6.0.1",
 		"@vitest/coverage-v8": "^4.1.5",
+		"eslint": "^10.4.0",
+		"eslint-config-prettier": "^10.1.8",
+		"fuse.js": "^7.3.0",
+		"globals": "^17.6.0",
 		"husky": "^9.1.7",
 		"jsdom": "^29.1.1",
 		"prettier": "^3.8.3",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5",
 		"semantic-release": "^25.0.3",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.59.4",
 		"vite": "^8.0.10",
+		"vite-plugin-dts": "^5.0.1",
 		"vitest": "^4.1.5"
 	},
 	"peerDependencies": {
 		"fuse.js": ">=6.0.0",
 		"react": ">=16.13.1",
-		"react-dom": ">=16.13.1"
+		"react-dom": ">=16.13.1",
+		"typescript": ">=6.0.0"
 	},
 	"peerDependenciesMeta": {
 		"fuse.js": {
 			"optional": true
+		},
+		"typescript": {
+			"optional": true
 		}
 	},
 	"dependencies": {
@@ -109,6 +126,10 @@
 						{
 							"path": "dist/index.es.js",
 							"label": "ES distribution"
+						},
+						{
+							"path": "dist/index.d.ts",
+							"label": "TypeScript declarations"
 						}
 					]
 				}
@@ -119,8 +140,10 @@
 		"dev": "cd dev && yarn && yarn dev",
 		"test": "vitest",
 		"test:ci": "vitest run --coverage",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint src vitest.setup.ts",
 		"build": "vite build",
 		"prepare": "husky",
-		"prettier": "prettier \"*/**/*.js\" --ignore-path ./.prettierignore --write && git add -u && git status"
+		"prettier": "prettier \"*/**/*.{js,ts,tsx}\" --ignore-path ./.prettierignore --write && git add -u && git status"
 	}
 }