feat(tts): stream OpenAI audio natively

docs/api/README.md

@@ -2872,8 +2872,8 @@ console.log(result.content);
 - [VoiceEvent](type-aliases/VoiceEvent.md)
 - [VoiceResult](type-aliases/VoiceResult.md)
 - [VoiceTurn](type-aliases/VoiceTurn.md)
-- [TTSProvider](type-aliases/TTSProvider.md)
-- [TTSStreamChunk](type-aliases/TTSStreamChunk.md)
+- [~~TTSProvider~~](type-aliases/TTSProvider.md)
+- [~~TTSStreamChunk~~](type-aliases/TTSStreamChunk.md)
 - [VoiceErrorOptions](type-aliases/VoiceErrorOptions.md)
 - [AudioMetadata](type-aliases/AudioMetadata.md)
 - [StreamHandlerConfig](type-aliases/StreamHandlerConfig.md)

docs/api/classes/OpenAITTS.md

@@ -6,15 +6,7 @@
 
 # Class: OpenAITTS
 
-Defined in: [voice/providers/OpenAITTS.ts:30](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L30)
-
-OpenAI Text-to-Speech Handler
-
-Supports high-quality neural TTS with multiple voices.
-
-## See
-
-https://platform.openai.com/docs/api-reference/audio/createSpeech
+Defined in: [voice/providers/OpenAITTS.ts:145](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L145)
 
 ## Implements
 
@@ -26,7 +18,7 @@ https://platform.openai.com/docs/api-reference/audio/createSpeech
 
 > **new OpenAITTS**(`apiKey?`): `OpenAITTS`
 
-Defined in: [voice/providers/OpenAITTS.ts:93](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L93)
+Defined in: [voice/providers/OpenAITTS.ts:208](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L208)
 
 #### Parameters
 
@@ -44,7 +36,7 @@ Defined in: [voice/providers/OpenAITTS.ts:93](https://github.com/juspay/neurolin
 
 > `readonly` **maxTextLength**: `4096` = `4096`
 
-Defined in: [voice/providers/OpenAITTS.ts:37](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L37)
+Defined in: [voice/providers/OpenAITTS.ts:152](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L152)
 
 Maximum text length (4096 characters)
 
@@ -58,7 +50,7 @@ Maximum text length (4096 characters)
 
 > **isConfigured**(): `boolean`
 
-Defined in: [voice/providers/OpenAITTS.ts:98](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L98)
+Defined in: [voice/providers/OpenAITTS.ts:213](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L213)
 
 Validate that the provider is properly configured
 
@@ -78,7 +70,7 @@ True if provider can generate TTS
 
 > **getVoices**(`languageCode?`): `Promise`\<[`TTSVoice`](../type-aliases/TTSVoice.md)[]\>
 
-Defined in: [voice/providers/OpenAITTS.ts:102](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L102)
+Defined in: [voice/providers/OpenAITTS.ts:217](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L217)
 
 Get available voices for the provider
 
@@ -106,7 +98,7 @@ List of available voices
 
 > **synthesize**(`text`, `options?`): `Promise`\<[`TTSResult`](../type-aliases/TTSResult.md)\>
 
-Defined in: [voice/providers/OpenAITTS.ts:111](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L111)
+Defined in: [voice/providers/OpenAITTS.ts:356](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L356)
 
 Generate audio from text using provider-specific TTS API
 
@@ -141,3 +133,39 @@ On synthesis failure, timeout, or configuration issues
 #### Implementation of
 
 `TTSHandler.synthesize`
+
+---
+
+### synthesizeStream()
+
+> **synthesizeStream**(`text`, `options?`): `AsyncIterable`\<[`TTSChunk`](../type-aliases/TTSChunk.md), `any`, `any`\> \| `undefined`
+
+Defined in: [voice/providers/OpenAITTS.ts:434](https://github.com/juspay/neurolink/blob/release/src/lib/voice/providers/OpenAITTS.ts#L434)
+
+Stream one segment's audio as the response body arrives.
+
+Returns `undefined` for any format without direct wire proof of
+incremental delivery, which selects the buffered `synthesize()` path.
+
+Every non-empty body read is yielded as soon as it is available and
+carries `isFinal: false`: assigning finality here would require a
+one-read lookahead, delaying every fragment by a full body read, and
+`TTSProcessor` recomputes finality globally anyway.
+
+#### Parameters
+
+##### text
+
+`string`
+
+##### options?
+
+[`TTSOptions`](../type-aliases/TTSOptions.md) = `{}`
+
+#### Returns
+
+`AsyncIterable`\<[`TTSChunk`](../type-aliases/TTSChunk.md), `any`, `any`\> \| `undefined`
+
+#### Implementation of
+
+`TTSHandler.synthesizeStream`

docs/api/classes/TTSError.md

@@ -6,7 +6,7 @@
 
 # Class: TTSError
 
-Defined in: [utils/ttsProcessor.ts:131](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L131)
+Defined in: [utils/ttsProcessor.ts:229](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L229)
 
 TTS Error class for text-to-speech specific errors
 
@@ -20,7 +20,7 @@ TTS Error class for text-to-speech specific errors
 
 > **new TTSError**(`options`): `TTSError`
 
-Defined in: [utils/ttsProcessor.ts:132](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L132)
+Defined in: [utils/ttsProcessor.ts:230](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L230)
 
 #### Parameters
 

docs/api/classes/TTSProcessor.md

@@ -6,7 +6,7 @@
 
 # Class: TTSProcessor
 
-Defined in: [utils/ttsProcessor.ts:171](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L171)
+Defined in: [utils/ttsProcessor.ts:290](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L290)
 
 TTS processor class for orchestrating text-to-speech operations
 
@@ -41,7 +41,7 @@ if (TTSProcessor.supports("google-ai")) {
 
 > `static` **registerHandler**(`providerName`, `handler`): `void`
 
-Defined in: [utils/ttsProcessor.ts:211](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L211)
+Defined in: [utils/ttsProcessor.ts:330](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L330)
 
 Register a TTS handler for a specific provider
 
@@ -83,7 +83,7 @@ TTSProcessor.registerHandler('google-ai', googleHandler);
 
 > `static` **getHandler**(`providerName`): [`TTSHandler`](../type-aliases/TTSHandler.md) \| `undefined`
 
-Defined in: [utils/ttsProcessor.ts:231](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L231)
+Defined in: [utils/ttsProcessor.ts:350](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L350)
 
 Get a registered TTS handler by provider name.
 
@@ -111,7 +111,7 @@ Handler instance or undefined if not registered
 
 > `static` **listProviders**(): `string`[]
 
-Defined in: [utils/ttsProcessor.ts:238](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L238)
+Defined in: [utils/ttsProcessor.ts:357](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L357)
 
 List the names of all registered providers.
 
@@ -125,7 +125,7 @@ List the names of all registered providers.
 
 > `static` **clearHandlers**(): `void`
 
-Defined in: [utils/ttsProcessor.ts:246](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L246)
+Defined in: [utils/ttsProcessor.ts:365](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L365)
 
 Removes every registered TTS handler. Primarily for test isolation —
 production code should not need to call this.
@@ -140,7 +140,7 @@ production code should not need to call this.
 
 > `static` **supports**(`providerName`): `boolean`
 
-Defined in: [utils/ttsProcessor.ts:263](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L263)
+Defined in: [utils/ttsProcessor.ts:382](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L382)
 
 Check if a provider is supported (has a registered TTS handler)
 
@@ -172,7 +172,7 @@ if (TTSProcessor.supports("google-ai")) {
 
 > `static` **synthesize**(`text`, `provider`, `options`): `Promise`\<[`TTSResult`](../type-aliases/TTSResult.md)\>
 
-Defined in: [utils/ttsProcessor.ts:313](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L313)
+Defined in: [utils/ttsProcessor.ts:432](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L432)
 
 Synthesize speech from text using a registered TTS provider
 
@@ -238,18 +238,48 @@ console.log(`Generated ${result.size} bytes of ${result.format} audio`);
 
 > `static` **synthesizeStream**(`textChunks`, `provider`, `options`, `shouldStop?`): `AsyncGenerator`\<[`TTSChunk`](../type-aliases/TTSChunk.md)\>
 
-Defined in: [utils/ttsProcessor.ts:465](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L465)
+Defined in: [utils/ttsProcessor.ts:862](https://github.com/juspay/neurolink/blob/release/src/lib/utils/ttsProcessor.ts#L862)
 
 Incrementally synthesize sentence-buffered text chunks.
 
 Text is flushed at a sentence boundary after `streamingBufferSize`
 characters, or hard-split before the provider's maximum text length.
-Each segment goes through `synthesize()`, preserving the existing handler
-registry, validation, error normalization, and telemetry seam.
 
-The most recent successful audio chunk is held until another succeeds or
-the input ends, so exactly one real audio chunk carries `isFinal: true`
-without emitting a separate empty terminator chunk.
+A segment is served by the handler's `synthesizeStream()` when it offers
+one and returns a stream, and by `synthesize()` otherwise — including
+when the native stream produces no deliverable audio at all, and including
+every way capability discovery itself can fail. The preflight reads and
+calls that decide whether a native stream exists all sit inside one
+guarded region in `resolveNativeStream`, with the call site's own catch
+backstopping it, so a handler that misbehaves while being ASKED lands on
+the buffered path rather than costing the segment. That is what makes the
+next sentence true of every segment rather than only of the ones that got
+that far.
+
+Either way the segment keeps the same handler registry, validation, error
+normalization and `tts.synthesize` telemetry seam — exactly one span per
+segment, opened by whichever path served it — cancellation included: a
+segment whose stream is still in flight when the consumer stops records
+its span from the unwind path rather than dropping it. Failures that
+originate in the native segment's own work, once a stream has been
+established, are a different case and keep the shaped failed-segment
+semantics every synthesis failure has.
+
+Provider-reported indexes, cumulative sizes and finality are discarded and
+recomputed globally. A native fragment is dropped unless it carries a
+non-empty binary payload, so no native read reaches the consumer as an
+empty chunk; the buffered path is unfiltered and forwards whatever
+`synthesize()` returns, so a handler that produces a zero-byte buffer
+still yields an empty chunk and a repeated `cumulativeSize`. The most
+recent successful audio chunk is held until another succeeds or the input
+ends, so exactly one real audio chunk carries `isFinal: true` without
+emitting a separate empty terminator chunk.
+
+Segment production and per-segment synthesis are deliberately inline
+rather than nested async generators: each additional generator layer costs
+every chunk several microtask turns, which is directly observable at
+`NeuroLink.stream()` as audio interleaving one text chunk later than it
+does without native streaming.
 
 #### Parameters
 

docs/api/type-aliases/AudioMetadata.md

@@ -8,60 +8,60 @@
 
 > **AudioMetadata** = `object`
 
-Defined in: [types/voice.ts:396](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L396)
+Defined in: [types/voice.ts:409](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L409)
 
 ## Properties
 
 ### format
 
 > **format**: [`TTSAudioFormat`](TTSAudioFormat.md)
 
-Defined in: [types/voice.ts:397](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L397)
+Defined in: [types/voice.ts:410](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L410)
 
 ---
 
 ### duration
 
 > **duration**: `number`
 
-Defined in: [types/voice.ts:398](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L398)
+Defined in: [types/voice.ts:411](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L411)
 
 ---
 
 ### sampleRate
 
 > **sampleRate**: `number`
 
-Defined in: [types/voice.ts:399](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L399)
+Defined in: [types/voice.ts:412](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L412)
 
 ---
 
 ### channels
 
 > **channels**: `number`
 
-Defined in: [types/voice.ts:400](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L400)
+Defined in: [types/voice.ts:413](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L413)
 
 ---
 
 ### bitDepth
 
 > **bitDepth**: `number`
 
-Defined in: [types/voice.ts:401](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L401)
+Defined in: [types/voice.ts:414](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L414)
 
 ---
 
 ### samples
 
 > **samples**: `number`
 
-Defined in: [types/voice.ts:402](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L402)
+Defined in: [types/voice.ts:415](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L415)
 
 ---
 
 ### size
 
 > **size**: `number`
 
-Defined in: [types/voice.ts:403](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L403)
+Defined in: [types/voice.ts:416](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L416)

docs/api/type-aliases/AzureTTSOptions.md

@@ -8,7 +8,7 @@
 
 > **AzureTTSOptions** = [`TTSOptions`](TTSOptions.md) & `object`
 
-Defined in: [types/voice.ts:438](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L438)
+Defined in: [types/voice.ts:451](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L451)
 
 ## Type Declaration
 

docs/api/type-aliases/BracketCountingState.md

@@ -8,7 +8,7 @@
 
 > **BracketCountingState** = `object`
 
-Defined in: [types/common.ts:586](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L586)
+Defined in: [types/common.ts:674](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L674)
 
 Shared bracket counting state and utilities
 Used by both validateJSONCompleteness and StructuredOutputParser
@@ -19,28 +19,28 @@ Used by both validateJSONCompleteness and StructuredOutputParser
 
 > **braceCount**: `number`
 
-Defined in: [types/common.ts:587](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L587)
+Defined in: [types/common.ts:675](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L675)
 
 ---
 
 ### bracketCount
 
 > **bracketCount**: `number`
 
-Defined in: [types/common.ts:588](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L588)
+Defined in: [types/common.ts:676](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L676)
 
 ---
 
 ### inString
 
 > **inString**: `boolean`
 
-Defined in: [types/common.ts:589](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L589)
+Defined in: [types/common.ts:677](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L677)
 
 ---
 
 ### escapeNext
 
 > **escapeNext**: `boolean`
 
-Defined in: [types/common.ts:590](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L590)
+Defined in: [types/common.ts:678](https://github.com/juspay/neurolink/blob/release/src/lib/types/common.ts#L678)

docs/api/type-aliases/ElevenLabsModel.md

@@ -8,4 +8,4 @@
 
 > **ElevenLabsModel** = `"eleven_multilingual_v2"` \| `"eleven_turbo_v2_5"` \| `"eleven_turbo_v2"` \| `"eleven_monolingual_v1"`
 
-Defined in: [types/voice.ts:457](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L457)
+Defined in: [types/voice.ts:470](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L470)

docs/api/type-aliases/ElevenLabsTTSOptions.md

@@ -8,7 +8,7 @@
 
 > **ElevenLabsTTSOptions** = [`TTSOptions`](TTSOptions.md) & `object`
 
-Defined in: [types/voice.ts:463](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L463)
+Defined in: [types/voice.ts:476](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L476)
 
 ## Type Declaration
 

docs/api/type-aliases/GoogleTTSOptions.md

@@ -8,7 +8,7 @@
 
 > **GoogleTTSOptions** = [`TTSOptions`](TTSOptions.md) & `object`
 
-Defined in: [types/voice.ts:478](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L478)
+Defined in: [types/voice.ts:491](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L491)
 
 ## Type Declaration
 

docs/api/type-aliases/GoogleVoiceType.md

@@ -8,4 +8,4 @@
 
 > **GoogleVoiceType** = `"Standard"` \| `"WaveNet"` \| `"Neural2"` \| `"Studio"` \| `"Polyglot"`
 
-Defined in: [types/voice.ts:471](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L471)
+Defined in: [types/voice.ts:484](https://github.com/juspay/neurolink/blob/release/src/lib/types/voice.ts#L484)