fix: move model construction off the JS thread (#944)

## Problem

The `loadModel` template in `RnExecutorchInstaller.h` constructs model
objects **synchronously on the JS thread**. For models like Kokoro TTS,
the constructor loads `.pte` files, initializes the phonemizer, and
reads voice data — blocking the JS thread for several seconds.

This prevents React from rendering any pending state updates (loading
spinners, progress indicators, etc.) until construction completes. For
example, calling `setIsSynthesizing(true)` followed by `tts.load()` will
not show the loading UI for 3-4 seconds because the JS thread is blocked
by the synchronous native constructor.

## Solution

Make `loadModel` return a **Promise** and dispatch the heavy model
construction to `GlobalThreadPool::detach` — matching the pattern
already used by `promiseHostFunction` for inference calls like
`generate()`.

### C++ (`RnExecutorchInstaller.h`)

- JSI arguments are still parsed on the JS thread (required for
`jsi::Value` access)
- Model construction is dispatched to `GlobalThreadPool::detach`
- The Promise resolves on the JS thread via `callInvoker->invokeAsync`
with the host object
- Error handling follows the same pattern as `promiseHostFunction` in
`ModelHostObject.h`

### TypeScript

- All `global.load*()` call sites updated to `await` the now-async
result
- Global type declarations updated to return `Promise<any>`
- `SpeechToText` already used `await`, so no change needed there

## Breaking Change

This is a breaking change for any consumers calling `global.load*()`
directly and expecting a synchronous return value. However:

- The public module APIs (`load()` methods) are already `async` — no
user-facing API changes needed
- The `global.load*()` functions are internal/undocumented

## Test Plan

- Verify model loading still works for all model types (TTS, LLM, OCR,
etc.)
- Verify that React state updates (loading spinners) render immediately
when `load()` is called, rather than being delayed until construction
completes
- Verify error handling still propagates correctly from native
construction failures

---------

Co-authored-by: Mateusz Słuszniak <mateusz.sluszniak@swmansion.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

docs/docs/06-api-reference/classes/TextEmbeddingsModule.md

@@ -136,7 +136,7 @@ Always call this method when you're done with a model to prevent memory leaks.
 
 > **forward**(`input`): `Promise`\<`Float32Array`\<`ArrayBufferLike`\>\>
 
-Defined in: [modules/natural_language_processing/TextEmbeddingsModule.ts:60](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextEmbeddingsModule.ts#L60)
+Defined in: [modules/natural_language_processing/TextEmbeddingsModule.ts:63](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextEmbeddingsModule.ts#L63)
 
 Executes the model's forward pass, where `input` is a text that will be embedded.
 

docs/docs/06-api-reference/classes/TextToSpeechModule.md

@@ -1,6 +1,6 @@
 # Class: TextToSpeechModule
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:17](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L17)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:18](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L18)
 
 Module for Text to Speech (TTS) functionalities.
 
@@ -20,7 +20,7 @@ Module for Text to Speech (TTS) functionalities.
 
 > **nativeModule**: `any` = `null`
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:21](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L21)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:22](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L22)
 
 Native module instance
 
@@ -30,7 +30,7 @@ Native module instance
 
 > **delete**(): `void`
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:182](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L182)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:229](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L229)
 
 Unloads the model from memory.
 
@@ -44,7 +44,7 @@ Unloads the model from memory.
 
 > **forward**(`text`, `speed?`): `Promise`\<`Float32Array`\<`ArrayBufferLike`\>\>
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:109](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L109)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:118](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L118)
 
 Synthesizes the provided text into speech.
 Returns a promise that resolves to the full audio waveform as a `Float32Array`.
@@ -71,11 +71,43 @@ A promise resolving to the synthesized audio waveform.
 
 ---
 
+### forwardFromPhonemes()
+
+> **forwardFromPhonemes**(`phonemes`, `speed?`): `Promise`\<`Float32Array`\<`ArrayBufferLike`\>\>
+
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:135](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L135)
+
+Synthesizes pre-computed phonemes into speech, bypassing the built-in phonemizer.
+This allows using an external G2P system (e.g. the Python `phonemizer` library,
+espeak-ng, or any custom phonemizer).
+
+#### Parameters
+
+##### phonemes
+
+`string`
+
+The pre-computed IPA phoneme string.
+
+##### speed?
+
+`number` = `1.0`
+
+Optional speed multiplier for the speech synthesis (default is 1.0).
+
+#### Returns
+
+`Promise`\<`Float32Array`\<`ArrayBufferLike`\>\>
+
+A promise resolving to the synthesized audio waveform.
+
+---
+
 ### load()
 
 > **load**(`config`, `onDownloadProgressCallback?`): `Promise`\<`void`\>
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:30](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L30)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:31](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L31)
 
 Loads the model and voice assets specified by the config object.
 `onDownloadProgressCallback` allows you to monitor the current progress.
@@ -104,7 +136,7 @@ Optional callback to monitor download progress.
 
 > **stream**(`input`): `AsyncGenerator`\<`Float32Array`\<`ArrayBufferLike`\>\>
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:127](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L127)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:196](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L196)
 
 Starts a streaming synthesis session. Yields audio chunks as they are generated.
 
@@ -124,11 +156,36 @@ An async generator yielding Float32Array audio chunks.
 
 ---
 
+### streamFromPhonemes()
+
+> **streamFromPhonemes**(`input`): `AsyncGenerator`\<`Float32Array`\<`ArrayBufferLike`\>\>
+
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:210](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L210)
+
+Starts a streaming synthesis session from pre-computed phonemes.
+Bypasses the built-in phonemizer, allowing use of external G2P systems.
+
+#### Parameters
+
+##### input
+
+[`TextToSpeechStreamingPhonemeInput`](../interfaces/TextToSpeechStreamingPhonemeInput.md)
+
+Input object containing phonemes and optional speed.
+
+#### Returns
+
+`AsyncGenerator`\<`Float32Array`\<`ArrayBufferLike`\>\>
+
+An async generator yielding Float32Array audio chunks.
+
+---
+
 ### streamStop()
 
 > **streamStop**(): `void`
 
-Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:175](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L175)
+Defined in: [modules/natural_language_processing/TextToSpeechModule.ts:222](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/modules/natural_language_processing/TextToSpeechModule.ts#L222)
 
 Stops the streaming process if there is any ongoing.
 

docs/docs/06-api-reference/functions/useTextToSpeech.md

@@ -2,7 +2,7 @@
 
 > **useTextToSpeech**(`TextToSpeechProps`): [`TextToSpeechType`](../interfaces/TextToSpeechType.md)
 
-Defined in: [hooks/natural_language_processing/useTextToSpeech.ts:19](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/hooks/natural_language_processing/useTextToSpeech.ts#L19)
+Defined in: [hooks/natural_language_processing/useTextToSpeech.ts:22](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/hooks/natural_language_processing/useTextToSpeech.ts#L22)
 
 React hook for managing Text to Speech instance.
 

docs/docs/06-api-reference/index.md

@@ -262,8 +262,11 @@
 - [TextToImageType](interfaces/TextToImageType.md)
 - [TextToSpeechConfig](interfaces/TextToSpeechConfig.md)
 - [TextToSpeechInput](interfaces/TextToSpeechInput.md)
+- [TextToSpeechPhonemeInput](interfaces/TextToSpeechPhonemeInput.md)
 - [TextToSpeechProps](interfaces/TextToSpeechProps.md)
+- [TextToSpeechStreamingCallbacks](interfaces/TextToSpeechStreamingCallbacks.md)
 - [TextToSpeechStreamingInput](interfaces/TextToSpeechStreamingInput.md)
+- [TextToSpeechStreamingPhonemeInput](interfaces/TextToSpeechStreamingPhonemeInput.md)
 - [TextToSpeechType](interfaces/TextToSpeechType.md)
 - [TokenizerProps](interfaces/TokenizerProps.md)
 - [TokenizerType](interfaces/TokenizerType.md)

docs/docs/06-api-reference/interfaces/TextToSpeechPhonemeInput.md

@@ -0,0 +1,32 @@
+# Interface: TextToSpeechPhonemeInput
+
+Defined in: [types/tts.ts:103](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L103)
+
+Text to Speech module input for pre-computed phonemes.
+Use this when you have your own phonemizer (e.g. the Python `phonemizer`
+library, espeak-ng, or any custom G2P system) and want to bypass the
+built-in phonemizer pipeline.
+
+## Extended by
+
+- [`TextToSpeechStreamingPhonemeInput`](TextToSpeechStreamingPhonemeInput.md)
+
+## Properties
+
+### phonemes
+
+> **phonemes**: `string`
+
+Defined in: [types/tts.ts:104](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L104)
+
+pre-computed IPA phoneme string
+
+---
+
+### speed?
+
+> `optional` **speed**: `number`
+
+Defined in: [types/tts.ts:105](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L105)
+
+optional speed argument - the higher it is, the faster the speech becomes

docs/docs/06-api-reference/interfaces/TextToSpeechStreamingCallbacks.md

@@ -0,0 +1,58 @@
+# Interface: TextToSpeechStreamingCallbacks
+
+Defined in: [types/tts.ts:189](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L189)
+
+Shared streaming lifecycle callbacks for TTS streaming modes.
+
+## Extended by
+
+- [`TextToSpeechStreamingInput`](TextToSpeechStreamingInput.md)
+- [`TextToSpeechStreamingPhonemeInput`](TextToSpeechStreamingPhonemeInput.md)
+
+## Properties
+
+### onBegin()?
+
+> `optional` **onBegin**: () => `void` \| `Promise`\<`void`\>
+
+Defined in: [types/tts.ts:190](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L190)
+
+Called when streaming begins
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+---
+
+### onEnd()?
+
+> `optional` **onEnd**: () => `void` \| `Promise`\<`void`\>
+
+Defined in: [types/tts.ts:192](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L192)
+
+Called when streaming ends
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>
+
+---
+
+### onNext()?
+
+> `optional` **onNext**: (`audio`) => `void` \| `Promise`\<`void`\>
+
+Defined in: [types/tts.ts:191](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L191)
+
+Called after each audio chunk gets calculated.
+
+#### Parameters
+
+##### audio
+
+`Float32Array`
+
+#### Returns
+
+`void` \| `Promise`\<`void`\>

docs/docs/06-api-reference/interfaces/TextToSpeechStreamingInput.md

@@ -1,6 +1,6 @@
 # Interface: TextToSpeechStreamingInput
 
-Defined in: [types/tts.ts:156](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L156)
+Defined in: [types/tts.ts:205](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L205)
 
 Text to Speech streaming input definition
 
@@ -11,43 +11,51 @@ Callbacks can be both synchronous or asynchronous.
 
 ## Extends
 
-- [`TextToSpeechInput`](TextToSpeechInput.md)
+- [`TextToSpeechInput`](TextToSpeechInput.md).[`TextToSpeechStreamingCallbacks`](TextToSpeechStreamingCallbacks.md)
 
 ## Properties
 
 ### onBegin()?
 
 > `optional` **onBegin**: () => `void` \| `Promise`\<`void`\>
 
-Defined in: [types/tts.ts:157](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L157)
+Defined in: [types/tts.ts:190](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L190)
 
 Called when streaming begins
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
+#### Inherited from
+
+[`TextToSpeechStreamingCallbacks`](TextToSpeechStreamingCallbacks.md).[`onBegin`](TextToSpeechStreamingCallbacks.md#onbegin)
+
 ---
 
 ### onEnd()?
 
 > `optional` **onEnd**: () => `void` \| `Promise`\<`void`\>
 
-Defined in: [types/tts.ts:159](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L159)
+Defined in: [types/tts.ts:192](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L192)
 
 Called when streaming ends
 
 #### Returns
 
 `void` \| `Promise`\<`void`\>
 
+#### Inherited from
+
+[`TextToSpeechStreamingCallbacks`](TextToSpeechStreamingCallbacks.md).[`onEnd`](TextToSpeechStreamingCallbacks.md#onend)
+
 ---
 
 ### onNext()?
 
 > `optional` **onNext**: (`audio`) => `void` \| `Promise`\<`void`\>
 
-Defined in: [types/tts.ts:158](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L158)
+Defined in: [types/tts.ts:191](https://github.com/software-mansion/react-native-executorch/blob/main/packages/react-native-executorch/src/types/tts.ts#L191)
 
 Called after each audio chunk gets calculated.
 
@@ -61,6 +69,10 @@ Called after each audio chunk gets calculated.
 
 `void` \| `Promise`\<`void`\>
 
+#### Inherited from
+
+[`TextToSpeechStreamingCallbacks`](TextToSpeechStreamingCallbacks.md).[`onNext`](TextToSpeechStreamingCallbacks.md#onnext)
+
 ---
 
 ### speed?